Type reference
The sections below collect the released SDK type documentation, including configuration, decision, lifecycle, beacon, and error types.
Overview
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.
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.
ConsentFlags
App consent flags used by createJob().
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.
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 }.
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 }.
CslClientOptions
Released package surface
Every SDK HTTP request sends x-csl-wrapper-version: <wrapper_version>. decisionDelivery defaults to "auto", and timing values are clamped to safe ranges.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
baseUrl | string | yes | none | Base CSL URL. A trailing slash is normalized away. |
getApiKey | () => string | Promise<string> | yes | none | Function called immediately before each SDK HTTP request to resolve the bearer token. |
decisionDelivery | "auto" | "websocket" | "polling" | "callback" | no | "auto" | Decision delivery strategy for the client. |
options.timeout_ms | number | no | 2000 | Base request timeout. Values are clamped to the documented safe range. |
options.decision_timeout_ms | number | no | 30000 | Decision wait budget. Values are clamped to the documented safe range. |
options.long_poll_wait_ms | number | no | 1500 | Long-poll wait_ms used by decision reads. |
options.short_poll_interval_ms | number | no | 250 | Short-poll interval used after long-poll attempts are exhausted. |
options.onError | (error: CslSdkError) => void | no | none | Observation hook for structured SDK errors surfaced through onError rather than thrown as hard failures. |
options.wrapper_version | string | no | "sdk" | Optional wrapper version label. Sent as x-csl-wrapper-version on every SDK request. |
JobRequest
Released public types
Prompt text must resolve to non-empty content and slots_requested must be an integer >= 1. When decisionDelivery: "callback" is used without callback_url, createJob() returns null and onError receives CslSdkError with code sdk_internal.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
job_type | string | yes | none | App job type. |
model_id | string | yes | none | Model identifier for the job. |
locale | string | yes | none | App locale. |
predicted_latency_ms | number | no | none | Optional latency hint. |
client_id | string | no | runtime-derived if omitted | Optional client id. |
chat_session_id | string | no | none | Optional chat session id. |
consent | ConsentFlags | yes | none | Consent flags for the app. |
prompt | { text: string; token_count_estimate?: number } | string | yes | none | Prompt payload. Sent to the CSL for topic extraction. The data firewall reduces this to an abstract category and language before any signal reaches the ad market. Raw text is never forwarded. |
slots_requested | number | yes | none | Number of requested slots. |
ssp_partner_id | string | no | none | Legacy single-partner selector for advanced routing cases. |
routing.preferred_partner_id | string | no | none | Preferred routing hint for new integrations. |
routing.candidate_partner_ids | string[] | no | none | Optional routing hint list for candidate partners. |
callback_url | string | no | none | Callback target for callback delivery. |
GenerationRequest
Released public types
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
generation_id | string | no | none | Identifier for the model generation. |
model_id | string | no | none | Reported model identifier. |
usage_json | unknown | no | none | Usage payload for finished or failed. |
error | string | no | none | Failure detail for the failed path. |
BeaconRequest
Released public types
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
beacon_id | string | yes | none | Idempotency input for the beacon. |
asset_token | string | yes | none | Asset authenticator for fill beacons. |
beacon_type | "rendered" | "visible_started" | "visible_ended" | "heartbeat" | "play_started" | "play_completed" | "clicked" | yes | none | Beacon type for render, visibility, playback, or click events. |
occurred_at_ms_client | number | yes | none | Client timestamp for the event. |
measurements | Record<string, unknown> | no | none | Optional measurements bag. |
Ask about integration
Start with Node direct for the recommended production-ready integration path.