Startupkit Jobs

https://github.com/startupkit-app/jobs-js
Admin
Typed, zero-dependency fetch client for Kit's (startupkit.app) public hiring API — list published...
Tokens:14,277
Snippets:151
Trust Score:3
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install the SDK

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/index.md

Use npm to add the package to your project dependencies.

```bash
npm install @startupkit-app/jobs
```

--------------------------------

### allJobs Usage Example

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/KitJobsClient.md

Example of iterating over all jobs using the client.

```ts
import { createClient } from "@startupkit-app/jobs";

const kit = createClient({ secretKey: process.env.KIT_SECRET_KEY });

for await (const job of kit.allJobs()) {
  console.log(job.id, job.title);
}
```

--------------------------------

### Apply Method Usage

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/KitJobsClient.md

Basic usage example for submitting an application.

```ts
const result = await kit.apply(
  job.id,
  {
    email: "jane@example.com",
    first_name: "Jane",
    last_name: "Doe",
    responses: { motivation: "…" },
  },
  { turnstileToken }
);
console.log(result.id, result.status); // "app_…", "submitted"
```

--------------------------------

### Usage of listJobs

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/KitJobsClient.md

Example showing client initialization, job listing with filters, and pagination handling.

```ts
import { createClient } from "@startupkit-app/jobs";

const kit = createClient({ secretKey: process.env.KIT_SECRET_KEY });

const page = await kit.listJobs({ department: "Engineering", remote: true });
for (const job of page.data) {
  console.log(job.title, job.location, job.url);
}
if (page.hasNextPage) {
  const next = await page.nextPage()!;
}
```

--------------------------------

### getJob Usage Example

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/KitJobsClient.md

Example of retrieving specific job details using a public token.

```ts
import { createClient } from "@startupkit-app/jobs";

const kit = createClient({ publishableKey: "pk_live_…" });
const job = await kit.getJob("tok_abc123");
console.log(job.description_html, job.accepting_applications);
```

--------------------------------

### Browser usage with publishable key and error handling

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/createClient.md

Example of initializing the client in the browser and handling API errors.

```ts
import { createClient, KitApiError } from "@startupkit-app/jobs";

const kit = createClient({ publishableKey: "pk_live_…" });

const job = await kit.getJob("tok_abc123");
console.log(job.title, job.accepting_applications);

try {
  const result = await kit.apply(job.id, { email: "jane@example.com" });
  console.log(result.id, result.status);
} catch (error) {
  if (error instanceof KitApiError && error.code === "already_applied") {
    // 409 — retry is pointless; show the existing application
  }
}
```

--------------------------------

### Server-side usage with secret key

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/createClient.md

Example of initializing the client on the server using a secret key.

```ts
import { createClient } from "@startupkit-app/jobs";

const kit = createClient({ secretKey: process.env.KIT_SECRET_KEY });

for await (const job of kit.allJobs({ remote: true })) {
  console.log(job.title, job.department, job.location, job.url);
}
```

--------------------------------

### Error Handling for Apply

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/KitJobsClient.md

Example demonstrating how to catch and handle KitApiError responses.

```ts
try {
  await kit.apply(job.id, { email });
} catch (error) {
  if (error instanceof KitApiError) {
    if (error.code === "already_applied") {
      // 409 — show existing application
    } else if (error.code === "validation_failed") {
      console.log(error.fields); // { email: ["is invalid"], … }
    }
  }
}
```

--------------------------------

### GET /api/public/v1/talent_pool

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/endpoints.md

Retrieves the talent-pool intake schema.

```APIDOC
## GET /api/public/v1/talent_pool

### Description
Talent-pool intake schema.

### Method
GET

### Endpoint
/api/public/v1/talent_pool

### Response
#### Success Response (200)
- **accepting_signups** (boolean) - Whether accepting entries.
- **consent** (TalentPoolConsent) - required, disclosure_html, retention_months, privacy_policy_url.
- **fields** (TalentPoolField[]) - Intake fields.
- **resume** (TalentPoolResume) - Resume constraints.
- **turnstile** (TurnstileConfig) - required, sitekey.
```

--------------------------------

### Handling KitApiError

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/errors.md

Example of catching and inspecting a KitApiError to access status, code, and field-level validation messages.

```ts
import { createClient, KitApiError } from "@startupkit-app/jobs";

const kit = createClient({ publishableKey: "pk_live_…" });

try {
  await kit.apply(job.id, { email });
} catch (error) {
  if (error instanceof KitApiError) {
    console.log(error.status, error.code, error.message);
    if (error.fields) {
      console.log(Object.entries(error.fields)
        .map(([field, messages]) => `${field}: ${messages.join(", ")}`));
    }
  }
}
```

--------------------------------

### GET /api/public/v1/jobs/{publicToken}

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/endpoints.md

Retrieves the full details of a specific job posting using its public token.

```APIDOC
## GET /api/public/v1/jobs/{publicToken}

### Description
Retrieves full job details including description, hiring stages, and application form requirements.

### Method
GET

### Endpoint
/api/public/v1/jobs/{publicToken}

### Parameters
#### Path Parameters
- **publicToken** (string) - Required - The unique identifier for the job, passed through encodeURIComponent.

### Response
#### Success Response (200)
- **id** (string) - Job ID
- **title** (string) - Job title
- **department** (string) - Department name
- **location** (string) - Job location
- **employment_type** (string) - Employment type
- **remote** (boolean) - Remote status
- **published_at** (string) - Publication date
- **url** (string) - Job URL
- **salary** (string) - Salary information
- **description_html** (string) - Full description as HTML
- **accepting_applications** (boolean) - Whether accepting applications
- **stages** (Stage[]) - Hiring stages
- **application_form** (ApplicationForm) - Application form configuration
```

