@cavuno/board 3.1.0 → 4.0.0

package/dist/index.mjs

@@ -1,162 +1,24 @@
-// src/errors.ts
-var BOARD_API_ERROR_CODES = [
-  // Cross-cutting envelope
-  "internal_error",
-  "validation_bad_request",
-  "validation_payload_too_large",
-  "rate_limited",
-  "rate_limit_unavailable",
-  "search_unavailable",
-  "too_many_filter_values",
-  "pagination_invalid_cursor",
-  "pagination_offset_too_large",
-  "auth_unauthenticated",
-  "auth_forbidden",
-  "plan_upgrade_required",
-  "unknown_error",
-  // Board resolution + custom pages
-  "boards_not_found",
-  "board_page_not_found",
-  // Board-user auth
-  "board_auth_email_taken",
-  "board_auth_invalid_credentials",
-  "board_auth_invalid_token",
-  "board_auth_registration_disabled",
-  "board_auth_token_expired",
-  // Board password gate
-  "board_password_required",
-  "board_password_invalid",
-  // Jobs browse
-  "jobs_not_found",
-  "jobs_invalid_filter",
-  // Taxonomy
-  "categories_not_found",
-  "skills_not_found",
-  "places_not_found",
-  // Companies (public reads)
-  "companies_not_found",
-  "company_markets_not_found",
-  "company_salary_not_found",
-  "company_category_salary_not_found",
-  // Salaries
-  "salaries_title_not_found",
-  "salaries_skill_not_found",
-  "salaries_location_not_found",
-  "salaries_title_location_not_found",
-  "salaries_skill_location_not_found",
-  // Blog (public reads)
-  "blog_post_not_found",
-  "blog_author_not_found",
-  "blog_tag_not_found",
-  // Talent directory
-  "talent_not_found",
-  "talent_directory_not_found",
-  "talent_directory_restricted",
-  // Job alerts (anonymous + authenticated)
-  "job_alert_not_found",
-  "job_alerts_disabled",
-  "candidate_alert_limit_reached",
-  "candidate_alert_not_found",
-  // Candidate account
-  "candidate_entry_not_found",
-  "candidate_handle_taken",
-  "candidate_job_not_found",
-  "resume_invalid_file",
-  "resume_upload_forbidden",
-  // Applications
-  "applications_external_apply_only",
-  "applications_guest_not_allowed",
-  "applications_job_not_found",
-  "applications_not_found",
-  "applications_resume_invalid_file",
-  "applications_unprocessable",
-  // Messaging
-  "messaging_application_not_found",
-  "messaging_application_not_linked",
-  "messaging_blocked",
-  "messaging_cannot_block_self",
-  "messaging_cold_rule",
-  "messaging_conversation_not_found",
-  "messaging_disabled",
-  "messaging_edit_window_expired",
-  "messaging_message_deleted",
-  "messaging_message_not_found",
-  "messaging_not_author",
-  "messaging_not_participant",
-  "messaging_not_permitted",
-  "messaging_not_recipient",
-  "messaging_rate_limited",
-  "messaging_recipient_not_found",
-  "messaging_recipient_not_open",
-  "messaging_unsend_window_expired",
-  // Employer self-service
-  "employer_applicant_not_found",
-  "employer_ats_unprocessable",
-  "employer_checkout_failed",
-  "employer_company_exists",
-  "employer_company_name_taken",
-  "employer_company_not_found",
-  "employer_job_not_found",
-  "employer_job_slug_taken",
-  "employer_jobs_quota_exceeded",
-  "employer_not_member",
-  "employer_payment_required",
-  "employer_pipeline_stage_not_found",
-  // Candidate job-access paywall
-  "paywall_already_active",
-  "paywall_disabled",
-  "paywall_invalid_checkout_session",
-  "paywall_no_candidate_profile",
-  "paywall_no_recurring_subscription",
-  "paywall_offer_not_found",
-  // Public job posting
-  "job_posting_logo_lookup_unavailable",
-  "job_posting_logo_not_found",
-  "job_posting_rejected"
-];
-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 Error && e.name === "BoardApiError" && typeof e.status === "number" && typeof e.code === "string";
-}
-function isNotFound(e) {
-  return isBoardApiError(e) && e.status === 404;
-}
-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;
-}
-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;
-}
+import {
+  ACCESS_TOKEN_KEY,
+  BOARD_ACCESS_GRANT_KEY,
+  BOARD_API_ERROR_CODES,
+  BoardApiError,
+  REFRESH_TOKEN_KEY,
+  clearSession,
+  isBoardApiError,
+  isBoardPasswordRequired,
+  isConflict,
+  isForbidden,
+  isNotFound,
+  isRateLimited,
+  isUnauthorized,
+  isValidationError,
+  resolveStorage,
+  writeSession
+} from "./chunk-2ETP5UH4.mjs";
+import {
+  paginate
+} from "./chunk-DLSO6XXY.mjs";
 
 // src/query.ts
 function toSearchParams(query) {
@@ -176,96 +38,8 @@ function toSearchParams(query) {
   return params;
 }
 
-// src/scope.ts
-function scopeToken(board) {
-  let hash = 5381;
-  for (let i = 0; i < board.length; i++) {
-    hash = (hash << 5) + hash + board.charCodeAt(i) >>> 0;
-  }
-  const sanitized = board.replace(/[^a-zA-Z0-9_-]/g, "_");
-  return `${sanitized}-${hash.toString(36)}`;
-}
-
-// 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";
-}
-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);
-    }
-  };
-}
-function browserStorage(mode, scope) {
-  if (!isBrowser()) {
-    throw new Error(
-      `storage mode '${mode}' is browser-only \u2014 use 'nostore' + per-call headers on the server`
-    );
-  }
-  let backing;
-  try {
-    backing = mode === "local" ? globalThis.localStorage : globalThis.sessionStorage;
-    if (!backing) throw new Error("unavailable");
-  } catch {
-    throw new Error(
-      `storage mode '${mode}' is unavailable in this browsing context (storage access is blocked \u2014 e.g. a sandboxed or third-party iframe). Use 'memory', or 'nostore' + per-call headers.`
-    );
-  }
-  const suffix = scope ? `:${scopeToken(scope)}` : "";
-  return {
-    getItem: (key) => backing.getItem(`${key}${suffix}`),
-    setItem: (key, value) => {
-      backing.setItem(`${key}${suffix}`, value);
-    },
-    removeItem: (key) => {
-      backing.removeItem(`${key}${suffix}`);
-    }
-  };
-}
-var NOSTORE_BRAND = /* @__PURE__ */ Symbol.for("@cavuno/board:nostore");
-var NOSTORE = {
-  [NOSTORE_BRAND]: true,
-  getItem: () => null,
-  setItem: () => {
-  },
-  removeItem: () => {
-  }
-};
-function resolveStorage(mode, scope) {
-  const resolved = mode ?? (isBrowser() ? "memory" : "nostore");
-  if (typeof resolved === "object") return resolved;
-  switch (resolved) {
-    case "memory":
-      return memoryStorage();
-    case "nostore":
-      return NOSTORE;
-    case "local":
-    case "session":
-      return browserStorage(resolved, scope);
-    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 = "3.1.0";
+var SDK_VERSION = "4.0.0";
 
 // src/client.ts
 function isRawBody(body) {
@@ -1067,28 +841,6 @@ function jobsNamespace(client) {
   };
 }
 
-// src/namespaces/legal.ts
-function legalNamespace(client) {
-  return {
-    /**
-     * Retrieve a board legal/about page — owner-authored prose as portable HTML
-     * (`privacy-policy` / `terms-of-service` / `cookie-policy` / `about`) plus,
-     * for `impressum`, structured legal-entity facts. The starter authors the
-     * layout, breadcrumb labels, and JSON-LD. `impressum` throws
-     * `board_page_not_found` (404) when the board has not enabled it.
-     *
-     * @example
-     * const { title, content } = await board.legal.retrieve('privacy-policy');
-     */
-    retrieve(type, options) {
-      return client.fetch(
-        `/legal/${encodeURIComponent(type)}`,
-        options
-      );
-    }
-  };
-}
-
 // src/namespaces/me.ts
 function meNamespace(client) {
   return {
@@ -2574,12 +2326,18 @@ function salariesNamespace(client) {
 function searchNamespace(client) {
   return {
     /**
-     * GET /search/suggest — federated keyword suggestions (companies +
-     * taxonomy terms), one interleaved server-ranked list. Order is the
-     * contract: do not re-sort.
+     * GET /search/suggest — federated keyword suggestions (companies,
+     * markets, taxonomy terms), one interleaved server-ranked list. Pass
+     * `types` to restrict kinds; `limit` applies after that filter. Order
+     * is the contract: do not re-sort. Routing is application-side via
+     * `suggestionPath` from `@cavuno/board/paths`.
      *
      * @example
-     * const { items } = await board.search.suggest({ q: 'acme', limit: 10 });
+     * const { items } = await board.search.suggest({
+     *   q: 'acme',
+     *   limit: 10,
+     *   types: ['company', 'skill'],
+     * });
      */
     suggest(query, options) {
       return client.fetch("/search/suggest", {
@@ -2672,14 +2430,6 @@ function taxonomyNamespace(client) {
         );
       }
     },
-    suggestions: {
-      list(query, options) {
-        return client.fetch("/suggestions", {
-          ...options,
-          query
-        });
-      }
-    },
     places: {
       ...taxonomyResolver(client, "places"),
       /**
@@ -2697,36 +2447,6 @@ function taxonomyNamespace(client) {
   };
 }
 
-// src/pagination.ts
-function paginate(listFn, query, options) {
-  async function* pages() {
-    let current = query;
-    for (; ; ) {
-      const page = await listFn(current, options);
-      yield page;
-      if (!page.hasMore || page.nextCursor === null) return;
-      const { offset: _offset, ...rest } = current ?? {};
-      current = { ...rest, cursor: page.nextCursor };
-    }
-  }
-  return {
-    pages,
-    async *[Symbol.asyncIterator]() {
-      for await (const page of pages()) {
-        yield* page.data;
-      }
-    },
-    async toArray({ limit }) {
-      const items = [];
-      for await (const page of pages()) {
-        items.push(...page.data);
-        if (items.length >= limit) break;
-      }
-      return items.slice(0, limit);
-    }
-  };
-}
-
 // src/messaging-derive.ts
 function isOwnMessage(message, counterpartyId) {
   return message.authorBoardUserId !== counterpartyId;
@@ -2806,7 +2526,6 @@ function createBoardClient(options) {
     embed: embedNamespace(client),
     companies: companiesNamespace(client),
     blog: blogNamespace(client),
-    legal: legalNamespace(client),
     auth: authNamespace(client),
     me: meNamespace(client),
     password: passwordNamespace(client),

package/dist/{jobs-lVvKCBCU.d.mts → jobs-BuLpV8iy.d.mts}

@@ -1,4 +1,4 @@
-import { S as Schemas } from './_spec-nkWAraS0.mjs';
+import { S as Schemas } from './_spec-GVe6WAfT.mjs';
 
 /**
  * Optional pagination metadata returned by Board API list operations.
@@ -36,8 +36,8 @@ type PublicJob = Schemas['PublicJob'];
 type PublicJobCard = Schemas['PublicJobCard'];
 /**
  * A job's opaque, display-only custom-field values, keyed by each
- * field's `key`. Resolve labels via the board's `CustomFieldDefinition`s
- * (`board.context().customFields`).
+ * field's `key`. Resolve labels via the board's job `CustomFieldDefinition`s
+ * (`board.context().customFields.job`).
  */
 type CustomFieldValues = PublicJob['customFieldValues'];
 type CustomFieldValue = CustomFieldValues[string];
@@ -104,4 +104,4 @@ type JobsSimilarQuery = {
 };
 type JobsSearchBody = Schemas['PublicSearchJobsBody'];
 
-export type { CustomFieldValues as C, EmploymentType as E, JobSort as J, ListEnvelope as L, OfficeLocation as O, PublicJob as P, RemoteOption as R, Seniority as S, PublicJobCard as a, JobsListQuery as b, JobCardListEnvelope as c, JobsSearchBody as d, JobCardSearchEnvelope as e, JobsSimilarQuery as f, SearchEnvelope as g, CustomFieldValue as h, EducationRequirement as i, JobCatalogPagination as j, JobCompany as k, OffsetPagination as l, RelatedSearch as m, RemotePermit as n, RemoteTimezone as o, StorefrontPagination as p };
+export type { CustomFieldValues as C, EmploymentType as E, JobSort as J, ListEnvelope as L, OfficeLocation as O, PublicJob as P, RemoteOption as R, Seniority as S, JobsListQuery as a, JobCardListEnvelope as b, JobsSearchBody as c, JobCardSearchEnvelope as d, JobsSimilarQuery as e, SearchEnvelope as f, CustomFieldValue as g, EducationRequirement as h, JobCatalogPagination as i, JobCompany as j, OffsetPagination as k, PublicJobCard as l, RelatedSearch as m, RemotePermit as n, RemoteTimezone as o, StorefrontPagination as p };

package/dist/{jobs-BiEvL9d7.d.ts → jobs-QrbXOYB9.d.ts}

@@ -1,4 +1,4 @@
-import { S as Schemas } from './_spec-nkWAraS0.js';
+import { S as Schemas } from './_spec-GVe6WAfT.js';
 
 /**
  * Optional pagination metadata returned by Board API list operations.
@@ -36,8 +36,8 @@ type PublicJob = Schemas['PublicJob'];
 type PublicJobCard = Schemas['PublicJobCard'];
 /**
  * A job's opaque, display-only custom-field values, keyed by each
- * field's `key`. Resolve labels via the board's `CustomFieldDefinition`s
- * (`board.context().customFields`).
+ * field's `key`. Resolve labels via the board's job `CustomFieldDefinition`s
+ * (`board.context().customFields.job`).
  */
 type CustomFieldValues = PublicJob['customFieldValues'];
 type CustomFieldValue = CustomFieldValues[string];
@@ -104,4 +104,4 @@ type JobsSimilarQuery = {
 };
 type JobsSearchBody = Schemas['PublicSearchJobsBody'];
 
-export type { CustomFieldValues as C, EmploymentType as E, JobSort as J, ListEnvelope as L, OfficeLocation as O, PublicJob as P, RemoteOption as R, Seniority as S, PublicJobCard as a, JobsListQuery as b, JobCardListEnvelope as c, JobsSearchBody as d, JobCardSearchEnvelope as e, JobsSimilarQuery as f, SearchEnvelope as g, CustomFieldValue as h, EducationRequirement as i, JobCatalogPagination as j, JobCompany as k, OffsetPagination as l, RelatedSearch as m, RemotePermit as n, RemoteTimezone as o, StorefrontPagination as p };
+export type { CustomFieldValues as C, EmploymentType as E, JobSort as J, ListEnvelope as L, OfficeLocation as O, PublicJob as P, RemoteOption as R, Seniority as S, JobsListQuery as a, JobCardListEnvelope as b, JobsSearchBody as c, JobCardSearchEnvelope as d, JobsSimilarQuery as e, SearchEnvelope as f, CustomFieldValue as g, EducationRequirement as h, JobCatalogPagination as i, JobCompany as j, OffsetPagination as k, PublicJobCard as l, RelatedSearch as m, RemotePermit as n, RemoteTimezone as o, StorefrontPagination as p };

package/dist/paths.d.mts

@@ -9,11 +9,27 @@
  * zero-dependency — safe to import in server runtimes, on the edge,
  * and in the browser.
  *
+ * Dynamic path segments are percent-encoded (URI, not bare IRI) so
+ * non-Latin board-language slugs (`SuggestionPathInput.canonicalSlug`)
+ * are legal in sitemap `<loc>`, canonical/`og:url`, and email links.
+ * Separators (`/`) are never encoded; already-encoded input is not
+ * double-encoded.
+ *
  * These paths mirror the hosted board's indexed URLs exactly (migration
  * parity). Do NOT change a pattern here without updating the hosted board
  * and the sitemap golden tests in lockstep — the structure is a locked
  * cross-surface contract.
  */
+/**
+ * Percent-encode one path segment for use in a URL path.
+ * Round-trips already-encoded input so `%E6…` is not double-encoded.
+ * Does not touch path separators — callers encode segments only.
+ *
+ * `:` is left unencoded so route-contract / well-known templates built via
+ * `jobDetailPath(':companySlug', ':jobSlug')` stay RFC-6570-style. Real
+ * board slugs are alphanumeric-plus-hyphen; non-ASCII is still encoded.
+ */
+declare function encodePathSegment(segment: string): string;
 /** Job detail — the canonical, indexed job URL. Requires BOTH slugs. */
 declare function jobDetailPath(companySlug: string, jobSlug: string): string;
 /** Category (keyword) job listing. */
@@ -22,10 +38,81 @@ declare function jobsCategoryPath(categorySlug: string): string;
 declare function jobsSkillPath(skillSlug: string): string;
 /** Location job listing. */
 declare function jobsLocationPath(placeSlug: string): string;
+/**
+ * Location + category combination job listing
+ * (`/jobs/locations/<place>/<category>`).
+ */
+declare function jobsLocationCategoryPath(placeSlug: string, categorySlug: string): string;
+/**
+ * Location + skill combination job listing
+ * (`/jobs/locations/<place>/skills/<skill>`).
+ */
+declare function jobsLocationSkillPath(placeSlug: string, skillSlug: string): string;
 /** Company profile. */
 declare function companyPath(companySlug: string): string;
 /** Company market (sector) listing. */
 declare function companyMarketPath(marketSlug: string): string;
+/**
+ * Suggestion kinds `suggestionPath` understands. Mirrors the wire
+ * `SuggestionItem` discriminators (and `termType` for terms) without
+ * importing generated OpenAPI types into the paths entry.
+ */
+type SuggestionPathInput = {
+    type: 'company';
+    slug: string;
+} | {
+    type: 'market';
+    slug: string;
+} | {
+    type: 'post';
+    slug: string;
+} | {
+    type: 'tag';
+    slug: string;
+} | {
+    type: 'term';
+    termType: 'category' | 'skill';
+    /** Board-language URL slug — use `canonicalSlug` from the wire item. */
+    canonicalSlug: string;
+};
+/** Search scopes that own different destinations for the same suggestion. */
+type SuggestionPathScope = 'jobs' | 'companies' | 'blog';
+type SuggestionPathOptions = {
+    scope: SuggestionPathScope;
+    /**
+     * Active place slug. When set on the `jobs` scope with a category or
+     * skill term, routes into the location combination pages.
+     */
+    location?: string;
+};
+/**
+ * Resolve a suggestion to a board-relative path for the given search scope
+ * The API never returns an `href` because the same
+ * `CompanySuggestion` means "navigate to the company page" under companies
+ * scope and "apply a `companySlug` filter" under jobs scope — only the app
+ * knows which.
+ *
+ * Returns `null` when the selection is not a navigation (jobs-scope company
+ * → filter, or a kind that has no path under the active scope). Compose from
+ * the existing `*Path` helpers; never string-build at the call site.
+ *
+ * | scope | suggestion | result |
+ * | --- | --- | --- |
+ * | jobs | skill | `/jobs/skills/<slug>` |
+ * | jobs | category | `/jobs/<slug>` |
+ * | jobs | skill + location | `/jobs/locations/<loc>/skills/<slug>` |
+ * | jobs | category + location | `/jobs/locations/<loc>/<slug>` |
+ * | jobs | company | `null` (apply `companySlug` filter) |
+ * | jobs | market | `null` |
+ * | jobs | post / tag | `null` |
+ * | companies | company | `/companies/<slug>` |
+ * | companies | market | `/companies/markets/<slug>` |
+ * | companies | term / post / tag | `null` |
+ * | blog | post | `/blog/<slug>` |
+ * | blog | tag | `/blog/tag/<slug>` |
+ * | blog | other | `null` |
+ */
+declare function suggestionPath(suggestion: SuggestionPathInput, options: SuggestionPathOptions): string | null;
 /** A company's salary overview. */
 declare function companySalaryPath(companySlug: string): string;
 /** Salary page for a job title. */
@@ -90,7 +177,8 @@ declare function goAlertsConfirmPath(): string;
 /**
  * Prefix a board-relative path with the board origin. A trailing slash on
  * the origin is tolerated (stripped) so callers need not normalise first.
+ * Paths from `*Path` helpers already percent-encode dynamic segments.
  */
 declare function boardUrl(origin: string, path: string): string;
 
-export { BOARD_PATHS, blogAuthorPath, blogPostPath, blogTagPath, boardUrl, companyMarketPath, companyPath, companySalaryPath, goAlertsConfirmPath, goAlertsManagePath, goJobPath, jobDetailPath, jobsCategoryPath, jobsLocationPath, jobsSkillPath, salaryLocationPath, salarySkillPath, salaryTitlePath };
+export { BOARD_PATHS, type SuggestionPathInput, type SuggestionPathOptions, type SuggestionPathScope, blogAuthorPath, blogPostPath, blogTagPath, boardUrl, companyMarketPath, companyPath, companySalaryPath, encodePathSegment, goAlertsConfirmPath, goAlertsManagePath, goJobPath, jobDetailPath, jobsCategoryPath, jobsLocationCategoryPath, jobsLocationPath, jobsLocationSkillPath, jobsSkillPath, salaryLocationPath, salarySkillPath, salaryTitlePath, suggestionPath };

package/dist/paths.d.ts

@@ -9,11 +9,27 @@
  * zero-dependency — safe to import in server runtimes, on the edge,
  * and in the browser.
  *
+ * Dynamic path segments are percent-encoded (URI, not bare IRI) so
+ * non-Latin board-language slugs (`SuggestionPathInput.canonicalSlug`)
+ * are legal in sitemap `<loc>`, canonical/`og:url`, and email links.
+ * Separators (`/`) are never encoded; already-encoded input is not
+ * double-encoded.
+ *
  * These paths mirror the hosted board's indexed URLs exactly (migration
  * parity). Do NOT change a pattern here without updating the hosted board
  * and the sitemap golden tests in lockstep — the structure is a locked
  * cross-surface contract.
  */
+/**
+ * Percent-encode one path segment for use in a URL path.
+ * Round-trips already-encoded input so `%E6…` is not double-encoded.
+ * Does not touch path separators — callers encode segments only.
+ *
+ * `:` is left unencoded so route-contract / well-known templates built via
+ * `jobDetailPath(':companySlug', ':jobSlug')` stay RFC-6570-style. Real
+ * board slugs are alphanumeric-plus-hyphen; non-ASCII is still encoded.
+ */
+declare function encodePathSegment(segment: string): string;
 /** Job detail — the canonical, indexed job URL. Requires BOTH slugs. */
 declare function jobDetailPath(companySlug: string, jobSlug: string): string;
 /** Category (keyword) job listing. */
@@ -22,10 +38,81 @@ declare function jobsCategoryPath(categorySlug: string): string;
 declare function jobsSkillPath(skillSlug: string): string;
 /** Location job listing. */
 declare function jobsLocationPath(placeSlug: string): string;
+/**
+ * Location + category combination job listing
+ * (`/jobs/locations/<place>/<category>`).
+ */
+declare function jobsLocationCategoryPath(placeSlug: string, categorySlug: string): string;
+/**
+ * Location + skill combination job listing
+ * (`/jobs/locations/<place>/skills/<skill>`).
+ */
+declare function jobsLocationSkillPath(placeSlug: string, skillSlug: string): string;
 /** Company profile. */
 declare function companyPath(companySlug: string): string;
 /** Company market (sector) listing. */
 declare function companyMarketPath(marketSlug: string): string;
+/**
+ * Suggestion kinds `suggestionPath` understands. Mirrors the wire
+ * `SuggestionItem` discriminators (and `termType` for terms) without
+ * importing generated OpenAPI types into the paths entry.
+ */
+type SuggestionPathInput = {
+    type: 'company';
+    slug: string;
+} | {
+    type: 'market';
+    slug: string;
+} | {
+    type: 'post';
+    slug: string;
+} | {
+    type: 'tag';
+    slug: string;
+} | {
+    type: 'term';
+    termType: 'category' | 'skill';
+    /** Board-language URL slug — use `canonicalSlug` from the wire item. */
+    canonicalSlug: string;
+};
+/** Search scopes that own different destinations for the same suggestion. */
+type SuggestionPathScope = 'jobs' | 'companies' | 'blog';
+type SuggestionPathOptions = {
+    scope: SuggestionPathScope;
+    /**
+     * Active place slug. When set on the `jobs` scope with a category or
+     * skill term, routes into the location combination pages.
+     */
+    location?: string;
+};
+/**
+ * Resolve a suggestion to a board-relative path for the given search scope
+ * The API never returns an `href` because the same
+ * `CompanySuggestion` means "navigate to the company page" under companies
+ * scope and "apply a `companySlug` filter" under jobs scope — only the app
+ * knows which.
+ *
+ * Returns `null` when the selection is not a navigation (jobs-scope company
+ * → filter, or a kind that has no path under the active scope). Compose from
+ * the existing `*Path` helpers; never string-build at the call site.
+ *
+ * | scope | suggestion | result |
+ * | --- | --- | --- |
+ * | jobs | skill | `/jobs/skills/<slug>` |
+ * | jobs | category | `/jobs/<slug>` |
+ * | jobs | skill + location | `/jobs/locations/<loc>/skills/<slug>` |
+ * | jobs | category + location | `/jobs/locations/<loc>/<slug>` |
+ * | jobs | company | `null` (apply `companySlug` filter) |
+ * | jobs | market | `null` |
+ * | jobs | post / tag | `null` |
+ * | companies | company | `/companies/<slug>` |
+ * | companies | market | `/companies/markets/<slug>` |
+ * | companies | term / post / tag | `null` |
+ * | blog | post | `/blog/<slug>` |
+ * | blog | tag | `/blog/tag/<slug>` |
+ * | blog | other | `null` |
+ */
+declare function suggestionPath(suggestion: SuggestionPathInput, options: SuggestionPathOptions): string | null;
 /** A company's salary overview. */
 declare function companySalaryPath(companySlug: string): string;
 /** Salary page for a job title. */
@@ -90,7 +177,8 @@ declare function goAlertsConfirmPath(): string;
 /**
  * Prefix a board-relative path with the board origin. A trailing slash on
  * the origin is tolerated (stripped) so callers need not normalise first.
+ * Paths from `*Path` helpers already percent-encode dynamic segments.
  */
 declare function boardUrl(origin: string, path: string): string;
 
-export { BOARD_PATHS, blogAuthorPath, blogPostPath, blogTagPath, boardUrl, companyMarketPath, companyPath, companySalaryPath, goAlertsConfirmPath, goAlertsManagePath, goJobPath, jobDetailPath, jobsCategoryPath, jobsLocationPath, jobsSkillPath, salaryLocationPath, salarySkillPath, salaryTitlePath };
+export { BOARD_PATHS, type SuggestionPathInput, type SuggestionPathOptions, type SuggestionPathScope, blogAuthorPath, blogPostPath, blogTagPath, boardUrl, companyMarketPath, companyPath, companySalaryPath, encodePathSegment, goAlertsConfirmPath, goAlertsManagePath, goJobPath, jobDetailPath, jobsCategoryPath, jobsLocationCategoryPath, jobsLocationPath, jobsLocationSkillPath, jobsSkillPath, salaryLocationPath, salarySkillPath, salaryTitlePath, suggestionPath };