@valuya/telegram-bot-channel 0.2.0-beta.1

package/.env.concierge.example

@@ -0,0 +1,20 @@
+HOST=0.0.0.0
+PORT=8792
+VALUYA_BASE=https://pay.gorilla.build
+VALUYA_TENANT_TOKEN=ttok_example
+TELEGRAM_LINKS_FILE=.data/telegram-links.json
+TELEGRAM_CHANNEL_APP_ID=telegram_main
+TELEGRAM_CHANNEL_RESOURCE=telegram:channel:concierge_demo
+TELEGRAM_CHANNEL_PLAN=standard
+TELEGRAM_CHANNEL_BOT=concierge_demo_bot
+TELEGRAM_CHANNEL_NAME=Premium Concierge
+TELEGRAM_CHANNEL_INVITE_URL=https://t.me/concierge_demo_bot
+TELEGRAM_CHANNEL_MODE=agent
+TELEGRAM_CHANNEL_MEMORY_FILE=.data/telegram-concierge-memory.json
+TELEGRAM_CHANNEL_SOUL_ID=concierge
+TELEGRAM_CHANNEL_SOUL_NAME=Premium Concierge
+TELEGRAM_CHANNEL_SOUL_LOCALE=de
+TELEGRAM_CHANNEL_SOUL_SYSTEM_PROMPT=Du bist ein diskreter, hilfreicher Premium-Concierge und hilfst dem Nutzer, passende Optionen schnell und angenehm zu finden.
+TELEGRAM_CHANNEL_SOUL_RESPONSE_SCHEMA_JSON={"format":"json","replyKey":"concierge_reply","followUpQuestionKey":"clarifying_question","followUpQuestionsKey":"option_questions","nextStepKey":"recommended_next_step","summaryKey":"preference_summary","userProfileKey":"user_preferences","rootPatternKey":"decision_style"}
+OPENAI_API_KEY=sk-...
+OPENAI_MODEL=gpt-4.1-mini

package/.env.example

@@ -0,0 +1,27 @@
+HOST=0.0.0.0
+PORT=8792
+
+VALUYA_BASE=https://pay.gorilla.build
+VALUYA_TENANT_TOKEN=ttok_example
+
+TELEGRAM_LINKS_FILE=.data/telegram-links.json
+TELEGRAM_CHANNEL_APP_ID=telegram_main
+TELEGRAM_CHANNEL_RESOURCE=telegram:channel:mentor_demo
+TELEGRAM_CHANNEL_PLAN=standard
+TELEGRAM_CHANNEL_BOT=mentor_demo_bot
+TELEGRAM_CHANNEL_NAME=Mentor Demo
+TELEGRAM_CHANNEL_INVITE_URL=https://t.me/mentor_demo_bot
+
+TELEGRAM_CHANNEL_MODE=agent
+TELEGRAM_CHANNEL_HUMAN_REPLY=Danke. Ein Mensch aus dem Team meldet sich hier bei dir.
+TELEGRAM_CHANNEL_INTERNAL_API_TOKEN=internal_demo_token
+
+TELEGRAM_CHANNEL_MEMORY_FILE=.data/telegram-channel-memory.json
+TELEGRAM_CHANNEL_SOUL_ID=mentor
+TELEGRAM_CHANNEL_SOUL_NAME=Mentor
+TELEGRAM_CHANNEL_SOUL_LOCALE=de
+TELEGRAM_CHANNEL_SOUL_SYSTEM_PROMPT=Du bist ein ruhiger, klarer Mentor und hilfst dem Nutzer, sein eigentliches Thema besser zu verstehen.
+TELEGRAM_CHANNEL_SOUL_RESPONSE_SCHEMA_JSON={"format":"json","replyKey":"mentor_reply","followUpQuestionKey":"deep_question","followUpQuestionsKey":"follow_up_questions","nextStepKey":"next_step","summaryKey":"conversation_summary","userProfileKey":"user_profile","rootPatternKey":"root_pattern"}
+
+OPENAI_API_KEY=sk-...
+OPENAI_MODEL=gpt-4.1-mini

package/.env.mentor.example

@@ -0,0 +1,20 @@
+HOST=0.0.0.0
+PORT=8792
+VALUYA_BASE=https://pay.gorilla.build
+VALUYA_TENANT_TOKEN=ttok_example
+TELEGRAM_LINKS_FILE=.data/telegram-links.json
+TELEGRAM_CHANNEL_APP_ID=telegram_main
+TELEGRAM_CHANNEL_RESOURCE=telegram:channel:mentor_demo
+TELEGRAM_CHANNEL_PLAN=standard
+TELEGRAM_CHANNEL_BOT=mentor_demo_bot
+TELEGRAM_CHANNEL_NAME=Mentor Demo
+TELEGRAM_CHANNEL_INVITE_URL=https://t.me/mentor_demo_bot
+TELEGRAM_CHANNEL_MODE=agent
+TELEGRAM_CHANNEL_MEMORY_FILE=.data/telegram-channel-memory.json
+TELEGRAM_CHANNEL_SOUL_ID=mentor
+TELEGRAM_CHANNEL_SOUL_NAME=Mentor
+TELEGRAM_CHANNEL_SOUL_LOCALE=de
+TELEGRAM_CHANNEL_SOUL_SYSTEM_PROMPT=Du bist ein ruhiger, klarer Mentor und hilfst dem Nutzer, die Wurzel seines Themas besser zu verstehen.
+TELEGRAM_CHANNEL_SOUL_RESPONSE_SCHEMA_JSON={"format":"json","replyKey":"mentor_reply","followUpQuestionKey":"deep_question","followUpQuestionsKey":"follow_up_questions","nextStepKey":"next_step","summaryKey":"conversation_summary","userProfileKey":"user_profile","rootPatternKey":"root_pattern"}
+OPENAI_API_KEY=sk-...
+OPENAI_MODEL=gpt-4.1-mini

