@runappsai/sdk 0.0.0-stage → 0.3.1

package/src/index.ts

@@ -0,0 +1,151 @@
+/**
+ * RunApps SDK for JavaScript / TypeScript.
+ *
+ * Top-level entry point — exports the `RunApps` client class plus all
+ * public types so callers can write strongly-typed wrappers without
+ * reaching into per-service modules.
+ */
+
+export { RunApps, RunApps as Client, RunApps as RunJobs, type ClientOptions, type AuthProvider } from "./client.js";
+
+// SDK telemetry — `client.events` fires these around every LLM-ish
+// service call so UI overlays (the badge being the canonical example)
+// can render real-time state. The ActivityTracker turns the raw
+// stream into the snapshot the badge reads each frame; exported
+// alongside the bus so power users can build their own status UI.
+export {
+  SDKEvents,
+  newRequestId,
+  type RequestStartEvent,
+  type RequestStreamDeltaEvent,
+  type RequestEndEvent,
+  type RequestErrorEvent,
+  type SDKEventMap,
+  type SDKCapability,
+  type Unsubscribe,
+} from "./events.js";
+export {
+  ActivityTracker,
+  type ActiveCall,
+  type CompletedCall,
+  type SessionStats,
+  type ActivitySnapshot,
+} from "./activity-tracker.js";
+export { BrowserAuth, type BrowserAuthOptions, type BrowserUser } from "./browser-auth.js";
+export { APIError } from "./errors.js";
+export type { Usage } from "./types.js";
+
+// Chat — service class is internal; types + builders are public.
+export type {
+  ChatMessage,
+  ContentPart,
+  ChatTool,
+  StreamOptions,
+  ChatCompletionParams,
+  ChatToolCall,
+  ChatChoiceMessage,
+  ChatChoice,
+  ChatCompletion,
+  ChatChunkDelta,
+  ChatChunkChoice,
+  ChatCompletionChunk,
+} from "./chat.js";
+export {
+  userMessage,
+  systemMessage,
+  assistantMessage,
+  toolResultMessage,
+  userMessageParts,
+  textPart,
+  imagePart,
+  videoPart,
+  audioPart,
+} from "./chat.js";
+
+// Models
+export type { Model, ModelListOptions, Tag } from "./models.js";
+export {
+  hasCapabilityTag,
+  acceptsModality,
+  supportsVoiceClone,
+  supportsInstructText,
+  defaultVoice,
+} from "./models.js";
+
+// Model options schema (input validation + capability introspection)
+export type {
+  Schema,
+  FieldSchema,
+  Constraint,
+  ConstraintKind,
+  Catalog,
+} from "./model_options.js";
+export {
+  getOptionsSchema,
+  acceptsField,
+  requiresField,
+  allowedValuesFor,
+} from "./model_options.js";
+export type { ValidationError } from "./validate.js";
+export { validateRequest } from "./validate.js";
+
+// Image
+export type {
+  ImageGenerateParams,
+  ImageResult,
+  ImageUsage,
+  ImageResponse,
+  ImageEditParams,
+  ImageFileInput,
+  AsyncImageJob,
+} from "./image.js";
+
+// Audio
+export type {
+  SpeechParams,
+  SpeechResponse,
+  TranscribeParams,
+  TranscribeResponse,
+  AudioFileInput,
+} from "./audio.js";
+
+// Video
+export type {
+  VideoGenerateParams,
+  VideoTask,
+  VideoStatus,
+  VideoUsageTokens,
+  WaitOptions,
+} from "./video.js";
+
+// Media helpers (shared by image + video + chat-multimodal)
+export { encodeImageUrl, decodeMediaUrl } from "./media.js";
+
+// Computer
+export type {
+  ComputerStepParams,
+  ComputerContentBlock,
+  ComputerResponse,
+} from "./computer.js";
+
+// Files (per-project file system)
+export type {
+  FileObject,
+  FileListResult,
+  PutOptions as FilePutOptions,
+  ListOptions as FileListOptions,
+  PutFromURLOptions as FilePutFromURLOptions,
+  BatchOp as FileBatchOp,
+  BatchResult as FileBatchResult,
+} from "./files.js";
+
+// Embeddings
+export type {
+  EmbeddingsParams,
+  Embedding,
+  EmbeddingsUsage,
+  EmbeddingsResponse,
+} from "./embeddings.js";
+
+// Server-tool names for chat.create({ server_tools }), with autocomplete.
+export { ServerTools, type ServerToolName } from "./chat.js";

