@wavebirdai/api 0.1.0-beta.2 → 0.1.0-beta.5

package/examples/next-ts/lib/auth.ts

@@ -1,12 +1,33 @@
+import "server-only";
+
+const cache = new WeakMap<Request, Promise<string | null>>();
+const ID = /^[A-Za-z0-9_-]{1,128}$/;
+
+/** Resolve a non-credential correlation ID from the app's authenticated session. */
+export function sessionIdForRequest(request: Request): Promise<string | null> {
+  const prior = cache.get(request);
+  if (prior) return prior;
+  const pending = (async () => {
+    const path = process.env.PUBLISHER_AUTH_CHECK_PATH;
+    if (!path || !/^\/(?!\/)[A-Za-z0-9/_-]+$/.test(path) ||
+        path.startsWith("/api/sponsor") || path === "/api/generate") return null;
+    try {
+      const requestOrigin = new URL(request.url).origin;
+      const trustedOrigin = (process.env.WAVEBIRD_PUBLIC_ORIGINS ?? "").split(",")
+        .map(value => value.trim()).find(value => value === requestOrigin);
+      if (!trustedOrigin) return null;
+      const result = await fetch(new URL(path, trustedOrigin), {
+        headers: { cookie: request.headers.get("cookie") || "" },
+        cache: "no-store", redirect: "manual", signal: AbortSignal.timeout(1500),
+      });
+      const id = result.headers.get("x-publisher-session-id");
+      return result.status === 204 && ID.test(id || "") ? id : null;
+    } catch { return null; }
+  })();
+  cache.set(request, pending);
+  return pending;
+}
+
 export async function authorizePublisherRequest(request: Request): Promise<boolean> {
-  const path = process.env.PUBLISHER_AUTH_CHECK_PATH;
-  if (!path || !/^\/(?!\/)[A-Za-z0-9/_-]+$/.test(path) || path.startsWith("/api/sponsor") || path === "/api/generate") return false;
-  try {
-    const result = await fetch(new URL(path, request.url), {
-      headers: { cookie: request.headers.get("cookie") || "" },
-      cache: "no-store",
-      redirect: "manual"
-    });
-    return result.status === 204;
-  } catch { return false; }
+  return (await sessionIdForRequest(request)) !== null;
 }

package/examples/next-ts/lib/publisher.ts

@@ -1,16 +1,25 @@
 import "server-only";
