@segmentstream/agent 0.0.0-stage → 0.1.1

package/dist/extension/lib/telegram/adapter.d.ts

@@ -0,0 +1,29 @@
+import { type TelegramChannel } from "eve/channels/telegram";
+import type { TelegramSettings } from "../../config.js";
+import { type Environment } from "../environment.js";
+import { type RuntimeToken } from "../runtime-token.js";
+import { type ObservedMessages } from "./observed.js";
+import { type DecideFunction } from "./router.js";
+import { type Transcriber } from "./voice.js";
+/**
+ * The SegmentStream Telegram adapter: eve's `telegramChannel`, with its credentials, identity,
+ * voice and routing replaced (`agent-design.md`, section 4). Everything it reads from the mount's
+ * configuration is read per request, because eve binds the mount after it loads the channel.
+ */
+export interface TelegramAdapterOptions {
+    /** The mounted `channels.telegram`, or `null` when the workspace has no Telegram channel. */
+    readonly settings: () => TelegramSettings | null;
+    readonly models: () => {
+        readonly stt: string | false;
+        readonly decision: string;
+    };
+    readonly decide: DecideFunction;
+    readonly environment?: Environment;
+    readonly token?: RuntimeToken;
+    /** For the proxy and the ontology service; tests pass a fake. */
+    readonly fetch?: typeof fetch;
+    readonly transcribe?: Transcriber;
+    readonly observed?: ObservedMessages;
+}
+/** The Telegram channel of the extension. */
+export declare function segmentstreamTelegram(options: TelegramAdapterOptions): TelegramChannel;

package/dist/extension/lib/telegram/adapter.mjs

@@ -0,0 +1,115 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+import { appOrigin, channelsEnabled, proxyEnvironment, webhookSecret } from "../environment.mjs";
+import { MAXIMUM_PROXY_BODY_BYTES, connectionProxy } from "../connection-proxy.mjs";
+import { agentIdentities } from "../identities.mjs";
+import { runtimeToken } from "../runtime-token.mjs";
+import { botIdentityCache } from "./bot.mjs";
+import { observedMessages } from "./observed.mjs";
+import { decisionRouter } from "./router.mjs";
+import { downloadTelegramFile, gatewayTranscriber } from "./voice.mjs";
+import { handleInboundMessage } from "./inbound.mjs";
+import { InboundRequest, currentInboundRequest, runInboundRequest, withReplacedText } from "./inbound-request.mjs";
+import { TELEGRAM_PLACEHOLDER_TOKEN, TELEGRAM_PROXY_ORIGIN, telegramProxyFetch } from "./proxy-fetch.mjs";
+import { deliverUnlessSilent } from "./silent.mjs";
+import { telegramWebhookVerifier } from "./webhook.mjs";
+import { telegramChannel } from "eve/channels/telegram";
+function segmentstreamTelegram(options) {
+	const environment = options.environment ?? process.env;
+	const token = options.token ?? runtimeToken;
+	const observed = options.observed ?? observedMessages();
+	const bot = botIdentityCache();
+	const proxies = new Map();
+	let identities;
+	function settings() {
+		const configured = options.settings();
+		if (configured === null) throw new Error("The Telegram channel is not configured in agent/segmentstream.json.");
+		return configured;
+	}
+	function proxy() {
+		const connection = settings().connection;
+		let existing = proxies.get(connection);
+		if (existing === void 0) {
+			existing = connectionProxy({
+				environment: proxyEnvironment(environment),
+				connection,
+				token,
+				...options.fetch === void 0 ? {} : { fetch: options.fetch }
+			});
+			proxies.set(connection, existing);
+		}
+		return existing;
+	}
+	function pairing() {
+		identities ??= agentIdentities({
+			origin: appOrigin(environment),
+			token,
+			...options.fetch === void 0 ? {} : { fetch: options.fetch }
+		});
+		return identities;
+	}
+	const channel = telegramChannel({
+		api: {
+			apiBaseUrl: TELEGRAM_PROXY_ORIGIN,
+			fileBaseUrl: TELEGRAM_PROXY_ORIGIN,
+			fetch: (input, init) => telegramProxyFetch(proxy())(input, init)
+		},
+		credentials: {
+			botToken: TELEGRAM_PLACEHOLDER_TOKEN,
+			webhookVerifier: telegramWebhookVerifier(() => webhookSecret(environment))
+		},
+		uploadPolicy: { maxBytes: MAXIMUM_PROXY_BODY_BYTES },
+		onMessage: (context, message) => handleInboundMessage({
+			context,
+			message,
+			request: currentInboundRequest(),
+			dependencies: {
+				policy: settings().policy,
+				sttModel: options.models().stt,
+				identities: pairing(),
+				bot,
+				decide: decisionRouter({
+					decide: options.decide,
+					model: options.models().decision
+				}),
+				transcribe: options.transcribe ?? gatewayTranscriber,
+				download: (fileId) => downloadTelegramFile({
+					proxy: proxy(),
+					fileId
+				}),
+				observed,
+				connectUrl: (code) => `${appOrigin(environment)}/agent/connect?code=${encodeURIComponent(code)}`
+			}
+		}),
+		events: { "message.completed": deliverUnlessSilent }
+	});
+	return {
+		...channel,
+		routes: channel.routes.map((route) => gatedRoute({
+			route,
+			options,
+			environment
+		}))
+	};
+}
+function gatedRoute(input) {
+	const { route, options, environment } = input;
+	if (route.transport === "websocket") return route;
+	return {
+		...route,
+		handler: async (request, args) => {
+			if (!channelsEnabled(environment)) return new Response("ok");
+			if (options.settings() === null) return new Response("not found", { status: 404 });
+			const inbound = new InboundRequest(async () => (await args.describe()).description ?? "");
+			return runInboundRequest(inbound, () => route.handler(request, {
+				...args,
+				from: (address) => withReplacedText(args.from(address), inbound)
+			}));
+		}
+	};
+}
+export { segmentstreamTelegram };

