@cavuno/board 1.25.0 → 1.27.0

package/dist/sitemap.d.mts

@@ -0,0 +1,63 @@
+import { BoardSdk } from './index.mjs';
+import './jobs-DK5mPBgq.mjs';
+import './salaries-CrJsaZe6.mjs';
+
+/**
+ * Sitemap primitives — the pure XML + bucket-filename logic behind a board
+ * frontend's `/sitemap.xml` index and `/sitemap/:file` bucket routes.
+ * Mirrors the hosted board's 8-bucket model (`board-sitemap.loader.ts`): a
+ * sitemap index points at one file per content bucket, each an ordinary
+ * `<urlset>`.
+ *
+ * The XML byte layout transcribes the hosted serializers
+ * (`sitemap-xml.utils.ts` — `serializeBoardSitemap` /
+ * `serializeBoardSitemapIndex`) and is golden-tested byte-equal against
+ * them in-monorepo. `changefreq`/`priority` are deliberately not supported:
+ * the hosted builders never emit them.
+ *
+ * Network enumeration lives in `walker.ts`; this module is pure so the
+ * chunking + filename round-trip is unit-tested without a board.
+ */
+declare const SITEMAP_BUCKETS: readonly ["marketing", "jobs-categories", "jobs-skills", "jobs-locations", "jobs-details", "companies", "salaries", "blog"];
+type SitemapBucket = (typeof SITEMAP_BUCKETS)[number];
+/** Matches the hosted chunk size so the two corpora line up bucket-for-bucket. */
+declare const SITEMAP_CHUNK_SIZE = 45000;
+declare function xmlEscape(value: string): string;
+/**
+ * Chunk 0 (or no chunk) → the bare bucket filename; chunks 1+ append `-2`,
+ * `-3`, … so the common single-chunk case has the cleanest URL. The scheme
+ * is the filename component of the hosted `getBoardSitemapBucketPath`.
+ */
+declare function bucketFilename(bucket: SitemapBucket, chunkIndex?: number): string;
+/** Inverse of `bucketFilename`; returns null for unknown buckets / non-xml. */
+declare function parseBucketFilename(filename: string): {
+    bucket: SitemapBucket;
+    chunkIndex: number;
+} | null;
+declare function chunk<T>(items: readonly T[], size: number): T[][];
+/**
+ * One `<url>` entry. A bare string is shorthand for `{ url }` — the walker
+ * emits plain URL strings; hosted-shaped entries carry `lastModified` (and
+ * `images` on job-detail entries: the company logo).
+ */
+interface SitemapUrlEntry {
+    url: string;
+    /** A `Date` serializes to ISO 8601; a string passes through as-is. */
+    lastModified?: Date | string;
+    /** Google image-sitemap extension URLs (adds the `xmlns:image` namespace). */
+    images?: readonly string[];
+}
+interface SitemapIndexEntry {
+    url: string;
+    lastModified?: Date | string;
+}
+declare function renderUrlset(entries: readonly (string | SitemapUrlEntry)[]): string;
+declare function renderSitemapIndex(entries: readonly (string | SitemapIndexEntry)[]): string;
+
+/** Matches the hosted thin-content floor: a listing page needs ≥5 jobs to index. */
+declare const MIN_JOBS_PER_INDEXED_PAGE = 5;
+/** Which buckets the index lists. Blog is gated by its feature; the rest emit an empty urlset when a board lacks that content (valid, just zero URLs). */
+declare function listedBuckets(board: BoardSdk): Promise<SitemapBucket[]>;
+declare function buildBucketUrls(board: BoardSdk, origin: string, bucket: SitemapBucket): Promise<string[]>;
+
+export { MIN_JOBS_PER_INDEXED_PAGE, SITEMAP_BUCKETS, SITEMAP_CHUNK_SIZE, type SitemapBucket, type SitemapIndexEntry, type SitemapUrlEntry, bucketFilename, buildBucketUrls, chunk, listedBuckets, parseBucketFilename, renderSitemapIndex, renderUrlset, xmlEscape };

package/dist/sitemap.d.ts