-import { createPublisherServer } from "@wavebirdai/api/server";
-import { authorizePublisherRequest } from "./auth";
+import { createPublisherServer, createPublisherTurnJournal, derivePublisherTurnKeySecret } from "@wavebirdai/api/server";
+import { authorizePublisherRequest, sessionIdForRequest } from "./auth";
+import { publisherTurnStorage } from "./turn-store";
 
 let publisher: ReturnType<typeof createPublisherServer> | null = null;
 
 export function getPublisher(): ReturnType<typeof createPublisherServer> {
-  return publisher ??= createPublisherServer({
+  if (publisher) return publisher;
+  const turnJournal = createPublisherTurnJournal({
+    storage: publisherTurnStorage(),
+    keySecret: derivePublisherTurnKeySecret(process.env.WAVEBIRD_PREFERENCE_SECRET ?? ""),
+    reportGeneration: (jobId, event) => getPublisher().reportGeneration(jobId, event),
+  });
+  return publisher = createPublisherServer({
   apiBaseUrl: process.env.WAVEBIRD_API_BASE_URL,
   clientId: process.env.WAVEBIRD_CLIENT_ID ?? "",
   secretKey: process.env.WAVEBIRD_SECRET_KEY ?? "",
   preferenceSecret: process.env.WAVEBIRD_PREFERENCE_SECRET ?? "",
   authorize: authorizePublisherRequest,
+  sessionIdForRequest,
+  turnJournal,
   publicOrigins: (process.env.WAVEBIRD_PUBLIC_ORIGINS ?? "").split(",").map(value => value.trim()).filter(Boolean),
   surfaceId: "chat_assistant",
   placementKey: "default",
@@ -22,8 +31,6 @@ export function getPublisher(): ReturnType<typeof createPublisherServer> {
   publisher: { app_name: "Your saved app name", app_domain: "your.example", categories: [] },
   allowedFormats: ["banner"],
   positionHint: "between",
-  maxWidth: 728,
-  maxHeight: 90,
   allowedSizes: [{ width: 728, height: 90 }, { width: 320, height: 50 }],
   responsiveSizeSelection: true
   });

package/examples/next-ts/lib/turn-store.ts

@@ -0,0 +1,10 @@
+import "server-only";
+import type { PublisherAtomicTurnStorage } from "@wavebirdai/api/server";
+
+/** Replace this fail-closed stub with createPostgresTurnStorage(your existing pg pool). */
+export function publisherTurnStorage(): PublisherAtomicTurnStorage {
+  return {
+    async atomic<T>(): Promise<T> { throw new Error("Connect your existing durable turn store"); },
+    async scan(): Promise<string[]> { throw new Error("Connect your existing durable turn store"); },
+  };
+}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@wavebirdai/api",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.5",
   "private": false,
   "type": "module",
-  "description": "Banner, Native, and Clip publisher integration for the wavebird API",
+  "description": "Integrate Banner, Native, and Clip placements into authenticated chat apps with server-side keys, consent, and generation lifecycle handling",
   "license": "MIT",
   "repository": { "type": "git", "url": "https://github.com/wavebird-ai/api" },
   "engines": { "node": ">=20" },
-  "files": ["dist", "examples", "bin", "templates", "README.md", "LICENSE"],
+  "files": ["dist", "src", "build.mjs", "examples", "bin", "templates", "README.md", "LICENSE"],
   "bin": { "wavebird-next": "./bin/wavebird-next.mjs" },
   "exports": {
     "./server": { "types": "./dist/server.d.ts", "import": "./dist/server.js" },

package/src/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/src/browser.js

@@ -0,0 +1,212 @@
+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");
+  if (!["chat", "code", "image", "voice", "agent"].includes(options.jobType)) throw new Error("publisher_job_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 || "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: 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 (!next.userId || !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/src/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/src/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 };
+}

package/src/server.d.ts

@@ -0,0 +1,76 @@
+export type PublisherTurnIdentity = { projectId: string; surfaceId: string; sessionId: string; turnId: string };
+/** The successor journal must make claims and phase transitions durable across workers. */
+export type PublisherTurnJournal = {
+  claimPlacement(turn: PublisherTurnIdentity): Promise<boolean>;
+  releaseRejectedPlacement(turn: PublisherTurnIdentity): Promise<void>;
+  bind(turn: PublisherTurnIdentity, jobId: string): Promise<void>;
+  claimGeneration(turn: PublisherTurnIdentity): Promise<boolean>;
+  phase(turn: PublisherTurnIdentity, event: "started" | "finished" | "failed"): Promise<void>;
+  reconcilePending?(projectId: string, surfaceId: string): Promise<void>;
+};
+/** Implement this over an existing serializable, persistent application store. */
+export type PublisherAtomicTurnStorage = {
+  atomic<T>(scope: string, key: string,
+    transition: (previous: unknown | null) => { state: unknown | null; result: T }): Promise<T>;
+  /** Return increasing hashed keys after cursor, at most limit. */
+  scan(scope: string, cursor: string, limit: number): Promise<string[]>;
+  prune?(scope: string): Promise<number>;
+};
+/** Use an existing pg-compatible pool; run install once in the publisher's normal migration step. */
+export function createPostgresTurnStorage(pool: {
+  connect(): Promise<{ query(sql: string, params?: unknown[]): Promise<{ rows: Array<Record<string, unknown>>; rowCount?: number }>;
+    release(): void }>;
+}): PublisherAtomicTurnStorage & { install(): Promise<void>; prune(scope: string): Promise<number> };
+export function createPublisherTurnJournal(options: {
+  storage: PublisherAtomicTurnStorage;
+  reportGeneration: (jobId: string, event: "started" | "finished" | "failed") => Promise<void>;
+  /** Stable server-only secret for pseudonymous durable turn keys, at least 32 UTF-8 bytes. */
+  keySecret: string;
+  onDiagnostic?: (code: string) => void;
+}): PublisherTurnJournal;
+/** Derive a stable, domain-separated journal key from the existing server-only preference secret. */
+export function derivePublisherTurnKeySecret(preferenceSecret: string): string;
+export type PublisherServerOptions = {
+  apiBaseUrl?: string;
+  clientId: string;
+  secretKey: string;
+  preferenceSecret: string;
+  authorize: (request: Request) => boolean | Promise<boolean>;
+  /** Opt-in successor: derive the exact browser session from the host's authenticated request. */
+  sessionIdForRequest?: (request: Request) => string | null | Promise<string | null>;
+  turnJournal?: PublisherTurnJournal;
+  onDiagnostic?: (code: string) => void;
+  publicOrigins: string[];
+  surfaceId: string;
+  placementKey: string;
+  jobType: "chat" | "code" | "image" | "voice" | "agent";
+  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" | "clip">;
+  positionHint: "above" | "below" | "sidebar" | "between";
+  /** Optional advanced caps; saved allowedSizes determine the normal envelope. */
+  maxWidth?: number;
+  maxHeight?: number;
+  allowedSizes: Array<{ width: number; height: number; formats?: Array<"banner" | "native" | "clip"> }>;
+  responsiveSizeSelection?: boolean;
+  bidfloor?: number;
+  bidfloorCurrency?: string;
+  blockedCategories?: string[];
+};
+export type GenerationLifecycleEvent = {
+  type: "started" | "done" | "error" | "abort";
+  sessionId: string;
+  generationId: string;
+};
+export type PublisherServer = {
+  sessionGET(request: Request): Promise<Response>;
+  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;