Jobs and search

Build paginated job discovery, faceted search, canonical details, and related jobs.

Build the core public experience: a filterable jobs page, a canonical job detail page, and a related-jobs rail. The API returns slim PublicJobCard objects for lists and a full PublicJob for details.

Prerequisites

A shared public board client.
A framework route for /jobs.
A detail route matching /companies/:companySlug/jobs/:jobSlug.

These methods are public. Cache them for a short, explicit period if your framework supports it; do not reuse that policy for board.me methods.

Load a jobs page

Convert untrusted URL parameters with the SDK filter parser, then pass supported values to board.jobs.list.

1// src/data/jobs.ts
2import { isNotFound } from '@cavuno/board';
3import { parseListingFilters } from '@cavuno/board/filters';
4import { jobDetailPath } from '@cavuno/board/paths';
5
6import { board } from '../lib/board';
7
8export async function loadJobsPage(search: Record<string, unknown>) {
9  const filters = parseListingFilters(search);
10
11  return board.jobs.list(
12    {
13      limit: 20,
14      remoteOption: filters.remoteOption
15        ? [filters.remoteOption]
16        : undefined,
17      employmentType: filters.employmentType
18        ? [filters.employmentType]
19        : undefined,
20      seniority: filters.seniority,
21      sort: filters.sort,
22    },
23    { cache: 'force-cache' },
24  );
25}
26
27export async function searchJobs(query: string) {
28  return board.jobs.search(
29    { query, limit: 20 },
30    undefined,
31    { cache: 'no-store' },
32  );
33}
34
35export async function loadJob(jobSlug: string) {
36  try {
37    const job = await board.jobs.retrieve(jobSlug);
38    const related = await board.jobs.similar(jobSlug, { limit: 5 });
39    const canonicalPath =
40      job.company?.slug && job.slug
41        ? jobDetailPath(job.company.slug, job.slug)
42        : null;
43
44    return { job, related: related.data, canonicalPath };
45  } catch (error) {
46    if (isNotFound(error)) return null;
47    throw error;
48  }
49}

list and search return an envelope with data, hasMore, and nextCursor. Job catalog responses can also include count, limit, offset, and gatedCount. Render the server values instead of calculating a total from the current page.

Use nextCursor to request the next page:

1const first = await board.jobs.list({ limit: 20 });
2
3const second = first.nextCursor
4  ? await board.jobs.list({ limit: 20, cursor: first.nextCursor })
5  : null;

Expected result

The listing loader returns a page of PublicJobCard objects and cursor state. The detail loader returns one full PublicJob, up to five related cards, and either a canonical path or null when the resource is missing.

Verify the result

Open /jobs and confirm that:

Every card uses job.slug and job.company?.slug to construct its detail URL.
Changing a supported filter changes the API request and the visible results.
The next-page control disappears when hasMore is false.
An unknown job slug produces your 404 page, not an empty job template.

Errors and edge cases

limit must be between 1 and 100. radius accepts 1–250 km and only widens a city or locality location; without it, a location search returns jobs in the place only.
Category and skill listing slugs can return 404 when they cannot be resolved.
fields: '+description' is the only supported sparse-field addition for cards.
A job without both a job slug and company slug has no canonical detail path. Do not invent one.
Search is a POST; avoid placing it in a long-lived shared cache unless the cache key includes the entire body.

Production checklist

Keep one canonical detail route: /companies/:companySlug/jobs/:jobSlug.
Abort requests tied to navigation or rapidly changing search input.
Log BoardApiError.requestId for unexpected failures.
Add metadata and JobPosting JSON-LD with SEO and structured data.

Next, connect each job to its employer with Companies.