@cavuno/board 1.37.0 → 1.39.0

package/dist/search-CqBa1Qc4.d.mts

@@ -0,0 +1,81 @@
+import { S as Schemas } from './_spec-DxC1ze93.mjs';
+
+type Awaitable<T> = T | Promise<T>;
+/**
+ * Async token storage. The SDK reads the access token from storage on
+ * every request (fresh-token rule); auth methods write/clear the pair.
+ */
+interface CustomStorage {
+    getItem(key: string): Awaitable<string | null>;
+    setItem(key: string, value: string): Awaitable<void>;
+    removeItem(key: string): Awaitable<void>;
+}
+type StorageMode = 'memory' | 'nostore' | 'local' | 'session' | CustomStorage;
+declare const ACCESS_TOKEN_KEY = "cavuno_board_access_token";
+declare const REFRESH_TOKEN_KEY = "cavuno_board_refresh_token";
+/** Board-password access grant — sent as `X-Board-Access` to pass the wall. */
+declare const BOARD_ACCESS_GRANT_KEY = "cavuno_board_access_grant";
+
+/**
+ * The request handed to `onRequest` and `fetch`. `onRequest` may
+ * mutate or replace it wholesale (locale headers, URL rewrites);
+ * whatever it returns is what gets fetched.
+ */
+interface BoardRequest {
+    /** Fully built URL, query string included. */
+    url: string;
+    /** Final RequestInit: method, Headers instance, serialized body, plus passthrough keys (`signal`, `cache`, `next`, `cf`, …). */
+    init: RequestInit;
+}
+interface Logger {
+    debug(message: string): void;
+    error(message: string): void;
+}
+/**
+ * Per-call options on every SDK method. Everything besides `body` and
+ * `query` is passed through to `fetch` untouched, so framework caching
+ * (`next: { tags }`, `cf: {...}`, `cache:`) rides for free.
+ */
+type FetchOptions = Omit<RequestInit, 'body'> & {
+    body?: unknown;
+    query?: Record<string, unknown>;
+};
+interface BoardClientOptions {
+    baseUrl: string;
+    /** Board identifier: `pk_…` key | `boards_…` ID | slug (ADR-0032). */
+    board: string;
+    storage: CustomStorage;
+    globalHeaders?: Record<string, string>;
+    onRequest?: (req: BoardRequest) => Awaitable<BoardRequest>;
+    onResponse?: (res: Response, req: BoardRequest) => Awaitable<void>;
+    logger?: Logger;
+}
+declare class BoardClient {
+    readonly storage: CustomStorage;
+    private readonly basePath;
+    private readonly options;
+    constructor(options: BoardClientOptions);
+    /**
+     * The full request pipeline. Public and first-class: custom endpoints
+     * work without an SDK release, and still get the board-identifier
+     * base path, default headers, bearer token, and both hooks.
+     *
+     * @example
+     * const stats = await board.client.fetch<MyShape>('/custom/stats');
+     */
+    fetch<T>(path: string, init?: FetchOptions): Promise<T>;
+}
+
+type SuggestResult = Schemas['SuggestResult'];
+type SuggestionItem = Schemas['SuggestionItem'];
+type CompanySuggestion = Schemas['CompanySuggestion'];
+type TermSuggestion = Schemas['TermSuggestion'];
+/** Query for `board.search.suggest()`. */
+type SearchSuggestQuery = {
+    /** Keyword; under 2 chars the server returns an empty `items` array. */
+    q?: string;
+    /** Max interleaved suggestions (1–25; default 25). */
+    limit?: number;
+};
+
+export { type Awaitable as A, type BoardRequest as B, type CompanySuggestion as C, type FetchOptions as F, type Logger as L, REFRESH_TOKEN_KEY as R, type SuggestionItem as S, type TermSuggestion as T, type SearchSuggestQuery as a, type SuggestResult as b, type StorageMode as c, BoardClient as d, ACCESS_TOKEN_KEY as e, BOARD_ACCESS_GRANT_KEY as f, type CustomStorage as g };

package/dist/search-DBoMM-gE.d.ts

