@mapier/imsg-sdk 0.2.2 → 0.3.0

package/docs/gateway-contract.md

@@ -57,6 +57,10 @@ interface Gateway {
     groupPhoto: boolean;
     groupParticipants: boolean;
     namePhotoSharing: boolean;
+    chatBackgroundSet: boolean;
+    chatBackgroundRemove: boolean;
+    editMessage: boolean;
+    mentionFormatting: boolean;
   };
   subscribe(sinceId?: number): AsyncIterable<GatewayEvent>;
   history(chatId: number, limit?: number): Promise<ImsgMessage[]>;
@@ -91,7 +95,11 @@ interface Gateway {
   ): 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 }>;
+  editMessage(chatId: number, targetGuid: string, text: string): Promise<{
+    ok: boolean;
+    skipped?: 'unchanged';
+    effectStarted?: 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 }>;
@@ -106,6 +114,21 @@ interface Gateway {
     skipped?: 'not-offered';
     effectStarted?: boolean;
   }>;
+  chatBackgroundStatus(chatId: number): Promise<{
+    chatId: number;
+    backgroundSet: boolean;
+    backgroundGuid: string | null;
+  } | null>;
+  setChatBackground(chatId: number, preset?: 'gradient'): Promise<{
+    ok: boolean;
+    backgroundGuid?: string;
+    effectStarted?: boolean;
+  }>;
+  removeChatBackground(chatId: number, expectedGuid?: string): Promise<{
+    ok: boolean;
+    skipped?: 'no-background';
+    effectStarted?: boolean;
+  }>;
 }
 
 interface ReactionNote {
@@ -160,7 +183,16 @@ both the long-lived RPC process and its one-time `status --json` probe.
 Patched verbs require the injected bridge's explicit selector markers
 `emojiTapbackSend`, `stickerSend`, `groupPhotoUpdate`, `groupAddParticipant`, and
 `groupRemoveParticipant`; Name & Photo requires both `namePhotoShouldOffer`
-and `namePhotoShare`; emoji additionally requires the selected RPC binary
+and `namePhotoShare`; chat backgrounds are gated per verb on
+`chatBackgroundSetGradient` (setter + PosterBoard/ChatKit runtime) and
+`chatBackgroundRemove` (setter + live-GUID getter), which the injected helper
+already composes; edit message requires any one of `editMessageItemTranslation`
+(macOS 27's five-argument `-[IMChat editMessageItem:…newPartTranslation:…]`,
+imsg#3), `editMessageItem` (macOS 26) or `editMessage` (macOS 13) — the helper
+uses the first present one; confirmed @mentions on `sendRich` require
+`mentionFormatting`, which the helper advertises only when IMSharedUtilities'
+confirmed-mention attribute key resolves at runtime (imsg#13); emoji
+additionally requires the selected RPC binary
 to report `rpc_features:["tapback.emoji"]`. That second half prevents a
 patched dylib behind a stock CLI from false-advertising custom emoji support.
 Missing status, malformed JSON, or absent markers fail closed.
@@ -175,10 +207,11 @@ guid by scanning `history(chatId, 30)` — the same 30-message ceiling
 `recentReactions` already documents above — so a guid older than that is as
 invisible to these methods as it is to `recentReactions`. `tapback` and
 `deleteMessage` pre-check against that scan before firing, so they return
-`{ ok: false }` without touching anything; `editMessage`/`unsendMessage` fire
-the RPC first and only find the ceiling on the VERIFY pass, so a guid outside
-the window still reports `{ ok: false }` but may have mutated the real row on
-the way there — "no confirmable effect," not a guaranteed no-op. FakeGateway
+`{ ok: false }` without touching anything, and so does `editMessage` (it also
+refuses a message that is not `is_from_me`); `unsendMessage` fires the RPC
+first and only finds the ceiling on the VERIFY pass, so a guid outside the
+window still reports `{ ok: false }` but may have mutated the real row on the
+way there — "no confirmable effect," not a guaranteed no-op. FakeGateway
 must enforce the identical window regardless: finding the target guid by
 scanning ALL of `this.messages` unconditionally would let the fake succeed
 at targeting a message the real path can't reach (parity rule 2) — a
@@ -219,6 +252,46 @@ prevent.
   this Gateway because `ImsgMessage` has no subject field. The `url` submode is
   exposed separately as `sendRichLink` because openclaw treats URL and
   text/subject/effect/reply as mutually exclusive modes.
+  `opts.textFormatting` is a list of ranges over the text in **UTF-16 code
+  units** (a JS string index; an emoji is two units): `styles`
+  (bold/italic/underline/strikethrough, macOS 15+, silently dropped on older
+  hosts), `effect` (a named macOS 27 text effect, resolved to Apple's id in
+  `resolveTextFormatting`), and `mention` — a **confirmed @mention**
+  (imsg#13, merged into `mapier/deploy` as `7c31772` — the pinned submodule
+  — `docs/send.md` "Text formatting and mentions"; the rules below mirror
+  `IMsgMentionFormatting.m` at that revision). `mention` is the EXACT `IMHandle.ID` of a participant of the
+  target chat as IMCore reports it (E.164 phone or the email), matched
+  byte-for-byte by the helper against the live participant list; the visible
+  text in the range must be the person's display name, never the handle (a
+  handle as visible text renders as a phone link with no highlight and no
+  notification, verified 2026-09-03 on an iPhone). Do not prefix the name
+  with "@": Messages' composer swallows the typed "@" and a genuine mention
+  row carries only the highlighted name (an "@" in the range simply renders
+  as text, as the 2026-09-03 SDK run showed). Formatting is **never
+  degraded**: the shared preflight `sendRichPreflight` /
+  `textFormattingRefusal` runs before the bridge is touched and refuses, with
+  a typed `SendResult.refused`, a mention range on a bridge without the
+  `mentionFormatting` marker (`mention-capability`), bad offsets on ANY range
+  — non-integer, zero length, outside the text, or splitting a surrogate pair
+  (`text-formatting-range`; the helper would otherwise silently drop a style
+  range and send plain text, which a caller cannot detect since formatting
+  is write-only), and a mention identifier that is not a bounded id or whose
+  visible text is the handle itself (`mention-identifier`). The helper
+  refuses a non-participant handle (`-32603` "Mention identifier is not a
+  participant handle of this chat", no row written), which `ImsgGateway`
+  classifies as `mention-not-participant`; a chat whose live participant
+  list is unreadable refuses every mention the same way. FakeGateway applies
+  the same preflight, checks membership against its chat record, and refuses
+  all mentions on an unreported-directory group. **A bare `ok:false` without
+  `refused` is NOT a no-send guarantee** (bridge timeout, transport loss);
+  only a `refused` result proves nothing was sent. Formatting and mentions
+  are write-only through this Gateway: `ImsgMessage` exposes neither, so the
+  smoke reads the confirmed-mention attribute (`__kIMMentionConfirmedMention`
+  followed by the handle) from `chat.db message.attributedBody` directly. The
+  `--only-mention` leg is opt-in via `--mention-handle` even in the full
+  Tier-2 run, because a confirmed mention notifies a real person.
+  **Host-verified 2026-09-03** through `ImsgGateway` on the shared Mac,
+  including the recipient-side highlight on an iPhone (see the ledger).
 - **`sendAttachment(chatId, filePath, opts?)`** — `send.attachment`
   (`handleSendAttachment`). Targets an **existing** chat only. `opts.audio:true`
   sends the file as a native voice-note bubble; `opts.replyToGuid` sets an
@@ -265,8 +338,44 @@ prevent.
   balloon lands as its own row later. `SendResult.guid` is therefore always
   undefined here; FakeGateway must not return one either.
 - **`editMessage(chatId, targetGuid, text)`** — `message.edit`
-  (`handleMessageEdit`). **Edits mutate the existing row's text IN PLACE: no
-  new row, no `subscribe()` event.** `MessageWatcher`'s cursor is a ROWID
+  (`handleMessageEdit`; imsg `docs/edit.md`). Capability-gated on the
+  `editMessage` marker (see above): on macOS 27 the helper calls the
+  five-argument `editMessageItem:atPartIndex:withNewPartText:newPartTranslation:backwardCompatabilityText:`
+  with part index 0 and the new text as backwards-compatibility text, and the
+  RPC answers `{ok:true}` on invocation only. **Preflight before firing**, same
+  discipline as `tapback`/`deleteMessage`: the guid must be inside the scan
+  window — located by a short poll (3 × 1 s, sleeping only between reads),
+  because a just-sent guid can lag history by a beat and a one-shot read
+  would fail closed on a message about to appear —
+  and the message must be an **editable own plain-text message**
+  (`isEditableOwnTextMessage` in `gateway/types.ts`, shared by both
+  implementations): `is_from_me` (Apple only permits editing your own
+  messages and the helper does not check), non-empty `text`, and no
+  attachments/poll — the RPC always edits part 0, which on those rows is not
+  the text, and a retracted row has nothing left to edit. Anything else is
+  refused as `ok:false, effectStarted:false` without touching the bridge, as
+  is empty or whitespace-only text. Text identical to the current row is the
+  idempotent `skipped:'unchanged'` (`ok:true`, nothing fired). The whole
+  decision is one shared function (`decideEditMessagePreflight`) so the two
+  implementations cannot drift. Known gap: a rich-link balloon carries its
+  URL as `text` and nothing on `ImsgMessage` marks it, so the real path
+  fires on it and the read-back decides; FakeGateway's rich-link row has no
+  text and is refused. After the RPC fires, a structured `-32603` whose
+  `data` is one of the helper's pre-invoke refusals (chat/message not found,
+  no selector, bad signature) is `effectStarted:false`; a bridge timeout or
+  any other `-32603` (an exception after IMChat was invoked) and an
+  unconfirmed read-back are `ok:false, effectStarted:true` — a consumer
+  reconciles those rather than treating them as a no-op. **Host-verified
+  2026-09-03** through `ImsgGateway` on the shared Mac (see the ledger
+  below); recipient-side rendering remains unobserved. `unsendMessage`
+  deliberately keeps its fire-first shape: retracting a just-sent row is a
+  legitimate use and its verify pass is the existing contract; a matching
+  preflight is a follow-up, not part of this change. Native CLI/RPC E2E on macOS 27 `26A5421a` (imsg#11, chat 8): both
+  paths edited a fresh own message and read the new text back on the same
+  guid/ROWID, with `message.date_edited` stamped — that column is not exposed
+  through `messages.history`, so the SDK smoke reads it from chat.db directly
+  while the gateway verifies by text read-back. **Edits mutate the existing
+  row's text IN PLACE: no new row, no `subscribe()` event.** `MessageWatcher`'s cursor is a ROWID
   high-water mark (`WHERE ROWID > cursor`), so an UPDATE to an existing row is
   structurally invisible to the watch stream — the only way to observe an
   edit is re-reading `history()` and comparing text for a guid you already
@@ -340,6 +449,81 @@ both implementations — none of Apple's group primitives apply to a 1:1 chat.
   and the receiving iPhone displayed Mapi's new contact info, closing the
   receiver-side verification gap.
 
+- **Chat backgrounds** — `chatBackgroundStatus` / `setChatBackground` /
+  `removeChatBackground` (Mapier-Labs/imsg#12, `chat.background.status|set|remove`).
+  A background is chat-scoped state recorded in chat.db's background tables,
+  not a message row: there is no `subscribe()` event and no history row on
+  either implementation. DM and group chats both accept all three verbs.
+  `chatBackgroundStatus` is a plain chat.db read (no selector marker, but it
+  needs the imsg#12 binary: an older build answers `-32601` and the call
+  throws). `null` means the chat does not exist (`-32602`); any other failure
+  is thrown, so a transient rpc/bridge fault can never masquerade as "no such
+  chat". It returns the persisted background channel GUID, which **lags
+  imagent** — a durable snapshot, never the live IMChat state.
+  `setChatBackground` supports the single runtime-verified `gradient` preset.
+  On the native side the RPC returns on helper acceptance — its response
+  embeds the pre-mutation chat.db snapshot, so no separate preflight read —
+  and the pipeline (PosterBoard builder → hidden `OverFullScreen` editor →
+  ChatKit poster/watch payloads → `setTranscriptBackgroundAndSendToChat:transferID:`)
+  runs asynchronously, bounded by per-stage watchdogs and a 90 s overall cap.
+  `ImsgGateway` therefore polls `chat.background.status` under a 90 s
+  deadline on a **monotonic** clock (`performance.now()`; a wall-clock
+  rollback cannot stretch the wait — the native CLI's own window; read first,
+  sleep 1 s between), in the pure loop `src/gateway/chat-background.ts`. Each poll is a
+  local chat.db read. The helper's operation record is a bridge round-trip on
+  Messages' main thread — it competes with the pipeline itself and, because
+  the native JSON-RPC loop is strictly serial, holds every other gateway verb
+  for up to 10 s on a stall — so it is read only (a) once, pulled forward,
+  when a NEW candidate appears (a background GUID different from the
+  pre-mutation snapshot) and (b) on a 15 s cadence for early failure
+  detection; a helper read that times out doubles that gap, up to 60 s, and
+  chat.db polling carries on meanwhile. **Success requires operation
+  correlation**: a candidate is accepted only when it equals the record's
+  `transfer_id` (the identifier IMChat persists as the background GUID, imsg
+  `docs/chat-background.md`). A changed guid, a newer `set` event, or both
+  are NOT evidence — a delayed write from an earlier operation satisfies them
+  — and a helper that no longer tracks the operation (bounded record table,
+  Messages relaunch) leaves nothing to correlate with, so that case ends the
+  wait as ambiguous rather than guessing. A bridge-timeout on a verification
+  read keeps polling; any other read failure (dead rpc child, transport loss)
+  ends the wait as ambiguous. `ok:true` carries the persisted GUID; a re-set
+  replaces the background and the GUID changes. FakeGateway mints a fresh GUID
+  per set from a sequence it persists in its snapshot. Result semantics
+  follow `shareNamePhoto`: `effectStarted:false` is a proven preflight
+  rejection — capability absent, `-32602` (unknown chat, bad preset), or a
+  helper refusal the SDK recognises in the JSON-RPC `error.data` (busy with
+  another background operation — the helper holds one in-process lock —,
+  guard mismatch, missing selector/runtime, "did not queue"); `ok:false,
+  effectStarted:true` means the effect may have started and persistence was
+  not proven — helper record `failed`, the deadline passed, an
+  rpc-child/transport failure, a bridge timeout, or any other `-32603` such as
+  an exception raised after IMChat was invoked (the native server reports all
+  of these under one code with the reason only in `data`) — and must be
+  reconciled, never reported as a proven no-op.
+  `removeChatBackground` is driven by the helper's **live** IMChat GUID, never
+  the caller's chat.db snapshot. The optional `expectedGuid` is a
+  compare-and-clear guard evaluated against that live GUID **first**, before
+  the no-background check: a mismatch — including a guard on a chat with no
+  live background — is `ok:false, effectStarted:false` and leaves the
+  background in place. An empty string is no guard (`normalizeChatBackgroundGuard`
+  in `gateway/types.ts`, shared by both implementations; the wire only
+  carries a non-empty one). Only then is a chat with no live background the
+  explicit `skipped:'no-background'` no-op (`ok:true`, IMChat never invoked).
+  The gateway reads chat.db before firing (the remove response's own snapshot
+  is post-invoke) and after a real clear checks that response, then polls
+  under a 30 s deadline for a `clear` event newer than the baseline; an unchanged empty
+  snapshot counts only when the pre-mutation read recorded the background
+  that is now gone, because an already-lagging empty snapshot proves nothing.
+  Native Set/Remove semantics were smoke-verified on macOS 27 `26A5421a`
+  (matching live GUID, chat.db event, cache, watch cache, upload metadata),
+  and the production CLI/RPC path went through its matched-build E2E before
+  imsg#12 merged. The SDK verbs were **host-verified 2026-09-03** through
+  `ImsgGateway` on the shared Mac (`--only-chat-background` leg of
+  `scripts/tier2-smoke.ts`; see the ledger below); recipient-side rendering,
+  group chats and the replace path remain unobserved. The leg
+  (`scripts/tier2-chat-background-leg.ts`) stops at the first failed check
+  and never clears a background whose guid it did not read back.
+
 **Host-verification ledger.** Exercised through `ImsgGateway` on the host Mac
 2026-07-14 (`scripts/tier2-smoke.ts`, chat 3996):
 
@@ -361,6 +545,66 @@ Each leg prints an EYEBALL step because a local write is not proof of
 receiver-visible delivery (the group-photo lesson). The `sendRich`
 text/effect/reply path was already live-verified.
 
+Exercised 2026-09-03 on the shared Mac (macOS 27 `26A5421a`, user
+`mapidev`, disposable DM chat 8, SDK `bf92147` against the deployed imsg#12
+CLI/helper: `bridge_version 2`, `v2_ready true`, `chatBackgroundSetGradient
+true`, `chatBackgroundRemove true`; `scripts/tier2-smoke.ts 8
+--only-chat-background`, run dir `map175-sdk-bg-e2e.PCVLad`):
+
+- **`setChatBackground` / `removeChatBackground` / `chatBackgroundStatus`**
+  — live-verified: both capability rows; baseline `backgroundSet:false`;
+  Set Gradient persisted a NEW background guid in ~7 s and a separate status
+  read returned the same guid; Remove with `NOT-THE-LIVE-GUID` →
+  `ok:false, effectStarted:false` with the background unchanged (the logged
+  `ImsgRpcError` is the deliberate mismatch); guarded Remove cleared it,
+  status read `backgroundSet:false`, and an unguarded Remove on the bare
+  chat → `skipped:'no-background'`. `ALL PASS`, exit 0; the audit recorded
+  two events, both in chat 8; native status identical before and after and
+  the fixture back at its no-background baseline. The `live-smoke.ts 8
+  --read-only` gate passed first. Not observed: the receiving device
+  rendering the Gradient; not covered: group chats, the replace (re-set)
+  path, relay/public-API integration.
+
+Exercised 2026-09-03 on the same host (SDK `6cf6ac5` against the same
+deployed helper: `editMessageItemTranslation true`, the two four-argument
+markers false; `scripts/tier2-smoke.ts 8 --only-edit-message`, run dir
+`map175-sdk-edit-e2e.fgUq4t`):
+
+Exercised 2026-09-03 on the same host (SDK `6e28c82` against the deployed
+imsg#13 helper, `mentionFormatting true`; disposable group chat 12 with
+three phone-handle participants; `scripts/tier2-smoke.ts 12 --only-mention
+--mention-handle <participant IMHandle.ID> --mention-name <display name>`, run dir
+`map175-sdk-mention-e2e.PuauKG`):
+
+- **`sendRich` confirmed @mention** — live-verified: capability row;
+  `@Neo tier2-smoke 21:13:08 mention` sent
+  (`86246294-B16D-4E5C-9E15-D5E80C90CB14`, row 3143) and read back on the
+  same guid; `chat.db attributedBody` carries `__kIMMentionConfirmedMention`
+  at byte 266 followed by the handle at byte 300; a non-participant handle
+  refused by the helper (`-32603` "Mention identifier is not a participant
+  handle of this chat") → `refused:'mention-not-participant'`, a range
+  outside the text → `'text-formatting-range'`, and the handle as visible
+  text → `'mention-identifier'`, none of the three texts in history
+  afterwards. 9/9 PASS, `ALL PASS`, exit 0; the audit recorded exactly one
+  event, in chat 12; native status identical before and after. The
+  `live-smoke.ts 12 --read-only` gate passed first (6/6). **Recipient-side
+  observed** this time: on the mentioned participant's iPhone the message
+  rendered with "@Neo" highlighted in the same style as a native mention.
+  Not covered: email-handle mentions (not covered natively either), the
+  `send-attachment` / multipart mention legs (no SDK surface).
+
+- **`editMessage`** — live-verified: capability row from the three-marker
+  fold; marker message sent (`73263626-5A07-4B3C-8244-D3133B8A8EA6`), edited,
+  new text read back on the SAME guid, `chat.db message.date_edited`
+  stamped (`810141791007747072`); unchanged text → `skipped:'unchanged'`;
+  whitespace text → `ok:false, effectStarted:false` with the edited text
+  still in place; the chat's newest inbound row (the DM partner's echo of
+  the marker) → `ok:false, effectStarted:false` and untouched. 10/10 PASS,
+  `ALL PASS`, exit 0; native status identical before and after. The
+  `live-smoke.ts 8 --read-only` gate passed first (6/6). Not observed: the
+  receiving device rendering "Edited" (the inbound echo carried the original
+  text, which is the partner's copy, not evidence either way).
+
 - **subscribe(sinceId?)** — long-lived event stream of new messages/reactions across all
   chats the host Mac's Messages account can see. `sinceId` is an **exclusive** cursor: only
   events with `id > sinceId` are delivered (catch-up semantics, not "starting at"). Today
@@ -783,8 +1027,16 @@ harness (`tsx --test`, see `package.json`). Required cases:
   returns `ok:false` for fewer than two options or an unknown chat
 - `sendRichLink` echoes an outbound row and returns `ok:false` for an unknown chat; preview
   metadata is not queryable through `ImsgMessage`
+- `sendRich` with a confirmed mention of a participant sends once (DM and group, alongside
+  styles); a non-participant handle, a wrongly formatted participant, a range outside the
+  text (mention OR style), an empty or padded handle, the handle as visible text, an
+  unreported group directory, and a missing `mentionFormatting` marker each return
+  `ok:false` with the matching typed `refused` reason and nothing sent
 - `editMessage` changes the target row's text in place — same row count before/after, no
-  new row
+  new row; refuses an inbound (not `is_from_me`) message, empty/whitespace text, and our own
+  message outside the scan window without mutation;
+  unchanged text is the idempotent `skipped:'unchanged'`; returns `ok:false` without
+  mutation when the `editMessage` capability marker is absent
 - `unsendMessage` retracts the target row (text clears, row persists);
   `deleteMessage` is dispatch-only with no stable history postcondition (the
   fake conservatively preserves the row); both return `ok: false` for an
@@ -794,13 +1046,19 @@ harness (`tsx --test`, see `package.json`). Required cases:
 - `renameGroup`/`addParticipant`/`removeParticipant` are reflected in a message sent
   afterward (`chat_name`/`participants`) and return `ok: false` against a DM
 - `setGroupPhoto`/`leaveGroup` return `ok: true` against a group and `ok: false` against a DM
-- patched sticker, group-photo, and participant verbs return `ok:false` without mutation
-  when their `imsg status` capability markers are absent
+- patched sticker, group-photo, participant, and chat-background verbs return `ok:false`
+  without mutation when their `imsg status` capability markers are absent
+- chat background: `setChatBackground` persists a NEW guid on a DM and a group (a re-set
+  changes the guid), `chatBackgroundStatus` reflects it, `removeChatBackground` clears it;
+  remove on a bare chat is the explicit `no-background` skip (also with an empty guard), a
+  mismatched `expectedGuid` is a preflight rejection that leaves the background (and is
+  checked before the no-background branch, so a stale guard on a bare chat rejects), and an
+  unknown chat never starts an effect
 - `recentReactions` surfaces an inbound custom-emoji reaction (`reaction: 'custom'`) with the
   real `emoji` intact
 - Fake-only restart coverage snapshots and restores a world, then proves
-  `sendStatus`, `checkHandle`, Name & Photo idempotency, current group metadata,
-  fixture state, and monotonic IDs survive exactly
+  `sendStatus`, `checkHandle`, Name & Photo idempotency, chat backgrounds (and their
+  guid sequence), current group metadata, fixture state, and monotonic IDs survive exactly
 
 FakeGateway runs this suite in CI on every PR. ImsgGateway runs it as a manual runbook step on
 the host Mac (see `docs/host-mac-control.md`) until a host-Mac CI runner exists — at that point