package/.env.support.example

@@ -0,0 +1,20 @@
+HOST=0.0.0.0
+PORT=8792
+VALUYA_BASE=https://pay.gorilla.build
+VALUYA_TENANT_TOKEN=ttok_example
+TELEGRAM_LINKS_FILE=.data/telegram-links.json
+TELEGRAM_CHANNEL_APP_ID=telegram_main
+TELEGRAM_CHANNEL_RESOURCE=telegram:channel:support_demo
+TELEGRAM_CHANNEL_PLAN=standard
+TELEGRAM_CHANNEL_BOT=support_demo_bot
+TELEGRAM_CHANNEL_NAME=Premium Support
+TELEGRAM_CHANNEL_INVITE_URL=https://t.me/support_demo_bot
+TELEGRAM_CHANNEL_MODE=agent
+TELEGRAM_CHANNEL_MEMORY_FILE=.data/telegram-support-memory.json
+TELEGRAM_CHANNEL_SOUL_ID=support
+TELEGRAM_CHANNEL_SOUL_NAME=Premium Support
+TELEGRAM_CHANNEL_SOUL_LOCALE=de
+TELEGRAM_CHANNEL_SOUL_SYSTEM_PROMPT=Du bist ein klarer Premium-Support-Assistent und hilfst dem Nutzer, das Problem ruhig und loesungsorientiert zu klaeren.
+TELEGRAM_CHANNEL_SOUL_RESPONSE_SCHEMA_JSON={"format":"json","replyKey":"support_reply","followUpQuestionKey":"clarifying_question","nextStepKey":"next_step","summaryKey":"case_summary","userProfileKey":"customer_context","rootPatternKey":"issue_pattern"}
+OPENAI_API_KEY=sk-...
+OPENAI_MODEL=gpt-4.1-mini

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valuya
+
+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,56 @@
+# @valuya/telegram-bot-channel
+
+`@valuya/telegram-bot-channel` is the Telegram companion to `@valuya/whatsapp-bot-channel`.
+
+It provides a first concrete gated Telegram channel example with:
+
+- Guard-gated access
+- human or agent moderation
+- schema-driven soul responses
+- persistent conversational memory
+- app-layer link interception for `/start <token>` and `LINK <token>`
+- a simple internal message server entrypoint
+
+This package builds on `@valuya/telegram-channel-access`.
+
+## Main pieces
+
+- `TelegramBotChannel`
+- `TelegramBotChannelApp`
+- `GuardTelegramChannelLinkResolver`
+- `SchemaDrivenSoulRuntime`
+- `FileSoulMemoryStore`
+- `server.ts`
+
+## Quick Start
+
+1. Start from [`.env.example`](/home/colt/Software/valuya-guard/packages/telegram-bot-channel/.env.example).
+2. Set the Guard values:
+   - `VALUYA_BASE`
+   - `VALUYA_TENANT_TOKEN`
+   - `TELEGRAM_CHANNEL_APP_ID`
+   - `TELEGRAM_CHANNEL_RESOURCE`
+3. Choose:
+   - `TELEGRAM_CHANNEL_MODE=human`
+   - or `TELEGRAM_CHANNEL_MODE=agent`
+4. If `agent`, set:
+   - `OPENAI_API_KEY`
+   - `TELEGRAM_CHANNEL_SOUL_SYSTEM_PROMPT`
+   - optional `TELEGRAM_CHANNEL_SOUL_RESPONSE_SCHEMA_JSON`
+5. Start it from the package folder:
+   - `pnpm start`
+6. Or use the repo-level launcher:
+   - `pnpm gated-channel:launch --channel telegram --preset mentor --slug mentor_demo`
+
+## Typical Uses
+
+- paid mentor or coach bot
+- premium Telegram community entrypoint
+- gated human Q&A channel
+- agent-moderated support channel
+
+## Starter Template
+
+For the reusable rollout model, see:
+- [gated-channel-starter-template.md](/home/colt/Software/valuya-guard/docs/gated-channel-starter-template.md)
+- [gated-channel-demo-presets.md](/home/colt/Software/valuya-guard/docs/gated-channel-demo-presets.md)

package/dist/app/TelegramBotChannelApp.d.ts

@@ -0,0 +1,19 @@
+import type { TelegramBotChannel } from "../runtime/TelegramBotChannel.js";
+import type { GuardTelegramChannelLinkResolver } from "../linking/GuardTelegramChannelLinkResolver.js";
+export declare class TelegramBotChannelApp {
+    private readonly deps;
+    private readonly app;
+    constructor(deps: {
+        channel: TelegramBotChannel;
+        linkResolver: GuardTelegramChannelLinkResolver;
+    });
+    handleInboundMessage(args: {
+        telegramUserId: string;
+        body: string;
+        telegramUsername?: string;
+        locale?: string;
+    }): Promise<{
+        reply: string;
+        metadata?: Record<string, unknown>;
+    }>;
+}

package/dist/app/TelegramBotChannelApp.js

