@cavuno/board 1.2.0 → 1.3.0

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

@@ -0,0 +1,93 @@
+---
+name: cavuno-board-client
+description: Create and configure the @cavuno/board client — baseUrl and the pk_ board identifier, global headers, request/response hooks, per-call FetchOptions caching passthrough, the client.fetch escape hatch, and the rule that keeps one shared instance safe under SSR.
+---
+
+# The Board API client
+
+`createBoardClient` returns a typed client whose namespaces (`jobs`, `companies`, `blog`, `auth`, `me`, …) all route through one request pipeline: board-identifier base path, default headers, bearer token from storage, and your hooks.
+
+## When to use
+
+- Creating the client instance your whole app shares.
+- Adding global headers, logging, request/response hooks, or framework caching.
+- Calling an endpoint the SDK doesn't expose yet (`client.fetch`).
+
+## When not to use
+
+- Per-surface usage (listing jobs, auth) — see the surface skills; they assume the client exists.
+
+## Create the client
+
+```ts
+import { createBoardClient } from '@cavuno/board';
+
+const board = createBoardClient({
+  baseUrl: 'https://api.cavuno.com',
+  board: 'pk_a8f3...', // pk_ key (preferred) | boards_ id | slug
+});
+```
+
+Use the `pk_…` publishable key for `board`, not the slug: the slug is operator-mutable and renames break deployed frontends. The `pk_…` key is immutable and client-safe.
+
+## Configuration
+
+```ts no-check
+const board = createBoardClient({
+  baseUrl: process.env.PUBLIC_CAVUNO_API_URL!,
+  board: process.env.PUBLIC_CAVUNO_BOARD!,
+  globalHeaders: { 'Accept-Language': 'en' },
+  onRequest: async (req) => req,          // mutate/replace the request (locale, URL rewrite)
+  onResponse: async (res, req) => {},     // side effects only (logging, analytics)
+  logger: console,
+  auth: { storage: 'memory' },            // see cavuno-board-auth
+});
+```
+
+The `onRequest`/`onResponse` hooks are first-class — do not monkey-patch the client. `onResponse` receives a **clone** of the response, so reading its body never disturbs the SDK's own parsing.
+
+## Per-call FetchOptions ride straight to fetch
+
+Every method takes a trailing `options?` of type `FetchOptions` (`Omit<RequestInit,'body'>` plus `query`). Anything besides `body`/`query` passes through to `fetch` untouched, so framework caching works with zero SDK knowledge:
+
+```ts snippet
+// Next.js ISR
+await board.jobs.list({ limit: 20 }, { next: { revalidate: 60, tags: ['jobs'] } });
+// Cloudflare Workers
+await board.jobs.list({ limit: 20 }, { cf: { cacheTtl: 60 } } as never);
+// Standard fetch + abort
+const ac = new AbortController();
+await board.jobs.list({ limit: 20 }, { cache: 'force-cache', signal: ac.signal });
+```
+
+## One shared instance is SSR-safe — if state stays per-call
+
+A single Workers isolate serves many users at once. A module-scoped client is safe **only** while per-user state is passed per call (`options.headers`), not stored on the instance. For browser/SPA usage, the instance may hold the session (`auth.storage`); for SSR, keep the session in an httpOnly cookie and pass `{ headers: { authorization } }` per call (see `cavuno-board-auth`).
+
+```ts
+import { createBoardClient } from '@cavuno/board';
+
+// Safe: shared, stateless. Per-user token rides per call.
+export const board = createBoardClient({
+  baseUrl: process.env.PUBLIC_CAVUNO_API_URL!,
+  board: process.env.PUBLIC_CAVUNO_BOARD!,
+});
+```
+
+## Escape hatch: client.fetch
+
+`board.client.fetch<T>(path, init)` is public and first-class — it runs the full pipeline (base path, headers, token, hooks), not a raw `fetch`. Use it to call an endpoint before the SDK ships a typed method for it:
+
+```ts snippet
+const data = await board.client.fetch<{ object: 'list'; data: unknown[] }>(
+  '/some-new-endpoint',
+  { query: { limit: 5 } },
+);
+```
+
+## Checklist
+
+- [ ] One client created from env values, reused everywhere.
+- [ ] `board` is the `pk_…` key, not the slug.
+- [ ] No per-user state on a shared SSR instance.
+- [ ] Caching done via per-call `FetchOptions`, not a wrapper.

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

