@chai-ui/core 0.8.0 → 0.10.0

package/src/server/chai-handler.ts

@@ -11,14 +11,26 @@
 
 const FAL_QUEUE_BASE = "https://queue.fal.run";
 const OPENROUTER_CHAT_URL = "https://openrouter.ai/api/v1/chat/completions";
+const VERCEL_GATEWAY_BASE = "https://ai-gateway.vercel.sh/v1";
 
-export type ChaiProviderId = "fal" | "openrouter";
+export type ChaiProviderId = "fal" | "openrouter" | "vercel";
+
+const PROVIDER_LABEL: Record<ChaiProviderId, string> = {
+  fal: "Fal.ai",
+  openrouter: "OpenRouter",
+  vercel: "Vercel AI Gateway",
+};
 
 export interface ChaiHandlerOptions {
   /** Defaults to the `FAL_KEY` environment variable. */
   falKey?: string;
   /** Defaults to the `OPENROUTER_API_KEY` environment variable. */
   openRouterKey?: string;
+  /**
+   * Vercel AI Gateway key. Defaults to `AI_GATEWAY_API_KEY`, then to
+   * `VERCEL_OIDC_TOKEN`, which Vercel sets automatically on deployed apps.
+   */
+  aiGatewayKey?: string;
   /**
    * Who may use this route. Return false to reject with 403. Without it,
    * anyone who can reach your site can spend your API credit: check your
@@ -26,7 +38,7 @@ export interface ChaiHandlerOptions {
    */
   authorize?: (request: Request) => boolean | Promise<boolean>;
   /**
-   * The only model ids this route will run, across both providers (e.g.
+   * The only model ids this route will run, across all providers (e.g.
    * `"fal-ai/flux/schnell"`, `"anthropic/claude-opus-5"`). Anything else is
    * rejected with 403, so nobody can run an expensive model through you.
    * Omit to allow every model.
@@ -79,6 +91,26 @@ export function createChaiHandler(options: ChaiHandlerOptions = {}): ChaiHandler
       });
     }
 
+    // Vercel AI Gateway is OpenAI-compatible: /chat for text, /images for image generation.
+    if (route.provider === "vercel") {
+      const upstream = route.rest === "chat" ? "chat/completions" : route.rest === "images" ? "images/generations" : null;
+      if (!upstream) return fail(404, `Unknown Vercel AI Gateway path "${route.rest}".`);
+      if (request.method !== "POST") return fail(405, "Use POST.");
+      const key = options.aiGatewayKey ?? readEnv("AI_GATEWAY_API_KEY") ?? readEnv("VERCEL_OIDC_TOKEN");
+      if (!key) return fail(500, "AI_GATEWAY_API_KEY isn't set on the server.");
+      const body = await request.text();
+      const model = readModel(body);
+      if (options.allowedModels && !(model && options.allowedModels.includes(model))) {
+        return fail(403, `Model "${model ?? "(none)"}" isn't allowed on this server.`);
+      }
+      return forward(fetchImpl, route.provider, `${VERCEL_GATEWAY_BASE}/${upstream}`, {
+        signal: request.signal,
+        method: "POST",
+        headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
+        body,
+      });
+    }
+
     // Fal's queue API: POST /<model> submits, GET /<model>/requests/<id>[/status]
     // polls, PUT /<model>/requests/<id>/cancel cancels.
     const isCancel = request.method === "PUT" && route.rest.endsWith("/cancel");
@@ -102,7 +134,7 @@ export function createChaiHandler(options: ChaiHandlerOptions = {}): ChaiHandler
 /** Finds the provider segment anywhere in the path, so the route can be mounted at any prefix. */
 function parseRoute(pathname: string): { provider: ChaiProviderId; rest: string } | null {
   const parts = pathname.split("/").filter(Boolean);
-  const i = parts.findIndex((p) => p === "fal" || p === "openrouter");
+  const i = parts.findIndex((p) => p === "fal" || p === "openrouter" || p === "vercel");
   if (i === -1 || i === parts.length - 1) return null;
   return { provider: parts[i] as ChaiProviderId, rest: parts.slice(i + 1).join("/") };
 }
@@ -116,11 +148,11 @@ async function forward(fetchImpl: typeof fetch, provider: ChaiProviderId, url: s
       headers: { "Content-Type": upstream.headers.get("content-type") ?? "application/json" },
     });
   } catch (err) {
-    return errorResponse(provider, 502, `Couldn't reach ${provider === "fal" ? "Fal.ai" : "OpenRouter"}: ${err instanceof Error ? err.message : String(err)}`);
+    return errorResponse(provider, 502, `Couldn't reach ${PROVIDER_LABEL[provider]}: ${err instanceof Error ? err.message : String(err)}`);
   }
 }
 
