@cavuno/board 4.68.0 → 4.70.0

package/dist/index.js

@@ -81,6 +81,7 @@ var BOARD_API_ERROR_CODES = [
   // Board-user auth
   "board_auth_account_not_found",
   "board_auth_email_taken",
+  "board_auth_email_undeliverable",
   "board_auth_invalid_credentials",
   "board_auth_invalid_token",
   "board_auth_registration_disabled",
@@ -199,6 +200,8 @@ var BOARD_API_ERROR_CODES = [
   "employer_not_member",
   "employer_payment_required",
   "employer_pipeline_stage_not_found",
+  "company_custom_field_not_found",
+  "company_custom_field_not_editable",
   "employer_member_not_found",
   "employer_invite_not_found",
   "not_company_admin",
@@ -446,7 +449,7 @@ async function clearSession(storage) {
 }
 
 // src/version.ts
-var SDK_VERSION = "4.68.0";
+var SDK_VERSION = "4.70.0";
 
 // src/client.ts
 function isRawBody(body) {
@@ -2262,7 +2265,10 @@ function meNamespace(client) {
           { ...options, method: "PATCH", body }
         );
       },
-      /** Retrieve profile custom fields for a company I belong to. */
+      /**
+       * Retrieve profile custom fields for a company I belong to, with the
+       * saved files of upload fields (`customFieldMedia`).
+       */
       retrieveCustomFields(slug, options) {
         return client.fetch(
           `/me/companies/${encodeURIComponent(slug)}/custom-fields`,
@@ -2276,6 +2282,26 @@ function meNamespace(client) {
           { ...options, method: "PATCH", body }
         );
       },
+      /**
+       * Upload one file to an owner-editable `image_gallery` or `file` field
+       * of a company I belong to (up to 10 MB; galleries take JPEG, PNG, WebP
+       * or GIF). The file is a draft until its `id` is saved to the field with
+       * `updateCustomFields`, as the ordered list of file IDs.
+       *
+       * @example
+       * const image = await board.me.companies.uploadCustomFieldFile('acme', 'office_photos', file);
+       * await board.me.companies.updateCustomFields('acme', {
+       *   values: { office_photos: [...savedIds, image.id] },
+       * });
+       */
+      uploadCustomFieldFile(slug, fieldKey, file, options) {
+        const form = new FormData();
+        form.append("file", file);
+        return client.fetch(
+          `/me/companies/${encodeURIComponent(slug)}/custom-fields/${encodeURIComponent(fieldKey)}/files`,
+          { ...options, method: "POST", body: form }
+        );
+      },
       /**
        * Delete a company I admin (soft-delete cascade + Forager
        * exclusion). Resolves void on success (204).
@@ -2358,11 +2384,17 @@ function meNamespace(client) {
        * membership on this board; 409 `membership_seat_taken` when the company
        * already holds one (or has an invoice pending).
        *
+       * By default every completed checkout redirects to `returnPath`. Pass
+       * `redirectOnCompletion: 'if_required'` to keep a card buyer on the page:
+       * Stripe.js calls `onComplete` instead, and only a payment method that
+       * needs a redirect returns to `returnPath`.
+       *
        * @example
        * const kit = await board.me.companies.startMembershipCheckout('acme', {
        *   planId,
        *   returnPath: '/memberships',
        *   colorMode: 'light',
+       *   redirectOnCompletion: 'if_required',
        * });
        */
       startMembershipCheckout(slug, body, options) {
@@ -2647,7 +2679,9 @@ function meNamespace(client) {
        * My reusable billing options for a company — active subscription slots +
        * remaining pre-purchased (bundle) order slots, the options a held draft
        * can be published with at no new charge (the checkout `billing.type:
-       * 'order' | 'subscription'`).
+       * 'order' | 'subscription'`). `capabilities` says whether the company
+       * can post at all (`canPost`), so a form can show a members-only gate
+       * before the job is written.
        */
       billingOptions: {
         /**
@@ -4794,6 +4828,29 @@ function createBoardClient(options) {
     seo(options2) {
       return client.fetch("/seo", options2);
     },
+    /**
+     * Sign an address up for the board's email from a newsletter form. Sends
+     * a confirmation email; nothing is granted until the person clicks it.
+     * Always resolves `{ status: 'submitted', sendingPaused }`. Limited to 3
+     * a minute per address and 10 requests a minute per IP; on a builder
+     * site Cavuno hosts the IP limit counts each visitor, plus 6 sign-ups a
+     * minute per visitor (429 `rate_limited`).
+     *
+     * @example
+     * await board.subscribe({
+     *   email,
+     *   consent: true,
+     *   consentText: 'Send me news and offers from Acme Jobs.',
+     *   source: 'blog-footer',
+     * });
+     */
+    subscribe(input, options2) {
+      return client.fetch("/subscribe", {
+        ...options2,
+        method: "POST",
+        body: input
+      });
+    },
     jobs: jobsNamespace(client),
     embed: embedNamespace(client),
     companies: companiesNamespace(client),

package/dist/index.mjs

@@ -28,7 +28,7 @@ import {
   isSsoRequired,
   isUnauthorized,
   isValidationError
-} from "./chunk-ZA5TZ6UH.mjs";
+} from "./chunk-UIKN2ERI.mjs";
 
 // src/query.ts
 function toSearchParams(query) {
@@ -49,7 +49,7 @@ function toSearchParams(query) {
 }
 
 // src/version.ts
-var SDK_VERSION = "4.68.0";
+var SDK_VERSION = "4.70.0";
 
 // src/client.ts
 function isRawBody(body) {
@@ -1862,7 +1862,10 @@ function meNamespace(client) {
           { ...options, method: "PATCH", body }
         );
       },
-      /** Retrieve profile custom fields for a company I belong to. */
+      /**
+       * Retrieve profile custom fields for a company I belong to, with the
+       * saved files of upload fields (`customFieldMedia`).
+       */
       retrieveCustomFields(slug, options) {
         return client.fetch(
           `/me/companies/${encodeURIComponent(slug)}/custom-fields`,
@@ -1876,6 +1879,26 @@ function meNamespace(client) {
           { ...options, method: "PATCH", body }
         );
       },
+      /**
+       * Upload one file to an owner-editable `image_gallery` or `file` field
+       * of a company I belong to (up to 10 MB; galleries take JPEG, PNG, WebP
+       * or GIF). The file is a draft until its `id` is saved to the field with
+       * `updateCustomFields`, as the ordered list of file IDs.
+       *
+       * @example
+       * const image = await board.me.companies.uploadCustomFieldFile('acme', 'office_photos', file);
+       * await board.me.companies.updateCustomFields('acme', {
+       *   values: { office_photos: [...savedIds, image.id] },
+       * });
+       */
+      uploadCustomFieldFile(slug, fieldKey, file, options) {
+        const form = new FormData();
+        form.append("file", file);
+        return client.fetch(
+          `/me/companies/${encodeURIComponent(slug)}/custom-fields/${encodeURIComponent(fieldKey)}/files`,
+          { ...options, method: "POST", body: form }
+        );
+      },
       /**
        * Delete a company I admin (soft-delete cascade + Forager
        * exclusion). Resolves void on success (204).
@@ -1958,11 +1981,17 @@ function meNamespace(client) {
        * membership on this board; 409 `membership_seat_taken` when the company
        * already holds one (or has an invoice pending).
        *
+       * By default every completed checkout redirects to `returnPath`. Pass
+       * `redirectOnCompletion: 'if_required'` to keep a card buyer on the page:
+       * Stripe.js calls `onComplete` instead, and only a payment method that
+       * needs a redirect returns to `returnPath`.
+       *
        * @example
        * const kit = await board.me.companies.startMembershipCheckout('acme', {
        *   planId,
        *   returnPath: '/memberships',
        *   colorMode: 'light',
+       *   redirectOnCompletion: 'if_required',
        * });
        */
       startMembershipCheckout(slug, body, options) {
@@ -2247,7 +2276,9 @@ function meNamespace(client) {
        * My reusable billing options for a company — active subscription slots +
        * remaining pre-purchased (bundle) order slots, the options a held draft
        * can be published with at no new charge (the checkout `billing.type:
-       * 'order' | 'subscription'`).
+       * 'order' | 'subscription'`). `capabilities` says whether the company
+       * can post at all (`canPost`), so a form can show a members-only gate
+       * before the job is written.
        */
       billingOptions: {
         /**
@@ -4364,6 +4395,29 @@ function createBoardClient(options) {
     seo(options2) {
       return client.fetch("/seo", options2);
     },
+    /**
+     * Sign an address up for the board's email from a newsletter form. Sends
+     * a confirmation email; nothing is granted until the person clicks it.
+     * Always resolves `{ status: 'submitted', sendingPaused }`. Limited to 3
+     * a minute per address and 10 requests a minute per IP; on a builder
+     * site Cavuno hosts the IP limit counts each visitor, plus 6 sign-ups a
+     * minute per visitor (429 `rate_limited`).
+     *
+     * @example
+     * await board.subscribe({
+     *   email,
+     *   consent: true,
+     *   consentText: 'Send me news and offers from Acme Jobs.',
+     *   source: 'blog-footer',
+     * });
+     */
+    subscribe(input, options2) {
+      return client.fetch("/subscribe", {
+        ...options2,
+        method: "POST",
+        body: input
+      });
+    },
     jobs: jobsNamespace(client),
     embed: embedNamespace(client),
     companies: companiesNamespace(client),

package/dist/{jobs-CrGBikhJ.d.mts → jobs-BMRvZlNx.d.mts}

@@ -1,4 +1,4 @@
-import { S as Schemas } from './_spec-t2B6ioRS.mjs';
+import { S as Schemas } from './_spec-Dk7QyuoJ.mjs';
 
 /**
  * Optional pagination metadata returned by Board API list operations.

package/dist/{jobs-D_LjWgIk.d.ts → jobs-BlAsTCQl.d.ts}

@@ -1,4 +1,4 @@
-import { S as Schemas } from './_spec-t2B6ioRS.js';
+import { S as Schemas } from './_spec-Dk7QyuoJ.js';
 
 /**
  * Optional pagination metadata returned by Board API list operations.

package/dist/{search-Yw5qsooq.d.mts → search-BB1TaaLa.d.mts}

@@ -1,4 +1,4 @@
-import { S as Schemas } from './_spec-t2B6ioRS.mjs';
+import { S as Schemas } from './_spec-Dk7QyuoJ.mjs';
 
 type Awaitable<T> = T | Promise<T>;
 /**

package/dist/{search-ClbqUjkA.d.ts → search-CoBeDgYT.d.ts}

@@ -1,4 +1,4 @@
-import { S as Schemas } from './_spec-t2B6ioRS.js';
+import { S as Schemas } from './_spec-Dk7QyuoJ.js';
 
 type Awaitable<T> = T | Promise<T>;
 /**

package/dist/{seo-CY5Vl13y.d.ts → seo-BmqJ_ChV.d.ts}

@@ -1,4 +1,4 @@
-import { S as Schemas } from './_spec-t2B6ioRS.js';
+import { S as Schemas } from './_spec-Dk7QyuoJ.js';
 
 /**
  * The public SEO-infra payload (`board.seo()`) — platform infrastructure a

package/dist/{seo-Bjevxvzd.d.mts → seo-M_8j5vdP.d.mts}

@@ -1,4 +1,4 @@
-import { S as Schemas } from './_spec-t2B6ioRS.mjs';
+import { S as Schemas } from './_spec-Dk7QyuoJ.mjs';
 
 /**
  * The public SEO-infra payload (`board.seo()`) — platform infrastructure a

package/dist/seo-files.d.mts

@@ -1,5 +1,5 @@
-import { B as BoardSeo } from './seo-Bjevxvzd.mjs';
-import './_spec-t2B6ioRS.mjs';
+import { B as BoardSeo } from './seo-M_8j5vdP.mjs';
+import './_spec-Dk7QyuoJ.mjs';
 
 /**
  * `@cavuno/board/seo-files` — platform-owned crawler/identity file bodies

package/dist/seo-files.d.ts

@@ -1,5 +1,5 @@
-import { B as BoardSeo } from './seo-CY5Vl13y.js';
-import './_spec-t2B6ioRS.js';
+import { B as BoardSeo } from './seo-BmqJ_ChV.js';
+import './_spec-Dk7QyuoJ.js';
 
 /**
  * `@cavuno/board/seo-files` — platform-owned crawler/identity file bodies

package/dist/seo.d.mts

@@ -1,9 +1,9 @@
-import { P as PublicBlogPostSummary, B as BlogAuthorEmbed } from './blog-B8UJJza1.mjs';
-import { e as JsonLdObject } from './breadcrumbs-BgBj_AiZ.mjs';
-export { A as ALL_COUNTRY_CODES, B as BreadcrumbItemInput, g as FaqItem, J as JobBreadcrumb, h as JsonLdBoard, N as NumberNotation, i as SENIORITY_ORDER, j as SalaryFaqEntry, k as SalaryJsonLdOptions, l as SalaryOccupationListOptions, b as buildJobBreadcrumbs, m as buildSalaryFaq, o as companyCategorySalaryJsonLd, p as companySalaryJsonLd, q as createBreadcrumbJsonLd, r as createJobPostingJsonLd, s as crossAxisSalaryJsonLd, t as faqJsonLd, c as formatSalaryStat, d as formatSalaryStatRange, u as itemListJsonLd, v as locationSalaryJsonLd, n as normalizeWebsiteUrl, w as skillSalaryJsonLd, x as sortBySeniority, y as titleSalaryJsonLd } from './breadcrumbs-BgBj_AiZ.mjs';
-import './_spec-t2B6ioRS.mjs';
-import './board-8RMVpFBw.mjs';
-import './jobs-CrGBikhJ.mjs';
+import { P as PublicBlogPostSummary, B as BlogAuthorEmbed } from './blog-Oo6YHXSE.mjs';
+import { e as JsonLdObject } from './breadcrumbs-DeIA0RQp.mjs';
+export { A as ALL_COUNTRY_CODES, B as BreadcrumbItemInput, g as FaqItem, J as JobBreadcrumb, h as JsonLdBoard, N as NumberNotation, i as SENIORITY_ORDER, j as SalaryFaqEntry, k as SalaryJsonLdOptions, l as SalaryOccupationListOptions, b as buildJobBreadcrumbs, m as buildSalaryFaq, o as companyCategorySalaryJsonLd, p as companySalaryJsonLd, q as createBreadcrumbJsonLd, r as createJobPostingJsonLd, s as crossAxisSalaryJsonLd, t as faqJsonLd, c as formatSalaryStat, d as formatSalaryStatRange, u as itemListJsonLd, v as locationSalaryJsonLd, n as normalizeWebsiteUrl, w as skillSalaryJsonLd, x as sortBySeniority, y as titleSalaryJsonLd } from './breadcrumbs-DeIA0RQp.mjs';
+import './_spec-Dk7QyuoJ.mjs';
+import './board-DzBYIwKz.mjs';
+import './jobs-BMRvZlNx.mjs';
 
 /**
  * Blog structured data on the `@cavuno/board` wire types, transcribed from

package/dist/seo.d.ts

@@ -1,9 +1,9 @@
-import { P as PublicBlogPostSummary, B as BlogAuthorEmbed } from './blog-W1cBNXyS.js';
-import { e as JsonLdObject } from './breadcrumbs-eV2OQqf6.js';
-export { A as ALL_COUNTRY_CODES, B as BreadcrumbItemInput, g as FaqItem, J as JobBreadcrumb, h as JsonLdBoard, N as NumberNotation, i as SENIORITY_ORDER, j as SalaryFaqEntry, k as SalaryJsonLdOptions, l as SalaryOccupationListOptions, b as buildJobBreadcrumbs, m as buildSalaryFaq, o as companyCategorySalaryJsonLd, p as companySalaryJsonLd, q as createBreadcrumbJsonLd, r as createJobPostingJsonLd, s as crossAxisSalaryJsonLd, t as faqJsonLd, c as formatSalaryStat, d as formatSalaryStatRange, u as itemListJsonLd, v as locationSalaryJsonLd, n as normalizeWebsiteUrl, w as skillSalaryJsonLd, x as sortBySeniority, y as titleSalaryJsonLd } from './breadcrumbs-eV2OQqf6.js';
-import './_spec-t2B6ioRS.js';
-import './board-On_r_ixp.js';
-import './jobs-D_LjWgIk.js';
+import { P as PublicBlogPostSummary, B as BlogAuthorEmbed } from './blog-DfUNkngR.js';
+import { e as JsonLdObject } from './breadcrumbs-CS0nlknq.js';
+export { A as ALL_COUNTRY_CODES, B as BreadcrumbItemInput, g as FaqItem, J as JobBreadcrumb, h as JsonLdBoard, N as NumberNotation, i as SENIORITY_ORDER, j as SalaryFaqEntry, k as SalaryJsonLdOptions, l as SalaryOccupationListOptions, b as buildJobBreadcrumbs, m as buildSalaryFaq, o as companyCategorySalaryJsonLd, p as companySalaryJsonLd, q as createBreadcrumbJsonLd, r as createJobPostingJsonLd, s as crossAxisSalaryJsonLd, t as faqJsonLd, c as formatSalaryStat, d as formatSalaryStatRange, u as itemListJsonLd, v as locationSalaryJsonLd, n as normalizeWebsiteUrl, w as skillSalaryJsonLd, x as sortBySeniority, y as titleSalaryJsonLd } from './breadcrumbs-CS0nlknq.js';
+import './_spec-Dk7QyuoJ.js';
+import './board-CfmGT0yV.js';
+import './jobs-BlAsTCQl.js';
 
 /**
  * Blog structured data on the `@cavuno/board` wire types, transcribed from

package/dist/server.d.mts

@@ -1,10 +1,10 @@
 import { BoardSdk } from './index.mjs';
-import './_spec-t2B6ioRS.mjs';
-import './search-Yw5qsooq.mjs';
-import './jobs-CrGBikhJ.mjs';
-import './board-8RMVpFBw.mjs';
-import './seo-Bjevxvzd.mjs';
-import './blog-B8UJJza1.mjs';
+import './_spec-Dk7QyuoJ.mjs';
+import './search-BB1TaaLa.mjs';
+import './jobs-BMRvZlNx.mjs';
+import './board-DzBYIwKz.mjs';
+import './seo-M_8j5vdP.mjs';
+import './blog-Oo6YHXSE.mjs';
 
 /**
  * Session cookie codec — pure (no framework imports, no node imports) so it

package/dist/server.d.ts

@@ -1,10 +1,10 @@
 import { BoardSdk } from './index.js';
-import './_spec-t2B6ioRS.js';
-import './search-ClbqUjkA.js';
-import './jobs-D_LjWgIk.js';
-import './board-On_r_ixp.js';
-import './seo-CY5Vl13y.js';
-import './blog-W1cBNXyS.js';
+import './_spec-Dk7QyuoJ.js';
+import './search-CoBeDgYT.js';
+import './jobs-BlAsTCQl.js';
+import './board-CfmGT0yV.js';
+import './seo-BmqJ_ChV.js';
+import './blog-DfUNkngR.js';
 
 /**
  * Session cookie codec — pure (no framework imports, no node imports) so it

package/dist/server.mjs

@@ -4,7 +4,7 @@ import {
 } from "./chunk-Z4ALWIGS.mjs";
 import {
   isUnauthorized
-} from "./chunk-ZA5TZ6UH.mjs";
+} from "./chunk-UIKN2ERI.mjs";
 
 // src/server/cookie.ts
 var COOKIE_ATTRIBUTES = "Path=/; HttpOnly; Secure; SameSite=Lax";

package/dist/sitemap.d.mts

@@ -1,10 +1,10 @@
 import { BoardSdk } from './index.mjs';
-import './_spec-t2B6ioRS.mjs';
-import './search-Yw5qsooq.mjs';
-import './jobs-CrGBikhJ.mjs';
-import './board-8RMVpFBw.mjs';
-import './seo-Bjevxvzd.mjs';
-import './blog-B8UJJza1.mjs';
+import './_spec-Dk7QyuoJ.mjs';
+import './search-BB1TaaLa.mjs';
+import './jobs-BMRvZlNx.mjs';
+import './board-DzBYIwKz.mjs';
+import './seo-M_8j5vdP.mjs';
+import './blog-Oo6YHXSE.mjs';
 
 /**
  * Sitemap primitives — the pure XML + bucket-filename logic behind a board

package/dist/sitemap.d.ts

@@ -1,10 +1,10 @@
 import { BoardSdk } from './index.js';
-import './_spec-t2B6ioRS.js';
-import './search-ClbqUjkA.js';
-import './jobs-D_LjWgIk.js';
-import './board-On_r_ixp.js';
-import './seo-CY5Vl13y.js';
-import './blog-W1cBNXyS.js';
+import './_spec-Dk7QyuoJ.js';
+import './search-CoBeDgYT.js';
+import './jobs-BlAsTCQl.js';
+import './board-CfmGT0yV.js';
+import './seo-BmqJ_ChV.js';
+import './blog-DfUNkngR.js';
 
 /**
  * Sitemap primitives — the pure XML + bucket-filename logic behind a board

package/dist/sitemap.mjs

@@ -3,7 +3,7 @@ import {
 } from "./chunk-DLSO6XXY.mjs";
 import {
   isNotFound
-} from "./chunk-ZA5TZ6UH.mjs";
+} from "./chunk-UIKN2ERI.mjs";
 import {
   BOARD_PATHS,
   blogAuthorPath,

package/dist/suggest.d.mts

@@ -1,5 +1,5 @@
-import { h as SuggestionItem, b as SearchSuggestQuery, F as FetchOptions, g as SuggestResult } from './search-Yw5qsooq.mjs';
-import './_spec-t2B6ioRS.mjs';
+import { h as SuggestionItem, b as SearchSuggestQuery, F as FetchOptions, g as SuggestResult } from './search-BB1TaaLa.mjs';
+import './_spec-Dk7QyuoJ.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-ClbqUjkA.js';
-import './_spec-t2B6ioRS.js';
+import { h as SuggestionItem, b as SearchSuggestQuery, F as FetchOptions, g as SuggestResult } from './search-CoBeDgYT.js';
+import './_spec-Dk7QyuoJ.js';
 
 /**
  * `@cavuno/board/suggest` — framework-agnostic headless search-suggest

package/package.json

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

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

@@ -217,6 +217,22 @@ await board.me.profile.updateCustomFields({
 });
 ```
 
+Company members upload to the company's upload fields the same way, with the company slug first. `customFieldMedia` on `board.me.companies.retrieveCustomFields` lists the saved files.
+
+```ts snippet
+const company = await board.me.companies.retrieveCustomFields('acme');
+const photos = Array.isArray(company.values.office_photos)
+  ? company.values.office_photos
+  : [];
+const photo = await board.me.companies.uploadCustomFieldFile(
+  'acme',
+  'office_photos',
+  file);
+await board.me.companies.updateCustomFields('acme', {
+  values: { office_photos: [...photos, photo.id] },
+});
+```
+
 Resume upload starts an asynchronous parse that may populate the profile. Poll within a fixed budget, surface failure, and keep manual editing available if parsing runs long.
 
 ```ts snippet

package/skills/cavuno-board-job-alerts/SKILL.md

@@ -32,14 +32,21 @@ const result = await board.jobAlerts.confirm({ token });
 switch (result.status) {
   case 'confirmed':
   case 'already_confirmed':
+  case 'waitlisted':
   case 'not_found':
     break;
+  case 'unsubscribed':
+    // Show the manage page's resume option; the subscribe form sends this
+    // address no confirmation email.
+    break;
   case 'expired':
     await board.jobAlerts.resendConfirmation({ email });
     break;
 }
 ```
 
+`waitlisted` means the alert is confirmed but the board can't send to more people yet; it starts once a spot opens. `unsubscribed` means the link was sent before the alerts were turned off, so it doesn't turn them back on. Subscribing again with the form sends no confirmation email to that address; the person resumes alerts from the manage link in an alert email (`board.jobAlerts.resubscribe`) or by signing in and creating an alert.
+
 Only `jobFunctions`, `placeSlugs`, and `remoteOptions` filter digest delivery. Seniority and salary fields are stored but do not scope delivery. The supported cadence is `weekly`.
 
 `jobFunctions` are category and skill slugs (the `slug` of a category or skill, such as `engineering` or `media-and-communication`). A digest matches a job when any entry equals one of the job's category or skill slugs. Prefer sending slugs. If you send display names or free-text keywords instead, the server slugifies each one when the alert is saved and matches it against the board's category and skill slugs, their aliases, and their board-language slugs. A display name that does not slugify to one of those (for example, a renamed category) is stored slugified and will not match, so send slugs whenever you have them. Alerts read back from the API therefore always carry slugs, so compare and display them as slugs.

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

@@ -0,0 +1,79 @@
+---
+name: cavuno-board-newsletter
+description: Newsletter sign-up forms with @cavuno/board. Use for an email sign-up for the board's news (footer, blog, landing page), its consent checkbox, the confirmation email, and sendingPaused.
+---
+
+# Newsletter sign-up
+
+`board.subscribe` signs an address up for the board's own email (news, offers, updates). It is separate from job alerts (`board.jobAlerts.subscribe`): use it for a form whose promise is "get our news", not "get matching jobs".
+
+Every sign-up is double opt-in. The person gets a confirmation email, and nothing is sent to them until they click it. The response is the same whether the address is new, waiting to confirm, or already subscribed, so it never tells a visitor who is on the list.
+
+## The form
+
+- An **unticked** checkbox the person must tick. Its wording must name the board, for example "Send me news and offers from Acme Jobs." Send that exact wording as `consentText`; it is kept as the record of what they agreed to, and a `consentText` without the board's name is refused with a 400.
+- A `source` label for the form, such as `blog-footer` or `homepage-hero` (lowercase letters, digits and hyphens). It shows as the person's Source in the board's dashboard, so give each form its own.
+- A hidden `website` field people leave empty. Bots fill it in; the API then answers as usual and does nothing.
+
+Read the board's name from `board.context()` rather than typing it.
+
+```ts snippet
+const { name } = await board.context();
+const consentText = `Send me news and offers from ${name}.`;
+
+const result = await board.subscribe({
+  email,
+  consent: true,
+  consentText,
+  source: 'blog-footer',
+  website: honeypotValue,
+});
+
+if (result.sendingPaused) {
+  // Recorded, but the board's email is paused for now.
+}
+```
+
+`pageUrl` is optional; it defaults to the request's `Referer`. Pass it when the call is made from your server, where the `Referer` is not the visitor's page.
+
+## After submitting
+
+Always show the same message: "Check your inbox to confirm your subscription." Never show "you're already subscribed"; the API deliberately doesn't say.
+
+When `sendingPaused` is `true`, add a short note that emails from the board may be delayed. The sign-up is still recorded.
+
+## Confirmation
+
+The confirmation email links to the board's job alert confirmation page, the same page job alerts use. That page completes the sign-up with `board.jobAlerts.confirm({ token })`; no separate route is needed. `confirmed` and `already_confirmed` mean the person is subscribed, and `not_found` or `expired` mean the link no longer works.
+
+The page serves both kinds of link, so word it by `subscription`. A newsletter link answers `subscription: 'marketing'` and never turns job alerts on, so don't tell that person their job alerts are confirmed:
+
+```ts
+const result = await board.jobAlerts.confirm({ token });
+const subscribed =
+  result.status === 'confirmed' || result.status === 'already_confirmed';
+const message = !subscribed
+  ? 'This link no longer works.'
+  : result.subscription === 'marketing'
+    ? "You're subscribed to our emails."
+    : 'Your job alert is confirmed.';
+```
+
+## Errors
+
+- `validation_bad_request` (400): a field is missing or malformed, `consent` isn't `true`, or `consentText` doesn't name the board.
+- `rate_limited` (429): 3 sign-ups a minute per address across all boards, or 10 requests a minute per IP. A self-hosted site calls from its own server, so all its visitors share that IP limit with every other sign-in and sign-up call from that server; on a builder site Cavuno hosts it counts each visitor separately, plus 6 sign-ups a minute per visitor. `details.retryAfterSeconds` says when to try again.
+- `rate_limit_unavailable` (503): retry shortly.
+
+```ts snippet
+import { BoardApiError } from '@cavuno/board';
+
+try {
+  await board.subscribe({ email, consent: true, consentText, source: 'footer' });
+} catch (error) {
+  if (error instanceof BoardApiError && error.status === 429) {
+    // Ask them to try again in a minute.
+  }
+  throw error;
+}
+```

package/skills/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.68.0",
+  "version": "4.70.0",
   "skills": [
     {
       "name": "cavuno-board-account",
@@ -106,6 +106,13 @@
       "framework": null,
       "category": "core"
     },
+    {
+      "name": "cavuno-board-newsletter",
+      "description": "Newsletter sign-up forms with @cavuno/board. Use for an email sign-up for the board's news (footer, blog, landing page), its consent checkbox, the confirmation email, and sendingPaused.",
+      "path": "skills/cavuno-board-newsletter/SKILL.md",
+      "framework": null,
+      "category": "core"
+    },
     {
       "name": "cavuno-board-paywall",
       "description": "Grant-is-truth candidate paywall with @cavuno/board. Use for offers, gated job counts, embedded checkout handoff, access confirmation, or subscription portal links.",