--------------------------------

### GET /api/public/v1/jobs

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/endpoints.md

Retrieves a paginated list of published job postings, with optional filtering by department, location, employment type, and remote status.

```APIDOC
## GET /api/public/v1/jobs

### Description
List published jobs (one page).

### Method
GET

### Endpoint
/api/public/v1/jobs

### Parameters
#### Query Parameters
- **department** (string) - Optional - Filter by department.
- **location** (string) - Optional - Filter by location.
- **employment_type** (string) - Optional - Filter by employment type.
- **remote** (boolean) - Optional - Filter by remote.
- **page** (number) - Optional - Page index.
- **per_page** (number) - Optional - Records per page.

### Response
#### Success Response (200)
- **data** (Job[]) - Job records on this page.
- **pagination** (Pagination) - { current_page, total_pages, total_count, per_page }.
```

--------------------------------

### Initializing the API Client

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/createClient.md

Demonstrates how to initialize the client with default settings or a custom base URL.

```ts
import { createClient, DEFAULT_BASE_URL } from "@startupkit-app/jobs";

const kit = createClient({ secretKey: "sk_…" }); // origin = DEFAULT_BASE_URL

const other = createClient({
  secretKey: "sk_…",
  baseUrl: "https://api.internal.example",
}); // alternate origin
```

--------------------------------

### Initialize and use the client

Source: https://github.com/startupkit-app/jobs-js/blob/main/README.md

Demonstrates server-side usage with a secret key, including pagination and fetching full job details.

```ts
import { createClient } from "@startupkit-app/jobs";

const kit = createClient({ secretKey: process.env.KIT_SECRET_KEY });

// One page at a time
const page = await kit.listJobs({ department: "Engineering", remote: true });
for (const job of page.data) {
  console.log(job.title, job.location, job.url);
}
if (page.hasNextPage) {
  const next = await page.nextPage()!;
}

// Or iterate everything
for await (const job of kit.allJobs()) {
  console.log(job.id, job.title);
}

// Full detail: description, stages, and the application form definition
const job = await kit.getJob(page.data[0].id);
console.log(job.description_html, job.accepting_applications);
```

--------------------------------

### createClient(options?: ClientOptions): KitJobsClient

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/createClient.md

Initializes a new KitJobsClient instance. The function accepts an optional configuration object to specify authentication keys and the API base URL.

```APIDOC
## createClient(options?: ClientOptions): KitJobsClient

### Description
Factory function to construct a `KitJobsClient`. This is the required entry point for interacting with the Kit jobs API.

### Parameters
- **options.publishableKey** (string) - Optional - Publishable key (pk_...). Browser-safe; requests are CORS-restricted.
- **options.secretKey** (string) - Optional - Secret key (sk_...). Server-only; never use in a browser.
- **options.baseUrl** (string) - Optional - API origin. Defaults to "https://app.startupkit.app".

### Return
- **KitJobsClient** - The initialized client instance.

### Throws
- **Error** - Thrown if both `publishableKey` and `secretKey` are provided.
- **Error** - Thrown if `secretKey` is used in a browser environment.

### Usage Example
```ts
import { createClient } from "@startupkit-app/jobs";

// Server-side usage
const kit = createClient({ secretKey: process.env.KIT_SECRET_KEY });

// Browser usage
const browserKit = createClient({ publishableKey: "pk_live_..." });
```
```

--------------------------------

### createClient(options)

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/createClient.md

Initializes a new client instance for interacting with the API.

```APIDOC
## createClient(options)

### Description
Initializes the SDK client. The client uses the `DEFAULT_BASE_URL` by default, which can be overridden by providing a custom `baseUrl`.

### Parameters
- **options** (object) - Required
  - **secretKey** (string) - Required - The secret key used for authentication.
  - **baseUrl** (string) - Optional - The base URL for API requests. Defaults to "https://app.startupkit.app".
```

--------------------------------

### createClient

Source: https://github.com/startupkit-app/jobs-js/blob/main/README.md

Initializes the Kit API client with either a publishable or secret key.

```APIDOC
## createClient

### Description
Initializes a new instance of the Kit API client. You must provide either a `publishableKey` or a `secretKey`.

### Signature
`createClient({ publishableKey?: string, secretKey?: string })`

### Parameters
- **publishableKey** (string) - Optional - Used for browser-based requests.
- **secretKey** (string) - Optional - Used for server-side requests.
```

--------------------------------

### Import public symbols from @startupkit-app/jobs

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/index.md

Use the package root to import client factories, error classes, and TypeScript definitions. Resource-specific modules are not intended for direct import.

```ts
import {
  createClient,
  DEFAULT_BASE_URL,
  KitApiError,
  KitNetworkError,
} from "@startupkit-app/jobs";

import type {
  ApplicationForm,
  ApplicationInput,
  ApplicationResult,
  ClientOptions,
  ErrorEnvelope,
  FormField,
  FormFieldType,
  Job,
  JobDetail,
  ListJobsParams,
  Page,
  Pagination,
  Question,
  QuestionType,
  RequestOptions,
  ResumeRequirements,
  Salary,
  Stage,
  TalentPoolConsent,
  TalentPoolField,
  TalentPoolForm,
  TalentPoolInput,
  TalentPoolResult,
  TalentPoolResume,
  TurnstileConfig,
  UploadMeta,
  UploadTicket,
} from "@startupkit-app/jobs";

import type { KitJobsClient } from "@startupkit-app/jobs";
```

