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

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

package/templates/WavebirdPlacement.jsx

@@ -7,7 +7,14 @@ export function WavebirdPlacement({ clientId, userId, conversationId, onReady })
   const target = useRef(null);
   useEffect(() => {
     if (!target.current || !clientId || !userId || !conversationId) return;
-    const ads = createPublisherAds({
+    const controller = new AbortController();
+    let disposed = false;
+    let ads = 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;
+      ads = createPublisherAds({
       target: target.current,
       clientId,
       surfaceId: "chat_assistant",
@@ -16,13 +23,16 @@ export function WavebirdPlacement({ clientId, userId, conversationId, onReady })
       consentMode: "wavebird_consent",
       userId,
       conversationId,
+      sessionId,
+      turnBinding: true,
       rendererUrl: "https://api.wavebird.ai/v1/render.js",
       placementEndpoint: "/api/sponsor-slot",
       consentEndpoint: "/api/sponsor-consent",
       privacySettingsTarget: "#wavebird-privacy-settings"
-    });
-    onReady?.(ads);
-    return () => { onReady?.(null); ads.dispose(); };
+      });
+      onReady?.(ads);
+    }).catch(() => {});
+    return () => { disposed = true; controller.abort(); onReady?.(null); ads?.dispose(); };
   }, [clientId, userId, conversationId, onReady]);
   return <>
     <button id="wavebird-privacy-settings" type="button">Sponsored choices</button>

package/templates/WavebirdPlacement.tsx

@@ -12,8 +12,16 @@ export function WavebirdPlacement({ clientId, userId, conversationId, onReady }:
   const target = useRef<HTMLElement | null>(null);
   useEffect(() => {
     if (!target.current || !clientId || !userId || !conversationId) return;
-    const ads = createPublisherAds({
-      target: target.current,
+    const container = target.current;
+    const controller = new AbortController();
+    let disposed = false;
+    let ads: PublisherAds | null = 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;
+      ads = createPublisherAds({
+      target: container,
       clientId,
       surfaceId: "chat_assistant",
       jobType: "chat",
@@ -21,13 +29,16 @@ export function WavebirdPlacement({ clientId, userId, conversationId, onReady }:
       consentMode: "wavebird_consent",
       userId,
       conversationId,
+      sessionId,
+      turnBinding: true,
       rendererUrl: "https://api.wavebird.ai/v1/render.js",
       placementEndpoint: "/api/sponsor-slot",
       consentEndpoint: "/api/sponsor-consent",
       privacySettingsTarget: "#wavebird-privacy-settings"
-    });
-    onReady?.(ads);
-    return () => { onReady?.(null); ads.dispose(); };
+      });
+      onReady?.(ads);
+    }).catch(() => {});
+    return () => { disposed = true; controller.abort(); onReady?.(null); ads?.dispose(); };
   }, [clientId, userId, conversationId, onReady]);
   return <>
     <button id="wavebird-privacy-settings" type="button">Sponsored choices</button>