@cavuno/board 4.27.0 → 4.29.0

package/CHANGELOG.md

@@ -3,6 +3,52 @@
 This changelog records changes that affect Board API compatibility, exported
 types, runtime behavior, or supported integration patterns.
 
+## 4.29.0 — 2026-09-29
+
+- **Candidate profile route.** `talentProfilePath(handle)` from
+  `@cavuno/board/paths` builds the default profile address, `/p/{handle}`.
+  The route contract gains an optional `talentProfile` role (param `handle`),
+  so a board can serve profiles at another shape with fixed text around the
+  handle, such as `/@{handle}`, and mark that route with
+  `export const cavunoPage = 'talentProfile'`. A profile address that is only
+  the handle (`/{handle}`) is rejected. Route templates may now contain `@`,
+  and TanStack route files with a `prefix{$param}` segment (for example
+  `@{$handle}.tsx`) are recognised.
+
+## 4.28.0 — 2026-09-25
+
+- **Resolve global location selections.** `board.locations.search` finds places
+  beyond a board’s existing jobs. Pass the same session token to
+  `board.locations.resolve` when a suggestion is selected, then use its
+  canonical location ID when submitting an office. `LocationResolveInput`
+  describes the selection request.
+
+- **Custom-field values on job cards.** Every `PublicJobCard` (jobs list,
+  search, similar, company jobs, embed, recommended and saved jobs) carries
+  `customFieldValues` for the job and `company.customFieldValues` for its
+  company, keyed by field key and `{}` when empty. Only `single_select`,
+  `multi_select`, `boolean` and `number` values are included; select values
+  are option keys. Text values stay on the full job and company, and private
+  company fields are never included. Job values are checked against the
+  board's current job custom-field definitions, so values of removed fields
+  or options are left out. A listing can now render custom-field badges
+  without fetching each job.
+- **Filter jobs by company custom fields.** `board.jobs.search` accepts
+  `filters.companyCustomFields`, matched against the public profile fields
+  of each job's company, with the same clauses as `filters.customFields`:
+  a field `key` and its accepted `values` (option keys, booleans or
+  numbers), AND across clauses and OR within one, up to 10 of each. Keys and
+  options come from `board.profileFields.retrieve('company')`. An unknown or
+  private key, or an undefined option key, returns `400 invalid_filter`. Job
+  and company keys never collide, so both lists may use the same key. When a
+  company's values change, its jobs follow in search within seconds. If the
+  filter cannot be served yet on a board, the search returns `503
+  search_filter_unavailable` with `details.filter: "companyCustomFields"`;
+  the same search without it works.
+- `JobsSearchBody` is now the spec's search body type as generated; its
+  `customFields` and `companyCustomFields` clauses stay identical to
+  `CustomFieldFilter`.
+
 ## 4.27.0 — 2026-09-23
 
 - **Collections and profile fields.** Company and talent responses carry
@@ -61,6 +107,17 @@ types, runtime behavior, or supported integration patterns.
   job. This applies to any edit of an existing job that has an office
   location but no work arrangement, even one that changes only other fields:
   send an allowed `remoteOption` with it.
