@vellumai/vellum-gateway 0.1.7

package/src/__tests__/schema.test.ts

@@ -0,0 +1,128 @@
+import { describe, test, expect, afterAll } from "bun:test";
+import { buildSchema } from "../schema.js";
+
+const PORT = 19836;
+
+const server = Bun.serve({
+  port: PORT,
+  fetch(req) {
+    const url = new URL(req.url);
+
+    if (url.pathname === "/schema") {
+      return Response.json(buildSchema());
+    }
+
+    return Response.json({ error: "Not found" }, { status: 404 });
+  },
+});
+
+afterAll(() => {
+  server.stop(true);
+});
+
+describe("/schema route", () => {
+  test("returns valid OpenAPI 3.1 schema via HTTP", async () => {
+    /**
+     * Tests that the /schema endpoint returns a valid OpenAPI document with
+     * the correct version and expected top-level structure.
+     */
+
+    // GIVEN a running gateway server
+
+    // WHEN we request the schema endpoint
+    const res = await fetch(`http://localhost:${PORT}/schema`);
+
+    // THEN we receive a 200 with valid JSON
+    expect(res.status).toBe(200);
+    const body = await res.json();
+
+    // AND the response is an OpenAPI 3.1 document
+    expect(body.openapi).toBe("3.1.0");
+    expect(body.info.title).toBe("Vellum Gateway");
+    expect(typeof body.info.version).toBe("string");
+
+    // AND it contains the expected top-level sections
+    expect(body.paths).toBeDefined();
+    expect(body.components).toBeDefined();
+    expect(body.components.schemas).toBeDefined();
+    expect(body.components.securitySchemes).toBeDefined();
+  });
+
+  test("schema includes all gateway routes", async () => {
+    /**
+     * Tests that the schema documents every route the gateway exposes.
+     */
+
+    // GIVEN a running gateway server
+
+    // WHEN we request the schema endpoint
+    const res = await fetch(`http://localhost:${PORT}/schema`);
+    const body = await res.json();
+
+    // THEN the paths include every gateway endpoint
+    expect(body.paths["/healthz"]).toBeDefined();
+    expect(body.paths["/readyz"]).toBeDefined();
+    expect(body.paths["/schema"]).toBeDefined();
+    expect(body.paths["/webhooks/telegram"]).toBeDefined();
+    expect(body.paths["/{path}"]).toBeDefined();
+  });
+
+  test("schema version matches package.json version", async () => {
+    /**
+     * Tests that the schema info.version stays in sync with package.json.
+     */
+
+    // GIVEN the version from package.json
+    const pkg = (await import("../../package.json")).default;
+
+    // WHEN we request the schema endpoint
+    const res = await fetch(`http://localhost:${PORT}/schema`);
+    const body = await res.json();
+
+    // THEN the schema version matches the package version
+    expect(body.info.version).toBe(pkg.version);
+  });
+});
+
+describe("buildSchema()", () => {
+  test("returns a plain object with all component schemas", () => {
+    /**
+     * Tests that buildSchema() includes all expected component schema
+     * definitions for request/response types.
+     */
+
+    // GIVEN no special setup needed
+
+    // WHEN we call buildSchema directly
+    const schema = buildSchema();
+
+    // THEN it contains all expected component schemas
+    const components = schema.components as Record<string, Record<string, unknown>>;
+    const schemaNames = Object.keys(components.schemas);
+    expect(schemaNames).toContain("HealthResponse");
+    expect(schemaNames).toContain("ReadyResponse");
+    expect(schemaNames).toContain("DrainingResponse");
+    expect(schemaNames).toContain("ErrorResponse");
+    expect(schemaNames).toContain("TelegramOk");
+    expect(schemaNames).toContain("TelegramUpdate");
+    expect(schemaNames).toContain("TelegramMessage");
+    expect(schemaNames).toContain("TelegramPhotoSize");
+    expect(schemaNames).toContain("TelegramDocument");
+  });
+
+  test("returns a JSON-serializable object", () => {
+    /**
+     * Tests that the schema can be round-tripped through JSON without loss.
+     */
+
+    // GIVEN no special setup needed
+
+    // WHEN we serialize and deserialize the schema
+    const schema = buildSchema();
+    const json = JSON.stringify(schema);
+    const parsed = JSON.parse(json);
+
+    // THEN the round-tripped object equals the original
+    expect(parsed).toEqual(schema);
+  });
+});