@@ -0,0 +1,35 @@
+import { BotChannelApp, extractLinkCommandToken, extractTelegramStartToken, } from "@valuya/bot-channel-app-core";
+function extractTelegramLinkToken(body) {
+    return extractTelegramStartToken(body) || extractLinkCommandToken(body);
+}
+export class TelegramBotChannelApp {
+    deps;
+    app;
+    constructor(deps) {
+        this.deps = deps;
+        this.app = new BotChannelApp({
+            channel: deps.channel,
+            linkResolver: deps.linkResolver,
+            extractLinkToken: (args) => extractTelegramLinkToken(args.body),
+            buildLinkArgs: (args, linkToken) => ({
+                telegramUserId: args.telegramUserId,
+                linkToken,
+                telegramUsername: args.telegramUsername,
+            }),
+            buildChannelArgs: (args) => args,
+            getChannelReply: (result) => result.reply,
+            getChannelMetadata: (result) => ({
+                kind: result.kind,
+                ...(result.kind === "agent" ? { soulId: result.soulId } : {}),
+            }),
+            getLinkMetadata: (result) => ({
+                linkAttempt: true,
+                linked: result.linked,
+                ...(result.code ? { code: result.code } : {}),
+            }),
+        });
+    }
+    async handleInboundMessage(args) {
+        return this.app.handleInboundMessage(args);
+    }
+}

package/dist/domain/types.d.ts

@@ -0,0 +1,13 @@
+import type { ChannelMode, MemoryStore, SoulDefinition, SoulResponse, SoulRuntime, TelegramChannelAccessConfig } from "@valuya/telegram-channel-access";
+import type { ChannelSoulDefinition as CoreChannelSoulDefinition, SoulResponseSchema as CoreSoulResponseSchema, StructuredCompletionResult as CoreStructuredCompletionResult, StructuredCompletionRunner as CoreStructuredCompletionRunner } from "@valuya/bot-channel-core";
+export type SoulResponseSchema = CoreSoulResponseSchema;
+export type ChannelSoulDefinition = SoulDefinition & CoreChannelSoulDefinition;
+export type StructuredCompletionResult = CoreStructuredCompletionResult | SoulResponse;
+export type StructuredCompletionRunner = CoreStructuredCompletionRunner;
+export type TelegramBotChannelConfig = TelegramChannelAccessConfig & {
+    mode?: ChannelMode;
+    souls?: ChannelSoulDefinition[];
+    memoryStore?: MemoryStore;
+    soulRuntime?: SoulRuntime;
+    humanReply?: string;
+};

package/dist/domain/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { TelegramBotChannel } from "./runtime/TelegramBotChannel.js";
+export { SchemaDrivenSoulRuntime } from "./runtime/SchemaDrivenSoulRuntime.js";
+export { FileSoulMemoryStore } from "./memory/FileSoulMemoryStore.js";
+export { createMentorSoulDefinition } from "./souls/createMentorSoulDefinition.js";
+export { TelegramBotChannelApp } from "./app/TelegramBotChannelApp.js";
+export { GuardTelegramChannelLinkResolver } from "./linking/GuardTelegramChannelLinkResolver.js";
+export type { ChannelSoulDefinition, SoulResponseSchema, StructuredCompletionResult, StructuredCompletionRunner, TelegramBotChannelConfig, } from "./domain/types.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { TelegramBotChannel } from "./runtime/TelegramBotChannel.js";
+export { SchemaDrivenSoulRuntime } from "./runtime/SchemaDrivenSoulRuntime.js";
+export { FileSoulMemoryStore } from "./memory/FileSoulMemoryStore.js";
+export { createMentorSoulDefinition } from "./souls/createMentorSoulDefinition.js";
+export { TelegramBotChannelApp } from "./app/TelegramBotChannelApp.js";
+export { GuardTelegramChannelLinkResolver } from "./linking/GuardTelegramChannelLinkResolver.js";

package/dist/linking/GuardTelegramChannelLinkResolver.d.ts

@@ -0,0 +1,32 @@
+import type { TelegramLinkResolver } from "@valuya/telegram-channel-access";
+export declare class GuardTelegramChannelLinkResolver implements TelegramLinkResolver {
+    private readonly service;
+    constructor(args: {
+        baseUrl: string;
+        tenantToken: string;
+        channelAppId: string;
+        linksFile: string;
+        redeemedFrom?: string;
+    });
+    ensureLinkedForPaymentAction(args: {
+        telegramUserId: string;
+        telegramUsername?: string;
+    }): Promise<{
+        allowed: true;
+        subject: import("./GuardTelegramLinkService.js").LinkedValuyaSubject;
+        link: import("./TelegramLinkStore.js").StoredTelegramChannelLink;
+    } | {
+        allowed: false;
+        reply: string;
+        code: import("./GuardTelegramLinkService.js").LinkErrorCode;
+    }>;
+    redeemLinkToken(args: {
+        telegramUserId: string;
+        linkToken: string;
+        telegramUsername?: string;
+    }): Promise<{
+        linked: boolean;
+        code?: string;
+        reply: string;
+    }>;
+}

package/dist/linking/GuardTelegramChannelLinkResolver.js

@@ -0,0 +1,37 @@
+import { GuardTelegramLinkService } from "./GuardTelegramLinkService.js";
+import { TelegramLinkStore } from "./TelegramLinkStore.js";
+export class GuardTelegramChannelLinkResolver {
+    service;
+    constructor(args) {
+        const linkStore = new TelegramLinkStore(args.linksFile);
+        this.service = new GuardTelegramLinkService({
+            baseUrl: args.baseUrl,
+            tenantToken: args.tenantToken,
+            channelAppId: args.channelAppId,
+            linkStore,
+            redeemedFrom: args.redeemedFrom || "telegram_bot_channel",
+        });
+    }
+    async ensureLinkedForPaymentAction(args) {
+        return this.service.ensureLinkedForPaymentAction(args);
+    }
+    async redeemLinkToken(args) {
+        const result = await this.service.redeemLinkToken(args);
+        if (!result.linked) {
+            return {
+                linked: false,
+                code: result.code,
+                reply: result.message,
+            };
+        }
+        return {
+            linked: true,
+            reply: [
+                "Konto erfolgreich verknuepft.",
+                "",
+                "Dein Zugang fuer diesen Telegram-Channel ist jetzt aktiv.",
+                "Schreib mir einfach ganz normal. Wenn der Channel agent-moderiert ist, antworte ich dir direkt hier.",
+            ].join("\n"),
+        };
+    }
+}

