wavebird SDK
This page documents the released @csl/wrapper-sdk package for teams integrating the CSL public wrapper API from Node/server or browser environments.
terminal
bash
npm install @csl/wrapper-sdkRelease status
@csl/wrapper-sdk is installable and fully functional, but not yet connected to the live ad market. You can integrate it, explore the full sponsoring lifecycle, and see exactly how it works. The first SSP connection is being completed before general availability. We publish early because we build in the open.
On this page
Quick Start
Start here, then go deeper on the dedicated page
The SDK root page now stays intentionally compact. It shows the happy-path integration and then sends you to the matching subpage for implementation details.
node-server.ts
typescript
import { CslClient } from "@csl/wrapper-sdk";
const client = new CslClient({
baseUrl: process.env.CSL_BASE_URL ?? "http://127.0.0.1:3000",
getApiKey: () => process.env.CSL_WRAPPER_API_KEY ?? "",
decisionDelivery: "polling",
});
const job = await client.createJob({
job_type: "chat",
model_id: "gpt-4o-mini",
locale: "en-US",
consent: {
semantic_targeting: true,
session_persistence: false,
cross_session_persistence: false,
},
prompt: { text: "I want a travel deal for a weekend trip." },
slots_requested: 1,
});
const decision = job?.slot_ids[0] ? await client.getDecision(job.slot_ids[0]) : null;
console.log(decision);What you get back
decision.ts
typescript
if (decision?.fill) {
console.log(decision.creative);
console.log(decision.constraints);
console.log(decision.cs_declaration);
} else {
console.log(decision?.reason ?? "pending");
}Installation
Install once, then choose the runtime entry
The detail pages keep the runtime-specific guidance. The root page only shows the package boundary and where to continue reading.
terminal
bash
npm install @csl/wrapper-sdkNode / server
@csl/wrapper-sdk
Browser
@csl/wrapper-sdk/browser
Info
TypeScript types are included. `options.wrapper_version` propagates through `x-csl-wrapper-version` on SDK requests.
Use `/sdk/configuration` for the full option table and `/sdk/patterns` for runtime-specific examples.
Core Concepts
Read the mental model once, then keep building
The detailed concept explanations live on the Concepts subpage. Here you just get the orientation layer.
Jobs and Slots
A job is the app-created unit of work. createJob() returns job_id plus one or more slot_ids, and each slot is resolved through getDecision(slotId).
Decisions and Beacons
A DecisionResponse can be pending, no-fill, or fill. After fill, sendBeacon() records wrapper events such as rendered, clicked, visible_started, and visible_ended.
Delivery Modes
Use the root page to choose, the pattern pages to implement
The root page should not repeat every full example. It shows the supported modes and points you to the matching pattern page.
Node direct
COREDirect Node/server usage of @csl/wrapper-sdk and CslClient for job creation, decision reads, generation reporting, and beacon sending.
This is the best first path for apps that want the released wrapper client surface with the smallest integration footprint.
Browser entry
TESTEDDirect browser usage of @csl/wrapper-sdk/browser with the same CslClient surface.
It fits when the browser can talk to CSL directly and your token-delivery plus CORS setup supports that boundary.
Callback delivery
ADVANCEDA server-side path where CSL posts the decision to a callback_url.
It fits apps that want signed webhook-style decision delivery and control over callback handling on the server side.
Proxy compatibility
COMPATIBLEAn HTTP/API path where the app sends OpenAI-compatible or Anthropic-compatible requests directly to CSL proxy routes.
It fits systems that already emit upstream-shaped HTTP requests and do not want to start with CslClient.
Evidence & Performance
Keep the benchmark headlines visible, not buried
The headline numbers remain on the root page, while the broader evidence story stays linked to the dedicated evidence resource.
Benchmark headlines
March 23, 2026
Firewall p99 latency
Filtering step before any ad request leaves the runtime.
Mock-SSP round-trip p99 latency
Internal ad path against a controlled exchange substitute.
End-to-end p99 latency
Measured runtime path with external model wait time excluded.
Pre-pilot campaign
March 30, 2026
Proof integrity
Processed at c100 with 0 missing proofs.
Settlement accuracy
6 scenarios with exact reconciliation.
Concurrency tested
Graceful degradation under spike load.
Sustained load
Processed over 8 hours with 0 proof gaps.
Info
Measured on a local host benchmark harness with Mock-SSP and without external GenAI wait time; this is reproducible engineering benchmark evidence, not a production SLA, internet-wide latency claim, or third-party audit.
The SDK is fully functional and verified. The remaining step before general availability is the connection to the first live SSP partner.
Last updated: 2026-04-01
Ask about integration
Start with Node direct for the recommended production-ready integration path.