Top-level methods

Reference for board context, SEO infrastructure, the raw client, and shared response conventions.

The SDK has public Board reads and one raw request escape hatch. Namespace methods use the same underlying BoardClient pipeline.

`board.context()`

1context(options?: FetchOptions): Promise<PublicBoard>

Returns the public configuration needed to build the board shell:

Field	Use
`id`, `slug`, `name`	Board identity. `id` is immutable; `slug` can change.
`language`	Required input for SDK display-formatting helpers.
`logoUrl`, `icons`	Board logo and the favicon / app-icon pack derived from it (absolute URLs or null). Brand identity — map `icons` into root-layout `<link rel="icon">` tags.
`primaryDomain`, `showCavunoBranding`	Public domain and whitelabel state.
`features`	Capability gates for alerts, candidates, employers, blog, talent directory (`off` \| `public` \| `employers_only`), registration wall, password protection, public submission, paywall, and impressum.
`analytics`	Public analytics IDs and the cookie-consent requirement.
`customFields`, `contact`	Job-field definitions (keyed by model) and public contact/social identity.
`jobForm`, `forms`	Built-in job-form options and constraints, and the operator's job, company, and talent forms as ordered field lists (`BoardFormLayout`). Render each list in order, skip entries with `visible: false`, and validate `required`. `jobForm.employmentType` gives the offered built-in types, the board's custom types (offer only those with `offered: true`) and their shared display `order`.
`sandbox`	Platform sandbox marker. Only doctor’s opted-in write probes should use it.

1const context = await board.context({ cache: 'force-cache' });
2
3if (context.features.blog) {
4  // Register or render the public blog route.
5}

Context is public and can normally use a shared cache. Feature flags guide presentation; they do not replace API authorization or entitlement enforcement.

`board.seo()`

1seo(options?: FetchOptions): Promise<BoardSeo>

Returns public platform infrastructure configuration:

canonicalBase for canonical links and the robots.txt sitemap line.
adsTxt and indexNowKey, each nullable.
googleSiteVerification, nullable.
manifest.name (board display name for a web manifest).

Icon URLs and themeColor are not returned — applications ship their own brand assets and presentation tokens.

1const seo = await board.seo({ cache: 'force-cache' });
2
3export function adsTxtResponse() {
4  if (seo.adsTxt === null) return new Response('Not found', { status: 404 });
5
6  return new Response(seo.adsTxt, {
7    headers: { 'content-type': 'text/plain; charset=utf-8' },
8  });
9}

board.seo() does not create page metadata or JSON-LD. Those pure builders live in @cavuno/board/seo.

Make a request to a custom endpoint

Use board.client.fetch() when an endpoint does not yet have a namespace method.

1fetch<T>(path: string, options?: FetchOptions): Promise<T>

Use the raw client for a live board-relative endpoint that does not yet have a namespace method. Prefer namespace methods when available because their bodies, queries, and responses are generated from the API contract.

1interface BoardStats {
2  object: 'board_stats';
3  activeJobs: number;
4}
5
6const stats = await board.client.fetch<BoardStats>('/custom/stats', {
7  query: { period: '30d' },
8  signal: AbortSignal.timeout(5_000),
9});

The path is appended below /v1/boards/{identifier}. It must begin with / to produce the intended route. The generic type is an application assertion—the raw client does not validate the response at runtime.

Query behavior

Queries must be flat objects. Arrays serialize as repeated keys, preserving order:

1await board.client.fetch('/custom/jobs', {
2  query: {
3    remoteOption: ['remote', 'hybrid'],
4    cursor: null,
5    limit: 20,
6  },
7});
8
9// ?remoteOption=remote&remoteOption=hybrid&limit=20

null and undefined are omitted. Other values are converted with String(value). Nested objects are not recursively encoded.

Body and response behavior

Ordinary bodies are JSON-stringified and receive content-type: application/json.
Strings, URLSearchParams, FormData, Blob, ArrayBuffer, and ReadableStream are sent unchanged.
A successful HTTP 204 resolves to undefined without parsing.
Other successful responses are parsed as JSON.
Every non-2xx response throws BoardApiError; an invalid or non-JSON error body becomes unknown_error.
There is no automatic retry, response validation, or 401 refresh.

Shared list envelopes

List methods return ListEnvelope<T> and searches return SearchEnvelope<T>:

1const page = await board.jobs.list({ limit: 20 });
2
3page.object; // "list"
4page.data; // PublicJobCard[]
5page.hasMore; // boolean
6page.nextCursor; // string | null

Jobs catalog envelopes can also contain count, limit, offset, and gatedCount. Consumers must ignore unknown additive response fields. Echo nextCursor instead of inspecting it; it is opaque.

Verify the behavior

Use a deliberate 204 endpoint and a deliberate missing path in development. Confirm that the first resolves undefined, while the second throws BoardApiError and retains its status, code, raw envelope, and request ID.