package/dist/linking/GuardTelegramLinkService.d.ts

@@ -0,0 +1,60 @@
+import type { StoredTelegramChannelLink, TelegramLinkStore } from "./TelegramLinkStore.js";
+export type LinkErrorCode = "invalid_token" | "token_expired" | "token_already_used" | "tenant_mismatch" | "not_linked" | "guard_unavailable";
+export type LinkedValuyaSubject = {
+    type: string;
+    externalId: string;
+    subjectId?: string;
+    privyUserId?: string;
+    linkedWalletAddress?: string;
+};
+export type LinkResult = {
+    linked: true;
+    source: "redeem" | "resolve" | "resolve_after_redeem_failure" | "local_cache";
+    subject: LinkedValuyaSubject;
+    link: StoredTelegramChannelLink;
+} | {
+    linked: false;
+    code: LinkErrorCode;
+    message: string;
+};
+type LogFn = (event: string, fields: Record<string, unknown>) => void;
+export declare class GuardTelegramLinkService {
+    private readonly baseUrl;
+    private readonly tenantToken;
+    private readonly channelAppId;
+    private readonly redeemedFrom;
+    private readonly linkStore;
+    private readonly log;
+    constructor(args: {
+        baseUrl: string;
+        tenantToken: string;
+        channelAppId: string;
+        linkStore: TelegramLinkStore;
+        redeemedFrom?: string;
+        logger?: LogFn;
+    });
+    redeemLinkToken(args: {
+        telegramUserId: string;
+        linkToken: string;
+        telegramUsername?: string;
+    }): Promise<LinkResult>;
+    resolveLinkedSubject(args: {
+        telegramUserId: string;
+        telegramUsername?: string;
+    }): Promise<LinkResult>;
+    ensureLinkedForPaymentAction(args: {
+        telegramUserId: string;
+        telegramUsername?: string;
+    }): Promise<{
+        allowed: true;
+        subject: LinkedValuyaSubject;
+        link: StoredTelegramChannelLink;
+    } | {
+        allowed: false;
+        reply: string;
+        code: LinkErrorCode;
+    }>;
+    private post;
+    private persistLink;
+}
+export {};

package/dist/linking/GuardTelegramLinkService.js

