Advanced SDK

Deep package docs for teams that intentionally use `@csl/wrapper-sdk`.

The API is the primary integration surface. This section exists for advanced TypeScript, React, migration, and compatibility use cases that need the released SDK package in depth.

Start with API docs unless you already know that you need typed client ergonomics, React helpers, migration compatibility, or direct package-level control.

$ npm install @csl/wrapper-sdk

Back to API docs →Get your API key →Read SDK quickstart →Troubleshooting →

The SDK surface is live and documented as an advanced compatibility layer. Primary product-facing onboarding remains API-first.

Three Steps

From key to first impression.

Start with the API

New Server API integrations should use POST /v1/placements and the hosted renderer first.

Open API quickstart →

Choose SDK only if needed

Use @csl/wrapper-sdk for typed package ergonomics, migration compatibility, or package-level control after the API model is clear.

SDK install →

Keep rendering hosted

The default frontend still uses render.js and wavebird.withTurn(). SDK UI helpers are compatibility surfaces.

Server API pattern →

The Code

Advanced package example in two blocks.

server.ts

typescript

SERVER

import { CslClient } from "@csl/wrapper-sdk";

const client = new CslClient({
  baseUrl: "https://api.wavebird.ai",
  getApiKey: () => process.env.WAVEBIRD_SECRET_KEY ?? "",
  decisionDelivery: "polling",
  publisher: {
    app_name: "MyAIChatApp",
    app_domain: "mychatapp.com",
    categories: ["IAB19"],
  },
});

// Minimal working call:
const { slot_ids } = await client.createJob({
  job_type: "chat",
});

const decision = await client.getDecision(slot_ids[0]);
// Pass decision to your frontend

AdSlot.tsx

typescript

WIDGET

import { WavebirdAd } from "@csl/wrapper-sdk/react";

function AdSlot({ decision, sendBeacon }) {
  return (
    <WavebirdAd
      decision={decision}
      sendBeacon={sendBeacon}
    />
  );
}

// That's it. Rendering, beacon tracking,
// and billing are all automatic.

ⓘThe WavebirdAd widget handles the full beacon sequence automatically. You only need to call sendBeacon manually if you build a custom renderer. Beacon billing rules →

Show vanilla JS version ▼

ad-slot.js

typescript

VANILLA

import { mountWavebirdAd } from "@csl/wrapper-sdk/mount";

const unmount = mountWavebirdAd({
  target: document.getElementById("ad-slot"),
  decision: decision,
  sendBeacon: async (req) => {
    await fetch("/api/beacon", {
      method: "POST",
      body: JSON.stringify(req),
    });
  },
});

What You Need

The setup checklist.

✓

An API key from the wavebird dashboard

Your API key authenticates SDK requests. Secret keys -> server-side. Publishable keys -> browser-side.

✓

Node.js 18+ or a modern browser

✓

A GenAI app that handles user prompts

Chat apps, copilots, coding assistants, vertical AI tools.

Platforms

Supported platforms

Platform	Status	Entry point
Node.js 18+	Supported	@csl/wrapper-sdk
Browser (React, Vue, Svelte)	Supported	@csl/wrapper-sdk/react
Browser (vanilla JS)	Supported	@csl/wrapper-sdk/mount
Next.js (App Router)	Supported	Server: @csl/wrapper-sdk, Client: /react
React Native	Unsupported	No official test coverage or examples in the current release
Electron	Unsupported	No official test coverage or examples in the current release
Deno	Not supported	-

Performance

Lightweight and non-blocking.

Metric	Value
Bundle size (server, gzip)	4.42 kB
Bundle size (react, gzip)	2.69 kB
Bundle size (mount, gzip)	2.69 kB
Client creation heap delta	304.7 kB
Cold start to first decision	27.87 ms

createJob() and getDecision() are async request methods and do not block the UI thread. The Node SDK has zero external runtime dependencies. The default request timeout is 2000ms, clamped to250..30000ms; the default decision budget is 30000ms.

API Surface

The app-facing surface.

Import	What it does
new CslClient(options)	Initialize with baseUrl + API key
client.createJob(request)	Start a sponsoring slot
client.getDecision(slotId)	Get fill, no-fill, or pending
client.reportGeneration(jobId, ...)	Track model start/finish/fail
client.sendBeacon(request)	Report render/click/visibility
<WavebirdAd /> (React)	Auto-render + auto-track widget
mountWavebirdAd() (vanilla JS)	Same widget, no React required

Full SDK reference →

Request Cadence

One prompt, one job.

Request a new ad when the user sends a new prompt. wavebird does not auto-refresh ads on a timer, and the SDK does not rotate creatives in the background.

Server-side frequency caps still apply. If a wrapper keeps creating jobs without corresponding user activity, CSL can return no-fill and flag the traffic as anomalous. If you want banner-only behavior, pass allowed_formats: ["banner"] explicitly. Native and clip are opt-in.

Integration Paths

Do not start here unless you need the package.

★ Default for new integrations: Server API

Your backend calls /v1/placements, your frontend loads render.js, and Wavebird owns media sizing, click handling, and beacons.
This is the shortest documented path for most production apps.

Use Server API default →

Advanced package path: SDK Server Integration

Use this only when your team intentionally wants CslClient, typed package methods, or an SDK migration path.

Open SDK Server Integration →

Also available: Browser Integration · Callback delivery · Proxy compatibility

All integration patterns →

How You Earn

What becomes billable.

You receive 80% of every verified ad impression.

wavebird retains 20% as platform fee.

Banner and native

rendered → visible_started → visible_ended ← billable

Clip (video)

rendered → play_started → play_completed ← billable

ⓘThe WavebirdAd widget sends the full sequence automatically. Custom renderers must follow the beacon billing guide. Billing guide →

For the SSP-facing integrity model behind these billing events, read the proof integrity whitepaper →

Get your API key →Read API quickstart →Read SDK quickstart →

Last updated: 2026-04-23

API first, Script Tag second, SDK third

Back to API docs Contact the team

These pages are the advanced package layer for teams that intentionally choose @csl/wrapper-sdk. Primary onboarding still lives in the API docs, and browser-first installs should start with the Script Tag. Use contact only when you want rollout review, enterprise coordination, or help with non-standard integration constraints. Beacon billing rules live in SDK Concepts.

Deep package docs for teams that intentionally use @csl/wrapper-sdk.

From key to first impression.

Start with the API

Choose SDK only if needed

Keep rendering hosted

Advanced package example in two blocks.

The setup checklist.

Supported platforms

Lightweight and non-blocking.

The app-facing surface.

One prompt, one job.

Do not start here unless you need the package.

What becomes billable.

API first, Script Tag second, SDK third

Deep package docs for teams that intentionally use `@csl/wrapper-sdk`.