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

package/src/server.js

@@ -0,0 +1,448 @@
+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 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 (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 ((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 (!String(options.clientId || "").startsWith("wbproj_")) throw new Error("publisher_project_invalid");
+  if (!String(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 (!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", "clip"].includes(value))) throw new Error("publisher_formats_invalid");
+  if (!["above", "below", "sidebar", "between"].includes(options.positionHint)) throw new Error("publisher_position_invalid");
+  if (!Array.isArray(options.allowedSizes) || options.allowedSizes.length === 0 || 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.formats !== undefined && (!Array.isArray(size.formats) || size.formats.length === 0 || size.formats.some(format => !options.allowedFormats.includes(format)))))) 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 || !Number.isSafeInteger(maxHeight) || maxHeight < 1) 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 !== "object" || Object.keys(options.publisher).some(key => !["app_name", "app_domain", "categories"].includes(key)) || 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 (!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:" && 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, allowedSizes: eligibleSizes, maxWidth, maxHeight, base,
+    consentSource: options.consentMode === "wavebird_consent" ? "wavebird_consent" : "wrapper_cmp" };
+}
+
+function publicOrigin(request, options) {
+  const host = request.headers.get("host")?.toLowerCase();
+  if (!host) return null;
+  const matches = options.publicOrigins.filter(origin => new URL(origin).host.toLowerCase() === host);
+  const browserOrigin = request.headers.get("origin");
+  if (browserOrigin) return matches.includes(browserOrigin) ? browserOrigin : null;
+  if (matches.length === 1) return matches[0];
+  const routeOrigin = new URL(request.url).origin;
+  return matches.includes(routeOrigin) ? routeOrigin : null;
+}
+
+function validOrigin(request, options, strict = true) {
+  const origin = request.headers.get("origin");
+  const site = request.headers.get("sec-fetch-site");
+  const expected = publicOrigin(request, options);
+  return expected !== null && (strict ? origin === expected : !origin || origin === expected) &&
+    (strict ? site !== "cross-site" : !site || site === "same-origin");
+}
+
+function gpc(request) {
+  return (request.headers.get("sec-gpc") || "").split(",").some(value => value.trim() === "1");
+}
+
+function proxyResult(upstream, body, extra = {}) {
+  return new Response(body || null, { status: upstream.status, headers: {
+    "Content-Type": upstream.headers.get("content-type") || "application/json",
+    "Cache-Control": "no-store",
+    ...(upstream.headers.get("x-request-id") ? { "x-request-id": upstream.headers.get("x-request-id") } : {}),
+    ...extra
+  } });
+}
+
+async function readBoundedText(value, limit, signal) {
+  if (!value.body) return "";
+  const reader = value.body.getReader();
+  const decoder = new TextDecoder();
+  let bytes = 0;
+  let output = "";
+  const cancel = () => { void reader.cancel().catch(() => {}); };
+  signal.addEventListener("abort", cancel, { once: true });
+  try {
+    while (true) {
+      if (signal.aborted) throw new Error("body_timeout");
+      const next = await reader.read();
+      if (signal.aborted) throw new Error("body_timeout");
+      if (next.done) break;
+      bytes += next.value.byteLength;
+      if (bytes > limit) { cancel(); throw new Error("body_limit_exceeded"); }
+      output += decoder.decode(next.value, { stream: true });
+    }
+    return output + decoder.decode();
+  } finally {
+    signal.removeEventListener("abort", cancel);
+    reader.releaseLock();
+  }
+}
+
+async function readPublisherJson(request) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 1500);
+  try { return JSON.parse(await readBoundedText(request, MAX_PUBLISHER_BODY_BYTES, controller.signal)); }
+  catch (error) {
+    const reason = error instanceof Error ? error.message : "invalid_json";
+    return response(reason, reason === "body_limit_exceeded" ? 413 : controller.signal.aborted ? 408 : 400);
+  } finally { clearTimeout(timer); }
+}
+
+function boundedFetcher() {
+  let active = 0;
+  return async (url, init) => {
+    if (active >= MAX_PARALLEL_WAVEBIRD_REQUESTS) return response("wavebird_capacity_exceeded", 429);
+    active++;
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    init.signal?.addEventListener("abort", abort, { once: true });
+    if (init.signal?.aborted) abort();
+    let timer;
+    const deadline = new Promise((_, reject) => {
+      timer = setTimeout(() => { abort(); reject(new Error("upstream_timeout")); }, 5000);
+    });
+    try {
+      return await Promise.race([deadline, (async () => {
+        const upstream = await fetch(url, { ...init, signal: controller.signal, redirect: "error", cache: "no-store" });
+        const body = await readBoundedText(upstream, MAX_WAVEBIRD_RESPONSE_BYTES, controller.signal);
+        return proxyResult(upstream, body);
+      })()]);
+    } finally {
+      controller.abort();
+      clearTimeout(timer);
+      init.signal?.removeEventListener("abort", abort);
+      active--;
+    }
+  };
+}
+
+function boundedGenerationReporter() {
+  let active = 0;
+  return async (url, init) => {
+    if (active >= MAX_PARALLEL_WAVEBIRD_REQUESTS) throw new Error("wavebird_capacity_exceeded");
+    active++;
+    const controller = new AbortController();
+    let timer;
+    const deadline = new Promise((_, reject) => {
+      timer = setTimeout(() => { controller.abort(); reject(new Error("generation_report_timeout")); }, 5000);
+    });
+    try {
+      await Promise.race([deadline, (async () => {
+        const upstream = await fetch(url, { ...init, signal: controller.signal, redirect: "error", cache: "no-store" });
+        await upstream.body?.cancel();
+        if (!upstream.ok) throw new Error(`generation_report_http_${upstream.status}`);
+      })()]);
+    } finally {
+      controller.abort();
+      clearTimeout(timer);
+      active--;
+    }
+  };
+}
+
+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 = 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({
+    async pull(controller) {
+      try {
+        const next = await reader.read();
+        if (next.done) { controller.close(); return; }
+        // The canonical transport emits one complete JSONL record per chunk.
+        try {
+          const record = JSON.parse(decoder.decode(next.value));
+          if (["started", "done", "error", "abort"].includes(record.type)) {
+            if (record.type !== "started") terminal = true;
+            await notify({ type: record.type, sessionId: record.session_id, generationId: record.generation_id });
+          }
+        } catch {}
+        controller.enqueue(next.value);
+      } catch (error) { controller.error(error); }
+    },
+    async cancel(reason) {
+      if (!terminal) {
+        terminal = true;
+        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 {}
+    }
+  }, { highWaterMark: 1 });
+  return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+}
+
+export function createPublisherServer(inputOptions) {
+  const options = normalizeOptions(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");
+    return crypto.subtle.importKey("raw", new TextEncoder().encode(options.preferenceSecret), { name: "HMAC", hash: "SHA-256" }, false, ["sign", "verify"]);
+  }
+  async function signPreference(request, state) {
+    const now = Date.now();
+    const payload = Buffer.from(JSON.stringify({ ...scope(request), state, issued_at: now, expires_at: now + PREFERENCE_TTL * 1000 })).toString("base64url");
+    const signature = await crypto.subtle.sign("HMAC", await preferenceKey(), new TextEncoder().encode(payload));
+    return cookie(payload + "." + Buffer.from(signature).toString("base64url"));
+  }
+  async function authorized(request) {
+    try { return await options.authorize(request) === true; } catch { return false; }
+  }
+  async function placementPOST(request) {
+    if (!await authorized(request)) return response("authentication_required", 401);
+    if (gpc(request)) return response("privacy_signal_policy_required", 403);
+    if (!validOrigin(request, options)) return response("invalid_origin", 403);
+    const qaOutcomes = new URL(request.url).searchParams.getAll("qa_test_outcome");
+    if (qaOutcomes.length > 1 || (qaOutcomes.length === 1 && qaOutcomes[0] !== "no_fill")) return response("invalid_qa_test_outcome", 400);
+    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;
+    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) {
+        return response("publisher_container_size_invalid", 400);
+      }
+      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 noFit();
+      const selected = fitting[0];
+      allowedSizes = [{ width: selected.width, height: selected.height }];
+      allowedFormats = requestedFormat === "auto"
+        ? options.allowedFormats.filter(format => fitting.some(size => size.width === selected.width && size.height === selected.height && (size.formats ?? options.allowedFormats).includes(format)))
+        : [requestedFormat];
+      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,
+      slots_requested: 1, placement_key: options.placementKey,
+      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,
+        ...(Object.hasOwn(options, "bidfloor") ? { bidfloor: options.bidfloor, bidfloor_currency: options.bidfloorCurrency.toUpperCase() } : {}),
+        gdpr_applies: options.gdprApplies === true,
+        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 } : {}) },
+      consent: { semantic_targeting: false, prompt_shared: false, gdpr_applies: options.gdprApplies === true,
+        consent_source: options.consentSource }
+    };
+    try {
+      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) {
+    if (!await authorized(request)) return response("authentication_required", 401);
+    const headers = { "Cache-Control": "no-store", Vary: "Cookie, Sec-GPC" };
+    if (!validOrigin(request, options, false)) return response("invalid_origin", 403, headers);
+    if (gpc(request)) return Response.json({ preference: null }, { headers });
+    try {
+      const value = (request.headers.get("cookie") || "").split(";").map(value => value.trim())
+        .find(value => value.startsWith(cookieName + "="))?.slice(cookieName.length + 1) || "";
+      if (value.length > 2048) throw new Error("preference_invalid");
+      const [payload, signature, extra] = value.split(".");
+      if (!payload || !signature || extra || !/^[A-Za-z0-9_-]+$/.test(payload) || !/^[A-Za-z0-9_-]+$/.test(signature)) return Response.json({ preference: null }, { headers });
+      if (!await crypto.subtle.verify("HMAC", await preferenceKey(), Buffer.from(signature, "base64url"), new TextEncoder().encode(payload))) return Response.json({ preference: null }, { headers });
+      const record = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+      const now = Date.now();
+      if (Object.entries(scope(request)).some(([key, value]) => record[key] !== value) ||
+        !["granted", "denied", "withdrawn"].includes(record.state) || !Number.isSafeInteger(record.issued_at) ||
+        !Number.isSafeInteger(record.expires_at) || record.issued_at > now || record.expires_at <= now ||
+        record.expires_at - record.issued_at !== PREFERENCE_TTL * 1000) return Response.json({ preference: null }, { headers });
+      return Response.json({ preference: { state: record.state, expires_at: record.expires_at } }, { headers });
+    } catch { return Response.json({ preference: null, error: "preference_unavailable" }, { headers }); }
+  }
+  async function consentPOST(request) {
+    if (!await authorized(request)) return response("authentication_required", 401);
+    if (!validOrigin(request, options)) return response("invalid_origin", 403);
+    if (gpc(request)) return response("privacy_signal_policy_required", 403);
+    const input = await readPublisherJson(request);
+    if (input instanceof Response) return input;
+    if (!input || typeof input.session_id !== "string" || !input.session_id.trim() ||
+      !["granted", "denied", "withdrawn", "cmp_error"].includes(input.lifecycle_state) ||
+      !Number.isSafeInteger(input.revision) || input.revision < 1) return response("consent_input_invalid", 400);
+    if (["tcf_string", "gpp_string", "gpp_sections"].some(field => Object.hasOwn(input, field))) return response("external_consent_protocol_requires_policy", 400);
+    const clear = input.remember_for_30_days === true ? { "Set-Cookie": cookie("", 0) } : {};
+    if (input.remember_for_30_days === true) {
+      try { await preferenceKey(); } catch { return response("preference_unavailable", 503, clear); }
+    }
+    let upstream;
+    let text;
+    try {
+      upstream = await consentFetch(options.base + "/consent", { method: "POST", headers: {
+        Authorization: `Bearer ${options.secretKey}`, "Content-Type": "application/json"
+      }, cache: "no-store", body: JSON.stringify({
+        client_id: options.clientId, session_id: input.session_id.trim(),
+        decision: options.consentMode === "wavebird_consent" ? "custom" : "basic",
+        source: options.consentMode === "wavebird_consent" ? "wavebird_dialog" : "publisher_custom",
+        lifecycle_state: input.lifecycle_state, revision: input.revision,
+        purposes: { semantic_targeting: false, session_persistence: false, cross_session_persistence: false, prompt_shared: false }
+      }) });
+      text = await upstream.text();
+    } catch { return response("consent_sync_unavailable", 502, clear); }
+    let setCookie = clear;
+    if (upstream.ok && input.remember_for_30_days === true && input.lifecycle_state !== "cmp_error") {
+      let snapshot;
+      try { snapshot = JSON.parse(text).authoritative_consent; } catch {}
+      if (snapshot?.lifecycle_state !== input.lifecycle_state || snapshot.revision !== input.revision) return response("consent_snapshot_invalid", 502, clear);
+      try { setCookie = { "Set-Cookie": await signPreference(request, input.lifecycle_state) }; }
+      catch { return response("preference_unavailable", 503, clear); }
+    }
+    return proxyResult(upstream, text, setCookie);
+  }
+  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 });
+    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");
+    await generationReportFetch(`${options.base}/jobs/${encodeURIComponent(jobId)}/generation/${event}`, {
+      method: "POST", headers: { Authorization: `Bearer ${options.secretKey}`, "Content-Type": "application/json" }, body: "{}"
+    });
+  }
+  return { sessionGET, placementPOST, consentGET, consentPOST, withGeneration, reportGeneration };
+}

