@nubemclaw/channel-telegram 1.2.2

package/dist/api/client.d.ts

@@ -0,0 +1,64 @@
+import { type NubemClawError, type Result } from "@nubemclaw/core";
+import type { ChannelLogger } from "@nubemclaw/channel-sdk";
+import { type TelegramMessage, type TelegramUpdate, type TelegramUser } from "./schemas.js";
+/**
+ * Telegram Bot API client (Phase 13, raw undici — ADR-0020 §1 chose
+ * library route per channel; Telegram's Bot API is REST simple enough
+ * that a raw client + zod boundary is lighter than pulling `grammy` or
+ * `telegraf` for the surface we actually use).
+ *
+ * Three methods F13 needs:
+ *
+ *   • `getMe()`           — smoke test for setup validation.
+ *   • `getUpdates(...)`   — long-poll fetch for the polling transport.
+ *   • `sendMessage(...)`  — outbound from the agent loop.
+ *
+ * Plus `setWebhook` / `deleteWebhook` for the webhook lifecycle; the
+ * polling transport calls `deleteWebhook` on start to avoid the 409
+ * Telegram returns if both modes are active.
+ *
+ * Boundary contract:
+ *
+ *   • Token NEVER appears in logs. We log only the method name
+ *     (`getUpdates`, `sendMessage`) — the bot path prefix is the
+ *     secret and stays in the URL.
+ *   • Every response is zod-parsed at this boundary. Callers see
+ *     `Result<T, NubemClawError>` and consume typed payloads.
+ *   • 401 → `auth.invalid_credentials`, 429 → `rate_limit.exceeded`
+ *     with `retry_after` (when Telegram supplies it), 5xx →
+ *     `provider.unavailable`. The polling transport's own backoff
+ *     layer above this client handles scheduling the retry.
+ */
+export interface TelegramApiClientOptions {
+    readonly token: string;
+    readonly logger: ChannelLogger;
+    /** Test seam: override the fetch implementation. Defaults to global. */
+    readonly fetch?: typeof fetch;
+    /** Test seam: override base URL (default https://api.telegram.org). */
+    readonly baseUrl?: string;
+}
+export interface SendMessageArgs {
+    readonly chatId: number;
+    readonly text: string;
+    readonly parseMode?: "HTML" | "MarkdownV2";
+}
+export interface GetUpdatesArgs {
+    readonly offset?: number;
+    readonly timeoutSec: number;
+    readonly allowedUpdates: readonly string[];
+}
+export interface SetWebhookArgs {
+    readonly url: string;
+    readonly secretToken: string;
+    readonly allowedUpdates: readonly string[];
+    readonly dropPendingUpdates?: boolean;
+}
+export interface TelegramApiClient {
+    getMe(): Promise<Result<TelegramUser, NubemClawError>>;
+    getUpdates(args: GetUpdatesArgs): Promise<Result<readonly TelegramUpdate[], NubemClawError>>;
+    sendMessage(args: SendMessageArgs): Promise<Result<TelegramMessage, NubemClawError>>;
+    setWebhook(args: SetWebhookArgs): Promise<Result<true, NubemClawError>>;
+    deleteWebhook(): Promise<Result<true, NubemClawError>>;
+}
+export declare const createTelegramApiClient: (opts: TelegramApiClientOptions) => TelegramApiClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/api/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,MAAM,EACZ,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AAGzE,OAAO,EAKL,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;CAC5C;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CACvC;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC,CAAC;IACvD,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,cAAc,EAAE,EAAE,cAAc,CAAC,CAAC,CAAC;IAC7F,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,cAAc,CAAC,CAAC,CAAC;IACrF,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC;IACxE,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC;CACxD;AAID,eAAO,MAAM,uBAAuB,GAClC,MAAM,wBAAwB,KAC7B,iBAwIF,CAAC"}

package/dist/api/client.js

