@cavuno/board 4.26.0 → 4.28.0

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, 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
@@ -41,6 +41,33 @@ const page = await board.jobs.list({
 Company slugs are the URL identity. Map `filters.company` directly to
 `companySlug` in `jobs.list` queries or `jobs.search` filters.
 
+## Filter by category in search
+
+An "All filters" panel can carry a category facet next to seniority, company,
+workplace and employment type. `parseListingFilters` reads `category` the same
+way as company (repeated or comma-separated slugs, first 10 kept). Send it as
+`filters.categories` in a `jobs.search` body; a job matches when it has any of
+the given categories, and the other filters still apply.
+
+```ts snippet
+const results = await board.jobs.search({
+  query: filters.q,
+  sort: filters.sort,
+  filters: {
+    categories: filters.category,
+    seniority: filters.seniority,
+    companySlug: filters.company,
+    remoteOption: filters.remoteOption ? [filters.remoteOption] : undefined,
+  },
+  limit: 20,
+});
+```
+
+`categories` accepts a term's `sourceSlug` or its board-language
+`canonicalSlug`; an unknown slug matches no jobs. `jobs.list` takes a single
+`category` instead, which seeds a category landing page rather than filtering
+a search. Use `jobs.search` whenever the category is one facet among several.
+
 ## Render controls from the vocabulary
 
 ```ts snippet
@@ -123,6 +150,129 @@ 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.
+
+```ts snippet
+const companyFields = await board.profileFields.retrieve('company');
+const technologyChoices = await board.profileFields.choices(
+  'company',
+  'technologies',
+  { search: 'typescript', limit: 20 });
+
+const companies = await board.companies.search({
+  query: 'engineering',
+  customFields: [{ key: 'member_tier', values: ['gold'] }],
+  objectReferences: [
+    { key: 'technologies', recordIds: [technologyChoices.data[0]!.id] },
+  ],
+});
+
+const candidateFields = await board.profileFields.retrieve('candidate');
+const certifications = await board.profileFields.choices(
+  'candidate',
+  'certifications',
+  { limit: 20 });
+const talent = await board.talent.list({
+  customFields: [{ key: 'available_for_mentoring', values: [true] }],
+  objectReferences: [
+    { key: 'certifications', recordIds: [certifications.data[0]!.id] },
+  ],
+});
+
+void companyFields.definitions;
+void candidateFields.referenceDefinitions;
+void companies.data;
+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:
@@ -135,7 +285,16 @@ Finish only after every applicable check passes:
   relevance, newest, and salary high.
 - Category and skill filtering sends `sourceSlug`, while links use
   `canonicalSlug`.
+- `/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-paywall/SKILL.md

@@ -26,7 +26,7 @@ for (const offer of offers) {
 }
 ```
 
-`offerType` is `'recurring' | 'lifetime'`; post the selected `offerKey` to checkout.
+`offerType` is `'recurring' | 'lifetime'`; post the selected `offerKey` to checkout unchanged. Treat it as opaque: newer offers use plan IDs, while older offers may use tier keys. Never derive it from the billing interval.
 
 Gated catalog reads expose withheld inventory as `gatedCount`. The same jobs endpoint returns the entitled view when called with the candidate bearer token.
 
@@ -44,8 +44,11 @@ if ((page.gatedCount ?? 0) > 0) {
 ```ts snippet
 import { loadStripe } from '@stripe/stripe-js';
 
+const { data: checkoutOffers } = await board.paywall.offers();
+const selectedOffer = checkoutOffers[0]; // Or the offer selected in your UI.
+if (!selectedOffer) throw new Error('No access offers available');
 const kit = await board.me.access.checkout({
-  offerKey: 'monthly',
+  offerKey: selectedOffer.offerKey,
   returnPath: '/account/access',
   colorMode: 'light',
 });

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

@@ -24,6 +24,93 @@ for (const plan of plans) {
 
 Pass the chosen `plan.id` as `submission.selectedPlan`. Invoice-only plans collect `invoiceBilling` rather than immediate payment.
 
+## Render the form from the operator's layout
+
+The operator orders the job form and chooses which fields show and which are required. `board.context().forms.job` is that form as one ordered list; render it top to bottom and never hard-code the order. Skip entries with `visible: false`: a hidden field is not collected and is never required.
+
+```ts snippet
+const { forms, jobForm } = await board.context();
+
+for (const field of forms.job) {
+  if (!field.visible) continue;
+  switch (field.kind) {
+    case 'builtin':
+      renderBuiltin(field.key, { required: field.required, locked: field.locked });
+      break;
+    case 'custom':
+      renderCustomField(field.definition, { required: field.required });
+      break;
+    case 'collection':
+      renderCollectionPicker(field.definition, { required: field.required });
+      break;
+  }
+}
+```
+
+A `builtin` entry is drawn by your own control for its `key`. A `locked` built-in is always shown and required; `lockReason` says why (for example `google_required` for the title and description Google for Jobs needs). Skip a built-in key you do not recognise. The keys map to submission fields:
+
+| `key` | Submission fields |
+| --- | --- |
+| `employmentType` | `employmentType`, from `jobForm.employmentType.allowedOptions` |
+| `seniority` | `seniority`, from `jobForm.seniority.allowedOptions` |
+| `title` | `title` |
+| `workArrangement` | `remoteOption`, from `jobForm.workArrangement.allowedOptions` |
+| `location` | `officeLocations`, `inOfficePeriod`, `inOfficeFrequency` |
+| `remoteEligibility` | `remoteWorkingPermits`, `remoteTimezones`, and `remoteSponsorship` when `jobForm.sponsorship.visible` |
+| `description` | `description` |
+| `salary` | `salaryRangeEnabled`, `salaryMin`, `salaryMax`, `salaryTimeframe`, `salaryCurrency` |
+| `applyMethod` | `applicationUrl` |
+| `company` | `companyName`, `companyWebsite`, and the resolved logo |
+
+`contactName`, `contactEmail`, and the plan are not layout fields; always collect them. `jobForm` still carries each built-in's allowed options and salary bounds.
+
+A `custom` entry renders from `definition` (`label`, `type`, `options`, `helpText`) and submits under `submission.customFieldValues[field.key]`; store option keys, never labels. A `collection` entry renders a picker capped by `definition.maxSelections` (one when `multiple` is false) with choices from `board.jobs.collectionChoices(field.key)`. The anonymous funnel takes no collection values, so collection fields belong on the signed-in employer job form (`board.me.companies.jobs.create`, `collectionValues`). Custom and collection rendering rules live in `cavuno-board-collections`.
+
+When a collection definition has `allowOverrides`, the employer job form can give each selected entry its own wording for this job — "Unlimited PTO" in place of the shared "Annual leave", for example. Offer an edit action per selected entry with a title (up to 160 characters) and a plain-text description (up to 2,000 characters), and send them as `collectionOverrides`, one item per entry that has wording:
+
+```ts snippet
+const created = await board.me.companies.jobs.create('acme', {
+  title: 'Head chef',
+  description: 'Run the kitchen.',
+  collectionValues: { benefits: [annualLeaveId] },
+  collectionOverrides: [
+    { fieldKey: 'benefits', recordId: annualLeaveId, title: 'Unlimited PTO' },
+  ],
+});
+
+await board.me.companies.jobs.update('acme', created.id, {
+  collectionOverrides: [],
+});
+```
+
+The list replaces the job's wording: omit it on `update` to keep what is stored, and send `[]` to restore every default. Wording for an entry the job does not select, or on a field without `allowOverrides`, is rejected with `jobs_constraint_violation`; `details.violations[].params.fieldKey` names the field, so show the message under it. Deselecting an entry drops its wording. The job's collection entries then return the resolved `title` and `description` to render.
+
+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.
@@ -111,6 +198,7 @@ Bare-email billing lookup is intentionally absent because it would expose whethe
 
 ## Completion gate
 
+- The form renders `forms.job` in order: hidden entries are absent, required and locked entries block submit while empty, and an unknown built-in key is skipped.
 - Every `create` call handles all four statuses.
 - Paid checkout redirects through `checkoutUrl`; the job appears only after webhook completion.
 - Free unmoderated submission returns a resolving `jobSlug`.

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/manifest.json

@@ -1,9 +1,9 @@
 {
-  "version": "4.26.0",
+  "version": "4.28.0",
   "skills": [
     {
       "name": "cavuno-board-account",
-      "description": "Candidate self-service boundary with @cavuno/board. Use for account, profile, resume onboarding, recommended jobs, avatar, experience, education, skills, languages, or notification preferences.",
+      "description": "Candidate self-service boundary with @cavuno/board. Use for account, profile, custom profile fields, collection selections, resume onboarding, recommended jobs, avatar, experience, education, skills, languages, or notification preferences.",
       "path": "skills/cavuno-board-account/SKILL.md",
       "framework": null,
       "category": "core"
@@ -36,9 +36,16 @@
       "framework": null,
       "category": "core"
     },
+    {
+      "name": "cavuno-board-collections",
+      "description": "Custom profile fields and collection references with @cavuno/board. Use for rendering company, talent or job custom fields, collection entries, benefits/technologies/certification sections, or collection-backed filters.",
+      "path": "skills/cavuno-board-collections/SKILL.md",
+      "framework": null,
+      "category": "core"
+    },
     {
       "name": "cavuno-board-companies",
-      "description": "Company catalog reads with @cavuno/board. Use for company indexes, market archives, profiles, company job rails, similar companies, or company salary pages.",
+      "description": "Company catalog reads with @cavuno/board. Use for company indexes, market archives, profiles, company job rails, similar companies, company salary pages, or employer job drafts.",
       "path": "skills/cavuno-board-companies/SKILL.md",
       "framework": null,
       "category": "core"
@@ -52,7 +59,7 @@
     },
     {
       "name": "cavuno-board-filters",
-      "description": "Listing-filter contracts with @cavuno/board. Use for job filter controls, 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"