@cavuno/board 4.57.0 → 4.59.0

package/dist/sitemap.d.mts

@@ -1,10 +1,10 @@
 import { BoardSdk } from './index.mjs';
-import './_spec-CDYDY0hB.mjs';
-import './search--bO1b3RJ.mjs';
-import './jobs-CgmHLS8j.mjs';
-import './board-DbBBz7Pv.mjs';
-import './seo-C7HjUu_z.mjs';
-import './blog-WupXypHv.mjs';
+import './_spec-bmTwonT1.mjs';
+import './search-CcCXc47H.mjs';
+import './jobs-DmrG_cGZ.mjs';
+import './board-BrJfw_S7.mjs';
+import './seo-DSRRhklF.mjs';
+import './blog-2rj7bfEp.mjs';
 
 /**
  * Sitemap primitives — the pure XML + bucket-filename logic behind a board
@@ -89,7 +89,18 @@ interface ListedSitemapBucket {
  * freshness stamp survives.
  */
 declare function listedBucketEntries(board: BoardSdk): Promise<ListedSitemapBucket[]>;
-declare function buildBucketUrls(board: BoardSdk, origin: string, bucket: SitemapBucket): Promise<string[]>;
+/** Options for `buildBucketUrls` and `buildBucketEntries`. */
+interface BuildBucketOptions {
+    /**
+     * Whether your site publishes `/impressum`, usually because it has
+     * Impressum content of its own. When set, the marketing bucket lists
+     * `/impressum` exactly when this is `true`, whatever the board's published
+     * sitemap or the deprecated `features.impressum` says. Leave it unset to
+     * keep following the board.
+     */
+    impressum?: boolean;
+}
+declare function buildBucketUrls(board: BoardSdk, origin: string, bucket: SitemapBucket, options?: BuildBucketOptions): Promise<string[]>;
 /**
  * Like `buildBucketUrls`, but keeps each URL's `lastModified` where the board
  * publishes one. The result feeds `renderUrlset` directly, so every `<url>`
@@ -100,6 +111,6 @@ declare function buildBucketUrls(board: BoardSdk, origin: string, bucket: Sitema
  * so entries come back as `{ url }` only — identical output to
  * `buildBucketUrls`, just in the wider shape.
  */
-declare function buildBucketEntries(board: BoardSdk, origin: string, bucket: SitemapBucket): Promise<SitemapUrlEntry[]>;
+declare function buildBucketEntries(board: BoardSdk, origin: string, bucket: SitemapBucket, options?: BuildBucketOptions): Promise<SitemapUrlEntry[]>;
 
-export { type ListedSitemapBucket, MIN_JOBS_PER_INDEXED_PAGE, SITEMAP_BUCKETS, SITEMAP_CHUNK_SIZE, type SitemapBucket, type SitemapIndexEntry, type SitemapUrlEntry, bucketFilename, buildBucketEntries, buildBucketUrls, chunk, listedBucketEntries, listedBuckets, parseBucketFilename, renderSitemapIndex, renderUrlset, xmlEscape };
+export { type BuildBucketOptions, type ListedSitemapBucket, MIN_JOBS_PER_INDEXED_PAGE, SITEMAP_BUCKETS, SITEMAP_CHUNK_SIZE, type SitemapBucket, type SitemapIndexEntry, type SitemapUrlEntry, bucketFilename, buildBucketEntries, buildBucketUrls, chunk, listedBucketEntries, listedBuckets, parseBucketFilename, renderSitemapIndex, renderUrlset, xmlEscape };

package/dist/sitemap.d.ts

@@ -1,10 +1,10 @@
 import { BoardSdk } from './index.js';
