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

package/dist/turn-journal.js

@@ -0,0 +1,155 @@
+import { Buffer } from "node:buffer";
+import { createHash, createHmac, randomUUID } from "node:crypto";
+
+const ID = /^[A-Za-z0-9_-]{1,128}$/;
+const JOB_ID = /^job_[A-Za-z0-9_-]{1,128}$/;
+
+/** Domain-separate the stable server preference secret for pseudonymous turn keys. */
+export function derivePublisherTurnKeySecret(preferenceSecret) {
+  if (typeof preferenceSecret !== "string" || Buffer.byteLength(preferenceSecret, "utf8") < 32)
+    throw new Error("publisher_preference_secret_invalid");
+  return createHmac("sha256", preferenceSecret).update("wavebird/turn-journal-key/v1").digest("hex");
+}
+
+/** Package-owned state machine over a publisher's existing atomic, durable store. */
+export function createPublisherTurnJournal({ storage, reportGeneration, keySecret, onDiagnostic }) {
+  if (typeof storage?.atomic !== "function" || typeof storage?.scan !== "function" ||
+      typeof reportGeneration !== "function") throw new Error("publisher_turn_storage_invalid");
+  if (typeof keySecret !== "string" || Buffer.byteLength(keySecret, "utf8") < 32)
+    throw new Error("publisher_turn_key_secret_invalid");
+  const tasks = new Set();
+  let activeReports = 0;
+  const reportWaiters = [];
+  const diagnostic = code => { try { onDiagnostic?.(code); } 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");
+  async function verifyKeyVersion(scope) {
+    if (verifiedScopes.has(scope)) return;
+    // A separate scope keeps this guard outside ordinary turn retention pruning.
+    const versionScope = createHash("sha256").update(JSON.stringify(["wavebird/turn-journal-meta/v1", scope])).digest("hex");
+    await storage.atomic(versionScope, versionKey, previous => {
+      if (previous && previous.keyFingerprint !== keyFingerprint)
+        throw new Error("publisher_turn_key_version_conflict");
+      return { state: previous || { keyFingerprint }, result: null };
+    });
+    verifiedScopes.add(scope);
+  }
+  function identity(turn) {
+    if (![turn?.projectId, turn?.surfaceId, turn?.sessionId, turn?.turnId].every(value => ID.test(value || "")))
+      throw new Error("publisher_turn_context_invalid");
+    const scope = createHash("sha256").update(JSON.stringify([turn.projectId, turn.surfaceId])).digest("hex");
+    const key = createHmac("sha256", keySecret).update(JSON.stringify([turn.projectId, turn.surfaceId, turn.sessionId, turn.turnId])).digest("hex");
+    return { scope, key };
+  }
+  function initial(scope) {
+    return { scope, createdAtMs: Date.now(), placementClaimed: false, generationClaimed: false,
+      jobId: null, phase: "idle", startedReported: false, terminalReported: false,
+      leaseId: null, leaseUntilMs: 0 };
+  }
+  async function change(turn, update) {
+    const { scope, key } = identity(turn);
+    await verifyKeyVersion(scope);
+    return storage.atomic(scope, key, previous => {
+      if (previous && previous.scope !== scope) throw new Error("publisher_turn_scope_conflict");
+      const state = { ...(previous || initial(scope)) };
+      const result = update(state);
+      return { state, result };
+    });
+  }
+  async function claimPlacement(turn) {
+    return change(turn, state => {
+      if (state.placementClaimed) return false;
+      state.placementClaimed = true;
+      return true;
+    });
+  }
+  async function releaseRejectedPlacement(turn) {
+    await change(turn, state => { if (!state.jobId) state.placementClaimed = false; });
+  }
+  async function claimGeneration(turn) {
+    return change(turn, state => {
+      if (state.generationClaimed) return false;
+      state.generationClaimed = true;
+      return true;
+    });
+  }
+  function schedule(scope, key) {
+    const task = drain(scope, key).catch(() => diagnostic("turn_journal_unavailable"));
+    tasks.add(task);
+    void task.finally(() => tasks.delete(task));
+  }
+  async function bind(turn, jobId) {
+    if (!JOB_ID.test(jobId || "")) throw new Error("publisher_job_id_invalid");
+    const { scope, key } = identity(turn);
+    const bound = await change(turn, state => {
+      if (!state.placementClaimed || state.jobId && state.jobId !== jobId) return false;
+      state.jobId = jobId;
+      return true;
+    });
+    if (!bound) throw new Error("publisher_turn_job_conflict");
+    schedule(scope, key);
+  }
+  async function phase(turn, event) {
+    if (!["started", "finished", "failed"].includes(event)) throw new Error("publisher_phase_invalid");
+    const { scope, key } = identity(turn);
+    const changed = await change(turn, state => {
+      if (!state.generationClaimed || state.phase !== (event === "started" ? "idle" : "started")) return false;
+      state.phase = event;
+      return true;
+    });
+    if (changed) schedule(scope, key);
+  }
+  async function lease(scope, key) {
+    return storage.atomic(scope, key, previous => {
+      if (!previous || previous.scope !== scope || !previous.jobId || previous.phase === "idle" ||
+          previous.leaseUntilMs > Date.now()) return { state: previous, result: null };
+      const event = !previous.startedReported ? "started" :
+        ["finished", "failed"].includes(previous.phase) && !previous.terminalReported ? previous.phase : null;
+      if (!event) return { state: previous, result: null };
+      const leaseId = randomUUID();
+      return { state: { ...previous, leaseId, leaseUntilMs: Date.now() + 10_000 },
+        result: { jobId: previous.jobId, event, leaseId } };
+    });
+  }
+  async function ack(scope, key, event, leaseId, accepted) {
+    await storage.atomic(scope, key, previous => {
+      if (!previous || previous.scope !== scope || previous.leaseId !== leaseId)
+        return { state: previous, result: null };
+      const state = { ...previous, leaseId: null, leaseUntilMs: 0 };
+      if (accepted) state[event === "started" ? "startedReported" : "terminalReported"] = true;
+      return { state, result: null };
+    });
+  }
+  async function drain(scope, key) {
+    while (true) {
+      const next = await lease(scope, key);
+      if (!next) return;
+      if (activeReports >= 4) await new Promise(resolve => reportWaiters.push(resolve));
+      activeReports++;
+      let accepted = false;
+      try { await reportGeneration(next.jobId, next.event); accepted = true; }
+      catch { diagnostic("generation_report_unavailable"); }
+      finally { activeReports--; reportWaiters.shift()?.(); }
+      await ack(scope, key, next.event, next.leaseId, accepted);
+      if (!accepted) return;
+    }
+  }
+  async function reconcilePending(projectId, surfaceId) {
+    if (!ID.test(projectId || "") || !ID.test(surfaceId || "")) throw new Error("publisher_turn_scope_invalid");
+    const scope = createHash("sha256").update(JSON.stringify([projectId, surfaceId])).digest("hex");
+    if (typeof storage.prune === "function" && await storage.prune(scope) > 0)
+      diagnostic("generation_report_retention_expired");
+    let cursor = "";
+    while (true) {
+      const keys = await storage.scan(scope, cursor, 100);
+      if (!Array.isArray(keys) || keys.length > 100 || keys.some((key, index) => typeof key !== "string" ||
+        !/^[a-f0-9]{64}$/.test(key) || key <= (index ? keys[index - 1] : cursor)))
+        throw new Error("publisher_turn_scan_invalid");
+      if (keys.length === 0) return;
+      await Promise.all(keys.map(key => drain(scope, key)));
+      cursor = keys.at(-1);
+    }
+  }
+  return { claimPlacement, releaseRejectedPlacement, bind, claimGeneration, phase, reconcilePending };
+}

package/examples/next-js/.env.example

@@ -0,0 +1,6 @@
+WAVEBIRD_API_BASE_URL=https://api.wavebird.ai
+WAVEBIRD_CLIENT_ID=wbproj_replace_from_dashboard
+WAVEBIRD_SECRET_KEY=sk_test_replace_from_dashboard
+WAVEBIRD_PREFERENCE_SECRET=replace_with_at_least_32_random_characters
+PUBLISHER_AUTH_CHECK_PATH=/api/your-existing-session-check
+WAVEBIRD_PUBLIC_ORIGINS=

package/examples/next-js/app/api/generate/route.js

@@ -0,0 +1,6 @@
+import { getPublisher } from "../../../lib/publisher.js";
+import { existingGeneration } from "../../../lib/model.js";
+
+export async function POST(request) {
+  return getPublisher().withGeneration({ request, run: existingGeneration });
+}

package/examples/next-js/app/api/sponsor-consent/route.js

@@ -0,0 +1,4 @@
+import { getPublisher } from "../../../lib/publisher.js";
+
+export const GET = (request) => getPublisher().consentGET(request);
+export const POST = (request) => getPublisher().consentPOST(request);

package/examples/next-js/app/api/sponsor-session/route.js

@@ -0,0 +1,5 @@
+import { getPublisher } from "../../../lib/publisher.js";
+
+export async function GET(request) {
+  return getPublisher().sessionGET(request);
+}

package/examples/next-js/app/api/sponsor-slot/route.js

@@ -0,0 +1,3 @@
+import { getPublisher } from "../../../lib/publisher.js";
+
+export const POST = (request) => getPublisher().placementPOST(request);

package/examples/next-js/app/layout.jsx

@@ -0,0 +1,3 @@
+export default function RootLayout({ children }) {
+  return <html lang="en"><body>{children}</body></html>;
+}

package/examples/next-js/app/page.jsx

@@ -0,0 +1,70 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { createPublisherAds } from "@wavebirdai/api/browser";
+
+export default function Page() {
+  const slot = useRef(null);
+  const ads = useRef(null);
+  const abort = useRef(null);
+  const [answer, setAnswer] = useState("");
+  useEffect(() => {
+    if (!slot.current) return;
+    const controller = new AbortController();
+    let disposed = false;
+    let current = null;
+    void fetch("/api/sponsor-session", { cache: "no-store", signal: controller.signal }).then(async response => {
+      if (!response.ok) return;
+      const sessionId = (await response.json()).session_id;
+      if (disposed || !/^[A-Za-z0-9_-]{1,128}$/.test(sessionId)) return;
+      current = createPublisherAds({
+      target: slot.current,
+      clientId: "wbproj_replace_from_dashboard",
+      surfaceId: "chat_assistant",
+      jobType: "chat",
+      timing: "during",
+      consentMode: "wavebird_consent",
+      userId: "replace-with-authenticated-user-id",
+      conversationId: "replace-with-current-conversation-id",
+      sessionId,
+      turnBinding: true,
+      rendererUrl: "https://api.wavebird.ai/v1/render.js",
+      placementEndpoint: "/api/sponsor-slot",
+      consentEndpoint: "/api/sponsor-consent",
+      privacySettingsTarget: "#privacy-settings"
+      });
+      ads.current = current;
+    }).catch(() => {});
+    return () => { disposed = true; controller.abort(); abort.current?.abort(); current?.dispose(); ads.current = null; };
+  }, []);
+  async function generate() {
+    if (!ads.current) return;
+    const current = new AbortController();
+    abort.current = current;
+    setAnswer("");
+    try {
+      await ads.current.connectGeneration({
+        signal: current.signal,
+        request: headers => fetch("/api/generate", { method: "POST", headers, signal: current.signal }),
+        consume: async (response, lifecycle) => {
+          if (!response.ok || !response.body) throw new Error("generation_unavailable");
+          const reader = response.body.getReader();
+          const decoder = new TextDecoder();
+          while (true) {
+            const next = await reader.read();
+            if (next.done) break;
+            setAnswer(value => value + decoder.decode(next.value, { stream: true }));
+            lifecycle.onDelta();
+          }
+        }
+      });
+    } catch { setAnswer(value => value || "Generation unavailable."); }
+  }
+  return <main style={{ maxWidth: 760, margin: "2rem auto" }}>
+    <h1>Publisher chat</h1>
+    <button id="privacy-settings" type="button">Sponsored choices</button>
+    <p aria-live="polite">{answer}</p>
+    <section ref={slot} aria-label="Sponsored placement area" style={{ width: "100%", maxWidth: 728, height: 346, margin: "1rem auto" }} />
+    <div><button type="button" onClick={generate}>Generate</button><button type="button" onClick={() => abort.current?.abort()}>Stop</button></div>
+  </main>;
+}

package/examples/next-js/lib/auth.js

@@ -0,0 +1,33 @@
+import "server-only";
+
+const cache = new WeakMap();
+const ID = /^[A-Za-z0-9_-]{1,128}$/;
+
+/** Resolve a non-credential correlation ID from the app's authenticated session. */
+export function sessionIdForRequest(request) {
+  const prior = cache.get(request);
+  if (prior) return prior;
+  const pending = (async () => {
+    const path = process.env.PUBLISHER_AUTH_CHECK_PATH;
+    if (!path || !/^\/(?!\/)[A-Za-z0-9/_-]+$/.test(path) ||
+        path.startsWith("/api/sponsor") || path === "/api/generate") return null;
+    try {
+      const requestOrigin = new URL(request.url).origin;
+      const trustedOrigin = (process.env.WAVEBIRD_PUBLIC_ORIGINS ?? "").split(",")
+        .map(value => value.trim()).find(value => value === requestOrigin);
+      if (!trustedOrigin) return null;
+      const result = await fetch(new URL(path, trustedOrigin), {
+        headers: { cookie: request.headers.get("cookie") || "" },
+        cache: "no-store", redirect: "manual", signal: AbortSignal.timeout(1500),
+      });
+      const id = result.headers.get("x-publisher-session-id");
+      return result.status === 204 && ID.test(id || "") ? id : null;
+    } catch { return null; }
+  })();
+  cache.set(request, pending);
+  return pending;
+}
+
+export async function authorizePublisherRequest(request) {
+  return (await sessionIdForRequest(request)) !== null;
+}

package/examples/next-js/lib/model.js

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

package/examples/next-js/lib/publisher.js

@@ -0,0 +1,37 @@
+import "server-only";
+import { createPublisherServer, createPublisherTurnJournal, derivePublisherTurnKeySecret } from "@wavebirdai/api/server";
+import { authorizePublisherRequest, sessionIdForRequest } from "./auth.js";
+import { publisherTurnStorage } from "./turn-store.js";
+
+let publisher;
+
+export function getPublisher() {
+  if (publisher) return publisher;
+  const turnJournal = createPublisherTurnJournal({
+    storage: publisherTurnStorage(),
+    keySecret: derivePublisherTurnKeySecret(process.env.WAVEBIRD_PREFERENCE_SECRET ?? ""),
+    reportGeneration: (jobId, event) => getPublisher().reportGeneration(jobId, event),
+  });
+  return publisher = createPublisherServer({
+  apiBaseUrl: process.env.WAVEBIRD_API_BASE_URL,
+  clientId: process.env.WAVEBIRD_CLIENT_ID,
+  secretKey: process.env.WAVEBIRD_SECRET_KEY,
+  preferenceSecret: process.env.WAVEBIRD_PREFERENCE_SECRET,
+  authorize: authorizePublisherRequest,
+  sessionIdForRequest,
+  turnJournal,
+  publicOrigins: (process.env.WAVEBIRD_PUBLIC_ORIGINS ?? "").split(",").map(value => value.trim()).filter(Boolean),
+  surfaceId: "chat_assistant",
+  placementKey: "default",
+  jobType: "chat",
+  locale: "en-US",
+  timing: "during",
+  consentMode: "wavebird_consent",
+  gdprApplies: true,
+  publisher: { app_name: "Your saved app name", app_domain: "your.example", categories: [] },
+  allowedFormats: ["banner"],
+  positionHint: "between",
+  allowedSizes: [{ width: 728, height: 90 }, { width: 320, height: 50 }],
+  responsiveSizeSelection: true
+  });
+}

package/examples/next-js/lib/turn-store.js

@@ -0,0 +1,9 @@
+import "server-only";
+
+/** Replace this fail-closed stub with createPostgresTurnStorage(your existing pg pool). */
+export function publisherTurnStorage() {
+  return {
+    async atomic() { throw new Error("Connect your existing durable turn store"); },
+    async scan() { throw new Error("Connect your existing durable turn store"); },
+  };
+}

package/examples/next-js/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "wavebird-api-next-js-example",
+  "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" }
+}

