Advanced iMessage Kit

A chatGuid is the unique identifier for a conversation. It follows the format service;-;address.

Common formats include:

• iMessage DM: iMessage;-;+1234567890 or iMessage;-;email@example.com
• SMS DM: SMS;-;+1234567890
• Group chat: iMessage;+;chat123456789
• Auto-detect: any;-;+1234567890 (The SDK will automatically detect the service type).

When running the SDK on a different machine than the iMessage server:

• Set serverUrl to point to the machine hosting the iMessage server.
• The SDK follows a local-first strategy: it reads local files first, then uploads the file bytes to the server.

To use the SDK, initialize it with the SDK function, provide a serverUrl, and call connect(). You can listen for real-time events like new-message using the .on() method and perform actions like sending messages via the messages namespace.

import { SDK } from "@photon-ai/advanced-imessage-kit";

const sdk = SDK({
  serverUrl: "http://localhost:1234",
});

await sdk.connect();

sdk.on("new-message", (message) => {
  console.log("New message:", message.text);
});

await sdk.messages.sendMessage({
  chatGuid: "iMessage;-;+1234567890",
  message: "Hello World!",
});

await sdk.close();

You can execute any of the provided examples in the repository using the Bun runtime. Use the following command structure, replacing <filename> with the specific example file you wish to run.

bun run examples/<filename>.ts

You can install the SDK using npm or bun.

npm install @photon-ai/advanced-imessage-kit
# or
bun add @photon-ai/advanced-imessage-kit

The SDK function accepts a ClientConfig object to customize behavior.

• serverUrl: The URL of the remote iMessage server (defaults to http://localhost:1234).
• apiKey: API key for server authentication.
• logLevel: Controls verbosity. Options: "debug" | "info" | "warn" | "error" (defaults to "info").
• logToFile: Boolean to enable/disable writing logs to ~/Library/Logs/AdvancedIMessageKit (defaults to true).

interface ClientConfig {
  serverUrl?: string; // Server URL, defaults to "http://localhost:1234"
  apiKey?: string; // API key (if server requires authentication)
  logLevel?: "debug" | "info" | "warn" | "error"; // Log level, defaults to "info"
  logToFile?: boolean; // Enable writing logs to ~/Library/Logs/AdvancedIMessageKit (default true)
}

After initializing the SDK, you must call connect() to establish a connection via Socket.IO. The SDK is designed to prioritize WebSocket transport to prevent message duplication issues common with polling.

Once connected and authenticated, the SDK will emit a ready event. You should wait for this event before attempting to perform operations.

const sdk = SDK();

sdk.on('ready', () => {
  console.log('SDK is ready to use!');
});

await sdk.connect();

You can interact with the iMessage SDK using the AdvancedIMessageKit class. It is recommended to use the getInstance() method to ensure a singleton instance is used throughout your application. You can pass a ClientConfig object to configure the server URL, API key, and logging behavior.

Configuration Options (ClientConfig):

• serverUrl: The URL of your iMessage server (defaults to http://localhost:1234).
• apiKey: The API key for authentication. If omitted, the SDK operates in 'legacy mode'.
• logLevel: The logging level (e.g., 'info', 'debug').
• logToFile: Boolean indicating whether to log to a file (defaults to true).

import { SDK } from '@photon-ai/advanced-imessage-kit';

const sdk = SDK({
  serverUrl: 'https://your-imessage-server.com',
  apiKey: 'your-api-key',
  logLevel: 'info',
  logToFile: true
});

A Handle is a messaging address (phone or email). Use sdk.handles to interact with them.

• queryHandles(options): Search for handles. Options include address (filter), with: ["chats"] (include related data), offset, and limit.
• getHandle(handleGuid): Fetches a specific handle.
• getHandleAvailability(address, service): Checks if an address supports a specific service like "imessage" or "facetime". This is useful for deciding whether to send an iMessage or an SMS.
• getHandleFocusStatus(handleGuid): Retrieves the current Focus status of a contact.

const hasIMessage = await sdk.handles.getHandleAvailability("+1234567890", "imessage");
const chatGuid = hasIMessage ? `iMessage;-;+1234567890` : `SMS;-;+1234567890`;

You can customize the background image for individual chats using sdk.chats.setBackground.

• Set via file path: Pass { filePath: "/path/to/image.png" }.
• Set via base64: Pass { fileData: "base64_string" }.
• Get info: getBackground(chatGuid) returns an object containing hasBackground (boolean), backgroundId, and imageUrl.
• Remove: removeBackground(chatGuid) clears the custom background.

// Set a background image (using file path)
await sdk.chats.setBackground("chat-guid", {
  filePath: "/path/to/image.png",
});