@@ -0,0 +1,86 @@
+---
+name: cavuno-board-errors
+description: Handle errors and access gating with the @cavuno/board SDK — the BoardApiError shape, the typed guards (isNotFound, isUnauthorized, isValidationError, isRateLimited, isForbidden, isConflict), and the board-password flow (isBoardPasswordRequired → password.verify → X-Board-Access grant).
+---
+
+# Errors and access gating
+
+Every SDK method throws on a non-2xx response. The error keeps the server's full typed envelope — never string-match messages.
+
+## When to use
+
+- Branching on failures (not found, unauthorized, validation, rate limit).
+- Unlocking a password-protected board.
+
+## The BoardApiError shape
+
+```ts no-check
+class BoardApiError extends Error {
+  status: number;
+  code: string;        // `<domain>_<snake_reason>`
+  details?: unknown;    // structured, per-code
+  requestId?: string;
+  raw: unknown;         // parsed body, untouched
+}
+```
+
+## Branch with the typed guards
+
+```ts snippet
+import {
+  isBoardApiError,
+  isNotFound,
+  isUnauthorized,
+  isValidationError,
+  isRateLimited,
+  isForbidden,
+  isConflict,
+} from '@cavuno/board';
+
+try {
+  return await board.jobs.retrieve('senior-chef');
+} catch (err) {
+  if (isNotFound(err)) return null;          // 404 → render not-found
+  if (isUnauthorized(err)) {                  // 401 → refresh or sign in
+    /* see cavuno-board-auth */
+  }
+  if (isValidationError(err)) {               // 400 validation_bad_request → field errors in err.details
+  }
+  if (isRateLimited(err)) {                    // 429 → back off
+  }
+  if (isBoardApiError(err)) {
+    console.error(err.code, err.requestId);    // log code + requestId for support
+  }
+  throw err;
+}
+```
+
+`isForbidden` (403) and `isConflict` (409) round out the set. Use `err.requestId` in support reports.
+
+## Password-protected boards
+
+A gated board answers reads with `isBoardPasswordRequired` until the visitor presents a grant. Exchange the password once with `password.verify()`; the SDK stores the grant and attaches it as `X-Board-Access` on every subsequent read automatically.
+
+```ts snippet
+import { isBoardPasswordRequired } from '@cavuno/board';
+
+try {
+  await board.jobs.list({ limit: 20 });
+} catch (err) {
+  if (isBoardPasswordRequired(err)) {
+    await board.password.verify(userEnteredPassword); // stores the grant
+    await board.jobs.list({ limit: 20 });             // now passes the wall
+  } else {
+    throw err;
+  }
+}
+```
+
+The grant is identical for every visitor of the board and is not a user session. On SSR (`nostore`), pass it per call as `{ headers: { 'x-board-access': grant } }` instead of relying on stored state.
+
+## Checklist
+
+- [ ] Failures branched via guards, never message string-matching.
+- [ ] `404` → handled not-found path (not a crash).
+- [ ] `err.requestId` logged for support.
+- [ ] Password-gated boards call `password.verify()` on `isBoardPasswordRequired`.

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

