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

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+## 0.1.0-beta.18
+
+- Prevent fractional clipping of the hosted ad frame at some device scales.
+- Correct the consent language guidance: browser preference comes first, then the publisher fallback.
+
+## 0.1.0-beta.17
+
+- Optional `consentLocale` and `consentTheme` browser settings for the hosted consent dialog.
+- Validate presentation settings before passing them to the renderer. Consent decisions, authorization and storage behavior are unchanged.
+- Updated installation instructions and consent appearance reference.
+
+## 0.1.0-beta.16
+
+- Fixed diagnostic categories for renderer and observed CSP failures, without signed URLs or credentials.
+- Optional placement positioning within the server-authorized formats, timing and size limits.
+- Contain synchronous and asynchronous diagnostic callback failures.
+- Expanded guidance for CSP, existing apps, session limits and separate secret ENV downloads.
+
+## 0.1.0-beta.15
+
+- Restore consent using the authoritative session revision after reload.
+
+## 0.1.0-beta.14
+
+- Reject wildcard origins during server configuration.
+- Clarify complete Server ENV, required dependencies and integration into existing apps.
+
+## 0.1.0-beta.13
+
+- Shorter setup instructions with links to the API docs and Dashboard.
+- Separate JavaScript, TypeScript and Python guides.
+- Generation examples that preserve the app's request, response display and cancellation.
+- Updated package description, documentation link and search keywords.
+
+At `0.1.0-beta.13`, runtime code, exports and generator templates were unchanged from `0.1.0-beta.12`. Existing integrations remain on their selected version until explicitly upgraded.
+
+The Python `0.1.0b9` source is included in the repository. Its released wheel is unchanged and is installed separately from npm.

package/README.md

@@ -10,7 +10,7 @@ Integrate Banner, Native and Clip ads into your AI app. wavebird handles ad deli
 | --- | --- |
 | JavaScript | `@wavebirdai/api`, follow the steps below |
 | TypeScript | `@wavebirdai/api`, with included types and TypeScript examples |
