# Faasjs API Jobs

> Use when building or reviewing FaasJS backend APIs and jobs: .api.ts files, defineApi, zod params schemas, HttpError, HTTP helpers, middleware/staticHandler, .job.ts files, defineJob, typed job paths and params, enqueueJob including transaction-coupled enqueueing, cron schedulers, retries, leases, workers, discovery, and job tests.

- Skill: `faasjs/faasjs-api-jobs` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add faasjs/faasjs-api-jobs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/faasjs/faasjs-api-jobs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: faasjs (https://skillmd.com/u/faasjs)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/faasjs/faasjs-api-jobs

---


# FaasJS API And Jobs

## Default Workflow

1. Keep API and job files inside the feature slice that owns the behavior.
2. Define external input schemas at the boundary and keep business input visible as `params.key`.
3. Use `HttpError` with explicit status codes for expected API failures; reserve plain `Error` for internal failures.
4. Use injected HTTP helpers for cookies, sessions, headers, status, body, and content type.
5. Treat jobs as at-least-once execution, make enqueueing explicit, and keep generated paths aligned with runtime discovery.

## Load These References

- `.api.ts`, `defineApi`, schemas, `params`, errors, injected fields, and type generation: `references/guidelines/define-api.md`.
- Cookies, sessions, response helpers, and HTTP plugin config: `references/guidelines/http-plugin.md`.
- Static file serving and middleware: `references/guidelines/middleware.md`.
- `.job.ts`, `defineJob`, `enqueueJob`, process ownership, and transaction-coupled enqueueing: `references/guidelines/jobs.md`.
- Generated job paths, params types, typegen, duplicate paths, and discovery roots: `references/guidelines/job-types-and-paths.md`.
- Cron expressions, scheduler deduplication, retries, attempts, and lease expiry: `references/guidelines/job-scheduling-and-retries.md`.
- Direct handler, queue, worker, scheduler, transaction, type, and discovery tests: `references/guidelines/job-testing.md`.

## Gotchas

- Destructure only the top-level handler context, such as `handler({ params })`; do not destructure business fields from `params`.
- Run `npx faas types` after adding, renaming, moving, or removing `.api.ts` or `.job.ts` files; ordinary handler edits do not change path declarations.
- Do not cast dynamic strings to generated job paths or keep transaction clients after their callbacks.
- Check user, tenant, organization, project, role, or permission scope before reading or mutating data.
- Do not log secrets, tokens, passwords, cookies, full sensitive payloads, or unredacted third-party responses.

## Validation

- Run focused API or job tests with `vp test <pattern>`.
- Run `npx faas types` after API or job path topology changes.
- Run `vp check --fix` before handoff when backend files changed.