@cavuno/board 1.25.0 → 1.27.0

package/dist/seo.d.ts

@@ -0,0 +1,288 @@
+import { P as PublicBoard, a as PublicBlogPostSummary, B as BlogAuthorEmbed, C as CompanyCategorySalary, b as CompanySalary, L as LocationSalaryDetail, S as SkillSalaryDetail, T as TitleSalaryDetail } from './salaries-CXt6Vkrp.js';
+import { P as PublicJob } from './jobs-DK5mPBgq.js';
+
+/**
+ * Google for Jobs `JobPosting` structured data on the `@cavuno/board` wire
+ * types, transcribed field-by-field from the hosted board's generator
+ * (`_lib/job-posting-json-ld.ts` + `job-posting-location-json-ld.ts`) and
+ * golden-tested against it in-monorepo (ADR-0057).
+ *
+ * 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
+ * parity ledger):
+ *   - `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 (`@kit/data-remote`
+ * `COUNTRIES`, built from `world-countries`): sorted by English common
+ * name, includes `XK` (Kosovo), excludes `KP` (North Korea). Golden-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;
+
+/**
+ * Blog structured data on the `@cavuno/board` wire types, transcribed from
+ * the hosted board's builders (`blog/_lib/server/blog-json-ld.ts`:
+ * `createArticleJsonLd` + `createAuthorProfilePageJsonLd`) and golden-tested
+ * against them in-monorepo (ADR-0057).
+ *
+ * JSON-LD structure is locale-neutral — no board-language parameter; every
+ * display string is a wire value (or caller copy) passed through.
+ */
+
+/**
+ * The post fields the Article builder reads — the detail `PublicBlogPost`
+ * satisfies this.
+ */
+type ArticleJsonLdPost = Pick<PublicBlogPostSummary, 'title' | 'customExcerpt' | 'publishedAt' | 'coverUrl' | 'authors'>;
+/**
+ * `Article` (+ author/publisher) for a blog post — mirrors the hosted
+ * Article JSON-LD.
+ *
+ * `image` follows the hosted precedence: the post's cover (feature) image
+ * first, then `ogImageUrl` — pass your page's OG image URL (hosted passes
+ * its generated `/blog/:slug/og` card; OG generation itself is app-owned
+ * per ADR-0039).
+ */
+declare function createBlogArticleJsonLd({ post, boardName, permalink, ogImageUrl, }: {
+    post: ArticleJsonLdPost;
+    boardName: string;
+    permalink: string;
+    /** Fallback image when the post has no cover, e.g. your generated OG card URL. */
+    ogImageUrl?: string | null;
+}): JsonLdObject;
+/**
+ * `ProfilePage` for a blog author page — the hosted shape: a `Person` main
+ * entity (id-anchored at `#profile`, social links normalized into `sameAs`),
+ * the author's recent posts as `hasPart` Articles, and a WriteAction
+ * `InteractionCounter` for the post count.
+ *
+ * Returns `null` when the author has no name. `hasPart` URLs assume the
+ * `/blog/:slug` post route (the hosted and starter convention).
+ */
+declare function createAuthorProfileJsonLd({ author, canonical, description, origin, posts, totalPosts, }: {
+    author: BlogAuthorEmbed;
+    /** Absolute canonical URL of the author page. */
+    canonical: string;
+    /** Author blurb — hosted passes the bio (or its templated hero copy). */
+    description: string;
+    /** Site origin for `hasPart` post URLs; `null` omits the posts. */
+    origin: string | null;
+    /** The author's recent posts (newest first) — the builder keeps the first 5. */
+    posts: Pick<PublicBlogPostSummary, 'title' | 'slug' | 'publishedAt'>[];
+    totalPosts: number;
+}): JsonLdObject | null;
+
+/**
+ * `BreadcrumbList` structured data, transcribed from the hosted board's
+ * `boards/_lib/server/breadcrumb-json-ld.ts` (`createBreadcrumbListJsonLd`)
+ * and golden-tested against it in-monorepo (ADR-0057).
+ *
+ * The hosted builder resolves relative hrefs against the board's canonical
+ * origin (custom domain aware, db-backed); this transcription takes the
+ * origin as a plain argument instead — pass absolute hrefs, or provide
+ * `options.origin` for relative ones. JSON-LD structure is locale-neutral:
+ * the labels are caller copy passed through.
+ */
+
+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;
+
+/**
+ * Framework-neutral `<head>` + structural JSON-LD builders for jobs-listing
+ * pages (ADR-0057). Locale-neutral pass-through: the caller supplies the
+ * heading/board copy (title/description COPY is board-SEO-config +
+ * localized — a named exclusion; these builders replicate the hosted
+ * STRUCTURE: title with result count, canonical, Open Graph, breadcrumb +
+ * job `ItemList`).
+ */
+
+interface ListingHeadOptions {
+    boardName: string;
+    origin: string;
+    /** Absolute path of THIS page, for canonical / og:url, e.g. `/jobs/robotik`. */
+    path: string;
+    /** Human heading, e.g. `Robotik jobs in Berlin` or `Jobs`. */
+    heading: string;
+    /** Result count — prefixed into the title (`N heading`). */
+    count?: number;
+}
+/**
+ * Meta/link descriptors for a jobs-listing page — title (with result
+ * count), meta description, Open Graph, and `<link rel=canonical>`.
+ * Framework-neutral: map `meta`/`links` into your head manager.
+ */
+declare function listingHead(options: ListingHeadOptions): {
+    meta: ({
+        title: string;
+        name?: undefined;
+        content?: undefined;
+        property?: undefined;
+    } | {
+        name: string;
+        content: string;
+        title?: undefined;
+        property?: undefined;
+    } | {
+        property: string;
+        content: string;
+        title?: undefined;
+        name?: undefined;
+    })[];
+    links: {
+        rel: string;
+        href: string;
+    }[];
+};
+interface JobLink {
+    slug: string;
+    company: {
+        slug: string;
+    } | null;
+}
+/**
+ * `BreadcrumbList` (+ `ItemList` of the visible jobs) JSON-LD for a listing
+ * page, mirroring the structural JSON-LD the hosted board emits. The rich
+ * category set (`Occupation`/`FAQPage`/`MonetaryAmountDistribution`) lives
+ * in `./salary` — feed it the salary detail reads.
+ */
+declare function listingJsonLd(options: {
+    origin: string;
+    /** Breadcrumb trail; the current (last) page omits `path` → no `item` (schema.org). */
+    breadcrumbs: Array<{
+        name: string;
+        path?: string;
+    }>;
+    jobs?: JobLink[];
+}): JsonLdObject[];
+
+/**
+ * Compact USD amount in the board language (`$90K`, de: `90.000 $`) — the
+ * hosted salary-page money formatter. USD-hardcoded (hosted quirk); the
+ * locale drives digits, grouping, and symbol placement only.
+ */
+declare function formatUsd(locale: string, value: number): string;
+/** `formatUsd(min) – formatUsd(max)` with the hosted spaced en dash. */
+declare function formatRange(locale: string, min: number, max: number): string;
+/**
+ * Seniority display label. Precedence (hosted shape): owner override >
+ * board-language lexicon (en = the English source labels) > title-case
+ * fallback for an unknown key (CAV-352 / 9b).
+ */
+declare function formatSeniority(locale: string, value: string, overrides?: Record<string, string>): string;
+/** 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[];
+interface FaqItem {
+    q: string;
+    a: string;
+}
+/**
+ * A templated salary FAQ (interim — see the module doc). The sentences are
+ * English; the embedded range is board-language-formatted via `formatRange`
+ * (the only part hosted localizes). Empty when there is no overall figure.
+ */
+declare function buildSalaryFaq(locale: string, label: string, overall: {
+    avgMin: number;
+    avgMax: number;
+    jobCount: number;
+} | null): FaqItem[];
+/** 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 `buildSalaryFaq` items (or any `{q,a}` list). */
+declare function faqJsonLd(faqs: FaqItem[]): JsonLdObject | null;
+/**
+ * `Occupation` for a job-title salary page. Per-seniority distribution
+ * names embed the board-language seniority label (`formatSeniority`).
+ */
+declare function titleSalaryJsonLd(locale: string, d: TitleSalaryDetail): JsonLdObject | null;
+/** `Occupation` for a skill salary page (overall distribution + median). */
+declare function skillSalaryJsonLd(d: SkillSalaryDetail): JsonLdObject | null;
+/**
+ * `Occupation` for a location salary page. City-level pages only (the
+ * hosted page gates on city/locality); `null` otherwise.
+ */
+declare function locationSalaryJsonLd(d: LocationSalaryDetail): JsonLdObject | null;
+/**
+ * Cross-axis (title×location / skill×location) `Occupation` JSON-LD. Takes
+ * primitives to stay decoupled from the two cross-axis detail wire types.
+ */
+declare function crossAxisSalaryJsonLd(locale: string, 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;
+}): JsonLdObject | null;
+/**
+ * `OccupationAggregationByEmployer` for a company's salary overview —
+ * mirrors the hosted company-salary page's Google-salary structured data
+ * (base + per-seniority distributions, the board median/IQR baseline as
+ * the aggregate stats).
+ */
+declare function companySalaryJsonLd(locale: string, d: CompanySalary): JsonLdObject | null;
+/** `Occupation` for one job category at a company (the hosted category page). */
+declare function companyCategorySalaryJsonLd(locale: string, d: CompanyCategorySalary): JsonLdObject | null;
+
+export { ALL_COUNTRY_CODES, type ArticleJsonLdPost, type BreadcrumbItemInput, type FaqItem, type JsonLdBoard, type JsonLdObject, type ListingHeadOptions, SENIORITY_ORDER, buildSalaryFaq, companyCategorySalaryJsonLd, companySalaryJsonLd, createAuthorProfileJsonLd, createBlogArticleJsonLd, createBreadcrumbJsonLd, createJobPostingJsonLd, crossAxisSalaryJsonLd, faqJsonLd, formatRange, formatSeniority, formatUsd, itemListJsonLd, listingHead, listingJsonLd, locationSalaryJsonLd, normalizeWebsiteUrl, skillSalaryJsonLd, sortBySeniority, titleSalaryJsonLd };