@chai-ui/core 0.1.0

package/src/server/chai-handler.ts

@@ -0,0 +1,146 @@
+/**
+ * `createChaiHandler`: the one server route the built-in engines call.
+ * The browser never sees an API key. `createFalEngine()` and
+ * `createOpenRouterEngine()` post to this route (default `/api/chai/...`),
+ * and it adds the key and forwards the request to the provider.
+ *
+ * Built on the web-standard `Request` → `Response`, so the same handler
+ * runs in Next.js, React Router (Remix), Hono, Cloudflare Workers, Bun and
+ * Deno. `toNodeHandler` (./node.ts) adapts it for Express and plain Node.
+ */
+
+const FAL_QUEUE_BASE = "https://queue.fal.run";
+const OPENROUTER_CHAT_URL = "https://openrouter.ai/api/v1/chat/completions";
+
+export type ChaiProviderId = "fal" | "openrouter";
+
+export interface ChaiHandlerOptions {
+  /** Defaults to the `FAL_KEY` environment variable. */
+  falKey?: string;
+  /** Defaults to the `OPENROUTER_API_KEY` environment variable. */
+  openRouterKey?: 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
+   * own login or session here before going live.
+   */
+  authorize?: (request: Request) => boolean | Promise<boolean>;
+  /**
+   * The only model ids this route will run, across both 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.
+   */
+  allowedModels?: string[];
+  /** Injectable for tests; defaults to the global `fetch`. */
+  fetch?: typeof fetch;
+}
+
+export interface ChaiHandler {
+  /** Handles any request under the route. */
+  handle: (request: Request) => Promise<Response>;
+  /** The same function, named for frameworks that export one per method (Next.js). */
+  GET: (request: Request) => Promise<Response>;
+  POST: (request: Request) => Promise<Response>;
+  /** Fal's cancel call. */
+  PUT: (request: Request) => Promise<Response>;
+}
+
+export function createChaiHandler(options: ChaiHandlerOptions = {}): ChaiHandler {
+  const fetchImpl = options.fetch ?? fetch;
+
+  async function handle(request: Request): Promise<Response> {
+    const route = parseRoute(new URL(request.url).pathname);
+    if (!route) {
+      return Response.json(
+        { error: { message: "chai-handler: expected a path ending in /fal/<model…> or /openrouter/chat." } },
+        { status: 404 }
+      );
+    }
+    const fail = (status: number, message: string) => errorResponse(route.provider, status, message);
+
+    if (options.authorize && !(await options.authorize(request))) return fail(403, "Not authorized.");
+
+    if (route.provider === "openrouter") {
+      if (route.rest !== "chat") return fail(404, `Unknown OpenRouter path "${route.rest}".`);
+      if (request.method !== "POST") return fail(405, "Use POST.");
+      const key = options.openRouterKey ?? readEnv("OPENROUTER_API_KEY");
+      if (!key) return fail(500, "OPENROUTER_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, OPENROUTER_CHAT_URL, {
+        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");
+    if (request.method !== "GET" && request.method !== "POST" && !isCancel) return fail(405, "Use GET or POST.");
+    const key = options.falKey ?? readEnv("FAL_KEY");
+    if (!key) return fail(500, "FAL_KEY isn't set on the server.");
+    if (options.allowedModels && !options.allowedModels.some((m) => route.rest === m || route.rest.startsWith(`${m}/`))) {
+      return fail(403, `Model "${falModel(route.rest)}" isn't allowed on this server.`);
+    }
+    return forward(fetchImpl, route.provider, `${FAL_QUEUE_BASE}/${route.rest}${new URL(request.url).search}`, {
+      signal: request.signal,
+      method: request.method,
+      headers: { Authorization: `Key ${key}`, "Content-Type": "application/json" },
+      body: request.method === "POST" ? await request.text() : undefined,
+    });
+  }
+
+  return { handle, GET: handle, POST: handle, PUT: handle };
+}
+
+/** 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");
+  if (i === -1 || i === parts.length - 1) return null;
+  return { provider: parts[i] as ChaiProviderId, rest: parts.slice(i + 1).join("/") };
+}
+
+/** Passes the provider's response straight through, streaming included. */
+async function forward(fetchImpl: typeof fetch, provider: ChaiProviderId, url: string, init: RequestInit): Promise<Response> {
+  try {
+    const upstream = await fetchImpl(url, init);
+    return new Response(upstream.body, {
+      status: upstream.status,
+      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)}`);
+  }
+}
+
+/** Errors in the shape each engine already reads: Fal's `{ error }`, OpenRouter'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 });
+}
+
+function readModel(body: string): string | undefined {
+  try {
+    const model = (JSON.parse(body) as { model?: unknown }).model;
+    return typeof model === "string" ? model : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The model part of a Fal queue path, for error messages: everything before `/requests/`. */
+function falModel(rest: string): string {
+  return rest.split("/requests/")[0]!;
+}
+
+function readEnv(name: string): string | undefined {
+  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env;
+  return env?.[name] || undefined;
+}

package/src/server/index.ts

@@ -0,0 +1,3 @@
+// @chai-ui/core/server: server-only. Never import this from browser code.
+export * from "./chai-handler.js";
+export * from "./node.js";

package/src/server/node.ts

@@ -0,0 +1,75 @@
+/**
+ * Runs a `ChaiHandler` on Node's own request/response objects, for Express
+ * and plain `http.createServer` (and dev servers built on them, like
+ * Vite's). Typed structurally, so this package needs no Node types.
+ */
+
+import type { ChaiHandler } from "./chai-handler.js";
+
+interface NodeRequest extends AsyncIterable<Uint8Array | string> {
+  method?: string;
+  url?: string;
+  /** Express keeps the full path here when the route is mounted at a prefix. */
+  originalUrl?: string;
+  headers: Record<string, string | string[] | undefined>;
+}
+
+interface NodeResponse {
+  statusCode: number;
+  writableEnded?: boolean;
+  on?(event: "close", listener: () => void): unknown;
+  setHeader(name: string, value: string): unknown;
+  write(chunk: Uint8Array): unknown;
+  end(chunk?: string | Uint8Array): unknown;
+}
+
+export function toNodeHandler(handler: ChaiHandler) {
+  return async (req: NodeRequest, res: NodeResponse): Promise<void> => {
+    const host = String(req.headers.host ?? "localhost");
+    const url = new URL(req.originalUrl ?? req.url ?? "/", `http://${host}`);
+    const method = req.method ?? "GET";
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(req.headers)) {
+      if (value !== undefined) headers.set(name, Array.isArray(value) ? value.join(", ") : value);
+    }
+    let body: Uint8Array<ArrayBuffer> | undefined;
+    if (method !== "GET" && method !== "HEAD") {
+      const chunks: Uint8Array[] = [];
+      for await (const chunk of req) chunks.push(typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk);
+      body = concat(chunks);
+    }
+
+    // When the browser disconnects (e.g. the person pressed stop), abort the
+    // provider call too, so a stream stops at the provider.
+    const controller = new AbortController();
+    res.on?.("close", () => {
+      if (!res.writableEnded) controller.abort();
+    });
+    const response = await handler.handle(new Request(url, { method, headers, body, signal: controller.signal }));
+    res.statusCode = response.status;
+    response.headers.forEach((value, name) => res.setHeader(name, value));
+    if (!response.body) return void res.end();
+    // Streamed through as it arrives, so streaming text renders live.
+    const reader = response.body.getReader();
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        res.write(value);
+      }
+    } catch {
+      // The provider stream was aborted because the browser left; nothing to send.
+    }
+    res.end();
+  };
+}
+
+function concat(chunks: Uint8Array[]): Uint8Array<ArrayBuffer> {
+  const out = new Uint8Array(chunks.reduce((n, c) => n + c.length, 0));
+  let offset = 0;
+  for (const c of chunks) {
+    out.set(c, offset);
+    offset += c.length;
+  }
+  return out;
+}

