@runappsai/sdk 0.0.0-stage → 0.3.0

package/src/transport.ts

@@ -0,0 +1,292 @@
+import { APIError } from "./errors.js";
+
+/**
+ * Internal — shared HTTP transport used by every service. Not part of the
+ * public API; do not import from outside `src/`.
+ *
+ * Uses the global `fetch` (Node 18+ / browsers / Deno / Bun all ship it).
+ * Errors from the gateway (status >= 400) are parsed and surfaced as
+ * `APIError`. Network errors propagate as the underlying fetch reject.
+ */
+export interface TransportOptions {
+  baseURL: string;
+  /** Static bearer token. Required unless `apiKeyResolver` is supplied. */
+  apiKey?: string;
+  /** Dynamic resolver — called immediately before each request. Use this
+   *  when the token is short-lived and refreshed externally (e.g. running
+   *  inside a runjobs resource bundle that exposes
+   *  `window.runjobs.getToken()`). The result is awaited per request, so
+   *  the caller can return a Promise that hits a token endpoint. Wins
+   *  over `apiKey` when both are supplied. */
+  apiKeyResolver?: () => string | Promise<string>;
+  /**
+   * Hook invoked on 401 responses, *before* the request is automatically
+   * retried once.  Use this to invalidate any cached token so the next
+   * `apiKeyResolver` call fetches a fresh one.  Throwing here cancels
+   * the retry — the original 401 propagates.
+   *
+   * Typical wiring (browser-auth):
+   *   onUnauthorized: () => auth.invalidate()
+   * which clears the in-memory + persisted token without flipping the
+   * sticky "signed out" flag.  The retry's resolveToken() then triggers
+   * the standard signIn() redirect-grant flow.
+   */
+  onUnauthorized?: () => void | Promise<void>;
+  /** Optional fetch override (e.g. node-fetch with custom agent). */
+  fetchImpl?: typeof fetch;
+}
+
+export class Transport {
+  readonly baseURL: string;
+  private readonly apiKey: string | undefined;
+  private readonly apiKeyResolver: (() => string | Promise<string>) | undefined;
+  private readonly onUnauthorized: (() => void | Promise<void>) | undefined;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(opts: TransportOptions) {
+    if (!opts.apiKey && !opts.apiKeyResolver) {
+      throw new Error(
+        "RunApps: pass either `apiKey` or `apiKeyResolver` when constructing the client",
+      );
+    }
+    this.baseURL = opts.baseURL.replace(/\/+$/, "");
+    this.apiKey = opts.apiKey;
+    this.apiKeyResolver = opts.apiKeyResolver;
+    this.onUnauthorized = opts.onUnauthorized;
+    // Bind to globalThis when using the platform's native fetch.
+    // Without binding, `this.fetchImpl(...)` invokes with `this`
+    // pointing at the Transport instance, and the browser's
+    // `Window.fetch` rejects that with "Illegal invocation".
+    // Caller-supplied `fetchImpl` is used as-is — they're responsible
+    // for any binding their wrapper needs.
+    this.fetchImpl = opts.fetchImpl ?? fetch.bind(globalThis);
+  }
+
+  /** Resolve the bearer token for the next request. */
+  private async resolveToken(): Promise<string> {
+    if (this.apiKeyResolver) return await this.apiKeyResolver();
+    return this.apiKey ?? "";
+  }
+
+  /**
+   * Wrap a fetch call with single-attempt 401 retry.  `build` produces a
+   * fresh RequestInit each call (so headers can re-resolve a fresh token,
+   * and bodies can be re-streamed for retry).  On 401, invokes
+   * `onUnauthorized()` (giving the caller a chance to invalidate cached
+   * auth state) then retries once with a fresh init.  No retry if
+   * `onUnauthorized` is absent or already retried.
+   */
+  private async fetchWithAuthRetry(
+    path: string,
+    build: () => Promise<RequestInit>,
+  ): Promise<Response> {
+    const url = this.baseURL + path;
+    let resp = await this.fetchImpl(url, await this.buildInit(build));
+    if (resp.status !== 401 || !this.onUnauthorized) return resp;
+    try {
+      await this.onUnauthorized();
+    } catch {
+      // Hook bailed out — surface the original 401.
+      return resp;
+    }
+    resp = await this.fetchImpl(url, await this.buildInit(build));
+    return resp;
+  }
+
+  /**
+   * Every request goes out uncacheable.
+   *
+   * Our identity lives in the Authorization header, never in the URL — so
+   * two different apps calling e.g. `/v1/files/projects/index.json` hit the
+   * *same* URL with different tokens.  The browser's HTTP cache doesn't key
+   * on request headers, and it is partitioned by the top-level registrable
+   * domain, which every `*.runapps.dev` bundle shares.  One cacheable
+   * response was therefore enough for app A to read app B's file and then
+   * save it back as its own.  The server no longer marks these cacheable;
+   * this is the client-side half of that fix, and it also protects bundles
+   * pinned to an older backend.
+   */
+  private async buildInit(build: () => Promise<RequestInit>): Promise<RequestInit> {
+    const init = await build();
+    return init.cache ? init : { ...init, cache: "no-store" };
+  }
+
+  /** POST JSON body; parse JSON response. */
+  async postJSON<T>(
+    path: string,
+    body: unknown,
+    init?: { signal?: AbortSignal },
+  ): Promise<T> {
+    const resp = await this.fetchWithAuthRetry(path, async () => ({
+      method: "POST",
+      headers: await this.jsonHeaders(),
+      body: JSON.stringify(body),
+      signal: init?.signal,
+    }));
+    if (!resp.ok) {
+      throw await this.parseError(resp);
+    }
+    return (await resp.json()) as T;
+  }
+
+  /** GET path; parse JSON response. */
+  async getJSON<T>(
+    path: string,
+    init?: { signal?: AbortSignal },
+  ): Promise<T> {
+    const resp = await this.fetchWithAuthRetry(path, async () => ({
+      method: "GET",
+      headers: await this.authHeaders(),
+      signal: init?.signal,
+    }));
+    if (!resp.ok) {
+      throw await this.parseError(resp);
+    }
+    return (await resp.json()) as T;
+  }
+
+  /** GET path; return raw bytes + content-type (for video/audio downloads)
+   *  and the ETag of those bytes, when the server sends one. */
+  async getRaw(
+    path: string,
+    init?: { signal?: AbortSignal },
+  ): Promise<{ data: Uint8Array; contentType: string; etag?: string }> {
+    const resp = await this.fetchWithAuthRetry(path, async () => ({
+      method: "GET",
+      headers: await this.authHeaders(),
+      signal: init?.signal,
+    }));
+    if (!resp.ok) {
+      throw await this.parseError(resp);
+    }
+    const buf = new Uint8Array(await resp.arrayBuffer());
+    const contentType = resp.headers.get("content-type") ?? "";
+    const etag = (resp.headers.get("etag") ?? "").replace(/"/g, "") || undefined;
+    return { data: buf, contentType, etag };
+  }
+
+  /** POST a multipart/form-data body. Used by audio.transcribe and image.edit. */
+  async postMultipart<T>(
+    path: string,
+    form: FormData,
+    init?: { signal?: AbortSignal },
+  ): Promise<T> {
+    const resp = await this.fetchWithAuthRetry(path, async () => ({
+      method: "POST",
+      headers: await this.authHeaders(), // do NOT set Content-Type — fetch sets it with boundary
+      body: form,
+      signal: init?.signal,
+    }));
+    if (!resp.ok) {
+      throw await this.parseError(resp);
+    }
+    return (await resp.json()) as T;
+  }
+
+  /**
+   * POST JSON body; return the raw streaming Response. Used by chat
+   * streaming. Caller is responsible for consuming the SSE body.
+   */
+  async postJSONStream(
+    path: string,
+    body: unknown,
+    init?: { signal?: AbortSignal },
+  ): Promise<Response> {
+    const resp = await this.fetchWithAuthRetry(path, async () => ({
+      method: "POST",
+      headers: {
+        ...(await this.jsonHeaders()),
+        "Accept-Encoding": "identity", // SSE lines arrive immediately, no gzip
+      },
+      body: JSON.stringify(body),
+      signal: init?.signal,
+    }));
+    if (!resp.ok) {
+      throw await this.parseError(resp);
+    }
+    return resp;
+  }
+
+  /** PUT raw bytes with caller-supplied content type and headers. */
+  async putBytes<T>(
+    path: string,
+    body: BodyInit,
+    opts?: {
+      contentType?: string;
+      headers?: Record<string, string>;
+      signal?: AbortSignal;
+      parse?: "json" | "none";
+    },
+  ): Promise<T> {
+    const resp = await this.fetchWithAuthRetry(path, async () => {
+      const headers: Record<string, string> = {
+        ...(await this.authHeaders()),
+        "Content-Type": opts?.contentType ?? "application/octet-stream",
+      };
+      if (opts?.headers) Object.assign(headers, opts.headers);
+      return {
+        method: "PUT",
+        headers,
+        body,
+        signal: opts?.signal,
+      };
+    });
+    if (!resp.ok) throw await this.parseError(resp);
+    if (opts?.parse === "none") return undefined as unknown as T;
+    return (await resp.json()) as T;
+  }
+
+  /** DELETE path; parse JSON response (or no body). */
+  async deletePath<T>(
+    path: string,
+    init?: { signal?: AbortSignal; parse?: "json" | "none" },
+  ): Promise<T> {
+    const resp = await this.fetchWithAuthRetry(path, async () => ({
+      method: "DELETE",
+      headers: await this.authHeaders(),
+      signal: init?.signal,
+    }));
+    if (!resp.ok) throw await this.parseError(resp);
+    if (init?.parse === "none") return undefined as unknown as T;
+    return (await resp.json()) as T;
+  }
+
+  /** HEAD path; surface status + selected response headers.  Used by
+   *  exists / stat where the body would just be an opaque blob. */
+  async head(
+    path: string,
+    init?: { signal?: AbortSignal },
+  ): Promise<{ status: number; headers: Headers }> {
+    const resp = await this.fetchWithAuthRetry(path, async () => ({
+      method: "HEAD",
+      headers: await this.authHeaders(),
+      signal: init?.signal,
+    }));
+    return { status: resp.status, headers: resp.headers };
+  }
+
+  private async jsonHeaders(): Promise<Record<string, string>> {
+    return {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${await this.resolveToken()}`,
+    };
+  }
+
+  private async authHeaders(): Promise<Record<string, string>> {
+    return { Authorization: `Bearer ${await this.resolveToken()}` };
+  }
+
+  private async parseError(resp: Response): Promise<APIError> {
+    const text = await resp.text();
+    let type = "error";
+    let message = text || resp.statusText;
+    try {
+      const parsed = JSON.parse(text) as { type?: string; message?: string };
+      if (parsed.type) type = parsed.type;
+      if (parsed.message) message = parsed.message;
+    } catch {
+      // Body wasn't JSON — fall back to raw text.
+    }
+    return new APIError(resp.status, type, message);
+  }
+}

package/src/types.ts

@@ -0,0 +1,31 @@
+/**
+ * Usage carries token consumption and cost information returned with every
+ * gateway response. `total_cost` is the gateway's billing total in USD —
+ * always present, while token counts are only populated when the upstream
+ * provider surfaces them.
+ *
+ * For chat completions that invoked server-executed tools (via the
+ * `server_tools` field), `total_cost` includes BOTH the model's raw
+ * upstream cost (summed across iterations) AND the post-markup USD price
+ * of every tool invocation.  The per-tool breakdown lives in `tool_costs`
+ * so callers can attribute charges without having to re-run the loop.
+ */
+export interface Usage {
+  prompt_tokens?: number;
+  completion_tokens?: number;
+  total_tokens?: number;
+  total_cost: number;
+  tool_costs?: ToolCost[];
+}
+
+/**
+ * Per-tool spend for a single chat completion that used server-executed
+ * tools.  `cost` is in USD and already post-markup — it matches the
+ * amount actually deducted from the user's balance for that tool's
+ * invocations during the request.
+ */
+export interface ToolCost {
+  name: string;
+  count: number;
+  cost: number;
+}

package/src/validate.ts

@@ -0,0 +1,364 @@
+// Generic validator for the gateway's options schema. Mirrors
+// /Users/zero/repos/sdk-go/validate.go — three-pass algorithm,
+// same field/constraint vocabulary, same parse logic.
+
+import { normalizeGroups } from "./model_options.js";
+import type { Schema, FieldSchema, Constraint, Group } from "./model_options.js";
+
+export interface ValidationError {
+  field: string;
+  reason: string;
+}
+
+/**
+ * Three-pass validator: per-field type/enum/bounds → per-field
+ * presence → cross-field constraints. Unknown fields in `req`
+ * (vendor passthroughs) are silently ignored — the gateway still
+ * validates them server-side if it cares.
+ *
+ * Returns an empty array on success, or a flat list of all
+ * validation failures so the UI can surface them at once.
+ */
+export function validateRequest(
+  schema: Schema | null | undefined,
+  req: Record<string, unknown> = {},
+): ValidationError[] {
+  if (!schema) return [];
+  const errors: ValidationError[] = [];
+
+  // Pass 1+2: per-field.
+  if (schema.inputs) {
+    for (const [name, field] of Object.entries(schema.inputs)) {
+      const set = name in req;
+      const val = req[name];
+      if (set && !isEmpty(val)) {
+        errors.push(...validateFieldValue(name, field, val));
+      } else if (set && field.min_items !== undefined) {
+        // Empty array trips min_items even when isEmpty() short-
+        // circuits validateFieldValue. Mirrors the sdk-go fix: bound
+        // was declared explicitly, dropping it silently would let a
+        // client POST `groups: []` to a schema that requires >=1.
+        if (Array.isArray(val) && val.length < field.min_items) {
+          errors.push({ field: name, reason: `at least ${field.min_items} items` });
+        }
+      }
+      errors.push(...validatePresence(name, field, val, set));
+    }
+  }
+
+  // Pass 3: cross-field.
+  for (const c of schema.constraints ?? []) {
+    errors.push(...validateConstraint(c, req));
+  }
+
+  return errors;
+}
+
+function validateFieldValue(
+  name: string,
+  field: FieldSchema,
+  val: unknown,
+): ValidationError[] {
+  const errors: ValidationError[] = [];
+
+  if (!typeMatches(field.type, val)) {
+    errors.push({
+      field: name,
+      reason: `expected type ${field.type}, got ${describeType(val)}`,
+    });
+    return errors; // bail early — bound/enum checks need correct type
+  }
+
+  if (field.enum && field.enum.length > 0 && !inEnum(val, field.enum)) {
+    errors.push({
+      field: name,
+      reason: `must be one of ${JSON.stringify(field.enum)}`,
+    });
+  }
+
+  if (field.type === "int" || field.type === "float") {
+    const n = numberValue(val);
+    if (n !== null) {
+      if (field.min !== undefined && n < field.min) {
+        errors.push({ field: name, reason: `must be >= ${field.min}` });
+      }
+      if (field.max !== undefined && n > field.max) {
+        errors.push({ field: name, reason: `must be <= ${field.max}` });
+      }
+    }
+  }
+
+  // Array bounds — apply to scalar array Types ("url[]", "string[]")
+  // AND to `repeatable` object groups whose value is a JSON array.
+  if (Array.isArray(val)) {
+    if (field.max_items !== undefined && val.length > field.max_items) {
+      errors.push({
+        field: name,
+        reason: `at most ${field.max_items} items`,
+      });
+    }
+    if (field.min_items !== undefined && val.length < field.min_items) {
+      errors.push({
+        field: name,
+        reason: `at least ${field.min_items} items`,
+      });
+    }
+  }
+
+  // Nested object recursion. `field.fields` declares a structured
+  // sub-object; with `repeatable: true` the wire value is an array of
+  // such objects. Errors carry a dotted path like
+  // "groups[1].prompt: required" so callers see the offending row.
+  // `ui.show_when` is deliberately NOT honoured at validation time —
+  // it's a UI hint only; conditionally-hidden fields are still
+  // subject to the same checks if a client sends them.
+  if (field.fields) {
+    if (field.repeatable) {
+      if (!Array.isArray(val)) {
+        errors.push({
+          field: name,
+          reason: `expected array of objects, got ${describeType(val)}`,
+        });
+      } else {
+        val.forEach((item, i) => {
+          if (typeof item !== "object" || item === null || Array.isArray(item)) {
+            errors.push({
+              field: `${name}[${i}]`,
+              reason: `expected object, got ${describeType(item)}`,
+            });
+            return;
+          }
+          errors.push(...validateObject(`${name}[${i}]`, field.fields!, item as Record<string, unknown>));
+        });
+      }
+    } else {
+      if (typeof val !== "object" || val === null || Array.isArray(val)) {
+        errors.push({
+          field: name,
+          reason: `expected object, got ${describeType(val)}`,
+        });
+      } else {
+        errors.push(...validateObject(name, field.fields, val as Record<string, unknown>));
+      }
+    }
+  }
+
+  return errors;
+}
+
+/** validateObject runs per-field validation against a sub-schema's
+ *  `fields` map for one object value. Errors return with
+ *  `<pathPrefix>.<innerName>` so the caller sees the full nested path. */
+function validateObject(
+  pathPrefix: string,
+  fields: Record<string, FieldSchema>,
+  obj: Record<string, unknown>,
+): ValidationError[] {
+  const errors: ValidationError[] = [];
+  for (const [innerName, innerField] of Object.entries(fields)) {
+    const childPath = `${pathPrefix}.${innerName}`;
+    const val = obj[innerName];
+    const set = innerName in obj;
+    if (set && !isEmpty(val)) {
+      errors.push(...validateFieldValue(childPath, innerField, val));
+    }
+    errors.push(...validatePresence(childPath, innerField, val, set));
+  }
+  return errors;
+}
+
+function validatePresence(
+  name: string,
+  field: FieldSchema,
+  val: unknown,
+  set: boolean,
+): ValidationError[] {
+  const presence = field.presence ?? "optional";
+  if (presence === "required" && (!set || isEmpty(val))) {
+    return [{ field: name, reason: "required" }];
+  }
+  if (presence === "forbidden" && set && !isEmpty(val)) {
+    return [{ field: name, reason: "must not be set for this model" }];
+  }
+  return [];
+}
+
+function validateConstraint(
+  c: Constraint,
+  req: Record<string, unknown>,
+): ValidationError[] {
+  switch (c.kind) {
+    case "any_of_required": {
+      const fields = c.fields ?? [];
+      const anySet = fields.some((f) => f in req && !isEmpty(req[f]));
+      if (anySet) return [];
+      return [
+        {
+          field: fields.join("/"),
+          reason: `at least one of ${fields.join(", ")} is required`,
+        },
+      ];
+    }
+
+    case "mutually_exclusive": {
+      const fields = c.fields ?? [];
+      const setFields = fields.filter((f) => f in req && !isEmpty(req[f]));
+      if (setFields.length > 1) {
+        return [
+          {
+            field: setFields.join("/"),
+            reason: `at most one of ${fields.join(", ")} may be set (got: ${setFields.join(", ")})`,
+          },
+        ];
+      }
+      return [];
+    }
+
+    case "group_mutex": {
+      // Best-effort: enforce only the anonymous "at most one group
+      // active" rule for both shapes. The strict discriminator-based
+      // check (validating `c.name`'s value + rejecting non-active
+      // group fields) lives in the gateway only — SDK validation
+      // stays a fast pre-flight hint, not a contract enforcer, so we
+      // avoid doubling the maintenance surface across SDKs.
+      const groups: Group[] = normalizeGroups(c.groups);
+      const activeGroups: Group[] = [];
+      const activeFields: string[] = [];
+      for (const g of groups) {
+        const setHere = g.fields.filter((f) => f in req && !isEmpty(req[f]));
+        if (setHere.length > 0) {
+          activeGroups.push(g);
+          activeFields.push(...setHere);
+        }
+      }
+      if (activeGroups.length > 1) {
+        const labels = groups.map((g) => `[${g.fields.join("+")}]`).join(" or ");
+        return [
+          {
+            field: activeFields.join("/"),
+            reason: `at most one of ${labels} may be used (got: ${activeFields.join(", ")})`,
+          },
+        ];
+      }
+      return [];
+    }
+
+    case "requires_all": {
+      const whenName = c.when;
+      if (!whenName) return [];
+      const whenSet = whenName in req && !isEmpty(req[whenName]);
+      if (!whenSet) return [];
+      const missing = (c.then ?? []).filter(
+        (f) => !(f in req) || isEmpty(req[f]),
+      );
+      if (missing.length === 0) return [];
+      return [
+        {
+          field: missing.join("/"),
+          reason: `required when ${whenName} is set`,
+        },
+      ];
+    }
+
+    case "pixel_bounds": {
+      const fieldName = c.fields?.[0];
+      if (!fieldName) return [];
+      const raw = req[fieldName];
+      if (typeof raw !== "string" || raw === "") return [];
+      const dims = parsePixelDims(raw);
+      if (!dims) {
+        return [{ field: fieldName, reason: `expected WxH dimensions, got "${raw}"` }];
+      }
+      const [w, h] = dims;
+      const px = w * h;
+      const errs: ValidationError[] = [];
+      if (c.min !== undefined && px < c.min) {
+        errs.push({
+          field: fieldName,
+          reason: `image too small: ${w}x${h} = ${px} pixels, minimum ${c.min}`,
+        });
+      }
+      if (c.max !== undefined && px > c.max) {
+        errs.push({
+          field: fieldName,
+          reason: `image too large: ${w}x${h} = ${px} pixels, maximum ${c.max}`,
+        });
+      }
+      return errs;
+    }
+  }
+  // Unknown constraint kind — skip (forward-compat).
+  return [];
+}
+
+// ─── Type helpers ────────────────────────────────────────────────────
+
+function typeMatches(typ: string, val: unknown): boolean {
+  switch (typ) {
+    case "string":
+      return typeof val === "string";
+    case "int":
+    case "float":
+      return numberValue(val) !== null;
+    case "bool":
+      return typeof val === "boolean";
+    case "url":
+      return typeof val === "string" && isURLLike(val);
+    case "url[]":
+      return Array.isArray(val) && val.every((v) => typeof v === "string" && isURLLike(v));
+    case "string[]":
+      return Array.isArray(val) && val.every((v) => typeof v === "string");
+    case "file":
+      return true; // multipart — can't validate
+    default:
+      return true; // unknown type — forward-compat
+  }
+}
+
+function describeType(val: unknown): string {
+  if (val === null) return "null";
+  if (Array.isArray(val)) return "array";
+  return typeof val;
+}
+
+function numberValue(val: unknown): number | null {
+  if (typeof val === "number" && Number.isFinite(val)) return val;
+  return null;
+}
+
+function isURLLike(s: string): boolean {
+  return s.startsWith("http://") || s.startsWith("https://") || s.startsWith("data:");
+}
+
+function isEmpty(val: unknown): boolean {
+  if (val === undefined || val === null) return true;
+  if (typeof val === "string") return val === "";
+  if (Array.isArray(val)) return val.length === 0;
+  return false;
+}
+
+function inEnum(val: unknown, enumVals: unknown[]): boolean {
+  for (const e of enumVals) {
+    if (equalLoose(val, e)) return true;
+  }
+  return false;
+}
+
+function equalLoose(a: unknown, b: unknown): boolean {
+  // Numbers compared as JS numbers (already float64-equivalent);
+  // strings/bools by ===.
+  return a === b;
+}
+
+function parsePixelDims(s: string): [number, number] | null {
+  for (const sep of ["x", "X", "*", "×"]) {
+    const idx = s.indexOf(sep);
+    if (idx <= 0) continue;
+    const w = parseInt(s.slice(0, idx).trim(), 10);
+    const h = parseInt(s.slice(idx + sep.length).trim(), 10);
+    if (Number.isFinite(w) && Number.isFinite(h) && w > 0 && h > 0) {
+      return [w, h];
+    }
+  }
+  return null;
+}