package/dist/extension/lib/telegram/bot.d.ts

@@ -0,0 +1,4 @@
+import type { TelegramHandle } from "eve/channels/telegram";
+import type { BotIdentity } from "./router.js";
+export type BotIdentityLookup = (telegram: Pick<TelegramHandle, "request">) => Promise<BotIdentity | undefined>;
+export declare function botIdentityCache(now?: () => number): BotIdentityLookup;

package/dist/extension/lib/telegram/bot.mjs

@@ -0,0 +1,45 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+const IDENTITY_TTL_MS = 36e5;
+const FAILURE_TTL_MS = 6e4;
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function identityFrom(body) {
+	const result = isRecord(body) ? body.result : void 0;
+	if (!isRecord(result) || typeof result.id !== "number" && typeof result.id !== "string") return;
+	return {
+		id: String(result.id),
+		username: typeof result.username === "string" ? result.username : void 0
+	};
+}
+function botIdentityCache(now = Date.now) {
+	let cached;
+	return async (telegram) => {
+		if (cached !== void 0 && cached.until > now()) return cached.identity;
+		let identity;
+		try {
+			const response = await telegram.request("getMe");
+			identity = response.ok ? identityFrom(response.body) : void 0;
+			if (identity === void 0) {
+				const body = isRecord(response.body) ? response.body : {};
+				console.error("[segmentstream] Telegram refused getMe", {
+					ok: response.ok,
+					description: typeof body.description === "string" ? body.description.slice(0, 200) : ""
+				});
+			}
+		} catch (error) {
+			console.error("[segmentstream] Telegram getMe failed", { error });
+		}
+		cached = {
+			identity,
+			until: now() + (identity === void 0 ? FAILURE_TTL_MS : IDENTITY_TTL_MS)
+		};
+		return identity;
+	};
+}
+export { botIdentityCache };

