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

package/dist/server.js

@@ -1,47 +1,94 @@
+import { Buffer } from "node:buffer";
 import { generationTransport } from "./generation.js";
+export { createPublisherTurnJournal, derivePublisherTurnKeySecret } from "./turn-journal.js";
+export { createPostgresTurnStorage } from "./postgres-turn-storage.js";
 
 const PREFERENCE_VERSION = "contextual-choice/v2";
 const PREFERENCE_TTL = 30 * 24 * 60 * 60;
 const MAX_PUBLISHER_BODY_BYTES = 16 * 1024;
 const MAX_WAVEBIRD_RESPONSE_BYTES = 256 * 1024;
 const MAX_PARALLEL_WAVEBIRD_REQUESTS = 2;
+const MAX_ALLOWED_SIZES = 8;
+const MAX_SIZE_EDGE = 4096;
+const MAX_ENVELOPE_EDGE = 8192;
 const ID = /^[A-Za-z0-9_-]{1,128}$/;
 const JOB_ID = /^job_[A-Za-z0-9_-]{1,128}$/;
 const PLACEMENT_KEY = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const SERVER_OPTION_KEYS = new Set(["apiBaseUrl", "clientId", "secretKey", "preferenceSecret", "authorize",
+  "sessionIdForRequest", "turnJournal", "onDiagnostic", "publicOrigins", "surfaceId", "placementKey",
+  "jobType", "locale", "timing", "consentMode", "gdprApplies", "publisher", "allowedFormats",
+  "positionHint", "maxWidth", "maxHeight", "allowedSizes", "responsiveSizeSelection", "bidfloor",
+  "bidfloorCurrency", "blockedCategories"]);
 
 function response(error, status, headers = {}) {
   return Response.json({ error }, { status, headers: { "Cache-Control": "no-store", ...headers } });
 }
 
 function normalizeOptions(options) {
-  if (typeof window !== "undefined") throw new Error("publisher_server_only");
+  if (typeof document !== "undefined") throw new Error("publisher_server_only");
+  if (options && Object.keys(options).some(key => !SERVER_OPTION_KEYS.has(key))) throw new Error("publisher_option_unknown");
   if (!options || typeof options.authorize !== "function") throw new Error("publisher_authorize_required");
-  if (!String(options.clientId || "").startsWith("wbproj_")) throw new Error("publisher_project_invalid");
-  if (!String(options.secretKey || "").trim()) throw new Error("publisher_server_key_required");
-  if (!ID.test(options.surfaceId || "") || !PLACEMENT_KEY.test(options.placementKey || "")) throw new Error("publisher_placement_invalid");
+  if (options.onDiagnostic !== undefined && typeof options.onDiagnostic !== "function")
+    throw new Error("publisher_diagnostic_invalid");
+  if (typeof options.preferenceSecret !== "string" || new TextEncoder().encode(options.preferenceSecret).byteLength < 32) throw new Error("preference_secret_required");
+  if ((options.turnJournal === undefined) !== (options.sessionIdForRequest === undefined) ||
+      (options.turnJournal !== undefined && (typeof options.sessionIdForRequest !== "function" ||
+        ["claimPlacement", "releaseRejectedPlacement", "bind", "claimGeneration", "phase"].some(name => typeof options.turnJournal?.[name] !== "function"))))
+    throw new Error("publisher_turn_journal_invalid");
+  if (typeof options.clientId !== "string" || !options.clientId.startsWith("wbproj_")) throw new Error("publisher_project_invalid");
+  if (typeof options.secretKey !== "string") throw new Error("publisher_server_key_invalid");
+  if (!options.secretKey.trim()) throw new Error("publisher_server_key_required");
+  if (!/^sk_(?:test|live)_/.test(options.secretKey)) throw new Error("publisher_server_key_invalid");
+  if (typeof options.surfaceId !== "string" || typeof options.placementKey !== "string" || !ID.test(options.surfaceId) || !PLACEMENT_KEY.test(options.placementKey)) throw new Error("publisher_placement_invalid");
   if (!["before", "during", "after"].includes(options.timing)) throw new Error("publisher_timing_invalid");
   if (!["wavebird_consent", "own_cmp"].includes(options.consentMode)) throw new Error("publisher_consent_mode_invalid");
-  if (!Array.isArray(options.allowedFormats) || options.allowedFormats.length === 0 || options.allowedFormats.some(value => !["banner", "native"].includes(value))) throw new Error("publisher_formats_invalid");
+  if (options.gdprApplies !== undefined && typeof options.gdprApplies !== "boolean") throw new Error("publisher_gdpr_invalid");
+  if (!Array.isArray(options.allowedFormats) || options.allowedFormats.length === 0 || options.allowedFormats.some(value => !["banner", "native", "clip"].includes(value))) throw new Error("publisher_formats_invalid");
   if (!["above", "below", "sidebar", "between"].includes(options.positionHint)) throw new Error("publisher_position_invalid");
-  if (!Number.isSafeInteger(options.maxWidth) || options.maxWidth < 1 || !Number.isSafeInteger(options.maxHeight) || options.maxHeight < 1) throw new Error("publisher_envelope_invalid");
-  if (!Array.isArray(options.allowedSizes) || options.allowedSizes.length === 0 || options.allowedSizes.some(size => !Number.isSafeInteger(size.width) || !Number.isSafeInteger(size.height) || size.width < 1 || size.height < 1 || size.width > options.maxWidth || size.height > options.maxHeight ||
+  if (!Array.isArray(options.allowedSizes) || options.allowedSizes.length === 0 || options.allowedSizes.length > MAX_ALLOWED_SIZES || options.allowedSizes.some(size => !size || typeof size !== "object" || Object.keys(size).some(key => !["width", "height", "formats"].includes(key)) || !Number.isSafeInteger(size.width) || !Number.isSafeInteger(size.height) || size.width < 1 || size.height < 1 || size.width > MAX_SIZE_EDGE || size.height > MAX_SIZE_EDGE ||
     (size.formats !== undefined && (!Array.isArray(size.formats) || size.formats.length === 0 || size.formats.some(format => !options.allowedFormats.includes(format)))))) throw new Error("publisher_sizes_invalid");
+  if (new Set(options.allowedSizes.map(size => `${size.width}x${size.height}`)).size !== options.allowedSizes.length)
+    throw new Error("publisher_sizes_invalid");
+  const maxWidth = options.maxWidth === undefined ? options.allowedSizes.reduce((max, size) => Math.max(max, size.width), 0) : options.maxWidth;
+  const maxHeight = options.maxHeight === undefined ? options.allowedSizes.reduce((max, size) => Math.max(max, size.height), 0) : options.maxHeight;
+  if (!Number.isSafeInteger(maxWidth) || maxWidth < 1 || maxWidth > MAX_ENVELOPE_EDGE ||
+      !Number.isSafeInteger(maxHeight) || maxHeight < 1 || maxHeight > MAX_ENVELOPE_EDGE)
+    throw new Error("publisher_envelope_invalid");
+  const eligibleSizes = options.allowedSizes.filter(size => size.width <= maxWidth && size.height <= maxHeight);
+  const hasFloor = Object.hasOwn(options, "bidfloor");
+  const hasCurrency = Object.hasOwn(options, "bidfloorCurrency");
+  if (hasFloor !== hasCurrency || (hasFloor && (!Number.isFinite(options.bidfloor) || options.bidfloor < 0 || typeof options.bidfloorCurrency !== "string" || !/^[A-Za-z]{3}$/.test(options.bidfloorCurrency))))
+    throw new Error("publisher_bidfloor_override_invalid");
   if (options.responsiveSizeSelection !== undefined && typeof options.responsiveSizeSelection !== "boolean") throw new Error("publisher_responsive_selection_invalid");
-  if (!options.publisher || typeof options.publisher.app_name !== "string" || typeof options.publisher.app_domain !== "string" || !Array.isArray(options.publisher.categories)) throw new Error("publisher_identity_invalid");
-  if (typeof options.jobType !== "string" || !options.jobType || typeof options.locale !== "string" || !options.locale) throw new Error("publisher_job_invalid");
-  const base = String(options.apiBaseUrl || "https://api.wavebird.ai").trim().replace(/\/+$/, "").replace(/\/v1$/, "") + "/v1";
-  if (!/^https:\/\//.test(base)) throw new Error("publisher_api_https_required");
+  if (!options.publisher || typeof options.publisher !== "object" || Object.keys(options.publisher).some(key => !["app_name", "app_domain", "categories"].includes(key)) ||
+    typeof options.publisher.app_name !== "string" || !options.publisher.app_name.trim() ||
+    typeof options.publisher.app_domain !== "string" || !options.publisher.app_domain.trim() ||
+    !Array.isArray(options.publisher.categories) ||
+    options.publisher.categories.some(value => typeof value !== "string" || !value.trim())) throw new Error("publisher_identity_invalid");
+  if (options.blockedCategories !== undefined && (!Array.isArray(options.blockedCategories) ||
+    options.blockedCategories.some(value => typeof value !== "string" || !value.trim())))
+    throw new Error("publisher_blocked_categories_invalid");
+  if (!["chat", "code", "image", "voice", "agent"].includes(options.jobType) || typeof options.locale !== "string" || !options.locale) throw new Error("publisher_job_invalid");
+  const apiBaseUrl = options.apiBaseUrl === undefined ? "https://api.wavebird.ai" : options.apiBaseUrl;
+  if (typeof apiBaseUrl !== "string" || !apiBaseUrl.trim() || /[\\?#]/.test(apiBaseUrl)) throw new Error("publisher_api_https_required");
+  const endpoint = apiBaseUrl.trim();
+  let parsedEndpoint;
+  try { parsedEndpoint = new URL(endpoint); } catch { throw new Error("publisher_api_https_required"); }
+  if (parsedEndpoint.protocol !== "https:" || !parsedEndpoint.hostname || parsedEndpoint.username || parsedEndpoint.password ||
+      parsedEndpoint.search || parsedEndpoint.hash) throw new Error("publisher_api_https_required");
+  const base = endpoint.replace(/\/+$/, "").replace(/\/v1$/, "") + "/v1";
   {
     if (!Array.isArray(options.publicOrigins) || options.publicOrigins.length < 1 || options.publicOrigins.length > 8) throw new Error("publisher_public_origins_invalid");
     for (const origin of options.publicOrigins) {
       let url;
       try { url = new URL(origin); } catch { throw new Error("publisher_public_origins_invalid"); }
       const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1";
-      if (url.origin !== origin || (url.protocol !== "https:" && !(loopback && url.protocol === "http:"))) throw new Error("publisher_public_origins_invalid");
+      if (url.origin !== origin || (url.protocol !== "https:" && !(loopback && url.protocol === "http:" && options.secretKey.startsWith("sk_test_")))) throw new Error("publisher_public_origins_invalid");
     }
     if (new Set(options.publicOrigins).size !== options.publicOrigins.length) throw new Error("publisher_public_origins_invalid");
   }
-  return { ...options, base, consentSource: options.consentMode === "wavebird_consent" ? "wavebird_consent" : "wrapper_cmp" };
+  return { ...options, allowedSizes: eligibleSizes, maxWidth, maxHeight, base,
+    consentSource: options.consentMode === "wavebird_consent" ? "wavebird_consent" : "wrapper_cmp" };
 }
 
 function publicOrigin(request, options) {
@@ -163,12 +210,17 @@ function boundedGenerationReporter() {
   };
 }
 
-function observeGeneration(response, request, onLifecycle) {
-  if (typeof onLifecycle !== "function" || response.headers.get("x-wavebird-generation-transport") !== "1" || !response.body) return response;
+function observeGeneration(response, request, onLifecycle, onCritical) {
+  if (typeof onLifecycle !== "function" && typeof onCritical !== "function") return response;
+  if (response.headers.get("x-wavebird-generation-transport") !== "1" || !response.body) return response;
   const reader = response.body.getReader();
   const decoder = new TextDecoder();
   let terminal = false;
-  const notify = event => {
+  const notify = async event => {
+    if (typeof onCritical === "function") {
+      try { await onCritical(event); } catch {}
+    }
+    if (typeof onLifecycle !== "function") return;
     try { Promise.resolve(onLifecycle(event)).catch(() => {}); } catch {}
   };
   const body = new ReadableStream({
@@ -181,7 +233,7 @@ function observeGeneration(response, request, onLifecycle) {
           const record = JSON.parse(decoder.decode(next.value));
           if (["started", "done", "error", "abort"].includes(record.type)) {
             if (record.type !== "started") terminal = true;
-            notify({ type: record.type, sessionId: record.session_id, generationId: record.generation_id });
+            await notify({ type: record.type, sessionId: record.session_id, generationId: record.generation_id });
           }
         } catch {}
         controller.enqueue(next.value);
@@ -190,7 +242,7 @@ function observeGeneration(response, request, onLifecycle) {
     async cancel(reason) {
       if (!terminal) {
         terminal = true;
-        notify({ type: "abort", sessionId: request.headers.get("x-wavebird-session-id"), generationId: request.headers.get("x-wavebird-generation-id") });
+        await notify({ type: "abort", sessionId: request.headers.get("x-wavebird-session-id"), generationId: request.headers.get("x-wavebird-generation-id") });
       }
       try { await reader.cancel(reason); } catch {}
     }
@@ -203,12 +255,40 @@ export function createPublisherServer(inputOptions) {
   const placementFetch = boundedFetcher();
   const consentFetch = boundedFetcher();
   const generationReportFetch = boundedGenerationReporter();
+  const diagnostic = code => { try { options.onDiagnostic?.(code); } catch {} };
+  if (typeof options.turnJournal?.reconcilePending === "function") {
+    void Promise.resolve().then(() => options.turnJournal.reconcilePending(options.clientId, options.surfaceId))
+      .catch(() => diagnostic("turn_journal_unavailable"));
+  }
+  async function journalCall(operation) {
+    let timer;
+    try { return await Promise.race([
+      Promise.resolve().then(operation),
+      new Promise((_, reject) => { timer = setTimeout(() => reject(new Error("turn_journal_timeout")), 1500); })
+    ]); } finally { clearTimeout(timer); }
+  }
+  async function trustedTurn(request, sessionId, turnId) {
+    if (!ID.test(sessionId || "") || !ID.test(turnId || "")) return null;
+    let trusted;
+    try { trusted = await journalCall(() => options.sessionIdForRequest(request)); } catch { return null; }
+    return trusted === sessionId ? { projectId: options.clientId, surfaceId: options.surfaceId, sessionId, turnId } : null;
+  }
+  async function sessionGET(request) {
+    if (!options.turnJournal) return response("turn_binding_unavailable", 404);
+    if (!await authorized(request)) return response("authentication_required", 401);
+    if (!validOrigin(request, options, false)) return response("invalid_origin", 403);
+    let sessionId;
+    try { sessionId = await journalCall(() => options.sessionIdForRequest(request)); }
+    catch { diagnostic("publisher_session_unavailable"); return response("publisher_session_unavailable", 503); }
+    if (!ID.test(sessionId || "")) return response("publisher_session_unavailable", 401);
+    return Response.json({ session_id: sessionId }, { headers: { "Cache-Control": "no-store", Vary: "Cookie" } });
+  }
   const cookieName = `__Host-wavebird-preference-${options.clientId}-${options.surfaceId}`;
   const cookie = (value, ttl = PREFERENCE_TTL) => `${cookieName}=${value}; Path=/; HttpOnly; Secure; SameSite=Strict; Max-Age=${ttl}`;
   const scope = request => ({ project: options.clientId, surface: options.surfaceId, version: PREFERENCE_VERSION,
     profile: options.consentMode === "wavebird_consent" ? "wavebird_dialog" : "publisher_custom", origin: publicOrigin(request, options) });
   async function preferenceKey() {
-    if (!options.preferenceSecret || options.preferenceSecret.length < 32) throw new Error("preference_secret_required");
+    if (new TextEncoder().encode(options.preferenceSecret).byteLength < 32) throw new Error("preference_secret_required");
     return crypto.subtle.importKey("raw", new TextEncoder().encode(options.preferenceSecret), { name: "HMAC", hash: "SHA-256" }, false, ["sign", "verify"]);
   }
   async function signPreference(request, state) {
@@ -229,11 +309,14 @@ export function createPublisherServer(inputOptions) {
     if (qaOutcomes.length && !options.secretKey.startsWith("sk_test_")) return response("qa_test_outcome_requires_test_key", 403);
     const input = await readPublisherJson(request);
     if (input instanceof Response) return input;
+    const turn = options.turnJournal ? await trustedTurn(request, input?.session_id, input?.turn_id) : null;
+    if (options.turnJournal && !turn) return response("publisher_turn_context_invalid", 401);
     let allowedSizes = options.allowedSizes.map(({ width, height }) => ({ width, height }));
     let allowedFormats = options.allowedFormats;
     let maxWidth = options.maxWidth;
     let maxHeight = options.maxHeight;
-    if (options.responsiveSizeSelection === true) {
+    const noFit = () => Response.json({ decision: { fill: false, reason: "no_fit" }, placement: null }, { headers: { "Cache-Control": "no-store" } });
+    if (options.responsiveSizeSelection !== false) {
       const bounds = input?.container_size;
       if (!bounds || !Number.isSafeInteger(bounds.width) || !Number.isSafeInteger(bounds.height) ||
           bounds.width < 1 || bounds.height < 1 || bounds.width > 8192 || bounds.height > 8192) {
@@ -241,10 +324,11 @@ export function createPublisherServer(inputOptions) {
       }
       const requestedFormat = input?.format ?? "auto";
       if (requestedFormat !== "auto" && !options.allowedFormats.includes(requestedFormat)) return response("publisher_format_invalid", 400);
+      if (allowedSizes.length === 0) return noFit();
       const fitting = options.allowedSizes.filter(size => size.width <= bounds.width && size.height <= bounds.height &&
         (requestedFormat === "auto" || (size.formats ?? options.allowedFormats).includes(requestedFormat)))
         .sort((a, b) => b.width - a.width || b.height - a.height);
-      if (fitting.length === 0) return Response.json({ decision: { fill: false, reason: "no_fit" }, placement: null }, { headers: { "Cache-Control": "no-store" } });
+      if (fitting.length === 0) return noFit();
       const selected = fitting[0];
       allowedSizes = [{ width: selected.width, height: selected.height }];
       allowedFormats = requestedFormat === "auto"
@@ -253,6 +337,13 @@ export function createPublisherServer(inputOptions) {
       maxWidth = Math.min(maxWidth, bounds.width);
       maxHeight = Math.min(maxHeight, bounds.height);
     }
+    else if (allowedSizes.length === 0) return noFit();
+    if (turn) {
+      let claimed;
+      try { claimed = await journalCall(() => options.turnJournal.claimPlacement(turn)); }
+      catch { diagnostic("turn_journal_unavailable"); return response("turn_journal_unavailable", 503); }
+      if (!claimed) return response("publisher_turn_replayed", 409);
+    }
     const sessionId = typeof input?.session_id === "string" && input.session_id.trim() ? input.session_id.trim() : crypto.randomUUID();
     const body = {
       client_id: options.clientId, session_id: sessionId, job_type: options.jobType, locale: options.locale,
@@ -260,8 +351,7 @@ export function createPublisherServer(inputOptions) {
       slot_hint: { position: options.positionHint, max_width: maxWidth, max_height: maxHeight,
         allowed_sizes: allowedSizes, presentation_version: "sponsored_moment_v2" },
       overrides: { allowed_formats: allowedFormats, timing: options.timing,
-        bidfloor: options.bidfloor ?? 0.5, bidfloor_currency: options.bidfloorCurrency ?? "EUR",
-        gdpr_applies: options.gdprApplies === true,
+        ...(Object.hasOwn(options, "bidfloor") ? { bidfloor: options.bidfloor, bidfloor_currency: options.bidfloorCurrency.toUpperCase() } : {}),
         publisher: { app_name: options.publisher.app_name, app_domain: options.publisher.app_domain,
           ...(options.publisher.categories.length ? { categories: options.publisher.categories } : {}) },
         ...(options.blockedCategories?.length ? { blocked_categories: options.blockedCategories } : {}) },
@@ -269,9 +359,27 @@ export function createPublisherServer(inputOptions) {
         consent_source: options.consentSource }
     };
     try {
-      return await placementFetch(`${options.base}/placements?wait_ms=1500${qaOutcomes.length ? "&test_outcome=no_fill" : ""}`, { method: "POST", headers: {
+      const result = await placementFetch(`${options.base}/placements?wait_ms=1500${qaOutcomes.length ? "&test_outcome=no_fill" : ""}`, { method: "POST", headers: {
         Authorization: `Bearer ${options.secretKey}`, "Content-Type": "application/json"
       }, body: JSON.stringify(body), cache: "no-store" });
+      if (turn && [400, 401, 403].includes(result.status)) {
+        try { await journalCall(() => options.turnJournal.releaseRejectedPlacement(turn)); }
+        catch { diagnostic("turn_journal_unavailable"); }
+      }
+      if (turn && result.status === 200) {
+        let payload;
+        try { payload = await result.clone().json(); } catch {}
+        const jobId = payload?.job_id;
+        if (JOB_ID.test(jobId || "")) {
+          try { await journalCall(() => options.turnJournal.bind(turn, jobId)); }
+          catch { diagnostic("turn_binding_unavailable"); return response("turn_binding_unavailable", 502); }
+        } else if (!(payload?.decision?.fill === false &&
+                     Object.hasOwn(payload ?? {}, "placement") && payload.placement === null)) {
+          diagnostic("turn_binding_unavailable");
+          return response("turn_binding_unavailable", 502);
+        }
+      }
+      return result;
     } catch { return response("wavebird_placement_unavailable", 502); }
   }
   async function consentGET(request) {
@@ -336,8 +444,24 @@ export function createPublisherServer(inputOptions) {
   async function withGeneration({ request, run, onLifecycle }) {
     if (!await authorized(request)) return response("authentication_required", 401);
     if (!validOrigin(request, options)) return response("invalid_origin", 403);
+    const turn = options.turnJournal ? await trustedTurn(request,
+      request.headers.get("x-wavebird-session-id"), request.headers.get("x-wavebird-generation-id")) : null;
+    if (options.turnJournal && !turn) return response("publisher_turn_context_invalid", 401);
+    if (turn) {
+      let claimed;
+      try { claimed = await journalCall(() => options.turnJournal.claimGeneration(turn)); }
+      catch { diagnostic("turn_journal_unavailable"); return run(request.signal); }
+      if (!claimed) return response("publisher_turn_replayed", 409);
+      try { await journalCall(() => options.turnJournal.phase(turn, "started")); }
+      catch { diagnostic("turn_journal_unavailable"); return run(request.signal); }
+    }
     const result = await generationTransport({ request, run });
-    return observeGeneration(result, request, onLifecycle);
+    const critical = turn ? async event => {
+      if (event.type === "started") return;
+      try { await journalCall(() => options.turnJournal.phase(turn, event.type === "done" ? "finished" : "failed")); }
+      catch { diagnostic("turn_journal_unavailable"); }
+    } : null;
+    return observeGeneration(result, request, onLifecycle, critical);
   }
   async function reportGeneration(jobId, event) {
     if (!JOB_ID.test(jobId) || !["started", "finished", "failed"].includes(event)) throw new Error("invalid_generation_report");
@@ -345,5 +469,5 @@ export function createPublisherServer(inputOptions) {
       method: "POST", headers: { Authorization: `Bearer ${options.secretKey}`, "Content-Type": "application/json" }, body: "{}"
     });
   }
-  return { placementPOST, consentGET, consentPOST, withGeneration, reportGeneration };
+  return { sessionGET, placementPOST, consentGET, consentPOST, withGeneration, reportGeneration };
 }

package/dist/turn-journal.js

@@ -0,0 +1,157 @@
+import { Buffer } from "node:buffer";
+import { createHash, createHmac, randomUUID } from "node:crypto";
+
+const ID = /^[A-Za-z0-9_-]{1,128}$/;
+const JOB_ID = /^job_[A-Za-z0-9_-]{1,128}$/;
+
+/** Domain-separate the stable server preference secret for pseudonymous turn keys. */
+export function derivePublisherTurnKeySecret(preferenceSecret) {
+  if (typeof preferenceSecret !== "string" || Buffer.byteLength(preferenceSecret, "utf8") < 32)
+    throw new Error("publisher_preference_secret_invalid");
+  return createHmac("sha256", preferenceSecret).update("wavebird/turn-journal-key/v1").digest("hex");
+}
+
+/** Package-owned state machine over a publisher's existing atomic, durable store. */
+export function createPublisherTurnJournal({ storage, reportGeneration, keySecret, onDiagnostic }) {
+  if (typeof storage?.atomic !== "function" || typeof storage?.scan !== "function" ||
+      typeof reportGeneration !== "function") throw new Error("publisher_turn_storage_invalid");
+  if (typeof keySecret !== "string" || Buffer.byteLength(keySecret, "utf8") < 32)
+    throw new Error("publisher_turn_key_secret_invalid");
+  if (onDiagnostic !== undefined && typeof onDiagnostic !== "function")
+    throw new Error("publisher_diagnostic_invalid");
+  const tasks = new Set();
+  let activeReports = 0;
+  const reportWaiters = [];
+  const diagnostic = code => { try { onDiagnostic?.(code); } catch {} };
+  const verifiedScopes = new Set();
+  const versionKey = createHash("sha256").update("wavebird/turn-journal-version-row/v1").digest("hex");
+  const keyFingerprint = createHmac("sha256", keySecret).update("wavebird/turn-journal-key-version/v1").digest("hex");
+  async function verifyKeyVersion(scope) {
+    if (verifiedScopes.has(scope)) return;
+    // A separate scope keeps this guard outside ordinary turn retention pruning.
+    const versionScope = createHash("sha256").update(JSON.stringify(["wavebird/turn-journal-meta/v1", scope])).digest("hex");
+    await storage.atomic(versionScope, versionKey, previous => {
+      if (previous && previous.keyFingerprint !== keyFingerprint)
+        throw new Error("publisher_turn_key_version_conflict");
+      return { state: previous || { keyFingerprint }, result: null };
+    });
+    verifiedScopes.add(scope);
+  }
+  function identity(turn) {
+    if (![turn?.projectId, turn?.surfaceId, turn?.sessionId, turn?.turnId].every(value => ID.test(value || "")))
+      throw new Error("publisher_turn_context_invalid");
+    const scope = createHash("sha256").update(JSON.stringify([turn.projectId, turn.surfaceId])).digest("hex");
+    const key = createHmac("sha256", keySecret).update(JSON.stringify([turn.projectId, turn.surfaceId, turn.sessionId, turn.turnId])).digest("hex");
+    return { scope, key };
+  }
+  function initial(scope) {
+    return { scope, createdAtMs: Date.now(), placementClaimed: false, generationClaimed: false,
+      jobId: null, phase: "idle", startedReported: false, terminalReported: false,
+      leaseId: null, leaseUntilMs: 0 };
+  }
+  async function change(turn, update) {
+    const { scope, key } = identity(turn);
+    await verifyKeyVersion(scope);
+    return storage.atomic(scope, key, previous => {
+      if (previous && previous.scope !== scope) throw new Error("publisher_turn_scope_conflict");
+      const state = { ...(previous || initial(scope)) };
+      const result = update(state);
+      return { state, result };
+    });
+  }
+  async function claimPlacement(turn) {
+    return change(turn, state => {
+      if (state.placementClaimed) return false;
+      state.placementClaimed = true;
+      return true;
+    });
+  }
+  async function releaseRejectedPlacement(turn) {
+    await change(turn, state => { if (!state.jobId) state.placementClaimed = false; });
+  }
+  async function claimGeneration(turn) {
+    return change(turn, state => {
+      if (state.generationClaimed) return false;
+      state.generationClaimed = true;
+      return true;
+    });
+  }
+  function schedule(scope, key) {
+    const task = drain(scope, key).catch(() => diagnostic("turn_journal_unavailable"));
+    tasks.add(task);
+    void task.finally(() => tasks.delete(task));
+  }
+  async function bind(turn, jobId) {
+    if (!JOB_ID.test(jobId || "")) throw new Error("publisher_job_id_invalid");
+    const { scope, key } = identity(turn);
+    const bound = await change(turn, state => {
+      if (!state.placementClaimed || state.jobId && state.jobId !== jobId) return false;
+      state.jobId = jobId;
+      return true;
+    });
+    if (!bound) throw new Error("publisher_turn_job_conflict");
+    schedule(scope, key);
+  }
+  async function phase(turn, event) {
+    if (!["started", "finished", "failed"].includes(event)) throw new Error("publisher_phase_invalid");
+    const { scope, key } = identity(turn);
+    const changed = await change(turn, state => {
+      if (!state.generationClaimed || state.phase !== (event === "started" ? "idle" : "started")) return false;
+      state.phase = event;
+      return true;
+    });
+    if (changed) schedule(scope, key);
+  }
+  async function lease(scope, key) {
+    return storage.atomic(scope, key, previous => {
+      if (!previous || previous.scope !== scope || !previous.jobId || previous.phase === "idle" ||
+          previous.leaseUntilMs > Date.now()) return { state: previous, result: null };
+      const event = !previous.startedReported ? "started" :
+        ["finished", "failed"].includes(previous.phase) && !previous.terminalReported ? previous.phase : null;
+      if (!event) return { state: previous, result: null };
+      const leaseId = randomUUID();
+      return { state: { ...previous, leaseId, leaseUntilMs: Date.now() + 10_000 },
+        result: { jobId: previous.jobId, event, leaseId } };
+    });
+  }
+  async function ack(scope, key, event, leaseId, accepted) {
+    await storage.atomic(scope, key, previous => {
+      if (!previous || previous.scope !== scope || previous.leaseId !== leaseId)
+        return { state: previous, result: null };
+      const state = { ...previous, leaseId: null, leaseUntilMs: 0 };
+      if (accepted) state[event === "started" ? "startedReported" : "terminalReported"] = true;
+      return { state, result: null };
+    });
+  }
+  async function drain(scope, key) {
+    while (true) {
+      const next = await lease(scope, key);
+      if (!next) return;
+      if (activeReports >= 4) await new Promise(resolve => reportWaiters.push(resolve));
+      activeReports++;
+      let accepted = false;
+      try { await reportGeneration(next.jobId, next.event); accepted = true; }
+      catch { diagnostic("generation_report_unavailable"); }
+      finally { activeReports--; reportWaiters.shift()?.(); }
+      await ack(scope, key, next.event, next.leaseId, accepted);
+      if (!accepted) return;
+    }
+  }
+  async function reconcilePending(projectId, surfaceId) {
+    if (!ID.test(projectId || "") || !ID.test(surfaceId || "")) throw new Error("publisher_turn_scope_invalid");
+    const scope = createHash("sha256").update(JSON.stringify([projectId, surfaceId])).digest("hex");
+    if (typeof storage.prune === "function" && await storage.prune(scope) > 0)
+      diagnostic("generation_report_retention_expired");
+    let cursor = "";
+    while (true) {
+      const keys = await storage.scan(scope, cursor, 100);
+      if (!Array.isArray(keys) || keys.length > 100 || keys.some((key, index) => typeof key !== "string" ||
+        !/^[a-f0-9]{64}$/.test(key) || key <= (index ? keys[index - 1] : cursor)))
+        throw new Error("publisher_turn_scan_invalid");
+      if (keys.length === 0) return;
+      await Promise.all(keys.map(key => drain(scope, key)));
+      cursor = keys.at(-1);
+    }
+  }
+  return { claimPlacement, releaseRejectedPlacement, bind, claimGeneration, phase, reconcilePending };
+}

package/examples/next-js/app/api/sponsor-session/route.js

@@ -0,0 +1,5 @@
+import { getPublisher } from "../../../lib/publisher.js";
+
+export async function GET(request) {
+  return getPublisher().sessionGET(request);
+}

package/examples/next-js/app/page.jsx

@@ -9,7 +9,15 @@ export default function Page() {
   const abort = useRef(null);
   const [answer, setAnswer] = useState("");
   useEffect(() => {
-    const current = createPublisherAds({
+    if (!slot.current) return;
+    const controller = new AbortController();
+    let disposed = false;
+    let current = null;
+    void fetch("/api/sponsor-session", { cache: "no-store", signal: controller.signal }).then(async response => {
+      if (!response.ok) return;
+      const sessionId = (await response.json()).session_id;
+      if (disposed || !/^[A-Za-z0-9_-]{1,128}$/.test(sessionId)) return;
+      current = createPublisherAds({
       target: slot.current,
       clientId: "wbproj_replace_from_dashboard",
       surfaceId: "chat_assistant",
@@ -18,13 +26,16 @@ export default function Page() {
       consentMode: "wavebird_consent",
       userId: "replace-with-authenticated-user-id",
       conversationId: "replace-with-current-conversation-id",
+      sessionId,
+      turnBinding: true,
       rendererUrl: "https://api.wavebird.ai/v1/render.js",
       placementEndpoint: "/api/sponsor-slot",
       consentEndpoint: "/api/sponsor-consent",
       privacySettingsTarget: "#privacy-settings"
-    });
-    ads.current = current;
-    return () => { abort.current?.abort(); current.dispose(); ads.current = null; };
+      });
+      ads.current = current;
+    }).catch(() => {});
+    return () => { disposed = true; controller.abort(); abort.current?.abort(); current?.dispose(); ads.current = null; };
   }, []);
   async function generate() {
     if (!ads.current) return;

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

@@ -1,12 +1,33 @@
+import "server-only";
+
+const cache = new WeakMap();
+const ID = /^[A-Za-z0-9_-]{1,128}$/;
+
+/** Resolve a non-credential correlation ID from the app's authenticated session. */
+export function sessionIdForRequest(request) {
+  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) {
-  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-js/lib/publisher.js

@@ -1,16 +1,25 @@
 import "server-only";
-import { createPublisherServer } from "@wavebirdai/api/server";
-import { authorizePublisherRequest } from "./auth.js";
+import { createPublisherServer, createPublisherTurnJournal, derivePublisherTurnKeySecret } from "@wavebirdai/api/server";
+import { authorizePublisherRequest, sessionIdForRequest } from "./auth.js";
+import { publisherTurnStorage } from "./turn-store.js";
 
 let publisher;
 
 export function getPublisher() {
-  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() {
   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-js/lib/turn-store.js

@@ -0,0 +1,9 @@
+import "server-only";
+
+/** Replace this fail-closed stub with createPostgresTurnStorage(your existing pg pool). */
+export function publisherTurnStorage() {
+  return {
+    async atomic() { throw new Error("Connect your existing durable turn store"); },
+    async scan() { throw new Error("Connect your existing durable turn store"); },
+  };
+}

package/examples/next-ts/app/api/sponsor-session/route.ts

@@ -0,0 +1,5 @@
+import { getPublisher } from "../../../lib/publisher";
+
+export async function GET(request: Request): Promise<Response> {
+  return getPublisher().sessionGET(request);
+}