@spectrum-ts/imessage 12.4.0 → 12.5.0

package/dist/index.js

@@ -1,7 +1,7 @@
 import { ErrorCode, NotFoundError, ValidationError, createGrpcClient } from "@photon-ai/advanced-imessage/grpc";
 import { sanitizePhone, withSpan } from "@photon-ai/otel";
 import { UnsupportedError, appLayoutSchema, cloud, definePlatform, fromVCard, mergeStreams, read, text, toVCard } from "@spectrum-ts/core";
-import { addMemberSchema, asAttachment, asContact, asCustom, asGroup, asPoll, asPollOption, asReply, asText, asVoice, avatarSchema, buildPhotoAction, createLogger, createTokenRenewal, ensureM4a, errorAttrs, groupSchema, leaveSpaceSchema, messageEffectSchema, photoActionSchema, reactionSchema, removeMemberSchema, renameSchema, resumableOrderedStream, sanitizeErrorMessage } from "@spectrum-ts/core/authoring";
+import { addMemberSchema, asAttachment, asContact, asCustom, asGroup, asPoll, asPollOption, asReply, asText, asVoice, avatarSchema, buildPhotoAction, createLogger, createTokenRenewal, ensureM4a, errorAttrs, groupSchema, leaveSpaceSchema, messageEffectSchema, photoActionSchema, reactionSchema, readSchema, removeMemberSchema, renameSchema, resumableOrderedStream, sanitizeErrorMessage } from "@spectrum-ts/core/authoring";
 import z from "zod";
 import { Marked } from "marked";
 import { LRUCache } from "lru-cache";
@@ -409,6 +409,12 @@ const IMESSAGE_PLATFORM = "imessage";
 const PART_PREFIX = /^p:(\d+)\//;
 const dmChatGuid = (address) => `any;-;${address}`;
 const chatTypeFromGuid = (guid) => guid.includes(";+;") ? "group" : "dm";
+const dmPeerFromChatGuid = (guid) => {
+	if (chatTypeFromGuid(guid) !== "dm") return;
+	const separator = guid.indexOf(";-;");
+	if (separator < 0) return;
+	return guid.slice(separator + 3) || void 0;
+};
 const toChatGuid = (value) => value;
 const toMessageGuid = (value) => value;
 const formatChildId = (partIndex, parentGuid) => `p:${partIndex}/${parentGuid}`;
@@ -671,7 +677,7 @@ const getRemoteAttachment = async (client, guid) => {
 };
 //#endregion
 //#region src/remote/inbound.ts
