@spectrum-ts/imessage 12.3.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$3 = 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$3.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$3.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$2 = 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;
@@ -1530,6 +1561,14 @@ var ContactShareTracker = class {
 		this.client = client;
 	}
 	/**
+	* Whether this line has already attempted to share with the chat during the
+	* 24-hour dedupe window. Callers use this before consulting any remote gate,
+	* so repeat inbound messages stay entirely local.
+	*/
+	hasRecentlyShared(chatGuid) {
+		return this.cache.has(chatGuid);
+	}
+	/**
 	* Best-effort share. The cache is set eagerly so that a burst of inbound
 	* messages for the same chat coalesces to a single API call. A
 	* `preconditionFailed` response remains cached for the normal 24-hour TTL,
@@ -1543,10 +1582,10 @@ var ContactShareTracker = class {
 		this.cache.set(chatGuid, true);
 		const safeChatGuid = sanitizeErrorMessage(chatGuid);
 		this.client.chats.shareContactInfo(chatGuid).then(() => {
-			log$2.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$2.warn("failed to share contact card", {
+			log$4.warn("failed to share contact card", {
 				"spectrum.imessage.contact.chat": safeChatGuid,
 				...errorAttrs(error)
 			}, error);
@@ -1572,7 +1611,7 @@ const getContactShareTracker = (client) => {
 };
 //#endregion
 //#region src/remote/group-events.ts
-const log$1 = 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`
@@ -1602,7 +1641,7 @@ const fetchIconContent = async (client, event) => {
 			}
 		});
 	} catch (e) {
-		log$1.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);
@@ -1657,7 +1696,7 @@ const toGroupEventMessages = async (client, event, phone) => {
 };
 //#endregion
 //#region src/remote/polls.ts
-const log = 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) => {
@@ -1689,7 +1728,7 @@ const cachePollEvent = (cache, event) => {
 		cache.set(event.pollMessageGuid, cached);
 		return cached;
 	} catch (e) {
-		log.error("failed to cache poll", {
+		log$2.error("failed to cache poll", {
 			"spectrum.imessage.poll.guid": event.pollMessageGuid,
 			...errorAttrs(e)
 		}, e);
@@ -1701,7 +1740,7 @@ const fetchPollInfo = async (client, cache, event) => {
 		cachePollInfo(cache, info);
 		return info;
 	} catch (e) {
-		log.error("failed to fetch poll", {
+		log$2.error("failed to fetch poll", {
 			"spectrum.imessage.poll.guid": event.pollMessageGuid,
 			...errorAttrs(e)
 		}, e);
@@ -1714,7 +1753,7 @@ const resolvePoll = async (client, cache, event) => {
 	try {
 		return cachePollInfo(cache, await client.polls.get(event.pollMessageGuid));
 	} catch (e) {
-		log.error("failed to resolve poll", {
+		log$2.error("failed to resolve poll", {
 			"spectrum.imessage.poll.guid": event.pollMessageGuid,
 			...errorAttrs(e)
 		}, e);
@@ -1774,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) => {
@@ -1826,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}`,
@@ -1931,14 +2120,23 @@ const clientStream = (client, pollCache, phone, includeGroupEvents, onInbound, r
 	if (includeGroupEvents) streams.push(groupStream(client, phone, recover));
 	return mergeStreams(streams);
 };
-const messages$1 = (clients, projectConfig) => {
+const shareWhenProfileSynced = (tracker, gate, chatGuid) => {
+	if (tracker.hasRecentlyShared(chatGuid)) return;
+	gate.isEnabled().then((enabled) => {
+		if (enabled) tracker.maybeShare(chatGuid);
+	}).catch((error) => {
+		streamLog.warn("profile sync gate failed; skipping automatic contact sharing", errorAttrs(error), error instanceof Error ? error : void 0);
+	});
+};
+const contactShareHandler = (tracker, profileSyncGate) => profileSyncGate ? (chatGuid) => shareWhenProfileSynced(tracker, profileSyncGate, chatGuid) : (chatGuid) => tracker.maybeShare(chatGuid);
+const messages$1 = (clients, projectConfig, profileSyncGate) => {
 	const pollCache = getPollCache(clients);
-	const shareEnabled = projectConfig?.profile?.imessageSynced === true;
+	const staticShareEnabled = projectConfig?.profile?.imessageSynced === true;
 	const recover = getCloudRecover(clients);
 	const includeGroupEvents = !isSharedMode(clients);
 	return mergeStreams(clients.map((entry) => {
-		const tracker = shareEnabled ? getContactShareTracker(entry.client) : void 0;
-		return clientStream(entry.client, pollCache, entry.phone, includeGroupEvents, tracker ? (chatGuid) => tracker.maybeShare(chatGuid) : void 0, recover);
+		const tracker = staticShareEnabled || profileSyncGate ? getContactShareTracker(entry.client) : void 0;
+		return clientStream(entry.client, pollCache, entry.phone, includeGroupEvents, tracker ? contactShareHandler(tracker, profileSyncGate) : void 0, recover);
 	}));
 };
 //#endregion
@@ -1999,7 +2197,7 @@ const stopTyping$1 = async (remote, spaceId) => {
 };
 //#endregion
 //#region src/remote/api.ts
-const messages = (clients, projectConfig) => messages$1(clients, projectConfig);
+const messages = (clients, projectConfig, profileSyncGate) => messages$1(clients, projectConfig, profileSyncGate);
 const setBackground = async (remote, spaceId, content) => setBackground$1(remote, spaceId, content);
 const sendCustomizedMiniApp = async (remote, spaceId, content) => sendCustomizedMiniApp$1(remote, spaceId, content);
 const updateCustomizedMiniApp = async (remote, spaceId, session, content) => updateCustomizedMiniApp$1(remote, spaceId, session, content);
@@ -2058,6 +2256,73 @@ const toSpectrumMiniApp = (url, layout, live) => asCustomizedMiniApp({
 	...live === void 0 ? {} : { live }
 });
 //#endregion
+//#region src/remote/profile-sync-gate.ts
+const PROFILE_SYNC_CACHE_TTL_MS = 6e4;
+const PROFILE_SYNC_RETRY_DELAY_MS = 3e4;
+const log = createLogger("spectrum.imessage.profile-sync");
+const createProfileSyncGate = (options) => {
+	const cacheTtlMs = options.cacheTtlMs ?? PROFILE_SYNC_CACHE_TTL_MS;
+	const retryDelayMs = options.retryDelayMs ?? PROFILE_SYNC_RETRY_DELAY_MS;
+	let cachedEnabled = options.initialEnabled;
+	let disposed = false;
+	let refreshInFlight;
+	let retryAfter = 0;
+	let validUntil = Date.now() + cacheTtlMs;
+	const refreshNow = async () => {
+		try {
+			const enabled = await options.refresh();
+			if (disposed) return false;
+			cachedEnabled = enabled;
+			retryAfter = 0;
+			validUntil = Date.now() + cacheTtlMs;
+			return enabled;
+		} catch (error) {
+			cachedEnabled = false;
+			retryAfter = Date.now() + retryDelayMs;
+			validUntil = 0;
+			log.warn("failed to refresh profile sync state; automatic contact sharing remains disabled", {
+				"spectrum.imessage.profile_sync.retry_in_ms": retryDelayMs,
+				...errorAttrs(error)
+			}, error);
+			return false;
+		}
+	};
+	const coalescedRefresh = () => {
+		if (!refreshInFlight) refreshInFlight = refreshNow().finally(() => {
+			refreshInFlight = void 0;
+		});
+		return refreshInFlight;
+	};
+	return {
+		dispose() {
+			disposed = true;
+			cachedEnabled = false;
+			validUntil = 0;
+		},
+		async isEnabled() {
+			if (disposed) return false;
+			const now = Date.now();
+			if (now < validUntil) return cachedEnabled;
+			if (now < retryAfter) return false;
+			return await coalescedRefresh();
+		}
+	};
+};
+const gates = /* @__PURE__ */ new WeakMap();
+const isProfileSynced = (projectConfig) => projectConfig.profile?.imessageSynced === true;
+const registerProfileSyncGate = (clients, projectId, projectSecret, projectConfig) => {
+	gates.get(clients)?.dispose();
+	gates.set(clients, createProfileSyncGate({
+		initialEnabled: isProfileSynced(projectConfig),
+		refresh: async () => isProfileSynced(await cloud.getProject(projectId, projectSecret))
+	}));
+};
+const getProfileSyncGate = (clients) => gates.get(clients);
+const disposeProfileSyncGate = (clients) => {
+	gates.get(clients)?.dispose();
+	gates.delete(clients);
+};
+//#endregion
 //#region src/index.ts
 const isPollContent = (content) => content.type === "poll" || content.type === "poll_option";
 const cacheRemoteOutbound = (remote, space, record) => {
@@ -2197,8 +2462,9 @@ const imessage = definePlatform(IMESSAGE_PLATFORM, {
 	config: configSchema,
 	static: { effect: { message: messageEffects } },
 	lifecycle: {
-		createClient: async ({ config, projectId, projectSecret }) => {
-			if (config.clients) return (Array.isArray(config.clients) ? config.clients : [config.clients]).map((e) => ({
+		createClient: async ({ config, projectConfig, projectId, projectSecret }) => {
+			let clients;
+			if (config.clients) clients = (Array.isArray(config.clients) ? config.clients : [config.clients]).map((e) => ({
 				phone: e.phone,
 				client: createGrpcClient({
 					address: e.address,
@@ -2208,10 +2474,13 @@ const imessage = definePlatform(IMESSAGE_PLATFORM, {
 					token: e.token
 				})
 			}));
-			if (!(projectId && projectSecret)) throw new Error("Cloud iMessage requires projectId and projectSecret. Pass credentials to Spectrum() or provide explicit clients with imessage.config({ clients: [...] }). For local Messages access, install @spectrum-ts/imessage-local and use localIMessage.config().");
-			return await createCloudClients(projectId, projectSecret);
+			else if (projectId && projectSecret) clients = await createCloudClients(projectId, projectSecret);
+			else throw new Error("Cloud iMessage requires projectId and projectSecret. Pass credentials to Spectrum() or provide explicit clients with imessage.config({ clients: [...] }). For local Messages access, install @spectrum-ts/imessage-local and use localIMessage.config().");
+			if (projectId && projectSecret && projectConfig) registerProfileSyncGate(clients, projectId, projectSecret, projectConfig);
+			return clients;
 		},
 		destroyClient: async ({ client }) => {
+			disposeProfileSyncGate(client);
 			await disposeCloudAuth(client);
 			await Promise.all(client.map((entry) => entry.client.close()));
 		}
@@ -2263,7 +2532,7 @@ const imessage = definePlatform(IMESSAGE_PLATFORM, {
 		}
 	},
 	message: { schema: messageSchema },
-	messages: ({ client, projectConfig }) => messages(client, projectConfig),
+	messages: ({ client, projectConfig }) => messages(client, projectConfig, getProfileSyncGate(client)),
 	send: async ({ space, content, client }) => {
 		if (content.type === "reply") {
 			const remote = remoteForMessageTarget(client, space, content.target, "reply", "replies");

package/package.json

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