@spectrum-ts/imessage 8.2.2 → 9.1.0

package/dist/index.d.ts

@@ -1,9 +1,23 @@
-import { AdvancedIMessage, MessageEffect } from "@photon-ai/advanced-imessage";
+import { AdvancedIMessage, ChatServiceType, MessageEffect } from "@photon-ai/advanced-imessage";
 import { IMessageSDK } from "@photon-ai/imessage-kit";
 import { Attachment, ContentBuilder, ContentInput, SchemaMessage, Space, read } from "@spectrum-ts/core";
 import { PhotoInput } from "@spectrum-ts/core/authoring";
 import z from "zod";
 
+//#region src/remote/members.d.ts
+/**
+ * A group participant mapped to spectrum's user shape. `id` is the canonical
+ * address (E.164 phone or email — the same handle format `space.create`
+ * accepts); `address`/`country`/`service` mirror the SDK record and match
+ * the extras declared by the provider's `userSchema`.
+ */
+type IMessageParticipant = {
+  id: string;
+  address: string;
+  country?: string;
+  service: ChatServiceType;
+};
+//#endregion
 //#region src/content/background.d.ts
 type BackgroundInput = PhotoInput;
 /**
@@ -259,6 +273,87 @@ declare const imessage: import("@spectrum-ts/core").Platform<import("@spectrum-t
     id: string;
     __platform: string;
   }, messageId: string) => Promise<IMessageMessage | undefined>;
+  getMembers: ({
+    client
+  }: {
+    client: IMessageClient;
+    config: {
+      local: true;
+    } | {
+      local: false;
+      clients?: {
+        address: string;
+        token: string;
+        phone: string;
+      } | {
+        address: string;
+        token: string;
+        phone: string;
+      }[] | undefined;
+    };
+    store: import("@spectrum-ts/core").Store;
+  }, space: {
+    id: string;
+    type: "dm" | "group";
+    phone: string;
+  } & {
+    id: string;
+    __platform: string;
+  }) => Promise<IMessageParticipant[]>;
+  getAvatar: ({
+    client
+  }: {
+    client: IMessageClient;
+    config: {
+      local: true;
+    } | {
+      local: false;
+      clients?: {
+        address: string;
+        token: string;
+        phone: string;
+      } | {
+        address: string;
+        token: string;
+        phone: string;
+      }[] | undefined;
+    };
+    store: import("@spectrum-ts/core").Store;
+  }, space: {
+    id: string;
+    type: "dm" | "group";
+    phone: string;
+  } & {
+    id: string;
+    __platform: string;
+  }) => Promise<import("@spectrum-ts/core").AvatarData | undefined>;
+  getDisplayName: ({
+    client
+  }: {
+    client: IMessageClient;
+    config: {
+      local: true;
+    } | {
+      local: false;
+      clients?: {
+        address: string;
+        token: string;
+        phone: string;
+      } | {
+        address: string;
+        token: string;
+        phone: string;
+      }[] | undefined;
+    };
+    store: import("@spectrum-ts/core").Store;
+  }, space: {
+    id: string;
+    type: "dm" | "group";
+    phone: string;
+  } & {
+    id: string;
+    __platform: string;
+  }) => Promise<string | undefined>;
   getAttachment: ({
     client
   }: {

package/dist/index.js

@@ -2,7 +2,7 @@ import { MessageEffect, NotFoundError, ValidationError, createClient } from "@ph
 import { IMessageSDK } from "@photon-ai/imessage-kit";
 import { sanitizePhone, withSpan } from "@photon-ai/otel";
 import { UnsupportedError, appLayoutSchema, cloud, definePlatform, fromVCard, mergeStreams, read, stream, text, toVCard } from "@spectrum-ts/core";
-import { asAttachment, asContact, asCustom, asGroup, asPoll, asPollOption, asReply, asText, buildPhotoAction, createLogger, ensureM4a, errorAttrs, groupSchema, messageEffectSchema, photoActionSchema, reactionSchema, resumableOrderedStream, sanitizeErrorMessage } from "@spectrum-ts/core/authoring";
+import { addMemberSchema, asAttachment, asContact, asCustom, asGroup, asPoll, asPollOption, asReply, asText, avatarSchema, buildPhotoAction, createLogger, ensureM4a, errorAttrs, groupSchema, leaveSpaceSchema, messageEffectSchema, photoActionSchema, reactionSchema, removeMemberSchema, renameSchema, resumableOrderedStream, sanitizeErrorMessage } from "@spectrum-ts/core/authoring";
 import z from "zod";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { createReadStream } from "node:fs";
@@ -216,7 +216,7 @@ const messageSchema = z.object({
 });
 //#endregion
 //#region src/auth.ts
-const log$3 = createLogger("spectrum.imessage.auth");
+const log$4 = createLogger("spectrum.imessage.auth");
 const RENEWAL_RATIO = .8;
 const EXPIRY_BUFFER_MS = 3e4;
 const RETRY_DELAY_MS = 3e4;
@@ -241,13 +241,13 @@ async function createCloudClients(projectId, projectSecret) {
 	};
 	const onRefreshSuccess = () => {
 		if (refreshFailures > 0) {
-			log$3.info("imessage token refresh recovered", { "spectrum.imessage.auth.attempt": refreshFailures });
+			log$4.info("imessage token refresh recovered", { "spectrum.imessage.auth.attempt": refreshFailures });
 			refreshFailures = 0;
 		}
 	};
 	const onRefreshFailure = (error) => {
 		refreshFailures += 1;
-		log$3.warn("imessage token refresh failed; retrying", {
+		log$4.warn("imessage token refresh failed; retrying", {
 			"spectrum.imessage.auth.attempt": refreshFailures,
 			"spectrum.imessage.auth.retry_in_ms": RETRY_DELAY_MS,
 			...errorAttrs(error)
@@ -732,6 +732,26 @@ const setIcon$1 = async (remote, spaceId, content) => {
 	const buffer = await content.action.read();
 	await remote.groups.setIcon(chat, new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength));
 };
+/**
+* Download the current icon of a remote iMessage group chat. Resolves
+* `undefined` when the group has no icon (the SDK's `NotFoundError` with
+* code `groupIconNotFound`); any other error — including a `chatNotFound`
+* `NotFoundError` — propagates. Bytes are copied into a Buffer so the result
+* round-trips into `setIcon` / `space.avatar(...)`. The caller (`getAvatar`
+* in the iMessage provider) owns the group-only / remote-only guards.
+*/
+const getIcon$1 = async (remote, spaceId) => {
+	try {
+		const icon = await remote.groups.getIcon(toChatGuid(spaceId));
+		return {
+			data: Buffer.from(icon.data),
+			mimeType: icon.mimeType
+		};
+	} catch (err) {
+		if (err instanceof NotFoundError && err.code === "groupIconNotFound") return;
+		throw err;
+	}
+};
 //#endregion
 //#region src/remote/background.ts
 /**
@@ -875,7 +895,7 @@ const getRemoteAttachment = async (client, guid) => {
 };
 //#endregion
 //#region src/remote/inbound.ts
-const log$2 = createLogger("spectrum.imessage.inbound");
+const log$3 = createLogger("spectrum.imessage.inbound");
 const messageAttachments = (message) => message.content.attachments;
 const resolveChatGuid = (message, hint) => {
 	if (hint) return hint;
@@ -931,7 +951,7 @@ const toVCardContent = async (client, info) => {
 	try {
 		return asContact(fromVCard((await downloadPrimaryAttachment(client, info.guid)).toString("utf8")));
 	} catch (err) {
-		log$2.warn("failed to parse vCard attachment; falling back to attachment content", {
+		log$3.warn("failed to parse vCard attachment; falling back to attachment content", {
 			"spectrum.imessage.attachment.guid": info.guid,
 			...errorAttrs(err)
 		}, err);
@@ -1014,7 +1034,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$2.warn("failed to resolve iMessage reply target; falling back to stub target", {
+		if (!(err instanceof NotFoundError)) log$3.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)
@@ -1087,6 +1107,48 @@ const getMessage$1 = async (remote, spaceId, msgId, phone) => {
 	}
 };
 //#endregion
+//#region src/remote/members.ts
+/**
+* Apply an `AddMember` content value to a remote iMessage group chat.
+* Fire-and-forget — the `Chat` returned by `addParticipants` is discarded.
+* The caller (`handleAddMember` in the iMessage provider) is responsible
+* for the group-only / remote-only guards.
+*/
+const addParticipants$1 = async (remote, spaceId, content) => {
+	await remote.groups.addParticipants(toChatGuid(spaceId), content.members);
+};
+/**
+* Apply a `RemoveMember` content value to a remote iMessage group chat.
+* Fire-and-forget — the `Chat` returned by `removeParticipants` is
+* discarded.
+*/
+const removeParticipants$1 = async (remote, spaceId, content) => {
+	await remote.groups.removeParticipants(toChatGuid(spaceId), content.members);
+};
+/**
+* Make the agent's own account leave a remote iMessage group chat.
+* Fire-and-forget.
+*/
+const leaveGroup$1 = async (remote, spaceId) => {
+	await remote.groups.leave(toChatGuid(spaceId));
+};
+/**
+* List a remote group chat's current participants, excluding the agent's own
+* handle (`selfPhone` — the dedicated number that owns the chat; the shared
+* sentinel never matches a canonical address, so shared mode returns the
+* full roster). The caller (`getMembers` in the iMessage provider) owns the
+* group-only / remote-only guards.
+*/
+const listParticipants$1 = async (remote, spaceId, selfPhone) => {
+	const { participants } = await remote.chats.get(toChatGuid(spaceId));
+	return participants.filter((p) => p.address !== selfPhone).map((p) => ({
+		id: p.address,
+		address: p.address,
+		country: p.country,
+		service: p.service
+	}));
+};
+//#endregion
 //#region src/remote/reactions.ts
 const EMOJI_TO_TAPBACK = {
 	"❤️": "love",
@@ -1186,6 +1248,15 @@ const markRead$1 = async (remote, spaceId) => {
 const setDisplayName$1 = async (remote, spaceId, content) => {
 	await remote.groups.setDisplayName(toChatGuid(spaceId), content.displayName);
 };
+/**
+* Read a remote iMessage group chat's title. The SDK returns an empty
+* `Chat.displayName` for an unnamed group; normalized to `undefined`. The
+* group-only guard lives at the action layer (see `remoteGroupClient`).
+*/
+const getDisplayName$1 = async (remote, spaceId) => {
+	const { displayName } = await remote.chats.get(toChatGuid(spaceId));
+	return displayName || void 0;
+};
 //#endregion
 //#region src/remote/markdown.ts
 const markdownLexer = new Marked();
@@ -1616,7 +1687,7 @@ const unsendMessage$1 = async (remote, spaceId, msgId) => {
 };
 //#endregion
 //#region src/remote/contact-share.ts
-const log$1 = createLogger("spectrum.imessage.contact");
+const log$2 = createLogger("spectrum.imessage.contact");
 const SHARE_TTL_MS = 1440 * 60 * 1e3;
 const MAX_TRACKED_CHATS = 1e4;
 /**
@@ -1653,10 +1724,10 @@ var ContactShareTracker = class {
 		this.cache.set(chatGuid, true);
 		const safeChatGuid = sanitizeErrorMessage(chatGuid);
 		this.client.chats.shareContactInfo(chatGuid).then(() => {
-			log$1.info("shared contact card", { "spectrum.imessage.contact.chat": safeChatGuid });
+			log$2.info("shared contact card", { "spectrum.imessage.contact.chat": safeChatGuid });
 		}).catch((error) => {
 			this.cache.delete(chatGuid);
-			log$1.warn("failed to share contact card", {
+			log$2.warn("failed to share contact card", {
 				"spectrum.imessage.contact.chat": safeChatGuid,
 				...errorAttrs(error)
 			}, error);
@@ -1681,6 +1752,91 @@ const getContactShareTracker = (client) => {
 	return tracker;
 };
 //#endregion
+//#region src/remote/group-events.ts
+const log$1 = 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`
+* is monotonic per line, so the id is unique across all change kinds.
+*/
+const groupEventMessageId = (event) => `${event.chatGuid}:group:${event.sequence}`;
+/**
+* The acting party of a group change. For `participantLeft` that is the
+* leaver (`change.participant`) — nobody leaves on someone else's behalf
+* (third-party removal is `participantRemoved`), and `leaveSpace` content
+* carries no members, so the leaver's identity can only travel on
+* `message.sender`. Every other change acts through `event.actor`, which the
+* platform doesn't always record.
+*/
+const groupEventActor = (event) => event.change.type === "participantLeft" ? event.change.participant : event.actor;
+const toOptionalSenderRef = (addr) => addr?.address ? toSenderRef(addr) : void 0;
+const fetchIconContent = async (client, event) => {
+	try {
+		const icon = await getIcon$1(client, event.chatGuid);
+		if (!icon) return;
+		return avatarSchema.parse({
+			type: "avatar",
+			action: {
+				kind: "set",
+				mimeType: icon.mimeType,
+				read: () => Promise.resolve(icon.data)
+			}
+		});
+	} catch (e) {
+		log$1.error("failed to fetch changed group icon", {
+			"spectrum.imessage.group.chat": event.chatGuid,
+			...errorAttrs(e)
+		}, e);
+		return;
+	}
+};
+const toGroupChangeContent = async (client, event) => {
+	const change = event.change;
+	switch (change.type) {
+		case "participantAdded": return change.participant.address ? addMemberSchema.parse({
+			type: "addMember",
+			members: [change.participant.address]
+		}) : void 0;
+		case "participantRemoved": return change.participant.address ? removeMemberSchema.parse({
+			type: "removeMember",
+			members: [change.participant.address]
+		}) : void 0;
+		case "participantLeft": return leaveSpaceSchema.parse({ type: "leaveSpace" });
+		case "displayNameChanged": return change.displayName ? renameSchema.parse({
+			type: "rename",
+			displayName: change.displayName
+		}) : void 0;
+		case "iconChanged": return await fetchIconContent(client, event);
+		case "iconRemoved": return avatarSchema.parse({
+			type: "avatar",
+			action: { kind: "clear" }
+		});
+		default: return;
+	}
+};
+/**
+* Convert a `group.changed` event into inbound spectrum messages. Unlike
+* reactions — where an event without an actor is dropped because the actor
+* is itself the substance — membership/rename/avatar changes surface even
+* when the platform recorded no actor: the state change is the payload, so
+* the message ships with `sender: undefined`.
+*/
+const toGroupEventMessages = async (client, event, phone) => {
+	const content = await toGroupChangeContent(client, event);
+	if (!content) return [];
+	return [{
+		id: groupEventMessageId(event),
+		content,
+		sender: toOptionalSenderRef(groupEventActor(event)),
+		space: {
+			id: event.chatGuid,
+			type: chatTypeFromGuid(event.chatGuid),
+			phone
+		},
+		timestamp: event.occurredAt
+	}];
+};
+//#endregion
 //#region src/remote/polls.ts
 const log = createLogger("spectrum.imessage.poll");
 const isVotedPollEvent = (event) => event.delta.type === "voted";
@@ -1851,6 +2007,22 @@ const toPollItem = async (client, pollCache, event, phone, cursor) => {
 		values: await toPollDeltaMessages(client, pollCache, event, phone)
 	};
 };
+const toGroupItem = async (client, event, phone, cursor) => {
+	const id = groupEventMessageId(event);
+	if (isEventFromCurrentAccount({
+		actor: groupEventActor(event),
+		isFromMe: event.isFromMe
+	}, phone)) return {
+		cursor,
+		id,
+		values: []
+	};
+	return {
+		cursor,
+		id,
+		values: await toGroupEventMessages(client, event, phone)
+	};
+};
 const toCatchUpCompleteItem = (event) => ({
 	cursor: String(event.headSequence),
 	id: `${event.type}:${event.headSequence}`,
@@ -1858,6 +2030,7 @@ const toCatchUpCompleteItem = (event) => ({
 });
 const isMessageEvent = (event) => event.type.startsWith("message.");
 const isPollEvent = (event) => event.type === "poll.changed";
+const isGroupEvent = (event) => event.type === "group.changed";
 async function* catchUpEvents(client, cursor, isWanted) {
 	const since = toResumeAfter(cursor);
 	if (since === void 0) return;
@@ -1906,7 +2079,20 @@ const pollStream = (client, pollCache, phone, recover) => resumableOrderedStream
 	processMissed: (event) => event.type === "catchup.complete" ? Promise.resolve(toCatchUpCompleteItem(event)) : toPollItem(client, pollCache, event, phone, String(event.sequence)),
 	subscribeLive: (cursor) => withClose(client.polls.subscribeEvents(), cursor)
 });
-const clientStream = (client, pollCache, phone, onInbound, recover) => mergeStreams([messageStream(client, phone, onInbound, recover), pollStream(client, pollCache, phone, recover)]);
+const groupStream = (client, phone, recover) => resumableOrderedStream({
+	fetchMissed: (cursor) => catchUpEvents(client, cursor, isGroupEvent),
+	isCursorRejectedError: isCursorRejectedIMessageError,
+	label: streamLabel("groups", phone),
+	recover,
+	processLive: (event) => toGroupItem(client, event, phone, String(event.sequence)),
+	processMissed: (event) => event.type === "catchup.complete" ? Promise.resolve(toCatchUpCompleteItem(event)) : toGroupItem(client, event, phone, String(event.sequence)),
+	subscribeLive: (cursor) => withClose(client.groups.subscribeEvents(), cursor)
+});
+const clientStream = (client, pollCache, phone, onInbound, recover) => mergeStreams([
+	messageStream(client, phone, onInbound, recover),
+	pollStream(client, pollCache, phone, recover),
+	groupStream(client, phone, recover)
+]);
 const messages$1 = (clients, projectConfig) => {
 	const pollCache = getPollCache(clients);
 	const shareEnabled = projectConfig?.profile?.imessageSynced === true;
@@ -1978,6 +2164,12 @@ const messages = (clients, projectConfig) => messages$1(clients, projectConfig);
 const setBackground = async (remote, spaceId, content) => setBackground$1(remote, spaceId, content);
 const sendCustomizedMiniApp = async (remote, spaceId, content) => sendCustomizedMiniApp$1(remote, spaceId, content);
 const setDisplayName = async (remote, spaceId, content) => setDisplayName$1(remote, spaceId, content);
+const getDisplayName = async (remote, spaceId) => getDisplayName$1(remote, spaceId);
+const addParticipants = async (remote, spaceId, content) => addParticipants$1(remote, spaceId, content);
+const removeParticipants = async (remote, spaceId, content) => removeParticipants$1(remote, spaceId, content);
+const leaveGroup = async (remote, spaceId) => leaveGroup$1(remote, spaceId);
+const listParticipants = async (remote, spaceId, selfPhone) => listParticipants$1(remote, spaceId, selfPhone);
+const getIcon = async (remote, spaceId) => getIcon$1(remote, spaceId);
 const setIcon = async (remote, spaceId, content) => setIcon$1(remote, spaceId, content);
 const markRead = async (remote, spaceId) => {
 	await markRead$1(remote, spaceId);
@@ -2133,6 +2325,34 @@ const handleAvatar = async (client, space, content) => {
 	await setIcon(clientForPhone(client, space.phone), space.id, content);
 };
 /**
+* Shared guard for the membership handlers: remote-only, group-only, then
+* per-phone client resolution. Mirrors the `handleRename` / `handleAvatar`
+* guard sequence.
+*/
+const remoteGroupClient = (client, space, action, detail) => {
+	if (isLocal(client)) throw UnsupportedError.action(action, "iMessage (local mode)", detail.local);
+	if (space.type !== "group") throw UnsupportedError.action(action, "iMessage", detail.dm);
+	return clientForPhone(client, space.phone);
+};
+const handleAddMember = async (client, space, content) => {
+	await addParticipants(remoteGroupClient(client, space, "addMember", {
+		dm: "only group chats can add members (this space is a DM — iMessage cannot convert a DM into a group; create a group via space.create instead)",
+		local: "adding members requires remote iMessage"
+	}), space.id, content);
+};
+const handleRemoveMember = async (client, space, content) => {
+	await removeParticipants(remoteGroupClient(client, space, "removeMember", {
+		dm: "only group chats can remove members (this space is a DM — iMessage cannot convert a DM into a group; create a group via space.create instead)",
+		local: "removing members requires remote iMessage"
+	}), space.id, content);
+};
+const handleLeaveSpace = async (client, space) => {
+	await leaveGroup(remoteGroupClient(client, space, "leaveSpace", {
+		dm: "only group chats can be left (this space is a DM)",
+		local: "leaving chats requires remote iMessage"
+	}), space.id);
+};
+/**
 * Dispatch the iMessage-only fire-and-forget control signals that live outside
 * the universal `Content` union (`background`, `contactCard`). Each is narrowed
 * via a runtime guard rather than a `content.type ===` check — the literals
@@ -2280,6 +2500,18 @@ const imessage = definePlatform("iMessage", {
 			await handleAvatar(client, space, content);
 			return;
 		}
+		if (content.type === "addMember") {
+			await handleAddMember(client, space, content);
+			return;
+		}
+		if (content.type === "removeMember") {
+			await handleRemoveMember(client, space, content);
+			return;
+		}
+		if (content.type === "leaveSpace") {
+			await handleLeaveSpace(client, space);
+			return;
+		}
 		if (content.type === "read") {
 			await handleRead(client, space);
 			return;
@@ -2296,6 +2528,24 @@ const imessage = definePlatform("iMessage", {
 			if (isLocal(client)) return getMessage$2(client, messageId);
 			return getMessage(clientForPhone(client, space.phone), space.id, messageId, space.phone);
 		},
+		getMembers: async ({ client }, space) => {
+			return await listParticipants(remoteGroupClient(client, space, "getMembers", {
+				dm: "only group chats support listing members (this space is a DM)",
+				local: "listing members requires remote iMessage"
+			}), space.id, space.phone);
+		},
+		getAvatar: async ({ client }, space) => {
+			return await getIcon(remoteGroupClient(client, space, "getAvatar", {
+				dm: "only group chats have avatars (this space is a DM)",
+				local: "fetching group avatars requires remote iMessage"
+			}), space.id);
+		},
+		getDisplayName: async ({ client }, space) => {
+			return await getDisplayName(remoteGroupClient(client, space, "getDisplayName", {
+				dm: "only group chats have display names (this space is a DM)",
+				local: "reading chat display names requires remote iMessage"
+			}), space.id);
+		},
 		getAttachment: async ({ client }, guid, phone) => {
 			if (isLocal(client)) throw UnsupportedError.action("getAttachment", "iMessage (local mode)", "fetching attachments by GUID requires remote iMessage");
 			if (client.length === 0) throw new Error("No iMessage clients configured");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spectrum-ts/imessage",
-  "version": "8.2.2",
+  "version": "9.1.0",
   "description": "iMessage provider for spectrum-ts — local and remote (advanced) modes.",
   "repository": {
     "type": "git",
@@ -39,7 +39,7 @@
     "zod": "^4.2.1"
   },
   "peerDependencies": {
-    "@spectrum-ts/core": "^8.0.0",
+    "@spectrum-ts/core": "^9.0.0",
     "typescript": "^5 || ^6.0.0"
   },
   "license": "MIT"