-import './_spec-CDYDY0hB.js';
-import './search-BvhQ92ZO.js';
-import './jobs-B-NPmaV0.js';
-import './board-CmQox8FZ.js';
-import './seo-CBRBS8Mc.js';
-import './blog-DNGOmaKI.js';
+import './_spec-bmTwonT1.js';
+import './search-DwJi7GFS.js';
+import './jobs-Cfmfxt86.js';
+import './board-Bdc--f9u.js';
+import './seo-D4DJWYCY.js';
+import './blog-BEKRpXYK.js';
 
 /**
  * Sitemap primitives — the pure XML + bucket-filename logic behind a board
@@ -89,7 +89,18 @@ interface ListedSitemapBucket {
  * freshness stamp survives.
  */
 declare function listedBucketEntries(board: BoardSdk): Promise<ListedSitemapBucket[]>;
-declare function buildBucketUrls(board: BoardSdk, origin: string, bucket: SitemapBucket): Promise<string[]>;
+/** Options for `buildBucketUrls` and `buildBucketEntries`. */
+interface BuildBucketOptions {
+    /**
+     * Whether your site publishes `/impressum`, usually because it has
+     * Impressum content of its own. When set, the marketing bucket lists
+     * `/impressum` exactly when this is `true`, whatever the board's published
+     * sitemap or the deprecated `features.impressum` says. Leave it unset to
+     * keep following the board.
+     */
+    impressum?: boolean;
+}
+declare function buildBucketUrls(board: BoardSdk, origin: string, bucket: SitemapBucket, options?: BuildBucketOptions): Promise<string[]>;
 /**
  * Like `buildBucketUrls`, but keeps each URL's `lastModified` where the board
  * publishes one. The result feeds `renderUrlset` directly, so every `<url>`
@@ -100,6 +111,6 @@ declare function buildBucketUrls(board: BoardSdk, origin: string, bucket: Sitema
  * so entries come back as `{ url }` only — identical output to
  * `buildBucketUrls`, just in the wider shape.
  */
-declare function buildBucketEntries(board: BoardSdk, origin: string, bucket: SitemapBucket): Promise<SitemapUrlEntry[]>;
+declare function buildBucketEntries(board: BoardSdk, origin: string, bucket: SitemapBucket, options?: BuildBucketOptions): Promise<SitemapUrlEntry[]>;
 
-export { type ListedSitemapBucket, MIN_JOBS_PER_INDEXED_PAGE, SITEMAP_BUCKETS, SITEMAP_CHUNK_SIZE, type SitemapBucket, type SitemapIndexEntry, type SitemapUrlEntry, bucketFilename, buildBucketEntries, buildBucketUrls, chunk, listedBucketEntries, listedBuckets, parseBucketFilename, renderSitemapIndex, renderUrlset, xmlEscape };
+export { type BuildBucketOptions, type ListedSitemapBucket, MIN_JOBS_PER_INDEXED_PAGE, SITEMAP_BUCKETS, SITEMAP_CHUNK_SIZE, type SitemapBucket, type SitemapIndexEntry, type SitemapUrlEntry, bucketFilename, buildBucketEntries, buildBucketUrls, chunk, listedBucketEntries, listedBuckets, parseBucketFilename, renderSitemapIndex, renderUrlset, xmlEscape };

package/dist/sitemap.js

@@ -335,11 +335,20 @@ async function listedBucketEntries(board) {
     );
   }
 }
