1---2name: faasjs-api-jobs3description: 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.4---56# FaasJS API And Jobs78## Default Workflow9101. Keep API and job files inside the feature slice that owns the behavior.112. Define external input schemas at the boundary and keep business input visible as `params.key`.123. Use `HttpError` with explicit status codes for expected API failures; reserve plain `Error` for internal failures.134. Use injected HTTP helpers for cookies, sessions, headers, status, body, and content type.145. Treat jobs as at-least-once execution, make enqueueing explicit, and keep generated paths aligned with runtime discovery.1516## Load These References1718- `.api.ts`, `defineApi`, schemas, `params`, errors, injected fields, and type generation: `references/guidelines/define-api.md`.19- Cookies, sessions, response helpers, and HTTP plugin config: `references/guidelines/http-plugin.md`.20- Static file serving and middleware: `references/guidelines/middleware.md`.21- `.job.ts`, `defineJob`, `enqueueJob`, process ownership, and transaction-coupled enqueueing: `references/guidelines/jobs.md`.22- Generated job paths, params types, typegen, duplicate paths, and discovery roots: `references/guidelines/job-types-and-paths.md`.23- Cron expressions, scheduler deduplication, retries, attempts, and lease expiry: `references/guidelines/job-scheduling-and-retries.md`.24- Direct handler, queue, worker, scheduler, transaction, type, and discovery tests: `references/guidelines/job-testing.md`.2526## Gotchas2728- Destructure only the top-level handler context, such as `handler({ params })`; do not destructure business fields from `params`.29- Run `npx faas types` after adding, renaming, moving, or removing `.api.ts` or `.job.ts` files; ordinary handler edits do not change path declarations.30- Do not cast dynamic strings to generated job paths or keep transaction clients after their callbacks.31- Check user, tenant, organization, project, role, or permission scope before reading or mutating data.32- Do not log secrets, tokens, passwords, cookies, full sensitive payloads, or unredacted third-party responses.3334## Validation3536- Run focused API or job tests with `vp test <pattern>`.37- Run `npx faas types` after API or job path topology changes.38- Run `vp check --fix` before handoff when backend files changed.
faasjs