@wavebirdai/api 0.1.0-beta.1 → 0.1.0-beta.4

package/README.md

@@ -1,55 +1,99 @@
-# wavebird publisher API
+# @wavebirdai/api
 
-`@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.
+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.
 
-## Installation
+## Integrate with Next.js
 
-For the npm prerelease, run this in the existing Next.js app directory beside `package.json`:
+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.
 
-```sh
-npm install @wavebirdai/api@0.1.0-beta.1
-```
+1. Install the package and generate the route files for your app directory:
 
-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.
+   ```sh
+   npm install @wavebirdai/api@0.1.0-beta.4
+   ./node_modules/.bin/wavebird-next init --lang ts --root . --app-dir src/app
+   ```
 
-The [full REST reference](https://wavebird.ai/api/reference/endpoints) remains available for integrations without this package.
+   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.
 
-Both JavaScript and TypeScript use the same package and URL; there is no separate language package.
+2. Set the server-only values in your deployment environment:
 
-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.
+   ```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
+   ```
 
-## Next.js route generator
+   `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.
 
-After installing the package, run one of these commands in an existing Next.js App Router project:
+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.
 
-```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
-```
+   The generated server route keeps the Wavebird key on the server and wraps your existing stream:
 
-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.
+   ```ts
+   import { getPublisher } from "../../../lib/publisher";
+   import { existingGeneration } from "../../../lib/model";
 
-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.
+   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 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.
+`@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 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.
+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-only Test key into the build process; the helper still validates configuration before handling traffic.
+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. 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.
+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
 

package/bin/wavebird-next.mjs

@@ -35,10 +35,12 @@ export async function plan(argv) {
   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")]
   ];

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

@@ -1,8 +1,9 @@
+/** 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 }): void;
+  setConversation(binding: { userId: string; conversationId: string; sessionId?: string }): void;
   dispose(): void;
   openPrivacySettings(): void;
   grant(choice?: unknown): Promise<unknown>;
@@ -16,6 +17,9 @@ export function createPublisherAds(options: {
   jobType: string;
   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;

package/dist/browser.js

@@ -21,9 +21,13 @@ function loadRenderer(url) {
 export function createPublisherAds(options) {
   const target = options.target;
   if (!target || !options.userId || !options.conversationId) throw new Error("Application container and session are required");
+  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: crypto.randomUUID() };
+  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");
@@ -48,6 +52,8 @@ export function createPublisherAds(options) {
       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;
@@ -58,10 +64,14 @@ export function createPublisherAds(options) {
   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 (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: crypto.randomUUID() };
+    binding = { userId: next.userId, conversationId: next.conversationId,
+      sessionId: turnBinding ? next.sessionId : crypto.randomUUID() };
     sponsor?.setConversation(binding); prepare();
   }
   function dispose() {
@@ -77,6 +87,8 @@ export function createPublisherAds(options) {
     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 }) });
@@ -144,7 +156,8 @@ export function createPublisherAds(options) {
                 return;
               }
               if (["done", "error", "abort"].includes(record.type)) {
-                ended = true; event(job, 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;
@@ -158,12 +171,16 @@ export function createPublisherAds(options) {
       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);
+        ended = true;
+        if (record.type !== "done" || timing !== "after") event(job, record.type);
       }
-      const primary = new Response([204, 205, 304].includes(metadata.status) ? null : output, {
+      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
       });
-      return await consume(primary, { onDelta: () => event(job, "progress") });
+      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;

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 };
+}

package/dist/server.d.ts

@@ -1,9 +1,45 @@
+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;
@@ -13,11 +49,12 @@ export type PublisherServerOptions = {
   consentMode: "wavebird_consent" | "own_cmp";
   gdprApplies: boolean;
   publisher: { app_name: string; app_domain: string; categories: string[] };
-  allowedFormats: Array<"banner" | "native">;
+  allowedFormats: Array<"banner" | "native" | "clip">;
   positionHint: "above" | "below" | "sidebar" | "between";
-  maxWidth: number;
-  maxHeight: number;
-  allowedSizes: Array<{ width: number; height: number; formats?: Array<"banner" | "native"> }>;
+  /** 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;
@@ -29,6 +66,7 @@ export type GenerationLifecycleEvent = {
   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>;