package/dist/extension/lib/telegram/inbound-request.d.ts

@@ -0,0 +1,22 @@
+import type { ChannelSource } from "eve/channels";
+/**
+ * What one webhook request shares between eve's `onMessage` hook and the route wrapper around it.
+ * `onMessage` may only return `{ auth, context, title }`; it cannot change the message eve sends.
+ * A voice message reaches it with no text, so it records the transcript here, and the wrapper's
+ * `send` delivers that text in place of the empty message. Async local storage scopes the record
+ * to the request: eve calls `onMessage` and `send` inside the route handler's async context.
+ */
+export declare class InboundRequest {
+    /** The agent's description from the compiled manifest, for the routing decision. */
+    readonly agentDescription: () => Promise<string>;
+    /** The text the turn should carry instead of the parsed message, once a transcript exists. */
+    text: string | undefined;
+    constructor(
+    /** The agent's description from the compiled manifest, for the routing decision. */
+    agentDescription: () => Promise<string>);
+}
+export declare function runInboundRequest<Result>(request: InboundRequest, run: () => Result): Result;
+/** The current webhook request, or `undefined` outside the wrapped route. */
+export declare function currentInboundRequest(): InboundRequest | undefined;
+/** A channel source whose `send` delivers the request's replacement text, when one was recorded. */
+export declare function withReplacedText<State>(source: ChannelSource<State>, request: InboundRequest): ChannelSource<State>;

package/dist/extension/lib/telegram/inbound-request.mjs

@@ -0,0 +1,37 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+import { AsyncLocalStorage } from "node:async_hooks";
+var InboundRequest = class {
+	agentDescription;
+	text;
+	constructor(agentDescription) {
+		this.agentDescription = agentDescription;
+	}
+};
+const storage = new AsyncLocalStorage();
+function runInboundRequest(request, run) {
+	return storage.run(request, run);
+}
+function currentInboundRequest() {
+	return storage.getStore();
+}
+function replaceText(message, text) {
+	if (typeof message === "string") return text;
+	return [{
+		type: "text",
+		text
+	}, ...message.filter((part) => part.type !== "text")];
+}
+function withReplacedText(source, request) {
+	return {
+		...source,
+		send(message, options) {
+			return source.send(request.text === void 0 ? message : replaceText(message, request.text), options);
+		}
+	};
+}
+export { InboundRequest, currentInboundRequest, runInboundRequest, withReplacedText };

package/dist/extension/lib/telegram/inbound.d.ts

@@ -0,0 +1,35 @@
+import type { TelegramContext, TelegramInboundResult, TelegramMessage } from "eve/channels/telegram";
+import type { TelegramPolicy } from "../../config.js";
+import type { AgentIdentities } from "../identities.js";
+import type { BotIdentityLookup } from "./bot.js";
+import type { InboundRequest } from "./inbound-request.js";
+import { type ObservedMessages } from "./observed.js";
+import { type RouteDecider } from "./router.js";
+import { type Transcriber } from "./voice.js";
+/**
+ * eve's Telegram `onMessage` hook, in the order `agent-design.md` gives:
+ *
+ * 1. The hard gate, with no model: bots, channel posts and senders without a live pairing never
+ *    start a turn. An unknown sender who writes to the bot privately gets a pairing link.
+ * 2. Voice becomes text, so the router and the agent read what was said.
+ * 3. The router answers or observes. An observed message goes to the chat's ring and stops here.
+ * 4. An answered message dispatches as the paired member, with the ring ahead of it as context.
+ */
+export interface InboundDependencies {
+    readonly policy: TelegramPolicy;
+    readonly sttModel: string | false;
+    readonly identities: AgentIdentities;
+    readonly bot: BotIdentityLookup;
+    readonly decide: RouteDecider;
+    readonly transcribe: Transcriber;
+    readonly download: (fileId: string) => Promise<Uint8Array>;
+    readonly observed: ObservedMessages;
+    /** The app's `/agent/connect` link for a pairing code. */
+    readonly connectUrl: (code: string) => string;
+}
+export declare function handleInboundMessage(input: {
+    readonly context: TelegramContext;
+    readonly message: TelegramMessage;
+    readonly request: InboundRequest | undefined;
+    readonly dependencies: InboundDependencies;
+}): Promise<TelegramInboundResult>;

