@vellumai/vellum-gateway 0.1.7

package/src/runtime/client.ts

@@ -0,0 +1,212 @@
+import type { GatewayConfig } from "../config.js";
+import { getLogger } from "../logger.js";
+
+const log = getLogger("runtime-client");
+
+/** Build common headers for runtime requests, including auth when configured. */
+function runtimeHeaders(config: GatewayConfig, extra?: Record<string, string>): Record<string, string> {
+  const headers: Record<string, string> = { ...extra };
+  if (config.runtimeBearerToken) {
+    headers["Authorization"] = `Bearer ${config.runtimeBearerToken}`;
+  }
+  return headers;
+}
+
+/**
+ * Thrown when the assistant rejects an attachment for a non-retriable reason
+ * (e.g. unsupported MIME type, dangerous file extension). Callers can use
+ * this to distinguish validation failures from transient errors.
+ */
+export class AttachmentValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AttachmentValidationError";
+  }
+}
+
+export type RuntimeInboundPayload = {
+  sourceChannel: string;
+  externalChatId: string;
+  externalMessageId: string;
+  content: string;
+  isEdit?: boolean;
+  senderName?: string;
+  senderExternalUserId?: string;
+  senderUsername?: string;
+  sourceMetadata?: Record<string, unknown>;
+  attachmentIds?: string[];
+};
+
+export type RuntimeAttachmentMeta = {
+  id: string;
+  filename: string;
+  mimeType: string;
+  sizeBytes: number;
+  kind: string;
+};
+
+export type RuntimeAttachmentPayload = RuntimeAttachmentMeta & {
+  data: string; // base64-encoded
+};
+
+export type RuntimeInboundResponse = {
+  accepted: boolean;
+  duplicate: boolean;
+  eventId: string;
+  assistantMessage?: {
+    id: string;
+    role: "assistant";
+    content: string;
+    timestamp: string;
+    attachments: RuntimeAttachmentMeta[];
+  };
+};
+
+export async function forwardToRuntime(
+  config: GatewayConfig,
+  assistantId: string,
+  payload: RuntimeInboundPayload,
+): Promise<RuntimeInboundResponse> {
+  const url = `${config.assistantRuntimeBaseUrl}/v1/assistants/${encodeURIComponent(assistantId)}/channels/inbound`;
+
+  let lastError: Error | null = null;
+
+  for (let attempt = 0; attempt <= config.runtimeMaxRetries; attempt++) {
+    if (attempt > 0) {
+      const delay = config.runtimeInitialBackoffMs * Math.pow(2, attempt - 1);
+      log.debug({ attempt, delay, assistantId }, "Retrying runtime forward");
+      await new Promise((r) => setTimeout(r, delay));
+    }
+
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: runtimeHeaders(config, { "Content-Type": "application/json" }),
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(config.runtimeTimeoutMs),
+      });
+
+      if (response.status >= 400 && response.status < 500) {
+        const body = await response.text();
+        log.warn(
+          { status: response.status, body, assistantId },
+          "Runtime returned client error, not retrying",
+        );
+        throw new Error(`Runtime returned ${response.status}: ${body}`);
+      }
+
+      if (response.status >= 500) {
+        const body = await response.text();
+        lastError = new Error(`Runtime returned ${response.status}: ${body}`);
+        log.warn(
+          { status: response.status, attempt, assistantId },
+          "Runtime returned server error",
+        );
+        continue;
+      }
+
+      const result = (await response.json()) as RuntimeInboundResponse;
+      log.debug(
+        { assistantId, eventId: result.eventId, duplicate: result.duplicate },
+        "Runtime forward succeeded",
+      );
+      return result;
+    } catch (err) {
+      if (
+        err instanceof Error &&
+        err.message.startsWith("Runtime returned 4")
+      ) {
+        throw err;
+      }
+      lastError = err instanceof Error ? err : new Error(String(err));
+      log.warn(
+        { err: lastError, attempt, assistantId },
+        "Runtime forward attempt failed",
+      );
+    }
+  }
+
+  throw lastError ?? new Error("Runtime forward failed after retries");
+}
+
+export async function resetConversation(
+  config: GatewayConfig,
+  assistantId: string,
+  sourceChannel: string,
+  externalChatId: string,
+): Promise<void> {
+  const url = `${config.assistantRuntimeBaseUrl}/v1/assistants/${encodeURIComponent(assistantId)}/channels/conversation`;
+
+  const response = await fetch(url, {
+    method: "DELETE",
+    headers: runtimeHeaders(config, { "Content-Type": "application/json" }),
+    body: JSON.stringify({ sourceChannel, externalChatId }),
+    signal: AbortSignal.timeout(config.runtimeTimeoutMs),
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`Reset conversation failed (${response.status}): ${body}`);
+  }
+}
+
+export type UploadAttachmentInput = {
+  filename: string;
+  mimeType: string;
+  data: string; // base64-encoded
+};
+
+export type UploadAttachmentResponse = {
+  id: string;
+};
+
+export async function downloadAttachment(
+  config: GatewayConfig,
+  assistantId: string,
+  attachmentId: string,
+): Promise<RuntimeAttachmentPayload> {
+  const url = `${config.assistantRuntimeBaseUrl}/v1/assistants/${encodeURIComponent(assistantId)}/attachments/${encodeURIComponent(attachmentId)}`;
+
+  const response = await fetch(url, {
+    method: "GET",
+    headers: runtimeHeaders(config),
+    signal: AbortSignal.timeout(config.runtimeTimeoutMs),
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`Attachment download failed (${response.status}): ${body}`);
+  }
+
+  return (await response.json()) as RuntimeAttachmentPayload;
+}
+
+export async function uploadAttachment(
+  config: GatewayConfig,
+  assistantId: string,
+  input: UploadAttachmentInput,
+): Promise<UploadAttachmentResponse> {
+  const url = `${config.assistantRuntimeBaseUrl}/v1/assistants/${encodeURIComponent(assistantId)}/attachments`;
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: runtimeHeaders(config, { "Content-Type": "application/json" }),
+    body: JSON.stringify(input),
+    signal: AbortSignal.timeout(config.runtimeTimeoutMs),
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+    // 4xx = non-retriable validation rejection (unsupported MIME, dangerous
+    // extension, missing fields). Distinguish from transient 5xx/network errors
+    // so callers can decide whether to skip or propagate.
+    if (response.status >= 400 && response.status < 500) {
+      throw new AttachmentValidationError(
+        `Attachment rejected (${response.status}): ${body}`,
+      );
+    }
+    throw new Error(`Attachment upload failed (${response.status}): ${body}`);
+  }
+
+  return (await response.json()) as UploadAttachmentResponse;
+}

