JobSync

https://github.com/gsync/jobsync
Admin
JobSync is a free, open-source job search management web app that helps job seekers track...
Tokens:100,366
Snippets:760
Trust Score:9.2
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Start development server

Source: https://github.com/gsync/jobsync/blob/main/CONTRIBUTING.md

Starts the development server.

```bash
npm run dev
```

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

### Install dependencies

Source: https://github.com/gsync/jobsync/blob/main/CONTRIBUTING.md

Installs all project dependencies.

```bash
npm install
```

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

### Copy environment file

Source: https://github.com/gsync/jobsync/blob/main/CONTRIBUTING.md

Copies the example environment file to .env so you can fill in your own values.

```bash
cp .env.example .env
```

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

### Branch naming examples

Source: https://github.com/gsync/jobsync/blob/main/CONTRIBUTING.md

Example branch names using the required prefixes: feat/, fix/, docs/, refactor/, test/, and chore/. Each branch should target the dev branch, never main.

```text
feat/add-resume-export
fix/automation-rate-limit
docs/update-api-routes
refactor/ai-provider-cleanup
test/task-actions-coverage
```

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

### Clone and run with Docker Compose

Source: https://github.com/gsync/jobsync/blob/main/README.md

Clone the repository do not contain any comments.  It uses Docker Compose to build and start the application.  The first startup builds the app image, which may take a few minutes; wait before accessing the app in the browser.

```sh
git clone https://github.com/Gsync/jobsync.git
cd jobsync
docker compose up
```

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

### GET /api/version

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/endpoints.md

Returns version information for the application.

```APIDOC
## GET /api/version

### Description
Returns version information for the application.

### Method
GET

### Endpoint
/api/version

### Response
#### Success Response (200)
- **current** (string) - Current version
- **latest** (string | null) - Latest version from GitHub releases
- **updateAvailable** (boolean) - Whether an update is available
- **releaseUrl** (string | null) - URL to the latest release

#### Error Responses
- **401**: Session required

### Notes
- The GitHub release lookup (`releases/latest` of `Gsync/jobsync`) fails soft; any error degrades to `updateAvailable: false`.
```

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

### GET /api/ai/ollama/ps

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/endpoints.md

Gets the running Ollama models. Requires a session.

```APIDOC
## GET /api/ai/ollama/ps

### Description
Gets the running Ollama models. Requires a session.

### Method
GET

### Endpoint
/api/ai/ollama/ps

### Response
#### Success Response (200)
- Proxied response from `GET {baseUrl}/api/ps`.

#### Error Responses
- **401** - Unauthenticated.
- **502** - Cannot connect to Ollama service.
- Upstream status otherwise.
```

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

### Commit message examples

Source: https://github.com/gsync/jobsync/blob/main/CONTRIBUTING.md

Example commit messages following the Conventional Commits specification. Each message uses a type and optional scope, with an imperative summary. Reference issues in the footer using 'Closes #123'.

```text
feat(automations): add rate limiting for manual runs
fix(tasks): prevent deletion of tasks with linked activities
docs: update environment variable list in README
refactor(ai): extract preprocessing into dedicated module
test(job-actions): add coverage for edge cases
```

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

### GET /api/backup/export

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/endpoints.md

Exports the backup as a zip file.

```APIDOC
## GET /api/backup/export

### Description
Exports the backup as a zip file.

### Method
GET

### Endpoint
/api/backup/export

### Response
#### Success Response (200)
- **Content-Type**: application/zip
- **Content-Disposition**: attachment; filename="jobsync-backup-<date>.zip"

#### Error Response (500)
- **error**: string - "Export failed"

```

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

### Saving an Encrypted Provider Key (User Action)

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/encryption-api-keys.md

Server action example that saves an encrypted API key for a provider, logging an error if the operation fails.

```ts
"use server";
import { saveApiKey } from "@/actions/apiKey.actions";
const result = await saveApiKey({ provider: "openai", key: apiKey, sensitive: true });
if (!result.success) console.error(result.message);
```

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

### GET /api/ai/ollama/tags

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/endpoints.md

Gets the list of Ollama tags. Requires a session.

```APIDOC
## GET /api/ai/ollama/tags

### Description
Gets the list of Ollama tags. Requires a session.

### Method
GET

### Endpoint
/api/ai/ollama/tags

### Response
#### Success Response (200)
- Proxied response from `GET {baseUrl}/api/tags`.

#### Error Responses
- **401** - Unauthenticated.
- **502** - Cannot connect to Ollama service.
- Upstream status otherwise.
```

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

### withSpan

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/telemetry.md

Starts a span, runs an async function with the span ambient, marks the span as errored if the function throws, and ends the span in a finally block.

```APIDOC
## withSpan

### Description
Starts a span, runs an async function with the span ambient, marks the span as errored if the function throws, and ends the span in a finally block.

### Signature
`async withSpan<T>(name: string, attrs: Attrs, fn: (span: Span) => Promise<T>): Promise<T>`

### Parameters
- **name** (string) - Required - The name of the span.
- **attrs** (Attrs) - Required - Attributes to attach to the span.
- **fn** ((span: Span) => Promise<T>) - Required - The async function to execute, receiving the span.

### Returns
- **Promise<T>** - Resolves with the return value of `fn`.

### Behavior
- Starts the span.
- Runs `fn` with the span ambient.
- On failure, marks the span as errored and rethrows.
- Ends the span in a `finally` block.
```

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