package/examples/next-ts/.env.example

@@ -0,0 +1,6 @@
+WAVEBIRD_API_BASE_URL=https://api.wavebird.ai
+WAVEBIRD_CLIENT_ID=wbproj_replace_from_dashboard
+WAVEBIRD_SECRET_KEY=sk_test_replace_from_dashboard
+WAVEBIRD_PREFERENCE_SECRET=replace_with_at_least_32_random_characters
+PUBLISHER_AUTH_CHECK_PATH=/api/your-existing-session-check
+WAVEBIRD_PUBLIC_ORIGINS=

package/examples/next-ts/app/api/generate/route.ts

@@ -0,0 +1,6 @@
+import { getPublisher } from "../../../lib/publisher";
+import { existingGeneration } from "../../../lib/model";
+
+export async function POST(request: Request): Promise<Response> {
+  return getPublisher().withGeneration({ request, run: existingGeneration });
+}

package/examples/next-ts/app/api/sponsor-consent/route.ts

@@ -0,0 +1,4 @@
+import { getPublisher } from "../../../lib/publisher";
+
+export const GET = (request: Request): Promise<Response> => getPublisher().consentGET(request);
+export const POST = (request: Request): Promise<Response> => getPublisher().consentPOST(request);

package/examples/next-ts/app/api/sponsor-session/route.ts

