@cavuno/board 4.27.0 → 4.28.0

package/dist/index.js

@@ -89,6 +89,9 @@ var BOARD_API_ERROR_CODES = [
   "categories_not_found",
   "skills_not_found",
   "places_not_found",
+  // Location search + `locationId` on job office locations
+  "locations_invalid_id",
+  "locations_unavailable",
   // Companies (public reads)
   "companies_not_found",
   "company_markets_not_found",
@@ -120,6 +123,7 @@ var BOARD_API_ERROR_CODES = [
   "candidate_handle_taken",
   "candidate_job_not_found",
   "candidate_notification_preference_paused",
+  "candidate_profile_required",
   "resume_invalid_file",
   "resume_upload_forbidden",
   // Applications
@@ -359,7 +363,7 @@ async function clearSession(storage) {
 }
 
 // src/version.ts
-var SDK_VERSION = "4.27.0";
+var SDK_VERSION = "4.28.0";
 
 // src/client.ts
 function isRawBody(body) {
@@ -1234,6 +1238,37 @@ function jobsNamespace(client) {
   };
 }
 
+// src/namespaces/locations.ts
+function locationsNamespace(client) {
+  return {
+    /**
+     * GET /locations/search — worldwide autocomplete over countries,
+     * regions, cities, and localities, not only places the board's jobs already
+     * use (that is `taxonomy.places.list({ q })`). Order is the contract: do
+     * not re-sort. Complete a pick with `locations.resolve` using the same
+     * session before sending its `id` as `locationId` later.
+     *
+     * @example
+     * const session = crypto.randomUUID();
+     * const { data } = await board.locations.search({ q: 'berl', session });
+     */
+    search(query, options) {
+      return client.fetch("/locations/search", {
+        ...options,
+        query
+      });
+    },
+    /** Complete a picked suggestion with the same search session. */
+    resolve(input, options) {
+      return client.fetch("/locations/resolve", {
+        ...options,
+        method: "POST",
+        body: input
+      });
+    }
+  };
+}
+
 // src/namespaces/me.ts
 function meNamespace(client) {
   return {
@@ -1995,15 +2030,19 @@ function meNamespace(client) {
         /**
          * Pay for / publish a held draft. Select billing: a paid plan
          * returns `{ status: 'checkout', checkoutUrl }` (send the buyer there;
-         * the webhook publishes on payment); a free / bundle / subscription plan
-         * publishes immediately (`status: 'published'`); an invoice plan emails a
-         * Stripe invoice (`status: 'invoice_sent'`).
+         * the webhook publishes on payment); a free plan publishes immediately
+         * (`status: 'published'`) unless the board requires free-job approval
+         * (`status: 'pending_approval'`); bundle, subscription, and member-credit
+         * posts always publish immediately; an invoice plan emails a Stripe
+         * invoice (`status: 'invoice_sent'`) or holds an on-issue post for
+         * approval.
          *
          * @example
          * const r = await board.me.companies.jobs.checkout('acme', jobId, {
          *   billing: { type: 'new', planId },
          * });
          * if (r.status === 'checkout') location.href = r.checkoutUrl!;
+         * if (r.status === 'pending_approval') showAwaitingReview(r.jobId);
          */
         checkout(slug, id, body, options) {
           return client.fetch(
@@ -3665,6 +3704,7 @@ function createBoardClient(options) {
     password: passwordNamespace(client),
     taxonomy: taxonomyNamespace(client),
     search: searchNamespace(client),
+    locations: locationsNamespace(client),
     redirects: redirectsNamespace(client),
     jobAlerts: jobAlertsNamespace(client),
     jobPosting: jobPostingNamespace(client),

package/dist/index.mjs

@@ -21,7 +21,7 @@ import {
   isRateLimited,
   isUnauthorized,
   isValidationError
-} from "./chunk-DUTQOLOF.mjs";
+} from "./chunk-EHSB2VAJ.mjs";
 
 // src/query.ts
 function toSearchParams(query) {
@@ -42,7 +42,7 @@ function toSearchParams(query) {
 }
 
 // src/version.ts
-var SDK_VERSION = "4.27.0";
+var SDK_VERSION = "4.28.0";
 
 // src/client.ts
 function isRawBody(body) {
@@ -917,6 +917,37 @@ function jobsNamespace(client) {
   };
 }
 
+// src/namespaces/locations.ts
+function locationsNamespace(client) {
+  return {
+    /**
+     * GET /locations/search — worldwide autocomplete over countries,
+     * regions, cities, and localities, not only places the board's jobs already
+     * use (that is `taxonomy.places.list({ q })`). Order is the contract: do
+     * not re-sort. Complete a pick with `locations.resolve` using the same
+     * session before sending its `id` as `locationId` later.
+     *
+     * @example
+     * const session = crypto.randomUUID();
+     * const { data } = await board.locations.search({ q: 'berl', session });
+     */
+    search(query, options) {
+      return client.fetch("/locations/search", {
+        ...options,
+        query
+      });
+    },
+    /** Complete a picked suggestion with the same search session. */
+    resolve(input, options) {
+      return client.fetch("/locations/resolve", {
+        ...options,
+        method: "POST",
+        body: input
+      });
+    }
+  };
+}
+
 // src/namespaces/me.ts
 function meNamespace(client) {
   return {
@@ -1678,15 +1709,19 @@ function meNamespace(client) {
         /**
          * Pay for / publish a held draft. Select billing: a paid plan
          * returns `{ status: 'checkout', checkoutUrl }` (send the buyer there;
-         * the webhook publishes on payment); a free / bundle / subscription plan
-         * publishes immediately (`status: 'published'`); an invoice plan emails a
-         * Stripe invoice (`status: 'invoice_sent'`).
+         * the webhook publishes on payment); a free plan publishes immediately
+         * (`status: 'published'`) unless the board requires free-job approval
+         * (`status: 'pending_approval'`); bundle, subscription, and member-credit
+         * posts always publish immediately; an invoice plan emails a Stripe
+         * invoice (`status: 'invoice_sent'`) or holds an on-issue post for
+         * approval.
          *
          * @example
          * const r = await board.me.companies.jobs.checkout('acme', jobId, {
          *   billing: { type: 'new', planId },
          * });
          * if (r.status === 'checkout') location.href = r.checkoutUrl!;
+         * if (r.status === 'pending_approval') showAwaitingReview(r.jobId);
          */
         checkout(slug, id, body, options) {
           return client.fetch(
@@ -3318,6 +3353,7 @@ function createBoardClient(options) {
     password: passwordNamespace(client),
     taxonomy: taxonomyNamespace(client),
     search: searchNamespace(client),
+    locations: locationsNamespace(client),
     redirects: redirectsNamespace(client),
     jobAlerts: jobAlertsNamespace(client),
     jobPosting: jobPostingNamespace(client),

package/dist/{jobs-R-h3A3kl.d.mts → jobs-CEIuahbz.d.ts}

@@ -1,4 +1,4 @@
-import { S as Schemas } from './_spec-B_pBNVUd.mjs';
+import { S as Schemas } from './_spec-DQvmsp5o.js';
 
 /**
  * Optional pagination metadata returned by Board API list operations.
@@ -119,11 +119,13 @@ type ObjectReferenceFilter = {
     key: string;
     recordIds: string[];
 };
-type GeneratedJobsSearchBody = Schemas['PublicSearchJobsBody'];
-type JobsSearchBody = Omit<GeneratedJobsSearchBody, 'filters'> & {
-    filters?: NonNullable<GeneratedJobsSearchBody['filters']> & {
-        customFields?: CustomFieldFilter[];
-    };
-};
+/**
+ * The `jobs.search` body, aliased from the spec like the response types.
+ * `filters.customFields` matches the job's own custom fields and
+ * `filters.companyCustomFields` the public profile fields of the job's
+ * company; both take {@link CustomFieldFilter} clauses (the tests pin that
+ * the spec shape and `CustomFieldFilter` stay identical).
+ */
+type JobsSearchBody = Schemas['PublicSearchJobsBody'];
 
 export type { CustomFieldValues as C, EmploymentType as E, JobSort as J, ListEnvelope as L, ObjectReferenceFilter as O, PublicJob as P, RemoteOption as R, Seniority as S, CustomFieldFilter as a, JobCollectionChoiceQuery as b, JobsListQuery as c, JobCardListEnvelope as d, JobsSearchBody as e, JobCardSearchEnvelope as f, JobsSimilarQuery as g, SearchEnvelope as h, CustomFieldValue as i, CustomFilterValue as j, EducationRequirement as k, JobCatalogPagination as l, JobCollectionChoiceList as m, JobCollectionFieldDefinition as n, JobCompany as o, OfficeLocation as p, OffsetPagination as q, PublicJobCard as r, RelatedSearch as s, RemotePermit as t, RemoteTimezone as u, ResolvedJobCollectionField as v, StorefrontPagination as w };

package/dist/{jobs-BRysn2m0.d.ts → jobs-DjMcghv6.d.mts}

@@ -1,4 +1,4 @@
-import { S as Schemas } from './_spec-B_pBNVUd.js';
+import { S as Schemas } from './_spec-DQvmsp5o.mjs';
 
 /**
  * Optional pagination metadata returned by Board API list operations.
@@ -119,11 +119,13 @@ type ObjectReferenceFilter = {
     key: string;
     recordIds: string[];
 };
-type GeneratedJobsSearchBody = Schemas['PublicSearchJobsBody'];
-type JobsSearchBody = Omit<GeneratedJobsSearchBody, 'filters'> & {
-    filters?: NonNullable<GeneratedJobsSearchBody['filters']> & {
-        customFields?: CustomFieldFilter[];
-    };
-};
+/**
+ * The `jobs.search` body, aliased from the spec like the response types.
+ * `filters.customFields` matches the job's own custom fields and
+ * `filters.companyCustomFields` the public profile fields of the job's
+ * company; both take {@link CustomFieldFilter} clauses (the tests pin that
+ * the spec shape and `CustomFieldFilter` stay identical).
+ */
+type JobsSearchBody = Schemas['PublicSearchJobsBody'];
 
 export type { CustomFieldValues as C, EmploymentType as E, JobSort as J, ListEnvelope as L, ObjectReferenceFilter as O, PublicJob as P, RemoteOption as R, Seniority as S, CustomFieldFilter as a, JobCollectionChoiceQuery as b, JobsListQuery as c, JobCardListEnvelope as d, JobsSearchBody as e, JobCardSearchEnvelope as f, JobsSimilarQuery as g, SearchEnvelope as h, CustomFieldValue as i, CustomFilterValue as j, EducationRequirement as k, JobCatalogPagination as l, JobCollectionChoiceList as m, JobCollectionFieldDefinition as n, JobCompany as o, OfficeLocation as p, OffsetPagination as q, PublicJobCard as r, RelatedSearch as s, RemotePermit as t, RemoteTimezone as u, ResolvedJobCollectionField as v, StorefrontPagination as w };

package/dist/{search-BlB690ma.d.mts → search-C0LiPXVb.d.mts}

@@ -1,4 +1,4 @@
-import { S as Schemas } from './_spec-B_pBNVUd.mjs';
+import { S as Schemas } from './_spec-DQvmsp5o.mjs';
 
 type Awaitable<T> = T | Promise<T>;
 /**

package/dist/{search-BK_zHHNQ.d.ts → search-D-EjtZH3.d.ts}

@@ -1,4 +1,4 @@
-import { S as Schemas } from './_spec-B_pBNVUd.js';
+import { S as Schemas } from './_spec-DQvmsp5o.js';
 
 type Awaitable<T> = T | Promise<T>;
 /**

package/dist/{seo-C7gMl6Y7.d.ts → seo-CjNGqZZH.d.ts}

@@ -1,4 +1,4 @@
-import { S as Schemas } from './_spec-B_pBNVUd.js';
+import { S as Schemas } from './_spec-DQvmsp5o.js';
 
 /**
  * The public SEO-infra payload (`board.seo()`) — platform infrastructure a

package/dist/{seo-0mbZ7M_E.d.mts → seo-DCQp8V1c.d.mts}

@@ -1,4 +1,4 @@
-import { S as Schemas } from './_spec-B_pBNVUd.mjs';
+import { S as Schemas } from './_spec-DQvmsp5o.mjs';
 
 /**
  * The public SEO-infra payload (`board.seo()`) — platform infrastructure a

package/dist/seo-files.d.mts

@@ -1,5 +1,5 @@
-import { B as BoardSeo } from './seo-0mbZ7M_E.mjs';
-import './_spec-B_pBNVUd.mjs';
+import { B as BoardSeo } from './seo-DCQp8V1c.mjs';
+import './_spec-DQvmsp5o.mjs';
 
 /**
  * `@cavuno/board/seo-files` — platform-owned crawler/identity file bodies

package/dist/seo-files.d.ts

@@ -1,5 +1,5 @@
-import { B as BoardSeo } from './seo-C7gMl6Y7.js';
-import './_spec-B_pBNVUd.js';
+import { B as BoardSeo } from './seo-CjNGqZZH.js';
+import './_spec-DQvmsp5o.js';
 
 /**
  * `@cavuno/board/seo-files` — platform-owned crawler/identity file bodies

package/dist/seo.d.mts

@@ -1,9 +1,9 @@
-import { P as PublicBlogPostSummary, B as BlogAuthorEmbed } from './blog-fhXRik6k.mjs';
-import { e as JsonLdObject } from './breadcrumbs-qE3CD--N.mjs';
-export { A as ALL_COUNTRY_CODES, B as BreadcrumbItemInput, g as FaqItem, J as JobBreadcrumb, h as JsonLdBoard, N as NumberNotation, i as SENIORITY_ORDER, j as SalaryFaqEntry, k as SalaryJsonLdOptions, l as SalaryOccupationListOptions, b as buildJobBreadcrumbs, m as buildSalaryFaq, o as companyCategorySalaryJsonLd, p as companySalaryJsonLd, q as createBreadcrumbJsonLd, r as createJobPostingJsonLd, s as crossAxisSalaryJsonLd, t as faqJsonLd, c as formatSalaryStat, d as formatSalaryStatRange, u as itemListJsonLd, v as locationSalaryJsonLd, n as normalizeWebsiteUrl, w as skillSalaryJsonLd, x as sortBySeniority, y as titleSalaryJsonLd } from './breadcrumbs-qE3CD--N.mjs';
-import './_spec-B_pBNVUd.mjs';
-import './board-DEiEHcpe.mjs';
-import './jobs-R-h3A3kl.mjs';
+import { P as PublicBlogPostSummary, B as BlogAuthorEmbed } from './blog-CvuObn9O.mjs';
+import { e as JsonLdObject } from './breadcrumbs-BBvJ5gq-.mjs';
+export { A as ALL_COUNTRY_CODES, B as BreadcrumbItemInput, g as FaqItem, J as JobBreadcrumb, h as JsonLdBoard, N as NumberNotation, i as SENIORITY_ORDER, j as SalaryFaqEntry, k as SalaryJsonLdOptions, l as SalaryOccupationListOptions, b as buildJobBreadcrumbs, m as buildSalaryFaq, o as companyCategorySalaryJsonLd, p as companySalaryJsonLd, q as createBreadcrumbJsonLd, r as createJobPostingJsonLd, s as crossAxisSalaryJsonLd, t as faqJsonLd, c as formatSalaryStat, d as formatSalaryStatRange, u as itemListJsonLd, v as locationSalaryJsonLd, n as normalizeWebsiteUrl, w as skillSalaryJsonLd, x as sortBySeniority, y as titleSalaryJsonLd } from './breadcrumbs-BBvJ5gq-.mjs';
+import './_spec-DQvmsp5o.mjs';
+import './board-D6xOidUX.mjs';
+import './jobs-DjMcghv6.mjs';
 
 /**
  * Blog structured data on the `@cavuno/board` wire types, transcribed from

package/dist/seo.d.ts

@@ -1,9 +1,9 @@
-import { P as PublicBlogPostSummary, B as BlogAuthorEmbed } from './blog-DzGRUsj5.js';
-import { e as JsonLdObject } from './breadcrumbs-DNaaP3xa.js';
-export { A as ALL_COUNTRY_CODES, B as BreadcrumbItemInput, g as FaqItem, J as JobBreadcrumb, h as JsonLdBoard, N as NumberNotation, i as SENIORITY_ORDER, j as SalaryFaqEntry, k as SalaryJsonLdOptions, l as SalaryOccupationListOptions, b as buildJobBreadcrumbs, m as buildSalaryFaq, o as companyCategorySalaryJsonLd, p as companySalaryJsonLd, q as createBreadcrumbJsonLd, r as createJobPostingJsonLd, s as crossAxisSalaryJsonLd, t as faqJsonLd, c as formatSalaryStat, d as formatSalaryStatRange, u as itemListJsonLd, v as locationSalaryJsonLd, n as normalizeWebsiteUrl, w as skillSalaryJsonLd, x as sortBySeniority, y as titleSalaryJsonLd } from './breadcrumbs-DNaaP3xa.js';
-import './_spec-B_pBNVUd.js';
-import './board-fVAXZ8T5.js';
-import './jobs-BRysn2m0.js';
+import { P as PublicBlogPostSummary, B as BlogAuthorEmbed } from './blog-CUkvhn3c.js';
+import { e as JsonLdObject } from './breadcrumbs-D2Cwrju4.js';
+export { A as ALL_COUNTRY_CODES, B as BreadcrumbItemInput, g as FaqItem, J as JobBreadcrumb, h as JsonLdBoard, N as NumberNotation, i as SENIORITY_ORDER, j as SalaryFaqEntry, k as SalaryJsonLdOptions, l as SalaryOccupationListOptions, b as buildJobBreadcrumbs, m as buildSalaryFaq, o as companyCategorySalaryJsonLd, p as companySalaryJsonLd, q as createBreadcrumbJsonLd, r as createJobPostingJsonLd, s as crossAxisSalaryJsonLd, t as faqJsonLd, c as formatSalaryStat, d as formatSalaryStatRange, u as itemListJsonLd, v as locationSalaryJsonLd, n as normalizeWebsiteUrl, w as skillSalaryJsonLd, x as sortBySeniority, y as titleSalaryJsonLd } from './breadcrumbs-D2Cwrju4.js';
+import './_spec-DQvmsp5o.js';
+import './board-CCG1pO6r.js';
+import './jobs-CEIuahbz.js';
 
 /**
  * Blog structured data on the `@cavuno/board` wire types, transcribed from

package/dist/server.d.mts

@@ -1,10 +1,10 @@
 import { BoardSdk } from './index.mjs';
-import './_spec-B_pBNVUd.mjs';
-import './search-BlB690ma.mjs';
-import './board-DEiEHcpe.mjs';
-import './jobs-R-h3A3kl.mjs';
-import './seo-0mbZ7M_E.mjs';
-import './blog-fhXRik6k.mjs';
+import './_spec-DQvmsp5o.mjs';
+import './search-C0LiPXVb.mjs';
+import './board-D6xOidUX.mjs';
+import './jobs-DjMcghv6.mjs';
+import './seo-DCQp8V1c.mjs';
+import './blog-CvuObn9O.mjs';
 
 /**
  * Session cookie codec — pure (no framework imports, no node imports) so it

package/dist/server.d.ts

@@ -1,10 +1,10 @@
 import { BoardSdk } from './index.js';
-import './_spec-B_pBNVUd.js';
-import './search-BK_zHHNQ.js';
-import './board-fVAXZ8T5.js';
-import './jobs-BRysn2m0.js';
-import './seo-C7gMl6Y7.js';
-import './blog-DzGRUsj5.js';
+import './_spec-DQvmsp5o.js';
+import './search-D-EjtZH3.js';
+import './board-CCG1pO6r.js';
+import './jobs-CEIuahbz.js';
+import './seo-CjNGqZZH.js';
+import './blog-CUkvhn3c.js';
 
 /**
  * Session cookie codec — pure (no framework imports, no node imports) so it

package/dist/server.mjs

@@ -4,7 +4,7 @@ import {
 } from "./chunk-Z4ALWIGS.mjs";
 import {
   isUnauthorized
-} from "./chunk-DUTQOLOF.mjs";
+} from "./chunk-EHSB2VAJ.mjs";
 
 // src/server/cookie.ts
 var COOKIE_ATTRIBUTES = "Path=/; HttpOnly; Secure; SameSite=Lax";

package/dist/sitemap.d.mts

@@ -1,10 +1,10 @@
 import { BoardSdk } from './index.mjs';
-import './_spec-B_pBNVUd.mjs';
-import './search-BlB690ma.mjs';
-import './board-DEiEHcpe.mjs';
-import './jobs-R-h3A3kl.mjs';
-import './seo-0mbZ7M_E.mjs';
-import './blog-fhXRik6k.mjs';
+import './_spec-DQvmsp5o.mjs';
+import './search-C0LiPXVb.mjs';
+import './board-D6xOidUX.mjs';
+import './jobs-DjMcghv6.mjs';
+import './seo-DCQp8V1c.mjs';
+import './blog-CvuObn9O.mjs';
 
 /**
  * Sitemap primitives — the pure XML + bucket-filename logic behind a board

package/dist/sitemap.d.ts

@@ -1,10 +1,10 @@
 import { BoardSdk } from './index.js';
-import './_spec-B_pBNVUd.js';
-import './search-BK_zHHNQ.js';
-import './board-fVAXZ8T5.js';
-import './jobs-BRysn2m0.js';
-import './seo-C7gMl6Y7.js';
-import './blog-DzGRUsj5.js';
+import './_spec-DQvmsp5o.js';
+import './search-D-EjtZH3.js';
+import './board-CCG1pO6r.js';
+import './jobs-CEIuahbz.js';
+import './seo-CjNGqZZH.js';
+import './blog-CUkvhn3c.js';
 
 /**
  * Sitemap primitives — the pure XML + bucket-filename logic behind a board

package/dist/sitemap.mjs

@@ -3,7 +3,7 @@ import {
 } from "./chunk-DLSO6XXY.mjs";
 import {
   isNotFound
-} from "./chunk-DUTQOLOF.mjs";
+} from "./chunk-EHSB2VAJ.mjs";
 import {
   BOARD_PATHS,
   blogAuthorPath,

package/dist/suggest.d.mts

@@ -1,5 +1,5 @@
-import { h as SuggestionItem, b as SearchSuggestQuery, F as FetchOptions, g as SuggestResult } from './search-BlB690ma.mjs';
-import './_spec-B_pBNVUd.mjs';
+import { h as SuggestionItem, b as SearchSuggestQuery, F as FetchOptions, g as SuggestResult } from './search-C0LiPXVb.mjs';
+import './_spec-DQvmsp5o.mjs';
 
 /**
  * `@cavuno/board/suggest` — framework-agnostic headless search-suggest

package/dist/suggest.d.ts

@@ -1,5 +1,5 @@
-import { h as SuggestionItem, b as SearchSuggestQuery, F as FetchOptions, g as SuggestResult } from './search-BK_zHHNQ.js';
-import './_spec-B_pBNVUd.js';
+import { h as SuggestionItem, b as SearchSuggestQuery, F as FetchOptions, g as SuggestResult } from './search-D-EjtZH3.js';
+import './_spec-DQvmsp5o.js';
 
 /**
  * `@cavuno/board/suggest` — framework-agnostic headless search-suggest

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cavuno/board",
-  "version": "4.27.0",
+  "version": "4.28.0",
   "description": "Build custom job boards and careers pages with Cavuno’s TypeScript SDK.",
   "keywords": [
     "api-client",

package/skills/cavuno-board-account/SKILL.md

@@ -11,6 +11,31 @@ Anonymous methods here are token-based email unsubscribe and email-change confir
 
 The host application owns forms, file pickers, and cookie plumbing; this SDK surface supplies data operations.
 
+## Candidate screens are candidate-only
+
+A board user is either a candidate or an employer (`me.role`). Only candidates have a candidate profile. Render candidate screens and fields (the profile form, profile completeness, resume upload, experience, education, skills, and languages) only when `me.role === 'candidate'`. On the account page, give an employer account the employer profile view instead: avatar, `displayName` (the one profile field every account can update), and a link to the employer screens (`board.me.companies.*`). Never show them the empty candidate form.
+
+The API is the backstop: a profile write from an account with no candidate profile returns 403 `candidate_profile_required` before anything is saved. `displayName` alone is the one profile field every account can update. Surface this error as a message; never swallow it and report "Saved".
+
+```ts snippet
+import { isBoardApiError } from '@cavuno/board';
+
+const me = await board.me.retrieve();
+if (me.role !== 'candidate') {
+  return renderEmployerProfile(me); // avatar, displayName, link to employer screens
+}
+
+try {
+  await board.me.profile.update({ headline: 'Staff Engineer' });
+  showSaved();
+} catch (error) {
+  if (isBoardApiError(error) && error.code === 'candidate_profile_required') {
+    return showError('Only candidate accounts have a candidate profile.');
+  }
+  throw error;
+}
+```
+
 ## Account and profile
 
 Account deletion is a synchronous, irreversible cascade over the profile, collections, saved jobs, alerts, avatar, and resume. Obtain explicit confirmation before calling it.
@@ -252,6 +277,8 @@ await board.me.notificationPreferences.unsubscribeWithToken({
 
 ## Completion gate
 
+- Candidate screens render only for `me.role === 'candidate'`; an employer account gets the employer profile view (avatar, `displayName`, link to employer screens).
+- A `candidate_profile_required` 403 shows an error and never a "Saved" state.
 - The profile form follows `forms.talent`: order matches, hidden fields are absent, and required fields block save while empty.
 - Profile update is visible after retrieval.
 - Scalar field updates preserve omitted values; collection selection updates preserve every selection the user meant to keep.

package/skills/cavuno-board-errors/SKILL.md

@@ -44,7 +44,7 @@ try {
 }
 ```
 
-The remaining status guards are `isForbidden` for 403 and `isConflict` for 409. Record `code` and `requestId` in support diagnostics. Because v1 may add error codes, unmatched `BoardApiError` instances still need a safe generic state.
+The remaining status guards are `isForbidden` for 403 and `isConflict` for 409. A 403 `candidate_profile_required` means an account that is not a candidate (for example an employer) tried to write candidate profile data: gate candidate screens on `me.role === 'candidate'` and show the error rather than a success state. Record `code` and `requestId` in support diagnostics. Because v1 may add error codes, unmatched `BoardApiError` instances still need a safe generic state.
 
 **Complete when:** every expected failure has one typed branch, an invalid resource renders not-found, and unmatched failures retain their original error.
 

package/skills/cavuno-board-filters/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cavuno-board-filters
-description: Listing-filter contracts with @cavuno/board. Use for job filter controls, profile-field filters, collection choices, sort controls, listing URL validation, or taxonomy-backed filter options.
+description: Listing-filter contracts with @cavuno/board. Use for job filter controls, job and company custom-field filters, profile-field filters, collection choices, sort controls, listing URL validation, or taxonomy-backed filter options.
 ---
 
 # Listing filters
@@ -150,6 +150,60 @@ const { items } = await board.search.suggest({
 The host router owns URL serialization and saved-filter persistence.
 Locations come from `board.taxonomy.places` rather than a static filter export.
 
+## Filter jobs by a job custom field
+
+The operator's job custom fields arrive as definitions on
+`board.context().customFields.job`. Expose a field as a filter only when the
+operator intends it as one: keep an explicit list of filter keys in your app
+config. Do not render a dropdown for every select field automatically; most
+custom fields are details for the job page, not listing facets.
+
+```ts snippet
+const context = await board.context();
+
+// The operator picked these; everything else stays a job-page detail.
+const FILTER_FIELD_KEYS = ['work_type'];
+const filterFields = context.customFields.job.filter(
+  (field) =>
+    FILTER_FIELD_KEYS.includes(field.key) &&
+    (field.type === 'single_select' || field.type === 'multi_select'));
+
+// Controls: option KEYS are the values, option labels are the text.
+const controls = filterFields.map((field) => ({
+  key: field.key,
+  label: field.label,
+  options: (field.options ?? []).map((option) => ({
+    value: option.key,
+    label: option.label,
+  })),
+}));
+
+// URL state holds option keys (`/jobs?work_type=contract`), never labels.
+// Drop anything that is not a current option before it reaches the API.
+const customFields = filterFields.flatMap((field) => {
+  const values = searchParams
+    .getAll(field.key)
+    .filter((value) => field.options?.some((option) => option.key === value));
+  return values.length > 0 ? [{ key: field.key, values }] : [];
+});
+
+const results = await board.jobs.search({
+  query: filters.q,
+  filters: {
+    seniority: filters.seniority,
+    customFields: customFields.length > 0 ? customFields : undefined,
+  },
+  limit: 20,
+});
+```
+
+Clauses are AND-matched; values inside one clause are alternatives. Each
+request takes at most 10 clauses of 10 values. An unknown key or an option key
+the field no longer offers returns `invalid_filter`, so validate URL input
+against the definitions as above. Boolean and number fields filter the same way
+with `values: [true]` or `values: [3]`. Labels change when the operator renames
+an option; keys do not, so bookmarked URLs keep working.
+
 ## Build filters from public profile fields
 
 `board.profileFields.retrieve('company')` and `retrieve('candidate')` return only public scalar and collection-reference definitions. Use each stored field key for filtering. For a collection reference, page or search its active public choices and submit the returned record `id`; the optional `logoUrl` is display metadata.
@@ -189,6 +243,36 @@ void talent.data;
 
 Clauses are AND-matched. Values or record IDs inside one clause are alternatives. Unknown, private, invalid, or archived choices return `invalid_filter`; each array accepts at most 10 clauses and each clause at most 10 choices. Job search supports scalar `customFields` under `filters`, but job collection references are outside this surface.
 
+## Filter jobs by job and company custom fields
+
+`jobs.search` takes two custom-field filters. `filters.customFields` matches the job's own fields, defined in `board.context().customFields.job`. `filters.companyCustomFields` matches the public profile fields of the job's company, defined in `board.profileFields.retrieve('company')`. Both use the clause shape above; the two lists never share keys, so a job field and a company field may both be called `type`.
+
+```ts snippet
+const [context, companyFields] = await Promise.all([
+  board.context(),
+  board.profileFields.retrieve('company'),
+]);
+const opportunityType = context.customFields.job.find(
+  (field) => field.key === 'opportunity_type');
+const employerType = companyFields.definitions.find(
+  (field) => field.key === 'employer_type');
+
+const results = await board.jobs.search({
+  query: filters.q,
+  filters: {
+    customFields: [{ key: 'opportunity_type', values: ['identified'] }],
+    companyCustomFields: [{ key: 'employer_type', values: ['acco'] }],
+  },
+  limit: 20,
+});
+
+void opportunityType;
+void employerType;
+void results.data;
+```
+
+Render each dropdown from the definition's `options` in order: show `label`, submit `key`, and keep the key in the URL so shared links survive a label change. Accept only keys the current definition offers; drop anything else from a hand-typed URL. Only `jobs.search` takes these filters. A company's jobs are re-indexed automatically when its values change. Worked example: [Custom field filters and badges](https://cavuno.com/docs/sdk/cookbook/custom-field-filters-and-badges).
+
 ## Completion gate
 
 Finish only after every applicable check passes:
@@ -204,8 +288,13 @@ Finish only after every applicable check passes:
 - `/jobs?category=engineering,design` sends
   `filters.categories: ['engineering', 'design']` to `jobs.search`.
 - Every paged taxonomy request forwards the previous opaque `nextCursor`.
+- Job custom-field controls exist only for keys the operator chose as
+  filters, read their options from `board.context().customFields.job`, and send
+  option keys in `filters.customFields`; an unknown option in the URL never
+  reaches the API.
 - Company and talent custom controls come from `board.profileFields`; private definitions and archived choices never become filter options.
 - Profile-filter requests use stored scalar values and returned collection entry IDs, not display labels.
+- Job-field dropdowns send `filters.customFields` and company-field dropdowns send `filters.companyCustomFields` to `jobs.search`, both built from the current definitions; a stale option key in the URL is dropped, not sent.
 
 ## Cavuno SDK reference