package/src/media.ts

@@ -0,0 +1,147 @@
+/**
+ * Media helpers shared by image / video / chat-multimodal endpoints.
+ *
+ * The gateway accepts media payloads as `data:<mime>;base64,<payload>`
+ * URIs on every `*_url` field — `encodeImageUrl` is the bridge from
+ * raw bytes to that wire format. Replaces the deprecated `*_b64` SDK
+ * fields, which were removed in favour of routing every payload
+ * through `*_url`.
+ */
+
+/**
+ * Wrap raw image bytes as a `data:<mime>;base64,<payload>` URI.
+ *
+ * MIME is sniffed from the magic bytes (PNG / JPEG / GIF / WebP). On
+ * unrecognised input we default to `application/octet-stream` — most
+ * upstreams accept and re-sniff server-side.
+ *
+ * @param bytes Image bytes — `Uint8Array`, `ArrayBuffer`, or `Blob`.
+ * @returns A data: URI suitable for any `*_url` field on the gateway.
+ *
+ * @example
+ * ```ts
+ * import { encodeImageUrl } from "@runjobs/sdk";
+ * const png = await fs.readFile("frame.png");
+ * await client.video.generate("Veo 3.1", {
+ *   prompt: "...",
+ *   first_frame_url: encodeImageUrl(png),
+ * });
+ * ```
+ */
+export function encodeImageUrl(
+  bytes: Uint8Array | ArrayBuffer | Blob,
+): string {
+  // Normalize to Uint8Array so the rest of the function is uniform.
+  if (bytes instanceof Blob) {
+    throw new Error(
+      "encodeImageUrl: Blob input requires async; await blob.arrayBuffer() and pass the result instead",
+    );
+  }
+  const u8 = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+
+  const mime = sniffImageMime(u8);
+
+  // btoa(String.fromCharCode(...u8)) blows the stack on large arrays;
+  // chunk to keep arg count bounded. 0x8000 is the conventional safe
+  // limit on JS engines.
+  const CHUNK = 0x8000;
+  let binary = "";
+  for (let i = 0; i < u8.length; i += CHUNK) {
+    binary += String.fromCharCode.apply(
+      null,
+      Array.from(u8.subarray(i, i + CHUNK)),
+    );
+  }
+  // btoa is browser-native and shimmed in Node ≥ 16 globalThis.
+  const b64 = (globalThis as { btoa?: (s: string) => string }).btoa
+    ? (globalThis as { btoa: (s: string) => string }).btoa(binary)
+    : Buffer.from(binary, "binary").toString("base64");
+
+  return `data:${mime};base64,${b64}`;
+}
+
+/**
+ * Resolve a media URL to raw bytes plus the declared mime label.
+ *
+ * Inverse of `encodeImageUrl`. Two transport modes handled:
+ *   - "data:<mime>;base64,<payload>"  — decode the inline payload
+ *   - "https://...", "http://..."     — `fetch()` + `.arrayBuffer()`,
+ *                                       mime from the response's
+ *                                       `Content-Type` header
+ *
+ * Returns `{bytes: Uint8Array, contentType: string}`. Pairs with
+ * `encodeImageUrl` so callers can round-trip bytes through the gateway
+ * without thinking about which transport mode the response chose.
+ *
+ * @example
+ * ```ts
+ * import { decodeMediaUrl } from "@runjobs/sdk";
+ * const job = await client.image.generateAsync("Seedream 5.0", {...});
+ * const { bytes, contentType } = await decodeMediaUrl(job.data[0].url);
+ * await fs.writeFile("out.png", bytes);
+ * ```
+ */
+export async function decodeMediaUrl(
+  url: string,
+): Promise<{ bytes: Uint8Array; contentType: string }> {
+  if (url.startsWith("data:")) {
+    const rest = url.slice(5);
+    const semi = rest.indexOf(";");
+    const comma = rest.indexOf(",");
+    if (semi === -1 || comma === -1 || comma < semi) {
+      throw new Error("decodeMediaUrl: malformed data URI");
+    }
+    const mime = rest.slice(0, semi);
+    const b64 = rest.slice(comma + 1);
+    return { bytes: base64ToBytes(b64), contentType: mime };
+  }
+  if (url.startsWith("http://") || url.startsWith("https://")) {
+    const resp = await fetch(url);
+    if (!resp.ok) {
+      throw new Error(`decodeMediaUrl: upstream ${resp.status}`);
+    }
+    const buf = await resp.arrayBuffer();
+    return {
+      bytes: new Uint8Array(buf),
+      contentType: resp.headers.get("Content-Type") ?? "",
+    };
+  }
+  throw new Error(`decodeMediaUrl: unsupported url scheme: ${url.slice(0, 32)}`);
+}
+
+/** Decode standard base64 to Uint8Array. Browser `atob` + Node `Buffer`
+ *  fallback — same impl as the audio service uses internally. */
+function base64ToBytes(b64: string): Uint8Array {
+  if (typeof Buffer !== "undefined") {
+    return new Uint8Array(Buffer.from(b64, "base64"));
+  }
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+/**
+ * Sniff a small set of image mimes from magic bytes. Mirrors the
+ * gateway's own sniff so encode / decode round-trip lands on the same
+ * label.
+ */
+function sniffImageMime(b: Uint8Array): string {
+  if (b.length >= 8 &&
+      b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47) {
+    return "image/png";
+  }
+  if (b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) {
+    return "image/jpeg";
+  }
+  if (b.length >= 6 &&
+      b[0] === 0x47 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x38) {
+    return "image/gif";
+  }
+  if (b.length >= 12 &&
+      b[0] === 0x52 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x46 &&
+      b[8] === 0x57 && b[9] === 0x45 && b[10] === 0x42 && b[11] === 0x50) {
+    return "image/webp";
+  }
+  return "application/octet-stream";
+}

package/src/model_options.ts

@@ -0,0 +1,220 @@
+// Mirror of internal/api/options_schema/types.go on the JS side.
+// See API.md "Options schema" for the full contract; the gateway
+// materialises this from the legacy options blob at /v1/models
+// response time.
+
+import type { Model } from "./models.js";
+
+/** Wire-format options shape returned by /v1/models. */
+export interface Schema {
+  /**
+   * Per-field constraints, keyed by canonical request field name
+   * (matching the JSON keys on Image/Video/Speech/Embed/Transcribe
+   * params). A field absent from this map is NOT accepted by the
+   * model.
+   */
+  inputs?: Record<string, FieldSchema>;
+  /** Cross-field rules. */
+  constraints?: Constraint[];
+  /** Rich content (TTS voices, emotions). */
+  catalog?: Catalog;
+}
+
+export interface FieldSchema {
+  type:
+    | "string"
+    | "int"
+    | "float"
+    | "bool"
+    | "url"
+    | "url[]"
+    | "string[]"
+    | "file";
+  /** Default when omitted is "optional". */
+  presence?: "required" | "optional" | "forbidden";
+  min?: number;
+  max?: number;
+  default?: unknown;
+  enum?: unknown[];
+  max_items?: number;
+  /** Lower-bound counterpart of max_items. Applies to array types
+   *  AND `repeatable` object groups. Nil = no minimum. */
+  min_items?: number;
+  /** Semantic hint for media-input fields. */
+  role?: "source" | "reference" | "motion";
+  /** When present, this field is a structured sub-object. The wire
+   *  value is `{<inner-name>: <value>, ...}` matching this inner
+   *  schema; renderers recurse into it. With `repeatable: true` the
+   *  wire value becomes an array of such objects (e.g. multi-utterance
+   *  TTS "+ add another group"). */
+  fields?: Record<string, FieldSchema>;
+  /** Pairs with `fields`: array-of-objects rather than a single
+   *  nested object. Ignored when `fields` is absent. */
+  repeatable?: boolean;
+
+  // ─── Display metadata — drives auto-rendered playground / form UIs.
+  // All optional; renderers fall back to type/role-based rendering
+  // when absent. See API.md "Options schema" for the full vocabulary.
+
+  /** Human-readable display label. Falls back to the field name. */
+  label?: string;
+  /** One-sentence tooltip / sub-text explainer. */
+  help?: string;
+  /**
+   * Widget override hint:
+   *   "textarea"     — large multi-line string
+   *   "slider"       — numeric with min/max
+   *   "radio"        — small enum
+   *   "voice_picker" — string with values from catalog.voices
+   *   "code"         — long string with syntax highlighting
+   *   "segmented"    — pill-shaped row of enum values (compact,
+   *                    horizontal). Best for short ordered enums
+   *                    like the resolution tier (512P / 1K / 2K /
+   *                    4K) in image generation. Renders as a single
+   *                    line; selected option has solid background.
+   *   "tile"         — grid of square cards, each carrying a small
+   *                    visual proxy for the value (aspect-ratio
+   *                    shape icon, or fit-brackets for the
+   *                    "adaptive" sentinel). Used for aspect_ratio
+   *                    in image generation. When the enum includes
+   *                    "adaptive" or "auto", that entry is
+   *                    promoted to a row-spanning anchor block.
+   *   "tabs"         — horizontal tab strip. Same data contract as
+   *                    "radio" but a different visual. Drives
+   *                    `ui.show_when` on sibling fields.
+   *   "card_group"   — bordered card containing the field's nested
+   *                    `fields`. With `repeatable: true` the card
+   *                    becomes a "+ add another"-able stack.
+   * Unknown values fall back to the type default (forward-compat).
+   */
+  widget?: string;
+  /**
+   * Nested presentational hints:
+   *   "group" (string)      — sectional grouping ("main"/"advanced"/"output").
+   *   "order" (int)         — display order within the group; lower first.
+   *   "card_label" (string) — title above a card_group; "{{i}}" is
+   *                           substituted with the card index for
+   *                           repeatable groups.
+   *   "show_when" ({field, equals})
+   *                         — purely-visual conditional: hide this
+   *                           field unless a sibling's value matches.
+   *                           Validator ignores it; server still
+   *                           accepts conditionally-hidden fields.
+   */
+  ui?: {
+    group?: string;
+    order?: number;
+    card_label?: string;
+    show_when?: { field: string; equals: unknown };
+    [k: string]: unknown;
+  };
+}
+
+export type ConstraintKind =
+  | "any_of_required"
+  | "mutually_exclusive"
+  | "group_mutex"
+  | "requires_all"
+  | "pixel_bounds";
+
+export interface Group {
+  /** Stable id; also the value the discriminator field
+   *  (`Constraint.name`) takes when this group is active. */
+  name?: string;
+  /** Tab strip display label. Falls back to `name`. */
+  label?: string;
+  fields: string[];
+}
+
+export interface Constraint {
+  kind: ConstraintKind;
+  fields?: string[];
+  /**
+   * On a `group_mutex` constraint, names the discriminator field
+   * selecting which group is active. The renderer auto-injects a
+   * `tabs` input with this name (enum = group names) and gives
+   * every group member an implicit `show_when` pointing at it.
+   * When omitted, the constraint behaves as legacy anonymous-group
+   * mutex — all members render flat, mutex enforced at submit.
+   */
+  name?: string;
+  /**
+   * Human-readable title for the synthesized tab widget (e.g.
+   * "Animation mode"). Falls back to `name` when omitted.
+   */
+  label?: string;
+  /**
+   * Used by `group_mutex`. Wire shape is either the legacy
+   * `string[][]` (each `[a,b,...]` reads as an anonymous
+   * `{fields:[a,b,...]}` Group) or the new `Group[]`. Consumers
+   * should normalize via `normalizeGroups()` before reading.
+   */
+  groups?: Group[] | string[][];
+  when?: string;
+  then?: string[];
+  min?: number;
+  max?: number;
+}
+
+/**
+ * Normalize either legacy `string[][]` or new `Group[]` into a
+ * uniform `Group[]`. Mirror of sdk-go's `Group.UnmarshalJSON`.
+ */
+export function normalizeGroups(g: Constraint["groups"]): Group[] {
+  if (!g) return [];
+  return g.map(item =>
+    Array.isArray(item) ? { fields: item as string[] } : (item as Group),
+  );
+}
+
+export interface Catalog {
+  voices?: Array<Record<string, unknown>>;
+  emotions?: string[];
+}
+
+/**
+ * Parse the model's wire-format `options` blob into the typed Schema.
+ * Returns null when the model has no options or the blob can't be
+ * structurally decoded — callers fall back to whatever default
+ * behaviour they had pre-schema.
+ */
+export function getOptionsSchema(model: Model): Schema | null {
+  const opts = model.options;
+  if (!opts || typeof opts !== "object") return null;
+  // The Model interface types options as Record<string, unknown>;
+  // Schema has the same JSON layout, so a structural cast is safe
+  // as long as the gateway emits the wire shape we expect. SDK
+  // consumers should call validateRequest() to surface errors —
+  // this getter is a thin typed view over the same data.
+  return opts as unknown as Schema;
+}
+
+/**
+ * True iff the model declares an Inputs entry for `name` with
+ * presence != "forbidden". Use for "should I show this UI chip"
+ * decisions.
+ */
+export function acceptsField(model: Model, name: string): boolean {
+  const schema = getOptionsSchema(model);
+  const f = schema?.inputs?.[name];
+  if (!f) return false;
+  return f.presence !== "forbidden";
+}
+
+/**
+ * True iff the schema marks `name` as presence: "required". Use for
+ * red-star UI marks and submit-button gating.
+ */
+export function requiresField(model: Model, name: string): boolean {
+  const schema = getOptionsSchema(model);
+  return schema?.inputs?.[name]?.presence === "required";
+}
+
+/**
+ * Discrete enum for the named field, or null if no enum constraint.
+ * Use to populate dropdown options on the client.
+ */
+export function allowedValuesFor(model: Model, name: string): unknown[] | null {
+  const schema = getOptionsSchema(model);
+  return schema?.inputs?.[name]?.enum ?? null;
+}

package/src/models.ts

@@ -0,0 +1,121 @@
+import type { Transport } from "./transport.js";
+
+/**
+ * One model available on the gateway. Pricing is in **pips** (1 USD =
+ * 1,000,000 pips), per million tokens — multiply by tokens / 10⁶ for the
+ * billed pip cost, or by tokens / 10¹² for USD.
+ */
+export interface Model {
+  id: string;
+  object: string;
+  capability: string;
+  provider?: string;
+  /**
+   * Server-derived "what this model can actually do" tags
+   * (e.g. {id:"t2v", label:"Text-to-Video"}, {id:"i2v", label:"Image-to-Video"}).
+   * Use `hasCapabilityTag` for stable filter checks; iterate for display.
+   * Labels are in English — frontends localise on their side.
+   */
+  capability_tags?: Tag[];
+  /**
+   * Accepted input modalities for chat models. Omitted on capabilities
+   * where it doesn't apply (image generation, TTS, etc.). Mirrors
+   * Anthropic / Gemini's own `inputModalities` field — operator-set on
+   * the gateway, surfaced verbatim here.
+   *
+   * Canonical values: `"text"`, `"image"`, `"video"`, `"audio"`. The
+   * list is open — future modalities ride through without an SDK
+   * update. Use `acceptsModality` for the stable filter check.
+   *
+   * @example
+   *   const videoCapable = models.filter(m => acceptsModality(m, "video"));
+   */
+  input_modalities?: string[];
+  options?: Record<string, unknown>;
+  input_price_per_mtok: number;
+  output_price_per_mtok: number;
+  fixed_price: boolean;
+  fixed_cost: number;
+  max_tokens: number;
+  max_input_tokens: number;
+  icon_url?: string;
+  available_voices?: string[];
+}
+
+/**
+ * One capability tag. Mirrors options_schema.Tag on the gateway. IDs
+ * are stable across releases; Labels are subject to translation.
+ */
+export interface Tag {
+  id: string;
+  label: string;
+}
+
+/** True iff `model.capability_tags` includes a tag with the given stable ID. */
+export const hasCapabilityTag = (model: Model, id: string): boolean =>
+  Array.isArray(model.capability_tags) &&
+  model.capability_tags.some((t) => t.id === id);
+
+/**
+ * True iff the chat model accepts the given input modality. Lets you
+ * filter by `"image"` / `"video"` / `"audio"` (or `"text"`, always
+ * true for chat models that set the field at all) without remembering
+ * whether the gateway uses canonical or aliased names.
+ *
+ * Returns `false` when `input_modalities` is unset — text-only is the
+ * conservative default.
+ *
+ * @example
+ *   const videoModels = (await client.models.list())
+ *     .filter(m => acceptsModality(m, "video"));
+ */
+export const acceptsModality = (model: Model, modality: string): boolean =>
+  Array.isArray(model.input_modalities) &&
+  model.input_modalities.includes(modality);
+
+export interface ModelListOptions {
+  /** Filter to one capability (e.g. "text", "vision", "image", "tts"). */
+  capability?: string;
+}
+
+/** True iff the gateway flag in `options[key]` is set. Accepts bool or numeric 1. */
+function optBool(model: Model, key: string): boolean {
+  const v = model.options?.[key];
+  if (typeof v === "boolean") return v;
+  if (typeof v === "number") return v !== 0;
+  return false;
+}
+
+/** Convenience: TTS model accepts a reference audio clip as `voice`? */
+export const supportsVoiceClone = (model: Model): boolean =>
+  optBool(model, "supports_voice_clone");
+
+/** Convenience: TTS model accepts a free-form `instruct_text` directive? */
+export const supportsInstructText = (model: Model): boolean =>
+  optBool(model, "supports_instruct_text");
+
+/** Convenience: admin-set default voice for a TTS model, or null. */
+export const defaultVoice = (model: Model): string | null => {
+  const v = model.options?.["default_voice"];
+  return typeof v === "string" ? v : null;
+};
+
+export class ModelsService {
+  constructor(private readonly transport: Transport) {}
+
+  /**
+   * List models available on the gateway. Pass `{ capability: "..." }` to
+   * filter server-side.
+   */
+  async list(
+    opts: ModelListOptions = {},
+    init?: { signal?: AbortSignal },
+  ): Promise<Model[]> {
+    let path = "/v1/models";
+    if (opts.capability) {
+      path += `?capability=${encodeURIComponent(opts.capability)}`;
+    }
+    const resp = await this.transport.getJSON<{ data: Model[] }>(path, init);
+    return resp.data;
+  }
+}