Headless API · Starter
Run the Headless React starter.
Start with exact mocks, a believable artist site, and no Casset credential.
Download casset-headless-react-v0.2.0-alpha.0.zip. The archive is immutable at this version; changing its bytes requires a package and starter version bump.
Install, test, and build
unzip casset-headless-react-v0.2.0-alpha.0.zip
cd casset-headless-react
pnpm install
pnpm test
pnpm buildThe generated archive is designed for a fresh temporary directory. A package-registry connection is still required to install its ordinary Vite and React dependencies. The Casset packages themselves resolve from the vendored directories.
What the archive contains
| Path | Purpose | Security boundary |
|---|---|---|
src/ | React example with ready, empty, and failure states. | Uses public contracts only. |
vite.config.ts | Optional local sandbox proxy. | Reads the credential server-side and strips response cookies. |
vendor/casset-apps-sdk | Exact @casset/apps 0.2 alpha source. | Local file dependency; no registry resolution. |
vendor/casset-react | Exact @casset/react 0.2 alpha source. | Depends on the vendored core package. |
.env.example | Documents two blank sandbox variables. | Contains no token or production identifier. |
src/view.test.ts | Verifies deterministic view-state derivation from mocked query results. | No browser or external service required. |
Developer kit facts
| Question | Answer |
|---|---|
| What it demonstrates | A believable public Artist and Catalog site, exact mocks, typed failures, request-ID diagnostics, and an optional server-only proxy for the two local sandbox reads. |
| Where it runs | As a developer-owned Vite + React application outside Casset. |
| Credentials | None in mocked mode. An optional one-time sandbox credential remains in Vite’s development server. |
| Mocked | Yes by default, using the built-in aurora-fields SDK fixture and exact schemas. |
| Version | 0.2.0-alpha.0 for the starter, @casset/apps, and @casset/react. |
| Install | pnpm install |
| Test | pnpm test |
| Build | pnpm build |
| Known limitations | Public v1 is deployed but unsupported for production use and may fail closed with 503. No production credential, production webhook delivery, private data, media, or playback control. Package installation still needs registry access. |
Two operating modes
| Mode | Input | What it proves | What it does not prove |
|---|---|---|---|
| Mocked | Exact local fixtures | UI handling for public schemas and typed failures | Database access, deployment, or live Casset availability |
| Local sandbox | Loopback Casset server + one-time credential | The two credentialed Artist and Catalog reads, request IDs, and immediate revocation behavior | Console actions, webhook delivery, replay, inspection, durable credentials, or production availability |
The local Developer Portal separately rehearses registration, credential issuance, signed webhooks, replay, and sanitized inspection. Those console and webhook operations are not bundled into this starter.
Connect the local sandbox
- Copy
.env.exampleto.env.local. - Set a loopback Casset origin and the one-time sandbox credential.
- Run
pnpm dev; Vite proxies same-origin sandbox requests. - Replace the mock-only
aurora-fieldsdefault with a published handle in that local database, such asconnorwhere seeded. The initial sandbox request otherwise returns the normal privacy-preserving 404. - Revoke the credential in the local Developer Portal to exercise
InvalidCredential.
CASSET_SANDBOX_BASE_URL=http://127.0.0.1:3000
CASSET_SANDBOX_CREDENTIAL=<one-time-local-value>Do not
- Do not commit
.env.localor copy a credential into frontend code. - Do not replace the vendored packages with unpublished registry dependencies.
- Do not treat the sandbox credential as durable, remotely scoped, or production-capable.
- Do not infer access to private artist data, media, or playback from a successful public read.
Continue with the quickstart or read availability and distribution truth.