@hasna/switcher 0.1.0

package/dist/sdk.d.ts

@@ -0,0 +1,311 @@
+import type { components } from "./generated/api";
+export type ProviderInput = components["schemas"]["ProviderInput"];
+export type Provider = components["schemas"]["Provider"];
+export type ProfileInput = components["schemas"]["ProfileInput"];
+export type Profile = components["schemas"]["Profile"];
+export type Model = components["schemas"]["Model"];
+export type Catalog = components["schemas"]["Catalog"];
+export type LaunchPlan = components["schemas"]["LaunchPlan"];
+export type Run = components["schemas"]["Run"];
+export type Page<T> = {
+    data: T[];
+    total: number;
+    limit: number;
+    offset: number;
+};
+export declare class SwitcherError extends Error {
+    status: number;
+    code: string;
+    requestId?: string | undefined;
+    constructor(status: number, code: string, message: string, requestId?: string | undefined);
+}
+export type ClientOptions = {
+    baseUrl: string;
+    apiKey: string | (() => string);
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+};
+export declare class SwitcherClient {
+    private readonly options;
+    readonly baseUrl: string;
+    constructor(options: ClientOptions);
+    request<T>(method: string, path: string, body?: unknown, options?: {
+        version?: number;
+        idempotencyKey?: string;
+    }): Promise<T>;
+    private query;
+    listProviders(options?: {}): Promise<Page<{
+        id: string;
+        name: string;
+        baseUrl: string;
+        protocol: "anthropic-messages" | "openai-responses" | "openai-chat";
+        credentialEnv?: string;
+        authStyle: "bearer" | "x-api-key";
+        modelsPath: string;
+        manualModels: {
+            id: string;
+            name: string;
+            description?: string;
+            contextWindow?: number;
+            maxOutputTokens?: number;
+            inputModalities?: string[];
+            outputModalities?: string[];
+            supportedParameters?: string[];
+        }[];
+        version: number;
+        updatedAt: string;
+    }>>;
+    getProvider(id: string): Promise<{
+        id: string;
+        name: string;
+        baseUrl: string;
+        protocol: "anthropic-messages" | "openai-responses" | "openai-chat";
+        credentialEnv?: string;
+        authStyle: "bearer" | "x-api-key";
+        modelsPath: string;
+        manualModels: {
+            id: string;
+            name: string;
+            description?: string;
+            contextWindow?: number;
+            maxOutputTokens?: number;
+            inputModalities?: string[];
+            outputModalities?: string[];
+            supportedParameters?: string[];
+        }[];
+        version: number;
+        updatedAt: string;
+    }>;
+    createProvider(input: ProviderInput, idempotencyKey?: string): Promise<{
+        id: string;
+        name: string;
+        baseUrl: string;
+        protocol: "anthropic-messages" | "openai-responses" | "openai-chat";
+        credentialEnv?: string;
+        authStyle: "bearer" | "x-api-key";
+        modelsPath: string;
+        manualModels: {
+            id: string;
+            name: string;
+            description?: string;
+            contextWindow?: number;
+            maxOutputTokens?: number;
+            inputModalities?: string[];
+            outputModalities?: string[];
+            supportedParameters?: string[];
+        }[];
+        version: number;
+        updatedAt: string;
+    }>;
+    updateProvider(input: ProviderInput, version: number, idempotencyKey?: string): Promise<{
+        id: string;
+        name: string;
+        baseUrl: string;
+        protocol: "anthropic-messages" | "openai-responses" | "openai-chat";
+        credentialEnv?: string;
+        authStyle: "bearer" | "x-api-key";
+        modelsPath: string;
+        manualModels: {
+            id: string;
+            name: string;
+            description?: string;
+            contextWindow?: number;
+            maxOutputTokens?: number;
+            inputModalities?: string[];
+            outputModalities?: string[];
+            supportedParameters?: string[];
+        }[];
+        version: number;
+        updatedAt: string;
+    }>;
+    deleteProvider(id: string, version: number, idempotencyKey?: string): Promise<{
+        deleted: string;
+    }>;
+    refreshModels(id: string, idempotencyKey?: string): Promise<{
+        models: {
+            id: string;
+            name: string;
+            description?: string;
+            contextWindow?: number;
+            maxOutputTokens?: number;
+            inputModalities?: string[];
+            outputModalities?: string[];
+            supportedParameters?: string[];
+        }[];
+        refreshedAt: string;
+        source: "remote" | "manual";
+    }>;
+    listModels(id: string, options?: {}): Promise<{
+        data: {
+            id: string;
+            name: string;
+            description?: string;
+            contextWindow?: number;
+            maxOutputTokens?: number;
+            inputModalities?: string[];
+            outputModalities?: string[];
+            supportedParameters?: string[];
+            codingEligible: boolean;
+        }[];
+        total: number;
+        limit: number;
+        offset: number;
+        refreshedAt: string;
+        source: "remote" | "manual";
+    }>;
+    listProfiles(options?: {}): Promise<Page<{
+        id: string;
+        name: string;
+        providerId: string;
+        harness: "claude" | "codex" | "grok" | "opencode2";
+        model: string;
+        version: number;
+        updatedAt: string;
+    }>>;
+    getProfile(id: string): Promise<{
+        id: string;
+        name: string;
+        providerId: string;
+        harness: "claude" | "codex" | "grok" | "opencode2";
+        model: string;
+        version: number;
+        updatedAt: string;
+    }>;
+    createProfile(input: ProfileInput, idempotencyKey?: string): Promise<{
+        id: string;
+        name: string;
+        providerId: string;
+        harness: "claude" | "codex" | "grok" | "opencode2";
+        model: string;
+        version: number;
+        updatedAt: string;
+    }>;
+    updateProfile(input: ProfileInput, version: number, idempotencyKey?: string): Promise<{
+        id: string;
+        name: string;
+        providerId: string;
+        harness: "claude" | "codex" | "grok" | "opencode2";
+        model: string;
+        version: number;
+        updatedAt: string;
+    }>;
+    deleteProfile(id: string, version: number, idempotencyKey?: string): Promise<{
+        deleted: string;
+    }>;
+    launchPlan(profileId: string, idempotencyKey?: string): Promise<{
+        provider: {
+            id: string;
+            name: string;
+            baseUrl: string;
+            protocol: "anthropic-messages" | "openai-responses" | "openai-chat";
+            credentialEnv?: string;
+            authStyle: "bearer" | "x-api-key";
+            modelsPath: string;
+            manualModels: {
+                id: string;
+                name: string;
+                description?: string;
+                contextWindow?: number;
+                maxOutputTokens?: number;
+                inputModalities?: string[];
+                outputModalities?: string[];
+                supportedParameters?: string[];
+            }[];
+            version: number;
+            updatedAt: string;
+        };
+        profile: {
+            id: string;
+            name: string;
+            providerId: string;
+            harness: "claude" | "codex" | "grok" | "opencode2";
+            model: string;
+            version: number;
+            updatedAt: string;
+        };
+        catalog: {
+            models: {
+                id: string;
+                name: string;
+                description?: string;
+                contextWindow?: number;
+                maxOutputTokens?: number;
+                inputModalities?: string[];
+                outputModalities?: string[];
+                supportedParameters?: string[];
+            }[];
+            refreshedAt: string;
+            source: "remote" | "manual";
+        };
+        planToken: string;
+        warnings: string[];
+    }>;
+    listRuns(options?: {}): Promise<Page<{
+        profileId: string;
+        harness: "claude" | "codex" | "grok" | "opencode2";
+        model: string;
+        planToken: string;
+        version: number;
+        updatedAt: string;
+        providerId: string;
+        providerVersion: number;
+        profileVersion: number;
+        id: string;
+        status: "running" | "exited" | "failed" | "interrupted";
+        startedAt: string;
+        endedAt?: string;
+        exitCode?: number;
+    }>>;
+    getRun(id: string): Promise<{
+        profileId: string;
+        harness: "claude" | "codex" | "grok" | "opencode2";
+        model: string;
+        planToken: string;
+        version: number;
+        updatedAt: string;
+        providerId: string;
+        providerVersion: number;
+        profileVersion: number;
+        id: string;
+        status: "running" | "exited" | "failed" | "interrupted";
+        startedAt: string;
+        endedAt?: string;
+        exitCode?: number;
+    }>;
+    createRun(input: components["schemas"]["RunInput"], idempotencyKey?: string): Promise<{
+        profileId: string;
+        harness: "claude" | "codex" | "grok" | "opencode2";
+        model: string;
+        planToken: string;
+        version: number;
+        updatedAt: string;
+        providerId: string;
+        providerVersion: number;
+        profileVersion: number;
+        id: string;
+        status: "running" | "exited" | "failed" | "interrupted";
+        startedAt: string;
+        endedAt?: string;
+        exitCode?: number;
+    }>;
+    finishRun(id: string, version: number, input: {
+        status: "exited" | "failed" | "interrupted";
+        exitCode: number;
+    }, idempotencyKey?: string): Promise<{
+        profileId: string;
+        harness: "claude" | "codex" | "grok" | "opencode2";
+        model: string;
+        planToken: string;
+        version: number;
+        updatedAt: string;
+        providerId: string;
+        providerVersion: number;
+        profileVersion: number;
+        id: string;
+        status: "running" | "exited" | "failed" | "interrupted";
+        startedAt: string;
+        endedAt?: string;
+        exitCode?: number;
+    }>;
+}
+export declare function clientFromEnv(env?: Record<string, string | undefined>): SwitcherClient;

