@runappsai/sdk 0.0.0-stage → 0.3.0

package/src/embeddings.ts

@@ -0,0 +1,97 @@
+import type { Transport } from "./transport.js";
+import type { Usage } from "./types.js";
+import type { SDKEvents } from "./events.js";
+import { wrapEvents } from "./event-wrap.js";
+
+/* ------------------------------------------------------------------ */
+/* Embeddings — POST /v1/embeddings                                    */
+/* ------------------------------------------------------------------ */
+/*                                                                     */
+/* OpenAI-compatible vector embedding endpoint. Wire shape mirrors     */
+/* OpenAI's `/v1/embeddings` exactly so callers porting from the      */
+/* official `openai` SDK can swap the import line and keep working.    */
+/* ------------------------------------------------------------------ */
+
+export interface EmbeddingsParams {
+  /** Single string OR array of strings — gateway forwards either
+   *  shape verbatim. Passing a string returns `data: [{...}]` (1
+   *  element), passing an array returns one element per input. */
+  input: string | string[];
+  /** OpenAI per-end-user observability tag. */
+  user?: string;
+  /** "float" (default) or "base64". `base64` packs vectors as
+   *  little-endian float32 + base64-encoded — saves bandwidth for
+   *  high-D embeddings (3072-D × 1000 docs is ~3× smaller than the
+   *  JSON float-array form). */
+  encoding_format?: "float" | "base64";
+  /** Truncate the output vector. text-embedding-3-* only — other
+   *  models reject. */
+  dimensions?: number;
+}
+
+export interface Embedding {
+  object: "embedding";
+  /** Vector. When `encoding_format` was "float" (default), this is
+   *  `number[]`. When "base64", this is the encoded `string`. */
+  embedding: number[] | string;
+  index: number;
+}
+
+/** OpenAI's usage block plus the gateway's billing extension
+ *  (`total_cost` in USD).
+ *
+ *  Shape parallels the `Usage` type used by chat / image / video so
+ *  callers can read `.total_cost` on every response uniformly. */
+export interface EmbeddingsUsage extends Usage {
+  prompt_tokens: number;
+  total_tokens: number;
+}
+
+export interface EmbeddingsResponse {
+  object: "list";
+  data: Embedding[];
+  model: string;
+  usage: EmbeddingsUsage;
+}
+
+export class EmbeddingsService {
+  constructor(
+    private readonly transport: Transport,
+    private readonly events: SDKEvents,
+  ) {}
+
+  /**
+   * Create one or more embeddings.
+   *
+   * ```ts
+   * const r = await client.embeddings.create("text-embedding-3-small", {
+   *   input: ["alpha", "beta"],
+   *   dimensions: 1536,
+   * });
+   * for (const e of r.data) {
+   *   console.log(e.index, (e.embedding as number[]).slice(0, 4));
+   * }
+   * console.log(`Cost: $${r.usage.total_cost.toFixed(6)}`);
+   * ```
+   */
+  async create(
+    model: string,
+    params: EmbeddingsParams,
+    init?: { signal?: AbortSignal },
+  ): Promise<EmbeddingsResponse> {
+    return wrapEvents(
+      this.events,
+      { model, capability: "embedding" },
+      () =>
+        this.transport.postJSON<EmbeddingsResponse>(
+          "/v1/embeddings",
+          { model, ...params },
+          init,
+        ),
+      (r) => ({
+        totalTokens: r.usage?.total_tokens,
+        costUSD: r.usage?.total_cost,
+      }),
+    );
+  }
+}

package/src/errors.ts

@@ -0,0 +1,29 @@
+/**
+ * APIError represents an error returned by the RunApps gateway.
+ *
+ * Use `instanceof APIError` (or check `name === "APIError"`) to distinguish
+ * gateway errors from network / runtime errors:
+ *
+ * ```ts
+ * try {
+ *   await client.chat.create({ model: "...", messages: [...] });
+ * } catch (e) {
+ *   if (e instanceof APIError) {
+ *     console.error(`API ${e.statusCode}: ${e.message}`);
+ *   } else {
+ *     throw e;
+ *   }
+ * }
+ * ```
+ */
+export class APIError extends Error {
+  public readonly statusCode: number;
+  public readonly type: string;
+
+  constructor(statusCode: number, type: string, message: string) {
+    super(`runapps: ${statusCode} ${type}: ${message}`);
+    this.name = "APIError";
+    this.statusCode = statusCode;
+    this.type = type;
+  }
+}

