@mapier/imsg-sdk 0.3.1 → 0.5.0

package/docs/gateway-contract.md

@@ -61,6 +61,8 @@ interface Gateway {
     chatBackgroundRemove: boolean;
     editMessage: boolean;
     mentionFormatting: boolean;
+    sharedLocations: boolean;
+    locationRequest: boolean;
   };
   subscribe(sinceId?: number): AsyncIterable<GatewayEvent>;
   history(chatId: number, limit?: number): Promise<ImsgMessage[]>;
@@ -104,10 +106,10 @@ interface Gateway {
   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 }>;
+  renameGroup(chatId: number, name: string): Promise<GroupMutationResult>;
   setGroupPhoto(chatId: number, filePath?: string): Promise<{ ok: boolean }>;
-  addParticipant(chatId: number, handle: string): Promise<{ ok: boolean }>;
-  removeParticipant(chatId: number, handle: string): Promise<{ ok: boolean }>;
+  addParticipant(chatId: number, handle: string): Promise<GroupMutationResult>;
+  removeParticipant(chatId: number, handle: string): Promise<GroupMutationResult>;
   leaveGroup(chatId: number): Promise<{ ok: boolean }>;
   shareNamePhoto(chatId: number): Promise<{
     ok: boolean;
@@ -129,8 +131,30 @@ interface Gateway {
     skipped?: 'no-background';
     effectStarted?: boolean;
   }>;
+
+  // Find My locations (M2B-31). See "Location" below.
+  readSharedLocations(chatGuid?: string): Promise<SharedLocation[]>;
+  sendLocationRequest(chatId: number): Promise<SendResult>;
+  watchLocations(): AsyncIterable<LocationUpdate>;
+}
+
+interface SharedLocation {
+  handle: string; // IMFindMyHandle.identifier: E.164 phone or Apple ID email
+  chatGuid?: string; // the handle's DM chat when resolvable
+  latitude?: number; // present together with longitude, only on a valid fix
+  longitude?: number;
+  horizontalAccuracyM?: number;
+  altitudeM?: number;
+  speedMps?: number; // -1 = unknown
+  locationType?: number; // FMLLocation.locationType raw
+  coarseAddress?: string;
+  capturedAt?: string; // ISO8601 UTC, FMLLocation.timestamp
+  isValid: boolean; // false = sharing, no fix yet (no coordinates)
 }
 
