@spectrum-ts/imessage 12.4.0 → 12.6.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, createStreamGroup, 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";
@@ -179,6 +179,73 @@ function effect(input, messageEffect) {
 	} };
 }
 //#endregion
+//#region src/lines.ts
+const linesLog = createLogger("spectrum.imessage.lines");
+const observers = /* @__PURE__ */ new WeakMap();
+const lineIds = /* @__PURE__ */ new WeakMap();
+let fallbackKeys = 0;
+/** Pairs an entry with the cloud instance it was built from. */
+const setLineId = (entry, instanceId) => {
+	lineIds.set(entry, instanceId);
+};
+/**
+* Stable per-entry key. Falls back to a generated id for explicitly-configured
+* clients, which carry no instance id and may legitimately repeat a phone
+* number — phone alone would collide.
+*/
+const lineKey = (entry) => {
+	const existing = lineIds.get(entry);
+	if (existing) return existing;
+	fallbackKeys += 1;
+	const generated = `line-${fallbackKeys}`;
+	lineIds.set(entry, generated);
+	return generated;
+};
+/**
+* Registers `observer` and returns a disposer that removes just this one, so a
+* closed message stream stops being called into. `clearLineObservers` remains
+* the whole-array teardown used when the client itself is destroyed.
+*/
+const addLineObserver = (clients, observer) => {
+	const existing = observers.get(clients);
+	if (existing) existing.add(observer);
+	else observers.set(clients, new Set([observer]));
+	return () => {
+		const current = observers.get(clients);
+		if (!current?.delete(observer)) return;
+		if (current.size === 0) observers.delete(clients);
+	};
+};
+const clearLineObservers = (clients) => {
+	observers.delete(clients);
+};
+/**
+* Synchronous by contract: `reconcile` calls this immediately after pushing the
+* entry, with no await in between, so an observer can never see a half-applied
+* array. A throwing observer is contained — it must not be able to reject the
+* token refresh, which would stall renewal for every line.
+*/
+const notifyLineAttached = (clients, entry) => {
+	for (const observer of observers.get(clients) ?? []) try {
+		observer.attach(entry);
+	} catch (error) {
+		linesLog.warn("imessage line observer failed to attach", errorAttrs(error), error instanceof Error ? error : void 0);
+	}
+};
+/**
+* Returns each observer's detach promise so the caller can settle them off the
+* refresh path — a wedged stream close must not stall token renewal.
+*/
+const notifyLineDetached = (clients, entry) => {
+	const pending = [];
+	for (const observer of observers.get(clients) ?? []) try {
+		pending.push(Promise.resolve(observer.detach(entry)));
+	} catch (error) {
+		linesLog.warn("imessage line observer failed to detach", errorAttrs(error), error instanceof Error ? error : void 0);
+	}
+	return pending;
+};
+//#endregion
 //#region src/types.ts
 /**
 * Sentinel phone for shared-token mode. The single shared client serves an
@@ -232,18 +299,92 @@ const messageSchema = z.object({
 //#endregion
 //#region src/auth.ts
 const FORCE_REFRESH_MIN_INTERVAL_MS = 5e3;
+const authLog = createLogger("spectrum.imessage.auth");
 const cloudAuthState = /* @__PURE__ */ new WeakMap();