@@ -0,0 +1,81 @@
+import { S as Schemas } from './_spec-DxC1ze93.js';
+
+type Awaitable<T> = T | Promise<T>;
+/**
+ * Async token storage. The SDK reads the access token from storage on
+ * every request (fresh-token rule); auth methods write/clear the pair.
+ */
+interface CustomStorage {
+    getItem(key: string): Awaitable<string | null>;
+    setItem(key: string, value: string): Awaitable<void>;
+    removeItem(key: string): Awaitable<void>;
+}
+type StorageMode = 'memory' | 'nostore' | 'local' | 'session' | CustomStorage;
+declare const ACCESS_TOKEN_KEY = "cavuno_board_access_token";
+declare const REFRESH_TOKEN_KEY = "cavuno_board_refresh_token";
+/** Board-password access grant — sent as `X-Board-Access` to pass the wall. */
+declare const BOARD_ACCESS_GRANT_KEY = "cavuno_board_access_grant";
+
+/**
+ * The request handed to `onRequest` and `fetch`. `onRequest` may
+ * mutate or replace it wholesale (locale headers, URL rewrites);
+ * whatever it returns is what gets fetched.
+ */
+interface BoardRequest {
+    /** Fully built URL, query string included. */
+    url: string;
+    /** Final RequestInit: method, Headers instance, serialized body, plus passthrough keys (`signal`, `cache`, `next`, `cf`, …). */
+    init: RequestInit;
+}
+interface Logger {
+    debug(message: string): void;
+    error(message: string): void;
+}
+/**
+ * Per-call options on every SDK method. Everything besides `body` and
+ * `query` is passed through to `fetch` untouched, so framework caching
+ * (`next: { tags }`, `cf: {...}`, `cache:`) rides for free.
+ */
+type FetchOptions = Omit<RequestInit, 'body'> & {
+    body?: unknown;
+    query?: Record<string, unknown>;
+};
+interface BoardClientOptions {
+    baseUrl: string;
+    /** Board identifier: `pk_…` key | `boards_…` ID | slug (ADR-0032). */
+    board: string;
+    storage: CustomStorage;
+    globalHeaders?: Record<string, string>;
+    onRequest?: (req: BoardRequest) => Awaitable<BoardRequest>;
+    onResponse?: (res: Response, req: BoardRequest) => Awaitable<void>;
+    logger?: Logger;
+}
+declare class BoardClient {
+    readonly storage: CustomStorage;
+    private readonly basePath;
+    private readonly options;
+    constructor(options: BoardClientOptions);
+    /**
+     * The full request pipeline. Public and first-class: custom endpoints
+     * work without an SDK release, and still get the board-identifier
+     * base path, default headers, bearer token, and both hooks.
+     *
+     * @example
+     * const stats = await board.client.fetch<MyShape>('/custom/stats');
+     */
+    fetch<T>(path: string, init?: FetchOptions): Promise<T>;
+}
+
+type SuggestResult = Schemas['SuggestResult'];
+type SuggestionItem = Schemas['SuggestionItem'];
+type CompanySuggestion = Schemas['CompanySuggestion'];
+type TermSuggestion = Schemas['TermSuggestion'];
+/** Query for `board.search.suggest()`. */
+type SearchSuggestQuery = {
+    /** Keyword; under 2 chars the server returns an empty `items` array. */
+    q?: string;
+    /** Max interleaved suggestions (1–25; default 25). */
+    limit?: number;
+};
+
+export { type Awaitable as A, type BoardRequest as B, type CompanySuggestion as C, type FetchOptions as F, type Logger as L, REFRESH_TOKEN_KEY as R, type SuggestionItem as S, type TermSuggestion as T, type SearchSuggestQuery as a, type SuggestResult as b, type StorageMode as c, BoardClient as d, ACCESS_TOKEN_KEY as e, BOARD_ACCESS_GRANT_KEY as f, type CustomStorage as g };

package/dist/seo.d.mts

@@ -1,7 +1,8 @@
-import { P as PublicBlogPostSummary, B as BlogAuthorEmbed, C as CompanyCategorySalary, a as CompanySalary, L as LocationSalaryDetail, S as SkillSalaryDetail, T as TitleSalaryDetail } from './salaries-9U42CM5A.mjs';
-import { P as PublicBoard } from './board-D0guOBYy.mjs';
-import { P as PublicJob } from './jobs-CMCADU_-.mjs';
+import { P as PublicBlogPostSummary, B as BlogAuthorEmbed, C as CompanyCategorySalary, a as CompanySalary, L as LocationSalaryDetail, S as SkillSalaryDetail, T as TitleSalaryDetail } from './salaries-Rb5h_eVZ.mjs';
+import { P as PublicBoard } from './board-CqYibYUA.mjs';
+import { P as PublicJob } from './jobs-DPPA1Nev.mjs';
 import { B as BoardLabelOverrides } from './ui-copy-CKfFTtLk.mjs';
