@spectrum-ts/imessage 5.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,34 @@
+# @spectrum-ts/imessage
+
+iMessage provider for [spectrum-ts](https://github.com/photon-hq/spectrum-ts), supporting local (imessage-kit) and remote (advanced-imessage) modes — including tapbacks, special effects, polls, and mini-apps.
+
+## Install
+
+```sh
+bun add spectrum-ts @spectrum-ts/imessage
+```
+
+## Use
+
+```ts
+import { Spectrum } from "spectrum-ts";
+import { imessage } from "@spectrum-ts/imessage";
+
+const spectrum = Spectrum({
+  providers: [imessage.config({ /* ... */ })],
+});
+```
+
+This package also exports the iMessage-specific content helpers `effect`, `read`, `background`, `customizedMiniApp`, and `nativeContactCard`.
+
+`nativeContactCard()` shares the bot account's own contact card (Apple's "Share Name and Photo") with a chat — remote mode only:
+
+```ts
+import { nativeContactCard } from "@spectrum-ts/imessage";
+
+await space.send(nativeContactCard());
+// or the sugar form, typed on the iMessage space:
+await space.shareContactCard();
+```
+
+See the [spectrum-ts documentation](https://photon.codes/spectrum) for the full guide.

package/dist/index.d.ts

@@ -0,0 +1,269 @@
+import { AdvancedIMessage, 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/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 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 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>;
+  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.
+ *
+ * `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 src/content/effect.d.ts
+type IMessageMessageEffect = MessageEffect;
+declare function effect(input: ContentInput, messageEffect: IMessageMessageEffect): ContentBuilder;
+//#endregion
+//#region src/types.d.ts
+interface RemoteClient {
+  client: AdvancedIMessage;
+  phone: string;
+}
+type IMessageClient = IMessageSDK | RemoteClient[];
+declare const userSchema: z.ZodObject<{}, 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 src/index.d.ts
+declare const imessage: import("@spectrum-ts/core").Platform<import("@spectrum-ts/core").PlatformDef<"iMessage", import("zod").ZodUnion<readonly [import("zod").ZodObject<{
+  local: import("zod").ZodLiteral<true>;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+  local: import("zod").ZodDefault<import("zod").ZodOptional<import("zod").ZodLiteral<false>>>;
+  clients: import("zod").ZodOptional<import("zod").ZodUnion<[import("zod").ZodObject<{
+    address: import("zod").ZodString;
+    token: import("zod").ZodString;
+    phone: import("zod").ZodString;
+  }, import("zod/v4/core").$strip>, import("zod").ZodArray<import("zod").ZodObject<{
+    address: import("zod").ZodString;
+    token: import("zod").ZodString;
+    phone: import("zod").ZodString;
+  }, import("zod/v4/core").$strip>>]>>;
+}, import("zod/v4/core").$strip>]>, import("zod").ZodType<object, unknown, import("zod/v4/core").$ZodTypeInternals<object, unknown>> | undefined, 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<{
+  phone: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>, IMessageClient, {
+  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, opts?: {
+    mimeType?: string;
+  }) => Promise<void>;
+  shareContactCard: (space: Space) => Promise<void>;
+}, Record<never, never>, {
+  getMessage: ({
+    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;
+  }, messageId: string) => Promise<IMessageMessage | undefined>;
+  getAttachment: ({
+    client
+  }: {
+    client: IMessageClient;
+  }, guid: string, phone?: string) => Promise<Attachment | undefined>;
+}>> & Readonly<{
+  effect: {
+    message: {
+      readonly slam: "com.apple.MobileSMS.expressivesend.impact";
+      readonly loud: "com.apple.MobileSMS.expressivesend.loud";
+      readonly gentle: "com.apple.MobileSMS.expressivesend.gentle";
+      readonly invisible: "com.apple.MobileSMS.expressivesend.invisibleink";
+      readonly confetti: "com.apple.messages.effect.CKConfettiEffect";
+      readonly fireworks: "com.apple.messages.effect.CKFireworksEffect";
+      readonly balloons: "com.apple.messages.effect.CKBalloonEffect";
+      readonly heart: "com.apple.messages.effect.CKHeartEffect";
+      readonly lasers: "com.apple.messages.effect.CKLasersEffect";
+      readonly celebration: "com.apple.messages.effect.CKHappyBirthdayEffect";
+      readonly sparkles: "com.apple.messages.effect.CKSparklesEffect";
+      readonly spotlight: "com.apple.messages.effect.CKSpotlightEffect";
+      readonly echo: "com.apple.messages.effect.CKEchoEffect";
+    };
+  };
+}>;
+//#endregion
+export { type BackgroundInput, type ContactCard, type CustomizedMiniApp, type CustomizedMiniAppInput, type CustomizedMiniAppLayout, type IMessageMessageEffect, background, customizedMiniApp, effect, imessage, nativeContactCard, read };