@spectrum-ts/imessage-local 10.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License Copyright (c) 2025 Photon AI
+
+Permission is hereby granted,
+free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice
+(including the next paragraph) shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# `@spectrum-ts/imessage-local`
+
+Local macOS iMessage provider for spectrum-ts, powered by `@photon-ai/imessage-kit`.
+
+```sh
+bun add spectrum-ts @spectrum-ts/imessage-local
+```
+
+```ts
+import { imessage } from "@spectrum-ts/imessage-local";
+import { Spectrum } from "spectrum-ts";
+
+const spectrum = Spectrum({
+  platforms: [imessage.config()],
+});
+```
+
+This package is intentionally not included in the batteries-included
+`spectrum-ts` package. Install it only on the macOS host that will access the
+local Messages database.

package/dist/index.d.ts

@@ -0,0 +1,269 @@
+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/types.d.ts
+declare const userSchema: z.ZodObject<{
+  address: z.ZodOptional<z.ZodString>;
+  country: z.ZodOptional<z.ZodString>;
+  service: z.ZodOptional<z.ZodEnum<{
+    iMessage: "iMessage";
+    SMS: "SMS";
+    RCS: "RCS";
+    unknown: "unknown";
+  }>>;
+}, z.core.$strip>;
+declare const spaceSchema: z.ZodObject<{
+  id: z.ZodString;
+  type: z.ZodEnum<{
+    dm: "dm";
+    group: "group";
+  }>;
+  phone: z.ZodString;
+}, z.core.$strip>;
+type IMessageMessage = SchemaMessage<typeof userSchema, typeof spaceSchema> & {
+  direction?: "inbound" | "outbound";
+  partIndex?: number;
+  parentId?: string;
+};
+//#endregion
+//#region ../imessage/src/content/background.d.ts
+type BackgroundInput = PhotoInput;
+/**
+ * Set or clear the chat background. iMessage-only, remote-only.
+ *
+ * - `background("clear")` — remove the current chat background.
+ * - `background("./photo.jpg")` — set background from a filesystem path.
+ *   MIME type is inferred from the extension; override with `options.mimeType`.
+ * - `background(new URL("https://…/photo.jpg"))` — fetch the background
+ *   lazily over the network. Bytes stay in memory (safe in read-only
+ *   environments). MIME type is inferred from the URL pathname extension;
+ *   override with `options.mimeType` when the URL has no usable extension.
+ * - `background(buffer, { mimeType })` — set background from in-memory bytes.
+ *   `options.mimeType` is required.
+ *
+ * `"clear"` is a reserved string-literal sentinel. If you have a file literally
+ * named `clear` with no extension, pass `"./clear"` or load it as a Buffer.
+ *
+ * `space.send(background(...))` is the canonical form; `space.background(...)`
+ * is sugar attached via `PlatformDef.space.actions` (only typed on
+ * `PlatformSpace<IMessageDef>`).
+ *
+ * `Background` is intentionally not a member of the universal `Content`
+ * union — the `as unknown as Content` cast keeps the builder shape compatible
+ * with the framework's `ContentBuilder.build(): Promise<Content>` signature.
+ * The framework treats it as a fire-and-forget control signal at runtime.
+ */
+declare function background(input: "clear"): ContentBuilder;
+declare function background(input: string | Buffer | URL, options?: {
+  mimeType?: string;
+}): ContentBuilder;
+//#endregion
+//#region ../imessage/src/content/contact-card.d.ts
+/**
+ * iMessage-only "share contact card" control signal. Pushes the *local
+ * account's native contact card* (the name + photo a recipient sees in their
+ * Messages app) to a chat via the SDK's `chats.shareContactInfo`.
+ *
+ * This is Apple's "Share Name and Photo" mechanism — distinct from the
+ * universal `contact(...)` content, which uploads an arbitrary person's vCard
+ * as a *file* attachment. There is no payload: the card shared is always the
+ * bot account's own.
+ *
+ * Like `background`, it lives entirely under the iMessage provider and never
+ * enters the universal `Content` discriminated union. The framework recognizes
+ * it via two generic content-level contracts:
+ *
+ * 1. `__platform: "iMessage"` — `findUnsupportedPlatformContent` in
+ *    `platform/build.ts` reads this tag and warns-and-skips when a different
+ *    platform receives it.
+ * 2. `__fireAndForget: true` — `dispatchSend`'s fire-and-forget check treats
+ *    this as a side-effecting send that returns no message id, the same way it
+ *    treats `read` / `typing`.
+ *
+ * iMessage's `send` handler narrows back via the `isContactCard` type guard
+ * before dispatching to `chats.shareContactInfo`.
+ */
+declare const contactCardSchema: z.ZodObject<{
+  type: z.ZodLiteral<"contactCard">;
+  __platform: z.ZodLiteral<"iMessage">;
+  __fireAndForget: z.ZodLiteral<true>;
+}, z.core.$strip>;
+type ContactCard = z.infer<typeof contactCardSchema>;
+/**
+ * Share the bot account's native iMessage contact card (name + photo) with the
+ * chat. iMessage-only, remote-only.
+ *
+ * `space.send(nativeContactCard())` is the canonical form; `space.shareContactCard()`
+ * is sugar attached via `PlatformDef.space.actions` (only typed on
+ * `PlatformSpace<IMessageDef>`).
+ *
+ * This is an explicit, on-demand share and always fires — unlike the automatic
+ * best-effort share gated behind the `imessageSynced` project profile, which
+ * dedupes to once per chat per 24h (see `remote/contact-share.ts`). Works in
+ * both DMs and group chats; the recipient chooses whether to accept the card.
+ *
+ * `ContactCard` is intentionally not a member of the universal `Content`
+ * union — the `as unknown as Content` cast keeps the builder shape compatible
+ * with the framework's `ContentBuilder.build(): Promise<Content>` signature.
+ * The framework treats it as a fire-and-forget control signal at runtime.
+ */
+declare function nativeContactCard(): ContentBuilder;
+//#endregion
+//#region ../imessage/src/content/customized-mini-app.d.ts
+declare const layoutSchema: z.ZodObject<{
+  caption: z.ZodOptional<z.ZodString>;
+  subcaption: z.ZodOptional<z.ZodString>;
+  trailingCaption: z.ZodOptional<z.ZodString>;
+  trailingSubcaption: z.ZodOptional<z.ZodString>;
+  image: z.ZodOptional<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+  imageTitle: z.ZodOptional<z.ZodString>;
+  imageSubtitle: z.ZodOptional<z.ZodString>;
+  summary: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * iMessage-only mini-app card content. Lives entirely under the iMessage
+ * provider — never enters the universal `Content` discriminated union. The
+ * framework recognizes it via the generic content-level platform contract:
+ *
+ * - `__platform: "iMessage"` — `findUnsupportedPlatformContent` reads this tag
+ *   and warns-and-skips when a different platform receives it.
+ *
+ * Unlike `background` / `read`, this content is **not** `__fireAndForget`: it
+ * produces a real outbound message, so the iMessage `send` handler narrows
+ * back to `CustomizedMiniApp` via the `isCustomizedMiniApp` guard and returns
+ * the resulting `ProviderMessageRecord` (rather than `void`).
+ */
+declare const customizedMiniAppSchema: z.ZodObject<{
+  type: z.ZodLiteral<"customized-mini-app">;
+  __platform: z.ZodLiteral<"iMessage">;
+  appName: z.ZodString;
+  appStoreId: z.ZodOptional<z.ZodNumber>;
+  extensionBundleId: z.ZodString;
+  layout: z.ZodObject<{
+    caption: z.ZodOptional<z.ZodString>;
+    subcaption: z.ZodOptional<z.ZodString>;
+    trailingCaption: z.ZodOptional<z.ZodString>;
+    trailingSubcaption: z.ZodOptional<z.ZodString>;
+    image: z.ZodOptional<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+    imageTitle: z.ZodOptional<z.ZodString>;
+    imageSubtitle: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>;
+  live: z.ZodOptional<z.ZodBoolean>;
+  teamId: z.ZodString;
+  url: z.ZodURL;
+}, z.core.$strip>;
+type CustomizedMiniApp = z.infer<typeof customizedMiniAppSchema>;
+type CustomizedMiniAppLayout = z.infer<typeof layoutSchema>;
+type CustomizedMiniAppInput = Omit<CustomizedMiniApp, "type" | "__platform">;
+/**
+ * Construct a `customized-mini-app` content value. iMessage-only, remote-only.
+ *
+ * The layout is what recipients see in the bubble. `teamId` and
+ * `extensionBundleId` identify the iMessage extension that receives `url` when
+ * the recipient taps the card; the server constructs the matching
+ * `MSMessageExtensionBalloonPlugin` plugin id from these values. `appStoreId`
+ * is optional and only points recipients without the extension at its App
+ * Store entry. `live` is optional; when omitted, the remote server keeps the
+ * static layout preview visible.
+ *
+ * `space.send(customizedMiniApp(...))` is the canonical form.
+ *
+ * `CustomizedMiniApp` is intentionally not a member of the universal `Content`
+ * union — the `as unknown as Content` cast keeps the builder shape compatible
+ * with the framework's `ContentBuilder.build(): Promise<Content>` signature.
+ */
+declare function customizedMiniApp(input: CustomizedMiniAppInput): ContentBuilder;
+//#endregion
+//#region ../imessage/src/content/effect.d.ts
+declare const messageEffects: {
+  readonly balloons: "com.apple.messages.effect.CKBalloonEffect";
+  readonly celebration: "com.apple.messages.effect.CKHappyBirthdayEffect";
+  readonly confetti: "com.apple.messages.effect.CKConfettiEffect";
+  readonly echo: "com.apple.messages.effect.CKEchoEffect";
+  readonly fireworks: "com.apple.messages.effect.CKFireworksEffect";
+  readonly gentle: "com.apple.MobileSMS.expressivesend.gentle";
+  readonly heart: "com.apple.messages.effect.CKHeartEffect";
+  readonly invisible: "com.apple.MobileSMS.expressivesend.invisibleink";
+  readonly lasers: "com.apple.messages.effect.CKLasersEffect";
+  readonly loud: "com.apple.MobileSMS.expressivesend.loud";
+  readonly slam: "com.apple.MobileSMS.expressivesend.impact";
+  readonly sparkles: "com.apple.messages.effect.CKSparklesEffect";
+  readonly spotlight: "com.apple.messages.effect.CKSpotlightEffect";
+};
+type IMessageMessageEffect = (typeof messageEffects)[keyof typeof messageEffects];
+declare function effect(input: ContentInput, messageEffect: IMessageMessageEffect): ContentBuilder;
+//#endregion
+//#region src/index.d.ts
+declare const imessage: import("@spectrum-ts/core").Platform<import("@spectrum-ts/core").PlatformDef<"iMessage", import("zod").ZodObject<{}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+  address: import("zod").ZodOptional<import("zod").ZodString>;
+  country: import("zod").ZodOptional<import("zod").ZodString>;
+  service: import("zod").ZodOptional<import("zod").ZodEnum<{
+    iMessage: "iMessage";
+    SMS: "SMS";
+    RCS: "RCS";
+    unknown: "unknown";
+  }>>;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+  id: import("zod").ZodString;
+  type: import("zod").ZodEnum<{
+    dm: "dm";
+    group: "group";
+  }>;
+  phone: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{}, import("zod/v4/core").$strip>, IMessageSDK, {
+  id: string;
+}, {
+  id: string;
+  type: "dm" | "group";
+  phone: string;
+}, import("zod").ZodObject<{
+  partIndex: import("zod").ZodOptional<import("zod").ZodNumber>;
+  parentId: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>, IMessageMessage, undefined, {
+  background: (space: Space, input: BackgroundInput, options?: {
+    mimeType?: string;
+  }) => Promise<void>;
+  shareContactCard: (space: Space) => Promise<void>;
+}, Record<never, never>, {
+  getMessage: ({
+    client
+  }: {
+    client: IMessageSDK;
+    config: Record<string, never>;
+    store: import("@spectrum-ts/core").Store;
+  }, _space: {
+    id: string;
+    type: "dm" | "group";
+    phone: string;
+  } & {
+    id: string;
+    __platform: string;
+  }, messageId: string) => Promise<IMessageMessage | undefined>;
+  getMembers: () => Promise<never>;
+  getAvatar: () => Promise<never>;
+  getDisplayName: () => Promise<never>;
+  getAttachment: () => Promise<Attachment | undefined>;
+}>> & Readonly<{
+  effect: {
+    message: {
+      readonly balloons: "com.apple.messages.effect.CKBalloonEffect";
+      readonly celebration: "com.apple.messages.effect.CKHappyBirthdayEffect";
+      readonly confetti: "com.apple.messages.effect.CKConfettiEffect";
+      readonly echo: "com.apple.messages.effect.CKEchoEffect";
+      readonly fireworks: "com.apple.messages.effect.CKFireworksEffect";
+      readonly gentle: "com.apple.MobileSMS.expressivesend.gentle";
+      readonly heart: "com.apple.messages.effect.CKHeartEffect";
+      readonly invisible: "com.apple.MobileSMS.expressivesend.invisibleink";
+      readonly lasers: "com.apple.messages.effect.CKLasersEffect";
+      readonly loud: "com.apple.MobileSMS.expressivesend.loud";
+      readonly slam: "com.apple.MobileSMS.expressivesend.impact";
+      readonly sparkles: "com.apple.messages.effect.CKSparklesEffect";
+      readonly spotlight: "com.apple.messages.effect.CKSpotlightEffect";
+    };
+  };
+}>;
+//#endregion
+export { type BackgroundInput, type ContactCard, type CustomizedMiniApp, type CustomizedMiniAppInput, type CustomizedMiniAppLayout, type IMessageMessageEffect, background, customizedMiniApp, effect, imessage, nativeContactCard, read };

package/dist/index.js

@@ -0,0 +1,536 @@
+import { IMessageSDK } from "@photon-ai/imessage-kit";
+import { UnsupportedError, appLayoutSchema, definePlatform, fromVCard, read, stream, text, toVCard } from "@spectrum-ts/core";
+import { asAttachment, asContact, asCustom, asReply, asText, buildPhotoAction, messageEffectSchema, photoActionSchema } from "@spectrum-ts/core/authoring";
+import z from "zod";
+import { setTimeout } from "node:timers/promises";
+import { createReadStream } from "node:fs";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { Readable } from "node:stream";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+//#region ../imessage/src/content/background.ts
+/**
+* iMessage-only chat background content. Lives entirely under the iMessage
+* provider — never enters the universal `Content` discriminated union. The
+* framework recognizes it via two generic content-level contracts:
+*
+* 1. `__platform: "iMessage"` — `findUnsupportedPlatformContent` in
+*    `platform/build.ts` reads this tag and warns-and-skips when a different
+*    platform receives it.
+* 2. `__fireAndForget: true` — `dispatchSend`'s fire-and-forget check
+*    treats this as a side-effecting send that returns no message id, the
+*    same way it treats `reaction` / `typing` / `edit`.
+*
+* iMessage's `send` handler narrows back to `Background` via the `isBackground`
+* type guard before dispatching to `chats.setBackground` / `removeBackground`.
+*/
+const backgroundSchema = z.object({
+	type: z.literal("background"),
+	__platform: z.literal("iMessage"),
+	__fireAndForget: z.literal(true),
+	action: photoActionSchema
+});
+const isBackground = (v) => backgroundSchema.safeParse(v).success;
+function background(input, options) {
+	const action = buildPhotoAction(input, options, "background");
+	return { build: async () => backgroundSchema.parse({
+		type: "background",
+		__platform: "iMessage",
+		__fireAndForget: true,
+		action
+	}) };
+}
+//#endregion
+//#region ../imessage/src/content/contact-card.ts
+/**
+* iMessage-only "share contact card" control signal. Pushes the *local
+* account's native contact card* (the name + photo a recipient sees in their
+* Messages app) to a chat via the SDK's `chats.shareContactInfo`.
+*
+* This is Apple's "Share Name and Photo" mechanism — distinct from the
+* universal `contact(...)` content, which uploads an arbitrary person's vCard
+* as a *file* attachment. There is no payload: the card shared is always the
+* bot account's own.
+*
+* Like `background`, it lives entirely under the iMessage provider and never
+* enters the universal `Content` discriminated union. The framework recognizes
+* it via two generic content-level contracts:
+*
+* 1. `__platform: "iMessage"` — `findUnsupportedPlatformContent` in
+*    `platform/build.ts` reads this tag and warns-and-skips when a different
+*    platform receives it.
+* 2. `__fireAndForget: true` — `dispatchSend`'s fire-and-forget check treats
+*    this as a side-effecting send that returns no message id, the same way it
+*    treats `read` / `typing`.
+*
+* iMessage's `send` handler narrows back via the `isContactCard` type guard
+* before dispatching to `chats.shareContactInfo`.
+*/
+const contactCardSchema = z.object({
+	type: z.literal("contactCard"),
+	__platform: z.literal("iMessage"),
+	__fireAndForget: z.literal(true)
+});
+const isContactCard = (v) => contactCardSchema.safeParse(v).success;
+/**
+* Share the bot account's native iMessage contact card (name + photo) with the
+* chat. iMessage-only, remote-only.
+*
+* `space.send(nativeContactCard())` is the canonical form; `space.shareContactCard()`
+* is sugar attached via `PlatformDef.space.actions` (only typed on
+* `PlatformSpace<IMessageDef>`).
+*
+* This is an explicit, on-demand share and always fires — unlike the automatic
+* best-effort share gated behind the `imessageSynced` project profile, which
+* dedupes to once per chat per 24h (see `remote/contact-share.ts`). Works in
+* both DMs and group chats; the recipient chooses whether to accept the card.
+*
+* `ContactCard` is intentionally not a member of the universal `Content`
+* union — the `as unknown as Content` cast keeps the builder shape compatible
+* with the framework's `ContentBuilder.build(): Promise<Content>` signature.
+* The framework treats it as a fire-and-forget control signal at runtime.
+*/
+function nativeContactCard() {
+	return { build: async () => contactCardSchema.parse({
+		type: "contactCard",
+		__platform: "iMessage",
+		__fireAndForget: true
+	}) };
+}
+//#endregion
+//#region ../imessage/src/content/customized-mini-app.ts
+const layoutSchema = appLayoutSchema;
+/**
+* iMessage-only mini-app card content. Lives entirely under the iMessage
+* provider — never enters the universal `Content` discriminated union. The
+* framework recognizes it via the generic content-level platform contract:
+*
+* - `__platform: "iMessage"` — `findUnsupportedPlatformContent` reads this tag
+*   and warns-and-skips when a different platform receives it.
+*
+* Unlike `background` / `read`, this content is **not** `__fireAndForget`: it
+* produces a real outbound message, so the iMessage `send` handler narrows
+* back to `CustomizedMiniApp` via the `isCustomizedMiniApp` guard and returns
+* the resulting `ProviderMessageRecord` (rather than `void`).
+*/
+const customizedMiniAppSchema = z.object({
+	type: z.literal("customized-mini-app"),
+	__platform: z.literal("iMessage"),
+	appName: z.string().nonempty(),
+	appStoreId: z.number().int().positive().optional(),
+	extensionBundleId: z.string().nonempty(),
+	layout: layoutSchema,
+	live: z.boolean().optional(),
+	teamId: z.string(),
+	url: z.url()
+});
+const isCustomizedMiniApp = (v) => customizedMiniAppSchema.safeParse(v).success;
+const asCustomizedMiniApp = (input) => customizedMiniAppSchema.parse({
+	type: "customized-mini-app",
+	__platform: "iMessage",
+	...input
+});
+/**
+* Construct a `customized-mini-app` content value. iMessage-only, remote-only.
+*
+* The layout is what recipients see in the bubble. `teamId` and
+* `extensionBundleId` identify the iMessage extension that receives `url` when
+* the recipient taps the card; the server constructs the matching
+* `MSMessageExtensionBalloonPlugin` plugin id from these values. `appStoreId`
+* is optional and only points recipients without the extension at its App
+* Store entry. `live` is optional; when omitted, the remote server keeps the
+* static layout preview visible.
+*
+* `space.send(customizedMiniApp(...))` is the canonical form.
+*
+* `CustomizedMiniApp` is intentionally not a member of the universal `Content`
+* union — the `as unknown as Content` cast keeps the builder shape compatible
+* with the framework's `ContentBuilder.build(): Promise<Content>` signature.
+*/
+function customizedMiniApp(input) {
+	return { build: async () => asCustomizedMiniApp(input) };
+}
+//#endregion
+//#region ../imessage/src/content/effect.ts
+const messageEffects = {
+	balloons: "com.apple.messages.effect.CKBalloonEffect",
+	celebration: "com.apple.messages.effect.CKHappyBirthdayEffect",
+	confetti: "com.apple.messages.effect.CKConfettiEffect",
+	echo: "com.apple.messages.effect.CKEchoEffect",
+	fireworks: "com.apple.messages.effect.CKFireworksEffect",
+	gentle: "com.apple.MobileSMS.expressivesend.gentle",
+	heart: "com.apple.messages.effect.CKHeartEffect",
+	invisible: "com.apple.MobileSMS.expressivesend.invisibleink",
+	lasers: "com.apple.messages.effect.CKLasersEffect",
+	loud: "com.apple.MobileSMS.expressivesend.loud",
+	slam: "com.apple.MobileSMS.expressivesend.impact",
+	sparkles: "com.apple.messages.effect.CKSparklesEffect",
+	spotlight: "com.apple.messages.effect.CKSpotlightEffect"
+};
+const SUPPORTED_EFFECTS = new Set(Object.values(messageEffects));
+const resolveContent = (input) => typeof input === "string" ? text(input).build() : input.build();
+function effect(input, messageEffect) {
+	return { build: async () => {
+		if (!SUPPORTED_EFFECTS.has(messageEffect)) throw new Error(`Unsupported iMessage message effect "${messageEffect}"`);
+		const inner = await resolveContent(input);
+		if (inner.type !== "text" && inner.type !== "markdown" && inner.type !== "attachment") throw new Error(`imessage effect() only supports text, markdown, and attachment content, got "${inner.type}"`);
+		return messageEffectSchema.parse({
+			type: "effect",
+			content: inner,
+			effect: messageEffect
+		});
+	} };
+}
+//#endregion
+//#region src/ids.ts
+const dmChatGuid = (address) => `any;-;${address}`;
+const chatTypeFromGuid = (guid) => guid.includes(";+;") ? "group" : "dm";
+const addTextPart = (parts, text) => {
+	const trimmed = text?.trim();
+	if (trimmed) parts.push({
+		type: "text",
+		text: trimmed
+	});
+};
+const hasUsableTextPart = (text) => text?.split("").some((segment) => segment.trim()) ?? false;
+const addAttachmentParts = (parts, attachments) => {
+	for (const attachment of attachments) if (attachment) parts.push({
+		type: "attachment",
+		attachment
+	});
+};
+const toOrderedParts = (text, attachments) => {
+	const parts = [];
+	if (!text) {
+		addAttachmentParts(parts, attachments);
+		return parts;
+	}
+	if (!text.includes("")) {
+		addAttachmentParts(parts, attachments);
+		addTextPart(parts, text);
+		return parts;
+	}
+	const textSegments = text.split("");
+	for (let i = 0; i < attachments.length; i++) {
+		addTextPart(parts, textSegments[i]);
+		const attachment = attachments[i];
+		if (attachment) parts.push({
+			type: "attachment",
+			attachment
+		});
+	}
+	addTextPart(parts, textSegments.slice(attachments.length).join(""));
+	return parts;
+};
+//#endregion
+//#region ../imessage/src/shared/vcard.ts
+const VCARD_MIME_TYPES = new Set([
+	"text/vcard",
+	"text/x-vcard",
+	"text/directory",
+	"application/vcard",
+	"application/x-vcard"
+]);
+const normalizeMimeType = (mimeType) => (mimeType.split(";")[0] ?? "").trim().toLowerCase();
+const isVCardAttachment = (mimeType, fileName) => {
+	if (mimeType && VCARD_MIME_TYPES.has(normalizeMimeType(mimeType))) return true;
+	return Boolean(fileName?.toLowerCase().endsWith(".vcf"));
+};
+const vcardFileName = (contact) => {
+	return `${(contact.name?.formatted ?? contact.user?.id ?? "contact").replace(/[^a-zA-Z0-9_\-.]/g, "_")}.vcf`;
+};
+const readLocalAttachment = async (att) => {
+	if (!att.localPath) throw new Error(`iMessage attachment ${att.id} has no local file available on disk`);
+	return readFile(att.localPath);
+};
+const toAttachmentContent = (att) => {
+	const { localPath } = att;
+	return asAttachment({
+		id: att.id,
+		name: att.fileName ?? "attachment",
+		mimeType: att.mimeType,
+		size: att.sizeBytes,
+		read: () => readLocalAttachment(att),
+		stream: localPath ? async () => Readable.toWeb(createReadStream(localPath)) : void 0
+	});
+};
+const toVCardContent = async (att) => {
+	try {
+		return asContact(fromVCard((await readLocalAttachment(att)).toString("utf8")));
+	} catch {
+		return toAttachmentContent(att);
+	}
+};
+const localAttachmentContent = async (att) => isVCardAttachment(att.mimeType, att.fileName) ? await toVCardContent(att) : toAttachmentContent(att);
+//#endregion
+//#region src/local/inbound.ts
+const ATTACHMENT_JOIN_RETRY_DELAY_MS = 250;
+const ATTACHMENT_JOIN_RETRY_LIMIT = 8;
+const ATTACHMENT_JOIN_FETCH_LIMIT = 10;
+const hasAttachmentPlaceholder = (message) => message.text?.includes("") ?? false;
+const isPendingAttachmentJoin = (message) => message.attachments.length === 0 && (message.hasAttachments || hasAttachmentPlaceholder(message));
+const replyTargetId = (message) => message.threadRootMessageId ?? void 0;
+const stubReplyTarget = (space, targetId) => ({
+	id: targetId,
+	content: asCustom({
+		imessage_type: "reply-target",
+		stub: true
+	}),
+	space
+});
+const asProviderReply = (content, target) => asReply({
+	content,
+	target
+});
+const wrapReply = (messages, targetId) => {
+	if (!targetId) return messages;
+	return messages.map((message) => ({
+		...message,
+		content: asProviderReply(message.content, stubReplyTarget(message.space, targetId))
+	}));
+};
+const refetchUntilAttachmentsSettle = async (client, message) => {
+	if (!message.chatId) return message;
+	for (let attempt = 0; attempt < ATTACHMENT_JOIN_RETRY_LIMIT; attempt += 1) {
+		await setTimeout(ATTACHMENT_JOIN_RETRY_DELAY_MS);
+		let rows;
+		try {
+			rows = await client.getMessages({
+				chatId: message.chatId,
+				limit: ATTACHMENT_JOIN_FETCH_LIMIT,
+				since: message.createdAt
+			});
+		} catch {
+			continue;
+		}
+		const refreshed = rows.find((row) => row.id === message.id);
+		if (refreshed && !isPendingAttachmentJoin(refreshed)) return refreshed;
+	}
+	return message;
+};
+const toMessages = async (message) => {
+	const { chatId, chatKind } = message;
+	if (!chatId || chatKind === "unknown") return [];
+	if (message.reaction !== null || message.kind !== "text" || message.retractedAt !== null) return [];
+	if (isPendingAttachmentJoin(message)) return [];
+	const base = {
+		sender: {
+			id: message.participant ?? "",
+			...message.participant ? { address: message.participant } : {}
+		},
+		space: {
+			id: chatId,
+			type: chatKind === "group" ? "group" : "dm",
+			phone: ""
+		},
+		timestamp: message.createdAt
+	};
+	const targetId = replyTargetId(message);
+	if (message.attachments.length > 0) {
+		if (!hasUsableTextPart(message.text)) return wrapReply(await Promise.all(message.attachments.map(async (att) => ({
+			...base,
+			id: `${message.id}:${att.id}`,
+			content: await localAttachmentContent(att)
+		}))), targetId);
+		const parts = toOrderedParts(message.text, message.attachments);
+		const messages = [];
+		for (let i = 0; i < parts.length; i++) {
+			const part = parts[i];
+			if (!part) continue;
+			messages.push(part.type === "text" ? {
+				...base,
+				id: `${message.id}:text:${i}`,
+				content: asText(part.text),
+				partIndex: i
+			} : {
+				...base,
+				id: `${message.id}:${part.attachment.id}`,
+				content: await localAttachmentContent(part.attachment),
+				partIndex: i
+			});
+		}
+		return wrapReply(messages, targetId);
+	}
+	return wrapReply([{
+		...base,
+		id: message.id,
+		content: {
+			type: "text",
+			text: message.text ?? ""
+		}
+	}], targetId);
+};
+const messages$1 = (client) => stream((emit, end) => {
+	let lastPromise = Promise.resolve();
+	const handleIncoming = async (message) => {
+		const ms = await toMessages(isPendingAttachmentJoin(message) ? await refetchUntilAttachmentsSettle(client, message) : message);
+		for (const m of ms) await emit(m);
+	};
+	const startPromise = client.startWatching({
+		onIncomingMessage: (message) => {
+			lastPromise = lastPromise.then(() => handleIncoming(message)).catch(end);
+		},
+		onError: end
+	}).catch(end);
+	return async () => {
+		await startPromise.catch(() => {});
+		await client.stopWatching();
+		await lastPromise.catch(() => {});
+	};
+});
+//#endregion
+//#region ../imessage/src/shared/errors.ts
+const LOCAL_IMESSAGE_PLATFORM = "iMessage (local mode)";
+const unsupportedLocalContent = (type, detail) => UnsupportedError.content(type, LOCAL_IMESSAGE_PLATFORM, detail);
+//#endregion
+//#region src/local/send.ts
+const synthRecord = (spaceId, content) => ({
+	id: crypto.randomUUID(),
+	content,
+	space: { id: spaceId },
+	timestamp: /* @__PURE__ */ new Date()
+});
+const sendTempFile = async (client, spaceId, name, data) => {
+	const safeName = basename(name) || "attachment";
+	const dir = await mkdtemp(join(tmpdir(), "spectrum-"));
+	const tmp = join(dir, safeName);
+	await writeFile(tmp, data);
+	try {
+		await client.send({
+			to: spaceId,
+			attachments: [tmp]
+		});
+	} finally {
+		await rm(dir, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+	}
+};
+const send$1 = async (client, spaceId, content) => {
+	switch (content.type) {
+		case "text":
+			await client.send({
+				to: spaceId,
+				text: content.text
+			});
+			return synthRecord(spaceId, content);
+		case "attachment":
+			await sendTempFile(client, spaceId, content.name, await content.read());
+			return synthRecord(spaceId, content);
+		case "contact": {
+			const vcf = await toVCard(content);
+			await sendTempFile(client, spaceId, vcardFileName(content), Buffer.from(vcf, "utf8"));
+			return synthRecord(spaceId, content);
+		}
+		case "effect": throw unsupportedLocalContent("effect", "message effects require remote iMessage");
+		case "poll": throw unsupportedLocalContent("poll");
+		default: throw unsupportedLocalContent(content.type);
+	}
+};
+const getMessage$1 = async (_client, _id) => void 0;
+//#endregion
+//#region src/local/api.ts
+const messages = (client) => messages$1(client);
+const send = (client, spaceId, content) => send$1(client, spaceId, content);
+const getMessage = (client, id) => getMessage$1(client, id);
+//#endregion
+//#region src/types.ts
+const configSchema = z.object({});
+const userSchema = z.object({
+	address: z.string().optional(),
+	country: z.string().optional(),
+	service: z.enum([
+		"iMessage",
+		"SMS",
+		"RCS",
+		"unknown"
+	]).optional()
+});
+const spaceSchema = z.object({
+	id: z.string(),
+	type: z.enum(["dm", "group"]),
+	phone: z.string()
+});
+const spaceParamsSchema = z.object({});
+const messageSchema = z.object({
+	partIndex: z.number().int().nonnegative().optional(),
+	parentId: z.string().optional()
+});
+//#endregion
+//#region src/index.ts
+const LOCAL_PLATFORM = "iMessage (local mode)";
+const unsupportedAction = (action, detail) => {
+	throw UnsupportedError.action(action, LOCAL_PLATFORM, detail);
+};
+const handleLocalOnlySend = async (client, spaceId, content) => {
+	if (content.type === "typing") return;
+	if (content.type === "app") return await send(client, spaceId, await text(await content.url()).build());
+	if (content.type === "edit") return unsupportedAction("edit");
+	if (content.type === "unsend") return unsupportedAction("unsend");
+	if (content.type === "streamText") return unsupportedAction("streamText", "streaming text responses require remote iMessage");
+	if (content.type === "rename") return unsupportedAction("rename", "renaming chats requires remote iMessage");
+	if (content.type === "avatar") return unsupportedAction("avatar", "setting group avatars requires remote iMessage");
+	if (content.type === "addMember") return unsupportedAction("addMember", "adding members requires remote iMessage");
+	if (content.type === "removeMember") return unsupportedAction("removeMember", "removing members requires remote iMessage");
+	if (content.type === "leaveSpace") return unsupportedAction("leaveSpace", "leaving chats requires remote iMessage");
+	if (content.type === "read") return unsupportedAction("read", "marking chats as read requires remote iMessage");
+	if (content.type === "reply") return unsupportedAction("reply");
+	if (content.type === "reaction") return unsupportedAction("react");
+	if (isBackground(content)) return unsupportedAction("background", "chat backgrounds require remote iMessage");
+	if (isContactCard(content)) return unsupportedAction("shareContactCard", "sharing the contact card requires remote iMessage");
+	if (isCustomizedMiniApp(content)) return unsupportedAction("customized-mini-app", "mini app cards require remote iMessage");
+	return await send(client, spaceId, content);
+};
+const imessage = definePlatform("iMessage", {
+	config: configSchema,
+	static: { effect: { message: messageEffects } },
+	lifecycle: {
+		createClient: async () => new IMessageSDK(),
+		destroyClient: async ({ client }) => {
+			await client.close();
+		}
+	},
+	user: {
+		schema: userSchema,
+		resolve: async ({ input }) => ({ id: input.userID })
+	},
+	space: {
+		schema: spaceSchema,
+		params: spaceParamsSchema,
+		create: async ({ input }) => {
+			if (input.users.length === 0) throw new Error("iMessage space creation requires at least one user");
+			if (input.users.length > 1) return unsupportedAction("space.create", "local mode cannot create group chats — use space.get(chatGuid) for an existing group");
+			return {
+				id: dmChatGuid(input.users[0]?.id ?? ""),
+				type: "dm",
+				phone: ""
+			};
+		},
+		get: async ({ input }) => ({
+			id: input.id,
+			type: chatTypeFromGuid(input.id),
+			phone: ""
+		}),
+		actions: {
+			background: async (space, input, options) => {
+				await space.send(background(input, options));
+			},
+			shareContactCard: async (space) => {
+				await space.send(nativeContactCard());
+			}
+		}
+	},
+	message: { schema: messageSchema },
+	messages: ({ client }) => messages(client),
+	send: async ({ space, content, client }) => handleLocalOnlySend(client, space.id, content),
+	actions: {
+		getMessage: async ({ client }, _space, messageId) => getMessage(client, messageId),
+		getMembers: async () => unsupportedAction("getMembers", "listing members requires remote iMessage"),
+		getAvatar: async () => unsupportedAction("getAvatar", "fetching group avatars requires remote iMessage"),
+		getDisplayName: async () => unsupportedAction("getDisplayName", "reading chat display names requires remote iMessage"),
+		getAttachment: async () => unsupportedAction("getAttachment", "fetching attachments by GUID requires remote iMessage")
+	}
+});
+//#endregion
+export { background, customizedMiniApp, effect, imessage, nativeContactCard, read };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@spectrum-ts/imessage-local",
+  "version": "10.0.0",
+  "description": "Local macOS iMessage provider for spectrum-ts.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/photon-hq/spectrum-ts.git",
+    "directory": "packages/imessage-local"
+  },
+  "homepage": "https://photon.codes/spectrum",
+  "bugs": {
+    "url": "https://github.com/photon-hq/spectrum-ts/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@photon-ai/imessage-kit": "^3.0.0",
+    "zod": "^4.2.1"
+  },
+  "peerDependencies": {
+    "@spectrum-ts/core": "^10.0.0",
+    "typescript": "^5 || ^6.0.0"
+  },
+  "license": "MIT"
+}