@wavebirdai/api 0.0.0-stage → 0.1.0-beta.1

package/examples/next-ts/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "wavebird-api-next-ts-example",
+  "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" },
+  "devDependencies": { "@types/node": "^25", "@types/react": "^19", "@types/react-dom": "^19", "typescript": "^5" }
+}

package/examples/next-ts/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "es2022"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [{ "name": "next" }]
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "@wavebirdai/api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.1",
+  "private": false,
+  "type": "module",
+  "description": "Banner/Native publisher integration for the wavebird API",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "https://github.com/wavebird-ai/api" },
+  "engines": { "node": ">=20" },
+  "files": ["dist", "examples", "bin", "templates", "README.md", "LICENSE"],
+  "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" },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "test": "node --test tests/*.test.mjs",
+    "pretest": "npm run build",
+    "prepack": "npm run build"
+  }
+}

package/templates/NEXT-SETUP.md

@@ -0,0 +1,11 @@
+# Connect wavebird to this Next.js app
+
+The generator installed `lib/publisher`, `lib/auth`, and `lib/model`; `app/api/generate`, `app/api/sponsor-slot`, and `app/api/sponsor-consent`; 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`, 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 the key or preference secret through `NEXT_PUBLIC_` or client props. `clientId` is the public project ID.
+2. Replace `lib/publisher`'s example surface, placement, dimensions, 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. 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; it must not be any wavebird route.
+4. Connect `lib/model` to the existing generation stream. The installed function throws until replaced. Keep the existing generation response and pass the supplied abort signal to it. Do not put model calls in the browser solely for this integration.
+5. In an existing client page, mount `<WavebirdPlacement clientId={publicProjectId} userId={authenticatedUserId} conversationId={activeConversationId} onReady={setAds} />` beside the real generation result, outside the input and transcript. When the user starts their existing generation, call `ads.connectGeneration({ signal, request: headers => fetch('/api/generate', { method: 'POST', headers, signal }), consume: async (response, lifecycle) => { /* consume your existing stream and call lifecycle.onDelta() for each delta */ } })`. Abort that same signal on Stop or unmount. Use a stable `onReady` callback. This example uses wavebird's consent dialog; if the saved project uses the publisher's own CMP, connect its real grant/deny/withdrawal/expiry/GPC lifecycle instead of changing only the label.
+
+These routes are real required Next.js files, not hidden package behavior. The package has no knowledge of your login session, CMP, or model stream. Start with a Test project and check that No-Fill, abort and late responses never block the primary result; all Test facts must remain nonpayable.

package/templates/WavebirdPlacement.jsx

@@ -0,0 +1,31 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import { createPublisherAds } from "@wavebirdai/api/browser";
+
+export function WavebirdPlacement({ clientId, userId, conversationId, onReady }) {
+  const target = useRef(null);
+  useEffect(() => {
+    if (!target.current || !clientId || !userId || !conversationId) return;
+    const ads = createPublisherAds({
+      target: target.current,
+      clientId,
+      surfaceId: "chat_assistant",
+      jobType: "chat",
+      timing: "during",
+      consentMode: "wavebird_consent",
+      userId,
+      conversationId,
+      rendererUrl: "https://api.wavebird.ai/v1/render.js",
+      placementEndpoint: "/api/sponsor-slot",
+      consentEndpoint: "/api/sponsor-consent",
+      privacySettingsTarget: "#wavebird-privacy-settings"
+    });
+    onReady?.(ads);
+    return () => { onReady?.(null); ads.dispose(); };
+  }, [clientId, userId, conversationId, onReady]);
+  return <>
+    <button id="wavebird-privacy-settings" type="button">Sponsored choices</button>
+    <section ref={target} aria-label="Sponsored placement area" style={{ width: "100%", maxWidth: 728, height: 346 }} />
+  </>;
+}

package/templates/WavebirdPlacement.tsx

@@ -0,0 +1,36 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import { createPublisherAds, type PublisherAds } from "@wavebirdai/api/browser";
+
+export function WavebirdPlacement({ clientId, userId, conversationId, onReady }: {
+  clientId: string;
+  userId: string;
+  conversationId: string;
+  onReady?: (ads: PublisherAds | null) => void;
+}) {
+  const target = useRef<HTMLElement | null>(null);
+  useEffect(() => {
+    if (!target.current || !clientId || !userId || !conversationId) return;
+    const ads = createPublisherAds({
+      target: target.current,
+      clientId,
+      surfaceId: "chat_assistant",
+      jobType: "chat",
+      timing: "during",
+      consentMode: "wavebird_consent",
+      userId,
+      conversationId,
+      rendererUrl: "https://api.wavebird.ai/v1/render.js",
+      placementEndpoint: "/api/sponsor-slot",
+      consentEndpoint: "/api/sponsor-consent",
+      privacySettingsTarget: "#wavebird-privacy-settings"
+    });
+    onReady?.(ads);
+    return () => { onReady?.(null); ads.dispose(); };
+  }, [clientId, userId, conversationId, onReady]);
+  return <>
+    <button id="wavebird-privacy-settings" type="button">Sponsored choices</button>
+    <section ref={target} aria-label="Sponsored placement area" style={{ width: "100%", maxWidth: 728, height: 346 }} />
+  </>;
+}

package/templates/model.js

@@ -0,0 +1,3 @@
+export async function existingGeneration() {
+  throw new Error("Connect your existing authenticated generation stream in lib/model.js");
+}

package/templates/model.ts

@@ -0,0 +1,3 @@
+export async function existingGeneration(_signal: AbortSignal): Promise<Response> {
+  throw new Error("Connect your existing authenticated generation stream in lib/model.ts");
+}