@hasna/connectors 1.3.23 → 1.3.25

package/connectors/connect-imessage/bun.lock

@@ -0,0 +1,32 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@hasna/connect-imessage",
+      "dependencies": {
+        "chalk": "^5.3.0",
+        "commander": "^12.1.0",
+      },
+      "devDependencies": {
+        "@types/bun": "latest",
+        "typescript": "^5",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.12", "", { "dependencies": { "bun-types": "1.3.12" } }, "sha512-DBv81elK+/VSwXHDlnH3Qduw+KxkTIWi7TXkAeh24zpi5l0B2kUg9Ga3tb4nJaPcOFswflgi/yAvMVBPrxMB+A=="],
+
+    "@types/node": ["@types/node@25.6.0", "", { "dependencies": { "undici-types": "~7.19.0" } }, "sha512-+qIYRKdNYJwY3vRCZMdJbPLJAtGjQBudzZzdzwQYkEPQd+PJGixUL5QfvCLDaULoLv+RhT3LDkwEfKaAkgSmNQ=="],
+
+    "bun-types": ["bun-types@1.3.12", "", { "dependencies": { "@types/node": "*" } }, "sha512-HqOLj5PoFajAQciOMRiIZGNoKxDJSr6qigAttOX40vJuSp6DN/CxWp9s3C1Xwm4oH7ybueITwiaOcWXoYVoRkA=="],
+
+    "chalk": ["chalk@5.6.2", "", {}, "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA=="],
+
+    "commander": ["commander@12.1.0", "", {}, "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.19.2", "", {}, "sha512-qYVnV5OEm2AW8cJMCpdV20CDyaN3g0AjDlOGf1OW4iaDEx8MwdtChUp4zu4H0VP3nDRF/8RKWH+IPp9uW0YGZg=="],
+  }
+}

package/connectors/connect-imessage/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@hasna/connect-imessage",
+  "version": "0.0.1",
+  "description": "iMessage connector CLI - bridge-first iMessage transport for send, reply, and conversation management",
+  "type": "module",
+  "bin": {
+    "connect-imessage": "bin/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun && bun build ./src/cli/index.ts --outdir ./bin --target bun",
+    "dev": "bun run ./src/cli/index.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "imessage",
+    "apple",
+    "messages",
+    "connector",
+    "cli",
+    "typescript",
+    "bun",
+    "hasna"
+  ],
+  "author": "Hasna",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "chalk": "^5.3.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

package/connectors/connect-imessage/src/api/client.ts

@@ -0,0 +1,139 @@
+import type { IMessageConfig, IMessageApiResponse } from '../types';
+import { IMessageApiError } from '../types';
+
+export interface ImessageRequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  params?: Record<string, string | number | boolean | undefined>;
+  body?: Record<string, unknown> | unknown[];
+}
+
+/**
+ * HTTP client for the iMessage bridge API
+ */
+export class ImessageClient {
+  private readonly bridgeUrl: string;
+  private readonly apiKey?: string;
+  private readonly deviceId?: string;
+
+  constructor(config: IMessageConfig) {
+    if (!config.bridgeUrl) {
+      throw new Error('Bridge URL is required');
+    }
+    // Normalize URL - strip trailing slash
+    this.bridgeUrl = config.bridgeUrl.replace(/\/+$/, '');
+    this.apiKey = config.apiKey;
+    this.deviceId = config.deviceId;
+  }
+
+  private buildUrl(path: string, params?: Record<string, string | number | boolean | undefined>): string {
+    const url = new URL(this.bridgeUrl + path);
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null && value !== '') {
+          url.searchParams.append(key, String(value));
+        }
+      });
+    }
+    return url.toString();
+  }
+
+  private getHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {
+      'Accept': 'application/json',
+    };
+
+    if (this.apiKey) {
+      headers['Authorization'] = 'Bearer ' + this.apiKey;
+    }
+    if (this.deviceId) {
+      headers['X-API-Key'] = this.deviceId;
+    }
+
+    return headers;
+  }
+
+  async request<T>(
+    path: string,
+    options: ImessageRequestOptions = {}
+  ): Promise<T> {
+    const { method = 'GET', params, body } = options;
+
+    const url = this.buildUrl(path, method === 'GET' ? params : undefined);
+    const headers = this.getHeaders();
+
+    const fetchOptions: RequestInit = {
+      method,
+      headers,
+    };
+
+    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      headers['Content-Type'] = 'application/json';
+      fetchOptions.body = JSON.stringify(body);
+    }
+
+    let response: Response;
+    try {
+      response = await fetch(url, fetchOptions);
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new IMessageApiError('Failed to reach bridge: ' + error.message, 0);
+      }
+      throw new IMessageApiError('Failed to reach bridge', 0);
+    }
+
+    let data: unknown;
+    const contentType = response.headers.get('content-type') || '';
+    if (contentType.includes('application/json')) {
+      const text = await response.text();
+      if (text) {
+        try {
+          data = JSON.parse(text);
+        } catch {
+          data = text;
+        }
+      }
+    } else {
+      data = await response.text();
+    }
+
+    if (!response.ok) {
+      const errorData = data as IMessageApiResponse;
+      const message = errorData?.error || (typeof data === 'string' ? data : response.statusText);
+      throw new IMessageApiError(message || 'Bridge request failed', response.status, errorData?.code);
+    }
+
+    return (data as IMessageApiResponse<T>)?.data ?? (data as T);
+  }
+
+  async get<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'GET', params });
+  }
+
+  async post<T>(path: string, body?: Record<string, unknown>): Promise<T> {
+    return this.request<T>(path, { method: 'POST', body });
+  }
+
+  async put<T>(path: string, body?: Record<string, unknown>): Promise<T> {
+    return this.request<T>(path, { method: 'PUT', body });
+  }
+
+  async patch<T>(path: string, body?: Record<string, unknown>): Promise<T> {
+    return this.request<T>(path, { method: 'PATCH', body });
+  }
+
+  async delete<T>(path: string): Promise<T> {
+    return this.request<T>(path, { method: 'DELETE' });
+  }
+
+  /**
+   * Get a preview of the bridge URL (for debugging)
+   */
+  getBridgeUrlPreview(): string {
+    try {
+      const url = new URL(this.bridgeUrl);
+      return url.host;
+    } catch {
+      return 'invalid-url';
+    }
+  }
+}