--------------------------------

### Initialize and Render Job Application Form

Source: https://github.com/startupkit-app/jobs-js/blob/main/examples/browser-apply.html

Initializes the client, fetches job metadata, and dynamically renders the application form elements based on the job configuration.

```javascript
import { createClient, KitApiError } from "https://esm.sh/@startupkit-app/jobs@0.1.0";

const PUBLISHABLE_KEY = "pk_live_REPLACE_ME"; // pk_ keys are browser-safe
const JOB_TOKEN = new URLSearchParams(location.search).get("job") ?? "REPLACE_ME";
const kit = createClient({ publishableKey: PUBLISHABLE_KEY });

const form = document.getElementById("apply-form");
const status = document.getElementById("status");

const job = await kit.getJob(JOB_TOKEN);
document.getElementById("job-title").textContent = job.title;
document.getElementById("job-description").innerHTML = job.description_html;
document.getElementById("consent").innerHTML = job.application_form.consent_disclosure_html;

// Render screening questions
const questionsEl = document.getElementById("questions");
for (const question of job.application_form.questions) {
  const label = document.createElement("label");
  label.textContent = question.prompt + (question.required ? " *" : "");
  const input = document.createElement("textarea");
  input.name = `question:${question.key}`;
  input.required = question.required;
  input.maxLength = question.max_length;
  label.appendChild(input);
  questionsEl.appendChild(label);
}

// Render Turnstile when the job requires it
let turnstileToken;
if (job.application_form.turnstile.required) {
  window.turnstile?.render("#turnstile-widget", {
    sitekey: job.application_form.turnstile.sitekey,
    callback: (token) => {
      turnstileToken = token;
    },
  });
}

if (job.accepting_applications) form.hidden = false;
else status.textContent = "This job is no longer accepting applications.";
```

--------------------------------

### Package Entry Point Configuration

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/index.md

The package.json configuration defining the dual ESM and CJS exports.

```json
"main": "./dist/index.cjs",
"module": "./dist/index.js",
"types": "./dist/index.d.ts",
"exports": {
  ".": {
    "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
    "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
  }
}
```

--------------------------------

### client.apply

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/index.md

Submits an application for a job.

```APIDOC
## client.apply(publicToken, input, opts?)

### Description
Submits an application to a specific job identified by the public token.
```

--------------------------------

### uploadFile(file, meta?)

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/KitJobsClient.md

High-level wrapper that handles the full upload process, including checksum calculation, registration, and the direct PUT request.

```APIDOC
## uploadFile(file: Blob | File, meta?: { filename?: string; content_type?: string })

### Description
Performs the complete direct-upload process: computes the MD5 checksum, registers the upload, and executes the PUT request to the storage provider.

### Parameters
- **file** (Blob | File) - Required - The file or blob data to upload.
- **meta.filename** (string) - Optional - Remote blob filename override.
- **meta.content_type** (string) - Optional - Content-type override.

### Return
- **Promise<{ signed_id: string }>** - The signed blob ID to be used in application inputs.

### Errors
- **KitNetworkError** - Thrown if the direct PUT request fails or returns a non-2xx status.

### Usage
```ts
const file = fileInput.files[0];
const { signed_id } = await kit.uploadFile(file);
await kit.apply(job.id, { email: "jane@example.com", resume_signed_id: signed_id });
```
```

--------------------------------

### ClientOptions interface

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/createClient.md

Configuration options for the client, including authentication keys and base URL.

```ts
export interface ClientOptions {
  /** Publishable key (`pk_…`) — safe for browsers; CORS-restricted by Origin. */
  publishableKey?: string;
  /** Secret key (`sk_…`) — server-side only. Never ship it to a browser. */
  secretKey?: string;
  /** API origin. Defaults to `https://app.startupkit.app`. */
  baseUrl?: string;
}
```

--------------------------------

### Upload a resume file

Source: https://github.com/startupkit-app/jobs-js/blob/main/README.md

Use the uploadFile method to handle direct-to-storage uploads and retrieve a signed_id for the application.

```ts
const file = fileInput.files[0]; // or a Blob in Node

// The job's constraints — validate client-side before uploading:
const { required, content_types, max_byte_size } = job.application_form.resume;

const { signed_id } = await kit.uploadFile(file);

await kit.apply(job.id, {
  email: "jane@example.com",
  resume_signed_id: signed_id,
});
```

--------------------------------

### kit.apply(jobId, data, options)

Source: https://github.com/startupkit-app/jobs-js/blob/main/README.md

Submits a job application for a specific job posting.

```APIDOC
## kit.apply(jobId, data, options)

### Description
Submits an application for a job. Includes support for Cloudflare Turnstile tokens for spam protection.

### Parameters
- **jobId** (string) - Required - The ID of the job being applied to.
- **data** (object) - Required - Application data including email, first_name, last_name, responses, and resume_signed_id.
- **options** (object) - Optional - Additional options such as { turnstileToken: string }.

### Response
- **result** (object) - Contains the application ID and status (e.g., 'submitted').
```

--------------------------------

### KitJobsClient Methods

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/KitJobsClient.md

The KitJobsClient interface provides the following methods for interacting with the jobs API.

```APIDOC
## listJobs(params?: ListJobsParams, options?: RequestOptions)

### Description
Lists published jobs, one page at a time.

## allJobs(params?: ListJobsParams, options?: RequestOptions)

### Description
Iterates every published job across all pages.

## getJob(publicToken: string, options?: RequestOptions)

### Description
Fetches full job detail (description, stages, application form).

## createUpload(meta: UploadMeta)