### GET /api/backup/snapshots

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/endpoints.md

Lists the caller's snapshots, newest first.

```APIDOC
## GET /api/backup/snapshots

### Description
Lists the caller's snapshots, newest first.

### Method
GET

### Endpoint
/api/backup/snapshots

### Response
#### Success Response (200)
- **snapshots**: array of SnapshotInfo - Each snapshot has: id, exportedAt, appVersion, counts, sizeBytes.

#### Error Response (500)
- **error**: string - "Could not list snapshots."

```

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

### Client-side stream consumption with useChat

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/agent-chat.md

Conceptual example of sending a chat request to the `/api/ai/chat` endpoint with a user message and page context. Uses the Vercel AI SDK `useChat` pattern.

```typescript
const response = await fetch("/api/ai/chat", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    messages: [{ role: "user", parts: [{ type: "text", text: "Review my resume" }] }],
    pageContext: { route: "/dashboard/profile/resume/abc123", resumeId: "abc123" },
  }),
});
```

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

### GET /api/ai/openrouter/models

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/endpoints.md

Proxies the OpenRouter model list endpoint. Requires a session.

```APIDOC
## GET /api/ai/openrouter/models

### Description
Proxies the OpenRouter model list endpoint. Requires a session.

### Method
GET

### Endpoint
/api/ai/openrouter/models

### Response
#### Success Response (200)
- Proxied response from https://openrouter.ai/api/v1/models

#### Error Responses
- **401** - Unauthenticated.
- **500** - API key not configured.
- Upstream status otherwise.
```

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

### GET /api/ai/openai/models

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/endpoints.md

Proxies the OpenAI model list endpoint. Requires a session.

```APIDOC
## GET /api/ai/openai/models

### Description
Proxies the OpenAI model list endpoint. Requires a session.

### Method
GET

### Endpoint
/api/ai/openai/models

### Response
#### Success Response (200)
- Proxied response from https://api.openai.com/v1/models

#### Error Responses
- **401** - Unauthenticated.
- **500** - OpenAI API key not configured.
- Upstream status otherwise.
```

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

### GET /api/ai/gemini/models

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/endpoints.md

Proxies the Gemini model list endpoint. Requires a session.

```APIDOC
## GET /api/ai/gemini/models

### Description
Proxies the Gemini model list endpoint. Requires a session.

### Method
GET

### Endpoint
/api/ai/gemini/models

### Response
#### Success Response (200)
- Proxied response from the Gemini model list.

#### Error Responses
- **401** - Unauthenticated.
- **500** - API key not configured.
- Upstream status otherwise.
```

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

### GET /api/ai/deepseek/models

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/endpoints.md

Proxies the DeepSeek model list endpoint. Requires a session.

```APIDOC
## GET /api/ai/deepseek/models

### Description
Proxies the DeepSeek model list endpoint. Requires a session.

### Method
GET

### Endpoint
/api/ai/deepseek/models

### Response
#### Success Response (200)
- Proxied response from https://api.deepseek.com/models

#### Error Responses
- **401** - Unauthenticated.
- **500** - API key not configured.
- Upstream status otherwise.
```

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

### handlers

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/auth.md

NextAuth route handlers bound to GET and POST at /api/auth/[...nextauth]. Used to handle authentication requests.

```APIDOC
## handlers

### Description
NextAuth route handlers bound to `GET`/`POST` at `/api/auth/[...nextauth]` in `src/app/api/auth/[...nextauth]/route.ts`.

### Method
`GET` / `POST`

### Endpoint
`/api/auth/[...nextauth]`

### Usage
Export these handlers in the route file to handle authentication requests.
```

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

### Set up database with Prisma

Source: https://github.com/gsync/jobsync/blob/main/CONTRIBUTING.md

Runs Prisma migrations to set up the database schema.

```bash
npx prisma migrate dev
```

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

### signup(formData)

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/auth.md

Creates a new user account with the provided name, email, and password. Validates input, hashes the password, seeds initial data, and returns success or error messages.

```APIDOC
## signup(formData)

### Description
Creates a new user account with the provided name, email, and password. Validates input, hashes the password, seeds initial data, and returns success or error messages.

### Method
Server Action

### Endpoint
`@/actions/auth.actions` - `signup`

### Parameters
#### Request Body
- **name** (string) - Required - User's name, must be at least 2 characters.
- **email** (string) - Required - User's email address.
- **password** (string) - Required - User's password, must be at least 6 characters.

### Request Example
```ts
const result = await signup({
  name: "John Doe",
  email: "john@example.com",
  password: "secret123"
});
```

### Response
#### Success Response
- **success** (boolean) - `true` on successful account creation.

#### Error Response
- **error** (string) - `"Invalid form data."` if validation fails, or `"An account with this email already exists."` if the email is already registered.

#### Response Example
```ts
// Success
{ success: true }

// Error
{ error: "Invalid form data." }
```
```

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

### signup Server Action

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/auth.md