package/dist/sdk.js

@@ -0,0 +1,227 @@
+// src/domain.ts
+import { z } from "zod";
+var harnessSchema = z.enum(["claude", "codex", "grok", "opencode2"]);
+var protocolSchema = z.enum(["anthropic-messages", "openai-responses", "openai-chat"]);
+var idSchema = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/);
+var label = z.string().min(1).max(200);
+var envRef = z.string().regex(/^SWITCHER_PROVIDER_[A-Z0-9_]+$/);
+function endpoint(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Fault(400, "invalid_url", "Use an absolute HTTPS URL (HTTP is allowed on loopback).");
+  }
+  const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && local) || url.username || url.password || url.search || url.hash)
+    throw new Fault(400, "invalid_url", "URL must use HTTPS, contain no credentials/query/fragment, or use HTTP on loopback.");
+  return url.href.replace(/\/+$/, "");
+}
+var urlSchema = z.string().max(2000).superRefine((v, ctx) => {
+  try {
+    endpoint(v);
+  } catch {
+    ctx.addIssue({ code: "custom", message: "Invalid endpoint URL" });
+  }
+}).transform(endpoint);
+var modelSchema = z.object({
+  id: z.string().min(1).max(300),
+  name: label,
+  description: z.string().max(8000).optional(),
+  contextWindow: z.number().int().positive().optional(),
+  maxOutputTokens: z.number().int().positive().optional(),
+  inputModalities: z.array(z.string().max(50)).max(20).optional(),
+  outputModalities: z.array(z.string().max(50)).max(20).optional(),
+  supportedParameters: z.array(z.string().max(100)).max(100).optional()
+}).strict();
+var providerInputSchema = z.object({
+  id: idSchema,
+  name: label,
+  baseUrl: urlSchema,
+  protocol: protocolSchema,
+  credentialEnv: envRef.optional(),
+  authStyle: z.enum(["bearer", "x-api-key"]).default("bearer"),
+  modelsPath: z.string().regex(/^[a-zA-Z0-9_/-]+$/).max(200).default("models"),
+  manualModels: z.array(modelSchema).max(1e4).default([])
+}).strict().refine((p) => !p.modelsPath.split("/").includes("..") && !p.modelsPath.startsWith("/"), "modelsPath must be relative");
+var profileInputSchema = z.object({
+  id: idSchema,
+  name: label,
+  providerId: idSchema,
+  harness: harnessSchema,
+  model: z.string().min(1).max(300)
+}).strict();
+var runInputSchema = z.object({
+  profileId: idSchema,
+  harness: harnessSchema,
+  model: z.string().min(1).max(300),
+  planToken: z.string().regex(/^[a-f0-9]{64}$/)
+}).strict();
+var runUpdateSchema = z.object({
+  status: z.enum(["exited", "failed", "interrupted"]),
+  exitCode: z.number().int().min(0).max(255)
+}).strict();
+
+class Fault extends Error {
+  status;
+  code;
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+}
+
+// src/http.ts
+var MAX_BYTES = 16 * 1024 * 1024;
+async function boundedJson(response, maxBytes = MAX_BYTES) {
+  if (!response.body)
+    throw new Fault(502, "invalid_upstream", "Upstream returned no body.");
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  try {
+    while (true) {
+      const item = await reader.read();
+      if (item.done)
+        break;
+      size += item.value.byteLength;
+      if (size > maxBytes)
+        throw new Fault(502, "response_too_large", "Response exceeds the size limit.");
+      chunks.push(item.value);
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset);
+      offset += chunk.length;
+    }
+    try {
+      return JSON.parse(new TextDecoder().decode(bytes));
+    } catch {
+      throw new Fault(502, "invalid_upstream", "Upstream returned invalid JSON.");
+    }
+  } finally {
+    await reader.cancel().catch(() => {});
+  }
+}
+
+// src/sdk.ts
+import { resolveCredential } from "@hasna/contracts/client";
+
+class SwitcherError extends Error {
+  status;
+  code;
+  requestId;
+  constructor(status, code, message, requestId) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.requestId = requestId;
+  }
+}
+
+class SwitcherClient {
+  options;
+  baseUrl;
+  constructor(options) {
+    this.baseUrl = endpoint(options.baseUrl).replace(/\/v1$/, "");
+    if (typeof options.apiKey === "string" && (!options.apiKey || /[\r\n]/.test(options.apiKey)))
+      throw new Error("Switcher API key is required.");
+    this.options = { ...options };
+  }
+  async request(method, path, body, options = {}) {
+    if (!/^\/v1\/[a-zA-Z0-9/?&=._%+-]+$/.test(path) || path.includes(".."))
+      throw new Error("Invalid API path.");
+    const apiKey = typeof this.options.apiKey === "function" ? this.options.apiKey() : this.options.apiKey;
+    if (!apiKey || /[\r\n]/.test(apiKey))
+      throw new Error("Switcher API key is required.");
+    const headers = { authorization: `Bearer ${apiKey}`, accept: "application/json" };
+    if (body !== undefined)
+      headers["content-type"] = "application/json";
+    if (method !== "GET")
+      headers["idempotency-key"] = options.idempotencyKey ?? crypto.randomUUID();
+    if (options.version !== undefined)
+      headers["if-match"] = String(options.version);
+    let response;
+    try {
+      response = await (this.options.fetch ?? fetch)(`${this.baseUrl}${path}`, { method, headers, body: body === undefined ? undefined : JSON.stringify(body), redirect: "manual", signal: AbortSignal.timeout(this.options.timeoutMs ?? 120000) });
+    } catch {
+      throw new SwitcherError(0, "connection_failed", "Switcher API request failed; check endpoint and service availability.");
+    }
+    let data;
+    try {
+      data = await boundedJson(response);
+    } catch {
+      throw new SwitcherError(response.status, "invalid_response", "Switcher API returned invalid JSON.");
+    }
+    if (!response.ok)
+      throw new SwitcherError(response.status, data?.error?.code ?? "api_error", data?.error?.message ?? `Switcher API returned HTTP ${response.status}.`, data?.error?.requestId);
+    return data;
+  }
+  query(options = {}) {
+    return new URLSearchParams(Object.entries(options).filter(([, v]) => v !== undefined).map(([k, v]) => [k, String(v)])).toString();
+  }
+  listProviders(options = {}) {
+    return this.request("GET", `/v1/providers?${this.query(options)}`);
+  }
+  getProvider(id) {
+    return this.request("GET", `/v1/providers/${encodeURIComponent(id)}`);
+  }
+  createProvider(input, idempotencyKey) {
+    return this.request("POST", "/v1/providers", input, { idempotencyKey });
+  }
+  updateProvider(input, version, idempotencyKey) {
+    return this.request("PUT", `/v1/providers/${encodeURIComponent(input.id)}`, input, { version, idempotencyKey });
+  }
+  deleteProvider(id, version, idempotencyKey) {
+    return this.request("DELETE", `/v1/providers/${encodeURIComponent(id)}`, undefined, { version, idempotencyKey });
+  }
+  refreshModels(id, idempotencyKey) {
+    return this.request("POST", `/v1/providers/${encodeURIComponent(id)}/refresh`, {}, { idempotencyKey });
+  }
+  listModels(id, options = {}) {
+    return this.request("GET", `/v1/providers/${encodeURIComponent(id)}/models?${this.query(options)}`);
+  }
+  listProfiles(options = {}) {
+    return this.request("GET", `/v1/profiles?${this.query(options)}`);
+  }
+  getProfile(id) {
+    return this.request("GET", `/v1/profiles/${encodeURIComponent(id)}`);
+  }
+  createProfile(input, idempotencyKey) {
+    return this.request("POST", "/v1/profiles", input, { idempotencyKey });
+  }
+  updateProfile(input, version, idempotencyKey) {
+    return this.request("PUT", `/v1/profiles/${encodeURIComponent(input.id)}`, input, { version, idempotencyKey });
+  }
+  deleteProfile(id, version, idempotencyKey) {
+    return this.request("DELETE", `/v1/profiles/${encodeURIComponent(id)}`, undefined, { version, idempotencyKey });
+  }
+  launchPlan(profileId, idempotencyKey) {
+    return this.request("POST", "/v1/launch-plans", { profileId }, { idempotencyKey });
+  }
+  listRuns(options = {}) {
+    return this.request("GET", `/v1/runs?${this.query(options)}`);
+  }
+  getRun(id) {
+    return this.request("GET", `/v1/runs/${encodeURIComponent(id)}`);
+  }
+  createRun(input, idempotencyKey) {
+    return this.request("POST", "/v1/runs", input, { idempotencyKey });
+  }
+  finishRun(id, version, input, idempotencyKey) {
+    return this.request("PATCH", `/v1/runs/${encodeURIComponent(id)}`, input, { version, idempotencyKey });
+  }
+}
+function clientFromEnv(env = process.env) {
+  const credential = () => resolveCredential("switcher", Object.fromEntries(Object.entries(env).filter(([name]) => name === "HASNA_SWITCHER_API_KEY")), { keychain: { enabled: false } })?.apiKey ?? "";
+  if (!env.HASNA_SWITCHER_API_URL || !credential())
+    throw new Error("Set HASNA_SWITCHER_API_URL and HASNA_SWITCHER_API_KEY; no local database fallback is available.");
+  return new SwitcherClient({ baseUrl: env.HASNA_SWITCHER_API_URL, apiKey: credential });
+}
+export {
+  clientFromEnv,
+  SwitcherError,
+  SwitcherClient
+};