@mapier/imsg-sdk

TypeScript SDK for iMessage automation on macOS via the Mapier-patched imsg native layer, a fork of 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:

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
}

Hosted synthetic runtimes can persist the versioned value returned by snapshot() and restore it into a fresh instance with devRestoreSnapshot(). This driver-only state includes gateway evidence such as send status, handle reachability, and Name & Photo idempotency; it is not part of the real Gateway interface.

See 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/deploy, prebuilt binaries on release 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 for host setup and docs/gateway-contract.md for the full interface contract.

Host preflight and API docs

Check the selected binary and injected bridge before deploying:

npx @mapier/imsg-sdk doctor
npx @mapier/imsg-sdk doctor --json

The doctor reports the native version, basic/bridge readiness, available patched selectors, and advertised RPC surface. It fails only when basic host control is unavailable; bridge problems remain explicit warnings so read-only deployments can still run.

• API guide — imports, contract groups, and the doctor API.
• Native compatibility — required binary/bridge pairing, release evidence, and known constraints.
• Capability matrix — every public action's verification and native-build status.
• Host operations — durable cursors, restart handling, and safe support evidence.
• examples/host-read.ts — preflight plus a real host history/watch client.

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.

Versioning

This package follows SemVer and is published to npm as @mapier/imsg-sdk (pnpm add @mapier/imsg-sdk). Pre-1.0: minor versions may break the API. See CONTRIBUTING.md for the release process and CHANGELOG.md for the version history.

License

MIT — see LICENSE. The native layer is a fork of openclaw/imsg, separately MIT-licensed upstream.