@wavebirdai/api 0.0.0-stage → 0.1.0-beta.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CSL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# @wavebirdai/api
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Add Wavebird Banner, Native, and Clip placements to an authenticated chat app. The package provides server handlers for placement, consent, and generation reporting, plus a browser adapter for the hosted renderer. Your server keeps the Wavebird key; your app keeps control of its login, model stream, layout, and consent choice.
+
+## Integrate with Next.js
+
+You need a saved Wavebird Test project and placement in Dashboard, a Server Test Key, an existing authenticated Next.js App Router app, and a durable turn store. Start with the placement's saved formats, sizes, timing, and consent mode. Test traffic is nonpayable.
+
+1. Install the package and generate the route files for your app directory:
+
+   ```sh
+   npm install @wavebirdai/api@0.1.0-beta.10
+   ./node_modules/.bin/wavebird-next init --lang ts --root . --app-dir src/app
+   ```
+
+   Use `--lang js --app-dir app` for a JavaScript app with `app/` at the project root. The generator adds files without overwriting existing ones and writes `WAVEBIRD-SETUP.md` with the exact connection points.
+
+2. Set the server-only values in your deployment environment:
+
+   ```dotenv
+   WAVEBIRD_CLIENT_ID=<saved-project-id>
+   WAVEBIRD_SECRET_KEY=<server-test-key>
+   WAVEBIRD_PREFERENCE_SECRET=<stable-random-value-at-least-32-bytes>
+   WAVEBIRD_PUBLIC_ORIGINS=https://your-app.example
+   ```
+
+   `WAVEBIRD_PUBLIC_ORIGINS` must contain each exact app origin, including scheme and port. For local Server Test-key work, add the exact loopback origin to this list while keeping the Dashboard project domain at its real HTTPS host. Never expose the server key or preference secret through `NEXT_PUBLIC_`, client props, or source control.
+
+3. Connect the generated files to your app: copy the **saved** placement settings into `lib/publisher`; have `lib/auth` validate the real logged-in request and return a stable, non-credential session ID; replace `lib/turn-store` with your persistent store; and connect `lib/model` to your existing generation stream. The supplied auth, store, and model hooks fail closed until you do this. If you use PostgreSQL, the provided adapter uses your existing pool and its `install()` belongs in your normal migration step.
+
+   The generated server route keeps the Wavebird key on the server and wraps your existing stream:
+
+   ```ts
+   import { getPublisher } from "../../../lib/publisher";
+   import { existingGeneration } from "../../../lib/model";
+
+   export async function POST(request: Request): Promise<Response> {
+     return getPublisher().withGeneration({ request, run: existingGeneration });
+   }
+   ```
+
+4. Mount the generated `WavebirdPlacement` beside your app's result area using real authenticated user and conversation IDs, then wrap the existing generation request:
+
+   ```tsx
+   <WavebirdPlacement
+     clientId={publicProjectId}
+     userId={authenticatedUserId}
+     conversationId={activeConversationId}
+     onReady={setAds}
+   />
+
+   await ads.connectGeneration({
+     signal,
+     request: headers => fetch("/api/generate", { method: "POST", headers, signal }),
+     consume: async (response, lifecycle) => {
+       if (!response.ok || !response.body) throw new Error("generation_unavailable");
+       const reader = response.body.getReader();
+       while (true) {
+         const next = await reader.read();
+         if (next.done) break;
+         // Forward next.value to your existing stream consumer.
+         lifecycle.onDelta();
+       }
+     },
+   });
+   ```
+
+   The generated `WAVEBIRD-SETUP.md` shows where the component and routes go. Use Wavebird's consent dialog only when that matches the saved project; for `own_cmp`, connect your actual CMP lifecycle.
+
+5. Validate in Test: confirm the saved format and size, consent and GPC behavior, No-Fill, Stop/abort, and late responses. The generation result must continue independently of the ad path. Move to another package version or Live only through your normal project approval process.
+
+JavaScript and TypeScript use this same package. Complete Next.js JavaScript and TypeScript examples are included in `node_modules/@wavebirdai/api/examples/next-js` and `node_modules/@wavebirdai/api/examples/next-ts`. For other frameworks, use the explicit `@wavebirdai/api/server` and `@wavebirdai/api/browser` exports described below. The [REST reference](https://wavebird.ai/api/reference/endpoints) covers integrations without this package. The established [`wavebird`](https://www.npmjs.com/package/wavebird) SDK is a separate package.
+
+## Server and browser boundary
+
+`@wavebirdai/api/server` exports `createPublisherServer`. Configure it with server-only Project ID, Server Test or production Key, preference signing secret, the publisher's real request authorization function, exact `publicOrigins`, and the saved project/placement values shown in the dashboard. The origin list is required. The package compares the browser Origin with a configured public origin whose host matches the route Host, even when Next.js or a proxy gives the route an internal URL. `localhost` and `127.0.0.1` are separate origins, and each port and scheme must match exactly; HTTP loopback is available only with a Server Test Key. A production key also requires its separately approved project and Wavebird server authority. Omit `bidfloor` and `bidfloorCurrency` to inherit saved pricing. An explicit override supplies both a nonnegative amount, including zero, and a three-letter currency; the API validates it against the saved project. It returns authenticated `placementPOST`, `consentGET`, `consentPOST`, and `withGeneration` handlers, plus the server-only `reportGeneration(jobId, event)` method. The helper constructs the existing `/v1/placements`, `/v1/consent`, and `/v1/jobs/{id}/generation/{event}` requests; it does not introduce a new Wavebird protocol. The Wavebird API remains authoritative for saved scope, creative formats, duration, fallback, and financial classification.
+
+Responsive size selection is enabled by default in this version. The browser adapter sends the measured reserved container size. The server chooses one of the saved `allowedSizes` that fits, or returns `no_fit` without an upstream placement request. Numeric `maxWidth` and `maxHeight` are optional advanced caps: when omitted, the saved sizes define the envelope; when supplied, they can only narrow eligible sizes. A size can carry `formats: ["banner"]`, `formats: ["native"]`, `formats: ["clip"]`, or an approved combination; this annotation remains on the publisher server and is stripped from the wavebird request. A browser format preference is accepted only when it is among the saved `allowedFormats` and compatible with the selected size. Set `responsiveSizeSelection: false` only for a deliberate fixed-size compatibility integration. Reserve enough height for the selected creative and its controls; do not stretch the returned creative or place it over the model result.
+
+Create the server helper when a request arrives, as the included Next.js examples do. This lets Next.js build a publisher app without loading its server key into the build process; the helper still validates configuration before handling traffic.
+
+`withGeneration({ request, run, onLifecycle })` accepts an optional server-side observer. It receives `{ type, sessionId, generationId }` for `started` and one terminal state: `done`, `error`, or `abort`. Use it to forward lifecycle events to your own generation reporter; observer failures do not change the model response. It runs only for authenticated, same-origin requests with valid generation transport IDs. The callback is not awaited, and it receives no prompt or model bytes.
+
+With `sessionIdForRequest` and `turnJournal` configured, the package validates the browser non-credential session ID against the publisher authenticated request, binds one turn to its authorized placement job, and automatically retries ordered generation reports. The PostgreSQL adapter uses the publisher existing pool; run its `install()` in the normal migration step. An unavailable journal suppresses ad placement while an authenticated model request can still run. The store and HMAC key must survive worker restarts. A durable per-project key-version guard rejects a changed preference secret before accepting another turn; pending reports can still reconcile. Coordinate key rotation after active turns are drained rather than clearing the guard while turns remain. This opt-in path requires a package version that includes these exports; earlier published versions retain their original behavior.
+
+Call `reportGeneration` only from trusted server code with a job ID returned by an authorized placement. Its events are `started`, `finished`, and `failed`. The server key scopes the request at wavebird; invalid IDs or events are rejected locally, and each report has a five-second deadline and a parallel request limit. Reporting errors reject the returned promise so the caller can handle them outside the model response path.
+
+`@wavebirdai/api/browser` exports the existing tested `createPublisherAds` and `connectPublisherGeneration` lifecycle helper. It loads the hosted renderer and attaches only to a reserved container selected by the publisher. Initialize it with the current app user and conversation IDs; pass optional same-origin `placementEndpoint` and `consentEndpoint` paths when using the server routes in this package. The helper forwards those paths to the hosted renderer. Keep the Server Key and preference signing secret in the server configuration; never pass them as browser options. Use the real wavebird consent dialog or the publisher's actual CMP. Consent on an idle page does not request an ad. For `during`, the helper displays only during an active generation. Its generation request and response stream run without waiting for consent synchronization, the ad response, or renderer readiness. It clears late responses on completion, error, abort, conversation change, GPC, or withdrawal.
+
+For `after`, resolve the generation consumer only after your app presents the result. The browser helper waits for both the transport finish and that consumer before starting the placement. If presentation fails, reject the consumer so the placement does not start.
+
+## Next.js
+
+The package contains equivalent JavaScript and TypeScript Next.js example files in `examples/next-js` and `examples/next-ts`. Each shows a publisher-owned reserved slot outside the input and scrolling transcript, same-origin consent and placement routes, the server-only configuration, and an existing generation stream wrapped by `withGeneration`. Their authorization hook fails closed until connected to the publisher's actual session validation. The sample generation stream is a local demonstration and is meant to be replaced by the publisher's existing model call.
+
+The required server-only values are `WAVEBIRD_CLIENT_ID`, `WAVEBIRD_SECRET_KEY`, `WAVEBIRD_PREFERENCE_SECRET`, and `WAVEBIRD_PUBLIC_ORIGINS`. Keep secrets outside browser bundles and source control. Set project surface, placement, job type, timing, formats, locale, consent profile, identity/domain, and ad-space dimensions from the saved dashboard configuration. Reserve space for the selected creative and controls without distorting it. The publisher positions the section in its own UI.
+
+## Test scope
+
+The browser and generation transport sources are included in the package. Before use in a publisher app, test the server routes, browser placement, consent, and generation lifecycle against its saved Test project and supported browser and host. Test traffic must remain nonpayable; installing this package does not activate Live ads.

package/bin/wavebird-next.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import { constants } from "node:fs";
+import { access, copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const usage = "Usage: wavebird-next init --lang js|ts --root <existing Next.js project> [--app-dir app|src/app]";
+
+function options(argv) {
+  if (argv[0] !== "init") throw new Error(usage);
+  const out = { appDir: "app" };
+  for (let i = 1; i < argv.length; i += 2) {
+    const key = argv[i];
+    const value = argv[i + 1];
+    const field = key === "--app-dir" ? "appDir" : key.slice(2);
+    if (!value || !["--lang", "--root", "--app-dir"].includes(key) || (field !== "appDir" && out[field] !== undefined)) throw new Error(usage);
+    if (key === "--app-dir") out.appDir = value;
+    else out[key.slice(2)] = value;
+  }
+  if (!["js", "ts"].includes(out.lang) || !out.root || !["app", "src/app"].includes(out.appDir)) throw new Error(usage);
+  return out;
+}
+
+export async function plan(argv) {
+  const { lang, root, appDir } = options(argv);
+  const projectRoot = resolve(root);
+  await access(projectRoot, constants.R_OK | constants.W_OK);
+  const appPath = resolve(projectRoot, appDir);
+  await access(appPath, constants.R_OK);
+  const base = dirname(appPath);
+  const ext = lang === "ts" ? "ts" : "js";
+  const componentExt = lang === "ts" ? "tsx" : "jsx";
+  const example = resolve(packageRoot, "examples", `next-${lang}`);
+  const files = [
+    [join(example, "lib", `publisher.${ext}`), join(base, "lib", `publisher.${ext}`)],
+    [join(example, "lib", `auth.${ext}`), join(base, "lib", `auth.${ext}`)],
+    [join(example, "lib", `turn-store.${ext}`), join(base, "lib", `turn-store.${ext}`)],
+    [resolve(packageRoot, "templates", `model.${ext}`), join(base, "lib", `model.${ext}`)],
+    [join(example, "app", "api", "generate", `route.${ext}`), join(appPath, "api", "generate", `route.${ext}`)],
+    [join(example, "app", "api", "sponsor-slot", `route.${ext}`), join(appPath, "api", "sponsor-slot", `route.${ext}`)],
+    [join(example, "app", "api", "sponsor-consent", `route.${ext}`), join(appPath, "api", "sponsor-consent", `route.${ext}`)],
+    [join(example, "app", "api", "sponsor-session", `route.${ext}`), join(appPath, "api", "sponsor-session", `route.${ext}`)],
+    [resolve(packageRoot, "templates", `WavebirdPlacement.${componentExt}`), join(base, "components", `WavebirdPlacement.${componentExt}`)],
+    [resolve(packageRoot, "templates", "NEXT-SETUP.md"), join(projectRoot, "WAVEBIRD-SETUP.md")]
+  ];
+  for (const [source, dest] of files) {
+    await access(source, constants.R_OK);
+    try { await access(dest); throw new Error(`Refusing to overwrite ${dest}`); }
+    catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
+  return { lang, projectRoot, appDir, files };
+}
+
+export async function install(argv) {
+  const result = await plan(argv);
+  for (const [source, dest] of result.files) {
+    await mkdir(dirname(dest), { recursive: true });
+    if (source.endsWith("NEXT-SETUP.md")) await writeFile(dest, await readFile(source, "utf8"), { flag: "wx" });
+    else await copyFile(source, dest, constants.COPYFILE_EXCL);
+  }
+  return result;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  install(process.argv.slice(2)).then(result => {
+    process.stdout.write(`Installed ${result.lang.toUpperCase()} wavebird routes and connectors in ${result.projectRoot}. Read WAVEBIRD-SETUP.md.\n`);
+  }).catch(error => { process.stderr.write(`${error.message}\n`); process.exitCode = 1; });
+}

package/build.mjs

@@ -0,0 +1,10 @@
+import { mkdir, copyFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+const root = dirname(fileURLToPath(import.meta.url));
+const dist = resolve(root, "dist");
+await mkdir(dist, { recursive: true });
+for (const file of ["generation.js", "turn-journal.js", "postgres-turn-storage.js", "browser.js", "server.js", "server.d.ts", "browser.d.ts"]) {
+  await copyFile(resolve(root, "src", file), resolve(dist, file));
+}

package/dist/browser.d.ts

@@ -0,0 +1,31 @@
+/** Resolve after the publisher has presented the result; After timing starts then. */
+export type GenerationConsumer<T> = (response: Response, lifecycle: { onDelta(): void }) => T | Promise<T>;
+export type PublisherAds = {
+  ready: Promise<void>;
+  connectGeneration<T>(options: { request: (headers: Record<string, string>) => Response | Promise<Response>; consume: GenerationConsumer<T>; signal?: AbortSignal }): Promise<T>;
+  setConversation(binding: { userId: string; conversationId: string; sessionId?: string }): void;
+  dispose(): void;
+  openPrivacySettings(): void;
+  grant(choice?: unknown): Promise<unknown>;
+  deny(): Promise<unknown>;
+  withdraw(): Promise<unknown>;
+};
+export function createPublisherAds(options: {
+  target: HTMLElement;
+  clientId: string;
+  surfaceId: string;
+  jobType: "chat" | "code" | "image" | "voice" | "agent";
+  userId: string;
+  conversationId: string;
+  /** Opt-in successor contract: a session ID supplied by the host's authenticated context. */
+  sessionId?: string;
+  turnBinding?: boolean;
+  timing?: "before" | "during" | "after";
+  consentMode?: "wavebird_consent" | "own_cmp";
+  rendererUrl?: string;
+  privacySettingsTarget?: string;
+  getFormat?: () => "banner" | "native" | "clip" | "auto";
+  placementEndpoint?: string;
+  consentEndpoint?: string;
+}): PublisherAds;
+export function connectPublisherGeneration<T>(url: string, init: RequestInit, consume: GenerationConsumer<T>): Promise<T>;

package/dist/browser.js

@@ -0,0 +1,220 @@
+let rendererReady = null;
+let rendererSource = null;
+
+function loadRenderer(url) {
+  if (window.wavebird?.createChatSponsor) return Promise.resolve();
+  if (rendererReady && rendererSource !== url) return Promise.reject(new Error("renderer_source_mismatch"));
+  if (!rendererReady) {
+    rendererSource = url;
+    rendererReady = new Promise((resolve, reject) => {
+      const script = document.createElement("script"); script.src = url;
+      const fail = () => { clearTimeout(timer); script.onload = null; script.onerror = null; script.remove(); reject(new Error("renderer_unavailable")); };
+      const timer = setTimeout(fail, 8000);
+      script.onerror = fail;
+      script.onload = () => { clearTimeout(timer); if (!window.wavebird?.createChatSponsor) fail(); else resolve(); };
+      document.head.append(script);
+    }).catch(error => { rendererReady = null; rendererSource = null; throw error; });
+  }
+  return rendererReady;
+}
+
+export function createPublisherAds(options) {
+  const target = options.target;
+  const requiredText = value => typeof value === "string" && value.trim().length > 0;
+  if (!target || !requiredText(options.userId) || !requiredText(options.conversationId))
+    throw new Error("Application container and session are required");
+  if (!["chat", "code", "image", "voice", "agent"].includes(options.jobType)) throw new Error("publisher_job_invalid");
+  if (typeof options.clientId !== "string" || !options.clientId.startsWith("wbproj_"))
+    throw new Error("publisher_project_invalid");
+  if (typeof options.surfaceId !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(options.surfaceId))
+    throw new Error("publisher_placement_invalid");
+  const turnBinding = options.turnBinding === true;
+  const validId = value => typeof value === "string" && /^[A-Za-z0-9_-]{1,128}$/.test(value);
+  if (turnBinding && !validId(options.sessionId)) throw new Error("publisher_trusted_session_required");
+  const timing = options.timing === undefined ? "during" : options.timing;
+  const consentMode = options.consentMode === undefined ? "wavebird_consent" : options.consentMode;
+  if (!["before", "during", "after"].includes(timing) || !["wavebird_consent", "own_cmp"].includes(consentMode)) throw new Error("Invalid publisher configuration");
+  let binding = { userId: options.userId, conversationId: options.conversationId,
+    sessionId: turnBinding ? options.sessionId : crypto.randomUUID() };
+  let sponsor = null, disposed = false, context = 0, active = null;
+  const slot = document.createElement("section");
+  slot.setAttribute("aria-label", "Sponsored placement");
+  slot.style.cssText = "width:100%;height:100%;overflow:hidden;margin:0 auto";
+  target.append(slot);
+  const privacyTarget = consentMode === "wavebird_consent" && options.privacySettingsTarget
+    ? document.querySelector(options.privacySettingsTarget) : null;
+  const openPrivacySettings = () => { if (!disposed) sponsor?.openPrivacySettings(); };
+  privacyTarget?.addEventListener("click", openPrivacySettings);
+  const notify = (method, id) => {
+    try { sponsor?.[method](id); }
+    catch {
+      try { sponsor?.dispose(); } catch {}
+      sponsor = null; slot.hidden = true; slot.replaceChildren();
+    }
+  };
+  const current = job => !disposed && !job.cancelled && job.context === context && active === job;
+  const event = (job, type) => {
+    if (!current(job)) return;
+    if (type === "started") {
+      if (job.state !== "pending") return;
+      job.state = "started"; notify("onStarted", job.id);
+    } else if (type === "progress") {
+      if (job.state === "started") { job.progressed = true; notify("onDelta", job.id); }
+    } else if (type === "no_result") {
+      if (job.state === "started") job.state = "no_result";
+    } else if (["done", "error", "abort"].includes(type)) {
+      if (job.state !== "started") return;
+      job.state = type;
+      notify(type === "done" ? "onDone" : type === "abort" ? "onAbort" : "onError", job.id);
+    }
+  };
+  const prepare = () => { if (!disposed && sponsor) void sponsor.prepare().catch(() => {}); };
+  function setConversation(next) {
+    if (disposed) return;
+    if (!requiredText(next?.userId) || !requiredText(next?.conversationId))
+      throw new Error("Application session is required");
+    if (turnBinding && !validId(next.sessionId)) throw new Error("publisher_trusted_session_required");
+    if (next.userId === binding.userId && next.conversationId === binding.conversationId &&
+        (!turnBinding || next.sessionId === binding.sessionId)) return;
+    if (turnBinding && next.sessionId === binding.sessionId) throw new Error("publisher_session_reuse");
+    if (active) event(active, "abort");
+    context++; active = null;
+    binding = { userId: next.userId, conversationId: next.conversationId,
+      sessionId: turnBinding ? next.sessionId : crypto.randomUUID() };
+    sponsor?.setConversation(binding); prepare();
+  }
+  function dispose() {
+    if (disposed) return;
+    if (active) event(active, "abort");
+    disposed = true; context++; active = null;
+    sponsor?.dispose(); sponsor = null; slot.remove();
+    privacyTarget?.removeEventListener("click", openPrivacySettings);
+    window.removeEventListener("pagehide", dispose);
+  }
+  window.addEventListener("pagehide", dispose);
+  const ready = loadRenderer(options.rendererUrl || "https://api.wavebird.ai/v1/render.js").then(() => {
+    if (disposed) return;
+    sponsor = window.wavebird.createChatSponsor({ target: slot, ...binding,
+      clientId: options.clientId, surfaceId: options.surfaceId, timing, consentMode,
+      cleanupAfterClip: true,
+      ...(turnBinding ? { turnBinding: true } : {}),
+      ...(options.getFormat === undefined ? {} : { getFormat: options.getFormat }),
+      ...(options.placementEndpoint === undefined ? {} : { placementEndpoint: options.placementEndpoint }),
+      ...(options.consentEndpoint === undefined ? {} : { consentEndpoint: options.consentEndpoint }) });
+    prepare();
+    if (active && current(active)) {
+      if (active.state === "started") {
+        notify("onStarted", active.id);
+        if (active.progressed) notify("onDelta", active.id);
+      } else if (timing === "after" && active.state === "done") {
+        notify("onStarted", active.id); notify("onDone", active.id);
+      }
+    }
+  }).catch(() => {});
+
+  async function connectGeneration({ request, consume, signal }) {
+    const job = { id: crypto.randomUUID(), sessionId: binding.sessionId, context, state: "pending", cancelled: false };
+    if (active) event(active, "abort");
+    active = job;
+    let reader = null, ended = false, buffer = "";
+    const decoder = new TextDecoder();
+    const abort = () => { event(job, "abort"); job.cancelled = true; void reader?.cancel().catch(() => {}); };
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) abort();
+    const headers = { "x-wavebird-session-id": job.sessionId, "x-wavebird-generation-id": job.id };
+    try {
+      const response = await request(headers);
+      if (response.headers.get("x-wavebird-generation-transport") !== "1") return await consume(response);
+      if (!response.body) throw new Error("generation_transport_missing");
+      reader = response.body.getReader();
+      async function nextRecord() {
+        while (true) {
+          const boundary = buffer.indexOf("\n");
+          if (boundary >= 0) {
+            const line = buffer.slice(0, boundary); buffer = buffer.slice(boundary + 1);
+            if (!line || line.length > 32768) throw new Error("generation_transport_invalid");
+            const record = JSON.parse(line);
+            if (record.session_id !== job.sessionId || record.generation_id !== job.id) throw new Error("generation_transport_context_mismatch");
+            return record;
+          }
+          if (buffer.length > 32768) throw new Error("generation_transport_limit");
+          const next = await reader.read();
+          if (signal?.aborted) throw new Error("generation_aborted");
+          if (next.done) throw new Error("generation_transport_truncated");
+          buffer += decoder.decode(next.value, { stream: true });
+        }
+      }
+      let metadata;
+      while (!metadata) {
+        const record = await nextRecord();
+        if (record.type === "started") event(job, "started");
+        else if (record.type === "response") metadata = record;
+        else throw new Error("generation_failed_before_response");
+      }
+      if (!Number.isInteger(metadata.status) || metadata.status < 200 || metadata.status > 599 || !Array.isArray(metadata.headers)) throw new Error("generation_response_invalid");
+      const output = new ReadableStream({
+        async pull(controller) {
+          try {
+            while (true) {
+              const record = await nextRecord();
+              if (record.type === "bytes") {
+                if (typeof record.data !== "string" || record.data.length > 21848 || !/^[A-Za-z0-9+/]*={0,2}$/.test(record.data)) throw new Error("generation_bytes_invalid");
+                const raw = atob(record.data), bytes = Uint8Array.from(raw, value => value.charCodeAt(0));
+                controller.enqueue(bytes);
+                if (timing !== "before" && options.jobType !== "image") event(job, "progress");
+                return;
+              }
+              if (["done", "error", "abort"].includes(record.type)) {
+                ended = true;
+                if (record.type !== "done" || timing !== "after") event(job, record.type);
+                if (record.type === "done" || !metadata.status.toString().startsWith("2")) controller.close();
+                else controller.error(new Error("generation_" + record.type));
+                return;
+              }
+              throw new Error("generation_transport_invalid");
+            }
+          } catch (error) { event(job, signal?.aborted ? "abort" : "error"); controller.error(error); }
+        },
+        cancel() { event(job, "abort"); void reader?.cancel().catch(() => {}); }
+      }, { highWaterMark: 0 });
+      if ([204, 205, 304].includes(metadata.status)) {
+        const record = await nextRecord();
+        if (!["done", "error", "abort"].includes(record.type)) throw new Error("generation_transport_invalid");
+        ended = true;
+        if (record.type !== "done" || timing !== "after") event(job, record.type);
+      }
+      const noBody = [204, 205, 304].includes(metadata.status);
+      const primary = new Response(noBody ? null : output, {
+        status: metadata.status, statusText: metadata.status_text || "", headers: metadata.headers
+      });
+      const result = await consume(primary, { onDelta: () => event(job, "progress") });
+      if (timing === "after" && ended) event(job, noBody ? "no_result" : "done");
+      return result;
+    } catch (error) {
+      event(job, signal?.aborted ? "abort" : "error");
+      throw error;
+    } finally {
+      if (!ended && job.state === "started") event(job, "abort");
+      signal?.removeEventListener("abort", abort);
+      if (reader) { try { await reader.cancel(); } catch {} reader.releaseLock(); }
+    }
+  }
+  return { ready, connectGeneration, setConversation, dispose, openPrivacySettings,
+    grant: choice => sponsor ? sponsor.grant(choice) : Promise.resolve({ status: "renderer_unavailable" }),
+    deny: () => sponsor ? sponsor.deny() : Promise.resolve({ status: "renderer_unavailable" }),
+    withdraw: () => sponsor ? sponsor.withdraw() : Promise.resolve({ status: "renderer_unavailable" }) };
+}
+
+export async function connectPublisherGeneration(url, init, consume) {
+  const ads = window.publisherAds;
+  if (!ads) return consume(await fetch(url, init), { onDelta() {} });
+  return ads.connectGeneration({
+    signal: init.signal ?? undefined,
+    request: values => {
+      const headers = new Headers(init.headers);
+      for (const [name, value] of Object.entries(values)) headers.set(name, value);
+      return fetch(url, { ...init, headers });
+    },
+    consume
+  });
+}

package/dist/generation.js

@@ -0,0 +1,98 @@
+import { Buffer } from "node:buffer";
+
+function generationTransport({ request, run }) {
+    const sessionId = request.headers.get("x-wavebird-session-id") || "";
+    const generationId = request.headers.get("x-wavebird-generation-id") || "";
+    const validId = (value) => /^[A-Za-z0-9_-]{1,128}$/.test(value);
+    if (!validId(sessionId) || !validId(generationId))
+        return run(request.signal);
+    const abort = new AbortController();
+    const stop = () => abort.abort(request.signal.reason);
+    request.signal.addEventListener("abort", stop, { once: true });
+    if (request.signal.aborted)
+        stop();
+    let reader = null;
+    let pending;
+    try {
+        pending = Promise.resolve(run(abort.signal));
+    }
+    catch (error) {
+        pending = Promise.reject(error);
+    }
+    pending.catch(() => { });
+    const encoder = new TextEncoder();
+    const record = (value) => encoder.encode(JSON.stringify({
+        session_id: sessionId, generation_id: generationId, ...value
+    }) + "\n");
+    async function* records() {
+        try {
+            if (abort.signal.aborted)
+                throw new Error("generation_aborted");
+            yield record({ type: "started" });
+            const response = await pending;
+            if (!(response instanceof Response))
+                throw new Error("model_response_required");
+            if (abort.signal.aborted)
+                throw new Error("generation_aborted");
+            const headers = [...response.headers.entries()].filter(([name]) => !["set-cookie", "content-length", "content-encoding", "transfer-encoding"].includes(name.toLowerCase()));
+            if (response.headers.has("set-cookie"))
+                throw new Error("model_response_cookie_requires_outer_route");
+            yield record({ type: "response", status: response.status, status_text: response.statusText, headers });
+            reader = response.body?.getReader() || null;
+            if (reader) {
+                while (true) {
+                    if (abort.signal.aborted)
+                        throw new Error("generation_aborted");
+                    const next = await reader.read();
+                    if (abort.signal.aborted)
+                        throw new Error("generation_aborted");
+                    if (next.done)
+                        break;
+                    for (let offset = 0; offset < next.value.length; offset += 16384) {
+                        yield record({ type: "bytes", data: Buffer.from(next.value.subarray(offset, offset + 16384)).toString("base64") });
+                    }
+                }
+            }
+            yield record({ type: response.ok ? "done" : "error" });
+        }
+        catch {
+            yield record({ type: abort.signal.aborted ? "abort" : "error" });
+        }
+        finally {
+            abort.abort();
+            if (reader) {
+                try {
+                    await reader.cancel();
+                }
+                catch { }
+                reader.releaseLock();
+            }
+            request.signal.removeEventListener("abort", stop);
+        }
+    }
+    const iterator = records();
+    const body = new ReadableStream({
+        async pull(controller) {
+            try {
+                const next = await iterator.next();
+                if (next.done)
+                    controller.close();
+                else
+                    controller.enqueue(next.value);
+            }
+            catch (error) {
+                controller.error(error);
+            }
+        },
+        cancel(reason) {
+            abort.abort(reason);
+            void reader?.cancel(reason).catch(() => { });
+            void iterator.return(undefined).catch(() => { });
+        }
+    }, { highWaterMark: 1 });
+    return new Response(body, { headers: {
+            "Content-Type": "application/x-wavebird-generation+jsonl",
+            "Cache-Control": "no-store", "X-Wavebird-Generation-Transport": "1"
+        } });
+}
+export { generationTransport };

package/dist/postgres-turn-storage.js

@@ -0,0 +1,81 @@
+/** PostgreSQL adapter for an existing publisher database; no database client is bundled. */
+const TABLE = "wavebird_publisher_turns";
+const CREATE_TABLE = `CREATE TABLE IF NOT EXISTS ${TABLE} (
+  scope_id text NOT NULL,
+  turn_key text NOT NULL,
+  state_json jsonb NOT NULL,
+  pending boolean NOT NULL,
+  created_at_ms bigint NOT NULL,
+  updated_at_ms bigint NOT NULL,
+  PRIMARY KEY (scope_id, turn_key)
+)`;
+const CREATE_INDEX = `CREATE INDEX IF NOT EXISTS wavebird_publisher_turns_pending
+  ON ${TABLE} (scope_id, turn_key) WHERE pending = true`;
+
+export function createPostgresTurnStorage(pool) {
+  if (!pool || typeof pool.connect !== "function") throw new Error("publisher_postgres_pool_required");
+  async function withClient(run) {
+    const client = await pool.connect();
+    try { return await run(client); } finally { client.release(); }
+  }
+  async function install() {
+    await withClient(async client => {
+      await client.query(CREATE_TABLE);
+      await client.query(CREATE_INDEX);
+    });
+  }
+  async function atomic(scope, key, transition) {
+    return withClient(async client => {
+      await client.query("BEGIN");
+      try {
+        const now = Date.now();
+        await client.query(`INSERT INTO ${TABLE}(scope_id,turn_key,state_json,pending,created_at_ms,updated_at_ms)
+          VALUES ($1,$2,'null'::jsonb,false,$3,$3) ON CONFLICT DO NOTHING`, [scope, key, now]);
+        const row = await client.query(`SELECT state_json FROM ${TABLE} WHERE scope_id=$1 AND turn_key=$2 FOR UPDATE`, [scope, key]);
+        if (row.rows.length !== 1) throw new Error("publisher_turn_storage_conflict");
+        const value = row.rows[0].state_json;
+        const previous = typeof value === "string" ? JSON.parse(value) : value;
+        const { state, result } = transition(previous);
+        if (state === null) {
+          await client.query(`DELETE FROM ${TABLE} WHERE scope_id=$1 AND turn_key=$2`, [scope, key]);
+        } else {
+          const pending = Boolean(state.jobId && state.phase !== "idle" &&
+            (!state.startedReported || (["finished", "failed"].includes(state.phase) && !state.terminalReported)));
+          await client.query(`UPDATE ${TABLE} SET state_json=$3::jsonb,pending=$4,updated_at_ms=$5
+            WHERE scope_id=$1 AND turn_key=$2`, [scope, key, JSON.stringify(state), pending, now]);
+        }
+        await client.query("COMMIT");
+        return result;
+      } catch (error) {
+        try { await client.query("ROLLBACK"); } catch {}
+        throw error;
+      }
+    });
+  }
+  async function scan(scope, cursor, limit) {
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) throw new Error("publisher_turn_scan_invalid");
+    return withClient(async client => {
+      const result = await client.query(`SELECT turn_key FROM ${TABLE}
+        WHERE scope_id=$1 AND pending=true AND turn_key>$2 ORDER BY turn_key LIMIT $3`, [scope, cursor, limit]);
+      return result.rows.map(row => row.turn_key);
+    });
+  }
+  async function prune(scope) {
+    return withClient(async client => {
+      await client.query("BEGIN");
+      try {
+        const now = Date.now();
+        await client.query(`DELETE FROM ${TABLE} WHERE scope_id=$1 AND pending=false AND updated_at_ms<$2`,
+          [scope, now - 86_400_000]);
+        const expired = await client.query(`DELETE FROM ${TABLE} WHERE scope_id=$1 AND pending=true AND created_at_ms<$2 RETURNING turn_key`,
+          [scope, now - 7 * 86_400_000]);
+        await client.query("COMMIT");
+        return expired.rowCount;
+      } catch (error) {
+        try { await client.query("ROLLBACK"); } catch {}
+        throw error;
+      }
+    });
+  }
+  return { install, atomic, scan, prune };
+}