spectrum-ts 2.0.0 → 3.0.0

package/dist/{chunk-NGC4DJIX.js → chunk-LX437ZTY.js}

@@ -1,10 +1,14 @@
 import { createRequire as __spectrumCreateRequire } from "node:module"; const require = __spectrumCreateRequire(import.meta.url);
 import {
+  StreamConsumedError,
+  asText,
+  drainStreamText,
   fetchUrlBytes,
   reaction,
   readSchema,
-  resolveContents
-} from "./chunk-2ILTJC35.js";
+  resolveContents,
+  streamTextBuilder
+} from "./chunk-LQMDV75O.js";
 
 // src/content/avatar.ts
 import z2 from "zod";
@@ -98,6 +102,11 @@ var asEdit = (input) => editSchema.parse({ type: "edit", ...input });
 function edit(content, target) {
   return {
     build: async () => {
+      if (!target) {
+        throw new Error(
+          "edit() target is undefined \u2014 the targeted message was never sent (space.send resolves undefined when a platform skips unsupported content)"
+        );
+      }
       if (target.direction !== "outbound") {
         throw new Error(
           `edit() target must be an outbound message (got direction "${target.direction}", message id "${target.id}")`
@@ -107,7 +116,7 @@ function edit(content, target) {
       if (!resolved) {
         throw new Error("edit() requires content");
       }
-      if (resolved.type === "edit" || resolved.type === "reply" || resolved.type === "reaction" || resolved.type === "group" || resolved.type === "typing" || resolved.type === "rename" || resolved.type === "avatar") {
+      if (resolved.type === "edit" || resolved.type === "reply" || resolved.type === "reaction" || resolved.type === "group" || resolved.type === "typing" || resolved.type === "rename" || resolved.type === "avatar" || resolved.type === "unsend") {
         throw new Error(`edit() cannot wrap "${resolved.type}" content`);
       }
       return asEdit({ content: resolved, target });
@@ -115,11 +124,25 @@ function edit(content, target) {
   };
 }
 
-// src/content/rename.ts
+// src/content/markdown.ts
 import z4 from "zod";
-var renameSchema = z4.object({
-  type: z4.literal("rename"),
-  displayName: z4.string().min(1, "rename() displayName must be non-empty")
+var markdownSchema = z4.object({
+  type: z4.literal("markdown"),
+  markdown: z4.string().nonempty()
+});
+var asMarkdown = (markdown2) => markdownSchema.parse({ type: "markdown", markdown: markdown2 });
+function markdown(source, options) {
+  if (typeof source === "string") {
+    return { build: async () => asMarkdown(source) };
+  }
+  return streamTextBuilder("markdown", source, options);
+}
+
+// src/content/rename.ts
+import z5 from "zod";
+var renameSchema = z5.object({
+  type: z5.literal("rename"),
+  displayName: z5.string().min(1, "rename() displayName must be non-empty")
 });
 function rename(displayName) {
   return {
@@ -128,15 +151,15 @@ function rename(displayName) {
 }
 
 // src/content/reply.ts
-import z5 from "zod";
+import z6 from "zod";
 var isMessage2 = (v) => typeof v === "object" && v !== null && "id" in v && "content" in v;
 var isContent2 = (v) => typeof v === "object" && v !== null && "type" in v && typeof v.type === "string";
-var replySchema = z5.object({
-  type: z5.literal("reply"),
-  content: z5.custom(isContent2, {
+var replySchema = z6.object({
+  type: z6.literal("reply"),
+  content: z6.custom(isContent2, {
     message: "reply content must be a Content value"
   }),
-  target: z5.custom(isMessage2, {
+  target: z6.custom(isMessage2, {
     message: "reply target must be a Message"
   })
 });
@@ -144,11 +167,16 @@ var asReply = (input) => replySchema.parse({ type: "reply", ...input });
 function reply(content, target) {
   return {
     build: async () => {
+      if (!target) {
+        throw new Error(
+          "reply() target is undefined \u2014 the targeted message was never sent (space.send resolves undefined when a platform skips unsupported content)"
+        );
+      }
       const [resolved] = await resolveContents([content]);
       if (!resolved) {
         throw new Error("reply() requires content");
       }
-      if (resolved.type === "reply" || resolved.type === "edit" || resolved.type === "reaction" || resolved.type === "group" || resolved.type === "typing" || resolved.type === "rename" || resolved.type === "avatar") {
+      if (resolved.type === "reply" || resolved.type === "edit" || resolved.type === "reaction" || resolved.type === "group" || resolved.type === "typing" || resolved.type === "rename" || resolved.type === "avatar" || resolved.type === "unsend") {
         throw new Error(`reply() cannot wrap "${resolved.type}" content`);
       }
       return asReply({ content: resolved, target });
@@ -157,10 +185,10 @@ function reply(content, target) {
 }
 
 // src/content/typing.ts
-import z6 from "zod";
-var typingSchema = z6.object({
-  type: z6.literal("typing"),
-  state: z6.enum(["start", "stop"])
+import z7 from "zod";
+var typingSchema = z7.object({
+  type: z7.literal("typing"),
+  state: z7.enum(["start", "stop"])
 });
 function typing(state = "start") {
   return {
@@ -168,6 +196,34 @@ function typing(state = "start") {
   };
 }
 
+// src/content/unsend.ts
+import z8 from "zod";
+var isMessage3 = (v) => typeof v === "object" && v !== null && "id" in v && "content" in v;
+var unsendSchema = z8.object({
+  type: z8.literal("unsend"),
+  target: z8.custom(isMessage3, {
+    message: "unsend target must be a Message"
+  })
+});
+var asUnsend = (input) => unsendSchema.parse({ type: "unsend", ...input });
+function unsend(target) {
+  return {
+    build: async () => {
+      if (!target) {
+        throw new Error(
+          "unsend() target is undefined \u2014 the targeted message was never sent (space.send resolves undefined when a platform skips unsupported content)"
+        );
+      }
+      if (target.direction !== "outbound") {
+        throw new Error(
+          `unsend() target must be an outbound message (got direction "${target.direction}", message id "${target.id}")`
+        );
+      }
+      return asUnsend({ target });
+    }
+  };
+}
+
 // src/utils/errors.ts
 var composeMessage = (opts) => {
   const platform = opts.platform ?? "platform";
@@ -235,6 +291,133 @@ function classifyIdentifier(s) {
 // src/platform/build.ts
 import { createLogger, withSpan } from "@photon-ai/otel";
 
+// src/utils/markdown.ts
+import { Marked } from "marked";
+var markdownLexer = new Marked();
+var BULLET = "\u2022 ";
+var HR_LINE = "\u2014\u2014\u2014";
+var NESTED_LIST_INDENT = "  ";
+var BLOCK_SEPARATOR = "\n\n";
+var TABLE_CELL_SEPARATOR = " | ";
+var DEFAULT_LIST_START = 1;
+var asMarkedToken = (token) => token;
+var checkboxPrefix = (item) => {
+  if (!item.task) {
+    return "";
+  }
+  return item.checked ? "[x] " : "[ ] ";
+};
+var listMarker = (list, index) => {
+  if (!list.ordered) {
+    return BULLET;
+  }
+  const start = list.start === "" ? DEFAULT_LIST_START : list.start;
+  return `${start + index}. `;
+};
+var renderLink = (token) => {
+  if (token.text === token.href) {
+    return token.href;
+  }
+  return `${renderInlineTokens(token.tokens)} (${token.href})`;
+};
+var renderImage = (token) => token.text ? `${token.text} (${token.href})` : token.href;
+var renderInlineToken = (token) => {
+  switch (token.type) {
+    case "strong":
+    case "em":
+    case "del":
+      return renderInlineTokens(token.tokens);
+    case "codespan":
+      return token.text;
+    case "br":
+      return "\n";
+    case "link":
+      return renderLink(token);
+    case "image":
+      return renderImage(token);
+    case "escape":
+      return token.text;
+    case "text":
+      return token.tokens ? renderInlineTokens(token.tokens) : token.text;
+    // Raw HTML in markdown source stays literal — plain text has no markup.
+    case "html":
+      return token.text;
+    // Task-item checkboxes are rendered from `ListItem.task`/`checked`.
+    case "checkbox":
+      return "";
+    default:
+      return "raw" in token ? String(token.raw) : "";
+  }
+};
+var renderInlineTokens = (tokens) => {
+  let out = "";
+  for (const token of tokens) {
+    out += renderInlineToken(asMarkedToken(token));
+  }
+  return out;
+};
+var renderBlockquote = (quote) => renderBlockTokens(quote.tokens).split("\n").map((line) => line ? `> ${line}` : ">").join("\n");
+var renderList = (list) => {
+  const lines = [];
+  for (const [index, item] of list.items.entries()) {
+    const prefix = `${listMarker(list, index)}${checkboxPrefix(item)}`;
+    const blocks = [];
+    for (const token of item.tokens) {
+      const rendered = renderBlockToken(asMarkedToken(token));
+      if (rendered) {
+        blocks.push(rendered);
+      }
+    }
+    const [first = "", ...rest] = blocks.join("\n").split("\n");
+    lines.push(`${prefix}${first}`);
+    for (const line of rest) {
+      lines.push(`${NESTED_LIST_INDENT}${line}`);
+    }
+  }
+  return lines.join("\n");
+};
+var renderTable = (table) => {
+  const renderRow = (cells) => cells.map((cell) => renderInlineTokens(cell.tokens)).join(TABLE_CELL_SEPARATOR);
+  const lines = [renderRow(table.header)];
+  for (const row of table.rows) {
+    lines.push(renderRow(row));
+  }
+  return lines.join("\n");
+};
+var renderBlockToken = (token) => {
+  switch (token.type) {
+    case "heading":
+    case "paragraph":
+      return renderInlineTokens(token.tokens);
+    case "code":
+      return token.text;
+    case "blockquote":
+      return renderBlockquote(token);
+    case "list":
+      return renderList(token);
+    case "table":
+      return renderTable(token);
+    case "hr":
+      return HR_LINE;
+    case "space":
+    case "def":
+      return "";
+    default:
+      return renderInlineToken(token);
+  }
+};
+var renderBlockTokens = (tokens) => {
+  const blocks = [];
+  for (const token of tokens) {
+    const rendered = renderBlockToken(asMarkedToken(token));
+    if (rendered) {
+      blocks.push(rendered);
+    }
+  }
+  return blocks.join(BLOCK_SEPARATOR);
+};
+var markdownToPlainText = (markdown2) => renderBlockTokens(markdownLexer.lexer(markdown2)).trim();
+
 // src/utils/telemetry.ts
 var targetId = (target) => {
   const id = target?.id;
@@ -254,6 +437,13 @@ var replyOrEditAttrs = (content) => {
     "spectrum.message.content.inner.type": typeof innerType === "string" ? innerType : void 0
   };
 };
+var unsendAttrs = (content) => {
+  const target = content.target;
+  return {
+    "spectrum.message.content.target.id": targetId(target),
+    "spectrum.message.content.target.type": targetType(target)
+  };
+};
 var reactionAttrs = (content) => {
   const target = content.target;
   const emoji = content.emoji;
@@ -303,6 +493,7 @@ var voiceAttrs = (content) => {
 var CONTENT_ATTR_HANDLERS = {
   reply: replyOrEditAttrs,
   edit: replyOrEditAttrs,
+  unsend: unsendAttrs,
   reaction: reactionAttrs,
   group: groupAttrs,
   typing: typingAttrs,
@@ -350,11 +541,11 @@ var supportsAnsiColor = () => {
   return Boolean(process.stderr?.isTTY);
 };
 var FIRE_AND_FORGET_TYPES = /* @__PURE__ */ new Set([
-  "reaction",
   "typing",
   "edit",
   "rename",
-  "avatar"
+  "avatar",
+  "unsend"
 ]);
 var isFireAndForget = (item) => FIRE_AND_FORGET_TYPES.has(item.type) || item.__fireAndForget === true;
 var RESERVED_SPACE_KEYS = /* @__PURE__ */ new Set([
@@ -362,6 +553,7 @@ var RESERVED_SPACE_KEYS = /* @__PURE__ */ new Set([
   "id",
   "send",
   "edit",
+  "unsend",
   "getMessage",
   "rename",
   "avatar",
@@ -380,7 +572,8 @@ var RESERVED_MESSAGE_KEYS = /* @__PURE__ */ new Set([
   "reply",
   "sender",
   "space",
-  "timestamp"
+  "timestamp",
+  "unsend"
 ]);
 var scopeLabel = (scope) => {
   if (scope === "space") {
@@ -451,6 +644,102 @@ var unsupportedPlatformContentError = (content, platform) => {
     `requires ${requiredPlatform}`
   );
 };
+var findStreamText = (item) => {
+  if (item.type === "streamText") {
+    return item;
+  }
+  if ((item.type === "reply" || item.type === "edit") && item.content.type === "streamText") {
+    return item.content;
+  }
+  return;
+};
+var replaceStreamText = (item, source, full) => {
+  const inner = source.format === "markdown" ? asMarkdown(full) : asText(full);
+  if (item.type === "reply" || item.type === "edit") {
+    return { ...item, content: inner };
+  }
+  return inner;
+};
+var downgradeMarkdown = (md) => {
+  const plain = markdownToPlainText(md.markdown);
+  return plain ? asText(plain) : void 0;
+};
+var replaceMarkdown = (item) => {
+  if (item.type === "markdown") {
+    return downgradeMarkdown(item) ?? item;
+  }
+  if ((item.type === "reply" || item.type === "edit") && item.content.type === "markdown") {
+    const downgraded = downgradeMarkdown(item.content);
+    return downgraded ? { ...item, content: downgraded } : item;
+  }
+  if (item.type === "group") {
+    let changed = false;
+    const items = item.items.map((member) => {
+      if (member.content.type !== "markdown") {
+        return member;
+      }
+      const downgraded = downgradeMarkdown(member.content);
+      if (!downgraded) {
+        return member;
+      }
+      changed = true;
+      return { ...member, content: downgraded };
+    });
+    return changed ? { ...item, items } : item;
+  }
+  return item;
+};
+async function resendDrainedStream(send, item, source, platform, unsupported) {
+  platformLog.info(
+    `${platform} does not support streaming text; waiting for the stream to finish to send the full text as one message.`,
+    {
+      "spectrum.provider": platform,
+      "spectrum.stream_text.fallback": true
+    }
+  );
+  let full;
+  try {
+    full = await drainStreamText(source);
+  } catch (drainErr) {
+    if (drainErr instanceof StreamConsumedError) {
+      throw unsupported;
+    }
+    throw drainErr;
+  }
+  if (!full) {
+    throw unsupported;
+  }
+  return await sendWithFallbacks(
+    send,
+    replaceStreamText(item, source, full),
+    platform
+  );
+}
+async function sendWithFallbacks(send, item, platform) {
+  try {
+    return await send(item);
+  } catch (err) {
+    if (!(err instanceof UnsupportedError)) {
+      throw err;
+    }
+    const source = findStreamText(item);
+    if (source) {
+      return await resendDrainedStream(send, item, source, platform, err);
+    }
+    const downgraded = replaceMarkdown(item);
+    if (downgraded === item) {
+      throw err;
+    }
+    platformLog.info(
+      `${platform} does not support markdown; sending the content as plain text instead.`,
+      {
+        "spectrum.provider": platform,
+        "spectrum.markdown.fallback": true
+      }
+    );
+    return await send(downgraded);
+  }
+}
 var providerMessageCoreKeys = /* @__PURE__ */ new Set([
   "content",
   "id",
@@ -537,19 +826,21 @@ function buildSpace(params) {
         ...contentAttrs(item)
       },
       async () => {
+        const platformError = unsupportedPlatformContentError(
+          item,
+          definition.name
+        );
+        if (platformError) {
+          warnUnsupported(platformError, definition.name);
+          return;
+        }
+        const providerSend = async (content) => await definition.send({
+          ...actionCtx,
+          content
+        });
         let raw;
         try {
-          const platformError = unsupportedPlatformContentError(
-            item,
-            definition.name
-          );
-          if (platformError) {
-            throw platformError;
-          }
-          raw = await definition.send({
-            ...actionCtx,
-            content: item
-          });
+          raw = await sendWithFallbacks(providerSend, item, definition.name);
         } catch (err) {
           if (err instanceof UnsupportedError) {
             warnUnsupported(err, definition.name);
@@ -637,6 +928,9 @@ function buildSpace(params) {
     edit: async (message, newContent) => {
       await space.send(edit(newContent, message));
     },
+    unsend: async (message) => {
+      await space.send(unsend(message));
+    },
     getMessage: getMessageImpl,
     rename: async (displayName) => {
       await space.send(rename(displayName));
@@ -684,7 +978,7 @@ function buildMessage(params) {
   };
   const react = async (emoji) => {
     const target = requireBuiltMessage("react");
-    await space.send(reaction(emoji, target));
+    return await space.send(reaction(emoji, target));
   };
   async function reply2(...content) {
     const target = requireBuiltMessage("reply");
@@ -700,6 +994,15 @@ function buildMessage(params) {
     }
     await space.send(edit(newContent, target));
   };
+  const unsend2 = async () => {
+    const target = requireBuiltMessage("unsend");
+    if (target.direction !== "outbound") {
+      throw new Error(
+        `cannot unsend message ${target.id}: only outbound messages can be unsent (direction: "${target.direction}")`
+      );
+    }
+    await space.send(unsend(target));
+  };
   const buildSenderWithPlatform = () => {
     if (params.sender === void 0) {
       return;
@@ -738,6 +1041,7 @@ function buildMessage(params) {
     react,
     reply: reply2,
     edit: edit2,
+    unsend: unsend2,
     sender: senderWithPlatform,
     space,
     timestamp: params.timestamp
@@ -748,21 +1052,6 @@ function buildMessage(params) {
 
 // src/platform/define.ts
 var platformLog2 = createLogger2("spectrum.platform");
-function classifySpaceIdentifier(args) {
-  const stringArgs = args.filter((a) => typeof a === "string");
-  if (stringArgs.length > 1) {
-    return { kind: "group" };
-  }
-  const s = stringArgs[0];
-  if (!s) {
-    return { kind: "unknown" };
-  }
-  const { kind, identifier } = classifyIdentifier(s);
-  if (kind === "unknown") {
-    return { kind: "unknown" };
-  }
-  return { kind, identifier };
-}
 function buildInstanceActions(platformName, declared, reservedKeys, buildCtx) {
   const out = {};
   for (const key of PLATFORM_WISE_ACTION_KEYS) {
@@ -794,7 +1083,6 @@ function buildInstanceActions(platformName, declared, reservedKeys, buildCtx) {
   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) => {
     const resolved = await def.user.resolve({
       input: { userID },
@@ -807,105 +1095,93 @@ function createPlatformInstance(def, runtime) {
       __platform: def.name
     };
   };
-  const resolveStringUsers = async (args) => {
-    const convertArg = async (arg) => {
-      if (typeof arg === "string") {
-        return await resolveUserID(arg);
-      }
-      if (Array.isArray(arg)) {
-        return await Promise.all(arg.map(convertArg));
-      }
-      return arg;
+  const providerCtx = () => ({
+    client: runtime.client,
+    config: runtime.config,
+    store: runtime.store
+  });
+  const parseSpaceParams = (params) => params !== void 0 && def.space.params ? def.space.params.parse(params) : params;
+  const finalizeSpace = (resolved) => {
+    const parsedSpace = def.space.schema ? def.space.schema.parse(resolved) : resolved;
+    const spaceRef = {
+      ...parsedSpace,
+      id: parsedSpace.id,
+      __platform: def.name
     };
-    return await Promise.all(args.map(convertArg));
-  };
-  const normalizeSpaceArgs = (args) => {
-    if (args.length === 0) {
-      return { users: [], params: void 0 };
-    }
-    const [first, ...rest] = args;
-    if (Array.isArray(first)) {
-      return {
-        users: first,
-        params: rest[0]
-      };
-    }
-    if (!isPlatformUser(first)) {
-      return {
-        users: [],
-        params: first
-      };
-    }
-    const last = args.at(-1);
-    if (last !== void 0 && !isPlatformUser(last)) {
-      return {
-        users: args.slice(0, -1),
-        params: last
-      };
-    }
-    return {
-      users: args,
-      params: void 0
+    const actionCtx = {
+      space: spaceRef,
+      ...providerCtx()
     };
+    return buildSpace({
+      spaceRef,
+      extras: parsedSpace,
+      actionCtx,
+      definition: def,
+      client: runtime.client,
+      config: runtime.config,
+      store: runtime.store
+    });
   };
   const base = {
     async user(userID) {
-      const resolved = await def.user.resolve({
-        input: { userID },
-        client: runtime.client,
-        config: runtime.config,
-        store: runtime.store
-      });
-      return {
-        ...resolved,
-        __platform: def.name
-      };
+      return await resolveUserID(userID);
     },
-    async space(...args) {
-      const { kind, identifier } = classifySpaceIdentifier(args);
-      return withSpan2(
-        "spectrum.space.resolve",
+    space: {
+      create: async (users, params) => {
+        const userList = Array.isArray(users) ? users : [users];
+        const first = userList.length === 1 ? userList[0] : void 0;
+        const single = typeof first === "string" ? classifyIdentifier(first) : void 0;
+        const kind = userList.length > 1 ? "group" : single?.kind ?? "unknown";
+        return await withSpan2(
+          "spectrum.space.create",
+          {
+            "spectrum.provider": def.name,
+            "spectrum.space.user_count": userList.length,
+            "spectrum.space.identifier_kind": kind,
+            "spectrum.space.identifier": kind === "unknown" ? void 0 : single?.identifier
+          },
+          async () => {
+            const resolvedUsers = await Promise.all(
+              userList.map(
+                (u) => typeof u === "string" ? resolveUserID(u) : u
+              )
+            );
+            const resolved = await def.space.create({
+              input: { users: resolvedUsers, params: parseSpaceParams(params) },
+              ...providerCtx()
+            });
+            return finalizeSpace(resolved);
+          }
+        );
+      },
+      get: async (id, params) => await withSpan2(
+        "spectrum.space.get",
         {
           "spectrum.provider": def.name,
-          "spectrum.space.identifier_kind": kind,
-          "spectrum.space.identifier": identifier
+          "spectrum.space.id": id
         },
         async () => {
-          const convertedArgs = await resolveStringUsers(args);
-          const { users, params } = normalizeSpaceArgs(convertedArgs);
-          let parsedParams = params;
-          if (params !== void 0 && def.space.params) {
-            parsedParams = def.space.params.parse(params);
+          const parsedParams = parseSpaceParams(params);
+          if (def.space.get) {
+            const resolved = await def.space.get({
+              input: { id, params: parsedParams },
+              ...providerCtx()
+            });
+            return finalizeSpace(resolved);
           }
-          const resolved = await def.space.resolve({
-            input: { users, params: parsedParams },
-            client: runtime.client,
-            config: runtime.config,
-            store: runtime.store
-          });
-          const parsedSpace = def.space.schema ? def.space.schema.parse(resolved) : resolved;
-          const spaceRef = {
-            ...parsedSpace,
-            id: parsedSpace.id,
-            __platform: def.name
-          };
-          const actionCtx = {
-            space: spaceRef,
-            client: runtime.client,
-            config: runtime.config,
-            store: runtime.store
-          };
-          return buildSpace({
-            spaceRef,
-            extras: parsedSpace,
-            actionCtx,
-            definition: def,
-            client: runtime.client,
-            config: runtime.config,
-            store: runtime.store
-          });
+          const candidate = { id };
+          if (def.space.schema) {
+            const parsed = def.space.schema.safeParse(candidate);
+            if (!parsed.success) {
+              throw new Error(
+                `Platform "${def.name}" cannot construct a space from an id alone \u2014 its space schema requires more fields. Implement \`space.get\` in the "${def.name}" provider definition.`,
+                { cause: parsed.error }
+              );
+            }
+          }
+          return finalizeSpace(candidate);
         }
-      );
+      )
     }
   };
   const eventProperties = {};
@@ -1039,10 +1315,15 @@ export {
   buildPhotoAction,
   avatar,
   edit,
+  markdownSchema,
+  asMarkdown,
+  markdown,
   rename,
   reply,
   typing,
+  unsend,
   UnsupportedError,
+  renderInlineTokens,
   contentAttrs,
   senderAttrs,
   wrapProviderMessage,