@wavebirdai/api 0.1.0-beta.10 → 0.1.0-beta.12

package/README.md

@@ -9,7 +9,7 @@ You need a saved Wavebird Test project and placement in Dashboard, a Server Test
 1. Install the package and generate the route files for your app directory:
 
    ```sh
-   npm install @wavebirdai/api@0.1.0-beta.10
+   npm install @wavebirdai/api@0.1.0-beta.12
    ./node_modules/.bin/wavebird-next init --lang ts --root . --app-dir src/app
    ```
 
@@ -85,7 +85,7 @@ With `sessionIdForRequest` and `turnJournal` configured, the package validates t
 
 Call `reportGeneration` only from trusted server code with a job ID returned by an authorized placement. Its events are `started`, `finished`, and `failed`. The server key scopes the request at wavebird; invalid IDs or events are rejected locally, and each report has a five-second deadline and a parallel request limit. Reporting errors reject the returned promise so the caller can handle them outside the model response path.
 
-`@wavebirdai/api/browser` exports the existing tested `createPublisherAds` and `connectPublisherGeneration` lifecycle helper. It loads the hosted renderer and attaches only to a reserved container selected by the publisher. Initialize it with the current app user and conversation IDs; pass optional same-origin `placementEndpoint` and `consentEndpoint` paths when using the server routes in this package. The helper forwards those paths to the hosted renderer. Keep the Server Key and preference signing secret in the server configuration; never pass them as browser options. Use the real wavebird consent dialog or the publisher's actual CMP. Consent on an idle page does not request an ad. For `during`, the helper displays only during an active generation. Its generation request and response stream run without waiting for consent synchronization, the ad response, or renderer readiness. It clears late responses on completion, error, abort, conversation change, GPC, or withdrawal.
+`@wavebirdai/api/browser` exports the existing tested `createPublisherAds` and `connectPublisherGeneration` lifecycle helper. Pass the mount's `ads` instance as the fourth `connectPublisherGeneration` argument when more than one surface can run; the original three-argument global lookup remains for older integrations. It loads the hosted renderer and attaches only to a reserved container selected by the publisher. Initialize it with the current app user and conversation IDs; pass optional same-origin `placementEndpoint` and `consentEndpoint` paths when using the server routes in this package. The helper forwards those paths to the hosted renderer. Keep the Server Key and preference signing secret in the server configuration; never pass them as browser options. Use the real wavebird consent dialog or the publisher's actual CMP. Consent on an idle page does not request an ad. For `during`, the helper displays only during an active generation. Its generation request and response stream run without waiting for consent synchronization, the ad response, or renderer readiness. It clears late responses on completion, error, abort, conversation change, GPC, or withdrawal.
 
 For `after`, resolve the generation consumer only after your app presents the result. The browser helper waits for both the transport finish and that consumer before starting the placement. If presentation fails, reject the consumer so the placement does not start.
 

package/dist/browser.d.ts

@@ -1,31 +1,42 @@
 /** Resolve after the publisher has presented the result; After timing starts then. */