+import './_spec-DxC1ze93.mjs';
 
 /**
  * Google for Jobs `JobPosting` structured data on the `@cavuno/board` wire

package/dist/seo.d.ts

@@ -1,7 +1,8 @@
-import { P as PublicBlogPostSummary, B as BlogAuthorEmbed, C as CompanyCategorySalary, a as CompanySalary, L as LocationSalaryDetail, S as SkillSalaryDetail, T as TitleSalaryDetail } from './salaries-C3w9kvPJ.js';
-import { P as PublicBoard } from './board-D_BRa2zC.js';
-import { P as PublicJob } from './jobs-CMCADU_-.js';
+import { P as PublicBlogPostSummary, B as BlogAuthorEmbed, C as CompanyCategorySalary, a as CompanySalary, L as LocationSalaryDetail, S as SkillSalaryDetail, T as TitleSalaryDetail } from './salaries-DK4RnJnw.js';
+import { P as PublicBoard } from './board-RfZEAJse.js';
+import { P as PublicJob } from './jobs-CLLIvtMc.js';
 import { B as BoardLabelOverrides } from './ui-copy-CKfFTtLk.js';
+import './_spec-DxC1ze93.js';
 
 /**
  * Google for Jobs `JobPosting` structured data on the `@cavuno/board` wire

package/dist/server.d.mts

@@ -1,7 +1,9 @@
 import { BoardSdk } from './index.mjs';
-import './jobs-CMCADU_-.mjs';
-import './board-D0guOBYy.mjs';
-import './salaries-9U42CM5A.mjs';
+import './_spec-DxC1ze93.mjs';
+import './search-CqBa1Qc4.mjs';
+import './board-CqYibYUA.mjs';
+import './jobs-DPPA1Nev.mjs';
+import './salaries-Rb5h_eVZ.mjs';
 
 /**
  * Session cookie codec — pure (no framework imports, no node imports) so it

package/dist/server.d.ts

@@ -1,7 +1,9 @@
 import { BoardSdk } from './index.js';
-import './jobs-CMCADU_-.js';
-import './board-D_BRa2zC.js';
-import './salaries-C3w9kvPJ.js';
+import './_spec-DxC1ze93.js';
+import './search-DBoMM-gE.js';
+import './board-RfZEAJse.js';
+import './jobs-CLLIvtMc.js';
+import './salaries-DK4RnJnw.js';
 
 /**
  * Session cookie codec — pure (no framework imports, no node imports) so it

package/dist/sitemap.d.mts

@@ -1,7 +1,9 @@
 import { BoardSdk } from './index.mjs';
-import './jobs-CMCADU_-.mjs';
-import './board-D0guOBYy.mjs';
-import './salaries-9U42CM5A.mjs';
+import './_spec-DxC1ze93.mjs';
+import './search-CqBa1Qc4.mjs';
+import './board-CqYibYUA.mjs';
+import './jobs-DPPA1Nev.mjs';
+import './salaries-Rb5h_eVZ.mjs';
 
 /**
  * Sitemap primitives — the pure XML + bucket-filename logic behind a board

package/dist/sitemap.d.ts

@@ -1,7 +1,9 @@
 import { BoardSdk } from './index.js';
-import './jobs-CMCADU_-.js';
-import './board-D_BRa2zC.js';
-import './salaries-C3w9kvPJ.js';
+import './_spec-DxC1ze93.js';
+import './search-DBoMM-gE.js';
+import './board-RfZEAJse.js';
+import './jobs-CLLIvtMc.js';
+import './salaries-DK4RnJnw.js';
 
 /**
  * Sitemap primitives — the pure XML + bucket-filename logic behind a board

package/dist/suggest.d.mts

@@ -0,0 +1,70 @@
+import { S as SuggestionItem, a as SearchSuggestQuery, F as FetchOptions, b as SuggestResult } from './search-CqBa1Qc4.mjs';
+import './_spec-DxC1ze93.mjs';
+
+/**
+ * `@cavuno/board/suggest` — framework-agnostic headless search-suggest
+ * controller (Algolia autocomplete-core pattern).
+ *
+ * Owns debounce, abort, and stale-drop so tenant frontends don't re-invent
+ * them. Patches ship via npm update. Zero runtime deps; isomorphic
+ * (`globalThis` timers only — never `window`/`document`).
+ *
+ * The ONE permitted view-level filter is excluding currently-applied company
+ * slugs from results (type `company` only). Wire data is never reshaped
+ * otherwise — order stays server-ranked.
+ */
+
+interface SuggestControllerOptions {
+    /** Minimum characters before querying (default 2 — hosted parity). */
+    minChars?: number;
+    /** Debounce for setQuery → request (default 250ms). */
+    debounceMs?: number;
+    /** Server `limit` passed through (1–25). */
+    limit?: number;
+}
+type SuggestStatus = 'idle' | 'loading' | 'ready' | 'error';
+interface SuggestState {
+    readonly query: string;
+    /**
+     * Server-ranked items. Previous items are RETAINED while a new request
+     * is loading (no flash-to-empty — hosted behavior).
+     */
+    readonly items: readonly SuggestionItem[];
+    /**
+     * `'loading'` from the moment a qualifying query is set (debounce window
+     * included) until that query's request settles. `'idle'` only when the
+     * query is empty/below minChars. `'ready'` / `'error'` after settle.
+     */
+    readonly status: SuggestStatus;
+    readonly error: unknown;
+}
+interface SuggestController {
+    setQuery(query: string): void;
+    /** Company slugs to hide from results (e.g. the currently-applied filter). */
+    setExcludedCompanySlugs(slugs: readonly string[]): void;
+    getState(): SuggestState;
+    /** Returns an unsubscribe function. Compatible with useSyncExternalStore. */
+    subscribe(listener: () => void): () => void;
+    dispose(): void;
+}
+type SuggestBoard = {
+    search: {
+        suggest(q?: SearchSuggestQuery, o?: FetchOptions): Promise<SuggestResult>;
+    };
+};
+/**
+ * Create a headless suggest controller bound to a board client (or any
+ * object exposing `search.suggest`).
+ *
+ * @example
+ * import { createBoardClient } from '@cavuno/board';
+ * import { createSuggestController } from '@cavuno/board/suggest';
+ *
+ * const board = createBoardClient({ board: 'pk_…' });
+ * const suggest = createSuggestController(board);
+ * suggest.subscribe(() => render(suggest.getState()));
+ * suggest.setQuery('acme');
+ */
+declare function createSuggestController(board: SuggestBoard, options?: SuggestControllerOptions): SuggestController;
+
+export { type SuggestController, type SuggestControllerOptions, type SuggestState, type SuggestStatus, createSuggestController };

