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

package/README.md

@@ -18,14 +18,14 @@ Native iOS and Android packages are not currently available. See [integration pa
 
 Use Node.js 20 or later on your server.
 
-1. **Open your project in Dashboard.** Choose your language and package version. Save your HTTPS app URL and approved origins. `www.example.com` and `example.com` are separate origins.
+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.
 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.12
+   npm install @wavebirdai/api@0.1.0-beta.15
    ```
 
-3. **Save the Server ENV.** Add the values from Dashboard to your server environment. Keep `WAVEBIRD_SECRET_KEY` and `WAVEBIRD_PREFERENCE_SECRET` out of browser code and Git.
+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.
 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.
 

package/dist/server.js

@@ -80,6 +80,7 @@ function normalizeOptions(options) {
   {
     if (!Array.isArray(options.publicOrigins) || options.publicOrigins.length < 1 || options.publicOrigins.length > 8) throw new Error("publisher_public_origins_invalid");
     for (const origin of options.publicOrigins) {
+      if (typeof origin !== "string" || origin.includes("*")) throw new Error("publisher_public_origins_invalid");
       let url;
       try { url = new URL(origin); } catch { throw new Error("publisher_public_origins_invalid"); }
       const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1";
@@ -387,21 +388,39 @@ export function createPublisherServer(inputOptions) {
     const headers = { "Cache-Control": "no-store", Vary: "Cookie, Sec-GPC" };
     if (!validOrigin(request, options, false)) return response("invalid_origin", 403, headers);
     if (gpc(request)) return Response.json({ preference: null }, { headers });
+    const revision = {};
+    if (options.sessionIdForRequest) {
+      let sessionId;
+      try { sessionId = await journalCall(() => options.sessionIdForRequest(request)); }
+      catch { return response("publisher_session_unavailable", 503, headers); }
+      if (!ID.test(sessionId || "")) return response("publisher_session_unavailable", 401, headers);
+      try {
+        const query = new URLSearchParams({ client_id: options.clientId, session_id: sessionId });
+        const result = await consentFetch(`${options.base}/consent?${query}`, {
+          method: "GET", headers: { Authorization: `Bearer ${options.secretKey}` }, cache: "no-store"
+        });
+        const state = await result.json();
+        if (!result.ok || !Number.isSafeInteger(state.current_revision) || state.current_revision < 0 ||
+            state.current_revision >= Number.MAX_SAFE_INTEGER) throw new Error("consent_revision_unavailable");
+        revision.current_revision = state.current_revision;
+      } catch { return response("consent_revision_unavailable", 503, headers); }
+    }
+    const preferenceResponse = value => Response.json({ ...value, ...revision }, { headers });
     try {
       const value = (request.headers.get("cookie") || "").split(";").map(value => value.trim())
         .find(value => value.startsWith(cookieName + "="))?.slice(cookieName.length + 1) || "";
       if (value.length > 2048) throw new Error("preference_invalid");
       const [payload, signature, extra] = value.split(".");
-      if (!payload || !signature || extra || !/^[A-Za-z0-9_-]+$/.test(payload) || !/^[A-Za-z0-9_-]+$/.test(signature)) return Response.json({ preference: null }, { headers });
-      if (!await crypto.subtle.verify("HMAC", await preferenceKey(), Buffer.from(signature, "base64url"), new TextEncoder().encode(payload))) return Response.json({ preference: null }, { headers });
+      if (!payload || !signature || extra || !/^[A-Za-z0-9_-]+$/.test(payload) || !/^[A-Za-z0-9_-]+$/.test(signature)) return preferenceResponse({ preference: null });
+      if (!await crypto.subtle.verify("HMAC", await preferenceKey(), Buffer.from(signature, "base64url"), new TextEncoder().encode(payload))) return preferenceResponse({ preference: null });
       const record = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
       const now = Date.now();
       if (Object.entries(scope(request)).some(([key, value]) => record[key] !== value) ||
         !["granted", "denied", "withdrawn"].includes(record.state) || !Number.isSafeInteger(record.issued_at) ||
         !Number.isSafeInteger(record.expires_at) || record.issued_at > now || record.expires_at <= now ||
-        record.expires_at - record.issued_at !== PREFERENCE_TTL * 1000) return Response.json({ preference: null }, { headers });
-      return Response.json({ preference: { state: record.state, expires_at: record.expires_at } }, { headers });
-    } catch { return Response.json({ preference: null, error: "preference_unavailable" }, { headers }); }
+        record.expires_at - record.issued_at !== PREFERENCE_TTL * 1000) return preferenceResponse({ preference: null });
+      return preferenceResponse({ preference: { state: record.state, expires_at: record.expires_at } });
+    } catch { return preferenceResponse({ preference: null, error: "preference_unavailable" }); }
   }
   async function consentPOST(request) {
     if (!await authorized(request)) return response("authentication_required", 401);

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

@@ -7,12 +7,18 @@ Use this path instead of copying Dashboard's route files. It supports an existin
 From the folder containing `package.json`:
 
 ```sh
-npm install @wavebirdai/api@0.1.0-beta.12
+npm install @wavebirdai/api@0.1.0-beta.15 server-only
 ./node_modules/.bin/wavebird-next init --lang ts --root . --app-dir src/app
 ```
 
 For JavaScript, use `--lang js`. For a root-level `app/` directory, use `--app-dir app`. The generator does not overwrite existing files. Read the generated `WAVEBIRD-SETUP.md` for their locations.
 
+`server-only` marks backend modules and is required by these examples. If you use the PostgreSQL adapter, install `pg` in your app too.
+
+### If a file already exists
+
+Keep your existing file. Create a temporary sibling folder with an empty `app/` directory, then run the installed generator with `--root ../wavebird-staging --app-dir app` (replace the folder name as needed). Review the generated files there and merge the connections into your app. Keep your existing authentication, model and generation route. If you move a helper into `lib/wavebird/`, update its relative imports and the routes that use it. Do not run the template model or authorization stub unchanged. No existing app files need to be deleted or overwritten.
+
 ## Connect your app
 
 | Generated area | Your connection |
@@ -33,4 +39,4 @@ Use wavebird's consent dialog or your real CMP according to the project's saved
 
 Check visible ads and Test Logs, then No-Fill, denied consent, Stop and a conversation change. An ad failure must not prevent the model result. The complete framework examples are in `examples/next-js` and `examples/next-ts` inside the installed package. Their demonstration model must be replaced with your own.
 
-[Return to setup](../../README.md#javascript-and-typescript) | [Configuration reference](reference.md)
+[Return to setup](../../README.md#set-up-javascript-or-typescript) | [Configuration reference](reference.md)

package/docs/web/reference.md

@@ -1,6 +1,6 @@
 # Web integration reference
 
-Applies to `@wavebirdai/api@0.1.0-beta.12`. [Start with the integration steps](../../README.md#javascript-and-typescript).
+Applies to `@wavebirdai/api@0.1.0-beta.15`. [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.
@@ -22,6 +22,8 @@ For `after`, resolve the generation consumer only after your app presents the re
 
 ## 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.
+
 - **401:** check the app session and server authorization before changing the wavebird key.
 - **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.

package/examples/next-js/package.json

@@ -3,5 +3,5 @@
   "private": true,
   "type": "module",
   "scripts": { "dev": "next dev", "build": "next build --webpack" },
-  "dependencies": { "next": "16.3.8", "react": "19.2.4", "react-dom": "19.2.4" }
+  "dependencies": { "next": "16.3.8", "react": "19.2.4", "react-dom": "19.2.4", "server-only": "0.0.1" }
 }

package/examples/next-ts/package.json

@@ -3,6 +3,6 @@
   "private": true,
   "type": "module",
   "scripts": { "dev": "next dev", "build": "next build --webpack", "typecheck": "tsc --noEmit" },
-  "dependencies": { "next": "16.3.8", "react": "19.2.4", "react-dom": "19.2.4" },
+  "dependencies": { "next": "16.3.8", "react": "19.2.4", "react-dom": "19.2.4", "server-only": "0.0.1" },
   "devDependencies": { "@types/node": "^25", "@types/react": "^19", "@types/react-dom": "^19", "typescript": "^5" }
 }

package/package.json

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

package/src/server.js

@@ -80,6 +80,7 @@ function normalizeOptions(options) {
   {
     if (!Array.isArray(options.publicOrigins) || options.publicOrigins.length < 1 || options.publicOrigins.length > 8) throw new Error("publisher_public_origins_invalid");
     for (const origin of options.publicOrigins) {
+      if (typeof origin !== "string" || origin.includes("*")) throw new Error("publisher_public_origins_invalid");
       let url;
       try { url = new URL(origin); } catch { throw new Error("publisher_public_origins_invalid"); }
       const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1";
@@ -387,21 +388,39 @@ export function createPublisherServer(inputOptions) {
     const headers = { "Cache-Control": "no-store", Vary: "Cookie, Sec-GPC" };
     if (!validOrigin(request, options, false)) return response("invalid_origin", 403, headers);
     if (gpc(request)) return Response.json({ preference: null }, { headers });
+    const revision = {};
+    if (options.sessionIdForRequest) {
+      let sessionId;
+      try { sessionId = await journalCall(() => options.sessionIdForRequest(request)); }
+      catch { return response("publisher_session_unavailable", 503, headers); }
+      if (!ID.test(sessionId || "")) return response("publisher_session_unavailable", 401, headers);
+      try {
+        const query = new URLSearchParams({ client_id: options.clientId, session_id: sessionId });
+        const result = await consentFetch(`${options.base}/consent?${query}`, {
+          method: "GET", headers: { Authorization: `Bearer ${options.secretKey}` }, cache: "no-store"
+        });
+        const state = await result.json();
+        if (!result.ok || !Number.isSafeInteger(state.current_revision) || state.current_revision < 0 ||
+            state.current_revision >= Number.MAX_SAFE_INTEGER) throw new Error("consent_revision_unavailable");
+        revision.current_revision = state.current_revision;
+      } catch { return response("consent_revision_unavailable", 503, headers); }
+    }
+    const preferenceResponse = value => Response.json({ ...value, ...revision }, { headers });
     try {
       const value = (request.headers.get("cookie") || "").split(";").map(value => value.trim())
         .find(value => value.startsWith(cookieName + "="))?.slice(cookieName.length + 1) || "";
       if (value.length > 2048) throw new Error("preference_invalid");
       const [payload, signature, extra] = value.split(".");
-      if (!payload || !signature || extra || !/^[A-Za-z0-9_-]+$/.test(payload) || !/^[A-Za-z0-9_-]+$/.test(signature)) return Response.json({ preference: null }, { headers });
-      if (!await crypto.subtle.verify("HMAC", await preferenceKey(), Buffer.from(signature, "base64url"), new TextEncoder().encode(payload))) return Response.json({ preference: null }, { headers });
+      if (!payload || !signature || extra || !/^[A-Za-z0-9_-]+$/.test(payload) || !/^[A-Za-z0-9_-]+$/.test(signature)) return preferenceResponse({ preference: null });
+      if (!await crypto.subtle.verify("HMAC", await preferenceKey(), Buffer.from(signature, "base64url"), new TextEncoder().encode(payload))) return preferenceResponse({ preference: null });
       const record = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
       const now = Date.now();
       if (Object.entries(scope(request)).some(([key, value]) => record[key] !== value) ||
         !["granted", "denied", "withdrawn"].includes(record.state) || !Number.isSafeInteger(record.issued_at) ||
         !Number.isSafeInteger(record.expires_at) || record.issued_at > now || record.expires_at <= now ||
-        record.expires_at - record.issued_at !== PREFERENCE_TTL * 1000) return Response.json({ preference: null }, { headers });
-      return Response.json({ preference: { state: record.state, expires_at: record.expires_at } }, { headers });
-    } catch { return Response.json({ preference: null, error: "preference_unavailable" }, { headers }); }
+        record.expires_at - record.issued_at !== PREFERENCE_TTL * 1000) return preferenceResponse({ preference: null });
+      return preferenceResponse({ preference: { state: record.state, expires_at: record.expires_at } });
+    } catch { return preferenceResponse({ preference: null, error: "preference_unavailable" }); }
   }
   async function consentPOST(request) {
     if (!await authorized(request)) return response("authentication_required", 401);

package/templates/NEXT-SETUP.md

@@ -2,7 +2,9 @@
 
 The generator installed `lib/publisher`, `lib/auth`, `lib/turn-store` and `lib/model`; `app/api/generate`, `app/api/sponsor-slot`, `app/api/sponsor-consent` and `app/api/sponsor-session`; and `components/WavebirdPlacement` (under `src/` when `src/app` was selected). No existing page was replaced.
 
-1. Set server-only `WAVEBIRD_CLIENT_ID`, `WAVEBIRD_SECRET_KEY`, `WAVEBIRD_PREFERENCE_SECRET` (a stable random value of at least 32 bytes), and `WAVEBIRD_PUBLIC_ORIGINS`. The last value is a comma-separated list of the exact scheme, host, and port where your app is opened. Keep the Dashboard project domain at your real HTTPS host. For local Server Test-key testing, include the exact loopback origin in `WAVEBIRD_PUBLIC_ORIGINS` without changing that project domain; Browser Test Keys instead use their separate Allowed origins field in API Keys. `localhost` and `127.0.0.1` are distinct. Do not use wildcards. The package rejects an absent or malformed list. Never expose server secrets through `NEXT_PUBLIC_` or client props. `clientId` is the public project ID.
+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.
 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.