@@ -0,0 +1,93 @@
+---
+name: cavuno-board-jobs
+description: Browse, search, and render jobs with the @cavuno/board SDK — jobs.list, jobs.search, jobs.retrieve, jobs.similar. Covers the slim card vs full job shapes, storefront pagination (count/limit/offset + opaque cursor), filters, and the candidate-paywall gatedCount.
+---
+
+# Jobs: browse, search, detail
+
+The highest-traffic surface. Listing and search return slim `PublicJobCard`s; the detail endpoint returns the full `PublicJob`.
+
+## When to use
+
+- Listing/search/keyword/location pages.
+- The job-detail page and its "similar jobs" rail.
+
+## When not to use
+
+- Company-scoped listings — use `companies.listJobs` (same card shape).
+- The ungated embeddable widget — use `embed.jobs`.
+
+## List and render cards
+
+`jobs.list` returns a `JobCardListEnvelope`: storefront pagination fields plus `data: PublicJobCard[]` and optional `relatedSearches`.
+
+```ts snippet
+const page = await board.jobs.list({ limit: 20, seniority: ['senior', 'lead'] });
+page.count;        // total matches ("X jobs")
+page.hasMore;      // more pages exist
+page.nextCursor;   // opaque forward token, or null
+for (const card of page.data) {
+  card.title;
+  card.company?.name;
+  card.links.public; // canonical /companies/:companySlug/jobs/:jobSlug
+}
+```
+
+### Filters and pagination
+
+`JobsListQuery` supports `limit` (1–100), `offset` (takes precedence over `cursor`), `cursor`, and filters: `companyId`, `remoteOption`, `employmentType`, `seniority` (single or repeated → OR-matched), `location` + `radius` (km), `category`, `skill`. Paginate by passing back `nextCursor`, or use numbered pages with `offset`:
+
+```ts snippet
+const p1 = await board.jobs.list({ limit: 20 });
+const p2 = p1.nextCursor
+  ? await board.jobs.list({ limit: 20, cursor: p1.nextCursor })
+  : null;
+// or numbered pages:
+const page3 = await board.jobs.list({ limit: 20, offset: 40 });
+```
+
+## Search
+
+`jobs.search` posts a `JobsSearchBody` (free-text `query` + structured `filters`) and returns a `JobCardSearchEnvelope`:
+
+```ts snippet
+const results = await board.jobs.search({
+  query: 'chef',
+  filters: {
+    seniority: ['senior'],
+    remoteOption: ['remote'],
+    publishedAt: { gte: '2026-01-01T00:00:00Z' },
+  },
+  limit: 20,
+});
+```
+
+## Detail and similar
+
+```ts snippet
+const job = await board.jobs.retrieve('senior-chef'); // full PublicJob
+job.description;       // HTML
+job.officeLocations;
+job.company?.slug;
+const rail = await board.jobs.similar('senior-chef', { limit: 5 });
+```
+
+## The candidate paywall: gatedCount
+
+On gated boards, some results are hidden from anonymous/unentitled viewers. `gatedCount` is how many were withheld for the current viewer (absent/0 when entitled). Surface it as an upsell rather than pretending the list is complete:
+
+```ts snippet
+const page = await board.jobs.list({ limit: 20 });
+if (page.gatedCount && page.gatedCount > 0) {
+  // e.g. "Sign in to see N more roles"
+}
+```
+
+A board-user bearer token on the same call returns the entitled (ungated) view — the endpoint is optional-auth, one URL for both anonymous and personalized reads.
+
+## Checklist
+
+- [ ] Listing/search use `PublicJobCard`; detail uses `PublicJob`.
+- [ ] Job links use `links.public` (canonical `/companies/:companySlug/jobs/:jobSlug`).
+- [ ] Pagination via `nextCursor` or `offset`, not client-side slicing.
+- [ ] `gatedCount` surfaced as an upsell, not hidden.

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

