@cavuno/board 4.8.0 → 4.10.0

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

@@ -137,7 +137,9 @@ if (data.length === 0 && (skills.data.length === 0 || resume.parseStatus !== 'pa
 Authenticated settings expose `messageEmails`, `applicationEmails`, and
 `recommendedJobEmails`. The first two default subscribed when no stored
 preference exists; recommendation email is explicit opt-in and defaults
-unsubscribed. Updating one channel returns the full set.
+unsubscribed. Each preference includes additive `waitlisted`. Updating
+one channel returns the full set. A subscribe at the Email subscribers
+cap waitlists instead of failing.
 
 ```ts snippet
 const preferences = await board.me.notificationPreferences.retrieve();

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

@@ -67,7 +67,9 @@ application's copy (message catalog or hard-coded board language).
 
 Category and skill collections contain terms backed by published jobs. Each
 term already carries a board-language `displayName`, immutable English
-`sourceSlug` for filtering, and board-language `canonicalSlug` for links.
+`sourceSlug` for filtering, board-language `canonicalSlug` for links, and
+a live `jobCount` (published jobs on the board — not a tally of the current
+list page).
 
 ```ts snippet
 const categories = await board.taxonomy.categories.list({ limit: 50 });
@@ -77,11 +79,23 @@ const categoryOptions = categories.data.map((term) => ({
   label: term.displayName,
   filterValue: term.sourceSlug,
   href: `/jobs/${term.canonicalSlug}`,
+  jobCount: term.jobCount,
 }));
 ```
 
-Category and skill lists accept `q`, `limit` (1–100), and opaque `cursor`.
-Pass `nextCursor` unchanged to the next request.
+For homepage "browse by category" tiles, ask for the busiest terms rather
+than the first page of the name-sorted collection:
+
+```ts snippet
+const top = await board.taxonomy.categories.list({
+  limit: 8,
+  sort: 'jobCount',
+});
+```
+
+Category and skill lists accept `q`, `limit` (1–100), `sort` (`name` or
+`jobCount`), and opaque `cursor`. Pass `nextCursor` unchanged to the next
+request. The cursor is bound to `q`, `limit`, and `sort`.
 
 ```ts snippet
 const first = await board.taxonomy.categories.list({ limit: 50 });

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` |
+| Employer talent access | `cavuno-board-talent-access` |
 | Public job posting | `cavuno-board-post-a-job` |
 | Localized chrome | `cavuno-board-i18n` |
 | Metadata and structured data | `cavuno-board-seo` |

package/skills/cavuno-board-talent-access/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: cavuno-board-talent-access
+description: Employer talent-access paywall with @cavuno/board. Use for charging models, remaining credits, per-candidate unlock gates, embedded checkout, in-place upgrades, or the company billing portal.
+---
+
+# Employer talent-access paywall
+
+Operators sell access to the candidate directory: profile-unlock credits and/or first-message credits. Credits are company-scoped. This is a different buyer from the candidate job-access paywall (`board.me.access.*`, skill `cavuno-board-paywall`).
+
+Two charging models (from `retrieve().accessModel`):
+
+- `paid_messaging` — full profiles; a first cold message spends a message credit.
+- `paid_unlocks_and_messaging` — directory cards redact; opaque `/p/{id}` requires an unlock credit; messaging stays credit-gated.
+
+When no public `talent_access` plan exists, `accessModel` is `none` and the paywall is inert.
+
+## Read the CTA and remaining credits
+
+`board.me.talentAccess.retrieve()` is the gating signal for a Message-vs-upsell CTA. Never cache it.
+
+```ts snippet
+const access = await board.me.talentAccess.retrieve();
+access.hasTalentAccess;
+access.accessModel;
+access.unlockCreditsRemaining;
+access.messageCreditsRemaining;
+access.hasUnlimitedUnlocks;
+access.hasUnlimitedMessages;
+access.companyId;
+```
+
+`companyId` is set when the viewer has exactly one approved membership. It is `null` when they have none or more than one — pass `companyId` on writes or the API returns `company_required`.
+
+## Gate one candidate
+
+Per-candidate already-unlocked state is a sibling read so the singleton never takes a candidate id.
+
+```ts snippet
+const gate = await board.me.talentAccess.retrieveCandidate('bu_candidate');
+if (!gate.alreadyUnlocked && !gate.hasUnlimitedUnlocks) {
+  renderUnlockCta(gate.unlockCreditsRemaining);
+}
+```
+
+## Mint and mount checkout
+
+`checkout` requires a signed-in approved employer and returns a mount kit. `returnPath` is relative; session metadata is `origin: talent_access`. Public talent plans come from `board.plans.list({ purpose: 'talent_access' })`.
+
+```ts snippet
+import { loadStripe } from '@stripe/stripe-js';
+
+const kit = await board.me.talentAccess.checkout({
+  planId: 'plan_1',
+  returnPath: '/employers',
+  colorMode: 'light',
+});
+
+const stripe = await loadStripe(kit.publishableKey, {
+  stripeAccount: kit.stripeAccountId,
+});
+```
+
+The kit contains `sessionId`, `clientSecret`, `stripeAccountId`, `publishableKey`, and `offerType`. The host owns Stripe.js and embedded-checkout mounting. Gate failures use `talent_access_unavailable`, `company_required`, and `stripe_not_connected`; handle them with `cavuno-board-errors`.
+
+## Confirm from remaining credits
+
+`retrieveCheckout` reports `open`, `complete`, or `expired`. Open sessions are remountable with their `clientSecret`; expired sessions require a new checkout. After completion, poll `retrieve()` because webhook delivery is asynchronous.
+
+```ts snippet
+const checkout = await board.me.talentAccess.retrieveCheckout(kit.sessionId);
+
+if (checkout.status === 'complete') {
+  let access = await board.me.talentAccess.retrieve();
+  for (let poll = 0; !access.hasTalentAccess && poll < 10; poll++) {
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    access = await board.me.talentAccess.retrieve();
+  }
+  if (access.hasTalentAccess) renderUnlockedDirectory();
+  else renderPendingAccess();
+}
+```
+
+## Spend an unlock
+
+Unlock is idempotent: a second call for the same company/candidate pair returns `alreadyUnlocked: true` with no decrement.
+
+```ts snippet
+const unlock = await board.me.talentAccess.unlock({
+  candidateId: 'bu_candidate',
+});
+if (unlock.alreadyUnlocked) renderProfile();
+else renderProfile(unlock.unlockCreditsRemaining);
+```
+
+`talent_access_required` means no plan or no remaining unlock credits.
+
+## Upgrade in place
+
+Out-of-credits plan changes call `upgrade`, never a second checkout. Checkout would mint a parallel subscription.
+
+```ts snippet
+await board.me.talentAccess.upgrade({ planId: 'plan_pro' });
+```
+
+`already_on_plan` means the company already holds that plan. `talent_access_required` means there is no current talent_access subscription to swap.
+
+## Open the company billing portal
+
+Job-posting and talent-access subscriptions share one Stripe customer per company. There is no `me.talentAccess.portal`.
+
+```ts snippet
+const { url } = await board.me.companies.billingPortal.create('acme', {
+  returnPath: '/employers/billing',
+});
+location.href = url;
+```
+
+## Message credits spend on start
+
+There is no separate message-credit spend endpoint. The composer gates on `hasTalentAccess` and remaining message credits; `conversations.start` still 403s `messaging_talent_access_required` on a cold send without credit.
+
+```ts snippet
+await board.me.conversations.start({
+  candidateBoardUserId: 'bu_candidate',
+  body: 'Hi, your profile looks like a great fit.',
+});
+```
+
+## Named vs opaque profile routes
+
+Named `/p/{handle}` is the share bypass and always shows a full `public` profile. Opaque `/p/{id}` is the unlock-gated route. When `accessModel === 'paid_unlocks_and_messaging'`, directory cards redact for viewers who are not unlimited.
+
+```ts snippet
+const named = await board.talent.retrieve('jane-doe');
+const opaque = await board.talent.retrieve('bu_candidate');
+```
+
+## Completion gate
+
+- `retrieve()` drives the Message-vs-upsell CTA and remaining-credit hints.
+- Opaque `/p/{id}` uses `retrieveCandidate` then `unlock`; named `/p/{handle}` does not.
+- Checkout reaches `complete`, then bounded `retrieve()` polling reaches `hasTalentAccess: true`.
+- `upgrade` is the out-of-credits plan swap; never a second checkout session.
+- Billing management uses `me.companies.billingPortal.create`, not a talent-access portal.
+- First-message spend stays on `conversations.start`.
+
+## Cavuno SDK reference
+
+For setup and API details beyond this workflow, use the [Cavuno Board SDK documentation](https://cavuno.com/docs/sdk).

package/skills/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.8.0",
+  "version": "4.10.0",
   "skills": [
     {
       "name": "cavuno-board-account",
@@ -154,6 +154,13 @@
       "path": "skills/cavuno-board-smoke-test/SKILL.md",
       "framework": null,
       "category": "core"
+    },
+    {
+      "name": "cavuno-board-talent-access",
+      "description": "Employer talent-access paywall with @cavuno/board. Use for charging models, remaining credits, per-candidate unlock gates, embedded checkout, in-place upgrades, or the company billing portal.",
+      "path": "skills/cavuno-board-talent-access/SKILL.md",
+      "framework": null,
+      "category": "core"
     }
   ]
 }