Defines the signup server action. Validates the form data with SignupFormSchema (name ≥ 2 chars, email, password ≥ 6 chars); on failure returns { error: "Invalid form data." }. Creates the user with bcrypt.hash(password, 10), then seeds initial data: JobSource from JOB_SOURCES, ContactRole from CONTACT_ROLES, JobStatus upserts from JOB_STATUSES, and JobStageType from JOB_STAGES (status-linked). Returns { error: "An account with this email already exists." } on duplicate email, otherwise { success: true }.

```ts
export async function signup(formData: {
  name: string;
  email: string;
  password: string;
}) {
```

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

### HTTP preflight and import backup

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/backup.md

Preflight then import backup from an HTTP request. Uses preflightBackup to validate the uploaded file and returns a 400 with the user message if a BackupError is thrown.

```ts
import { preflightBackup, importBackup, BackupError } from "@/lib/backup";

const bytes = Buffer.from(await (await req.formData()).get("file")!.arrayBuffer());
try {
  const result = await preflightBackup(bytes, session.user.id, session.user.email ?? "");
  // result.emailMatches / result.targetIsEmpty / result.manifest
} catch (error) {
  if (error instanceof BackupError) return NextResponse.json({ error: error.userMessage }, { status: 400 });
  throw error;
}
```

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

### Deploy on Windows with PowerShell

Source: https://github.com/gsync/jobsync/blob/main/README.md

Runs the PowerShell deployment script natively on Windows.  Use this instead of `deploy.sh` when on Windows.

```powershell
.\deploy.ps1
```

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

### Server action: getNotesByJobId with auth and scoped read

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/server-actions.md

Standard server action pattern: query notes for a job scoped to the authenticated user. Uses requireUser() for auth, Prisma for the read, and handleError for failures.

```ts
"use server";
import prisma from "@/lib/db";
import { requireUser } from "./shared";
import { handleError } from "@/lib/utils";

export async function getNotesByJobId(jobId: string) {
  try {
    const user = await requireUser();
    const notes = await prisma.note.findMany({
      where: { jobId, userId: user.id },
      orderBy: { createdAt: "desc" },
    });
    return { success: true, data: notes };
  } catch (error) {
    return handleError(error, "Failed to fetch notes.");
  }
}
```

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

### RESUME_REVIEW_SYSTEM_PROMPT, buildResumeReviewPrompt(text)

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/ai.md

System prompt and builder for resume review prompts.

```APIDOC
## RESUME_REVIEW_SYSTEM_PROMPT, buildResumeReviewPrompt(text)

### Description
System prompt and builder for resume review prompts.

### Exports
- **RESUME_REVIEW_SYSTEM_PROMPT** - The system prompt constant.
- **buildResumeReviewPrompt(text)** - Builds a prompt for resume review.

### Parameters (buildResumeReviewPrompt)
- **text** (string) - Required - The resume text.

### Returns
- A string prompt.

```

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

### Claude Desktop config with mcp-remote

Source: https://github.com/gsync/jobsync/wiki/MCP

Paste this into claude_desktop_config.json to add JobSync to Claude Desktop. Requires mcp-remote because Claude Desktop only connects to local servers. If the URL is plain http on a home network, add --allow-http to args; the token dialog snippet already includes it when needed.

```json
{
  "mcpServers": {
    "jobsync": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://<your-jobsync-url>/api/mcp",
        "--header",
        "Authorization: Bearer <your-token>"
      ]
    }
  }
}
```

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

### AUTOMATION_JOB_MATCH_SYSTEM_PROMPT, buildAutomationJobMatchPrompt(...)

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/ai.md

System prompt and builder for automation job match prompts.

```APIDOC
## AUTOMATION_JOB_MATCH_SYSTEM_PROMPT, buildAutomationJobMatchPrompt(...)

### Description
System prompt and builder for automation job match prompts.

### Exports
- **AUTOMATION_JOB_MATCH_SYSTEM_PROMPT** - The system prompt constant.
- **buildAutomationJobMatchPrompt(...)** - Builds a prompt for automation job matching.

### Parameters (buildAutomationJobMatchPrompt)
- Additional parameters not specified in the source.

### Returns
- A string prompt.

```

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

### signup

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/server-actions.md

Server action for user signup. It accepts a form data object with name, email, and password, and returns a standard success/data/message shape.

```APIDOC
## signup(formData: { name, email, password })

### Description
Creates a new user account with the provided name, email, and password.

### Method
Server Action

### Parameters
- **formData** (object) - Required - Contains `name`, `email`, `password`.

### Returns
- **success** (boolean) - Indicates whether the operation succeeded.
- **data** (any, optional) - Additional data on success.
- **message** (string, optional) - Error message on failure.

```

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

### JOB_MATCH_SYSTEM_PROMPT, buildJobMatchPrompt(resumeText, jobText)

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/ai.md

System prompt and builder for job match prompts.

```APIDOC
## JOB_MATCH_SYSTEM_PROMPT, buildJobMatchPrompt(resumeText, jobText)

### Description
System prompt and builder for job match prompts.

### Exports
- **JOB_MATCH_SYSTEM_PROMPT** - The system prompt constant.
- **buildJobMatchPrompt(resumeText, jobText)** - Builds a prompt for job matching.

### Parameters (buildJobMatchPrompt)
- **resumeText** (string) - Required - The resume text.
- **jobText** (string) - Required - The job description text.

### Returns
- A string prompt.

```

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