@@ -0,0 +1,96 @@
+---
+name: cavuno-board-setup
+description: End-to-end orchestrator for building a headless Cavuno job board with the @cavuno/board SDK. Start here after `npx @cavuno/board setup` copies the skills — detect the framework, wire the client, render board context, jobs browsing and detail, board-user auth and saved jobs, handle errors and access gating, then verify.
+---
+
+# Setting up a Cavuno board
+
+`@cavuno/board` is a thin, isomorphic, typed client for the Cavuno Board API (`/v1/boards/:identifier/*`). It brings the commerce of a job board — jobs, companies, blog, search, auth, saved jobs, alerts — to the framework you already use. You bring the framework and own the layout; the SDK brings the data contract.
+
+This skill is the orchestrator. Work top to bottom, delegating each surface to its focused skill.
+
+## When to use
+
+- Standing up a new headless board frontend against the Board API.
+- Adding board data (jobs/companies/blog/auth) to an existing app.
+- After `npx @cavuno/board setup` has installed the package and copied these skills.
+
+## When not to use
+
+- Authoring the hosted board inside the Cavuno admin (that's the operator Puck builder, not the SDK).
+- Building the operator/admin REST API client — that's `@kit/api-client`, not `@cavuno/board`.
+
+## Inspect the app
+
+Read `package.json` and the project layout before writing anything. Identify: the framework (see below), whether it renders on a server (SSR/RSC) or only in the browser, and where server-only secrets are read. Match the project's existing conventions — do not introduce a new data-fetching style.
+
+## Detect the framework
+
+`@cavuno/board` is framework-agnostic: it needs only `fetch` and runs in the browser, Node ≥ 20, and Cloudflare Workers. Detect the framework from dependencies and adapt:
+
+- `@tanstack/react-start` → the reference flavor. Read `cavuno-board-tanstack-start` for SSR-loader + cookie wiring.
+- `next` → use Server Components + per-call `FetchOptions` (`next: { revalidate, tags }`).
+- Anything else (Nuxt, SvelteKit, Astro, SolidStart, plain JS) → use the core skills directly; the SDK surface is identical.
+
+## Use standard environment names
+
+Read these two values from the environment; never hard-code them:
+
+- `PUBLIC_CAVUNO_API_URL` — the API base, e.g. `https://api.cavuno.com`.
+- `PUBLIC_CAVUNO_BOARD` — the board identifier. Use the `pk_…` publishable key, not the slug (the slug is operator-mutable and breaks deployed frontends on rename).
+
+Both are public-safe (the `pk_…` key is client-safe by design). Use your framework's public-env convention for the variable name (`VITE_`, `PUBLIC_`, `NEXT_PUBLIC_`); the values are the same.
+
+## Keep credentials server-side
+
+The board identifier is public. A board-user **bearer JWT is not** — it must never reach the browser bundle. On a server framework, keep the session in an httpOnly cookie owned by your app and pass it per call; see `cavuno-board-auth`.
+
+## Use board route conventions
+
+The canonical public job-detail URL is `/companies/:companySlug/jobs/:jobSlug` — a job needs both slugs. `/jobs`, `/jobs/:keyword`, `/jobs/locations/:slug` are listing/search pages, never individual jobs. Mirror these paths so a board migrating hosted → headless keeps its indexed URLs.
+
+## Wire the client
+
+Create one client and reuse it. See `cavuno-board-client`.
+
+```ts
+import { createBoardClient } from '@cavuno/board';
+
+export const board = createBoardClient({
+  baseUrl: process.env.PUBLIC_CAVUNO_API_URL!,
+  board: process.env.PUBLIC_CAVUNO_BOARD!,
+});
+```
+
+## Build the board shell from context
+
+`board.context()` (a root method on the client) returns identity, theme, analytics, and the board's capability `features` flags. Render branding from it and **gate every optional surface on its capability flag** — only build a route when its feature is enabled. (A dedicated context skill ships with a later slice; the return type is self-describing until then.)
+
+## Build jobs browsing + detail
+
+The core surface. `jobs.list` / `jobs.search` for listing pages, `jobs.retrieve` for the detail page, `jobs.similar` for the related rail. Honor storefront pagination and the candidate-paywall `gatedCount`. See `cavuno-board-jobs`.
+
+## Add board users + saved jobs
+
+Register/login/refresh/logout, then `me.retrieve` and `me.savedJobs.*`. There is **no auto-refresh on 401** — handle it explicitly. See `cavuno-board-auth`.
+
+## Handle errors + gating
+
+Every method throws `BoardApiError` on a non-2xx; branch with the typed guards. Password-protected boards need a `password.verify()` grant. See `cavuno-board-errors`.
+
+## App-owned concerns (out of scope)
+
+The SDK serves data only. Your app owns: page layout and chrome copy, marketing/legal prose, and the authoring of SEO artifacts (sitemap, RSS, OG images) — built from API data, not served as documents. The Board API never returns layouts or page-builder JSON.
+
+## Verification
+
+- `board.context()` resolves and returns your board's name.
+- A listing page renders cards from `board.jobs.list()`.
+- A detail page renders from `board.jobs.retrieve(slug)`.
+- An invalid slug surfaces a handled `isNotFound(err)` path, not a crash.
+
+When the `cavuno-board-smoke-test` skill is present, run it against your `pk_…` to verify end to end.
+
+## Stop conditions
+
+Stop and ask the human when: no `pk_…` board identifier or API URL is available; the framework is unrecognized and has no server boundary for secrets; or a surface you need (e.g. job alerts, applications) has no corresponding skill yet — the SDK only exposes endpoints that are live, so a missing skill means the endpoint isn't shipped.

package/skills/flavors/tanstack-start/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: cavuno-board-tanstack-start
+description: TanStack-Start-on-Cloudflare-Workers reference wiring for a headless Cavuno board — SSR loaders calling @cavuno/board server-side, the session held in an __Host- httpOnly cookie owned by the app, a single-flight refresh helper, and FetchOptions cache passthrough on Workers.
+---
+
+# Reference flavor: TanStack Start on Cloudflare Workers
+
+This is the framework-specific layer for the reference starter (`wollemiahq/cavuno-board-starter`). The core skills (`cavuno-board-client`, `-jobs`, `-auth`, `-errors`) define the SDK surface; this skill shows how to wire it into TanStack Start on Workers. Read the core skills first.
+
+## When to use
+
+- The project depends on `@tanstack/react-start`.
+- You need the SSR-loader + httpOnly-cookie + single-flight-refresh patterns.
+
+## One shared, stateless client
+
+```ts
+import { createBoardClient } from '@cavuno/board';
+
+// Module-scoped, no auth.storage → safe across concurrent Workers requests.
+export const board = createBoardClient({
+  baseUrl: process.env.PUBLIC_CAVUNO_API_URL!,
+  board: process.env.PUBLIC_CAVUNO_BOARD!,
+});
+```
+
+## Read in server loaders; cache via FetchOptions
+
+Call the SDK only on the server (route loaders / server functions), never from the browser with a token. On Workers, pass cache directives straight through:
+
+```ts no-check
+import { createFileRoute } from '@tanstack/react-start';
+import { board } from '~/lib/board';
+
+export const Route = createFileRoute('/jobs')({
+  loader: async () => {
+    // `cf` rides straight to the Workers fetch — the SDK needs no framework knowledge.
+    return board.jobs.list({ limit: 20 }, { cf: { cacheTtl: 60 } } as never);
+  },
+});
+```
+
+## Session in an `__Host-` httpOnly cookie owned by the app
+
+The SDK never owns the cookie. Store the bearer pair in an `__Host-`-prefixed httpOnly cookie set by your server functions, read it on each request, and pass the token per call:
+
+```ts no-check
+import { board } from '~/lib/board';
+import { readSessionCookie } from '~/lib/session.server';
+
+export async function loadMe(request: Request) {
+  const { accessToken } = readSessionCookie(request);
+  // Pass the token via `options` (2nd arg). The 1st arg is `query`.
+  return board.me.retrieve(undefined, {
+    headers: { authorization: `Bearer ${accessToken}` },
+  });
+}
+```
+
+## Single-flight refresh
+
+Refresh tokens are single-use; concurrent 401s must trigger exactly one rotation. Encode it once and reuse everywhere:
+
+```ts no-check
+import { isUnauthorized } from '@cavuno/board';
+import { board } from '~/lib/board';
+
+let inflight: Promise<void> | null = null;
+
+// `getAccessToken`/`getRefreshToken` read your __Host- cookie (the SDK never
+// touches it). On a 401 we refresh exactly once — concurrent callers await the
+// same `inflight` promise — then retry `run` with the rotated token. Your
+// refresh handler must write the new pair to the cookie so the retry reads it.
+export async function withFreshSession<T>(
+  getAccessToken: () => string,
+  getRefreshToken: () => string,
+  run: (accessToken: string) => Promise<T>,
+): Promise<T> {
+  try {
+    return await run(getAccessToken());
+  } catch (err) {
+    if (!isUnauthorized(err)) throw err;
+    inflight ??= board.auth
+      .refresh({ refreshToken: getRefreshToken() })
+      .then(() => undefined)
+      .finally(() => (inflight = null));
+    await inflight;
+    return run(getAccessToken()); // retry with the rotated token
+  }
+}
+```
+
+## Canonical URLs
+
+Mirror the hosted board's public URLs so indexed links survive a hosted → headless migration: job detail at `/companies/$companySlug/jobs/$jobSlug`, listings at `/jobs`, `/jobs/$keyword`, `/jobs/locations/$slug`.
+
+## Checklist
+
+- [ ] All SDK calls are server-side; no bearer token in the browser bundle.
+- [ ] Session in an `__Host-` httpOnly cookie owned by the app, passed per call.
+- [ ] Single-flight refresh wraps concurrent 401s.
+- [ ] Public route paths mirror the hosted board's canonical URLs.

package/skills/manifest.json

@@ -0,0 +1,47 @@
+{
+  "version": "1.3.0",
+  "skills": [
+    {
+      "name": "cavuno-board-auth",
+      "description": "Authenticate board users with the @cavuno/board SDK — register, login, refresh, logout, email verification and password reset. Covers bearer-JWT storage modes, the deliberate no-auto-refresh-on-401 rule (and single-flight handling), and the server-side httpOnly-cookie pattern that keeps tokens out of the browser.",
+      "path": "skills/cavuno-board-auth/SKILL.md",
+      "framework": null,
+      "category": "core"
+    },
+    {
+      "name": "cavuno-board-client",
+      "description": "Create and configure the @cavuno/board client — baseUrl and the pk_ board identifier, global headers, request/response hooks, per-call FetchOptions caching passthrough, the client.fetch escape hatch, and the rule that keeps one shared instance safe under SSR.",
+      "path": "skills/cavuno-board-client/SKILL.md",
+      "framework": null,
+      "category": "core"
+    },
+    {
+      "name": "cavuno-board-errors",
+      "description": "Handle errors and access gating with the @cavuno/board SDK — the BoardApiError shape, the typed guards (isNotFound, isUnauthorized, isValidationError, isRateLimited, isForbidden, isConflict), and the board-password flow (isBoardPasswordRequired → password.verify → X-Board-Access grant).",
+      "path": "skills/cavuno-board-errors/SKILL.md",
+      "framework": null,
+      "category": "core"
+    },
+    {
+      "name": "cavuno-board-jobs",
+      "description": "Browse, search, and render jobs with the @cavuno/board SDK — jobs.list, jobs.search, jobs.retrieve, jobs.similar. Covers the slim card vs full job shapes, storefront pagination (count/limit/offset + opaque cursor), filters, and the candidate-paywall gatedCount.",
+      "path": "skills/cavuno-board-jobs/SKILL.md",
+      "framework": null,
+      "category": "core"
+    },
+    {
+      "name": "cavuno-board-setup",
+      "description": "End-to-end orchestrator for building a headless Cavuno job board with the @cavuno/board SDK. Start here after `npx @cavuno/board setup` copies the skills — detect the framework, wire the client, render board context, jobs browsing and detail, board-user auth and saved jobs, handle errors and access gating, then verify.",
+      "path": "skills/cavuno-board-setup/SKILL.md",
+      "framework": null,
+      "category": "core"
+    },
+    {
+      "name": "cavuno-board-tanstack-start",
+      "description": "TanStack-Start-on-Cloudflare-Workers reference wiring for a headless Cavuno board — SSR loaders calling @cavuno/board server-side, the session held in an __Host- httpOnly cookie owned by the app, a single-flight refresh helper, and FetchOptions cache passthrough on Workers.",
+      "path": "skills/flavors/tanstack-start/SKILL.md",
+      "framework": "tanstack-start",
+      "category": "flavor"
+    }
+  ]
+}