SDK Server Integration

ADVANCED

Direct Node/server usage of @csl/wrapper-sdk and CslClient for job creation, decision reads, generation reporting, and beacon sending.

Use it only when you want the released package surface with typed lifecycle methods instead of the shorter Server API default.

Inside the SDK section, this is the clearest package path. Product-facing onboarding still lives under /api.

For new integrations, use the Server API default first

The shortest production path is documented under Server API: call /v1/placements and render with the hosted render.js flow. Stay on this SDK page only when the package surface is an intentional requirement.

Included today

@csl/wrapper-sdk
createJob()
getDecision()
reportGeneration()
sendBeacon()

Verified source

README quickstart
SDK tests
Package smoke

Use this page when you want the complete server-side lifecycle in one place instead of the shorter quickstart snippet.

The example below stays on the direct CslClient path: initialize once, create the job, report generation, read the decision, send a beacon on fill, and finish the lifecycle.

node-server.ts

typescript

ADVANCED

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

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

const job = await client.createJob({
  job_type: "chat",
  context: {
    topic: "programming",
  },
});

if (job?.slot_ids[0]) {
  await client.reportGeneration(job.job_id, "started", {
    generation_id: `gen_${job.job_id}`,
    model_id: "gpt-4o-mini",
  });

  const decision = await client.getDecision(job.slot_ids[0]);

  if (decision?.fill === true) {
    await client.sendBeacon({
      beacon_id: `rendered-${Date.now()}`,
      asset_token: decision.asset_token,
      beacon_type: "rendered",
      occurred_at_ms_client: Date.now(),
    });
  }

  await client.reportGeneration(job.job_id, "finished", {
    generation_id: `gen_${job.job_id}`,
    model_id: "gpt-4o-mini",
  });
}

Use API Quickstart for the default working setup, SDK Quickstart for the package setup, Integration flow for the step-by-step lifecycle, and CslClient reference for signatures and type-level details.

Patterns overview

SDK Browser Integration

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.