package/dist/suggest.d.ts

@@ -0,0 +1,70 @@
+import { S as SuggestionItem, a as SearchSuggestQuery, F as FetchOptions, b as SuggestResult } from './search-DBoMM-gE.js';
+import './_spec-DxC1ze93.js';
+
+/**
+ * `@cavuno/board/suggest` — framework-agnostic headless search-suggest
+ * controller (Algolia autocomplete-core pattern).
+ *
+ * Owns debounce, abort, and stale-drop so tenant frontends don't re-invent
+ * them. Patches ship via npm update. Zero runtime deps; isomorphic
+ * (`globalThis` timers only — never `window`/`document`).
+ *
+ * The ONE permitted view-level filter is excluding currently-applied company
+ * slugs from results (type `company` only). Wire data is never reshaped
+ * otherwise — order stays server-ranked.
+ */
+
+interface SuggestControllerOptions {
+    /** Minimum characters before querying (default 2 — hosted parity). */
+    minChars?: number;
+    /** Debounce for setQuery → request (default 250ms). */
+    debounceMs?: number;
+    /** Server `limit` passed through (1–25). */
+    limit?: number;
+}
+type SuggestStatus = 'idle' | 'loading' | 'ready' | 'error';
+interface SuggestState {
+    readonly query: string;
+    /**
+     * Server-ranked items. Previous items are RETAINED while a new request
+     * is loading (no flash-to-empty — hosted behavior).
+     */
+    readonly items: readonly SuggestionItem[];
+    /**
+     * `'loading'` from the moment a qualifying query is set (debounce window
+     * included) until that query's request settles. `'idle'` only when the
+     * query is empty/below minChars. `'ready'` / `'error'` after settle.
+     */
+    readonly status: SuggestStatus;
+    readonly error: unknown;
+}
+interface SuggestController {
+    setQuery(query: string): void;
+    /** Company slugs to hide from results (e.g. the currently-applied filter). */
+    setExcludedCompanySlugs(slugs: readonly string[]): void;
+    getState(): SuggestState;
+    /** Returns an unsubscribe function. Compatible with useSyncExternalStore. */
+    subscribe(listener: () => void): () => void;
+    dispose(): void;
+}
+type SuggestBoard = {
+    search: {
+        suggest(q?: SearchSuggestQuery, o?: FetchOptions): Promise<SuggestResult>;
+    };
+};
+/**
+ * Create a headless suggest controller bound to a board client (or any
+ * object exposing `search.suggest`).
+ *
+ * @example
+ * import { createBoardClient } from '@cavuno/board';
+ * import { createSuggestController } from '@cavuno/board/suggest';
+ *
+ * const board = createBoardClient({ board: 'pk_…' });
+ * const suggest = createSuggestController(board);
+ * suggest.subscribe(() => render(suggest.getState()));
+ * suggest.setQuery('acme');
+ */
+declare function createSuggestController(board: SuggestBoard, options?: SuggestControllerOptions): SuggestController;
+
+export { type SuggestController, type SuggestControllerOptions, type SuggestState, type SuggestStatus, createSuggestController };

