@wavebirdai/api 0.1.0-beta.15 → 0.1.0-beta.16

package/README.md

@@ -22,11 +22,11 @@ Use Node.js 20 or later on your server.
 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.15
+   npm install @wavebirdai/api@0.1.0-beta.16
    ```
 
 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. Keep the saved formats, sizes and timing.
+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](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.

package/bin/wavebird-next.mjs

@@ -46,7 +46,7 @@ export async function plan(argv) {
   ];
   for (const [source, dest] of files) {
     await access(source, constants.R_OK);
-    try { await access(dest); throw new Error(`Refusing to overwrite ${dest}`); }
+    try { await access(dest); throw new Error(`Refusing to overwrite ${dest}. Keep the existing file. Copy the matching connection hooks from Dashboard Overview into your app. See https://wavebird.ai/api/quickstart#backend`); }
     catch (error) { if (error.code !== "ENOENT") throw error; }
   }
   return { lang, projectRoot, appDir, files };

package/dist/browser.d.ts

@@ -30,6 +30,8 @@ type PublisherAdsOptionsBase = {
   rendererUrl?: string;
   privacySettingsTarget?: string;
   getFormat?: () => "banner" | "native" | "clip" | "auto";
+  /** Fixed diagnostic codes only. Exceptions in this callback never interrupt the model. */
+  onDiagnostic?: (event: { code: "renderer_csp_blocked" | "renderer_unavailable" | "renderer_frame_unavailable" }) => void;
   placementEndpoint?: string;
   consentEndpoint?: string;
 };

package/dist/browser.js

