@cavuno/board 3.2.0 → 4.1.0

package/dist/{board-BJbXd_9_.d.mts → board-BTEZ0uiI.d.ts}

@@ -1,5 +1,5 @@
-import { S as Schemas } from './_spec-nkWAraS0.mjs';
-import { L as ListEnvelope, m as RelatedSearch } from './jobs-lVvKCBCU.mjs';
+import { S as Schemas } from './_spec-BZDv2dc5.js';
+import { L as ListEnvelope, m as RelatedSearch } from './jobs-BbLJfz1z.js';
 
 type PublicCompany = Schemas['CompanyPublic'];
 /** A market (sector) a company operates in — name + its source slug. */
@@ -92,10 +92,11 @@ type PublicBoard = Schemas['PublicBoardContext'];
 type PublicBoardFeatures = PublicBoard['features'];
 type PublicBoardAnalytics = PublicBoard['analytics'];
 /**
- * An operator-defined custom job-field definition. Board-wide;
- * use it to render and localize a job's opaque `customFieldValues` (resolve
- * option `key`s → labels, honour field `type` and display order). Shared with
- * the Operator API's custom-field surface (one canonical schema).
+ * An operator-defined custom field definition. Board-wide and
+ * model-scoped under `board.context().customFields` (today only `job`);
+ * use it to render and localize a record's opaque `customFieldValues`
+ * (resolve option `key`s → labels, honour field `type` and display order).
+ * Shared with the Operator API's custom-field surface (one canonical schema).
  */
 type CustomFieldDefinition = Schemas['CustomFieldDefinition'];
 type CustomFieldType = CustomFieldDefinition['type'];

package/dist/breadcrumbs-SGaWth6C.d.ts

