@10x-media/jobs 0.1.0-beta.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# @10x-media/jobs
+
+## 0.1.0-beta.0
+
+### Minor Changes
+
+- Initial beta of `@10x-media/jobs`: an ops layer over Payload's built-in jobs queue, opt-in and layered, with full multi-node support.
+
+  - **Observability** (always on): a jobs dashboard over `payload-jobs` with a derived status column, a queue-health bar, error and log panels, friendlier labels, and a read-only-record model.
+  - **Reliability** (`reliability`): a worker heartbeat lease, a stuck-job sweeper that requeues then dead-letters, and multi-node leader election with fencing tokens, so jobs survive crashes and run safely across replicas. Works on MongoDB and PostgreSQL.
+  - **Execution** (`createWorker`): a graceful-drain worker that runs jobs on every node, schedules and sweeps only on the elected leader, and finishes in-flight work on SIGTERM, plus `autoRunConfig` for the simple single-node path.
+  - **Queue control** (`queueControl`): durable cluster-wide pause and resume, a queue-health endpoint, and a hardened, pause-aware run endpoint with real access control (including a `CRON_SECRET` checker for serverless).
+  - **Deployment presets** for serverless (Vercel), single-node Docker, and multi-node Docker, with a documented worker entrypoint.
+
+  Enable each layer as your topology needs; with none enabled you still get the dashboard. See the README for the per-topology guide.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 10x Media GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,351 @@
+# @10x-media/jobs
+
+A jobs ops dashboard and a production-grade reliability, execution, and queue-control layer for Payload's built-in `payload-jobs`.
+
+[![npm](https://img.shields.io/npm/v/@10x-media/jobs?style=flat-square)](https://www.npmjs.com/package/@10x-media/jobs)
+
+Part of the [@10x-media Payload plugins](https://github.com/10x-media/payload-plugins) collection. In beta: published under the `beta` dist-tag until a stable 1.0.
+
+## Requirements
+
+- Payload v3 (peer: `payload@^3.82.0`)
+- React 19 (peer)
+
+## Installation
+
+```bash
+pnpm add @10x-media/jobs
+```
+
+## Usage
+
+```ts
+import { buildConfig } from 'payload'
+import { jobs } from '@10x-media/jobs'
+
+export default buildConfig({
+  // ...
+  plugins: [
+    jobs({
+      // options
+    }),
+  ],
+})
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `disabled` | `boolean` | `false` | When `true`, returns the incoming config unchanged. Useful for toggling the plugin per environment. |
+| `reliability` | `ReliabilityOptions \| false` | off | Job leases, the orphan sweeper, leader election, and serverless staleness. Opt in with `{}` (defaults) or a tuned object. |
+| `queueControl` | `QueueControlOptions \| false` | off | Cluster-wide pause/resume, hardened run/sweep/status endpoints, and access guards. Opt in with `{}` (defaults) or a tuned object. |
+
+<!-- Add new options to this table as you build them. -->
+
+## Deployment topologies
+
+The plugin ships four opt-in layers. You add only the ones your deployment needs, and you pick a topology preset to wire reliability and queue-control consistently.
+
+### Overview
+
+| Layer | What it adds | How to enable |
+|---|---|---|
+| Observability | The jobs ops dashboard (status, queue health, error and log panels) and i18n. | Always on (just adding `jobs()`). |
+| Reliability | Job leases, an orphan sweeper, leader election, serverless staleness. | `reliability: {}` (or a tuned `ReliabilityOptions`). |
+| Execution | A standalone worker (`createWorker`) that runs jobs everywhere and schedules/sweeps only while holding the leader lease, with a graceful SIGTERM drain. | Run the worker entrypoint as its own process. |
+| Queue control | Cluster-wide pause/resume plus hardened `/api/payload-jobs/queue-run`, `/queue-sweep`, and `/queue-status` endpoints with access guards. | `queueControl: {}` (or a tuned `QueueControlOptions`). |
+
+Every layer is opt-in. The observability dashboard is always present once the plugin is installed. The other three you turn on as your topology demands.
+
+Three facts shape every topology below.
+
+1. **Reliability and queue-control require at least one configured task.** The `payload-jobs` collection only materializes once you configure at least one task. With zero tasks, `createWorker` throws a clear error telling you to add one, and the lease store has no table to read. Configure your tasks on `jobs.tasks` in `buildConfig` before enabling reliability or running a worker.
+
+2. **The worker is a separate process, not your web server.** The execution layer (`createWorker`) is meant to run as its own long-lived process (a worker container, a separate Vercel-incompatible service). Your Next.js / Payload web server handles HTTP. The worker boots its own Payload instance against the same database and owns the run/schedule/sweep loops. The only topology that does not run a worker process is serverless, which drives everything from cron-hit endpoints instead.
+
+3. **Completed jobs are deleted, not kept.** Payload's `jobs.deleteJobOnComplete` defaults to `true` in v3.85, so a job that finishes successfully is removed from the queue. The dashboard and the `/queue-status` counts therefore reflect pending, processing, failed, and scheduled jobs, never completed ones. Set `jobs.deleteJobOnComplete: false` in `buildConfig` if you want completed jobs to persist for auditing.
+
+Pick a preset:
+
+```ts
+import { jobs, serverlessPreset, singleNodePreset, multiNodePreset } from '@10x-media/jobs'
+
+// Serverless (Vercel): cron-driven endpoints, no long-running worker.
+jobs({ ...serverlessPreset({ maxDurationMs: 800_000 }) })
+
+// Single-node Docker: one worker container, claim races moot.
+jobs({ ...singleNodePreset() })
+
+// Multi-node Docker: many worker replicas, one elected scheduler and sweeper.
+jobs({ ...multiNodePreset({ leaderId: process.env.HOSTNAME }) })
+```
+
+Each preset returns `{ reliability, queueControl }`, so spreading it into `jobs({ ... })` configures both layers at once. An override after the spread replaces the whole group (it does not deep-merge), so to tweak one field spread the group too: `jobs({ ...multiNodePreset(), reliability: { ...multiNodePreset().reliability, leaderId: 'node-7' } })`.
+
+### Serverless (Vercel)
+
+Serverless functions are killed at their `maxDuration` with no SIGTERM, so there is no long-running worker and heartbeats are meaningless. `serverlessPreset` instead derives job staleness from the platform hard-kill duration and guards the control endpoints with a shared cron secret. You drive the run and sweep from Vercel Cron.
+
+```ts
+// payload.config.ts
+import { buildConfig } from 'payload'
+import { jobs, serverlessPreset } from '@10x-media/jobs'
+
+export default buildConfig({
+  // ...
+  jobs: {
+    tasks: [
+      // ...your tasks; at least one is required.
+    ],
+  },
+  plugins: [jobs({ ...serverlessPreset({ maxDurationMs: 800_000 }) })],
+})
+```
+
+`serverlessPreset` sets `reliability.jobLeaseTtlMs` and `reliability.serverless.maxDurationMs` to your `maxDurationMs`, and sets `queueControl.access` to `cronSecretAccess()`. Pass `cronSecretEnvVar` if your secret lives somewhere other than `CRON_SECRET`.
+
+Generate the `vercel.json` crons with `vercelCrons()`:
+
+```ts
+// scripts/vercel-crons.ts (or hand-write the array below into vercel.json)
+import { vercelCrons } from '@10x-media/jobs'
+
+console.log(JSON.stringify({ crons: vercelCrons() }, null, 2))
+```
+
+```json
+{
+  "crons": [
+    { "path": "/api/payload-jobs/queue-run?allQueues=true", "schedule": "* * * * *" },
+    { "path": "/api/payload-jobs/queue-sweep", "schedule": "* * * * *" }
+  ]
+}
+```
+
+`vercelCrons()` defaults to every minute (Vercel Pro). Override any path or schedule, for example `vercelCrons({ sweepSchedule: '*/5 * * * *' })`.
+
+**The cron secret.** Set `CRON_SECRET` in your Vercel project. Vercel sends it as `Authorization: Bearer ${CRON_SECRET}` on every cron invocation, and `cronSecretAccess` checks exactly that header (a logged-in admin user also passes, so you can hit the endpoints manually from the panel). Without the secret set, unauthenticated cron requests are rejected.
+
+**The endpoints.** Both are plugin-registered GET endpoints on the `payload-jobs` collection:
+
+- `/api/payload-jobs/queue-run` runs due jobs (pause-aware, mirrors the native run params). `?allQueues=true` runs every queue, `?queue=<name>` runs one, `?limit=<n>` caps jobs per invocation, `?disableScheduling=true` skips schedule handling.
+- `/api/payload-jobs/queue-sweep` runs one orphan sweep (a single cron invocation, so no leader election). Requires reliability to be enabled.
+
+**Vercel limits.** Match your plan to a cron cadence and a function duration:
+
+- **Hobby**: crons run at most **once per day** and functions cap at **300s**. That is unusable for real job processing. Use Hobby only for a toy or a demo.
+- **Pro**: crons run **per minute** and functions extend to **800s**. That per-minute, 800s window is the practical floor for serverless job processing, which is why `serverlessPreset({ maxDurationMs: 800_000 })` and `vercelCrons()` default to it.
+
+**`limit` guidance.** A serverless run must finish inside `maxDuration`. Set `?limit=<n>` on the run cron (or `vercelCrons({ runPath: '/api/payload-jobs/queue-run?allQueues=true&limit=20' })`) so one batch of jobs comfortably fits the window. Size the limit to `maxDuration / (slowest expected job duration)` with headroom. If a batch risks overrunning, lower the limit and let the next minute's cron pick up the rest.
+
+### Single-node Docker
+
+One worker container claims and runs every job serially, so claim races are moot and leader election is a no-op (the single node always wins). `singleNodePreset()` turns on reliability and queue-control with defaults; the in-process worker runs the scheduler and sweeper directly.
+
+```ts
+// payload.config.ts
+import { buildConfig } from 'payload'
+import { jobs, singleNodePreset } from '@10x-media/jobs'
+
+export default buildConfig({
+  // ...
+  jobs: {
+    tasks: [
+      // ...your tasks; at least one is required.
+    ],
+  },
+  plugins: [jobs({ ...singleNodePreset() })],
+})
+```
+
+Run the worker as its own service in `docker-compose.yml`, alongside your web service and database:
+
+```yaml
+services:
+  web:
+    build: .
+    command: ['node', 'server.js']
+    environment:
+      DATABASE_URI: postgres://postgres:postgres@db:5432/app
+      PAYLOAD_SECRET: ${PAYLOAD_SECRET}
+    depends_on: [db]
+
+  worker:
+    build: .
+    # Exec-form CMD so Node is PID 1 and receives SIGTERM directly.
+    command: ['node', 'dist/worker.js']
+    environment:
+      DATABASE_URI: postgres://postgres:postgres@db:5432/app
+      PAYLOAD_SECRET: ${PAYLOAD_SECRET}
+    depends_on: [db]
+
+  db:
+    image: postgres:16
+    environment:
+      POSTGRES_DB: app
+      POSTGRES_PASSWORD: postgres
+```
+
+`dist/worker.js` is your compiled worker entrypoint (see below). In development you can run the TypeScript source directly with `node --import tsx worker.ts`. With one claimer, you do not need to tune leader leases; defaults are fine.
+
+### Multi-node Docker
+
+Many worker replicas share one database. Every replica runs jobs, but only the replica holding the `scheduler` lease handles schedules and only the one holding the `sweeper` lease runs the orphan sweep. `multiNodePreset()` is the default: leader-elected scheduling and sweeping with no extra infrastructure (the leases live in the plugin-owned `payload-jobs-locks` collection).
+
+```ts
+// payload.config.ts
+import { buildConfig } from 'payload'
+import { jobs, multiNodePreset } from '@10x-media/jobs'
+
+export default buildConfig({
+  // ...
+  jobs: {
+    tasks: [
+      // ...your tasks; at least one is required.
+    ],
+  },
+  // process.env.HOSTNAME is each container's id, a natural stable leader id.
+  plugins: [jobs({ ...multiNodePreset({ leaderId: process.env.HOSTNAME }) })],
+})
+```
+
+`leaderId` is the stable identity this node uses when it acquires a lease. Pass `process.env.HOSTNAME` (or any per-replica stable value); omit it to let the worker generate a `hostname:pid` identity at runtime. Leadership fails over automatically: if the current leader dies, another replica acquires the lease once it expires (`leaderLeaseTtlMs`, default 30s) and a monotonic fence token prevents a revived zombie from acting.
+
+**Env-designated-leader fallback (zero infra).** If you do not want leader election at all, you can designate one replica as the scheduler by environment. Run native auto-scheduling on a single replica and disable scheduling on the rest:
+
+```ts
+import { autoRunConfig } from '@10x-media/jobs'
+
+const isScheduler = process.env.JOBS_SCHEDULER === '1'
+
+export default buildConfig({
+  // ...
+  jobs: {
+    tasks: [/* ... */],
+    // Only the designated replica handles schedules; the others just run jobs.
+    autoRun: autoRunConfig({ disableScheduling: !isScheduler }),
+  },
+  plugins: [jobs({ ...multiNodePreset() })],
+})
+```
+
+Set `JOBS_SCHEDULER=1` on exactly one replica (or run a single dedicated scheduler replica). This trades automatic failover for zero coordination state. Leader election (the default) is preferred when you want a replica loss to recover on its own.
+
+**Graceful shutdown is a hard requirement under multi-node.** When an orchestrator rolls or scales down a replica, it sends SIGTERM, then SIGKILLs after a grace period. The worker's drain requeues its in-flight job (so another replica picks it up) and releases its leases, but only if it is given time to finish.
+
+- The orchestrator grace period **must exceed** the worker's `drainTimeoutMs`. In Docker Compose set `stop_grace_period`; in Kubernetes set `terminationGracePeriodSeconds`. If the grace period is shorter, the orchestrator SIGKILLs a still-draining worker and you lose the clean requeue.
+- The container `CMD` must be **exec form** (`CMD ["node", "dist/worker.js"]`, not `CMD node dist/worker.js`). Shell form runs Node as a child of `/bin/sh`, which does not forward SIGTERM, so the worker never drains and is hard-killed every time.
+
+```yaml
+services:
+  worker:
+    build: .
+    command: ['node', 'dist/worker.js'] # exec form: Node receives SIGTERM
+    # Must be greater than the worker's drainTimeoutMs (default 30s here, so 45s of headroom).
+    stop_grace_period: 45s
+    deploy:
+      replicas: 3
+    environment:
+      DATABASE_URI: postgres://postgres:postgres@db:5432/app
+      PAYLOAD_SECRET: ${PAYLOAD_SECRET}
+    depends_on: [db]
+```
+
+The Kubernetes equivalent: an exec-form `command` in the pod spec and `terminationGracePeriodSeconds: 45` (greater than `drainTimeoutMs`).
+
+### The worker entrypoint
+
+The worker is a thin bootstrap: boot Payload, resolve reliability options, and start the worker. `createWorker` installs SIGTERM/SIGINT drain handlers by default, so the process drains and exits 0 on a real signal. This is the canonical pattern (mirrors `packages/jobs/dev/worker.ts`):
+
+```ts
+// worker.ts
+import { getPayload } from 'payload'
+import { createWorker, resolveReliabilityOptions } from '@10x-media/jobs'
+
+import config from './payload.config'
+
+const RELIABILITY_OPTIONS = {
+  jobLeaseTtlMs: 300_000,
+  leaderLeaseTtlMs: 30_000,
+  sweepIntervalMs: 60_000,
+}
+
+const main = async (): Promise<void> => {
+  const payload = await getPayload({ config })
+  const reliability = resolveReliabilityOptions(RELIABILITY_OPTIONS)
+  if (!reliability) {
+    throw new Error('@10x-media/jobs worker: reliability resolved to null')
+  }
+  createWorker({
+    payload,
+    reliability,
+    drainTimeoutMs: 30_000,
+    runIntervalMs: 2_000,
+  }).start()
+  payload.logger.info('@10x-media/jobs worker started; awaiting jobs and signals')
+}
+
+main().catch((err) => {
+  console.error('@10x-media/jobs worker failed to start', err)
+  process.exit(1)
+})
+```
+
+Notes:
+
+- `resolveReliabilityOptions` fully defaults your `ReliabilityOptions`. It returns `null` when reliability is off (passed `false` or `undefined`), which the worker cannot run with, hence the guard.
+- Pass the same reliability tuning you give the plugin (share a constant between `payload.config.ts` and `worker.ts`) so the lease TTLs match across the cluster.
+- `createWorker` registers SIGTERM and SIGINT handlers automatically (`installSignals` defaults to `true`). On signal it drains in-flight jobs (within `drainTimeoutMs`), requeues any straggler, releases leases, destroys the Payload instance, and exits 0. Keep your orchestrator grace period above `drainTimeoutMs` (see Multi-node above).
+- Run it with `node --import tsx worker.ts` in development, or compile it and run `node dist/worker.js` in production.
+
+### CI-optional e2e recipes
+
+Two real-process scenarios are proven in-process by the test suite, so they are not automated in CI. Both are useful to run by hand against a real database when validating a deployment. Mark them manual / CI-optional.
+
+**Recipe 1: two workers, one elected scheduler.** Run two worker processes against the same database and confirm exactly one holds the `scheduler` lease.
+
+```bash
+# Terminal 1 and Terminal 2 (same DATABASE_URI), distinct leader ids:
+JOBS_LEADER_ID=node-a node --import tsx worker.ts
+JOBS_LEADER_ID=node-b node --import tsx worker.ts
+```
+
+Then inspect the leases collection (one row per role, `owner` names the current holder):
+
+```ts
+const locks = await payload.find({
+  collection: 'payload-jobs-locks',
+  where: { role: { equals: 'scheduler' } },
+})
+// Expect exactly one row whose `owner` is node-a OR node-b, never both.
+console.log(locks.docs.map((d) => ({ role: d.role, owner: d.owner, fenceToken: d.fenceToken })))
+```
+
+Only the owning worker logs schedule handling; the other runs jobs but never schedules. (Wire `leaderId` into your worker from `process.env.JOBS_LEADER_ID` for this recipe.)
+
+**Recipe 2: kill a worker mid-job, watch the sweeper recover the orphan.** Confirm that a hard-killed worker's in-flight job is reclaimed by another worker's sweeper after the lease expires.
+
+```bash
+# Start two workers against the same DB (as above), then queue a long job:
+#   await payload.jobs.queue({ task: 'your-slow-task', input: { ... } })
+# Find the PID of the worker that claimed it and hard-kill it (no drain):
+kill -9 <worker-pid>
+```
+
+A `kill -9` skips the graceful drain entirely, so the job stays marked processing with a stale lease. After `jobLeaseTtlMs` elapses, the surviving worker's sweeper detects the orphan and requeues it (up to `maxRecoveries` times, then dead-letters). Watch the job flip back to queued and then get re-claimed:
+
+```ts
+const orphans = await payload.find({
+  collection: 'payload-jobs',
+  where: { and: [{ processing: { equals: false } }, { recoveryAttempts: { greater_than: 0 } }] },
+})
+// After the lease TTL, the killed worker's job appears here with recoveryAttempts >= 1.
+console.log(orphans.totalDocs)
+```
+
+Give it at least `jobLeaseTtlMs + sweepIntervalMs` before asserting recovery.
+
+## License
+
+[MIT](./LICENSE). Copyright 10x Media GmbH.

package/dist/deriveJobStatus-CM_sCsgm.js

@@ -0,0 +1,72 @@
+//#region src/jobs/deriveJobStatus.ts
+const isCancelled = (error) => typeof error === "object" && error !== null && error.cancelled === true;
+/**
+* Collapse a job's raw fields into one status. Payload has no status field; the
+* state lives across `processing`, `hasError`, `error.cancelled`, `completedAt`,
+* `waitUntil`, and `totalTried`. Order matters: the first matching rule wins.
+*/
+const deriveJobStatus = (job, now = Date.now()) => {
+	if (job.processing === true) return "running";
+	if (job.hasError === true) return isCancelled(job.error) ? "cancelled" : "failed";
+	if (job.completedAt) return "succeeded";
+	if ((job.totalTried ?? 0) > 0) return "retrying";
+	if (job.waitUntil && new Date(job.waitUntil).getTime() > now) return "scheduled";
+	return "queued";
+};
+const NOT_RUNNING = { processing: { not_equals: true } };
+const NO_ERROR = { hasError: { equals: false } };
+const NOT_COMPLETED = { completedAt: { exists: false } };
+const NOT_TRIED = { totalTried: { equals: 0 } };
+/**
+* A Payload `where` selecting exactly the jobs `deriveJobStatus` would label with
+* `status`. Each clause negates the higher-precedence rules so the seven
+* partition the collection; the health bar counts each with `payload.count`, and
+* a cross-DB test asserts the counts match `deriveJobStatus` row for row.
+* `processing`/`hasError`/`totalTried` always carry their Payload defaults
+* (`false`/`false`/`0`), so the boolean and number clauses are null-safe.
+*/
+const statusWhere = (status, now = Date.now()) => {
+	const at = new Date(now).toISOString();
+	return {
+		running: { processing: { equals: true } },
+		cancelled: { and: [
+			NOT_RUNNING,
+			{ hasError: { equals: true } },
+			{ "error.cancelled": { equals: true } }
+		] },
+		failed: { and: [
+			NOT_RUNNING,
+			{ hasError: { equals: true } },
+			{ or: [{ "error.cancelled": { exists: false } }, { "error.cancelled": { equals: false } }] }
+		] },
+		succeeded: { and: [
+			NOT_RUNNING,
+			NO_ERROR,
+			{ completedAt: { exists: true } }
+		] },
+		retrying: { and: [
+			NOT_RUNNING,
+			NO_ERROR,
+			NOT_COMPLETED,
+			{ totalTried: { greater_than: 0 } }
+		] },
+		scheduled: { and: [
+			NOT_RUNNING,
+			NO_ERROR,
+			NOT_COMPLETED,
+			NOT_TRIED,
+			{ waitUntil: { greater_than: at } }
+		] },
+		queued: { and: [
+			NOT_RUNNING,
+			NO_ERROR,
+			NOT_COMPLETED,
+			NOT_TRIED,
+			{ or: [{ waitUntil: { exists: false } }, { waitUntil: { less_than_equal: at } }] }
+		] }
+	}[status];
+};
+//#endregion
+export { statusWhere as n, deriveJobStatus as t };
+
+//# sourceMappingURL=deriveJobStatus-CM_sCsgm.js.map

package/dist/deriveJobStatus-CM_sCsgm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deriveJobStatus-CM_sCsgm.js","names":[],"sources":["../src/jobs/deriveJobStatus.ts"],"sourcesContent":["import type { Where } from 'payload'\n\n/** The seven derived job states, by precedence (see `deriveJobStatus`). */\nexport type JobStatus =\n\t| 'cancelled'\n\t| 'failed'\n\t| 'queued'\n\t| 'retrying'\n\t| 'running'\n\t| 'scheduled'\n\t| 'succeeded'\n\n/** The subset of `payload-jobs` fields a status is derived from. */\nexport interface JobStatusInput {\n\tcompletedAt?: null | string\n\terror?: unknown\n\thasError?: boolean | null\n\tprocessing?: boolean | null\n\ttotalTried?: null | number\n\twaitUntil?: null | string\n}\n\nconst isCancelled = (error: unknown): boolean =>\n\ttypeof error === 'object' &&\n\terror !== null &&\n\t(error as { cancelled?: unknown }).cancelled === true\n\n/**\n * Collapse a job's raw fields into one status. Payload has no status field; the\n * state lives across `processing`, `hasError`, `error.cancelled`, `completedAt`,\n * `waitUntil`, and `totalTried`. Order matters: the first matching rule wins.\n */\nexport const deriveJobStatus = (job: JobStatusInput, now: number = Date.now()): JobStatus => {\n\tif (job.processing === true) {\n\t\treturn 'running'\n\t}\n\tif (job.hasError === true) {\n\t\treturn isCancelled(job.error) ? 'cancelled' : 'failed'\n\t}\n\tif (job.completedAt) {\n\t\treturn 'succeeded'\n\t}\n\tif ((job.totalTried ?? 0) > 0) {\n\t\treturn 'retrying'\n\t}\n\tif (job.waitUntil && new Date(job.waitUntil).getTime() > now) {\n\t\treturn 'scheduled'\n\t}\n\treturn 'queued'\n}\n\nconst NOT_RUNNING: Where = { processing: { not_equals: true } }\nconst NO_ERROR: Where = { hasError: { equals: false } }\nconst NOT_COMPLETED: Where = { completedAt: { exists: false } }\nconst NOT_TRIED: Where = { totalTried: { equals: 0 } }\n\n/**\n * A Payload `where` selecting exactly the jobs `deriveJobStatus` would label with\n * `status`. Each clause negates the higher-precedence rules so the seven\n * partition the collection; the health bar counts each with `payload.count`, and\n * a cross-DB test asserts the counts match `deriveJobStatus` row for row.\n * `processing`/`hasError`/`totalTried` always carry their Payload defaults\n * (`false`/`false`/`0`), so the boolean and number clauses are null-safe.\n */\nexport const statusWhere = (status: JobStatus, now: number = Date.now()): Where => {\n\tconst at = new Date(now).toISOString()\n\tconst clauses: Record<JobStatus, Where> = {\n\t\trunning: { processing: { equals: true } },\n\t\tcancelled: {\n\t\t\tand: [NOT_RUNNING, { hasError: { equals: true } }, { 'error.cancelled': { equals: true } }],\n\t\t},\n\t\tfailed: {\n\t\t\tand: [\n\t\t\t\tNOT_RUNNING,\n\t\t\t\t{ hasError: { equals: true } },\n\t\t\t\t{\n\t\t\t\t\tor: [{ 'error.cancelled': { exists: false } }, { 'error.cancelled': { equals: false } }],\n\t\t\t\t},\n\t\t\t],\n\t\t},\n\t\tsucceeded: { and: [NOT_RUNNING, NO_ERROR, { completedAt: { exists: true } }] },\n\t\tretrying: { and: [NOT_RUNNING, NO_ERROR, NOT_COMPLETED, { totalTried: { greater_than: 0 } }] },\n\t\tscheduled: {\n\t\t\tand: [NOT_RUNNING, NO_ERROR, NOT_COMPLETED, NOT_TRIED, { waitUntil: { greater_than: at } }],\n\t\t},\n\t\tqueued: {\n\t\t\tand: [\n\t\t\t\tNOT_RUNNING,\n\t\t\t\tNO_ERROR,\n\t\t\t\tNOT_COMPLETED,\n\t\t\t\tNOT_TRIED,\n\t\t\t\t{ or: [{ waitUntil: { exists: false } }, { waitUntil: { less_than_equal: at } }] },\n\t\t\t],\n\t\t},\n\t}\n\treturn clauses[status]\n}\n"],"mappings":";AAsBA,MAAM,eAAe,UACpB,OAAO,UAAU,YACjB,UAAU,QACT,MAAkC,cAAc;;;;;;AAOlD,MAAa,mBAAmB,KAAqB,MAAc,KAAK,IAAI,MAAiB;CAC5F,IAAI,IAAI,eAAe,MACtB,OAAO;CAER,IAAI,IAAI,aAAa,MACpB,OAAO,YAAY,IAAI,KAAK,IAAI,cAAc;CAE/C,IAAI,IAAI,aACP,OAAO;CAER,KAAK,IAAI,cAAc,KAAK,GAC3B,OAAO;CAER,IAAI,IAAI,aAAa,IAAI,KAAK,IAAI,SAAS,EAAE,QAAQ,IAAI,KACxD,OAAO;CAER,OAAO;AACR;AAEA,MAAM,cAAqB,EAAE,YAAY,EAAE,YAAY,KAAK,EAAE;AAC9D,MAAM,WAAkB,EAAE,UAAU,EAAE,QAAQ,MAAM,EAAE;AACtD,MAAM,gBAAuB,EAAE,aAAa,EAAE,QAAQ,MAAM,EAAE;AAC9D,MAAM,YAAmB,EAAE,YAAY,EAAE,QAAQ,EAAE,EAAE;;;;;;;;;AAUrD,MAAa,eAAe,QAAmB,MAAc,KAAK,IAAI,MAAa;CAClF,MAAM,KAAK,IAAI,KAAK,GAAG,EAAE,YAAY;CA8BrC,OAAO;EA5BN,SAAS,EAAE,YAAY,EAAE,QAAQ,KAAK,EAAE;EACxC,WAAW,EACV,KAAK;GAAC;GAAa,EAAE,UAAU,EAAE,QAAQ,KAAK,EAAE;GAAG,EAAE,mBAAmB,EAAE,QAAQ,KAAK,EAAE;EAAC,EAC3F;EACA,QAAQ,EACP,KAAK;GACJ;GACA,EAAE,UAAU,EAAE,QAAQ,KAAK,EAAE;GAC7B,EACC,IAAI,CAAC,EAAE,mBAAmB,EAAE,QAAQ,MAAM,EAAE,GAAG,EAAE,mBAAmB,EAAE,QAAQ,MAAM,EAAE,CAAC,EACxF;EACD,EACD;EACA,WAAW,EAAE,KAAK;GAAC;GAAa;GAAU,EAAE,aAAa,EAAE,QAAQ,KAAK,EAAE;EAAC,EAAE;EAC7E,UAAU,EAAE,KAAK;GAAC;GAAa;GAAU;GAAe,EAAE,YAAY,EAAE,cAAc,EAAE,EAAE;EAAC,EAAE;EAC7F,WAAW,EACV,KAAK;GAAC;GAAa;GAAU;GAAe;GAAW,EAAE,WAAW,EAAE,cAAc,GAAG,EAAE;EAAC,EAC3F;EACA,QAAQ,EACP,KAAK;GACJ;GACA;GACA;GACA;GACA,EAAE,IAAI,CAAC,EAAE,WAAW,EAAE,QAAQ,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,iBAAiB,GAAG,EAAE,CAAC,EAAE;EAClF,EACD;CAEY,EAAE;AAChB"}

package/dist/exports/client.d.ts

@@ -0,0 +1,49 @@
+import { ArrayFieldClientComponent, DefaultCellComponentProps, JSONFieldClientComponent, UIFieldClientComponent } from "payload";
+
+//#region src/jobs/JobDocDescription.d.ts
+/** Document-header description for a job: the record ID, kept accessible and copyable. */
+declare const JobDocDescription: () => import("react/jsx-runtime").JSX.Element | null;
+//#endregion
+//#region src/jobs/JobErrorPanel.d.ts
+/**
+ * Field component for a job's `error`: renders the reason as a read-only panel
+ * instead of raw JSON. Cancellations read neutral; real failures read as errors.
+ */
+declare const JobErrorPanel: JSONFieldClientComponent;
+//#endregion
+//#region src/jobs/JobLogTimeline.d.ts
+/**
+ * Field component for a job's `log`: a read-only per-attempt timeline. Each
+ * attempt collapses to a one-line summary and expands to reveal its full data
+ * (timings, task ID, input, output, error) so nothing is hidden.
+ */
+declare const JobLogTimeline: ArrayFieldClientComponent;
+//#endregion
+//#region src/jobs/JobStatusCell.d.ts
+/**
+ * List cell that renders a job's derived status as a native Payload Pill. On the
+ * linked (first) column it wraps the badge in a link to the document, matching
+ * Payload's default cell behavior.
+ */
+declare const JobStatusCell: ({
+  collectionSlug,
+  link,
+  linkURL,
+  rowData
+}: DefaultCellComponentProps) => import("react/jsx-runtime").JSX.Element;
+//#endregion
+//#region src/jobs/JobStatusHeader.d.ts
+/**
+ * Document header for a job: the derived status as a Pill plus the key facts,
+ * read from the form so it stays in sync. Rendered at the top of the edit view.
+ */
+declare const JobStatusHeader: UIFieldClientComponent;
+//#endregion
+//#region src/jobs/RelativeTimeCell.d.ts
+/** List cell for date fields: relative time, with the admin-formatted timestamp on hover. */
+declare const RelativeTimeCell: ({
+  cellData
+}: DefaultCellComponentProps) => import("react/jsx-runtime").JSX.Element | null;
+//#endregion
+export { JobDocDescription, JobErrorPanel, JobLogTimeline, JobStatusCell, JobStatusHeader, RelativeTimeCell };
+//# sourceMappingURL=client.d.ts.map