Configuration reference
The reference below documents the released constructor and payload fields that are safe to explain publicly today.
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> | server only | none | Server-side secret key resolver for wrapper-authenticated requests. |
getPublishableKey | () => string | Promise<string> | browser only | none | Browser-safe publishable key resolver. The SDK exchanges this for an activation token before runtime calls. |
publishableKey | string | browser only | none | Static browser-safe publishable key alternative to getPublishableKey. |
decisionDelivery | "auto" | "websocket" | "polling" | "callback" | no | "auto" | Decision delivery strategy for the client. |
publisher | { app_name?: string; app_domain?: string; app_bundle?: string; categories?: string[] } | no | none | Optional publisher metadata automatically merged into every createJob() request. |
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
job_type is required and slots_requested defaults to 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. |
slots_requested | number | no | 1 | Number of requested slots. |
model_id | string | no | "unknown" | Optional model identifier for the job. |
locale | string | no | "en" | Optional 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. |
prompt | { text?: string; token_count_estimate?: number } | string | no | none | Optional prompt payload. Sent to the CSL for topic extraction only when you choose to provide it. The data firewall reduces this to an abstract category and language before any signal reaches a configured partner path. Raw text is never forwarded. |
context.topic | string | no | none | Optional topic hint when you do not want to share prompt text. |
context.prompt_text | string | no | none | Optional prompt alias for integrations that separate explicit context from prompt capture. |
consent | ConsentFlags | no | server defaults | Optional consent flags for semantic targeting, prompt sharing, GDPR, wrapper-CMP TCF, GPP, and legacy US privacy. |
publisher | { app_name?: string; app_domain?: string; app_bundle?: string; categories?: string[] } | no | constructor defaults if configured | Optional publisher metadata automatically merged from the client constructor when configured. |
slot_config | { allowed_formats?: ("banner" | "clip" | "native")[]; max_width?: number; max_height?: number; position_hint?: string; bidfloor?: number; bidfloorcur?: string } | no | none | Optional format, size, placement, and bidfloor hints. |
brand_safety | { blocked_categories?: string[]; blocked_domains?: string[] } | no | none | Optional blocking controls for categories and advertiser domains. |
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. |
Configuration changes
Updating your project's app_domain in the dashboard immediately rewrites allowed_origins on active publishable keys for that project.
Secret keys remain valid because browser origin checks do not apply to server-side auth. If the same domain update also reflects a server deployment or ownership change, rotate the affected secret keys in the dashboard so consumers pick up a replacement key while the previous key stays valid for 24 hours.
Use this when your wrapper domain changes between preview and production, or when you move to a new canonical app host.
Rate limits
Each API key has a configurable rate limit. The default is 100 requests per minute per key. When the limit is exceeded, createJob() does not throw. It returns a typed fail-soft result instead:
rate-limit.json
json
View and adjust rate limits in the dashboard under Settings → API Keys → Advanced.
Related docs: Testing and Troubleshooting.
API first, Script Tag second, SDK third
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.