### GET /api/automations/[id]/logs

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/endpoints.md

Streams automation run logs via Server-Sent Events. Provides real-time updates and run status.

```APIDOC
## GET /api/automations/[id]/logs

### Description
Server-Sent Events stream of the run log store. Provides real-time log snapshots and run status.

### Method
GET

### Endpoint
/api/automations/[id]/logs

### Parameters
#### Path Parameters
- **id** (string) - Required - The automation id.

### Response
#### Success Response (200)
- Content-Type: text/event-stream
- Cache-Control: no-cache
- Events: retry once, then data snapshots every 1 second.
- Data format: { logs: AutomationLog[], isRunning: boolean, startedAt?: string, completedAt?: string }
- Errors are delivered as SSE data frames with an error field (HTTP 200).

#### Response Example
retry: 1000

data: {"logs":[],"isRunning":false}

#### Error Responses
- **401** - Not authenticated (delivered as SSE error frame).
- **404** - Automation not found (delivered as SSE error frame).
```

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

### Deploy script for Unix-like systems

Source: https://github.com/gsync/jobsync/blob/main/README.md

Pulls the latest changes and rebuilds the application on Unix-like systems.  Requires `sudo` and works with WSL or Git Bash.

```sh
curl -fsSL https://raw.githubusercontent.com/Gsync/jobsync/main/deploy.sh | sudo bash -s
```

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

### POST /api/ai/resume/import

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/endpoints.md

Streaming AI resume-import that extracts structured resume sections from an uploaded resume file. Requires a session.

```APIDOC
## POST /api/ai/resume/import

### Description
Streaming AI resume-import that extracts structured resume sections from an uploaded resume file. Requires a session.

### Method
POST

### Endpoint
/api/ai/resume/import

### Parameters
#### Request Body
- **resumeId** (string) - Required - The resume identifier.
- **selectedModel** (AiModel) - Required - The AI model to use.

### Response
#### Success Response (200)
- Content-Type: application/x-ndjson
- One JSON snapshot per partialOutputStream item, terminated by `{ "__error": "<message>" }` on in-stream failure.
- Header `x-resume-import-truncated: "true"|"false"`.

#### Error Responses
- **400** - Missing fields, or resume has no attached file / invalid file path / file missing on disk.
- **401** - Unauthenticated.
- **422** - Extraction/preprocessing failure with `{ error, code }` where code is one of `UNSUPPORTED_FORMAT`, `NO_TEXT`, `DECOMPRESSION_BOMB`, `ENCRYPTED`, `EXTRACTION_FAILED`.
- **429** - Rate limited.
- **503** - AI service unreachable.
- **504** - Generation timeout.
```

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

### Backup manifest and zip guards (manifest.ts)

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/backup.md

Declares the public API of the backup manifest module. `openBackupZip` runs `preflightZip` (entry count and uncompressed size from the central directory only, no inflation) and rejects over `BACKUP_MAX_ENTRIES` (5000) or `BACKUP_MAX_UNCOMPRESSED_BYTES` (100 MB) with `BackupError("That file is not a readable zip archive.")`. `readManifest` requires `manifest.json`; version mismatch yields `BackupError("This backup was made by a different version of JobSync. Expected format version 1, found <n>.")` and missing fields yield `"manifest.json is missing required fields."`. `BackupError` carries a `userMessage` safe to show the user; any other thrown error is internal.

```ts
export class BackupError extends Error {
  constructor(public userMessage: string)
}

export function countRows(data: BackupData): Record<string, number>
export function buildManifest(data: BackupData, sourceEmail: string): BackupManifest

export async function openBackupZip(bytes: Buffer): Promise<JSZip>
export async function readManifest(zip: JSZip): Promise<BackupManifest>
```

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

### POST /api/backup/rollback

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/endpoints.md

Rolls back to a snapshot. The import proceeds with confirmWipe = true and writes a fresh snapshot first.

```APIDOC
## POST /api/backup/rollback

### Description
Rolls back to a snapshot. The import proceeds with confirmWipe = true and writes a fresh snapshot first.

### Method
POST

### Endpoint
/api/backup/rollback

### Parameters
#### Request Body
- **snapshotId** (string) - Required - The ID of the snapshot to roll back to.

### Response
#### Success Response (200)
No specific response body documented.

#### Error Responses
- **400**: No snapshot selected, or BackupError.userMessage.
- **500**: Other failures.

```

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

### buildManifest(data: BackupData, sourceEmail: string): BackupManifest

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/backup.md

Builds a BackupManifest object from backup data and source email, including format version, app version, export timestamp, and row counts.

```APIDOC
## buildManifest(data: BackupData, sourceEmail: string): BackupManifest

### Description
Builds a BackupManifest object from backup data and source email, including format version, app version, export timestamp, and row counts.

### Method
Function

### Endpoint
src/lib/backup/manifest.ts

### Parameters
#### Parameters
- **data** (BackupData) - Required - The backup data object containing model arrays.
- **sourceEmail** (string) - Required - The email of the user who exported the backup.

### Returns
- **BackupManifest** - The constructed manifest object.
```

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