package/dist/extension/lib/telegram/inbound.mjs

@@ -0,0 +1,117 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+import { telegramPrincipal } from "./principal.mjs";
+import { observedChatKey, observedContext } from "./observed.mjs";
+import { isAddressed, routeMessage } from "./router.mjs";
+import { voiceNote, voiceOf, voiceText } from "./voice.mjs";
+const UNKNOWN_PRIVATE = "I don't know who you are yet. Open this link and sign in to connect your Telegram account; it works for ten minutes:";
+const REFUSED = "Your access to this agent was revoked, or your membership is inactive. Ask a workspace administrator.";
+function display(user) {
+	if (user.username !== void 0) return `@${user.username}`;
+	const name = [user.firstName, user.lastName].filter((part) => part !== void 0 && part !== "").join(" ");
+	return name === "" ? void 0 : name;
+}
+function sentAt(message) {
+	const date = message.raw.date;
+	return new Date(typeof date === "number" ? date * 1e3 : Date.now()).toISOString();
+}
+function observedMessage(message, text) {
+	return {
+		author: display(message.from) ?? message.from.id,
+		text,
+		at: sentAt(message)
+	};
+}
+function unknownInGroup(bot) {
+	return `I don't know who you are yet. Message me privately to connect your account.${bot?.username === void 0 ? "" : ` https://t.me/${bot.username}`}`;
+}
+async function answerUnpaired(input) {
+	const { context, message, lookup, dependencies } = input;
+	if (lookup.status === "refused") {
+		await context.telegram.post(REFUSED);
+		return;
+	}
+	if (message.chat.type !== "private") {
+		await context.telegram.post(unknownInGroup(input.bot));
+		return;
+	}
+	const sender = display(message.from);
+	const pairing = await dependencies.identities.createPairing({
+		provider: "telegram",
+		externalId: message.from.id,
+		...sender === void 0 ? {} : { display: sender }
+	});
+	await context.telegram.post(`${UNKNOWN_PRIVATE}\n${dependencies.connectUrl(pairing.code)}`);
+}
+async function handleInboundMessage(input) {
+	const { context, dependencies } = input;
+	const message = input.message;
+	if (message.from === void 0 || message.from.isBot || message.chat.type === "channel") return null;
+	const sent = {
+		...message,
+		from: message.from
+	};
+	const bot = await dependencies.bot(context.telegram);
+	const addressed = isAddressed(sent, bot);
+	const lookup = await dependencies.identities.lookup({
+		provider: "telegram",
+		externalId: sent.from.id
+	});
+	if (lookup.status !== "paired") {
+		if (addressed) await answerUnpaired({
+			context,
+			message: sent,
+			lookup,
+			bot,
+			dependencies
+		});
+		return null;
+	}
+	const voice = voiceOf(sent.raw);
+	const caption = sent.text || sent.caption;
+	const notes = [];
+	let text = caption;
+	if (voice !== void 0 && (addressed || dependencies.policy === "smart")) {
+		const spoken = await voiceText({
+			voice,
+			model: dependencies.sttModel,
+			download: dependencies.download,
+			transcribe: dependencies.transcribe
+		});
+		text = [caption, spoken.text].filter((part) => part.trim() !== "").join("\n\n");
+		notes.push(spoken.note);
+	} else if (voice !== void 0) text = caption || voiceNote(voice);
+	if (text.trim() === "" && sent.attachments.length === 0) return null;
+	const chat = observedChatKey({
+		chatId: sent.chat.id,
+		...sent.messageThreadId === void 0 ? {} : { messageThreadId: sent.messageThreadId }
+	});
+	if (await routeMessage({
+		policy: dependencies.policy,
+		addressed,
+		decide: dependencies.decide,
+		question: async () => ({
+			agent: await input.request?.agentDescription() ?? "",
+			observed: dependencies.observed.list(chat),
+			message: observedMessage(sent, text)
+		})
+	}) === "observe") {
+		dependencies.observed.add(chat, observedMessage(sent, text === "" ? "[attachment]" : text));
+		return null;
+	}
+	if (voice !== void 0 && input.request !== void 0) input.request.text = text;
+	else if (voice !== void 0) notes.push(text);
+	await context.telegram.startTyping();
+	return {
+		auth: telegramPrincipal({
+			message: sent,
+			member: lookup.member
+		}),
+		context: [...observedContext(dependencies.observed.take(chat)), ...notes]
+	};
+}
+export { handleInboundMessage };

