Headless API · SDK

Fetch Casset artist data from TypeScript.

Use one client to read public Artist and Catalog data. Add the separate React adapter only when you need React query state.

Fetch /connor

import { createCassetClient } from "@casset/apps"

const casset = createCassetClient({
  baseUrl: "http://127.0.0.1:3000",
})

const [artist, catalog] = await Promise.all([
  casset.getArtist("connor"),
  casset.getCatalog("connor"),
])

Both packages are version 0.2.0-alpha.0, repository-local, and vendored into the generated starter. Neither package is published to npm. The example uses a local Casset origin because the deployed public v1 routes are not supported for production use.

Client options

createCassetClient options
Option	Default	Accepted	Behavior
`baseUrl`	Required	HTTPS, or HTTP on localhost / 127.0.0.1 / ::1	Rejects credentials, query strings, fragments, and non-loopback HTTP.
`credential`	None	Non-empty string	Adds a Bearer header. Intended only for the local sandbox in this alpha.
`fetch`	globalThis.fetch	Fetch-compatible function	Inject one fetch implementation, or a transport—not both.
`transport`	Fetch transport	CassetTransport	Makes deterministic tests and mocks possible without network calls.
`timeoutMs`	8,000	1–60,000	Applies per attempt through AbortController.
`maxRetries`	2	0–5	Retries after the initial GET; default maximum is three total attempts.
`maxRetryAfterMs`	5,000	0–30,000	Caps Retry-After and exponential delays.
`requestIdFactory`	Generated sdk-* ID	Function returning a valid request ID	One ID is reused across every attempt and must be mirrored by the response.
`sleep`	setTimeout	Async duration function	Injectable for deterministic retry tests.

Methods

Casset client methods
Method	Returns	Notes
`getArtist(handle, options?)`	`PublicArtistResponse`	GET only. Validates the handle before transport.
`getCatalog(handle, options?)`	`PublicCatalogResponse`	GET only. Returns an empty tracks array when a public artist has no active Tracks.

Per-request options accept requestId and an externalAbortSignal. An external abort is terminal and is not retried.

Strict response parsing

The parsers require every documented field, reject unknown fields, verify schema names, enforce bounded strings and track counts, and reject unsafe public links. A malformed 2xx response becomes a non-retryableIntegrationFailure in the client. Direct parser calls throwCassetContractError with structured issues.

Request ID protocol

IDs are 8–120 characters from letters, digits, period, underscore, colon, and hyphen.
Secret-shaped values, JWT-like values, whitespace, and line breaks are rejected.
The response x-request-id must exactly match the request ID.
A missing or mismatched response ID becomes a non-retryable IntegrationFailure.

React adapter

React adapter exports
Export	Purpose	Boundary
`CassetClientProvider`	Makes one CassetClient available to descendants.	Does not create or configure a client.
`useCassetClient()`	Reads the configured client.	Throws when no provider exists.
`useCassetArtist(handle)`	Loads and shares an artist query store per client and handle.	Returns idle, loading, ready, or error plus reload().
`useCassetCatalog(handle)`	Loads and shares a Catalog query store per client and handle.	Returns the exact public Catalog contract.
`CassetHostProvider / useCassetHostSnapshot`	Native App host bindings exported by the same package.	For Casset Apps, not Headless HTTP playback control.

Exact mocks

const transport = createCassetMockTransport({ state: "empty" })
const casset = createCassetClient({
  baseUrl: "https://sandbox.casset.test",
  transport,
  requestIdFactory: () => "test-request-001",
})

await casset.getArtist("aurora-fields") // Built-in SDK mock identity

Mock states cover ready, empty, permission denied, entitlement required, invalid credential, rate limit, unavailable resource, and integration failure. They use the same schemas and request-ID rules as the client.

Related reference