@profullstack/agenticjobs 0.1.0

package/dist/schema/instance.js

@@ -0,0 +1,147 @@
+/**
+ * The federation contract.
+ *
+ * Every instance serves a descriptor at `/.well-known/agenticjobs`, and that
+ * one document is how a directory lists it, how a client decides it is talking
+ * to a job board at all, and how one instance searches another. Adding a field
+ * here is additive; a client must ignore what it does not recognise, because
+ * instances upgrade on their owners' schedules and never together.
+ */
+import { clean } from "./text.js";
+/** Bumped only for a change that would break an older reader. */
+export const PROTOCOL_VERSION = 1;
+export const WELL_KNOWN_PATH = '/.well-known/agenticjobs';
+/** How long an instance stays `online` without a successful re-check. */
+export const ONLINE_TTL_MS = 30 * 60 * 1000;
+/** How often an instance re-announces itself. Comfortably inside the TTL. */
+export const HEARTBEAT_MS = 10 * 60 * 1000;
+/** Dropped from the directory after this many consecutive failures. */
+export const MAX_FAILURES = 48;
+export const DEFAULT_DIRECTORY = 'https://agenticjobs.work';
+/**
+ * A URL the directory is willing to list.
+ *
+ * It has to be somewhere another person's browser can actually go. A loopback
+ * or link-local address is only reachable from the machine that published it,
+ * so listing one produces an entry nobody but its owner can ever open — and,
+ * because the directory fetches the URL itself, accepting one would also point
+ * the directory's own HTTP client at its own network.
+ */
+export function publishable(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:')
+        return null;
+    const host = url.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    if (host === 'localhost' || host.endsWith('.localhost') || host.endsWith('.local'))
+        return null;
+    if (host === '::1' || host === '0.0.0.0')
+        return null;
+    if (/^127\./.test(host))
+        return null;
+    if (/^10\./.test(host))
+        return null;
+    if (/^192\.168\./.test(host))
+        return null;
+    if (/^169\.254\./.test(host))
+        return null;
+    // 172.16.0.0/12 is the one private range that is easy to get wrong by eye.
+    if (/^172\.(1[6-9]|2\d|3[01])\./.test(host))
+        return null;
+    // Unique local addresses, fc00::/7.
+    if (/^f[cd][0-9a-f]{2}:/.test(host))
+        return null;
+    // Only the origin is ever kept. A path, a query or credentials in the URL
+    // would all end up concatenated onto endpoint paths later.
+    return new URL(url.origin);
+}
+const MAX_NAME = 80;
+const MAX_TAGLINE = 200;
+/**
+ * Validate a descriptor fetched from an instance.
+ *
+ * Everything here arrived over the network from a stranger, so the URL is
+ * taken from where we fetched it rather than from what the document claims,
+ * and every string is flattened before it can reach a terminal or a page.
+ */
+export function parseDescriptor(input, fetchedFrom) {
+    if (typeof input !== 'object' || input === null)
+        return null;
+    const record = input;
+    const origin = publishable(fetchedFrom);
+    if (origin === null)
+        return null;
+    const protocol = Number(record['protocol']);
+    if (!Number.isFinite(protocol) || protocol < 1)
+        return null;
+    const software = record['software'];
+    const softwareRecord = typeof software === 'object' && software !== null ? software : {};
+    const jobs = record['jobs'];
+    const jobsRecord = typeof jobs === 'object' && jobs !== null ? jobs : {};
+    const endpoints = record['endpoints'];
+    const endpointsRecord = typeof endpoints === 'object' && endpoints !== null
+        ? endpoints
+        : {};
+    const base = origin.origin;
+    const contact = clean(record['contact'], 200);
+    return {
+        protocol: Math.floor(protocol),
+        url: base,
+        name: clean(record['name'], MAX_NAME) || new URL(base).hostname,
+        tagline: clean(record['tagline'], MAX_TAGLINE),
+        topics: Array.isArray(record['topics'])
+            ? record['topics']
+                .map((topic) => clean(topic, 40).toLowerCase())
+                .filter((topic) => topic !== '')
+                .slice(0, 12)
+            : [],
+        software: {
+            name: clean(softwareRecord['name'], 40) || 'unknown',
+            version: clean(softwareRecord['version'], 20) || '0',
+        },
+        jobs: {
+            open: count(jobsRecord['open']),
+            total: count(jobsRecord['total']),
+        },
+        endpoints: {
+            search: relative(endpointsRecord['search'], base, '/api/v1/jobs'),
+            openapi: relative(endpointsRecord['openapi'], base, '/api/v1/openapi.json'),
+            mcp: relative(endpointsRecord['mcp'], base, '/api/mcp'),
+            feed: relative(endpointsRecord['feed'], base, '/jobs.json'),
+        },
+        directory: record['directory'] === true,
+        contact: contact === '' ? null : contact,
+    };
+}
+function count(value) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return 0;
+    return Math.min(10_000_000, Math.floor(parsed));
+}
+/**
+ * Endpoints are pinned to the instance's own origin.
+ *
+ * An instance that advertises `https://example.com/api` for its search
+ * endpoint would otherwise have every federated client in the network query
+ * example.com on its behalf, with the directory's blessing.
+ */
+function relative(value, base, fallback) {
+    if (typeof value !== 'string' || value.trim() === '')
+        return `${base}${fallback}`;
+    try {
+        const resolved = new URL(value, base);
+        if (resolved.origin !== base)
+            return `${base}${fallback}`;
+        return resolved.toString();
+    }
+    catch {
+        return `${base}${fallback}`;
+    }
+}
+//# sourceMappingURL=instance.js.map