### Description
Low-level: registers a blob and returns direct-upload instructions.

## uploadFile(file: Blob | File, meta?: { filename?: string; content_type?: string })

### Description
High-level resume/file upload: computes the base64 MD5 checksum, registers the blob, PUTs the bytes to storage, and returns the signed_id to pass in apply.

## apply(publicToken: string, input: ApplicationInput, opts?: { turnstileToken?: string })

### Description
Submits an application to a job.

## getTalentPool(options?: RequestOptions)

### Description
Fetches the talent-pool intake schema (consent terms, fields, resume rules).

## joinTalentPool(input: TalentPoolInput, opts?: { turnstileToken?: string })

### Description
Adds someone to the talent pool. The entry is created unverified and Kit emails a double-opt-in link.
```

--------------------------------

### Apply to a job with Turnstile

Source: https://github.com/startupkit-app/jobs-js/blob/main/README.md

Initialize the client and submit an application, including a Cloudflare Turnstile token if required by the job configuration.

```ts
import { createClient } from "@startupkit-app/jobs";

const kit = createClient({ publishableKey: "pk_live_…" });

const job = await kit.getJob("tok_abc123");
// Render job.application_form.fields and job.application_form.questions,
// show job.application_form.consent_disclosure_html near the submit button.

const result = await kit.apply(
  job.id,
  {
    email: "jane@example.com",
    first_name: "Jane",
    last_name: "Doe",
    responses: { motivation: "…" }, // keyed by Question.key
  },
  { turnstileToken } // from the Turnstile widget callback
);

console.log(result.id, result.status); // "app_…", "submitted"
```

--------------------------------

### client.uploadFile

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/index.md

Handles the full file upload flow.

```APIDOC
## client.uploadFile(file, meta?)

### Description
Computes an MD5 checksum, registers the upload, and performs the direct PUT request to the storage provider. Returns the signed_id.
```

--------------------------------

### Create an upload ticket

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/KitJobsClient.md

Use createUpload to register a file and receive a signed URL and headers for a direct PUT request.

```ts
const ticket = await kit.createUpload({
  filename: "resume.pdf",
  byte_size: 1234,
  checksum: "…", // base64 MD5
  content_type: "application/pdf",
});
console.log(ticket.signed_id, ticket.direct_upload.url);
```

--------------------------------

### allJobs Implementation

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/KitJobsClient.md

The internal implementation of the allJobs async generator.

```ts
export async function* allJobs(
  http: Http,
  params: ListJobsParams = {},
  options?: RequestOptions
): AsyncGenerator<Job, void, undefined> {
  let page: Page<Job> | null = await listJobs(http, params, options);
  while (page) {
    yield* page.data;
    const next = page.nextPage();
    page = next ? await next : null;
  }
}
```

--------------------------------

### kit.uploadFile(file)

Source: https://github.com/startupkit-app/jobs-js/blob/main/README.md

Uploads a file directly to storage and returns a signed ID for use in an application.

```APIDOC
## kit.uploadFile(file)

### Description
Handles the direct upload process for files like resumes. It computes the MD5 checksum, registers the blob, and uploads the bytes to storage.

### Parameters
- **file** (File|Blob) - Required - The file object to be uploaded.

### Response
- **signed_id** (string) - The identifier to be used in the apply method.
```

--------------------------------

### createClient function signature

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/createClient.md

The factory function signature for initializing the client.

```ts
export function createClient(options: ClientOptions = {}): KitJobsClient
```

--------------------------------

### POST /api/public/v1/talent_pool/entries

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/endpoints.md

Submit a talent-pool signup entry.

```APIDOC
## POST /api/public/v1/talent_pool/entries

### Description
Submit a talent-pool signup.

### Method
POST

### Endpoint
/api/public/v1/talent_pool/entries

### Parameters
#### Request Body
- **talent_pool_entry** (TalentPoolInput) - Required - Signup; consent must be affirmative.
- **turnstile_token** (string) - Optional - From opts.turnstileToken.

### Request Example
{
  "talent_pool_entry": {
    "email": "jane@example.com",
    "linkedin_url": "https://linkedin.com/in/jane",
    "resume_signed_id": "…",
    "consent": true,
    "consent_ip_address": "203.0.113.6"
  },
  "turnstile_token": "…"
}

### Response
#### Success Response (200/201)
- **id** (string) - Entry id (tpe_…).
- **status** (string) - Unverified until double-opt-in (pending_verification).
- **submitted_at** (string) - ISO 8601.

#### Response Example
{
  "id": "tpe_12345",
  "status": "pending_verification",
  "submitted_at": "2023-10-27T10:00:00Z"
}
```

--------------------------------

### client.uploadFile

Source: https://github.com/startupkit-app/jobs-js/blob/main/README.md

Uploads a file to the service.

```APIDOC
## client.uploadFile

### Description
Uploads a file and returns a signed ID.

### Signature
`client.uploadFile(file, meta?): Promise<{ signed_id: string }>`
```

--------------------------------

### Manage Talent Pool Intake and Submission

Source: https://github.com/startupkit-app/jobs-js/blob/main/README.md

Retrieves the talent pool configuration and submits a new entry. Ensure the form is hidden if pool.accepting_signups is false.

```ts
const pool = await kit.getTalentPool();

if (!pool.accepting_signups) return; // hide the form entirely

// Render pool.fields, and pool.consent.disclosure_html next to a checkbox.
// pool.consent.retention_months says how long the entry is kept;
// pool.consent.privacy_policy_url may be null.

const resume = checkbox.checked && file ? await kit.uploadFile(file) : undefined;

