@thejob/jobs-client 1.0.0

package/README.md

@@ -0,0 +1,108 @@
+# @thejob/jobs-client
+
+Typed client for **thejob-jobs-service**. Published by the service that owns the
+data, so consumers never hand-roll HTTP calls or redeclare job types.
+
+```ts
+import { JobsClient } from '@thejob/jobs-client';
+
+const jobs = new JobsClient({
+  baseUrl: process.env.JOBS_SERVICE_URL!,
+  apiKey: process.env.JOBS_SERVICE_API_KEY,   // backend-to-backend
+  // token: userJwt,                          // user-scoped calls (bookmarks)
+});
+
+const { results, total } = await jobs.listJobs({
+  search: 'angular developer',
+  workMode: ['remote', 'hybrid'],
+  category: ['Technology, Data & Digital'],
+  salary: { min: 50000 },
+  limit: 6,
+});
+// -> ?search=angular+developer&workMode[0]=remote&workMode[1]=hybrid
+//    &category[0]=Technology%2C+Data+%26+Digital&salary[min]=50000&limit=6
+```
+
+> **Not yet wired to the service.** jobs-service still parses the older
+> `filter[field]=value` form. The client emits the `qs` form above; migrating the
+> service and its ~20 existing call sites is a separate, approved step.
+
+## Methods
+
+Twenty methods for twenty endpoints, one to one. No wrappers, no helpers.
+
+| | |
+|---|---|
+| **Read** | `listJobs` · `getJob` · `listSimilarJobs` · `searchJobsV3` · `searchJobsMeili` |
+| **Write** | `createJob` · `updateJob` · `deleteJob` · `closeJob` · `reopenJob` · `toggleJobFeatured` · `purgeJobCache` |
+| **Bookmarks** | `addBookmark` · `removeBookmark` |
+| **Expiry** | `listJobsDueForExpiryCheck` · `closeLapsedJobs` |
+| **Indexing** | `getIndexingQuota` · `indexJobs` |
+| **Admin** | `purgeAllJobsCache` · `health` |
+
+There is no `countJobs`: a count is `listJobs({ ...filter, limit: 1 })` read off
+`total`, which is one line at the call site and keeps what `total` means visible.
+
+## Design
+
+**One method per endpoint, never per use case.** Methods are named for the
+resource and operation (`listJobs`, `closeJob`), not for why a caller wants the
+data. A `getNewestJobsForADigest` would be the same mistake as an endpoint called
+`/jobs/newest-for-digest`: one caller's intent baked into a shared contract.
+Narrowing is the **filter's** job.
+
+**Facets are flat and typed**, sitting next to paging exactly as they appear in
+the URL, so the type mirrors the request it produces. A typo in a declared facet
+is a compile error rather than a filter that saves, renders, and silently matches
+nothing.
+
+**Encoding is `qs` with its standard defaults** — arrays as `key[0]`, objects as
+`key[nested]`. Because arrays are a *structure* rather than a delimited string, a
+comma inside a value is just a character: no escaping, and no delimiter
+convention left for a consumer to get wrong. (7 of the 9 job categories in use
+contain a comma.)
+
+Query strings are built by `buildQuerySuffix` from
+[`@thejob/util/query`](../../../thejob-util/src/query), shared with every other
+service client. It adds the one thing `qs` cannot know — which inputs must
+produce **no parameter at all**. `qs` drops `undefined` and `[]`, but would
+happily emit `workMode=`, `skills[0]=`, or a key with untrimmed spaces, each of
+which matches nothing while looking correctly configured. Blank values and empty
+facets are dropped; `false` and `0` are kept, being meaningful.
+
+**`total` is the filter's count, not the page size.** Six cards under "142 new
+jobs" is honest; counting the cards makes `limit` silently change the headline.
+
+## Types
+
+`JobDoc`, `JobListQuery`, `JobPage`, `BookmarkResult` are the **canonical**
+definitions, owned here and imported back by jobs-service, so there is exactly
+one definition of each.
+
+The client covers jobs and nothing else. Saved searches are user data and belong
+to user-service; alert sweeps belong to notification-service. Neither has a
+method here.
+
+It returns jobs as the service stores them and does no presentation: no renaming
+to a template's field names, no joining a location into one string, no formatting
+a salary. A consumer that needs a narrower payload asks for it with `fields`;
+how a job is *displayed* is the consumer's own decision, not a shared contract.
+
+## Coverage
+
+`client.test.ts` reads `src/routes/jobs.ts` and `src/app.ts`, collects every route
+the service registers, then drives a fake `fetch` through all twenty methods and
+asserts nothing is left over. It records what each method actually *requests*
+rather than grepping the source, so it proves the method calls the path.
+
+A client that covers only part of an API is how consumers end up hand-rolling
+"just this one call" alongside it — the duplication this package exists to remove.
+
+Two exclusions, both deliberate:
+
+- **`/webhooks/*`** — called *into* jobs-service by dory and the data-processor
+  and authenticated by signature, not by a consumer holding this client.
+- **`GET /`, `/login`, `/logout`, `/dashboard/api/*`** — the operations dashboard.
+  Cookie-gated, same-origin, browser-only, so an API-key client could not
+  authenticate against them anyway. These live in `src/ui/`, which the test does
+  not read.

