# TypeScript SDK

> @colophon-cms/sdk: read published content, write drafts and publish through publish requests from JavaScript and TypeScript, with typed answers and one error type.

Source: https://docs.colophon.404human.dev/sdk/

`@colophon-cms/sdk` is a small client for both of Colophon's HTTP APIs. A website uses it to read published
content from the [delivery API](https://docs.colophon.404human.dev/api/delivery/); a build step, import script or tool uses it to write drafts
and publish through the [management API](https://docs.colophon.404human.dev/api/management/). It sends exactly the requests you would send with
`curl`, keeps the API's field names as they are (`next_cursor`, not `nextCursor`), and turns every refusal
into one error type.

Its types are generated from the OpenAPI document the server serves, so a field the API answers is a field
the SDK knows. It is ESM only, has no runtime dependencies, and runs on Node.js 22.17 or newer and in browsers.

## Install it from a clone

1. **Build the package.** `@colophon-cms/sdk` isn't on npm yet, so build its package from a clone of the
   repository:

   ```sh not-
   git clone https://github.com/akira-shirase-oss/colophon-cms.git
   cd colophon-cms
   npm ci --workspace @colophon-cms/sdk --include-workspace-root=false --no-audit --no-fund >/dev/null
   npm pack --workspace @colophon-cms/sdk --silent
   ```

   ```text not-
   colophon-cms-sdk-0.1.0-alpha.1.tgz
   ```

2. **Build the rich-text renderer too, if you show rich text.** `@colophon-cms/rich-text` turns a rich-text
   field into HTML. It isn't on npm either; pack it the same way:

   ```sh
   npm ci --workspace @colophon-cms/rich-text --include-workspace-root=false --no-audit --no-fund >/dev/null
   npm pack --workspace @colophon-cms/rich-text --silent
   ```

   ```text
   colophon-cms-rich-text-0.1.0-alpha.1.tgz
   ```

3. **Install the tarballs** into your own project, beside the clone:

   ```sh
   mkdir ../recipe-script && cd ../recipe-script
   npm init -y >/dev/null
   npm install --no-audit --no-fund \
     ../colophon-cms/colophon-cms-sdk-0.1.0-alpha.1.tgz \
     ../colophon-cms/colophon-cms-rich-text-0.1.0-alpha.1.tgz
   ```

The examples below continue from the [quick start](https://docs.colophon.404human.dev/quick-start/): the project "Field notes" with its `recipes`,
and `PROJECT` and `COLOPHON_TOKEN` in your environment. They call `https://cms.example.com`: put your
Colophon's address there (the quick start on this machine is `http://localhost:8080`), or enter it once in
**Your Colophon URL** above.

## Make a client

```js not-

const client = new Client({ baseUrl: 'https://cms.example.com', token: process.env.COLOPHON_TOKEN });

const site = client.delivery(process.env.PROJECT);    // published content: /content/v1/…
const cms = client.environment(process.env.PROJECT);  // drafts and writes: /api/v1/projects/…/environments/…
```

Both take the **project id**, the one in **Settings** → **General** → **Technical details**, and an
environment name, `production` when you leave it out: `client.environment(id, 'staging')`. The delivery API
doesn't know a project by its URL name: `delivery('field-notes')` is answered `404 not_found`.

`new Client()` takes these options:

| Option | Default | What it does |
|---|---|---|
| `baseUrl` | (required) | Colophon's origin, such as `https://cms.example.com`. Must be `http:` or `https:` |
| `token` | none | A bearer credential: a project API token (`colophon_api_…`) or a personal access token from `colophon login`. Sent as `Authorization: Bearer` |
| `session` | none | A Studio session instead of a token: `{ csrf, cookie? }`. `csrf` is the `colophon_csrf` cookie's value, sent as `X-CSRF-Token` on writes; `cookie` is the `colophon_session` value, outside a browser only. Pass `token` or `session`, not both |
| `timeoutMs` | `15000` | How long one request may take. A per-call `signal` joins it |
| `maxBodyBytes` | 16 MiB | The largest answer it will read, declared or measured. Past it the call fails with `response_too_large` |
| `compat` | `'warn'` | The server-version check: `'warn'`, `'throw'` or `'off'`. See [Is this SDK right for the server?](#is-this-sdk-right-for-the-server) |
| `headers` | none | Extra headers on every request, such as an `Origin` the server trusts for session writes outside a browser. The credential's own headers win over them |
| `fetch` | the runtime's | The `fetch` to use |

The client attaches the credential you give it and nothing more. It never signs in, refreshes or stores a
credential: make a token in the Studio ([Authentication & API tokens](https://docs.colophon.404human.dev/api/authentication/)) or sign in with
the [CLI](https://docs.colophon.404human.dev/cli/).

The client itself also has a few calls that aren't about one environment: `livez()`, `readyz()` and
`version()` (no credential needed); `me()`, `listProjects()` and `getProject(id)`, which are for people (an
API token is refused); `validateRichText(doc)`, which checks a rich-text document without storing it; and
`compatibility()`.

:::danger[Never put a token in a browser]
Delivery reads need no credential, so a website's browser code makes a `Client` without one. A project API
token or a personal access token is a password: use it only on a server, in a build step or a script, read
from the environment. To show editors drafts on your site, use [Preview](https://docs.colophon.404human.dev/studio/preview/), whose tokens
last minutes, read only one entry or one publish request, and stay in an `HttpOnly` cookie your browser code
can't read.
:::

## Read published content

Save this as `read.mjs`:

```js title="read.mjs"

const baseUrl = 'https://cms.example.com';
const project = process.env.PROJECT; // the project id, not its URL name

const client = new Client({ baseUrl });
const site = client.delivery(project); // the production environment

// A page of published entries, and the release it came from.
const page = await site.list('recipes', { limit: 10 });
console.log('published:', page.data.map((entry) => entry.title), 'etag:', page.response.etag);

// One entry, its rich text rendered to HTML.
const { data: tart } = await site.get('recipes', page.data[0].id);
const html = renderToHtml(tart.content.method, {
  assetUrl: (id) => `${baseUrl}/media/v1/${project}/production/${id}`,
  media: mediaFor(tart),
});
console.log(html);

// Every read through `pinned` names release 1.
const pinned = site.atGeneration(1);
const quick = await pinned.query('recipes', {
  filters: [{ field: 'minutes', op: 'lte', value: 60 }],
  fields: ['dish', 'minutes'],
});
console.log('release 1, under an hour:', quick.data.map((entry) => entry.content));

// A refusal is an ApiError.
try {
  await site.query('recipes', { filters: [{ field: 'dish', op: 'eq', value: 'Lemon tart' }] });
} catch (error) {
  if (!(error instanceof ApiError)) throw error;
  console.log(error.status, error.code, error.reason, error.pointer, error.retryable);
  console.log(error.message, error.requestId);
}
```

```sh
node read.mjs
```

```text
published: [ 'Lemon tart' ] etag: "5a53d3b764fde469e9d76ec852d5faaf"
<p>Blind-bake the pastry, then fill it with lemon curd and bake until just set.</p>
release 1, under an hour: [ { dish: 'Lemon tart', minutes: 45 } ]
422 validation_failed field_not_indexed /filters/0/field false
`dish` isn't declared `index`ed 01a1ee85-704f-760e-bb09-3e888dc81dc9
```

The query filters on `minutes`, so it works once that field is filterable, as
[Filter and sort](https://docs.colophon.404human.dev/api/delivery/#filter-and-sort) sets up; `dish` isn't, and the refusal says so at the
filter's pointer.

`client.delivery(project, environment?)` has three reads, each the route of the same name on the
[delivery API](https://docs.colophon.404human.dev/api/delivery/):

| Method | Route | Options |
|---|---|---|
| `list(collection, opts?)` | `GET /content/v1/{project}/{environment}/{collection}` | `limit`, `cursor`, `generation` |
| `get(collection, entry, opts?)` | `GET …/{collection}/{entry}` | `generation` |
| `query(collection, document, opts?)` | `POST …/{collection}/query` | `cursor`, `generation` |

A list answers `data` and `next_cursor`; pass `next_cursor` back as `cursor` for the next page, until it is
`null`.

### Pin a release

`site.atGeneration(g)` returns the same three reads, each pinned to release `g`. A page built from several
reads through one pinned scope can never mix two releases, even if someone publishes in the middle. Asking a
pinned scope for a different `generation` throws a `TypeError` instead of quietly mixing them.

### Render rich text and images

A rich-text field arrives as JSON (`colophon/rich-text`, version 1), never as HTML. `renderToHtml(value,
options)` from `@colophon-cms/rich-text` turns it into HTML the same way the Studio's preview does: escaped
text, links limited to `https:`, `http:`, `mailto:`, site paths and fragments, and no inline styles or
scripts. It takes:

- `assetUrl(id)`: the address of a media-library image, used when `media` doesn't know it;
- `media(id)`: optional, an image's source, size and responsive candidates.

`mediaFor(row)` builds `media` from the `media` record a delivery row carries for the images its release
published. For each image it answers `src`, the exact version that release published, with its `width` and
`height` (so the page doesn't shift as images load), and, when smaller `wN` renditions exist, a `srcset` and
a `sizes` that defaults to the full width up to 1280 px. An image the record doesn't hold answers
`undefined`, and the renderer falls back to `assetUrl`. `mediaFor(row, { current: true })` follows replaced images
instead, and `{ sizes: '50vw' }` changes the slot. For an image field, call it with the asset id:
`mediaFor(row)(row.content.photo)`.

In TypeScript, `content` is typed as a plain record, so cast a rich-text field:
`row.content?.['method'] as RichTextValue`, with `type RichTextValue` imported from
`@colophon-cms/rich-text`. A document the renderer doesn't understand throws `UnrenderableContent`; content
reaches the delivery API only after the server validated it, so that means a bug, not content to guess at.

## Write drafts with a token

`client.environment(project, environment?)` is the management API for one environment. The example below
runs with the quick start's token. Give a script of your own a **Custom** token with only what it does
(**See**, **Create** and **Edit** to write drafts and open publish requests; **Publish** only if it
publishes), the shortest lifetime that fits, and revoke it when the script is retired. Without **Approve**,
the example's approve step is refused with `missing_permission` before the `agent_self_review` rule is
reached. See [Authentication & API tokens](https://docs.colophon.404human.dev/api/authentication/).

Every answer is the API's body with one more field, `response`:

| `response.` | What it is |
|---|---|
| `status` | The HTTP status of the success, such as `200` or `201` |
| `etag` | The `ETag` header: the revision or hash the next guarded write sends back as `ifMatch`. `null` when the route sends none |
| `replayed` | `true` when the server answered from an earlier request with the same idempotency key (`Idempotent-Replayed: true`) |
| `requestId` | The `x-request-id` to quote when you report a problem |

Writes name their guards as options, and the SDK makes them required where the route requires them:

- **`idempotencyKey`** on every write that creates something. `newIdempotencyKey()` makes one (a random UUID).
  Use one key per logical write and keep it: if the answer is lost and you send the same write again with the
  same key, Colophon answers with the first result instead of writing twice. See
  [Idempotency-Key](https://docs.colophon.404human.dev/api/management/#create-the-idempotency-key-header).
- **`ifMatch`** on every write that changes something that exists: the `response.etag` of the read or write
  you based it on. If someone saved in between, the write is refused with `409` and nothing is lost. See
  [If-Match](https://docs.colophon.404human.dev/api/management/#save-the-if-match-header).

Save this as `write.mjs`:

```js title="write.mjs"

const baseUrl = 'https://cms.example.com';
const project = process.env.PROJECT;

const client = new Client({ baseUrl, token: process.env.COLOPHON_TOKEN, compat: 'throw' });
const cms = client.environment(project); // production

const mine = await cms.ownPermissions();
console.log('kind:', mine.data.kind, 'actions:', mine.data.permissions.length);

// Create a draft. Keep the key: a retry with the same key is answered from the first result.
const key = newIdempotencyKey();
const created = await cms.createEntry('recipes', { dish: 'Bakewell tart', minutes: 50 }, { idempotencyKey: key });
const again = await cms.createEntry('recipes', { dish: 'Bakewell tart', minutes: 50 }, { idempotencyKey: key });
console.log('created:', created.data.id, created.response.status, created.response.replayed);
console.log('retried:', again.data.id, again.response.status, again.response.replayed);

// Save on top of the revision just read: ifMatch is the ETag that answer carried.
const id = created.data.id;
const saved = await cms.saveEntry('recipes', id, { ...created.data.content, minutes: 55 }, {
  ifMatch: created.response.etag,
  idempotencyKey: newIdempotencyKey(),
});
console.log('saved:', saved.data.content, saved.response.etag);

// The same save on top of the old ETag is a conflict, and the error carries the current one.
try {
  await cms.saveEntry('recipes', id, { ...created.data.content, minutes: 40 }, {
    ifMatch: created.response.etag,
    idempotencyKey: newIdempotencyKey(),
  });
} catch (error) {
  if (!(error instanceof ApiError)) throw error;
  console.log('conflict:', error.status, error.code, error.reason, error.etag);
}

// Open a publish request and send it for review.
const request = await cms.createChangeset(
  { title: 'Add the Bakewell tart', entries: [id] },
  { idempotencyKey: newIdempotencyKey() },
);
const hash = request.response.etag;
const submitted = await cms.submitChangeset(request.data.id, { ifMatch: hash });
console.log('request:', submitted.data.status.state, hash);

// A token can't approve what a token sent: a person approves it.
try {
  await cms.reviewChangeset(request.data.id, { decision: 'approve' }, { ifMatch: hash });
} catch (error) {
  if (!(error instanceof ApiError)) throw error;
  console.log('approve:', error.status, error.code, error.reason);
  console.log(error.message);
}
```

```sh
node write.mjs
```

```text
kind: token actions: 8
created: 01a1ee85-afa4-779f-895f-42780642e364 201 false
retried: 01a1ee85-afa4-779f-895f-42780642e364 201 true
saved: { dish: 'Bakewell tart', minutes: 55 } "01a1ee85-afb2-7023-be82-d666cd76c119"
conflict: 409 conflict stale_revision "01a1ee85-afb2-7023-be82-d666cd76c119"
request: awaiting_review "sha256:acc0efd34baa0deacc66de7757b02a85c6d3ee28264809999a671300375f98e9"
approve: 403 forbidden agent_self_review
an API token can't approve a changeset an API token submitted; it needs a person's approval
```

What happened:

- The second `createEntry` with the same key made nothing new: same id, `replayed: true`.
- The save sent the create's `ETag` as `If-Match` and made a new revision, whose `ETag` came back.
- The second save was based on a revision that is no longer current, so it was refused with `409` and
  `stale_revision`; `error.etag` is the current revision, the `ifMatch` a retry would send after looking at
  what changed.
- The publish request pins the entry's current revision; its `ETag` is the request's hash, which every later
  step sends as `ifMatch`.
- A token may send a request for review but not approve one a token sent: that needs a person.

### Publish through the API

Once a person has approved the request (in the Studio, **Publish requests** → the request → **Approve this
version**), the token may publish it. `base_generation` is the newest release you have seen, `0` before the
first:

```js not-
const { response: current } = await cms.getChangeset(request.data.id);
const releases = await cms.listReleases();
const release = await cms.publishChangeset(
  request.data.id,
  { base_generation: releases.data[0]?.generation ?? 0 },
  { ifMatch: current.etag, idempotencyKey: newIdempotencyKey() },
);
const receipt = await cms.getReceipt(release.data.generation);
console.log(receipt.data.label, receipt.data.deliveries);
```

The answers are those in [Publish through the API](https://docs.colophon.404human.dev/api/management/#publish-through-the-api). If another
release went out after the one you named, `publishChangeset` is refused with `409 generation_moved`: read the
releases again, check what changed, and publish on top of the new one.

## Every method

Every method takes an optional `signal` (an `AbortSignal`) with its other options. `{ idempotencyKey }`,
`{ ifMatch }` and `{ ifMatch, idempotencyKey }` are required where shown. Routes are under
`/api/v1/projects/{project}/environments/{environment}`.

**Entries**

| Method | Route |
|---|---|
| `listEntries(collection, { limit, cursor, q, created_by, locale })` | `GET collections/{collection}/entries` |
| `getEntry(collection, entry)` | `GET …/entries/{entry}`; its `ETag` is the next save's `ifMatch` |
| `createEntry(collection, document, { idempotencyKey, locale })` | `POST …/entries` |
| `saveEntry(collection, entry, document, { ifMatch, idempotencyKey, locale })` | `PUT …/entries/{entry}` |
| `deleteEntry(collection, entry, { ifMatch, idempotencyKey })` | `DELETE …/entries/{entry}`; refused with `409 still_referenced` while anything still refers to it |
| `entryHistory(collection, entry)` | `GET …/entries/{entry}/revisions` |
| `getRevision(collection, entry, revision)` | `GET …/revisions/{revision}` |
| `queryEntries(collection, document, { cursor })` | `POST …/entries/query`: the [query document](https://docs.colophon.404human.dev/api/delivery/#filter-and-sort), over drafts |

**Content types**

| Method | Route |
|---|---|
| `listContentTypes()` | `GET content-types` |
| `getContentType(slug)` | `GET content-types/{slug}` |
| `createContentType(body, { idempotencyKey })` | `POST content-types` |
| `updateContentType(slug, definition, { ifMatch, idempotencyKey })` | `PUT content-types/{slug}` |
| `deleteContentType(slug, { ifMatch, idempotencyKey })` | `DELETE content-types/{slug}`; only an empty one |

**Publish requests and releases**

| Method | Route |
|---|---|
| `listChangesets()` | `GET changesets` |
| `getChangeset(changeset)` | `GET changesets/{changeset}`; its `ETag` is the hash later steps send |
| `createChangeset({ title, entries, unpublish }, { idempotencyKey })` | `POST changesets` |
| `submitChangeset(changeset, { ifMatch })` | `POST …/submit` |
| `reviewChangeset(changeset, { decision, comment, stage }, { ifMatch })` | `POST …/reviews`; `decision` is `approve` or `request_changes` |
| `publishChangeset(changeset, { base_generation }, { ifMatch, idempotencyKey })` | `POST …/publish` |
| `listReleases()` | `GET releases`, newest first (the first page) |
| `getReceipt(generation)` | `GET releases/{generation}`: the receipt |

**Comments and tasks**

| Method | Route |
|---|---|
| `listComments(collection, entry, { limit, cursor, revision, state })` | `GET …/entries/{entry}/comments` |
| `getComment(collection, entry, comment)` | `GET …/comments/{comment}` |
| `createComment(collection, entry, { revision, body, field }, { idempotencyKey })` | `POST …/comments` |
| `resolveComment(collection, entry, comment, { ifMatch, idempotencyKey })` | `POST …/comments/{comment}/resolve` |
| `reopenComment(collection, entry, comment, { ifMatch, idempotencyKey })` | `POST …/comments/{comment}/reopen` |
| `listTasks({ status, collection, entry, assignee, limit, cursor })` | `GET tasks` |
| `getTask(task)` | `GET tasks/{task}` |
| `createTask({ entry, title, revision, changeset, assignee }, { idempotencyKey })` | `POST tasks` |
| `updateTask(task, { title, assignee, status }, { ifMatch, idempotencyKey })` | `PATCH tasks/{task}`; `status` is `open`, `done` or `cancelled` |

**Schema migrations, media and permissions**

| Method | Route |
|---|---|
| `listMigrations({ collection, state })` | `GET migrations` |
| `getMigration(migration)` | `GET migrations/{migration}` |
| `listMigrationItems(migration, { outcome, after, limit })` | `GET migrations/{migration}/items` |
| `listAssets()` | `GET assets` (the first page) |
| `getAsset(asset)` | `GET assets/{asset}`, with its renditions |
| `ownPermissions()` | `GET permissions`: what this credential may do here |

Migrations are read-only here: planning, approving and applying one is a person's job, with
[`colophon migration`](https://docs.colophon.404human.dev/cli/). Image bytes come from `/media/v1`, not through the SDK.

For anything else (members, tokens, website connections, schedules, imports and exports, bulk jobs), the
generated types are exported as `paths`, `operations` and `components`, and the common schemas by name
(`EntryDocument`, `ChangesetView`, `ReceiptView` and others), so a call of your own is still typed. Every
route is in the [API reference](https://docs.colophon.404human.dev/api/reference/).

## Errors

Every failure is an `ApiError`, never a bare network error:

| Field | What it holds |
|---|---|
| `status` | The HTTP status, or `0` when no answer arrived |
| `code` | The [error envelope](https://docs.colophon.404human.dev/api/errors/)'s `code`, or one the SDK raised itself (below) |
| `message` | Words safe to show a person. Don't branch on them |
| `requestId` | The request id, from the envelope or the `x-request-id` header |
| `details` | The envelope's `details`: `reason`, `pointer`, and whatever the refusal lists (the missing `permission`, the entries in the way) |
| `reason`, `pointer` | Shortcuts for `details.reason` and `details.pointer` |
| `etag` | The `ETag` the failed answer carried: on a `409`, the current one |
| `retryAfterMs` | `Retry-After` in milliseconds on a `429`, capped at a minute |
| `retryable` | `true` when sending the same request again may succeed: no answer (`status` `0`), `429`, a `5xx`, `deadline_exceeded`, `rate_limited` or `unavailable`. A write may still have happened when no answer came, so retry a write only with the same idempotency key. Never `true` for `incompatible_server` |

Branch on `code` and `reason`. The codes the SDK raises itself:

| `code` | `status` | When |
|---|---|---|
| `no_answer` | `0` | No answer: refused connection, DNS, or `timeoutMs` or your `signal` ran out |
| `invalid_response` | the status | The answer wasn't the JSON the API promises, such as a proxy's error page |
| `response_too_large` | the status | The answer ran past `maxBodyBytes` |
| `incompatible_server` | `0` | `compat: 'throw'` and the server doesn't fit; nothing was sent |

The client never retries by itself. When you retry a write, send the **same** idempotency key, so a write
whose answer was lost isn't made twice:

```js title="retry.mjs"

// One key for the logical write, reused by every attempt.
async function createWithRetry(cms, collection, document, attempts = 3) {
  const idempotencyKey = newIdempotencyKey();
  for (let attempt = 1; ; attempt++) {
    try {
      return await cms.createEntry(collection, document, { idempotencyKey });
    } catch (error) {
      if (!(error instanceof ApiError) || !error.retryable || attempt === attempts) throw error;
      console.log(`attempt ${attempt}: ${error.code}, trying again with the same key`);
      await new Promise((resolve) => setTimeout(resolve, error.retryAfterMs ?? 500 * attempt));
    }
  }
}

// Against a server that isn't there:
const cms = new Client({ baseUrl: 'http://127.0.0.1:9', token: 'not-a-real-token', compat: 'off' }).environment('field-notes');
try {
  await createWithRetry(cms, 'recipes', { dish: 'Parkin', minutes: 90 });
} catch (error) {
  console.log('gave up:', error.code, error.retryable);
}
```

```sh
node retry.mjs
```

```text
attempt 1: no_answer, trying again with the same key
attempt 2: no_answer, trying again with the same key
gave up: no_answer true
```

The third failure is thrown. A `409`, `403` or `422` answers the same every time, so `retryable` is
`false` for them.

If you call the API with your own `fetch`, `errorOf(body)` reads a parsed body as the error envelope's `error`
object (`code`, `message`, `details`, `request_id`), or `null` when it isn't one.

## Is this SDK right for the server?

Before 1.0, each minor release may change the API, so the SDK and the server must be on the same minor
version (any `0.1.x` with any `0.1.x`), the server must serve API `v1`, and it must be at least the oldest
server this SDK supports (`OLDEST_SERVER`, `0.1.0-alpha.1`). The `colophon` CLI uses the same rule.
`client.compatibility()` reads the server's `/version` and says whether it fits:

```js title="fit.mjs"

const fit = await new Client({ baseUrl: 'https://cms.example.com' }).compatibility();
console.log(fit);
```

```sh
node fit.mjs
```

```text
{
  compatible: true,
  sdk: '0.1.0-alpha.1',
  server: '0.1.0-alpha.1',
  api: [ 'v1' ]
}
```

When it doesn't fit, `misfit` is a stable code (`api_dropped`, `api_not_yet`, `later_line`, `earlier_line`,
`before_oldest`, `no_version_report`) and `reason` says which side to upgrade. Against a server on 0.2.0:

```text not-
@colophon-cms/sdk 0.1.0-alpha.1 is too old for the server at https://cms.example.com, which runs 0.2.0: before 1.0 each minor release may change the API, so the SDK and the server must share a minor version, and the server is on a later one (0.1 here, 0.2 there). Install @colophon-cms/sdk@0.2.0 to match it.
```

The client also checks once by itself, before its first API call, as the `compat` option says:

- `'warn'` (the default): prints `reason` with `console.warn` if the server doesn't fit, and never delays or
  fails a call;
- `'throw'`: waits for the check, then fails every call with `incompatible_server` while the server doesn't
  fit, sending nothing;
- `'off'`: never asks.

A check that gets no answer decides nothing and is tried again on the next call. `livez()`, `readyz()` and
`version()` never wait for it.

## Draft preview on your own site

When an editor presses **Preview** in the Studio, your site receives a one-time code and trades it for a
short-lived preview token. The SDK has the pieces, built on the standard `Request` and `Response`, so they
work in any framework:

- `createPreviewHandler({ baseUrl, project, isAllowedPath })`: your site's preview route. It exchanges the
  code, keeps the token in an `HttpOnly` cookie and redirects to the page, never to another site;
- `previewTokenFromRequest(request)`: the token from that cookie, or `null`;
- `previewClient({ baseUrl, project }).reader(token)`: `list`, `get` and `query` that see the draft;
- `previewHeaders({ studioOrigin })`: headers for a preview page, so no cache keeps it, no search engine
  indexes it, and only the Studio may frame it.

`exitPreviewHandler()` clears the cookie, and `listenForDraftUpdates({ studioOrigin, previewing })` reloads
the page in the browser after each save. Setting up the preview address and the whole flow is on
[Preview](https://docs.colophon.404human.dev/studio/preview/).

## What's next

	- [Management API](https://docs.colophon.404human.dev/api/management/): Idempotency keys, If-Match, validation and publishing, with every request and answer.
	- [Delivery API](https://docs.colophon.404human.dev/api/delivery/): Lists, queries, pinned releases, caching and taken-down content.
	- [Authentication & API tokens](https://docs.colophon.404human.dev/api/authentication/): Making a token with the least it needs, limits, and what a token can never do.
	- [CLI](https://docs.colophon.404human.dev/cli/): Sign in, list and create content, read receipts and run migrations from a terminal.
