@cavuno/board 4.4.0 → 4.5.0

package/CHANGELOG.md

@@ -3,6 +3,34 @@
 This changelog records changes that affect Board API compatibility, exported
 types, runtime behavior, or supported integration patterns.
 
+## 4.5.0 — 2026-08-21
+
+- **Board-user account self-service**: signed-in board users manage their own
+  account over the API. New `board.me` verbs and `/v1/boards/{identifier}/me/*`
+  endpoints: `updatePassword`, `requestEmailChange` / `confirmEmailChange`
+  (verify-then-switch), and account deletion. The `board_user` resource now
+  exposes `hasPassword` so headless frontends can decide between change-password
+  and set-password flows.
+- **Company team management**: `board.me.companies` gains members and invites —
+  list members, change a member's role (`admin` / `member`), remove a member,
+  create / list / revoke email invites (7-day links), accept an invite, and
+  `leave(slug)` (`DELETE .../me/companies/{slug}/membership`). A company always
+  keeps at least one admin: the API answers `409 last_admin` when an action
+  would strand it.
+- **Analytics**: apply-clicks and job-visitors reporting can group by
+  first-touch channel, and apply-click rows carry `jobSlug`.
+- **Company blocklist**: endpoints for blocking a company from automated
+  sourcing so imports and aggregation cannot reintroduce it.
+- **Fix**: salary formatting falls back cleanly when the runtime lacks
+  `Intl.NumberFormat.formatRange`.
+
+## 4.4.1 — 2026-08-10
+
+- **SDK installation documentation**: The npm and GitHub README now presents
+  package installation as the recommended TypeScript SDK path, with CDN
+  installation as a separate option for static HTML and other no-build sites.
+  Links point to the canonical SDK installation guides on cavuno.com.
+
 ## 4.4.0 — 2026-08-10
 
 - **Classic-script browser build**: `@cavuno/board` now ships a dependency-free

package/README.md

@@ -2,114 +2,130 @@
 
 Build custom job boards and careers pages with Cavuno’s TypeScript SDK.
 