package/dist/client.d.ts

@@ -0,0 +1,154 @@
+/**
+ * JobsClient: a typed wrapper over the thejob-jobs-service HTTP API.
+ *
+ * The whole API, one method per ENDPOINT — not one method per use case. A
+ * consumer should never construct a URL or encode a filter itself. If
+ * jobs-service can do it, this client exposes it.
+ *
+ * Methods are named after the resource and the operation (`listJobs`, `getJob`,
+ * `closeJob`), never after why a particular caller wants it. A method called
+ * `getNewestJobsForADigest` would be the same mistake as an endpoint called
+ * `/jobs/newest-for-digest`: the caller's intent leaking into a shared contract.
+ * Narrowing is the FILTER's job.
+ *
+ * SCOPE: jobs, and nothing else. This service is a DATA SOURCE. Saved searches
+ * are user data (owner, label, alert cadence, send bookkeeping — not one field
+ * describes a job) and belong to user-service; deciding whom to mail and when
+ * belongs to notification-service. Neither has a place here, so neither has a
+ * method here.
+ *
+ * Auth: pass `apiKey` for backend-to-backend calls, `token` for user-scoped ones
+ * (bookmarks). Uses the global `fetch`.
+ */
+import type { BookmarkResult, JobDoc, JobListQuery, JobPage } from './types.js';
+export interface JobsClientOptions {
+    /** Base URL of the service, e.g. "http://localhost:3081" (trailing slash trimmed). */
+    baseUrl: string;
+    /** Service API key, sent as `x-api-key` (backend-to-backend callers). */
+    apiKey?: string;
+    /** Bearer token, sent as `Authorization: Bearer <token>` (user-scoped calls). */
+    token?: string;
+    /** Optional fetch implementation (for tests or non-global-fetch runtimes). */
+    fetch?: typeof fetch;
+    /** Extra headers applied to every request. */
+    headers?: Record<string, string>;
+}
+/** Thrown for any non-2xx response. Carries the status and parsed body. */
+export declare class JobsClientError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+export declare class JobsClient {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly headers;
+    constructor(options: JobsClientOptions);
+    private request;
+    /**
+     * A GET with the query string built by the shared `@thejob/util/query`
+     * helper, which owns the rules about what must NOT be sent — a blank value or
+     * an empty array encodes to a term matching nothing, silently.
+     */
+    private get;
+    /**
+     * Jobs matching a filter, with the filter's TOTAL alongside the page.
+     *
+     * `total` is the count for the filter, not the number returned: a digest that
+     * shows six cards under "142 new jobs" is honest, whereas counting the cards
+     * makes `limit` silently change the headline.
+     *
+     * Pass `search` to rank by meaning (hybrid vector + FTS) instead of recency.
+     * For a count alone, pass `limit: 1` and read `total`.
+     */
+    listJobs(query?: JobListQuery): Promise<JobPage>;
+    /** One job by shortId. Throws `JobsClientError` with status 404 if absent. */
+    getJob(shortId: string, fields?: string[]): Promise<JobDoc>;
+    /** Jobs similar to one job (vector neighbours). */
+    listSimilarJobs(shortId: string, query?: JobListQuery): Promise<JobPage>;
+    /** Query-understanding search: parsed facets applied as a hard filter. */
+    searchJobsV3(query?: JobListQuery): Promise<JobPage>;
+    /** Meilisearch-backed search. */
+    searchJobsMeili(query?: JobListQuery): Promise<JobPage>;
+    /**
+     * Create a job as the acting user (requires `token`).
+     *
+     * `draft: true` saves it as a Draft; anything else PUBLISHES it, which is the
+     * service's own default and is why this option exists rather than being left
+     * to the caller to append. Without it a "save as draft" button reaches
+     * `POST /jobs` with no flag and puts the job straight in front of applicants,
+     * with nothing to signal that the wrong thing happened.
+     */
+    createJob(job: Partial<JobDoc>, options?: {
+        draft?: boolean;
+    }): Promise<JobDoc>;
+    /** Update a job the acting user owns. */
+    updateJob(shortId: string, patch: Partial<JobDoc>): Promise<JobDoc>;
+    deleteJob(shortId: string): Promise<unknown>;
+    closeJob(shortId: string): Promise<JobDoc>;
+    reopenJob(shortId: string): Promise<JobDoc>;
+    /**
+     * Admin: flip the featured flag, and say in WHICH markets.
+     *
+     * `markets` is not optional decoration. The service reads it as
+     * `Array.isArray(body.markets) ? body.markets : []`, so a call that omits it
+     * sends nothing and the job's featured markets are REPLACED WITH AN EMPTY
+     * LIST — the job stays flagged featured while surfacing in no market, with no
+     * error. This client omitted the argument entirely, so every caller silently
+     * cleared the targeting it meant to set.
+     */
+    toggleJobFeatured(shortId: string, isFeatured: boolean, markets?: string[]): Promise<JobDoc>;
+    /** Admin: purge every locale variant of a job's page from the CDN. */
+    purgeJobCache(shortId: string): Promise<{
+        purged: boolean;
+        slug?: string;
+    }>;
+    addBookmark(shortId: string): Promise<BookmarkResult>;
+    removeBookmark(shortId: string): Promise<BookmarkResult>;
+    /**
+     * Jobs due for an expiry re-check: undated published jobs old enough to be
+     * worth re-crawling, and not re-checked recently.
+     *
+     * The selection depends on when the service last re-checked each job, which is
+     * its own bookkeeping, so this is a purpose-built feed rather than something a
+     * caller could express as a `listJobs` filter.
+     */
+    listJobsDueForExpiryCheck(query?: JobListQuery): Promise<JobPage>;
+    /**
+     * Run the dated auto-close sweep on demand.
+     *
+     * The in-process cron already runs this on a timer; this is the manual
+     * trigger for an operator or a test.
+     */
+    closeLapsedJobs(): Promise<{
+        closed?: number;
+        [k: string]: unknown;
+    }>;
+    /** Remaining Google Indexing API budget. The service owns the count. */
+    getIndexingQuota(): Promise<{
+        used?: number;
+        limit?: number;
+        [k: string]: unknown;
+    }>;
+    /**
+     * Submit jobs' canonical page URLs to Google's Indexing API so they are
+     * (re)crawled promptly. Over-budget requests are refused before Google is
+     * touched.
+     */
+    indexJobs(shortIds: string[]): Promise<{
+        submitted?: number;
+        [k: string]: unknown;
+    }>;
+    /** Admin: purge the whole job cache (not one job — see `purgeJobCache`). */
+    purgeAllJobsCache(): Promise<{
+        purged?: boolean;
+        [k: string]: unknown;
+    }>;
+    /** Service health. */
+    health(): Promise<{
+        status: string;
+        db?: string;
+        uptime?: number;
+    }>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -0,0 +1,211 @@
+/**
+ * JobsClient: a typed wrapper over the thejob-jobs-service HTTP API.
+ *
+ * The whole API, one method per ENDPOINT — not one method per use case. A
+ * consumer should never construct a URL or encode a filter itself. If
+ * jobs-service can do it, this client exposes it.
+ *
+ * Methods are named after the resource and the operation (`listJobs`, `getJob`,
+ * `closeJob`), never after why a particular caller wants it. A method called
+ * `getNewestJobsForADigest` would be the same mistake as an endpoint called
+ * `/jobs/newest-for-digest`: the caller's intent leaking into a shared contract.
+ * Narrowing is the FILTER's job.
+ *
+ * SCOPE: jobs, and nothing else. This service is a DATA SOURCE. Saved searches
+ * are user data (owner, label, alert cadence, send bookkeeping — not one field
+ * describes a job) and belong to user-service; deciding whom to mail and when
+ * belongs to notification-service. Neither has a place here, so neither has a
+ * method here.
+ *
+ * Auth: pass `apiKey` for backend-to-backend calls, `token` for user-scoped ones
+ * (bookmarks). Uses the global `fetch`.
+ */
+import { buildQuerySuffix } from '@thejob/util/query';
+/** Thrown for any non-2xx response. Carries the status and parsed body. */
+export class JobsClientError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'JobsClientError';
+    }
+}
+export class JobsClient {
+    baseUrl;
+    fetchImpl;
+    headers;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.fetchImpl = options.fetch ?? globalThis.fetch;
+        this.headers = { ...options.headers };
+        if (options.apiKey)
+            this.headers['x-api-key'] = options.apiKey;
+        if (options.token)
+            this.headers['authorization'] = `Bearer ${options.token}`;
+        if (!this.fetchImpl) {
+            throw new Error('No fetch implementation available; pass one via options.fetch');
+        }
+    }
+    // ── plumbing ───────────────────────────────────────────────────────────────
+    async request(method, path, body) {
+        const init = { method, headers: { ...this.headers } };
+        if (body !== undefined) {
+            init.headers['content-type'] = 'application/json';
+            init.body = JSON.stringify(body);
+        }
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, init);
+        const text = await res.text();
+        const parsed = text ? JSON.parse(text) : null;
+        if (!res.ok) {
+            const message = parsed?.error ?? `jobs-service ${res.status}`;
+            throw new JobsClientError(message, res.status, parsed);
+        }
+        return parsed;
+    }
+    /**
+     * A GET with the query string built by the shared `@thejob/util/query`
+     * helper, which owns the rules about what must NOT be sent — a blank value or
+     * an empty array encodes to a term matching nothing, silently.
+     */
+    get(path, q) {
+        const { fields, ...rest } = (q ?? {});
+        const params = { ...rest };
+        // ONE comma-joined param. `parseResponseFields` server-side reads
+        // `params.get('fields')` and splits on commas, so letting `qs` index it
+        // (`fields[0]=…`) means `.get('fields')` is null and the PROJECTION IS
+        // SILENTLY DROPPED — the caller gets every field of every row back, which
+        // looks like a working call with a much larger payload.
+        if (fields?.length)
+            params['fields'] = fields.join(',');
+        return this.request('GET', `${path}${buildQuerySuffix(params)}`);
+    }
+    // ── jobs: read ─────────────────────────────────────────────────────────────
+    /**
+     * Jobs matching a filter, with the filter's TOTAL alongside the page.
+     *
+     * `total` is the count for the filter, not the number returned: a digest that
+     * shows six cards under "142 new jobs" is honest, whereas counting the cards
+     * makes `limit` silently change the headline.
+     *
+     * Pass `search` to rank by meaning (hybrid vector + FTS) instead of recency.
+     * For a count alone, pass `limit: 1` and read `total`.
+     */
+    listJobs(query = {}) {
+        return this.get('/jobs', query);
+    }
+    /** One job by shortId. Throws `JobsClientError` with status 404 if absent. */
+    getJob(shortId, fields) {
+        return this.get(`/jobs/${encodeURIComponent(shortId)}`, { fields });
+    }
+    /** Jobs similar to one job (vector neighbours). */
+    listSimilarJobs(shortId, query = {}) {
+        return this.get(`/jobs/${encodeURIComponent(shortId)}/similar`, query);
+    }
+    /** Query-understanding search: parsed facets applied as a hard filter. */
+    searchJobsV3(query = {}) {
+        return this.get('/jobs/search-v3', query);
+    }
+    /** Meilisearch-backed search. */
+    searchJobsMeili(query = {}) {
+        return this.get('/jobs/search-meili', query);
+    }
+    // ── jobs: write ────────────────────────────────────────────────────────────
+    /**
+     * Create a job as the acting user (requires `token`).
+     *
+     * `draft: true` saves it as a Draft; anything else PUBLISHES it, which is the
+     * service's own default and is why this option exists rather than being left
+     * to the caller to append. Without it a "save as draft" button reaches
+     * `POST /jobs` with no flag and puts the job straight in front of applicants,
+     * with nothing to signal that the wrong thing happened.
+     */
+    createJob(job, options = {}) {
+        const suffix = options.draft ? buildQuerySuffix({ draft: true }) : '';
+        return this.request('POST', `/jobs${suffix}`, job);
+    }
+    /** Update a job the acting user owns. */
+    updateJob(shortId, patch) {
+        return this.request('PATCH', `/jobs/${encodeURIComponent(shortId)}`, patch);
+    }
+    deleteJob(shortId) {
+        return this.request('DELETE', `/jobs/${encodeURIComponent(shortId)}`);
+    }
+    closeJob(shortId) {
+        return this.request('POST', `/jobs/${encodeURIComponent(shortId)}/close`);
+    }
+    reopenJob(shortId) {
+        return this.request('POST', `/jobs/${encodeURIComponent(shortId)}/reopen`);
+    }
+    /**
+     * Admin: flip the featured flag, and say in WHICH markets.
+     *
+     * `markets` is not optional decoration. The service reads it as
+     * `Array.isArray(body.markets) ? body.markets : []`, so a call that omits it
+     * sends nothing and the job's featured markets are REPLACED WITH AN EMPTY
+     * LIST — the job stays flagged featured while surfacing in no market, with no
+     * error. This client omitted the argument entirely, so every caller silently
+     * cleared the targeting it meant to set.
+     */
+    toggleJobFeatured(shortId, isFeatured, markets = []) {
+        return this.request('PATCH', `/jobs/${encodeURIComponent(shortId)}/toggle-featured`, {
+            isFeatured,
+            markets,
+        });
+    }
+    /** Admin: purge every locale variant of a job's page from the CDN. */
+    purgeJobCache(shortId) {
+        return this.request('POST', `/jobs/${encodeURIComponent(shortId)}/purge-cache`);
+    }
+    // ── bookmarks (user-scoped; requires `token`) ──────────────────────────────
+    addBookmark(shortId) {
+        return this.request('PUT', `/jobs/${encodeURIComponent(shortId)}/bookmarks`);
+    }
+    removeBookmark(shortId) {
+        return this.request('DELETE', `/jobs/${encodeURIComponent(shortId)}/bookmarks`);
+    }
+    // ── expiry ─────────────────────────────────────────────────────────────────
+    /**
+     * Jobs due for an expiry re-check: undated published jobs old enough to be
+     * worth re-crawling, and not re-checked recently.
+     *
+     * The selection depends on when the service last re-checked each job, which is
+     * its own bookkeeping, so this is a purpose-built feed rather than something a
+     * caller could express as a `listJobs` filter.
+     */
+    listJobsDueForExpiryCheck(query = {}) {
+        return this.get('/jobs/expiry-candidates', query);
+    }
+    // ── operations (admin / service key) ───────────────────────────────────────
+    /**
+     * Run the dated auto-close sweep on demand.
+     *
+     * The in-process cron already runs this on a timer; this is the manual
+     * trigger for an operator or a test.
+     */
+    closeLapsedJobs() {
+        return this.request('POST', '/jobs/close-lapsed');
+    }
+    /** Remaining Google Indexing API budget. The service owns the count. */
+    getIndexingQuota() {
+        return this.request('GET', '/jobs/index/quota');
+    }
+    /**
+     * Submit jobs' canonical page URLs to Google's Indexing API so they are
+     * (re)crawled promptly. Over-budget requests are refused before Google is
+     * touched.
+     */
+    indexJobs(shortIds) {
+        return this.request('POST', '/jobs/index', { shortIds });
+    }
+    /** Admin: purge the whole job cache (not one job — see `purgeJobCache`). */
+    purgeAllJobsCache() {
+        return this.request('DELETE', '/jobs/cache');
+    }
+    /** Service health. */
+    health() {
+        return this.request('GET', '/health');
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { JobsClient, JobsClientError, type JobsClientOptions } from './client.js';
+export type { BookmarkResult, JobDoc, JobFilter, JobListQuery, JobLocation, JobPage, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAElF,YAAY,EACV,cAAc,EACd,MAAM,EACN,SAAS,EACT,YAAY,EACZ,WAAW,EACX,OAAO,GACR,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { JobsClient, JobsClientError } from './client.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAA0B,MAAM,aAAa,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The wire types of the thejob-jobs-service HTTP API.
+ *
+ * CANONICAL definitions, owned by jobs-service and published here so consumers
+ * never redeclare them. marketing-service previously hand-wrote its own copies
+ * of these shapes and they drifted (the same value was `jobCount` in one place
+ * and `newJobCount` in another), which is the class of bug this package removes.
+ *
+ * jobs-service imports these back from the package, so there is exactly one
+ * definition of each shape.
+ */
+import type { ListQueryOptions } from '@thejob/util/query';
+import type { InferType } from 'yup';
+import type { JobFilterSchema, JobSchema } from '@thejob/schema';
+/**
+ * Everything a list or search call can ask for.
+ *
+ * FLAT and TYPED: facets sit at the top level next to paging, exactly as they
+ * appear in the URL, so the type mirrors the request it produces. Declaring the
+ * known facets as real fields means a typo is a compile error rather than a
+ * filter that saves, renders, and silently matches nothing — the failure mode a
+ * loose `Record<string, string>` invites.
+ *
+ * Encoded with `qs` defaults, so arrays and nested objects are STRUCTURAL:
+ *
+ *     workMode: ['remote', 'hybrid']   -> workMode[0]=remote&workMode[1]=hybrid
+ *     salary: { min: 50000 }           -> salary[min]=50000
+ *     category: ['Technology, Data & Digital']
+ *                                      -> category[0]=Technology%2C%20Data...
+ *
+ * A comma inside a value is just a character. Nothing needs escaping, and there
+ * is no delimiter convention to get wrong.
+ */
+/**
+ * The closed vocabulary of facets a job query can filter on.
+ *
+ * Named separately, matching `UserFilter`, `GroupFilter` and `PageFilter`, so a
+ * consumer can talk about the filter on its own — a UI widget's state, or a
+ * saved search — without dragging paging along. `JobListQuery` is this plus the
+ * reserved params.
+ */
+export type JobFilter = Partial<InferType<typeof JobFilterSchema>>;
+/**
+ * A jobs listing request: the facets, plus the reserved params.
+ *
+ * `ListQueryOptions` from `@thejob/util/query` supplies the reserved half
+ * (`search`, paging, sorting, `fields`), so this client cannot disagree with any
+ * other about what those mean. That block was spelled out here and, verbatim,
+ * in three sibling clients: four copies that agreed only by coincidence.
+ *
+ * The FACETS stay local, because they are this service's schema's business. The
+ * type is the plain intersection of the two halves rather than a shared
+ * `ListQuery<F>` wrapper: that wrapper was only ever `F & ListQueryOptions`,
+ * so it hid an `&` behind a longer spelling that every consumer had to alias
+ * anyway — and its bare form silently meant "no facets at all".
+ *
+ * Facets sit at the TOP LEVEL because that is what jobs-service parses
+ * (`workMode[0]=remote`), and `buildQuerySuffix` encodes the whole object as
+ * one flat query string — no `filter[...]` wrapper.
+ */
+export type JobListQuery = JobFilter & ListQueryOptions;
+/**
+ * One place a job is offered.
+ *
+ * Named and exported rather than left inline on `JobDoc`, because consumers
+ * need to talk about a location on its own — marketing groups a digest by it,
+ * and hand-rolling the triple there is how a consumer ends up with a `country`
+ * where this says `countryCode`, matching nothing while typechecking fine.
+ *
+ * `countryCode` is uppercase ISO alpha-2 ("IN", "SE"); `city` and `state` are
+ * display names.
+ */
+export type JobLocation = NonNullable<InferType<typeof JobSchema>['locations']>[number];
+/**
+ * A job as jobs-service returns it. DERIVED from `JobSchema`, never re-declared.
+ *
+ * The hand-written version drifted from the data it claimed to describe: it said
+ * `salary: { min, max, currency }` where a job carries `salaryRange` (with
+ * `compensationType` and `isNegotiable` besides), and its location was three
+ * optional fields where a real one has `country`, `address` and `geo`. Nothing
+ * caught it because the index signature below makes every field access
+ * typecheck, so an email template read `job.title` for months.
+ *
+ * `Partial` because a caller may narrow the response with `fields`; the index
+ * signature stays for the same reason — a projection can also carry computed
+ * extras (`score`, `id`) that the stored schema does not declare.
+ */
+export type JobDoc = Partial<InferType<typeof JobSchema>> & {
+    [field: string]: unknown;
+};
+/** A page of jobs plus how many matched the FILTER (not the page size). */
+export interface JobPage {
+    results: JobDoc[];
+    total: number;
+    page?: number;
+    limit?: number;
+}
+export interface BookmarkResult {
+    bookmarked?: boolean;
+    [field: string]: unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AACrC,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGjE;;;;;;;;;;;;;;;;;;GAkBG;AACH;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC;AAEnE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,gBAAgB,CAAC;AAExD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,CAAC,SAAS,CAAC,OAAO,SAAS,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAExF;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,SAAS,CAAC,CAAC,GAAG;IAC1D,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B,CAAC;AAEF,2EAA2E;AAC3E,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@thejob/jobs-client",
+  "version": "1.0.0",
+  "description": "Typed TypeScript/JavaScript client for the thejob-jobs-service HTTP API.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@thejob/schema": "^2.1.9",
+    "@thejob/util": "file:.yalc/@thejob/util",
+    "qs": "^6.16.0",
+    "yup": "^1.7.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.19",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.9"
+  }
+}