createBoardClient

createBoardClient(options) creates the complete typed Board SDK. A client is safe to reuse across public requests. A shared server client is also safe when it uses nostore and receives user credentials per call.

Signature

12345678
import {
  createBoardClient,
  type BoardSdk,
  type CreateBoardClientOptions,
} from '@cavuno/board';

const create: (options: CreateBoardClientOptions) => BoardSdk =
  createBoardClient;

Options

Create a browser client

123456789
// src/lib/cavuno.ts
import { createBoardClient } from '@cavuno/board';

export const board = createBoardClient({
  board: 'pk_example',
  auth: { storage: 'session' },
});

const context = await board.context();

Storage modes have intentionally different lifetimes:

• memory is private to this client and disappears on reload.
• session uses sessionStorage and survives reloads in one tab.
• local uses localStorage and survives browser restarts.
• nostore never retains tokens.
• A custom adapter owns persistence, board scoping, and user isolation.

local and session throw during client creation when used outside a browser or when Web Storage access is blocked. Their keys are scoped by the board identifier so two boards on one origin do not share tokens.

Create a stateless server client

1234567891011121314
// src/lib/cavuno.server.ts
import { createBoardClient } from '@cavuno/board';

export const board = createBoardClient({
  board: process.env.PUBLIC_CAVUNO_BOARD!,
  auth: { storage: 'nostore' },
});

export function getMe(accessToken: string) {
  return board.me.retrieve(undefined, {
    cache: 'no-store',
    headers: { authorization: `Bearer ${accessToken}` },
  });
}

Store the token pair in an application-owned httpOnly cookie. Never attach one user’s storage adapter to a module-scoped server client.

Use custom storage

12345678910111213
import type { CustomStorage } from '@cavuno/board';

const values = new Map<string, string>();

const storage: CustomStorage = {
  getItem: (key) => values.get(key) ?? null,
  setItem: (key, value) => {
    values.set(key, value);
  },
  removeItem: (key) => {
    values.delete(key);
  },
};

The SDK reads the access token on every request. Auth methods write and clear the access/refresh pair. Logging out deliberately leaves the board-password grant intact because it is board-scoped, not user-scoped.

Request pipeline

For every board.client.fetch or namespace call, the client performs these steps in order:

1. Remove trailing slashes from baseUrl and build /v1/boards/{encodedBoard}{path}.
2. Serialize a flat query. Arrays become repeated keys; null and undefined values are omitted.
3. Separate body and query; pass every other FetchOptions field through to fetch.
4. JSON-stringify ordinary bodies and add content-type: application/json. Strings, URLSearchParams, FormData, Blob, ArrayBuffer, and ReadableStream pass through unchanged.
5. Merge headers in this order: accept: application/json, JSON content type, globalHeaders, stored bearer token, stored X-Board-Access grant, then per-call headers. Later values win.
6. Add X-Cavuno-Sdk: board@{SDK_VERSION} only when the request is non-GET or already carries authorization/board access. An explicit header is not replaced.
7. Run and await onRequest, then log and call globalThis.fetch.
8. Run and await onResponse with a clone, so the hook cannot consume the SDK’s response body.
9. Return undefined for HTTP 204; parse successful non-204 responses as JSON.
10. For non-2xx responses, parse the error envelope and throw BoardApiError. An unparseable envelope becomes unknown_error.

The client never automatically retries a request and never refreshes a session on 401.

Hook the pipeline

1234567891011121314
const board = createBoardClient({
  board: 'pk_example',
  globalHeaders: { 'x-app-version': '2026.07.10' },
  onRequest(request) {
    request.init.headers = new Headers(request.init.headers);
    request.init.headers.set('x-request-source', 'custom-board');
    return request;
  },
  onResponse(response, request) {
    if (!response.ok) {
      console.error(response.status, request.url);
    }
  },
});

Do not log authorization headers, board-access grants, or private response bodies.

Verify the client

Call board.context() and inspect the network request. It should target /v1/boards/{identifier}, include accept: application/json, and omit X-Cavuno-Sdk on an anonymous GET. An authenticated read should include both the bearer and SDK version headers.

Unknown storage modes fail during construction. Board resolution and all other non-2xx request failures use BoardApiError.