@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
}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/macos26-tier2, 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.
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.