+- **Employer checkout can return `pending_approval`.** When a board requires
+  approval of free jobs, a free employer post (and an invoice post that
+  publishes on issue) is held as a draft for the operator to publish instead
+  of going live, and `POST
+  /boards/{identifier}/me/companies/{slug}/jobs/{id}/checkout` answers
+  `status: "pending_approval"` with the `jobId`. Treat it as "submitted, not
+  live": do not link the job as published. Bundle, subscription and
+  member-credit posts still publish immediately (`status: "published"`), as
+  does a free post on a board without approval. The board operator now also
+  receives the job-submission notification for employer posts, matching the
+  public posting form.
 - **`jobs_constraint_violation` errors carry structured details.**
   `error.details.violations` lists each broken rule as `{ code, path, params }`
   (for example `{ code: "custom_field_required", path: ["customFieldValues",

package/dist/{_spec-B_pBNVUd.d.mts → _spec-CQx5p1cM.d.mts}

@@ -163,6 +163,15 @@ interface components {
             /** Format: date-time */
             expiresAt: string;
         };
+        AudienceAttribution: {
+            channel?: string;
+            source?: string;
+            campaign?: string;
+            location?: string;
+            browser?: string;
+            os?: string;
+            device?: string;
+        };
         Block: {
             /** @enum {string} */
             object: "block";
@@ -238,10 +247,12 @@ interface components {
             /** @description Minimum 8 characters. */
             password: string;
             displayName: string;
+            audienceAttribution?: components["schemas"]["AudienceAttribution"];
             /** @description True only when the person ticked a marketing checkbox your UI displayed with its disclosure wording. Omit when no checkbox was shown; false and absent both record nothing. */
             marketingConsent?: boolean;
         };
         BoardAuthRequestMagicLinkBody: {
+            audienceAttribution?: components["schemas"]["AudienceAttribution"];
             /** Format: email */
             email: string;
             /** @description Optional same-origin path to carry through the email link. */
@@ -787,6 +798,9 @@ interface components {
         ConvertSourcedCandidateBody: {
             stage: string;
         };
+        CreateAlertBody: components["schemas"]["AlertBody"] & {
+            audienceAttribution?: components["schemas"]["AudienceAttribution"];
+        };
         CreateApplyApprovalBody: {
             sessionKey: string;
         };
@@ -853,10 +867,19 @@ interface components {
                 employmentType: string;
                 remoteOption: string;
                 officeLocations: {
-                    /** @enum {string} */
+                    /**
+                     * @deprecated
+                     * @description Deprecated — send `locationId` instead (an `id` from `GET /locations/search` or `GET /places`). Still accepted.
+                     * @enum {string}
+                     */
                     provider?: "mapbox";
+                    /**
+                     * @deprecated
+                     * @description Deprecated — send `locationId` instead (an `id` from `GET /locations/search` or `GET /places`). Still accepted.
+                     */
                     providerPlaceId?: string;
-                    displayName: string;
+                    /** @description Display text for the location. Required unless `locationId` is sent; with `locationId` it defaults to the location's full name (locality, city, region, country), e.g. `Lyon, Auvergne-Rhône-Alpes, France`. */
+                    displayName?: string;
                     countryCode?: string;
                     region?: string;
                     locality?: string;
@@ -864,6 +887,10 @@ interface components {
                     latitude?: number;
                     longitude?: number;
                     boundingBox?: number[];
+                    /**
+                     * @deprecated
+                     * @description Deprecated — send `locationId` instead (an `id` from `GET /locations/search` or `GET /places`). Still accepted.
+                     */
                     raw?: {
                         suggestion?: {
                             [key: string]: unknown;
@@ -872,6 +899,8 @@ interface components {
                             [key: string]: unknown;
                         };
                     };
+                    /** @description Opaque location id from `GET /locations/search` or `GET /places` (`id`) — the preferred way to send a location. Resolved server-side to the full place; the other fields are then ignored except `displayName`. An unknown id returns `400 locations_invalid_id`. If the lookup is temporarily unavailable the entry is kept with `displayName` alone, or the request fails with `503 locations_unavailable` when there is none. */
+                    locationId?: string;
                 }[];
                 inOfficePeriod?: string;
                 inOfficeFrequency?: number;
@@ -1044,7 +1073,7 @@ interface components {
             /** @enum {string} */
             object: "employer_checkout";
             /** @enum {string} */
-            status: "checkout" | "published" | "invoice_sent";
+            status: "checkout" | "published" | "pending_approval" | "invoice_sent";
             /** @description The Stripe Checkout / hosted-invoice URL, or `null`. */
             checkoutUrl: string | null;
             jobId: string;
@@ -1193,8 +1222,8 @@ interface components {
             inOfficePeriod?: "per_week" | "per_month" | "per_year";
             /** @description How often the candidate must be in-office over `inOfficePeriod`. */
             inOfficeFrequency?: number;
-            /** @description Physical office locations associated with the job. Prefer `{query: "City, Country"}` for free-form input; `{city, country, region?, locality?}` is also accepted when you already have structured fields. Each entry is resolved server-side; a country mismatch returns `400 jobs_unresolvable_location`. */
-            officeLocations?: components["schemas"]["JobOfficeLocationInput"][];
+            /** @description Physical office locations associated with the job. Prefer `{locationId}` with an `id` from `GET /locations/search` (what a location picker returns); `{query: "City, Country"}` for free-form text and `{city, country, region?, locality?}` are also accepted and geocoded server-side (a country mismatch returns `400 jobs_unresolvable_location`). A location outside the board's job-form `allowedCountries` returns `400 jobs_constraint_violation`. */
+            officeLocations?: components["schemas"]["EmployerJobOfficeLocationInput"][];
             /** @description Collection-reference selections keyed by the configured job collection field key. Values are arrays of record IDs, including for single-select fields. On PATCH omitted keys are preserved; send null or an empty array to clear a field. */
             collectionValues?: {
                 [key: string]: string[] | unknown;
@@ -1263,6 +1292,24 @@ interface components {
              */
             public: string | null;
         };
+        EmployerJobOfficeLocationInput: {
+            /** @description Opaque location id from `GET /locations/search` or `GET /places` (`id`). Resolved server-side to the full place (country, region, city, locality). An unknown id returns `400 locations_invalid_id`; `503 locations_unavailable` while the lookup is temporarily down. */
+            locationId: string;
+            /** @description Display text for the location. Defaults to the location's full name (locality, city, region, country), e.g. `Lyon, Auvergne-Rhône-Alpes, France`. */
+            displayName?: string;
+        } | {
+            /** @description Free-form location string (e.g. `"Berlin, Germany"`, `"Utrecht, Netherlands"`, `"Mountain View, California, USA"`). Resolved server-side; rejected when no high-confidence match is found. */
+            query: string;
+        } | {
+            /** @description Neighborhood or sub-locality. */
+            locality?: string;
+            /** @description City. */
+            city: string;
+            /** @description Region, state, or province. */
+            region?: string;
+            /** @description ISO 3166-1 alpha-2 country code OR recognized country name/alias. Aliases are normalized to canonical alpha-2 server-side (e.g. `US`, `USA`, `United States` → `US`; `UK`, `GB`, `United Kingdom` → `GB`). */
+            country: string;
+        };
         EmployerJobStat: {
             /** @enum {string} */
             object: "employer_job_stat";
@@ -1470,8 +1517,8 @@ interface components {
             inOfficePeriod?: "per_week" | "per_month" | "per_year";
             /** @description How often the candidate must be in-office over `inOfficePeriod`. */
             inOfficeFrequency?: number;
-            /** @description Physical office locations associated with the job. Prefer `{query: "City, Country"}` for free-form input; `{city, country, region?, locality?}` is also accepted when you already have structured fields. Each entry is resolved server-side; a country mismatch returns `400 jobs_unresolvable_location`. */
-            officeLocations?: components["schemas"]["JobOfficeLocationInput"][];
+            /** @description Physical office locations associated with the job. Prefer `{locationId}` with an `id` from `GET /locations/search` (what a location picker returns); `{query: "City, Country"}` for free-form text and `{city, country, region?, locality?}` are also accepted and geocoded server-side (a country mismatch returns `400 jobs_unresolvable_location`). A location outside the board's job-form `allowedCountries` returns `400 jobs_constraint_violation`. */
+            officeLocations?: components["schemas"]["EmployerJobOfficeLocationInput"][];
             /** @description Collection-reference selections keyed by the configured job collection field key. Values are arrays of record IDs, including for single-select fields. On PATCH omitted keys are preserved; send null or an empty array to clear a field. */
             collectionValues?: {
                 [key: string]: string[] | unknown;
@@ -1574,19 +1621,6 @@ interface components {
             /** @description Pre-formatted display name for the location, or `null` if not resolved. */
             displayName: string | null;
         };
-        JobOfficeLocationInput: {
-            /** @description Free-form location string (e.g. `"Berlin, Germany"`, `"Utrecht, Netherlands"`, `"Mountain View, California, USA"`). Resolved server-side; rejected when no high-confidence match is found. */
-            query: string;
-        } | {
-            /** @description Neighborhood or sub-locality. */
-            locality?: string;
-            /** @description City. */
-            city: string;
-            /** @description Region, state, or province. */
-            region?: string;
-            /** @description ISO 3166-1 alpha-2 country code OR recognized country name/alias. Aliases are normalized to canonical alpha-2 server-side (e.g. `US`, `USA`, `United States` → `US`; `UK`, `GB`, `United Kingdom` → `GB`). */
-            country: string;
-        };
         JobPostingBillingOptions: {
             /** @enum {string} */
             object: "job_posting_billing_options";
@@ -1680,6 +1714,12 @@ interface components {
             /** Format: email */
             email: string;
         };
+        LocationResolveInput: {
+            /** @description Opaque id returned by location search. */
+            locationId: string;
+            /** @description The same opaque session id used for the search interaction that returned this location. */
+            session: string;
+        };
         LocationSalaryDetail: {
             /** @enum {string} */
             object: "location_salary_detail";
@@ -1702,6 +1742,8 @@ interface components {
             } | null;
             childLocations: {
                 placeName: string;
+                /** @description Display label for the place in a salary list. A city or locality adds its subdivision code ("New York, NY", "Washington, DC") so it reads apart from the region it shares a name with; a region or country is its name. Render this rather than `placeName` in lists. */
+                placeLabel: string;
                 placeSlug: string;
                 countryCode: string;
                 avgSalaryMin: number;
@@ -1718,6 +1760,8 @@ interface components {
                 regionSlug: string;
                 cities: {
                     placeName: string;
+                    /** @description Display label for the place in a salary list. A city or locality adds its subdivision code ("New York, NY", "Washington, DC") so it reads apart from the region it shares a name with; a region or country is its name. Render this rather than `placeName` in lists. */
+                    placeLabel: string;
                     placeSlug: string;
                     countryCode: string;
                     avgSalaryMin: number;
@@ -1746,6 +1790,8 @@ interface components {
             }[];
             siblingLocations: {
                 placeName: string;
+                /** @description Display label for the place in a salary list. A city or locality adds its subdivision code ("New York, NY", "Washington, DC") so it reads apart from the region it shares a name with; a region or country is its name. Render this rather than `placeName` in lists. */
+                placeLabel: string;
                 placeSlug: string;
                 countryCode: string;
                 avgSalaryMin: number;
@@ -2524,6 +2570,10 @@ interface components {
                 slug: string;
                 name: string;
                 logoUrl: string | null;
+                /** @description The company's public custom-field values of the select, boolean, and number types, keyed by field key; select values are option `key`s. Private fields and text types are omitted (the full company carries text values). `{}` when none. */
+                customFieldValues: {
+                    [key: string]: string | string[] | boolean | number;
+                };
             } | null;
             /** @description Job categories (slug + board display name). Guaranteed resolvable: every emitted slug resolves via `GET /v1/boards/:identifier/categories/:slug`. */
             categories: {
@@ -2535,6 +2585,10 @@ interface components {
                 slug: string;
                 name: string;
             }[];
+            /** @description The job's custom-field values of the select, boolean, and number types, keyed by each field's `key`; select values are option `key`s. Resolve labels via the board's `customFields.job` definitions (see `GET /v1/boards/:identifier`). Values of fields no longer defined, and removed options, are omitted; text types are only on the full job (`PublicJob`). `{}` when none. */
+            customFieldValues: {
+                [key: string]: string | string[] | boolean | number;
+            };
             links: {
                 /**
                  * Format: uri
@@ -2553,6 +2607,25 @@ interface components {
              */
             public: string | null;
         };
+        PublicLocation: {
+            /** @enum {string} */
+            object: "location";
+            /** @description Opaque location id. Complete the pick through `POST /locations/resolve` with this id and the search session before using it in a later submission. Shares its id space with `PublicPlace.id`. */
+            id: string;
+            /** @description The location’s own name, e.g. `Berlin`. */
+            name: string;
+            /** @description Name with its parent context, for display in the input once picked, e.g. `Berlin, Germany`. */
+            fullName: string;
+            /** @description The parent context alone, for a secondary line in the result list, e.g. `Germany` for Berlin or `Berlin, Germany` for Kreuzberg; `null` for a country. */
+            contextLabel: string | null;
+            /**
+             * @description Same vocabulary as `PublicPlace.placeType`: `country`, `region`, `city`, or `locality`.
+             * @enum {string}
+             */
+            placeType: "country" | "region" | "city" | "locality";
+            /** @description ISO 3166-1 alpha-2 country code, or `null` if unknown. */
+            countryCode: string | null;
+        };
         PublicPlace: {
             /** @enum {string} */
             object: "place";
@@ -2617,6 +2690,11 @@ interface components {
                     key: string;
                     values: (string | number | boolean)[];
                 }[];
+                /** @description Public custom company profile fields, matched against each job's company. Keys and option keys come from the board's public company profile field definitions (`GET /v1/boards/{identifier}/profile-fields/company`). Clauses are AND-matched; values within a clause are OR-matched. Up to 10 clauses and 10 values per clause. An unknown or private key, or an undefined option key, is rejected with `400 invalid_filter`. Kept separate from `customFields`, so a job field and a company field may share a key. */
+                companyCustomFields?: {
+                    key: string;
+                    values: (string | number | boolean)[];
+                }[];
             };
             /** @description An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results. */
             cursor?: string;
@@ -2921,6 +2999,8 @@ interface components {
             object: "salary_location";
             placeSlug: string;
             placeName: string;
+            /** @description Display label for the place in a salary list. A city or locality adds its subdivision code ("New York, NY", "Washington, DC") so it reads apart from the region it shares a name with; a region or country is its name. Render this rather than `placeName` in lists. */
+            placeLabel: string;
             /** @description Slug of the parent place; `null` for a top-level node. */
             parentSlug: string | null;
             avgSalaryMin: number;
@@ -3023,6 +3103,8 @@ interface components {
             childLocations: {
                 placeSlug: string;
                 placeName: string;
+                /** @description Display label for the place in a salary list. A city or locality adds its subdivision code ("New York, NY", "Washington, DC") so it reads apart from the region it shares a name with; a region or country is its name. Render this rather than `placeName` in lists. */
+                placeLabel: string;
                 avgSalaryMin: number;
                 avgSalaryMax: number;
                 jobCount: number;
@@ -3033,6 +3115,8 @@ interface components {
                 cities: {
                     placeSlug: string;
                     placeName: string;
+                    /** @description Display label for the place in a salary list. A city or locality adds its subdivision code ("New York, NY", "Washington, DC") so it reads apart from the region it shares a name with; a region or country is its name. Render this rather than `placeName` in lists. */
+                    placeLabel: string;
                     avgSalaryMin: number;
                     avgSalaryMax: number;
                     jobCount: number;
@@ -3041,6 +3125,8 @@ interface components {
             otherLocations: {
                 placeSlug: string;
                 placeName: string;
+                /** @description Display label for the place in a salary list. A city or locality adds its subdivision code ("New York, NY", "Washington, DC") so it reads apart from the region it shares a name with; a region or country is its name. Render this rather than `placeName` in lists. */
+                placeLabel: string;
                 avgSalaryMin: number;
                 avgSalaryMax: number;
                 jobCount: number;
@@ -3111,6 +3197,8 @@ interface components {
                 avgSalaryMax: number;
                 jobCount: number;
                 placeName: string;
+                /** @description Display label for the place in a salary list. A city or locality adds its subdivision code ("New York, NY", "Washington, DC") so it reads apart from the region it shares a name with; a region or country is its name. Render this rather than `placeName` in lists. */
+                placeLabel: string;
                 placeSlug: string;
                 countryCode: string;
             }[];
@@ -3436,6 +3524,8 @@ interface components {
             childLocations: {
                 placeSlug: string;
                 placeName: string;
+                /** @description Display label for the place in a salary list. A city or locality adds its subdivision code ("New York, NY", "Washington, DC") so it reads apart from the region it shares a name with; a region or country is its name. Render this rather than `placeName` in lists. */
+                placeLabel: string;
                 avgSalaryMin: number;
                 avgSalaryMax: number;
                 jobCount: number;
@@ -3446,6 +3536,8 @@ interface components {
                 cities: {
                     placeSlug: string;
                     placeName: string;
+                    /** @description Display label for the place in a salary list. A city or locality adds its subdivision code ("New York, NY", "Washington, DC") so it reads apart from the region it shares a name with; a region or country is its name. Render this rather than `placeName` in lists. */
+                    placeLabel: string;
                     avgSalaryMin: number;
                     avgSalaryMax: number;
                     jobCount: number;
@@ -3454,6 +3546,8 @@ interface components {
             otherLocations: {
                 placeSlug: string;
                 placeName: string;
+                /** @description Display label for the place in a salary list. A city or locality adds its subdivision code ("New York, NY", "Washington, DC") so it reads apart from the region it shares a name with; a region or country is its name. Render this rather than `placeName` in lists. */
+                placeLabel: string;
                 avgSalaryMin: number;
                 avgSalaryMax: number;
                 jobCount: number;
@@ -3528,6 +3622,8 @@ interface components {
                 avgSalaryMax: number;
                 jobCount: number;
                 placeName: string;
+                /** @description Display label for the place in a salary list. A city or locality adds its subdivision code ("New York, NY", "Washington, DC") so it reads apart from the region it shares a name with; a region or country is its name. Render this rather than `placeName` in lists. */
+                placeLabel: string;
                 placeSlug: string;
                 countryCode: string;
             }[];
@@ -3636,6 +3732,7 @@ interface components {
             /** @enum {string} */
             channel: "messageEmails" | "applicationEmails" | "recommendedJobEmails";
             subscribed: boolean;
+            audienceAttribution?: components["schemas"]["AudienceAttribution"];
         };
         UpdatePasswordBody: {
             currentPassword: string;