@@ -0,0 +1,108 @@
+import { err, nubemClawError, ok, } from "@nubemsystems/nubemclaw-core";
+import { z } from "zod";
+import { TelegramErrEnvelope, TelegramMessageSchema, TelegramUpdateSchema, TelegramUserSchema, } from "./schemas.js";
+const DEFAULT_BASE_URL = "https://api.telegram.org";
+export const createTelegramApiClient = (opts) => {
+    const baseUrl = opts.baseUrl ?? DEFAULT_BASE_URL;
+    const doFetch = opts.fetch ?? fetch;
+    const callMethod = async (method, body, resultSchema) => {
+        const url = `${baseUrl}/bot${opts.token}/${method}`;
+        let res;
+        try {
+            res = await doFetch(url, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: body === undefined ? "{}" : JSON.stringify(body),
+            });
+        }
+        catch (cause) {
+            opts.logger.warn({ method, err: cause }, "telegram api fetch failed");
+            return err(nubemClawError({
+                code: "provider.unavailable",
+                message: `telegram ${method}: network error`,
+                cause,
+            }));
+        }
+        let json;
+        try {
+            json = await res.json();
+        }
+        catch (cause) {
+            opts.logger.warn({ method, status: res.status, err: cause }, "telegram api non-JSON body");
+            return err(nubemClawError({
+                code: "provider.bad_response",
+                message: `telegram ${method}: non-JSON response (status ${res.status})`,
+                cause,
+            }));
+        }
+        // Failure envelope path — handled first because Telegram returns
+        // structured errors with HTTP 2xx and 4xx alike.
+        const errParse = TelegramErrEnvelope.safeParse(json);
+        if (errParse.success && !errParse.data.ok) {
+            const failure = errParse.data;
+            const retryAfter = failure.parameters?.retry_after;
+            const mapped = failure.error_code === 401
+                ? "auth.invalid_credentials"
+                : failure.error_code === 429
+                    ? "rate_limit.exceeded"
+                    : failure.error_code >= 500
+                        ? "provider.unavailable"
+                        : "provider.bad_response";
+            return err(nubemClawError({
+                code: mapped,
+                message: `telegram ${method}: ${failure.description}`,
+                meta: {
+                    error_code: failure.error_code,
+                    ...(retryAfter !== undefined ? { retry_after: retryAfter } : {}),
+                },
+            }));
+        }
+        const okSchema = z.object({ ok: z.literal(true), result: resultSchema });
+        const okParse = okSchema.safeParse(json);
+        if (!okParse.success) {
+            opts.logger.warn({ method, status: res.status, issues: okParse.error.issues }, "telegram api response failed schema validation");
+            return err(nubemClawError({
+                code: "provider.bad_response",
+                message: `telegram ${method}: response did not match expected schema`,
+                meta: { status: res.status, issues: okParse.error.issues },
+            }));
+        }
+        return ok(okParse.data.result);
+    };
+    return {
+        getMe: () => callMethod("getMe", undefined, TelegramUserSchema),
+        getUpdates: async (args) => {
+            const result = await callMethod("getUpdates", {
+                ...(args.offset !== undefined ? { offset: args.offset } : {}),
+                timeout: args.timeoutSec,
+                allowed_updates: args.allowedUpdates,
+            }, z.array(TelegramUpdateSchema));
+            if (!result.ok)
+                return result;
+            return ok(result.value);
+        },
+        sendMessage: (args) => callMethod("sendMessage", {
+            chat_id: args.chatId,
+            text: args.text,
+            ...(args.parseMode !== undefined ? { parse_mode: args.parseMode } : {}),
+        }, TelegramMessageSchema),
+        setWebhook: async (args) => {
+            const result = await callMethod("setWebhook", {
+                url: args.url,
+                secret_token: args.secretToken,
+                allowed_updates: args.allowedUpdates,
+                drop_pending_updates: args.dropPendingUpdates ?? false,
+            }, z.literal(true));
+            if (!result.ok)
+                return result;
+            return ok(true);
+        },
+        deleteWebhook: async () => {
+            const result = await callMethod("deleteWebhook", { drop_pending_updates: false }, z.literal(true));
+            if (!result.ok)
+                return result;
+            return ok(true);
+        },
+    };
+};
+//# sourceMappingURL=client.js.map

package/dist/api/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"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"}