package/dist/extension/lib/telegram/observed.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The bounded ring of group messages the router observed without answering. The router shows it to
+ * the decision model, and a reply carries it into the turn as context, so the agent knows what the
+ * chat was talking about.
+ *
+ * eve's `defineState` would be the durable home, but it is session state and needs an active eve
+ * context; an observed message has neither, because observing must not start a session. The ring
+ * therefore lives in process memory, per chat and forum topic, and a cold start begins empty.
+ */
+/** How many observed messages a chat keeps; the oldest goes first. */
+export declare const OBSERVED_MESSAGES = 30;
+export interface ObservedMessage {
+    /** How the chat names the author: their username, else their first name. */
+    readonly author: string;
+    readonly text: string;
+    /** ISO time the message was sent. */
+    readonly at: string;
+}
+export interface ObservedMessages {
+    add(chat: string, message: ObservedMessage): void;
+    list(chat: string): ReadonlyArray<ObservedMessage>;
+    /** Returns and forgets the chat's ring, once a reply has carried it into a turn. */
+    take(chat: string): ReadonlyArray<ObservedMessage>;
+}
+export declare function observedMessages(capacity?: number): ObservedMessages;
+/** The key of a chat's ring: the chat and, in a forum, the topic. */
+export declare function observedChatKey(input: {
+    readonly chatId: string;
+    readonly messageThreadId?: number;
+}): string;
+/** The ring as turn context: one block the model reads before the message it answers. */
+export declare function observedContext(messages: ReadonlyArray<ObservedMessage>): ReadonlyArray<string>;

package/dist/extension/lib/telegram/observed.mjs

@@ -0,0 +1,47 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+const OBSERVED_MESSAGES = 30;
+const MAXIMUM_CHATS = 500;
+const MAXIMUM_TEXT_LENGTH = 1e3;
+function observedMessages(capacity = 30) {
+	const chats = new Map();
+	return {
+		add(chat, message) {
+			const ring = [...chats.get(chat) ?? [], {
+				...message,
+				text: message.text.slice(0, MAXIMUM_TEXT_LENGTH)
+			}];
+			chats.delete(chat);
+			chats.set(chat, ring.slice(-capacity));
+			if (chats.size > MAXIMUM_CHATS) {
+				const oldest = chats.keys().next();
+				if (oldest.done !== true) chats.delete(oldest.value);
+			}
+		},
+		list(chat) {
+			return chats.get(chat) ?? [];
+		},
+		take(chat) {
+			const ring = chats.get(chat) ?? [];
+			chats.delete(chat);
+			return ring;
+		}
+	};
+}
+function observedChatKey(input) {
+	return input.messageThreadId === void 0 ? input.chatId : `${input.chatId}:${input.messageThreadId}`;
+}
+function observedContext(messages) {
+	if (messages.length === 0) return [];
+	return [[
+		"<observed_messages>",
+		"Earlier messages in this chat that were not addressed to you, oldest first:",
+		...messages.map((message) => `[${message.at}] ${message.author}: ${message.text}`),
+		"</observed_messages>"
+	].join("\n")];
+}
+export { OBSERVED_MESSAGES, observedChatKey, observedContext, observedMessages };

