@cavuno/board 1.2.1 → 1.4.0

package/dist/index.d.ts

@@ -252,6 +252,8 @@ interface CustomStorage {
 type StorageMode = 'memory' | 'nostore' | 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
@@ -340,6 +342,8 @@ interface PublicBoard {
     language: string;
     logoUrl: string | null;
     primaryDomain: string | null;
+    /** Whitelabel toggle (default `true`) — render the "Powered by Cavuno" badge unless `false`. */
+    showCavunoBranding: boolean;
     features: PublicBoardFeatures;
     analytics: PublicBoardAnalytics;
     theme: PublicBoardTheme | null;
@@ -364,6 +368,24 @@ interface BoardSeo {
      * canonical links from it — NOT the request origin.
      */
     canonicalBase: string;
+    /**
+     * Absolute URLs for the board's configured favicons / app icons (null when
+     * unset). The variant key implies the role + size; build `<link rel="icon">`
+     * tags + the web-manifest icon list from these.
+     */
+    icons: {
+        ico: string | null;
+        svg: string | null;
+        appleTouch: string | null;
+        icon192: string | null;
+        icon512: string | null;
+        iconMaskable512: string | null;
+    };
+    /** Web-manifest metadata; assemble `site.webmanifest` from this + `icons`. */
+    manifest: {
+        name: string;
+        themeColor: string;
+    };
 }
 
 /**
@@ -402,6 +424,12 @@ declare class BoardApiError extends Error {
 declare function isBoardApiError(e: unknown): e is BoardApiError;
 declare function isNotFound(e: unknown): e is BoardApiError;
 declare function isUnauthorized(e: unknown): e is BoardApiError;
+/**
+ * The board is password-protected and the read carried no valid `X-Board-Access`
+ * grant. Distinct from an expired board-USER token (also 401): this code means
+ * "call `password.verify()` again to mint a fresh grant", not "re-login".
+ */
+declare function isBoardPasswordRequired(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;
@@ -413,7 +441,7 @@ declare function isConflict(e: unknown): e is BoardApiError;
  * constant because the package is platform-neutral and cannot read
  * package.json at runtime.
  */
-declare const SDK_VERSION = "1.2.1";
+declare const SDK_VERSION = "1.4.0";
 
 interface BoardUser {
     id: string;
@@ -464,6 +492,41 @@ interface ResetPasswordBody {
     password: string;
 }
 
+/**
+ * Query for `board.embed.jobs()` — the embeddable, UNGATED jobs widget. Mirrors
+ * the browse list's facets + geo, plus a free-text `q` keyword (the widget is
+ * searchable). Deliberately has NO `category`/`skill` programmatic seeding and
+ * NO `fields` sparse fieldset — the embed widget exposes none of those.
+ */
+type EmbedJobsQuery = {
+    /** Free-text search query, up to 200 characters. */
+    q?: string;
+    cursor?: string;
+    /** Default 8; values above the embed ceiling of 50 are clamped to 50. */
+    limit?: number;
+    /** Storefront page offset; takes precedence over `cursor`. `offset + limit` ≤ 10,000. */
+    offset?: number;
+    /** Single or repeated (up to 10) — repeated params are OR-matched. */
+    companyId?: string | string[];
+    remoteOption?: RemoteOption | RemoteOption[];
+    employmentType?: EmploymentType | EmploymentType[];
+    seniority?: Seniority | Seniority[];
+    /** Place slug for a geo radius search; unresolvable slugs are ignored. */
+    location?: string;
+    /** Radius in km around `location` (10–250; default 50). */
+    radius?: number;
+};
+
+/**
+ * The board-access grant returned by `password.verify()`. Send `token` as the
+ * `X-Board-Access` header on content reads to pass a board's password wall
+ * (the SDK does this automatically once the grant is stored).
+ */
+interface BoardAccessGrant {
+    object: 'board_access_grant';
+    token: string;
+}
+
 /**
  * The result of resolving a path against the board's configured redirects
  * (`board.redirects.resolve()`). A headless frontend 308s to `target`, or 404s
@@ -477,6 +540,29 @@ interface RedirectResolution {
     target: string | null;
 }
 
+/**
+ * A board legal/about page (ADR-0039 transitional portable-prose field). The
+ * API serves owner-authored prose as portable HTML; the starter authors the
+ * layout + JSON-LD. Impressum additionally carries structured legal-entity
+ * facts and is gated by the board's `impressumEnabled` flag (404 when off).
+ */
+type LegalPageType = 'terms-of-service' | 'privacy-policy' | 'cookie-policy' | 'about' | 'impressum';
+interface LegalEntity {
+    legalName: string | null;
+    address: string | null;
+}
+interface PublicLegalPage {
+    object: 'legal_page';
+    type: string;
+    /** Page heading (H1), with `{{board_name}}` resolved. */
+    title: string;
+    /** Owner-authored prose as portable HTML; `''` when the page has no body. */
+    content: string;
+    contentFormat: 'html';
+    /** Structured impressum facts; `null` for non-impressum pages. */
+    legalEntity: LegalEntity | null;
+}
+
 /** Author shape embedded on posts (no `object` discriminator). */
 interface BlogAuthorEmbed {
     id: string;
@@ -509,9 +595,13 @@ interface PublicBlogPostSummary {
     slug: string;
     featured: boolean;
     coverUrl: string | null;
+    /** Alt text for `coverUrl` (the cover/feature image). */
+    featureImageAlt: string | null;
     customExcerpt: string | null;
     readingTimeMin: number | null;
     publishedAt: string | null;
+    /** A custom canonical URL override for this post, if set. */
+    canonicalUrl: string | null;
     createdAt: string;
     authors: BlogAuthorEmbed[];
     tags: BlogTagEmbed[];
@@ -520,11 +610,22 @@ interface PublicBlogPostSummary {
 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;
+    /**
+     * Slug-history resolution. When the requested slug is a renamed post's OLD
+     * slug, `redirected` is `true` and `newSlug` is the post's current slug —
+     * issue a 308 to it. Otherwise `redirected` is `false` and `newSlug` is null.
+     */
+    redirected: boolean;
+    newSlug: string | null;
+}
+/** Previous (older) + next (newer) posts for the detail prev/next nav. */
+interface PublicBlogAdjacentPosts {
+    object: 'blog_adjacent_posts';
+    previous: PublicBlogPostSummary | null;
+    next: PublicBlogPostSummary | null;
 }
 type BlogPostsListQuery = {
     cursor?: string;
@@ -535,6 +636,10 @@ type BlogPostsListQuery = {
     /** Opt-in only: pass `'true'` to restrict to featured posts. */
     featured?: 'true';
 };
+type BlogSimilarQuery = {
+    /** 1–20; default 6. */
+    limit?: number;
+};
 interface BlogSearchBody {
     /** Free-text query, 1–200 characters. Required. */
     query: string;
@@ -567,6 +672,21 @@ type CompanyJobsListQuery = {
     /** 1–100. */
     limit?: number;
 };
+type CompanySimilarQuery = {
+    /** 1–20, default 6. */
+    limit?: number;
+};
+interface CompanyMarket {
+    object: 'company_market';
+    slug: string;
+    name: string;
+    companyCount: number;
+}
+type CompanyMarketsListQuery = {
+    /** 1–200, default 100 (a top-by-company-count preview). */
+    limit?: number;
+    search?: string;
+};
 interface CompaniesSearchBody {
     /** Free-text query, up to 200 characters. */
     query?: string;
@@ -596,6 +716,109 @@ interface SaveJobBody {
     jobId: string;
 }
 
+type JobAlertFrequency = 'daily' | 'weekly';
+type JobAlertRemoteOption = 'on_site' | 'hybrid' | 'remote';
+/**
+ * Alert filters a consumer can capture. Only `jobFunctions` (→ job categories),
+ * `placeSlugs` (→ place IDs) and `remoteOptions` scope the digest server-side;
+ * `seniorityLevels`/`salary*` are stored but do not filter delivery.
+ */
+type JobAlertFiltersInput = {
+    jobFunctions?: string[];
+    seniorityLevels?: string[];
+    remoteOptions?: JobAlertRemoteOption[];
+    placeSlugs?: string[];
+    salaryMin?: number;
+    salaryMax?: number;
+    salaryCurrency?: string;
+};
+/** Body for `jobAlerts.subscribe`. `consent` must be `true` (server-enforced). */
+type JobAlertSubscribeInput = {
+    email: string;
+    consent: true;
+    frequency?: JobAlertFrequency;
+    filters?: JobAlertFiltersInput;
+    /** Scopes the alert to the originating job/search (for the digest + analytics). */
+    context?: {
+        source?: string;
+        jobId?: string;
+        jobSlug?: string;
+    };
+};
+interface JobAlertSubscription {
+    object: 'job_alert_subscription';
+    status: 'created' | 'duplicate';
+    requiresConfirmation: boolean;
+    confirmed: boolean;
+}
+interface JobAlertConfirmation {
+    object: 'job_alert_confirmation';
+    status: 'confirmed' | 'already_confirmed' | 'expired' | 'not_found';
+}
+interface JobAlertResendResult {
+    object: 'job_alert_confirmation_resend';
+    status: 'sent' | 'not_found' | 'already_confirmed' | 'throttled' | 'send_failed';
+}
+interface JobAlertManageResult {
+    object: 'job_alert_manage_result';
+    success: boolean;
+}
+/**
+ * The stored filter criteria surfaced on the manage page (a serializable subset
+ * of the internal filter object — the fields a consumer renders). `jobFunctions`,
+ * `placeIds` and `remoteOptions` are the dimensions the digest actually matches on.
+ */
+interface JobAlertStoredFilters {
+    jobFunctions?: string[];
+    seniorityLevels?: string[];
+    remoteOptions?: string[];
+    placeIds?: string[];
+    salaryMin?: number | null;
+    salaryMax?: number | null;
+    salaryCurrency?: string | null;
+    frequency?: string;
+}
+interface JobAlertPreference {
+    id: string;
+    label: string | null;
+    frequency: string;
+    isActive: boolean;
+    filters: JobAlertStoredFilters;
+    /** Per-preference HMAC token for `updatePreference`/`deletePreference`. */
+    manageToken: string;
+}
+interface JobAlertManageState {
+    object: 'job_alert_manage_state';
+    email: string;
+    confirmed: boolean;
+    unsubscribed: boolean;
+    preferences: JobAlertPreference[];
+}
+/** Query for `jobAlerts.manage` — the HMAC manage token from the digest email. */
+type JobAlertManageQuery = {
+    subscription: string;
+    token: string;
+};
+/** Body for `jobAlerts.unsubscribe` / `resubscribe` (HMAC manage token). */
+type JobAlertManageTokenInput = {
+    subscriptionId: string;
+    token: string;
+    preferenceId?: string;
+};
+type JobAlertUpdatePreferenceInput = {
+    subscriptionId: string;
+    preferenceId: string;
+    token: string;
+    /** Required — the update is a full replace; restate it to avoid resetting cadence. */
+    frequency: JobAlertFrequency;
+    filters?: JobAlertFiltersInput;
+};
+type JobAlertDeletePreferenceInput = {
+    subscriptionId: string;
+    preferenceId: string;
+    token: string;
+};
+
 interface TaxonomyGeo {
     lat: number | null;
     lng: number | null;
@@ -622,6 +845,17 @@ interface TaxonomyResolution {
     redirectTo: string | null;
     geo: TaxonomyGeo | null;
 }
+/**
+ * Query for `taxonomy.places.list()`. Omit it (or `q`) for the full locations
+ * directory; pass `q` (≥2 chars) for location autocomplete — the top name
+ * matches ranked, what a location search field renders.
+ */
+type PlacesListQuery = {
+    /** Location autocomplete query; ≥2 chars → top name matches, under 2 → empty. */
+    q?: string;
+    /** Max autocomplete results when `q` is given (1–50; default 10). */
+    limit?: number;
+};
 /**
  * A place in the board's locations directory (`taxonomy.places.list()` →
  * `GET /places`), the data the `/jobs/locations/` index renders. `jobCount` is
@@ -701,16 +935,23 @@ declare function createBoardClient(options: CreateBoardClientOptions): {
         search(body: JobsSearchBody, query?: Record<string, never>, options?: FetchOptions): Promise<JobCardSearchEnvelope>;
         similar(jobSlug: string, query?: JobsSimilarQuery, options?: FetchOptions): Promise<ListEnvelope<PublicJobCard>>;
     };
+    embed: {
+        jobs(query?: EmbedJobsQuery, options?: FetchOptions): Promise<ListEnvelope<PublicJobCard>>;
+    };
     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<JobCardListEnvelope>;
+        similar(companySlug: string, query?: CompanySimilarQuery, options?: FetchOptions): Promise<ListEnvelope<PublicCompany>>;
+        markets(query?: CompanyMarketsListQuery, options?: FetchOptions): Promise<ListEnvelope<CompanyMarket>>;
     };
     blog: {
         posts: {
             list(query?: BlogPostsListQuery, options?: FetchOptions): Promise<ListEnvelope<PublicBlogPostSummary>>;
             retrieve(postSlug: string, query?: Record<string, never>, options?: FetchOptions): Promise<PublicBlogPost>;
+            adjacent(postSlug: string, options?: FetchOptions): Promise<PublicBlogAdjacentPosts>;
+            similar(postSlug: string, query?: BlogSimilarQuery, options?: FetchOptions): Promise<ListEnvelope<PublicBlogPostSummary>>;
         };
         tags: {
             list(query?: Record<string, never>, options?: FetchOptions): Promise<ListEnvelope<PublicBlogTag>>;
@@ -722,6 +963,9 @@ declare function createBoardClient(options: CreateBoardClientOptions): {
         };
         search(body: BlogSearchBody, query?: Record<string, never>, options?: FetchOptions): Promise<SearchEnvelope<PublicBlogPostSummary>>;
     };
+    legal: {
+        retrieve(type: LegalPageType, options?: FetchOptions): Promise<PublicLegalPage>;
+    };
     auth: {
         register(body: RegisterBody, options?: FetchOptions): Promise<BoardAuthSession>;
         login(body: LoginBody, options?: FetchOptions): Promise<BoardAuthSession>;
@@ -739,6 +983,9 @@ declare function createBoardClient(options: CreateBoardClientOptions): {
             unsave(jobId: string, query?: Record<string, never>, options?: FetchOptions): Promise<void>;
         };
     };
+    password: {
+        verify(password: string, options?: FetchOptions): Promise<BoardAccessGrant>;
+    };
     taxonomy: {
         categories: {
             resolve(slug: string, options?: FetchOptions): Promise<TaxonomyResolution>;
@@ -747,14 +994,28 @@ declare function createBoardClient(options: CreateBoardClientOptions): {
             resolve(slug: string, options?: FetchOptions): Promise<TaxonomyResolution>;
         };
         places: {
-            list(options?: FetchOptions): Promise<ListEnvelope<PublicPlace>>;
+            list(query?: PlacesListQuery, options?: FetchOptions): Promise<ListEnvelope<PublicPlace>>;
             resolve(slug: string, options?: FetchOptions): Promise<TaxonomyResolution>;
         };
     };
     redirects: {
         resolve(path: string, options?: FetchOptions): Promise<RedirectResolution>;
     };
+    jobAlerts: {
+        subscribe(input: JobAlertSubscribeInput, options?: FetchOptions): Promise<JobAlertSubscription>;
+        confirm(input: {
+            token: string;
+        }, options?: FetchOptions): Promise<JobAlertConfirmation>;
+        resendConfirmation(input: {
+            email: string;
+        }, options?: FetchOptions): Promise<JobAlertResendResult>;
+        manage(query: JobAlertManageQuery, options?: FetchOptions): Promise<JobAlertManageState>;
+        unsubscribe(input: JobAlertManageTokenInput, options?: FetchOptions): Promise<JobAlertManageResult>;
+        resubscribe(input: JobAlertManageTokenInput, options?: FetchOptions): Promise<JobAlertManageResult>;
+        updatePreference(input: JobAlertUpdatePreferenceInput, options?: FetchOptions): Promise<JobAlertManageResult>;
+        deletePreference(input: JobAlertDeletePreferenceInput, options?: FetchOptions): Promise<JobAlertManageResult>;
+    };
 };
 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 BoardSeo, type BoardUser, type CompaniesListQuery, type CompaniesSearchBody, type CompanyJobsListQuery, type CreateBoardClientOptions, type CustomStorage, type EducationRequirement, type EmploymentType, type FetchOptions, type ForgotPasswordBody, type JobCardListEnvelope, type JobCardSearchEnvelope, 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, type PublicJobCard, type PublicPlace, REFRESH_TOKEN_KEY, type RedirectResolution, type RefreshBody, type RegisterBody, type RelatedSearch, type RemoteOption, type RemotePermit, type RemoteTimezone, type ResetPasswordBody, SDK_VERSION, type SaveJobBody, type SavedJob, type SavedJobsListQuery, type SearchEnvelope, type Seniority, type StorageMode, type StorefrontPagination, type TaxonomyGeo, type TaxonomyResolution, type VerifyEmailBody, createBoardClient, isBoardApiError, isConflict, isForbidden, isNotFound, isRateLimited, isUnauthorized, isValidationError };
+export { ACCESS_TOKEN_KEY, type Awaitable, BOARD_ACCESS_GRANT_KEY, type BlogAuthorEmbed, type BlogPostsListQuery, type BlogSearchBody, type BlogSimilarQuery, type BlogTagEmbed, type BoardAccessGrant, BoardApiError, type BoardAuthSession, BoardClient, type BoardRequest, type BoardSdk, type BoardSeo, type BoardUser, type CompaniesListQuery, type CompaniesSearchBody, type CompanyJobsListQuery, type CompanyMarket, type CompanyMarketsListQuery, type CompanySimilarQuery, type CreateBoardClientOptions, type CustomStorage, type EducationRequirement, type EmbedJobsQuery, type EmploymentType, type FetchOptions, type ForgotPasswordBody, type JobAlertConfirmation, type JobAlertDeletePreferenceInput, type JobAlertFiltersInput, type JobAlertFrequency, type JobAlertManageQuery, type JobAlertManageResult, type JobAlertManageState, type JobAlertManageTokenInput, type JobAlertPreference, type JobAlertRemoteOption, type JobAlertResendResult, type JobAlertStoredFilters, type JobAlertSubscribeInput, type JobAlertSubscription, type JobAlertUpdatePreferenceInput, type JobCardListEnvelope, type JobCardSearchEnvelope, type JobCompany, type JobsListQuery, type JobsSearchBody, type LegalEntity, type LegalPageType, type ListEnvelope, type Logger, type LoginBody, type LogoutBody, type OfficeLocation, type PlacesListQuery, type PublicBlogAdjacentPosts, type PublicBlogAuthor, type PublicBlogPost, type PublicBlogPostSummary, type PublicBlogTag, type PublicBoard, type PublicBoardAnalytics, type PublicBoardFeatures, type PublicBoardTheme, type PublicCompany, type PublicJob, type PublicJobCard, type PublicLegalPage, type PublicPlace, REFRESH_TOKEN_KEY, type RedirectResolution, type RefreshBody, type RegisterBody, type RelatedSearch, type RemoteOption, type RemotePermit, type RemoteTimezone, type ResetPasswordBody, SDK_VERSION, type SaveJobBody, type SavedJob, type SavedJobsListQuery, type SearchEnvelope, type Seniority, type StorageMode, type StorefrontPagination, type TaxonomyGeo, type TaxonomyResolution, type VerifyEmailBody, createBoardClient, isBoardApiError, isBoardPasswordRequired, isConflict, isForbidden, isNotFound, isRateLimited, isUnauthorized, isValidationError };