-async function buildBucketUrls(board, origin, bucket) {
-  const entries = await buildBucketEntries(board, origin, bucket);
+async function buildBucketUrls(board, origin, bucket, options) {
+  const entries = await buildBucketEntries(board, origin, bucket, options);
   return entries.map((entry) => entry.url);
 }
-async function buildBucketEntries(board, origin, bucket) {
+async function buildBucketEntries(board, origin, bucket, options) {
+  const entries = await boardBucketEntries(board, origin, bucket);
+  if (bucket !== "marketing" || options?.impressum === void 0) {
+    return entries;
+  }
+  const impressumUrl = `${origin}${BOARD_PATHS.impressum}`;
+  const listed = entries.filter((entry) => entry.url !== impressumUrl);
+  return options.impressum ? [...listed, { url: impressumUrl }] : listed;
+}
+async function boardBucketEntries(board, origin, bucket) {
   try {
     return await mirrorBucketEntries(board, origin, bucket);
   } catch (error) {

package/dist/sitemap.mjs

@@ -201,11 +201,20 @@ async function listedBucketEntries(board) {
     );
   }
 }
-async function buildBucketUrls(board, origin, bucket) {
-  const entries = await buildBucketEntries(board, origin, bucket);
+async function buildBucketUrls(board, origin, bucket, options) {
+  const entries = await buildBucketEntries(board, origin, bucket, options);
   return entries.map((entry) => entry.url);
 }
-async function buildBucketEntries(board, origin, bucket) {
+async function buildBucketEntries(board, origin, bucket, options) {
+  const entries = await boardBucketEntries(board, origin, bucket);
+  if (bucket !== "marketing" || options?.impressum === void 0) {
+    return entries;
+  }
+  const impressumUrl = `${origin}${BOARD_PATHS.impressum}`;
+  const listed = entries.filter((entry) => entry.url !== impressumUrl);
+  return options.impressum ? [...listed, { url: impressumUrl }] : listed;
+}
+async function boardBucketEntries(board, origin, bucket) {
   try {
     return await mirrorBucketEntries(board, origin, bucket);
   } catch (error) {

package/dist/suggest.d.mts

@@ -1,5 +1,5 @@
-import { h as SuggestionItem, b as SearchSuggestQuery, F as FetchOptions, g as SuggestResult } from './search--bO1b3RJ.mjs';
-import './_spec-CDYDY0hB.mjs';
+import { h as SuggestionItem, b as SearchSuggestQuery, F as FetchOptions, g as SuggestResult } from './search-CcCXc47H.mjs';
+import './_spec-bmTwonT1.mjs';
 
 /**
  * `@cavuno/board/suggest` — framework-agnostic headless search-suggest

package/dist/suggest.d.ts

@@ -1,5 +1,5 @@
-import { h as SuggestionItem, b as SearchSuggestQuery, F as FetchOptions, g as SuggestResult } from './search-BvhQ92ZO.js';
-import './_spec-CDYDY0hB.js';
+import { h as SuggestionItem, b as SearchSuggestQuery, F as FetchOptions, g as SuggestResult } from './search-DwJi7GFS.js';
+import './_spec-bmTwonT1.js';
 
 /**
  * `@cavuno/board/suggest` — framework-agnostic headless search-suggest

package/dist/well-known.mjs

@@ -1,6 +1,6 @@
 import {
   compileManifest
-} from "./chunk-GUXSUQCP.mjs";
+} from "./chunk-LO7D3AIX.mjs";
 import "./chunk-MSY7ERBY.mjs";
 
 // src/well-known/handler.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cavuno/board",
-  "version": "4.57.0",
+  "version": "4.59.0",
   "description": "Build custom job boards and careers pages with Cavuno’s TypeScript SDK.",
   "keywords": [
     "api-client",

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

@@ -90,3 +90,10 @@ The signed-in OTP verification, resend, magic-link, and OAuth branches use their
 ## Cavuno SDK reference
 
 For setup and API details beyond this workflow, use the [Cavuno Board SDK documentation](https://cavuno.com/docs/sdk).
+
+
+### OAuth browser proof
+
+SSO sign-ins require proof from the browser that started authorization. Google and LinkedIn sign-ins accept and check the same proof whenever it is supplied, and it will become required for them in a later release. The browser SDK establishes and retains a random secret before `getOAuthAuthorizationUrl` or `getSsoAuthorizationUrl`, sends only its SHA-256 hash to authorization, and supplies the secret when `exchangeOAuth` runs. Keep browser storage available through the provider round trip. Never take a binding secret from a completion URL or copy another browser's completion token.
+
+Server callers (a Worker or other server runtime without browser storage) should generate a random secret, retain it securely in the visitor's session (for example an HttpOnly cookie), pass its lowercase SHA-256 hex as `browserBindingHash` to `getOAuthAuthorizationUrl`, and pass the original secret as `browserBinding` to `exchangeOAuth`. Without a `browserBindingHash`, the SDK sends a Google or LinkedIn request unbound from a server runtime; that is accepted today so existing deployments keep working, and will be refused once proof becomes required. A sign-in started with proof must finish with the matching secret: failed proof leaves the one-time token unconsumed. Automatic OAuth proof is cleared if authorization fails or once exchange succeeds; a rejected exchange keeps the proof available for retry.

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

@@ -59,7 +59,9 @@ formatSalaryStatRange(language, 90000, 120000, detail.currency);
 formatSalaryStatRange(language, 90000, 120000, detail.currency, 'standard');
 
 // Custom fields — language first. number → kind: 'number' (raw);
-// multi_select → kind: 'multi_select' with values: string[] (labels).
+// multi_select → kind: 'multi_select' with values: string[] (labels);
+// rich_text → kind: 'rich_text' with API-sanitized HTML: render it as HTML.
+// kind: 'text' stays plain text, so keep escaping it.
 // Do not String(n). Do not join multi-select in the SDK — app owns list
 // style (conjunction / short / chips):
 // new Intl.ListFormat(language, { style: 'long', type: 'conjunction' })
@@ -121,6 +123,8 @@ const jobBadges = resolveCustomFieldDisplay(
   switch (entry.kind) {
     case 'text': // a single_select resolves to its option label
       return [entry.value];
+    case 'rich_text': // sanitized HTML: render in a detail section, not a badge
+      return [];
     case 'multi_select':
       return entry.values;
     case 'boolean':

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

@@ -0,0 +1,135 @@
+---
+name: cavuno-board-products
+description: Digital product storefront with @cavuno/board. Use for product lists and pages, reviews, free claims, embedded paid checkout, the purchase download page with its email confirmation, downloads, buyer reviews, resending the link, or the signed-in buyer's purchases.
+---
+
+# Digital product storefront
+
+Operators create products in the Cavuno dashboard or the Operator API. The frontend lists them, sells them and serves the buyer's download page. `board.products` covers the catalogue and checkout; `board.purchases` covers everything after the purchase, keyed by the purchase token in the buyer's download link.
+
+Routes: `BOARD_PATHS.products` (`/products`), `productPath(slug)`, the download page at `purchasePath(token)`, and `BOARD_PATHS.mePurchases` (`/me/purchases`), all from `@cavuno/board/paths`. Link to the `downloadUrl` the API returns instead of building the download path: it follows the board's route manifest.
+
+## List and render products
+
+```ts snippet
+const { data: products, nextCursor } = await board.products.list({
+  sort: 'featured', // 'newest' | 'rating' | 'price_asc'
+  price: 'paid', // or 'free'; omit for both
+  limit: 24,
+});
+
+const product = await board.products.get('salary-guide');
+if (product.ratingsEnabled) {
+  const { data: reviews } = await board.products.reviews('salary-guide');
+}
+```
+
+Only listed products appear in `list`; show a Products nav item only when it returns any. `get` also answers for an unlisted product by its exact slug: render it, but keep `isListed: false` pages out of lists, sitemaps and search indexes. An unknown, archived or undeliverable product is `products_not_found` (404). `price.kind` is `free`, `fixed` or `pay_what_you_want` (`amountCents` is the minimum, `suggestedCents` the prefill). `details` rows are `kind: 'text'` (`label`, `value`) or `kind: 'check'` (`label`, `checked`): render a check row as a tick or a cross with "Yes"/"No" as its accessible text, not as a word. Catalogue reads are public and cacheable.
+
+## Checkout: free and paid
+
+Collect the email and the answers to `product.questions` (text → string, checkbox → boolean, dropdown → one of `options`) in your own form, then call `checkout` from the server.
+
+```ts snippet
+const result = await board.products.checkout('salary-guide', {
+  email: 'ada@example.com',
+  answers: [{ questionId: 'waiver', value: true }],
+  jobAlertOptIn: false, // free products only; render unticked
+  returnPath: '/products/salary-guide',
+  website: '', // honeypot: render hidden, send empty
+});
+
+if (result.status === 'complete') {
+  redirect(result.downloadUrl); // free claim recorded and emailed
+} else {
+  mountEmbeddedCheckout(result); // paid: Stripe mount kit
+}
+```
+
+`status: 'open'` returns `publishableKey`, `stripeAccountId`, `clientSecret` and `sessionId`. Mount with `loadStripe(publishableKey, { stripeAccount: stripeAccountId })` and `initEmbeddedCheckout({ clientSecret })`. The session expires after 30 minutes. For pay what you want, send `amountCents` (at least the minimum) or omit it to let the buyer choose on Stripe's page; `amountCents: 0` on a $0+ product is a free claim.
+
+After Stripe returns with `session_id`, poll briefly:
+
+```ts snippet
+const status = await board.products.getCheckout('salary-guide', sessionId, {
+  cache: 'no-store',
+});
+if (status.status === 'paid') redirect(status.downloadUrl);
+// still 'awaiting_payment' after ~10 s: "We have emailed your download link"
+```
+
+Checkout errors: `product_sold_out` (409), `product_email_invalid` (400), `product_email_blocked` (403), `product_amount_below_minimum` (400, `details.minimumCents`), `product_amount_invalid` (400), `product_answers_invalid` (400, `details.questionId`), `stripe_not_connected` (409), `rate_limited` (429), `rate_limit_unavailable` (503); `getCheckout` with an unknown session is `product_checkout_not_found`.
+
+## Download page and the shared-link check
+
+The token is the buyer's credential: `no-store`, `noindex`, and never in analytics, sitemaps or cache keys. The buyer's first open and a signed-in buyer pass; a forwarded link gets `purchase_email_confirmation_required` (403). A server-side frontend never forwards the API's confirmation cookie, so keep the returned `confirmationToken` in your own per-purchase cookie and pass it back as the `confirmationToken` option (sent as `PURCHASE_CONFIRMATION_HEADER`).
+
+```ts snippet
+import { isBoardApiError } from '@cavuno/board';
+
+try {
+  const purchase = await board.purchases.get(token, {
+    confirmationToken,
+    cache: 'no-store',
+  });
+  if (purchase.confirmationToken) saveConfirmation(purchase.confirmationToken);
+} catch (error) {
+  if (
+    isBoardApiError(error) &&
+    error.code === 'purchase_email_confirmation_required'
+  ) {
+    renderEmailPrompt(); // then:
+    const confirmation = await board.purchases.confirmEmail(token, {
+      email: typedEmail,
+    }); // purchase_email_mismatch (403) on a wrong email
+    saveConfirmation(confirmation.confirmationToken);
+  } else throw error;
+}
+```
+
+`purchase.files` holds files (`state`: `ready`, `preparing`, `limit_reached`; `downloadsLeft`, `sizeBytes`, `pageCount`, `stamped`) and links (`url`, opened directly). Also `downloadCap`, `stamping`, `receiptUrl` (null for free), `refundPolicy`, `ratingsEnabled` and the buyer's own `review`.
+
+## Downloads
+
+Each call counts a download, so trigger it from a button, then redirect to the short-lived signed `url` at once.
+
+```ts snippet
+const { url } = await board.purchases.download(token, fileId, {
+  confirmationToken,
+});
+const zip = await board.purchases.downloadAll(token, { confirmationToken });
+// zip.preparing / zip.limitReached: file ids left out of the ZIP
+```
+
+`purchase_file_preparing` (409): the stamped PDF is being made, nothing counted, the buyer is emailed when ready. `purchase_download_limit_reached` (409): permanent until the board resets it; never retry it as a rate limit. `purchase_download_all_unavailable` (503): offer single files. Also `purchase_awaiting_payment` (409), `purchase_access_removed` (410), `purchase_unavailable` (410), `purchase_file_not_found` and `purchases_not_found` (404). Purchase-token routes ignore the board password and plan gates.
+
+## Reviews, resend and the library
+
+```ts snippet
+await board.purchases.review(
+  token,
+  { stars: 5, comment: 'Exactly what I needed' }, // displayName optional
+  { confirmationToken });
+
+await board.purchases.resend({
+  email: 'ada@example.com',
+  productSlug: 'salary-guide',
+  website: '',
+}); // always 202: never reveals whether a purchase exists
+
+const { data: mine } = await board.purchases.mine({ cache: 'no-store' });
+```
+
+`review` replaces the buyer's earlier review; `product_reviews_disabled` (404) when ratings are off, `purchase_refunded` (409), `purchase_review_invalid` (400). `mine` needs a board user session and lists purchases made while signed in plus those made with the user's verified email, each with `downloadUrl`.
+
+## Completion gate
+
+- The list shows listed products only; a link-only product page renders with `noindex`.
+- A free claim redirects to `downloadUrl`; a paid test checkout mounts, returns with `session_id`, and `getCheckout` reaches `paid`.
+- A forwarded download link asks for the email, and the confirmation survives a reload through your own cookie.
+- Downloads start from a button; `purchase_download_limit_reached` disables the button instead of retrying.
+- Download pages, checkout status and `mine()` are `no-store`; purchase paths never reach analytics or the sitemap.
+
+## Cavuno SDK reference
+
+For setup and API details beyond this workflow, use the [Cavuno Board SDK documentation](https://cavuno.com/docs/sdk/build-your-board/digital-products).

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

@@ -64,6 +64,7 @@ Route each enabled capability to its focused skill:
 | Saved jobs and applications | `cavuno-board-applications` |
 | Messaging | `cavuno-board-messaging` |
 | Candidate paywall | `cavuno-board-paywall` |
+| Digital products | `cavuno-board-products` |
 | Employer talent access | `cavuno-board-talent-access` |
 | Public job posting | `cavuno-board-post-a-job` |
 | Localized chrome | `cavuno-board-i18n` |

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

@@ -132,8 +132,12 @@ it):
 
 - Taxonomy and location pages enter the sitemap at five distinct jobs,
   `MIN_JOBS_PER_INDEXED_PAGE`.
-- Marketing URLs follow context feature flags for impressum, talent directory,
-  and employers. Blog is listed only when `features.blog` is enabled.
+- Marketing URLs follow context feature flags for talent directory and
+  employers. Blog is listed only when `features.blog` is enabled.
+- `/impressum` follows the board unless you pass the `impressum` option
+  (`buildBucketEntries(board, origin, bucket, { impressum })`). Pass it when
+  your site owns its Impressum content, so the sitemap lists `/impressum`
+  exactly when the page exists. `features.impressum` is deprecated.
 - Salary index reads use `context().language`, producing board-language
   canonical salary slugs. Job, company, market, and blog slugs arrive
   canonical on the wire.

package/skills/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.57.0",
+  "version": "4.59.0",
   "skills": [
     {
       "name": "cavuno-board-account",
@@ -113,6 +113,13 @@
       "framework": null,
       "category": "core"
     },
+    {
+      "name": "cavuno-board-products",
+      "description": "Digital product storefront with @cavuno/board. Use for product lists and pages, reviews, free claims, embedded paid checkout, the purchase download page with its email confirmation, downloads, buyer reviews, resending the link, or the signed-in buyer's purchases.",
+      "path": "skills/cavuno-board-products/SKILL.md",
+      "framework": null,
+      "category": "core"
+    },
     {
       "name": "cavuno-board-salaries",
       "description": "Salary read models with @cavuno/board. Use for title, skill, or location salary indexes and detail, cross-axis pages, or the salary companies hub.",