@wavebirdai/api 0.1.0-beta.18 → 0.1.0-beta.19

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.0-beta.19
+
+- Bind consent writes to the authenticated publisher session when a trusted session resolver is configured. A stale or different session is rejected before any consent write or preference-cookie change.
+- Release late model response bodies after cancellation, including browser disposal and conversation changes.
+- Reject canceled or superseded generations after asynchronous result presentation instead of returning success.
+- Supply both lifecycle callbacks for raw/model-only responses and the helper without an ad mount.
+- Acquire generation-report leases only when a dispatch slot is available, preventing expiry while queued.
+- Reuse each server instance's non-exportable preference signing key and release rejected auth-check bodies in the examples.
+- Clarify maintained Node.js runtimes, response cancellation, database timeouts and pending-report recovery. Existing package pins and technical minimum remain unchanged.
+
 ## 0.1.0-beta.18
 
 - Prevent fractional clipping of the hosted ad frame at some device scales.

package/README.md

@@ -16,17 +16,17 @@ Native iOS and Android packages are not currently available. See [integration pa
 
 ## Set up JavaScript or TypeScript
 
-Use Node.js 20 or later on your server.
+Use a [supported Node.js LTS release](https://github.com/nodejs/Release#release-schedule) with current security updates. The technical minimum remains Node.js 20, which is no longer maintained.
 
-1. **Open your project in Dashboard.** Choose your language and package version. In App settings, verify the domain using a DNS TXT record or HTTPS file, then save your HTTPS app URL and approved origins. `www.example.com` and `example.com` are separate hosts.
+1. **Open your app in Dashboard.** Choose JavaScript or TypeScript. New apps use the current package; existing apps keep their saved version. Verify your domain with an HTTPS file or DNS TXT record, then save your HTTPS app URL and approved origins. `www.example.com` and `example.com` are separate hosts.
 2. **Install the package.** Run this in your app's terminal, in the folder containing `package.json`:
 
    ```sh
-   npm install @wavebirdai/api@0.1.0-beta.18
+   npm install @wavebirdai/api@0.1.0-beta.19
    ```
 
 3. **Save the Server ENV from Overview, Integration step 2.** The key-only download is not the full configuration. Keep `WAVEBIRD_SECRET_KEY` and the stable, project-specific `WAVEBIRD_PREFERENCE_SECRET` out of browser code and Git. Include the saved `WAVEBIRD_PUBLIC_ORIGINS`.
-4. **Connect the backend and frontend code.** Follow Dashboard's generated files to connect your app session, durable turn storage, model stream and ad slot. The source ZIP contains code only; download secret Server ENV separately. Keep the saved formats, sizes and timing. For apps with a Content Security Policy, follow the [exact renderer rules](https://github.com/wavebird-ai/api/blob/main/docs/web/nextjs.md#generate-files).
+4. **Connect the backend and frontend code.** Follow Dashboard's generated files to connect your app session, durable turn storage, model stream and ad slot. The source ZIP contains code only; download secret Server ENV separately. Keep the project-approved formats, timing and size limits. For apps with a Content Security Policy, follow the [exact renderer rules](https://github.com/wavebird-ai/api/blob/main/docs/web/nextjs.md#generate-files).
 5. **Run your first Test ad.** Confirm that the ad appears and the request is recorded in Test Logs. Check that generation still works with declined consent, no available ad and Stop.
 
 Test ads are nonpayable. Complete the [Live prerequisites](https://wavebird.ai/api/guides/going-live) before requesting Live activation.
@@ -35,7 +35,7 @@ For Next.js, you can use the [generator](https://github.com/wavebird-ai/api/blob
 
 ## Connect your model output
 
-Use `@wavebirdai/api/server` on the server and `@wavebirdai/api/browser` for the ad slot. Your response consumer must display the model output and finish only after the result is visible.
+Use `@wavebirdai/api/server` on the server and `@wavebirdai/api/browser` for the ad slot. Your response consumer must display the model output and finish only after the result is visible. Forward the same abort signal to your request and stop your own UI updates when it is aborted. Canceled or superseded generations reject with `generation_aborted`.
 
 [JavaScript and TypeScript examples](https://github.com/wavebird-ai/api/blob/main/docs/web/generation.md) | [Server and browser reference](https://github.com/wavebird-ai/api/blob/main/docs/web/reference.md)
 

package/dist/browser.js

@@ -145,7 +145,7 @@ export function createPublisherAds(options) {
     if (next.userId === binding.userId && next.conversationId === binding.conversationId &&
         (!turnBinding || next.sessionId === binding.sessionId)) return;
     if (turnBinding && next.sessionId === binding.sessionId) throw new Error("publisher_session_reuse");
-    if (active) event(active, "abort");
+    active?.cancel?.();
     context++; active = null;
     binding = { userId: next.userId, conversationId: next.conversationId,
       sessionId: turnBinding ? next.sessionId : crypto.randomUUID() };
@@ -153,7 +153,7 @@ export function createPublisherAds(options) {
   }
   function dispose() {
     if (disposed) return;
-    if (active) event(active, "abort");
+    active?.cancel?.();
     disposed = true; context++; active = null;
     sponsor?.dispose(); sponsor = null; slot.remove();
     slot.removeEventListener?.("ad:render_failed", onRenderFailure, true);
@@ -187,20 +187,21 @@ export function createPublisherAds(options) {
   async function connectGeneration({ request, consume, signal }) {
     const job = { id: crypto.randomUUID(), sessionId: binding.sessionId, context, state: "pending", cancelled: false,
       presented: false, consumed: false };
-    if (active) event(active, "abort");
-    active = job;
-    let reader = null, ended = false, buffer = "";
+    active?.cancel?.();
+    let reader = null, response = null, ended = false, buffer = "";
     const decoder = new TextDecoder();
     const abort = () => { event(job, "abort"); job.cancelled = true; void reader?.cancel().catch(() => {}); };
+    job.cancel = abort;
+    active = job;
     signal?.addEventListener("abort", abort, { once: true });
     if (signal?.aborted) abort();
     const headers = { "x-wavebird-session-id": job.sessionId, "x-wavebird-generation-id": job.id };
     try {
       if (signal?.aborted) throw new Error("generation_aborted");
-      const response = await request(headers);
+      response = await request(headers);
       if (!current(job)) throw new Error("generation_aborted");
       if (response.headers.get("x-wavebird-generation-transport") !== "1") {
-        const result = await consume(response, { onDelta() {} });
+        const result = await consume(response, { onDelta() {}, onPresented() {} });
         if (!current(job)) throw new Error("generation_aborted");
         return result;
       }
@@ -208,6 +209,7 @@ export function createPublisherAds(options) {
       reader = response.body.getReader();
       async function nextRecord() {
         while (true) {
+          if (!current(job)) throw new Error("generation_aborted");
           const boundary = buffer.indexOf("\n");
           if (boundary >= 0) {
             const line = buffer.slice(0, boundary); buffer = buffer.slice(boundary + 1);
@@ -218,7 +220,7 @@ export function createPublisherAds(options) {
           }
           if (buffer.length > 32768) throw new Error("generation_transport_limit");
           const next = await reader.read();
-          if (signal?.aborted) throw new Error("generation_aborted");
+          if (!current(job)) throw new Error("generation_aborted");
           if (next.done) throw new Error("generation_transport_truncated");
           buffer += decoder.decode(next.value, { stream: true });
         }
@@ -272,6 +274,7 @@ export function createPublisherAds(options) {
         event(job, "progress");
         if (timing === "before" || (timing === "during" && options.jobType === "image")) event(job, "presented");
       }, onPresented: () => event(job, "presented") });
+      if (!current(job)) throw new Error("generation_aborted");
       job.consumed = true;
       if (timing === "before" || (timing === "during" && options.jobType === "image")) event(job, "presented");
       if (timing === "after" && ended && !noBody) event(job, "done");
@@ -283,6 +286,8 @@ export function createPublisherAds(options) {
       if (!ended && job.state === "started") event(job, "abort");
       signal?.removeEventListener("abort", abort);
       if (reader) { try { await reader.cancel(); } catch {} reader.releaseLock(); }
+      else if (response?.body && !response.body.locked) void response.body.cancel().catch(() => {});
+      job.cancel = null;
     }
   }
   return { ready, connectGeneration, setConversation, dispose, openPrivacySettings,
@@ -292,7 +297,7 @@ export function createPublisherAds(options) {
 }
 
 export async function connectPublisherGeneration(url, init, consume, ads = window.publisherAds) {
-  if (!ads) return consume(await fetch(url, init), { onDelta() {} });
+  if (!ads) return consume(await fetch(url, init), { onDelta() {}, onPresented() {} });
   return ads.connectGeneration({
     signal: init.signal ?? undefined,
     request: values => {

package/dist/generation.js

@@ -11,10 +11,15 @@ function generationTransport({ request, run }) {
     request.signal.addEventListener("abort", stop, { once: true });
     if (request.signal.aborted)
         stop();
-    let reader = null;
+    let reader = null, modelResponse = null;
     let pending;
     try {
-        pending = Promise.resolve(run(abort.signal));
+        pending = Promise.resolve(run(abort.signal)).then(response => {
+            modelResponse = response;
+            if (abort.signal.aborted && response?.body && !response.body.locked)
+                void response.body.cancel().catch(() => { });
+            return response;
+        });
     }
     catch (error) {
         pending = Promise.reject(error);
@@ -67,6 +72,9 @@ function generationTransport({ request, run }) {
                 catch { }
                 reader.releaseLock();
             }
+            else if (modelResponse?.body && !modelResponse.body.locked) {
+                void modelResponse.body.cancel().catch(() => { });
+            }
             request.signal.removeEventListener("abort", stop);
         }
     }
@@ -87,6 +95,9 @@ function generationTransport({ request, run }) {
         cancel(reason) {
             abort.abort(reason);
             void reader?.cancel(reason).catch(() => { });
+            if (!reader && modelResponse?.body && !modelResponse.body.locked)
+                void modelResponse.body.cancel(reason).catch(() => { });
+            request.signal.removeEventListener("abort", stop);
             void iterator.return(undefined).catch(() => { });
         }
     }, { highWaterMark: 1 });

package/dist/server.d.ts

@@ -61,7 +61,8 @@ type PublisherServerBaseOptions = {
 /** Trusted session resolution and the durable turn journal must be supplied together. */
 export type PublisherServerOptions = PublisherServerBaseOptions & (
   { sessionIdForRequest?: never; turnJournal?: never } |
-  { sessionIdForRequest: (request: Request) => string | null | Promise<string | null>;
+  { /** Resolve the current authenticated session for consent, placement and generation requests. */
+    sessionIdForRequest: (request: Request) => string | null | Promise<string | null>;
     turnJournal: PublisherTurnJournal }
 );
 export type GenerationLifecycleEvent = {

package/dist/server.js

@@ -288,9 +288,10 @@ export function createPublisherServer(inputOptions) {
   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) });
+  let preferenceKeyPromise;
   async function preferenceKey() {
     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"]);
+    return preferenceKeyPromise ??= 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();
@@ -432,6 +433,13 @@ export function createPublisherServer(inputOptions) {
       !["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);
+    if (options.sessionIdForRequest) {
+      let sessionId;
+      try { sessionId = await journalCall(() => options.sessionIdForRequest(request)); }
+      catch { return response("publisher_session_unavailable", 503); }
+      if (!ID.test(sessionId || "")) return response("publisher_session_unavailable", 401);
+      if (input.session_id.trim() !== sessionId) return response("publisher_session_mismatch", 401);
+    }
     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); }

package/dist/turn-journal.js

@@ -19,7 +19,6 @@ export function createPublisherTurnJournal({ storage, reportGeneration, keySecre
     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 { Promise.resolve(onDiagnostic?.(code)).catch(() => {}); } catch {} };
@@ -77,9 +76,7 @@ export function createPublisherTurnJournal({ storage, reportGeneration, keySecre
     });
   }
   function schedule(scope, key) {
-    const task = drain(scope, key).catch(() => diagnostic("turn_journal_unavailable"));
-    tasks.add(task);
-    void task.finally(() => tasks.delete(task));
+    void drain(scope, key).catch(() => diagnostic("turn_journal_unavailable"));
   }
   async function bind(turn, jobId) {
     if (!JOB_ID.test(jobId || "")) throw new Error("publisher_job_id_invalid");
@@ -125,15 +122,20 @@ export function createPublisherTurnJournal({ storage, reportGeneration, keySecre
   }
   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++;
+      else 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);
+      try {
+        const next = await lease(scope, key);
+        if (!next) return;
+        try { await reportGeneration(next.jobId, next.event); accepted = true; }
+        catch { diagnostic("generation_report_unavailable"); }
+        await ack(scope, key, next.event, next.leaseId, accepted);
+      } finally {
+        const waiter = reportWaiters.shift();
+        if (waiter) waiter();
+        else activeReports--;
+      }
       if (!accepted) return;
     }
   }

package/docs/web/generation.md

@@ -1,10 +1,10 @@
 # Connect generation to the displayed result
 
-These are connection helpers, not complete apps. Use the same installed `@wavebirdai/api@0.1.0-beta.18` as your server routes.
+These are connection helpers, not complete apps. Use the same installed `@wavebirdai/api@0.1.0-beta.19` as your server routes.
 
 - `ads` is the instance for this surface, returned by `createPublisherAds` or the generated component's `onReady` callback.
 - `sendExistingRequest` sends your existing authenticated model request. Merge the provided headers into its headers and preserve its body and abort signal. Call the route wrapped by `withGeneration`.
-- `consumeAndPresentResponse` is your existing response parser and UI consumer. Call `onDelta` as output becomes visible. Call `onPresented` when the result is presented. Resolve after presentation, and reject on failure. For an image, do not report progress before the result is displayed.
+- `consumeAndPresentResponse` is your existing response parser and UI consumer. Call `onDelta` as output becomes visible and `onPresented` when the result is presented. Resolve after presentation and reject on failure. Capture the same abort signal to stop your own UI updates after Stop or a new submit. For an image, do not report progress before the result is displayed.
 
 ## TypeScript
 
@@ -22,10 +22,7 @@ export function runGeneration<T>(
   return ads.connectGeneration({
     signal,
     request: headers => sendExistingRequest(headers, signal),
-    consume: (response, lifecycle) => consumeAndPresentResponse(response, {
-      onDelta: lifecycle.onDelta,
-      onPresented: () => lifecycle.onPresented?.(),
-    }),
+    consume: consumeAndPresentResponse,
   });
 }
 ```
@@ -39,15 +36,12 @@ export function runGeneration(
   return ads.connectGeneration({
     signal,
     request: headers => sendExistingRequest(headers, signal),
-    consume: (response, lifecycle) => consumeAndPresentResponse(response, {
-      onDelta: lifecycle.onDelta,
-      onPresented: () => lifecycle.onPresented?.(),
-    }),
+    consume: consumeAndPresentResponse,
   });
 }
 ```
 
-The optional call preserves model-only responses, which do not provide an ad presentation callback in this package version. It does not convert failed advertising into a successful ad result.
+Both callbacks are available for every response in this version. For raw/model-only fallback responses they are no-ops; calling them does not start an ad or mark a failed ad as successful.
 
 ## Timing and cleanup
 

package/docs/web/nextjs.md

@@ -2,6 +2,8 @@
 
 Use this path instead of copying Dashboard's route files. It supports an existing Next.js App Router app with JavaScript or TypeScript. Use the saved Dashboard configuration in either path.
 
+Run the app on a supported Node.js LTS release with current security updates. Node.js 20 remains the technical minimum, but is no longer maintained.
+
 ## Generate files
 
 The generator never overwrites existing files. If it reports a conflict, keep your app's file and merge the authentication, storage and generation hooks from [Dashboard Overview](https://dashboard.wavebird.ai/wavebird/overview). Do not delete your model implementation to make the generator run.
@@ -11,7 +13,7 @@ If your app sets Content Security Policy, allow `https://api.wavebird.ai` in its
 From the folder containing `package.json`:
 
 ```sh
-npm install @wavebirdai/api@0.1.0-beta.18 server-only
+npm install @wavebirdai/api@0.1.0-beta.19 server-only
 ./node_modules/.bin/wavebird-next init --lang ts --root . --app-dir src/app
 ```
 

package/docs/web/reference.md

@@ -1,6 +1,6 @@
 # Web integration reference
 
-Applies to `@wavebirdai/api@0.1.0-beta.18`. [Start with the integration steps](../../README.md#set-up-javascript-or-typescript).
+Applies to `@wavebirdai/api@0.1.0-beta.19`. [Start with the integration steps](../../README.md#set-up-javascript-or-typescript).
 
 
 `@wavebirdai/api/server` exports `createPublisherServer`. Configure it with server-only Project ID, Server Test or production Key, preference signing secret, the publisher's real request authorization function, exact `publicOrigins`, and the saved project/placement values shown in the dashboard. The origin list is required. The package compares the browser Origin with a configured public origin whose host matches the route Host, even when Next.js or a proxy gives the route an internal URL. `localhost` and `127.0.0.1` are separate origins, and each port and scheme must match exactly; HTTP loopback is available only with a Server Test Key. A production key also requires its separately approved project and wavebird server authority. Omit `bidfloor` and `bidfloorCurrency` to inherit saved pricing. An explicit override supplies both a nonnegative amount, including zero, and a three-letter currency; the API validates it against the saved project. It returns authenticated `placementPOST`, `consentGET`, `consentPOST`, and `withGeneration` handlers, plus the server-only `reportGeneration(jobId, event)` method. The helper constructs the existing `/v1/placements`, `/v1/consent`, and `/v1/jobs/{id}/generation/{event}` requests; it does not introduce a new wavebird protocol. The wavebird API remains authoritative for saved scope, creative formats, duration, fallback, and financial classification.
@@ -11,7 +11,9 @@ Create the server helper when a request arrives, as the included Next.js example
 
 `withGeneration({ request, run, onLifecycle })` accepts an optional server-side observer. It receives `{ type, sessionId, generationId }` for `started` and one terminal state: `done`, `error`, or `abort`. Use it to forward lifecycle events to your own generation reporter; observer failures do not change the model response. It runs only for authenticated, same-origin requests with valid generation transport IDs. The callback is not awaited, and it receives no prompt or model bytes.
 
-With `sessionIdForRequest` and `turnJournal` configured, the package validates the browser non-credential session ID against the publisher authenticated request, binds one turn to its authorized placement job, and automatically retries ordered generation reports. The PostgreSQL adapter uses the publisher existing pool; run its `install()` in the normal migration step. An unavailable journal suppresses ad placement while an authenticated model request can still run. The store and HMAC key must survive worker restarts. A durable per-project key-version guard rejects a changed preference secret before accepting another turn; pending reports can still reconcile. Coordinate key rotation after active turns are drained rather than clearing the guard while turns remain. These exports are included in `0.1.0-beta.12`. Earlier versions retain their original behavior.
+With `sessionIdForRequest` and `turnJournal` configured, the package validates the non-credential browser session ID against the authenticated request and binds each turn to its authorized placement job. Failed generation reports remain in the durable store. Turn updates and server-helper initialization retry pending reports in order. For recovery during idle periods, call `turnJournal.reconcilePending(projectId, surfaceId)` from an existing server maintenance job; the package does not start a background timer. Delivery is repeatable, so the receiving service must remain idempotent.
+
+The PostgreSQL adapter uses your existing pool. Run its `install()` in your normal migration step and configure pool acquisition, query and lock timeouts. The helper's wait deadline alone does not cancel a database operation. An unavailable journal suppresses ad placement while an authenticated model request can still run. Keep the store and HMAC key stable across workers and restarts. A durable project key-version guard rejects changed keys before new turns; pending reports can still reconcile. Drain active turns before coordinating a key rotation. Never clear the guard to restore ad service. These exports are included from `0.1.0-beta.12`; earlier versions retain their behavior.
 
 Call `reportGeneration` only from trusted server code with a job ID returned by an authorized placement. Its events are `started`, `finished`, and `failed`. The server key scopes the request at wavebird; invalid IDs or events are rejected locally, and each report has a five-second deadline and a parallel request limit. Reporting errors reject the returned promise so the caller can handle them outside the model response path.
 
@@ -19,6 +21,8 @@ Call `reportGeneration` only from trusted server code with a job ID returned by
 
 For `after`, resolve the generation consumer only after your app presents the result. The browser helper waits for both the transport finish and that consumer before starting the placement. If presentation fails, reject the consumer so the placement does not start.
 
+Pass the same abort signal to the request and capture it in your response consumer. Stop, a new submit, conversation changes and disposal invalidate the old generation; it must not report success after its consumer finishes. `generation_aborted` is an expected cancellation, not a reason to replace a key. The consumer must stop its own UI updates when aborted. In beta.19, raw/model-only fallback responses supply both `onDelta` and `onPresented` as no-ops, preserving the typed callback contract without starting an ad.
+
 
 ## Placement and diagnosis
 
@@ -51,6 +55,8 @@ This is a configuration fragment, not a complete integration. Appearance does no
 With the trusted-session integration, consent restoration reads the current server revision before synchronizing the saved choice. Reloading does not reset consent revisions. An unavailable revision keeps ads disabled until consent can be synchronized; it does not block the model response.
 
 - **401:** check the app session and server authorization before changing the wavebird key.
+- **`publisher_session_mismatch`:** the page's session no longer matches the authenticated request. Reload the page and use the current session from your session endpoint. Do not retry with an old ID, replace the key or reset consent counters.
+- **Consent conflict:** reload older open tabs after updating the hosted integration. Request the current consent revision before an explicit choice. A genuine concurrent choice must fail closed; never automatically retry a grant.
 - **Origin rejected:** compare scheme, hostname and port with the saved project and server allowlist. `www.example.com` and `example.com` are separate origins.
 - **No-Fill or `no_fit`:** keep the model result usable. Check saved formats and the measured slot size. Do not stretch a creative to force it to fit.
 - **Empty frame:** record only the fixed error category and relative timing. HTTP 200 alone does not prove visible rendering. Never share signed URLs, headers, tokens or a HAR containing credentials.

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

@@ -21,6 +21,7 @@ export function sessionIdForRequest(request) {
         cache: "no-store", redirect: "manual", signal: AbortSignal.timeout(1500),
       });
       const id = result.headers.get("x-publisher-session-id");
+      void result.body?.cancel().catch(() => {});
       return result.status === 204 && ID.test(id || "") ? id : null;
     } catch { return null; }
   })();

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

@@ -21,6 +21,7 @@ export function sessionIdForRequest(request: Request): Promise<string | null> {
         cache: "no-store", redirect: "manual", signal: AbortSignal.timeout(1500),
       });
       const id = result.headers.get("x-publisher-session-id");
+      void result.body?.cancel().catch(() => {});
       return result.status === 204 && ID.test(id || "") ? id : null;
     } catch { return null; }
   })();

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@wavebirdai/api",
-  "version": "0.1.0-beta.18",
+  "version": "0.1.0-beta.19",
   "private": false,
   "type": "module",
-  "description": "JavaScript and TypeScript integration for wavebird Banner, Native and Clip ads, with consent and generation lifecycle handling.",
+  "description": "JavaScript and TypeScript helpers for wavebird Banner, Native and Clip ads, with consent and generation lifecycle handling.",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/browser.js

@@ -145,7 +145,7 @@ export function createPublisherAds(options) {
     if (next.userId === binding.userId && next.conversationId === binding.conversationId &&
         (!turnBinding || next.sessionId === binding.sessionId)) return;
     if (turnBinding && next.sessionId === binding.sessionId) throw new Error("publisher_session_reuse");
-    if (active) event(active, "abort");
+    active?.cancel?.();
     context++; active = null;
     binding = { userId: next.userId, conversationId: next.conversationId,
       sessionId: turnBinding ? next.sessionId : crypto.randomUUID() };
@@ -153,7 +153,7 @@ export function createPublisherAds(options) {
   }
   function dispose() {
     if (disposed) return;
-    if (active) event(active, "abort");
+    active?.cancel?.();
     disposed = true; context++; active = null;
     sponsor?.dispose(); sponsor = null; slot.remove();
     slot.removeEventListener?.("ad:render_failed", onRenderFailure, true);
@@ -187,20 +187,21 @@ export function createPublisherAds(options) {
   async function connectGeneration({ request, consume, signal }) {
     const job = { id: crypto.randomUUID(), sessionId: binding.sessionId, context, state: "pending", cancelled: false,
       presented: false, consumed: false };
-    if (active) event(active, "abort");
-    active = job;
-    let reader = null, ended = false, buffer = "";
+    active?.cancel?.();
+    let reader = null, response = null, ended = false, buffer = "";
     const decoder = new TextDecoder();
     const abort = () => { event(job, "abort"); job.cancelled = true; void reader?.cancel().catch(() => {}); };
+    job.cancel = abort;
+    active = job;
     signal?.addEventListener("abort", abort, { once: true });
     if (signal?.aborted) abort();
     const headers = { "x-wavebird-session-id": job.sessionId, "x-wavebird-generation-id": job.id };
     try {
       if (signal?.aborted) throw new Error("generation_aborted");
-      const response = await request(headers);
+      response = await request(headers);
       if (!current(job)) throw new Error("generation_aborted");
       if (response.headers.get("x-wavebird-generation-transport") !== "1") {
-        const result = await consume(response, { onDelta() {} });
+        const result = await consume(response, { onDelta() {}, onPresented() {} });
         if (!current(job)) throw new Error("generation_aborted");
         return result;
       }
@@ -208,6 +209,7 @@ export function createPublisherAds(options) {
       reader = response.body.getReader();
       async function nextRecord() {
         while (true) {
+          if (!current(job)) throw new Error("generation_aborted");
           const boundary = buffer.indexOf("\n");
           if (boundary >= 0) {
             const line = buffer.slice(0, boundary); buffer = buffer.slice(boundary + 1);
@@ -218,7 +220,7 @@ export function createPublisherAds(options) {
           }
           if (buffer.length > 32768) throw new Error("generation_transport_limit");
           const next = await reader.read();
-          if (signal?.aborted) throw new Error("generation_aborted");
+          if (!current(job)) throw new Error("generation_aborted");
           if (next.done) throw new Error("generation_transport_truncated");
           buffer += decoder.decode(next.value, { stream: true });
         }
@@ -272,6 +274,7 @@ export function createPublisherAds(options) {
         event(job, "progress");
         if (timing === "before" || (timing === "during" && options.jobType === "image")) event(job, "presented");
       }, onPresented: () => event(job, "presented") });
+      if (!current(job)) throw new Error("generation_aborted");
       job.consumed = true;
       if (timing === "before" || (timing === "during" && options.jobType === "image")) event(job, "presented");
       if (timing === "after" && ended && !noBody) event(job, "done");
@@ -283,6 +286,8 @@ export function createPublisherAds(options) {
       if (!ended && job.state === "started") event(job, "abort");
       signal?.removeEventListener("abort", abort);
       if (reader) { try { await reader.cancel(); } catch {} reader.releaseLock(); }
+      else if (response?.body && !response.body.locked) void response.body.cancel().catch(() => {});
+      job.cancel = null;
     }
   }
   return { ready, connectGeneration, setConversation, dispose, openPrivacySettings,
@@ -292,7 +297,7 @@ export function createPublisherAds(options) {
 }
 
 export async function connectPublisherGeneration(url, init, consume, ads = window.publisherAds) {
-  if (!ads) return consume(await fetch(url, init), { onDelta() {} });
+  if (!ads) return consume(await fetch(url, init), { onDelta() {}, onPresented() {} });
   return ads.connectGeneration({
     signal: init.signal ?? undefined,
     request: values => {

package/src/generation.js

@@ -11,10 +11,15 @@ function generationTransport({ request, run }) {
     request.signal.addEventListener("abort", stop, { once: true });
     if (request.signal.aborted)
         stop();
-    let reader = null;
+    let reader = null, modelResponse = null;
     let pending;
     try {
-        pending = Promise.resolve(run(abort.signal));
+        pending = Promise.resolve(run(abort.signal)).then(response => {
+            modelResponse = response;
+            if (abort.signal.aborted && response?.body && !response.body.locked)
+                void response.body.cancel().catch(() => { });
+            return response;
+        });
     }
     catch (error) {
         pending = Promise.reject(error);
@@ -67,6 +72,9 @@ function generationTransport({ request, run }) {
                 catch { }
                 reader.releaseLock();
             }
+            else if (modelResponse?.body && !modelResponse.body.locked) {
+                void modelResponse.body.cancel().catch(() => { });
+            }
             request.signal.removeEventListener("abort", stop);
         }
     }
@@ -87,6 +95,9 @@ function generationTransport({ request, run }) {
         cancel(reason) {
             abort.abort(reason);
             void reader?.cancel(reason).catch(() => { });
+            if (!reader && modelResponse?.body && !modelResponse.body.locked)
+                void modelResponse.body.cancel(reason).catch(() => { });
+            request.signal.removeEventListener("abort", stop);
             void iterator.return(undefined).catch(() => { });
         }
     }, { highWaterMark: 1 });

package/src/server.d.ts

@@ -61,7 +61,8 @@ type PublisherServerBaseOptions = {
 /** Trusted session resolution and the durable turn journal must be supplied together. */
 export type PublisherServerOptions = PublisherServerBaseOptions & (
   { sessionIdForRequest?: never; turnJournal?: never } |
-  { sessionIdForRequest: (request: Request) => string | null | Promise<string | null>;
+  { /** Resolve the current authenticated session for consent, placement and generation requests. */
+    sessionIdForRequest: (request: Request) => string | null | Promise<string | null>;
     turnJournal: PublisherTurnJournal }
 );
 export type GenerationLifecycleEvent = {

package/src/server.js

@@ -288,9 +288,10 @@ export function createPublisherServer(inputOptions) {
   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) });
+  let preferenceKeyPromise;
   async function preferenceKey() {
     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"]);
+    return preferenceKeyPromise ??= 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();
@@ -432,6 +433,13 @@ export function createPublisherServer(inputOptions) {
       !["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);
+    if (options.sessionIdForRequest) {
+      let sessionId;
+      try { sessionId = await journalCall(() => options.sessionIdForRequest(request)); }
+      catch { return response("publisher_session_unavailable", 503); }
+      if (!ID.test(sessionId || "")) return response("publisher_session_unavailable", 401);
+      if (input.session_id.trim() !== sessionId) return response("publisher_session_mismatch", 401);
+    }
     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); }

package/src/turn-journal.js

@@ -19,7 +19,6 @@ export function createPublisherTurnJournal({ storage, reportGeneration, keySecre
     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 { Promise.resolve(onDiagnostic?.(code)).catch(() => {}); } catch {} };
@@ -77,9 +76,7 @@ export function createPublisherTurnJournal({ storage, reportGeneration, keySecre
     });
   }
   function schedule(scope, key) {
-    const task = drain(scope, key).catch(() => diagnostic("turn_journal_unavailable"));
-    tasks.add(task);
-    void task.finally(() => tasks.delete(task));
+    void drain(scope, key).catch(() => diagnostic("turn_journal_unavailable"));
   }
   async function bind(turn, jobId) {
     if (!JOB_ID.test(jobId || "")) throw new Error("publisher_job_id_invalid");
@@ -125,15 +122,20 @@ export function createPublisherTurnJournal({ storage, reportGeneration, keySecre
   }
   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++;
+      else 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);
+      try {
+        const next = await lease(scope, key);
+        if (!next) return;
+        try { await reportGeneration(next.jobId, next.event); accepted = true; }
+        catch { diagnostic("generation_report_unavailable"); }
+        await ack(scope, key, next.event, next.leaseId, accepted);
+      } finally {
+        const waiter = reportWaiters.shift();
+        if (waiter) waiter();
+        else activeReports--;
+      }
       if (!accepted) return;
     }
   }

package/templates/NEXT-SETUP.md

@@ -1,5 +1,7 @@
 # Connect wavebird to this Next.js app
 
+Use a supported Node.js LTS release with current security updates. Node.js 20 remains the technical minimum, but is no longer maintained.
+
 If your app sets Content Security Policy, merge `https://api.wavebird.ai` into `script-src`, `frame-src` and `connect-src`. Preserve nonces and existing protections. Do not disable CSP or allow wildcard origins. Keep secret Server ENV outside source downloads, Git and browser bundles.
 
 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.
@@ -14,3 +16,5 @@ Install `server-only` in your app (`npm install server-only`). Install `pg` too
 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.
+
+Your response consumer must stop UI updates when the same abort signal is canceled and resolve only after the result is visible. Call `lifecycle.onPresented()` when the result is presented. Superseded or stopped generations reject with `generation_aborted`. Set pool acquisition, query and lock timeouts on your existing database pool. If idle periods require pending-report recovery, call `turnJournal.reconcilePending(projectId, surfaceId)` from your existing server maintenance job.