@opentag/telegram 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amplift
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# @opentag/telegram
+
+Telegram message normalization and callback helpers for OpenTag.
+
+Use this package to normalize Telegram bot messages into `OpenTagEvent` objects
+and to encode or parse Telegram callback thread keys.
+
+## Install
+
+```bash
+pnpm add @opentag/telegram
+```
+
+## Exports
+
+- `normalizeTelegramMessage`: converts a Telegram message into an `OpenTagEvent`.
+- `encodeTelegramThreadKey`: encodes bot, chat, and message coordinates for callback routing.
+- `parseTelegramThreadKey`: decodes a Telegram callback thread key.
+- `renderTelegramAcknowledgement`: renders the Telegram acknowledgement body.
+- `renderTelegramFinalResult`: renders the Telegram final result body.
+- `createTelegramSendMessagePayload`: creates a Telegram Bot API `sendMessage` payload.
+
+## Example
+
+```ts
+import { normalizeTelegramMessage } from "@opentag/telegram";
+
+const event = normalizeTelegramMessage({
+  botId: "bot_123",
+  botUsername: "opentag_bot",
+  chatId: "456",
+  chatType: "private",
+  userId: "789",
+  username: "alice",
+  text: "investigate this deploy failure",
+  messageId: 101,
+  updateId: 202,
+  binding: {
+    botId: "bot_123",
+    chatId: "456",
+    repoProvider: "github",
+    owner: "acme",
+    repo: "demo"
+  }
+});
+
+if (event) {
+  // Send the event to @opentag/client or your own OpenTag-compatible control plane.
+}
+```
+
+## Stability
+
+Telegram thread key format is public because callback sinks depend on it.
+Change it only with a migration path.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./normalize.js";
+export * from "./render.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,231 @@
+// src/normalize.ts
+import { commandFromRawText } from "@opentag/core";
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function stripTelegramInvocation(input) {
+  const trimmed = input.text.trim();
+  if (!trimmed) return null;
+  if (input.chatType === "private") return trimmed;
+  const username = input.botUsername?.replace(/^@/, "");
+  const patterns = username ? [
+    new RegExp(`^@${escapeRegExp(username)}\\s+`, "i"),
+    new RegExp(`^/opentag@${escapeRegExp(username)}\\s+`, "i"),
+    /^\/opentag\s+/i
+  ] : [/^\/opentag\s+/i];
+  for (const pattern of patterns) {
+    const stripped = trimmed.replace(pattern, "").trim();
+    if (stripped !== trimmed) {
+      return stripped.length > 0 ? stripped : null;
+    }
+  }
+  return null;
+}
+function encodeTelegramThreadKey(input) {
+  return [input.botId, input.chatId, String(input.replyToMessageId), input.messageThreadId ? String(input.messageThreadId) : ""].join("|");
+}
+function parseTelegramThreadKey(threadKey) {
+  const [botId, chatId, replyToMessageIdRaw, messageThreadIdRaw] = threadKey.split("|");
+  const replyToMessageId = Number(replyToMessageIdRaw);
+  if (!botId || !chatId || !Number.isInteger(replyToMessageId) || replyToMessageId <= 0) {
+    throw new Error(`Invalid Telegram thread key: ${threadKey}`);
+  }
+  const messageThreadId = messageThreadIdRaw ? Number(messageThreadIdRaw) : void 0;
+  return {
+    botId,
+    chatId,
+    replyToMessageId,
+    ...messageThreadId && Number.isInteger(messageThreadId) && messageThreadId > 0 ? { messageThreadId } : {}
+  };
+}
+function permissionsForIntent(intent) {
+  const permissions = [
+    {
+      scope: "chat:postMessage",
+      reason: "reply in the originating Telegram thread"
+    },
+    {
+      scope: "runner:local",
+      reason: "execute the run on a paired local daemon"
+    }
+  ];
+  if (intent === "fix" || intent === "run") {
+    permissions.push(
+      {
+        scope: "repo:read",
+        reason: "inspect the repository in the paired local checkout"
+      },
+      {
+        scope: "repo:write",
+        reason: "commit code changes on an isolated run branch"
+      },
+      {
+        scope: "pr:create",
+        reason: "open a pull request for completed code changes"
+      }
+    );
+  }
+  return permissions;
+}
+function referenceTitle(reference) {
+  return reference.title ?? "Command file reference";
+}
+function contextPointersForCommand(command) {
+  const context = [];
+  for (const reference of command.parsed?.references ?? []) {
+    if (reference.kind === "url") {
+      context.push({
+        kind: "url",
+        uri: reference.uri,
+        visibility: "organization",
+        title: reference.title ?? "Command URL reference"
+      });
+      continue;
+    }
+    if (reference.kind === "file" || reference.kind === "path") {
+      context.push({
+        kind: "file",
+        uri: reference.uri,
+        ...reference.line ? { line: reference.line } : {},
+        ...reference.startLine ? { startLine: reference.startLine } : {},
+        ...reference.endLine ? { endLine: reference.endLine } : {},
+        visibility: "organization",
+        title: referenceTitle(reference)
+      });
+    }
+  }
+  return context;
+}
+function commandMetadata(command) {
+  if (!command.parsed) return {};
+  return {
+    commandParser: command.parsed.version,
+    commandDiagnostics: command.parsed.diagnostics,
+    ...command.parsed.approval ? { approval: command.parsed.approval } : {},
+    ...command.parsed.network ? { network: command.parsed.network } : {}
+  };
+}
+function normalizeTelegramMessage(input) {
+  const rawText = stripTelegramInvocation({
+    text: input.text,
+    chatType: input.chatType,
+    ...input.botUsername ? { botUsername: input.botUsername } : {}
+  });
+  if (!rawText) return null;
+  const command = commandFromRawText(rawText);
+  const agentId = input.agentId ?? "opentag";
+  return {
+    id: `evt_telegram_${input.updateId ?? `${input.botId}_${input.chatId}_${input.messageId}`}`,
+    source: "telegram",
+    sourceEventId: String(input.updateId ?? input.messageId),
+    receivedAt: input.receivedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    actor: {
+      provider: "telegram",
+      providerUserId: input.userId,
+      ...input.username ? { handle: input.username } : {}
+    },
+    target: {
+      mention: input.botUsername ? `@${input.botUsername.replace(/^@/, "")}` : "/opentag",
+      agentId,
+      ...command.parsed?.executorHint ? { executorHint: command.parsed.executorHint } : {}
+    },
+    command,
+    context: [
+      {
+        provider: "telegram",
+        kind: "message",
+        uri: `telegram://bot/${input.botId}/chat/${input.chatId}/message/${input.messageId}`,
+        visibility: "organization",
+        title: "Telegram message"
+      },
+      {
+        kind: "text",
+        uri: input.text,
+        visibility: "organization",
+        title: "Telegram message text"
+      },
+      ...contextPointersForCommand(command)
+    ],
+    permissions: permissionsForIntent(command.intent),
+    callback: {
+      provider: "telegram",
+      uri: input.callbackUri ?? "https://api.telegram.org/sendMessage",
+      threadKey: encodeTelegramThreadKey({
+        botId: input.botId,
+        chatId: input.chatId,
+        replyToMessageId: input.messageId,
+        ...input.messageThreadId ? { messageThreadId: input.messageThreadId } : {}
+      })
+    },
+    metadata: {
+      botId: input.botId,
+      chatId: input.chatId,
+      messageId: input.messageId,
+      chatType: input.chatType,
+      ...input.messageThreadId ? { messageThreadId: input.messageThreadId } : {},
+      ...input.botUsername ? { telegramBotUsername: input.botUsername.replace(/^@/, "") } : {},
+      ...commandMetadata(command),
+      repoProvider: input.binding.repoProvider ?? "github",
+      owner: input.binding.owner,
+      repo: input.binding.repo
+    }
+  };
+}
+
+// src/render.ts
+function nextActionSummary(result) {
+  if (!result.nextAction) return void 0;
+  if (typeof result.nextAction === "string") return result.nextAction;
+  return result.nextAction.summary;
+}
+function renderTelegramAcknowledgement(runId) {
+  return `I picked this up: ${runId}`;
+}
+function renderTelegramProgress(message) {
+  if (/starting claude --print|thinking/i.test(message)) {
+    return "Thinking...";
+  }
+  return "Working...";
+}
+function renderTelegramFinalResult(result) {
+  const lines = [`Finished with ${result.conclusion}.`, "", result.summary];
+  if (result.verification?.length) {
+    lines.push("", "Verification:");
+    for (const check of result.verification) {
+      lines.push(`- ${check.command}: ${check.outcome}`);
+    }
+  }
+  const nextAction = nextActionSummary(result);
+  if (nextAction) {
+    lines.push("", `Next action: ${nextAction}`);
+  }
+  return lines.join("\n");
+}
+function createTelegramSendMessagePayload(input) {
+  return {
+    chat_id: input.chatId,
+    text: input.text,
+    ...input.replyToMessageId ? { reply_to_message_id: input.replyToMessageId, allow_sending_without_reply: true } : {},
+    ...input.messageThreadId ? { message_thread_id: input.messageThreadId } : {}
+  };
+}
+function createTelegramSendMessageDraftPayload(input) {
+  return {
+    chat_id: input.chatId,
+    text: input.text,
+    draft_id: input.draftId,
+    ...input.messageThreadId ? { message_thread_id: input.messageThreadId } : {}
+  };
+}
+export {
+  createTelegramSendMessageDraftPayload,
+  createTelegramSendMessagePayload,
+  encodeTelegramThreadKey,
+  normalizeTelegramMessage,
+  parseTelegramThreadKey,
+  renderTelegramAcknowledgement,
+  renderTelegramFinalResult,
+  renderTelegramProgress,
+  stripTelegramInvocation
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/normalize.ts","../src/render.ts"],"sourcesContent":["import { commandFromRawText, type ContextPointer, type OpenTagCommand, type OpenTagEvent, type PermissionGrant } from \"@opentag/core\";\n\nexport type TelegramChannelBinding = {\n  botId: string;\n  chatId: string;\n  repoProvider?: string;\n  owner: string;\n  repo: string;\n};\n\nexport type TelegramMessageInput = {\n  botId: string;\n  botUsername?: string;\n  chatId: string;\n  chatType: \"private\" | \"group\" | \"supergroup\" | \"channel\";\n  userId: string;\n  username?: string;\n  text: string;\n  messageId: number;\n  updateId?: number;\n  messageThreadId?: number;\n  receivedAt?: string;\n  agentId?: string;\n  callbackUri?: string;\n  binding: TelegramChannelBinding;\n};\n\nfunction escapeRegExp(text: string): string {\n  return text.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n}\n\nexport function stripTelegramInvocation(input: {\n  text: string;\n  chatType: TelegramMessageInput[\"chatType\"];\n  botUsername?: string;\n}): string | null {\n  const trimmed = input.text.trim();\n  if (!trimmed) return null;\n  if (input.chatType === \"private\") return trimmed;\n\n  const username = input.botUsername?.replace(/^@/, \"\");\n  const patterns = username\n    ? [\n        new RegExp(`^@${escapeRegExp(username)}\\\\s+`, \"i\"),\n        new RegExp(`^/opentag@${escapeRegExp(username)}\\\\s+`, \"i\"),\n        /^\\/opentag\\s+/i\n      ]\n    : [/^\\/opentag\\s+/i];\n\n  for (const pattern of patterns) {\n    const stripped = trimmed.replace(pattern, \"\").trim();\n    if (stripped !== trimmed) {\n      return stripped.length > 0 ? stripped : null;\n    }\n  }\n\n  return null;\n}\n\nexport function encodeTelegramThreadKey(input: {\n  botId: string;\n  chatId: string;\n  replyToMessageId: number;\n  messageThreadId?: number;\n}): string {\n  return [input.botId, input.chatId, String(input.replyToMessageId), input.messageThreadId ? String(input.messageThreadId) : \"\"].join(\"|\");\n}\n\nexport function parseTelegramThreadKey(threadKey: string): {\n  botId: string;\n  chatId: string;\n  replyToMessageId: number;\n  messageThreadId?: number;\n} {\n  const [botId, chatId, replyToMessageIdRaw, messageThreadIdRaw] = threadKey.split(\"|\");\n  const replyToMessageId = Number(replyToMessageIdRaw);\n  if (!botId || !chatId || !Number.isInteger(replyToMessageId) || replyToMessageId <= 0) {\n    throw new Error(`Invalid Telegram thread key: ${threadKey}`);\n  }\n  const messageThreadId = messageThreadIdRaw ? Number(messageThreadIdRaw) : undefined;\n  return {\n    botId,\n    chatId,\n    replyToMessageId,\n    ...(messageThreadId && Number.isInteger(messageThreadId) && messageThreadId > 0 ? { messageThreadId } : {})\n  };\n}\n\nfunction permissionsForIntent(intent: OpenTagCommand[\"intent\"]): PermissionGrant[] {\n  const permissions: PermissionGrant[] = [\n    {\n      scope: \"chat:postMessage\",\n      reason: \"reply in the originating Telegram thread\"\n    },\n    {\n      scope: \"runner:local\",\n      reason: \"execute the run on a paired local daemon\"\n    }\n  ];\n\n  if (intent === \"fix\" || intent === \"run\") {\n    permissions.push(\n      {\n        scope: \"repo:read\",\n        reason: \"inspect the repository in the paired local checkout\"\n      },\n      {\n        scope: \"repo:write\",\n        reason: \"commit code changes on an isolated run branch\"\n      },\n      {\n        scope: \"pr:create\",\n        reason: \"open a pull request for completed code changes\"\n      }\n    );\n  }\n\n  return permissions;\n}\n\nfunction referenceTitle(reference: NonNullable<OpenTagCommand[\"parsed\"]>[\"references\"][number]): string {\n  return reference.title ?? \"Command file reference\";\n}\n\nfunction contextPointersForCommand(command: OpenTagCommand): ContextPointer[] {\n  const context: ContextPointer[] = [];\n  for (const reference of command.parsed?.references ?? []) {\n    if (reference.kind === \"url\") {\n      context.push({\n        kind: \"url\",\n        uri: reference.uri,\n        visibility: \"organization\",\n        title: reference.title ?? \"Command URL reference\"\n      });\n      continue;\n    }\n    if (reference.kind === \"file\" || reference.kind === \"path\") {\n      context.push({\n        kind: \"file\",\n        uri: reference.uri,\n        ...(reference.line ? { line: reference.line } : {}),\n        ...(reference.startLine ? { startLine: reference.startLine } : {}),\n        ...(reference.endLine ? { endLine: reference.endLine } : {}),\n        visibility: \"organization\",\n        title: referenceTitle(reference)\n      });\n    }\n  }\n  return context;\n}\n\nfunction commandMetadata(command: OpenTagCommand): Record<string, unknown> {\n  if (!command.parsed) return {};\n  return {\n    commandParser: command.parsed.version,\n    commandDiagnostics: command.parsed.diagnostics,\n    ...(command.parsed.approval ? { approval: command.parsed.approval } : {}),\n    ...(command.parsed.network ? { network: command.parsed.network } : {})\n  };\n}\n\nexport function normalizeTelegramMessage(input: TelegramMessageInput): OpenTagEvent | null {\n  const rawText = stripTelegramInvocation({\n    text: input.text,\n    chatType: input.chatType,\n    ...(input.botUsername ? { botUsername: input.botUsername } : {})\n  });\n  if (!rawText) return null;\n\n  const command = commandFromRawText(rawText);\n  const agentId = input.agentId ?? \"opentag\";\n\n  return {\n    id: `evt_telegram_${input.updateId ?? `${input.botId}_${input.chatId}_${input.messageId}`}`,\n    source: \"telegram\",\n    sourceEventId: String(input.updateId ?? input.messageId),\n    receivedAt: input.receivedAt ?? new Date().toISOString(),\n    actor: {\n      provider: \"telegram\",\n      providerUserId: input.userId,\n      ...(input.username ? { handle: input.username } : {})\n    },\n    target: {\n      mention: input.botUsername ? `@${input.botUsername.replace(/^@/, \"\")}` : \"/opentag\",\n      agentId,\n      ...(command.parsed?.executorHint ? { executorHint: command.parsed.executorHint } : {})\n    },\n    command,\n    context: [\n      {\n        provider: \"telegram\",\n        kind: \"message\",\n        uri: `telegram://bot/${input.botId}/chat/${input.chatId}/message/${input.messageId}`,\n        visibility: \"organization\",\n        title: \"Telegram message\"\n      },\n      {\n        kind: \"text\",\n        uri: input.text,\n        visibility: \"organization\",\n        title: \"Telegram message text\"\n      },\n      ...contextPointersForCommand(command)\n    ],\n    permissions: permissionsForIntent(command.intent),\n    callback: {\n      provider: \"telegram\",\n      uri: input.callbackUri ?? \"https://api.telegram.org/sendMessage\",\n      threadKey: encodeTelegramThreadKey({\n        botId: input.botId,\n        chatId: input.chatId,\n        replyToMessageId: input.messageId,\n        ...(input.messageThreadId ? { messageThreadId: input.messageThreadId } : {})\n      })\n    },\n    metadata: {\n      botId: input.botId,\n      chatId: input.chatId,\n      messageId: input.messageId,\n      chatType: input.chatType,\n      ...(input.messageThreadId ? { messageThreadId: input.messageThreadId } : {}),\n      ...(input.botUsername ? { telegramBotUsername: input.botUsername.replace(/^@/, \"\") } : {}),\n      ...commandMetadata(command),\n      repoProvider: input.binding.repoProvider ?? \"github\",\n      owner: input.binding.owner,\n      repo: input.binding.repo\n    }\n  };\n}\n","import type { OpenTagRunResult } from \"@opentag/core\";\n\nfunction nextActionSummary(result: OpenTagRunResult): string | undefined {\n  if (!result.nextAction) return undefined;\n  if (typeof result.nextAction === \"string\") return result.nextAction;\n  return result.nextAction.summary;\n}\n\nexport function renderTelegramAcknowledgement(runId: string): string {\n  return `I picked this up: ${runId}`;\n}\n\nexport function renderTelegramProgress(message: string): string {\n  if (/starting claude --print|thinking/i.test(message)) {\n    return \"Thinking...\";\n  }\n\n  return \"Working...\";\n}\n\nexport function renderTelegramFinalResult(result: OpenTagRunResult): string {\n  const lines = [`Finished with ${result.conclusion}.`, \"\", result.summary];\n\n  if (result.verification?.length) {\n    lines.push(\"\", \"Verification:\");\n    for (const check of result.verification) {\n      lines.push(`- ${check.command}: ${check.outcome}`);\n    }\n  }\n\n  const nextAction = nextActionSummary(result);\n  if (nextAction) {\n    lines.push(\"\", `Next action: ${nextAction}`);\n  }\n\n  return lines.join(\"\\n\");\n}\n\nexport type TelegramSendMessagePayload = {\n  chat_id: string;\n  text: string;\n  reply_to_message_id?: number;\n  message_thread_id?: number;\n  allow_sending_without_reply?: boolean;\n};\n\nexport type TelegramSendMessageDraftPayload = {\n  chat_id: string;\n  text: string;\n  draft_id: number;\n  message_thread_id?: number;\n};\n\nexport function createTelegramSendMessagePayload(input: {\n  chatId: string;\n  text: string;\n  replyToMessageId?: number;\n  messageThreadId?: number;\n}): TelegramSendMessagePayload {\n  return {\n    chat_id: input.chatId,\n    text: input.text,\n    ...(input.replyToMessageId ? { reply_to_message_id: input.replyToMessageId, allow_sending_without_reply: true } : {}),\n    ...(input.messageThreadId ? { message_thread_id: input.messageThreadId } : {})\n  };\n}\n\nexport function createTelegramSendMessageDraftPayload(input: {\n  chatId: string;\n  text: string;\n  draftId: number;\n  messageThreadId?: number;\n}): TelegramSendMessageDraftPayload {\n  return {\n    chat_id: input.chatId,\n    text: input.text,\n    draft_id: input.draftId,\n    ...(input.messageThreadId ? { message_thread_id: input.messageThreadId } : {})\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/normalize.d.ts

@@ -0,0 +1,43 @@
+import { type OpenTagEvent } from "@opentag/core";
+export type TelegramChannelBinding = {
+    botId: string;
+    chatId: string;
+    repoProvider?: string;
+    owner: string;
+    repo: string;
+};
+export type TelegramMessageInput = {
+    botId: string;
+    botUsername?: string;
+    chatId: string;
+    chatType: "private" | "group" | "supergroup" | "channel";
+    userId: string;
+    username?: string;
+    text: string;
+    messageId: number;
+    updateId?: number;
+    messageThreadId?: number;
+    receivedAt?: string;
+    agentId?: string;
+    callbackUri?: string;
+    binding: TelegramChannelBinding;
+};
+export declare function stripTelegramInvocation(input: {
+    text: string;
+    chatType: TelegramMessageInput["chatType"];
+    botUsername?: string;
+}): string | null;
+export declare function encodeTelegramThreadKey(input: {
+    botId: string;
+    chatId: string;
+    replyToMessageId: number;
+    messageThreadId?: number;
+}): string;
+export declare function parseTelegramThreadKey(threadKey: string): {
+    botId: string;
+    chatId: string;
+    replyToMessageId: number;
+    messageThreadId?: number;
+};
+export declare function normalizeTelegramMessage(input: TelegramMessageInput): OpenTagEvent | null;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../src/normalize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgE,KAAK,YAAY,EAAwB,MAAM,eAAe,CAAC;AAEtI,MAAM,MAAM,sBAAsB,GAAG;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,SAAS,GAAG,OAAO,GAAG,YAAY,GAAG,SAAS,CAAC;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,sBAAsB,CAAC;CACjC,CAAC;AAMF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,oBAAoB,CAAC,UAAU,CAAC,CAAC;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,MAAM,GAAG,IAAI,CAsBhB;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,MAAM,CAET;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAaA;AA2ED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,oBAAoB,GAAG,YAAY,GAAG,IAAI,CAmEzF"}

package/dist/render.d.ts

@@ -0,0 +1,30 @@
+import type { OpenTagRunResult } from "@opentag/core";
+export declare function renderTelegramAcknowledgement(runId: string): string;
+export declare function renderTelegramProgress(message: string): string;
+export declare function renderTelegramFinalResult(result: OpenTagRunResult): string;
+export type TelegramSendMessagePayload = {
+    chat_id: string;
+    text: string;
+    reply_to_message_id?: number;
+    message_thread_id?: number;
+    allow_sending_without_reply?: boolean;
+};
+export type TelegramSendMessageDraftPayload = {
+    chat_id: string;
+    text: string;
+    draft_id: number;
+    message_thread_id?: number;
+};
+export declare function createTelegramSendMessagePayload(input: {
+    chatId: string;
+    text: string;
+    replyToMessageId?: number;
+    messageThreadId?: number;
+}): TelegramSendMessagePayload;
+export declare function createTelegramSendMessageDraftPayload(input: {
+    chatId: string;
+    text: string;
+    draftId: number;
+    messageThreadId?: number;
+}): TelegramSendMessageDraftPayload;
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAQtD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAgB1E;AAED,MAAM,MAAM,0BAA0B,GAAG;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,+BAA+B,GAAG;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,wBAAgB,gCAAgC,CAAC,KAAK,EAAE;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,0BAA0B,CAO7B;AAED,wBAAgB,qCAAqC,CAAC,KAAK,EAAE;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,+BAA+B,CAOlC"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@opentag/telegram",
+  "version": "0.2.0",
+  "description": "Telegram message normalization and callback helpers for OpenTag.",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "opentag",
+    "telegram",
+    "bots",
+    "agents",
+    "webhooks"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@opentag/core": "0.2.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsup && tsc -b tsconfig.json --emitDeclarationOnly --force",
+    "lint": "tsc --noEmit"
+  }
+}