@@ -0,0 +1,5 @@
+import { getPublisher } from "../../../lib/publisher";
+
+export async function GET(request: Request): Promise<Response> {
+  return getPublisher().sessionGET(request);
+}

package/examples/next-ts/app/api/sponsor-slot/route.ts

@@ -0,0 +1,3 @@
+import { getPublisher } from "../../../lib/publisher";
+
+export const POST = (request: Request): Promise<Response> => getPublisher().placementPOST(request);

package/examples/next-ts/app/layout.tsx

@@ -0,0 +1,5 @@
+import type { ReactNode } from "react";
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return <html lang="en"><body>{children}</body></html>;
+}

package/examples/next-ts/app/page.tsx

@@ -0,0 +1,71 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { createPublisherAds, type PublisherAds } from "@wavebirdai/api/browser";
+
+export default function Page() {
+  const slot = useRef<HTMLElement | null>(null);
+  const ads = useRef<PublisherAds | null>(null);
+  const abort = useRef<AbortController | null>(null);
+  const [answer, setAnswer] = useState("");
+  useEffect(() => {
+    if (!slot.current) return;
+    const target = slot.current;
+    const controller = new AbortController();
+    let disposed = false;
+    let current: PublisherAds | null = null;
+    void fetch("/api/sponsor-session", { cache: "no-store", signal: controller.signal }).then(async response => {
+      if (!response.ok) return;
+      const sessionId = (await response.json()).session_id;
+      if (disposed || !/^[A-Za-z0-9_-]{1,128}$/.test(sessionId)) return;
+      current = createPublisherAds({
+      target,
+      clientId: "wbproj_replace_from_dashboard",
+      surfaceId: "chat_assistant",
+      jobType: "chat",
+      timing: "during",
+      consentMode: "wavebird_consent",
+      userId: "replace-with-authenticated-user-id",
+      conversationId: "replace-with-current-conversation-id",
+      sessionId,
+      turnBinding: true,
+      rendererUrl: "https://api.wavebird.ai/v1/render.js",
+      placementEndpoint: "/api/sponsor-slot",
+      consentEndpoint: "/api/sponsor-consent",
+      privacySettingsTarget: "#privacy-settings"
+      });
+      ads.current = current;
+    }).catch(() => {});
+    return () => { disposed = true; controller.abort(); abort.current?.abort(); current?.dispose(); ads.current = null; };
+  }, []);
+  async function generate() {
+    if (!ads.current) return;
+    const current = new AbortController();
+    abort.current = current;
+    setAnswer("");
+    try {
+      await ads.current.connectGeneration({
+        signal: current.signal,
+        request: headers => fetch("/api/generate", { method: "POST", headers, signal: current.signal }),
+        consume: async (response, lifecycle) => {
+          if (!response.ok || !response.body) throw new Error("generation_unavailable");
+          const reader = response.body.getReader();
+          const decoder = new TextDecoder();
+          while (true) {
+            const next = await reader.read();
+            if (next.done) break;
+            setAnswer(value => value + decoder.decode(next.value, { stream: true }));
+            lifecycle.onDelta();
+          }
+        }
+      });
+    } catch { setAnswer(value => value || "Generation unavailable."); }
+  }
+  return <main style={{ maxWidth: 760, margin: "2rem auto" }}>
+    <h1>Publisher chat</h1>
+    <button id="privacy-settings" type="button">Sponsored choices</button>
+    <p aria-live="polite">{answer}</p>
+    <section ref={slot} aria-label="Sponsored placement area" style={{ width: "100%", maxWidth: 728, height: 346, margin: "1rem auto" }} />
+    <div><button type="button" onClick={generate}>Generate</button><button type="button" onClick={() => abort.current?.abort()}>Stop</button></div>
+  </main>;
+}