-`@cavuno/board` is a typed, isomorphic client for the
-[Cavuno job board platform](https://cavuno.com) Board API. It has zero runtime
-dependencies and runs in browsers, Node.js 20 or newer, and Cloudflare Workers.
+`@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.
 
-You bring the framework and own the layout; the SDK brings the job board:
-jobs and search, companies, salaries, blog, board-user auth, saved jobs,
-applications, job alerts, messaging, employer self-service, checkout, and
-the candidate paywall — every method typed from the API's own OpenAPI
-contract.
+[Documentation](https://cavuno.com/docs/sdk) ·
+[Installing](https://cavuno.com/docs/sdk/installing) ·
+[SDK reference](https://cavuno.com/docs/sdk/reference) ·
+[API reference](https://cavuno.com/docs/api) ·
+[Source](https://github.com/wollemiahq/cavuno-sdk)
 
-## Building with a coding agent
+## Installation
 
-The package ships an Agent Skills corpus for Codex, Claude Code, Cursor, and
-other compatible coding agents. It teaches them how to wire a board correctly — client setup,
-auth and session ownership, pagination, gating, error handling, and a
-runtime smoke test:
-
-Install the latest skills directly from the public SDK repository:
+### Install as package
 
 ```bash
-npx skills add wollemiahq/cavuno-sdk --skill cavuno-board-setup
-# Or install the complete Cavuno skill set:
-npx skills add wollemiahq/cavuno-sdk --skill '*'
+npm install @cavuno/board
 ```
 
-For skills matched exactly to an installed SDK version, copy them from the
-package instead:
+The package includes ESM and CommonJS builds. ESM imports are tree-shakeable,
+and helper packages such as `@cavuno/board/format` can be imported separately.
 
-```bash
-npm install @cavuno/board     # or: pnpm add / yarn add / bun add
-npx @cavuno/board setup       # copies version-matched Agent Skills
-```
+### Install via CDN
+
+No package manager or build step? Follow the
+[CDN installation guide](https://cavuno.com/docs/sdk/installing/cdn)
+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.
 
-Then ask your agent: *"set up my Cavuno board"* — it reads the
-`cavuno-board-setup` skill and works surface by surface. Because the
-skills live in your project and match your installed version, the agent
-never works from stale docs.
+See [Installing](https://cavuno.com/docs/sdk/installing) for every installation option.
 
-## Quick start (by hand)
+## Quick start
 
 ```ts
 import { createBoardClient } from '@cavuno/board';
 
 const board = createBoardClient({
-  board: process.env.PUBLIC_CAVUNO_BOARD!, // pk_… publishable key
+  board: 'pk_your_publishable_key',
 });
 
-const { name, language, features } = await board.context();
-const page = await board.jobs.list({ limit: 20 });
-const job = await board.jobs.retrieve('senior-chef');
+const [context, jobs] = await Promise.all([
+  board.context(),
+  board.jobs.list({ limit: 20 }),
+]);
 
-// Federated search-dropdown suggestions (companies, markets, taxonomy terms).
-const { items } = await board.search.suggest({
-  q: 'acme',
-  limit: 10,
-  types: ['company', 'skill'],
-});
-// Or the headless controller (debounce / abort / stale-drop built in):
-// import { createSuggestController } from '@cavuno/board/suggest';
-// const suggest = createSuggestController(board);
-// suggest.setQuery('acme');
+console.log(context.name);
+console.log(jobs.data);
 ```
 
-Every method accepts trailing `FetchOptions` — `signal`, `headers`, and
-framework caching directives (`next: { tags }`, `cf: {…}`) pass through to
-`fetch` untouched. Walk full catalogs with the async iterator:
+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.
 
-```ts
-import { paginate } from '@cavuno/board';
+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.
 
-// the query `limit` is the page size; toArray's `limit` caps items collected
-for await (const card of paginate(board.jobs.list, { limit: 100 })) {
-  urls.push(card.links.public);
+```ts
+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);
+  }
 }
-const first500 = await paginate(board.companies.list, { limit: 100 })
-  .toArray({ limit: 500 });
 ```
 
-Errors are typed — every non-2xx throws a `BoardApiError` carrying the full
-v1 envelope (`status`, `code`, `details`, `requestId`), with guards like
-`isNotFound`, `isRateLimited`, and `isBoardPasswordRequired`.
+See [Handle SDK errors](https://cavuno.com/docs/sdk/fundamentals/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](https://cavuno.com/docs/sdk/fundamentals/authentication-and-session-ownership)
+before adding signed-in workflows.
 
-## Auth model
+## Make a request to a custom endpoint
 
-Three tiers, safe for browsers by construction:
+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.
 
-- **`pk_…` publishable key** — identifies the board; public by design.
-- **Board-user JWT** — candidate/employer sessions via `board.auth.*`.
-  Pluggable storage (`memory` in the browser, `nostore` on the server);
-  on SSR, keep the session in an httpOnly cookie your app owns and pass
-  the token per call. No auto-refresh on 401 — rotation is explicit.
-- **No secret keys** — operator/admin credentials never touch this SDK.
+See [`board.client.fetch()`](https://cavuno.com/docs/sdk/reference/top-level-methods#make-a-request-to-a-custom-endpoint)
+for options and examples.
 
-## Escape hatch
+## Set up with a coding agent
+
+The package includes version-matched Agent Skills for Codex, Claude Code,
+Cursor, and other compatible coding agents:
+
+```bash
+npx @cavuno/board setup
+```
 
-`board.client.fetch<T>(path, init)` sends a typed request through the full
-pipeline (board base path, headers, bearer token, hooks) for endpoints the
-SDK doesn't cover yet.
+Then ask your agent to set up the Cavuno board using the installed
+`cavuno-board-setup` skill. See
+[Set up with an agent](https://cavuno.com/docs/sdk/installing/agent)
+for the review and verification workflow.
 
-## Docs
+## Resources
 
-- Cavuno: <https://cavuno.com>
-- SDK guides and reference: <https://cavuno.com/docs/sdk>
-- API documentation: <https://cavuno.com/docs/api>
-- OpenAPI document: `GET https://api.cavuno.com/v1/openapi.json`
-- Source: <https://github.com/wollemiahq/cavuno-sdk>
-- Issues: <https://github.com/wollemiahq/cavuno-sdk/issues>
-- Clone-and-own TanStack Start + shadcn/ui template:
-  <https://github.com/wollemiahq/cavuno-tanstack-start-shadcn-job-board-template>
+- [SDK guides and reference](https://cavuno.com/docs/sdk)
+- [Board API documentation](https://cavuno.com/docs/api)
+- [OpenAPI document](https://api.cavuno.com/v1/openapi.json)
+- [Source](https://github.com/wollemiahq/cavuno-sdk)
+- [Issues](https://github.com/wollemiahq/cavuno-sdk/issues)
+- [TanStack Start + shadcn/ui job board template](https://github.com/wollemiahq/cavuno-tanstack-start-shadcn-job-board-template)
 
 MIT © Wollemia

package/dist/{_spec-COlkrizX.d.mts → _spec-BJah6GIZ.d.mts}

@@ -1,5 +1,8 @@
 interface components {
     schemas: {
+        AcceptCompanyMemberInviteBody: {
+            token: string;
+        };
         AccessCheckoutBody: {
             /**
              * @description The offer tier to purchase (from `GET /paywall/offers/enabled`).
@@ -262,6 +265,8 @@ interface components {
             email: string;
             displayName: string | null;
             emailVerified: boolean;
+            /** @description Whether the account has a password credential. False for OAuth/magic-link-only accounts; frontends use it to offer change-password vs set-password (the set flow is POST /auth/forgot-password). */
+            hasPassword: boolean;
         };
         BulkMoveApplicantsBody: {
             applicationIds: string[];
@@ -404,6 +409,34 @@ interface components {
             /** @description Source slug for the market. Use it as the `:market` segment of the market-scoped company browse. */
             slug: string;
         };
+        CompanyMember: {
+            id: string;
+            /** @enum {string} */
+            object: "company_member";
+            boardUserId: string;
+            displayName: string | null;
+            email: string;
+            /** @enum {string} */
+            role: "admin" | "member";
+            approvedBy: string | null;
+            /** Format: date-time */
+            createdAt: string;
+        };
+        CompanyMemberInvite: {
+            id: string;
+            /** @enum {string} */
+            object: "company_member_invite";
+            email: string;
+            /** Format: date-time */
+            createdAt: string;
+            /** Format: date-time */
+            expiresAt: string;
+        };
+        CompanyMemberInviteAcceptance: {
+            /** @enum {string} */
+            object: "company_member_invite_acceptance";
+            companySlug: string;
+        };
         CompanyMembership: {
             id: string;
             /** @enum {string} */
@@ -558,6 +591,9 @@ interface components {
             /** @description Live published-job count for this company on the board. */
             jobCount: number;
         };
+        ConfirmEmailChangeBody: {
+            token: string;
+        };
         ConfirmWorkEmailBody: {
             token: string;
         };
@@ -618,6 +654,10 @@ interface components {
             /** @description URL-friendly slug for the company. Auto-generated from `name` when omitted. */
             slug?: string;
         };
+        CreateCompanyMemberInviteBody: {
+            /** Format: email */
+            email: string;
+        };
         CreateEducationBody: {
             institutionName: string;
             institutionUrl?: string;
@@ -1982,6 +2022,8 @@ interface components {
             salaryCurrency: string | null;
             salaryTimeframe: string | null;
             isFeatured: boolean;
+            /** @description True when this listing is a Forager CPC / partner-feed ad persisted on the board. */
+            isSponsored: boolean;
             /** @description Plain-text card teaser derived from the job description (HTML stripped, first sentence / word-boundary cut). `null` when there is nothing honest to show. Always present — independent of the `?fields=+description` opt-in for the long-form HTML body. Prefer this over requesting `+description` for list/card renders. */
             summary: string | null;
             locationLabel: string | null;
@@ -2154,6 +2196,10 @@ interface components {
             reason: "spam" | "harassment" | "misrepresentation" | "other";
             freeText?: string;
         };
+        RequestEmailChangeBody: {
+            /** Format: email */
+            email: string;
+        };
         Resume: {
             /** @enum {string} */
             object: "resume";
@@ -2730,6 +2776,10 @@ interface components {
             jobSearchStatusVisibleTo?: "everyone" | "employers_only";
             openToRelocate?: boolean;
         };
+        UpdateCompanyMemberRoleBody: {
+            /** @enum {string} */
+            role: "admin" | "member";
+        };
         UpdateEducationBody: {
             institutionName?: string;
             institutionUrl?: string;
@@ -2775,6 +2825,11 @@ interface components {
             channel: "messageEmails" | "applicationEmails";
             subscribed: boolean;
         };
+        UpdatePasswordBody: {
+            currentPassword: string;
+            /** @description Minimum 8 characters. */
+            newPassword: string;
+        };
         UpdatePipelineStageBody: {
             label?: string;
             hidden?: boolean;

package/dist/{_spec-COlkrizX.d.ts → _spec-BJah6GIZ.d.ts}

@@ -1,5 +1,8 @@
 interface components {
     schemas: {
+        AcceptCompanyMemberInviteBody: {
+            token: string;
+        };
         AccessCheckoutBody: {
             /**
              * @description The offer tier to purchase (from `GET /paywall/offers/enabled`).
@@ -262,6 +265,8 @@ interface components {
             email: string;
             displayName: string | null;
             emailVerified: boolean;
+            /** @description Whether the account has a password credential. False for OAuth/magic-link-only accounts; frontends use it to offer change-password vs set-password (the set flow is POST /auth/forgot-password). */
+            hasPassword: boolean;
         };
         BulkMoveApplicantsBody: {
             applicationIds: string[];
@@ -404,6 +409,34 @@ interface components {
             /** @description Source slug for the market. Use it as the `:market` segment of the market-scoped company browse. */
             slug: string;
         };
+        CompanyMember: {
+            id: string;
+            /** @enum {string} */
+            object: "company_member";
+            boardUserId: string;
+            displayName: string | null;
+            email: string;
+            /** @enum {string} */
+            role: "admin" | "member";
+            approvedBy: string | null;
+            /** Format: date-time */
+            createdAt: string;
+        };
+        CompanyMemberInvite: {
+            id: string;
+            /** @enum {string} */
+            object: "company_member_invite";
+            email: string;
+            /** Format: date-time */
+            createdAt: string;
+            /** Format: date-time */
+            expiresAt: string;
+        };
+        CompanyMemberInviteAcceptance: {
+            /** @enum {string} */
+            object: "company_member_invite_acceptance";
+            companySlug: string;
+        };
         CompanyMembership: {
             id: string;
             /** @enum {string} */
@@ -558,6 +591,9 @@ interface components {
             /** @description Live published-job count for this company on the board. */
             jobCount: number;
         };
+        ConfirmEmailChangeBody: {
+            token: string;
+        };
         ConfirmWorkEmailBody: {
             token: string;
         };
@@ -618,6 +654,10 @@ interface components {
             /** @description URL-friendly slug for the company. Auto-generated from `name` when omitted. */
             slug?: string;
         };
+        CreateCompanyMemberInviteBody: {
+            /** Format: email */
+            email: string;
+        };
         CreateEducationBody: {
             institutionName: string;
             institutionUrl?: string;
@@ -1982,6 +2022,8 @@ interface components {
             salaryCurrency: string | null;
             salaryTimeframe: string | null;
             isFeatured: boolean;
+            /** @description True when this listing is a Forager CPC / partner-feed ad persisted on the board. */
+            isSponsored: boolean;
             /** @description Plain-text card teaser derived from the job description (HTML stripped, first sentence / word-boundary cut). `null` when there is nothing honest to show. Always present — independent of the `?fields=+description` opt-in for the long-form HTML body. Prefer this over requesting `+description` for list/card renders. */
             summary: string | null;
             locationLabel: string | null;
@@ -2154,6 +2196,10 @@ interface components {
             reason: "spam" | "harassment" | "misrepresentation" | "other";
             freeText?: string;
         };
+        RequestEmailChangeBody: {
+            /** Format: email */
+            email: string;
+        };
         Resume: {
             /** @enum {string} */
             object: "resume";
@@ -2730,6 +2776,10 @@ interface components {
             jobSearchStatusVisibleTo?: "everyone" | "employers_only";
             openToRelocate?: boolean;
         };
+        UpdateCompanyMemberRoleBody: {
+            /** @enum {string} */
+            role: "admin" | "member";
+        };
         UpdateEducationBody: {
             institutionName?: string;
             institutionUrl?: string;
@@ -2775,6 +2825,11 @@ interface components {
             channel: "messageEmails" | "applicationEmails";
             subscribed: boolean;
         };
+        UpdatePasswordBody: {
+            currentPassword: string;
+            /** @description Minimum 8 characters. */
+            newPassword: string;
+        };
         UpdatePipelineStageBody: {
             label?: string;
             hidden?: boolean;

package/dist/{blog-DO8Yn21_.d.mts → blog-4Owyo4U_.d.mts}

@@ -1,4 +1,4 @@
-import { S as Schemas } from './_spec-COlkrizX.mjs';
+import { S as Schemas } from './_spec-BJah6GIZ.mjs';
 
 /** Author shape embedded on posts (no `object` discriminator). */
 type BlogAuthorEmbed = Schemas['PublicBlogAuthorEmbed'];

package/dist/{blog-CgA_ljHa.d.ts → blog-DJi_1n7W.d.ts}

@@ -1,4 +1,4 @@
-import { S as Schemas } from './_spec-COlkrizX.js';
+import { S as Schemas } from './_spec-BJah6GIZ.js';
 
 /** Author shape embedded on posts (no `object` discriminator). */
 type BlogAuthorEmbed = Schemas['PublicBlogAuthorEmbed'];

package/dist/{board-JgFR-2UW.d.mts → board-CpR7o9bL.d.mts}

@@ -1,5 +1,5 @@
-import { S as Schemas } from './_spec-COlkrizX.mjs';
-import { L as ListEnvelope, m as RelatedSearch } from './jobs-C1Mxty1n.mjs';
+import { S as Schemas } from './_spec-BJah6GIZ.mjs';
+import { L as ListEnvelope, m as RelatedSearch } from './jobs-C27qlt6o.mjs';
 
 type PublicCompany = Schemas['CompanyPublic'];
 /** A market (sector) a company operates in — name + its source slug. */

package/dist/{board-D51C3gB5.d.ts → board-KDx9U0nw.d.ts}

@@ -1,5 +1,5 @@
-import { S as Schemas } from './_spec-COlkrizX.js';
-import { L as ListEnvelope, m as RelatedSearch } from './jobs-DOF3QXdq.js';
+import { S as Schemas } from './_spec-BJah6GIZ.js';
+import { L as ListEnvelope, m as RelatedSearch } from './jobs-Ay-V6Q6y.js';
 
 type PublicCompany = Schemas['CompanyPublic'];
 /** A market (sector) a company operates in — name + its source slug. */

package/dist/{breadcrumbs-_QzN4nEk.d.ts → breadcrumbs-CJ-NpA-V.d.ts}

@@ -1,5 +1,5 @@
-import { P as PublicBoard, a as CompanyCategorySalary, b as CompanySalary, L as LocationSalaryDetail, S as SkillSalaryDetail, T as TitleSalaryDetail } from './board-D51C3gB5.js';
-import { P as PublicJob } from './jobs-DOF3QXdq.js';
+import { P as PublicBoard, a as CompanyCategorySalary, b as CompanySalary, L as LocationSalaryDetail, S as SkillSalaryDetail, T as TitleSalaryDetail } from './board-KDx9U0nw.js';
+import { P as PublicJob } from './jobs-Ay-V6Q6y.js';
 
 /**
  * Wire enum for `salaryTimeframe`. Defined here (not re-exported from any

package/dist/{breadcrumbs-zAN2biAq.d.mts → breadcrumbs-DOJH_7nO.d.mts}

@@ -1,5 +1,5 @@
-import { P as PublicBoard, a as CompanyCategorySalary, b as CompanySalary, L as LocationSalaryDetail, S as SkillSalaryDetail, T as TitleSalaryDetail } from './board-JgFR-2UW.mjs';
-import { P as PublicJob } from './jobs-C1Mxty1n.mjs';
+import { P as PublicBoard, a as CompanyCategorySalary, b as CompanySalary, L as LocationSalaryDetail, S as SkillSalaryDetail, T as TitleSalaryDetail } from './board-CpR7o9bL.mjs';
+import { P as PublicJob } from './jobs-C27qlt6o.mjs';
 
 /**
  * Wire enum for `salaryTimeframe`. Defined here (not re-exported from any