Type reference
The sections below collect the released SDK type documentation, including configuration, decision, lifecycle, beacon, and error types.
Overview
WavebirdClientOptions
Constructor options for WavebirdClient, including baseUrl, server getApiKey, browser getPublishableKey, delivery mode, timing, onError, and wrapper_version.
DecisionDeliveryMode
The four supported delivery modes: auto, websocket, polling, and callback.
WavebirdSdkError
Structured SDK error object emitted through options.onError when transport, parsing, timeout, or internal failures are observed.
WavebirdSdkErrorCode
Machine-readable error-code enum for HTTP, network, timeout, WebSocket, parse, and internal failures.
ConsentFlags
Optional privacy and consent flags used by createJob().
JobRequest
Create-job request shape. Start with job_type, then add optional consent, context, slot configuration, brand safety, routing, or callback settings as needed.
JobResponse
Union of accepted job metadata and the typed rate_limit_exceeded result returned by createJob().
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
WavebirdClientOptions
Constructor options for WavebirdClient, including baseUrl, server getApiKey, browser getPublishableKey, 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.
WavebirdSdkError
Structured SDK error object emitted through options.onError when transport, parsing, timeout, or internal failures are observed.
WavebirdSdkErrorCode
Machine-readable error-code enum for HTTP, network, timeout, WebSocket, parse, and internal failures.
Jobs and decisions
ConsentFlags
Optional privacy and 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. Start with job_type, then add optional consent, context, slot configuration, brand safety, routing, or callback settings as needed.
JobResponse
Union of accepted job metadata and the typed rate_limit_exceeded result returned by createJob().
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 }.
WavebirdClientOptions
Released package surface
Every SDK HTTP request sends x-csl-wrapper-version: <wrapper_version> as a wire-protocol header. decisionDelivery defaults to "auto", and timing values are clamped to safe ranges.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
baseUrl | string | yes | none | Base wavebird API URL. A trailing slash is normalized away. |
getApiKey | () => string | Promise<string> | server only | none | Server-side secret key resolver for wrapper-authenticated requests. Use a sandbox sk_test_... key first, then switch to a live key after production readiness is approved. |
getPublishableKey | () => string | Promise<string> | browser only | none | Browser-safe publishable key resolver. The SDK exchanges this for an activation token after the request origin matches the allowed origins configured in the dashboard. |
publishableKey | string | browser only | none | Static browser-safe publishable key alternative to getPublishableKey. Use only publishable keys in browser code. |
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: WavebirdSdkError) => 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 WavebirdSdkError 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 wavebird runtime 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. |
Choose hosted defaults or package control
These pages document the package layer for teams that choose wavebird to control ad requests, decisions, rendering helpers, consent, and beacons directly. Use the API docs for hosted defaults, and use contact only when you want rollout review, enterprise coordination, or help with non-standard integration constraints. Beacon billing rules live in SDK Concepts.