-export type GenerationConsumer<T> = (response: Response, lifecycle: { onDelta(): void }) => T | Promise<T>;
-export type PublisherAds = {
+export type GenerationConsumer<T> = (response: Response, lifecycle: {
+  /** Streaming output progress. For Before and During Image, call after the first result is presented. */
+  onDelta(): void;
+  /** Explicitly mark the result as presented. Idempotent and bound to this generation. */
+  onPresented(): void;
+}) => T | Promise<T>;
+export type PublisherAds<Bound extends boolean = boolean> = {
   ready: Promise<void>;
   connectGeneration<T>(options: { request: (headers: Record<string, string>) => Response | Promise<Response>; consume: GenerationConsumer<T>; signal?: AbortSignal }): Promise<T>;
-  setConversation(binding: { userId: string; conversationId: string; sessionId?: string }): void;
+  setConversation(binding: Bound extends true
+    ? { userId: string; conversationId: string; sessionId: string }
+    : { userId: string; conversationId: string; sessionId?: string }): void;
   dispose(): void;
   openPrivacySettings(): void;
   grant(choice?: unknown): Promise<unknown>;
   deny(): Promise<unknown>;
   withdraw(): Promise<unknown>;
 };
-export function createPublisherAds(options: {
+type PublisherAdsOptionsBase = {
   target: HTMLElement;
   clientId: string;
   surfaceId: string;
   jobType: "chat" | "code" | "image" | "voice" | "agent";
   userId: string;
   conversationId: string;
-  /** Opt-in successor contract: a session ID supplied by the host's authenticated context. */
-  sessionId?: string;
-  turnBinding?: boolean;
   timing?: "before" | "during" | "after";
   consentMode?: "wavebird_consent" | "own_cmp";
+  /** Optional official renderer URL. Only https://api.wavebird.ai/v1/render.js is supported. */
   rendererUrl?: string;
   privacySettingsTarget?: string;
   getFormat?: () => "banner" | "native" | "clip" | "auto";
   placementEndpoint?: string;
   consentEndpoint?: string;
-}): PublisherAds;
-export function connectPublisherGeneration<T>(url: string, init: RequestInit, consume: GenerationConsumer<T>): Promise<T>;
+};
+export function createPublisherAds(options: PublisherAdsOptionsBase &
+  { turnBinding?: false; sessionId?: string }): PublisherAds<false>;
+/** Opt-in successor: a trusted host session is required at mount and at each conversation change. */
+export function createPublisherAds(options: PublisherAdsOptionsBase &
+  { turnBinding: true; sessionId: string }): PublisherAds<true>;
+/** Pass the mount's ads instance to keep concurrent surfaces bound to their own generation. */
+export function connectPublisherGeneration<T>(url: string, init: RequestInit, consume: GenerationConsumer<T>, ads?: PublisherAds): Promise<T>;

package/dist/browser.js

@@ -21,19 +21,44 @@ function loadRenderer(url) {
 export function createPublisherAds(options) {
   const target = options.target;
   const requiredText = value => typeof value === "string" && value.trim().length > 0;
-  if (!target || !requiredText(options.userId) || !requiredText(options.conversationId))
+  if (!target || typeof target.append !== "function" || !requiredText(options.userId) || !requiredText(options.conversationId))
     throw new Error("Application container and session are required");
   if (!["chat", "code", "image", "voice", "agent"].includes(options.jobType)) throw new Error("publisher_job_invalid");
   if (typeof options.clientId !== "string" || !options.clientId.startsWith("wbproj_"))
     throw new Error("publisher_project_invalid");
   if (typeof options.surfaceId !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(options.surfaceId))
     throw new Error("publisher_placement_invalid");
+  if (options.turnBinding !== undefined && typeof options.turnBinding !== "boolean")
+    throw new Error("publisher_turn_binding_invalid");
   const turnBinding = options.turnBinding === true;
   const validId = value => typeof value === "string" && /^[A-Za-z0-9_-]{1,128}$/.test(value);
   if (turnBinding && !validId(options.sessionId)) throw new Error("publisher_trusted_session_required");
   const timing = options.timing === undefined ? "during" : options.timing;
   const consentMode = options.consentMode === undefined ? "wavebird_consent" : options.consentMode;
   if (!["before", "during", "after"].includes(timing) || !["wavebird_consent", "own_cmp"].includes(consentMode)) throw new Error("Invalid publisher configuration");
+  const validEndpoint = value => {
+    if (typeof value !== "string" || !value || value.trim() !== value) return false;
+    try {
+      const base = new URL(window.location?.href ?? "https://publisher.invalid/");
+      const endpoint = new URL(value, base);
+      return ["http:", "https:"].includes(endpoint.protocol) && endpoint.origin === base.origin &&
+        !endpoint.username && !endpoint.password && !endpoint.hash;
+    } catch { return false; }
+  };
+  if ((options.placementEndpoint !== undefined && !validEndpoint(options.placementEndpoint)) ||
+      (options.consentEndpoint !== undefined && !validEndpoint(options.consentEndpoint)))
+    throw new Error("publisher_endpoint_invalid");
+  const rendererUrl = options.rendererUrl === undefined ? "https://api.wavebird.ai/v1/render.js" : options.rendererUrl;
+  if (rendererUrl !== "https://api.wavebird.ai/v1/render.js") throw new Error("publisher_renderer_url_invalid");
+  if (options.getFormat !== undefined && typeof options.getFormat !== "function")
+    throw new Error("publisher_format_hook_invalid");
+  let privacyTarget = null;
+  if (consentMode === "wavebird_consent" && options.privacySettingsTarget !== undefined) {
+    if (typeof options.privacySettingsTarget !== "string" || !options.privacySettingsTarget.trim())
+      throw new Error("publisher_privacy_target_invalid");
+    try { privacyTarget = document.querySelector(options.privacySettingsTarget); }
+    catch { throw new Error("publisher_privacy_target_invalid"); }
+  }
   let binding = { userId: options.userId, conversationId: options.conversationId,
     sessionId: turnBinding ? options.sessionId : crypto.randomUUID() };
   let sponsor = null, disposed = false, context = 0, active = null;
@@ -41,8 +66,6 @@ export function createPublisherAds(options) {
   slot.setAttribute("aria-label", "Sponsored placement");
   slot.style.cssText = "width:100%;height:100%;overflow:hidden;margin:0 auto";
   target.append(slot);
-  const privacyTarget = consentMode === "wavebird_consent" && options.privacySettingsTarget
-    ? document.querySelector(options.privacySettingsTarget) : null;
   const openPrivacySettings = () => { if (!disposed) sponsor?.openPrivacySettings(); };
   privacyTarget?.addEventListener("click", openPrivacySettings);
   const notify = (method, id) => {
@@ -52,6 +75,10 @@ export function createPublisherAds(options) {
       sponsor = null; slot.hidden = true; slot.replaceChildren();
     }
   };
+  const notifyPresented = id => {
+    // Additive bridge: an already deployed renderer may predate this event.
+    if (typeof sponsor?.onPresented === "function") notify("onPresented", id);
+  };
   const current = job => !disposed && !job.cancelled && job.context === context && active === job;
   const event = (job, type) => {
     if (!current(job)) return;
@@ -61,9 +88,15 @@ export function createPublisherAds(options) {
     } else if (type === "progress") {
       if (job.state === "started") { job.progressed = true; notify("onDelta", job.id); }
     } else if (type === "no_result") {
-      if (job.state === "started") job.state = "no_result";
-    } else if (["done", "error", "abort"].includes(type)) {
       if (job.state !== "started") return;
+      job.state = "no_result";
+      if (timing !== "after") notify("onError", job.id);
+    } else if (type === "presented") {
+      if (!["started", "done"].includes(job.state) || job.presented) return;
+      job.presented = true; notifyPresented(job.id);
+    } else if (["done", "error", "abort"].includes(type)) {
+      if (job.state !== "started" &&
+          !(job.state === "done" && !job.consumed && ["error", "abort"].includes(type))) return;
       job.state = type;
       notify(type === "done" ? "onDone" : type === "abort" ? "onAbort" : "onError", job.id);
     }
@@ -92,10 +125,10 @@ export function createPublisherAds(options) {
     window.removeEventListener("pagehide", dispose);
   }
   window.addEventListener("pagehide", dispose);
-  const ready = loadRenderer(options.rendererUrl || "https://api.wavebird.ai/v1/render.js").then(() => {
+  const ready = loadRenderer(rendererUrl).then(() => {
     if (disposed) return;
     sponsor = window.wavebird.createChatSponsor({ target: slot, ...binding,
-      clientId: options.clientId, surfaceId: options.surfaceId, timing, consentMode,
+      clientId: options.clientId, surfaceId: options.surfaceId, jobType: options.jobType, timing, consentMode,
       cleanupAfterClip: true,
       ...(turnBinding ? { turnBinding: true } : {}),
       ...(options.getFormat === undefined ? {} : { getFormat: options.getFormat }),
@@ -113,7 +146,8 @@ export function createPublisherAds(options) {
   }).catch(() => {});
 
   async function connectGeneration({ request, consume, signal }) {
-    const job = { id: crypto.randomUUID(), sessionId: binding.sessionId, context, state: "pending", cancelled: false };
+    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 = "";
@@ -123,8 +157,14 @@ export function createPublisherAds(options) {
     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);
-      if (response.headers.get("x-wavebird-generation-transport") !== "1") return await consume(response);
+      if (!current(job)) throw new Error("generation_aborted");
+      if (response.headers.get("x-wavebird-generation-transport") !== "1") {
+        const result = await consume(response, { onDelta() {} });
+        if (!current(job)) throw new Error("generation_aborted");
+        return result;
+      }
       if (!response.body) throw new Error("generation_transport_missing");
       reader = response.body.getReader();
       async function nextRecord() {
@@ -161,12 +201,13 @@ export function createPublisherAds(options) {
                 if (typeof record.data !== "string" || record.data.length > 21848 || !/^[A-Za-z0-9+/]*={0,2}$/.test(record.data)) throw new Error("generation_bytes_invalid");
                 const raw = atob(record.data), bytes = Uint8Array.from(raw, value => value.charCodeAt(0));
                 controller.enqueue(bytes);
-                if (timing !== "before" && options.jobType !== "image") event(job, "progress");
+                if (bytes.length && timing !== "before" && options.jobType !== "image") event(job, "progress");
                 return;
               }
               if (["done", "error", "abort"].includes(record.type)) {
                 ended = true;
-                if (record.type !== "done" || timing !== "after") event(job, record.type);
+                if (record.type === "done" && [204, 205, 304].includes(metadata.status)) event(job, "no_result");
+                else if (record.type !== "done" || timing !== "after") event(job, record.type);
                 if (record.type === "done" || !metadata.status.toString().startsWith("2")) controller.close();
                 else controller.error(new Error("generation_" + record.type));
                 return;
@@ -181,14 +222,20 @@ export function createPublisherAds(options) {
         const record = await nextRecord();
         if (!["done", "error", "abort"].includes(record.type)) throw new Error("generation_transport_invalid");
         ended = true;
-        if (record.type !== "done" || timing !== "after") event(job, record.type);
+        if (record.type === "done") event(job, "no_result");
+        else event(job, record.type);
       }
       const noBody = [204, 205, 304].includes(metadata.status);
       const primary = new Response(noBody ? null : output, {
         status: metadata.status, statusText: metadata.status_text || "", headers: metadata.headers
       });
-      const result = await consume(primary, { onDelta: () => event(job, "progress") });
-      if (timing === "after" && ended) event(job, noBody ? "no_result" : "done");
+      const result = await consume(primary, { onDelta: () => {
+        event(job, "progress");
+        if (timing === "before" || (timing === "during" && options.jobType === "image")) event(job, "presented");
+      }, onPresented: () => event(job, "presented") });
+      job.consumed = true;
+      if (timing === "before" || (timing === "during" && options.jobType === "image")) event(job, "presented");
+      if (timing === "after" && ended && !noBody) event(job, "done");
       return result;
     } catch (error) {
       event(job, signal?.aborted ? "abort" : "error");
@@ -205,8 +252,7 @@ export function createPublisherAds(options) {
     withdraw: () => sponsor ? sponsor.withdraw() : Promise.resolve({ status: "renderer_unavailable" }) };
 }
 
-export async function connectPublisherGeneration(url, init, consume) {
-  const ads = window.publisherAds;
+export async function connectPublisherGeneration(url, init, consume, ads = window.publisherAds) {
   if (!ads) return consume(await fetch(url, init), { onDelta() {} });
   return ads.connectGeneration({
     signal: init.signal ?? undefined,

package/dist/server.d.ts

@@ -30,15 +30,12 @@ export function createPublisherTurnJournal(options: {
 }): PublisherTurnJournal;
 /** Derive a stable, domain-separated journal key from the existing server-only preference secret. */
 export function derivePublisherTurnKeySecret(preferenceSecret: string): string;
-export type PublisherServerOptions = {
+type PublisherServerBaseOptions = {
   apiBaseUrl?: string;
   clientId: string;
   secretKey: string;
   preferenceSecret: string;
   authorize: (request: Request) => boolean | Promise<boolean>;
-  /** Opt-in successor: derive the exact browser session from the host's authenticated request. */
-  sessionIdForRequest?: (request: Request) => string | null | Promise<string | null>;
-  turnJournal?: PublisherTurnJournal;
   onDiagnostic?: (code: string) => void;
   publicOrigins: string[];
   surfaceId: string;
@@ -47,7 +44,7 @@ export type PublisherServerOptions = {
   locale: string;
   timing: "before" | "during" | "after";
   consentMode: "wavebird_consent" | "own_cmp";
-  gdprApplies: boolean;
+  gdprApplies?: boolean;
   publisher: { app_name: string; app_domain: string; categories: string[] };
   allowedFormats: Array<"banner" | "native" | "clip">;
   positionHint: "above" | "below" | "sidebar" | "between";
@@ -60,6 +57,12 @@ export type PublisherServerOptions = {
   bidfloorCurrency?: string;
   blockedCategories?: string[];
 };
+/** 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>;
+    turnJournal: PublisherTurnJournal }
+);
 export type GenerationLifecycleEvent = {
   type: "started" | "done" | "error" | "abort";
   sessionId: string;

package/dist/server.js

@@ -28,6 +28,8 @@ function normalizeOptions(options) {
   if (typeof document !== "undefined") throw new Error("publisher_server_only");
   if (options && Object.keys(options).some(key => !SERVER_OPTION_KEYS.has(key))) throw new Error("publisher_option_unknown");
   if (!options || typeof options.authorize !== "function") throw new Error("publisher_authorize_required");
+  if (options.onDiagnostic !== undefined && typeof options.onDiagnostic !== "function")
+    throw new Error("publisher_diagnostic_invalid");
   if (typeof options.preferenceSecret !== "string" || new TextEncoder().encode(options.preferenceSecret).byteLength < 32) throw new Error("preference_secret_required");
   if ((options.turnJournal === undefined) !== (options.sessionIdForRequest === undefined) ||
       (options.turnJournal !== undefined && (typeof options.sessionIdForRequest !== "function" ||

package/dist/turn-journal.js

@@ -17,6 +17,8 @@ export function createPublisherTurnJournal({ storage, reportGeneration, keySecre
       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 = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wavebirdai/api",
-  "version": "0.1.0-beta.10",
+  "version": "0.1.0-beta.12",
   "private": false,
   "type": "module",
   "description": "Integrate Banner, Native, and Clip placements into authenticated chat apps with server-side keys, consent, and generation lifecycle handling",

package/src/browser.d.ts

@@ -1,31 +1,42 @@
 /** Resolve after the publisher has presented the result; After timing starts then. */
-export type GenerationConsumer<T> = (response: Response, lifecycle: { onDelta(): void }) => T | Promise<T>;
-export type PublisherAds = {
+export type GenerationConsumer<T> = (response: Response, lifecycle: {
+  /** Streaming output progress. For Before and During Image, call after the first result is presented. */
+  onDelta(): void;
+  /** Explicitly mark the result as presented. Idempotent and bound to this generation. */
+  onPresented(): void;
+}) => T | Promise<T>;
+export type PublisherAds<Bound extends boolean = boolean> = {
   ready: Promise<void>;
   connectGeneration<T>(options: { request: (headers: Record<string, string>) => Response | Promise<Response>; consume: GenerationConsumer<T>; signal?: AbortSignal }): Promise<T>;
-  setConversation(binding: { userId: string; conversationId: string; sessionId?: string }): void;
+  setConversation(binding: Bound extends true
+    ? { userId: string; conversationId: string; sessionId: string }
+    : { userId: string; conversationId: string; sessionId?: string }): void;
   dispose(): void;
   openPrivacySettings(): void;
   grant(choice?: unknown): Promise<unknown>;
   deny(): Promise<unknown>;
   withdraw(): Promise<unknown>;
 };
-export function createPublisherAds(options: {
+type PublisherAdsOptionsBase = {
   target: HTMLElement;
   clientId: string;
   surfaceId: string;
   jobType: "chat" | "code" | "image" | "voice" | "agent";
   userId: string;
   conversationId: string;
-  /** Opt-in successor contract: a session ID supplied by the host's authenticated context. */
-  sessionId?: string;
-  turnBinding?: boolean;
   timing?: "before" | "during" | "after";
   consentMode?: "wavebird_consent" | "own_cmp";
+  /** Optional official renderer URL. Only https://api.wavebird.ai/v1/render.js is supported. */
   rendererUrl?: string;
   privacySettingsTarget?: string;
   getFormat?: () => "banner" | "native" | "clip" | "auto";
   placementEndpoint?: string;
   consentEndpoint?: string;
-}): PublisherAds;
-export function connectPublisherGeneration<T>(url: string, init: RequestInit, consume: GenerationConsumer<T>): Promise<T>;
+};
+export function createPublisherAds(options: PublisherAdsOptionsBase &
+  { turnBinding?: false; sessionId?: string }): PublisherAds<false>;
+/** Opt-in successor: a trusted host session is required at mount and at each conversation change. */
+export function createPublisherAds(options: PublisherAdsOptionsBase &
+  { turnBinding: true; sessionId: string }): PublisherAds<true>;
+/** Pass the mount's ads instance to keep concurrent surfaces bound to their own generation. */
+export function connectPublisherGeneration<T>(url: string, init: RequestInit, consume: GenerationConsumer<T>, ads?: PublisherAds): Promise<T>;

package/src/browser.js

@@ -21,19 +21,44 @@ function loadRenderer(url) {
 export function createPublisherAds(options) {
   const target = options.target;
   const requiredText = value => typeof value === "string" && value.trim().length > 0;
-  if (!target || !requiredText(options.userId) || !requiredText(options.conversationId))
+  if (!target || typeof target.append !== "function" || !requiredText(options.userId) || !requiredText(options.conversationId))
     throw new Error("Application container and session are required");
   if (!["chat", "code", "image", "voice", "agent"].includes(options.jobType)) throw new Error("publisher_job_invalid");
   if (typeof options.clientId !== "string" || !options.clientId.startsWith("wbproj_"))
     throw new Error("publisher_project_invalid");
   if (typeof options.surfaceId !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(options.surfaceId))
     throw new Error("publisher_placement_invalid");
+  if (options.turnBinding !== undefined && typeof options.turnBinding !== "boolean")
+    throw new Error("publisher_turn_binding_invalid");
   const turnBinding = options.turnBinding === true;
   const validId = value => typeof value === "string" && /^[A-Za-z0-9_-]{1,128}$/.test(value);
   if (turnBinding && !validId(options.sessionId)) throw new Error("publisher_trusted_session_required");
   const timing = options.timing === undefined ? "during" : options.timing;
   const consentMode = options.consentMode === undefined ? "wavebird_consent" : options.consentMode;
   if (!["before", "during", "after"].includes(timing) || !["wavebird_consent", "own_cmp"].includes(consentMode)) throw new Error("Invalid publisher configuration");
+  const validEndpoint = value => {
+    if (typeof value !== "string" || !value || value.trim() !== value) return false;
+    try {
+      const base = new URL(window.location?.href ?? "https://publisher.invalid/");
+      const endpoint = new URL(value, base);
+      return ["http:", "https:"].includes(endpoint.protocol) && endpoint.origin === base.origin &&
+        !endpoint.username && !endpoint.password && !endpoint.hash;
+    } catch { return false; }
+  };
+  if ((options.placementEndpoint !== undefined && !validEndpoint(options.placementEndpoint)) ||
+      (options.consentEndpoint !== undefined && !validEndpoint(options.consentEndpoint)))
+    throw new Error("publisher_endpoint_invalid");
+  const rendererUrl = options.rendererUrl === undefined ? "https://api.wavebird.ai/v1/render.js" : options.rendererUrl;
+  if (rendererUrl !== "https://api.wavebird.ai/v1/render.js") throw new Error("publisher_renderer_url_invalid");
+  if (options.getFormat !== undefined && typeof options.getFormat !== "function")
+    throw new Error("publisher_format_hook_invalid");
+  let privacyTarget = null;
+  if (consentMode === "wavebird_consent" && options.privacySettingsTarget !== undefined) {
+    if (typeof options.privacySettingsTarget !== "string" || !options.privacySettingsTarget.trim())
+      throw new Error("publisher_privacy_target_invalid");
+    try { privacyTarget = document.querySelector(options.privacySettingsTarget); }
+    catch { throw new Error("publisher_privacy_target_invalid"); }
+  }
   let binding = { userId: options.userId, conversationId: options.conversationId,
     sessionId: turnBinding ? options.sessionId : crypto.randomUUID() };
   let sponsor = null, disposed = false, context = 0, active = null;
@@ -41,8 +66,6 @@ export function createPublisherAds(options) {
   slot.setAttribute("aria-label", "Sponsored placement");
   slot.style.cssText = "width:100%;height:100%;overflow:hidden;margin:0 auto";
   target.append(slot);
-  const privacyTarget = consentMode === "wavebird_consent" && options.privacySettingsTarget
-    ? document.querySelector(options.privacySettingsTarget) : null;
   const openPrivacySettings = () => { if (!disposed) sponsor?.openPrivacySettings(); };
   privacyTarget?.addEventListener("click", openPrivacySettings);
   const notify = (method, id) => {
@@ -52,6 +75,10 @@ export function createPublisherAds(options) {
       sponsor = null; slot.hidden = true; slot.replaceChildren();
     }
   };
+  const notifyPresented = id => {
+    // Additive bridge: an already deployed renderer may predate this event.
+    if (typeof sponsor?.onPresented === "function") notify("onPresented", id);
+  };
   const current = job => !disposed && !job.cancelled && job.context === context && active === job;
   const event = (job, type) => {
     if (!current(job)) return;
@@ -61,9 +88,15 @@ export function createPublisherAds(options) {
     } else if (type === "progress") {
       if (job.state === "started") { job.progressed = true; notify("onDelta", job.id); }
     } else if (type === "no_result") {
-      if (job.state === "started") job.state = "no_result";
-    } else if (["done", "error", "abort"].includes(type)) {
       if (job.state !== "started") return;
+      job.state = "no_result";
+      if (timing !== "after") notify("onError", job.id);
+    } else if (type === "presented") {
+      if (!["started", "done"].includes(job.state) || job.presented) return;
+      job.presented = true; notifyPresented(job.id);
+    } else if (["done", "error", "abort"].includes(type)) {
+      if (job.state !== "started" &&
+          !(job.state === "done" && !job.consumed && ["error", "abort"].includes(type))) return;
       job.state = type;
       notify(type === "done" ? "onDone" : type === "abort" ? "onAbort" : "onError", job.id);
     }
@@ -92,10 +125,10 @@ export function createPublisherAds(options) {
     window.removeEventListener("pagehide", dispose);
   }
   window.addEventListener("pagehide", dispose);
-  const ready = loadRenderer(options.rendererUrl || "https://api.wavebird.ai/v1/render.js").then(() => {
+  const ready = loadRenderer(rendererUrl).then(() => {
     if (disposed) return;
     sponsor = window.wavebird.createChatSponsor({ target: slot, ...binding,
-      clientId: options.clientId, surfaceId: options.surfaceId, timing, consentMode,
+      clientId: options.clientId, surfaceId: options.surfaceId, jobType: options.jobType, timing, consentMode,
       cleanupAfterClip: true,
       ...(turnBinding ? { turnBinding: true } : {}),
       ...(options.getFormat === undefined ? {} : { getFormat: options.getFormat }),
@@ -113,7 +146,8 @@ export function createPublisherAds(options) {
   }).catch(() => {});
 
   async function connectGeneration({ request, consume, signal }) {
-    const job = { id: crypto.randomUUID(), sessionId: binding.sessionId, context, state: "pending", cancelled: false };
+    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 = "";
@@ -123,8 +157,14 @@ export function createPublisherAds(options) {
     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);
-      if (response.headers.get("x-wavebird-generation-transport") !== "1") return await consume(response);
+      if (!current(job)) throw new Error("generation_aborted");
+      if (response.headers.get("x-wavebird-generation-transport") !== "1") {
+        const result = await consume(response, { onDelta() {} });
+        if (!current(job)) throw new Error("generation_aborted");
+        return result;
+      }
       if (!response.body) throw new Error("generation_transport_missing");
       reader = response.body.getReader();
       async function nextRecord() {
@@ -161,12 +201,13 @@ export function createPublisherAds(options) {
                 if (typeof record.data !== "string" || record.data.length > 21848 || !/^[A-Za-z0-9+/]*={0,2}$/.test(record.data)) throw new Error("generation_bytes_invalid");
                 const raw = atob(record.data), bytes = Uint8Array.from(raw, value => value.charCodeAt(0));
                 controller.enqueue(bytes);
-                if (timing !== "before" && options.jobType !== "image") event(job, "progress");
+                if (bytes.length && timing !== "before" && options.jobType !== "image") event(job, "progress");
                 return;
               }
               if (["done", "error", "abort"].includes(record.type)) {
                 ended = true;
-                if (record.type !== "done" || timing !== "after") event(job, record.type);
+                if (record.type === "done" && [204, 205, 304].includes(metadata.status)) event(job, "no_result");
+                else if (record.type !== "done" || timing !== "after") event(job, record.type);
                 if (record.type === "done" || !metadata.status.toString().startsWith("2")) controller.close();
                 else controller.error(new Error("generation_" + record.type));
                 return;
@@ -181,14 +222,20 @@ export function createPublisherAds(options) {
         const record = await nextRecord();
         if (!["done", "error", "abort"].includes(record.type)) throw new Error("generation_transport_invalid");
         ended = true;
-        if (record.type !== "done" || timing !== "after") event(job, record.type);
+        if (record.type === "done") event(job, "no_result");
+        else event(job, record.type);
       }
       const noBody = [204, 205, 304].includes(metadata.status);
       const primary = new Response(noBody ? null : output, {
         status: metadata.status, statusText: metadata.status_text || "", headers: metadata.headers
       });
-      const result = await consume(primary, { onDelta: () => event(job, "progress") });
-      if (timing === "after" && ended) event(job, noBody ? "no_result" : "done");
+      const result = await consume(primary, { onDelta: () => {
+        event(job, "progress");
+        if (timing === "before" || (timing === "during" && options.jobType === "image")) event(job, "presented");
+      }, onPresented: () => event(job, "presented") });
+      job.consumed = true;
+      if (timing === "before" || (timing === "during" && options.jobType === "image")) event(job, "presented");
+      if (timing === "after" && ended && !noBody) event(job, "done");
       return result;
     } catch (error) {
       event(job, signal?.aborted ? "abort" : "error");
@@ -205,8 +252,7 @@ export function createPublisherAds(options) {
     withdraw: () => sponsor ? sponsor.withdraw() : Promise.resolve({ status: "renderer_unavailable" }) };
 }
 
-export async function connectPublisherGeneration(url, init, consume) {
-  const ads = window.publisherAds;
+export async function connectPublisherGeneration(url, init, consume, ads = window.publisherAds) {
   if (!ads) return consume(await fetch(url, init), { onDelta() {} });
   return ads.connectGeneration({
     signal: init.signal ?? undefined,

package/src/server.d.ts

@@ -30,15 +30,12 @@ export function createPublisherTurnJournal(options: {
 }): PublisherTurnJournal;
 /** Derive a stable, domain-separated journal key from the existing server-only preference secret. */
 export function derivePublisherTurnKeySecret(preferenceSecret: string): string;
-export type PublisherServerOptions = {
+type PublisherServerBaseOptions = {
   apiBaseUrl?: string;
   clientId: string;
   secretKey: string;
   preferenceSecret: string;
   authorize: (request: Request) => boolean | Promise<boolean>;
-  /** Opt-in successor: derive the exact browser session from the host's authenticated request. */
-  sessionIdForRequest?: (request: Request) => string | null | Promise<string | null>;
-  turnJournal?: PublisherTurnJournal;
   onDiagnostic?: (code: string) => void;
   publicOrigins: string[];
   surfaceId: string;
@@ -47,7 +44,7 @@ export type PublisherServerOptions = {
   locale: string;
   timing: "before" | "during" | "after";
   consentMode: "wavebird_consent" | "own_cmp";
-  gdprApplies: boolean;
+  gdprApplies?: boolean;
   publisher: { app_name: string; app_domain: string; categories: string[] };
   allowedFormats: Array<"banner" | "native" | "clip">;
   positionHint: "above" | "below" | "sidebar" | "between";
@@ -60,6 +57,12 @@ export type PublisherServerOptions = {
   bidfloorCurrency?: string;
   blockedCategories?: string[];
 };
+/** 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>;
+    turnJournal: PublisherTurnJournal }
+);
 export type GenerationLifecycleEvent = {
   type: "started" | "done" | "error" | "abort";
   sessionId: string;

package/src/server.js

@@ -28,6 +28,8 @@ function normalizeOptions(options) {
   if (typeof document !== "undefined") throw new Error("publisher_server_only");
   if (options && Object.keys(options).some(key => !SERVER_OPTION_KEYS.has(key))) throw new Error("publisher_option_unknown");
   if (!options || typeof options.authorize !== "function") throw new Error("publisher_authorize_required");
+  if (options.onDiagnostic !== undefined && typeof options.onDiagnostic !== "function")
+    throw new Error("publisher_diagnostic_invalid");
   if (typeof options.preferenceSecret !== "string" || new TextEncoder().encode(options.preferenceSecret).byteLength < 32) throw new Error("preference_secret_required");
   if ((options.turnJournal === undefined) !== (options.sessionIdForRequest === undefined) ||
       (options.turnJournal !== undefined && (typeof options.sessionIdForRequest !== "function" ||

package/src/turn-journal.js

@@ -17,6 +17,8 @@ export function createPublisherTurnJournal({ storage, reportGeneration, keySecre
       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 = [];