@@ -0,0 +1,303 @@
+export class GuardTelegramLinkService {
+    baseUrl;
+    tenantToken;
+    channelAppId;
+    redeemedFrom;
+    linkStore;
+    log;
+    constructor(args) {
+        this.baseUrl = args.baseUrl.replace(/\/+$/, "");
+        this.tenantToken = args.tenantToken;
+        this.channelAppId = args.channelAppId;
+        this.linkStore = args.linkStore;
+        this.redeemedFrom = args.redeemedFrom?.trim() || "telegram_bot_channel";
+        this.log = args.logger || (() => { });
+    }
+    async redeemLinkToken(args) {
+        const telegramUserId = normalizeTelegramUserId(args.telegramUserId);
+        const linkToken = String(args.linkToken || "").trim();
+        if (!linkToken) {
+            return {
+                linked: false,
+                code: "invalid_token",
+                message: "Invalid link token. Please use the latest onboarding link.",
+            };
+        }
+        try {
+            const env = await this.post("guard_telegram_redeem_response", "/api/guard/channels/telegram/redeem", {
+                link_token: linkToken,
+                channel_user_id: telegramUserId,
+                channel_username: cleanOptional(args.telegramUsername),
+                redeemed_from: this.redeemedFrom,
+            });
+            const persisted = await this.persistLink(telegramUserId, args.telegramUsername, env.link);
+            if (!persisted) {
+                return {
+                    linked: false,
+                    code: "guard_unavailable",
+                    message: "Could not confirm link result. Please try again.",
+                };
+            }
+            return {
+                linked: true,
+                source: "redeem",
+                subject: toLinkedSubject(persisted),
+                link: persisted,
+            };
+        }
+        catch (error) {
+            const guardError = toGuardError(error);
+            if (guardError.code === "token_already_used") {
+                const resolved = await this.resolveLinkedSubject({
+                    telegramUserId,
+                    telegramUsername: args.telegramUsername,
+                });
+                if (resolved.linked) {
+                    return {
+                        linked: true,
+                        source: "resolve_after_redeem_failure",
+                        subject: resolved.subject,
+                        link: resolved.link,
+                    };
+                }
+            }
+            return {
+                linked: false,
+                code: guardError.code,
+                message: guardError.message,
+            };
+        }
+    }
+    async resolveLinkedSubject(args) {
+        const telegramUserId = normalizeTelegramUserId(args.telegramUserId);
+        try {
+            const env = await this.post("guard_telegram_resolve_response", "/api/guard/channels/telegram/resolve", {
+                channel_user_id: telegramUserId,
+                channel_app_id: this.channelAppId,
+            });
+            const persisted = await this.persistLink(telegramUserId, args.telegramUsername, env.link);
+            if (!persisted || persisted.status !== "linked") {
+                return {
+                    linked: false,
+                    code: "not_linked",
+                    message: buildUnlinkedMessage(),
+                };
+            }
+            return {
+                linked: true,
+                source: "resolve",
+                subject: toLinkedSubject(persisted),
+                link: persisted,
+            };
+        }
+        catch (error) {
+            const guardError = toGuardError(error);
+            return {
+                linked: false,
+                code: guardError.code,
+                message: guardError.message,
+            };
+        }
+    }
+    async ensureLinkedForPaymentAction(args) {
+        const telegramUserId = normalizeTelegramUserId(args.telegramUserId);
+        const local = await this.linkStore.getChannelLink(telegramUserId);
+        if (isLinked(local)) {
+            return {
+                allowed: true,
+                subject: toLinkedSubject(local),
+                link: local,
+            };
+        }
+        const resolved = await this.resolveLinkedSubject({
+            telegramUserId,
+            telegramUsername: args.telegramUsername,
+        });
+        if (resolved.linked) {
+            return {
+                allowed: true,
+                subject: resolved.subject,
+                link: resolved.link,
+            };
+        }
+        const reply = resolved.code === "not_linked"
+            ? buildUnlinkedMessage()
+            : `I could not verify your Valuya link (${resolved.code}). Please retry.`;
+        return {
+            allowed: false,
+            reply,
+            code: resolved.code,
+        };
+    }
+    async post(eventName, path, body) {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json",
+                Authorization: `Bearer ${this.tenantToken}`,
+            },
+            body: JSON.stringify(body),
+        });
+        const payload = (await safeParseJson(response));
+        this.log(eventName, {
+            tenant: tenantRef(this.tenantToken),
+            path,
+            status: response.status,
+            ok: response.ok && payload?.ok !== false,
+            error_code: payload?.code || payload?.error || null,
+        });
+        if (!response.ok || payload?.ok === false) {
+            throw toGuardApiError(response.status, payload);
+        }
+        return payload;
+    }
+    async persistLink(telegramUserId, telegramUsername, link) {
+        const status = String(link?.status || "").trim() || "unlinked";
+        const normalizedWallet = normalizeWallet(link?.wallet_address);
+        const subjectType = String(link?.subject?.type || "").trim();
+        const subjectExternalId = String(link?.subject?.external_id || "").trim();
+        const protocolSubjectHeader = normalizeProtocolSubjectHeader(link?.protocol_subject?.header);
+        const parsedProtocolSubject = parseProtocolSubjectHeader(protocolSubjectHeader);
+        const protocolSubjectType = cleanOptional(link?.protocol_subject?.type) || parsedProtocolSubject?.type;
+        const protocolSubjectId = stringOrUndefined(link?.protocol_subject?.id) || parsedProtocolSubject?.id;
+        const channelAppId = String(link?.channel_app_id || this.channelAppId).trim();
+        if (status === "linked" && (!protocolSubjectHeader || !parsedProtocolSubject || !normalizedWallet)) {
+            return null;
+        }
+        return this.linkStore.upsertChannelLink(telegramUserId, {
+            telegram_user_id: telegramUserId,
+            telegram_username: cleanOptional(telegramUsername),
+            tenant_id: stringOrUndefined(link?.tenant_id),
+            channel_app_id: channelAppId,
+            valuya_subject_id: stringOrUndefined(link?.subject_id),
+            valuya_subject_type: subjectType || undefined,
+            valuya_subject_external_id: subjectExternalId || undefined,
+            valuya_privy_user_id: cleanOptional(link?.privy_user_id),
+            valuya_linked_wallet_address: normalizedWallet,
+            valuya_privy_wallet_id: cleanOptional(link?.privy_wallet_id),
+            valuya_protocol_subject_type: protocolSubjectType,
+            valuya_protocol_subject_id: protocolSubjectId,
+            valuya_protocol_subject_header: cleanOptional(protocolSubjectHeader),
+            status,
+            linked_at: status === "linked" ? new Date().toISOString() : undefined,
+        });
+    }
+}
+function buildUnlinkedMessage() {
+    return [
+        "Your Telegram account is not linked to Valuya yet.",
+        "Please open your latest onboarding link to Telegram and run /start again.",
+    ].join("\n");
+}
+function toLinkedSubject(link) {
+    const protocolSubject = requireProtocolSubject(link);
+    return {
+        type: protocolSubject.type,
+        externalId: protocolSubject.id,
+        ...(link.valuya_subject_id ? { subjectId: link.valuya_subject_id } : {}),
+        ...(link.valuya_privy_user_id ? { privyUserId: link.valuya_privy_user_id } : {}),
+        ...(link.valuya_linked_wallet_address ? { linkedWalletAddress: link.valuya_linked_wallet_address } : {}),
+    };
+}
+function isLinked(link) {
+    if (!link)
+        return false;
+    return (link.status === "linked" &&
+        parseProtocolSubjectHeader(link.valuya_protocol_subject_header || "") !== null &&
+        Boolean(link.valuya_linked_wallet_address?.trim()));
+}
+class GuardApiError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+function toGuardApiError(status, payload) {
+    const backendCode = `${payload?.code || payload?.error || payload?.message || ""}`.toLowerCase();
+    if (status === 404 || backendCode.includes("not_linked")) {
+        return new GuardApiError("not_linked", buildUnlinkedMessage());
+    }
+    if (backendCode.includes("invalid") || backendCode.includes("malformed")) {
+        return new GuardApiError("invalid_token", "Invalid link token. Please use the latest onboarding link.");
+    }
+    if (backendCode.includes("expired")) {
+        return new GuardApiError("token_expired", "This link token has expired. Please restart onboarding.");
+    }
+    if (backendCode.includes("already") || backendCode.includes("used")) {
+        return new GuardApiError("token_already_used", "This link token was already used. Open your latest onboarding link and retry.");
+    }
+    if (backendCode.includes("tenant_mismatch")) {
+        return new GuardApiError("tenant_mismatch", "This onboarding link belongs to a different tenant. Generate a new link for this bot and retry.");
+    }
+    return new GuardApiError("guard_unavailable", "Valuya Guard is currently unavailable. Please retry.");
+}
+function toGuardError(error) {
+    if (error instanceof GuardApiError)
+        return error;
+    const message = error instanceof Error ? error.message : String(error);
+    return new GuardApiError("guard_unavailable", `Valuya Guard is currently unavailable. (${message})`);
+}
+async function safeParseJson(response) {
+    const text = await response.text();
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { message: text };
+    }
+}
+function cleanOptional(input) {
+    const value = String(input || "").trim();
+    return value || undefined;
+}
+function stringOrUndefined(input) {
+    if (typeof input === "number" && Number.isFinite(input))
+        return String(input);
+    const value = String(input || "").trim();
+    return value || undefined;
+}
+function normalizeTelegramUserId(input) {
+    const value = String(input || "").trim();
+    if (!/^\d+$/.test(value))
+        throw new Error("telegram_channel_user_id_invalid");
+    return value;
+}
+function tenantRef(token) {
+    const v = String(token || "").trim();
+    return v ? v.slice(0, 12) : "unknown";
+}
+function normalizeWallet(input) {
+    const value = String(input || "").trim().toLowerCase();
+    if (!value)
+        return undefined;
+    if (!/^0x[a-f0-9]{40}$/.test(value))
+        return undefined;
+    return value;
+}
+function normalizeProtocolSubjectHeader(input) {
+    return String(input || "").trim();
+}
+function requireProtocolSubject(link) {
+    const header = String(link.valuya_protocol_subject_header || "").trim();
+    const parsed = parseProtocolSubjectHeader(header);
+    if (!parsed)
+        throw new Error("guard_protocol_subject_missing");
+    return parsed;
+}
+function parseProtocolSubjectHeader(header) {
+    const value = String(header || "").trim();
+    const idx = value.indexOf(":");
+    if (idx <= 0 || idx === value.length - 1)
+        return null;
+    if (value.indexOf(":", idx + 1) !== -1)
+        return null;
+    const type = value.slice(0, idx).trim();
+    const id = value.slice(idx + 1).trim();
+    if (!type || !id)
+        return null;
+    return { type, id, header: `${type}:${id}` };
+}