package/src/event-wrap.ts

@@ -0,0 +1,168 @@
+/**
+ * Tiny wrapper used by every LLM-ish service to fire
+ * `request:start` → `request:end` / `request:error` events around a
+ * single network call. Centralised here so the service files don't
+ * duplicate the try/catch + latency-stopwatch pattern N times.
+ *
+ * Streaming chat has its own logic (it must yield deltas mid-flight)
+ * — see `wrapStream` below.
+ */
+
+import { newRequestId, type SDKCapability, type SDKEvents } from "./events.js";
+
+interface CallMeta {
+  model: string;
+  capability: SDKCapability;
+}
+
+interface EndInfo {
+  totalTokens?: number;
+  costUSD?: number;
+  finishReason?: string;
+}
+
+/**
+ * Run `fn` while emitting start/end/error events around it.
+ * `extractEnd` plucks token / cost / finish_reason off the response
+ * shape so each service can map its own response type without the
+ * helper knowing about it.
+ *
+ * Re-throws on error so the caller still sees the rejection — the
+ * helper only inserts telemetry, it doesn't swallow.
+ */
+export async function wrapEvents<T>(
+  events: SDKEvents,
+  meta: CallMeta,
+  fn: () => Promise<T>,
+  extractEnd?: (r: T) => EndInfo,
+): Promise<T> {
+  const id = newRequestId();
+  const startedAt = Date.now();
+  events.emit("request:start", {
+    id,
+    model: meta.model,
+    capability: meta.capability,
+    startedAt,
+    streaming: false,
+  });
+  try {
+    const result = await fn();
+    const info = extractEnd ? extractEnd(result) : {};
+    events.emit("request:end", {
+      id,
+      model: meta.model,
+      capability: meta.capability,
+      latencyMs: Date.now() - startedAt,
+      totalTokens: info.totalTokens ?? 0,
+      ...(info.costUSD !== undefined && { costUSD: info.costUSD }),
+      ...(info.finishReason !== undefined && { finishReason: info.finishReason }),
+    });
+    return result;
+  } catch (err) {
+    const e = err as Error & { statusCode?: number };
+    events.emit("request:error", {
+      id,
+      model: meta.model,
+      capability: meta.capability,
+      latencyMs: Date.now() - startedAt,
+      error: e,
+      ...(typeof e.statusCode === "number" && { statusCode: e.statusCode }),
+    });
+    throw err;
+  }
+}
+
+/**
+ * Token-count estimator for stream deltas. Stream chunks carry text,
+ * not tokens — getting an exact count would mean shipping a
+ * tokenizer in the SDK (huge), so we use the standard ~4-chars =
+ * 1-token English heuristic. Off by 10-30% for code or non-English,
+ * but the badge UI shows tokens/sec as a vibe indicator, not for
+ * billing, so the imprecision is fine.
+ */
+export function estimateTokens(text: string): number {
+  if (!text) return 0;
+  return Math.max(1, Math.round(text.length / 4));
+}
+
+/**
+ * Stream wrapper — same start/end/error envelope as wrapEvents but
+ * also fires `request:streamDelta` for each yielded chunk so the
+ * badge's tokens/sec sliding window has samples.
+ *
+ * Generic over the chunk type because each service's stream
+ * (chat / video / etc.) carries its own shape. The caller passes a
+ * `extractDelta` that pulls text + cumulative usage off the chunk.
+ *
+ * Usage:
+ *   yield* wrapStream(events, {model, capability}, () => transport.postJSONStream(...),
+ *     (chunk) => ({ deltaText: chunk.choices[0]?.delta?.content, usage: chunk.usage }));
+ */
+export async function* wrapStream<TChunk>(
+  events: SDKEvents,
+  meta: CallMeta,
+  source: () => AsyncIterable<TChunk>,
+  extractDelta: (chunk: TChunk) => {
+    deltaText?: string;
+    // When a chunk carries cumulative usage (final chunk in OpenAI
+    // streams), surface it so the end event can use exact totals
+    // instead of the heuristic running sum.
+    completionTokens?: number;
+    costUSD?: number;
+    finishReason?: string;
+  },
+): AsyncGenerator<TChunk, void, unknown> {
+  const id = newRequestId();
+  const startedAt = Date.now();
+  events.emit("request:start", {
+    id,
+    model: meta.model,
+    capability: meta.capability,
+    startedAt,
+    streaming: true,
+  });
+  let totalTokens = 0;
+  let lastUsageTokens: number | undefined;
+  let costUSD: number | undefined;
+  let finishReason: string | undefined;
+  try {
+    for await (const chunk of source()) {
+      const info = extractDelta(chunk);
+      if (info.deltaText) {
+        const delta = estimateTokens(info.deltaText);
+        totalTokens += delta;
+        events.emit("request:streamDelta", {
+          id,
+          deltaTokens: delta,
+          totalTokens,
+        });
+      }
+      if (info.completionTokens !== undefined) lastUsageTokens = info.completionTokens;
+      if (info.costUSD !== undefined) costUSD = info.costUSD;
+      if (info.finishReason !== undefined) finishReason = info.finishReason;
+      yield chunk;
+    }
+    events.emit("request:end", {
+      id,
+      model: meta.model,
+      capability: meta.capability,
+      latencyMs: Date.now() - startedAt,
+      // Prefer the exact upstream count over our heuristic when it
+      // arrived in the final chunk.
+      totalTokens: lastUsageTokens ?? totalTokens,
+      ...(costUSD !== undefined && { costUSD }),
+      ...(finishReason !== undefined && { finishReason }),
+    });
+  } catch (err) {
+    const e = err as Error & { statusCode?: number };
+    events.emit("request:error", {
+      id,
+      model: meta.model,
+      capability: meta.capability,
+      latencyMs: Date.now() - startedAt,
+      error: e,
+      ...(typeof e.statusCode === "number" && { statusCode: e.statusCode }),
+    });
+    throw err;
+  }
+}

