spectrum-ts 0.9.0 → 0.9.1

package/dist/{chunk-6ZOLTQDN.js → chunk-HU2EOF3K.js}

@@ -2,10 +2,38 @@ import {
   bufferToStream,
   readSchema,
   streamSchema
-} from "./chunk-CZIWNTXP.js";
+} from "./chunk-OIXH5S65.js";
+import {
+  resolveContents
+} from "./chunk-U6WCQVVX.js";
 
-// src/content/richlink.ts
+// src/content/group.ts
 import z from "zod";
+var isMessage = (v) => typeof v === "object" && v !== null && "id" in v && "content" in v;
+var groupSchema = z.object({
+  type: z.literal("group"),
+  items: z.array(z.custom(isMessage)).min(2)
+});
+var asGroup = (input) => groupSchema.parse({ type: "group", items: input.items });
+var stubOutboundMessage = (content) => ({ id: "", content });
+function group(...items) {
+  return {
+    build: async () => {
+      const resolved = await resolveContents(items);
+      const members = [];
+      for (const item of resolved) {
+        if (item.type === "group" || item.type === "reaction") {
+          throw new Error(`group() cannot contain "${item.type}" items`);
+        }
+        members.push(stubOutboundMessage(item));
+      }
+      return asGroup({ items: members });
+    }
+  };
+}
+
+// src/content/richlink.ts
+import z2 from "zod";
 
 // src/utils/link-metadata.ts
 import ogs from "open-graph-scraper";
@@ -76,22 +104,22 @@ var fetchImage = async (url) => {
 };
 
 // src/content/richlink.ts