package/src/schema.ts

@@ -0,0 +1,383 @@
+import packageJson from "../package.json" with { type: "json" };
+
+export function buildSchema(): Record<string, unknown> {
+  return {
+    openapi: "3.1.0",
+    info: {
+      title: "Vellum Gateway",
+      version: packageJson.version,
+      description:
+        "HTTP gateway that bridges external channels (Telegram, etc.) to the Vellum assistant runtime and provides an authenticated reverse proxy.",
+    },
+    paths: {
+      "/healthz": {
+        get: {
+          summary: "Liveness probe",
+          operationId: "healthz",
+          responses: {
+            "200": {
+              description: "Gateway is alive",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/HealthResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/readyz": {
+        get: {
+          summary: "Readiness probe",
+          description:
+            "Returns 200 when the gateway is ready to accept traffic. Returns 503 during graceful shutdown drain.",
+          operationId: "readyz",
+          responses: {
+            "200": {
+              description: "Gateway is ready",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ReadyResponse" },
+                },
+              },
+            },
+            "503": {
+              description:
+                "Gateway is draining (graceful shutdown in progress)",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/DrainingResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/schema": {
+        get: {
+          summary: "OpenAPI schema",
+          description: "Returns the full OpenAPI schema for this gateway.",
+          operationId: "getSchema",
+          responses: {
+            "200": {
+              description: "OpenAPI 3.1 schema document",
+              content: {
+                "application/json": {
+                  schema: { type: "object", additionalProperties: true },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/webhooks/telegram": {
+        post: {
+          summary: "Telegram webhook",
+          description:
+            "Receives inbound Telegram updates, normalizes them, resolves routing, and forwards to the assistant runtime.",
+          operationId: "telegramWebhook",
+          security: [{ TelegramWebhookSecret: [] }],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/TelegramUpdate" },
+              },
+            },
+          },
+          responses: {
+            "200": {
+              description: "Update accepted",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/TelegramOk" },
+                },
+              },
+            },
+            "400": {
+              description: "Invalid JSON or unreadable body",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "401": {
+              description: "Webhook secret verification failed",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "405": {
+              description: "Method not allowed (only POST accepted)",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "413": {
+              description: "Webhook payload too large",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description: "Internal error processing inbound event",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "503": {
+              description: "Telegram integration not configured",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/{path}": {
+        get: {
+          summary: "Runtime proxy",
+          description:
+            "Reverse-proxies requests to the assistant runtime when GATEWAY_RUNTIME_PROXY_ENABLED is true. Supports all HTTP methods. Returns 404 when the proxy is disabled.",
+          operationId: "runtimeProxyGet",
+          security: [{ BearerAuth: [] }],
+          parameters: [
+            {
+              name: "path",
+              in: "path",
+              required: true,
+              schema: { type: "string" },
+              description:
+                "Upstream path forwarded to the assistant runtime",
+            },
+          ],
+          responses: {
+            "200": {
+              description: "Proxied response from the assistant runtime",
+            },
+            "401": {
+              description: "Missing or invalid bearer token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "404": {
+              description: "Runtime proxy not enabled",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "500": {
+              description:
+                "Server misconfigured (proxy auth enabled without token)",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "502": {
+              description: "Upstream connection failed",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "504": {
+              description: "Upstream request timed out",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+        post: {
+          summary: "Runtime proxy",
+          description:
+            "Reverse-proxies requests to the assistant runtime when GATEWAY_RUNTIME_PROXY_ENABLED is true.",
+          operationId: "runtimeProxyPost",
+          security: [{ BearerAuth: [] }],
+          parameters: [
+            {
+              name: "path",
+              in: "path",
+              required: true,
+              schema: { type: "string" },
+              description:
+                "Upstream path forwarded to the assistant runtime",
+            },
+          ],
+          requestBody: {
+            required: false,
+            content: {
+              "application/json": {
+                schema: { type: "object", additionalProperties: true },
+              },
+            },
+          },
+          responses: {
+            "200": {
+              description: "Proxied response from the assistant runtime",
+            },
+            "401": {
+              description: "Missing or invalid bearer token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "502": {
+              description: "Upstream connection failed",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "504": {
+              description: "Upstream request timed out",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    components: {
+      schemas: {
+        HealthResponse: {
+          type: "object",
+          required: ["status"],
+          properties: {
+            status: { type: "string", enum: ["ok"] },
+          },
+        },
+        ReadyResponse: {
+          type: "object",
+          required: ["status"],
+          properties: {
+            status: { type: "string", enum: ["ok"] },
+          },
+        },
+        DrainingResponse: {
+          type: "object",
+          required: ["status"],
+          properties: {
+            status: { type: "string", enum: ["draining"] },
+          },
+        },
+        ErrorResponse: {
+          type: "object",
+          required: ["error"],
+          properties: {
+            error: { type: "string" },
+          },
+        },
+        TelegramOk: {
+          type: "object",
+          required: ["ok"],
+          properties: {
+            ok: { type: "boolean" },
+          },
+        },
+        TelegramUpdate: {
+          type: "object",
+          description: "Telegram Bot API Update object",
+          properties: {
+            update_id: { type: "integer" },
+            message: { $ref: "#/components/schemas/TelegramMessage" },
+            edited_message: {
+              $ref: "#/components/schemas/TelegramMessage",
+            },
+          },
+        },
+        TelegramMessage: {
+          type: "object",
+          properties: {
+            message_id: { type: "integer" },
+            text: { type: "string" },
+            caption: { type: "string" },
+            chat: {
+              type: "object",
+              properties: {
+                id: { type: "integer" },
+                type: { type: "string" },
+              },
+            },
+            from: {
+              type: "object",
+              properties: {
+                id: { type: "integer" },
+                is_bot: { type: "boolean" },
+                username: { type: "string" },
+                first_name: { type: "string" },
+                last_name: { type: "string" },
+                language_code: { type: "string" },
+              },
+            },
+            photo: {
+              type: "array",
+              items: {
+                $ref: "#/components/schemas/TelegramPhotoSize",
+              },
+            },
+            document: { $ref: "#/components/schemas/TelegramDocument" },
+          },
+        },
+        TelegramPhotoSize: {
+          type: "object",
+          properties: {
+            file_id: { type: "string" },
+            file_unique_id: { type: "string" },
+            width: { type: "integer" },
+            height: { type: "integer" },
+            file_size: { type: "integer" },
+          },
+        },
+        TelegramDocument: {
+          type: "object",
+          properties: {
+            file_id: { type: "string" },
+            file_unique_id: { type: "string" },
+            file_name: { type: "string" },
+            mime_type: { type: "string" },
+            file_size: { type: "integer" },
+          },
+        },
+      },
+      securitySchemes: {
+        BearerAuth: {
+          type: "http",
+          scheme: "bearer",
+        },
+        TelegramWebhookSecret: {
+          type: "apiKey",
+          in: "header",
+          name: "X-Telegram-Bot-Api-Secret-Token",
+        },
+      },
+    },
+  };
+}