const entry = await kit.joinTalentPool(
  {
    email: "jane@example.com",
    linkedin_url: "https://linkedin.com/in/jane",
    resume_signed_id: resume?.signed_id,
    consent: consentCheckbox.checked, // never hardcode true — see below
  },
  { turnstileToken } // when pool.turnstile.required
);

console.log(entry.id, entry.status); // "tpe_…", "pending_verification"
```

--------------------------------

### Catching API and Network Errors

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/errors.md

Demonstrates how to differentiate between API-specific errors and network-level failures using instanceof checks.

```ts
import { createClient, KitApiError, KitNetworkError } from "@startupkit-app/jobs";

const kit = createClient({ publishableKey: "pk_live_…" });

try {
  await kit.apply(job.id, { email });
} catch (error) {
  if (error instanceof KitApiError) {
    switch (error.code) {
      case "already_applied":         /* 409 */
        break;
      case "validation_failed":       /* 422 — see error.fields */
        console.log(error.fields);   // { email: ["is invalid"], … }
        break;
      case "turnstile_failed":       /* 422 — refresh the widget and retry */
        break;
      default:
        console.error(error.status, error.code, error.message);
    }
  } else if (error instanceof KitNetworkError) {
    /* network / DNS / direct-upload PUT failure — retry or offline UI */
  }
}
```

--------------------------------

### POST /api/public/v1/jobs/{publicToken}/applications

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/endpoints.md

Submits an application for a specific job posting.

```APIDOC
## POST /api/public/v1/jobs/{publicToken}/applications

### Description
Submits a new job application for the specified job token.

### Method
POST

### Endpoint
/api/public/v1/jobs/{publicToken}/applications

### Parameters
#### Path Parameters
- **publicToken** (string) - Required - The unique identifier for the job.

#### Request Body
- **application** (ApplicationInput) - Required - The application data including contact info, responses, and resume ID.
- **turnstile_token** (string) - Optional - Required when form requires Turnstile verification.

### Request Example
{
  "application": {
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": null,
    "responses": { "motivation": "…" },
    "resume_signed_id": "…",
    "files": {}
  },
  "turnstile_token": "…"
}

### Response
#### Success Response (200/201)
- **id** (string) - Application id
- **status** (string) - Always "submitted"
- **job** (string) - Job public token
- **submitted_at** (string) - ISO 8601 timestamp
```

--------------------------------

### allJobs(params?: ListJobsParams, options?: RequestOptions)

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/KitJobsClient.md

Fetches all jobs using an async generator that lazily pulls pages of jobs.

```APIDOC
## allJobs(params?: ListJobsParams, options?: RequestOptions)

### Description
Fetches all jobs by lazily pulling pages of jobs and yielding each job individually.

### Parameters
- **params** (ListJobsParams) - Optional - Same filters as listJobs.
- **options** (RequestOptions) - Optional - Per-request fetch options.

### Return
- **AsyncIterable<Job>** - An async generator that yields every Job across all pages.

### Usage
```ts
import { createClient } from "@startupkit-app/jobs";

const kit = createClient({ secretKey: process.env.KIT_SECRET_KEY });

for await (const job of kit.allJobs()) {
  console.log(job.id, job.title);
}
```
```

--------------------------------

### client.allJobs

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/index.md

Retrieves all jobs as an asynchronous iterable.

```APIDOC
## client.allJobs(params?)

### Description
Returns an AsyncIterable of all jobs matching the provided parameters.
```

--------------------------------

### Upload a file

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/KitJobsClient.md

Use uploadFile to perform the complete direct-upload process, including checksum generation and the final PUT request.

```ts
const file = fileInput.files[0];
const { signed_id } = await kit.uploadFile(file);
await kit.apply(job.id, { email: "jane@example.com", resume_signed_id: signed_id });
```

--------------------------------

### client.createUpload

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/index.md

Registers a file upload and receives an upload ticket.

```APIDOC
## client.createUpload(meta)

### Description
Registers a blob for upload and returns an UploadTicket containing direct upload instructions.
```

--------------------------------

### POST /api/public/v1/direct_uploads

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/endpoints.md

Registers a blob for direct upload.

```APIDOC
## POST /api/public/v1/direct_uploads

### Description
Register a blob for direct upload (low-level).

### Method
POST

### Endpoint
/api/public/v1/direct_uploads

### Request Body
- **blob** (UploadMeta) - Required - Blob metadata (built by uploadFile; checksum is base64 MD5).

### Request Example
{
  "blob": {
    "filename": "resume.pdf",
    "byte_size": 1234,
    "checksum": "…",
    "content_type": "application/pdf"
  }
}

### Response
#### Success Response (200/201)
- **signed_id** (string) - Signed blob id.
- **filename** (string) - Echoed filename.
- **content_type** (string) - Echoed content type.
- **byte_size** (number) - Echoed byte size.
- **direct_upload.url** (string) - Storage URL for the PUT.
- **direct_upload.headers** (Record<string, string>) - Headers for the PUT.
```

--------------------------------

### Define RequestOptions interface

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/types.md

Configuration options for fetch requests, supporting cache directives, Next.js revalidation, and abort signals.

```ts
export interface RequestOptions {
  cache?: RequestCache;
  next?: { revalidate?: number | false; tags?: string[] };
  signal?: AbortSignal;
}
```

--------------------------------

### client.listJobs

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/index.md

Retrieves a paginated list of jobs.

```APIDOC
## client.listJobs(params?)

### Description
Fetches a page of job listings based on provided parameters.