-| Python | `wavebird-publisher-server`, follow the [Python guide](python/README.md) |
+| Python | `wavebird-publisher-server`, follow the [Python guide](https://github.com/wavebird-ai/api/blob/main/python/README.md) |
 
 Native iOS and Android packages are not currently available. See [integration paths](https://wavebird.ai/api/integration-paths) for supported environments.
 
@@ -22,22 +22,26 @@ 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.16
+   npm install @wavebirdai/api@0.1.0-beta.18
    ```
 
 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](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 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).
 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.
 
-For Next.js, you can use the [generator](docs/web/nextjs.md) instead of copying Dashboard's route files.
+For Next.js, you can use the [generator](https://github.com/wavebird-ai/api/blob/main/docs/web/nextjs.md) instead of copying Dashboard's route files.
 
 ## 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.
 
-[JavaScript and TypeScript examples](docs/web/generation.md) | [Server and browser reference](docs/web/reference.md)
+[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)
+
+## Consent appearance
+
+The wavebird dialog follows the visitor's browser language. Optional `consentLocale` supplies a fallback before English; `consentTheme` adjusts appearance. Consent choices and permissions stay unchanged. See [consent appearance](https://github.com/wavebird-ai/api/blob/main/docs/web/reference.md#consent-appearance) for supported languages and options.
 
 ## Update an existing integration
 

package/dist/browser.d.ts

@@ -17,6 +17,18 @@ export type PublisherAds<Bound extends boolean = boolean> = {
   deny(): Promise<unknown>;
   withdraw(): Promise<unknown>;
 };
+export type PublisherConsentTheme = {
+  /** Six-digit hex colors. Insufficient contrast falls back to readable colors. */
+  accentColor?: string;
+  backgroundColor?: string;
+  textColor?: string;
+  /** Font family names only, without CSS rules or URLs. No font is downloaded. */
+  fontFamily?: string;
+  /** Corner radius in pixels, 0–20. */
+  radius?: number;
+  /** Card padding in pixels, 12–32. */
+  spacing?: number;
+};
 type PublisherAdsOptionsBase = {
   target: HTMLElement;
   clientId: string;
@@ -26,6 +38,10 @@ type PublisherAdsOptionsBase = {
   conversationId: string;
   timing?: "before" | "during" | "after";
   consentMode?: "wavebird_consent" | "own_cmp";
+  /** Defaults to browser language preferences, then English. Optional BCP 47 language tag or "auto". */
+  consentLocale?: string;
+  /** Presentation only. Does not change consent choices or storage. */
+  consentTheme?: PublisherConsentTheme;
   /** Optional official renderer URL. Only https://api.wavebird.ai/v1/render.js is supported. */
   rendererUrl?: string;
   privacySettingsTarget?: string;

package/dist/browser.js

@@ -54,6 +54,23 @@ export function createPublisherAds(options) {
     throw new Error("publisher_format_hook_invalid");
   if (options.onDiagnostic !== undefined && typeof options.onDiagnostic !== "function")
     throw new Error("publisher_diagnostic_hook_invalid");
+  if (options.consentLocale !== undefined && (typeof options.consentLocale !== "string" ||
+      !/^(?:auto|[a-z]{2,3}(?:-[a-z0-9]{2,8})*)$/i.test(options.consentLocale)))
+    throw new Error("publisher_consent_locale_invalid");
+  const consentTheme = options.consentTheme === undefined ? undefined : options.consentTheme;
+  if (consentTheme !== undefined) {
+    const validators = {
+      accentColor: value => typeof value === "string" && /^#[\da-f]{6}$/i.test(value),
+      backgroundColor: value => typeof value === "string" && /^#[\da-f]{6}$/i.test(value),
+      textColor: value => typeof value === "string" && /^#[\da-f]{6}$/i.test(value),
+      fontFamily: value => typeof value === "string" && /^[a-z0-9 ,"'\-]{1,160}$/i.test(value),
+      radius: value => typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 20,
+      spacing: value => typeof value === "number" && Number.isFinite(value) && value >= 12 && value <= 32,
+    };
+    if (!consentTheme || typeof consentTheme !== "object" || Array.isArray(consentTheme) ||
+        Object.entries(consentTheme).some(([key, value]) => !Object.hasOwn(validators, key) || !validators[key](value)))
+      throw new Error("publisher_consent_theme_invalid");
+  }
   let privacyTarget = null;
   if (consentMode === "wavebird_consent" && options.privacySettingsTarget !== undefined) {
     if (typeof options.privacySettingsTarget !== "string" || !options.privacySettingsTarget.trim())
@@ -80,7 +97,9 @@ export function createPublisherAds(options) {
   // 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";
+  // The hosted creative clips its own contents. Clipping this full-width mount
+  // loses a fractional pixel at some device scales and invalidates visibility.
+  slot.style.cssText = "width:100%;height:100%;overflow:visible;margin:0 auto";
   target.append(slot);
   const openPrivacySettings = () => { if (!disposed) sponsor?.openPrivacySettings(); };
   privacyTarget?.addEventListener("click", openPrivacySettings);
@@ -148,6 +167,8 @@ export function createPublisherAds(options) {
     sponsor = window.wavebird.createChatSponsor({ target: slot, ...binding,
       clientId: options.clientId, surfaceId: options.surfaceId, jobType: options.jobType, timing, consentMode,
       cleanupAfterClip: true,
+      ...(options.consentLocale === undefined ? {} : { consentLocale: options.consentLocale }),
+      ...(consentTheme === undefined ? {} : { consentTheme: { ...consentTheme } }),
       ...(turnBinding ? { turnBinding: true } : {}),
       ...(options.getFormat === undefined ? {} : { getFormat: options.getFormat }),
       ...(options.placementEndpoint === undefined ? {} : { placementEndpoint: options.placementEndpoint }),

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.16` as your server routes.
+These are connection helpers, not complete apps. Use the same installed `@wavebirdai/api@0.1.0-beta.18` 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

@@ -11,7 +11,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.16 server-only
+npm install @wavebirdai/api@0.1.0-beta.18 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.16`. [Start with the integration steps](../../README.md#set-up-javascript-or-typescript).
+Applies to `@wavebirdai/api@0.1.0-beta.18`. [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.
@@ -30,6 +30,22 @@ For renderer failures, the browser's optional `onDiagnostic` receives only a fix
 
 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.
 
+## Consent appearance
+
+The hosted renderer uses the first supported language in the visitor's browser preferences. Optional `consentLocale: "de-DE"` on `createPublisherAds` is a fallback if none matches. English is the final fallback. Omit it or use `"auto"` to keep the English fallback.
+
+Supported languages: English, Spanish, German, Japanese, French, Portuguese, Russian, Italian, Dutch, Polish, Turkish, Indonesian, Chinese, Persian, Czech, Vietnamese, Korean, Arabic, Ukrainian and Hungarian. Chinese includes simplified and traditional script. Korean uses South Korean wording. Arabic and Persian use right-to-left text.
+
+Language support is delivered by the hosted renderer. Browser preferences take priority over the publisher fallback.
+
+The optional `consentTheme` accepts `accentColor`, `backgroundColor` and `textColor` as six-digit hex colors, `fontFamily` as existing font names, `radius` from 0 to 20, and `spacing` from 12 to 32 pixels. Low-contrast colors fall back to readable colors. No fonts are downloaded. For example:
+
+```js
+consentTheme: { accentColor: "#243c5a", radius: 4, fontFamily: "Arial, sans-serif" }
+```
+
+This is a configuration fragment, not a complete integration. Appearance does not change choices, storage, consent requirements or the `own_cmp` integration. Do not hide, rename or disable consent actions with app styles.
+
 ## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wavebirdai/api",
-  "version": "0.1.0-beta.16",
+  "version": "0.1.0-beta.18",
   "private": false,
   "type": "module",
   "description": "JavaScript and TypeScript integration for wavebird Banner, Native and Clip ads, with consent and generation lifecycle handling.",
@@ -20,6 +20,7 @@
     "bin",
     "templates",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "docs/web",
     "python/README.md",

package/src/browser.d.ts

@@ -17,6 +17,18 @@ export type PublisherAds<Bound extends boolean = boolean> = {
   deny(): Promise<unknown>;
   withdraw(): Promise<unknown>;
 };
+export type PublisherConsentTheme = {
+  /** Six-digit hex colors. Insufficient contrast falls back to readable colors. */
+  accentColor?: string;
+  backgroundColor?: string;
+  textColor?: string;
+  /** Font family names only, without CSS rules or URLs. No font is downloaded. */
+  fontFamily?: string;
+  /** Corner radius in pixels, 0–20. */
+  radius?: number;
+  /** Card padding in pixels, 12–32. */
+  spacing?: number;
+};
 type PublisherAdsOptionsBase = {
   target: HTMLElement;
   clientId: string;
@@ -26,6 +38,10 @@ type PublisherAdsOptionsBase = {
   conversationId: string;
   timing?: "before" | "during" | "after";
   consentMode?: "wavebird_consent" | "own_cmp";
+  /** Defaults to browser language preferences, then English. Optional BCP 47 language tag or "auto". */
+  consentLocale?: string;
+  /** Presentation only. Does not change consent choices or storage. */
+  consentTheme?: PublisherConsentTheme;
   /** Optional official renderer URL. Only https://api.wavebird.ai/v1/render.js is supported. */
   rendererUrl?: string;
   privacySettingsTarget?: string;

package/src/browser.js

@@ -54,6 +54,23 @@ export function createPublisherAds(options) {
     throw new Error("publisher_format_hook_invalid");
   if (options.onDiagnostic !== undefined && typeof options.onDiagnostic !== "function")
     throw new Error("publisher_diagnostic_hook_invalid");
+  if (options.consentLocale !== undefined && (typeof options.consentLocale !== "string" ||
+      !/^(?:auto|[a-z]{2,3}(?:-[a-z0-9]{2,8})*)$/i.test(options.consentLocale)))
+    throw new Error("publisher_consent_locale_invalid");
+  const consentTheme = options.consentTheme === undefined ? undefined : options.consentTheme;
+  if (consentTheme !== undefined) {
+    const validators = {
+      accentColor: value => typeof value === "string" && /^#[\da-f]{6}$/i.test(value),
+      backgroundColor: value => typeof value === "string" && /^#[\da-f]{6}$/i.test(value),
+      textColor: value => typeof value === "string" && /^#[\da-f]{6}$/i.test(value),
+      fontFamily: value => typeof value === "string" && /^[a-z0-9 ,"'\-]{1,160}$/i.test(value),
+      radius: value => typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 20,
+      spacing: value => typeof value === "number" && Number.isFinite(value) && value >= 12 && value <= 32,
+    };
+    if (!consentTheme || typeof consentTheme !== "object" || Array.isArray(consentTheme) ||
+        Object.entries(consentTheme).some(([key, value]) => !Object.hasOwn(validators, key) || !validators[key](value)))
+      throw new Error("publisher_consent_theme_invalid");
+  }
   let privacyTarget = null;
   if (consentMode === "wavebird_consent" && options.privacySettingsTarget !== undefined) {
     if (typeof options.privacySettingsTarget !== "string" || !options.privacySettingsTarget.trim())
@@ -80,7 +97,9 @@ export function createPublisherAds(options) {
   // 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";
+  // The hosted creative clips its own contents. Clipping this full-width mount
+  // loses a fractional pixel at some device scales and invalidates visibility.
+  slot.style.cssText = "width:100%;height:100%;overflow:visible;margin:0 auto";
   target.append(slot);
   const openPrivacySettings = () => { if (!disposed) sponsor?.openPrivacySettings(); };
   privacyTarget?.addEventListener("click", openPrivacySettings);
@@ -148,6 +167,8 @@ export function createPublisherAds(options) {
     sponsor = window.wavebird.createChatSponsor({ target: slot, ...binding,
       clientId: options.clientId, surfaceId: options.surfaceId, jobType: options.jobType, timing, consentMode,
       cleanupAfterClip: true,
+      ...(options.consentLocale === undefined ? {} : { consentLocale: options.consentLocale }),
+      ...(consentTheme === undefined ? {} : { consentTheme: { ...consentTheme } }),
       ...(turnBinding ? { turnBinding: true } : {}),
       ...(options.getFormat === undefined ? {} : { getFormat: options.getFormat }),
       ...(options.placementEndpoint === undefined ? {} : { placementEndpoint: options.placementEndpoint }),

package/templates/NEXT-SETUP.md

@@ -6,7 +6,7 @@ The generator installed `lib/publisher`, `lib/auth`, `lib/turn-store` and `lib/m
 
 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.
 
-1. Copy the complete Server ENV from the Dashboard: `WAVEBIRD_CLIENT_ID`, `WAVEBIRD_SECRET_KEY`, `WAVEBIRD_PREFERENCE_SECRET`, and `WAVEBIRD_PUBLIC_ORIGINS`. Keep the saved preference secret stable. The origins value is a comma-separated list of the exact scheme, host, and port where your app is opened. Keep the Dashboard project domain at your real HTTPS host. For local Server Test-key testing, include the exact loopback origin in `WAVEBIRD_PUBLIC_ORIGINS` without changing that project domain; Browser Test Keys instead use their separate Allowed origins field in API Keys. `localhost` and `127.0.0.1` are distinct. Do not use wildcards. The package rejects an absent or malformed list. Never expose server secrets through `NEXT_PUBLIC_` or client props. `clientId` is the public project ID.
+1. Copy the complete Server ENV from the Dashboard: `WAVEBIRD_API_BASE_URL`, `WAVEBIRD_CLIENT_ID`, `WAVEBIRD_SECRET_KEY`, `WAVEBIRD_PREFERENCE_SECRET`, and `WAVEBIRD_PUBLIC_ORIGINS`. Keep the saved preference secret stable. The origins value is a comma-separated list of the exact scheme, host, and port where your app is opened. Keep the Dashboard project domain at your real HTTPS host. For local Server Test-key testing, include the exact loopback origin in `WAVEBIRD_PUBLIC_ORIGINS` without changing that project domain; Browser Test Keys instead use their separate Allowed origins field in API Keys. `localhost` and `127.0.0.1` are distinct. Do not use wildcards. The package rejects an absent or malformed list. Never expose server secrets through `NEXT_PUBLIC_` or client props. `clientId` is the public project ID.
 2. Replace `lib/publisher`'s example surface, placement, allowed sizes, formats, locale, consent mode, and publisher identity with the **saved Dashboard values**. The responsive example lists 728×90 and 320×50 Banner sizes only to show the size-selection shape. The saved sizes define the normal envelope; optional `maxWidth` and `maxHeight` are advanced caps that only narrow it. Keep `responsiveSizeSelection: true` only when the selected project and placement approve every configured size. Remove any size absent from the saved project before Test traffic. The API enforces its own authority; example values do not create a valid placement.
 3. Connect `lib/auth` to the app's real session authorization. Its supplied path check fails closed when `PUBLISHER_AUTH_CHECK_PATH` is absent. The path must be a publisher-owned same-origin route that returns 204 only for an authorized user and supplies an `x-publisher-session-id` header containing a stable non-credential correlation ID for that authenticated session. Never return a cookie, bearer token or raw credential as that ID. The route must not be any wavebird route. The example sends the session cookie to that check only when the request origin exactly matches `WAVEBIRD_PUBLIC_ORIGINS`; a missing or different origin fails closed. The package checks that the browser's session ID matches this server-validated value before placement or generation.
 4. Replace `lib/turn-store`'s fail-closed stub with `createPostgresTurnStorage(yourExistingPgPool)` or another persistent store implementing the package's atomic interface. For PostgreSQL, run the adapter's `install()` once in your normal database migration step; use a pool shared by the publisher's workers. Keep `WAVEBIRD_PREFERENCE_SECRET` stable across workers and restarts; the package derives a separate journal key from it and rejects a changed key for an active project. Coordinate secret rotation after active turns are drained; never clear the journal guard to restore ad service while turns remain. The package owns turn claims, ordered reports, retry and bounded reconciliation. An unavailable store suppresses ad placement while the authenticated model route remains available.