package/dist/extension/lib/telegram/principal.d.ts

@@ -0,0 +1,20 @@
+import type { TelegramMessage } from "eve/channels/telegram";
+import type { SessionAuthContext } from "eve/context";
+import type { PairedMember } from "../identities.js";
+/** The route authenticator the ontology connection and the model resolver recognize. */
+export declare const TELEGRAM_AUTHENTICATOR = "segmentstream-telegram";
+/**
+ * The session principal of a paired sender. The member comes from the pairing, never from the
+ * message, so the model cannot choose whom it acts for. Pairing is by user: a member keeps their
+ * roles in every chat, and a group chat is recorded in the principal id and attributes for audit.
+ */
+export declare function telegramPrincipal(input: {
+    readonly message: TelegramMessage & {
+        readonly from: NonNullable<TelegramMessage["from"]>;
+    };
+    readonly member: PairedMember;
+}): SessionAuthContext;
+/** The member a session principal acts for: `memberId` stamped by a SegmentStream channel. */
+export declare function memberIdOf(principal: SessionAuthContext | null | undefined): string | undefined;
+/** The member's roles on a session principal; empty when it carries none. */
+export declare function rolesOf(principal: SessionAuthContext | null | undefined): ReadonlyArray<string>;

package/dist/extension/lib/telegram/principal.mjs

@@ -0,0 +1,40 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+const TELEGRAM_AUTHENTICATOR = "segmentstream-telegram";
+function isGroup(message) {
+	return message.chat.type === "group" || message.chat.type === "supergroup";
+}
+function telegramPrincipal(input) {
+	const { message, member } = input;
+	const sender = message.from.id;
+	const attributes = {
+		memberId: member.id,
+		roles: member.roles,
+		chatId: message.chat.id,
+		chatType: message.chat.type
+	};
+	if (member.name !== null) attributes.memberName = member.name;
+	if (message.from.username !== void 0) attributes.username = message.from.username;
+	return {
+		authenticator: TELEGRAM_AUTHENTICATOR,
+		issuer: "telegram",
+		principalId: isGroup(message) ? `telegram:${message.chat.id}:${sender}` : `telegram:${sender}`,
+		principalType: "user",
+		subject: sender,
+		attributes
+	};
+}
+function memberIdOf(principal) {
+	const memberId = principal?.attributes.memberId;
+	return typeof memberId === "string" && memberId !== "" ? memberId : void 0;
+}
+function rolesOf(principal) {
+	const roles = principal?.attributes.roles;
+	if (typeof roles === "string") return [roles];
+	return roles ?? [];
+}
+export { TELEGRAM_AUTHENTICATOR, memberIdOf, rolesOf, telegramPrincipal };

package/dist/extension/lib/telegram/proxy-fetch.d.ts

