@cavuno/board 4.64.0 → 4.66.0

package/dist/skills.js

@@ -27,7 +27,7 @@ __export(skills_exports, {
 });
 module.exports = __toCommonJS(skills_exports);
 
-// node_modules/.pnpm/tsup@8.5.1_postcss@8.5.22_tsx@4.23.1_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js
+// node_modules/.pnpm/tsup@8.5.1_postcss@8.5.32_tsx@4.23.1_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js
 var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
 var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
 

package/dist/suggest.d.mts

@@ -1,5 +1,5 @@
-import { h as SuggestionItem, b as SearchSuggestQuery, F as FetchOptions, g as SuggestResult } from './search-BtrwcLkc.mjs';
-import './_spec-D1Qg_Twd.mjs';
+import { h as SuggestionItem, b as SearchSuggestQuery, F as FetchOptions, g as SuggestResult } from './search-CrXCM8Hq.mjs';
+import './_spec-DBI6azWs.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-DZeNdYN6.js';
-import './_spec-D1Qg_Twd.js';
+import { h as SuggestionItem, b as SearchSuggestQuery, F as FetchOptions, g as SuggestResult } from './search-DPHLf8pI.js';
+import './_spec-DBI6azWs.js';
 
 /**
  * `@cavuno/board/suggest` — framework-agnostic headless search-suggest

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cavuno/board",
-  "version": "4.64.0",
+  "version": "4.66.0",
   "description": "Build custom job boards and careers pages with Cavuno’s TypeScript SDK.",
   "keywords": [
     "api-client",
@@ -134,6 +134,16 @@
         "default": "./dist/go.js"
       }
     },
+    "./mcp": {
+      "import": {
+        "types": "./dist/mcp.d.mts",
+        "default": "./dist/mcp.mjs"
+      },
+      "require": {
+        "types": "./dist/mcp.d.ts",
+        "default": "./dist/mcp.js"
+      }
+    },
     "./route-contract": {
       "import": {
         "types": "./dist/route-contract.d.mts",
@@ -240,7 +250,8 @@
     "publint": "^0.3.12",
     "tsup": "^8.4.0",
     "tsx": "^4.19.2",
-    "vitest": "^2.1.9",
+    "vite": "^8.3.6",
+    "vitest": "^5.1.0",
     "typescript": "^5.9.3",
     "@typescript/native-preview": "7.0.0-dev.20260707.2"
   },

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

@@ -112,18 +112,26 @@ const categoryOptions = categories.data.map((term) => ({
 }));
 ```
 
-For homepage "browse by category" tiles, ask for the busiest terms rather
-than the first page of the name-sorted collection:
+Categories also carry `totalJobCount`: published jobs on the category or
+any subcategory, each job once. A parent category page lists its
+subcategories' jobs, so show `totalJobCount` next to category links. A parent
+whose jobs all sit in subcategories has `jobCount` 0 and is still listed.
+
+For homepage "browse by category" tiles, ask for the busiest top-level
+categories rather than the first page of the name-sorted collection:
 
 ```ts snippet
 const top = await board.taxonomy.categories.list({
+  topLevel: true,
   limit: 8,
-  sort: 'jobCount',
+  sort: 'totalJobCount',
 });
 ```
 
 Category and skill lists accept `q`, `limit` (1–100), `sort` (`name` or
-`jobCount`), and opaque `cursor`. Pass `nextCursor` unchanged to the next
+`jobCount`; categories also `totalJobCount`), and opaque `cursor`. With
+`sort: 'jobCount'` and no `q` or `topLevel`, a parent with no jobs of its own
+is left out; `totalJobCount` includes it. Pass `nextCursor` unchanged to the next
 request. The cursor is bound to `q`, `limit`, and `sort`.
 
 ```ts snippet

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

@@ -0,0 +1,80 @@
+---
+name: cavuno-board-mcp
+description: Serve the board's public MCP server at /mcp with @cavuno/board/mcp. Use when connecting a self-hosted board to Claude, ChatGPT, Cursor or another MCP client, or when /mcp or /mcp/docs returns 404 on the board's host.
+---
+
+# Board MCP server
+
+Every paid Cavuno board has a public, read-only MCP server: AI assistants can
+search its jobs, read job and company pages, and look up salaries. Boards that
+Cavuno hosts serve it at `/mcp` on their own domain already. A self-hosted
+board serves it by mounting `createMcpHandler` from `@cavuno/board/mcp`, which
+forwards to the Board API, so the tools, limits and setup page match every
+other Cavuno board.
+
+## Mount the handler
+
+Mount one handler at `/mcp`, `/mcp/*` and `/.well-known/ai-catalog.json`, for
+GET, HEAD and POST. Pass
+the board's publishable key: job and company links in tool results then point
+at the key's own origin.
+
+```ts snippet
+import { createMcpHandler } from '@cavuno/board/mcp';
+
+// app/mcp/[[...path]]/route.ts, and the same lines in
+// app/.well-known/ai-catalog.json/route.ts
+const handler = createMcpHandler({
+  board: process.env.NEXT_PUBLIC_CAVUNO_BOARD_KEY!,
+});
+export const GET = handler;
+export const HEAD = handler;
+export const POST = handler;
+```
+
+Other frameworks mount the same `(request: Request) => Promise<Response>`
+function on each path. Do not add authentication, cookies or caching in front
+of `/mcp`: every tool is an anonymous read, and MCP clients POST without
+credentials.
+
+## What each path answers
+
+- `POST /mcp`: the stateless Streamable HTTP transport.
+- `GET /mcp` from a browser: a redirect to `/mcp/docs`. Any other non-POST
+  request answers 405.
+- `GET /mcp/docs`: an HTML page listing the tools and how to add the server
+  to each assistant. Use this URL as the documentation link in a Claude or
+  ChatGPT directory submission.
+- `GET /mcp/server-card`: the MCP Server Card, the server's name, version,
+  title, icons and URL as `application/mcp-server-card+json`, for an
+  assistant to read before it connects.
+- `GET /.well-known/ai-catalog.json`: the AI Catalog, which lists the Server
+  Card so an assistant that knows only the board's domain can find the server.
+
+A free-plan board, a password-protected board, or a board whose operator has
+switched the server off answers 404 on every path.
+
+## Limits
+
+The Board API allows 1,000 MCP requests a minute per visitor address. Requests
+forwarded from a self-hosted server arrive from that server's address, so the
+limit applies to the board's MCP traffic as a whole. Over the limit, `/mcp`
+answers 429 with `Retry-After`.
+
+## Completion gate
+
+Finish only after every check passes against the deployed board:
+
+- `POST /mcp` with `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`,
+  `Content-Type: application/json` and
+  `Accept: application/json, text/event-stream` returns the tool list.
+- Opening `/mcp` in a browser lands on `/mcp/docs`, and that page names the
+  board and shows `https://<board-host>/mcp` as the server URL.
+- `GET /.well-known/ai-catalog.json` returns an entry whose `url` is
+  `https://<board-host>/mcp/server-card`, and that card's `remotes` URL is
+  `https://<board-host>/mcp`.
+- A job URL in a `search_jobs` result opens on the board's own host.
+
+## Cavuno SDK reference
+
+For setup and API details beyond this workflow, use the [Cavuno Board SDK documentation](https://cavuno.com/docs/sdk).

package/skills/cavuno-board-post-a-job/SKILL.md

@@ -5,7 +5,7 @@ description: Post a job publicly with @cavuno/board. Use for plan selection, log
 
 # Status-first job posting
 
-The public posting funnel is anonymous and rate-limited. Its invariant is status-first handling: `board.jobPosting.create` returns one of four success states, and the host follows that state. Rejected submissions throw `BoardApiError` instead.
+The public posting funnel is anonymous and rate-limited. Its invariant is status-first handling: `board.jobPosting.create` returns one of its success states, and the host follows that state. Rejected submissions throw `BoardApiError` instead.
 
 Employer dashboard job management belongs to `board.me.companies.jobs.*`. Candidate access payments belong to `cavuno-board-paywall`.
 
@@ -160,11 +160,59 @@ switch (result.status) {
 
 The mapping is:
 
-- paid Stripe plan → `checkout`;
+- paid Stripe plan → `checkout`, or `embedded_checkout` when you send `checkoutUiMode: 'embedded_page'`;
 - free or credited posting → `published`, or `pending_approval` on moderated boards;
 - invoice plan → `invoice_sent`.
 
-The checkout value is a URL for a host-owned full-page redirect. Payment publication happens by webhook; the SDK exposes no Stripe integration or publish-confirm method.
+`checkoutUrl` is a URL for a host-owned full-page redirect. Payment publication happens by webhook; the SDK exposes no Stripe integration or publish-confirm method.
+
+## Embedded checkout
+
+To keep the poster on your page, send `checkoutUiMode: 'embedded_page'`. A paid plan then returns `embedded_checkout` with everything Stripe.js needs. Load Stripe.js from `js.stripe.com` yourself; the SDK never bundles it.
+
+```ts no-check
+const result = await board.jobPosting.create({
+  submission,
+  checkoutUiMode: 'embedded_page',
+});
+
+if (result.status === 'embedded_checkout') {
+  const stripe = await loadStripe(result.publishableKey, {
+    stripeAccount: result.stripeAccountId,
+  });
+  const checkout = await stripe.initEmbeddedCheckout({
+    clientSecret: result.clientSecret,
+    onComplete: () => showPaid(result.sessionId),
+  });
+  checkout.mount('#checkout');
+}
+```
+
+Cards finish in place and fire `onComplete`. Payment methods that need a redirect still return to the board's `/post/success`, so that page must exist in both modes.
+
+## Checkout outcome
+
+After either checkout, read what happened with the session id: `sessionId` from `embedded_checkout`, or `session_id` on the `/post/success` return URL. `awaiting_payment` lasts until the payment webhook lands, so poll briefly. `processing` means a bank payment is still clearing and can take days; `payment_failed` means it failed. `jobStatus` and `jobUrl` say whether the job is live.
+
+```ts snippet
+const outcome = await board.jobPosting.getCheckout(sessionId);
+
+switch (outcome.status) {
+  case 'paid':
+    if (outcome.jobUrl) linkToJob(outcome.jobUrl);
+    break;
+  case 'processing':
+    showPaymentProcessing(outcome.jobTitle);
+    break;
+  case 'awaiting_payment':
+    retrySoon();
+    break;
+  case 'payment_failed':
+  case 'canceled':
+    offerToPostAgain();
+    break;
+}
+```
 
 ## Verified existing credit
 
@@ -200,8 +248,9 @@ Bare-email billing lookup is intentionally absent because it would expose whethe
 ## Completion gate
 
 - The form renders `forms.job` in order: hidden entries are absent, required and locked entries block submit while empty, and an unknown built-in key is skipped.
-- Every `create` call handles all four statuses.
-- Paid checkout redirects through `checkoutUrl`; the job appears only after webhook completion.
+- Every `create` call handles every status it can return (`embedded_checkout` only with `checkoutUiMode: 'embedded_page'`).
+- Paid checkout redirects through `checkoutUrl` or mounts `clientSecret`; the job appears only after webhook completion.
+- The return page reads `getCheckout(sessionId)` and tells `paid` from `processing`.
 - Free unmoderated submission returns a resolving `jobSlug`.
 - Missing domain logos leave submission usable without `logoUrl`.
 - Existing credit is selectable only after token verification.

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

@@ -10,17 +10,19 @@ import {
 
 const { name } = await board.context();
 const post = await board.blog.posts.retrieve('hello-world');
+const [firstAuthor] = post.authors;
 const article = createBlogArticleJsonLd({
   post,
   boardName: name,
   permalink: `https://jobs.example.com/blog/${post.slug}`,
   ogImageUrl: `https://jobs.example.com/blog/${post.slug}/og`,
+  authorProfileUrl: firstAuthor
+    ? `https://jobs.example.com/blog/author/${firstAuthor.slug}`
+    : null,
 });
 
 const author = await board.blog.authors.retrieve('jane');
-const { data: authorPosts } = await board.blog.posts.list({
-  authorSlug: 'jane',
-});
+const authorPosts = await board.blog.posts.list({ authorSlug: 'jane' });
 // Profile description is application-owned. Prefer author.bio; otherwise
 // compose from the board catalog (shape only — not an English sentence).
 const profile = createAuthorProfileJsonLd({
@@ -29,14 +31,17 @@ const profile = createAuthorProfileJsonLd({
   description:
     author.bio ?? messages.authorProfileDescription({ name: author.name }),
   origin: 'https://jobs.example.com',
-  posts: authorPosts,
-  totalPosts: authorPosts.length,
+  posts: authorPosts.data,
+  // The author's total, not this page's length.
+  totalPosts: authorPosts.count ?? authorPosts.data.length,
 });
 ```
 
-The article `ogImageUrl` is the fallback when the post has no cover. Supply
-author posts newest-first; the profile builder keeps the first five as
-`hasPart`.
+The article `ogImageUrl` is the fallback when the post has no cover. Pass
+`authorProfileUrl` as the same URL you give the profile's `canonical`, so the
+post's author and the profile's `Person` share one `@id`. Supply author posts
+newest-first; the profile builder keeps the first five as `hasPart`. The list's
+`count` is the author's total published posts; `data` is one page.
 
 This branch is complete when the post emits an `Article`, the author emits a
 `ProfilePage`, every URL is absolute and canonical, and a null builder result

package/skills/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.64.0",
+  "version": "4.66.0",
   "skills": [
     {
       "name": "cavuno-board-account",
@@ -92,6 +92,13 @@
       "framework": null,
       "category": "core"
     },
+    {
+      "name": "cavuno-board-mcp",
+      "description": "Serve the board's public MCP server at /mcp with @cavuno/board/mcp. Use when connecting a self-hosted board to Claude, ChatGPT, Cursor or another MCP client, or when /mcp or /mcp/docs returns 404 on the board's host.",
+      "path": "skills/cavuno-board-mcp/SKILL.md",
+      "framework": null,
+      "category": "core"
+    },
     {
       "name": "cavuno-board-messaging",
       "description": "Polled messaging contract with @cavuno/board. Use for inboxes, unread badges, threads, read receipts, message moderation, or user blocks.",