@@ -0,0 +1,63 @@
+import { BoardSdk } from './index.js';
+import './jobs-DK5mPBgq.js';
+import './salaries-CXt6Vkrp.js';
+
+/**
+ * Sitemap primitives — the pure XML + bucket-filename logic behind a board
+ * frontend's `/sitemap.xml` index and `/sitemap/:file` bucket routes.
+ * Mirrors the hosted board's 8-bucket model (`board-sitemap.loader.ts`): a
+ * sitemap index points at one file per content bucket, each an ordinary
+ * `<urlset>`.
+ *
+ * The XML byte layout transcribes the hosted serializers
+ * (`sitemap-xml.utils.ts` — `serializeBoardSitemap` /
+ * `serializeBoardSitemapIndex`) and is golden-tested byte-equal against
+ * them in-monorepo. `changefreq`/`priority` are deliberately not supported:
+ * the hosted builders never emit them.
+ *
+ * Network enumeration lives in `walker.ts`; this module is pure so the
+ * chunking + filename round-trip is unit-tested without a board.
+ */
+declare const SITEMAP_BUCKETS: readonly ["marketing", "jobs-categories", "jobs-skills", "jobs-locations", "jobs-details", "companies", "salaries", "blog"];
+type SitemapBucket = (typeof SITEMAP_BUCKETS)[number];
+/** Matches the hosted chunk size so the two corpora line up bucket-for-bucket. */
+declare const SITEMAP_CHUNK_SIZE = 45000;
+declare function xmlEscape(value: string): string;
+/**
+ * Chunk 0 (or no chunk) → the bare bucket filename; chunks 1+ append `-2`,
+ * `-3`, … so the common single-chunk case has the cleanest URL. The scheme
+ * is the filename component of the hosted `getBoardSitemapBucketPath`.
+ */
+declare function bucketFilename(bucket: SitemapBucket, chunkIndex?: number): string;
+/** Inverse of `bucketFilename`; returns null for unknown buckets / non-xml. */
+declare function parseBucketFilename(filename: string): {
+    bucket: SitemapBucket;
+    chunkIndex: number;
+} | null;
+declare function chunk<T>(items: readonly T[], size: number): T[][];
+/**
+ * One `<url>` entry. A bare string is shorthand for `{ url }` — the walker
+ * emits plain URL strings; hosted-shaped entries carry `lastModified` (and
+ * `images` on job-detail entries: the company logo).
+ */
+interface SitemapUrlEntry {
+    url: string;
+    /** A `Date` serializes to ISO 8601; a string passes through as-is. */
+    lastModified?: Date | string;
+    /** Google image-sitemap extension URLs (adds the `xmlns:image` namespace). */
+    images?: readonly string[];
+}
+interface SitemapIndexEntry {
+    url: string;
+    lastModified?: Date | string;
+}
+declare function renderUrlset(entries: readonly (string | SitemapUrlEntry)[]): string;
+declare function renderSitemapIndex(entries: readonly (string | SitemapIndexEntry)[]): string;
+
+/** Matches the hosted thin-content floor: a listing page needs ≥5 jobs to index. */
+declare const MIN_JOBS_PER_INDEXED_PAGE = 5;
+/** Which buckets the index lists. Blog is gated by its feature; the rest emit an empty urlset when a board lacks that content (valid, just zero URLs). */
+declare function listedBuckets(board: BoardSdk): Promise<SitemapBucket[]>;
+declare function buildBucketUrls(board: BoardSdk, origin: string, bucket: SitemapBucket): Promise<string[]>;
+
+export { MIN_JOBS_PER_INDEXED_PAGE, SITEMAP_BUCKETS, SITEMAP_CHUNK_SIZE, type SitemapBucket, type SitemapIndexEntry, type SitemapUrlEntry, bucketFilename, buildBucketUrls, chunk, listedBuckets, parseBucketFilename, renderSitemapIndex, renderUrlset, xmlEscape };

package/dist/sitemap.js

@@ -0,0 +1,353 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/sitemap/index.ts
+var sitemap_exports = {};
+__export(sitemap_exports, {
+  MIN_JOBS_PER_INDEXED_PAGE: () => MIN_JOBS_PER_INDEXED_PAGE,
+  SITEMAP_BUCKETS: () => SITEMAP_BUCKETS,
+  SITEMAP_CHUNK_SIZE: () => SITEMAP_CHUNK_SIZE,
+  bucketFilename: () => bucketFilename,
+  buildBucketUrls: () => buildBucketUrls,
+  chunk: () => chunk,
+  listedBuckets: () => listedBuckets,
+  parseBucketFilename: () => parseBucketFilename,
+  renderSitemapIndex: () => renderSitemapIndex,
+  renderUrlset: () => renderUrlset,
+  xmlEscape: () => xmlEscape
+});
+module.exports = __toCommonJS(sitemap_exports);
+
+// 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;
+}