imessage-ts/USAGE_GUIDE.md

TypeScript library for interacting with iMessage on macOS - send messages, monitor chats, and automate responses

# iMessage-TS Usage Guide

This guide explains how to use the iMessage-TS library to interact with the local iMessage database on macOS.

## Installation

```bash
npm install imessage-ts
```

## Requirements

- macOS (as iMessage is exclusive to Apple platforms)
- Node.js 14 or later
- An active Apple ID signed into iMessage
- Terminal/iTerm with "Full Disk Access" permissions

## Basic Usage

```typescript
import { IMessageClient } from 'imessage-ts';

// Initialize the client
const client = new IMessageClient();
await client.initialize();

// Check if iMessage is available
const isAvailable = await client.isAvailable();
console.log(`iMessage available: ${isAvailable}`);

// Get conversations
const conversations = await client.getConversations({ limit: 10 });
console.log(`You have ${conversations.length} conversations`);

// Get messages from a conversation
const messages = await client.getMessages({ 
  conversationId: conversations[0].id,
  limit: 20
});

// Send a message
await client.sendMessage({
  text: 'Hello from Node.js!',
  to: '+1234567890', // Phone number or email
});

// Close when done
client.close();
```

## Event Handling

```typescript
import { IMessageClient } from 'imessage-ts';

const client = new IMessageClient();
await client.initialize();

// Listen for new messages
client.on('message', (event) => {
  console.log(`New message from ${event.message.handle}: ${event.message.text}`);
});

// Listen for read receipts
client.on('messageRead', (event) => {
  console.log(`Message ${event.messageId} was read at ${event.readAt}`);
});

// Start watching
client.startWatching();

// Later, stop watching
client.stopWatching();
```

## Working with Attachments

```typescript
import { IMessageClient, AttachmentType } from 'imessage-ts';

const client = new IMessageClient();
await client.initialize();

// Get attachments from a specific message
const messageId = 'message123456';
const attachments = await client.getAttachments({ messageId });

// Get images from a conversation
const conversationId = 'chat123456';
const images = await client.getAttachments({ 
  conversationId,
  types: [AttachmentType.IMAGE]
});

// Send a message with attachments
await client.sendMessage({
  text: 'Check out these photos!',
  to: '+1234567890',
  attachments: ['/path/to/image1.jpg', '/path/to/image2.jpg']
});
```

## Group Chats

```typescript
import { IMessageClient } from 'imessage-ts';

const client = new IMessageClient();
await client.initialize();

// Get group conversations only
const groupChats = await client.getConversations({ onlyGroups: true });

// Send a message to a group
await client.sendMessage({
  text: 'Hello group!',
  to: ['email1@example.com', 'email2@example.com', '+1234567890'],
  subject: 'New Group Chat'
});
```

## API Reference

### IMessageClient

The main class for interacting with iMessage.

#### Constructor

```typescript
new IMessageClient(options?: DatabaseOptions)
```

Options:
- `databasePath` - Path to the iMessage database (default: `~/Library/Messages/chat.db`)
- `attachmentsPath` - Path to the attachments directory (default: `~/Library/Messages/Attachments`)
- `pollInterval` - Interval in milliseconds to check for new messages (default: `1000`)

#### Methods

- `initialize()` - Initialize the client
- `close()` - Close the client and database connections
- `startWatching()` - Start watching for new messages
- `stopWatching()` - Stop watching for new messages
- `isAvailable()` - Check if iMessage is available
- `getConversations(options?)` - Get conversations
- `getConversationById(id)` - Get a conversation by ID
- `getConversationByChatIdentifier(chatIdentifier)` - Get a conversation by chat identifier
- `getMessages(options)` - Get messages from a conversation
- `getMessageById(id)` - Get a message by ID
- `getAttachments(options)` - Get attachments
- `sendMessage(options)` - Send a message

#### Events

- `message` - Fired when a new message is received
- `messageRead` - Fired when a message is marked as read
- `messageDelivered` - Fired when a message is delivered
- `messageSent` - Fired when a message is sent
- `messageFailed` - Fired when sending a message fails
- `error` - Fired when an error occurs

## Troubleshooting

### Permission Issues

If you encounter permission errors:

1. Make sure your terminal app has "Full Disk Access" in System Preferences > Security & Privacy > Privacy
2. iMessage database is often protected, so your application might need additional permissions
3. For production apps, consider using the macOS Hardened Runtime and appropriate entitlements

### Database Locking

The iMessage database is often locked by the Messages app. This library creates a temporary copy to avoid locking issues, but in some cases you might still encounter problems if the database is actively being modified.

### AppleScript Issues

Message sending uses AppleScript, which might require additional permissions. Make sure your application can execute AppleScript commands.