@nubemclaw/channel-telegram 1.2.2

package/src/setup.test.ts

@@ -0,0 +1,169 @@
+import { isErr, isOk } from "@nubemclaw/core";
+import {
+  createScriptedWizard,
+  resolveCredentialPaths,
+  runChannelSetup,
+} from "@nubemclaw/channel-sdk";
+import { GrammyError, HttpError } from "grammy";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createTelegramSetup } from "./setup.js";
+
+/**
+ * Tests pin the setup flow against a scripted wizard + a stub grammy
+ * Bot (only `api.getMe` is needed for validate). The order
+ * `prompt → safeParse → validate → persist` and the atomicity
+ * guarantee (persist NEVER runs if validate fails) are tested
+ * explicitly — the contract is documented in ADR-0020 §2 and the SDK
+ * `runChannelSetup` orchestrator owns the order.
+ */
+
+const silentLogger = {
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  debug: () => {},
+};
+
+const fakeBotToken = "123456789:ABCDEFghijklmnop_qrstuv-wxyz0123456";
+
+interface FakeBotApi {
+  getMe: ReturnType<typeof vi.fn>;
+}
+
+const makeBotFactory = (api: FakeBotApi) => (_token: string) => ({ api }) as never;
+
+describe("createTelegramSetup", () => {
+  let stateDir = "";
+
+  beforeEach(async () => {
+    stateDir = await mkdtemp(join(tmpdir(), "nbc-telegram-setup-"));
+  });
+
+  afterEach(async () => {
+    await rm(stateDir, { recursive: true, force: true });
+  });
+
+  it("happy path — prompt → validate → persist writes the token at the canonical path", async () => {
+    const getMe = vi.fn(async () => ({
+      id: 42,
+      is_bot: true,
+      first_name: "TestBot",
+      username: "test_bot",
+    }));
+    const setup = createTelegramSetup({
+      logger: silentLogger,
+      botFactory: makeBotFactory({ getMe }),
+      envVars: { NUBEMCLAW_STATE_DIR: stateDir },
+    });
+    const wizard = createScriptedWizard([{ kind: "value", value: fakeBotToken }]);
+
+    const result = await runChannelSetup(setup, { wizard });
+    expect(isOk(result)).toBe(true);
+
+    const paths = resolveCredentialPaths(
+      { channel: "telegram", role: "bot-token" },
+      { NUBEMCLAW_STATE_DIR: stateDir },
+    );
+    expect(await readFile(paths.credentialFile, "utf8")).toBe(fakeBotToken);
+    expect(getMe).toHaveBeenCalledOnce();
+  });
+
+  it("malformed token → validation.failed BEFORE bot.api.getMe is called", async () => {
+    const getMe = vi.fn();
+    const setup = createTelegramSetup({
+      logger: silentLogger,
+      botFactory: makeBotFactory({ getMe }),
+      envVars: { NUBEMCLAW_STATE_DIR: stateDir },
+    });
+    const wizard = createScriptedWizard([{ kind: "value", value: "garbage-not-a-token" }]);
+
+    const result = await runChannelSetup(setup, { wizard });
+    expect(isErr(result)).toBe(true);
+    if (isErr(result)) expect(result.error.code).toBe("validation.failed");
+    expect(getMe).not.toHaveBeenCalled();
+  });
+
+  it("getMe throws GrammyError(401) → channel.setup_validation_failed, no file written", async () => {
+    const getMe = vi.fn(async () => {
+      // GrammyError signature: (message, error_code, method, payload, response?).
+      // The constructor is exposed by grammy; we mimic a 401 response.
+      throw new GrammyError(
+        "Call to 'getMe' failed! Unauthorized",
+        // @ts-expect-error — grammy expects a Response shape; tests only use the description + code.
+        { ok: false, error_code: 401, description: "Unauthorized" },
+        "getMe",
+        {},
+      );
+    });
+    const setup = createTelegramSetup({
+      logger: silentLogger,
+      botFactory: makeBotFactory({ getMe }),
+      envVars: { NUBEMCLAW_STATE_DIR: stateDir },
+    });
+    const wizard = createScriptedWizard([{ kind: "value", value: fakeBotToken }]);
+
+    const result = await runChannelSetup(setup, { wizard });
+    expect(isErr(result)).toBe(true);
+    if (isErr(result)) {
+      expect(result.error.code).toBe("channel.setup_validation_failed");
+      expect(result.error.meta?.["error_code"]).toBe(401);
+    }
+
+    const paths = resolveCredentialPaths(
+      { channel: "telegram", role: "bot-token" },
+      { NUBEMCLAW_STATE_DIR: stateDir },
+    );
+    await expect(readFile(paths.credentialFile, "utf8")).rejects.toThrow();
+  });
+
+  it("getMe throws HttpError (network down) → channel.setup_validation_failed, no file written", async () => {
+    const getMe = vi.fn(async () => {
+      throw new HttpError("ECONNREFUSED", new Error("connect ECONNREFUSED"));
+    });
+    const setup = createTelegramSetup({
+      logger: silentLogger,
+      botFactory: makeBotFactory({ getMe }),
+      envVars: { NUBEMCLAW_STATE_DIR: stateDir },
+    });
+    const wizard = createScriptedWizard([{ kind: "value", value: fakeBotToken }]);
+    const result = await runChannelSetup(setup, { wizard });
+    expect(isErr(result)).toBe(true);
+    if (isErr(result)) expect(result.error.code).toBe("channel.setup_validation_failed");
+  });
+
+  it("getMe returns is_bot:false → channel.setup_validation_failed", async () => {
+    const getMe = vi.fn(async () => ({
+      id: 1,
+      is_bot: false,
+      first_name: "Human",
+      username: "human",
+    }));
+    const setup = createTelegramSetup({
+      logger: silentLogger,
+      botFactory: makeBotFactory({ getMe }),
+      envVars: { NUBEMCLAW_STATE_DIR: stateDir },
+    });
+    const wizard = createScriptedWizard([{ kind: "value", value: fakeBotToken }]);
+    const result = await runChannelSetup(setup, { wizard });
+    expect(isErr(result)).toBe(true);
+    if (isErr(result)) expect(result.error.code).toBe("channel.setup_validation_failed");
+  });
+
+  it("operator cancellation → channel.setup_cancelled, getMe never called", async () => {
+    const getMe = vi.fn();
+    const setup = createTelegramSetup({
+      logger: silentLogger,
+      botFactory: makeBotFactory({ getMe }),
+      envVars: { NUBEMCLAW_STATE_DIR: stateDir },
+    });
+    const wizard = createScriptedWizard([{ kind: "cancel" }]);
+    const result = await runChannelSetup(setup, { wizard });
+    expect(isErr(result)).toBe(true);
+    if (isErr(result)) expect(result.error.code).toBe("channel.setup_cancelled");
+    expect(getMe).not.toHaveBeenCalled();
+  });
+});