package/src/types.ts

@@ -0,0 +1,96 @@
+/**
+ * CHAI UI — shared data types for the component library.
+ */
+
+/** The kinds of media a component can take in or produce. */
+export type MediaKind = "image" | "video" | "audio" | "text";
+
+/**
+ * A piece of media a person attached (or an engine received) — just enough
+ * to know its kind and where it lives.
+ */
+export interface DroppedMedia {
+  src: string;
+  kind: MediaKind;
+  /** Original file name, for the upload-summary UI. Absent for non-file sources. */
+  name?: string;
+  /** Original file size in bytes, for the upload-summary UI. */
+  size?: number;
+}
+
+/**
+ * Token/cost accounting for one model call, when the engine reports one.
+ * `costUsd` is deliberately separate from the token counts: an engine may
+ * know real token counts but have no verified per-model pricing to convert
+ * them with (see `ModelOption.pricePerMillionTokens`) — degrade to showing
+ * tokens without a cost rather than guessing a price.
+ */
+export interface Usage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+  costUsd?: number;
+}
+
+/**
+ * The verdict of one quality check the builder's own backend ran on a
+ * generated output (e.g. brand safety, prompt adherence), appended to the
+ * model call's response. CHAI never runs or scores a check; it only
+ * renders the verdict: `passed` true is green, false is red.
+ */
+export interface Evaluation {
+  id: string;
+  label: string;
+  passed: boolean;
+}
+
+/**
+ * The thin value-in/value-out shape a form control satisfies (e.g.
+ * `Toggle`) — deliberately minimal so most existing components already
+ * qualify without an adapter.
+ */
+export interface PrimitiveProps<T = unknown> {
+  value: T;
+  onChange: (next: T) => void;
+  disabled?: boolean;
+}
+
+/** One labeled option, for option-list controls (e.g. Composer's aspect ratios). */
+export interface ParameterOption<T> {
+  value: T;
+  label: string;
+}
+
+/** A model a component can offer or route to. */
+export interface ModelOption {
+  id: string;
+  label: string;
+  provider: string;
+  /** Rough cost/latency signal, for future cost/latency-aware routing. */
+  speed: "fast" | "standard" | "slow";
+  /**
+   * USD per million tokens, if known — lets real token counts convert into
+   * a real cost. Deliberately optional and absent by default: provider
+   * pricing changes and isn't tracked anywhere in this repo yet, so a wrong
+   * hardcoded number would be worse than no cost at all. Set this per model
+   * only from a source you're actively keeping current.
+   */
+  pricePerMillionTokens?: { input: number; output: number };
+}
+
+/**
+ * A specific generation use case. These names deliberately match the
+ * leaderboard categories at github.com/oolong-tea-2026/arena-ai-leaderboards,
+ * so a future model-ranking lookup can join on it directly, plus
+ * "text-to-text" for a plain text request (a Composer with no use case
+ * picked). That repo has no audio-generation category at all, a real gap
+ * for any future audio use case.
+ */
+export type GenerationUseCase =
+  | "text-to-image"
+  | "image-edit"
+  | "text-to-video"
+  | "image-to-video"
+  | "video-edit"
+  | "vision"
+  | "text-to-text";