@mapier/imsg-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mapier Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# @mapier/imsg-sdk
+
+TypeScript SDK for iMessage automation on macOS via the Mapier-patched `imsg` native layer, a fork of
+[`openclaw/imsg`](https://github.com/openclaw/imsg) (MIT).
+
+The package provides the gateway contract, the real `ImsgGateway` for a host Mac, and a deterministic `FakeGateway`
+that runs anywhere.
+
+Status: pre-release extraction. The gateway code was copied from `imsg-agent` at commit
+`56b42c91f89fc3a2350f97c53f303aea6271d511` and last re-synced at `6e0b96b` (imsg-agent PR #161:
+the full Tier-2 + read-verb surface, portable chat directory/backfill, and the 2026-07-14
+host-verification ledger).
+
+During the parallel-maintenance window, every gateway change must land in both repositories.
+
+## Quickstart
+
+`FakeGateway` runs anywhere — no Mac, no device, no network:
+
+```ts
+import { FakeGateway } from '@mapier/imsg-sdk';
+
+const gateway = new FakeGateway();
+const chatId = gateway.ensureDm('+15551234567');
+
+gateway.injectInbound({ chatId, sender: '+15551234567', senderName: 'Ava', text: 'you free tonight?' });
+await gateway.send({ chatId }, 'yep, 7pm works');
+
+for await (const event of gateway.subscribe()) {
+  console.log(event.is_from_me ? `me: ${event.text}` : `${event.sender_name}: ${event.text}`);
+  if (event.is_from_me) break; // our send() echoing back confirms the round-trip
+}
+```
+
+See [`examples/quickstart.ts`](examples/quickstart.ts) for the runnable version:
+`pnpm tsx examples/quickstart.ts`.
+
+## Real gateway
+
+`ImsgGateway` drives real iMessage and requires a host Mac. It needs Mapier's pinned fork of
+`openclaw/imsg`: `markxiong0122/imsg`, branch `mapier/macos26-tier2`, prebuilt binaries on release
+[`v0.1.0`](https://github.com/markxiong0122/imsg/releases/tag/v0.1.0). Build it (`make build`) and
+point the SDK at it via the `IMSG_BIN` environment variable. Caveat: rich-link delivery
+(`sendRichLink`) requires a build carrying the fork's `mapier/richlink-sync-fix` patch, which
+the `v0.1.0` release binaries predate — no capability marker gates it (see
+`docs/interactions.md`, `rich-link-card`). See
+[`docs/host-mac-control.md`](docs/host-mac-control.md) for host setup and
+[`docs/gateway-contract.md`](docs/gateway-contract.md) for the full interface contract.
+
+## Interactions
+
+`src/interactions/` catalogs iMessage interaction kinds across four tiers — web-link,
+App Clip checkout, native balloons (tapback, poll, effect, rich-link card), and a future
+MSMessages host-extension tier — with an honest capability/status per kind, plus a device-free
+trial harness over `FakeGateway`. See [`docs/interactions.md`](docs/interactions.md).
+
+## Versioning
+
+This package follows [SemVer](https://semver.org/) and is published to npm as
+[`@mapier/imsg-sdk`](https://www.npmjs.com/package/@mapier/imsg-sdk) (`pnpm add @mapier/imsg-sdk`).
+Pre-1.0: minor versions may break the API. See
+[CONTRIBUTING.md](CONTRIBUTING.md#releasing) for the release process and
+[CHANGELOG.md](CHANGELOG.md) for the version history.
+
+## License
+
+MIT — see [LICENSE](LICENSE). The native layer is a fork of
+[`openclaw/imsg`](https://github.com/openclaw/imsg), separately MIT-licensed upstream.

package/dist/gateway/external-ids.d.ts

@@ -0,0 +1,3 @@
+export declare function isImessageParticipantExternalId(value: string): boolean;
+export declare function isImessageDmConversationExternalId(value: string): boolean;
+export declare function isImessageGroupConversationExternalId(value: string): boolean;

package/dist/gateway/external-ids.js

@@ -0,0 +1,37 @@
+// Portable iMessage identifier validation, mirroring the zod refinements in
+// imsg-agent's connector protocol (shared/src/connector/protocol-primitives.ts)
+// as plain predicates so the SDK stays dependency-free. The semantics must stay
+// identical: at agent cutover these become the single source and the agent's
+// schemas wrap them.
+// Bounded-identifier envelope shared by every portable id: non-empty, capped,
+// no control characters, no surrounding whitespace.
+function isBoundedId(value) {
+    if (value.length < 1 || value.length > 512)
+        return false;
+    if (value.trim() !== value)
+        return false;
+    return [...value].every((character) => {
+        const codePoint = character.codePointAt(0);
+        return codePoint !== undefined && codePoint > 31 && codePoint !== 127;
+    });
+}
+// E.164 phone number, or an email that is already lowercase and NFC-normalized
+// (the connector wire's canonical form — comparison happens after
+// normalizeParticipant, but the portable id itself must arrive canonical).
+export function isImessageParticipantExternalId(value) {
+    if (!isBoundedId(value))
+        return false;
+    return (/^\+[1-9][0-9]{6,14}$/.test(value) ||
+        (/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(value) && value === value.toLowerCase() && value === value.normalize('NFC')));
+}
+// DM GUID: `any;-;<participant>` — the portable id structurally carries its
+// validated peer handle.
+export function isImessageDmConversationExternalId(value) {
+    const prefix = 'any;-;';
+    return isBoundedId(value) && value.startsWith(prefix) && isImessageParticipantExternalId(value.slice(prefix.length));
+}
+// Group GUID: `any;+;<32 hex>` — opaque, carries no membership.
+export function isImessageGroupConversationExternalId(value) {
+    return isBoundedId(value) && /^any;\+;[A-Fa-f0-9]{32}$/.test(value);
+}
+//# sourceMappingURL=external-ids.js.map

package/dist/gateway/external-ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-ids.js","sourceRoot":"","sources":["../../src/gateway/external-ids.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,gFAAgF;AAChF,gFAAgF;AAChF,6EAA6E;AAC7E,qBAAqB;AAErB,8EAA8E;AAC9E,oDAAoD;AACpD,SAAS,WAAW,CAAC,KAAa;IAChC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,GAAG;QAAE,OAAO,KAAK,CAAC;IACzD,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IACzC,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,SAAS,EAAE,EAAE;QACpC,MAAM,SAAS,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;QAC3C,OAAO,SAAS,KAAK,SAAS,IAAI,SAAS,GAAG,EAAE,IAAI,SAAS,KAAK,GAAG,CAAC;IACxE,CAAC,CAAC,CAAC;AACL,CAAC;AAED,+EAA+E;AAC/E,kEAAkE;AAClE,2EAA2E;AAC3E,MAAM,UAAU,+BAA+B,CAAC,KAAa;IAC3D,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtC,OAAO,CACL,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC;QAClC,CAAC,4BAA4B,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,KAAK,CAAC,WAAW,EAAE,IAAI,KAAK,KAAK,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAChH,CAAC;AACJ,CAAC;AAED,4EAA4E;AAC5E,yBAAyB;AACzB,MAAM,UAAU,kCAAkC,CAAC,KAAa;IAC9D,MAAM,MAAM,GAAG,QAAQ,CAAC;IACxB,OAAO,WAAW,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,+BAA+B,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;AACvH,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,qCAAqC,CAAC,KAAa;IACjE,OAAO,WAAW,CAAC,KAAK,CAAC,IAAI,0BAA0B,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACtE,CAAC"}

package/dist/gateway/fake.d.ts

@@ -0,0 +1,161 @@
+import type { MessageAttachment } from '../types.js';
+import type { Gateway, GatewayCapabilities, GatewayEvent, GatewayChat, GatewayHistoryRange, GroupChatResolution, GroupChatResolutionRequest, HandleCheck, ImsgMessage, NamePhotoShareResult, Reaction, ReactionNote, ReactResult, SendResult, SendStatus, SendTarget } from './types.js';
+export interface FakeGatewayOptions {
+    latencyMs?: number;
+    capabilities?: Partial<GatewayCapabilities>;
+}
+export declare class FakeGateway implements Gateway {
+    readonly capabilities: GatewayCapabilities;
+    private messages;
+    private chats;
+    private groupDirectoryComplete;
+    private groupParticipantsUnreported;
+    private namePhotoSharedChats;
+    private reachableAddresses;
+    private sentGuids;
+    private nextId;
+    private nextChatId;
+    private latencyMs;
+    private subscribers;
+    private activeSubscribers;
+    private forcedSendFailure;
+    constructor(opts?: FakeGatewayOptions);
+    private delay;
+    private allocId;
+    private emit;
+    private ensureDmChat;
+    private latestMessage;
+    private newestIncoming;
+    private buildMessage;
+    private buildOutboundMessage;
+    private toggleReaction;
+    subscribe(sinceId?: number): AsyncIterable<GatewayEvent>;
+    history(chatId: number, limit?: number): Promise<ImsgMessage[]>;
+    listChats(limit?: number): Promise<GatewayChat[]>;
+    historyRange(chatId: number, range: GatewayHistoryRange): Promise<ImsgMessage[]>;
+    send(target: SendTarget, text: string): Promise<SendResult>;
+    react(chatId: number, reaction: Reaction, expectedGuid?: string): Promise<ReactResult>;
+    createGroup(handles: string[], firstMessage: string): Promise<{
+        chatId: number;
+    }>;
+    recentReactions(chatId: number, limit?: number): Promise<ReactionNote[]>;
+    resolveDmChat(handle: string): Promise<number | null>;
+    resolveGroupChat(request: GroupChatResolutionRequest): Promise<GroupChatResolution>;
+    sendStatus(guid: string): Promise<SendStatus>;
+    checkHandle(address: string, opts?: {
+        aliasType?: 'phone' | 'email';
+    }): Promise<HandleCheck>;
+    private findInScanWindow;
+    tapback(chatId: number, targetGuid: string, reaction: Reaction, remove?: boolean): Promise<ReactResult>;
+    emojiTapback(chatId: number, targetGuid: string, emoji: string, remove?: boolean): Promise<ReactResult>;
+    sendRich(chatId: number, text: string, opts?: {
+        effect?: string;
+        replyToGuid?: string;
+        subject?: string;
+    }): Promise<SendResult>;
+    sendAttachment(chatId: number, _filePath: string, opts?: {
+        audio?: boolean;
+        replyToGuid?: string;
+    }): Promise<SendResult>;
+    sendSticker(chatId: number, _filePath: string, _opts?: {
+        attachToGuid?: string;
+        partIndex?: number;
+    }): Promise<SendResult>;
+    sendPoll(chatId: number, question: string, options: string[]): Promise<SendResult>;
+    sendRichLink(chatId: number, _url: string): Promise<SendResult>;
+    editMessage(chatId: number, targetGuid: string, text: string): Promise<{
+        ok: boolean;
+    }>;
+    unsendMessage(chatId: number, targetGuid: string): Promise<{
+        ok: boolean;
+    }>;
+    deleteMessage(chatId: number, targetGuid: string): Promise<{
+        ok: boolean;
+    }>;
+    setTyping(chatId: number, _on: boolean): Promise<{
+        ok: boolean;
+    }>;
+    markRead(chatId: number): Promise<{
+        ok: boolean;
+    }>;
+    renameGroup(chatId: number, name: string): Promise<{
+        ok: boolean;
+    }>;
+    setGroupPhoto(chatId: number, _filePath?: string): Promise<{
+        ok: boolean;
+    }>;
+    addParticipant(chatId: number, handle: string): Promise<{
+        ok: boolean;
+    }>;
+    removeParticipant(chatId: number, handle: string): Promise<{
+        ok: boolean;
+    }>;
+    leaveGroup(chatId: number): Promise<{
+        ok: boolean;
+    }>;
+    shareNamePhoto(chatId: number): Promise<NamePhotoShareResult>;
+    setGroupDirectoryComplete(complete: boolean): void;
+    setGroupParticipantsUnreported(chatId: number, unreported: boolean): void;
+    injectInbound(params: {
+        chatId?: number;
+        sender: string;
+        senderName?: string;
+        text?: string;
+        attachments?: MessageAttachment[];
+    }): ImsgMessage;
+    injectReaction(params: {
+        chatId: number;
+        sender: string;
+        senderName?: string;
+        reaction?: Reaction;
+        emoji?: string;
+        targetGuid?: string;
+    }): ImsgMessage;
+    injectPollCreate(params: {
+        chatId?: number;
+        sender?: string;
+        senderName?: string;
+        fromMe?: boolean;
+        question: string;
+        options: string[];
+    }): {
+        balloon: ImsgMessage;
+        caption: ImsgMessage;
+    };
+    private pollSnapshot;
+    injectPollVote(params: {
+        chatId: number;
+        sender: string;
+        senderName?: string;
+        pollGuid: string;
+        optionIds: string[];
+    }): ImsgMessage;
+    injectPollAddOption(params: {
+        chatId: number;
+        sender: string;
+        senderName?: string;
+        pollGuid: string;
+        optionText: string;
+    }): ImsgMessage;
+    failNextSend(): void;
+    setHandleReachable(address: string, reachable: boolean): void;
+    ensureDm(handle: string): number;
+    snapshot(): {
+        chats: Array<{
+            chatId: number;
+            chatGuid: string;
+            isGroup: boolean;
+            participants: string[];
+        }>;
+        messages: ImsgMessage[];
+    };
+    devRestoreSnapshot(input: {
+        readonly chats: ReadonlyArray<{
+            readonly chatId: number;
+            readonly isGroup: boolean;
+            readonly participants: readonly string[];
+        }>;
+        readonly messages: readonly ImsgMessage[];
+    }): void;
+    onEvent(listener: (msg: ImsgMessage) => void): () => void;
+}