spectrum-ts 2.0.0 → 3.1.0

package/dist/{chunk-2ILTJC35.js → chunk-LQMDV75O.js}

@@ -195,16 +195,202 @@ function custom(raw) {
 }
 
 // src/content/text.ts
+import z5 from "zod";
+
+// src/content/stream-text.ts
 import z4 from "zod";
-var textSchema = z4.object({
-  type: z4.literal("text"),
-  text: z4.string().nonempty()
+var streamTextSchema = z4.object({
+  type: z4.literal("streamText"),
+  // A single-consumption producer of normalized text deltas. The builder
+  // closes over the normalized source; the platform driver calls it once.
+  // Kept opaque to Zod via `z.custom` (same approach as `attachment.read`).
+  stream: z4.custom(
+    (v) => typeof v === "function",
+    {
+      message: "streamText.stream must be a function returning AsyncIterable<string>"
+    }
+  ),
+  // How platforms should interpret the accumulated text; absent = plain.
+  format: z4.enum(["plain", "markdown"]).optional()
 });
-var asText = (text2) => textSchema.parse({ type: "text", text: text2 });
-function text(text2) {
+var asRecord = (value) => typeof value === "object" && value !== null ? value : void 0;
+var SKIP_EVENT_TYPES = /* @__PURE__ */ new Set([
+  "message_start",
+  "message_delta",
+  "message_stop",
+  "content_block_start",
+  "content_block_stop",
+  "ping"
+]);
+var fromOpenAIResponses = (obj) => {
+  const type = obj.type;
+  if (typeof type !== "string" || !type.startsWith("response.")) {
+    return;
+  }
+  if (type === "response.output_text.delta" && typeof obj.delta === "string") {
+    return obj.delta;
+  }
+  return null;
+};
+var fromAnthropicDelta = (obj) => {
+  if (obj.type !== "content_block_delta") {
+    return;
+  }
+  const delta = asRecord(obj.delta);
+  if (delta?.type === "text_delta" && typeof delta.text === "string") {
+    return delta.text;
+  }
+  return null;
+};
+var fromAiSdkPart = (obj) => {
+  if (obj.type !== "text-delta") {
+    return;
+  }
+  if (typeof obj.textDelta === "string") {
+    return obj.textDelta;
+  }
+  return typeof obj.text === "string" ? obj.text : null;
+};
+var fromOpenAIChat = (obj) => {
+  if (!Array.isArray(obj.choices)) {
+    return;
+  }
+  const delta = asRecord(asRecord(obj.choices[0])?.delta);
+  const content = delta?.content;
+  return typeof content === "string" ? content : null;
+};
+var fromControlEvent = (obj) => typeof obj.type === "string" && SKIP_EVENT_TYPES.has(obj.type) ? null : void 0;
+var OBJECT_EXTRACTORS = [
+  fromOpenAIResponses,
+  fromAnthropicDelta,
+  fromAiSdkPart,
+  fromOpenAIChat,
+  fromControlEvent
+];
+var defaultExtract = (chunk) => {
+  if (typeof chunk === "string") {
+    return chunk;
+  }
+  const record = asRecord(chunk);
+  if (!record) {
+    throw new Error(
+      `text stream: cannot extract a text delta from a ${typeof chunk} chunk. Pass { extract } to map your stream's chunks to text.`
+    );
+  }
+  for (const extractor of OBJECT_EXTRACTORS) {
+    const result = extractor(record);
+    if (result !== void 0) {
+      return result;
+    }
+  }
+  throw new Error(
+    `text stream: unrecognized chunk shape (type=${String(record.type)}). Pass an { extract } function to map your provider's chunk to a text delta.`
+  );
+};
+var isReadableStream = (value) => typeof value?.getReader === "function";
+var isAsyncIterable = (value) => typeof value?.[Symbol.asyncIterator] === "function";
+async function* readableToAsync(source) {
+  if (isAsyncIterable(source)) {
+    yield* source;
+    return;
+  }
+  const reader = source.getReader();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        return;
+      }
+      yield value;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+var resolveChunkIterable = (source) => {
+  const textStream = source.textStream;
+  if (textStream != null) {
+    if (isReadableStream(textStream)) {
+      return readableToAsync(textStream);
+    }
+    if (isAsyncIterable(textStream)) {
+      return textStream;
+    }
+    throw new Error(
+      "text stream: `.textStream` must be an AsyncIterable or a ReadableStream."
+    );
+  }
+  if (isReadableStream(source)) {
+    return readableToAsync(source);
+  }
+  if (isAsyncIterable(source)) {
+    return source;
+  }
+  throw new Error(
+    "text stream: source must be an AsyncIterable, a ReadableStream, or an object with a `.textStream` (e.g. the AI SDK streamText() result)."
+  );
+};
+var StreamConsumedError = class extends Error {
+  constructor() {
+    super(
+      "text stream: this source has already been consumed \u2014 a stream can only be sent once."
+    );
+    this.name = "StreamConsumedError";
+  }
+};
+var normalize = (source, options) => {
+  const extract = options?.extract ? options.extract : defaultExtract;
+  let consumed = false;
+  return async function* normalized() {
+    if (consumed) {
+      throw new StreamConsumedError();
+    }
+    consumed = true;
+    for await (const chunk of resolveChunkIterable(source)) {
+      const delta = extract(chunk);
+      if (delta) {
+        yield delta;
+      }
+    }
+  };
+};
+var asStreamText = (input) => streamTextSchema.parse({
+  type: "streamText",
+  stream: input.stream,
+  ...input.format ? { format: input.format } : {}
+});
+var drainStreamText = async (content) => {
+  let full = "";
+  for await (const delta of content.stream()) {
+    full += delta;
+  }
+  return full;
+};
+var streamTextBuilder = (kind, source, options) => {
+  if (typeof source.build === "function") {
+    throw new Error(
+      `${kind}(): pass the stream source itself (an AsyncIterable, a ReadableStream, or an SDK result with .textStream), not another content builder.`
+    );
+  }
   return {
-    build: async () => asText(text2)
+    build: async () => asStreamText({
+      stream: normalize(source, options),
+      format: kind === "markdown" ? "markdown" : void 0
+    })
   };
+};
+
+// src/content/text.ts
+var textSchema = z5.object({
+  type: z5.literal("text"),
+  text: z5.string().nonempty()
+});
+var asText = (text2) => textSchema.parse({ type: "text", text: text2 });
+function text(source, options) {
+  if (typeof source === "string") {
+    return { build: async () => asText(source) };
+  }
+  return streamTextBuilder("text", source, options);
 }
 
 // src/content/resolve.ts
@@ -213,12 +399,12 @@ var resolveContents = (items) => Promise.all(
 );
 
 // src/content/reaction.ts
-import z5 from "zod";
+import z6 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.custom(isMessage, {
+var reactionSchema = z6.object({
+  type: z6.literal("reaction"),
+  emoji: z6.string().min(1),
+  target: z6.custom(isMessage, {
     message: "reaction target must be a Message"
   })
 });
@@ -226,6 +412,11 @@ var asReaction = (input) => reactionSchema.parse({ type: "reaction", ...input })
 function reaction(emoji, target) {
   return {
     build: async () => {
+      if (!target) {
+        throw new Error(
+          "reaction() target is undefined \u2014 the targeted message was never sent (space.send resolves undefined when a platform skips unsupported content)"
+        );
+      }
       if (target.content.type === "reaction") {
         throw new Error('reaction() cannot target "reaction" content');
       }
@@ -250,6 +441,9 @@ export {
   attachment,
   asCustom,
   custom,
+  StreamConsumedError,
+  drainStreamText,
+  streamTextBuilder,
   textSchema,
   asText,
   text,

package/dist/{chunk-3B4QH4JG.js → chunk-MHGCPC2V.js}

@@ -1,7 +1,7 @@
 import { createRequire as __spectrumCreateRequire } from "node:module"; const require = __spectrumCreateRequire(import.meta.url);
 import {
   resolveContents
-} from "./chunk-2ILTJC35.js";
+} from "./chunk-LQMDV75O.js";
 
 // src/content/group.ts
 import z from "zod";

package/dist/{chunk-U7AWXDH6.js → chunk-NZ5WCMTY.js}

@@ -4,7 +4,7 @@ import {
 } from "./chunk-6UZFVXQF.js";
 import {
   readSchema
-} from "./chunk-2ILTJC35.js";
+} from "./chunk-LQMDV75O.js";
 
 // src/content/contact.ts
 import vCard from "vcf";

package/dist/{chunk-5LT5J3NR.js → chunk-PSSWQBOH.js}

@@ -4,23 +4,25 @@ import {
 } from "./chunk-34FQGGD7.js";
 import {
   asGroup
-} from "./chunk-3B4QH4JG.js";
+} from "./chunk-MHGCPC2V.js";
 import {
   asVoice
-} from "./chunk-NNY6LMSC.js";
+} from "./chunk-77U6SH5A.js";
 import {
   toVCard
 } from "./chunk-6UZFVXQF.js";
 import {
   UnsupportedError,
-  definePlatform
-} from "./chunk-NGC4DJIX.js";
+  asMarkdown,
+  definePlatform,
+  renderInlineTokens
+} from "./chunk-L3NUESOW.js";
 import {
   asAttachment,
   asCustom,
   asReaction,
   asText
-} from "./chunk-2ILTJC35.js";
+} from "./chunk-LQMDV75O.js";
 
 // src/providers/telegram/config.ts
 import z from "zod";
@@ -361,6 +363,167 @@ var stripVariationSelector = (emoji) => emoji.replace(VARIATION_SELECTOR_16, "")
 var isAllowedReactionEmoji = (emoji) => ALLOWED_REACTION_EMOJI.has(stripVariationSelector(emoji));
 var normalizeReactionEmoji = (emoji) => isAllowedReactionEmoji(emoji) ? stripVariationSelector(emoji) : emoji;
 
+// src/providers/telegram/outbound/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 AMP_PATTERN = /&/g;
+var LT_PATTERN = /</g;
+var GT_PATTERN = />/g;
+var QUOTE_PATTERN = /"/g;
+var escapeHtml = (value) => value.replace(AMP_PATTERN, "&amp;").replace(LT_PATTERN, "&lt;").replace(GT_PATTERN, "&gt;");
+var escapeAttribute = (value) => escapeHtml(value).replace(QUOTE_PATTERN, "&quot;");
+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 escapeHtml(token.href);
+  }
+  return `<a href="${escapeAttribute(token.href)}">${renderInlineTokens2(token.tokens)}</a>`;
+};
+var renderImage = (token) => `<a href="${escapeAttribute(token.href)}">${escapeHtml(token.text || token.href)}</a>`;
+var renderText = (token) => {
+  if (token.tokens) {
+    return renderInlineTokens2(token.tokens);
+  }
+  return token.escaped ? token.text : escapeHtml(token.text);
+};
+var renderInlineToken = (token) => {
+  switch (token.type) {
+    case "strong":
+      return `<b>${renderInlineTokens2(token.tokens)}</b>`;
+    case "em":
+      return `<i>${renderInlineTokens2(token.tokens)}</i>`;
+    case "del":
+      return `<s>${renderInlineTokens2(token.tokens)}</s>`;
+    case "codespan":
+      return `<code>${escapeHtml(token.text)}</code>`;
+    case "br":
+      return "\n";
+    case "link":
+      return renderLink(token);
+    case "image":
+      return renderImage(token);
+    case "escape":
+      return escapeHtml(token.text);
+    case "text":
+      return renderText(token);
+    // Raw HTML in markdown source renders literally, never passes through:
+    // a tag outside Telegram's whitelist would 400 the whole Bot API call
+    // (a TelegramApiError, not UnsupportedError — the plain-text fallback
+    // would not catch it). Escaping makes invalid output impossible.
+    case "html":
+      return escapeHtml(token.text);
+    // Task-item checkboxes are rendered from `ListItem.task`/`checked`.
+    case "checkbox":
+      return "";
+    default:
+      return "raw" in token ? escapeHtml(String(token.raw)) : "";
+  }
+};
+var renderInlineTokens2 = (tokens) => {
+  let out = "";
+  for (const token of tokens) {
+    out += renderInlineToken(asMarkedToken(token));
+  }
+  return out;
+};
+var renderCode = (token) => {
+  if (token.lang) {
+    return `<pre><code class="language-${escapeAttribute(token.lang)}">${escapeHtml(token.text)}</code></pre>`;
+  }
+  return `<pre>${escapeHtml(token.text)}</pre>`;
+};
+var renderQuoteBody = (tokens) => {
+  const blocks = [];
+  for (const token of tokens) {
+    const marked = asMarkedToken(token);
+    const rendered = marked.type === "blockquote" ? renderQuoteBody(marked.tokens) : renderBlockToken(marked);
+    if (rendered) {
+      blocks.push(rendered);
+    }
+  }
+  return blocks.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 `<pre>${escapeHtml(lines.join("\n"))}</pre>`;
+};
+var renderBlockToken = (token) => {
+  switch (token.type) {
+    // Telegram has no headings; bold is the conventional stand-in.
+    case "heading":
+      return `<b>${renderInlineTokens2(token.tokens)}</b>`;
+    case "paragraph":
+      return renderInlineTokens2(token.tokens);
+    case "code":
+      return renderCode(token);
+    case "blockquote":
+      return `<blockquote>${renderQuoteBody(token.tokens)}</blockquote>`;
+    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 markdownToTelegramHtml = (markdown) => {
+  const blocks = [];
+  for (const token of markdownLexer.lexer(markdown)) {
+    const rendered = renderBlockToken(asMarkedToken(token));
+    if (rendered) {
+      blocks.push(rendered);
+    }
+  }
+  return blocks.join(BLOCK_SEPARATOR).trim();
+};
+
 // src/providers/telegram/outbound/message.ts
 var VCARD_FILENAME = "contact.vcf";
 var VCARD_MIME = "text/vcard";
@@ -420,6 +583,14 @@ var buildSend = async (content) => {
   switch (content.type) {
     case "text":
       return { method: "sendMessage", params: { text: content.text } };
+    case "markdown":
+      return {
+        method: "sendMessage",
+        params: {
+          text: markdownToTelegramHtml(content.markdown),
+          parse_mode: "HTML"
+        }
+      };
     case "richlink":
       return { method: "sendMessage", params: { text: content.url } };
     case "attachment":
@@ -467,8 +638,70 @@ var buildSend = async (content) => {
   }
 };
 
-// src/providers/telegram/outbound/send.ts
+// src/providers/telegram/outbound/stream-text.ts
+import { sendMessageDraft } from "@photon-ai/telegram-ts";
 var MILLIS_PER_SECOND2 = 1e3;
+var DRAFT_THROTTLE_MS = 500;
+var nextDraftId = 1;
+var sendStreamText = async (client, space, content) => {
+  const chatId = Number(space.id);
+  if (!(Number.isInteger(chatId) && chatId > 0)) {
+    throw UnsupportedError.content(
+      "streamText",
+      TELEGRAM_PLATFORM,
+      `message drafts work only in private chats (got chat id "${space.id}").`
+    );
+  }
+  const draftId = nextDraftId;
+  nextDraftId += 1;
+  const renderBody = (text) => content.format === "markdown" ? { text: markdownToTelegramHtml(text), parse_mode: "HTML" } : { text };
+  let lastDraftText;
+  let lastDraftAt = 0;
+  let draftsAvailable = true;
+  const updateDraft = async (text) => {
+    if (!draftsAvailable || text === lastDraftText) {
+      return;
+    }
+    try {
+      await sendMessageDraft({
+        body: { chat_id: chatId, draft_id: draftId, ...renderBody(text) },
+        client
+      });
+      lastDraftText = text;
+      lastDraftAt = Date.now();
+    } catch {
+      draftsAvailable = false;
+    }
+  };
+  await updateDraft("");
+  let full = "";
+  for await (const delta of content.stream()) {
+    full += delta;
+    if (Date.now() - lastDraftAt >= DRAFT_THROTTLE_MS) {
+      await updateDraft(full);
+    }
+  }
+  if (!full) {
+    throw UnsupportedError.content(
+      "streamText",
+      TELEGRAM_PLATFORM,
+      "stream produced no text \u2014 nothing to send."
+    );
+  }
+  const sent = await executeSpec(client, {
+    method: "sendMessage",
+    params: { chat_id: space.id, ...renderBody(full) }
+  });
+  return {
+    id: String(sent.message_id),
+    content: content.format === "markdown" ? asMarkdown(full) : asText(full),
+    space: { id: space.id },
+    timestamp: new Date(sent.date * MILLIS_PER_SECOND2)
+  };
+};
+
+// src/providers/telegram/outbound/send.ts
+var MILLIS_PER_SECOND3 = 1e3;
 var sendContent = async (client, space, content) => {
   const spec = await buildSend(content);
   const sent = await executeSpec(client, {
@@ -479,7 +712,7 @@ var sendContent = async (client, space, content) => {
     id: String(sent.message_id),
     content,
     space: { id: space.id },
-    timestamp: new Date(sent.date * MILLIS_PER_SECOND2)
+    timestamp: new Date(sent.date * MILLIS_PER_SECOND3)
   };
 };
 var sendGroup = async (client, space, items) => {
@@ -508,7 +741,14 @@ var sendReaction = async (client, space, content) => {
     },
     client
   });
-  return;
+  const timestamp = /* @__PURE__ */ new Date();
+  const unixSeconds = Math.floor(timestamp.getTime() / MILLIS_PER_SECOND3);
+  return {
+    id: `reaction:${space.id}:${messageId}:${unixSeconds}:bot:${emoji}`,
+    content,
+    space: { id: space.id },
+    timestamp
+  };
 };
 var sendTyping = async (client, space, state) => {
   if (state === "start") {
@@ -520,18 +760,23 @@ var sendTyping = async (client, space, state) => {
   return;
 };
 var sendEdit = async (client, space, content) => {
-  if (content.content.type !== "text") {
+  const inner = content.content;
+  if (inner.type !== "text" && inner.type !== "markdown") {
     throw UnsupportedError.content(
       "edit",
       TELEGRAM_PLATFORM,
-      `only text content can be edited (got "${content.content.type}").`
+      `only text and markdown content can be edited (got "${inner.type}").`
     );
   }
+  const body = inner.type === "markdown" ? {
+    text: markdownToTelegramHtml(inner.markdown),
+    parse_mode: "HTML"
+  } : { text: inner.text };
   await editMessageText({
     body: {
       chat_id: space.id,
       message_id: parseMessageId(content.target.id),
-      text: content.content.text
+      ...body
     },
     client
   });
@@ -552,6 +797,8 @@ var send = async ({
       return await sendEdit(client, space, content);
     case "group":
       return await sendGroup(client, space, content.items);
+    case "streamText":
+      return await sendStreamText(client, space, content);
     case "poll":
     case "poll_option":
     case "effect":
@@ -564,36 +811,21 @@ var send = async ({
 };
 
 // src/providers/telegram/space.ts
-import z2 from "zod";
-var spaceParamsSchema = z2.object({
-  /**
-   * Target a chat directly by id. Telegram chat ids are numbers in the wire
-   * format (negative for groups/supergroups); accept either form and store as
-   * a string. For a private chat the id equals the user's id.
-   */
-  chatId: z2.union([z2.string().min(1), z2.number()]).optional()
-});
 var resolveUser = ({
   input
 }) => Promise.resolve({ id: input.userID });
-var resolveSpace = ({
+var createSpace = ({
   input
 }) => {
-  const chatId = input.params?.chatId;
-  if (chatId !== void 0) {
-    return Promise.resolve({ id: String(chatId) });
-  }
   const [first, ...rest] = input.users;
   if (first && rest.length === 0) {
     return Promise.resolve({ id: first.id });
   }
   if (!first) {
-    throw new Error(
-      "Telegram space creation requires params.chatId or a single recipient user."
-    );
+    throw new Error("Telegram space creation requires a recipient user.");
   }
   throw new Error(
-    "Telegram bots cannot create group chats \u2014 pass params.chatId for an existing chat, or resolve a single user (their private chat)."
+    "Telegram bots cannot create group chats \u2014 use space.get(chatId) for an existing chat, or create a space with a single user (their private chat)."
   );
 };
 
@@ -685,7 +917,7 @@ var telegram = definePlatform(TELEGRAM_PLATFORM, {
     }
   },
   user: { resolve: resolveUser },
-  space: { params: spaceParamsSchema, resolve: resolveSpace },
+  space: { create: createSpace },
   messages: handleMessages,
   send
 });