-var richlinkCoverSchema = z.object({
-  mimeType: z.string().min(1).optional(),
+var richlinkCoverSchema = z2.object({
+  mimeType: z2.string().min(1).optional(),
   read: readSchema,
   stream: streamSchema
 });
-var optionalStringAccessor = z.function({
+var optionalStringAccessor = z2.function({
   input: [],
-  output: z.promise(z.string().min(1).optional())
+  output: z2.promise(z2.string().min(1).optional())
 });
-var coverAccessor = z.function({
+var coverAccessor = z2.function({
   input: [],
-  output: z.promise(richlinkCoverSchema.optional())
+  output: z2.promise(richlinkCoverSchema.optional())
 });
-var richlinkSchema = z.object({
-  type: z.literal("richlink"),
-  url: z.url(),
+var richlinkSchema = z2.object({
+  type: z2.literal("richlink"),
+  url: z2.url(),
   title: optionalStringAccessor,
   summary: optionalStringAccessor,
   cover: coverAccessor
@@ -136,6 +164,8 @@ function richlink(url) {
 }
 
 export {
+  asGroup,
+  group,
   asRichlink,
   richlink
 };

package/dist/{chunk-CZIWNTXP.js → chunk-OIXH5S65.js}

@@ -555,15 +555,17 @@ function custom(raw) {
 
 // src/content/reaction.ts
 import z5 from "zod";
+var isMessage = (v) => typeof v === "object" && v !== null && "id" in v && "content" in v;
 var reactionSchema = z5.object({
   type: z5.literal("reaction"),
   emoji: z5.string().min(1),
-  target: z5.string().min(1)
+  target: z5.custom(isMessage, {
+    message: "reaction target must be a Message"
+  })
 });
 var asReaction = (input) => reactionSchema.parse({ type: "reaction", ...input });
 function reaction(emoji, target) {
-  const targetId = typeof target === "string" ? target : target.id;
-  return { build: async () => asReaction({ emoji, target: targetId }) };
+  return { build: async () => asReaction({ emoji, target }) };
 }
 
 // src/utils/stream.ts

package/dist/{chunk-PLJI5FTO.js → chunk-U6WCQVVX.js}

@@ -88,6 +88,63 @@ var warnUnsupported = (err, fallbackPlatform) => {
     supportsAnsiColor() ? `${ANSI_YELLOW}${body}${ANSI_RESET}` : body
   );
 };
+var providerMessageCoreKeys = /* @__PURE__ */ new Set([
+  "content",
+  "id",
+  "sender",
+  "space",
+  "timestamp"
+]);
+var extractExtras = (raw, definition) => {
+  const entries = Object.entries(raw).filter(
+    ([key]) => !providerMessageCoreKeys.has(key)
+  );
+  const extra = Object.fromEntries(entries);
+  return definition.message?.schema ? definition.message.schema.parse(extra) : extra;
+};
+function wrapProviderMessage(raw, ctx) {
+  const wrappedContent = wrapNestedContent(raw.content, ctx);
+  return buildMessage({
+    id: raw.id,
+    content: wrappedContent,
+    sender: raw.sender,
+    timestamp: raw.timestamp ?? /* @__PURE__ */ new Date(),
+    extras: extractExtras(raw, ctx.definition),
+    spaceRef: ctx.spaceRef,
+    space: ctx.space,
+    definition: ctx.definition,
+    client: ctx.client,
+    config: ctx.config,
+    direction: "inbound"
+  });
+}
+var wrapNestedContent = (content, ctx) => {
+  if (content.type === "reaction") {
+    const target = content.target;
+    if (isRawProviderRecord(target)) {
+      return {
+        ...content,
+        target: wrapProviderMessage(target, ctx)
+      };
+    }
+    return content;
+  }
+  if (content.type === "group") {
+    const items = content.items.map((item) => {
+      const raw = item;
+      return isRawProviderRecord(raw) ? wrapProviderMessage(raw, ctx) : item;
+    });
+    return { ...content, items };
+  }
+  return content;
+};
+var isRawProviderRecord = (v) => {
+  if (typeof v !== "object" || v === null) {
+    return false;
+  }
+  const record = v;
+  return "id" in record && "content" in record && typeof record.react !== "function" && typeof record.reply !== "function";
+};
 function buildSpace(params) {
   const { spaceRef, extras, typingCtx, definition, client, config } = params;
   let space;
@@ -98,7 +155,7 @@ function buildSpace(params) {
       }
       await definition.actions.reactToMessage({
         space: spaceRef,
-        messageId: item.target,
+        target: item.target,
         reaction: item.emoji,
         client,
         config
@@ -130,9 +187,31 @@ function buildSpace(params) {
         `Platform "${definition.name}" send did not return a message id`
       );
     }
+    const outboundContent = item.type === "group" && sendResult.groupMembers ? {
+      ...item,
+      items: item.items.map((stub, idx) => {
+        const member = sendResult?.groupMembers?.[idx];
+        if (!member?.id) {
+          return stub;
+        }
+        return buildMessage({
+          id: member.id,
+          content: stub.content,
+          sender: member.sender,
+          timestamp: member.timestamp ?? /* @__PURE__ */ new Date(),
+          extras: {},
+          spaceRef,
+          space,
+          definition,
+          client,
+          config,
+          direction: "outbound"
+        });
+      })
+    } : item;
     return buildMessage({
       id: sendResult.id,
-      content: item,
+      content: outboundContent,
       sender: sendResult.sender,
       timestamp: sendResult.timestamp ?? /* @__PURE__ */ new Date(),
       extras: {},
@@ -162,6 +241,40 @@ function buildSpace(params) {
     }
     return results;
   }
+  async function getMessageImpl(id) {
+    if (!definition.actions.getMessage) {
+      warnUnsupported(
+        UnsupportedError.action("getMessage", definition.name),
+        definition.name
+      );
+      return;
+    }
+    let raw;
+    try {
+      raw = await definition.actions.getMessage({
+        space: spaceRef,
+        messageId: id,
+        client,
+        config
+      });
+    } catch (err) {
+      if (err instanceof UnsupportedError) {
+        warnUnsupported(err, definition.name);
+        return;
+      }
+      throw err;
+    }
+    if (!raw) {
+      return;
+    }
+    return wrapProviderMessage(raw, {
+      client,
+      config,
+      definition,
+      space,
+      spaceRef
+    });
+  }
   space = {
     ...extras,
     ...spaceRef,
@@ -169,6 +282,7 @@ function buildSpace(params) {
     edit: async (message, newContent) => {
       await message.edit(newContent);
     },
+    getMessage: getMessageImpl,
     startTyping: async () => {
       await definition.actions.startTyping?.(typingCtx);
     },
@@ -189,6 +303,7 @@ function buildSpace(params) {
 }
 function buildMessage(params) {
   const { definition, client, config, spaceRef, space } = params;
+  let self;
   const react = async (reaction) => {
     if (!definition.actions.reactToMessage) {
       warnUnsupported(
@@ -197,10 +312,15 @@ function buildMessage(params) {
       );
       return;
     }
+    if (!self) {
+      throw new Error(
+        "react() called before message construction completed (internal bug)"
+      );
+    }
     try {
       await definition.actions.reactToMessage({
         space: spaceRef,
-        messageId: params.id,
+        target: self,
         reaction,
         client,
         config
@@ -268,7 +388,7 @@ function buildMessage(params) {
   }
   const senderWithPlatform = params.sender === void 0 ? void 0 : { ...params.sender, __platform: definition.name };
   if (params.direction === "outbound") {
-    return {
+    const outbound = {
       ...params.extras,
       id: params.id,
       content: params.content,
@@ -308,8 +428,10 @@ function buildMessage(params) {
       space,
       timestamp: params.timestamp
     };
+    self = outbound;
+    return outbound;
   }
-  return {
+  const inbound = {
     ...params.extras,
     id: params.id,
     content: params.content,
@@ -321,6 +443,8 @@ function buildMessage(params) {
     space,
     timestamp: params.timestamp
   };
+  self = inbound;
+  return inbound;
 }
 
 // src/platform/define.ts
@@ -507,7 +631,7 @@ export {
   text,
   resolveContents,
   UnsupportedError,
+  wrapProviderMessage,
   buildSpace,
-  buildMessage,
   definePlatform
 };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as ContentBuilder, U as User, M as Message, a as ContentInput, b as Content, P as ProviderMessage, c as PlatformDef, d as Platform, e as PlatformProviderConfig, S as SpectrumLike, f as CustomEventStreams, g as Space, I as InboundMessage, O as OutboundMessage } from './types-B8g0pvfg.js';
-export { A as AnyPlatformDef, E as EventProducer, h as PlatformInstance, i as PlatformMessage, j as PlatformSpace, k as PlatformUser, l as SchemaMessage } from './types-B8g0pvfg.js';
+import { C as ContentBuilder, U as User, M as Message, a as ContentInput, b as Content, P as ProviderMessage, c as PlatformDef, d as Platform, e as PlatformProviderConfig, S as SpectrumLike, f as CustomEventStreams, g as Space, I as InboundMessage, O as OutboundMessage } from './types-D5KhSXLy.js';
+export { A as AnyPlatformDef, E as EventProducer, h as PlatformInstance, i as PlatformMessage, j as PlatformSpace, k as PlatformUser, l as SchemaMessage } from './types-D5KhSXLy.js';
 import vCard from 'vcf';
 import z__default from 'zod';
 export { M as ManagedStream, m as mergeStreams, s as stream } from './stream-B55k7W8-.js';
@@ -122,21 +122,39 @@ declare function contact(input: string | ContactInput | vCard): ContentBuilder;
 
 declare function custom(raw: unknown): ContentBuilder;
 
+/**
+ * A `group` bundles multiple messages into one logical unit (e.g. an album
+ * of images sent together). Each item is a full `Message` — addressable by
+ * id, reactable via `.react()`, replyable via `.reply()`.
+ *
+ * Groups do not nest, and reactions cannot be group members. Enforced by the
+ * `group()` builder; platforms may additionally reject unsupported item
+ * content types at send time.
+ */
+declare const groupSchema: z__default.ZodObject<{
+    type: z__default.ZodLiteral<"group">;
+    items: z__default.ZodArray<z__default.ZodCustom<Message, Message>>;
+}, z__default.core.$strip>;
+type Group = z__default.infer<typeof groupSchema>;
+declare function group(...items: [ContentInput, ContentInput, ...ContentInput[]]): ContentBuilder;
+
 declare const reactionSchema: z__default.ZodObject<{
     type: z__default.ZodLiteral<"reaction">;
     emoji: z__default.ZodString;
-    target: z__default.ZodString;
+    target: z__default.ZodCustom<Message, Message>;
 }, z__default.core.$strip>;
 type Reaction = z__default.infer<typeof reactionSchema>;
 /**
- * Construct a `reaction` content value. Passing a `Message` extracts its id;
- * a string is treated as the target message id directly.
+ * Construct a `reaction` content value targeting the given message.
  *
  * `space.send(reaction(emoji, message))` is sugar for `message.react(emoji)`.
  * Reactions are fire-and-forget — the returned `OutboundMessage` will be
  * `undefined` because platforms do not surface a message id for reactions.
+ *
+ * To react to a message known only by id, resolve it first via
+ * `space.getMessage(id)`.
  */
-declare function reaction(emoji: string, target: Message | string): ContentBuilder;
+declare function reaction(emoji: string, target: Message): ContentBuilder;
 
 declare const resolveContents: (items: readonly ContentInput[]) => Promise<Content[]>;
 
@@ -2122,14 +2140,32 @@ type SpectrumInstance<Providers extends PlatformProviderConfig[] = PlatformProvi
     edit(message: OutboundMessage, newContent: ContentInput): Promise<void>;
     responding<T>(space: Space, fn: () => T | Promise<T>): Promise<T>;
 };
+/**
+ * Runtime behavior tweaks for a Spectrum instance.
+ */
+interface SpectrumOptions {
+    /**
+     * When `true`, inbound `group` messages are never delivered whole. Instead,
+     * each group item is yielded from `spectrum.messages` as its own
+     * `[space, message]` tuple, in order. Items retain their individual
+     * `id`, `sender`, `timestamp`, and `.react()` / `.reply()` methods.
+     *
+     * Does not affect outbound `group(...)` sends or `space.getMessage(id)`.
+     *
+     * @default false
+     */
+    flattenGroups?: boolean;
+}
 declare function Spectrum<const Providers extends PlatformProviderConfig[]>(options: {
     projectId: string;
     projectSecret: string;
     providers: [...Providers];
+    options?: SpectrumOptions;
 } | {
     projectId?: never;
     projectSecret?: never;
     providers: [...Providers];
+    options?: SpectrumOptions;
 }): Promise<SpectrumInstance<Providers>>;
 
 type SubscriptionStatus = "active" | "canceled" | "past_due";
@@ -2198,4 +2234,4 @@ declare class UnsupportedError extends Error {
 declare const fromVCard: (vcf: string) => ContactInput;
 declare const toVCard: (contact: Contact) => Promise<string>;
 
-export { type CloudPlatform, type Contact, type ContactAddress, type ContactDetails, type ContactEmail, type ContactInput, type ContactName, type ContactOrg, type ContactPhone, Content, ContentBuilder, ContentInput, type DedicatedTokenData, Emoji, type EmojiKey, type ImessageInfoData, Message, Platform, PlatformDef, PlatformProviderConfig, type PlatformStatus, type PlatformsData, type Reaction, type Richlink, type SharedTokenData, Space, Spectrum, SpectrumCloudError, type SpectrumInstance, type SubscriptionData, type SubscriptionStatus, type TokenData, UnsupportedError, type UnsupportedKind, User, type Voice, attachment, cloud, contact, custom, definePlatform, fromVCard, reaction, resolveContents, richlink, text, toVCard, voice };
+export { type CloudPlatform, type Contact, type ContactAddress, type ContactDetails, type ContactEmail, type ContactInput, type ContactName, type ContactOrg, type ContactPhone, Content, ContentBuilder, ContentInput, type DedicatedTokenData, Emoji, type EmojiKey, type Group, type ImessageInfoData, Message, Platform, PlatformDef, PlatformProviderConfig, type PlatformStatus, type PlatformsData, type Reaction, type Richlink, type SharedTokenData, Space, Spectrum, SpectrumCloudError, type SpectrumInstance, type SubscriptionData, type SubscriptionStatus, type TokenData, UnsupportedError, type UnsupportedKind, User, type Voice, attachment, cloud, contact, custom, definePlatform, fromVCard, group, reaction, resolveContents, richlink, text, toVCard, voice };

package/dist/index.js

@@ -1,6 +1,7 @@
 import {
+  group,
   richlink
-} from "./chunk-6ZOLTQDN.js";
+} from "./chunk-HU2EOF3K.js";
 import {
   SpectrumCloudError,
   attachment,
@@ -15,15 +16,15 @@ import {
   stream,
   streamSchema,
   toVCard
-} from "./chunk-CZIWNTXP.js";
+} from "./chunk-OIXH5S65.js";
 import {
   UnsupportedError,
-  buildMessage,
   buildSpace,
   definePlatform,
   resolveContents,
-  text
-} from "./chunk-PLJI5FTO.js";
+  text,
+  wrapProviderMessage
+} from "./chunk-U6WCQVVX.js";
 
 // src/content/voice.ts
 import { createReadStream } from "fs";
@@ -2063,28 +2064,32 @@ var Emoji = { ...GeneratedEmoji, ...aliases };
 
 // src/spectrum.ts
 import z2 from "zod";
-var providerMessageCoreKeys = /* @__PURE__ */ new Set([
-  "content",
-  "id",
-  "sender",
-  "space",
-  "timestamp"
-]);
+var spectrumOptionsSchema = z2.object({
+  flattenGroups: z2.boolean().optional()
+}).optional();
 var spectrumConfigSchema = z2.union([
   z2.object({
     projectId: z2.string().min(1),
     projectSecret: z2.string().min(1),
-    providers: z2.array(z2.custom())
+    providers: z2.array(z2.custom()),
+    options: spectrumOptionsSchema
   }),
   z2.object({
     projectId: z2.undefined().optional(),
     projectSecret: z2.undefined().optional(),
-    providers: z2.array(z2.custom())
+    providers: z2.array(z2.custom()),
+    options: spectrumOptionsSchema
   })
 ]);
 async function Spectrum(options) {
   spectrumConfigSchema.parse(options);
-  const { projectId, projectSecret, providers } = options;
+  const {
+    projectId,
+    projectSecret,
+    providers,
+    options: runtimeOptions
+  } = options;
+  const flattenGroups = runtimeOptions?.flattenGroups ?? false;
   const platformStates = /* @__PURE__ */ new Map();
   const customEventStreams = /* @__PURE__ */ new Map();
   let stopped = false;
@@ -2132,11 +2137,6 @@ async function Spectrum(options) {
     });
     const bindSend = async function* () {
       for await (const msg of raw) {
-        const extraEntries = Object.entries(msg).filter(
-          ([key]) => !providerMessageCoreKeys.has(key)
-        );
-        const extra = Object.fromEntries(extraEntries);
-        const parsedExtra = definition.message?.schema ? definition.message.schema.parse(extra) : {};
         const spaceRef = {
           ...msg.space,
           __platform: definition.name
@@ -2150,19 +2150,19 @@ async function Spectrum(options) {
           client,
           config
         });
-        const normalizedMessage = buildMessage({
-          id: msg.id,
-          content: msg.content,
-          sender: msg.sender,
-          timestamp: msg.timestamp ?? /* @__PURE__ */ new Date(),
-          extras: parsedExtra,
-          spaceRef,
-          space,
-          definition,
+        const normalizedMessage = wrapProviderMessage(msg, {
           client,
           config,
-          direction: "inbound"
+          definition,
+          space,
+          spaceRef
         });
+        if (flattenGroups && normalizedMessage.content.type === "group") {
+          for (const item of normalizedMessage.content.items) {
+            yield [space, item];
+          }
+          continue;
+        }
         yield [space, normalizedMessage];
       }
     };
@@ -2310,6 +2310,7 @@ export {
   custom,
   definePlatform,
   fromVCard,
+  group,
   mergeStreams,
   reaction,
   resolveContents,

package/dist/providers/imessage/index.d.ts

@@ -1,10 +1,10 @@
 import { M as ManagedStream } from '../../stream-B55k7W8-.js';
-import { AdvancedIMessage } from '@photon-ai/advanced-imessage';
-import { IMessageSDK } from '@photon-ai/imessage-kit';
+import { l as SchemaMessage, d as Platform, c as PlatformDef, P as ProviderMessage } from '../../types-D5KhSXLy.js';
+import * as zod_v4_core from 'zod/v4/core';
 import * as z from 'zod';
 import z__default from 'zod';
-import { l as SchemaMessage, d as Platform, c as PlatformDef, P as ProviderMessage } from '../../types-B8g0pvfg.js';
-import * as zod_v4_core from 'zod/v4/core';
+import { AdvancedIMessage } from '@photon-ai/advanced-imessage';
+import { IMessageSDK } from '@photon-ai/imessage-kit';
 import 'hotscript';
 
 type IMessageClient = IMessageSDK | AdvancedIMessage[];
@@ -16,7 +16,10 @@ declare const spaceSchema: z__default.ZodObject<{
         group: "group";
     }>;
 }, z__default.core.$strip>;
-type IMessageMessage = SchemaMessage<typeof userSchema, typeof spaceSchema>;
+type IMessageMessage = SchemaMessage<typeof userSchema, typeof spaceSchema> & {
+    partIndex?: number;
+    parentId?: string;
+};
 
 declare const imessage: Platform<PlatformDef<"iMessage", z.ZodUnion<readonly [z.ZodObject<{
     local: z.ZodLiteral<true>;
@@ -43,7 +46,10 @@ declare const imessage: Platform<PlatformDef<"iMessage", z.ZodUnion<readonly [z.
 } | {
     id: string;
     type: "group";
-}, undefined, ProviderMessage<{
+}, z.ZodObject<{
+    partIndex: z.ZodOptional<z.ZodNumber>;
+    parentId: z.ZodOptional<z.ZodString>;
+}, zod_v4_core.$strip>, ProviderMessage<{
     id: string;
 }, {
     id: string;
@@ -51,7 +57,10 @@ declare const imessage: Platform<PlatformDef<"iMessage", z.ZodUnion<readonly [z.
 } | {
     id: string;
     type: "group";
-}, Record<never, never>>, {
+}, {
+    partIndex?: number | undefined;
+    parentId?: string | undefined;
+}>, {
     messages: ({ client }: {
         client: IMessageClient;
         config: {

package/dist/providers/imessage/index.js

@@ -1,6 +1,7 @@
 import {
+  asGroup,
   asRichlink
-} from "../../chunk-6ZOLTQDN.js";
+} from "../../chunk-HU2EOF3K.js";
 import {
   asAttachment,
   asContact,
@@ -11,12 +12,12 @@ import {
   mergeStreams,
   stream,
   toVCard
-} from "../../chunk-CZIWNTXP.js";
+} from "../../chunk-OIXH5S65.js";
 import {
   UnsupportedError,
   asText,
   definePlatform
-} from "../../chunk-PLJI5FTO.js";
+} from "../../chunk-U6WCQVVX.js";
 
 // src/providers/imessage/index.ts
 import { createClient as createClient2, directChat } from "@photon-ai/advanced-imessage";
@@ -249,6 +250,7 @@ var send = async (client, spaceId, content) => {
       throw UnsupportedError.content(content.type, "iMessage (local mode)");
   }
 };
+var getMessage = async (_client, _id) => void 0;
 
 // src/providers/imessage/remote.ts
 import {
@@ -380,10 +382,52 @@ var ensureM4a = async (buffer, mimeType) => {
   return transcodeToM4a(buffer);
 };
 
+// src/providers/imessage/cache.ts
+var DEFAULT_MAX = 1e3;
+var MessageCache = class {
+  map = /* @__PURE__ */ new Map();
+  max;
+  constructor(max = DEFAULT_MAX) {
+    this.max = max;
+  }
+  get(id) {
+    return this.map.get(id);
+  }
+  set(id, message) {
+    if (this.map.has(id)) {
+      this.map.delete(id);
+    }
+    this.map.set(id, message);
+    if (this.map.size > this.max) {
+      const first = this.map.keys().next().value;
+      if (first !== void 0) {
+        this.map.delete(first);
+      }
+    }
+  }
+  clear() {
+    this.map.clear();
+  }
+};
+var caches = /* @__PURE__ */ new WeakMap();
+var getMessageCache = (owner) => {
+  let cache = caches.get(owner);
+  if (!cache) {
+    cache = new MessageCache();
+    caches.set(owner, cache);
+  }
+  return cache;
+};
+
 // src/providers/imessage/remote.ts
 var PLATFORM = "iMessage";
 var URL_BALLOON_BUNDLE_ID = "com.apple.messages.URLBalloonProvider";
-var unsupportedContent = (type) => UnsupportedError.content(type, PLATFORM);
+var GROUP_ITEM_ALLOWED = /* @__PURE__ */ new Set([
+  "attachment",
+  "contact",
+  "voice"
+]);
+var unsupportedContent = (type, detail) => UnsupportedError.content(type, PLATFORM, detail);
 var toSendResult = (receipt) => ({
   id: receipt.guid,
   timestamp: /* @__PURE__ */ new Date()
@@ -442,14 +486,19 @@ var getAssociatedMessageType = (message) => {
   const fromRaw = raw?.associatedMessageType;
   return typeof fromRaw === "string" ? fromRaw : void 0;
 };
-var baseMessage = (event) => ({
-  sender: { id: event.message.sender?.address ?? "" },
-  space: {
-    id: event.chatGuid,
-    type: event.chatGuid.includes(";+;") ? "group" : "dm"
-  },
-  timestamp: event.timestamp
-});
+var getBalloonBundleId = (message) => {
+  const raw = message._raw;
+  const id = raw?.balloonBundleId;
+  return typeof id === "string" ? id : void 0;
+};
+var resolveChatGuid = (message, hint) => {
+  if (hint) {
+    return hint;
+  }
+  const first = message.chatGuids?.[0];
+  return first ?? "";
+};
+var resolveSenderId = (message) => message.sender?.address ?? "";
 var toAttachmentContent2 = (client, info) => asAttachment({
   name: info.fileName,
   mimeType: info.mimeType,
@@ -465,10 +514,87 @@ var toVCardContent2 = async (client, info) => {
     return toAttachmentContent2(client, info);
   }
 };
-var getBalloonBundleId = (message) => {
-  const raw = message._raw;
-  const id = raw?.balloonBundleId;
-  return typeof id === "string" ? id : void 0;
+var attachmentContent = async (client, info) => isVCardAttachment2(info.mimeType, info.fileName) ? await toVCardContent2(client, info) : toAttachmentContent2(client, info);
+var baseShape = (message, chatGuidHint, timestamp) => {
+  const chat = resolveChatGuid(message, chatGuidHint);
+  return {
+    sender: { id: resolveSenderId(message) },
+    space: {
+      id: chat,
+      type: chat.includes(";+;") ? "group" : "dm"
+    },
+    timestamp
+  };
+};
+var buildAttachmentMessage = async (client, base, info, id, partIndex, parentId) => {
+  const content = await attachmentContent(client, info);
+  const msg = { ...base, id, content, partIndex };
+  if (parentId !== void 0) {
+    msg.parentId = parentId;
+  }
+  return msg;
+};
+var rebuildFromAppleMessage = async (client, message, chatGuidHint) => {
+  const messageGuidStr = message.guid;
+  const timestamp = message.dateCreated ?? /* @__PURE__ */ new Date();
+  const base = baseShape(message, chatGuidHint, timestamp);
+  if (message.attachments.length === 1) {
+    const info = message.attachments[0];
+    if (!info) {
+      throw new Error("Unreachable: attachments.length === 1 but no element");
+    }
+    return buildAttachmentMessage(client, base, info, messageGuidStr, 0);
+  }
+  if (message.attachments.length > 1) {
+    const items = [];
+    for (let i = 0; i < message.attachments.length; i++) {
+      const info = message.attachments[i];
+      if (!info) {
+        continue;
+      }
+      items.push(
+        await buildAttachmentMessage(
+          client,
+          base,
+          info,
+          formatChildId(i, messageGuidStr),
+          i,
+          messageGuidStr
+        )
+      );
+    }
+    return {
+      ...base,
+      id: messageGuidStr,
+      content: asGroup({ items })
+    };
+  }
+  const text = message.text;
+  if (getBalloonBundleId(message) === URL_BALLOON_BUNDLE_ID) {
+    const url = text ?? "";
+    try {
+      return { ...base, id: messageGuidStr, content: asRichlink({ url }) };
+    } catch {
+      return {
+        ...base,
+        id: messageGuidStr,
+        content: url ? asText(url) : asCustom(message)
+      };
+    }
+  }
+  return {
+    ...base,
+    id: messageGuidStr,
+    content: text ? asText(text) : asCustom(message)
+  };
+};
+var cacheMessage = (cache, message) => {
+  cache.set(message.id, message);
+  if (message.content.type === "group") {
+    for (const item of message.content.items) {
+      cache.set(item.id, item);
+    }
+  }
 };
 var toRichlinkMessage = (event, base, id) => {
   const url = event.message.text ?? "";
@@ -482,8 +608,42 @@ var toRichlinkMessage = (event, base, id) => {
     };
   }
 };
-var PART_PREFIX = /^p:\d+\//;
-var toReactionMessage = (event, base, id, target) => {
+var PART_PREFIX = /^p:(\d+)\//;
+var formatChildId = (partIndex, parentGuid) => `p:${partIndex}/${parentGuid}`;
+var parseTapbackTarget = (target) => {
+  const match = target.match(PART_PREFIX);
+  const guid = target.replace(PART_PREFIX, "");
+  const partIndex = match ? Number(match[1]) : 0;
+  return { guid, partIndex };
+};
+var parseChildId = (id) => {
+  const match = id.match(PART_PREFIX);
+  if (!match) {
+    return null;
+  }
+  return {
+    parentGuid: id.replace(PART_PREFIX, ""),
+    partIndex: Number(match[1])
+  };
+};
+var resolveReactionTarget = async (client, cache, strippedGuid, partIndex) => {
+  let candidate = cache.get(strippedGuid);
+  if (!candidate) {
+    try {
+      const fetched = await client.messages.get(messageGuid(strippedGuid));
+      candidate = await rebuildFromAppleMessage(client, fetched);
+      cacheMessage(cache, candidate);
+    } catch {
+      return;
+    }
+  }
+  if (candidate.content.type === "group") {
+    const item = candidate.content.items[partIndex];
+    return item ?? candidate;
+  }
+  return candidate;
+};
+var toReactionMessage = async (client, cache, event, base, id, target) => {
   const type = getAssociatedMessageType(event.message);
   if (type && isTapbackRemoval(type)) {
     return [];
@@ -495,41 +655,89 @@ var toReactionMessage = (event, base, id, target) => {
   if (!emoji) {
     return [];
   }
-  const normalizedTarget = target.replace(PART_PREFIX, "");
+  const { guid: strippedGuid, partIndex } = parseTapbackTarget(target);
+  const resolved = await resolveReactionTarget(
+    client,
+    cache,
+    strippedGuid,
+    partIndex
+  );
+  if (!resolved) {
+    return [];
+  }
   return [
-    { ...base, id, content: asReaction({ emoji, target: normalizedTarget }) }
+    {
+      ...base,
+      id,
+      content: asReaction({ emoji, target: resolved })
+    }
   ];
 };
-var toMessages2 = async (client, event) => {
-  const base = baseMessage(event);
+var toMessages2 = async (client, cache, event) => {
+  const base = baseShape(event.message, event.chatGuid, event.timestamp);
   const messageGuidStr = event.message.guid;
   const assoc = event.message.associatedMessageGuid;
   if (assoc) {
-    return toReactionMessage(event, base, messageGuidStr, assoc);
+    return toReactionMessage(client, cache, event, base, messageGuidStr, assoc);
   }
   if (getBalloonBundleId(event.message) === URL_BALLOON_BUNDLE_ID) {
-    return [toRichlinkMessage(event, base, messageGuidStr)];
+    const msg2 = toRichlinkMessage(event, base, messageGuidStr);
+    cacheMessage(cache, msg2);
+    return [msg2];
   }
-  if (event.message.attachments.length > 0) {
-    return Promise.all(
-      event.message.attachments.map(async (info) => ({
-        ...base,
-        id: `${messageGuidStr}:${info.guid}`,
-        content: isVCardAttachment2(info.mimeType, info.fileName) ? await toVCardContent2(client, info) : toAttachmentContent2(client, info)
-      }))
+  if (event.message.attachments.length === 1) {
+    const info = event.message.attachments[0];
+    if (!info) {
+      throw new Error("Unreachable: attachments.length === 1 but no element");
+    }
+    const msg2 = await buildAttachmentMessage(
+      client,
+      base,
+      info,
+      messageGuidStr,
+      0
     );
+    cacheMessage(cache, msg2);
+    return [msg2];
   }
-  const text = event.message.text;
-  return [
-    {
+  if (event.message.attachments.length > 1) {
+    const items = [];
+    for (let i = 0; i < event.message.attachments.length; i++) {
+      const info = event.message.attachments[i];
+      if (!info) {
+        continue;
+      }
+      items.push(
+        await buildAttachmentMessage(
+          client,
+          base,
+          info,
+          formatChildId(i, messageGuidStr),
+          i,
+          messageGuidStr
+        )
+      );
+    }
+    const parent = {
       ...base,
       id: messageGuidStr,
-      content: text ? asText(text) : asCustom(event.message)
-    }
-  ];
+      content: asGroup({ items })
+    };
+    cacheMessage(cache, parent);
+    return [parent];
+  }
+  const text = event.message.text;
+  const msg = {
+    ...base,
+    id: messageGuidStr,
+    content: text ? asText(text) : asCustom(event.message)
+  };
+  cacheMessage(cache, msg);
+  return [msg];
 };
 var clientStream = (client) => {
   const sub = client.messages.subscribe("message.received");
+  const cache = getMessageCache(client);
   return stream((emit, end) => {
     const pump = (async () => {
       try {
@@ -537,7 +745,7 @@ var clientStream = (client) => {
           if (event.message.isFromMe) {
             continue;
           }
-          for (const message of await toMessages2(client, event)) {
+          for (const message of await toMessages2(client, cache, event)) {
             await emit(message);
           }
         }
@@ -581,12 +789,7 @@ var stopTyping = async (clients, spaceId) => {
   }
   await remote.chats.stopTyping(chatGuid(spaceId));
 };
-var send2 = async (clients, spaceId, content) => {
-  const remote = clients[0];
-  if (!remote) {
-    throw new Error("No remote iMessage client available");
-  }
-  const chat = chatGuid(spaceId);
+var sendSingle = async (remote, chat, content) => {
   switch (content.type) {
     case "text":
       return toSendResult(await remote.messages.send(chat, content.text));
@@ -601,9 +804,7 @@ var send2 = async (clients, spaceId, content) => {
         mimeType: content.mimeType
       });
       return toSendResult(
-        await remote.messages.send(chat, "", {
-          attachment: attachment.guid
-        })
+        await remote.messages.send(chat, "", { attachment: attachment.guid })
       );
     }
     case "contact": {
@@ -631,6 +832,34 @@ var send2 = async (clients, spaceId, content) => {
       throw unsupportedContent(content.type);
   }
 };
+var send2 = async (clients, spaceId, content) => {
+  const remote = clients[0];
+  if (!remote) {
+    throw new Error("No remote iMessage client available");
+  }
+  const chat = chatGuid(spaceId);
+  if (content.type === "group") {
+    for (const sub of content.items) {
+      const itemType = sub.content.type;
+      if (!GROUP_ITEM_ALLOWED.has(itemType)) {
+        throw unsupportedContent(
+          "group",
+          `"${itemType}" items are not supported inside a group`
+        );
+      }
+    }
+    const groupMembers = [];
+    for (const sub of content.items) {
+      groupMembers.push(await sendSingle(remote, chat, sub.content));
+    }
+    const first = groupMembers[0];
+    if (!first) {
+      throw new Error("Empty group");
+    }
+    return { ...first, groupMembers };
+  }
+  return sendSingle(remote, chat, content);
+};
 var replyToMessage = async (clients, spaceId, msgId, content) => {
   const remote = clients[0];
   if (!remote) {
@@ -709,18 +938,56 @@ var editMessage = async (clients, spaceId, msgId, content) => {
     content.text
   );
 };
-var reactToMessage = async (clients, spaceId, msgId, reaction) => {
+var reactToMessage = async (clients, spaceId, target, reaction) => {
   const remote = clients[0];
   if (!remote) {
     return;
   }
   const chat = chatGuid(spaceId);
-  const msg = messageGuid(msgId);
+  const parentGuid = target.parentId ?? target.id;
+  const guid = messageGuid(parentGuid);
+  const opts = typeof target.partIndex === "number" ? { partIndex: target.partIndex } : void 0;
   const native = EMOJI_TO_TAPBACK[reaction];
   if (native) {
-    await remote.messages.react(chat, msg, native);
+    await remote.messages.react(chat, guid, native, opts);
   } else {
-    await remote.messages.reactEmoji(chat, msg, reaction);
+    await remote.messages.reactEmoji(chat, guid, reaction, opts);
+  }
+};
+var getMessage2 = async (clients, spaceId, msgId) => {
+  const remote = clients[0];
+  if (!remote) {
+    return;
+  }
+  const cache = getMessageCache(remote);
+  const cached = cache.get(msgId);
+  if (cached) {
+    return cached;
+  }
+  const childRef = parseChildId(msgId);
+  if (childRef) {
+    try {
+      const fetched = await remote.messages.get(
+        messageGuid(childRef.parentGuid)
+      );
+      const parent = await rebuildFromAppleMessage(remote, fetched, spaceId);
+      cacheMessage(cache, parent);
+      if (parent.content.type !== "group") {
+        return;
+      }
+      const items = parent.content.items;
+      return items[childRef.partIndex];
+    } catch {
+      return;
+    }
+  }
+  try {
+    const fetched = await remote.messages.get(messageGuid(msgId));
+    const rebuilt = await rebuildFromAppleMessage(remote, fetched, spaceId);
+    cacheMessage(cache, rebuilt);
+    return rebuilt;
+  } catch {
+    return;
   }
 };
 
@@ -741,6 +1008,10 @@ var spaceSchema = z.object({
   id: z.string(),
   type: z.enum(["dm", "group"])
 });
+var messageSchema = z.object({
+  partIndex: z.number().int().nonnegative().optional(),
+  parentId: z.string().optional()
+});
 
 // src/providers/imessage/index.ts
 var imessage = definePlatform("iMessage", {
@@ -776,6 +1047,9 @@ var imessage = definePlatform("iMessage", {
       return { id: chat.guid, type: "group" };
     }
   },
+  message: {
+    schema: messageSchema
+  },
   lifecycle: {
     createClient: async ({
       config,
@@ -829,11 +1103,16 @@ var imessage = definePlatform("iMessage", {
       }
       await stopTyping(client, space.id);
     },
-    reactToMessage: async ({ space, messageId, reaction, client }) => {
+    reactToMessage: async ({ space, target, reaction, client }) => {
       if (isLocal(client)) {
         throw UnsupportedError.action("react", "iMessage (local mode)");
       }
-      await reactToMessage(client, space.id, messageId, reaction);
+      await reactToMessage(
+        client,
+        space.id,
+        target,
+        reaction
+      );
     },
     replyToMessage: async ({ space, messageId, content, client }) => {
       if (isLocal(client)) {
@@ -846,6 +1125,12 @@ var imessage = definePlatform("iMessage", {
         throw UnsupportedError.action("edit", "iMessage (local mode)");
       }
       await editMessage(client, space.id, messageId, content);
+    },
+    getMessage: async ({ space, messageId, client }) => {
+      if (isLocal(client)) {
+        return getMessage(client, messageId);
+      }
+      return getMessage2(client, space.id, messageId);
     }
   }
 });

package/dist/providers/terminal/index.d.ts

@@ -1,4 +1,4 @@
-import { d as Platform, c as PlatformDef, P as ProviderMessage } from '../../types-B8g0pvfg.js';
+import { d as Platform, c as PlatformDef, P as ProviderMessage } from '../../types-D5KhSXLy.js';
 import * as node_readline from 'node:readline';
 import z__default from 'zod';
 import 'hotscript';

package/dist/providers/terminal/index.js

@@ -1,7 +1,7 @@
 import {
   UnsupportedError,
   definePlatform
-} from "../../chunk-PLJI5FTO.js";
+} from "../../chunk-U6WCQVVX.js";
 
 // src/providers/terminal/index.ts
 import { createInterface } from "readline";

package/dist/providers/whatsapp-business/index.d.ts

@@ -2,7 +2,7 @@ import { M as ManagedStream } from '../../stream-B55k7W8-.js';
 import { WhatsAppClient } from '@photon-ai/whatsapp-business';
 import * as z from 'zod';
 import z__default from 'zod';
-import { l as SchemaMessage, d as Platform, c as PlatformDef, P as ProviderMessage } from '../../types-B8g0pvfg.js';
+import { l as SchemaMessage, d as Platform, c as PlatformDef, P as ProviderMessage } from '../../types-D5KhSXLy.js';
 import * as zod_v4_core from 'zod/v4/core';
 import 'hotscript';
 

package/dist/providers/whatsapp-business/index.js

@@ -6,12 +6,12 @@ import {
   cloud,
   mergeStreams,
   stream
-} from "../../chunk-CZIWNTXP.js";
+} from "../../chunk-OIXH5S65.js";
 import {
   UnsupportedError,
   asText,
   definePlatform
-} from "../../chunk-PLJI5FTO.js";
+} from "../../chunk-U6WCQVVX.js";
 
 // src/providers/whatsapp-business/index.ts
 import { createClient as createClient2 } from "@photon-ai/whatsapp-business";
@@ -401,11 +401,16 @@ var mapContent = (client, content) => {
       return asCustom({ whatsapp_type: "sticker", ...content.sticker });
     case "location":
       return asCustom({ whatsapp_type: "location", ...content.location });
-    case "reaction":
+    case "reaction": {
+      const stubTarget = {
+        id: content.reaction.messageId,
+        content: asCustom({ whatsapp_type: "reaction-target", stub: true })
+      };
       return asReaction({
         emoji: content.reaction.emoji,
-        target: content.reaction.messageId
+        target: stubTarget
       });
+    }
     case "interactive":
       return asCustom({ whatsapp_type: "interactive", ...content.interactive });
     case "button":
@@ -723,11 +728,11 @@ var whatsappBusiness = definePlatform("WhatsApp Business", {
     send: async ({ space, content, client }) => {
       return await send(client, space.id, content);
     },
-    reactToMessage: async ({ space, messageId, reaction, client }) => {
+    reactToMessage: async ({ space, target, reaction, client }) => {
       await reactToMessage(
         client,
         space.id,
-        messageId,
+        target.id,
         reaction
       );
     },

package/dist/{types-B8g0pvfg.d.ts → types-D5KhSXLy.d.ts}

@@ -91,7 +91,10 @@ declare const contentSchema: z__default.ZodDiscriminatedUnion<[z__default.ZodObj
 }, z__default.core.$strip>, z__default.ZodObject<{
     type: z__default.ZodLiteral<"reaction">;
     emoji: z__default.ZodString;
-    target: z__default.ZodString;
+    target: z__default.ZodCustom<Message, Message>;
+}, z__default.core.$strip>, z__default.ZodObject<{
+    type: z__default.ZodLiteral<"group">;
+    items: z__default.ZodArray<z__default.ZodCustom<Message, Message>>;
 }, z__default.core.$strip>], "type">;
 type Content = z__default.infer<typeof contentSchema>;
 interface ContentBuilder {
@@ -107,6 +110,13 @@ interface User {
 interface Space<_Def = unknown> {
     readonly __platform: string;
     edit(message: OutboundMessage, newContent: ContentInput): Promise<void>;
+    /**
+     * Look up a message in this space by its id. Returns `undefined` if the
+     * platform has no way to resolve the id (e.g. cache miss with no by-id
+     * SDK fallback). Used to materialize a `Message` for APIs that require one,
+     * such as `reaction()`.
+     */
+    getMessage(id: string): Promise<Message | undefined>;
     readonly id: string;
     responding<T>(fn: () => T | Promise<T>): Promise<T>;
     send(content: ContentInput): Promise<OutboundMessage | undefined>;
@@ -158,6 +168,14 @@ type ProviderMessage<TSender extends ResolvedUser = ResolvedUser, TSpace extends
     timestamp?: Date;
 } & TExtra;
 interface SendResult<TSender extends ResolvedUser = ResolvedUser> {
+    /**
+     * Per-item send receipts returned when the dispatched content was a
+     * `group`. Providers that iterate native sends to emulate a group
+     * (e.g. iMessage) populate this so the platform build layer can
+     * replace the outbound group's placeholder items with real Messages
+     * that carry each item's own id.
+     */
+    groupMembers?: SendResult<TSender>[];
     id: string;
     sender?: TSender;
     timestamp?: Date;
@@ -190,7 +208,7 @@ interface PlatformDef<_Name extends string = string, _ConfigSchema extends z__de
         }) => Promise<void>;
         reactToMessage?: (_: {
             space: _ResolvedSpace & SpaceRef;
-            messageId: string;
+            target: _MessageType;
             reaction: string;
             client: _Client;
             config: z__default.infer<_ConfigSchema>;
@@ -209,6 +227,12 @@ interface PlatformDef<_Name extends string = string, _ConfigSchema extends z__de
             client: _Client;
             config: z__default.infer<_ConfigSchema>;
         }) => Promise<void>;
+        getMessage?: (_: {
+            space: _ResolvedSpace & SpaceRef;
+            messageId: string;
+            client: _Client;
+            config: z__default.infer<_ConfigSchema>;
+        }) => Promise<_MessageType | undefined>;
     };
     config: _ConfigSchema;
     events: _Events;
@@ -259,6 +283,7 @@ interface AnyPlatformDef {
         reactToMessage?: (_: any) => Promise<void>;
         replyToMessage?: (_: any) => Promise<SendResult>;
         editMessage?: (_: any) => Promise<void>;
+        getMessage?: (_: any) => Promise<any>;
     };
     config: z__default.ZodType<object>;
     events: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spectrum-ts",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",