-const log$4 = createLogger("spectrum.imessage.inbound");
+const log$5 = createLogger("spectrum.imessage.inbound");
 const messageAttachments = (message) => message.content.attachments;
 const resolveChatGuid = (message, hint) => {
 	if (hint) return hint;
@@ -735,7 +741,7 @@ const toVCardContent = async (client, info) => {
 	try {
 		return asContact(fromVCard((await downloadPrimaryAttachment(client, info.guid)).toString("utf8")));
 	} catch (err) {
-		log$4.warn("failed to parse vCard attachment; falling back to attachment content", {
+		log$5.warn("failed to parse vCard attachment; falling back to attachment content", {
 			"spectrum.imessage.attachment.guid": info.guid,
 			...errorAttrs(err)
 		}, err);
@@ -823,7 +829,7 @@ const resolveReplyTarget = async (client, base, targetGuid, currentGuid, options
 		if (options.cache) cacheMessage(options.cache, rebuilt);
 		return rebuilt;
 	} catch (err) {
-		if (!(err instanceof NotFoundError)) log$4.warn("failed to resolve iMessage reply target; falling back to stub target", {
+		if (!(err instanceof NotFoundError)) log$5.warn("failed to resolve iMessage reply target; falling back to stub target", {
 			"spectrum.imessage.message.guid": currentGuid,
 			"spectrum.imessage.reply.target_guid": targetGuid,
 			...errorAttrs(err)
@@ -860,6 +866,36 @@ const cacheMessage = (cache, message) => {
 		for (const item of group.items) if (isIMessageMessage(item)) cache.set(item.id, item);
 	}
 };
+/**
+* Resolve a guid to the spectrum message it maps to, for events that reference
+* their target only by guid (reactions, read receipts). Cache first — outbound
+* sends are cached at send time by `cacheRemoteOutbound`, inbound messages when
+* they are converted — then one `messages.get` + rebuild, which also warms the
+* cache so sibling events for the same guid (a group's other participants) are
+* free.
+*
+* Any failure drops the event: these are secondary signals and must never wedge
+* the stream. Deliberately unlike `getMessage` below (the public
+* `space.getMessage` action), which rethrows non-`NotFoundError` failures; and
+* unlike it this never resolves `p:N/guid` child ids, because event payloads
+* always carry the parent guid.
+*/
+const resolveTargetMessage = async (client, cache, chatGuid, targetGuid, phone) => {
+	const cached = cache.get(targetGuid);
+	if (cached) return cached;
+	try {
+		const rebuilt = await rebuildFromAppleMessage(client, await client.messages.get(toMessageGuid(targetGuid)), phone, chatGuid);
+		cacheMessage(cache, rebuilt);
+		return rebuilt;
+	} catch (error) {
+		log$5.debug("event target could not be resolved; dropping the event", {
+			"spectrum.imessage.target_guid": targetGuid,
+			"spectrum.imessage.chat_guid": chatGuid,
+			...errorAttrs(error)
+		}, error instanceof Error ? error : void 0);
+		return;
+	}
+};
 const toInboundMessages = async (client, cache, event, phone) => {
 	const base = buildMessageBase(event.message, event.chatGuid, event.occurredAt, phone);
 	const messageGuidStr = event.message.guid;
@@ -955,13 +991,8 @@ const asProviderReaction = (emoji, target) => reactionSchema.parse({
 	type: "reaction"
 });
 const resolveReactionTarget = async (client, cache, chat, targetGuid, partIndex, phone) => {
-	let candidate = cache.get(targetGuid);
-	if (!candidate) try {
-		candidate = await rebuildFromAppleMessage(client, await client.messages.get(toMessageGuid(targetGuid)), phone, chat);
-		cacheMessage(cache, candidate);
-	} catch {
-		return;
-	}
+	const candidate = await resolveTargetMessage(client, cache, chat, targetGuid, phone);
+	if (!candidate) return;
 	if (candidate.content.type === "group") {
 		const items = candidate.content.items;
 		if (!Array.isArray(items)) return candidate;
@@ -1503,7 +1534,7 @@ const randomPhone = (clients) => {
 };
 //#endregion
 //#region src/remote/contact-share.ts
-const log$3 = createLogger("spectrum.imessage.contact");
+const log$4 = createLogger("spectrum.imessage.contact");
 const SHARE_TTL_MS = 1440 * 60 * 1e3;
 const MAX_TRACKED_CHATS = 1e4;
 const isPreconditionFailure = (error) => typeof error === "object" && error !== null && "code" in error && error.code === ErrorCode.preconditionFailed;
@@ -1551,10 +1582,10 @@ var ContactShareTracker = class {
 		this.cache.set(chatGuid, true);
 		const safeChatGuid = sanitizeErrorMessage(chatGuid);
 		this.client.chats.shareContactInfo(chatGuid).then(() => {
-			log$3.info("shared contact card", { "spectrum.imessage.contact.chat": safeChatGuid });
+			log$4.info("shared contact card", { "spectrum.imessage.contact.chat": safeChatGuid });
 		}).catch((error) => {
 			if (!isPreconditionFailure(error)) this.cache.delete(chatGuid);
-			log$3.warn("failed to share contact card", {
+			log$4.warn("failed to share contact card", {
 				"spectrum.imessage.contact.chat": safeChatGuid,
 				...errorAttrs(error)
 			}, error);
@@ -1580,7 +1611,7 @@ const getContactShareTracker = (client) => {
 };
 //#endregion
 //#region src/remote/group-events.ts
-const log$2 = createLogger("spectrum.imessage.group");
+const log$3 = createLogger("spectrum.imessage.group");
 /**
 * Synthetic id for a `group.changed` event — shared between the stream item
 * (the dedup key across live/catch-up) and the surfaced message. `sequence`
@@ -1610,7 +1641,7 @@ const fetchIconContent = async (client, event) => {
 			}
 		});
 	} catch (e) {
-		log$2.error("failed to fetch changed group icon", {
+		log$3.error("failed to fetch changed group icon", {
 			"spectrum.imessage.group.chat": event.chatGuid,
 			...errorAttrs(e)
 		}, e);
@@ -1665,7 +1696,7 @@ const toGroupEventMessages = async (client, event, phone) => {
 };
 //#endregion
 //#region src/remote/polls.ts
-const log$1 = createLogger("spectrum.imessage.poll");
+const log$2 = createLogger("spectrum.imessage.poll");
 const isVotedPollEvent = (event) => event.delta.type === "voted";
 const isUnvotedPollEvent = (event) => event.delta.type === "unvoted";
 const toCachedPoll = (input) => {
@@ -1697,7 +1728,7 @@ const cachePollEvent = (cache, event) => {
 		cache.set(event.pollMessageGuid, cached);
 		return cached;
 	} catch (e) {
-		log$1.error("failed to cache poll", {
+		log$2.error("failed to cache poll", {
 			"spectrum.imessage.poll.guid": event.pollMessageGuid,
 			...errorAttrs(e)
 		}, e);
@@ -1709,7 +1740,7 @@ const fetchPollInfo = async (client, cache, event) => {
 		cachePollInfo(cache, info);
 		return info;
 	} catch (e) {
-		log$1.error("failed to fetch poll", {
+		log$2.error("failed to fetch poll", {
 			"spectrum.imessage.poll.guid": event.pollMessageGuid,
 			...errorAttrs(e)
 		}, e);
@@ -1722,7 +1753,7 @@ const resolvePoll = async (client, cache, event) => {
 	try {
 		return cachePollInfo(cache, await client.polls.get(event.pollMessageGuid));
 	} catch (e) {
-		log$1.error("failed to resolve poll", {
+		log$2.error("failed to resolve poll", {
 			"spectrum.imessage.poll.guid": event.pollMessageGuid,
 			...errorAttrs(e)
 		}, e);
@@ -1782,10 +1813,140 @@ const toPollDeltaMessages = async (client, pollCache, event, phone) => {
 	return [];
 };
 //#endregion
+//#region src/remote/read-receipts.ts
+const log$1 = createLogger("spectrum.imessage.read");
+/**
+* Synthetic id for a `message.read` event — shared between the stream item
+* (the dedup key across live/catch-up) and the surfaced message. `sequence` is
+* monotonic per line, so N participants reading the same message produce N
+* distinct ids, and the same event replayed through catch-up produces the id
+* it produced live.
+*/
+const readReceiptMessageId = (event) => `${event.messageGuid}:read:${event.sequence}`;
+const asProviderRead = (target) => readSchema.parse({
+	target,
+	type: "read"
+});
+/**
+* Whether the reader could be identified at all, decided without resolving
+* the target. A DM always can (the peer is in the guid); a group only if the
+* platform named an actor. Lets an unattributable group receipt drop before
+* paying for an RPC.
+*/
+const isAttributable = (event) => dmPeerFromChatGuid(event.chatGuid) !== void 0 || event.actor?.address !== void 0;
+/**
+* Identify the reader.
+*
+* `event.actor` is **not** the reader on this arm. Verified against a live
+* line: in a DM where the peer read our message, `actor` came back as *our
+* own* line's address, not theirs.
+*
+* So the chat guid comes first. In a DM there are exactly two participants
+* and the target is already known to be ours, which makes the reader
+* definitionally the other one — no address comparison needed, and therefore
+* correct on pooled lines too, where `phone` is the `"shared"` sentinel and
+* comparing it against a real address is meaningless.
+*
+* A group guid carries no participant list, so there `actor` is the only
+* possible attribution. It is trusted only when it names neither this line
+* nor the target's own sender; the latter is what catches the shared-mode
+* case, since the sentinel never equals a real address. An unattributable
+* receipt is dropped rather than surfaced with a wrong reader — the reader's
+* identity is the entire payload.
+*/
+const toReader = (event, target, phone) => {
+	const peer = dmPeerFromChatGuid(event.chatGuid);
+	if (peer) return {
+		id: peer,
+		address: peer
+	};
+	const actor = event.actor;
+	if (actor?.address && actor.address !== phone && actor.address !== target.sender?.address) return toSenderRef(actor);
+};
+/**
+* Convert a `message.read` event into an inbound `read` message — someone read
+* a message the agent sent. `sender` is the reader; `content.target` is ours.
+*
+* Two guards, cheapest first:
+*
+* 1. **The reader must be identifiable -> else drop.** Unlike a membership
+*    change (where the state change itself is the payload and
+*    `sender: undefined` still carries meaning), the reader's identity *is*
+*    the payload of a receipt. An unattributed receipt in a group is
+*    indistinguishable noise and would corrupt any "N of M have read" tally.
+*    Same call as `toReactionMessages`. See `toReader`.
+*
+* 2. **The target must be one of ours.** `event.isFromMe` is not trustworthy
+*    here: the proto carries no comment for it on this arm, and it most
+*    plausibly describes the *underlying message* — which for a genuine
+*    receipt is ours, i.e. `true` — so keying self-suppression off it would
+*    suppress every receipt worth surfacing. The durable invariant is that a
+*    peer's receipt always points at a message we sent, so the resolved target
+*    must be `direction: "outbound"`. That one check also suppresses the echo
+*    of our own `chats.markRead()`, which marks *their* inbound messages and
+*    therefore resolves `direction: "inbound"`.
+*/
+const toReadReceiptMessages = async (client, cache, event, phone) => {
+	if (!isAttributable(event)) {
+		log$1.debug("read receipt dropped: reader could not be identified", {
+			"spectrum.imessage.read.message_guid": event.messageGuid,
+			"spectrum.imessage.read.sequence": event.sequence,
+			"spectrum.imessage.read.chat_guid": event.chatGuid,
+			"spectrum.imessage.read.has_actor": false
+		});
+		return [];
+	}
+	const target = await resolveTargetMessage(client, cache, event.chatGuid, event.messageGuid, phone);
+	if (!target) {
+		log$1.debug("read receipt dropped: target message could not be resolved", {
+			"spectrum.imessage.read.message_guid": event.messageGuid,
+			"spectrum.imessage.read.sequence": event.sequence
+		});
+		return [];
+	}
+	if (target.direction !== "outbound") {
+		log$1.debug("read receipt dropped: target is not one of ours", {
+			"spectrum.imessage.read.message_guid": event.messageGuid,
+			"spectrum.imessage.read.sequence": event.sequence,
+			"spectrum.imessage.read.target_direction": target.direction ?? "unset"
+		});
+		return [];
+	}
+	const reader = toReader(event, target, phone);
+	if (!reader) {
+		log$1.debug("read receipt dropped: reader could not be identified", {
+			"spectrum.imessage.read.message_guid": event.messageGuid,
+			"spectrum.imessage.read.sequence": event.sequence,
+			"spectrum.imessage.read.chat_guid": event.chatGuid,
+			"spectrum.imessage.read.has_actor": true
+		});
+		return [];
+	}
+	const readAt = event.readAt;
+	log$1.debug("read receipt surfaced", {
+		"spectrum.imessage.read.message_guid": event.messageGuid,
+		"spectrum.imessage.read.sequence": event.sequence,
+		"spectrum.imessage.read.reader": sanitizePhone(reader.id),
+		"spectrum.imessage.read.used_read_at": readAt !== void 0
+	});
+	return [{
+		id: readReceiptMessageId(event),
+		content: asProviderRead(target),
+		sender: reader,
+		space: {
+			id: event.chatGuid,
+			type: chatTypeFromGuid(event.chatGuid),
+			phone
+		},
+		timestamp: readAt ?? event.occurredAt
+	}];
+};
+//#endregion
 //#region src/remote/stream.ts
 const isCursorRejectedIMessageError = (error) => error instanceof ValidationError;
 const streamLabel = (kind, phone) => `imessage.${kind}:${phone === "shared" ? phone : sanitizePhone(phone)}`;
-const isEventFromCurrentAccount = (event, phone) => event.isFromMe || phone !== "shared" && event.actor?.address !== void 0 && event.actor.address === phone;
+const isActorCurrentAccount = (actor, phone) => phone !== "shared" && actor?.address !== void 0 && actor.address === phone;
+const isEventFromCurrentAccount = (event, phone) => event.isFromMe || isActorCurrentAccount(event.actor, phone);
 const streamLog = createLogger("spectrum.imessage.stream");
 const isRetryableMappingError = (error) => typeof error === "object" && error !== null && error.retryable === true;
 const skipUnmappable = async (label, cursor, map) => {
@@ -1834,6 +1995,26 @@ const toMessageItem = async (client, event, phone, cursor, onInbound) => {
 			values: await toReactionMessages(client, cache, event, phone)
 		};
 	}
+	if (event.type === "message.read") {
+		const id = readReceiptMessageId(event);
+		streamLog.debug("received a read event", {
+			"spectrum.imessage.read.message_guid": event.messageGuid,
+			"spectrum.imessage.read.sequence": event.sequence,
+			"spectrum.imessage.read.chat_guid": event.chatGuid,
+			"spectrum.imessage.read.actor": event.actor?.address ? sanitizePhone(event.actor.address) : "none",
+			"spectrum.imessage.read.is_from_me": event.isFromMe,
+			"spectrum.imessage.read.line": phone
+		});
+		return {
+			cursor,
+			id,
+			values: await toReadReceiptMessages(client, getMessageCache(client), event, phone)
+		};
+	}
+	streamLog.debug("message event consumed without mapping", {
+		"spectrum.imessage.event_type": event.type,
+		"spectrum.imessage.sequence": event.sequence
+	});
 	return {
 		cursor,
 		id: `${event.type}:${"messageGuid" in event ? event.messageGuid : "unknown"}:${event.sequence}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spectrum-ts/imessage",
-  "version": "12.4.0",
+  "version": "12.5.0",
   "description": "iMessage provider for spectrum-ts.",
   "repository": {
     "type": "git",