### Parameters
- **params** (object) - Optional
```

--------------------------------

### Retrieve Talent Pool Configuration

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/KitJobsClient.md

Fetches the talent pool intake schema to determine if signups are enabled and to retrieve consent details.

```ts
const pool = await kit.getTalentPool();
if (!pool.accepting_signups) return; // no signup form
console.log(pool.consent.disclosure_html, pool.consent.retention_months);
```

--------------------------------

### Define ResumeRequirements interface

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/types.md

Specifies constraints for resume uploads, including size and content type limits.

```ts
export interface ResumeRequirements {
  required: boolean;
  content_types: string[];
  max_byte_size: number;
}
```

--------------------------------

### listJobs Method Signature

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/KitJobsClient.md

The method signature for retrieving a paginated list of jobs.

```ts
listJobs(params?: ListJobsParams, options?: RequestOptions): Promise<Page<Job>>
```

--------------------------------

### allJobs Method Signature

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/KitJobsClient.md

The signature for the allJobs method.

```ts
allJobs(params?: ListJobsParams, options?: RequestOptions): AsyncIterable<Job>
```

--------------------------------

### Register a blob for direct upload

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/endpoints.md

Request body schema for registering a blob. Requires a Bearer token for authentication.

```json
{
  "blob": {
    "filename": "resume.pdf",
    "byte_size": 1234,
    "checksum": "…",
    "content_type": "application/pdf"
  }
}
```

--------------------------------

### client.getJob

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/index.md

Retrieves details for a specific job.

```APIDOC
## client.getJob(publicToken)

### Description
Fetches detailed information for a job using its public token.
```

--------------------------------

### kit.getJob(jobId)

Source: https://github.com/startupkit-app/jobs-js/blob/main/README.md

Retrieves the details of a specific job posting, including application form fields, questions, and resume requirements.

```APIDOC
## kit.getJob(jobId)

### Description
Fetches job details using the job identifier. The returned object contains the application form structure, including fields, questions, and resume requirements.

### Parameters
- **jobId** (string) - Required - The unique identifier for the job posting (e.g., 'tok_abc123').

### Response
- **job** (object) - The job object containing application_form, fields, questions, and resume requirements.
```

--------------------------------

### MD5 hashing utilities

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/internal.md

Provides MD5 hashing functions for transfer integrity checks, specifically for generating base64 checksums required by Active Storage.

```ts
export function md5(input: Uint8Array): Uint8Array;   // 16-byte digest
export function md5Base64(input: Uint8Array): string;  // base64-encoded digest
```

--------------------------------

### Assert Consent IP Address Server-Side

Source: https://github.com/startupkit-app/jobs-js/blob/main/README.md

Use this when submitting entries from a server to ensure the end user's IP is recorded instead of the server's egress IP. This requires a secret key (sk_...).

```ts
// Server-side, sk_… key. Take the IP from your framework's request object.
await kit.joinTalentPool({
  email,
  consent: form.consent === "on",
  consent_ip_address: requestIp,
});
```

--------------------------------

### KitJobsClient Interface Declaration

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/KitJobsClient.md

The primary interface definition for the KitJobsClient, outlining all available methods for job and talent pool operations.

```ts
export interface KitJobsClient {
  /** Lists published jobs, one page at a time. */
  listJobs(params?: ListJobsParams, options?: RequestOptions): Promise<Page<Job>>;
  /** Iterates every published job across all pages. */
  allJobs(params?: ListJobsParams, options?: RequestOptions): AsyncIterable<Job>;
  /** Fetches full job detail (description, stages, application form). */
  getJob(publicToken: string, options?: RequestOptions): Promise<JobDetail>;
  /** Low-level: registers a blob and returns direct-upload instructions. */
  createUpload(meta: UploadMeta): Promise<UploadTicket>;
  /**
   * High-level resume/file upload: computes the base64 MD5 checksum,
   * registers the blob, PUTs the bytes to storage, and returns the
   * `signed_id` to pass in `apply`.
   */
  uploadFile(
    file: Blob | File,
    meta?: { filename?: string; content_type?: string }
  ): Promise<{ signed_id: string }>;
  /** Submits an application to a job. */
  apply(
    publicToken: string,
    input: ApplicationInput,
    opts?: { turnstileToken?: string }
  ): Promise<ApplicationResult>;
  /** Fetches the talent-pool intake schema (consent terms, fields, resume rules). */
  getTalentPool(options?: RequestOptions): Promise<TalentPoolForm>;
  /**
   * Adds someone to the talent pool. The entry is created unverified and Kit
   * emails a double-opt-in link; `input.consent` must reflect an affirmative
   * action by the person, never a hardcoded `true`.
   */
  joinTalentPool(
    input: TalentPoolInput,
    opts?: { turnstileToken?: string }
  ): Promise<TalentPoolResult>;
}
```

--------------------------------

### Define ApplicationForm interface

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/types.md

Aggregates form fields, screening questions, and configuration requirements for job applications.

```ts
export interface ApplicationForm {
  fields: FormField[];
  questions: Question[];
  consent_disclosure_html: string;
  resume: ResumeRequirements;
  turnstile: TurnstileConfig;
}
```

--------------------------------

### client.getTalentPool

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/index.md

Retrieves the talent pool form structure.

```APIDOC
## client.getTalentPool()