### Span API type and functions (span.ts)

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/telemetry.md

Span API type and function signatures. startSpan generates a 16-byte trace id and 8-byte span id, chains to the current parent via AsyncLocalStorage, and returns a no-op frozen NOOP_SPAN when disabled. runInSpan makes the span ambient for fn's execution. withSpan starts, runs, marks error and rethrows on failure, and ends in finally.

```typescript
export type Span = {
  traceId: string;
  spanId: string;
  setAttrs(attrs: Attrs): void;
  setError(error: unknown): void;
  end(attrs?: Attrs): void;
};

export function startSpan(name: string, attrs?: Attrs): Span
export function runInSpan<T>(span: Span, fn: () => T): T
export async function withSpan<T>(name: string, attrs: Attrs, fn: (span: Span) => Promise<T>): Promise<T>
```

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

### buildBackupZip(userId: string, sourceEmail: string): Promise<{ buffer: Buffer; fileName: string }>

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/backup.md

Builds a backup zip containing resume files, manifest.json, and data.json, compressed with DEFLATE.

```APIDOC
## buildBackupZip(userId: string, sourceEmail: string): Promise<{ buffer: Buffer; fileName: string }>

### Description
Builds a backup zip containing resume files, manifest.json, and data.json, compressed with DEFLATE. Resume file bytes are read from disk into files/<fileId>/<basename>; rows whose bytes are missing or outside the resumes directory are marked fileMissing: true. The resulting file name is jobsync-backup-<date>.zip.

### Method
buildBackupZip

### Endpoint
buildBackupZip(userId: string, sourceEmail: string): Promise<{ buffer: Buffer; fileName: string }>

### Parameters
#### Parameters
- **userId** (string) - Required - The ID of the user whose data to back up.
- **sourceEmail** (string) - Required - The email of the source account, used in the manifest.

### Response
#### Success Response
- **buffer** (Buffer) - The zip file buffer.
- **fileName** (string) - The generated file name, e.g., jobsync-backup-<date>.zip.

#### Response Example
```json
{
  "buffer": "<Buffer>" ,
  "fileName": "jobsync-backup-2025-01-01.zip"
}
```
```

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

### Pre-PR local checks

Source: https://github.com/gsync/jobsync/blob/main/CONTRIBUTING.md

Commands to run locally before opening a PR. Lint and unit tests must pass; E2E tests are optional. A PR that fails lint or tests will not be reviewed until resolved.

```bash
# Lint — must produce no errors
npm run lint

# Unit tests — all must pass
npm run test

# (Optional) E2e tests
npm run test:e2e
```

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

### COVER_LETTER_SYSTEM_PROMPT, buildCoverLetterPrompt(...)

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/ai.md

System prompt and builder for cover letter prompts.

```APIDOC
## COVER_LETTER_SYSTEM_PROMPT, buildCoverLetterPrompt(...)

### Description
System prompt and builder for cover letter prompts.

### Exports
- **COVER_LETTER_SYSTEM_PROMPT** - The system prompt constant.
- **buildCoverLetterPrompt(...)** - Builds a prompt for cover letter generation.

### Parameters (buildCoverLetterPrompt)
- Additional parameters not specified in the source.

### Returns
- A string prompt.

```

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

### openBackupZip(bytes: Buffer): Promise<JSZip>

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/backup.md

Opens a backup zip file after running preflight checks on entry count and uncompressed size. Rejects with a BackupError if the file is not a readable zip archive.

```APIDOC
## openBackupZip(bytes: Buffer): Promise<JSZip>

### Description
Opens a backup zip file after running preflight checks on entry count and uncompressed size. Rejects with a BackupError if the file is not a readable zip archive.

### Method
Function

### Endpoint
src/lib/backup/manifest.ts

### Parameters
#### Parameters
- **bytes** (Buffer) - Required - The raw bytes of the backup zip file.

### Returns
- **Promise<JSZip>** - A promise that resolves to the loaded JSZip object.

### Errors
- **BackupError** - Thrown when the file is not a readable zip archive (e.g., exceeds BACKUP_MAX_ENTRIES or BACKUP_MAX_UNCOMPRESSED_BYTES).
```

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

### Clone your fork

Source: https://github.com/gsync/jobsync/blob/main/CONTRIBUTING.md

Clones your fork of the repository and changes into the project directory.

```bash
git clone https://github.com/<your-username>/jobsync.git
cd jobsync
```

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

### POST /api/profile/resume

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/endpoints.md

Creates or replaces a resume via multipart/form-data upload.

```APIDOC
## POST /api/profile/resume

### Description
Creates or replaces a resume. Binary uploads are handled via multipart/form-data.

### Method
POST

### Endpoint
/api/profile/resume

### Parameters
#### Request Body (multipart/form-data)
- **title** (string) - Required - Resume title
- **file** (file) - Optional - PDF or DOCX, max 5 MB, magic-byte checked
- **id** (string) - Optional - Existing resume id for update

### Behavior
- If `id` and `title` are present: update
  - If a file is supplied: `replaceResumeFile`
  - Else: `editResume`
  - Returns `200`
- Otherwise: create, returns `201`

### Response
#### Success Responses
- **200**: Update successful
- **201**: Create successful

#### Error Responses
- **401**: Session required
- **400**: File too large / MIME not allowed / content-type mismatch
- **500**: Internal failure
```

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

