wavebird logo

CslClient

PRODUCTION-READY

CslClient is the wrapper-facing entry point for Node/server and browser integrations. It carries the core paths for jobs, decisions, generation events, and beacons.

Public request methods are fail-silent by design. Use options.onError to observe structured CslSdkError values and machine-readable CslSdkErrorCode values.

Methods

createJob(request: JobRequest): Promise<JobResponse | null>

Creates a wrapper job and returns accepted job metadata or null on fail-silent transport or contract failure.

ParameterTypeRequiredDescription
requestJobRequestyesCreate-job payload with consent, prompt, slot count, and optional routing or callback settings.

Returns

Resolves to accepted JobResponse metadata with job_id and slot_ids, or null when the SDK falls back silently.

Notes

  • Use callback_url inside request when the job should switch to callback delivery.
  • Transport or contract failures are observed through options.onError, not thrown as hard failures.
getDecision(slotId: string, options?: { wait_ms?: number }): Promise<DecisionResponse>

Returns a normalized DecisionResponse union. Ready decisions preserve constraints and cs_declaration.

ParameterTypeRequiredDescription
slotIdstringyesOne slot id from createJob(). The SDK resolves it through polling, WebSocket, auto, or callback-aware delivery rules.
options{ wait_ms?: number }noOptional polling wait budget for direct decision reads when the integration wants to tune the long-poll request.

Returns

Resolves to DecisionResponse, which can represent pending, no-fill, or fill outcomes.

Notes

  • When decisionDelivery is "auto", the SDK prefers WebSocket where available and falls back to polling.
reportGeneration(jobId: string, event: GenerationEvent, request?: GenerationRequest): Promise<void>

Reports started, finished, or failed generation events to the public wrapper API.

ParameterTypeRequiredDescription
jobIdstringyesAccepted wrapper job id returned by createJob().
eventGenerationEventyesLifecycle stage: "started", "finished", or "failed".
requestGenerationRequestnoOptional lifecycle payload such as generation_id, model_id, usage_json, or error.

Returns

Resolves when the lifecycle event has been handed off through the public wrapper API.

Notes

  • Use the same jobId for every lifecycle update tied to one wrapper job.
sendBeacon(request: BeaconRequest): Promise<BeaconResponse>

Sends wrapper beacons such as rendered, visible_started, visible_ended, clicked, and related public beacon types.

ParameterTypeRequiredDescription
requestBeaconRequestyesPublic beacon payload with beacon id, asset_token, beacon type, client timestamp, and optional measurements.

Returns

Resolves to BeaconResponse, which acknowledges whether the beacon was accepted and may include reason_code.

Notes

  • Send beacons only after a fill decision because asset_token comes from the filled response.

Important `createJob()` fields

The table below highlights the minimum request fields most integrators need first when wiring `createJob()`.

createJob() request

Released public JobRequest shape

FieldTypeRequiredDefaultDescription
job_typestringyesnoneType of job, for example "chat".
model_idstringyesnoneModel identifier.
localestringyesnoneLocale code, for example "en-US".
consentConsentFlagsyesnoneUser consent configuration.
prompt{ text: string }yesnonePrompt context for targeting.
slots_requestednumberyesnoneNumber of sponsoring slots.

Error handling

Public methods stay fail-silent. Observe SDK failures through options.onError, then handle null or incomplete results in your integration code.

  • CslSdkError is the structured error object surfaced through options.onError.
  • CslSdkErrorCode is the machine-readable companion for transport, timeout, parse, WebSocket, HTTP, and internal failure categories.
  • Treat null from createJob() as a failed handoff and keep your app path moving without assuming a sponsored slot exists.

Documented `CslSdkErrorCode` values

  • sdk_http
  • sdk_network
  • sdk_timeout
  • sdk_websocket
  • sdk_parse
  • sdk_internal

error-handling.ts

typescript

ONERROR
const client = new CslClient({
  baseUrl: process.env.CSL_BASE_URL ?? "http://127.0.0.1:3000",
  getApiKey: () => process.env.CSL_WRAPPER_API_KEY ?? "",
  options: {
    onError: (error) => {
      console.error(error.code, error.message, error.cause);
    },
  },
});

const job = await client.createJob(request);

if (!job) {
  // Fail-silent path: inspect telemetry or your onError hook.
}

The cause field may contain the originating Error when the SDK can preserve that underlying failure context.

Package and client types

CslClientOptions

Constructor options for CslClient, including baseUrl, getApiKey, delivery mode, timing, onError, and wrapper_version.

DecisionDeliveryMode

The four supported delivery modes: auto, websocket, polling, and callback.

auto prefers WebSocket when a global WebSocket exists, falls back to polling when it does not, and switches to callback when callback_url is supplied.

CslSdkError

Structured SDK error object emitted through options.onError when transport, parsing, timeout, or internal failures are observed.

CslSdkErrorCode

Machine-readable error-code enum for HTTP, network, timeout, WebSocket, parse, and internal failures.

Jobs and decisions

ConsentFlags

App consent flags used by createJob().

In the current integration flow, these flags align with the Semantic Source and Semantic Persistence dimensions of the Compute Sponsoring standard. Setting semantic_targeting: true with both persistence flags false corresponds to the CS-S (S1/P0) profile described in the Compute Sponsoring glossary.

JobRequest

Create-job request shape. It includes consent, prompt, slot count, optional routing hints, and callback_url for callback delivery.

JobResponse

Accepted job metadata with job_id, slot_ids, and status: "accepted".

DecisionResponse

Normalized decision union for pending, ready no-fill, and ready fill. Fill preserves creative, asset_token, constraints, and cs_declaration.

Lifecycle and contracts

GenerationEvent

"started" | "finished" | "failed". This type sits behind reportGeneration().

GenerationRequest

Payload for generation lifecycle reporting. The documented fields are generation_id, model_id, usage_json, and error.

BeaconRequest

Payload for wrapper beacon events. The documented fields are beacon id, asset token, beacon type, client timestamp, and optional measurements.

BeaconResponse

Acknowledgement response for sendBeacon(). It returns { accepted, reason_code }.

Ask about integration

Ask about integration

Start with Node direct for the recommended production-ready integration path.