@cavuno/board 4.27.0 → 4.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cavuno/board",
-  "version": "4.27.0",
+  "version": "4.29.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
 

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

@@ -96,6 +96,55 @@ the same card view-model as listings — do not convert a full job client-side.
 const card = toJobCardVM(saved.job, { language, /* … */ });
 ```
 
+## Badges on job cards
+
+Every job card (listings, search, company jobs, similar, recommended, and
+saved jobs) carries `customFieldValues` for the job and
+`company.customFieldValues` for its company. Both hold only select, boolean,
+and number values keyed by field key; select values are option keys. Text
+fields stay on the full job and company, and private company fields never
+appear. Both are `{}` when empty, so a card needs no extra request to show a
+badge.
+
+```ts snippet
+import { resolveCustomFieldDisplay } from '@cavuno/board/format';
+
+const context = await board.context();
+const companyFields = await board.profileFields.retrieve('company');
+
+// Badge only the fields the operator wants on cards (an app-config list).
+const JOB_BADGE_KEYS = ['work_type'];
+const jobBadges = resolveCustomFieldDisplay(
+  context.language,
+  context.customFields.job.filter((field) => JOB_BADGE_KEYS.includes(field.key)),
+  card.customFieldValues).flatMap((entry) => {
+  switch (entry.kind) {
+    case 'text': // a single_select resolves to its option label
+      return [entry.value];
+    case 'multi_select':
+      return entry.values;
+    case 'boolean':
+      return entry.value ? [entry.label] : [];
+    case 'number':
+      return [`${entry.label}: ${entry.value}`];
+  }
+});
+
+// Company badge: resolve the stored option key to its public label.
+const employerField = companyFields.definitions.find(
+  (field) => field.key === 'employer_category');
+const employerKey = card.company?.customFieldValues.employer_category;
+const employerBadge =
+  typeof employerKey === 'string'
+    ? (employerField?.options?.find((option) => option.key === employerKey)
+        ?.label ?? null)
+    : null;
+```
+
+Load the definitions once per page (both are cacheable board metadata), not
+once per card. A key with no current definition or option resolves to nothing:
+drop the badge rather than printing the raw key.
+
 ## Completion gate
 
 Finish only after every applicable check passes:
@@ -107,6 +156,9 @@ Finish only after every applicable check passes:
 - Open ranges return `bound: 'from' | 'upTo'`; the application adds open-range
   chrome and composes order itself.
 - Saved jobs arrive as cards; no `fullJobToCard` conversion.
+- Card badges read `card.customFieldValues` / `card.company.customFieldValues`
+  and resolve option keys to labels through the definitions; no raw key is
+  shown and no card triggers a per-job detail fetch.
 - Salary-stat formatters receive the detail's `currency` (never invent USD).
 - Formatting changes neither salary amounts nor invents chrome words.
 

package/skills/cavuno-board-post-a-job/SKILL.md

@@ -87,6 +87,30 @@ The list replaces the job's wording: omit it on `update` to keep what is stored,
 
 Validate `required` client-side from these entries before submitting, so the poster sees a missing field before the request.
 
+## Pick office locations
+
+Back the `location` field with `board.locations.search`, a worldwide search over countries, regions, cities, and localities. `session` is required: generate one per location-field interaction, reuse it across keystrokes and the pick-time `board.locations.resolve` call, then generate a new one for the next interaction. Renew it before 50 search requests or after 180 seconds. Pass `jobForm.location.allowedCountries` as `country` to narrow suggestions to the board's allowed countries.
+
+```ts snippet
+const session = crypto.randomUUID();
+const { data: locations } = await board.locations.search({
+  q: 'berl',
+  session,
+  country: jobForm.location.allowedCountries?.join(','),
+});
+
+const picked = locations[0];
+if (picked) {
+  const location = await board.locations.resolve({
+    locationId: picked.id,
+    session,
+  });
+  submission.officeLocations.push({ locationId: location.id });
+}
+```
+
+Show `fullName` in the input once picked and `contextLabel` as the secondary line in the result list. Resolve the picked `id` with the same session before committing the selection, then send the resolved `id` as `locationId` in the later job submission. `board.taxonomy.places.list({ q })` ids are accepted as `locationId` too. An id the server does not recognise throws `locations_invalid_id`, and `locations_unavailable` means the search is temporarily down, so let the poster retry.
+
 ## Resolve a logo
 
 Both logo paths return a stored `publicUrl` for `create`. The SDK owns multipart encoding.

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

@@ -37,6 +37,13 @@ const companies = await board.salaries.companies.list();
 region, and city nesting from each `SalaryLocation.parentSlug`; top-level rows
 have `parentSlug: null`.
 
+Every place row in a salary response (location index nodes, `topLocations`,
+child, sibling, and other locations) carries `placeName` and `placeLabel`.
+Render `placeLabel` wherever places are listed: it tells a city from the
+region it shares a name with ("New York, NY" under "New York", "Washington,
+DC" beside "Washington"). Keep `placeName` for data you pass on, such as
+JSON-LD.
+
 ## Retrieve detail and canonicalize slugs
 
 Every axis `retrieve(slug)` accepts an inbound English or board-language slug.

package/skills/cavuno-board-talent-access/SKILL.md

@@ -135,6 +135,13 @@ const named = await board.talent.retrieve('jane-doe');
 const opaque = await board.talent.retrieve('bu_candidate');
 ```
 
+The profile route may move to another shape with fixed text around the handle, for example `src/routes/@{$handle}.tsx` for `/@jane`. When you move it:
+
+- Keep `export const cavunoPage = 'talentProfile'` on the profile route file, so links Cavuno builds (webhooks, admin links) follow the new address.
+- Keep `/p/$handle` working as a permanent (301) redirect to the same value on the new route.
+- Build every profile link (cards, messages, canonical tag, JSON-LD) through one helper that encodes only the handle, never the fixed text.
+- Never serve a bare `/$handle` at the root: it collides with board pages and is rejected as a profile address.
+
 ## Completion gate
 
 - `retrieve()` drives the Message-vs-upsell CTA and remaining-credit hints.

package/skills/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.27.0",
+  "version": "4.29.0",
   "skills": [
     {
       "name": "cavuno-board-account",
@@ -59,7 +59,7 @@
     },
     {
       "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.",
       "path": "skills/cavuno-board-filters/SKILL.md",
       "framework": null,
       "category": "core"