@@ -0,0 +1,372 @@
+import { P as PublicBoard, a as CompanyCategorySalary, b as CompanySalary, L as LocationSalaryDetail, S as SkillSalaryDetail, T as TitleSalaryDetail } from './board-BTEZ0uiI.js';
+import { P as PublicJob } from './jobs-BbLJfz1z.js';
+
+/**
+ * Wire enum for `salaryTimeframe`. Defined here (not re-exported from any
+ * private  catalog) so the published `@cavuno/board/format` types
+ * stay self-contained.
+ */
+type SalaryTimeframeValue = 'per_year' | 'per_month' | 'per_week' | 'per_day' | 'per_hour';
+type SalaryTimeframeInput = SalaryTimeframeValue | string | null | undefined;
+/**
+ * Which ICU currency form to render.
+ *
+ * `'symbol'` (default) is the UNAMBIGUOUS form — `CA$`, `A$`, `CN¥` — and is
+ * the right default for a board listing several currencies side by side.
+ * `'narrowSymbol'` is the short form (`$`, `¥`); on a single-currency board
+ * there is nothing to confuse it with, and it reads cleaner. A caller-supplied
+ * presentation preference, passed straight to `Intl` — not a word.
+ */
+type CurrencyDisplay = 'symbol' | 'narrowSymbol';
+/**
+ * Number notation preference, passed straight to `Intl.NumberFormat`.
+ *
+ * When omitted, magnitude picks: `'compact'` only where ICU actually
+ * shortens (absolute value ≥ 1000 → `$90K`); smaller values stay
+ * `'standard'` so hourly/day rates keep CLDR minor units (`$22.50`,
+ * `KWD 22.567`). Compact on a two-figure rate is meaningless and drops
+ * cents. Caller override always wins.
+ */
+type NumberNotation = 'compact' | 'standard';
+/**
+ * Formatted salary amount + which open/closed bound it represents.
+ * Applications own:
+ * - chrome words for `from` / `upTo` (e.g. "From", "ab")
+ * - joining `text` with `timeframe` (order, spacing, `/`, particles)
+ * - bidi isolation around each operand when directions may differ
+ *   (U+2066/U+2069 FSI/PDI, or HTML `<bdi>` / `dir="auto"`)
+ */
+type FormattedSalaryRange = {
+    /** Intl-formatted amount (or range). No timeframe attached. */
+    text: string;
+    /**
+     * The wire timeframe enum, passed straight back — NOT a word.
+     *
+     * Every rendering of it is presentation: "year", "Yearly", "/yr",
+     * "per annum", "pro Jahr", "年収". `Intl` can produce exactly one of
+     * those forms, so producing it here would pick for the application.
+     * The app maps the enum through its own catalog, the same way it maps
+     * `bound` and breadcrumb `kind`.
+     *
+     * `null` when the wire value is absent or not a known timeframe.
+     */
+    timeframe: SalaryTimeframeValue | null;
+    bound: 'range' | 'from' | 'upTo';
+};
+/**
+ * Format a per-job salary range in the BOARD language
+ * (`board.context().language` — required, never defaulted; see ).
+ *
+ * Returns `{ text, timeframe, bound }` so applications can:
+ * - attach open-range chrome in their own locale (`bound`)
+ * - compose amount + timeframe order themselves (prefix vs postfix, with or
+ *   without `/`, with or without a space — ja/zh often glue with no space)
+ * - isolate bidi when composing (see module JSDoc)
+ *
+ * Returns `null` when both bounds are null, currency is missing/empty, the
+ * locale is invalid/unsupported, or `Intl` rejects the currency format.
+ *
+ * @example
+ * formatSalaryRange('en', 90000, 120000, 'per_year', 'USD');
+ * // { text: "$90–120K", timeframe: "per_year", bound: "range" }
+ * formatSalaryRange('en', 90000, null, 'per_year', 'USD');
+ * // { text: "$90K", timeframe: "per_year", bound: "from" }
+ * formatSalaryRange('de', 90000, 120000, 'per_year', 'EUR');
+ * // { text: "90.000–120.000 €", timeframe: "per_year", bound: "range" }
+ * formatSalaryRange('de', 90000, 120000, 'per_year', null);
+ * // null  // no currency → no salary
+ * formatSalaryRange('en', 22.5, null, 'per_hour', 'USD');
+ * // { text: "$22.50", timeframe: "per_hour", bound: "from" }  // magnitude → standard
+ */
+declare function formatSalaryRange(language: string, min: number | null, max: number | null, timeframe: SalaryTimeframeInput, currency?: string | null, currencyDisplay?: CurrencyDisplay, notation?: NumberNotation): FormattedSalaryRange | null;
+
+/**
+ * Google for Jobs `JobPosting` structured data on the `@cavuno/board` wire
+ * types, transcribed field-by-field from the hosted board's generator
+ * (the hosted board implementation + `job-posting-location-json-ld.ts`) and
+ * tested against the hosted behavior.
+ *
+ * JSON-LD structure is locale-neutral per schema.org — no board-language
+ * parameter here; the only display strings are wire values passed through.
+ *
+ * Named exclusions (hosted behaviours with no wire twin, recorded in the
+ * public API contract):
+ *   - `board.companyLegalName` — hosted falls back to it for the
+ *     organization name between `company.name` and `board.name`; the wire
+ *     board context does not expose it.
+ *   - `board.companyWebsiteUrl` — hosted falls back to it for `sameAs` when
+ *     the company has no website; not on the wire.
+ *   - the hosted `job.place`/`locationLabel` jobLocation fallback (used when
+ *     a job has no office locations) — the wire `PublicJob` carries no
+ *     resolved place geo, only `officeLocations`.
+ */
+
+type JsonLdObject = Record<string, unknown>;
+/** The only board fields JSON-LD needs — keeps callers' shapes flexible. */
+type JsonLdBoard = Pick<PublicBoard, 'name' | 'logoUrl'>;
+/**
+ * Worldwide-remote jobs must still emit `applicantLocationRequirements`
+ * next to TELECOMMUTE (Google requires a location signal), so the hosted
+ * board — and this transcription — lists every country it recognises.
+ *
+ * This is the hosted board's exact country catalog: sorted by English common
+ * name, includes `XK` (Kosovo), and excludes `KP` (North Korea). tested
+ * against the hosted list so the two cannot drift.
+ */
+declare const ALL_COUNTRY_CODES: readonly ["AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BA", "BW", "BV", "BR", "IO", "VG", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "BQ", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CK", "CR", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "CD", "EC", "EG", "SV", "GQ", "ER", "EE", "SZ", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "CI", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MK", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "CG", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "KR", "SS", "ES", "LK", "SD", "SR", "SJ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "VI", "UY", "UZ", "VU", "VA", "VE", "VN", "WF", "EH", "YE", "ZM", "ZW"];
+/**
+ * Build the Google for Jobs `JobPosting` JSON-LD object for a job detail
+ * page, or `null` when nothing renderable remains after pruning. Embed the
+ * result in a `<script type="application/ld+json">` tag.
+ */
+declare function createJobPostingJsonLd({ job, board, shareUrl, }: {
+    job: PublicJob;
+    board: JsonLdBoard;
+    shareUrl: string;
+}): JsonLdObject | null;
+/**
+ * Prefix `https://` onto scheme-less company websites; `null` for
+ * blank input (hosted shape — a whitespace-only website never becomes
+ * a bare `https://` `sameAs`).
+ */
+declare function normalizeWebsiteUrl(website: string): string | null;
+
+/**
+ * Salary amount in the board language and the job's currency
+ * (`$90K`, `$90,000.00`, `90.000 €`, …) — the hosted salary-page money
+ * formatter with locale-driven digits/grouping and a real currency code.
+ *
+ * `notation` matches `formatSalaryRange`: omit to pick by magnitude
+ * (`|value| ≥ 1000` → compact; smaller → standard so hourly/day rates keep
+ * CLDR minor units). Pass `'standard'` for full figures (`$90,000`) or
+ * `'compact'` to force short form. Compact vs standard is register (hero
+ * card vs FAQ prose), not locale.
+ *
+ * Empty/missing/`null` currency is not USD — returns `null` (same stance as
+ * `job-posting` omitting `baseSalary`). When `Intl` rejects the locale or
+ * currency, or the value is non-finite (`NaN` / `±Infinity`), returns `null`
+ * rather than English `M`/`k` abbreviations, a bare `$`, or a literal `$NaN`.
+ */
+declare function formatSalaryStat(locale: string, value: number, currency: string | null | undefined, notation?: NumberNotation): string | null;
+/**
+ * Salary range via `Intl.NumberFormat.prototype.formatRange` so the
+ * locale owns separator, repeated currency/magnitude, and bidi marks.
+ * Returns `null` when currency is empty/null, either bound is non-finite, or
+ * `Intl` rejects the inputs.
+ *
+ * `notation` matches `formatSalaryRange` / `formatSalaryStat` (magnitude
+ * default when omitted). Pass `'standard'` for full-figure ranges used in
+ * FAQ prose (`$100,000 – $150,000`); default compact suits hero cards.
+ *
+ * When `min === max` the figure is a fixed salary, not a range: format a
+ * single amount. ICU's `formatRange(X, X)` emits `approximatelySign`
+ * (`~$140K`) because a degenerate range is not silently flattened — correct
+ * for "about X", wrong for a pin where min and max are the same posted
+ * salary.
+ */
+declare function formatSalaryStatRange(locale: string, min: number, max: number, currency: string | null | undefined, notation?: NumberNotation): string | null;
+/** The canonical seniority ladder order the hosted salary pages sort by. */
+declare const SENIORITY_ORDER: readonly ["entry_level", "associate", "mid_level", "senior", "lead", "principal", "director", "executive"];
+/** Sort rows by `SENIORITY_ORDER` (unknown keys sink to the end). Non-mutating. */
+declare function sortBySeniority<T extends {
+    seniority: string;
+}>(items: T[]): T[];
+/**
+ * Options shared by salary JSON-LD builders that emit per-seniority
+ * distributions. Applications compose the finished distribution `name` —
+ * the SDK never invents display words or word order.
+ */
+interface SalaryJsonLdOptions {
+    /**
+     * Composes the finished `MonetaryAmountDistribution.name` for one
+     * seniority row. Receives the wire seniority enum (`entry_level`,
+     * `senior`, …) and the occupation/entity label (category name, title,
+     * …). Return the whole string in board-language order — e.g. French
+     * `"Ingénieur logiciel sénior"`, Japanese without a space, English
+     * `"Senior Software Engineer"`. When omitted, per-seniority
+     * distributions ship without a `name` (valid structured data;
+     * wrong-language / wrong-order names are not).
+     */
+    seniorityName?: (args: {
+        seniority: string;
+        entity: string;
+    }) => string;
+}
+/** Finished FAQ copy ready for `faqJsonLd` (application-composed). */
+interface FaqItem {
+    q: string;
+    a: string;
+}
+/**
+ * Structured salary FAQ entry — kinds + values, never prose.
+ *
+ * - `average`: overall range (Intl compact convenience + raw figures) and
+ *   sample size for the "what is the average?" question. `range` is a
+ *   convenience string; `avgMin` / `avgMax` / `currency` stay so the app can
+ *   reformat (e.g. standard notation for prose FAQ answers).
+ * - `methodology`: label only; the application writes the calculation
+ *   explanation from its catalog.
+ *
+ * Map each entry to `{ q, a }` with board-language plural rules before
+ * calling `faqJsonLd`.
+ */
+type SalaryFaqEntry = {
+    kind: 'average';
+    /**
+     * Entity label echoed so FAQ mapping is a pure map over entries —
+     * the app does not re-close over the page's category/skill name.
+     * The SDK never reads it for formatting.
+     */
+    label: string;
+    /**
+     * Convenience compact range from `formatSalaryStatRange`. Prefer
+     * `avgMin`/`avgMax`/`currency` when composing full-figure prose.
+     * `null` when Intl cannot format (raw figures still present).
+     */
+    range: string | null;
+    avgMin: number;
+    avgMax: number;
+    currency: string;
+    jobCount: number;
+} | {
+    kind: 'methodology';
+    /** Same echo as average — pure map over entries without re-closing. */
+    label: string;
+};
+/**
+ * Salary FAQ *data* for a page that has an overall figure. Returns entry
+ * kinds plus values; the application composes questions and answers.
+ * Empty when there is no overall figure. Carries raw `avgMin` / `avgMax` /
+ * `currency` alongside the compact `range` convenience so FAQ prose can
+ * reformat (standard vs compact is register, not locale). Sentences leave
+ * the SDK.
+ *
+ * `label` is echoed on both entries so the application can map kinds →
+ * `{ q, a }` without re-threading the entity name from the page scope.
+ */
+declare function buildSalaryFaq(locale: string, label: string, overall: {
+    avgMin: number;
+    avgMax: number;
+    jobCount: number;
+} | null, currency: string): SalaryFaqEntry[];
+/** An `ItemList` for a salary index page (the listing's items + their URLs). */
+declare function itemListJsonLd(items: {
+    name: string;
+    url: string;
+}[]): JsonLdObject | null;
+/** A `FAQPage` from application-composed `{q,a}` items. */
+declare function faqJsonLd(faqs: FaqItem[]): JsonLdObject | null;
+/**
+ * `Occupation` for a job-title salary page.
+ *
+ * Names are data labels only (category name). Pass `seniorityName` so the
+ * application composes per-seniority distribution names (word order included).
+ */
+declare function titleSalaryJsonLd(d: TitleSalaryDetail, options?: SalaryJsonLdOptions): JsonLdObject | null;
+/** `Occupation` for a skill salary page (overall distribution + median). */
+declare function skillSalaryJsonLd(d: SkillSalaryDetail): JsonLdObject | null;
+/**
+ * Options for builders that list occupations present on a non-occupation
+ * page (location overview, company salary overview). Callers supply absolute
+ * URLs for each occupation's own salary page — that page carries the real
+ * Occupation rich result.
+ */
+interface SalaryOccupationListOptions {
+    /**
+     * Absolute URL for an occupation (title / category) row on this page.
+     * Required so the ItemList links to pages that carry real Occupation
+     * structured data rather than inventing an Occupation for a place or
+     * employer.
+     */
+    occupationUrl: (row: {
+        categorySlug: string;
+        categoryName: string;
+    }) => string;
+}
+/**
+ * `ItemList` of occupations (top categories) on a city-level location
+ * salary page. Location and employer overviews are not occupations — they
+ * must not claim `schema.org/Occupation`. City-level pages only (hosted
+ * gate); `null` when not a city/locality or when there are no category rows.
+ */
+declare function locationSalaryJsonLd(d: LocationSalaryDetail, options?: SalaryOccupationListOptions): JsonLdObject | null;
+/**
+ * Cross-axis (title×location / skill×location) `Occupation` JSON-LD. Takes
+ * primitives to stay decoupled from the two cross-axis detail wire types.
+ *
+ * Occupation name is the axis name (data); place lives in
+ * `occupationLocation`. Pass `seniorityName` for per-seniority names.
+ */
+declare function crossAxisSalaryJsonLd(args: {
+    name: string;
+    placeName: string;
+    countryCode: string;
+    overall: {
+        avgMin: number;
+        avgMax: number;
+        p25Min: number | null;
+        p75Max: number | null;
+    } | null;
+    bySeniority: {
+        seniority: string;
+        avgSalaryMin: number;
+        avgSalaryMax: number;
+    }[];
+    currency: string;
+}, options?: SalaryJsonLdOptions): JsonLdObject | null;
+/**
+ * `ItemList` of occupations (categories) on a company salary overview.
+ * An employer is not an occupation — do not emit
+ * `OccupationAggregationByEmployer` with the company name as `Occupation.name`.
+ * Each list entry links to the category-at-company page that carries the
+ * real Occupation structured data. `null` when `byCategory` is empty.
+ */
+declare function companySalaryJsonLd(d: CompanySalary, options?: SalaryOccupationListOptions): JsonLdObject | null;
+/**
+ * `Occupation` for one job category at a company (the hosted category page).
+ * Occupation name is the category (data); company lives on
+ * `hiringOrganization`. Pass `seniorityName` for per-seniority names.
+ */
+declare function companyCategorySalaryJsonLd(d: CompanyCategorySalary, options?: SalaryJsonLdOptions): JsonLdObject | null;
+
+interface BreadcrumbItemInput {
+    label: string | null | undefined;
+    href?: string | null;
+}
+/**
+ * Build a `BreadcrumbList`, hosted semantics: labels are trimmed and empty
+ * items dropped; fewer than 2 surviving items → `null` (a single crumb is
+ * not a trail); the current page (no `href`) omits `item` per schema.org.
+ * Relative hrefs resolve against `options.origin`; without an origin a
+ * relative item is omitted (never emit a relative `item` URL).
+ */
+declare function createBreadcrumbJsonLd(items: BreadcrumbItemInput[], options?: {
+    origin?: string | null;
+}): JsonLdObject | null;
+/**
+ * A single crumb in the job-detail trail. Chrome crumbs (`home`, `jobs`) are
+ * kinds — the application supplies display names. Record-derived crumbs keep
+ * `name` because that name is data off the job (place, category, title).
+ */
+type JobBreadcrumb = {
+    kind: 'home' | 'jobs';
+    path: string;
+} | {
+    kind: 'place' | 'category' | 'job';
+    name: string;
+    path?: string;
+};
+/**
+ * Home › Jobs › [country › region › city] › primaryCategory › Title.
+ * The place crumbs link into the listing routes (`/jobs/locations/:slug`);
+ * the category crumb nests under the most-specific place when present
+ * (`/jobs/locations/:place/:category`), else `/jobs/:category`. The last
+ * crumb (the job title) carries no `path` — the current page. Mirrors
+ * page.tsx:336-367.
+ *
+ * Returns structural kinds for chrome crumbs and data names for record
+ * crumbs. The application maps `kind` → display labels.
+ */
+declare function buildJobBreadcrumbs(job: PublicJob): JobBreadcrumb[];
+
+export { ALL_COUNTRY_CODES as A, type BreadcrumbItemInput as B, type CurrencyDisplay as C, type FormattedSalaryRange as F, type JobBreadcrumb as J, type NumberNotation as N, type SalaryTimeframeInput as S, type SalaryTimeframeValue as a, buildJobBreadcrumbs as b, formatSalaryStat as c, formatSalaryStatRange as d, type JsonLdObject as e, formatSalaryRange as f, type FaqItem as g, type JsonLdBoard as h, SENIORITY_ORDER as i, type SalaryFaqEntry as j, type SalaryJsonLdOptions as k, type SalaryOccupationListOptions as l, buildSalaryFaq as m, normalizeWebsiteUrl as n, companyCategorySalaryJsonLd as o, companySalaryJsonLd as p, createBreadcrumbJsonLd as q, createJobPostingJsonLd as r, crossAxisSalaryJsonLd as s, faqJsonLd as t, itemListJsonLd as u, locationSalaryJsonLd as v, skillSalaryJsonLd as w, sortBySeniority as x, titleSalaryJsonLd as y };