package/dist/linking/TelegramLinkStore.d.ts

@@ -0,0 +1,26 @@
+export type StoredTelegramChannelLink = {
+    telegram_user_id: string;
+    telegram_username?: string;
+    tenant_id?: string;
+    channel_app_id: string;
+    valuya_subject_id?: string;
+    valuya_subject_type?: string;
+    valuya_subject_external_id?: string;
+    valuya_privy_user_id?: string;
+    valuya_linked_wallet_address?: string;
+    valuya_privy_wallet_id?: string;
+    valuya_protocol_subject_type?: string;
+    valuya_protocol_subject_id?: string;
+    valuya_protocol_subject_header?: string;
+    status: string;
+    linked_at: string;
+    updated_at: string;
+};
+export declare class TelegramLinkStore {
+    private readonly filePath;
+    constructor(filePath: string);
+    getChannelLink(telegramUserId: string): Promise<StoredTelegramChannelLink | null>;
+    upsertChannelLink(telegramUserId: string, patch: Partial<StoredTelegramChannelLink>): Promise<StoredTelegramChannelLink>;
+    private readAll;
+    private writeAll;
+}

package/dist/linking/TelegramLinkStore.js

@@ -0,0 +1,60 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+export class TelegramLinkStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async getChannelLink(telegramUserId) {
+        const state = await this.readAll();
+        return state.channelLinks[telegramUserId] ?? null;
+    }
+    async upsertChannelLink(telegramUserId, patch) {
+        const state = await this.readAll();
+        const current = state.channelLinks[telegramUserId];
+        const now = new Date().toISOString();
+        const nextStatus = patch.status ?? current?.status ?? "linked";
+        const linkedAt = patch.linked_at ?? current?.linked_at ?? now;
+        const merged = {
+            telegram_user_id: patch.telegram_user_id ?? current?.telegram_user_id ?? telegramUserId,
+            telegram_username: patch.telegram_username ?? current?.telegram_username,
+            tenant_id: patch.tenant_id ?? current?.tenant_id,
+            channel_app_id: patch.channel_app_id ?? current?.channel_app_id ?? "telegram_main",
+            valuya_subject_id: patch.valuya_subject_id ?? current?.valuya_subject_id,
+            valuya_subject_type: patch.valuya_subject_type ?? current?.valuya_subject_type,
+            valuya_subject_external_id: patch.valuya_subject_external_id ?? current?.valuya_subject_external_id,
+            valuya_privy_user_id: patch.valuya_privy_user_id ?? current?.valuya_privy_user_id,
+            valuya_linked_wallet_address: patch.valuya_linked_wallet_address ?? current?.valuya_linked_wallet_address,
+            valuya_privy_wallet_id: patch.valuya_privy_wallet_id ?? current?.valuya_privy_wallet_id,
+            valuya_protocol_subject_type: patch.valuya_protocol_subject_type ?? current?.valuya_protocol_subject_type,
+            valuya_protocol_subject_id: patch.valuya_protocol_subject_id ?? current?.valuya_protocol_subject_id,
+            valuya_protocol_subject_header: patch.valuya_protocol_subject_header ?? current?.valuya_protocol_subject_header,
+            status: nextStatus,
+            linked_at: linkedAt,
+            updated_at: now,
+        };
+        if (!merged.telegram_user_id.trim())
+            throw new Error("state_telegram_user_id_required");
+        if (!merged.channel_app_id.trim())
+            throw new Error("state_channel_app_id_required");
+        if (!merged.status.trim())
+            throw new Error("state_channel_link_status_required");
+        state.channelLinks[telegramUserId] = merged;
+        await this.writeAll(state);
+        return merged;
+    }
+    async readAll() {
+        try {
+            const raw = await readFile(this.filePath, "utf8");
+            const parsed = JSON.parse(raw);
+            return { channelLinks: parsed?.channelLinks ?? {} };
+        }
+        catch {
+            return { channelLinks: {} };
+        }
+    }
+    async writeAll(state) {
+        await mkdir(dirname(this.filePath), { recursive: true });
+        await writeFile(this.filePath, JSON.stringify(state, null, 2), "utf8");
+    }
+}