-const requirePhone = (data, instanceId) => {
-	const phone = data.numbers?.[instanceId];
-	if (!phone) throw new Error(`iMessage instance ${instanceId} has no phone assigned`);
-	return phone;
-};
+const instanceAttrs = (instanceId) => ({ "spectrum.imessage.instance": instanceId });
 async function createCloudClients(projectId, projectSecret) {
 	let tokenData = await cloud.issueImessageTokens(projectId, projectSecret);
 	let lastRefreshAt = Date.now();
-	const records = [];
-	const syncPhones = (data) => {
-		for (const { entry, instanceId } of records) entry.phone = requirePhone(data, instanceId);
+	const entries = [];
+	const records = /* @__PURE__ */ new Map();
+	const buildEntry = (instanceId, phone, initialToken) => ({
+		phone,
+		client: createGrpcClient({
+			address: `${instanceId}.imsg.photon.codes:443`,
+			autoIdempotency: true,
+			retry: true,
+			tls: true,
+			token: async () => {
+				await renewal.refreshIfNeeded();
+				if (tokenData.type !== "dedicated") return initialToken;
+				return tokenData.auth[instanceId] ?? initialToken;
+			}
+		})
+	});
+	const retire = async (entry) => {
+		await Promise.allSettled(notifyLineDetached(entries, entry));
+		await entry.client.close();
+	};
+	const removeMissing = (data) => {
+		let removed = 0;
+		for (const [instanceId, entry] of records) {
+			if (data.auth[instanceId]) continue;
+			records.delete(instanceId);
+			const index = entries.indexOf(entry);
+			if (index >= 0) entries.splice(index, 1);
+			removed += 1;
+			retire(entry).catch((error) => {
+				authLog.warn("failed to retire imessage line", {
+					...instanceAttrs(instanceId),
+					...errorAttrs(error)
+				}, error instanceof Error ? error : void 0);
+			});
+		}
+		return removed;
+	};
+	const addOrSync = (data) => {
+		let added = 0;
+		for (const [instanceId, token] of Object.entries(data.auth)) {
+			const phone = data.numbers?.[instanceId];
+			const existing = records.get(instanceId);
+			if (existing) {
+				if (phone) existing.phone = phone;
+				else authLog.warn("imessage line lost its phone number; keeping the last known number", instanceAttrs(instanceId));
+				notifyLineAttached(entries, existing);
+				continue;
+			}
+			if (!phone) {
+				authLog.warn("skipping imessage line without a phone number", instanceAttrs(instanceId));
+				continue;
+			}
+			const entry = buildEntry(instanceId, phone, token);
+			setLineId(entry, instanceId);
+			records.set(instanceId, entry);
+			entries.push(entry);
+			notifyLineAttached(entries, entry);
+			added += 1;
+		}
+		return added;
+	};
+	/**
+	* Brings the client set in line with the token payload, which is the only
+	* inventory the cloud exposes: keys present but untracked are newly
+	* provisioned, tracked keys that vanished were deprovisioned.
+	*
+	* An empty payload means the project has no lines, not that the response is
+	* suspect — keeping entries the payload no longer covers would leave the
+	* client routing through channels whose tokens have stopped being refreshed.
+	* A genuinely malformed payload (no `auth` at all) throws instead, which the
+	* caller contains before any line is removed.
+	*/
+	const reconcile = (data) => {
+		const removed = removeMissing(data);
+		const added = addOrSync(data);
+		if (added > 0 || removed > 0) authLog.info("imessage lines reconciled", {
+			"spectrum.imessage.lines.added": added,
+			"spectrum.imessage.lines.removed": removed,
+			"spectrum.imessage.lines.total": entries.length
+		});
 	};
 	const renewal = createTokenRenewal({
 		expiresInSeconds: () => tokenData.expiresIn,
@@ -251,7 +392,12 @@ async function createCloudClients(projectId, projectSecret) {
 		refresh: async () => {
 			tokenData = await cloud.issueImessageTokens(projectId, projectSecret);
 			lastRefreshAt = Date.now();
-			if (tokenData.type === "dedicated") syncPhones(tokenData);
+			if (tokenData.type !== "dedicated") return;
+			try {
+				reconcile(tokenData);
+			} catch (error) {
+				authLog.error("imessage line reconcile failed", errorAttrs(error), error instanceof Error ? error : void 0);
+			}
 		}
 	});
 	const forceRefresh = async () => {
@@ -263,10 +409,11 @@ async function createCloudClients(projectId, projectSecret) {
 		forceRefresh
 	};
 	if (tokenData.type === "shared") {
-		const entries = [{
+		const address = process.env.SPECTRUM_IMESSAGE_ADDRESS ?? "imessage.spectrum.photon.codes:443";
+		entries.push({
 			phone: SHARED_PHONE,
 			client: createGrpcClient({
-				address: process.env.SPECTRUM_IMESSAGE_ADDRESS ?? "imessage.spectrum.photon.codes:443",
+				address,
 				autoIdempotency: true,
 				retry: true,
 				tls: true,
@@ -275,35 +422,16 @@ async function createCloudClients(projectId, projectSecret) {
 					return tokenData.token;
 				}
 			})
-		}];
+		});
 		cloudAuthState.set(entries, cloudAuth);
 		return entries;
 	}
-	const dedicated = tokenData;
-	for (const [instanceId, token] of Object.entries(dedicated.auth)) {
-		const entry = {
-			phone: requirePhone(dedicated, instanceId),
-			client: createGrpcClient({
-				address: `${instanceId}.imsg.photon.codes:443`,
-				autoIdempotency: true,
-				retry: true,
-				tls: true,
-				token: async () => {
-					await renewal.refreshIfNeeded();
-					return tokenData.auth[instanceId] ?? token;
-				}
-			})
-		};
-		records.push({
-			entry,
-			instanceId
-		});
-	}
-	const entries = records.map((r) => r.entry);
+	reconcile(tokenData);
 	cloudAuthState.set(entries, cloudAuth);
 	return entries;
 }
 async function disposeCloudAuth(clients) {
+	clearLineObservers(clients);
 	const auth = cloudAuthState.get(clients);
 	if (auth) {
 		auth.dispose();
@@ -409,6 +537,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 +805,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 +869,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 +957,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 +994,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 +1119,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 +1662,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 +1710,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 +1739,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 +1769,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 +1824,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 +1856,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 +1868,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 +1881,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 +1941,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 +2123,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}`,
@@ -1952,11 +2261,26 @@ const messages$1 = (clients, projectConfig, profileSyncGate) => {
 	const pollCache = getPollCache(clients);
 	const staticShareEnabled = projectConfig?.profile?.imessageSynced === true;
 	const recover = getCloudRecover(clients);
-	const includeGroupEvents = !isSharedMode(clients);
-	return mergeStreams(clients.map((entry) => {
+	const shared = isSharedMode(clients);
+	const includeGroupEvents = !shared;
+	const build = (entry) => () => {
 		const tracker = staticShareEnabled || profileSyncGate ? getContactShareTracker(entry.client) : void 0;
 		return clientStream(entry.client, pollCache, entry.phone, includeGroupEvents, tracker ? contactShareHandler(tracker, profileSyncGate) : void 0, recover);
-	}));
+	};
+	const group = createStreamGroup({ label: "imessage.messages" });
+	for (const entry of clients) group.add(lineKey(entry), build(entry));
+	if (shared) return group;
+	const disposeObserver = addLineObserver(clients, {
+		attach: (entry) => {
+			group.add(lineKey(entry), build(entry));
+		},
+		detach: (entry) => group.remove(lineKey(entry)).then(() => void 0)
+	});
+	const closeGroup = group.close.bind(group);
+	return Object.assign(group, { close: async () => {
+		disposeObserver();
+		await closeGroup();
+	} });
 };
 //#endregion
 //#region src/remote/stream-text.ts

package/package.json

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