-/** Errors in the shape each engine already reads: Fal's `{ error }`, OpenRouter's `{ error: { message } }`. */
+/** Errors in the shape each engine already reads: Fal's `{ error }`, OpenRouter's and Vercel's `{ error: { message } }`. */
 function errorResponse(provider: ChaiProviderId, status: number, message: string): Response {
   const body = provider === "fal" ? { error: message } : { error: { message } };
   return Response.json(body, { status });

package/src/suggested-models.ts

@@ -4,7 +4,8 @@ import { DEFAULT_MAX_REGIONS } from "./region-edit.js";
 /**
  * Suggested models, so builders don't have to write model lists. Composer
  * and MediaAnalyzer use them when no `models` is passed; passing `models`
- * still replaces them. The first model in each list is the default pick.
+ * still replaces them. Nothing is picked for the person: with a Model menu
+ * they pick or turn on auto-select; with no menu, the list's first runs.
  *
  * Generation runs on Fal (the default engine), analysis on OpenRouter (the
  * reasoning engine). Every entry was checked against the provider's own

package/src/voice-input.ts

@@ -0,0 +1,257 @@
+/**
+ * Voice input for the Composer: record from the microphone, send the clip
+ * to a speech-to-text model, and hand back the transcript. Framework-free,
+ * so React and Vue each add only the button.
+ */
+import { abortError, isAbortError } from "./engine.js";
+import { createFalTranscriber } from "./engines/fal.js";
+
+/** A recorded clip, as a data URL. */
+export interface VoiceClip {
+  src: string;
+  kind: "audio";
+  /** What the browser recorded, e.g. `"audio/webm;codecs=opus"` (Chrome, Firefox) or `"audio/mp4"` (Safari). */
+  mimeType: string;
+}
+
+/** Turns a recorded clip into text. Reject with an `AbortError` when `signal` aborts. */
+export type Transcribe = (audio: VoiceClip, options?: { signal?: AbortSignal }) => Promise<string>;
+
+/**
+ * Turns on the Composer's mic. Name a Fal speech-to-text model and Chai
+ * sends the clip through your existing `/api/chai/fal` route, or pass your
+ * own `transcribe` for any other provider. There's no default model: the
+ * mic shows only once you choose one.
+ */
+export type VoiceInputConfig = (
+  | { model: string; transcribe?: never; endpoint?: string }
+  | { transcribe: Transcribe; model?: never; endpoint?: never }
+) & {
+  /** Longest recording, in seconds. Recording stops and transcribes at this length. Defaults to 60. */
+  maxSeconds?: number;
+};
+
+export type VoiceInputStatus = "idle" | "recording" | "transcribing" | "error";
+
+export interface VoiceInputState {
+  status: VoiceInputStatus;
+  /** How long the current recording has run. */
+  elapsedMs: number;
+  /** A short message for the person while `status` is "error". */
+  error: string | null;
+  /**
+   * The microphone's recent loudness while recording, oldest first, each
+   * 0–1: what a waveform draws, so the person sees they're being heard.
+   * Empty when not recording, or when the browser has no Web Audio.
+   */
+  levels: number[];
+}
+
+/** How many level readings a waveform shows. */
+export const VOICE_LEVEL_COUNT = 48;
+
+export const DEFAULT_VOICE_MAX_SECONDS = 60;
+
+/** Recording formats, best first. Chrome and Firefox record WebM, Safari MP4. */
+const MIME_TYPES = ["audio/webm;codecs=opus", "audio/webm", "audio/mp4", "audio/ogg;codecs=opus"];
+
+/** The `Transcribe` a config describes: its own, or a Fal transcriber for its model. */
+export function voiceTranscriber(config: VoiceInputConfig): Transcribe {
+  return config.transcribe ?? createFalTranscriber({ model: config.model!, endpoint: config.endpoint });
+}
+
+/** "0:05", "1:00": how long a recording has run. */
+export function formatVoiceElapsed(ms: number): string {
+  const s = Math.floor(ms / 1000);
+  return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, "0")}`;
+}
+
+/** Why the microphone couldn't start, in words for the person. */
+export function describeMicError(err: unknown): string {
+  const { name, message } = (err as { name?: string; message?: string } | null) ?? {};
+  // Chrome's wording when the computer, not the site, blocks the browser
+  // (macOS Privacy & Security, Windows microphone privacy).
+  if (name === "NotAllowedError" && /system/i.test(message ?? "")) {
+    return "Your computer is blocking this browser from the microphone. Allow it in your system's privacy settings, then reload.";
+  }
+  if (name === "NotAllowedError" || name === "SecurityError") {
+    return "Microphone access is blocked. Allow it in your browser's site settings to use voice input.";
+  }
+  if (name === "NotFoundError" || name === "OverconstrainedError") return "No microphone found.";
+  if (name === "NotReadableError") return "The microphone is in use by another app.";
+  return "The microphone couldn't start.";
+}
+
+interface VoiceInputDeps {
+  /** Defaults to the browser's `navigator.mediaDevices.getUserMedia`. */
+  getUserMedia?: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
+  /** Defaults to the browser's `MediaRecorder`. */
+  MediaRecorder?: typeof MediaRecorder;
+  /** Defaults to the browser's `AudioContext`, for the waveform. Without one, recording still works. */
+  AudioContext?: typeof AudioContext;
+}
+
+/**
+ * The recorder behind the mic button. `start` asks for the microphone and
+ * records; `stop` ends the recording and transcribes it; `cancel` stops
+ * either without a transcript. `onTranscript` gets the text: it never
+ * submits, so the person can fix it first.
+ */
+export function createVoiceInput(
+  getConfig: () => VoiceInputConfig,
+  onTranscript: (text: string) => void,
+  deps: VoiceInputDeps = {}
+) {
+  let state: VoiceInputState = { status: "idle", elapsedMs: 0, error: null, levels: [] };
+  const listeners = new Set<() => void>();
+  const set = (next: Partial<VoiceInputState>) => {
+    state = { ...state, ...next };
+    listeners.forEach((l) => l());
+  };
+
+  let recorder: MediaRecorder | null = null;
+  let stream: MediaStream | null = null;
+  let timer: ReturnType<typeof setInterval> | null = null;
+  let controller: AbortController | null = null;
+  let discard = false;
+  let audio: AudioContext | null = null;
+  let readLevel: (() => number) | null = null;
+
+  function release() {
+    if (timer) clearInterval(timer);
+    timer = null;
+    void audio?.close().catch(() => {});
+    audio = null;
+    readLevel = null;
+    stream?.getTracks().forEach((t) => t.stop());
+    stream = null;
+    recorder = null;
+  }
+
+  async function start() {
+    if (state.status === "recording" || state.status === "transcribing") return;
+    const Recorder = deps.MediaRecorder ?? (typeof MediaRecorder === "undefined" ? undefined : MediaRecorder);
+    const getUserMedia =
+      deps.getUserMedia ?? (typeof navigator !== "undefined" ? navigator.mediaDevices?.getUserMedia?.bind(navigator.mediaDevices) : undefined);
+    if (!Recorder || !getUserMedia) return set({ status: "error", error: "Voice input isn't supported in this browser." });
+    try {
+      stream = await getUserMedia({ audio: true });
+    } catch (err) {
+      return set({ status: "error", error: describeMicError(err) });
+    }
+    const mimeType = MIME_TYPES.find((t) => Recorder.isTypeSupported?.(t));
+    const chunks: Blob[] = [];
+    discard = false;
+    recorder = new Recorder(stream, mimeType ? { mimeType } : undefined);
+    recorder.ondataavailable = (e) => {
+      if (e.data.size > 0) chunks.push(e.data);
+    };
+    recorder.onstop = () => {
+      const type = recorder?.mimeType || mimeType || "audio/webm";
+      release();
+      if (discard) return set({ status: "idle", elapsedMs: 0, levels: [] });
+      void transcribe(new Blob(chunks, { type }), type);
+    };
+    recorder.start();
+    readLevel = listen(stream);
+    const startedAt = Date.now();
+    const maxMs = (getConfig().maxSeconds ?? DEFAULT_VOICE_MAX_SECONDS) * 1000;
+    set({ status: "recording", elapsedMs: 0, error: null, levels: [] });
+    timer = setInterval(() => {
+      const elapsedMs = Date.now() - startedAt;
+      const levels = readLevel ? [...state.levels, readLevel()].slice(-VOICE_LEVEL_COUNT) : state.levels;
+      set({ elapsedMs, levels });
+      if (elapsedMs >= maxMs) stop();
+    }, 80);
+  }
+
+  /** Reads the stream's loudness, 0–1, through Web Audio. Null without it. */
+  function listen(source: MediaStream): (() => number) | null {
+    const Context = deps.AudioContext ?? (typeof AudioContext === "undefined" ? undefined : AudioContext);
+    if (!Context) return null;
+    try {
+      audio = new Context();
+      const analyser = audio.createAnalyser();
+      analyser.fftSize = 256;
+      audio.createMediaStreamSource(source).connect(analyser);
+      const samples = new Uint8Array(analyser.fftSize);
+      return () => {
+        analyser.getByteTimeDomainData(samples);
+        let sum = 0;
+        for (const v of samples) sum += ((v - 128) / 128) ** 2;
+        // Speech sits low on this scale: lift it so a normal voice fills the bars.
+        return Math.min(1, Math.sqrt(sum / samples.length) * 4);
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  async function transcribe(blob: Blob, mimeType: string) {
+    if (blob.size === 0) return set({ status: "error", error: "Nothing was recorded. Try again." });
+    set({ status: "transcribing", levels: [] });
+    controller = new AbortController();
+    try {
+      const src = await readAsDataUrl(blob);
+      if (controller.signal.aborted) throw abortError();
+      const text = (await voiceTranscriber(getConfig())({ src, kind: "audio", mimeType }, { signal: controller.signal })).trim();
+      if (!text) return set({ status: "error", error: "Didn't catch that. Try again." });
+      onTranscript(text);
+      set({ status: "idle", elapsedMs: 0, levels: [] });
+    } catch (err) {
+      if (isAbortError(err)) return set({ status: "idle", elapsedMs: 0, levels: [] });
+      set({ status: "error", error: "Transcription failed. Try again." });
+    } finally {
+      controller = null;
+    }
+  }
+
+  /** Ends the recording and transcribes it. */
+  function stop() {
+    if (recorder && recorder.state !== "inactive") recorder.stop();
+  }
+
+  /** Stops recording or transcribing, with no transcript. */
+  function cancel() {
+    if (state.status === "recording") {
+      discard = true;
+      stop();
+    } else if (state.status === "transcribing") controller?.abort();
+  }
+
+  /** Clears an error, back to the idle mic. */
+  function dismiss() {
+    if (state.status === "error") set({ status: "idle", error: null, elapsedMs: 0, levels: [] });
+  }
+
+  return {
+    getState: () => state,
+    subscribe(listener: () => void) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    start,
+    stop,
+    cancel,
+    dismiss,
+    /** Stops everything, for when the Composer goes away. */
+    dispose() {
+      discard = true;
+      controller?.abort();
+      if (recorder && recorder.state !== "inactive") recorder.stop();
+      release();
+    },
+  };
+}
+
+export type VoiceInput = ReturnType<typeof createVoiceInput>;
+
+/** A clip's data URL, for the model's `audio_url`. */
+function readAsDataUrl(blob: Blob): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(String(reader.result));
+    reader.onerror = () => reject(reader.error);
+    reader.readAsDataURL(blob);
+  });
+}