package/examples/next-ts/lib/auth.ts

@@ -0,0 +1,33 @@
+import "server-only";
+
+const cache = new WeakMap<Request, Promise<string | null>>();
+const ID = /^[A-Za-z0-9_-]{1,128}$/;
+
+/** Resolve a non-credential correlation ID from the app's authenticated session. */
+export function sessionIdForRequest(request: Request): Promise<string | null> {
+  const prior = cache.get(request);
+  if (prior) return prior;
+  const pending = (async () => {
+    const path = process.env.PUBLISHER_AUTH_CHECK_PATH;
+    if (!path || !/^\/(?!\/)[A-Za-z0-9/_-]+$/.test(path) ||
+        path.startsWith("/api/sponsor") || path === "/api/generate") return null;
+    try {
+      const requestOrigin = new URL(request.url).origin;
+      const trustedOrigin = (process.env.WAVEBIRD_PUBLIC_ORIGINS ?? "").split(",")
+        .map(value => value.trim()).find(value => value === requestOrigin);
+      if (!trustedOrigin) return null;
+      const result = await fetch(new URL(path, trustedOrigin), {
+        headers: { cookie: request.headers.get("cookie") || "" },
+        cache: "no-store", redirect: "manual", signal: AbortSignal.timeout(1500),
+      });
+      const id = result.headers.get("x-publisher-session-id");
+      return result.status === 204 && ID.test(id || "") ? id : null;
+    } catch { return null; }
+  })();
+  cache.set(request, pending);
+  return pending;
+}
+
+export async function authorizePublisherRequest(request: Request): Promise<boolean> {
+  return (await sessionIdForRequest(request)) !== null;
+}