package/src/events.ts

@@ -0,0 +1,172 @@
+/**
+ * Typed runtime event bus for SDK call telemetry.
+ *
+ * Every LLM-ish service method (chat, embeddings, image, audio, video,
+ * computer) emits start / streamDelta / end / error events on the
+ * shared `client.events` bus so UI overlays (e.g. the bottom-right
+ * identity badge with its activity ring) can render real-time state
+ * without business code having to thread anything through.
+ *
+ * Goals:
+ *   - **Typed**: handler signatures are inferred from the event name.
+ *   - **Zero-cost when nobody listens**: no listeners → emit is a few
+ *     property reads. The browser `EventTarget` does the heavy lifting.
+ *   - **Service-agnostic**: events carry just enough context (id /
+ *     model / capability / token counts) for a generic UI to render
+ *     them without knowing which service fired the call.
+ *
+ * Why a custom wrapper instead of `EventTarget` directly:
+ *   - The native API is untyped (`addEventListener("foo", anyHandler)`).
+ *   - Browser CustomEvent's `detail` payload trick is awkward to read.
+ *   - Subscribers want an `off()` closure, not a separate
+ *     `removeEventListener` call with the same callback reference.
+ */
+
+/** Capability bucket of the calling service, mirroring /v1/models. */
+export type SDKCapability =
+  | "text"
+  | "vision"
+  | "embedding"
+  | "image_generation"
+  | "image_edit"
+  | "text_to_speech"
+  | "speech_to_text"
+  | "video_generation"
+  | "computer_use";
+
+/** Fired the moment a request hits the wire. */
+export interface RequestStartEvent {
+  /** Stable id correlating start → end/error events for one call. */
+  id: string;
+  /** Model name the caller asked for (NOT the upstream id). */
+  model: string;
+  /** Capability bucket — drives badge icon / colour. */
+  capability: SDKCapability;
+  /** ms since epoch when the request left the SDK. */
+  startedAt: number;
+  /** `true` for stream:true requests so the UI can pre-pick the
+   *  pulsing-ring animation instead of swapping mid-call. */
+  streaming: boolean;
+}
+
+/** Fired on every stream chunk that carried new content tokens. */
+export interface RequestStreamDeltaEvent {
+  /** Matches the corresponding RequestStartEvent.id. */
+  id: string;
+  /** Approximate completion tokens in THIS chunk (one delta event
+   *  per visible SSE chunk; usage roll-up arrives in end). */
+  deltaTokens: number;
+  /** Cumulative completion tokens since stream start. */
+  totalTokens: number;
+}
+
+/** Fired once when the call settles successfully. */
+export interface RequestEndEvent {
+  id: string;
+  model: string;
+  capability: SDKCapability;
+  /** Wall-clock from start to settle. */
+  latencyMs: number;
+  /** Final completion tokens (matches the gateway's usage.completion_tokens
+   *  when the response carries it; 0 otherwise). */
+  totalTokens: number;
+  /** USD cost as reported by the gateway's `usage.total_cost`. May be
+   *  undefined for endpoints that don't return cost (rare). */
+  costUSD?: number;
+  /** OpenAI-style stop / length / tool_calls / content_filter, or
+   *  undefined for non-chat endpoints. */
+  finishReason?: string;
+}
+
+/** Fired once when the call fails — at start, mid-stream, or anywhere. */
+export interface RequestErrorEvent {
+  id: string;
+  model: string;
+  capability: SDKCapability;
+  latencyMs: number;
+  /** The thrown Error (typically `APIError` with statusCode / body). */
+  error: Error;
+  /** HTTP status when known (forwarded from APIError when present). */
+  statusCode?: number;
+}
+
+/** Compile-time map of event name → payload shape. Drives handler
+ *  inference in `on()` / `emit()` so callers can't subscribe to a
+ *  typo'd name or read a non-existent field. */
+export interface SDKEventMap {
+  "request:start": RequestStartEvent;
+  "request:streamDelta": RequestStreamDeltaEvent;
+  "request:end": RequestEndEvent;
+  "request:error": RequestErrorEvent;
+}
+
+/** Disposer returned by `on()` — call to unsubscribe. */
+export type Unsubscribe = () => void;
+
+/**
+ * Lightweight typed event bus. Backed by `EventTarget` so memory
+ * leaks from un-disposed listeners surface in the standard DevTools
+ * memory profile path. In Node we fall back to a plain Map<string,
+ * Set<handler>> since `EventTarget` was only added in Node 15+ and we
+ * still support 14 in places (the SDK targets 18+ but tests sometimes
+ * stub globals).
+ */
+export class SDKEvents {
+  private readonly handlers = new Map<keyof SDKEventMap, Set<(payload: unknown) => void>>();
+
+  /**
+   * Subscribe to an event. Returns a disposer; calling the disposer
+   * removes the subscription. Multiple subscriptions to the same
+   * event are supported.
+   */
+  on<K extends keyof SDKEventMap>(name: K, handler: (event: SDKEventMap[K]) => void): Unsubscribe {
+    let set = this.handlers.get(name);
+    if (!set) {
+      set = new Set();
+      this.handlers.set(name, set);
+    }
+    const wrapped = handler as (payload: unknown) => void;
+    set.add(wrapped);
+    return () => {
+      this.handlers.get(name)?.delete(wrapped);
+    };
+  }
+
+  /**
+   * Fire an event. Handlers run synchronously in subscription order.
+   * Throws inside one handler don't prevent the others from running —
+   * the bus catches and logs (console.error) so a buggy listener can't
+   * take down the rest of the UI.
+   */
+  emit<K extends keyof SDKEventMap>(name: K, payload: SDKEventMap[K]): void {
+    const set = this.handlers.get(name);
+    if (!set || set.size === 0) return;
+    for (const h of set) {
+      try {
+        h(payload);
+      } catch (err) {
+        // Listener bug — don't propagate, but surface in the console
+        // so developers notice during integration.
+        // eslint-disable-next-line no-console
+        console.error("[runapps sdk] event listener for", name, "threw:", err);
+      }
+    }
+  }
+
+  /** Drop all subscriptions. Tests call this between cases. */
+  clear(): void {
+    this.handlers.clear();
+  }
+}
+
+/** Generate a short opaque ID for correlating start/end events.
+ *  Not a UUID — sub-microsecond uniqueness within a session is
+ *  enough, and we want to keep the wire log compact. */
+export function newRequestId(): string {
+  return (
+    "req_" +
+    Date.now().toString(36) +
+    "_" +
+    Math.random().toString(36).slice(2, 8)
+  );
+}