package/connectors/connect-imessage/src/api/conversations.ts

@@ -0,0 +1,49 @@
+import type { ImessageClient } from './client';
+import type { IMessageConversation } from '../types';
+
+export interface ListConversationsOptions {
+  limit?: number;
+  offset?: number;
+}
+
+/**
+ * Conversation API module - list and retrieve iMessage conversations
+ */
+export class ConversationsApi {
+  constructor(private readonly client: ImessageClient) {}
+
+  /**
+   * List all conversations
+   */
+  async list(options: ListConversationsOptions = {}): Promise<IMessageConversation[]> {
+    const params: Record<string, number | undefined> = {};
+    if (options.limit) params.limit = options.limit;
+    if (options.offset) params.offset = options.offset;
+    return this.client.get<IMessageConversation[]>('/conversations', params);
+  }
+
+  /**
+   * Iterate over all conversations (handles pagination)
+   */
+  async *listAll(options: ListConversationsOptions = {}): AsyncGenerator<IMessageConversation> {
+    let offset = options.offset || 0;
+    const limit = options.limit || 50;
+
+    while (true) {
+      const conversations = await this.list({ limit, offset });
+      if (conversations.length === 0) break;
+      for (const conversation of conversations) {
+        yield conversation;
+      }
+      if (conversations.length < limit) break;
+      offset += conversations.length;
+    }
+  }
+
+  /**
+   * Get a specific conversation by chat GUID
+   */
+  async get(chatGuid: string): Promise<IMessageConversation> {
+    return this.client.get<IMessageConversation>(`/conversations/${encodeURIComponent(chatGuid)}`);
+  }
+}

package/connectors/connect-imessage/src/api/health.ts

@@ -0,0 +1,16 @@
+import type { ImessageClient } from './client';
+import type { IMessageHealth } from '../types';
+
+/**
+ * Health API module - check bridge and iMessage service status
+ */
+export class HealthApi {
+  constructor(private readonly client: ImessageClient) {}
+
+  /**
+   * Check bridge and iMessage health
+   */
+  async check(): Promise<IMessageHealth> {
+    return this.client.get<IMessageHealth>('/health');
+  }
+}

package/connectors/connect-imessage/src/api/index.ts