package/examples/next-ts/lib/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");
+}

package/examples/next-ts/lib/publisher.ts

@@ -0,0 +1,37 @@
+import "server-only";
+import { createPublisherServer, createPublisherTurnJournal, derivePublisherTurnKeySecret } from "@wavebirdai/api/server";
+import { authorizePublisherRequest, sessionIdForRequest } from "./auth";
+import { publisherTurnStorage } from "./turn-store";
+
+let publisher: ReturnType<typeof createPublisherServer> | null = null;
+
+export function getPublisher(): ReturnType<typeof createPublisherServer> {
+  if (publisher) return publisher;
+  const turnJournal = createPublisherTurnJournal({
+    storage: publisherTurnStorage(),
+    keySecret: derivePublisherTurnKeySecret(process.env.WAVEBIRD_PREFERENCE_SECRET ?? ""),
+    reportGeneration: (jobId, event) => getPublisher().reportGeneration(jobId, event),
+  });
+  return publisher = createPublisherServer({
+  apiBaseUrl: process.env.WAVEBIRD_API_BASE_URL,
+  clientId: process.env.WAVEBIRD_CLIENT_ID ?? "",
+  secretKey: process.env.WAVEBIRD_SECRET_KEY ?? "",
+  preferenceSecret: process.env.WAVEBIRD_PREFERENCE_SECRET ?? "",
+  authorize: authorizePublisherRequest,
+  sessionIdForRequest,
+  turnJournal,
+  publicOrigins: (process.env.WAVEBIRD_PUBLIC_ORIGINS ?? "").split(",").map(value => value.trim()).filter(Boolean),
+  surfaceId: "chat_assistant",
+  placementKey: "default",
+  jobType: "chat",
+  locale: "en-US",
+  timing: "during",
+  consentMode: "wavebird_consent",
+  gdprApplies: true,
+  publisher: { app_name: "Your saved app name", app_domain: "your.example", categories: [] },
+  allowedFormats: ["banner"],
+  positionHint: "between",
+  allowedSizes: [{ width: 728, height: 90 }, { width: 320, height: 50 }],
+  responsiveSizeSelection: true
+  });
+}

package/examples/next-ts/lib/turn-store.ts

@@ -0,0 +1,10 @@
+import "server-only";
+import type { PublisherAtomicTurnStorage } from "@wavebirdai/api/server";
+
+/** Replace this fail-closed stub with createPostgresTurnStorage(your existing pg pool). */
+export function publisherTurnStorage(): PublisherAtomicTurnStorage {
+  return {
+    async atomic<T>(): Promise<T> { throw new Error("Connect your existing durable turn store"); },
+    async scan(): Promise<string[]> { throw new Error("Connect your existing durable turn store"); },
+  };
+}

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.10",
+  "private": false,
+  "type": "module",
+  "description": "Integrate Banner, Native, and Clip placements into authenticated chat apps with server-side keys, 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" },
+  "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"
+  }
+}