spectrum-ts 1.13.1 → 1.15.0

package/dist/{chunk-4TXLNBGE.js → chunk-2B76JFHX.js}

@@ -1,8 +1,9 @@
 import {
   bufferToStream,
+  fetchUrlBytes,
   readSchema,
   streamSchema
-} from "./chunk-YDHES53X.js";
+} from "./chunk-YFCDKZ6W.js";
 
 // src/content/voice.ts
 import { createReadStream } from "fs";
@@ -26,11 +27,23 @@ var resolveVoiceName = (input, name) => {
   if (name) {
     return name;
   }
+  if (input instanceof URL) {
+    return basename(input.pathname) || void 0;
+  }
   if (typeof input === "string") {
     return basename(input);
   }
   return;
 };
+var resolveVoiceMimeHint = (input, name) => {
+  if (input instanceof URL) {
+    return basename(input.pathname) || void 0;
+  }
+  if (typeof input === "string") {
+    return basename(input);
+  }
+  return name;
+};
 var resolveVoiceMimeType = (name, mimeType) => {
   if (mimeType) {
     if (!AUDIO_MIME_PATTERN.test(mimeType)) {
@@ -79,8 +92,16 @@ function voice(input, options) {
   return {
     build: async () => {
       const name = resolveVoiceName(input, options?.name);
-      const mimeHint = typeof input === "string" ? basename(input) : name;
+      const mimeHint = resolveVoiceMimeHint(input, name);
       const mimeType = resolveVoiceMimeType(mimeHint, options?.mimeType);
+      if (input instanceof URL) {
+        return asVoice({
+          name,
+          mimeType,
+          duration: options?.duration,
+          read: async () => (await fetchUrlBytes(input)).data
+        });
+      }
       if (typeof input === "string") {
         const stats = await stat(input);
         if (!stats.isFile()) {

package/dist/{chunk-FPYXHZZA.js → chunk-BGV4SFVJ.js}

@@ -2,7 +2,7 @@ import {
   asGroup,
   asRichlink,
   groupSchema
-} from "./chunk-UFJZIZDO.js";
+} from "./chunk-JBMQ5GEW.js";
 import {
   asPoll,
   asPollOption
@@ -16,7 +16,7 @@ import {
   asContact,
   fromVCard,
   toVCard
-} from "./chunk-L3VXHUVY.js";
+} from "./chunk-J2ANGYYW.js";
 import {
   UnsupportedError,
   asAttachment,
@@ -29,11 +29,12 @@ import {
   reactionSchema,
   text,
   textSchema
-} from "./chunk-YDHES53X.js";
+} from "./chunk-YFCDKZ6W.js";
 
 // src/providers/imessage/index.ts
 import { createClient as createClient2, MessageEffect as MessageEffect2 } from "@photon-ai/advanced-imessage";
 import { IMessageSDK as IMessageSDK2 } from "@photon-ai/imessage-kit";
+import { withSpan } from "@photon-ai/otel";
 
 // src/providers/imessage/content/background.ts
 import z from "zod";
@@ -322,6 +323,7 @@ var readLocalAttachment = async (att) => {
 var toAttachmentContent = (att) => {
   const { localPath } = att;
   return asAttachment({
+    id: att.id,
     name: att.fileName ?? DEFAULT_ATTACHMENT_NAME,
     mimeType: att.mimeType,
     size: att.sizeBytes,
@@ -546,7 +548,7 @@ var setBackground = async (remote, spaceId, content) => {
 
 // src/providers/imessage/remote/inbound.ts
 import {
-  NotFoundError
+  NotFoundError as NotFoundError2
 } from "@photon-ai/advanced-imessage";
 
 // src/providers/imessage/cache.ts
@@ -620,45 +622,10 @@ var getPollCache = (owner) => {
   return cache;
 };
 
-// src/providers/imessage/remote/inbound.ts
-var URL_BALLOON_BUNDLE_ID = "com.apple.messages.URLBalloonProvider";
-var getBalloonBundleId = (message) => message.content.balloonBundleId;
-var messageAttachments = (message) => message.content.attachments;
-var resolveChatGuid = (message, hint) => {
-  if (hint) {
-    return hint;
-  }
-  const first = message.chatGuids?.[0];
-  return first ?? "";
-};
-var resolveSenderId = (message) => message.sender?.address ?? "";
-var isIMessageMessage = (value) => {
-  if (typeof value !== "object" || value === null) {
-    return false;
-  }
-  const record = value;
-  return typeof record.id === "string" && record.id.length > 0 && typeof record.content === "object" && record.content !== null && typeof record.sender === "object" && record.sender !== null && typeof record.space === "object" && record.space !== null;
-};
-var asProviderGroup = (items) => groupSchema.parse({ type: "group", items });
-var buildMessageBase = (message, chatGuidHint, timestamp, phone) => {
-  const chat = resolveChatGuid(message, chatGuidHint);
-  return {
-    sender: { id: resolveSenderId(message) },
-    space: {
-      id: chat,
-      type: chat.includes(";+;") ? "group" : "dm",
-      phone
-    },
-    timestamp
-  };
-};
-var toAttachmentContent2 = (client, info) => asAttachment({
-  name: info.fileName,
-  mimeType: info.mimeType,
-  size: info.totalBytes,
-  read: async () => await downloadPrimaryAttachment(client, info.guid),
-  stream: async () => downloadPrimaryAttachmentStream(client, info.guid)
-});
+// src/providers/imessage/remote/attachments.ts
+import {
+  NotFoundError
+} from "@photon-ai/advanced-imessage";
 var downloadPrimaryAttachmentStream = (client, attachmentGuid) => {
   const frames = client.attachments.downloadStream(attachmentGuid);
   const iterator = frames[Symbol.asyncIterator]();
@@ -713,6 +680,66 @@ var downloadPrimaryAttachment = async (client, attachmentGuid) => {
   }
   return Buffer.concat(chunks);
 };
+var getRemoteAttachment = async (client, guid) => {
+  let info;
+  try {
+    info = await client.attachments.get(guid);
+  } catch (err) {
+    if (err instanceof NotFoundError) {
+      return;
+    }
+    throw err;
+  }
+  return asAttachment({
+    id: info.guid,
+    name: info.fileName,
+    mimeType: info.mimeType,
+    size: info.totalBytes,
+    read: () => downloadPrimaryAttachment(client, info.guid),
+    stream: async () => downloadPrimaryAttachmentStream(client, info.guid)
+  });
+};
+
+// src/providers/imessage/remote/inbound.ts
+var URL_BALLOON_BUNDLE_ID = "com.apple.messages.URLBalloonProvider";
+var getBalloonBundleId = (message) => message.content.balloonBundleId;
+var messageAttachments = (message) => message.content.attachments;
+var resolveChatGuid = (message, hint) => {
+  if (hint) {
+    return hint;
+  }
+  const first = message.chatGuids?.[0];
+  return first ?? "";
+};
+var resolveSenderId = (message) => message.sender?.address ?? "";
+var isIMessageMessage = (value) => {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const record = value;
+  return typeof record.id === "string" && record.id.length > 0 && typeof record.content === "object" && record.content !== null && typeof record.sender === "object" && record.sender !== null && typeof record.space === "object" && record.space !== null;
+};
+var asProviderGroup = (items) => groupSchema.parse({ type: "group", items });
+var buildMessageBase = (message, chatGuidHint, timestamp, phone) => {
+  const chat = resolveChatGuid(message, chatGuidHint);
+  return {
+    sender: { id: resolveSenderId(message) },
+    space: {
+      id: chat,
+      type: chat.includes(";+;") ? "group" : "dm",
+      phone
+    },
+    timestamp
+  };
+};
+var toAttachmentContent2 = (client, info) => asAttachment({
+  id: info.guid,
+  name: info.fileName,
+  mimeType: info.mimeType,
+  size: info.totalBytes,
+  read: async () => await downloadPrimaryAttachment(client, info.guid),
+  stream: async () => downloadPrimaryAttachmentStream(client, info.guid)
+});
 var toVCardContent2 = async (client, info) => {
   try {
     const buf = await downloadPrimaryAttachment(client, info.guid);
@@ -896,7 +923,7 @@ var getMessage3 = async (remote, spaceId, msgId, phone) => {
       const item = parent.content.items[childRef.partIndex];
       return isIMessageMessage(item) ? item : void 0;
     } catch (err) {
-      if (err instanceof NotFoundError) {
+      if (err instanceof NotFoundError2) {
         return;
       }
       throw err;
@@ -916,7 +943,7 @@ var getMessage3 = async (remote, spaceId, msgId, phone) => {
     cacheMessage(cache, rebuilt);
     return rebuilt;
   } catch (err) {
-    if (err instanceof NotFoundError) {
+    if (err instanceof NotFoundError2) {
       return;
     }
     throw err;
@@ -1375,7 +1402,7 @@ var editMessage = async (remote, spaceId, msgId, content) => {
 import {
   AuthenticationError,
   IMessageError,
-  NotFoundError as NotFoundError2,
+  NotFoundError as NotFoundError3,
   ValidationError
 } from "@photon-ai/advanced-imessage";
 
@@ -1751,7 +1778,7 @@ var toPollDeltaMessages = async (client, pollCache, event, phone) => {
 
 // src/providers/imessage/remote/stream.ts
 var isRetryableIMessageStreamError = (error) => {
-  if (error instanceof AuthenticationError || error instanceof NotFoundError2 || error instanceof ValidationError) {
+  if (error instanceof AuthenticationError || error instanceof NotFoundError3 || error instanceof ValidationError) {
     return false;
   }
   if (error instanceof IMessageError) {
@@ -2202,12 +2229,53 @@ var imessage = definePlatform("iMessage", {
     return await send4(remote, space.id, content);
   },
   actions: {
-    getMessage: async ({ space, messageId, client }) => {
+    getMessage: async ({ client }, space, messageId) => {
       if (isLocal(client)) {
         return getMessage2(client, messageId);
       }
       const remote = clientForPhone(client, space.phone);
       return getMessage4(remote, space.id, messageId, space.phone);
+    },
+    // Fetch an attachment by GUID. Returns a spectrum `Attachment` whose
+    // `.read()` / `.stream()` lazily download the bytes — calling both
+    // issues two independent gRPC downloads, so cache `.read()` if you
+    // need the bytes more than once. Returns `undefined` for unknown
+    // GUIDs. Local-mode iMessage is not supported.
+    getAttachment: async ({ client }, guid, phone) => {
+      if (isLocal(client)) {
+        throw UnsupportedError.action(
+          "getAttachment",
+          "iMessage (local mode)",
+          "fetching attachments by GUID requires remote iMessage"
+        );
+      }
+      if (client.length === 0) {
+        throw new Error("No iMessage clients configured");
+      }
+      const routedPhone = (() => {
+        if (isSharedMode(client)) {
+          return SHARED_PHONE;
+        }
+        if (phone) {
+          return phone;
+        }
+        if (client.length === 1) {
+          return client[0].phone;
+        }
+        throw new Error(
+          `imessage.getAttachment requires a phone in multi-phone mode. Available: ${availablePhones(client).join(", ")}`
+        );
+      })();
+      const remote = clientForPhone(client, routedPhone);
+      return withSpan(
+        "spectrum.imessage.getAttachment",
+        {
+          "spectrum.provider": "iMessage",
+          "spectrum.imessage.attachment.guid": guid,
+          "spectrum.imessage.phone": routedPhone
+        },
+        () => getRemoteAttachment(remote, guid)
+      );
     }
   }
 });

package/dist/{chunk-L3VXHUVY.js → chunk-J2ANGYYW.js}

@@ -1,6 +1,6 @@
 import {
   readSchema
-} from "./chunk-YDHES53X.js";
+} from "./chunk-YFCDKZ6W.js";
 
 // src/utils/vcard.ts
 import vCard from "vcf";

package/dist/{chunk-UFJZIZDO.js → chunk-JBMQ5GEW.js}

@@ -1,9 +1,10 @@
 import {
   bufferToStream,
+  fetchUrlBytes,
   readSchema,
   resolveContents,
   streamSchema
-} from "./chunk-YDHES53X.js";
+} from "./chunk-YFCDKZ6W.js";
 
 // src/content/group.ts
 import z from "zod";
@@ -82,24 +83,10 @@ var fetchLinkMetadata = async (url) => {
     return {};
   }
 };
-var fetchImage = async (url) => {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
-  try {
-    const res = await fetch(url, {
-      signal: controller.signal,
-      headers: { "User-Agent": USER_AGENT }
-    });
-    if (!res.ok) {
-      throw new Error(`image fetch ${url} returned ${res.status}`);
-    }
-    const data = Buffer.from(await res.arrayBuffer());
-    const mimeType = res.headers.get("content-type") ?? void 0;
-    return { data, mimeType };
-  } finally {
-    clearTimeout(timer);
-  }
-};
+var fetchImage = (url) => fetchUrlBytes(new URL(url), {
+  timeoutMs: DEFAULT_TIMEOUT_MS,
+  headers: { "User-Agent": USER_AGENT }
+});
 
 // src/content/richlink.ts
 var richlinkCoverSchema = z2.object({

package/dist/{chunk-NBXNTQIQ.js → chunk-TSJKUFNE.js}

@@ -1,18 +1,18 @@
 import {
   asVoice
-} from "./chunk-4TXLNBGE.js";
+} from "./chunk-2B76JFHX.js";
 import {
   asContact,
   fromVCard,
   toVCard
-} from "./chunk-L3VXHUVY.js";
+} from "./chunk-J2ANGYYW.js";
 import {
   UnsupportedError,
   asAttachment,
   asCustom,
   definePlatform,
   reactionSchema
-} from "./chunk-YDHES53X.js";
+} from "./chunk-YFCDKZ6W.js";
 
 // src/providers/terminal/index.ts
 import { spawn } from "child_process";

package/dist/{chunk-E7AXYNOZ.js → chunk-VOAKCXBF.js}

@@ -10,7 +10,7 @@ import {
   asReaction,
   asText,
   definePlatform
-} from "./chunk-YDHES53X.js";
+} from "./chunk-YFCDKZ6W.js";
 
 // src/providers/slack/index.ts
 import { createClient as createClient2, staticTokens } from "@photon-ai/slack";
@@ -169,6 +169,7 @@ var tsToDate = (ts) => {
   return new Date(seconds * 1e3);
 };
 var lazySlackFile = (client, teamId, file) => asAttachment({
+  id: file.id,
   name: file.name,
   mimeType: file.mimeType,
   size: file.size,

package/dist/{chunk-VQOW7X7U.js → chunk-YEQPATHB.js}

@@ -8,7 +8,7 @@ import {
 } from "./chunk-YKWKZ2PZ.js";
 import {
   asContact
-} from "./chunk-L3VXHUVY.js";
+} from "./chunk-J2ANGYYW.js";
 import {
   UnsupportedError,
   asAttachment,
@@ -16,7 +16,7 @@ import {
   asReaction,
   asText,
   definePlatform
-} from "./chunk-YDHES53X.js";
+} from "./chunk-YFCDKZ6W.js";
 
 // src/providers/whatsapp-business/index.ts
 import { createClient as createClient2 } from "@photon-ai/whatsapp-business";
@@ -508,6 +508,7 @@ var fetchMedia = async (client, mediaId) => {
   return response;
 };
 var lazyMedia = (client, media) => asAttachment({
+  id: media.id,
   name: media.filename ?? `media-${media.id}`,
   mimeType: media.mimeType,
   read: async () => Buffer.from(await (await fetchMedia(client, media.id)).arrayBuffer()),

package/dist/{chunk-YDHES53X.js → chunk-YFCDKZ6W.js}

@@ -1,4 +1,5 @@
 // src/content/attachment.ts
+import { randomUUID } from "crypto";
 import { createReadStream } from "fs";
 import { readFile, stat } from "fs/promises";
 import { basename } from "path";
@@ -22,18 +23,52 @@ var bufferToStream = (buf) => new ReadableStream({
     controller.close();
   }
 });
+var DEFAULT_FETCH_TIMEOUT_MS = 1e4;
+var fetchUrlBytes = async (url, options) => {
+  const controller = new AbortController();
+  const timer = setTimeout(
+    () => controller.abort(),
+    options?.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS
+  );
+  try {
+    const res = await fetch(url, {
+      signal: controller.signal,
+      headers: options?.headers
+    });
+    if (!res.ok) {
+      throw new Error(`URL fetch ${url.toString()} returned ${res.status}`);
+    }
+    const data = Buffer.from(await res.arrayBuffer());
+    const mimeType = res.headers.get("content-type") ?? void 0;
+    return { data, mimeType };
+  } finally {
+    clearTimeout(timer);
+  }
+};
 
 // src/content/attachment.ts
 var DEFAULT_ATTACHMENT_NAME = "attachment";
 var attachmentSchema = z2.object({
   type: z2.literal("attachment"),
+  id: z2.string().nonempty(),
   name: z2.string().nonempty(),
   mimeType: z2.string().nonempty(),
   size: z2.number().int().nonnegative().optional(),
   read: readSchema,
   stream: streamSchema
 });
-var resolveAttachmentName = (input, name) => name || (typeof input === "string" ? basename(input) : DEFAULT_ATTACHMENT_NAME);
+var resolveAttachmentName = (input, name) => {
+  if (name) {
+    return name;
+  }
+  if (input instanceof URL) {
+    return basename(input.pathname) || DEFAULT_ATTACHMENT_NAME;
+  }
+  if (typeof input === "string") {
+    return basename(input);
+  }
+  return DEFAULT_ATTACHMENT_NAME;
+};
 var resolveAttachmentMimeType = (name, mimeType) => {
   if (mimeType) {
     return mimeType;
@@ -58,6 +93,7 @@ var asAttachment = (input) => {
   const stream = input.stream ?? (async () => bufferToStream(await read()));
   return attachmentSchema.parse({
     type: "attachment",
+    id: input.id ?? randomUUID(),
     name: input.name,
     mimeType: input.mimeType,
     size: input.size,
@@ -68,11 +104,21 @@ var asAttachment = (input) => {
 function attachment(input, options) {
   return {
     build: async () => {
+      const id = options?.id;
       const name = resolveAttachmentName(input, options?.name);
       const mimeType = resolveAttachmentMimeType(name, options?.mimeType);
+      if (input instanceof URL) {
+        return asAttachment({
+          id,
+          name,
+          mimeType,
+          read: async () => (await fetchUrlBytes(input)).data
+        });
+      }
       if (typeof input === "string") {
         const stats = await stat(input);
         return asAttachment({
+          id,
           name,
           mimeType,
           size: stats.size,
@@ -83,6 +129,7 @@ function attachment(input, options) {
         });
       }
       return asAttachment({
+        id,
         name,
         mimeType,
         size: input.byteLength,
@@ -114,7 +161,12 @@ var resolveMimeType = (input, mimeType, contentLabel) => {
   if (mimeType) {
     return mimeType;
   }
-  if (typeof input === "string") {
+  if (input instanceof URL) {
+    const resolved = lookupMimeType2(basename2(input.pathname));
+    if (resolved) {
+      return resolved;
+    }
+  } else if (typeof input === "string") {
     const resolved = lookupMimeType2(basename2(input));
     if (resolved) {
       return resolved;
@@ -140,7 +192,9 @@ var buildPhotoAction = (input, options, contentLabel) => {
   }
   const mimeType = resolveMimeType(input, options?.mimeType, contentLabel);
   let read;
-  if (typeof input === "string") {
+  if (input instanceof URL) {
+    read = cachedRead(async () => (await fetchUrlBytes(input)).data);
+  } else if (typeof input === "string") {
     read = cachedRead(() => readFile2(input));
   } else {
     const snapshot = Buffer.from(input);
@@ -502,6 +556,7 @@ var RESERVED_SPACE_KEYS = /* @__PURE__ */ new Set([
   "stopTyping",
   "responding"
 ]);
+var PLATFORM_WISE_ACTION_KEYS = /* @__PURE__ */ new Set(["getMessage"]);
 var RESERVED_MESSAGE_KEYS = /* @__PURE__ */ new Set([
   "content",
   "direction",
@@ -514,8 +569,17 @@ var RESERVED_MESSAGE_KEYS = /* @__PURE__ */ new Set([
   "space",
   "timestamp"
 ]);
+var scopeLabel = (scope) => {
+  if (scope === "space") {
+    return "Space";
+  }
+  if (scope === "message") {
+    return "Message";
+  }
+  return "PlatformInstance";
+};
 var warnReservedAction = (scope, name, platform) => {
-  const body = `[spectrum-ts] ${platform} declared ${scope} action "${name}" which collides with a reserved ${scope === "space" ? "Space" : "Message"} key; skipping.`;
+  const body = `[spectrum-ts] ${platform} declared ${scope} action "${name}" which collides with a reserved ${scopeLabel(scope)} key; skipping.`;
   console.warn(
     supportsAnsiColor() ? `${ANSI_YELLOW}${body}${ANSI_RESET}` : body
   );
@@ -718,11 +782,7 @@ function buildSpace(params) {
   async function getMessageImpl(id) {
     const getMessage = definition.actions?.getMessage;
     if (!getMessage) {
-      warnUnsupported(
-        UnsupportedError.action("getMessage", definition.name),
-        definition.name
-      );
-      return;
+      throw UnsupportedError.action("getMessage", definition.name);
     }
     return withSpan(
       "spectrum.message.get",
@@ -732,22 +792,11 @@ function buildSpace(params) {
         "spectrum.message.id": id
       },
       async () => {
-        let raw;
-        try {
-          raw = await getMessage({
-            space: spaceRef,
-            messageId: id,
-            client,
-            config,
-            store
-          });
-        } catch (err) {
-          if (err instanceof UnsupportedError) {
-            warnUnsupported(err, definition.name);
-            return;
-          }
-          throw err;
-        }
+        const raw = await getMessage(
+          { client, config, store },
+          spaceRef,
+          id
+        );
         if (!raw) {
           return;
         }
@@ -785,7 +834,7 @@ function buildSpace(params) {
       await space.send(rename(displayName));
     },
     avatar: (async (input, options) => {
-      if (typeof input === "string") {
+      if (typeof input === "string" || input instanceof URL) {
         await space.send(avatar(input, options));
         return;
       }
@@ -905,6 +954,36 @@ function classifySpaceIdentifier(args) {
   }
   return { kind, identifier };
 }
+function buildInstanceActions(platformName, declared, reservedKeys, buildCtx) {
+  const out = {};
+  for (const key of PLATFORM_WISE_ACTION_KEYS) {
+    const override = declared?.[key];
+    if (override && typeof override === "function") {
+      out[key] = (...args) => override(buildCtx(), ...args);
+    } else {
+      out[key] = () => {
+        throw UnsupportedError.action(key, platformName);
+      };
+    }
+  }
+  if (!declared) {
+    return out;
+  }
+  for (const [name, factory] of Object.entries(declared)) {
+    if (PLATFORM_WISE_ACTION_KEYS.has(name)) {
+      continue;
+    }
+    if (reservedKeys.has(name)) {
+      warnReservedAction("instance", name, platformName);
+      continue;
+    }
+    if (typeof factory !== "function") {
+      continue;
+    }
+    out[name] = (...args) => factory(buildCtx(), ...args);
+  }
+  return out;
+}
 function createPlatformInstance(def, runtime) {
   const isPlatformUser = (value) => typeof value === "object" && value !== null && "__platform" in value && value.__platform === def.name;
   const resolveUserID = async (userID) => {
@@ -1040,7 +1119,26 @@ function createPlatformInstance(def, runtime) {
       return messagesIterable;
     }
   });
-  return Object.assign(base, eventProperties);
+  const instanceActions = buildInstanceActions(
+    def.name,
+    def.actions,
+    /* @__PURE__ */ new Set([
+      "user",
+      "space",
+      "messages",
+      ...Object.keys(customEvents)
+    ]),
+    () => ({
+      client: runtime.client,
+      config: runtime.config,
+      store: runtime.store
+    })
+  );
+  return Object.assign(
+    base,
+    instanceActions,
+    eventProperties
+  );
 }
 function definePlatform(name, def) {
   const fullDef = { name, ...def };
@@ -1121,6 +1219,7 @@ export {
   readSchema,
   streamSchema,
   bufferToStream,
+  fetchUrlBytes,
   attachmentSchema,
   asAttachment,
   attachment,