Skip to main content

​
Overview

The AdvancedIMessageKit class is the main SDK client that provides a complete interface for interacting with iMessage services. It implements a singleton pattern and manages WebSocket connections, HTTP requests, and event handling.

​
Class Definition

class AdvancedIMessageKit extends EventEmitter implements TypedEventEmitter

​
Static Methods

​
getInstance()

Get or create the singleton SDK instance. 
static getInstance(config?: ClientConfig): AdvancedIMessageKit
​
config
ClientConfig
Configuration options for the SDK client. See ClientConfig for details.
​
return
AdvancedIMessageKit
The singleton SDK instance
Example: 
import { AdvancedIMessageKit } from '@photon-ai/advanced-imessage-kit';

const sdk = AdvancedIMessageKit.getInstance({
  serverUrl: 'http://localhost:1234',
  apiKey: 'your-api-key',
  logLevel: 'info'
});

​
Properties

​
config

The configuration object used to initialize the SDK. 
readonly config: ClientConfig

​
logger

Logger instance for the SDK. 
readonly logger: Logger

​
http

Axios HTTP client instance configured with base URL and API key headers. 
readonly http: AxiosInstance

​
socket

Socket.IO client instance for real-time event handling. 
readonly socket: Socket

​
Module Properties

The SDK provides access to various functional modules: 
readonly attachments: AttachmentModule
readonly messages: MessageModule
readonly chats: ChatModule
readonly contacts: ContactModule
readonly handles: HandleModule
readonly facetime: FaceTimeModule
readonly icloud: ICloudModule
readonly polls: PollModule
readonly scheduledMessages: ScheduledMessageModule
readonly server: ServerModule

​
Instance Methods

​
connect()

Establish connection to the iMessage server via WebSocket. 
async connect(): Promise<void>
This method:
  • Connects to the server using Socket.IO
  • Sets up event listeners for server events
  • Handles authentication if an API key is provided
  • Emits a ready event when the connection is established and authenticated
Example: 
const sdk = AdvancedIMessageKit.getInstance({
  serverUrl: 'http://localhost:1234',
  apiKey: 'your-api-key'
});

// Listen for ready event
sdk.on('ready', () => {
  console.log('SDK is ready!');
});

// Connect to server
await sdk.connect();

​
close()

Disconnect from the iMessage server. 
async close(): Promise<void>
Example: 
await sdk.close();
console.log('Disconnected from server');

​
enqueueSend()

Enqueue a send operation to ensure sequential delivery. All send operations (messages, attachments, stickers) use this method internally to guarantee order. 
public enqueueSend<T>(task: () => Promise<T>): Promise<T>
​
task
() => Promise<T>
required
An async function that performs the send operation
​
return
Promise<T>
Promise that resolves with the task result
Example: 
// Ensure messages are sent in order
const result = await sdk.enqueueSend(async () => {
  return await someAsyncSendOperation();
});

​
clearProcessedMessages()

Clear processed message records to prevent memory leaks. The SDK maintains a cache of processed message GUIDs for deduplication. 
public clearProcessedMessages(maxSize?: number): void
​
maxSize
number
default:"1000"
Maximum number of messages to retain in the cache
Example: 
// Clear old messages, keep the 500 most recent
sdk.clearProcessedMessages(500);

​
getProcessedMessageCount()

Get the count of processed messages in the deduplication cache. 
public getProcessedMessageCount(): number
​
return
number
Number of processed messages in cache
Example: 
const count = sdk.getProcessedMessageCount();
console.log(`Tracking ${count} processed messages`);

​
Event Methods

The SDK extends EventEmitter with type-safe event handling:

​
on()

Register an event listener. 
on<K extends keyof PhotonEventMap>(
  event: K,
  listener: (data: PhotonEventMap[K]) => void
): this

​
once()

Register a one-time event listener. 
once<K extends keyof PhotonEventMap>(
  event: K,
  listener: (data: PhotonEventMap[K]) => void
): this

​
off()

Remove an event listener. 
off<K extends keyof PhotonEventMap>(
  event: K,
  listener: (data: PhotonEventMap[K]) => void
): this

​
emit()

Emit an event. 
emit<K extends keyof PhotonEventMap>(
  event: K,
  ...args: PhotonEventMap[K] extends undefined ? [] : [PhotonEventMap[K]]
): boolean
Example: 
// Listen for new messages
sdk.on('new-message', (message) => {
  console.log('New message:', message);
});

// Listen for connection events
sdk.on('ready', () => {
  console.log('SDK ready');
});

sdk.on('disconnect', () => {
  console.log('Disconnected');
});

​
Complete Example

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

// Initialize SDK
const sdk = AdvancedIMessageKit.getInstance({
  serverUrl: 'http://localhost:1234',
  apiKey: 'your-api-key',
  logLevel: 'info',
  logToFile: true
});

// Set up event listeners
sdk.on('ready', () => {
  console.log('Connected and authenticated!');
});

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

sdk.on('disconnect', () => {
  console.log('Connection lost');
});

// Connect to server
await sdk.connect();

// Use SDK modules
const chats = await sdk.chats.getChats();
console.log(`You have ${chats.length} chats`);

// Send a message
await sdk.messages.sendMessage({
  chatGuid: 'chat-guid',
  text: 'Hello, world!'
});

// Clean up when done
await sdk.close();

​
Singleton Pattern

The SDK uses a singleton pattern to ensure only one instance exists globally. This prevents multiple WebSocket connections and ensures consistent state: 
// These both return the same instance
const sdk1 = AdvancedIMessageKit.getInstance();
const sdk2 = AdvancedIMessageKit.getInstance();

console.log(sdk1 === sdk2); // true

​
See Also