package/dist/suggest.js

@@ -0,0 +1,165 @@
+"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/suggest/index.ts
+var suggest_exports = {};
+__export(suggest_exports, {
+  createSuggestController: () => createSuggestController
+});
+module.exports = __toCommonJS(suggest_exports);
+var DEFAULT_MIN_CHARS = 2;
+var DEFAULT_DEBOUNCE_MS = 250;
+function isAbortError(error) {
+  return typeof DOMException !== "undefined" && error instanceof DOMException && error.name === "AbortError" || error instanceof Error && error.name === "AbortError";
+}
+function applyExclusions(items, excluded) {
+  if (excluded.size === 0) return items.slice();
+  return items.filter(
+    (item) => !(item.type === "company" && excluded.has(item.slug.toLowerCase()))
+  );
+}
+function createSuggestController(board, options) {
+  const minChars = options?.minChars ?? DEFAULT_MIN_CHARS;
+  const debounceMs = options?.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+  const limit = options?.limit;
+  let disposed = false;
+  let state = {
+    query: "",
+    items: [],
+    status: "idle",
+    error: null
+  };
+  let rawItems = [];
+  let excluded = /* @__PURE__ */ new Set();
+  let sequence = 0;
+  let timer = null;
+  let abortController = null;
+  const listeners = /* @__PURE__ */ new Set();
+  function notify() {
+    for (const listener of listeners) listener();
+  }
+  function setState(next) {
+    state = next;
+    notify();
+  }
+  function cancelTimer() {
+    if (timer !== null) {
+      globalThis.clearTimeout(timer);
+      timer = null;
+    }
+  }
+  function abortInFlight() {
+    if (abortController) {
+      abortController.abort();
+      abortController = null;
+    }
+  }
+  function runRequest(query) {
+    const seq = ++sequence;
+    abortInFlight();
+    const controller = new AbortController();
+    abortController = controller;
+    const suggestQuery = { q: query };
+    if (limit !== void 0) suggestQuery.limit = limit;
+    void board.search.suggest(suggestQuery, { signal: controller.signal }).then((result) => {
+      if (disposed || seq !== sequence) return;
+      abortController = null;
+      rawItems = result.items;
+      setState({
+        query: state.query,
+        items: applyExclusions(rawItems, excluded),
+        status: "ready",
+        error: null
+      });
+    }).catch((error) => {
+      if (disposed || seq !== sequence) return;
+      if (isAbortError(error)) return;
+      abortController = null;
+      setState({
+        query: state.query,
+        items: state.items,
+        status: "error",
+        error
+      });
+    });
+  }
+  return {
+    setQuery(query) {
+      if (disposed) return;
+      const trimmed = query.trim();
+      cancelTimer();
+      if (trimmed.length < minChars) {
+        sequence += 1;
+        abortInFlight();
+        rawItems = [];
+        setState({
+          query,
+          items: [],
+          status: "idle",
+          error: null
+        });
+        return;
+      }
+      sequence += 1;
+      abortInFlight();
+      setState({
+        query,
+        items: state.items,
+        status: "loading",
+        error: null
+      });
+      timer = globalThis.setTimeout(() => {
+        timer = null;
+        if (disposed) return;
+        runRequest(trimmed);
+      }, debounceMs);
+    },
+    setExcludedCompanySlugs(slugs) {
+      if (disposed) return;
+      excluded = new Set(
+        slugs.map((s) => s.trim().toLowerCase()).filter(Boolean)
+      );
+      setState({
+        query: state.query,
+        items: applyExclusions(rawItems, excluded),
+        status: state.status,
+        error: state.error
+      });
+    },
+    getState() {
+      return state;
+    },
+    subscribe(listener) {
+      if (disposed) return () => {
+      };
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      cancelTimer();
+      abortInFlight();
+      sequence += 1;
+      listeners.clear();
+    }
+  };
+}