@cavuno/board 1.26.0 → 1.28.0

package/dist/sitemap.mjs

@@ -0,0 +1,330 @@
+// src/sitemap/xml.ts
+var SITEMAP_BUCKETS = [
+  "marketing",
+  "jobs-categories",
+  "jobs-skills",
+  "jobs-locations",
+  "jobs-details",
+  "companies",
+  "salaries",
+  "blog"
+];
+var SITEMAP_CHUNK_SIZE = 45e3;
+function xmlEscape(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
+function bucketFilename(bucket, chunkIndex = 0) {
+  const suffix = chunkIndex > 0 ? `-${chunkIndex + 1}` : "";
+  return `${bucket}${suffix}.xml`;
+}
+function parseBucketFilename(filename) {
+  if (!filename.endsWith(".xml")) return null;
+  const stem = filename.slice(0, -".xml".length);
+  const chunkMatch = stem.match(/^(.+?)-(\d+)$/);
+  if (chunkMatch) {
+    const candidate = chunkMatch[1];
+    const chunkNumber = Number.parseInt(chunkMatch[2] ?? "", 10);
+    if (SITEMAP_BUCKETS.includes(candidate) && Number.isFinite(chunkNumber) && chunkNumber >= 2) {
+      return { bucket: candidate, chunkIndex: chunkNumber - 1 };
+    }
+  }
+  if (SITEMAP_BUCKETS.includes(stem)) {
+    return { bucket: stem, chunkIndex: 0 };
+  }
+  return null;
+}
+function chunk(items, size) {
+  if (items.length === 0) return [];
+  if (items.length <= size) return [[...items]];
+  const out = [];
+  for (let i = 0; i < items.length; i += size) {
+    out.push(items.slice(i, i + size));
+  }
+  return out;
+}
+var XML_DECLARATION = '<?xml version="1.0" encoding="UTF-8"?>\n';
+var SITEMAP_NS = "http://www.sitemaps.org/schemas/sitemap/0.9";
+var IMAGE_NS = "http://www.google.com/schemas/sitemap-image/1.1";
+function lastmod(value) {
+  const serialized = value instanceof Date ? value.toISOString() : value;
+  return `<lastmod>${xmlEscape(serialized)}</lastmod>
+`;
+}
+function renderUrlset(entries) {
+  const normalized = entries.map(
+    (entry) => typeof entry === "string" ? { url: entry } : entry
+  );
+  const hasImages = normalized.some((entry) => (entry.images?.length ?? 0) > 0);
+  const namespaces = [`xmlns="${SITEMAP_NS}"`];
+  if (hasImages) {
+    namespaces.push(`xmlns:image="${IMAGE_NS}"`);
+  }
+  let xml = XML_DECLARATION + `<urlset ${namespaces.join(" ")}>
+`;
+  for (const entry of normalized) {
+    xml += "<url>\n";
+    xml += `<loc>${xmlEscape(entry.url)}</loc>
+`;
+    if (entry.images?.length) {
+      for (const image of entry.images) {
+        xml += `<image:image>
+<image:loc>${xmlEscape(image)}</image:loc>
+</image:image>
+`;
+      }
+    }
+    if (entry.lastModified) {
+      xml += lastmod(entry.lastModified);
+    }
+    xml += "</url>\n";
+  }
+  xml += "</urlset>\n";
+  return xml;
+}
+function renderSitemapIndex(entries) {
+  let xml = XML_DECLARATION + `<sitemapindex xmlns="${SITEMAP_NS}">
+`;
+  for (const raw of entries) {
+    const entry = typeof raw === "string" ? { url: raw } : raw;
+    xml += "<sitemap>\n";
+    xml += `<loc>${xmlEscape(entry.url)}</loc>
+`;
+    if (entry.lastModified) {
+      xml += lastmod(entry.lastModified);
+    }
+    xml += "</sitemap>\n";
+  }
+  xml += "</sitemapindex>\n";
+  return xml;
+}
+
+// src/pagination.ts
+function paginate(listFn, query, options) {
+  async function* pages() {
+    let current = query;
+    for (; ; ) {
+      const page = await listFn(current, options);
+      yield page;
+      if (!page.hasMore || page.nextCursor === null) return;
+      const { offset: _offset, ...rest } = current ?? {};
+      current = { ...rest, cursor: page.nextCursor };
+    }
+  }
+  return {
+    pages,
+    async *[Symbol.asyncIterator]() {
+      for await (const page of pages()) {
+        yield* page.data;
+      }
+    },
+    async toArray({ limit }) {
+      const items = [];
+      for await (const page of pages()) {
+        items.push(...page.data);
+        if (items.length >= limit) break;
+      }
+      return items.slice(0, limit);
+    }
+  };
+}
+
+// src/sitemap/walker.ts
+var MIN_JOBS_PER_INDEXED_PAGE = 5;
+var MAX_PAGES = 200;
+async function drainPages(pages) {
+  const acc = [];
+  let pageCount = 0;
+  for await (const page of pages) {
+    acc.push(...page.data);
+    pageCount += 1;
+    if (pageCount >= MAX_PAGES) {
+      if (page.hasMore) {
+        console.warn(
+          `[sitemap] hit the ${MAX_PAGES}-page pagination cap \u2014 output may be truncated`
+        );
+      }
+      break;
+    }
+  }
+  return acc;
+}
+var PAGE = 100;
+var OFFSET_CONCURRENCY = 8;
+var OFFSET_CEILING = 1e4;
+async function enumerateByOffset(fetchAt, fallback) {
+  const first = await fetchAt(0);
+  if (first.count === void 0) return fallback();
+  const all = [...first.data];
+  const ceiling = Math.min(first.count, OFFSET_CEILING);
+  const offsets = [];
+  for (let o = PAGE; o < ceiling; o += PAGE) offsets.push(o);
+  for (let i = 0; i < offsets.length; i += OFFSET_CONCURRENCY) {
+    const pages = await Promise.all(
+      offsets.slice(i, i + OFFSET_CONCURRENCY).map(fetchAt)
+    );
+    for (const page of pages) all.push(...page.data);
+  }
+  if (first.count > OFFSET_CEILING) {
+    console.warn(
+      `[sitemap] count ${first.count} exceeds the ${OFFSET_CEILING} offset ceiling \u2014 tail not enumerated (needs cursor/bulk support).`
+    );
+  }
+  return all;
+}
+function enumerateJobs(board) {
+  return enumerateByOffset(
+    (offset) => board.jobs.list({ limit: PAGE, offset }),
+    () => drainPages(paginate(board.jobs.list, { limit: PAGE }).pages())
+  );
+}
+function enumerateCompanies(board) {
+  return enumerateByOffset(
+    (offset) => board.companies.list({ limit: PAGE, offset }),
+    () => drainPages(paginate(board.companies.list, { limit: PAGE }).pages())
+  );
+}
+async function listedBuckets(board) {
+  const { features } = await board.context();
+  return SITEMAP_BUCKETS.filter((b) => b !== "blog" || features.blog);
+}
+async function buildBucketUrls(board, origin, bucket) {
+  switch (bucket) {
+    case "marketing":
+      return marketing(board, origin);
+    case "jobs-categories":
+      return jobsTaxonomy(board, origin, "categories");
+    case "jobs-skills":
+      return jobsTaxonomy(board, origin, "skills");
+    case "jobs-locations":
+      return jobsLocations(board, origin);
+    case "jobs-details":
+      return jobDetails(board, origin);
+    case "companies":
+      return companies(board, origin);
+    case "salaries":
+      return salaries(board, origin);
+    case "blog":
+      return blog(board, origin);
+  }
+}
+async function marketing(board, origin) {
+  const { features } = await board.context();
+  const urls = [
+    `${origin}/`,
+    `${origin}/jobs`,
+    `${origin}/about`,
+    `${origin}/privacy-policy`,
+    `${origin}/terms-of-service`,
+    `${origin}/cookie-policy`
+  ];
+  if (features.impressum) urls.push(`${origin}/impressum`);
+  if (features.talentDirectory) urls.push(`${origin}/talent`);
+  if (features.employers) urls.push(`${origin}/employers`);
+  return urls;
+}
+async function jobsTaxonomy(board, origin, kind) {
+  const jobs = await enumerateJobs(board);
+  const counts = /* @__PURE__ */ new Map();
+  for (const job of jobs) {
+    const slugs = new Set(
+      (kind === "categories" ? job.categories : job.skills).map((t) => t.slug)
+    );
+    for (const slug of slugs) counts.set(slug, (counts.get(slug) ?? 0) + 1);
+  }
+  const prefix = kind === "categories" ? `${origin}/jobs` : `${origin}/jobs/skills`;
+  return [...counts.entries()].filter(([, n]) => n >= MIN_JOBS_PER_INDEXED_PAGE).map(([slug]) => slug).sort().map((slug) => `${prefix}/${slug}`);
+}
+async function jobsLocations(board, origin) {
+  const { language } = await board.context();
+  const { data } = await board.salaries.locations.list({ locale: language });
+  return data.filter((l) => l.jobCount >= MIN_JOBS_PER_INDEXED_PAGE).map((l) => l.placeSlug).sort().map((slug) => `${origin}/jobs/locations/${slug}`);
+}
+async function jobDetails(board, origin) {
+  const jobs = await enumerateJobs(board);
+  const seen = /* @__PURE__ */ new Set();
+  for (const job of jobs) {
+    if (!job.company?.slug || !job.slug) continue;
+    seen.add(`${origin}/companies/${job.company.slug}/jobs/${job.slug}`);
+  }
+  return [...seen].sort();
+}
+async function companies(board, origin) {
+  const [list, markets] = await Promise.all([
+    enumerateCompanies(board),
+    board.companies.markets()
+  ]);
+  const urls = [`${origin}/companies`];
+  for (const company of list) urls.push(`${origin}/companies/${company.slug}`);
+  for (const market of markets.data) {
+    urls.push(`${origin}/companies/markets/${market.slug}`);
+  }
+  return urls;
+}
+async function salaries(board, origin) {
+  const { language } = await board.context();
+  const [salaryCompanies, titles, skills, locations] = await Promise.all([
+    board.salaries.companies.list(),
+    board.salaries.titles.list({ locale: language }),
+    board.salaries.skills.list({ locale: language }),
+    board.salaries.locations.list({ locale: language })
+  ]);
+  if (!salaryCompanies.data.length && !titles.data.length && !skills.data.length && !locations.data.length) {
+    return [];
+  }
+  const urls = [`${origin}/salaries`];
+  if (salaryCompanies.data.length) {
+    urls.push(`${origin}/salaries/companies`);
+    for (const c of salaryCompanies.data) {
+      urls.push(`${origin}/companies/${c.companySlug}/salaries`);
+    }
+  }
+  if (titles.data.length) {
+    urls.push(`${origin}/salaries/titles`);
+    for (const t of titles.data)
+      urls.push(`${origin}/salaries/titles/${t.slug}`);
+  }
+  if (skills.data.length) {
+    urls.push(`${origin}/salaries/skills`);
+    for (const s of skills.data)
+      urls.push(`${origin}/salaries/skills/${s.slug}`);
+  }
+  if (locations.data.length) {
+    urls.push(`${origin}/salaries/locations`);
+    for (const l of locations.data) {
+      urls.push(`${origin}/salaries/locations/${l.placeSlug}`);
+    }
+  }
+  return urls;
+}
+async function blog(board, origin) {
+  const posts = await drainPages(
+    paginate(board.blog.posts.list, { limit: 100 }).pages()
+  );
+  const urls = [`${origin}/blog`];
+  const tagSlugs = /* @__PURE__ */ new Set();
+  const authorSlugs = /* @__PURE__ */ new Set();
+  for (const post of posts) {
+    urls.push(`${origin}/blog/${post.slug}`);
+    for (const tag of post.tags) tagSlugs.add(tag.slug);
+    for (const author of post.authors) authorSlugs.add(author.slug);
+  }
+  for (const slug of [...tagSlugs].sort())
+    urls.push(`${origin}/blog/tag/${slug}`);
+  for (const slug of [...authorSlugs].sort()) {
+    urls.push(`${origin}/blog/author/${slug}`);
+  }
+  return urls;
+}
+export {
+  MIN_JOBS_PER_INDEXED_PAGE,
+  SITEMAP_BUCKETS,
+  SITEMAP_CHUNK_SIZE,
+  bucketFilename,
+  buildBucketUrls,
+  chunk,
+  listedBuckets,
+  parseBucketFilename,
+  renderSitemapIndex,
+  renderUrlset,
+  xmlEscape
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cavuno/board",
-  "version": "1.26.0",
+  "version": "1.28.0",
   "description": "Typed isomorphic client for the Cavuno Board API",
   "license": "MIT",
   "type": "commonjs",
@@ -60,6 +60,36 @@
         "default": "./dist/theme.js"
       }
     },
