@mapier/imsg-sdk 0.6.0 → 0.7.0

package/docs/gateway-contract.md

@@ -66,6 +66,7 @@ interface Gateway {
     locationRequest: boolean;
     extensionCardSend: boolean;
     extensionCardUpdate: boolean;
+    multipartSend: boolean;
   };
   subscribe(sinceId?: number): AsyncIterable<GatewayEvent>;
   history(chatId: number, limit?: number): Promise<ImsgMessage[]>;
@@ -117,6 +118,11 @@ interface Gateway {
     card: ExtensionCard,
     opts?: { update?: ExtensionCardHandle },
   ): Promise<ExtensionCardResult>;
+  sendMultipart(
+    chatId: number,
+    parts: readonly MultipartPart[],
+    opts?: { replyToGuid?: string; effect?: string; subject?: string },
+  ): Promise<MultipartResult>;
   editMessage(chatId: number, targetGuid: string, text: string): Promise<{
     ok: boolean;
     skipped?: 'unchanged';
@@ -266,6 +272,22 @@ interface ExtensionCardResult {
   effectStarted?: boolean;
   reason?: GroupMutationFailure; // only unsupported / refused / fire-failed are reachable
 }
+
+// sendMultipart (M2B-55). One message made of several parts, in the order
+// given — that order is each part's NUMBER, the same number tapback's
+// `partIndex` names. Audio is not a part: the voice flag is message-wide, so a
+// voice note still goes alone through sendAttachment.
+type MultipartPart =
+  | { kind: 'text'; text: string; textFormatting?: TextFormatRange[] }  // the same ranges sendRich takes
+  | { kind: 'file'; filePath: string };                                 // a path on the HOST Mac
+
+interface MultipartResult {
+  ok: boolean;
+  guid?: string;                 // absent when Messages had not exposed the row yet; never synthesized
+  partCount?: number;            // the host's own count of the parts it built
+  effectStarted?: boolean;
+  reason?: GroupMutationFailure; // only unsupported / refused / fire-failed are reachable
+}
 ```
 
 ### Tier 2 (bridge-backed)
@@ -305,6 +327,11 @@ Part-level tapbacks require `tapbackPart`, which the helper computes from the
 part's own chat item plus an associated-message initializer taking a range —
 and which no other tapback marker may stand in for, because a helper without it
 does not reject `part_index`, it writes a corrupt row (M2B-45, above).
+Multipart sends require `multipartSend`, composed by the helper from the
+file-transfer centre plus the attachment IMMessage initializer, and equally
+un-substitutable: a helper predating file parts reads only each part's `text`,
+so it DROPS every file part without a word and answers ok with a short
+`parts_count` (M2B-55, below).
 Missing status, malformed JSON, or absent markers fail closed.
 `FakeGateway.capabilities` mirrors this gate and can disable the same surface
 for parity tests. A remote adapter (e.g. imsg-agent's connector) must gate on
@@ -592,6 +619,67 @@ prevent.
   builder's returns above the IMChat call; `send-extension-card failed:` is
   deliberately **not** among them, because that `@try` wraps the whole
   build-and-send block. FakeGateway reaches only the proven half.
+- **`sendMultipart(chatId, parts, opts?)`** — `send.multipart`
+  (`RPCServer+MultipartHandler.swift` → `handleSendMultipart` in
+  `IMsgInjected.m`). Several parts as **one message**, targeting an **existing**
+  chat only. Gated on `multipartSend`, and the gate covers the whole verb
+  including a text-only list: the marker guards a silent LOSS rather than a
+  rejection (a helper predating file parts drops them and answers ok), so a
+  caller must never be left to discover mid-list that this host eats photos.
+
+  **What "one message" means on a phone** — proven on a real iPhone from the
+  lab Mac (macOS 26.6.2) on 2026-09-21, through the native CLI:
+  one notification and one `chat.db` row, **not** one bubble. Each part draws as
+  its own bubble, in the order given, and consecutive photos are gathered by the
+  receiving phone into a stack (five photos arrived as one stack labelled
+  "5 photos"). Two text parts in a row are fine — two bubbles — so, unlike
+  Linq, this verb allows them. A text part with a **trailing newline draws an
+  empty last line** in its bubble, so callers must not add one (the
+  single-attachment path's caption does, which is a native wart, not a model to
+  copy). **Part number = index in `parts`**, and that is exactly the
+  `partIndex` a later `tapback` names. Audio is not a part: the voice flag is
+  message-wide, so a voice note still goes alone through `sendAttachment`.
+
+  **`effect`, `subject` and `replyToGuid` are message-wide**, read by the
+  native handler exactly as `send.rich` reads them — IMCore has one of each per
+  message, never one per part. Per-part `textFormatting` is the `sendRich`
+  range vocabulary scoped to that part, offsets counted in that part's own
+  text; a mention still needs `mentionFormatting` and is `unsupported` without
+  it. Formatting on a **file** part is refused rather than dropped.
+
+  **Validation happens before the RPC**, mirroring the native pass that runs
+  before a single transfer is staged: a non-empty array, every entry an object
+  of a known `kind`, non-empty `text`, non-empty `filePath` carrying no newline
+  or NUL, per-part formatting through the same `textFormattingRefusal` sendRich
+  uses, and the Mac-side caps **100 parts / 40 file parts**
+  — plus one rule that exists only because of how this verb fails: a part
+  carrying **both** a `text` and a `filePath` is refused *before* its `kind` is
+  consulted, never resolved by the label. Whichever branch the label chose would
+  drop the other key without a word, and losing part content in silence is the
+  failure the whole verb exists to remove; it must not come back in through a
+  caller that names a part wrong. The native handler refuses it by index for the
+  same reason (an empty string counts as absent on both keys, on both sides)
+  (`MULTIPART_MAX_PARTS` / `MULTIPART_MAX_FILE_PARTS`, mirroring
+  `MultipartLimits` and `kMaxMultipartParts`). Each is a proven no-op
+  (`effectStarted:false`, `reason:'refused'`). Two native checks are
+  deliberately **not** mirrored: the 100 MiB total-byte cap and whether each
+  file exists. This SDK never touches the filesystem — the path belongs to the
+  Mac — so a local check would make the fake and the real path disagree in both
+  directions; a missing file is the helper's refusal, classified through
+  `MULTIPART_PROVEN_REJECTIONS`.
+
+  **No verification pass exists**, for the reason `sendAttachment` has none:
+  the synchronous response carries the message's guid, which is the proof to
+  read `sendStatus()` on, while the row Messages writes at dispatch says
+  nothing about the upload that follows (`is_sent` stays 0 until the bytes are
+  out). So only `unsupported` / `refused` / `fire-failed` are reachable.
+  `send-multipart failed:` is deliberately **not** a proven rejection: that
+  `@try` wraps the whole build-and-dispatch block. `partCount` is the **host's**
+  count of the parts it built and is never replaced with the caller's list
+  length — a count shorter than the list is precisely how a helper that dropped
+  file parts would show up. There is deliberately no numeric `id`: the native
+  result sets `message_id` to the message GUID, so no rowid exists on the real
+  path and FakeGateway must not hand back one either.
 - **`editMessage(chatId, targetGuid, text)`** — `message.edit`
   (`handleMessageEdit`; imsg `docs/edit.md`). Capability-gated on the
   `editMessage` marker (see above): on macOS 27 the helper calls the
@@ -1209,6 +1297,49 @@ both markers read `true` on the current build — a host with `extensionCardSend
 and not `extensionCardUpdate` is possible by construction but has never been
 seen. There is no smoke leg for this verb yet; the host proof is driven by hand.
 
+**HOST-VERIFIED 2026-09-21 (lab Mac, macOS 26.6.2) — `sendMultipart` (M2B-55),
+through this SDK verb.** The native layer was already proven on a real iPhone
+the same day through the native CLI (Mapier-Labs/imsg#28): ten shapes — caption
++ photo, photo + caption, caption + 3 photos, alternating text and photos, two
+text parts, five photos, a 93 MiB ten-photo message — each arriving as a single
+notification with the parts in the order given and the photos stacked, which is
+where the "no trailing newline" and "consecutive text parts are fine" rules come
+from, and where the phone RENDERING of these shapes is settled. This run drove
+the gateway verb itself: the packed tarball of SDK `43b6454` installed into a
+scratch dir, `IMSG_BIN` pointed at the native build of imsg#28 head `f2a8bc6`
+(helper sha256 `3229d9dd…`). The phone rendering was not re-judged per SDK
+send — these legs prove the SDK's half, and `chat.db` is the oracle for it:
+
+- `capabilities.multipartSend` and `capabilities.mentionFormatting` both read
+  `true` off that build.
+- `[text, file, file, text]` → `{ok:true, guid, partCount:4}`, and that guid is
+  **ONE** `chat.db` row with `part_count` 4, **two attachment joins**,
+  `is_sent` 1, `is_delivered` 1, `error` 0. That pair is the load-bearing
+  observation of the whole verb: a `partCount` of 4 arriving with both photos
+  actually joined is the direct evidence that the file parts were not silently
+  dropped — the failure the `multipartSend` marker exists to prevent, until now
+  reasoned from the helper's source rather than seen.
+- `[text with a bold range, file]` with `effect` and `subject` →
+  `{ok:true, guid, partCount:2}`; ONE row, `part_count` 2, one attachment,
+  the subject set, and `expressive_send_style_id`
+  `com.apple.messages.effect.CKConfettiEffect`, sent and delivered, `error` 0.
+  So the per-part `text_formatting` and the message-wide `effect` / `subject`
+  survive this SDK's wire shape into the fields the native handler's
+  `send.rich` parsers write.
+- An empty list, a 41-file list, and `textFormatting` on a file part each
+  answered `{ok:false, effectStarted:false, reason:'refused'}` — and the run
+  wrote **exactly two rows in total**, so all three refusals fired nothing.
+  That row count is the only way to prove `effectStarted:false`, which is a
+  claim about what did NOT happen.
+
+**Still NOT host-verified for M2B-55:** a confirmed mention inside a multipart
+text part (it needs a group thread, and the marker reading `true` is not the
+same as a mention landing); `replyToGuid` as an inline-reply target; and every
+string in `MULTIPART_PROVEN_REJECTIONS` — no send failed on the host, so the
+fire-failure classifier stays read-from-source and unit-tested only, unlike
+M2B-45's `'has no part '`, which its run happened to provoke. There is still no
+smoke leg for this verb; the host proof is driven by hand.
+
 - **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
@@ -1576,6 +1707,22 @@ a different product.
   implementations also refuse to invent a guid: when Messages exposes none, the
   success carries `updatable:false` and no handle rather than a synthesized one.
 
+- **A multipart send is ONE row, and the fake may under-count its parts —
+  never over-count** (M2B-55). `sendMultipart` emits a single outbound row on
+  both implementations, whatever the part list holds: one notification, one
+  `chat.db` row, several bubbles. What the fake does not do is synthesize that
+  row's inner shape. The real row's `text` is Apple's own concatenation of the
+  parts with object-replacement placeholders where the files sit, and its
+  `attachments[]` only appears on a later history/watch row — the send response
+  reports neither, and inventing them is exactly what `sendAttachment` already
+  refuses to do. The consequence is deliberate: `FakeGateway.partCount()` still
+  counts attachments, so a fake-sent multipart row reports 1 part however many
+  it really had, and a part-level tapback on it is refused where a host would
+  accept it. That is the allowed direction (the fake must not succeed at what
+  the real path refuses), and counting `(text ? 1 : 0) + attachments.length`
+  instead is a contract change that needs the host run to prove the real part
+  layout first.
+
 - **Inbound media.** Real messages can carry `attachments[]` with empty `text`. FakeGateway must
   be able to emit the exact attachment metadata with `text: undefined`/empty so
   this path gets exercised — the agent currently ignores attachments gracefully
@@ -1737,6 +1884,12 @@ harness (`tsx --test`, see `package.json`). Required cases:
   `extensionCardSend` but not `extensionCardUpdate` sends but refuses the update. One case
   asserts a NEGATIVE: an update aimed at a previous update's guid is **not** caught — the
   fake must not be safer than the Mac, which cannot detect it either
+- `sendMultipart` lands text and file parts as ONE outbound row (not one per part), reports
+  the host's `partCount` and a guid, and preserves an inline-reply guid alongside the
+  message-wide effect and subject; an empty list, an empty text part, formatting on a file
+  part, 41 file parts and an unknown chat are each `refused` with no row written, and a
+  missing `multipartSend` marker is `unsupported` — including for a text-only list, which
+  such a host could actually have sent
 - Fake-only restart coverage snapshots and restores a world, then proves
   `sendStatus`, `checkHandle`, Name & Photo idempotency, chat backgrounds (and their
   guid sequence), Find My shares, current group metadata, fixture state, and monotonic IDs

package/package.json

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