@@ -52,6 +52,8 @@ export function createPublisherAds(options) {
   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");
+  if (options.onDiagnostic !== undefined && typeof options.onDiagnostic !== "function")
+    throw new Error("publisher_diagnostic_hook_invalid");
   let privacyTarget = null;
   if (consentMode === "wavebird_consent" && options.privacySettingsTarget !== undefined) {
     if (typeof options.privacySettingsTarget !== "string" || !options.privacySettingsTarget.trim())
@@ -62,7 +64,21 @@ export function createPublisherAds(options) {
   let binding = { userId: options.userId, conversationId: options.conversationId,
     sessionId: turnBinding ? options.sessionId : crypto.randomUUID() };
   let sponsor = null, disposed = false, context = 0, active = null;
+  const diagnostic = code => {
+    if (!disposed) { try { Promise.resolve(options.onDiagnostic?.({ code })).catch(() => {}); } catch {} }
+  };
+  const onPolicyViolation = event => {
+    if (event.disposition !== "enforce" ||
+        !["script-src", "script-src-elem", "frame-src", "connect-src"].includes(event.effectiveDirective)) return;
+    try {
+      if (new URL(event.blockedURI).origin === "https://api.wavebird.ai") diagnostic("renderer_csp_blocked");
+    } catch {}
+  };
+  document.addEventListener?.("securitypolicyviolation", onPolicyViolation);
   const slot = document.createElement("section");
+  const onRenderFailure = () => diagnostic("renderer_frame_unavailable");
+  // Renderer failures originate in a child mount and do not bubble.
+  slot.addEventListener?.("ad:render_failed", onRenderFailure, true);
   slot.setAttribute("aria-label", "Sponsored placement");
   slot.style.cssText = "width:100%;height:100%;overflow:hidden;margin:0 auto";
   target.append(slot);
@@ -121,8 +137,10 @@ export function createPublisherAds(options) {
     if (active) event(active, "abort");
     disposed = true; context++; active = null;
     sponsor?.dispose(); sponsor = null; slot.remove();
+    slot.removeEventListener?.("ad:render_failed", onRenderFailure, true);
     privacyTarget?.removeEventListener("click", openPrivacySettings);
     window.removeEventListener("pagehide", dispose);
+    document.removeEventListener?.("securitypolicyviolation", onPolicyViolation);
   }
   window.addEventListener("pagehide", dispose);
   const ready = loadRenderer(rendererUrl).then(() => {
@@ -143,7 +161,7 @@ export function createPublisherAds(options) {
         notify("onStarted", active.id); notify("onDone", active.id);
       }
     }
-  }).catch(() => {});
+  }).catch(() => { diagnostic("renderer_unavailable"); });
 
   async function connectGeneration({ request, consume, signal }) {
     const job = { id: crypto.randomUUID(), sessionId: binding.sessionId, context, state: "pending", cancelled: false,

package/dist/server.d.ts

@@ -47,7 +47,8 @@ type PublisherServerBaseOptions = {
   gdprApplies?: boolean;
   publisher: { app_name: string; app_domain: string; categories: string[] };
   allowedFormats: Array<"banner" | "native" | "clip">;
-  positionHint: "above" | "below" | "sidebar" | "between";
+  /** Omit to inherit the project's saved position. Must match your physical layout when supplied. */
+  positionHint?: "above" | "below" | "sidebar" | "between";
   /** Optional advanced caps; saved allowedSizes determine the normal envelope. */
   maxWidth?: number;
   maxHeight?: number;

package/dist/server.js

@@ -44,7 +44,7 @@ function normalizeOptions(options) {
   if (!["wavebird_consent", "own_cmp"].includes(options.consentMode)) throw new Error("publisher_consent_mode_invalid");
   if (options.gdprApplies !== undefined && typeof options.gdprApplies !== "boolean") throw new Error("publisher_gdpr_invalid");
   if (!Array.isArray(options.allowedFormats) || options.allowedFormats.length === 0 || options.allowedFormats.some(value => !["banner", "native", "clip"].includes(value))) throw new Error("publisher_formats_invalid");
-  if (!["above", "below", "sidebar", "between"].includes(options.positionHint)) throw new Error("publisher_position_invalid");
+  if (options.positionHint !== undefined && !["above", "below", "sidebar", "between"].includes(options.positionHint)) throw new Error("publisher_position_invalid");
   if (!Array.isArray(options.allowedSizes) || options.allowedSizes.length === 0 || options.allowedSizes.length > MAX_ALLOWED_SIZES || options.allowedSizes.some(size => !size || typeof size !== "object" || Object.keys(size).some(key => !["width", "height", "formats"].includes(key)) || !Number.isSafeInteger(size.width) || !Number.isSafeInteger(size.height) || size.width < 1 || size.height < 1 || size.width > MAX_SIZE_EDGE || size.height > MAX_SIZE_EDGE ||
     (size.formats !== undefined && (!Array.isArray(size.formats) || size.formats.length === 0 || size.formats.some(format => !options.allowedFormats.includes(format)))))) throw new Error("publisher_sizes_invalid");
   if (new Set(options.allowedSizes.map(size => `${size.width}x${size.height}`)).size !== options.allowedSizes.length)
@@ -256,7 +256,7 @@ export function createPublisherServer(inputOptions) {
   const placementFetch = boundedFetcher();
   const consentFetch = boundedFetcher();
   const generationReportFetch = boundedGenerationReporter();
-  const diagnostic = code => { try { options.onDiagnostic?.(code); } catch {} };
+  const diagnostic = code => { try { Promise.resolve(options.onDiagnostic?.(code)).catch(() => {}); } catch {} };
   if (typeof options.turnJournal?.reconcilePending === "function") {
     void Promise.resolve().then(() => options.turnJournal.reconcilePending(options.clientId, options.surfaceId))
       .catch(() => diagnostic("turn_journal_unavailable"));

package/dist/turn-journal.js

@@ -22,7 +22,7 @@ export function createPublisherTurnJournal({ storage, reportGeneration, keySecre
   const tasks = new Set();
   let activeReports = 0;
   const reportWaiters = [];
-  const diagnostic = code => { try { onDiagnostic?.(code); } catch {} };
+  const diagnostic = code => { try { Promise.resolve(onDiagnostic?.(code)).catch(() => {}); } 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");

package/docs/web/generation.md

@@ -1,6 +1,6 @@
 # Connect generation to the displayed result
 
-These are connection helpers, not complete apps. Use the same installed `@wavebirdai/api@0.1.0-beta.15` as your server routes.
+These are connection helpers, not complete apps. Use the same installed `@wavebirdai/api@0.1.0-beta.16` 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`.

package/docs/web/nextjs.md

@@ -4,10 +4,14 @@ Use this path instead of copying Dashboard's route files. It supports an existin
 
 ## 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.
+
+If your app sets Content Security Policy, allow `https://api.wavebird.ai` in its script, frame and connection rules. Update `script-src-elem` too if your policy uses it. Preserve existing nonces and protections. Do not use wildcards or disable CSP. The optional browser `onDiagnostic` callback reports `renderer_csp_blocked` only for an observed enforced violation, `renderer_unavailable` if loading fails, or `renderer_frame_unavailable` if the ad frame fails. Without a CSP event, the cause remains unknown. Diagnostics never include blocked URLs or credentials.
+
 From the folder containing `package.json`:
 
 ```sh
-npm install @wavebirdai/api@0.1.0-beta.15 server-only
+npm install @wavebirdai/api@0.1.0-beta.16 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.15`. [Start with the integration steps](../../README.md#set-up-javascript-or-typescript).
+Applies to `@wavebirdai/api@0.1.0-beta.16`. [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.
@@ -20,6 +20,16 @@ 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.
 
 
+## Placement and diagnosis
+
+Place the component where the ad belongs in your layout. Set `positionHint` to `above`, `below`, `sidebar` or `between` to describe that physical position. Omit it to use the project's saved position. The server still enforces formats, timing, maximum sizes, project ownership and consent.
+
+Allow the creative, disclosure and controls to determine the slot height. A fixed creative-only height can crop the ad. In a fixed-height chat, keep the composer separate and allow the ad area to scroll if its expanded information exceeds the available space. Empty or cleared slots should collapse.
+
+For renderer failures, the browser's optional `onDiagnostic` receives only a fixed `code`. `renderer_csp_blocked` requires an observed enforced policy violation. `renderer_unavailable` and `renderer_frame_unavailable` do not identify the cause. See the [CSP setup](nextjs.md#generate-files). Callback errors never interrupt model output.
+
+Use the existing `generationId` in the server `onLifecycle` observer to correlate generation events. It is not a credential. Retain only that ID, event category and relative timing, never session identities, request headers or response contents. A renderer error without an exact turn or slot link must stay uncorrelated.
+
 ## Troubleshooting
 
 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.
@@ -28,6 +38,7 @@ With the trusted-session integration, consent restoration reads the current serv
 - **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.
+- **Frequency limit:** limits apply to the supplied session. `frequency_cap_exceeded` is an actual cap denial. Test decision metadata identifies its policy and limit; an unknown reset time remains `null`. `frequency_session_required` means session data is missing. `frequency_service_unavailable`, `frequency_context_unavailable` and `frequency_configuration_invalid` are technical failures, not proof of repeated ad exposure.
 - **After ad arrives too early:** resolve the result consumer after the UI has presented the result, not merely after the last network byte.
 
 See [troubleshooting](https://wavebird.ai/api/troubleshooting) and [format behavior](https://wavebird.ai/api/concepts/ad-formats).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wavebirdai/api",
-  "version": "0.1.0-beta.15",
+  "version": "0.1.0-beta.16",
   "private": false,
   "type": "module",
   "description": "JavaScript and TypeScript integration for wavebird Banner, Native and Clip ads, with consent and generation lifecycle handling.",

package/src/browser.d.ts

@@ -30,6 +30,8 @@ type PublisherAdsOptionsBase = {
   rendererUrl?: string;
   privacySettingsTarget?: string;
   getFormat?: () => "banner" | "native" | "clip" | "auto";
+  /** Fixed diagnostic codes only. Exceptions in this callback never interrupt the model. */
+  onDiagnostic?: (event: { code: "renderer_csp_blocked" | "renderer_unavailable" | "renderer_frame_unavailable" }) => void;
   placementEndpoint?: string;
   consentEndpoint?: string;
 };

package/src/browser.js

@@ -52,6 +52,8 @@ export function createPublisherAds(options) {
   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");
+  if (options.onDiagnostic !== undefined && typeof options.onDiagnostic !== "function")
+    throw new Error("publisher_diagnostic_hook_invalid");
   let privacyTarget = null;
   if (consentMode === "wavebird_consent" && options.privacySettingsTarget !== undefined) {
     if (typeof options.privacySettingsTarget !== "string" || !options.privacySettingsTarget.trim())
@@ -62,7 +64,21 @@ export function createPublisherAds(options) {
   let binding = { userId: options.userId, conversationId: options.conversationId,
     sessionId: turnBinding ? options.sessionId : crypto.randomUUID() };
   let sponsor = null, disposed = false, context = 0, active = null;
+  const diagnostic = code => {
+    if (!disposed) { try { Promise.resolve(options.onDiagnostic?.({ code })).catch(() => {}); } catch {} }
+  };
+  const onPolicyViolation = event => {
+    if (event.disposition !== "enforce" ||
+        !["script-src", "script-src-elem", "frame-src", "connect-src"].includes(event.effectiveDirective)) return;
+    try {
+      if (new URL(event.blockedURI).origin === "https://api.wavebird.ai") diagnostic("renderer_csp_blocked");
+    } catch {}
+  };
+  document.addEventListener?.("securitypolicyviolation", onPolicyViolation);
   const slot = document.createElement("section");
+  const onRenderFailure = () => diagnostic("renderer_frame_unavailable");
+  // Renderer failures originate in a child mount and do not bubble.
+  slot.addEventListener?.("ad:render_failed", onRenderFailure, true);
   slot.setAttribute("aria-label", "Sponsored placement");
   slot.style.cssText = "width:100%;height:100%;overflow:hidden;margin:0 auto";
   target.append(slot);
@@ -121,8 +137,10 @@ export function createPublisherAds(options) {
     if (active) event(active, "abort");
     disposed = true; context++; active = null;
     sponsor?.dispose(); sponsor = null; slot.remove();
+    slot.removeEventListener?.("ad:render_failed", onRenderFailure, true);
     privacyTarget?.removeEventListener("click", openPrivacySettings);
     window.removeEventListener("pagehide", dispose);
+    document.removeEventListener?.("securitypolicyviolation", onPolicyViolation);
   }
   window.addEventListener("pagehide", dispose);
   const ready = loadRenderer(rendererUrl).then(() => {
@@ -143,7 +161,7 @@ export function createPublisherAds(options) {
         notify("onStarted", active.id); notify("onDone", active.id);
       }
     }
-  }).catch(() => {});
+  }).catch(() => { diagnostic("renderer_unavailable"); });
 
   async function connectGeneration({ request, consume, signal }) {
     const job = { id: crypto.randomUUID(), sessionId: binding.sessionId, context, state: "pending", cancelled: false,

package/src/server.d.ts

@@ -47,7 +47,8 @@ type PublisherServerBaseOptions = {
   gdprApplies?: boolean;
   publisher: { app_name: string; app_domain: string; categories: string[] };
   allowedFormats: Array<"banner" | "native" | "clip">;
-  positionHint: "above" | "below" | "sidebar" | "between";
+  /** Omit to inherit the project's saved position. Must match your physical layout when supplied. */
+  positionHint?: "above" | "below" | "sidebar" | "between";
   /** Optional advanced caps; saved allowedSizes determine the normal envelope. */
   maxWidth?: number;
   maxHeight?: number;

package/src/server.js

@@ -44,7 +44,7 @@ function normalizeOptions(options) {
   if (!["wavebird_consent", "own_cmp"].includes(options.consentMode)) throw new Error("publisher_consent_mode_invalid");
   if (options.gdprApplies !== undefined && typeof options.gdprApplies !== "boolean") throw new Error("publisher_gdpr_invalid");
   if (!Array.isArray(options.allowedFormats) || options.allowedFormats.length === 0 || options.allowedFormats.some(value => !["banner", "native", "clip"].includes(value))) throw new Error("publisher_formats_invalid");
-  if (!["above", "below", "sidebar", "between"].includes(options.positionHint)) throw new Error("publisher_position_invalid");
+  if (options.positionHint !== undefined && !["above", "below", "sidebar", "between"].includes(options.positionHint)) throw new Error("publisher_position_invalid");
   if (!Array.isArray(options.allowedSizes) || options.allowedSizes.length === 0 || options.allowedSizes.length > MAX_ALLOWED_SIZES || options.allowedSizes.some(size => !size || typeof size !== "object" || Object.keys(size).some(key => !["width", "height", "formats"].includes(key)) || !Number.isSafeInteger(size.width) || !Number.isSafeInteger(size.height) || size.width < 1 || size.height < 1 || size.width > MAX_SIZE_EDGE || size.height > MAX_SIZE_EDGE ||
     (size.formats !== undefined && (!Array.isArray(size.formats) || size.formats.length === 0 || size.formats.some(format => !options.allowedFormats.includes(format)))))) throw new Error("publisher_sizes_invalid");
   if (new Set(options.allowedSizes.map(size => `${size.width}x${size.height}`)).size !== options.allowedSizes.length)
@@ -256,7 +256,7 @@ export function createPublisherServer(inputOptions) {
   const placementFetch = boundedFetcher();
   const consentFetch = boundedFetcher();
   const generationReportFetch = boundedGenerationReporter();
-  const diagnostic = code => { try { options.onDiagnostic?.(code); } catch {} };
+  const diagnostic = code => { try { Promise.resolve(options.onDiagnostic?.(code)).catch(() => {}); } catch {} };
   if (typeof options.turnJournal?.reconcilePending === "function") {
     void Promise.resolve().then(() => options.turnJournal.reconcilePending(options.clientId, options.surfaceId))
       .catch(() => diagnostic("turn_journal_unavailable"));

package/src/turn-journal.js

@@ -22,7 +22,7 @@ export function createPublisherTurnJournal({ storage, reportGeneration, keySecre
   const tasks = new Set();
   let activeReports = 0;
   const reportWaiters = [];
-  const diagnostic = code => { try { onDiagnostic?.(code); } catch {} };
+  const diagnostic = code => { try { Promise.resolve(onDiagnostic?.(code)).catch(() => {}); } 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");

package/templates/NEXT-SETUP.md

@@ -1,5 +1,7 @@
 # Connect wavebird to this Next.js app
 
+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.
 
 Install `server-only` in your app (`npm install server-only`). Install `pg` too if you use the PostgreSQL adapter. Use the full Server ENV from Dashboard's Integration step 2, including the saved preference secret and origins. A key-only ENV download is not the full configuration. Keep the preference secret unchanged across restarts.