package/src/__tests__/telegram-normalize.test.ts

@@ -0,0 +1,303 @@
+import { describe, test, expect } from "bun:test";
+import { normalizeTelegramUpdate } from "../telegram/normalize.js";
+import { verifyWebhookSecret } from "../telegram/verify.js";
+
+describe("normalizeTelegramUpdate", () => {
+  const validPayload = {
+    update_id: 123456,
+    message: {
+      message_id: 42,
+      text: "Hello bot",
+      chat: { id: 99001, type: "private" },
+      from: {
+        id: 55001,
+        is_bot: false,
+        username: "testuser",
+        first_name: "Test",
+        last_name: "User",
+        language_code: "en",
+      },
+    },
+  };
+
+  test("normalizes a valid private text message", () => {
+    const result = normalizeTelegramUpdate(validPayload);
+    expect(result).not.toBeNull();
+    expect(result!.version).toBe("v1");
+    expect(result!.sourceChannel).toBe("telegram");
+    expect(result!.message.content).toBe("Hello bot");
+    expect(result!.message.externalChatId).toBe("99001");
+    expect(result!.message.externalMessageId).toBe("123456");
+    expect(result!.sender.externalUserId).toBe("55001");
+    expect(result!.sender.username).toBe("testuser");
+    expect(result!.sender.displayName).toBe("Test User");
+    expect(result!.sender.firstName).toBe("Test");
+    expect(result!.sender.lastName).toBe("User");
+    expect(result!.sender.languageCode).toBe("en");
+    expect(result!.sender.isBot).toBe(false);
+    expect(result!.source.updateId).toBe("123456");
+    expect(result!.source.messageId).toBe("42");
+    expect(result!.source.chatType).toBe("private");
+    expect(result!.raw).toEqual(validPayload);
+  });
+
+  test("returns null for unsupported message types (e.g. sticker-only)", () => {
+    const payload = {
+      update_id: 1,
+      message: {
+        message_id: 1,
+        chat: { id: 1, type: "private" },
+        sticker: { file_id: "abc" },
+      },
+    };
+    expect(normalizeTelegramUpdate(payload)).toBeNull();
+  });
+
+  test("normalizes a photo message", () => {
+    const payload = {
+      update_id: 100,
+      message: {
+        message_id: 10,
+        chat: { id: 200, type: "private" },
+        from: { id: 300, is_bot: false, username: "photouser", first_name: "Photo" },
+        photo: [
+          { file_id: "small_id", file_unique_id: "s1", width: 90, height: 90 },
+          { file_id: "medium_id", file_unique_id: "s2", width: 320, height: 320 },
+          { file_id: "large_id", file_unique_id: "s3", width: 800, height: 800 },
+        ],
+        caption: "Check this out",
+      },
+    };
+    const result = normalizeTelegramUpdate(payload);
+    expect(result).not.toBeNull();
+    expect(result!.message.content).toBe("Check this out");
+    expect(result!.message.attachments).toHaveLength(1);
+    expect(result!.message.attachments![0]).toEqual({
+      type: "photo",
+      fileId: "large_id",
+      fileSize: undefined,
+    });
+  });
+
+  test("normalizes a photo message without caption", () => {
+    const payload = {
+      update_id: 101,
+      message: {
+        message_id: 11,
+        chat: { id: 200, type: "private" },
+        from: { id: 300, is_bot: false },
+        photo: [
+          { file_id: "only_id", file_unique_id: "s1", width: 800, height: 800 },
+        ],
+      },
+    };
+    const result = normalizeTelegramUpdate(payload);
+    expect(result).not.toBeNull();
+    expect(result!.message.content).toBe("");
+    expect(result!.message.attachments).toHaveLength(1);
+    expect(result!.message.attachments![0].fileId).toBe("only_id");
+  });
+
+  test("normalizes a document message", () => {
+    const payload = {
+      update_id: 102,
+      message: {
+        message_id: 12,
+        chat: { id: 200, type: "private" },
+        from: { id: 300, is_bot: false, username: "docuser" },
+        document: {
+          file_id: "doc_file_id",
+          file_unique_id: "du1",
+          file_name: "report.pdf",
+          mime_type: "application/pdf",
+          file_size: 12345,
+        },
+        caption: "Here is the report",
+      },
+    };
+    const result = normalizeTelegramUpdate(payload);
+    expect(result).not.toBeNull();
+    expect(result!.message.content).toBe("Here is the report");
+    expect(result!.message.attachments).toHaveLength(1);
+    expect(result!.message.attachments![0]).toEqual({
+      type: "document",
+      fileId: "doc_file_id",
+      fileName: "report.pdf",
+      mimeType: "application/pdf",
+      fileSize: 12345,
+    });
+  });
+
+  test("normalizes a document message without caption", () => {
+    const payload = {
+      update_id: 103,
+      message: {
+        message_id: 13,
+        chat: { id: 200, type: "private" },
+        from: { id: 300, is_bot: false },
+        document: {
+          file_id: "doc_id_2",
+          file_unique_id: "du2",
+          file_name: "data.csv",
+          mime_type: "text/csv",
+        },
+      },
+    };
+    const result = normalizeTelegramUpdate(payload);
+    expect(result).not.toBeNull();
+    expect(result!.message.content).toBe("");
+    expect(result!.message.attachments).toHaveLength(1);
+  });
+
+  test("text-only messages have no attachments field", () => {
+    const result = normalizeTelegramUpdate(validPayload);
+    expect(result).not.toBeNull();
+    expect(result!.message.attachments).toBeUndefined();
+  });
+
+  test("returns null for group messages", () => {
+    const payload = {
+      ...validPayload,
+      message: { ...validPayload.message, chat: { id: 99001, type: "group" } },
+    };
+    expect(normalizeTelegramUpdate(payload)).toBeNull();
+  });
+
+  test("returns null for payloads without update_id", () => {
+    const { update_id: _, ...rest } = validPayload;
+    expect(normalizeTelegramUpdate(rest)).toBeNull();
+  });
+
+  test("returns null for payloads without chat id", () => {
+    const payload = {
+      update_id: 1,
+      message: { message_id: 1, text: "hello", chat: {} },
+    };
+    expect(normalizeTelegramUpdate(payload)).toBeNull();
+  });
+
+  test("uses chat.id as fallback for sender when from.id is missing", () => {
+    const payload = {
+      update_id: 1,
+      message: {
+        message_id: 1,
+        text: "hello",
+        chat: { id: 12345, type: "private" },
+      },
+    };
+    const result = normalizeTelegramUpdate(payload);
+    expect(result).not.toBeNull();
+    expect(result!.sender.externalUserId).toBe("12345");
+  });
+
+  test("returns null for non-message updates (e.g. callback_query)", () => {
+    const payload = {
+      update_id: 1,
+      callback_query: { id: "abc", data: "some_data" },
+    };
+    expect(normalizeTelegramUpdate(payload)).toBeNull();
+  });
+
+  test("normalizes an edited_message update with isEdit flag", () => {
+    const payload = {
+      update_id: 200,
+      edited_message: {
+        message_id: 42,
+        text: "Hello bot (edited)",
+        chat: { id: 99001, type: "private" },
+        from: {
+          id: 55001,
+          is_bot: false,
+          username: "testuser",
+          first_name: "Test",
+        },
+      },
+    };
+    const result = normalizeTelegramUpdate(payload);
+    expect(result).not.toBeNull();
+    expect(result!.message.isEdit).toBe(true);
+    expect(result!.message.content).toBe("Hello bot (edited)");
+    expect(result!.message.externalChatId).toBe("99001");
+    expect(result!.message.externalMessageId).toBe("200");
+    expect(result!.source.updateId).toBe("200");
+    expect(result!.source.messageId).toBe("42");
+    expect(result!.sender.externalUserId).toBe("55001");
+  });
+
+  test("prefers message over edited_message when both are present", () => {
+    const payload = {
+      update_id: 300,
+      message: {
+        message_id: 50,
+        text: "Original",
+        chat: { id: 99001, type: "private" },
+        from: { id: 55001, is_bot: false },
+      },
+      edited_message: {
+        message_id: 50,
+        text: "Edited",
+        chat: { id: 99001, type: "private" },
+        from: { id: 55001, is_bot: false },
+      },
+    };
+    const result = normalizeTelegramUpdate(payload);
+    expect(result).not.toBeNull();
+    expect(result!.message.isEdit).toBeUndefined();
+    expect(result!.message.content).toBe("Original");
+  });
+
+  test("sets isEdit for edited_message with photo", () => {
+    const payload = {
+      update_id: 400,
+      edited_message: {
+        message_id: 60,
+        chat: { id: 200, type: "private" },
+        from: { id: 300, is_bot: false },
+        photo: [
+          { file_id: "edited_photo", file_unique_id: "ep1", width: 800, height: 800 },
+        ],
+        caption: "Updated caption",
+      },
+    };
+    const result = normalizeTelegramUpdate(payload);
+    expect(result).not.toBeNull();
+    expect(result!.message.isEdit).toBe(true);
+    expect(result!.message.content).toBe("Updated caption");
+    expect(result!.message.attachments).toHaveLength(1);
+  });
+
+  test("returns null for edited_message in group chat", () => {
+    const payload = {
+      update_id: 500,
+      edited_message: {
+        message_id: 70,
+        text: "Edited group msg",
+        chat: { id: 99001, type: "group" },
+        from: { id: 55001, is_bot: false },
+      },
+    };
+    expect(normalizeTelegramUpdate(payload)).toBeNull();
+  });
+});
+
+describe("verifyWebhookSecret", () => {
+  test("returns true for matching secret", () => {
+    const headers = new Headers({ "x-telegram-bot-api-secret-token": "my-secret" });
+    expect(verifyWebhookSecret(headers, "my-secret")).toBe(true);
+  });
+
+  test("returns false for mismatched secret", () => {
+    const headers = new Headers({ "x-telegram-bot-api-secret-token": "wrong" });
+    expect(verifyWebhookSecret(headers, "my-secret")).toBe(false);
+  });
+
+  test("returns false when header is missing", () => {
+    const headers = new Headers();
+    expect(verifyWebhookSecret(headers, "my-secret")).toBe(false);
+  });
+
+  test("returns false when expected secret is empty", () => {
+    const headers = new Headers({ "x-telegram-bot-api-secret-token": "something" });
+    expect(verifyWebhookSecret(headers, "")).toBe(false);
+  });
+});

