SDK versioning

@cavuno/board has a semantic package version and targets the separately versioned Cavuno Board API v1. Updating the package changes local code, types, helpers, CLI behavior, and bundled skills; it does not change the /v1 URL prefix.

Inspect the installed SDK version

123
import { SDK_VERSION } from '@cavuno/board';

console.log(`Cavuno Board SDK ${SDK_VERSION}`);

SDK_VERSION is a release-managed constant guarded by a test that compares it with package.json. It is also used in the conditional X-Cavuno-Sdk: board@{version} request header.

Anonymous GETs omit that header to remain CORS-simple. Non-GET requests and reads carrying authorization or a board-access grant include it unless the application supplied its own value.

Distinguish package and API versions

Use onResponse when diagnostics need response headers:

123456789
const board = createBoardClient({
  board: 'pk_example',
  onResponse(response) {
    console.debug({
      apiVersion: response.headers.get('x-cavuno-api-version'),
      apiBuild: response.headers.get('x-cavuno-api-build'),
    });
  },
});

Do not persist these diagnostics with bearer tokens or private bodies.

Compatibility within API v1

• Successful response objects can gain fields. Read the fields you need and ignore unknown ones.
• Error codes can be added. BoardApiErrorCode intentionally remains an open string union, so keep a default branch.
• The SDK returns the v1 wire body without renaming or reshaping it.
• Public request and response types are generated from the OpenAPI snapshot; the SDK does not validate successful responses at runtime.
• board.client.fetch<T> uses the application’s generic assertion and is not covered by generated endpoint types.
• A package major update can change public SDK behavior or declarations and requires explicit migration review.

Runtime compatibility

The published package declares Node.js 20 or newer. The core client and non-Node helper entries use web-standard globals and are designed for browsers, Workers, and Node 20+.

The @cavuno/board/skills loader and CLI use Node filesystem APIs. Use @cavuno/board/skills/types when a non-Node runtime only needs manifest types.

The package publishes import and require conditions for the root and helper subpaths. Run both your application build and server runtime checks after changing module tooling.

Consumer upgrade workflow

1. Read the package changelog for every version being crossed.
2. Update @cavuno/board and commit the lockfile change on a branch.
3. Run the application typecheck before editing call sites; generated signature changes should fail where they are used.
4. Re-run npx @cavuno/board setup so checked-in skills match the installed package.
5. Run application unit/integration tests and a production-mode build.
6. Exercise the specific public reads, sessions, writes, pagination, formatting, SEO, and sitemap helpers your app uses.
7. Deploy a preview and run npx @cavuno/board doctor --frontend <preview-url>.
8. Compare representative error handling, request IDs, JobPosting JSON-LD, canonical routes, and sitemap output before promotion.

For a major update, inventory root and subpath imports before upgrading. Do not hide removed exports behind locally copied implementations; decide whether to migrate or remain pinned.

Repository release gates

Contributors releasing this package run the package’s defined gates:

12345
pnpm --filter @cavuno/board test
pnpm --filter @cavuno/board typecheck
pnpm --filter @cavuno/board check:types
pnpm --filter @cavuno/board build
pnpm --filter @cavuno/board check:publish

They verify tests, browser/Node typings, generated OpenAPI drift, build output, package exports, and published type compatibility. Releases use release-please; package version changes are commit-driven rather than handwritten.

Verify an upgrade

123
node -e "import('@cavuno/board').then(({SDK_VERSION}) => console.log(SDK_VERSION))"
npx @cavuno/board setup
npx @cavuno/board doctor --frontend https://preview.jobs.example.com

The printed runtime version, installed dependency version, and setup output version should agree. A doctor skill-freshness failure means the runtime package was upgraded without refreshing the copied corpus.

Pin the dependency according to your release policy. Do not silently admit a new major release to production.