### Description
Fetches the form definition for the talent pool.
```

--------------------------------

### Define Pagination interface

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/types.md

Represents pagination metadata returned by listJobs.

```ts
export interface Pagination {
  current_page: number;
  total_pages: number;
  total_count: number;
  per_page: number;
}
```

--------------------------------

### getJob Method Signature

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/KitJobsClient.md

The signature for the getJob method.

```ts
getJob(publicToken: string, options?: RequestOptions): Promise<JobDetail>
```

--------------------------------

### Handle Form Submission and File Upload

Source: https://github.com/startupkit-app/jobs-js/blob/main/examples/browser-apply.html

Processes form data, uploads resumes, and submits the application to the API while handling potential validation errors.

```javascript
form.addEventListener("submit", async (event) => {
  event.preventDefault();
  status.textContent = "Submitting…";
  const data = new FormData(form);

  try {
    // 1. Upload the resume (optional)
    let resume_signed_id;
    const resume = data.get("resume");
    if (resume instanceof File && resume.size > 0) {
      status.textContent = "Uploading resume…";
      ({ signed_id: resume_signed_id } = await kit.uploadFile(resume));
    }

    // 2. Collect screening question answers
    const responses = {};
    for (const question of job.application_form.questions) {
      const answer = data.get(`question:${question.key}`);
      if (answer) responses[question.key] = String(answer);
    }

    // 3. Submit the application
    const result = await kit.apply(
      job.id,
      {
        email: String(data.get("email")),
        first_name: String(data.get("first_name") || "") || undefined,
        last_name: String(data.get("last_name") || "") || undefined,
        responses,
        resume_signed_id,
      },
      { turnstileToken }
    );

    status.textContent = `Application ${result.id} submitted. Good luck!`;
    form.querySelector("button").disabled = true;
  } catch (error) {
    if (error instanceof KitApiError) {
      if (error.code === "already_applied") {
        status.textContent = "You have already applied to this job.";
      } else if (error.fields) {
        status.textContent = Object.entries(error.fields)
          .map(([field, messages]) => `${field}: ${messages.join(", ")}`)
          .join(" · ");
      } else {
        status.textContent = error.message;
      }
    } else {
      status.textContent = "Network error — please try again.";
    }
  }
});
```

--------------------------------

### client.joinTalentPool

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/index.md

Submits an entry to the talent pool.

```APIDOC
## client.joinTalentPool(input, opts?)

### Description
Submits user input to join the talent pool.
```

--------------------------------

### Define Page<T> interface

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/types.md

Generic interface for handling paginated API responses.

```ts
export interface Page<T> {
  data: T[];
  pagination: Pagination;
  hasNextPage: boolean;
  nextPage(): Promise<Page<T>> | null;
}
```

--------------------------------

### Define ApplicationInput interface

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/types.md

Represents the structure of data submitted when applying for a job.

```ts
export interface ApplicationInput {
  email: string;
  first_name?: string;
  last_name?: string;
  phone?: string;
  responses?: Record<string, string>;
  resume_signed_id?: string;
  files?: Record<string, string>;
}
```

--------------------------------

### Define TurnstileConfig interface

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/types.md

Configures Cloudflare Turnstile requirements and site keys.

```ts
export interface TurnstileConfig {
  required: boolean;
  sitekey: string | null;
}
```

--------------------------------

### joinTalentPool(data, options)

Source: https://github.com/startupkit-app/jobs-js/blob/main/README.md

Submits a new entry to the talent pool. Entries are created in an unverified state and require double-opt-in via email.

```APIDOC
## joinTalentPool(data, options)

### Description
Submits a new candidate entry to the talent pool. Requires explicit consent and optional Turnstile verification.

### Parameters
#### Data
- **email** (string) - Required - Candidate email address.
- **linkedin_url** (string) - Optional - Candidate LinkedIn profile URL.
- **resume_signed_id** (string) - Optional - Signed ID of the uploaded resume file.
- **consent** (boolean) - Required - Must be the actual state of the user's consent checkbox.
- **consent_ip_address** (string) - Optional - IP address of the end user (only honored with secret keys).

#### Options
- **turnstileToken** (string) - Required if pool.turnstile.required is true.

### Response
- **id** (string) - The unique identifier for the talent pool entry (e.g., "tpe_...").
- **status** (string) - The current status of the entry (e.g., "pending_verification").
```

--------------------------------

### Apply Method Signature

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/KitJobsClient.md

The TypeScript signature for the apply method.

```ts
apply(
  publicToken: string,
  input: ApplicationInput,
  opts?: { turnstileToken?: string }
): Promise<ApplicationResult>
```

--------------------------------

### Define JobDetail interface

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/types.md

Represents the full details of a job posting, including HTML description and application stages.

```ts
export interface JobDetail extends Job {
  description_html: string;
  accepting_applications: boolean;
  stages: Stage[];
  application_form: ApplicationForm;
}
```

--------------------------------

### Handle API and Network Errors

Source: https://github.com/startupkit-app/jobs-js/blob/main/README.md

Use try-catch blocks to differentiate between KitApiError for non-2xx responses and KitNetworkError for connectivity issues.

```ts
import { KitApiError, KitNetworkError } from "@startupkit-app/jobs";

try {
  await kit.apply(job.id, { email });
} catch (error) {
  if (error instanceof KitApiError) {
    switch (error.code) {
      case "already_applied": // 409
        break;
      case "validation_failed": // 422 — see error.fields
        console.log(error.fields); // { email: ["is invalid"], … }
        break;
      case "turnstile_failed": // 422 — refresh the widget and retry
        break;
      default:
        console.error(error.status, error.code, error.message);
    }
  } else if (error instanceof KitNetworkError) {
    // retry / offline UI
  }
}
```

--------------------------------

### DEFAULT_BASE_URL Constant Definition

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/createClient.md

The default API origin used by the SDK when no custom base URL is provided.

```ts
export const DEFAULT_BASE_URL = "https://app.startupkit.app";
```

--------------------------------

### listJobs

Source: https://github.com/startupkit-app/jobs-js/blob/main/README.md

Retrieves a paginated list of published jobs based on optional filters.

```APIDOC
## listJobs