package/dist/memory/FileSoulMemoryStore.d.ts

@@ -0,0 +1 @@
+export { FileSoulMemoryStore } from "@valuya/bot-channel-core";

package/dist/memory/FileSoulMemoryStore.js

@@ -0,0 +1 @@
+export { FileSoulMemoryStore } from "@valuya/bot-channel-core";

package/dist/runtime/SchemaDrivenSoulRuntime.d.ts

@@ -0,0 +1 @@
+export { SchemaDrivenSoulRuntime } from "@valuya/bot-channel-core";

package/dist/runtime/SchemaDrivenSoulRuntime.js

@@ -0,0 +1 @@
+export { SchemaDrivenSoulRuntime } from "@valuya/bot-channel-core";

package/dist/runtime/TelegramBotChannel.d.ts

@@ -0,0 +1,18 @@
+import { TelegramChannelAccessService, type MemoryStore, type SoulRuntime, type TelegramChannelRuntimeResult } from "@valuya/telegram-channel-access";
+import type { TelegramBotChannelConfig } from "../domain/types.js";
+export declare class TelegramBotChannel {
+    private readonly config;
+    private readonly runtime;
+    private readonly humanReply?;
+    constructor(config: TelegramBotChannelConfig, deps?: {
+        access?: TelegramChannelAccessService;
+        memoryStore?: MemoryStore;
+        soulRuntime?: SoulRuntime;
+    });
+    handleMessage(args: {
+        telegramUserId: string;
+        body: string;
+        telegramUsername?: string;
+        locale?: string;
+    }): Promise<TelegramChannelRuntimeResult>;
+}

package/dist/runtime/TelegramBotChannel.js