package/dist/schema/instance.js.map

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

package/dist/schema/job.d.ts

@@ -0,0 +1,151 @@
+/**
+ * What a job is, on this board and on every other one.
+ *
+ * These shapes are the contract between the seven front doors — pages, REST,
+ * MCP, CLI, TUI, desktop and the directory — so a field that is not here is a
+ * field one surface has and the others do not. They are also the federation
+ * contract: an instance reading another instance's listings parses exactly
+ * this, which is why the enumerations are string unions with runtime guards
+ * rather than TypeScript enums nobody else can see.
+ */
+export declare const EMPLOYMENT_TYPES: readonly ["full-time", "part-time", "contract", "internship", "temporary"];
+export type EmploymentType = (typeof EMPLOYMENT_TYPES)[number];
+export declare const WORKPLACES: readonly ["remote", "hybrid", "onsite"];
+export type Workplace = (typeof WORKPLACES)[number];
+export declare const SENIORITIES: readonly ["intern", "junior", "mid", "senior", "staff", "principal", "lead"];
+export type Seniority = (typeof SENIORITIES)[number];
+export declare const SALARY_PERIODS: readonly ["hour", "day", "week", "month", "year"];
+export type SalaryPeriod = (typeof SALARY_PERIODS)[number];
+export declare const JOB_STATUSES: readonly ["draft", "published", "closed"];
+export type JobStatus = (typeof JOB_STATUSES)[number];
+/**
+ * Where an employer stands on candidates who let an agent do the work.
+ *
+ * This board exists because that question currently gets answered by silent
+ * rejection. Making it a required field means a listing has to say, and an
+ * agent reading the listing can decide whether to bother.
+ *
+ * - `welcome`     agent-written applications are fine, no disclosure asked.
+ * - `disclose`    fine, but say so; the application carries an `agent` block.
+ * - `human-only`  the employer wants a person to have written it.
+ */
+export declare const AGENT_POLICIES: readonly ["welcome", "disclose", "human-only"];
+export type AgentPolicy = (typeof AGENT_POLICIES)[number];
+export interface Salary {
+    min: number | null;
+    max: number | null;
+    currency: string;
+    period: SalaryPeriod;
+    equity: string | null;
+}
+export interface Organisation {
+    id: string;
+    slug: string;
+    name: string;
+    website: string | null;
+    logoUrl: string | null;
+    description: string | null;
+    createdAt: string;
+}
+export interface Job {
+    id: string;
+    slug: string;
+    org: Organisation;
+    title: string;
+    /** Markdown. Rendered on pages, handed over raw everywhere else. */
+    description: string;
+    employmentType: EmploymentType;
+    workplace: Workplace;
+    seniority: Seniority | null;
+    /** Free text ("Berlin", "US timezones"). `null` when workplace is remote and unrestricted. */
+    location: string | null;
+    /** ISO 3166-1 alpha-2 codes a remote hire may sit in. Empty means anywhere. */
+    remoteRegions: string[];
+    salary: Salary;
+    tags: string[];
+    stack: string[];
+    requirements: string[];
+    responsibilities: string[];
+    agentPolicy: AgentPolicy;
+    apply: ApplyMethod;
+    status: JobStatus;
+    publishedAt: string | null;
+    expiresAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * How to apply.
+ *
+ * `board` is the one that matters: it means the application is a POST to this
+ * instance against a published schema, which is the only variant an agent can
+ * complete without a browser. The other two exist because employers ask for
+ * them, and a listing that lies about having them is worse than one that says
+ * so plainly.
+ */
+export type ApplyMethod = {
+    via: 'board';
+    schema: ApplySchema;
+} | {
+    via: 'url';
+    url: string;
+} | {
+    via: 'email';
+    email: string;
+};
+/**
+ * The shape of an application, published with the job.
+ *
+ * A subset of JSON Schema on purpose. It is small enough to render as an HTML
+ * form and small enough for a model to fill in without a validator, and both
+ * of those matter more here than expressiveness.
+ */
+export interface ApplySchema {
+    fields: ApplyField[];
+}
+export interface ApplyField {
+    name: string;
+    label: string;
+    type: 'text' | 'textarea' | 'email' | 'url' | 'select' | 'file';
+    required: boolean;
+    /** Only for `select`. */
+    options?: string[];
+    /** Shown under the input, and included in the machine-readable schema. */
+    help?: string;
+    maxLength?: number;
+}
+/** Every job gets these unless the employer replaces them. */
+export declare const DEFAULT_APPLY_SCHEMA: ApplySchema;
+/**
+ * `draft` is the candidate-side control point: an agent prepared it and the
+ * person has not released it yet. An employer never sees a draft.
+ */
+export declare const APPLICATION_STATUSES: readonly ["draft", "new", "reviewing", "rejected", "hired"];
+export type ApplicationStatus = (typeof APPLICATION_STATUSES)[number];
+export interface Application {
+    id: string;
+    jobId: string;
+    /** Answers keyed by `ApplyField.name`. */
+    answers: Record<string, string>;
+    /**
+     * Present when the applicant declared an agent wrote it. Never inferred:
+     * guessing would make the disclosure worthless in both directions.
+     */
+    agent: AgentDisclosure | null;
+    status: ApplicationStatus;
+    /** Null while it is still a draft nobody has sent. */
+    submittedAt: string | null;
+    createdAt: string;
+}
+export interface AgentDisclosure {
+    /** Free text, e.g. "claude-opus-5 via agenticjobs-mcp". */
+    name: string;
+    /** Whether a human read it before it was sent. */
+    supervised: boolean;
+}
+export declare function isEmploymentType(value: unknown): value is EmploymentType;
+export declare function isWorkplace(value: unknown): value is Workplace;
+export declare function isSeniority(value: unknown): value is Seniority;
+export declare function isSalaryPeriod(value: unknown): value is SalaryPeriod;
+export declare function isAgentPolicy(value: unknown): value is AgentPolicy;
+export declare function isJobStatus(value: unknown): value is JobStatus;

package/dist/schema/job.js

@@ -0,0 +1,73 @@
+/**
+ * What a job is, on this board and on every other one.
+ *
+ * These shapes are the contract between the seven front doors — pages, REST,
+ * MCP, CLI, TUI, desktop and the directory — so a field that is not here is a
+ * field one surface has and the others do not. They are also the federation
+ * contract: an instance reading another instance's listings parses exactly
+ * this, which is why the enumerations are string unions with runtime guards
+ * rather than TypeScript enums nobody else can see.
+ */
+export const EMPLOYMENT_TYPES = [
+    'full-time',
+    'part-time',
+    'contract',
+    'internship',
+    'temporary',
+];
+export const WORKPLACES = ['remote', 'hybrid', 'onsite'];
+export const SENIORITIES = ['intern', 'junior', 'mid', 'senior', 'staff', 'principal', 'lead'];
+export const SALARY_PERIODS = ['hour', 'day', 'week', 'month', 'year'];
+export const JOB_STATUSES = ['draft', 'published', 'closed'];
+/**
+ * Where an employer stands on candidates who let an agent do the work.
+ *
+ * This board exists because that question currently gets answered by silent
+ * rejection. Making it a required field means a listing has to say, and an
+ * agent reading the listing can decide whether to bother.
+ *
+ * - `welcome`     agent-written applications are fine, no disclosure asked.
+ * - `disclose`    fine, but say so; the application carries an `agent` block.
+ * - `human-only`  the employer wants a person to have written it.
+ */
+export const AGENT_POLICIES = ['welcome', 'disclose', 'human-only'];
+/** Every job gets these unless the employer replaces them. */
+export const DEFAULT_APPLY_SCHEMA = {
+    fields: [
+        { name: 'name', label: 'Your name', type: 'text', required: true, maxLength: 120 },
+        { name: 'email', label: 'Email', type: 'email', required: true, maxLength: 200 },
+        { name: 'url', label: 'Portfolio, GitHub or LinkedIn', type: 'url', required: false, maxLength: 500 },
+        {
+            name: 'cover',
+            label: 'Why you',
+            type: 'textarea',
+            required: true,
+            maxLength: 5000,
+            help: 'Plain text. Short is fine.',
+        },
+    ],
+};
+/**
+ * `draft` is the candidate-side control point: an agent prepared it and the
+ * person has not released it yet. An employer never sees a draft.
+ */
+export const APPLICATION_STATUSES = ['draft', 'new', 'reviewing', 'rejected', 'hired'];
+export function isEmploymentType(value) {
+    return typeof value === 'string' && EMPLOYMENT_TYPES.includes(value);
+}
+export function isWorkplace(value) {
+    return typeof value === 'string' && WORKPLACES.includes(value);
+}
+export function isSeniority(value) {
+    return typeof value === 'string' && SENIORITIES.includes(value);
+}
+export function isSalaryPeriod(value) {
+    return typeof value === 'string' && SALARY_PERIODS.includes(value);
+}
+export function isAgentPolicy(value) {
+    return typeof value === 'string' && AGENT_POLICIES.includes(value);
+}
+export function isJobStatus(value) {
+    return typeof value === 'string' && JOB_STATUSES.includes(value);
+}
+//# sourceMappingURL=job.js.map

package/dist/schema/job.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job.js","sourceRoot":"","sources":["../../src/schema/job.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,WAAW;IACX,WAAW;IACX,UAAU;IACV,YAAY;IACZ,WAAW;CACH,CAAC;AAGX,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAC;AAGlE,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,CAAU,CAAC;AAGxG,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAU,CAAC;AAGhF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,CAAU,CAAC;AAGtE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,SAAS,EAAE,UAAU,EAAE,YAAY,CAAU,CAAC;AAsF7E,8DAA8D;AAC9D,MAAM,CAAC,MAAM,oBAAoB,GAAgB;IAC/C,MAAM,EAAE;QACN,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE;QAClF,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE;QAChF,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,+BAA+B,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE;QACrG;YACE,IAAI,EAAE,OAAO;YACb,KAAK,EAAE,SAAS;YAChB,IAAI,EAAE,UAAU;YAChB,QAAQ,EAAE,IAAI;YACd,SAAS,EAAE,IAAI;YACf,IAAI,EAAE,4BAA4B;SACnC;KACF;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,CAAU,CAAC;AA0BhG,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,gBAAsC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC9F,CAAC;AACD,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,UAAgC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACxF,CAAC;AACD,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,WAAiC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACzF,CAAC;AACD,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,cAAoC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC5F,CAAC;AACD,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,cAAoC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC5F,CAAC;AACD,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,YAAkC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC1F,CAAC"}

package/dist/schema/jsonld.d.ts

@@ -0,0 +1,18 @@
+/**
+ * schema.org JobPosting.
+ *
+ * Two audiences, one document. Search engines want this because it is the
+ * format they already index, and an agent wants it because it is the one job
+ * description shape it has certainly seen before. Emitting it on the page and
+ * from the API means neither audience needs a bespoke parser for this board.
+ *
+ * The `agentPolicy` and the application schema have no schema.org equivalent,
+ * so they travel in an `additionalProperty` array, which is the vocabulary's
+ * own escape hatch and survives every validator.
+ */
+import type { Job } from './job.ts';
+export interface JsonLdJobPosting extends Record<string, unknown> {
+    '@context': 'https://schema.org';
+    '@type': 'JobPosting';
+}
+export declare function jobPostingJsonLd(job: Job, origin: string): JsonLdJobPosting;

package/dist/schema/jsonld.js

@@ -0,0 +1,120 @@
+/**
+ * schema.org JobPosting.
+ *
+ * Two audiences, one document. Search engines want this because it is the
+ * format they already index, and an agent wants it because it is the one job
+ * description shape it has certainly seen before. Emitting it on the page and
+ * from the API means neither audience needs a bespoke parser for this board.
+ *
+ * The `agentPolicy` and the application schema have no schema.org equivalent,
+ * so they travel in an `additionalProperty` array, which is the vocabulary's
+ * own escape hatch and survives every validator.
+ */
+/** Annualise so `baseSalary` is comparable between listings. */
+const PER_YEAR = {
+    hour: 2080,
+    day: 260,
+    week: 52,
+    month: 12,
+    year: 1,
+};
+export function jobPostingJsonLd(job, origin) {
+    const url = `${origin}/jobs/${job.slug}`;
+    const doc = {
+        '@context': 'https://schema.org',
+        '@type': 'JobPosting',
+        '@id': url,
+        url,
+        title: job.title,
+        description: job.description,
+        datePosted: job.publishedAt ?? job.createdAt,
+        employmentType: EMPLOYMENT[job.employmentType] ?? 'OTHER',
+        hiringOrganization: {
+            '@type': 'Organization',
+            name: job.org.name,
+            ...(job.org.website ? { sameAs: job.org.website } : {}),
+            ...(job.org.logoUrl ? { logo: job.org.logoUrl } : {}),
+        },
+        directApply: job.apply.via === 'board',
+    };
+    if (job.expiresAt)
+        doc['validThrough'] = job.expiresAt;
+    if (job.tags.length > 0)
+        doc['keywords'] = job.tags.join(', ');
+    if (job.seniority)
+        doc['experienceRequirements'] = job.seniority;
+    if (job.requirements.length > 0)
+        doc['qualifications'] = job.requirements.join('\n');
+    if (job.responsibilities.length > 0)
+        doc['responsibilities'] = job.responsibilities.join('\n');
+    if (job.workplace === 'remote') {
+        // Google's own requirement: TELECOMMUTE plus a location the hire may sit
+        // in. Omitting jobLocation on a remote role is the single most common way
+        // a correct-looking posting fails validation.
+        doc['jobLocationType'] = 'TELECOMMUTE';
+        if (job.remoteRegions.length > 0) {
+            doc['applicantLocationRequirements'] = job.remoteRegions.map((code) => ({
+                '@type': 'Country',
+                name: code,
+            }));
+        }
+    }
+    if (job.location) {
+        doc['jobLocation'] = {
+            '@type': 'Place',
+            address: { '@type': 'PostalAddress', addressLocality: job.location },
+        };
+    }
+    const salary = job.salary;
+    if (salary.min !== null || salary.max !== null) {
+        const min = salary.min ?? salary.max;
+        const max = salary.max ?? salary.min;
+        doc['baseSalary'] = {
+            '@type': 'MonetaryAmount',
+            currency: salary.currency.toUpperCase(),
+            value: {
+                '@type': 'QuantitativeValue',
+                minValue: min,
+                maxValue: max,
+                unitText: salary.period.toUpperCase(),
+            },
+        };
+        doc['estimatedSalary'] = {
+            '@type': 'MonetaryAmount',
+            currency: salary.currency.toUpperCase(),
+            value: {
+                '@type': 'QuantitativeValue',
+                minValue: Math.round((min ?? 0) * (PER_YEAR[salary.period] ?? 1)),
+                maxValue: Math.round((max ?? 0) * (PER_YEAR[salary.period] ?? 1)),
+                unitText: 'YEAR',
+            },
+        };
+    }
+    const extra = [
+        { '@type': 'PropertyValue', name: 'agentPolicy', value: job.agentPolicy },
+        { '@type': 'PropertyValue', name: 'applyVia', value: job.apply.via },
+    ];
+    if (job.stack.length > 0) {
+        extra.push({ '@type': 'PropertyValue', name: 'stack', value: job.stack.join(', ') });
+    }
+    if (job.apply.via === 'board') {
+        // The whole point of the board: an agent can read the form it has to fill
+        // in without rendering a page, and the endpoint it posts to is derivable
+        // from the @id above.
+        extra.push({
+            '@type': 'PropertyValue',
+            name: 'applySchemaUrl',
+            value: `${origin}/api/v1/jobs/${job.slug}/apply-schema`,
+        });
+    }
+    doc['additionalProperty'] = extra;
+    return doc;
+}
+const EMPLOYMENT = {
+    'full-time': 'FULL_TIME',
+    'part-time': 'PART_TIME',
+    contract: 'CONTRACTOR',
+    internship: 'INTERN',
+    temporary: 'TEMPORARY',
+};
+//# sourceMappingURL=jsonld.js.map

package/dist/schema/jsonld.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonld.js","sourceRoot":"","sources":["../../src/schema/jsonld.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AASH,gEAAgE;AAChE,MAAM,QAAQ,GAA2B;IACvC,IAAI,EAAE,IAAI;IACV,GAAG,EAAE,GAAG;IACR,IAAI,EAAE,EAAE;IACR,KAAK,EAAE,EAAE;IACT,IAAI,EAAE,CAAC;CACR,CAAC;AAEF,MAAM,UAAU,gBAAgB,CAAC,GAAQ,EAAE,MAAc;IACvD,MAAM,GAAG,GAAG,GAAG,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,CAAC;IACzC,MAAM,GAAG,GAAqB;QAC5B,UAAU,EAAE,oBAAoB;QAChC,OAAO,EAAE,YAAY;QACrB,KAAK,EAAE,GAAG;QACV,GAAG;QACH,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,UAAU,EAAE,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,SAAS;QAC5C,cAAc,EAAE,UAAU,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,OAAO;QACzD,kBAAkB,EAAE;YAClB,OAAO,EAAE,cAAc;YACvB,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,IAAI;YAClB,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvD,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACtD;QACD,WAAW,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,KAAK,OAAO;KACvC,CAAC;IAEF,IAAI,GAAG,CAAC,SAAS;QAAE,GAAG,CAAC,cAAc,CAAC,GAAG,GAAG,CAAC,SAAS,CAAC;IACvD,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,GAAG,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/D,IAAI,GAAG,CAAC,SAAS;QAAE,GAAG,CAAC,wBAAwB,CAAC,GAAG,GAAG,CAAC,SAAS,CAAC;IACjE,IAAI,GAAG,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC;QAAE,GAAG,CAAC,gBAAgB,CAAC,GAAG,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrF,IAAI,GAAG,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC;QAAE,GAAG,CAAC,kBAAkB,CAAC,GAAG,GAAG,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAE/F,IAAI,GAAG,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;QAC/B,yEAAyE;QACzE,0EAA0E;QAC1E,8CAA8C;QAC9C,GAAG,CAAC,iBAAiB,CAAC,GAAG,aAAa,CAAC;QACvC,IAAI,GAAG,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACjC,GAAG,CAAC,+BAA+B,CAAC,GAAG,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBACtE,OAAO,EAAE,SAAS;gBAClB,IAAI,EAAE,IAAI;aACX,CAAC,CAAC,CAAC;QACN,CAAC;IACH,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;QACjB,GAAG,CAAC,aAAa,CAAC,GAAG;YACnB,OAAO,EAAE,OAAO;YAChB,OAAO,EAAE,EAAE,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,GAAG,CAAC,QAAQ,EAAE;SACrE,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;IAC1B,IAAI,MAAM,CAAC,GAAG,KAAK,IAAI,IAAI,MAAM,CAAC,GAAG,KAAK,IAAI,EAAE,CAAC;QAC/C,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC,GAAG,CAAC;QACrC,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC,GAAG,CAAC;QACrC,GAAG,CAAC,YAAY,CAAC,GAAG;YAClB,OAAO,EAAE,gBAAgB;YACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE;YACvC,KAAK,EAAE;gBACL,OAAO,EAAE,mBAAmB;gBAC5B,QAAQ,EAAE,GAAG;gBACb,QAAQ,EAAE,GAAG;gBACb,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE;aACtC;SACF,CAAC;QACF,GAAG,CAAC,iBAAiB,CAAC,GAAG;YACvB,OAAO,EAAE,gBAAgB;YACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE;YACvC,KAAK,EAAE;gBACL,OAAO,EAAE,mBAAmB;gBAC5B,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;gBACjE,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;gBACjE,QAAQ,EAAE,MAAM;aACjB;SACF,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAA8B;QACvC,EAAE,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,GAAG,CAAC,WAAW,EAAE;QACzE,EAAE,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE;KACrE,CAAC;IACF,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACvF,CAAC;IACD,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,KAAK,OAAO,EAAE,CAAC;QAC9B,0EAA0E;QAC1E,yEAAyE;QACzE,sBAAsB;QACtB,KAAK,CAAC,IAAI,CAAC;YACT,OAAO,EAAE,eAAe;YACxB,IAAI,EAAE,gBAAgB;YACtB,KAAK,EAAE,GAAG,MAAM,gBAAgB,GAAG,CAAC,IAAI,eAAe;SACxD,CAAC,CAAC;IACL,CAAC;IACD,GAAG,CAAC,oBAAoB,CAAC,GAAG,KAAK,CAAC;IAElC,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,GAA2B;IACzC,WAAW,EAAE,WAAW;IACxB,WAAW,EAAE,WAAW;IACxB,QAAQ,EAAE,YAAY;IACtB,UAAU,EAAE,QAAQ;IACpB,SAAS,EAAE,WAAW;CACvB,CAAC"}

package/dist/schema/query.d.ts

@@ -0,0 +1,47 @@
+/**
+ * One query shape, used by the page, the API, MCP, the CLI and the federated
+ * search across instances.
+ *
+ * Federation is the reason this is a declared type rather than whatever
+ * querystring each surface felt like parsing: a search fanned out to twelve
+ * instances has to mean the same thing on all of them, and an instance running
+ * an older release has to be able to ignore a field it does not know without
+ * silently returning the wrong set.
+ */
+import { type AgentPolicy, type EmploymentType, type Seniority, type Workplace } from './job.ts';
+export declare const SORTS: readonly ["recent", "relevant", "salary"];
+export type Sort = (typeof SORTS)[number];
+export interface JobQuery {
+    /** Full text over title, description, tags and stack. */
+    q: string | null;
+    employmentType: EmploymentType | null;
+    workplace: Workplace | null;
+    seniority: Seniority | null;
+    agentPolicy: AgentPolicy | null;
+    tags: string[];
+    /** Minimum annualised salary, in the instance's currency. */
+    salaryMin: number | null;
+    org: string | null;
+    sort: Sort;
+    limit: number;
+    offset: number;
+}
+export declare const MAX_LIMIT = 100;
+export declare const EMPTY_QUERY: JobQuery;
+/**
+ * Parse a querystring into a query.
+ *
+ * Unknown values are dropped rather than rejected. A filter this instance does
+ * not understand must not turn a federated search into an error on one node
+ * and a result set on the rest — the user would see a shorter list and no
+ * explanation.
+ */
+export declare function parseQuery(params: URLSearchParams): JobQuery;
+/** The inverse, so a client can rebuild a link to the search it just ran. */
+export declare function queryToParams(query: JobQuery): URLSearchParams;
+export interface JobPage<T> {
+    items: T[];
+    total: number;
+    limit: number;
+    offset: number;
+}