package/src/setup.ts

@@ -0,0 +1,139 @@
+import { err, nubemClawError, ok, type NubemClawError, type Result } from "@nubemclaw/core";
+import {
+  resolveCredentialPaths,
+  writeChannelCredential,
+  type ChannelLogger,
+  type ChannelSetup,
+  type Wizard,
+} from "@nubemclaw/channel-sdk";
+import { Bot, GrammyError, HttpError } from "grammy";
+import { z } from "zod";
+
+/**
+ * `TelegramSetup` — guided credential capture for the Telegram channel
+ * (Phase 13, ADR-0020 §2).
+ *
+ * Wizard transcript:
+ *
+ *   1. `secret` — bot token, format `<digits>:<token>` (BotFather).
+ *
+ * Schema (`credentialSchema`):
+ *
+ *   - `botToken: string` matching `/^\d+:[A-Za-z0-9_-]+$/`.
+ *
+ * Validate (`validate`):
+ *
+ *   - Instantiates a transient grammy `Bot` and calls `bot.api.getMe()`.
+ *     grammy maps the Bot API failure modes to typed errors:
+ *       • `GrammyError` with `error_code: 401` → invalid token.
+ *       • `HttpError` → transport/network failure.
+ *   - We translate both into `channel.setup_validation_failed` so the
+ *     operator sees a clean message; the orchestrator does NOT persist.
+ *
+ * Persist (`persist`):
+ *
+ *   - Atomic 0o600 write to
+ *     `~/.nubemclaw-dev/credentials/telegram-bot-token` via
+ *     `writeChannelCredential` (SDK shared helper).
+ *
+ * Cancellation at any step is converted by `runChannelSetup` to
+ * `channel.setup_cancelled` — see ADR-0020 §2.
+ */
+
+const TELEGRAM_BOT_TOKEN_REGEX = /^\d+:[A-Za-z0-9_-]+$/;
+
+export const TelegramCredentialsSchema = z
+  .object({
+    botToken: z.string().regex(TELEGRAM_BOT_TOKEN_REGEX, {
+      message: "expected BotFather format: <digits>:<token>",
+    }),
+  })
+  .strict();
+export type TelegramCredentials = z.infer<typeof TelegramCredentialsSchema>;
+
+export interface CreateTelegramSetupOptions {
+  readonly logger: ChannelLogger;
+  /**
+   * Test seam: override the Bot constructor. Production callers
+   * always use grammy's `Bot`; tests inject a fake whose `api.getMe()`
+   * is scriptable.
+   */
+  readonly botFactory?: (token: string) => Pick<Bot, "api">;
+  /** Test seam: override env vars for credential path resolution. */
+  readonly envVars?: NodeJS.ProcessEnv;
+}
+
+export const createTelegramSetup = (
+  opts: CreateTelegramSetupOptions,
+): ChannelSetup<TelegramCredentials> => ({
+  channel: "telegram",
+  credentialSchema: TelegramCredentialsSchema,
+
+  async promptOperator(wizard: Wizard): Promise<Result<TelegramCredentials, "cancelled">> {
+    const token = await wizard.secret({
+      message: "Telegram bot token (BotFather format: 123456:ABC...)",
+      validate: (value) => {
+        if (value === undefined || value.trim() === "") return "required";
+        if (!TELEGRAM_BOT_TOKEN_REGEX.test(value.trim())) {
+          return "expected BotFather format: <digits>:<token>";
+        }
+        return undefined;
+      },
+    });
+    if (!token.ok) return token;
+    return ok({ botToken: token.value.trim() });
+  },
+
+  async validate(creds: TelegramCredentials): Promise<Result<void, NubemClawError>> {
+    const factory = opts.botFactory ?? ((token: string) => new Bot(token));
+    const bot = factory(creds.botToken);
+    try {
+      const me = await bot.api.getMe();
+      if (me.is_bot !== true) {
+        return err(
+          nubemClawError({
+            code: "channel.setup_validation_failed",
+            message: "telegram getMe returned a non-bot identity — token is not a bot token",
+          }),
+        );
+      }
+      opts.logger.info({ username: me.username, id: me.id }, "telegram bot validated");
+      return ok(undefined);
+    } catch (cause) {
+      if (cause instanceof GrammyError) {
+        return err(
+          nubemClawError({
+            code: "channel.setup_validation_failed",
+            message: `telegram getMe rejected the token: ${cause.description}`,
+            meta: { error_code: cause.error_code },
+            cause,
+          }),
+        );
+      }
+      if (cause instanceof HttpError) {
+        return err(
+          nubemClawError({
+            code: "channel.setup_validation_failed",
+            message: `telegram getMe could not reach the Bot API: ${cause.message}`,
+            cause,
+          }),
+        );
+      }
+      return err(
+        nubemClawError({
+          code: "channel.setup_validation_failed",
+          message: `telegram getMe failed: ${String(cause)}`,
+          cause,
+        }),
+      );
+    }
+  },
+
+  async persist(creds: TelegramCredentials): Promise<void> {
+    const paths = resolveCredentialPaths(
+      { channel: "telegram", role: "bot-token" },
+      opts.envVars ?? process.env,
+    );
+    await writeChannelCredential(creds.botToken, paths);
+  },
+});