### POST /api/backup/import/preflight

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/endpoints.md

Reads a backup without writing. Validates the uploaded backup file and returns preflight information.

```APIDOC
## POST /api/backup/import/preflight

### Description
Reads a backup without writing. Validates the uploaded backup file and returns preflight information.

### Method
POST

### Endpoint
/api/backup/import/preflight

### Parameters
#### Request Body
- **file** (file) - Required - The backup file to preflight.

### Response
#### Success Response (200)
- **manifest**: object - The backup manifest.
- **emailMatches**: boolean - Whether the backup email matches the current user.
- **targetIsEmpty**: boolean - Whether the target database is empty.
- **targetCounts**: object - Counts of records in the target.

#### Error Responses
- **413**: Payload too large (content-length or file size exceeds BACKUP_MAX_UPLOAD_BYTES).
- **400**: Missing/empty file, or unreadable zip / bad manifest / missing data.json (error message from BackupError.userMessage).
- **500**: Other failures.

```

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

### Configure MCP client for JobSync

Source: https://github.com/gsync/jobsync/blob/main/README.md

Configurations for connecting an MCP client to JobSync's remote MCP server. Use the Claude Desktop (via mcp-remote) version for Claude Desktop, which requires the npx mcp-remote bridge. Use the streamable-http version for clients that support that protocol natively, such as OpenClaw or Hermes. The URLs and tokens are placeholders that must be replaced with your own values.

```json
{
  "mcpServers": {
    "jobsync": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://<your-jobsync-url>/api/mcp",
        "--header",
        "Authorization: Bearer <your-token>"
      ]
    }
  }
}
```

```json
{
  "mcpServers": {
    "jobsync": {
      "type": "streamable-http",
      "url": "http://<your-jobsync-url>/api/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}
```

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

### Streamable-HTTP config for other clients

Source: https://github.com/gsync/jobsync/wiki/MCP

Use this for clients like OpenClaw and Hermes that support streamable-http natively. No bridge needed. Replace the URL and token with your actual values.

```json
{
  "mcpServers": {
    "jobsync": {
      "type": "streamable-http",
      "url": "http://<your-jobsync-url>/api/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}
```

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

### Backup schema with Zod (schema.ts)

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/backup.md

Defines the Zod schemas for the backup manifest and data. `ManifestSchema` requires `formatVersion` to be exactly `BACKUP_FORMAT_VERSION` (1), plus `appVersion`, `exportedAt`, `sourceEmail`, and `counts`. `BackupDataSchema` is a placeholder for 30 model arrays plus `_JobToTag`, `_QuestionToTag`, `jobStatuses`, and `user`; the actual shape is described in the surrounding prose.

```ts
export const BACKUP_FORMAT_VERSION = 1;

export const ManifestSchema = z.object({
  formatVersion: z.literal(BACKUP_FORMAT_VERSION),
  appVersion: z.string(),
  exportedAt: z.string(),
  sourceEmail: z.string(),
  counts: z.record(z.string(), z.number()),
});
export type BackupManifest = z.infer<typeof ManifestSchema>;

export const BackupDataSchema = z.object({ /* 30 model arrays + _JobToTag + _QuestionToTag + jobStatuses + user */ });
export type BackupData = z.infer<typeof BackupDataSchema>;
```

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

### POST /api/backup/import

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/endpoints.md

Performs a destructive import of a backup, optionally wiping existing data.

```APIDOC
## POST /api/backup/import

### Description
Performs a destructive import of a backup, optionally wiping existing data.

### Method
POST

### Endpoint
/api/backup/import

### Parameters
#### Request Body
- **file** (file) - Required - The backup file to import.
- **confirmWipe** (string) - Required - Set to "true" to replace existing data.

### Response
#### Success Response (200)
- **counts**: object - Counts of imported records.
- **filesWritten**: number - Number of files written.
- **snapshotPath**: string | null - Path to the created snapshot, if any.

#### Error Responses
- **413**: Payload too large.
- **400**: Missing/empty file, unreadable zip, bad manifest, missing data.json, stale session, active automation run, unresolved stage-type status, or anchor-data-wipe guard.
- **500**: Other failures.

```

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

### Snapshot API: SnapshotInfo interface and functions

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/backup.md

Defines the SnapshotInfo interface and the public functions for snapshot management: snapshotDir, writeSnapshot, listSnapshots, and readSnapshot. Snapshots are zip backups named pre-import-<ISO-stamp>.zip under <UPLOADS_DIR>/backups/<userId>/. readSnapshot validates the id against the anchored SNAPSHOT_ID regex as a path-traversal guard.

```ts
export interface SnapshotInfo {
  id: string;
  exportedAt: string;
  appVersion: string;
  counts: Record<string, number>;
  sizeBytes: number;
}

export function snapshotDir(userId: string): string
export async function writeSnapshot(userId: string, email: string): Promise<string>
export async function listSnapshots(userId: string): Promise<SnapshotInfo[]>
export async function readSnapshot(userId: string, id: string): Promise<Buffer>
```

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