### Description
Fetches a page of jobs from the hiring API. Supports filtering by department and remote status.

### Signature
`listJobs(filters?: { department?: string, remote?: boolean })`

### Parameters
- **department** (string) - Optional - Filter jobs by department name.
- **remote** (boolean) - Optional - Filter jobs by remote status.

### Response
- **data** (Array) - List of job objects.
- **hasNextPage** (boolean) - Indicates if more pages are available.
- **nextPage** (Function) - Method to fetch the next page of results.
```

--------------------------------

### Define Stage interface

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/types.md

Represents read-only pipeline metadata for job stages.

```ts
export interface Stage {
  name: string;
  type: string;
}
```

--------------------------------

### getJob

Source: https://github.com/startupkit-app/jobs-js/blob/main/README.md

Retrieves full details for a specific job by its ID.

```APIDOC
## getJob

### Description
Fetches the full details of a job, including description, stages, and application form definition.

### Signature
`getJob(id: string)`

### Parameters
- **id** (string) - Required - The unique identifier of the job.
```

--------------------------------

### Define UploadTicket interface

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/types.md

Represents the response received after creating an upload, containing the signed ID and direct upload instructions.

```ts
export interface UploadTicket {
  signed_id: string;
  filename: string;
  content_type: string;
  byte_size: number;
  direct_upload: {
    url: string;
    headers: Record<string, string>;
  };
}
```

--------------------------------

### Define Job interface

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/types.md

Represents the core job structure used in listJobs and allJobs.

```ts
export interface Job {
  id: string;
  title: string;
  department: string | null;
  location: string | null;
  employment_type: string | null;
  remote: boolean;
  published_at: string | null;
  url: string | null;
  salary?: Salary;
}
```

--------------------------------

### ListJobsParams Interface

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/KitJobsClient.md

The interface defining available filters and pagination options for listing jobs.

```ts
export interface ListJobsParams {
  department?: string;
  location?: string;
  employment_type?: string;
  remote?: boolean;
  page?: number;
  per_page?: number;
}
```

--------------------------------

### Submit Job Application Request Body

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/endpoints.md

The JSON structure required for submitting a job application via the POST endpoint.

```json
{
  "application": {
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": null,
    "responses": { "motivation": "…" },
    "resume_signed_id": "…",
    "files": {}
  },
  "turnstile_token": "…"
}
```

--------------------------------

### Request Body Structure

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/KitJobsClient.md

The JSON body structure for the POST request.

```ts
{ application: input, turnstile_token? } // `turnstile_token` present only when opts.turnstileToken set
```

--------------------------------

### Define TalentPoolForm interface

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/types.md

Structure for the talent pool form configuration, returned by getTalentPool.

```ts
export interface TalentPoolForm {
  accepting_signups: boolean;
  consent: TalentPoolConsent;
  fields: TalentPoolField[];
  resume: TalentPoolResume;
  turnstile: TurnstileConfig;
}
```

--------------------------------

### Validate and submit resume

Source: https://github.com/startupkit-app/jobs-js/blob/main/README.md

Check the resume requirement status before submission to prevent unnecessary API calls and handle form validation.

```ts
const { required } = job.application_form.resume;

fileInput.required = required;
label.textContent = required ? "Resume *" : "Resume";

form.addEventListener("submit", async (event) => {
  event.preventDefault();
  const file = fileInput.files[0];

  if (required && !file) {
    showError("A resume is required for this role.");
    return; // don't spend a round-trip on a submission that will 422
  }

  const resume_signed_id = file ? (await kit.uploadFile(file)).signed_id : undefined;
  await kit.apply(job.id, { email, resume_signed_id });
});
```

--------------------------------

### Define TalentPoolInput interface

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/types.md

Structure for candidate submissions accepted by joinTalentPool. Ensure consent is not hardcoded as true.

```ts
export interface TalentPoolInput {
  email: string;
  linkedin_url?: string;
  resume_signed_id?: string;
  consent: boolean;
  consent_ip_address?: string;
}
```

--------------------------------

### Define TalentPoolConsent interface

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/types.md

Configures consent requirements for talent pool participation.

```ts
export interface TalentPoolConsent {
  required: boolean;
  disclosure_html: string;
  retention_months: number;
  privacy_policy_url: string | null;
}
```

--------------------------------

### Define UploadMeta interface

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/types.md

Represents the metadata required for initiating a file upload process.

```ts
export interface UploadMeta {
  filename: string;
  byte_size: number;
  checksum: string;
  content_type: string;
}
```

--------------------------------

### Handle upload errors

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/api-reference/KitJobsClient.md

Catch KitNetworkError to handle failures during the direct upload process.

```ts
try {
  await kit.uploadFile(file);
} catch (error) {
  if (error instanceof KitNetworkError) {
    // retry / offline UI — the blob was never registered or the PUT failed
  }
}
```

--------------------------------

### Define Question interface

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/types.md

Defines the structure of a screening question used in the application process.

```ts
export interface Question {
  key: string;
  type: QuestionType;
  prompt: string;
  required: boolean;
  max_length: number;
  options?: string[];
}
```

--------------------------------

### Define ApplicationResult interface

Source: https://github.com/startupkit-app/jobs-js/blob/main/_autodocs/types.md

Represents the result of a job application submission.

```ts
export interface ApplicationResult {
  id: string;
  status: "submitted";
  job: string;
  submitted_at: string;
}
```
Tokens:
Raw