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

package/README.md

@@ -1,100 +1,46 @@
-# @wavebirdai/api
+# wavebird API
 
-Add Wavebird Banner, Native, and Clip placements to an authenticated chat app. The package provides server handlers for placement, consent, and generation reporting, plus a browser adapter for the hosted renderer. Your server keeps the Wavebird key; your app keeps control of its login, model stream, layout, and consent choice.
+Integrate Banner, Native and Clip ads into your AI app. wavebird handles ad delivery and consent. Your app keeps its existing login, model and result display.
 
-## Integrate with Next.js
+[API docs](https://wavebird.ai/api/quickstart) | [Dashboard](https://dashboard.wavebird.ai/wavebird) | [Troubleshooting](https://wavebird.ai/api/troubleshooting)
 
-You need a saved Wavebird Test project and placement in Dashboard, a Server Test Key, an existing authenticated Next.js App Router app, and a durable turn store. Start with the placement's saved formats, sizes, timing, and consent mode. Test traffic is nonpayable.
+## Choose your language
 
-1. Install the package and generate the route files for your app directory:
+| Language | Package and guide |
+| --- | --- |
+| 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) |
 
-   ```sh
-   npm install @wavebirdai/api@0.1.0-beta.12
-   ./node_modules/.bin/wavebird-next init --lang ts --root . --app-dir src/app
-   ```
-
-   Use `--lang js --app-dir app` for a JavaScript app with `app/` at the project root. The generator adds files without overwriting existing ones and writes `WAVEBIRD-SETUP.md` with the exact connection points.
-
-2. Set the server-only values in your deployment environment:
+Native iOS and Android packages are not currently available. See [integration paths](https://wavebird.ai/api/integration-paths) for supported environments.
 
-   ```dotenv
-   WAVEBIRD_CLIENT_ID=<saved-project-id>
-   WAVEBIRD_SECRET_KEY=<server-test-key>
-   WAVEBIRD_PREFERENCE_SECRET=<stable-random-value-at-least-32-bytes>
-   WAVEBIRD_PUBLIC_ORIGINS=https://your-app.example
-   ```
-
-   `WAVEBIRD_PUBLIC_ORIGINS` must contain each exact app origin, including scheme and port. For local Server Test-key work, add the exact loopback origin to this list while keeping the Dashboard project domain at its real HTTPS host. Never expose the server key or preference secret through `NEXT_PUBLIC_`, client props, or source control.
-
-3. Connect the generated files to your app: copy the **saved** placement settings into `lib/publisher`; have `lib/auth` validate the real logged-in request and return a stable, non-credential session ID; replace `lib/turn-store` with your persistent store; and connect `lib/model` to your existing generation stream. The supplied auth, store, and model hooks fail closed until you do this. If you use PostgreSQL, the provided adapter uses your existing pool and its `install()` belongs in your normal migration step.
+## Set up JavaScript or TypeScript
 
-   The generated server route keeps the Wavebird key on the server and wraps your existing stream:
+Use Node.js 20 or later on your server.
 
-   ```ts
-   import { getPublisher } from "../../../lib/publisher";
-   import { existingGeneration } from "../../../lib/model";
-
-   export async function POST(request: Request): Promise<Response> {
-     return getPublisher().withGeneration({ request, run: existingGeneration });
-   }
-   ```
+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.
+2. **Install the package.** Run this in your app's terminal, in the folder containing `package.json`:
 
-4. Mount the generated `WavebirdPlacement` beside your app's result area using real authenticated user and conversation IDs, then wrap the existing generation request:
-
-   ```tsx
-   <WavebirdPlacement
-     clientId={publicProjectId}
-     userId={authenticatedUserId}
-     conversationId={activeConversationId}
-     onReady={setAds}
-   />
-
-   await ads.connectGeneration({
-     signal,
-     request: headers => fetch("/api/generate", { method: "POST", headers, signal }),
-     consume: async (response, lifecycle) => {
-       if (!response.ok || !response.body) throw new Error("generation_unavailable");
-       const reader = response.body.getReader();
-       while (true) {
-         const next = await reader.read();
-         if (next.done) break;
-         // Forward next.value to your existing stream consumer.
-         lifecycle.onDelta();
-       }
-     },
-   });
+   ```sh
+   npm install @wavebirdai/api@0.1.0-beta.12
    ```
 
-   The generated `WAVEBIRD-SETUP.md` shows where the component and routes go. Use Wavebird's consent dialog only when that matches the saved project; for `own_cmp`, connect your actual CMP lifecycle.
-
-5. Validate in Test: confirm the saved format and size, consent and GPC behavior, No-Fill, Stop/abort, and late responses. The generation result must continue independently of the ad path. Move to another package version or Live only through your normal project approval process.
-
-JavaScript and TypeScript use this same package. Complete Next.js JavaScript and TypeScript examples are included in `node_modules/@wavebirdai/api/examples/next-js` and `node_modules/@wavebirdai/api/examples/next-ts`. For other frameworks, use the explicit `@wavebirdai/api/server` and `@wavebirdai/api/browser` exports described below. The [REST reference](https://wavebird.ai/api/reference/endpoints) covers integrations without this package. The established [`wavebird`](https://www.npmjs.com/package/wavebird) SDK is a separate package.
-
-## Server and browser boundary
-
-`@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.
-
-Responsive size selection is enabled by default in this version. The browser adapter sends the measured reserved container size. The server chooses one of the saved `allowedSizes` that fits, or returns `no_fit` without an upstream placement request. Numeric `maxWidth` and `maxHeight` are optional advanced caps: when omitted, the saved sizes define the envelope; when supplied, they can only narrow eligible sizes. A size can carry `formats: ["banner"]`, `formats: ["native"]`, `formats: ["clip"]`, or an approved combination; this annotation remains on the publisher server and is stripped from the wavebird request. A browser format preference is accepted only when it is among the saved `allowedFormats` and compatible with the selected size. Set `responsiveSizeSelection: false` only for a deliberate fixed-size compatibility integration. Reserve enough height for the selected creative and its controls; do not stretch the returned creative or place it over the model result.
-
-Create the server helper when a request arrives, as the included Next.js examples do. This lets Next.js build a publisher app without loading its server key into the build process; the helper still validates configuration before handling traffic.
-
-`withGeneration({ request, run, onLifecycle })` accepts an optional server-side observer. It receives `{ type, sessionId, generationId }` for `started` and one terminal state: `done`, `error`, or `abort`. Use it to forward lifecycle events to your own generation reporter; observer failures do not change the model response. It runs only for authenticated, same-origin requests with valid generation transport IDs. The callback is not awaited, and it receives no prompt or model bytes.
-
-With `sessionIdForRequest` and `turnJournal` configured, the package validates the browser non-credential session ID against the publisher authenticated request, binds one turn to its authorized placement job, and automatically retries ordered generation reports. The PostgreSQL adapter uses the publisher existing pool; run its `install()` in the normal migration step. An unavailable journal suppresses ad placement while an authenticated model request can still run. The store and HMAC key must survive worker restarts. A durable per-project key-version guard rejects a changed preference secret before accepting another turn; pending reports can still reconcile. Coordinate key rotation after active turns are drained rather than clearing the guard while turns remain. This opt-in path requires a package version that includes these exports; earlier published versions retain their original behavior.
+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.
+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.
 
-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.
+Test ads are nonpayable. Complete the [Live prerequisites](https://wavebird.ai/api/guides/going-live) before requesting Live activation.
 
-`@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 Next.js, you can use the [generator](docs/web/nextjs.md) instead of copying Dashboard's route files.
 
-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.
+## Connect your model output
 
-## Next.js
+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.
 
-The package contains equivalent JavaScript and TypeScript Next.js example files in `examples/next-js` and `examples/next-ts`. Each shows a publisher-owned reserved slot outside the input and scrolling transcript, same-origin consent and placement routes, the server-only configuration, and an existing generation stream wrapped by `withGeneration`. Their authorization hook fails closed until connected to the publisher's actual session validation. The sample generation stream is a local demonstration and is meant to be replaced by the publisher's existing model call.
+[JavaScript and TypeScript examples](docs/web/generation.md) | [Server and browser reference](docs/web/reference.md)
 
-The required server-only values are `WAVEBIRD_CLIENT_ID`, `WAVEBIRD_SECRET_KEY`, `WAVEBIRD_PREFERENCE_SECRET`, and `WAVEBIRD_PUBLIC_ORIGINS`. Keep secrets outside browser bundles and source control. Set project surface, placement, job type, timing, formats, locale, consent profile, identity/domain, and ad-space dimensions from the saved dashboard configuration. Reserve space for the selected creative and controls without distorting it. The publisher positions the section in its own UI.
+## Update an existing integration
 
-## Test scope
+Keep your installed version until you choose to upgrade. Follow the [migration guide](https://wavebird.ai/api/reference/versioning) and check the affected integration before deployment. The older `wavebird` npm package uses a different integration path.
 
-The browser and generation transport sources are included in the package. Before use in a publisher app, test the server routes, browser placement, consent, and generation lifecycle against its saved Test project and supported browser and host. Test traffic must remain nonpayable; installing this package does not activate Live ads.
+[Configuration](https://wavebird.ai/api/configuration) | [REST reference](https://wavebird.ai/api/reference/endpoints) | [Report an issue](https://github.com/wavebird-ai/api/issues)

package/docs/web/generation.md

@@ -0,0 +1,58 @@
+# 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.
+
+- `ads` is the instance for this surface, returned by `createPublisherAds` or the generated component's `onReady` callback.
+- `sendExistingRequest` sends your existing authenticated model request. Merge the provided headers into its headers and preserve its body and abort signal. Call the route wrapped by `withGeneration`.
+- `consumeAndPresentResponse` is your existing response parser and UI consumer. Call `onDelta` as output becomes visible. Call `onPresented` when the result is presented. Resolve after presentation, and reject on failure. For an image, do not report progress before the result is displayed.
+
+## TypeScript
+
+```ts
+import type { PublisherAds, GenerationConsumer } from "@wavebirdai/api/browser";
+
+export function runGeneration<T>(
+  ads: PublisherAds,
+  signal: AbortSignal,
+  sendExistingRequest: (
+    headers: Record<string, string>, signal: AbortSignal
+  ) => Promise<Response>,
+  consumeAndPresentResponse: GenerationConsumer<T>
+): Promise<T> {
+  return ads.connectGeneration({
+    signal,
+    request: headers => sendExistingRequest(headers, signal),
+    consume: (response, lifecycle) => consumeAndPresentResponse(response, {
+      onDelta: lifecycle.onDelta,
+      onPresented: () => lifecycle.onPresented?.(),
+    }),
+  });
+}
+```
+
+## JavaScript
+
+```js
+export function runGeneration(
+  ads, signal, sendExistingRequest, consumeAndPresentResponse
+) {
+  return ads.connectGeneration({
+    signal,
+    request: headers => sendExistingRequest(headers, signal),
+    consume: (response, lifecycle) => consumeAndPresentResponse(response, {
+      onDelta: lifecycle.onDelta,
+      onPresented: () => lifecycle.onPresented?.(),
+    }),
+  });
+}
+```
+
+The optional call preserves model-only responses, which do not provide an ad presentation callback in this package version. It does not convert failed advertising into a successful ad result.
+
+## Timing and cleanup
+
+For `after`, the helper waits for the transport to finish and the consumer to resolve before requesting placement. Receiving the final byte is not the same as presenting the result.
+
+For `during`, placement runs alongside generation. Retention depends on the format and surface. Do not add an unconditional stream-end hide action for all ads. The hosted renderer owns creative behavior, and the package enables Clip cleanup after playback. Follow the saved timing and the [format contract](https://wavebird.ai/api/concepts/ad-formats).
+
+Pass the app's abort signal, update the conversation binding on conversation changes, and call `dispose()` on sign-out or surface teardown. Do not wait for renderer readiness before allowing model generation.

package/docs/web/nextjs.md

@@ -0,0 +1,36 @@
+# Next.js generator
+
+Use this path instead of copying Dashboard's route files. It supports an existing Next.js App Router app with JavaScript or TypeScript. Use the saved Dashboard configuration in either path.
+
+## Generate files
+
+From the folder containing `package.json`:
+
+```sh
+npm install @wavebirdai/api@0.1.0-beta.12
+./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.
+
+## Connect your app
+
+| Generated area | Your connection |
+| --- | --- |
+| `lib/publisher` | Server ENV and the saved project's placement configuration |
+| `lib/auth` | Validate the real request session and return a stable, non-credential session ID |
+| `lib/turn-store` | Durable atomic turn storage. The PostgreSQL adapter uses your existing pool. Run its `install()` through your normal migration process. |
+| `lib/model` | Your existing abortable model request and response stream |
+| `WavebirdPlacement` | A reserved slot beside the result, outside the input and scrolling transcript |
+
+The auth, store and model hooks fail closed until connected. Do not replace authorization with `true`. Keep the preference signing secret stable across workers and restarts.
+
+Mount `WavebirdPlacement` with the authenticated user and active conversation IDs. Use its `onReady` callback to retain the ads instance for that surface. Connect the generation request as shown in the [connection examples](generation.md). Keep request headers, body and cancellation from your app.
+
+Use wavebird's consent dialog or your real CMP according to the project's saved consent mode. Do not grant consent from application startup code.
+
+## Check the result
+
+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)

package/docs/web/reference.md

@@ -0,0 +1,31 @@
+# Web integration reference
+
+Applies to `@wavebirdai/api@0.1.0-beta.12`. [Start with the integration steps](../../README.md#javascript-and-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.
+
+Responsive size selection is enabled by default in this version. The browser adapter sends the measured reserved container size. The server chooses one of the saved `allowedSizes` that fits, or returns `no_fit` without an upstream placement request. Numeric `maxWidth` and `maxHeight` are optional advanced caps: when omitted, the saved sizes define the envelope; when supplied, they can only narrow eligible sizes. A size can carry `formats: ["banner"]`, `formats: ["native"]`, `formats: ["clip"]`, or an approved combination; this annotation remains on the publisher server and is stripped from the wavebird request. A browser format preference is accepted only when it is among the saved `allowedFormats` and compatible with the selected size. Set `responsiveSizeSelection: false` only for a deliberate fixed-size compatibility integration. Reserve enough height for the selected creative and its controls; do not stretch the returned creative or place it over the model result.
+
+Create the server helper when a request arrives, as the included Next.js examples do. This lets Next.js build a publisher app without loading its server key into the build process; the helper still validates configuration before handling traffic.
+
+`withGeneration({ request, run, onLifecycle })` accepts an optional server-side observer. It receives `{ type, sessionId, generationId }` for `started` and one terminal state: `done`, `error`, or `abort`. Use it to forward lifecycle events to your own generation reporter; observer failures do not change the model response. It runs only for authenticated, same-origin requests with valid generation transport IDs. The callback is not awaited, and it receives no prompt or model bytes.
+
+With `sessionIdForRequest` and `turnJournal` configured, the package validates the browser non-credential session ID against the publisher authenticated request, binds one turn to its authorized placement job, and automatically retries ordered generation reports. The PostgreSQL adapter uses the publisher existing pool; run its `install()` in the normal migration step. An unavailable journal suppresses ad placement while an authenticated model request can still run. The store and HMAC key must survive worker restarts. A durable per-project key-version guard rejects a changed preference secret before accepting another turn; pending reports can still reconcile. Coordinate key rotation after active turns are drained rather than clearing the guard while turns remain. These exports are included in `0.1.0-beta.12`. Earlier versions retain their original behavior.
+
+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 `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 starts placement with generation. The hosted renderer applies format-specific retention and cleanup, so `during` is not a universal instruction to hide every format when the stream ends. Its generation request and response stream run without waiting for consent synchronization, the ad response, or renderer readiness. It forwards completion, error, abort and conversation changes to the renderer. Consent withdrawal and GPC must suppress unauthorized advertising. Do not implement a second hide timer in the app or treat a hidden slot as proof of an ad blocker.
+
+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.
+
+
+## Troubleshooting
+
+- **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.
+- **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.
+- **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,17 +1,42 @@
 {
   "name": "@wavebirdai/api",
-  "version": "0.1.0-beta.12",
+  "version": "0.1.0-beta.13",
   "private": false,
   "type": "module",
-  "description": "Integrate Banner, Native, and Clip placements into authenticated chat apps with server-side keys, consent, and generation lifecycle handling",
+  "description": "JavaScript and TypeScript integration for wavebird Banner, Native and Clip ads, with consent and generation lifecycle handling.",
   "license": "MIT",
-  "repository": { "type": "git", "url": "https://github.com/wavebird-ai/api" },
-  "engines": { "node": ">=20" },
-  "files": ["dist", "src", "build.mjs", "examples", "bin", "templates", "README.md", "LICENSE"],
-  "bin": { "wavebird-next": "./bin/wavebird-next.mjs" },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wavebird-ai/api"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "src",
+    "build.mjs",
+    "examples",
+    "bin",
+    "templates",
+    "README.md",
+    "LICENSE",
+    "docs/web",
+    "python/README.md",
+    "python/examples/fastapi_app/README.md"
+  ],
+  "bin": {
+    "wavebird-next": "./bin/wavebird-next.mjs"
+  },
   "exports": {
-    "./server": { "types": "./dist/server.d.ts", "import": "./dist/server.js" },
-    "./browser": { "types": "./dist/browser.d.ts", "import": "./dist/browser.js" },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -19,5 +44,18 @@
     "test": "node --test tests/*.test.mjs",
     "pretest": "npm run build",
     "prepack": "npm run build"
-  }
+  },
+  "homepage": "https://wavebird.ai/api/quickstart",
+  "bugs": {
+    "url": "https://github.com/wavebird-ai/api/issues"
+  },
+  "keywords": [
+    "wavebird",
+    "advertising",
+    "javascript",
+    "typescript",
+    "ai-apps",
+    "consent",
+    "publisher-integration"
+  ]
 }

package/python/README.md

@@ -0,0 +1,46 @@
+# wavebird Python integration
+
+Connect a Python server to wavebird placement, consent and generation reporting. The browser uses the official wavebird renderer. Banner, Native and Clip follow the saved project's formats and timing.
+
+This is a separate package from `@wavebirdai/api`. Python and Web have independent versions. Live ads require separate project approval.
+
+## Install
+
+Use Python 3.11 or later. Download the wheel from the [0.1.0b9 release](https://github.com/wavebird-ai/api/releases/tag/python-v0.1.0b9). Verify its SHA-256 before installing:
+
+```text
+wavebird_publisher_server-0.1.0b9-py3-none-any.whl
+86949813a16d895d54958d042833836f02264c7665a884c39b2094ada2538f34
+```
+
+In your app's virtual environment, install the downloaded file:
+
+```sh
+python -m pip install ./wavebird_publisher_server-0.1.0b9-py3-none-any.whl
+```
+
+The server exports are:
+
+```python
+from wavebird_publisher import PublisherConfig, PublisherServer
+```
+
+This import is not a complete configuration. Use the [FastAPI connection guide](examples/fastapi_app/README.md) for session, generation and browser hooks. FastAPI and an ASGI server are separate application dependencies. The wheel is distributed through GitHub Releases, not through this npm package.
+
+## Configure and connect
+
+1. Save the project settings and exact approved origins in [Dashboard](https://dashboard.wavebird.ai/wavebird). Keep the Server Key and Preference Secret on the server.
+2. Configure `PublisherConfig` from those saved values. Use `server_key`. The older `server_test_key` name remains compatible for existing Test integrations.
+3. Mount the FastAPI routes in your app and connect its real session validation and abortable model response. Default example hooks deny access or raise until connected.
+4. Load the same-origin `/api/wavebird/browser.js` module beside a reserved slot. Connect the real response consumer and consent flow. Python alone does not display an ad.
+5. Check the visible creative, its reporting and Test Logs. Test activity is nonpayable. No-Fill, denied consent or ad failures must leave model generation usable.
+
+## Deployment
+
+Use `turn_journal_path` on durable storage shared by workers on one host. The SQLite journal preserves turn bindings and pending generation reports across restarts. The in-memory coordinator remains compatible with older integrations. Multi-host and serverless deployments require a separately verified shared-store path.
+
+The supplied FastAPI example enables responsive selection using saved sizes and format mappings. The low-level Python configuration does not enable it by default. Optional width and height caps can only narrow the saved envelope.
+
+Each enabled format needs a visible integration check. Clip also needs playback and natural-end cleanup checks.
+
+[API docs](https://wavebird.ai/api/quickstart) | [Integration paths](https://wavebird.ai/api/integration-paths) | [Troubleshooting](https://wavebird.ai/api/troubleshooting)

package/python/examples/fastapi_app/README.md

@@ -0,0 +1,42 @@
+# Connect an existing FastAPI app
+
+Install the [Python 0.1.0b9 wheel](../../README.md#install), FastAPI and your ASGI server in the app's environment. The example uses the package's existing `/v1` contract and keeps credentials server-side.
+
+## 1. Set server configuration
+
+`run.py` reads the following values. Copy the saved project settings rather than choosing new formats or origins in the browser.
+
+| Purpose | Environment variables |
+| --- | --- |
+| Project and secrets | `WAVEBIRD_CLIENT_ID`, `WAVEBIRD_SECRET_KEY`, `WAVEBIRD_PREFERENCE_SECRET` |
+| Origins | `WAVEBIRD_PUBLIC_ORIGINS` |
+| Placement | `WAVEBIRD_SURFACE_ID`, `WAVEBIRD_PLACEMENT_KEY`, `WAVEBIRD_JOB_TYPE`, `WAVEBIRD_POSITION_HINT` |
+| Consent and timing | `WAVEBIRD_CONSENT_MODE`, `WAVEBIRD_GDPR_APPLIES`, `WAVEBIRD_TIMING` |
+| Publisher | `WAVEBIRD_APP_NAME`, `WAVEBIRD_APP_DOMAIN`, `WAVEBIRD_LOCALE` |
+| Formats and sizes | `WAVEBIRD_ALLOWED_FORMATS`, `WAVEBIRD_ALLOWED_SIZES`, `WAVEBIRD_SIZE_FORMATS_JSON` |
+| Turn storage | `WAVEBIRD_TURN_JOURNAL_PATH` |
+
+Origins are comma-separated exact origins, including scheme and port. `www` and the bare domain are separate entries. Sizes use `320x50,300x250` syntax. A format map such as `[[320,50,["banner"]],[300,250,["native","clip"]]]` must cover every saved size with its actual allowed formats. These are syntax examples, not replacement project values.
+
+The journal path must be absolute and durable, shared by the app's workers on one host. Keep secrets out of Git, responses and browser bundles.
+
+## 2. Connect session and generation
+
+In `publisher_hooks.py`:
+
+- `session_id_for_request` returns the server-validated app session ID. Authorization derives from that hook. Its default denies access.
+- `existing_generation` calls your existing model stream and preserves response and cancellation. Its default raises an error.
+
+The example's `create_app(..., host_app=your_existing_app, turn_journal_path=...)` mounts package routes without replacing your routes or middleware. It uses `mount_fastapi` from the installed package. Do not call the example factory as though it were a package export.
+
+## 3. Connect the browser
+
+Load the package's same-origin `/api/wavebird/browser.js` module beside your reserved slot. Supply real session and model-response hooks, saved timing, job type, slot settings and consent mode. Resolve the consumer only after presenting the result. Dispose the browser integration on sign-out and teardown.
+
+For an app mounted at `/app`, load the module under that mount and pass `apiBasePath: "/app"`. This accepts local path segments, not another origin. The module loads the official `https://api.wavebird.ai/v1/render.js` renderer.
+
+## 4. Verify
+
+Check the visible creative, reporting and a durable nonpayable project fact. Clip additionally needs playback and completion. Check No-Fill, refusal, withdrawal and Stop while confirming the model still works.
+
+Local adapter tests cover routing and security controls. They do not replace visible browser checks. This SQLite path does not qualify a multi-host or serverless deployment.