cavuno-sdk

Cavuno Board SDK

Build custom job boards and careers pages with Cavuno’s TypeScript SDK.

@cavuno/board is the zero-dependency client for the Cavuno Board API. It runs in browsers, Node.js 20 or newer, and Cloudflare Workers, with TypeScript declarations generated from the API’s OpenAPI contract.

Documentation · Installing · SDK reference · API reference · Source

Installation

Install as package

npm install @cavuno/board

The package includes ESM and CommonJS builds. ESM imports are tree-shakeable, and helper packages such as @cavuno/board/format can be imported separately.

Install via CDN

No package manager or build step? Follow the CDN installation guide for a version-pinned build and its integrity hash. The CDN build is the same SDK downloaded as one file; package imports remain the recommended choice when they are available.

See Installing for every installation option.

Quick start

import { createBoardClient } from '@cavuno/board';

const board = createBoardClient({
  board: 'pk_your_publishable_key',
});

const [context, jobs] = await Promise.all([
  board.context(),
  board.jobs.list({ limit: 20 }),
]);

console.log(context.name);
console.log(jobs.data);

A pk_… key identifies a board and is public by design. Get it from Settings → Developer → SDK in Cavuno. The client connects to https://api.cavuno.com by default.

The client exposes typed namespaces for jobs and search, companies, salaries, blog, board-user authentication, saved jobs, applications, job alerts, messaging, employer workflows, checkout, candidate access, and SEO data.

Handle errors

Every non-2xx response throws a BoardApiError with the API status, code, details, and request ID.

import { BoardApiError, isNotFound } from '@cavuno/board';

try {
  await board.jobs.retrieve('missing-job');
} catch (error) {
  if (isNotFound(error)) {
    // Render your application's not-found state.
  } else if (error instanceof BoardApiError) {
    console.error(error.code, error.requestId);
  }
}

See Handle SDK errors for the complete error contract and guards.

Authentication

• A pk_… publishable key identifies the board and may be included in browser code.
• Candidate and employer sessions use board.auth.*. Choose browser storage deliberately; server-rendered applications should keep sessions in their own httpOnly cookies.
• Operator and admin credentials must never be used with this SDK or exposed to frontend code.

Read Authentication and sessions before adding signed-in workflows.

Make a request to a custom endpoint

For an endpoint without a namespace method, board.client.fetch<T>(path, init) uses the same board base path, headers, bearer token, serialization, and hooks as the rest of the client. Treat the generic response type as your application’s assertion; custom responses are not generated from the public OpenAPI contract.

See board.client.fetch() for options and examples.

Set up with a coding agent

The package includes version-matched Agent Skills for Codex, Claude Code, Cursor, and other compatible coding agents:

npx @cavuno/board setup

Then ask your agent to set up the Cavuno board using the installed cavuno-board-setup skill. See Set up with an agent for the review and verification workflow.

Reporting problems

Coding agents (and people) can report anything in the Board API or SDK that got in the way: a missing capability, unclear documentation, a surprising response or an unhelpful error. Send an Agent Feedback Protocol v0.1 report to POST https://api.cavuno.com/v1/feedback; no credentials are needed, and the discovery document is at https://api.cavuno.com/.well-known/agent-feedback.

curl https://api.cavuno.com/v1/feedback \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{ "type": "missing_capability", "goal": "What you were trying to do", "message": "What got in the way", "agent": { "name": "my-agent", "model": "model-name" } }'

type, goal and message are required. Up to 20 reports every 5 minutes. Never include credentials or personal data.

Resources

• SDK guides and reference
• Board API documentation
• OpenAPI document
• Source
• Issues
• TanStack Start + shadcn/ui job board template

MIT © Wollemia

Advertising defaults

board.context() returns ads.enabled, ads.clientId (the AdSense publisher ID), and ads.defaultSlotId (a Google-issued ad unit ID). Render ads only when enabled with a valid publisher and unit. The default reuses the board's existing advertising setup: the enabled jobs:list.footer unit takes priority, otherwise the first enabled valid unit in alphabetical placement-key order is used. No configured unit, disabled advertising, or an invalid publisher yields a null default. Google approval and an existing ad unit are still required.

Your frontend owns ad positions and sizes. Reuse the default across placements, or pass another Google-issued slot ID to an individual ad component; there is no SDK placement registry. Custom units should still respect ads.enabled and the board's consent requirements.