### Run Jest unit tests

Source: https://github.com/gsync/jobsync/blob/main/CONTRIBUTING.md

Commands for running Jest unit tests. Use `npm run test` for all tests, `npm run test:watch` for watch mode, and the `--` variants to target a single file or a test name pattern.

```bash
npm run test               # Run all unit tests
npm run test:watch         # Watch mode
npm run test -- path/to/test.test.ts   # Single file
npm run test -- --testNamePattern="test name"  # Single test
```

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

### signIn

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/auth.md

Sign-in helper used with the credentials provider. Typically called with provider 'credentials' and options including email, password, and redirect.

```APIDOC
## signIn

### Description
Sign-in helper used by `authenticate()` in `src/actions/auth.actions.ts` with `signIn("credentials", { email, password, redirect: false })`.

### Parameters
- `provider` (string) - Required - The authentication provider, e.g., `"credentials"`.
- `options` (object) - Required - Options object containing:
  - `email` (string) - Required - User email.
  - `password` (string) - Required - User password.
  - `redirect` (boolean) - Optional - Whether to redirect after sign-in. Default is `true`.

### Returns
- `Promise<...>` - Result of the sign-in attempt.

### Example
```ts
await signIn("credentials", { email, password, redirect: false });
```
```

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

### Preprocessing Utilities

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/ai.md

Functions for validating and preprocessing resumes and text for AI reviews and match offers.

```APIDOC
## Preprocessing Utilities

### Description
Functions for validating and preprocessing resumes and text for AI reviews and match offers.

### Functions

#### validateResume(text: string, opts?: ...): ValidationResult
Validates a resume text.

#### convertResumeToText(resume: Resume): Promise<string>
Converts a Resume object to plain text.

#### preprocessText(singleLineText: string): Promise<PreprocessingResult>
Preprocesses a single-line text string.

#### preprocessResume(resume: Resume): Promise<PreprocessingResult>
Preprocesses a resume. This is the entry used for reviews and match offers. It fails (`success:false`) when a resume is too short or missing content.

### Types
```ts
export interface PreprocessedResume { normalizedText: string; metadata: ResumeMetadata; isValid: boolean }
export type PreprocessingResult =
  | { success: true; data: PreprocessedResume }
  | { success: false; error: { code: string; message: string; details?: object } };
```

### Validation Thresholds
- `MIN_CHAR_COUNT = 200`
- `MAX_WORD_COUNT = 10000`
```

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

### log (info, warn, error)

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/telemetry.md

The log object provides three methods (info, warn, error) for structured logging. Each method writes to the console first and then enqueues an OTLP log record tied to the ambient span when telemetry is enabled. These methods never throw into the request.

```APIDOC
## log.info

### Description
Logs an informational message to the console and enqueues an OTLP log record tied to the ambient span when telemetry is enabled. Never throws into the request.

### Method
info

### Signature
`log.info(message: string, attrs?: Attrs): void`

### Parameters
- **message** (string) - Required - The log message.
- **attrs** (Attrs) - Optional - Additional attributes to attach to the log record.

### Behavior
- Always writes to console first (`console.info`).
- Enqueues an OTLP log record tied to the ambient span when enabled.
- Never throws into the request.
```

```APIDOC
## log.warn

### Description
Logs a warning message to the console and enqueues an OTLP log record tied to the ambient span when telemetry is enabled. Never throws into the request.

### Method
warn

### Signature
`log.warn(message: string, attrs?: Attrs): void`

### Parameters
- **message** (string) - Required - The log message.
- **attrs** (Attrs) - Optional - Additional attributes to attach to the log record.

### Behavior
- Always writes to console first (`console.warn`).
- Enqueues an OTLP log record tied to the ambient span when enabled.
- Never throws into the request.
```

```APIDOC
## log.error

### Description
Logs an error message to the console and enqueues an OTLP log record tied to the ambient span when telemetry is enabled. Never throws into the request.

### Method
error

### Signature
`log.error(message: string, attrs?: Attrs): void`

### Parameters
- **message** (string) - Required - The log message.
- **attrs** (Attrs) - Optional - Additional attributes to attach to the log record.

### Behavior
- Always writes to console first (`console.error`).
- Enqueues an OTLP log record tied to the ambient span when enabled.
- Never throws into the request.
```

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

### readManifest(zip: JSZip): Promise<BackupManifest>

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/backup.md

Reads and validates the manifest.json from a backup zip. Throws BackupError for version mismatches or missing required fields.

```APIDOC
## readManifest(zip: JSZip): Promise<BackupManifest>

### Description
Reads and validates the manifest.json from a backup zip. Throws BackupError for version mismatches or missing required fields.

### Method
Function

### Endpoint
src/lib/backup/manifest.ts

### Parameters
#### Parameters
- **zip** (JSZip) - Required - The loaded JSZip object of the backup archive.

### Returns
- **Promise<BackupManifest>** - A promise that resolves to the validated BackupManifest.

### Errors
- **BackupError** - Thrown when manifest.json is missing, version mismatch, or missing required fields.
```

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

