@kieksme/csp-plugin-telegram 0.0.0-stage → 0.12.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kieks.me
+
+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

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @kieksme/csp-plugin-telegram
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Eigenständiges CSP-Support-Plugin: ein Telegram-Forum-Thema je Portal-Chat, menschliche Übernahme, Antworten der zuständigen Person und manuelle Rückgabe oder Abschluss. Benötigt `chat`, PostgreSQL, einen Bot mit Themenrechten und eine private Forum-Supergruppe.
+
+Installation nach Veröffentlichung:
+
+```sh
+pnpm dlx @kieksme/csp-cli plugin add @kieksme/csp-plugin-telegram
+```
+
+Offene Webseiten verwenden `chatSupport: { "mode": "telegram", "auth": "anonymous" }`; alternativ Entra-Login. Bot-Token und Webhook-Secret gehören ausschließlich auf den API-Host. Genau ein Supporttransport je Instanz.
+
+[Einrichtung, Rechte, Architektur und Grenzen](https://github.com/kieksme/csp/wiki/telegram-support). Reale Telegram-Verbindung **noch ungetestet**; automatisierte Prüfungen verwenden synthetische Antworten.
+
+Explicit human requests use the shared persistent waiting state and directed notifications, with current support membership checks. See [shared chat behaviour](../../docs/chat.md).

package/dist/browser.d.ts

@@ -0,0 +1,8 @@
+declare const _default: {
+    id: string;
+    sdkVersion: string;
+    requires: string[];
+    sections: never[];
+};
+
+export { _default as default };

package/dist/browser.js

@@ -0,0 +1,14 @@
+import {
+  cspPlugin
+} from "./chunk-CN5ESZIH.js";
+
+// src/browser.tsx
+var browser_default = {
+  id: "telegram",
+  sdkVersion: cspPlugin.sdkVersion,
+  requires: ["chat"],
+  sections: []
+};
+export {
+  browser_default as default
+};

package/dist/chunk-CN5ESZIH.js

@@ -0,0 +1,14 @@
+// package.json
+var cspPlugin = {
+  id: "telegram",
+  sdkVersion: "^0.12.0",
+  browser: "./browser",
+  server: "./server",
+  requires: [
+    "chat"
+  ]
+};
+
+export {
+  cspPlugin
+};

package/dist/server.d.ts

@@ -0,0 +1,175 @@
+import * as _kieksme_csp_sdk from '@kieksme/csp-sdk';
+import * as zod from 'zod';
+import { z } from 'zod';
+
+declare const configSchema: z.ZodEffects<z.ZodObject<{
+    CSP_TELEGRAM_ENABLED: z.ZodDefault<z.ZodEnum<["true", "false"]>>;
+    CSP_TELEGRAM_DEMO: z.ZodDefault<z.ZodEnum<["true", "false"]>>;
+    CSP_DEMO: z.ZodOptional<z.ZodString>;
+    CSP_TELEGRAM_AUTH: z.ZodDefault<z.ZodEnum<["entra", "anonymous"]>>;
+    CSP_CHAT_SESSION_SECRET: z.ZodOptional<z.ZodString>;
+    CSP_CHAT_DATABASE_URL: z.ZodOptional<z.ZodString>;
+    CSP_CHAT_RETENTION_DAYS: z.ZodDefault<z.ZodNumber>;
+    CSP_ENTRA_TENANT_ID: z.ZodOptional<z.ZodString>;
+    CSP_ENTRA_API_AUDIENCE: z.ZodOptional<z.ZodString>;
+    CSP_ENTRA_API_SCOPE: z.ZodDefault<z.ZodString>;
+    CSP_ENTRA_PORTAL_CLIENT_ID: z.ZodOptional<z.ZodString>;
+    CSP_TELEGRAM_BOT_TOKEN: z.ZodOptional<z.ZodString>;
+    CSP_TELEGRAM_WEBHOOK_SECRET: z.ZodOptional<z.ZodString>;
+    CSP_TELEGRAM_CHAT_ID: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    CSP_TELEGRAM_SUPPORT_USER_IDS: z.ZodOptional<z.ZodPipeline<z.ZodEffects<z.ZodString, string[], string>, z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>>;
+}, "strip", z.ZodTypeAny, {
+    CSP_TELEGRAM_ENABLED: "true" | "false";
+    CSP_TELEGRAM_DEMO: "true" | "false";
+    CSP_TELEGRAM_AUTH: "entra" | "anonymous";
+    CSP_CHAT_RETENTION_DAYS: number;
+    CSP_ENTRA_API_SCOPE: string;
+    CSP_DEMO?: string | undefined;
+    CSP_CHAT_SESSION_SECRET?: string | undefined;
+    CSP_CHAT_DATABASE_URL?: string | undefined;
+    CSP_ENTRA_TENANT_ID?: string | undefined;
+    CSP_ENTRA_API_AUDIENCE?: string | undefined;
+    CSP_ENTRA_PORTAL_CLIENT_ID?: string | undefined;
+    CSP_TELEGRAM_BOT_TOKEN?: string | undefined;
+    CSP_TELEGRAM_WEBHOOK_SECRET?: string | undefined;
+    CSP_TELEGRAM_CHAT_ID?: string | undefined;
+    CSP_TELEGRAM_SUPPORT_USER_IDS?: string[] | undefined;
+}, {
+    CSP_TELEGRAM_ENABLED?: "true" | "false" | undefined;
+    CSP_TELEGRAM_DEMO?: "true" | "false" | undefined;
+    CSP_DEMO?: string | undefined;
+    CSP_TELEGRAM_AUTH?: "entra" | "anonymous" | undefined;
+    CSP_CHAT_SESSION_SECRET?: string | undefined;
+    CSP_CHAT_DATABASE_URL?: string | undefined;
+    CSP_CHAT_RETENTION_DAYS?: number | undefined;
+    CSP_ENTRA_TENANT_ID?: string | undefined;
+    CSP_ENTRA_API_AUDIENCE?: string | undefined;
+    CSP_ENTRA_API_SCOPE?: string | undefined;
+    CSP_ENTRA_PORTAL_CLIENT_ID?: string | undefined;
+    CSP_TELEGRAM_BOT_TOKEN?: string | undefined;
+    CSP_TELEGRAM_WEBHOOK_SECRET?: string | undefined;
+    CSP_TELEGRAM_CHAT_ID?: string | undefined;
+    CSP_TELEGRAM_SUPPORT_USER_IDS?: string | undefined;
+}>, {
+    CSP_TELEGRAM_ENABLED: "true" | "false";
+    CSP_TELEGRAM_DEMO: "true" | "false";
+    CSP_TELEGRAM_AUTH: "entra" | "anonymous";
+    CSP_CHAT_RETENTION_DAYS: number;
+    CSP_ENTRA_API_SCOPE: string;
+    CSP_DEMO?: string | undefined;
+    CSP_CHAT_SESSION_SECRET?: string | undefined;
+    CSP_CHAT_DATABASE_URL?: string | undefined;
+    CSP_ENTRA_TENANT_ID?: string | undefined;
+    CSP_ENTRA_API_AUDIENCE?: string | undefined;
+    CSP_ENTRA_PORTAL_CLIENT_ID?: string | undefined;
+    CSP_TELEGRAM_BOT_TOKEN?: string | undefined;
+    CSP_TELEGRAM_WEBHOOK_SECRET?: string | undefined;
+    CSP_TELEGRAM_CHAT_ID?: string | undefined;
+    CSP_TELEGRAM_SUPPORT_USER_IDS?: string[] | undefined;
+}, {
+    CSP_TELEGRAM_ENABLED?: "true" | "false" | undefined;
+    CSP_TELEGRAM_DEMO?: "true" | "false" | undefined;
+    CSP_DEMO?: string | undefined;
+    CSP_TELEGRAM_AUTH?: "entra" | "anonymous" | undefined;
+    CSP_CHAT_SESSION_SECRET?: string | undefined;
+    CSP_CHAT_DATABASE_URL?: string | undefined;
+    CSP_CHAT_RETENTION_DAYS?: number | undefined;
+    CSP_ENTRA_TENANT_ID?: string | undefined;
+    CSP_ENTRA_API_AUDIENCE?: string | undefined;
+    CSP_ENTRA_API_SCOPE?: string | undefined;
+    CSP_ENTRA_PORTAL_CLIENT_ID?: string | undefined;
+    CSP_TELEGRAM_BOT_TOKEN?: string | undefined;
+    CSP_TELEGRAM_WEBHOOK_SECRET?: string | undefined;
+    CSP_TELEGRAM_CHAT_ID?: string | undefined;
+    CSP_TELEGRAM_SUPPORT_USER_IDS?: string | undefined;
+}>;
+
+declare const _default: {
+    id: string;
+    sdkVersion: string;
+    requires: string[];
+    configSchema: zod.ZodEffects<zod.ZodObject<{
+        CSP_TELEGRAM_ENABLED: zod.ZodDefault<zod.ZodEnum<["true", "false"]>>;
+        CSP_TELEGRAM_DEMO: zod.ZodDefault<zod.ZodEnum<["true", "false"]>>;
+        CSP_DEMO: zod.ZodOptional<zod.ZodString>;
+        CSP_TELEGRAM_AUTH: zod.ZodDefault<zod.ZodEnum<["entra", "anonymous"]>>;
+        CSP_CHAT_SESSION_SECRET: zod.ZodOptional<zod.ZodString>;
+        CSP_CHAT_DATABASE_URL: zod.ZodOptional<zod.ZodString>;
+        CSP_CHAT_RETENTION_DAYS: zod.ZodDefault<zod.ZodNumber>;
+        CSP_ENTRA_TENANT_ID: zod.ZodOptional<zod.ZodString>;
+        CSP_ENTRA_API_AUDIENCE: zod.ZodOptional<zod.ZodString>;
+        CSP_ENTRA_API_SCOPE: zod.ZodDefault<zod.ZodString>;
+        CSP_ENTRA_PORTAL_CLIENT_ID: zod.ZodOptional<zod.ZodString>;
+        CSP_TELEGRAM_BOT_TOKEN: zod.ZodOptional<zod.ZodString>;
+        CSP_TELEGRAM_WEBHOOK_SECRET: zod.ZodOptional<zod.ZodString>;
+        CSP_TELEGRAM_CHAT_ID: zod.ZodOptional<zod.ZodEffects<zod.ZodString, string, string>>;
+        CSP_TELEGRAM_SUPPORT_USER_IDS: zod.ZodOptional<zod.ZodPipeline<zod.ZodEffects<zod.ZodString, string[], string>, zod.ZodArray<zod.ZodEffects<zod.ZodString, string, string>, "many">>>;
+    }, "strip", zod.ZodTypeAny, {
+        CSP_TELEGRAM_ENABLED: "true" | "false";
+        CSP_TELEGRAM_DEMO: "true" | "false";
+        CSP_TELEGRAM_AUTH: "entra" | "anonymous";
+        CSP_CHAT_RETENTION_DAYS: number;
+        CSP_ENTRA_API_SCOPE: string;
+        CSP_DEMO?: string | undefined;
+        CSP_CHAT_SESSION_SECRET?: string | undefined;
+        CSP_CHAT_DATABASE_URL?: string | undefined;
+        CSP_ENTRA_TENANT_ID?: string | undefined;
+        CSP_ENTRA_API_AUDIENCE?: string | undefined;
+        CSP_ENTRA_PORTAL_CLIENT_ID?: string | undefined;
+        CSP_TELEGRAM_BOT_TOKEN?: string | undefined;
+        CSP_TELEGRAM_WEBHOOK_SECRET?: string | undefined;
+        CSP_TELEGRAM_CHAT_ID?: string | undefined;
+        CSP_TELEGRAM_SUPPORT_USER_IDS?: string[] | undefined;
+    }, {
+        CSP_TELEGRAM_ENABLED?: "true" | "false" | undefined;
+        CSP_TELEGRAM_DEMO?: "true" | "false" | undefined;
+        CSP_DEMO?: string | undefined;
+        CSP_TELEGRAM_AUTH?: "entra" | "anonymous" | undefined;
+        CSP_CHAT_SESSION_SECRET?: string | undefined;
+        CSP_CHAT_DATABASE_URL?: string | undefined;
+        CSP_CHAT_RETENTION_DAYS?: number | undefined;
+        CSP_ENTRA_TENANT_ID?: string | undefined;
+        CSP_ENTRA_API_AUDIENCE?: string | undefined;
+        CSP_ENTRA_API_SCOPE?: string | undefined;
+        CSP_ENTRA_PORTAL_CLIENT_ID?: string | undefined;
+        CSP_TELEGRAM_BOT_TOKEN?: string | undefined;
+        CSP_TELEGRAM_WEBHOOK_SECRET?: string | undefined;
+        CSP_TELEGRAM_CHAT_ID?: string | undefined;
+        CSP_TELEGRAM_SUPPORT_USER_IDS?: string | undefined;
+    }>, {
+        CSP_TELEGRAM_ENABLED: "true" | "false";
+        CSP_TELEGRAM_DEMO: "true" | "false";
+        CSP_TELEGRAM_AUTH: "entra" | "anonymous";
+        CSP_CHAT_RETENTION_DAYS: number;
+        CSP_ENTRA_API_SCOPE: string;
+        CSP_DEMO?: string | undefined;
+        CSP_CHAT_SESSION_SECRET?: string | undefined;
+        CSP_CHAT_DATABASE_URL?: string | undefined;
+        CSP_ENTRA_TENANT_ID?: string | undefined;
+        CSP_ENTRA_API_AUDIENCE?: string | undefined;
+        CSP_ENTRA_PORTAL_CLIENT_ID?: string | undefined;
+        CSP_TELEGRAM_BOT_TOKEN?: string | undefined;
+        CSP_TELEGRAM_WEBHOOK_SECRET?: string | undefined;
+        CSP_TELEGRAM_CHAT_ID?: string | undefined;
+        CSP_TELEGRAM_SUPPORT_USER_IDS?: string[] | undefined;
+    }, {
+        CSP_TELEGRAM_ENABLED?: "true" | "false" | undefined;
+        CSP_TELEGRAM_DEMO?: "true" | "false" | undefined;
+        CSP_DEMO?: string | undefined;
+        CSP_TELEGRAM_AUTH?: "entra" | "anonymous" | undefined;
+        CSP_CHAT_SESSION_SECRET?: string | undefined;
+        CSP_CHAT_DATABASE_URL?: string | undefined;
+        CSP_CHAT_RETENTION_DAYS?: number | undefined;
+        CSP_ENTRA_TENANT_ID?: string | undefined;
+        CSP_ENTRA_API_AUDIENCE?: string | undefined;
+        CSP_ENTRA_API_SCOPE?: string | undefined;
+        CSP_ENTRA_PORTAL_CLIENT_ID?: string | undefined;
+        CSP_TELEGRAM_BOT_TOKEN?: string | undefined;
+        CSP_TELEGRAM_WEBHOOK_SECRET?: string | undefined;
+        CSP_TELEGRAM_CHAT_ID?: string | undefined;
+        CSP_TELEGRAM_SUPPORT_USER_IDS?: string | undefined;
+    }>;
+    setup(ctx: _kieksme_csp_sdk.ServerContext): Promise<void>;
+};
+
+export { configSchema, _default as default };

package/dist/server.js

@@ -0,0 +1,558 @@
+import {
+  cspPlugin
+} from "./chunk-CN5ESZIH.js";
+
+// src/server.ts
+import {
+  MemoryStore,
+  PostgresStore as PostgresStore2,
+  portalAuthenticator,
+  setupAnonymousSessions,
+  setupConversations
+} from "@kieksme/csp-core/support";
+
+// src/config.ts
+import { z } from "zod";
+var userId = z.string().regex(/^[1-9][0-9]{0,15}$/).refine((v) => Number.isSafeInteger(Number(v)));
+var configSchema = z.object({
+  CSP_TELEGRAM_ENABLED: z.enum(["true", "false"]).default("false"),
+  CSP_TELEGRAM_DEMO: z.enum(["true", "false"]).default("false"),
+  CSP_DEMO: z.string().optional(),
+  CSP_TELEGRAM_AUTH: z.enum(["entra", "anonymous"]).default("entra"),
+  CSP_CHAT_SESSION_SECRET: z.string().regex(/^[a-f0-9]{64}$/i).optional(),
+  CSP_CHAT_DATABASE_URL: z.string().url().optional(),
+  CSP_CHAT_RETENTION_DAYS: z.coerce.number().int().min(1).max(365).default(30),
+  CSP_ENTRA_TENANT_ID: z.string().uuid().optional(),
+  CSP_ENTRA_API_AUDIENCE: z.string().uuid().optional(),
+  CSP_ENTRA_API_SCOPE: z.string().min(1).default("Chat.Access"),
+  CSP_ENTRA_PORTAL_CLIENT_ID: z.string().uuid().optional(),
+  CSP_TELEGRAM_BOT_TOKEN: z.string().regex(/^[1-9][0-9]{4,15}:[A-Za-z0-9_-]{20,}$/).optional(),
+  CSP_TELEGRAM_WEBHOOK_SECRET: z.string().regex(/^[A-Za-z0-9_-]{32,256}$/).optional(),
+  CSP_TELEGRAM_CHAT_ID: z.string().regex(/^-100[0-9]{5,13}$/).refine((v) => Number.isSafeInteger(Number(v))).optional(),
+  CSP_TELEGRAM_SUPPORT_USER_IDS: z.string().transform(
+    (v) => v.split(",").map((id) => id.trim()).filter(Boolean)
+  ).pipe(z.array(userId).min(1).max(100)).optional()
+}).superRefine((c, ctx) => {
+  if (c.CSP_TELEGRAM_DEMO === "true") {
+    if (c.CSP_TELEGRAM_ENABLED === "true" || c.CSP_DEMO !== "true")
+      ctx.addIssue({
+        code: "custom",
+        message: "Support demo requires CSP_DEMO=true and CSP_TELEGRAM_ENABLED=false"
+      });
+    return;
+  }
+  if (c.CSP_TELEGRAM_ENABLED !== "true") return;
+  for (const key of [
+    "CSP_CHAT_DATABASE_URL",
+    "CSP_TELEGRAM_BOT_TOKEN",
+    "CSP_TELEGRAM_WEBHOOK_SECRET",
+    "CSP_TELEGRAM_CHAT_ID",
+    "CSP_TELEGRAM_SUPPORT_USER_IDS"
+  ]) {
+    if (!c[key])
+      ctx.addIssue({
+        code: "custom",
+        path: [key],
+        message: "Required for Telegram support"
+      });
+  }
+  for (const key of c.CSP_TELEGRAM_AUTH === "anonymous" ? ["CSP_CHAT_SESSION_SECRET"] : [
+    "CSP_ENTRA_TENANT_ID",
+    "CSP_ENTRA_API_AUDIENCE",
+    "CSP_ENTRA_PORTAL_CLIENT_ID"
+  ])
+    if (!c[key])
+      ctx.addIssue({
+        code: "custom",
+        path: [key],
+        message: "Required for Telegram authentication"
+      });
+  if (!/^postgres(?:ql)?:\/\//.test(c.CSP_CHAT_DATABASE_URL ?? ""))
+    ctx.addIssue({
+      code: "custom",
+      path: ["CSP_CHAT_DATABASE_URL"],
+      message: "Use a PostgreSQL connection URL"
+    });
+});
+
+// src/telegram.ts
+import { timingSafeEqual } from "crypto";
+import { z as z2 } from "zod";
+import {
+  action,
+  supportReply,
+  ChatError
+} from "@kieksme/csp-core/support";
+
+// src/inbox.ts
+import { PostgresStore } from "@kieksme/csp-core/support";
+var PostgresInbox = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  async init() {
+    await this.store.pool.query(`CREATE TABLE IF NOT EXISTS csp_telegram_inbox (
+      seq bigserial PRIMARY KEY, id text UNIQUE NOT NULL, conversation_id uuid NOT NULL REFERENCES csp_conversations(id) ON DELETE CASCADE,
+      body jsonb, attempts integer NOT NULL DEFAULT 0, next_at timestamptz NOT NULL DEFAULT now());`);
+  }
+  async put(job) {
+    await this.store.pool.query({
+      text: "INSERT INTO csp_telegram_inbox(id,conversation_id,body) VALUES ($1,$2,$3) ON CONFLICT(id) DO NOTHING",
+      values: [job.id, job.conversationId, job]
+    });
+  }
+  async drain(process) {
+    const rows = await this.store.pool.query(`SELECT o.* FROM csp_telegram_inbox o WHERE body IS NOT NULL AND next_at<=now()
+      AND NOT EXISTS(SELECT 1 FROM csp_telegram_inbox p WHERE p.conversation_id=o.conversation_id AND p.seq<o.seq AND p.body IS NOT NULL) ORDER BY seq LIMIT 20`);
+    for (const row of rows.rows) {
+      try {
+        await process(row.body);
+        await this.store.pool.query(
+          "UPDATE csp_telegram_inbox SET body=NULL WHERE seq=$1",
+          [row.seq]
+        );
+      } catch {
+        await this.store.pool.query(
+          "UPDATE csp_telegram_inbox SET attempts=attempts+1,next_at=now()+$2 * interval '1 second' WHERE seq=$1",
+          [row.seq, Math.min(300, 2 ** Math.min(row.attempts + 1, 8))]
+        );
+      }
+    }
+  }
+};
+function inboxFor(store) {
+  if (!(store instanceof PostgresStore))
+    throw new Error("Live Telegram support requires PostgreSQL");
+  return new PostgresInbox(store);
+}
+
+// src/telegram.ts
+var integer = z2.number().int().safe();
+var userSchema = z2.object({
+  id: integer.positive(),
+  is_bot: z2.boolean(),
+  first_name: z2.string().min(1),
+  last_name: z2.string().optional()
+});
+var chatSchema = z2.object({
+  id: integer,
+  type: z2.string(),
+  is_forum: z2.boolean().optional(),
+  username: z2.string().optional()
+});
+var messageSchema = z2.object({
+  message_id: integer.positive(),
+  date: integer.nonnegative(),
+  chat: chatSchema,
+  message_thread_id: integer.positive().optional(),
+  from: userSchema.optional(),
+  text: z2.string().max(4096).optional(),
+  sender_chat: z2.unknown().optional(),
+  forward_origin: z2.unknown().optional(),
+  via_bot: z2.unknown().optional()
+});
+var updateSchema = z2.object({
+  update_id: integer.nonnegative(),
+  message: messageSchema.optional(),
+  callback_query: z2.object({
+    id: z2.string().min(1).max(200),
+    from: userSchema,
+    data: z2.string().max(64).optional(),
+    message: messageSchema.optional()
+  }).optional()
+});
+function verifyTelegramSecret(expected, supplied) {
+  if (typeof supplied !== "string") return false;
+  const a = Buffer.from(expected), b = Buffer.from(supplied);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+function telegramApi(config, fetcher = fetch) {
+  let blockedUntil = 0;
+  return async (method, body = {}) => {
+    if (Date.now() < blockedUntil)
+      throw new Error("Telegram rate limit active");
+    let response;
+    try {
+      response = await fetcher(
+        `https://api.telegram.org/bot${config.CSP_TELEGRAM_BOT_TOKEN}/${method}`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(body),
+          signal: AbortSignal.timeout(1e4)
+        }
+      );
+    } catch {
+      throw new Error("Telegram API temporarily unavailable");
+    }
+    let data;
+    try {
+      data = await response.json();
+    } catch {
+      throw new Error("Invalid Telegram response");
+    }
+    const result = z2.object({
+      ok: z2.boolean(),
+      result: z2.unknown().optional(),
+      error_code: integer.optional(),
+      description: z2.string().optional(),
+      parameters: z2.object({ retry_after: integer.positive().optional() }).optional()
+    }).safeParse(data);
+    if (response.status === 429 || result.success && result.data.error_code === 429)
+      blockedUntil = Date.now() + Math.min(
+        86400,
+        result.success ? result.data.parameters?.retry_after ?? 60 : 60
+      ) * 1e3;
+    if (method === "editMessageText" && result.success && result.data.error_code === 400 && result.data.description === "Bad Request: message is not modified")
+      return true;
+    if (!response.ok || !result.success || !result.data.ok)
+      throw new Error("Telegram API request failed");
+    return result.data.result;
+  };
+}
+function chunks(text, limit) {
+  const result = [];
+  let part = "";
+  for (const char of text) {
+    if (part.length + char.length > limit) {
+      result.push(part);
+      part = "";
+    }
+    part += char;
+  }
+  if (part) result.push(part);
+  return result;
+}
+function card(c) {
+  const status = c.status === "bot" || c.status === "waiting" ? c.status === "waiting" ? "Pers\xF6nlicher Support angefragt \xB7 KI pausiert" : "Digitaler Assistent" : c.status === "closed" ? c.resolution ? "Problem gel\xF6st" : "Abgeschlossen" : `Support: ${c.support?.name}`;
+  return {
+    text: `Portal-Support
+Portal-Nutzer: ${c.owner.name}
+Gespr\xE4ch: ${c.id}
+Status: ${status}`,
+    reply_markup: {
+      inline_keyboard: c.status === "closed" ? [] : [
+        (c.status === "bot" || c.status === "waiting" ? [
+          ["take", "\xDCbernehmen"],
+          ["resolve", "Problem gel\xF6st"]
+        ] : [
+          ["release", "An Bot zur\xFCckgeben"],
+          ["close", "Abschlie\xDFen"],
+          ["resolve", "Problem gel\xF6st"]
+        ]).map(([id, text]) => ({ text, callback_data: `${id}:${c.id}` }))
+      ]
+    }
+  };
+}
+function supportAuthorizer(config, api) {
+  return async (id) => {
+    if (!config.CSP_TELEGRAM_SUPPORT_USER_IDS?.includes(id)) return;
+    const member = z2.object({
+      status: z2.string(),
+      is_member: z2.boolean().optional(),
+      user: userSchema
+    }).parse(
+      await api("getChatMember", {
+        chat_id: config.CSP_TELEGRAM_CHAT_ID,
+        user_id: Number(id)
+      })
+    );
+    if (String(member.user.id) !== id || member.user.is_bot || !(["creator", "administrator", "member"].includes(member.status) || member.status === "restricted" && member.is_member === true))
+      return;
+    return {
+      id: `telegram:${config.CSP_TELEGRAM_CHAT_ID}:${id}`,
+      name: [member.user.first_name, member.user.last_name].filter(Boolean).join(" ").slice(0, 200)
+    };
+  };
+}
+async function createTelegramBridge(app, store, config, fetcher = fetch, onTake = () => {
+}, inbox = inboxFor(store)) {
+  const api = telegramApi(config, fetcher), authorize = supportAuthorizer(config, api), channel = `telegram:${config.CSP_TELEGRAM_CHAT_ID}`;
+  const bot = userSchema.parse(await api("getMe"));
+  if (!bot.is_bot) throw new Error("Telegram identity must be a bot");
+  const chat = chatSchema.parse(
+    await api("getChat", { chat_id: config.CSP_TELEGRAM_CHAT_ID })
+  );
+  if (String(chat.id) !== config.CSP_TELEGRAM_CHAT_ID || chat.type !== "supergroup" || chat.username || !chat.is_forum)
+    throw new Error("Telegram support requires a forum supergroup");
+  const rights = z2.object({
+    status: z2.literal("administrator"),
+    can_manage_topics: z2.literal(true),
+    user: userSchema
+  }).safeParse(
+    await api("getChatMember", {
+      chat_id: config.CSP_TELEGRAM_CHAT_ID,
+      user_id: bot.id
+    })
+  );
+  if (!rights.success || rights.data.user.id !== bot.id)
+    throw new Error("Telegram bot requires administrator topic permissions");
+  await inbox.init();
+  let working = false, closing = false;
+  const answer = async (job, text) => {
+    if (job.callbackId)
+      await api("answerCallbackQuery", {
+        callback_query_id: job.callbackId,
+        text,
+        show_alert: true
+      }).catch(() => {
+      });
+  };
+  const process = async (job) => {
+    const person = await authorize(job.user);
+    if (!person) {
+      await answer(
+        job,
+        "Keine Supportberechtigung. Freigabe und Gruppenmitgliedschaft sind erforderlich."
+      );
+      return;
+    }
+    try {
+      const taken = await store.change(job.conversationId, (c, queue) => {
+        if (c.thread?.conversationId !== channel || c.thread.rootId !== job.rootId || c.seen.includes(job.id))
+          return false;
+        const receivedAt = job.receivedAt ?? Date.now();
+        if (c.thread.lastUpdateAt && receivedAt - c.thread.lastUpdateAt > 7 * 864e5) {
+          c.supportActionAt = -1;
+          if (c.status === "support") c.supportSince = -1;
+        }
+        c.thread.lastUpdateAt = Math.max(
+          c.thread.lastUpdateAt ?? 0,
+          receivedAt
+        );
+        if (job.action) {
+          if (job.timestamp <= (c.supportActionAt ?? -1)) return false;
+          if (!["close", "resolve"].includes(job.action) && c.messages.length >= 500)
+            throw new ChatError(
+              409,
+              "Gespr\xE4chslimit erreicht. Bitte abschlie\xDFen."
+            );
+          const transition = job.action === "take" && (c.status === "bot" || c.status === "waiting") || job.action === "resolve" && c.status !== "closed";
+          action(c, job.action, person, queue);
+          c.supportActionAt = job.timestamp;
+          if (job.action === "take" && transition)
+            c.supportSince = job.timestamp;
+          c.seen.push(job.id);
+          return transition;
+        }
+        if (job.timestamp > (c.supportSince ?? Infinity))
+          supportReply(c, person, job.id, job.text ?? "", queue);
+        return false;
+      });
+      if (taken) onTake(job.conversationId);
+      await answer(job, "Support-Aktion verarbeitet.");
+    } catch (error) {
+      if (!(error instanceof ChatError)) throw error;
+      await answer(job, error.message);
+      if (!job.callbackId && job.text)
+        await api("sendMessage", {
+          chat_id: config.CSP_TELEGRAM_CHAT_ID,
+          message_thread_id: Number(job.rootId),
+          text: `Support-Antwort nicht weitergeleitet: ${error.message}`,
+          link_preview_options: { is_disabled: true }
+        }).catch(() => {
+        });
+    }
+  };
+  const worker = async () => {
+    if (working || closing) return;
+    working = true;
+    try {
+      await inbox.drain(process);
+    } catch {
+    } finally {
+      working = false;
+    }
+  };
+  const interval = setInterval(() => void worker(), 1e3);
+  app.post(
+    "/api/telegram/webhook",
+    {
+      bodyLimit: 131072,
+      onRequest: async (req) => {
+        if (!verifyTelegramSecret(
+          config.CSP_TELEGRAM_WEBHOOK_SECRET,
+          req.headers["x-telegram-bot-api-secret-token"]
+        ))
+          throw new ChatError(401, "Ung\xFCltiges Telegram-Webhook-Secret");
+      }
+    },
+    async (req, reply) => {
+      reply.header("Cache-Control", "no-store");
+      const parsed = updateSchema.safeParse(req.body);
+      if (!parsed.success)
+        throw new ChatError(400, "Ung\xFCltiges Telegram-Update");
+      const p = parsed.data, callback = p.callback_query, m = callback?.message ?? p.message, user = callback?.from ?? m?.from;
+      if (!m || !user || user.is_bot || m.sender_chat !== void 0 || m.forward_origin !== void 0 || m.via_bot !== void 0 || !m.message_thread_id || m.chat.type !== "supergroup" || String(m.chat.id) !== config.CSP_TELEGRAM_CHAT_ID)
+        return { ok: true };
+      const c = await store.findThread(channel, String(m.message_thread_id));
+      if (!c) return { ok: true };
+      let command;
+      if (callback) {
+        const match = /^(take|release|close|resolve):([a-f0-9-]{36})$/.exec(
+          callback.data ?? ""
+        );
+        if (!match || match[2] !== c.id || String(m.message_id) !== c.thread?.serviceUrl && String(m.message_id) !== c.supportRequest?.messageId || m.from?.id !== bot.id)
+          return { ok: true };
+        command = match[1];
+      } else if (!m.text?.trim()) return { ok: true };
+      await inbox.put({
+        id: `update:${p.update_id}`,
+        conversationId: c.id,
+        rootId: String(m.message_thread_id),
+        user: String(user.id),
+        timestamp: p.update_id,
+        receivedAt: Date.now(),
+        action: command,
+        text: callback ? void 0 : m.text,
+        callbackId: callback?.id
+      });
+      void worker();
+      return { ok: true };
+    }
+  );
+  app.addHook("preClose", async () => {
+    closing = true;
+    clearInterval(interval);
+  });
+  return {
+    async send(job, c) {
+      if (job.kind === "create" && !c.thread) {
+        const topic = z2.object({ message_thread_id: integer.positive() }).parse(
+          await api("createForumTopic", {
+            chat_id: config.CSP_TELEGRAM_CHAT_ID,
+            name: chunks(`Support ${c.owner.name}`, 128)[0]
+          })
+        );
+        await store.change(c.id, (current) => {
+          current.thread = {
+            conversationId: channel,
+            rootId: String(topic.message_thread_id)
+          };
+        });
+        c = await store.get(c.id);
+      }
+      if (!c.thread || c.thread.conversationId !== channel)
+        throw new Error("Telegram topic missing");
+      const base = {
+        chat_id: config.CSP_TELEGRAM_CHAT_ID,
+        message_thread_id: Number(c.thread.rootId)
+      };
+      if (job.kind === "request") {
+        if (c.status !== "waiting" || c.supportRequest?.id !== job.id || c.supportRequest.messageId)
+          return;
+        const targets = [];
+        for (const id of job.targets ?? []) {
+          const person = await authorize(id);
+          if (person) targets.push({ id, name: person.name });
+        }
+        const names = targets.map((p) => p.name).join(", ");
+        const text = names + (names ? ": " : "") + "Pers\xF6nlicher Support angefragt. Bitte \xFCbernehmen.";
+        let offset = 0;
+        const entities = targets.map((p) => {
+          const entity = {
+            type: "text_mention",
+            offset,
+            length: p.name.length,
+            user: { id: Number(p.id) }
+          };
+          offset += p.name.length + 2;
+          return entity;
+        });
+        const result = z2.object({ message_id: integer.positive() }).parse(
+          await api("sendMessage", {
+            ...base,
+            text,
+            entities,
+            reply_markup: card(c).reply_markup,
+            link_preview_options: { is_disabled: true }
+          })
+        );
+        await store.change(c.id, (current) => {
+          if (current.supportRequest?.id === job.id)
+            current.supportRequest.messageId = String(result.message_id);
+        });
+      } else if (job.kind === "create" || job.kind === "card") {
+        if (c.thread.serviceUrl) {
+          await api("editMessageText", {
+            chat_id: base.chat_id,
+            message_id: Number(c.thread.serviceUrl),
+            ...card(c)
+          });
+        } else {
+          const result = z2.object({ message_id: integer.positive() }).parse(await api("sendMessage", { ...base, ...card(c) }));
+          await store.change(c.id, (current) => {
+            current.thread.serviceUrl = String(result.message_id);
+          });
+        }
+      } else if (job.message) {
+        const m = job.message, text = `${m.kind === "user" ? c.owner.name : m.kind === "bot" ? "Digitaler Assistent" : m.name ?? "Support"}
+${m.content}`;
+        for (const part of chunks(text, 3500))
+          await api("sendMessage", {
+            ...base,
+            text: part,
+            link_preview_options: { is_disabled: true }
+          });
+      }
+    },
+    async close() {
+      closing = true;
+      clearInterval(interval);
+      while (working) await new Promise((resolve) => setTimeout(resolve, 20));
+    },
+    drain: worker
+  };
+}
+
+// src/server.ts
+var server_default = {
+  id: "telegram",
+  sdkVersion: cspPlugin.sdkVersion,
+  requires: ["chat"],
+  configSchema,
+  async setup(ctx) {
+    const c = configSchema.parse(ctx.env), demo = c.CSP_TELEGRAM_DEMO === "true";
+    if (c.CSP_TELEGRAM_ENABLED !== "true" && !demo) {
+      if (ctx.config.chatSupport)
+        throw new Error(
+          "Profile requires support, but runtime support is disabled"
+        );
+      return;
+    }
+    if (ctx.config.chatSupport?.mode !== (demo ? "demo" : "telegram"))
+      throw new Error("Frontend and runtime support modes differ");
+    const anonymous = c.CSP_TELEGRAM_AUTH === "anonymous";
+    if (!demo && anonymous !== (ctx.config.chatSupport.auth === "anonymous"))
+      throw new Error("Frontend and runtime authentication modes differ");
+    if (!demo && !anonymous && (ctx.config.chatSupport.tenantId !== c.CSP_ENTRA_TENANT_ID || ctx.config.chatSupport.clientId !== c.CSP_ENTRA_PORTAL_CLIENT_ID || ctx.config.chatSupport.scope !== `api://${c.CSP_ENTRA_API_AUDIENCE}/${c.CSP_ENTRA_API_SCOPE}`))
+      throw new Error("Entra frontend and API configuration differ");
+    const store = demo ? new MemoryStore() : new PostgresStore2(c.CSP_CHAT_DATABASE_URL);
+    const authenticate = demo ? async () => ({
+      tenantId: "demo",
+      userId: "demo-user",
+      name: "Portal-Nutzer Demo"
+    }) : anonymous ? setupAnonymousSessions(ctx, c.CSP_CHAT_SESSION_SECRET) : portalAuthenticator(
+      c.CSP_ENTRA_TENANT_ID,
+      c.CSP_ENTRA_API_AUDIENCE,
+      c.CSP_ENTRA_API_SCOPE
+    );
+    try {
+      await setupConversations(
+        ctx,
+        store,
+        authenticate,
+        demo,
+        (onTake) => createTelegramBridge(ctx.app, store, c, ctx.fetch, onTake)
+      );
+    } catch (e) {
+      await store.close();
+      throw e;
+    }
+  }
+};
+export {
+  configSchema,
+  server_default as default
+};

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@kieksme/csp-plugin-telegram",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.12.0",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@kieksme/csp-sdk": "^0.12.0",
+    "@kieksme/csp-core": "^0.12.0",
+    "zod": "^3.25.76",
+    "fastify": "^5.6.1"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "cspPlugin": {
+    "id": "telegram",
+    "sdkVersion": "^0.12.0",
+    "browser": "./browser",
+    "server": "./server",
+    "requires": [
+      "chat"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kieksme/csp.git",
+    "directory": "packages/plugin-telegram"
+  },
+  "bugs": {
+    "url": "https://github.com/kieksme/csp/issues"
+  },
+  "scripts": {
+    "build": "tsup src/browser.tsx src/server.ts --format esm --dts --clean --external @kieksme/csp-sdk --external react --external react-dom"
+  }
 }