@@ -0,0 +1,30 @@
+import { InMemoryMemoryStore, TelegramChannelAccessService, TelegramChannelRuntime, } from "@valuya/telegram-channel-access";
+export class TelegramBotChannel {
+    config;
+    runtime;
+    humanReply;
+    constructor(config, deps) {
+        this.config = config;
+        const access = deps?.access || new TelegramChannelAccessService(config);
+        const memoryStore = deps?.memoryStore || config.memoryStore || new InMemoryMemoryStore();
+        const soulRuntime = deps?.soulRuntime || config.soulRuntime;
+        this.runtime = new TelegramChannelRuntime({
+            access,
+            mode: config.mode,
+            memoryStore,
+            soulRuntime,
+            souls: config.souls,
+        });
+        this.humanReply = config.humanReply;
+    }
+    async handleMessage(args) {
+        const result = await this.runtime.handleMessage(args);
+        if (result.kind === "human" && this.humanReply) {
+            return {
+                ...result,
+                reply: this.humanReply,
+            };
+        }
+        return result;
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server.js

@@ -0,0 +1,123 @@
+import { createServer } from "node:http";
+import { createConfiguredSoul, createOptionalOpenAISoulRuntime, normalizeChannelMode, } from "@valuya/bot-channel-bootstrap-core";
+import { createOpenAIResponsesRunner, getRequestPath, handleInternalJsonMessage, requiredEnv, } from "@valuya/bot-channel-server-core";
+import { TelegramBotChannelApp } from "./app/TelegramBotChannelApp.js";
+import { GuardTelegramChannelLinkResolver } from "./linking/GuardTelegramChannelLinkResolver.js";
+import { FileSoulMemoryStore } from "./memory/FileSoulMemoryStore.js";
+import { SchemaDrivenSoulRuntime } from "./runtime/SchemaDrivenSoulRuntime.js";
+import { TelegramBotChannel } from "./runtime/TelegramBotChannel.js";
+import { createMentorSoulDefinition } from "./souls/createMentorSoulDefinition.js";
+const PORT = Number(process.env.PORT || 8792);
+const HOST = process.env.HOST?.trim() || "0.0.0.0";
+const LINKS_FILE = requiredEnv("TELEGRAM_LINKS_FILE");
+const VALUYA_BASE = requiredEnv("VALUYA_BASE").replace(/\/+$/, "");
+const VALUYA_TENANT_TOKEN = requiredEnv("VALUYA_TENANT_TOKEN");
+const TELEGRAM_CHANNEL_APP_ID = requiredEnv("TELEGRAM_CHANNEL_APP_ID");
+const CHANNEL_PLAN = process.env.TELEGRAM_CHANNEL_PLAN?.trim() || "standard";
+const CHANNEL_RESOURCE = process.env.TELEGRAM_CHANNEL_RESOURCE?.trim() || "";
+const CHANNEL_BOT = process.env.TELEGRAM_CHANNEL_BOT?.trim() || "";
+const CHANNEL_NAME = process.env.TELEGRAM_CHANNEL_NAME?.trim() || "";
+const CHANNEL_INVITE_URL = process.env.TELEGRAM_CHANNEL_INVITE_URL?.trim() || "";
+const SOUL_MEMORY_FILE = process.env.TELEGRAM_CHANNEL_MEMORY_FILE?.trim() || ".data/telegram-channel-memory.json";
+const SOUL_ID = process.env.TELEGRAM_CHANNEL_SOUL_ID?.trim() || "mentor";
+const SOUL_NAME = process.env.TELEGRAM_CHANNEL_SOUL_NAME?.trim() || "Mentor";
+const SOUL_LOCALE = process.env.TELEGRAM_CHANNEL_SOUL_LOCALE?.trim() || "de";
+const SOUL_SYSTEM_PROMPT = process.env.TELEGRAM_CHANNEL_SOUL_SYSTEM_PROMPT?.trim() || "";
+const SOUL_RESPONSE_SCHEMA_JSON = process.env.TELEGRAM_CHANNEL_SOUL_RESPONSE_SCHEMA_JSON?.trim() || "";
+const CHANNEL_MODE = normalizeChannelMode({
+    value: process.env.TELEGRAM_CHANNEL_MODE,
+    soulId: SOUL_ID,
+});
+const OPENAI_API_KEY = process.env.OPENAI_API_KEY?.trim() || "";
+const OPENAI_MODEL = process.env.OPENAI_MODEL?.trim() || "gpt-4.1-mini";
+const HUMAN_REPLY = process.env.TELEGRAM_CHANNEL_HUMAN_REPLY?.trim() || "";
+const INTERNAL_API_TOKEN = process.env.TELEGRAM_CHANNEL_INTERNAL_API_TOKEN?.trim() || "";
+const linkResolver = new GuardTelegramChannelLinkResolver({
+    baseUrl: VALUYA_BASE,
+    tenantToken: VALUYA_TENANT_TOKEN,
+    channelAppId: TELEGRAM_CHANNEL_APP_ID,
+    linksFile: LINKS_FILE,
+});
+const souls = CHANNEL_MODE.kind === "agent"
+    ? [createConfiguredSoul({
+            baseSoul: createMentorSoulDefinition({
+                id: SOUL_ID,
+                name: SOUL_NAME,
+                locale: SOUL_LOCALE,
+                ...(SOUL_SYSTEM_PROMPT ? { systemPrompt: SOUL_SYSTEM_PROMPT } : {}),
+            }),
+            responseSchemaJson: SOUL_RESPONSE_SCHEMA_JSON,
+        })]
+    : [];
+const channel = new TelegramBotChannel({
+    baseUrl: VALUYA_BASE,
+    tenantToken: VALUYA_TENANT_TOKEN,
+    channelResource: CHANNEL_RESOURCE || undefined,
+    channelBot: CHANNEL_BOT || undefined,
+    channelName: CHANNEL_NAME || undefined,
+    channelPlan: CHANNEL_PLAN,
+    channelInviteUrl: CHANNEL_INVITE_URL || undefined,
+    mode: CHANNEL_MODE,
+    souls,
+    memoryStore: new FileSoulMemoryStore(SOUL_MEMORY_FILE),
+    soulRuntime: createOptionalOpenAISoulRuntime({
+        mode: CHANNEL_MODE,
+        apiKey: OPENAI_API_KEY,
+        model: OPENAI_MODEL,
+        createRunner: createOpenAICompletionRunner,
+        createRuntime: (args) => new SchemaDrivenSoulRuntime(args),
+    }),
+    humanReply: HUMAN_REPLY || undefined,
+    linking: linkResolver,
+});
+const app = new TelegramBotChannelApp({
+    channel,
+    linkResolver,
+});
+const server = createServer(async (req, res) => {
+    try {
+        const requestPath = getRequestPath(req.url);
+        if (req.method !== "POST" || requestPath !== "/internal/message") {
+            res.writeHead(404, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ ok: false, error: "not_found" }));
+            return;
+        }
+        const response = await handleInternalJsonMessage({
+            req,
+            internalApiToken: INTERNAL_API_TOKEN || undefined,
+            providedToken: String(req.headers["x-agent-internal-token"] || "").trim() || null,
+            onMessage: async (body) => app.handleInboundMessage({
+                telegramUserId: normalizeTelegramUserId(String(body.telegramUserId || "")),
+                body: String(body.body || ""),
+                telegramUsername: typeof body.telegramUsername === "string" ? body.telegramUsername : undefined,
+                locale: typeof body.locale === "string" ? body.locale : undefined,
+            }),
+        });
+        res.writeHead(response.status, response.headers);
+        res.end(response.body);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(JSON.stringify({ level: "error", event: "telegram_bot_channel_error", message }));
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: false, error: "internal_error", message: "Temporary error. Please retry." }));
+    }
+});
+server.listen(PORT, HOST, () => {
+    console.log(JSON.stringify({
+        level: "info",
+        event: "telegram_bot_channel_started",
+        host: HOST,
+        port: PORT,
+        internalPath: "/internal/message",
+        channelMode: CHANNEL_MODE.kind,
+        resource: CHANNEL_RESOURCE || null,
+        plan: CHANNEL_PLAN,
+    }));
+});
+function createOpenAICompletionRunner(args) {
+    return createOpenAIResponsesRunner(args);
+}
+function normalizeTelegramUserId(raw) {
+    return String(raw || "").trim();
+}

package/dist/souls/createMentorSoulDefinition.d.ts

@@ -0,0 +1 @@
+export { createMentorSoulDefinition } from "@valuya/bot-channel-core";

package/dist/souls/createMentorSoulDefinition.js

@@ -0,0 +1 @@
+export { createMentorSoulDefinition } from "@valuya/bot-channel-core";

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@valuya/telegram-bot-channel",
+  "version": "0.2.0-beta.1",
+  "description": "Gated Telegram channel example with human or soul-moderated runtime on top of Valuya Guard",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    ".env.example",
+    ".env.mentor.example",
+    ".env.support.example",
+    ".env.concierge.example"
+  ],
+  "dependencies": {
+    "@valuya/bot-channel-app-core": "^0.2.0-beta.1",
+    "@valuya/bot-channel-bootstrap-core": "^0.2.0-beta.1",
+    "@valuya/bot-channel-core": "^0.2.0-beta.1",
+    "@valuya/bot-channel-server-core": "^0.2.0-beta.1",
+    "@valuya/telegram-channel-access": "^0.2.0-beta.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.10"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "start": "pnpm run build && node dist/server.js",
+    "test": "pnpm run build && node --test dist/*.test.js dist/app/*.test.js"
+  }
+}