@mapier/imsg-sdk 0.2.0 → 0.2.1

package/docs/interactions.md

@@ -0,0 +1,176 @@
+# Interaction catalog
+
+`src/interactions/` is the extensibility seam for iMessage interaction kinds: web-link
+cards, App Clip checkout sheets, native balloons (tapbacks, polls, message effects, URL
+previews), and a future MSMessages host-extension tier. It is a typed catalog
+(`InteractionRegistry`) plus a device-free trial harness (`InteractionHarness`) over
+`FakeGateway`. It does not change `src/gateway/*` — every claim about our own Gateway is a
+citation against `docs/gateway-contract.md` / `docs/imsg-polls.md`, never a new capability.
+Claims about external products (cited below) are outside what this repo's docs can verify.
+
+## Four-mechanism model
+
+| Tier | Install cost | Reach | Richness | Fallback |
+|---|---|---|---|---|
+| `web-surface` | none | anyone with the link | full web UI, but leaves the chat | none — this **is** the floor |
+| `app-clip` | none (ephemeral, no App Store entry) | anyone with an iPhone | native sheet (checkout/action UI), in-flow | `web-url` |
+| `native-balloon` | none | anyone (stock Messages) | Apple's own balloon types only — tapback, poll, message effect, URL preview | `plain-text` |
+| `extension` | recipient installs our MSMessages host **once** | installed users only | fully custom, live/interactive card, reusable across mini-apps | `web-url` |
+
+Every tier richer than `web-surface` degrades to something (`InteractionDescriptor.fallback`) —
+a recipient without the richer capability is never left with nothing, just a less rich version
+of the same interaction.
+
+**Two corrections to the naive three-tier read, both citing external primary sources (not
+verifiable from this repo's own docs, cited here as provenance):**
+
+- **App Clips are zero-install**, not "extension-lite." Apple's App Clip model launches an
+  ephemeral native experience straight from a link — no App Store visit, nothing left installed
+  after. Linq's Agent Pay flow uses exactly this: an iMessage link opens a native checkout sheet
+  with zero install cost, falling back to a web checkout on non-iPhone. That makes `app-clip`
+  tier-distinct from `extension` on the install axis even though both are "native" — **this is
+  the highest-value unbuilt lever for zero-install native interaction** in the catalog: richer
+  than a balloon, no install tax.
+- **A real MSMessages extension is a *host*, not a one-off card.** Photon's Spectrum model:
+  the recipient installs Photon's MSMessages extension once; after that, arbitrary mini-app URLs
+  render live in-bubble via `app(url, {live:true})` (`MSMessageLiveLayout` /
+  `MSMessagesAppViewController`), no per-mini-app install. Non-installed recipients get a URL
+  fallback. The install wall is real (Apple gates live/interactive rendering behind "the
+  extension is installed," full stop — no wire flag, no server-render around it) but it's a
+  *one-time* cost amortized across every future mini-app, not a per-card cost. See
+  `host-extension-card` below.
+
+## The contract
+
+`InteractionDescriptor` (`src/interactions/types.ts`) is one row per kind. `InteractionRegistry`
+enforces laws at `register()` time — a bad row fails at startup, not at first use:
+
+1. No duplicate `id`.
+2. `tier: 'extension'` requires `requiresRecipientInstall: true` — a real MSMessages host card
+   cannot exist without an install; a row claiming otherwise is a lie about the tier itself. This
+   check keys off `tier === 'extension'` specifically, not off `requiresRecipientInstall` in
+   general — `app-clip` is a separate, legitimately install-free tier and must not trip it.
+3. `correlation: 'none'` forbids `inboundReadback: true` — a readback needs a key to correlate
+   against.
+
+`InteractionRegistry.agentUsable()` — `outbound: 'agent' && status: 'host-smoked'` — is the set a
+product feature can actually build on today: the running agent process can trigger it, and the
+real host Mac has confirmed it does what it claims.
+
+### Status is not a success flag
+
+`InteractionStatus` (`unbuilt` → `fake-only` → `host-smoked`) is a **verification-maturity
+ladder** — how far up `unit tests → FakeGateway → live smoke on host Mac` (the ladder in this
+repo's `CLAUDE.md`) a kind has climbed. It does **not** mean "this works." `host-smoked` means
+*ground truth is known*, not *ground truth is good*. Usability is carried by `outbound` and
+`completionTransport`, not `status` — see `rich-link-card` below, which is `host-smoked` and
+simultaneously `outbound: 'none'` because the host run proved it does *not* deliver.
+
+## Today's catalog (`src/interactions/catalog.ts`)
+
+Several rows below are corrected against earlier catalog drafts a teammate proposed from memory;
+each correction was checked against this repo's own contract docs (or, for external-product
+claims, cited as cross-repo/external provenance) before being written into `catalog.ts`. Three
+corrections changed which kinds `agentUsable()` returns.
+
+- **`tapback`** — native-balloon, `message-guid` correlation. The real path is
+  `Gateway.tapback(chatId, targetGuid, reaction, remove?)`, not `react()` — `react()` takes no
+  guid parameter at all (it always targets "the newest incoming bubble", `expectedGuid` is a
+  precondition, not targeting; `docs/gateway-contract.md` §1). A row that claims
+  `message-guid` correlation only fits the guid-targeted verb. Host-verified: `tier2-smoke.ts`
+  fires add/remove and confirms against history in the same run. `fallback: 'plain-text'` — a
+  recipient just sees no tapback, only the plain message.
+- **`web-link`** — web-surface, `link-code` correlation, completion out-of-band (a product
+  store/webhook, not a Gateway event). This kind's real implementation (`link-surface.ts`, the
+  onboarding/round pages) lives in `imsg-agent`, not this repo, so its verification is outside
+  what `docs/gateway-contract.md` can attest to — flagged as such in its `notes`.
+  `fallback: 'none'` — it's the floor of the model, nothing to degrade to.
+- **`poll`** — native-balloon, `message-guid` correlation. **Corrected from a draft that had
+  `outbound: 'manual-host-op'`, citing "contract forbids Gateway poll send."** That citation was
+  wrong: the contract's forbidden-surface list says `sendPoll` *creates polls only* — it forbids
+  **voting/unvoting** through the Gateway, not creating. `sendPoll` itself is a first-class
+  `Gateway` method, live-verified delivering ("renders as a native interactive poll on the
+  receiving device", `docs/gateway-contract.md` "Host-verification ledger"). There is no
+  principled distinction that makes `tapback` agent-outbound but `poll` manual-only — both are
+  Tier-2 bridge verbs, both host-verified, both agent-callable. `outbound: 'agent'`. Voting stays
+  inbound-readback-only; the agent still cannot vote on anyone's behalf, only create.
+  `fallback: 'plain-text'`.
+- **`effect`** — native-balloon, correlation `none` (a send-time decoration, not a
+  request/response interaction). **Corrected from a draft that had `outbound: 'manual-host-op'`,
+  `status: 'unbuilt'`, citing "fork/IMCore can drive ~12 message effects via `balloonBundleID`;
+  not yet wired to Gateway."** That undercounts what's already shipped: `Gateway.sendRich`'s
+  `opts.effect` (`docs/gateway-contract.md` §1) already accepts exactly this set — 4 bubble
+  effects (`impact`, `loud`, `gentle`, `invisibleink`) + 8 screen effects (`confetti`, `lasers`,
+  `fireworks`, `balloons`, `sparkles`, `spotlight`, `echo`, `love`, `celebration`) — 12 total,
+  matching the draft's own count. The host-verification ledger states "the `sendRich`
+  text/**effect**/reply path was already live-verified." `outbound: 'agent'`, `status:
+  'host-smoked'`. This is the same mislabel `poll` had — a capability already wired through an
+  existing Gateway method, not a new unbuilt seam. `fallback: 'plain-text'`.
+- **`rich-link-card`** — native-balloon, correlation `none` (the real `sendRichLink` returns no
+  guid — `{ ok, queued }` only). `sendRichLink` **is** wired into `Gateway`
+  (`docs/gateway-contract.md` §1, `src/gateway/types.ts`), and on builds carrying the fork's
+  `mapier/richlink-sync-fix` patch it **delivers**. The earlier 2026-07-14 host run had
+  established it as non-delivering headless (`{ok:true, queued:true}` with no `chat.db` row —
+  rich links were the only send type forced down the dylib's *deferred* `dispatch_after` branch,
+  where the RPC response was written before the deferred block fired and a throw there was
+  silent; polls build the same balloon payload but dispatch synchronously). The same-day fork
+  fix moved rich links onto the synchronous dispatch path, and the follow-up host run recorded
+  an `is_sent=1` URLBalloonProvider row with `send_status` reporting delivery (`imsg-agent`
+  `docs/parking-lot.md` 2026-07-14 and the gateway contract's host-verification ledger). Two
+  caveats keep this row conservative: the url submode is iMessage-only (hard-rejects
+  SMS-service chats), and **no capability marker gates the patch** — a binary predating
+  `richlink-sync-fix` (including the pinned `v0.1.0` release) still returns `{ok:true}` while
+  silently dropping the send. `outbound: 'none'` therefore stands until the deployment
+  branch/release provably carries the patch: flipping it would put a kind into `agentUsable()`
+  that regresses silently on a stale binary, the exact over-claim `docs/gateway-contract.md`
+  parity rule 2 exists to prevent. Fallback until then: `send()` a bare URL as plain text — it
+  delivers, and the receiver's Messages auto-unfurls it into a preview card (gated behind
+  "Tap to Load" until Mapi is a saved contact). `status: 'host-smoked'` — see "Status is not a
+  success flag" above. `fallback: 'plain-text'`.
+- **`app-clip`** — **new tier**, `tier: 'app-clip'`, `requiresRecipientInstall: false` (App Clips
+  are ephemeral — no App Store install persists), `link-code` correlation, completion
+  out-of-band. Modeled on Linq's Agent Pay flow (cited above) — external product, cited as
+  provenance, not verified from this repo. `status: 'unbuilt'`: nothing in this SDK or its native
+  fork launches an App Clip today. `outbound: 'none'`. `fallback: 'web-url'` — a non-iPhone
+  recipient (or a stock flow before this is built) gets the existing `web-link` page instead.
+  Flagged as the catalog's highest-value unbuilt seam: richer than any `native-balloon` kind,
+  with `web-surface`'s zero install cost.
+- **`host-extension-card`** — renamed from an earlier draft's `extension-card`. `tier:
+  'extension'`, `requiresRecipientInstall: true`, `status: 'unbuilt'`. Modeled on Photon's
+  Spectrum host-extension pattern (cited above) — external product, cited as provenance. The
+  2026-07-14 spike (`imsg-agent` `docs/parking-lot.md`, cross-repo context) already ran and
+  returned a **verdict against building a bespoke per-feature extension**: Apple's own
+  `MSMessageLiveLayout` docs confirm a live/interactive card only renders on a device with the
+  *sending* extension installed, and there is no reverse-engineering precedent anywhere
+  (BlueBubbles/mautrix/jesec/Project Zero) for injecting a third-party extension balloon via
+  private API. The host model doesn't remove the install wall — it only amortizes it across
+  every future mini-app instead of paying it per card, which is a real difference in economics
+  but not in Apple's gate. `status` stays `unbuilt`; unlike the `app-clip` seam, this one is not
+  currently prioritized. `fallback: 'web-url'`.
+
+## Adding a kind
+
+Mirrors `docs/gateway-contract.md` §4's contributor discipline:
+
+1. **Real-path proof.** A manual host-Mac run (or, for `web-surface`/external-product-modeled
+   kinds, the owning repo's own verification, or cited external documentation) establishing
+   ground truth — what actually happens, not what the API promises.
+2. **Catalog row.** Register it in `catalog.ts` with `status` reflecting where that proof landed
+   (`fake-only` if only exercised against `FakeGateway`, `host-smoked` once real-path proof
+   exists) and `outbound`/`completionTransport`/`fallback` reflecting what the proof actually
+   showed — not what the API surface merely allows.
+3. **Conformance case.** A `tests/interactions.test.ts` case exercising the row through
+   `InteractionRegistry`/`InteractionHarness`.
+4. **This doc.** Update the row's writeup here with the citation.
+
+A row may enter the catalog as `status: 'unbuilt'` only as a documented seam — e.g. `app-clip`,
+`host-extension-card` — never as a placeholder for something already claimed to work elsewhere
+(the mistake the original `poll` and `effect` drafts made).
+
+## Unbuilt seams: priority note
+
+`app-clip` (zero-install, native, richer than any balloon) is the highest-value unbuilt lever in
+this catalog. `host-extension-card` (real MSMessages host extension) stays cataloged as a
+documented, deliberately `unbuilt` seam — the 2026-07-14 spike found the install wall real and
+not currently worth paying for a bespoke extension — but is not prioritized the way `app-clip`
+is.

package/docs/operations.md

@@ -0,0 +1,47 @@
+# Operating a host gateway
+
+## Start-up
+
+1. Build and inject the matching Mapier `imsg` CLI and bridge.
+2. Set `IMSG_BIN` to that CLI.
+3. Run `imsg-sdk doctor --json` and retain its output with the deployment.
+4. Refuse bridge-backed workflows unless doctor reports the needed capability.
+
+## Durable event consumption
+
+Gateway row IDs are global and monotonic. Persist the highest fully handled
+event ID only after downstream work succeeds, then pass it back to
+`subscribe(cursor)` after a process restart. The cursor is exclusive: an event
+with `id === cursor` is not delivered again.
+
+```ts
+let cursor = await loadLastHandledRowId();
+const gateway = new ImsgGateway(onUnexpectedRpcExit);
+
+for await (const event of gateway.subscribe(cursor)) {
+  await handle(event);
+  cursor = event.id;
+  await saveLastHandledRowId(cursor);
+}
+```
+
+`ImsgGateway` supervises a silent native watch session and resumes it from the
+last observed ID. That protects a running process. A process restart still
+requires the application's durable cursor; no SDK can infer whether the caller
+finished handling its last event.
+
+## Failure handling
+
+Treat the constructor's unexpected-RPC-exit callback as a supervisor signal:
+record the closed error context, construct a fresh gateway, and resume from the
+persisted cursor. Do not reuse an instance whose RPC child exited.
+
+For support reports, collect only:
+
+- SDK version and commit;
+- native fork commit and `imsg-sdk doctor --json` output;
+- macOS version and architecture;
+- the action name, result, and opaque message/chat IDs if available.
+
+Do not put message text, attachment paths, contact data, or raw private-API
+errors into shared logs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapier/imsg-sdk",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "TypeScript SDK for iMessage automation on macOS: the Gateway contract, ImsgGateway (real), and a device-free FakeGateway.",
   "license": "MIT",
   "repository": {
@@ -33,6 +33,9 @@
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "imsg-sdk": "./dist/cli.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -46,6 +49,10 @@
       "types": "./dist/polls.d.ts",
       "import": "./dist/polls.js"
     },
+    "./doctor": {
+      "types": "./dist/doctor.d.ts",
+      "import": "./dist/doctor.js"
+    },
     "./gateway/types": {
       "types": "./dist/gateway/types.d.ts",
       "import": "./dist/gateway/types.js"
@@ -62,6 +69,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "scripts/*.applescript"
   ],
   "scripts": {