@@ -0,0 +1,28 @@
+import type { ConnectionProxy } from "../connection-proxy.js";
+/**
+ * Telegram puts the bot token in the URL path: eve's Telegram API layer calls
+ * `${apiBaseUrl}/bot<token>/<method>` for methods and `${fileBaseUrl}/file/bot<token>/<path>` for
+ * downloads, and it refuses to run without a token. The token lives in backend-next behind the
+ * workspace's Telegram connection, whose `bot` API is `https://api.telegram.org/bot<token>/` and
+ * whose `file` API is `https://api.telegram.org/file/bot<token>/`.
+ *
+ * So the channel gets a placeholder token and an origin that does not resolve, and its `fetch`
+ * is this function: it accepts only URLs under that origin with that placeholder, strips both, and
+ * sends the method or file path through the connection proxy. A request that somehow bypassed it
+ * would fail to resolve rather than reach Telegram, and the real token never enters this process.
+ */
+/** The origin eve's Telegram API layer is pointed at. `.invalid` never resolves (RFC 6761). */
+export declare const TELEGRAM_PROXY_ORIGIN = "https://telegram.segmentstream.invalid";
+/** Stands in for the bot token, which only backend-next holds. Not a secret. */
+export declare const TELEGRAM_PLACEHOLDER_TOKEN = "segmentstream-connection";
+/** The Telegram channel tried to send a request this adapter does not route through the proxy. */
+export declare class TelegramProxyRouteError extends Error {
+    readonly name = "TelegramProxyRouteError";
+}
+/** Where a Telegram URL goes on the connection: an API and a path relative to its base URL. */
+export declare function telegramProxyRoute(url: string): {
+    readonly api: "bot" | "file";
+    readonly path: string;
+};
+/** The `fetch` eve's Telegram channel calls; see the module comment. */
+export declare function telegramProxyFetch(proxy: ConnectionProxy): typeof fetch;

package/dist/extension/lib/telegram/proxy-fetch.mjs

@@ -0,0 +1,69 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+const TELEGRAM_PROXY_ORIGIN = "https://telegram.segmentstream.invalid";
+const TELEGRAM_PLACEHOLDER_TOKEN = "segmentstream-connection";
+const METHOD_PREFIX = `${TELEGRAM_PROXY_ORIGIN}/bot${TELEGRAM_PLACEHOLDER_TOKEN}/`;
+const FILE_PREFIX = `${TELEGRAM_PROXY_ORIGIN}/file/bot${TELEGRAM_PLACEHOLDER_TOKEN}/`;
+const METHODS = new Set([
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE",
+	"HEAD",
+	"OPTIONS"
+]);
+var TelegramProxyRouteError = class extends Error {
+	name = "TelegramProxyRouteError";
+};
+function requestUrl(input) {
+	if (typeof input === "string") return input;
+	return input instanceof URL ? input.href : input.url;
+}
+function telegramProxyRoute(url) {
+	if (url.startsWith(FILE_PREFIX)) return {
+		api: "file",
+		path: `/${url.slice(FILE_PREFIX.length)}`
+	};
+	if (url.startsWith(METHOD_PREFIX)) return {
+		api: "bot",
+		path: `/${url.slice(METHOD_PREFIX.length)}`
+	};
+	throw new TelegramProxyRouteError("The Telegram channel sends requests only through the connection proxy.");
+}
+function headerPairs(headers) {
+	return [...new Headers(headers).entries()];
+}
+async function bodyBytes(body) {
+	if (body === void 0 || body === null) return new Uint8Array();
+	return new Uint8Array(await new Response(body).arrayBuffer());
+}
+function proxyMethod(method) {
+	const upper = (method ?? "GET").toUpperCase();
+	for (const candidate of METHODS) if (candidate === upper) return candidate;
+	throw new TelegramProxyRouteError(`The connection proxy does not forward ${upper} requests.`);
+}
+function hasNullBody(status) {
+	return status === 101 || status === 204 || status === 205 || status === 304;
+}
+function telegramProxyFetch(proxy) {
+	return async (input, init) => {
+		const route = telegramProxyRoute(requestUrl(input));
+		const reply = await proxy.request({
+			api: route.api,
+			method: proxyMethod(init?.method),
+			path: route.path,
+			headers: headerPairs(init?.headers),
+			body: await bodyBytes(init?.body)
+		});
+		return new Response(hasNullBody(reply.status) ? null : Buffer.from(reply.body), {
+			status: reply.status,
+			headers: reply.headers.map(([name, value]) => [name, value])
+		});
+	};
+}
+export { TELEGRAM_PLACEHOLDER_TOKEN, TELEGRAM_PROXY_ORIGIN, TelegramProxyRouteError, telegramProxyFetch, telegramProxyRoute };