package/src/transport.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+
+import { createTelegramTransport } from "./transport.js";
+
+/**
+ * Unit tests for the operational transport. The Agent / ProxyAgent
+ * internals are exercised in production paths only — the live test
+ * (#150) verifies the wrapped fetch against the real Telegram API.
+ * Here we pin the public contract:
+ *
+ *   • Returns an object with both `fetch` and `close`.
+ *   • `close()` is idempotent.
+ *   • Proxy URL precedence: explicit option > env var > none.
+ *   • The wrapped fetch resolves against a real URL (we point at a
+ *     local httpbin-like echo path served by Node's built-in test
+ *     server in `tests/live/...` later; here we just smoke the
+ *     wiring with a `data:` URL to avoid real network).
+ *
+ * Tests do NOT instantiate undici Agents with real connections —
+ * the channel-level test (#144 v2) and the live test (#150) cover
+ * the end-to-end path.
+ */
+
+describe("createTelegramTransport", () => {
+  it("returns fetch + close from the factory", () => {
+    const t = createTelegramTransport();
+    expect(typeof t.fetch).toBe("function");
+    expect(typeof t.close).toBe("function");
+  });
+
+  it("close() is idempotent (second call resolves immediately, no throw)", async () => {
+    const t = createTelegramTransport();
+    await t.close();
+    await t.close();
+  });
+
+  it("resolves proxy URL from explicit option over env var", () => {
+    // Smoke test: the transport accepts the proxyUrl without throwing
+    // at construction time. End-to-end behavior is verified in the live
+    // test where the proxy is reachable.
+    const t = createTelegramTransport({
+      proxyUrl: "http://proxy.example.test:8080",
+      envVars: { NUBEMCLAW_PROXY_URL: "http://different-proxy.example.test:9090" },
+    });
+    expect(t.fetch).toBeDefined();
+  });
+
+  it("resolves proxy URL from NUBEMCLAW_PROXY_URL env var when no explicit option", () => {
+    const t = createTelegramTransport({
+      envVars: { NUBEMCLAW_PROXY_URL: "http://env-proxy.example.test:7070" },
+    });
+    expect(t.fetch).toBeDefined();
+  });
+
+  it("falls back to direct dispatcher when neither option nor env var is set", () => {
+    const t = createTelegramTransport({ envVars: {} });
+    expect(t.fetch).toBeDefined();
+  });
+
+  it("ignores empty string proxy URLs (treats as 'not set')", () => {
+    const t = createTelegramTransport({
+      proxyUrl: "   ",
+      envVars: { NUBEMCLAW_PROXY_URL: "  " },
+    });
+    expect(t.fetch).toBeDefined();
+  });
+});