package/src/__tests__/telegram-only-default.test.ts

@@ -0,0 +1,134 @@
+import { describe, test, expect, afterAll } from "bun:test";
+
+/**
+ * Proves that non-Telegram requests return 404 when the gateway runs in its
+ * default configuration (proxy disabled). Uses the same routing logic as
+ * src/index.ts so that changes to the production routing (e.g. accidentally
+ * enabling the proxy by default) will be caught by this test.
+ */
+
+const PORT = 19830; // ephemeral port for test
+
+// Minimal env for loadConfig
+const env: Record<string, string> = {
+  TELEGRAM_BOT_TOKEN: "test-tok",
+  TELEGRAM_WEBHOOK_SECRET: "wh-sec",
+  ASSISTANT_RUNTIME_BASE_URL: "http://localhost:7821",
+  GATEWAY_PORT: String(PORT),
+  // GATEWAY_RUNTIME_PROXY_ENABLED intentionally unset → defaults to false
+};
+
+// Save and set env
+const saved: Record<string, string | undefined> = {};
+for (const [k, v] of Object.entries(env)) {
+  saved[k] = process.env[k];
+  process.env[k] = v;
+}
+// Ensure proxy flag is unset
+saved["GATEWAY_RUNTIME_PROXY_ENABLED"] =
+  process.env.GATEWAY_RUNTIME_PROXY_ENABLED;
+delete process.env.GATEWAY_RUNTIME_PROXY_ENABLED;
+
+// Dynamically import to pick up env
+const { loadConfig } = await import("../config.js");
+const { createTelegramWebhookHandler } = await import(
+  "../http/routes/telegram-webhook.js"
+);
+const { createRuntimeProxyHandler } = await import(
+  "../http/routes/runtime-proxy.js"
+);
+
+const config = loadConfig();
+
+const handleTelegramWebhook = createTelegramWebhookHandler(
+  config,
+  async () => {},
+);
+
+// Mirror production routing from src/index.ts: only create proxy when enabled
+const handleRuntimeProxy = config.runtimeProxyEnabled
+  ? createRuntimeProxyHandler(config)
+  : null;
+
+const server = Bun.serve({
+  port: PORT,
+  async fetch(req) {
+    const url = new URL(req.url);
+
+    if (url.pathname === "/healthz") {
+      return Response.json({ status: "ok" });
+    }
+
+    if (url.pathname === "/readyz") {
+      return Response.json({ status: "ok" });
+    }
+
+    if (url.pathname === "/webhooks/telegram") {
+      return handleTelegramWebhook(req);
+    }
+
+    if (handleRuntimeProxy) {
+      return handleRuntimeProxy(req);
+    }
+
+    return Response.json({ error: "Not found" }, { status: 404 });
+  },
+});
+
+afterAll(() => {
+  server.stop(true);
+  for (const [k, v] of Object.entries(saved)) {
+    if (v === undefined) delete process.env[k];
+    else process.env[k] = v;
+  }
+});
+
+describe("Telegram-only default: non-Telegram requests return 404", () => {
+  test("GET / returns 404", async () => {
+    const res = await fetch(`http://localhost:${PORT}/`);
+    expect(res.status).toBe(404);
+    const body = await res.json();
+    expect(body.error).toBe("Not found");
+  });
+
+  test("GET /v1/health returns 404", async () => {
+    const res = await fetch(`http://localhost:${PORT}/v1/health`);
+    expect(res.status).toBe(404);
+  });
+
+  test("POST /v1/assistants/foo/chat returns 404", async () => {
+    const res = await fetch(`http://localhost:${PORT}/v1/assistants/foo/chat`, {
+      method: "POST",
+      body: "{}",
+      headers: { "content-type": "application/json" },
+    });
+    expect(res.status).toBe(404);
+  });
+
+  test("GET /random-path returns 404", async () => {
+    const res = await fetch(`http://localhost:${PORT}/random-path`);
+    expect(res.status).toBe(404);
+  });
+
+  test("config.runtimeProxyEnabled is false by default", () => {
+    expect(config.runtimeProxyEnabled).toBe(false);
+  });
+
+  test("runtime proxy handler is not created when proxy is disabled", () => {
+    expect(handleRuntimeProxy).toBeNull();
+  });
+
+  test("GET /healthz returns 200 (infrastructure routes still work)", async () => {
+    const res = await fetch(`http://localhost:${PORT}/healthz`);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.status).toBe("ok");
+  });
+
+  test("GET /readyz returns 200 (infrastructure routes still work)", async () => {
+    const res = await fetch(`http://localhost:${PORT}/readyz`);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.status).toBe("ok");
+  });
+});