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

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,56 @@
-# Temporary Holding Version
+# wavebird publisher 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.
+`@wavebirdai/api` provides Banner/Native integration with the wavebird REST API and hosted renderer. Version `0.1.0-beta.1` is an opt-in prerelease. The pinned public GitHub `.4` and optional `.5` archives remain available; existing publishers keep their installed version unless they opt in. The established [`wavebird`](https://www.npmjs.com/package/wavebird) SDK remains separate.
+
+## Installation
+
+For the npm prerelease, run this in the existing Next.js app directory beside `package.json`:
+
+```sh
+npm install @wavebirdai/api@0.1.0-beta.1
+```
+
+The public `.4` GitHub asset uses fixed sizes. Public `.5` adds optional responsive selection. This prerelease corrects the responsive generator example and package guidance; neither public archive is overwritten. A version change does not migrate an existing integration automatically.
+
+The [full REST reference](https://wavebird.ai/api/reference/endpoints) remains available for integrations without this package.
+
+Both JavaScript and TypeScript use the same package and URL; there is no separate language package.
+
+For a saved single-format placement such as Banner-only After, pass `getFormat: () => "banner"` to `createPublisherAds` along with the matching same-origin placement endpoint. The package forwards that choice to the hosted renderer; the server still enforces the saved project and format. Omit `getFormat` when the saved placement intentionally lets wavebird choose among supported formats.
+
+## Next.js route generator
+
+After installing the package, run one of these commands in an existing Next.js App Router project:
+
+```sh
+./node_modules/.bin/wavebird-next init --lang js --root . --app-dir app
+./node_modules/.bin/wavebird-next init --lang ts --root . --app-dir src/app
+```
+
+Choose one language and the actual App Router directory. The command refuses to overwrite existing files. It installs `lib/publisher`, `lib/auth`, and a fail-closed `lib/model`; required `app/api/generate`, `app/api/sponsor-slot`, and `app/api/sponsor-consent` route files; `components/WavebirdPlacement`; and `WAVEBIRD-SETUP.md`. The `src/app` option puts `lib` and `components` under `src/`. These routes are application files produced by the generator, not implicit package exports. JS and TS Next.js example files are also included in the package's `examples/` directory; connect their authorization and generation hooks before use. The generated publisher lists two illustrative Banner sizes and enables responsive selection; replace both sizes with the exact saved project sizes before Test traffic.
+
+Set the server-only environment variables, including `WAVEBIRD_PUBLIC_ORIGINS` with the exact scheme, host, and port where your app is opened. Keep the Dashboard project domain at its real HTTPS host; for local Server Test-key testing, add the exact loopback origin to this server-only list without changing that project domain. Browser Test Keys have a separate Allowed origins field in API Keys. Insert actual saved Dashboard settings in `lib/publisher`, connect your real session check in `lib/auth`, and connect your existing model stream in `lib/model`. The supplied auth hook fails closed without its publisher-owned check path, and the generated model hook throws until replaced. The generated client component requires authenticated user and conversation IDs from the publisher. Mount it by the existing result area and call its returned ads object's `connectGeneration` around the existing request/stream consumer. The generated setup file shows the short entry point. Use your real consent lifecycle: the template selects wavebird's consent dialog, while an `own_cmp` saved project must be wired to the publisher's actual CMP before any served test.
+
+## Server and browser boundary
+
+`@wavebirdai/api/server` exports `createPublisherServer`. Configure it with server-only Project ID, Server Test or Live 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 is accepted only for loopback. 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 selection is opt-in with `responsiveSizeSelection: true`. The hosted 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. A size can carry `formats: ["banner"]`, `formats: ["native"]`, or both; 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. Without opt-in, existing fixed-size requests retain their previous behavior. 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-only Test 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.
+
+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.
+
+## 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. Do not shrink the reserve below the saved creative envelope plus the 256px Banner/Native control space. 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,67 @@
+#!/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}`)],
+    [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}`)],
+    [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/dist/browser.d.ts

@@ -0,0 +1,27 @@
+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 }): 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: string;
+  userId: string;
+  conversationId: string;
+  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,194 @@
+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;
+  if (!target || !options.userId || !options.conversationId) throw new Error("Application container and session are required");
+  const timing = options.timing || "during", consentMode = options.consentMode || "wavebird_consent";
+  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: 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 (["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 (!next.userId || !next.conversationId) throw new Error("Application session is required");
+    if (next.userId === binding.userId && next.conversationId === binding.conversationId) return;
+    if (active) event(active, "abort");
+    context++; active = null;
+    binding = { userId: next.userId, conversationId: next.conversationId, 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,
+      ...(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" && !["image", "image_generation"].includes(options.jobType)) event(job, "progress");
+                return;
+              }
+              if (["done", "error", "abort"].includes(record.type)) {
+                ended = true; 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; event(job, record.type);
+      }
+      const primary = new Response([204, 205, 304].includes(metadata.status) ? null : output, {
+        status: metadata.status, statusText: metadata.status_text || "", headers: metadata.headers
+      });
+      return await consume(primary, { onDelta: () => event(job, "progress") });
+    } 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,96 @@
+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/server.d.ts

@@ -0,0 +1,38 @@
+export type PublisherServerOptions = {
+  apiBaseUrl?: string;
+  clientId: string;
+  secretKey: string;
+  preferenceSecret: string;
+  authorize: (request: Request) => boolean | Promise<boolean>;
+  publicOrigins: string[];
+  surfaceId: string;
+  placementKey: string;
+  jobType: string;
+  locale: string;
+  timing: "before" | "during" | "after";
+  consentMode: "wavebird_consent" | "own_cmp";
+  gdprApplies: boolean;
+  publisher: { app_name: string; app_domain: string; categories: string[] };
+  allowedFormats: Array<"banner" | "native">;
+  positionHint: "above" | "below" | "sidebar" | "between";
+  maxWidth: number;
+  maxHeight: number;
+  allowedSizes: Array<{ width: number; height: number; formats?: Array<"banner" | "native"> }>;
+  responsiveSizeSelection?: boolean;
+  bidfloor?: number;
+  bidfloorCurrency?: string;
+  blockedCategories?: string[];
+};
+export type GenerationLifecycleEvent = {
+  type: "started" | "done" | "error" | "abort";
+  sessionId: string;
+  generationId: string;
+};
+export type PublisherServer = {
+  placementPOST(request: Request): Promise<Response>;
+  consentGET(request: Request): Promise<Response>;
+  consentPOST(request: Request): Promise<Response>;
+  withGeneration(options: { request: Request; run: (signal: AbortSignal) => Response | Promise<Response>; onLifecycle?: (event: GenerationLifecycleEvent) => void | Promise<void> }): Promise<Response>;
+  reportGeneration(jobId: string, event: "started" | "finished" | "failed"): Promise<void>;
+};
+export function createPublisherServer(options: PublisherServerOptions): PublisherServer;