@cavuno/board 1.2.0 → 1.3.0

package/dist/index.mjs

@@ -27,6 +27,9 @@ function isNotFound(e) {
 function isUnauthorized(e) {
   return isBoardApiError(e) && e.status === 401;
 }
+function isBoardPasswordRequired(e) {
+  return isBoardApiError(e) && e.status === 401 && e.code === "board_password_required";
+}
 function isForbidden(e) {
   return isBoardApiError(e) && e.status === 403;
 }
@@ -61,6 +64,7 @@ function toSearchParams(query) {
 // src/storage.ts
 var ACCESS_TOKEN_KEY = "cavuno_board_access_token";
 var REFRESH_TOKEN_KEY = "cavuno_board_refresh_token";
+var BOARD_ACCESS_GRANT_KEY = "cavuno_board_access_grant";
 function isBrowser() {
   return typeof globalThis.document !== "undefined";
 }
@@ -105,7 +109,7 @@ async function clearSession(storage) {
 }
 
 // src/version.ts
-var SDK_VERSION = "1.2.0";
+var SDK_VERSION = "1.3.0";
 
 // src/client.ts
 function isRawBody(body) {
@@ -147,12 +151,14 @@ var BoardClient = class {
     }
     const token = await this.storage.getItem(ACCESS_TOKEN_KEY);
     if (token !== null) headers.set("authorization", `Bearer ${token}`);
+    const grant = await this.storage.getItem(BOARD_ACCESS_GRANT_KEY);
+    if (grant !== null) headers.set("x-board-access", grant);
     if (callHeaders) {
       new Headers(callHeaders).forEach((value, key) => {
         headers.set(key, value);
       });
     }
-    if ((method !== "GET" || headers.has("authorization")) && !headers.has("x-cavuno-sdk")) {
+    if ((method !== "GET" || headers.has("authorization") || headers.has("x-board-access")) && !headers.has("x-cavuno-sdk")) {
       headers.set("x-cavuno-sdk", `board@${SDK_VERSION}`);
     }
     let req = {
@@ -163,7 +169,8 @@ var BoardClient = class {
     this.options.logger?.debug(`${method} ${req.url}`);
     const res = await globalThis.fetch(req.url, req.init);
     this.options.logger?.debug(`${res.status} ${method} ${req.url}`);
-    if (this.options.onResponse) await this.options.onResponse(res.clone(), req);
+    if (this.options.onResponse)
+      await this.options.onResponse(res.clone(), req);
     if (res.status === 204) return void 0;
     if (res.ok) return await res.json();
     let parsed;
@@ -358,6 +365,30 @@ function blogNamespace(client) {
           `/blog/posts/${encodeURIComponent(postSlug)}`,
           { ...options, query }
         );
+      },
+      /**
+       * The previous (older) and next (newer) posts for prev/next navigation.
+       *
+       * @example
+       * const { previous, next } = await board.blog.posts.adjacent('hello-world');
+       */
+      adjacent(postSlug, options) {
+        return client.fetch(
+          `/blog/posts/${encodeURIComponent(postSlug)}/adjacent`,
+          options
+        );
+      },
+      /**
+       * Posts most similar to one post (the related-posts rail).
+       *
+       * @example
+       * const { data } = await board.blog.posts.similar('hello-world', { limit: 6 });
+       */
+      similar(postSlug, query, options) {
+        return client.fetch(
+          `/blog/posts/${encodeURIComponent(postSlug)}/similar`,
+          { ...options, query }
+        );
       }
     },
     tags: {
@@ -463,6 +494,96 @@ function companiesNamespace(client) {
   };
 }
 
+// src/namespaces/embed.ts
+function embedNamespace(client) {
+  return {
+    /**
+     * List published jobs for an embeddable widget — the same featured-ranked
+     * cards as `board.jobs.list`, but UNGATED: the candidate paywall never
+     * applies, so the full page is always returned and there is no
+     * `gatedCount`. Powers the public "Powered by Cavuno" embed. `limit`
+     * defaults to 8 and is clamped to a maximum of 50.
+     *
+     * @example
+     * const { data, nextCursor } = await board.embed.jobs({ q: 'chef', limit: 8 });
+     */
+    jobs(query, options) {
+      return client.fetch("/embed/jobs", {
+        ...options,
+        query
+      });
+    }
+  };
+}
+
+// src/namespaces/job-alerts.ts
+function jobAlertsNamespace(client) {
+  return {
+    /** Subscribe an email to job alerts. Sends a double-opt-in confirmation email. */
+    subscribe(input, options) {
+      return client.fetch("/job-alerts", {
+        ...options,
+        method: "POST",
+        body: input
+      });
+    },
+    /** Complete double opt-in with the token from the confirmation email. */
+    confirm(input, options) {
+      return client.fetch("/job-alerts/confirm", {
+        ...options,
+        method: "POST",
+        body: input
+      });
+    },
+    /** Re-send the confirmation email for an unconfirmed subscription. */
+    resendConfirmation(input, options) {
+      return client.fetch(
+        "/job-alerts/resend-confirmation",
+        { ...options, method: "POST", body: input }
+      );
+    },
+    /** Read a subscription + its preferences for the manage page (HMAC token). */
+    manage(query, options) {
+      return client.fetch("/job-alerts/manage", {
+        ...options,
+        query
+      });
+    },
+    /** Deactivate a subscription via the HMAC manage token. */
+    unsubscribe(input, options) {
+      return client.fetch("/job-alerts/unsubscribe", {
+        ...options,
+        method: "POST",
+        body: input
+      });
+    },
+    /** Re-activate a previously unsubscribed subscription via the manage token. */
+    resubscribe(input, options) {
+      return client.fetch("/job-alerts/resubscribe", {
+        ...options,
+        method: "POST",
+        body: input
+      });
+    },
+    /** Edit a preference's filters/frequency via the manage token. */
+    updatePreference(input, options) {
+      return client.fetch("/job-alerts/preferences", {
+        ...options,
+        method: "POST",
+        body: input
+      });
+    },
+    /** Delete a preference via the manage token. */
+    deletePreference(input, options) {
+      return client.fetch("/job-alerts/preferences", {
+        ...options,
+        method: "DELETE",
+        body: input
+      });
+    }
+  };
+}
+
 // src/namespaces/jobs.ts
 function jobsNamespace(client) {
   return {
@@ -587,6 +708,30 @@ function meNamespace(client) {
   };
 }
 
+// src/namespaces/password.ts
+function passwordNamespace(client) {
+  return {
+    /**
+     * Exchange a board password for an access grant and store it. After this
+     * resolves, every subsequent read auto-carries the grant as the
+     * `X-Board-Access` header — until the password rotates, after which reads
+     * fail with 401 `board_password_required` and you must `verify()` again
+     * (the SDK never auto-retries — verify is rate-limited — and never
+     * auto-clears; the host re-challenges). On the server (`nostore` storage)
+     * the grant is returned but not persisted; pass it per-call instead.
+     */
+    async verify(password, options) {
+      const grant = await client.fetch("/password/verify", {
+        ...options,
+        method: "POST",
+        body: { password }
+      });
+      await client.storage.setItem(BOARD_ACCESS_GRANT_KEY, grant.token);
+      return grant;
+    }
+  };
+}
+
 // src/namespaces/redirects.ts
 function redirectsNamespace(client) {
   return {
@@ -628,9 +773,16 @@ function taxonomyNamespace(client) {
     skills: taxonomyResolver(client, "skills"),
     places: {
       ...taxonomyResolver(client, "places"),
-      /** List every place used by a published job, with its live job count. */
-      list(options) {
-        return client.fetch("/places", options);
+      /**
+       * Without `query`: list every place used by a published job, with its
+       * live job count (the locations directory). With `query.q` (≥2 chars):
+       * location autocomplete — the top name matches ranked.
+       */
+      list(query, options) {
+        return client.fetch("/places", {
+          ...options,
+          query
+        });
       }
     }
   };
@@ -675,22 +827,27 @@ function createBoardClient(options) {
       return client.fetch("/seo", options2);
     },
     jobs: jobsNamespace(client),
+    embed: embedNamespace(client),
     companies: companiesNamespace(client),
     blog: blogNamespace(client),
     auth: authNamespace(client),
     me: meNamespace(client),
+    password: passwordNamespace(client),
     taxonomy: taxonomyNamespace(client),
-    redirects: redirectsNamespace(client)
+    redirects: redirectsNamespace(client),
+    jobAlerts: jobAlertsNamespace(client)
   };
 }
 export {
   ACCESS_TOKEN_KEY,
+  BOARD_ACCESS_GRANT_KEY,
   BoardApiError,
   BoardClient,
   REFRESH_TOKEN_KEY,
   SDK_VERSION,
   createBoardClient,
   isBoardApiError,
+  isBoardPasswordRequired,
   isConflict,
   isForbidden,
   isNotFound,

package/dist/skills.d.mts

@@ -0,0 +1,38 @@
+/**
+ * Skill-corpus loader. Node-only (reads the shipped `skills/` directory from
+ * the installed package) — kept out of the isomorphic core and exposed via the
+ * `@cavuno/board/skills` subpath export. Both `npx @cavuno/board setup` and the
+ * in-admin sidekick (ADR-0033) read the corpus through here, so the two doors
+ * stay fed from one source.
+ */
+interface SkillManifestEntry {
+    name: string;
+    description: string;
+    /** Path to the SKILL.md, relative to the package root. */
+    path: string;
+    /** Framework slug for flavor skills; `null` for framework-agnostic core skills. */
+    framework: string | null;
+    category: 'core' | 'flavor';
+}
+interface SkillManifest {
+    version: string;
+    skills: SkillManifestEntry[];
+}
+interface LoadedSkill extends SkillManifestEntry {
+    content: string;
+}
+interface SkillCorpus {
+    version: string;
+    skills: LoadedSkill[];
+}
+/** Resolve a package-root-relative path (e.g. a manifest `path`) to an absolute path. */
+declare function resolveFromPackageRoot(relativePath: string): string;
+declare function loadSkillManifest(): SkillManifest;
+/**
+ * Load the full skill corpus — manifest metadata plus each skill's markdown
+ * `content`. The sidekick injects `content` into its agent context; an external
+ * Claude Code instead receives the files copied by the setup command.
+ */
+declare function loadSkillCorpus(): SkillCorpus;
+
+export { type LoadedSkill, type SkillCorpus, type SkillManifest, type SkillManifestEntry, loadSkillCorpus, loadSkillManifest, resolveFromPackageRoot };

package/dist/skills.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Skill-corpus loader. Node-only (reads the shipped `skills/` directory from
+ * the installed package) — kept out of the isomorphic core and exposed via the
+ * `@cavuno/board/skills` subpath export. Both `npx @cavuno/board setup` and the
+ * in-admin sidekick (ADR-0033) read the corpus through here, so the two doors
+ * stay fed from one source.
+ */
+interface SkillManifestEntry {
+    name: string;
+    description: string;
+    /** Path to the SKILL.md, relative to the package root. */
+    path: string;
+    /** Framework slug for flavor skills; `null` for framework-agnostic core skills. */
+    framework: string | null;
+    category: 'core' | 'flavor';
+}
+interface SkillManifest {
+    version: string;
+    skills: SkillManifestEntry[];
+}
+interface LoadedSkill extends SkillManifestEntry {
+    content: string;
+}
+interface SkillCorpus {
+    version: string;
+    skills: LoadedSkill[];
+}
+/** Resolve a package-root-relative path (e.g. a manifest `path`) to an absolute path. */
+declare function resolveFromPackageRoot(relativePath: string): string;
+declare function loadSkillManifest(): SkillManifest;
+/**
+ * Load the full skill corpus — manifest metadata plus each skill's markdown
+ * `content`. The sidekick injects `content` into its agent context; an external
+ * Claude Code instead receives the files copied by the setup command.
+ */
+declare function loadSkillCorpus(): SkillCorpus;
+
+export { type LoadedSkill, type SkillCorpus, type SkillManifest, type SkillManifestEntry, loadSkillCorpus, loadSkillManifest, resolveFromPackageRoot };

package/dist/skills.js

@@ -0,0 +1,62 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/skills.ts
+var skills_exports = {};
+__export(skills_exports, {
+  loadSkillCorpus: () => loadSkillCorpus,
+  loadSkillManifest: () => loadSkillManifest,
+  resolveFromPackageRoot: () => resolveFromPackageRoot
+});
+module.exports = __toCommonJS(skills_exports);
+
+// ../../node_modules/.pnpm/tsup@8.5.1_jiti@2.7.0_postcss@8.5.14_tsx@4.21.0_typescript@5.9.3_yaml@2.8.4/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();
+
+// src/skills.ts
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var import_node_url = require("url");
+function packageRoot() {
+  return (0, import_node_path.resolve)((0, import_node_path.dirname)((0, import_node_url.fileURLToPath)(importMetaUrl)), "..");
+}
+function resolveFromPackageRoot(relativePath) {
+  return (0, import_node_path.resolve)(packageRoot(), relativePath);
+}
+function loadSkillManifest() {
+  const manifestPath = resolveFromPackageRoot("skills/manifest.json");
+  return JSON.parse((0, import_node_fs.readFileSync)(manifestPath, "utf8"));
+}
+function loadSkillCorpus() {
+  const manifest = loadSkillManifest();
+  return {
+    version: manifest.version,
+    skills: manifest.skills.map((skill) => ({
+      ...skill,
+      content: (0, import_node_fs.readFileSync)(resolveFromPackageRoot(skill.path), "utf8")
+    }))
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  loadSkillCorpus,
+  loadSkillManifest,
+  resolveFromPackageRoot
+});

package/dist/skills.mjs

@@ -0,0 +1,29 @@
+// src/skills.ts
+import { readFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+function packageRoot() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+}
+function resolveFromPackageRoot(relativePath) {
+  return resolve(packageRoot(), relativePath);
+}
+function loadSkillManifest() {
+  const manifestPath = resolveFromPackageRoot("skills/manifest.json");
+  return JSON.parse(readFileSync(manifestPath, "utf8"));
+}
+function loadSkillCorpus() {
+  const manifest = loadSkillManifest();
+  return {
+    version: manifest.version,
+    skills: manifest.skills.map((skill) => ({
+      ...skill,
+      content: readFileSync(resolveFromPackageRoot(skill.path), "utf8")
+    }))
+  };
+}
+export {
+  loadSkillCorpus,
+  loadSkillManifest,
+  resolveFromPackageRoot
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cavuno/board",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Typed isomorphic client for the Cavuno Board API",
   "license": "MIT",
   "repository": {
@@ -15,6 +15,9 @@
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "cavuno-board": "./dist/bin.mjs"
+  },
   "exports": {
     ".": {
       "import": {
@@ -25,10 +28,22 @@
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
       }
-    }
+    },
+    "./skills": {
+      "import": {
+        "types": "./dist/skills.d.mts",
+        "default": "./dist/skills.mjs"
+      },
+      "require": {
+        "types": "./dist/skills.d.ts",
+        "default": "./dist/skills.js"
+      }
+    },
+    "./skills/*": "./skills/*"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "publishConfig": {
     "access": "public"
@@ -36,15 +51,17 @@
   "scripts": {
     "build": "tsup",
     "clean": "git clean -xdf .turbo dist node_modules",
-    "typecheck": "tsgo --noEmit",
+    "typecheck": "tsgo --noEmit && tsgo --noEmit -p tsconfig.node.json",
     "test": "vitest run",
+    "gen:skills-manifest": "tsx scripts/generate-skills-manifest.ts",
     "assert-publish-target": "node -e \"const p=require('./package.json'); if(p.name!=='@cavuno/board'){throw new Error('Refusing to publish: package.json name is '+p.name+', expected @cavuno/board')}; if(p.private){throw new Error('Refusing to publish: package.json has private:true')}\"",
-    "prepublishOnly": "pnpm run assert-publish-target && pnpm run build"
+    "prepublishOnly": "pnpm run assert-publish-target && pnpm run gen:skills-manifest && pnpm run build"
   },
   "devDependencies": {
     "@kit/tsconfig": "workspace:*",
     "@types/node": "catalog:",
     "tsup": "^8.4.0",
+    "tsx": "^4.19.2",
     "vitest": "^2.1.9"
   }
 }

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

@@ -0,0 +1,113 @@
+---
+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.
+---
+
+# Board-user authentication
+
+Board users (candidates, employers) authenticate with a short-lived bearer access token plus a refresh token. The SDK manages the pair via pluggable async storage. There is exactly one auth mode — bearer JWT (no cookie/session mode).
+
+## When to use
+
+- Sign-up / sign-in / sign-out for board users.
+- Email verification and password reset flows.
+- Wiring authenticated calls (`me`, saved jobs, applications).
+
+## When not to use
+
+- Anonymous reads (jobs/companies/blog) — no auth needed.
+- Board-password gating — that's a separate grant; see `cavuno-board-errors`.
+
+## Register and login
+
+```ts snippet
+await board.auth.register({
+  role: 'candidate',
+  method: 'emailpass',
+  email: 'ada@example.com',
+  password: 'a-strong-password',
+  displayName: 'Ada',
+});
+
+const session = await board.auth.login({
+  email: 'ada@example.com',
+  password: 'a-strong-password',
+});
+session.boardUser.email; // the signed-in user
+session.accessToken;     // bearer; never expose to the browser bundle on SSR
+```
+
+`register`/`login`/`refresh` persist the returned token pair to storage; `logout` clears it. The SDK never navigates — your app owns redirects and verification UX.
+
+## Storage modes
+
+`auth.storage` is `'memory'` | `'nostore'` | a `CustomStorage`. Defaults: **`memory` in the browser, `nostore` on the server**. Browser login works out of the box; shared SSR instances stay stateless.
+
+```ts
+import { createBoardClient } from '@cavuno/board';
+
+// Browser/SPA: token held in memory on the instance.
+const board = createBoardClient({
+  baseUrl: 'https://api.cavuno.com',
+  board: 'pk_a8f3...',
+  auth: { storage: 'memory' },
+});
+```
+
+A `CustomStorage` implements async `getItem`/`setItem`/`removeItem` — back it with `localStorage`, IndexedDB, Redis, or your own store.
+
+## No auto-refresh on 401 — handle it explicitly
+
+An expired access token surfaces as a `BoardApiError` you detect with `isUnauthorized`. The SDK does **not** silently refresh — refresh tokens are single-use with atomic rotation, so safe refresh under concurrency needs a single-flight guard you own.
+
+```ts snippet
+import { isUnauthorized } from '@cavuno/board';
+
+try {
+  return await board.me.retrieve();
+} catch (err) {
+  if (isUnauthorized(err)) {
+    await board.auth.refresh(); // reads the stored refresh token, rotates the pair
+    return await board.me.retrieve();
+  }
+  throw err;
+}
+```
+
+Under concurrency, wrap `auth.refresh()` in a single-flight promise so parallel 401s trigger exactly one rotation (the reference flavor encodes this once — see `cavuno-board-tanstack-start`).
+
+## refresh / logout token sourcing
+
+Both accept an optional body `{ refreshToken }`. When omitted, the SDK reads the token from storage and throws if neither exists — so `nostore` (server) callers must pass it explicitly:
+
+```ts snippet
+await board.auth.refresh({ refreshToken });   // server: explicit
+await board.auth.logout({ refreshToken });    // revokes server-side, clears storage
+```
+
+## Server-side pattern (keep tokens out of the browser)
+
+On SSR, do not hold the session on a shared instance. Keep the token pair in an httpOnly cookie owned by your app and pass it per call:
+
+```ts snippet
+// `accessToken` comes from your httpOnly cookie, read in server code.
+// Per-call options are the 2nd argument; the 1st is `query` (pass undefined).
+const me = await board.me.retrieve(undefined, {
+  headers: { authorization: `Bearer ${accessToken}` },
+});
+```
+
+## Email verification & password reset
+
+```ts snippet
+await board.auth.verifyEmail({ token });             // token from the email link
+await board.auth.forgotPassword({ email });          // sends the reset email
+await board.auth.resetPassword({ token, password }); // token from the email link
+```
+
+## Checklist
+
+- [ ] Bearer tokens never reach the browser bundle on SSR (httpOnly cookie + per-call header).
+- [ ] 401s handled explicitly with `isUnauthorized` + `auth.refresh()`.
+- [ ] Concurrent refresh guarded by single-flight.
+- [ ] `nostore` callers pass `{ refreshToken }` to `refresh`/`logout`.