+type LocationShareEvent = 'location_update' | 'share_started' | 'share_ended';
+type LocationUpdate = SharedLocation & { event: LocationShareEvent };
+
 interface ReactionNote {
   id: number; // the reaction's global rowid
   // 'custom' covers an arbitrary-emoji tapback (iOS 18+, imsg surfaces it as
@@ -145,7 +169,12 @@ interface ReactResult {
   skipped?: 'already-reacted' | 'stale-target' | 'not-reacted';
 }
 
-type GatewayEvent = ImsgMessage; // message or reaction; see §2 shape
+// message or reaction; see §2 shape. Deliberately NOT widened to a union
+// for Find My updates (0.4.0): every pinned consumer reads `.id`/`.chat_guid`
+// straight off the subscribe value (imsg-relay mac-daemon, imsg-agent
+// runtime-event-source), so live location changes have their own stream,
+// `watchLocations()`, and this type stays exactly what it was.
+type GatewayEvent = ImsgMessage;
 
 type Reaction = 'love' | 'like' | 'dislike' | 'laugh' | 'emphasis' | 'question';
 
@@ -160,6 +189,20 @@ interface GroupChatResolutionRequest {
   expectedParticipantExternalIds: readonly string[];
   excludedParticipantExternalIds?: readonly string[];
 }
+
+// renameGroup / addParticipant / removeParticipant. A success is proven (read
+// back from a fresh chats.list) and carries neither field. Every failure
+// carries both, and `effectStarted` follows from `reason` alone.
+interface GroupMutationResult {
+  ok: boolean;
+  effectStarted?: boolean;
+  reason?:
+    | 'unsupported'         // capability marker absent       — effectStarted:false
+    | 'refused'             // proven rejection before IMChat — effectStarted:false
+    | 'fire-failed'         // the call errored, may have applied — effectStarted:true
+    | 'unverified'          // fired, never confirmed in the window — effectStarted:true
+    | 'verify-read-failed'; // fired, the verification read broke  — effectStarted:true
+}
 ```
 
 ### Tier 2 (bridge-backed)
@@ -403,7 +446,63 @@ prevent.
   The long-lived RPC process keeps a stale chat-metadata view after its own
   mutation on macOS 26, while a fresh `imsg chats` process sees the update.
   Verification therefore polls fresh, read-only CLI processes (using the
-  same `IMSG_BIN`) for up to 20 seconds before returning `ok:false`.
+  same `IMSG_BIN`) — `GROUP_MUTATION_VERIFY_ATTEMPTS` (20) × 1 s, so a
+  **20-second** window — before giving up.
+
+  **A failure says which failure it is** (`GroupMutationResult`, M2B-40).
+  These three verbs used to answer a bare `ok:false` whether nothing had
+  fired or the mutation had gone out unconfirmed, which left a consumer no
+  choice but to settle every failure as possibly-applied — un-retirable
+  reconciliation work by construction. The classification, in the order the
+  gateway reaches it:
+
+  - **`unsupported`** (`effectStarted:false`) — `addParticipant`/
+    `removeParticipant` without the `groupParticipants` marker. Nothing was
+    called and no request on this host build ever could be.
+  - **`refused`** (`effectStarted:false`) — a proven rejection before IMChat
+    was invoked. Either the gateway's own preflight (target is a DM; the
+    removal would break the member floor below) or the helper's: a `-32602`,
+    or a `-32603` whose `error.data` carries one of that verb's known
+    pre-invoke refusals (`Chat not found`, `Could not vend handle`,
+    `Participant not found on chat`, `_setDisplayName: not available`, the
+    missing-selector and missing-parameter texts). The lists are per verb, in
+    `gateway/group-mutation.ts`, and are matched the same way the
+    chat-background pair matches its own.
+  - **`fire-failed`** (`effectStarted:true`) — the mutation call errored but
+    the error does NOT prove the helper stopped short: a bridge timeout, an
+    exception raised after IMChat was invoked, a dead rpc child, any
+    unmodelled `-32603`. It may already have applied.
+  - **`unverified`** (`effectStarted:true`) — it fired cleanly and the 20 s
+    window closed with `chats.list` never showing the wanted state.
+  - **`verify-read-failed`** (`effectStarted:true`) — it fired cleanly and
+    then the verification read itself failed, so there is no evidence either
+    way. One failed read ends the wait (it always has): `imsg chats` is a
+    local chat.db read, so a failure means a broken host, not a blip. Kept
+    distinct from `unverified` because the remediation is an operator's, not
+    a retry.
+
+  A success stays the bare `{ok:true}` it has always been: it was read back
+  from chat.db, so neither field would add anything.
+
+  **Apple's three-member floor.** A group conversation stays at three or more
+  members, the local user included; Apple silently declines a removal that
+  would drop it below that — `removeParticipants:reason:` returns normally and
+  the membership does not change. There is no error to classify, so
+  `removeParticipant` counts first: one fresh `chats.list` read before firing,
+  and a group whose `participants[]` (which excludes the local user, so the
+  group has `participants.length + 1` members) is shorter than
+  `GROUP_MIN_MEMBERS` is `refused` outright instead of costing the full 20 s
+  and then reporting ambiguity. The same read refuses a DM target for all
+  three verbs, which the bridge likewise answers by doing nothing.
+
+  Both preflight rules are **best-effort and fail open**: only what that read
+  actually reported is acted on. A chat outside `CHAT_SCAN_LIMIT`, a read that
+  failed, a row without the field, or a membership list that no longer
+  contains the target handle all fall through to fire-and-verify. An unknown
+  target must never become a confident refusal — the same discipline
+  `participant_directory_unavailable` applies in `resolveGroupChat`. Trusting
+  the count only when the target is still listed is what keeps a stale
+  chat.db view from refusing a removal that would have worked.
 - **`setGroupPhoto`/`leaveGroup`** — `group.setIcon` / `group.leave`. No field
   in imsg's JSON output reflects a group photo, and `participants[]` always
   excludes the local user (see "Participants exclude the local user" above),
@@ -527,6 +626,73 @@ both implementations — none of Apple's group primitives apply to a 1:1 chat.
   (`scripts/tier2-chat-background-leg.ts`) stops at the first failed check
   and never clears a background whose guid it did not read back.
 
+- **Location** — `readSharedLocations` / `watchLocations` /
+  `sendLocationRequest` (M2B-31; the shared wire contract lives with the
+  Mac and relay tracks, `location-wire.md`). Find My shares are
+  account-scoped state on the host Mac — the handles in
+  `findMyHandlesSharingLocationWithMe` and each handle's latest
+  `FMLLocation` — not message rows: no `subscribe()` event, no history row
+  on either implementation. Two separate helper markers gate the surface,
+  read from `imsg status --json` like every other patched verb:
+  `sharedLocations` (the read path) and `locationRequest` (the request
+  card, which reuses polls' extension-balloon initializer); neither implies
+  the other.
+  `readSharedLocations(chatGuid?)` is the native `locations.read`
+  (`{chat_guid?}` → `{locations, read_at}`): every sharing handle, or only
+  the one whose DM chat is `chatGuid`. The helper turns tracking on for a
+  handle's DM chat once per process and reads the current fix; a handle
+  that shares but has no fix yet comes back `isValid:false` with **no
+  coordinates** — never a zero fix. The mapping (`src/gateway/locations.ts`)
+  is total over malformed rows and drops what it cannot vouch for (no
+  handle; a "valid" row missing a coordinate). **It throws** — on both
+  implementations — when the bridge does not advertise `sharedLocations`
+  and on any rpc failure: an empty list is a positive claim ("nobody is
+  sharing") that a bridge which could not read must not make.
+  `sendLocationRequest(chatId)` is `location_request.send` (`{chat_id}`;
+  the handler resolves `chat_id`/`chat_guid`/`chat_identifier` alike, so the
+  Gateway keeps its numeric local id like every other verb): Apple's native
+  "Request Location" card, the one Messages sends from + › Location ›
+  Request, built by the helper with a fresh payload id. Targets an
+  **existing** chat only. **Fire-and-forget like `sendPoll`**: `ok:true`
+  means the helper dispatched the card; `guid` is the balloon row when
+  Messages exposed it synchronously and is absent otherwise (documented on
+  the native side). The recipient's answer, if any, arrives as a location
+  share — a `location` update below, or a decoded Find My share card on a
+  message row (imsg `docs/json.md` "Location card"), which this Gateway
+  does not model yet. FakeGateway emits the bare outbound row (like
+  `sendSticker`; `ImsgMessage` models nothing of the card) and returns only
+  the guid.
+  `watchLocations()` streams one `LocationUpdate` per change the native
+  watch reports — the `location` notification the watch stream emits
+  alongside `message`: a new fix (`location_update`), a handle starting
+  (`share_started`) or stopping (`share_ended`, which may carry no
+  coordinates) to share; on the native side this is a 30 s poll of
+  `locations.read` inside the watch session. `ImsgGateway` therefore holds
+  a **dedicated, non-rotated, cursorless** native watch session for it
+  (`src/imsg/location-watch.ts`, opened on the first `watchLocations()`
+  call): the message watch retires its process every 10 s once it has a
+  cursor, which would starve that poll. Its `message` notifications are
+  ignored. That poll runs in *every* subscription unless the subscriber
+  turns it off, so the message watch subscribes with `location_interval_s:
+  0` and this session is the only one that leaves the interval unset — one
+  Find My reader per connector, not one per watch session.
+  Location updates carry no rowid, so there is no catch-up: a
+  restarted session (child death) resumes nothing and a consumer takes the
+  baseline from `readSharedLocations()`, then applies updates. Malformed
+  notifications are dropped and reported as
+  `imsg_watch_location_malformed`, never forwarded. Single consumer, like
+  `subscribe()`, with the same documented divergence (FakeGateway allows
+  sequential re-watch). `GatewayEvent` is unchanged: see the note on it in
+  §1. FakeGateway's `injectSharedLocation(update)` is the fixture driver —
+  it goes through the real wire mapper, updates the in-memory share list
+  (`share_ended` removes the handle) and feeds `watchLocations()`.
+  **Host-verified 2026-09-13** (ledger below): `scripts/tier2-smoke.ts
+  <chatId> --only-location` (read leg, sends nothing) and
+  `--location-request` (posts the card; opt-in, the recipient sees it) are
+  the gate. Still open on the native side, to be confirmed in the relay
+  e2e: whether a fresh watch session emits the current snapshot
+  immediately or only diffs after its first poll.
+
 **Host-verification ledger.** Exercised through `ImsgGateway` on the host Mac
 2026-07-14 (`scripts/tier2-smoke.ts`, chat 3996):
 
@@ -608,6 +774,29 @@ three phone-handle participants; `scripts/tier2-smoke.ts 12 --only-mention
   receiving device rendering "Edited" (the inbound echo carried the original
   text, which is the partner's copy, not evidence either way).
 
+Exercised 2026-09-13 on the host (SDK `d6fecca` against the deployed M2B-31
+helper, imsg `0071842` built on the host, `sharedLocations true` /
+`locationRequest true`; `scripts/tier2-smoke.ts 7 --only-location
+--location-request`, bench `~/imsg-sdk-location-e2e-d6fecca`):
+
+- **`readSharedLocations` / `sendLocationRequest`** — live-verified: both
+  capability rows; `readSharedLocations()` returned a list (0 handles: no
+  share was active during the run, so the fix shape was not exercised
+  through the SDK here); `sendLocationRequest(7)` returned
+  `{ok:true, guid:23DB6804-EAAC-476D-8CA5-7AE71642B960}` and the row read
+  back from `chat.db` as a Find My balloon
+  (`…:0000000000:com.apple.findmy.FindMyMessagesApp`); an unknown chat
+  (`999999999`) → `ok:false` (native `-32602`). 6/6 PASS, `ALL PASS`, exit
+  0; the audit recorded exactly one event, in chat 7 ("Requested your
+  location"). Recipient-side, same helper build on a second Mac (macOS
+  26.6.2, 2026-09-13): the card rendered with a Share button on an iPhone
+  for a sender NOT in contacts, a 1 h share came back as a valid fix from
+  `imsg locations --json`, and `imsg watch --json --location-interval 30`
+  emitted `share_started` / `location_update` / `share_ended` — native
+  layer only; `ImsgGateway.watchLocations()` end to end is the relay e2e.
+  Not covered: group chats, email-handle shares, share expiry vs. Apple's
+  handle drop.
+
 Eyeballed 2026-09-04 on the same host (SDK `5826316` = v0.3.0, deployed
 `imsg` 0.13.0 helper, all four 0.3.0 capability flags true) with a human
 watching the receiving iPhone (iOS 26.6.1) between steps, one gateway call
@@ -660,6 +849,22 @@ the phone, created that day) and group chat 12 (three phone handles):
   backgrounds) THEN failure`). That is per-endpoint pruning, not a failure
   of the send, and the phone's endpoints are unaffected.
 
+**NOT YET HOST-VERIFIED — `GroupMutationResult` (M2B-40).** The reason
+vocabulary, the three-member floor and the DM preflight are derived from the
+native sources (`IMsgInjected.m` `handleAddParticipant` /
+`handleRemoveParticipant` / `handleSetDisplayName`,
+`RPCServer+ChatHandlers.swift` `invokeBridge`) and are covered by unit tests,
+which under hard rule 1 is **not** proof: `imsg` exit codes lie and Messages.app
+cannot be faked. Before this ships, `scripts/tier2-smoke.ts --group-chat-id
+<group> --participant <handle>` has to run on the host and answer three
+questions: (1) does a removal at the floor actually get refused by Apple, or
+does it land — the whole preflight is wrong if it lands; (2) is the floor three
+members counting the local user, i.e. does a 4-member group allow exactly one
+removal; (3) do the add/remove/rename round trips still return the bare
+`{ok:true}` they did before the preflight read was added. The smoke's group leg
+prints the measured membership and asserts the floor refusal, so a single run
+settles all three.
+
 - **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
@@ -916,6 +1121,28 @@ a different product.
     There is no "create empty group". Adding/removing a member on an *existing* group is possible —
     see "Tier 2" above (`addParticipant`/`removeParticipant`, bridge-backed) — but only through
     those methods, not through `createGroup`.
+  - **A group never shrinks below three members.** Apple keeps a group
+    conversation at `GROUP_MIN_MEMBERS` (3) or more, counting the local user,
+    and silently declines any removal that would break that — no error, no
+    change. So `removeParticipant` on a group whose `participants[]` (local
+    user excluded, see "Participants exclude the local user") is shorter than
+    three is `{ok:false, effectStarted:false, reason:'refused'}` and nothing
+    is fired. FakeGateway models the floor too: a fake that happily shrinks a
+    group to two exceeds what the real gateway can do, and fixtures built on
+    it would rehearse a removal iMessage refuses.
+  - **A group mutation that failed says where it failed.** `renameGroup`,
+    `addParticipant` and `removeParticipant` return `GroupMutationResult`
+    (§1): a failure always carries `reason` and the `effectStarted` that
+    follows from it, so a proven no-op is settled as a clean failure and only
+    a mutation that actually reached IMChat is reconciled. The reason
+    vocabulary and the per-verb proven-rejection lists are under "Tier 2"
+    above. FakeGateway reaches only the proven-no-op half (`unsupported`,
+    `refused`) — it has no bridge to time out on and must never manufacture
+    an `effectStarted:true` that would send a consumer off to reconcile a
+    mutation that never existed. Removing a handle the chat does not list is
+    one of those refusals on both sides: the helper matches against the live
+    IMChat participant list and answers `Participant not found on chat`,
+    so the fake must not model it as a silent success either.
   - **Compose guard**: if Cmd+N fails to enter compose (sibling of the react Cmd+T failure,
     observed live 2026-07-17), every scripted keystroke would land in the focused chat's
     compose field and each Return would send it — recipient handles texted into an open
@@ -1099,10 +1326,20 @@ harness (`tsx --test`, see `package.json`). Required cases:
 - `setTyping`/`markRead` dispatch `{ ok: true }` against an existing chat and `{ ok: false }`
   against an unknown one, with no queryable state either way
 - `renameGroup`/`addParticipant`/`removeParticipant` are reflected in a message sent
-  afterward (`chat_name`/`participants`) and return `ok: false` against a DM
+  afterward (`chat_name`/`participants`); a DM target is the proven
+  `{ok:false, effectStarted:false, reason:'refused'}`, and so is a removal that
+  would break Apple's three-member floor or that names a handle the chat does
+  not list — in both cases the membership is untouched afterward
 - `setGroupPhoto`/`leaveGroup` return `ok: true` against a group and `ok: false` against a DM
 - patched sticker, group-photo, participant, and chat-background verbs return `ok:false`
-  without mutation when their `imsg status` capability markers are absent
+  without mutation when their `imsg status` capability markers are absent; the
+  participant verbs name it `reason:'unsupported'`, distinct from a request the
+  host declined
+- (real-path only, `tests/group-mutation.test.ts` over the pure module) a bridge
+  rejection raised before IMChat is `refused`; a timeout, an unmodelled `-32603`
+  or a non-rpc error is `fire-failed`; an exhausted verify window is
+  `unverified`; a failed verification read is `verify-read-failed` — one verb's
+  proven-rejection text does not excuse another's
 - 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
@@ -1111,9 +1348,18 @@ harness (`tsx --test`, see `package.json`). Required cases:
   unknown chat never starts an effect
 - `recentReactions` surfaces an inbound custom-emoji reaction (`reaction: 'custom'`) with the
   real `emoji` intact
+- `readSharedLocations` lists every sharing handle, narrows by chat guid, replaces (never
+  accumulates) a handle's row on a newer fix, and keeps a no-fix handle coordinate-free;
+  it throws without the `sharedLocations` marker
+- `watchLocations` streams `share_started` → `location_update` → `share_ended` in order,
+  `share_ended` drops the handle from the read, and a second concurrent consumer is refused
+- `sendLocationRequest` posts the card as its own outbound row to an existing chat, returns
+  the balloon guid, refuses an unknown chat (no find-or-create), and fails closed without
+  the `locationRequest` marker (no row written)
 - Fake-only restart coverage snapshots and restores a world, then proves
   `sendStatus`, `checkHandle`, Name & Photo idempotency, chat backgrounds (and their
-  guid sequence), current group metadata, fixture state, and monotonic IDs survive exactly
+  guid sequence), Find My shares, current group metadata, fixture state, and monotonic IDs
+  survive exactly; a snapshot carrying a share the wire mapper would refuse does not restore
 
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapier/imsg-sdk",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "TypeScript SDK for iMessage automation on macOS: the Gateway contract, ImsgGateway (real), and a device-free FakeGateway.",
   "license": "MIT",
   "repository": {