package/src/turn-journal.js

@@ -0,0 +1,154 @@
+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");
+  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/templates/NEXT-SETUP.md

@@ -1,11 +1,12 @@
 # Connect wavebird to this Next.js app
 
-The generator installed `lib/publisher`, `lib/auth`, and `lib/model`; `app/api/generate`, `app/api/sponsor-slot`, and `app/api/sponsor-consent`; and `components/WavebirdPlacement` (under `src/` when `src/app` was selected). No existing page was replaced.
+The generator installed `lib/publisher`, `lib/auth`, `lib/turn-store` and `lib/model`; `app/api/generate`, `app/api/sponsor-slot`, `app/api/sponsor-consent` and `app/api/sponsor-session`; and `components/WavebirdPlacement` (under `src/` when `src/app` was selected). No existing page was replaced.
 
-1. Set server-only `WAVEBIRD_CLIENT_ID`, `WAVEBIRD_SECRET_KEY`, `WAVEBIRD_PREFERENCE_SECRET`, and `WAVEBIRD_PUBLIC_ORIGINS`. The last value is a comma-separated list of the exact scheme, host, and port where your app is opened. Keep the Dashboard project domain at your real HTTPS host. For local Server Test-key testing, include the exact loopback origin in `WAVEBIRD_PUBLIC_ORIGINS` without changing that project domain; Browser Test Keys instead use their separate Allowed origins field in API Keys. `localhost` and `127.0.0.1` are distinct. Do not use wildcards. The package rejects an absent or malformed list. Never expose the key or preference secret through `NEXT_PUBLIC_` or client props. `clientId` is the public project ID.
-2. Replace `lib/publisher`'s example surface, placement, dimensions, formats, locale, consent mode, and publisher identity with the **saved Dashboard values**. The responsive example lists 728×90 and 320×50 Banner sizes only to show the size-selection shape. Keep `responsiveSizeSelection: true` only when the selected project and placement approve every configured size. Remove any size absent from the saved project before Test traffic. The API enforces its own authority; example values do not create a valid placement.
-3. Connect `lib/auth` to the app's real session authorization. Its supplied path check fails closed when `PUBLISHER_AUTH_CHECK_PATH` is absent. The path must be a publisher-owned same-origin route that returns 204 only for an authorized user; it must not be any wavebird route.
-4. Connect `lib/model` to the existing generation stream. The installed function throws until replaced. Keep the existing generation response and pass the supplied abort signal to it. Do not put model calls in the browser solely for this integration.
-5. In an existing client page, mount `<WavebirdPlacement clientId={publicProjectId} userId={authenticatedUserId} conversationId={activeConversationId} onReady={setAds} />` beside the real generation result, outside the input and transcript. When the user starts their existing generation, call `ads.connectGeneration({ signal, request: headers => fetch('/api/generate', { method: 'POST', headers, signal }), consume: async (response, lifecycle) => { /* consume your existing stream and call lifecycle.onDelta() for each delta */ } })`. Abort that same signal on Stop or unmount. Use a stable `onReady` callback. This example uses wavebird's consent dialog; if the saved project uses the publisher's own CMP, connect its real grant/deny/withdrawal/expiry/GPC lifecycle instead of changing only the label.
+1. Set server-only `WAVEBIRD_CLIENT_ID`, `WAVEBIRD_SECRET_KEY`, `WAVEBIRD_PREFERENCE_SECRET` (a stable random value of at least 32 bytes), and `WAVEBIRD_PUBLIC_ORIGINS`. The last value is a comma-separated list of the exact scheme, host, and port where your app is opened. Keep the Dashboard project domain at your real HTTPS host. For local Server Test-key testing, include the exact loopback origin in `WAVEBIRD_PUBLIC_ORIGINS` without changing that project domain; Browser Test Keys instead use their separate Allowed origins field in API Keys. `localhost` and `127.0.0.1` are distinct. Do not use wildcards. The package rejects an absent or malformed list. Never expose server secrets through `NEXT_PUBLIC_` or client props. `clientId` is the public project ID.
+2. Replace `lib/publisher`'s example surface, placement, allowed sizes, formats, locale, consent mode, and publisher identity with the **saved Dashboard values**. The responsive example lists 728×90 and 320×50 Banner sizes only to show the size-selection shape. The saved sizes define the normal envelope; optional `maxWidth` and `maxHeight` are advanced caps that only narrow it. Keep `responsiveSizeSelection: true` only when the selected project and placement approve every configured size. Remove any size absent from the saved project before Test traffic. The API enforces its own authority; example values do not create a valid placement.
+3. Connect `lib/auth` to the app's real session authorization. Its supplied path check fails closed when `PUBLISHER_AUTH_CHECK_PATH` is absent. The path must be a publisher-owned same-origin route that returns 204 only for an authorized user and supplies an `x-publisher-session-id` header containing a stable non-credential correlation ID for that authenticated session. Never return a cookie, bearer token or raw credential as that ID. The route must not be any wavebird route. The example sends the session cookie to that check only when the request origin exactly matches `WAVEBIRD_PUBLIC_ORIGINS`; a missing or different origin fails closed. The package checks that the browser's session ID matches this server-validated value before placement or generation.
+4. Replace `lib/turn-store`'s fail-closed stub with `createPostgresTurnStorage(yourExistingPgPool)` or another persistent store implementing the package's atomic interface. For PostgreSQL, run the adapter's `install()` once in your normal database migration step; use a pool shared by the publisher's workers. Keep `WAVEBIRD_PREFERENCE_SECRET` stable across workers and restarts; the package derives a separate journal key from it and rejects a changed key for an active project. Coordinate secret rotation after active turns are drained; never clear the journal guard to restore ad service while turns remain. The package owns turn claims, ordered reports, retry and bounded reconciliation. An unavailable store suppresses ad placement while the authenticated model route remains available.
+5. Connect `lib/model` to the existing generation stream. The installed function throws until replaced. Keep the existing generation response and pass the supplied abort signal to it. Do not put model calls in the browser solely for this integration.
+6. In an existing client page, mount `<WavebirdPlacement clientId={publicProjectId} userId={authenticatedUserId} conversationId={activeConversationId} onReady={setAds} />` beside the real generation result, outside the input and transcript. The component retrieves the non-credential session ID through the authenticated same-origin route. When the user starts their existing generation, call `ads.connectGeneration({ signal, request: headers => fetch('/api/generate', { method: 'POST', headers, signal }), consume: async (response, lifecycle) => { /* consume your existing stream and call lifecycle.onDelta() for each delta */ } })`. Abort that same signal on Stop, logout or unmount. Use a stable `onReady` callback. This example uses wavebird's consent dialog; if the saved project uses the publisher's own CMP, connect its real grant/deny/withdrawal/expiry/GPC lifecycle instead of changing only the label.
 
 These routes are real required Next.js files, not hidden package behavior. The package has no knowledge of your login session, CMP, or model stream. Start with a Test project and check that No-Fill, abort and late responses never block the primary result; all Test facts must remain nonpayable.