@cavuno/board 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,538 @@
+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' | CustomStorage;
+declare const ACCESS_TOKEN_KEY = "cavuno_board_access_token";
+declare const REFRESH_TOKEN_KEY = "cavuno_board_refresh_token";
+
+/**
+ * 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>;
+}
+
+interface PublicBoardFeatures {
+    jobAlerts: boolean;
+    candidates: boolean;
+    employers: boolean;
+    blog: boolean;
+    talentDirectory: boolean;
+    registrationWall: boolean;
+    passwordProtected: boolean;
+    publicJobSubmission: boolean;
+    candidatePaywall: boolean;
+}
+interface PublicBoardAnalytics {
+    ga4MeasurementId: string | null;
+    gtmId: string | null;
+    metaPixelId: string | null;
+    linkedInPartnerId: string | null;
+    cookieConsentRequired: boolean;
+}
+interface PublicBoardTheme {
+    mode: string;
+    schemeId: string;
+    typography: {
+        fontSans: string;
+        fontHeading?: string | null;
+    };
+    colors: Record<string, unknown>;
+}
+interface PublicBoard {
+    object: 'public_board';
+    /** Immutable board identifier (`boards_…`, ADR-0032). */
+    id: string;
+    /** Mutable canonical slug. */
+    slug: string;
+    name: string;
+    language: string;
+    logoUrl: string | null;
+    primaryDomain: string | null;
+    features: PublicBoardFeatures;
+    analytics: PublicBoardAnalytics;
+    theme: PublicBoardTheme | null;
+}
+
+/**
+ * Error raised for every non-2xx Board API response.
+ *
+ * Carries the complete v1 error envelope (`01-conventions.md` §5.2):
+ * `{ error: { code, message, details?, requestId } }` — nothing is
+ * discarded, so callers never need to string-match messages.
+ *
+ * @example
+ * try {
+ *   await board.jobs.retrieve('senior-chef');
+ * } catch (e) {
+ *   if (isNotFound(e)) showEmptyState();
+ *   else throw e;
+ * }
+ */
+declare class BoardApiError extends Error {
+    readonly status: number;
+    /** `<domain>_<snake_reason>` code from the v1 error envelope. */
+    readonly code: string;
+    /** Structured, per-code details — shape varies by `code`. */
+    readonly details?: unknown;
+    readonly requestId?: string;
+    /** The parsed response body, untouched. */
+    readonly raw: unknown;
+    constructor(input: {
+        status: number;
+        code: string;
+        message: string;
+        details?: unknown;
+        requestId?: string;
+        raw: unknown;
+    });
+}
+declare function isBoardApiError(e: unknown): e is BoardApiError;
+declare function isNotFound(e: unknown): e is BoardApiError;
+declare function isUnauthorized(e: unknown): e is BoardApiError;
+declare function isForbidden(e: unknown): e is BoardApiError;
+declare function isValidationError(e: unknown): e is BoardApiError;
+declare function isRateLimited(e: unknown): e is BoardApiError;
+declare function isConflict(e: unknown): e is BoardApiError;
+
+/**
+ * Kept in lockstep with the package.json `version` field — guarded by
+ * version.test.ts, which fails the suite on any drift. A hand-written
+ * constant because the package is platform-neutral and cannot read
+ * package.json at runtime.
+ */
+declare const SDK_VERSION = "1.0.0";
+
+interface BoardUser {
+    id: string;
+    object: 'board_user';
+    role: 'candidate' | 'employer';
+    email: string;
+    displayName: string | null;
+    emailVerified: boolean;
+}
+/**
+ * Bearer pair returned by register/login/refresh. `expiresAt` is the
+ * ACCESS token expiry in epoch ms; the refresh token's own 30-day TTL
+ * is intentionally not exposed.
+ */
+interface BoardAuthSession {
+    object: 'board_auth_session';
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+    boardUser: BoardUser;
+}
+interface RegisterBody {
+    role: 'candidate' | 'employer';
+    /** Only `emailpass` is supported. */
+    method: 'emailpass';
+    email: string;
+    password: string;
+    displayName: string;
+}
+interface LoginBody {
+    email: string;
+    password: string;
+}
+interface RefreshBody {
+    refreshToken: string;
+}
+interface LogoutBody {
+    refreshToken: string;
+}
+interface VerifyEmailBody {
+    token: string;
+}
+interface ForgotPasswordBody {
+    email: string;
+}
+interface ResetPasswordBody {
+    token: string;
+    password: string;
+}
+
+/** Author shape embedded on posts (no `object` discriminator). */
+interface BlogAuthorEmbed {
+    id: string;
+    name: string;
+    slug: string;
+    bio: string | null;
+    avatarUrl: string | null;
+    websiteUrl: string | null;
+    twitterUrl: string | null;
+    linkedinUrl: string | null;
+    githubUrl: string | null;
+}
+/** Tag shape embedded on posts (no `object` discriminator). */
+interface BlogTagEmbed {
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+}
+interface PublicBlogAuthor extends BlogAuthorEmbed {
+    object: 'public_blog_author';
+}
+interface PublicBlogTag extends BlogTagEmbed {
+    object: 'public_blog_tag';
+}
+interface PublicBlogPostSummary {
+    id: string;
+    object: 'public_blog_post';
+    title: string;
+    slug: string;
+    featured: boolean;
+    coverUrl: string | null;
+    customExcerpt: string | null;
+    readingTimeMin: number | null;
+    publishedAt: string | null;
+    createdAt: string;
+    authors: BlogAuthorEmbed[];
+    tags: BlogTagEmbed[];
+}
+/** Detail shape — `html` appears on the single read only, never on summaries. */
+interface PublicBlogPost extends PublicBlogPostSummary {
+    html: string | null;
+    ogImageUrl: string | null;
+    featureImageAlt: string | null;
+    featureImageCaption: string | null;
+    seoTitle: string | null;
+    seoDescription: string | null;
+    canonicalUrl: string | null;
+}
+type BlogPostsListQuery = {
+    cursor?: string;
+    /** 1–100. */
+    limit?: number;
+    tagSlug?: string;
+    authorSlug?: string;
+    /** Opt-in only: pass `'true'` to restrict to featured posts. */
+    featured?: 'true';
+};
+interface BlogSearchBody {
+    /** Free-text query, 1–200 characters. Required. */
+    query: string;
+    cursor?: string | null;
+    /** 1–50. */
+    limit?: number;
+}
+
+/**
+ * Stripe-shaped success envelopes (`01-conventions.md` §5.1). The
+ * server MAY add top-level fields; consumers MUST ignore unknown
+ * fields.
+ */
+interface ListEnvelope<T> {
+    object: 'list';
+    url: string;
+    hasMore: boolean;
+    /** `null` when `hasMore` is false — always present, never undefined. */
+    nextCursor: string | null;
+    data: T[];
+}
+interface SearchEnvelope<T> {
+    object: 'search_result';
+    url: string;
+    hasMore: boolean;
+    nextCursor: string | null;
+    data: T[];
+}
+
+interface PublicCompany {
+    id: string;
+    object: 'public_company';
+    name: string;
+    slug: string;
+    website: string | null;
+    logoUrl: string | null;
+    description: string | null;
+    jobCount: number;
+    publishedJobCount: number;
+    links: {
+        public: string | null;
+    };
+}
+type CompaniesListQuery = {
+    cursor?: string;
+    /** 1–100. */
+    limit?: number;
+};
+type CompanyJobsListQuery = {
+    cursor?: string;
+    /** 1–100. */
+    limit?: number;
+};
+interface CompaniesSearchBody {
+    /** Free-text query, up to 200 characters. */
+    query?: string;
+    cursor?: string;
+    /** 1–100. */
+    limit?: number;
+}
+
+type RemoteOption = 'on_site' | 'hybrid' | 'remote';
+type EmploymentType = 'full_time' | 'part_time' | 'contract' | 'internship' | 'temporary' | 'volunteer' | 'other';
+type Seniority = 'entry_level' | 'associate' | 'mid_level' | 'senior' | 'lead' | 'principal' | 'director' | 'executive';
+type EducationRequirement = 'high_school' | 'associate_degree' | 'bachelor_degree' | 'professional_certificate' | 'postgraduate_degree' | 'no_requirements';
+interface OfficeLocation {
+    countryCode: string | null;
+    country: string | null;
+    locality: string | null;
+    city: string | null;
+    region: string | null;
+    regionCode: string | null;
+    postalCode: string | null;
+    displayName: string | null;
+}
+interface JobCompany {
+    id: string;
+    name: string | null;
+    slug: string | null;
+    logoUrl: string | null;
+    website: string | null;
+}
+interface RemotePermit {
+    type: string;
+    value: string;
+}
+interface RemoteTimezone {
+    type: string;
+    value: string;
+    plusMinus?: number;
+}
+interface PublicJob {
+    id: string;
+    object: 'public_job';
+    title: string;
+    slug: string | null;
+    status: string;
+    companyId: string | null;
+    employmentType: string | null;
+    remoteOption: string | null;
+    seniority: string | null;
+    salaryMin: number | null;
+    salaryMax: number | null;
+    salaryCurrency: string | null;
+    salaryTimeframe: string | null;
+    isFeatured: boolean;
+    publishedAt: string | null;
+    expiresAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    description: string | null;
+    applicationUrl: string | null;
+    /** Canonical hierarchical permit selection. */
+    remotePermits: RemotePermit[];
+    /** Read-only — derived from `remotePermits`. */
+    remoteWorldwide: boolean | null;
+    /** Canonical hierarchical timezone selection. */
+    remoteTimezones: RemoteTimezone[];
+    /** Read-only — derived from `remoteTimezones`. */
+    remoteAllowedTzOffsets: number[];
+    /** Read-only — derived from `remotePermits`. */
+    remoteWorkPermitCountryCodes: string[];
+    /** Read-only — derived from `remotePermits`. */
+    remoteWorkPermitSubdivisionCodes: string[];
+    remoteSponsorship: 'yes' | 'no' | 'unknown';
+    educationRequirements: EducationRequirement[];
+    experienceMonths: number | null;
+    experienceInPlaceOfEducation: boolean | null;
+    inOfficePeriod: 'per_week' | 'per_month' | 'per_year' | null;
+    inOfficeFrequency: number | null;
+    company: JobCompany | null;
+    officeLocations: OfficeLocation[];
+    links: {
+        public: string | null;
+    };
+}
+type JobsListQuery = {
+    cursor?: string;
+    /** 1–100. */
+    limit?: number;
+    companyId?: string;
+    remoteOption?: RemoteOption;
+    employmentType?: EmploymentType;
+    seniority?: Seniority;
+};
+interface JobsSearchBody {
+    /** Free-text query, up to 200 characters. */
+    query?: string;
+    filters?: {
+        /** Up to 10 values each. */
+        companyId?: string[];
+        remoteOption?: RemoteOption[];
+        employmentType?: EmploymentType[];
+        seniority?: Seniority[];
+        /** ISO 8601 datetime bounds. */
+        publishedAt?: {
+            gte?: string;
+            lte?: string;
+        };
+    };
+    cursor?: string;
+    /** 1–100. */
+    limit?: number;
+}
+
+/**
+ * The embedded `job` is the SAME `public_job` shape the anonymous jobs
+ * list emits — saved rows and search rows render with one component.
+ */
+interface SavedJob {
+    id: string;
+    object: 'saved_job';
+    jobId: string;
+    /** ISO 8601. */
+    savedAt: string;
+    job: PublicJob;
+}
+type SavedJobsListQuery = {
+    cursor?: string;
+    /** 1–100. */
+    limit?: number;
+};
+interface SaveJobBody {
+    jobId: string;
+}
+
+interface CreateBoardClientOptions {
+    baseUrl: string;
+    /** Board identifier: `pk_…` key (provisioned default) | `boards_…` ID | slug. */
+    board: string;
+    auth?: {
+        /** Default: `'memory'` in the browser, `'nostore'` on the server. */
+        storage?: StorageMode;
+    };
+    globalHeaders?: Record<string, string>;
+    onRequest?: (req: BoardRequest) => Awaitable<BoardRequest>;
+    onResponse?: (res: Response, req: BoardRequest) => Awaitable<void>;
+    logger?: Logger;
+}
+/**
+ * Create a Board API client.
+ *
+ * Isomorphic (browser, Workers, Node ≥ 20), zero dependencies. One
+ * module-scoped instance is safe under SSR as long as per-user state
+ * stays per-call (`options.headers`) rather than in `auth.storage`.
+ *
+ * @example
+ * import { createBoardClient } from '@cavuno/board';
+ *
+ * const board = createBoardClient({
+ *   baseUrl: 'https://api.cavuno.com',
+ *   board: 'pk_a8f3…',
+ * });
+ * const { data } = await board.jobs.list({ limit: 20 });
+ */
+declare function createBoardClient(options: CreateBoardClientOptions): {
+    /**
+     * 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: BoardClient;
+    /**
+     * Board context — identity, features, analytics, theme.
+     *
+     * @example
+     * const { name, theme } = await board.context();
+     */
+    context(options?: FetchOptions): Promise<PublicBoard>;
+    jobs: {
+        list(query?: JobsListQuery, options?: FetchOptions): Promise<ListEnvelope<PublicJob>>;
+        retrieve(jobSlug: string, query?: Record<string, never>, options?: FetchOptions): Promise<PublicJob>;
+        search(body: JobsSearchBody, query?: Record<string, never>, options?: FetchOptions): Promise<SearchEnvelope<PublicJob>>;
+    };
+    companies: {
+        list(query?: CompaniesListQuery, options?: FetchOptions): Promise<ListEnvelope<PublicCompany>>;
+        retrieve(companySlug: string, query?: Record<string, never>, options?: FetchOptions): Promise<PublicCompany>;
+        search(body: CompaniesSearchBody, query?: Record<string, never>, options?: FetchOptions): Promise<SearchEnvelope<PublicCompany>>;
+        listJobs(companySlug: string, query?: CompanyJobsListQuery, options?: FetchOptions): Promise<ListEnvelope<PublicJob>>;
+    };
+    blog: {
+        posts: {
+            list(query?: BlogPostsListQuery, options?: FetchOptions): Promise<ListEnvelope<PublicBlogPostSummary>>;
+            retrieve(postSlug: string, query?: Record<string, never>, options?: FetchOptions): Promise<PublicBlogPost>;
+        };
+        tags: {
+            list(query?: Record<string, never>, options?: FetchOptions): Promise<ListEnvelope<PublicBlogTag>>;
+            retrieve(tagSlug: string, query?: Record<string, never>, options?: FetchOptions): Promise<PublicBlogTag>;
+        };
+        authors: {
+            list(query?: Record<string, never>, options?: FetchOptions): Promise<ListEnvelope<PublicBlogAuthor>>;
+            retrieve(authorSlug: string, query?: Record<string, never>, options?: FetchOptions): Promise<PublicBlogAuthor>;
+        };
+        search(body: BlogSearchBody, query?: Record<string, never>, options?: FetchOptions): Promise<SearchEnvelope<PublicBlogPostSummary>>;
+    };
+    auth: {
+        register(body: RegisterBody, options?: FetchOptions): Promise<BoardAuthSession>;
+        login(body: LoginBody, options?: FetchOptions): Promise<BoardAuthSession>;
+        refresh(body?: RefreshBody, options?: FetchOptions): Promise<BoardAuthSession>;
+        logout(body?: LogoutBody, options?: FetchOptions): Promise<void>;
+        verifyEmail(body: VerifyEmailBody, options?: FetchOptions): Promise<void>;
+        forgotPassword(body: ForgotPasswordBody, options?: FetchOptions): Promise<void>;
+        resetPassword(body: ResetPasswordBody, options?: FetchOptions): Promise<void>;
+    };
+    me: {
+        retrieve(query?: Record<string, never>, options?: FetchOptions): Promise<BoardUser>;
+        savedJobs: {
+            list(query?: SavedJobsListQuery, options?: FetchOptions): Promise<ListEnvelope<SavedJob>>;
+            save(body: SaveJobBody, query?: Record<string, never>, options?: FetchOptions): Promise<SavedJob>;
+            unsave(jobId: string, query?: Record<string, never>, options?: FetchOptions): Promise<void>;
+        };
+    };
+};
+type BoardSdk = ReturnType<typeof createBoardClient>;
+
+export { ACCESS_TOKEN_KEY, type Awaitable, type BlogAuthorEmbed, type BlogPostsListQuery, type BlogSearchBody, type BlogTagEmbed, BoardApiError, type BoardAuthSession, BoardClient, type BoardRequest, type BoardSdk, type BoardUser, type CompaniesListQuery, type CompaniesSearchBody, type CompanyJobsListQuery, type CreateBoardClientOptions, type CustomStorage, type EducationRequirement, type EmploymentType, type FetchOptions, type ForgotPasswordBody, type JobCompany, type JobsListQuery, type JobsSearchBody, type ListEnvelope, type Logger, type LoginBody, type LogoutBody, type OfficeLocation, type PublicBlogAuthor, type PublicBlogPost, type PublicBlogPostSummary, type PublicBlogTag, type PublicBoard, type PublicBoardAnalytics, type PublicBoardFeatures, type PublicBoardTheme, type PublicCompany, type PublicJob, REFRESH_TOKEN_KEY, type RefreshBody, type RegisterBody, type RemoteOption, type RemotePermit, type RemoteTimezone, type ResetPasswordBody, SDK_VERSION, type SaveJobBody, type SavedJob, type SavedJobsListQuery, type SearchEnvelope, type Seniority, type StorageMode, type VerifyEmailBody, createBoardClient, isBoardApiError, isConflict, isForbidden, isNotFound, isRateLimited, isUnauthorized, isValidationError };