+    "./seo": {
+      "import": {
+        "types": "./dist/seo.d.mts",
+        "default": "./dist/seo.mjs"
+      },
+      "require": {
+        "types": "./dist/seo.d.ts",
+        "default": "./dist/seo.js"
+      }
+    },
+    "./sitemap": {
+      "import": {
+        "types": "./dist/sitemap.d.mts",
+        "default": "./dist/sitemap.mjs"
+      },
+      "require": {
+        "types": "./dist/sitemap.d.ts",
+        "default": "./dist/sitemap.js"
+      }
+    },
+    "./server": {
+      "import": {
+        "types": "./dist/server.d.mts",
+        "default": "./dist/server.mjs"
+      },
+      "require": {
+        "types": "./dist/server.d.ts",
+        "default": "./dist/server.js"
+      }
+    },
     "./skills": {
       "import": {
         "types": "./dist/skills.d.mts",

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

@@ -41,20 +41,21 @@ session.accessToken;     // bearer; never expose to the browser bundle on SSR
 
 ## Storage modes
 
-`auth.storage` is `'memory'` | `'nostore'` | a `CustomStorage`. Defaults: **`memory` in the browser, `nostore` on the server**. Browser login works out of the box; shared SSR instances stay stateless.
+`auth.storage` is `'memory'` | `'nostore'` | `'local'` | `'session'` | a `CustomStorage`. Defaults: **`memory` in the browser, `nostore` on the server**. Browser login works out of the box; shared SSR instances stay stateless.
 
 ```ts
 import { createBoardClient } from '@cavuno/board';
 
-// Browser/SPA: token held in memory on the instance.
+// Browser/SPA: 'local' persists the pair across tabs + reloads via
+// localStorage; 'session' scopes it to the tab; 'memory' drops it on reload.
 const board = createBoardClient({
   baseUrl: 'https://api.cavuno.com',
   board: 'pk_a8f3...',
-  auth: { storage: 'memory' },
+  auth: { storage: 'local' },
 });
 ```
 
-A `CustomStorage` implements async `getItem`/`setItem`/`removeItem` — back it with `localStorage`, IndexedDB, Redis, or your own store.
+`'local'`/`'session'` are **browser-only** — off-browser they throw loudly at client creation (`storage mode 'local' is browser-only — use 'nostore' + per-call headers on the server`). A `CustomStorage` implements async `getItem`/`setItem`/`removeItem` — back it with IndexedDB, Redis, or your own store.
 
 ## No auto-refresh on 401 — handle it explicitly
 
@@ -87,7 +88,7 @@ await board.auth.logout({ refreshToken });    // revokes server-side, clears sto
 
 ## Server-side pattern (keep tokens out of the browser)
 
-On SSR, do not hold the session on a shared instance. Keep the token pair in an httpOnly cookie owned by your app and pass it per call:
+On SSR, do not hold the session on a shared instance. Keep the token pair in an httpOnly cookie owned by your app and pass it per call. `@cavuno/board/server` ships the cookie codec + the single-flight refresh helper for exactly this (see `cavuno-board-server`):
 
 ```ts snippet
 // `accessToken` comes from your httpOnly cookie, read in server code.

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

@@ -0,0 +1,180 @@
+---
+name: cavuno-board-seo
+description: Structured data + head builders for board frontends with @cavuno/board/seo — Google for Jobs JobPosting JSON-LD, breadcrumbs, blog Article/ProfilePage, salary-page Occupation/FAQ structured data, and listing <head> descriptors. Use when building a job-detail, listing, blog, or salary page and it needs JSON-LD or SEO meta tags, or whenever "structured data", "rich results", or "Google for Jobs" comes up.
+---
+
+# SEO: structured data + head builders
+
+`@cavuno/board/seo` emits the exact structured data the hosted board emits —
+golden-tested against the hosted builders, so a tenant frontend gets Google
+for Jobs, breadcrumb, blog, and salary rich results without reinventing (or
+drifting from) the platform's rules. Render every builder's output into a
+`<script type="application/ld+json">` tag; builders return `null` when there
+is nothing worth emitting — skip the tag then.
+
+## When to use
+
+- A job detail page needs Google for Jobs `JobPosting` JSON-LD.
+- Any page needs a `BreadcrumbList`.
+- Blog post / author pages need `Article` / `ProfilePage` JSON-LD.
+- Salary pages need `Occupation`/`MonetaryAmountDistribution`/`ItemList`/
+  `FAQPage` structured data or the templated salary FAQ.
+- A jobs-listing page needs its `<head>` (title with count, canonical, OG).
+
+## When not to use
+
+- Display text on the page itself — `cavuno-board-format`.
+- Sitemaps and robots.txt — the sitemap module/skill.
+- OG image generation and route maps — app-owned (see out of scope).
+
+## Job-posting JSON-LD (the detail page)
+
+`PublicJob` carries every field this needs — including the derived remote
+permit codes. Worldwide-remote jobs automatically enumerate all 249
+countries (Google requires a location signal next to TELECOMMUTE).
+
+```ts snippet
+import { createJobPostingJsonLd } from '@cavuno/board/seo';
+
+const { name, logoUrl } = await board.context();
+const job = await board.jobs.retrieve('senior-chef');
+
+const jsonLd = createJobPostingJsonLd({
+  job,
+  board: { name, logoUrl },
+  shareUrl: `https://jobs.example.com/companies/${job.company?.slug}/jobs/${job.slug}`,
+});
+// null when nothing renderable remains — omit the <script> tag then.
+```
+
+## Breadcrumbs
+
+Hosted semantics: labels are trimmed, blank crumbs dropped, fewer than two
+crumbs → `null`, and the current page (no `href`) omits `item`. Pass
+absolute hrefs, or give `origin` and use paths:
+
+```ts snippet
+import { createBreadcrumbJsonLd } from '@cavuno/board/seo';
+
+const trail = createBreadcrumbJsonLd(
+  [
+    { label: 'Home', href: '/' },
+    { label: 'Jobs', href: '/jobs' },
+    { label: job.title }, // current page — no href
+  ],
+  { origin: 'https://jobs.example.com' },
+);
+```
+
+## Blog Article + author ProfilePage
+
+```ts snippet
+import {
+  createBlogArticleJsonLd,
+  createAuthorProfileJsonLd,
+} from '@cavuno/board/seo';
+
+const post = await board.blog.posts.retrieve('hello-world');
+const article = createBlogArticleJsonLd({
+  post,
+  boardName: name,
+  permalink: `https://jobs.example.com/blog/${post.slug}`,
+  ogImageUrl: `https://jobs.example.com/blog/${post.slug}/og`, // fallback when no cover
+});
+
+const author = await board.blog.authors.retrieve('jane');
+const { data: authorPosts } = await board.blog.posts.list({ authorSlug: 'jane' });
+const profile = createAuthorProfileJsonLd({
+  author,
+  canonical: `https://jobs.example.com/blog/author/${author.slug}`,
+  description: author.bio ?? `Posts by ${author.name}`,
+  origin: 'https://jobs.example.com',
+  posts: authorPosts, // newest first; the builder keeps 5 as hasPart
+  totalPosts: authorPosts.length,
+});
+```
+
+## Salary-page structured data + FAQ
+
+The board language is a REQUIRED leading parameter wherever display strings
+are produced (no `en` default). The money formatters are USD-hardcoded —
+the hosted salary-page quirk, kept deliberately; the locale drives number
+formatting only. The FAQ ships TEMPLATED English sentences (board-custom
+FAQ copy is a tracked API gap and will supersede it).
+
+```ts snippet
+import {
+  titleSalaryJsonLd,
+  buildSalaryFaq,
+  faqJsonLd,
+  itemListJsonLd,
+  formatRange,
+  sortBySeniority,
+} from '@cavuno/board/seo';
+
+const { language } = await board.context();
+const detail = await board.salaries.titles.retrieve('software-engineer');
+
+const occupation = titleSalaryJsonLd(language, detail);
+const faq = faqJsonLd(
+  buildSalaryFaq(language, detail.categoryName, detail.overallSalary),
+);
+// Index pages: itemListJsonLd(items); on-page figures: formatRange(language, min, max)
+// and sortBySeniority(detail.bySeniority) for the ladder table.
+```
+
+Also available: `skillSalaryJsonLd(detail)`, `locationSalaryJsonLd(detail)`
+(city-level pages only), `crossAxisSalaryJsonLd(locale, args)`,
+`companySalaryJsonLd(locale, detail)`,
+`companyCategorySalaryJsonLd(locale, detail)`, `formatUsd(locale, value)`,
+`formatSeniority(locale, key)`, `SENIORITY_ORDER`.
+
+## Listing pages: head + structural JSON-LD
+
+Locale-neutral pass-through — you supply the heading copy:
+
+```ts snippet
+import { listingHead, listingJsonLd } from '@cavuno/board/seo';
+
+const head = listingHead({
+  boardName: name,
+  origin: 'https://jobs.example.com',
+  path: '/jobs/robotics',
+  heading: 'Robotics jobs',
+  count: 42, // → "42 Robotics jobs | Acme Jobs"
+});
+// head.meta → title/description/OG descriptors; head.links → canonical.
+
+const objects = listingJsonLd({
+  origin: 'https://jobs.example.com',
+  breadcrumbs: [{ name: 'Home', path: '/' }, { name: 'Jobs' }],
+  jobs: cards.map((c) => ({ slug: c.slug, company: c.company })),
+});
+```
+
+## Anti-patterns
+
+```ts no-check
+// NEVER hand-roll JobPosting JSON-LD — the pruning, salary mirroring, and
+// worldwide country enumeration are Google-spec rules the SDK encodes:
+const ld = { '@type': 'JobPosting', salary: job.salaryMin }; // wrong shape
+// NEVER default the locale on salary builders:
+titleSalaryJsonLd('en', detail); // hardcoded 'en' on a de board
+// NEVER emit a JSON-LD script for a null builder result.
+```
+
+## Out of scope — do not invent exports
+
+OG **image generation** (the `/og` card renderer), the legal/route **map**,
+and the meta title/description **copy** (board SEO config + localized copy
+is not replicated — `listingHead` takes your strings) are app-owned. No
+sitemap builders here — that is `@cavuno/board/sitemap`'s job.
+
+## Verify
+
+- [ ] The job detail page's JSON-LD validates in Google's Rich Results test
+      as a JobPosting, and a worldwide-remote job lists 249 countries.
+- [ ] Pages with a null builder result render NO empty ld+json script.
+- [ ] A de board passes `language` from `board.context()` — the salary
+      FAQ figures render de-formatted, and no call site hardcodes 'en'.
+- [ ] Breadcrumb JSON-LD only appears on pages with 2+ crumbs.