@cavuno/board 1.0.0

package/dist/index.mjs

@@ -0,0 +1,621 @@
+// src/errors.ts
+var BoardApiError = class extends Error {
+  status;
+  /** `<domain>_<snake_reason>` code from the v1 error envelope. */
+  code;
+  /** Structured, per-code details — shape varies by `code`. */
+  details;
+  requestId;
+  /** The parsed response body, untouched. */
+  raw;
+  constructor(input) {
+    super(input.message);
+    this.name = "BoardApiError";
+    this.status = input.status;
+    this.code = input.code;
+    this.details = input.details;
+    this.requestId = input.requestId;
+    this.raw = input.raw;
+  }
+};
+function isBoardApiError(e) {
+  return e instanceof BoardApiError;
+}
+function isNotFound(e) {
+  return isBoardApiError(e) && e.status === 404;
+}
+function isUnauthorized(e) {
+  return isBoardApiError(e) && e.status === 401;
+}
+function isForbidden(e) {
+  return isBoardApiError(e) && e.status === 403;
+}
+function isValidationError(e) {
+  return isBoardApiError(e) && e.status === 400 && e.code === "validation_bad_request";
+}
+function isRateLimited(e) {
+  return isBoardApiError(e) && e.status === 429;
+}
+function isConflict(e) {
+  return isBoardApiError(e) && e.status === 409;
+}
+
+// src/query.ts
+function toSearchParams(query) {
+  const params = new URLSearchParams();
+  if (!query) return params;
+  for (const [key, value] of Object.entries(query)) {
+    if (value === void 0 || value === null) continue;
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (item === void 0 || item === null) continue;
+        params.append(key, String(item));
+      }
+    } else {
+      params.append(key, String(value));
+    }
+  }
+  return params;
+}
+
+// src/storage.ts
+var ACCESS_TOKEN_KEY = "cavuno_board_access_token";
+var REFRESH_TOKEN_KEY = "cavuno_board_refresh_token";
+function isBrowser() {
+  return typeof globalThis.document !== "undefined";
+}
+function memoryStorage() {
+  const backing = /* @__PURE__ */ new Map();
+  return {
+    getItem: (key) => backing.get(key) ?? null,
+    setItem: (key, value) => {
+      backing.set(key, value);
+    },
+    removeItem: (key) => {
+      backing.delete(key);
+    }
+  };
+}
+var NOSTORE = {
+  getItem: () => null,
+  setItem: () => {
+  },
+  removeItem: () => {
+  }
+};
+function resolveStorage(mode) {
+  const resolved = mode ?? (isBrowser() ? "memory" : "nostore");
+  if (typeof resolved === "object") return resolved;
+  switch (resolved) {
+    case "memory":
+      return memoryStorage();
+    case "nostore":
+      return NOSTORE;
+    default:
+      throw new Error(`Unknown storage mode '${String(resolved)}'`);
+  }
+}
+async function writeSession(storage, session) {
+  await storage.setItem(ACCESS_TOKEN_KEY, session.accessToken);
+  await storage.setItem(REFRESH_TOKEN_KEY, session.refreshToken);
+}
+async function clearSession(storage) {
+  await storage.removeItem(ACCESS_TOKEN_KEY);
+  await storage.removeItem(REFRESH_TOKEN_KEY);
+}
+
+// src/version.ts
+var SDK_VERSION = "1.0.0";
+
+// src/client.ts
+function isRawBody(body) {
+  return typeof body === "string" || body instanceof URLSearchParams || typeof FormData !== "undefined" && body instanceof FormData || typeof Blob !== "undefined" && body instanceof Blob || body instanceof ArrayBuffer || typeof ReadableStream !== "undefined" && body instanceof ReadableStream;
+}
+var BoardClient = class {
+  storage;
+  basePath;
+  options;
+  constructor(options) {
+    this.options = options;
+    this.storage = options.storage;
+    const baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.basePath = `${baseUrl}/v1/boards/${encodeURIComponent(options.board)}`;
+  }
+  /**
+   * 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');
+   */
+  async fetch(path, init = {}) {
+    const { body, query, headers: callHeaders, ...passthrough } = init;
+    const method = (init.method ?? "GET").toUpperCase();
+    let url = `${this.basePath}${path}`;
+    const params = toSearchParams(query);
+    const search = params.toString();
+    if (search) url += `?${search}`;
+    const jsonBody = body !== void 0 && !isRawBody(body);
+    const serializedBody = body === void 0 ? void 0 : jsonBody ? JSON.stringify(body) : body;
+    const headers = new Headers({ accept: "application/json" });
+    if (jsonBody) headers.set("content-type", "application/json");
+    for (const [key, value] of Object.entries(
+      this.options.globalHeaders ?? {}
+    )) {
+      headers.set(key, value);
+    }
+    const token = await this.storage.getItem(ACCESS_TOKEN_KEY);
+    if (token !== null) headers.set("authorization", `Bearer ${token}`);
+    if (callHeaders) {
+      new Headers(callHeaders).forEach((value, key) => {
+        headers.set(key, value);
+      });
+    }
+    if ((method !== "GET" || headers.has("authorization")) && !headers.has("x-cavuno-sdk")) {
+      headers.set("x-cavuno-sdk", `board@${SDK_VERSION}`);
+    }
+    let req = {
+      url,
+      init: { ...passthrough, method, headers, body: serializedBody }
+    };
+    if (this.options.onRequest) req = await this.options.onRequest(req);
+    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 (res.status === 204) return void 0;
+    if (res.ok) return await res.json();
+    let parsed;
+    try {
+      parsed = await res.json();
+    } catch {
+      parsed = void 0;
+    }
+    const envelope = parsed?.error;
+    const error = envelope && typeof envelope.code === "string" && typeof envelope.message === "string" ? new BoardApiError({
+      status: res.status,
+      code: envelope.code,
+      message: envelope.message,
+      details: envelope.details,
+      requestId: envelope.requestId,
+      raw: parsed
+    }) : new BoardApiError({
+      status: res.status,
+      code: "unknown_error",
+      message: res.statusText || "Request failed",
+      raw: parsed
+    });
+    this.options.logger?.error(
+      `${error.status} ${error.code} ${method} ${req.url}`
+    );
+    throw error;
+  }
+};
+
+// src/namespaces/auth.ts
+function authNamespace(client) {
+  async function persist(session) {
+    await writeSession(client.storage, session);
+    return session;
+  }
+  async function resolveRefreshToken(body) {
+    if (body?.refreshToken) return body.refreshToken;
+    const stored = await client.storage.getItem(REFRESH_TOKEN_KEY);
+    if (stored === null) {
+      throw new Error(
+        "No refresh token available \u2014 pass { refreshToken } or configure auth.storage"
+      );
+    }
+    return stored;
+  }
+  return {
+    /**
+     * Register a board user (emailpass). Persists the returned token
+     * pair to storage and returns the session.
+     *
+     * @example
+     * await board.auth.register({
+     *   role: 'candidate',
+     *   method: 'emailpass',
+     *   email: 'a@b.com',
+     *   password: 'hunter22',
+     *   displayName: 'Ada',
+     * });
+     */
+    async register(body, options) {
+      const session = await client.fetch("/auth/register", {
+        ...options,
+        method: "POST",
+        body
+      });
+      return persist(session);
+    },
+    /**
+     * Log in with email + password. Persists the returned token pair to
+     * storage and returns the session. The SDK never navigates — the
+     * host app owns any redirect/verification UX.
+     *
+     * @example
+     * const { boardUser } = await board.auth.login({
+     *   email: 'a@b.com',
+     *   password: 'hunter22',
+     * });
+     */
+    async login(body, options) {
+      const session = await client.fetch("/auth/login", {
+        ...options,
+        method: "POST",
+        body
+      });
+      return persist(session);
+    },
+    /**
+     * Rotate the refresh token for a new bearer pair. Refresh tokens
+     * are single-use; the rotated pair is persisted to storage. There
+     * is no automatic refresh on 401 — call this explicitly.
+     *
+     * @example
+     * await board.auth.refresh(); // uses the stored refresh token
+     */
+    async refresh(body, options) {
+      const refreshToken = await resolveRefreshToken(body);
+      const session = await client.fetch("/auth/refresh", {
+        ...options,
+        method: "POST",
+        body: { refreshToken }
+      });
+      return persist(session);
+    },
+    /**
+     * Revoke the refresh token and clear stored tokens. Idempotent
+     * server-side (204 even for unknown tokens). If the request itself
+     * fails (network error, 5xx), stored tokens are deliberately kept —
+     * clearing them would leave a live refresh token server-side while
+     * the client believes it's logged out. Catch and retry, or clear
+     * storage yourself to force a local logout.
+     *
+     * @example
+     * await board.auth.logout();
+     */
+    async logout(body, options) {
+      const refreshToken = await resolveRefreshToken(body);
+      await client.fetch("/auth/logout", {
+        ...options,
+        method: "POST",
+        body: { refreshToken }
+      });
+      await clearSession(client.storage);
+    },
+    /**
+     * Confirm an email-verification token (sent by register).
+     *
+     * @example
+     * await board.auth.verifyEmail({ token });
+     */
+    verifyEmail(body, options) {
+      return client.fetch("/auth/verify-email", {
+        ...options,
+        method: "POST",
+        body
+      });
+    },
+    /**
+     * Request a password-reset email. Always resolves (204) whether or
+     * not the email exists — no account oracle.
+     *
+     * @example
+     * await board.auth.forgotPassword({ email: 'a@b.com' });
+     */
+    forgotPassword(body, options) {
+      return client.fetch("/auth/forgot-password", {
+        ...options,
+        method: "POST",
+        body
+      });
+    },
+    /**
+     * Set a new password with a reset token. The token is single-use;
+     * all existing sessions are invalidated server-side.
+     *
+     * @example
+     * await board.auth.resetPassword({ token, password: 'newpass99' });
+     */
+    resetPassword(body, options) {
+      return client.fetch("/auth/reset-password", {
+        ...options,
+        method: "POST",
+        body
+      });
+    }
+  };
+}
+
+// src/namespaces/blog.ts
+function blogNamespace(client) {
+  return {
+    posts: {
+      /**
+       * List published posts (summaries — no `html`).
+       *
+       * @example
+       * const { data } = await board.blog.posts.list({ tagSlug: 'news' });
+       */
+      list(query, options) {
+        return client.fetch(
+          "/blog/posts",
+          { ...options, query }
+        );
+      },
+      /**
+       * Retrieve one post by slug, including its `html` body.
+       *
+       * @example
+       * const post = await board.blog.posts.retrieve('hello-world');
+       */
+      retrieve(postSlug, query, options) {
+        return client.fetch(
+          `/blog/posts/${encodeURIComponent(postSlug)}`,
+          { ...options, query }
+        );
+      }
+    },
+    tags: {
+      /** @example const { data } = await board.blog.tags.list(); */
+      list(query, options) {
+        return client.fetch("/blog/tags", {
+          ...options,
+          query
+        });
+      },
+      /** @example const tag = await board.blog.tags.retrieve('news'); */
+      retrieve(tagSlug, query, options) {
+        return client.fetch(
+          `/blog/tags/${encodeURIComponent(tagSlug)}`,
+          { ...options, query }
+        );
+      }
+    },
+    authors: {
+      /** @example const { data } = await board.blog.authors.list(); */
+      list(query, options) {
+        return client.fetch("/blog/authors", {
+          ...options,
+          query
+        });
+      },
+      /** @example const author = await board.blog.authors.retrieve('jane'); */
+      retrieve(authorSlug, query, options) {
+        return client.fetch(
+          `/blog/authors/${encodeURIComponent(authorSlug)}`,
+          { ...options, query }
+        );
+      }
+    },
+    /**
+     * Free-text post search (returns post summaries).
+     *
+     * @example
+     * const { data } = await board.blog.search({ query: 'launch' });
+     */
+    search(body, query, options) {
+      return client.fetch(
+        "/blog/search",
+        { ...options, method: "POST", body, query }
+      );
+    }
+  };
+}
+
+// src/namespaces/companies.ts
+function companiesNamespace(client) {
+  return {
+    /**
+     * List companies on the board.
+     *
+     * @example
+     * const { data } = await board.companies.list({ limit: 20 });
+     */
+    list(query, options) {
+      return client.fetch("/companies", {
+        ...options,
+        query
+      });
+    },
+    /**
+     * Retrieve one company by slug.
+     *
+     * @example
+     * const company = await board.companies.retrieve('acme');
+     */
+    retrieve(companySlug, query, options) {
+      return client.fetch(
+        `/companies/${encodeURIComponent(companySlug)}`,
+        { ...options, query }
+      );
+    },
+    /**
+     * Free-text company search.
+     *
+     * @example
+     * const { data } = await board.companies.search({ query: 'acme' });
+     */
+    search(body, query, options) {
+      return client.fetch("/companies/search", {
+        ...options,
+        method: "POST",
+        body,
+        query
+      });
+    },
+    /**
+     * List one company's published jobs.
+     *
+     * @example
+     * const { data } = await board.companies.listJobs('acme', { limit: 10 });
+     */
+    listJobs(companySlug, query, options) {
+      return client.fetch(
+        `/companies/${encodeURIComponent(companySlug)}/jobs`,
+        { ...options, query }
+      );
+    }
+  };
+}
+
+// src/namespaces/jobs.ts
+function jobsNamespace(client) {
+  return {
+    /**
+     * List published jobs.
+     *
+     * @example
+     * const { data, nextCursor } = await board.jobs.list({ limit: 20 });
+     */
+    list(query, options) {
+      return client.fetch("/jobs", {
+        ...options,
+        query
+      });
+    },
+    /**
+     * Retrieve one published job by slug.
+     *
+     * @example
+     * const job = await board.jobs.retrieve('senior-chef');
+     */
+    retrieve(jobSlug, query, options) {
+      return client.fetch(`/jobs/${encodeURIComponent(jobSlug)}`, {
+        ...options,
+        query
+      });
+    },
+    /**
+     * Free-text + faceted job search.
+     *
+     * @example
+     * const { data } = await board.jobs.search({
+     *   query: 'chef',
+     *   filters: { seniority: ['senior'] },
+     * });
+     */
+    search(body, query, options) {
+      return client.fetch("/jobs/search", {
+        ...options,
+        method: "POST",
+        body,
+        query
+      });
+    }
+  };
+}
+
+// src/namespaces/me.ts
+function meNamespace(client) {
+  return {
+    /**
+     * Retrieve the authenticated board user.
+     *
+     * @example
+     * const me = await board.me.retrieve();
+     */
+    // `query?: Record<string, never>` = no query params today; the slot
+    // holds the locked (id, query?, options?) shape and widens to a real
+    // query type without breaking callers when the API grows one.
+    retrieve(query, options) {
+      return client.fetch("/me", { ...options, query });
+    },
+    savedJobs: {
+      /**
+       * List the authenticated user's saved jobs (each embeds the full
+       * `public_job`).
+       *
+       * @example
+       * const { data } = await board.me.savedJobs.list({ limit: 20 });
+       */
+      list(query, options) {
+        return client.fetch("/me/saved-jobs", {
+          ...options,
+          query
+        });
+      },
+      /**
+       * Save a job. Converges — saving an already-saved job returns the
+       * identical row.
+       *
+       * @example
+       * await board.me.savedJobs.save({ jobId: job.id });
+       */
+      save(body, query, options) {
+        return client.fetch("/me/saved-jobs", {
+          ...options,
+          method: "POST",
+          body,
+          query
+        });
+      },
+      /**
+       * Unsave a job. Idempotent — unknown IDs still 204.
+       *
+       * @example
+       * await board.me.savedJobs.unsave(job.id);
+       */
+      unsave(jobId, query, options) {
+        return client.fetch(
+          `/me/saved-jobs/${encodeURIComponent(jobId)}`,
+          { ...options, method: "DELETE", query }
+        );
+      }
+    }
+  };
+}
+
+// src/index.ts
+function createBoardClient(options) {
+  const client = new BoardClient({
+    baseUrl: options.baseUrl,
+    board: options.board,
+    storage: resolveStorage(options.auth?.storage),
+    globalHeaders: options.globalHeaders,
+    onRequest: options.onRequest,
+    onResponse: options.onResponse,
+    logger: options.logger
+  });
+  return {
+    /**
+     * Escape hatch: raw typed request through the full pipeline (board
+     * base path, default headers, bearer token, hooks). Custom
+     * endpoints work without an SDK release.
+     */
+    client,
+    /**
+     * Board context — identity, features, analytics, theme.
+     *
+     * @example
+     * const { name, theme } = await board.context();
+     */
+    context(options2) {
+      return client.fetch("", options2);
+    },
+    jobs: jobsNamespace(client),
+    companies: companiesNamespace(client),
+    blog: blogNamespace(client),
+    auth: authNamespace(client),
+    me: meNamespace(client)
+  };
+}
+export {
+  ACCESS_TOKEN_KEY,
+  BoardApiError,
+  BoardClient,
+  REFRESH_TOKEN_KEY,
+  SDK_VERSION,
+  createBoardClient,
+  isBoardApiError,
+  isConflict,
+  isForbidden,
+  isNotFound,
+  isRateLimited,
+  isUnauthorized,
+  isValidationError
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@cavuno/board",
+  "version": "1.0.0",
+  "description": "Typed isomorphic client for the Cavuno Board API",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wollemiahq/cavuno.git",
+    "directory": "packages/board-sdk"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "24.9.1",
+    "tsup": "^8.4.0",
+    "vitest": "^2.1.9",
+    "@kit/tsconfig": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "git clean -xdf .turbo dist node_modules",
+    "typecheck": "tsgo --noEmit",
+    "test": "vitest run",
+    "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')}\""
+  }
+}