@@ -0,0 +1,62 @@
+import type { IMessageConfig } from '../types';
+import { ImessageClient } from './client';
+import { HealthApi } from './health';
+import { ConversationsApi } from './conversations';
+import { MessagesApi } from './messages';
+
+/**
+ * Main iMessage Connector class
+ * Provides access to iMessage via a bridge API
+ */
+export class IMessage {
+  private readonly client: ImessageClient;
+
+  // Service APIs
+  public readonly health: HealthApi;
+  public readonly conversations: ConversationsApi;
+  public readonly messages: MessagesApi;
+
+  constructor(config: IMessageConfig) {
+    this.client = new ImessageClient(config);
+    this.health = new HealthApi(this.client);
+    this.conversations = new ConversationsApi(this.client);
+    this.messages = new MessagesApi(this.client);
+  }
+
+  /**
+   * Create a client from environment variables
+   * Looks for IMESSAGE_BRIDGE_URL, IMESSAGE_API_KEY, IMESSAGE_DEVICE_ID
+   */
+  static fromEnv(): IMessage {
+    const bridgeUrl = process.env.IMESSAGE_BRIDGE_URL;
+
+    if (!bridgeUrl) {
+      throw new Error('IMESSAGE_BRIDGE_URL environment variable is required');
+    }
+
+    return new IMessage({
+      bridgeUrl,
+      apiKey: process.env.IMESSAGE_API_KEY,
+      deviceId: process.env.IMESSAGE_DEVICE_ID,
+    });
+  }
+
+  /**
+   * Get the bridge URL preview
+   */
+  getBridgeUrlPreview(): string {
+    return this.client.getBridgeUrlPreview();
+  }
+
+  /**
+   * Get the underlying client for direct API access
+   */
+  getClient(): ImessageClient {
+    return this.client;
+  }
+}
+
+export { ImessageClient } from './client';
+export { HealthApi } from './health';
+export { ConversationsApi } from './conversations';
+export { MessagesApi } from './messages';

package/connectors/connect-imessage/src/api/messages.ts

@@ -0,0 +1,119 @@
+import type { ImessageClient } from './client';
+import type { IMessage, IMessageAttachment } from '../types';
+
+export interface ListMessagesOptions {
+  chatGuid: string;
+  limit?: number;
+  offset?: number;
+  before?: string;
+  after?: string;
+}
+
+export interface SendMessageOptions {
+  chatGuid?: string;
+  recipient?: string;
+  text: string;
+  method?: string;
+  effectId?: string;
+}
+
+export interface ReplyMessageOptions {
+  text: string;
+  selectedMessageGuid: string;
+}
+
+/**
+ * Message API module - send, receive, and manage iMessages
+ */
+export class MessagesApi {
+  constructor(private readonly client: ImessageClient) {}
+
+  /**
+   * List messages for a conversation
+   */
+  async list(options: ListMessagesOptions): Promise<IMessage[]> {
+    const params: Record<string, string | number | undefined> = {
+      chatGuid: options.chatGuid,
+    };
+    if (options.limit) params.limit = options.limit;
+    if (options.offset) params.offset = options.offset;
+    if (options.before) params.before = options.before;
+    if (options.after) params.after = options.after;
+    return this.client.get<IMessage[]>('/messages', params);
+  }
+
+  /**
+   * Iterate over all messages (handles pagination)
+   */
+  async *listAll(options: ListMessagesOptions): AsyncGenerator<IMessage> {
+    let offset = options.offset || 0;
+    const limit = options.limit || 50;
+
+    while (true) {
+      const messages = await this.list({ ...options, limit, offset });
+      if (messages.length === 0) break;
+      for (const message of messages) {
+        yield message;
+      }
+      if (messages.length < limit) break;
+      offset += messages.length;
+    }
+  }
+
+  /**
+   * Send a message to a conversation
+   */
+  async send(options: SendMessageOptions): Promise<IMessage> {
+    const body: Record<string, unknown> = {
+      text: options.text,
+    };
+    if (options.chatGuid) body.chatGuid = options.chatGuid;
+    if (options.recipient) body.recipient = options.recipient;
+    if (options.method) body.method = options.method;
+    if (options.effectId) body.effectId = options.effectId;
+    return this.client.post<IMessage>('/messages', body);
+  }
+
+  /**
+   * Send a reply to a specific message (tapback or quoted reply)
+   */
+  async reply(messageGuid: string, options: ReplyMessageOptions): Promise<IMessage> {
+    const body: Record<string, unknown> = {
+      text: options.text,
+      selectedMessageGuid: options.selectedMessageGuid,
+    };
+    return this.client.post<IMessage>(`/messages/${messageGuid}/reply`, body);
+  }
+
+  /**
+   * Get a specific message by GUID
+   */
+  async get(messageGuid: string): Promise<IMessage> {
+    return this.client.get<IMessage>(`/messages/${messageGuid}`);
+  }
+
+  /**
+   * Download a message attachment
+   */
+  async downloadAttachment(attachmentGuid: string): Promise<ArrayBuffer> {
+    return this.client.request<ArrayBuffer>(`/attachments/${attachmentGuid}`, {
+      method: 'GET',
+    });
+  }
+
+  /**
+   * Send a tapback (reaction) to a message
+   */
+  async tapback(messageGuid: string, tapback: string): Promise<IMessage> {
+    return this.client.post<IMessage>(`/messages/${messageGuid}/tapback`, {
+      tapback,
+    } as unknown as Record<string, unknown>);
+  }
+
+  /**
+   * Mark messages as read in a conversation
+   */
+  async markRead(chatGuid: string): Promise<void> {
+    await this.client.post<void>(`/conversations/${encodeURIComponent(chatGuid)}/read`);
+  }
+}