### Company Actions

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/server-actions.md

Server actions for managing companies and watched boards.

```APIDOC
## getCompanyList

### Description
Retrieves a paginated list of companies.

### Method
Action

### Endpoint
`getCompanyList(...)`

### Parameters
- **page** (number) - Optional - Page number.
- **limit** (number) - Optional - Number of records per page.

### Response
Returns a list of companies.

```

```APIDOC
## getAllCompanies

### Description
Retrieves all companies.

### Method
Action

### Endpoint
`getAllCompanies()`

### Response
Returns an array of all companies.

```

```APIDOC
## getCompanyById

### Description
Retrieves a single company by its ID.

### Method
Action

### Endpoint
`getCompanyById(id)`

### Parameters
- **id** (string) - Required - The company ID.

### Response
Returns the company object.

```

```APIDOC
## getCompanyDetails

### Description
Retrieves detailed company information.

### Method
Action

### Endpoint
`getCompanyDetails(id)`

### Parameters
- **id** (string) - Required - The company ID.

### Response
Returns a `CompanyDetails` object.

```

```APIDOC
## addCompany

### Description
Adds a new company.

### Method
Action

### Endpoint
`addCompany(...)`

### Parameters
- **input** (object) - Required - The company data.

### Response
Returns the created company.

```

```APIDOC
## updateCompany

### Description
Updates an existing company.

### Method
Action

### Endpoint
`updateCompany(...)`

### Parameters
- **input** (object) - Required - The company data including the ID.

### Response
Returns the updated company.

```

```APIDOC
## deleteCompanyById

### Description
Deletes a company by its ID.

### Method
Action

### Endpoint
`deleteCompanyById(id)`

### Parameters
- **id** (string) - Required - The company ID.

### Response
Returns a success indicator.

```

```APIDOC
## watchBoardCompany

### Description
Watches a company on a board.

### Method
Action

### Endpoint
`watchBoardCompany(...)`

### Parameters
- **input** (object) - Required - The watch data.

### Response
Returns the watch result.

```

```APIDOC
## setCompanyWatched

### Description
Sets whether a company is watched.

### Method
Action

### Endpoint
`setCompanyWatched(id, watched)`

### Parameters
- **id** (string) - Required - The company ID.
- **watched** (boolean) - Required - Whether to watch the company.

### Response
Returns the updated company.

```

```APIDOC
## getWatchedBoards

### Description
Retrieves all watched boards.

### Method
Action

### Endpoint
`getWatchedBoards()`

### Response
Returns a list of watched boards.

```

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

### addJob

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/server-actions.md

Server action to create a new job and its first stage. Returns a standard success/data/message shape.

```APIDOC
## addJob(formData: JobForm)

### Description
Creates a new job and its first stage.

### Method
Server Action

### Parameters
- **formData** (JobForm) - Required - Job form data.

### Returns
- **success** (boolean) - Indicates whether the operation succeeded.
- **data** (any, optional) - Additional data on success.
- **message** (string, optional) - Error message on failure.

```

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

### getModel(provider, modelName, userId?)

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/ai.md

Returns a Vercel AI SDK LanguageModel instance for the given provider and model name, resolving credentials and factory functions.

```APIDOC
## getModel(provider, modelName, userId?)

### Description
Returns a Vercel AI SDK `LanguageModel` instance for the specified provider and model name. Resolves the provider factory and API credential, throwing descriptive errors when the provider is unknown, the factory is missing, or credentials are not configured.

### Method
FUNCTION

### Endpoint
`getModel(provider, modelName, userId?)`

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **provider** (ProviderType) - Required - The AI provider identifier: "openai" | "ollama" | "deepseek" | "openrouter" | "gemini"
- **modelName** (string) - Required - The model name to instantiate
- **userId** (string) - Optional - User ID used for API key resolution

### Request Example
```ts
const model = await getModel("openai", "gpt-4o", "user_123");
```

### Response
Returns a Vercel AI SDK `LanguageModel` instance.

### Errors
- `Error(
```

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

### createJobTitle

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/server-actions.md

Server action to create a job title reference row. Returns a standard success/data/message shape.

```APIDOC
## createJobTitle(...)

### Description
Creates a new job title reference row.

### Method
Server Action

### Parameters
- (parameters not specified in source)

### Returns
- **success** (boolean) - Indicates whether the operation succeeded.
- **data** (any, optional) - Additional data on success.
- **message** (string, optional) - Error message on failure.

```

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

### createJobSource

Source: https://github.com/gsync/jobsync/blob/main/_autodocs/api-reference/server-actions.md

Server action to create a job source reference row. Returns a standard success/data/message shape.

```APIDOC
## createJobSource(...)

### Description
Creates a new job source reference row.

### Method
Server Action

### Parameters
- (parameters not specified in source)

### Returns
- **success** (boolean) - Indicates whether the operation succeeded.
- **data** (any, optional) - Additional data on success.
- **message** (string, optional) - Error message on failure.

```

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

### Create feature branch

Source: https://github.com/gsync/jobsync/blob/main/CONTRIBUTING.md

Creates and switches to a new branch for your feature, based on the current branch (dev).

```bash
git checkout -b feat/your-feature-name
```
Tokens:
Raw