@owlmeans/server-job 0.1.18-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OwlMeans Common — Fullstack typescript framework
+
+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,114 @@
+# @owlmeans/server-job
+
+The read side of a queue, as entrypoints an application elevates: list, get, cancel and a socket
+that pushes lifecycle events. Jobs themselves are enqueued and processed through
+[`@owlmeans/queue`](../queue) and its driver — nothing here produces or consumes work.
+
+## Overview
+
+- `declareJobEntrypoints(root, opts?)` — the four declarations, for the app's SHARED package
+- `serveJobEntrypoints(entrypoints, root, opts?)` — elevate them with this package's handlers
+- `listJobs` / `getJob` / `cancelJob` / `watchJobs` — the handlers, when an app elevates by hand
+- A caller sees only the jobs it owns; the escape hatch is an option, not a hardcoded permission
+
+## Installation
+
+```bash
+bun add @owlmeans/server-job@^0.1.18-rc.0
+```
+
+## Usage
+
+Declare the group once, in the package both halves import:
+
+```typescript
+import { declareJobEntrypoints } from '@owlmeans/server-job'
+
+export const REPORTS = 'reports'
+export const entrypoints = [
+  ...declareJobEntrypoints(REPORTS, { path: '/reports/jobs', parent: app.api.base }),
+]
+```
+
+Serve it in the API process, alongside the queue driver it already wires:
+
+```typescript
+import { serveJobEntrypoints } from '@owlmeans/server-job'
+import { appendRedisQueue } from '@owlmeans/redis-queue'
+
+appendRedisQueue(context)
+serveJobEntrypoints(entrypoints, REPORTS, { queue: REPORT_QUEUE })
+context.registerEntrypoints(entrypoints)
+```
+
+Enqueue with the owner in the payload — that is what every read here filters on:
+
+```typescript
+await context.jobs<ReportJob, ReportResult>(REPORT_QUEUE).create({
+  name: 'report:build',
+  data: { owner: req.auth!.profileId ?? req.auth!.userId, target: id },
+})
+```
+
+And report progress from the processor, so there is something to watch:
+
+```typescript
+worker.process(REPORT_QUEUE, 'report:build', async job => {
+  for (const [done, page] of pages.entries()) {
+    await job.touch()
+    await job.progress({ done, total: pages.length })
+    await render(page)
+  }
+  return { url }
+})
+```
+
+## Ownership
+
+`data.owner` (rename it with `ownerField`) is compared against `auth.profileId ?? auth.userId`.
+A job that exists but belongs to someone else answers exactly as an absent one: `UnknownJob`.
+
+An operator console passes a predicate instead of a permission name:
+
+```typescript
+serveJobEntrypoints(entrypoints, REPORTS, {
+  queue: REPORT_QUEUE,
+  admin: req => req.auth?.scopes?.includes('ops') === true,
+})
+```
+
+## The one gotcha
+
+A `JobEvent` carries no owner, so `watchJobs` attributes each frame by reading its job back. A
+queue configured with `removeOnComplete` has nothing left to read when the completion arrives, and
+an unattributable frame is dropped rather than fanned out. Leave completed jobs in place on any
+queue that is watched.
+
+## Depends On
+
+- [`@owlmeans/queue`](../queue) — `ctx.jobs(queue)`, `JobRecord`, `JobEvent`, `UnknownJob`
+- [`@owlmeans/server-api`](../server-api) — `handleRequest` / `handleParams`
+- [`@owlmeans/server-socket`](../server-socket) — `handleConnection`
+- [`@owlmeans/server-entrypoint`](../server-entrypoint) — `elevate`
+- [`@owlmeans/auth-common`](../auth-common) — `DEFAULT_GUARD`
+
+## Related
+
+- [`@owlmeans/client-job`](../client-job) — the browser half that addresses these entrypoints
+- [`@owlmeans/web-panel`](../web-panel) `./jobs` — `JobProgress`, `JobStatus`, `useJobToasts`
+
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded agent skills under `agent-meta/`. After installing your
+`@owlmeans/*` packages, run the OwlMeans agent-skills installer to place them into
+your project's skill store (`.agents/skills/`):
+
+```sh
+npx @owlmeans/agent-skills@^0.1.18-rc.12
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

package/agent-meta/manifest.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 2,
+  "package": "@owlmeans/server-job",
+  "version": "0.1.18-rc.0",
+  "generatedAt": "2026-09-04T22:43:25.448Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "server-job",
+      "category": "package-specific",
+      "file": "skills/server-job/SKILL.md",
+      "canonicalPath": ".agents/skills/server-job/SKILL.md"
+    }
+  ]
+}

package/agent-meta/skills/server-job/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: server-job
+description: How to use @owlmeans/server-job — declaring and elevating the list/get/cancel/watch entrypoints over a queue, the ownership rule that scopes them to the authenticated subject, the admin escape hatch, and the socket that pushes JobEvent frames. Auto-invoked when exposing queue jobs to an application's UI or importing job entrypoint helpers.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/server-job
+
+**Layer:** Server
+**Install:** `"@owlmeans/server-job": "^0.1.18-rc.0"` in `dependencies`
+
+The READ side of a queue. `@owlmeans/queue` and its driver enqueue and process; this package turns
+what they leave behind into four entrypoints an application elevates, so that "a long job reports
+progress to the user's screen" is wiring rather than code.
+
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `declareJobEntrypoints(root, opts?)` | The four declarations of one job group, for the SHARED package |
+| `jobEntrypointAliases(root)` | `{ base, list, get, cancel, watch }` — the alias shape both halves use |
+| `serveJobEntrypoints(entrypoints, root, opts?)` | Elevate the group with this package's handlers |
+| `listJobs(opts?)` / `getJob(opts?)` / `cancelJob(opts?)` | The HTTP handlers, for elevating by hand |
+| `watchJobs(opts?)` | The socket handler — pushes `JobEvent` frames under `JOB_EVENT` |
+| `jobOwnerOf(req)` / `requireJobOwner(req)` / `jobViewer(req, ctx, opts?)` | Who a request reads as |
+| `jobScope(viewer, opts?)` / `owns(record, viewer, opts?)` / `readOwnedJob(...)` | Applying that to records |
+| `ownerFieldOf(opts?)` / `ownerOf(record, opts?)` | The configured owner field, and what one record says its owner is |
+| `jobsOf(ctx, opts?)` | The `QueueResource` a group reads |
+| `JobListQuerySchema` | The list query's ajv schema, for a filter of your own |
+| `JobEntrypointAliases` / `JobEntrypointOptions` / `JobHandlerOptions` / `JobAdminCheck` / `JobListQuery` | The alias and option shapes |
+| Constants | `DEFAULT_JOB_ROOT` (`jobs`), `DEFAULT_JOB_PATH` (`/jobs`), `DEFAULT_OWNER_FIELD` (`owner`), `DEFAULT_JOB_SORT` (`createdAt`), `JOB_EVENT` (`job-event`) |
+
+## Declaring, once, in the shared package
+
+A group is a root alias plus a path. Everything under it is derived, so a target app declares it in
+the package its API and its browser both import, and neither side ever writes a path:
+
+```typescript
+import { declareJobEntrypoints } from '@owlmeans/server-job'
+
+export const REPORTS = 'reports'
+export const entrypoints = [
+  ...declareJobEntrypoints(REPORTS, { path: '/reports/jobs', parent: app.api.base }),
+]
+```
+
+Aliases are `<root>`, `<root>:list`, `<root>:get`, `<root>:cancel`, `<root>:watch`. **That shape,
+and the `job-event` frame name, are the whole contract with `@owlmeans/client-job`** — the two
+packages restate them instead of sharing a module, because this one pulls fastify in and a browser
+bundle must not.
+
+The guard rides on the base alone and the other four inherit it. It defaults to `DEFAULT_GUARD`
+because ownership is derived from the authenticated subject, and an unguarded group has no subject
+to derive it from — `guard: null` is for a group scoped some other way, and its handlers then
+answer `AuthorizationError`. `service` points the group at another app's route; `path` moves it.
+
+`/watch` is declared before `/:id` so the static branch reads first. Declaring a second group is
+the same call with another root.
+
+## Serving
+
+```typescript
+import { serveJobEntrypoints } from '@owlmeans/server-job'
+import { appendRedisQueue } from '@owlmeans/redis-queue'
+
+appendRedisQueue(context)
+serveJobEntrypoints(entrypoints, REPORTS, { queue: REPORT_QUEUE })
+context.registerEntrypoints(entrypoints)
+```
+
+`elevate` replaces in place, so an app wanting one handler of its own elevates that alias again
+afterwards. `queue` names which declared queue the group reads; omitted, `ctx.jobs()` answers with
+the sole declared queue and refuses to guess once there are two. Passing an array that carries no
+group under that root is a `SyntaxError` — the declarations and the serving call must name the same
+root, and they usually do because both read it from one exported constant.
+
+## The ownership rule
+
+**A caller sees only the jobs it owns**, and ownership lives in the job's own payload — a
+`JobRecord` has no owner column, so the producer writes it:
+
+```typescript
+await context.jobs(REPORT_QUEUE).create({
+  name: 'report:build',
+  data: { owner: req.auth!.profileId ?? req.auth!.userId, target: id },
+})
+```
+
+Reads filter on `data.owner` (`ownerField` renames it) against `auth.profileId ?? auth.userId` —
+profile first, the same subject `@owlmeans/server-socket` addresses a connection by, so one profile
+of a multi-profile account does not see another's work.
+
+A job that exists but belongs to someone else answers **`UnknownJob`, exactly as an absent one
+does**. Telling the two apart is what turns a broker id space into an enumeration oracle.
+
+The escape hatch is a predicate, never a permission name — which permission, gate or role means
+"operator" is the application's decision:
+
+```typescript
+serveJobEntrypoints(entrypoints, REPORTS, {
+  queue: REPORT_QUEUE,
+  admin: req => req.auth?.scopes?.includes('ops') === true,
+})
+```
+
+Absent an `admin` check every read is scoped and an anonymous request is refused, so a group wired
+with no options at all is closed rather than open.
+
+## What each handler answers
+
+| Alias | Method | Answers |
+|---|---|---|
+| `<root>:list` | GET `/` | `ListResult<JobRecord>`, newest first by `createdAt`. `state`, `name`, `page`, `size` in the query. Paging is opt-in and driven by `size` (1–200): without one the whole scoped list comes back and a `page` alone counts for nothing, since a broker has no default page size. `state` and `name` are plain strings, so a driver state this package does not know still narrows the list |
+| `<root>:get` | GET `/:id` | One `JobRecord`, or `UnknownJob` |
+| `<root>:cancel` | DELETE `/:id` | The record that was removed. Cancellation IS deletion in the queue contract; it does not interrupt a processor mid-run |
+| `<root>:watch` | SOCKET `/watch` | `JobEvent` frames under `job-event`, as the queue publishes them. The subscription is released on the socket's system `close` frame, so a dropped browser stops the queue subscription behind it |
+
+## The one gotcha
+
+**A `JobEvent` carries no owner.** `watchJobs` attributes each frame by reading its job back and
+remembers the ids that answered for the life of the connection. A queue configured with
+`removeOnComplete` therefore loses its completion events here — the record they would be
+attributed by is gone by the time the event arrives, and an unattributable frame is dropped rather
+than fanned out to everyone. **Leave completed jobs in place on any queue that is watched.**
+
+## Depends On
+
+- `@owlmeans/queue` — `ctx.jobs(queue)`, `JobRecord`, `JobEvent`, `JobState`, `UnknownJob`
+- `@owlmeans/server-api` — `handleRequest`, `handleParams`
+- `@owlmeans/server-socket` — `handleConnection`, and the guard enforcement that fills `req.auth`
+- `@owlmeans/server-entrypoint` — `elevate`
+- `@owlmeans/auth-common` — `DEFAULT_GUARD`
+
+## Related
+
+- `queue` — declaring queues, writing processors, and `job.progress()` (there is nothing to watch
+  without it)
+- `redis-queue` — the driver, its shutdown rule and its retention options
+- `client-job` — the browser half; `web-panel` — `./jobs` renders what it collects

package/build/actions/cancel.d.ts

@@ -0,0 +1,15 @@
+import type { AbstractResponse } from '@owlmeans/entrypoint';
+import type { RefedEntrypointHandler } from '@owlmeans/server-entrypoint';
+import type { JobHandlerOptions } from '../types.js';
+/**
+ * Cancel a job and answer with what was cancelled.
+ *
+ * Cancellation IS deletion in the queue contract — the job and its children leave the broker — so
+ * a job already finished cancels to its final record and one already gone answers `UnknownJob`.
+ * Nothing here interrupts a processor that is mid-run; a job holding a lock keeps it until the
+ * processor notices its own `signal`.
+ *
+ * @throws {UnknownJob}
+ */
+export declare const cancelJob: (opts?: JobHandlerOptions) => RefedEntrypointHandler<AbstractResponse<any>>;
+//# sourceMappingURL=cancel.d.ts.map

package/build/actions/cancel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cancel.d.ts","sourceRoot":"","sources":["../../src/actions/cancel.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAA;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAGpD;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS,UACb,iBAAiB,KACvB,sBAAsB,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAO3C,CAAA"}

package/build/actions/cancel.js

@@ -0,0 +1,19 @@
+import { handleParams } from '@owlmeans/server-api';
+import { jobViewer, jobsOf, readOwnedJob } from '../utils/index.js';
+/**
+ * Cancel a job and answer with what was cancelled.
+ *
+ * Cancellation IS deletion in the queue contract — the job and its children leave the broker — so
+ * a job already finished cancels to its final record and one already gone answers `UnknownJob`.
+ * Nothing here interrupts a processor that is mid-run; a job holding a lock keeps it until the
+ * processor notices its own `signal`.
+ *
+ * @throws {UnknownJob}
+ */
+export const cancelJob = (opts) => handleParams(async ({ id }, ctx, req) => {
+    const resource = jobsOf(ctx, opts);
+    // Read first: `take` cannot tell whose job it removed, so ownership is settled before it.
+    await readOwnedJob(resource, id, await jobViewer(req, ctx, opts), opts);
+    return await resource.take(id);
+});
+//# sourceMappingURL=cancel.js.map

package/build/actions/cancel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cancel.js","sourceRoot":"","sources":["../../src/actions/cancel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAInD,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAEnE;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CACvB,IAAwB,EACuB,EAAE,CACjD,YAAY,CAAiB,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;IACtD,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;IAClC,0FAA0F;IAC1F,MAAM,YAAY,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,CAAA;IAEvE,OAAO,MAAM,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;AAChC,CAAC,CAAC,CAAA"}

package/build/actions/get.d.ts

@@ -0,0 +1,10 @@
+import type { AbstractResponse } from '@owlmeans/entrypoint';
+import type { RefedEntrypointHandler } from '@owlmeans/server-entrypoint';
+import type { JobHandlerOptions } from '../types.js';
+/**
+ * One job.
+ *
+ * @throws {UnknownJob} for an id that is absent AND for one that belongs to someone else.
+ */
+export declare const getJob: (opts?: JobHandlerOptions) => RefedEntrypointHandler<AbstractResponse<any>>;
+//# sourceMappingURL=get.d.ts.map

package/build/actions/get.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get.d.ts","sourceRoot":"","sources":["../../src/actions/get.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAA;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAGpD;;;;GAIG;AACH,eAAO,MAAM,MAAM,UACV,iBAAiB,KACvB,sBAAsB,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAK3C,CAAA"}

package/build/actions/get.js

@@ -0,0 +1,12 @@
+import { handleParams } from '@owlmeans/server-api';
+import { jobViewer, jobsOf, readOwnedJob } from '../utils/index.js';
+/**
+ * One job.
+ *
+ * @throws {UnknownJob} for an id that is absent AND for one that belongs to someone else.
+ */
+export const getJob = (opts) => handleParams(async ({ id }, ctx, req) => {
+    const resource = jobsOf(ctx, opts);
+    return await readOwnedJob(resource, id, await jobViewer(req, ctx, opts), opts);
+});
+//# sourceMappingURL=get.js.map

package/build/actions/get.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get.js","sourceRoot":"","sources":["../../src/actions/get.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAInD,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAEnE;;;;GAIG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CACpB,IAAwB,EACuB,EAAE,CACjD,YAAY,CAAiB,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;IACtD,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;IAElC,OAAO,MAAM,YAAY,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,CAAA;AAChF,CAAC,CAAC,CAAA"}

package/build/actions/index.d.ts

@@ -0,0 +1,5 @@
+export * from './list.js';
+export * from './get.js';
+export * from './cancel.js';
+export * from './watch.js';
+//# sourceMappingURL=index.d.ts.map

package/build/actions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/actions/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA;AACzB,cAAc,UAAU,CAAA;AACxB,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA"}

package/build/actions/index.js

@@ -0,0 +1,5 @@
+export * from './list.js';
+export * from './get.js';
+export * from './cancel.js';
+export * from './watch.js';
+//# sourceMappingURL=index.js.map

package/build/actions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/actions/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA;AACzB,cAAc,UAAU,CAAA;AACxB,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA"}

package/build/actions/list.d.ts

@@ -0,0 +1,13 @@
+import type { AbstractResponse } from '@owlmeans/entrypoint';
+import type { RefedEntrypointHandler } from '@owlmeans/server-entrypoint';
+import type { JobHandlerOptions } from '../types.js';
+/**
+ * The caller's jobs, newest first.
+ *
+ * Paging is opt-in: a `page` without a `size` is refused by the queue resource rather than
+ * silently windowed, because a broker has no default page size to count against. The state and
+ * name filters go through the same criteria language as every other resource, so a filter written
+ * for this list means the same thing applied to the store the browser holds.
+ */
+export declare const listJobs: (opts?: JobHandlerOptions) => RefedEntrypointHandler<AbstractResponse<any>>;
+//# sourceMappingURL=list.d.ts.map

package/build/actions/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/actions/list.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAA;AAKzE,OAAO,KAAK,EAAE,iBAAiB,EAAgB,MAAM,aAAa,CAAA;AAGlE;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,UACZ,iBAAiB,KACvB,sBAAsB,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAe7C,CAAA"}

package/build/actions/list.js

@@ -0,0 +1,26 @@
+import { handleRequest } from '@owlmeans/server-api';
+import { DEFAULT_JOB_SORT } from '../consts.js';
+import { jobScope, jobViewer, jobsOf } from '../utils/index.js';
+/**
+ * The caller's jobs, newest first.
+ *
+ * Paging is opt-in: a `page` without a `size` is refused by the queue resource rather than
+ * silently windowed, because a broker has no default page size to count against. The state and
+ * name filters go through the same criteria language as every other resource, so a filter written
+ * for this list means the same thing applied to the store the browser holds.
+ */
+export const listJobs = (opts) => handleRequest(async (req, ctx) => {
+    const resource = jobsOf(ctx, opts);
+    const viewer = await jobViewer(req, ctx, opts);
+    const query = (req.query ?? {});
+    const where = {
+        ...jobScope(viewer, opts),
+        ...(query.state != null ? { state: query.state } : {}),
+        ...(query.name != null ? { name: query.name } : {}),
+    };
+    return await resource.list(where, {
+        sort: [{ field: DEFAULT_JOB_SORT, order: 'desc' }],
+        ...(query.size != null ? { size: query.size, page: query.page ?? 0 } : {}),
+    });
+});
+//# sourceMappingURL=list.js.map

package/build/actions/list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../../src/actions/list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAMpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAE/C,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAE/D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CACtB,IAAwB,EACuB,EAAE,CAAC,aAAa,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;IACnF,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;IAClC,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAA;IAC9C,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAiB,CAAA;IAE/C,MAAM,KAAK,GAAwB;QACjC,GAAG,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;QACzB,GAAG,CAAC,KAAK,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClE,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpD,CAAA;IAED,OAAO,MAAM,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE;QAChC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAClD,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC3E,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/build/actions/watch.d.ts

@@ -0,0 +1,17 @@
+import type { AbstractResponse } from '@owlmeans/entrypoint';
+import type { RefedEntrypointHandler } from '@owlmeans/server-entrypoint';
+import type { JobHandlerOptions } from '../types.js';
+/**
+ * Push this caller's job lifecycle events down a socket.
+ *
+ * The frames are `JobEvent`s exactly as the queue publishes them, under the {@link JOB_EVENT}
+ * event name — no shape of this package's own, so a client applies them with the contract types.
+ *
+ * **A `JobEvent` carries no owner**, so each one is attributed by reading its job back, and the
+ * ids that answered are remembered for the life of the connection. A queue configured with
+ * `removeOnComplete` therefore loses its completion events here: the record they would be
+ * attributed by is gone by the time the event arrives, and an unattributable event is dropped
+ * rather than fanned out to everyone. Leave completed jobs in place on any queue that is watched.
+ */
+export declare const watchJobs: (opts?: JobHandlerOptions) => RefedEntrypointHandler<AbstractResponse<any>>;
+//# sourceMappingURL=watch.d.ts.map

package/build/actions/watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../../src/actions/watch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAA;AAKzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAGpD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,SAAS,UACb,iBAAiB,KACvB,sBAAsB,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAyC7C,CAAA"}

package/build/actions/watch.js

@@ -0,0 +1,57 @@
+import { handleConnection } from '@owlmeans/server-socket';
+import { MessageType } from '@owlmeans/socket';
+import { JOB_EVENT } from '../consts.js';
+import { jobViewer, jobsOf, owns } from '../utils/index.js';
+/**
+ * Push this caller's job lifecycle events down a socket.
+ *
+ * The frames are `JobEvent`s exactly as the queue publishes them, under the {@link JOB_EVENT}
+ * event name — no shape of this package's own, so a client applies them with the contract types.
+ *
+ * **A `JobEvent` carries no owner**, so each one is attributed by reading its job back, and the
+ * ids that answered are remembered for the life of the connection. A queue configured with
+ * `removeOnComplete` therefore loses its completion events here: the record they would be
+ * attributed by is gone by the time the event arrives, and an unattributable event is dropped
+ * rather than fanned out to everyone. Leave completed jobs in place on any queue that is watched.
+ */
+export const watchJobs = (opts) => handleConnection(async (conn, ctx, req) => {
+    const resource = jobsOf(ctx, opts);
+    const viewer = await jobViewer(req, ctx, opts);
+    const mine = new Set();
+    const attributable = async (event) => {
+        if (viewer == null || mine.has(event.id)) {
+            return true;
+        }
+        const record = await resource.load(event.id);
+        if (record == null || !owns(record, viewer, opts)) {
+            return false;
+        }
+        mine.add(event.id);
+        return true;
+    };
+    const unsubscribe = await resource.subscribe(async (event) => {
+        try {
+            if (await attributable(event)) {
+                await conn.notify(JOB_EVENT, event);
+            }
+        }
+        catch (e) {
+            console.error('Job watch notify error:', e);
+        }
+    });
+    conn.listen(async (message) => {
+        if (typeof message !== 'object') {
+            return;
+        }
+        const msg = message;
+        if (msg.type === MessageType.System && msg.event === 'close') {
+            try {
+                await unsubscribe();
+            }
+            catch (e) {
+                console.error('Job watch unsubscribe error:', e);
+            }
+        }
+    });
+});
+//# sourceMappingURL=watch.js.map

package/build/actions/watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.js","sourceRoot":"","sources":["../../src/actions/watch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAI1D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE9C,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAExC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAA;AAE3D;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CACvB,IAAwB,EACuB,EAAE,CAAC,gBAAgB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;IAC5F,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;IAClC,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAA;IAC9C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAE9B,MAAM,YAAY,GAAG,KAAK,EAAE,KAAe,EAAoB,EAAE;QAC/D,IAAI,MAAM,IAAI,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;YACzC,OAAO,IAAI,CAAA;QACb,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;QAC5C,IAAI,MAAM,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC;YAClD,OAAO,KAAK,CAAA;QACd,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;QAElB,OAAO,IAAI,CAAA;IACb,CAAC,CAAA;IAED,MAAM,WAAW,GAAG,MAAM,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAC,KAAK,EAAC,EAAE;QACzD,IAAI,CAAC;YACH,IAAI,MAAM,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC9B,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,CAAA;YACrC,CAAC;QACH,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,CAAC,CAAC,CAAA;QAC7C,CAAC;IACH,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,MAAM,CAAC,KAAK,EAAC,OAAO,EAAC,EAAE;QAC1B,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAChC,OAAM;QACR,CAAC;QACD,MAAM,GAAG,GAAG,OAA6B,CAAA;QACzC,IAAI,GAAG,CAAC,IAAI,KAAK,WAAW,CAAC,MAAM,IAAI,GAAG,CAAC,KAAK,KAAK,OAAO,EAAE,CAAC;YAC7D,IAAI,CAAC;gBACH,MAAM,WAAW,EAAE,CAAA;YACrB,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,OAAO,CAAC,KAAK,CAAC,8BAA8B,EAAE,CAAC,CAAC,CAAA;YAClD,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/build/consts.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The alias root a target app gets when its declaration names none, and the path segment the
+ * group answers under.
+ */
+export declare const DEFAULT_JOB_ROOT = "jobs";
+export declare const DEFAULT_JOB_PATH = "/jobs";
+/**
+ * Where the owner is recorded inside a job's payload.
+ *
+ * A `JobRecord` has no owner column — the broker keeps only what the contract declares — so the
+ * producer writes the subject into the job's own `data`, and every read here filters on
+ * `data.<field>`. Change it per declaration when the app's payloads already name the subject
+ * something else.
+ */
+export declare const DEFAULT_OWNER_FIELD = "owner";
+/**
+ * The socket event a `JobEvent` frame is pushed under.
+ *
+ * This name, and the `<root>:<verb>` alias shape in `entrypoints.ts`, are the whole contract
+ * between this package and `@owlmeans/client-job` — the two halves cannot share a module without
+ * dragging fastify into a browser bundle, so they each state it and the skills pin it.
+ */
+export declare const JOB_EVENT = "job-event";
+/** Newest first: a job list is read to see what is happening now. */
+export declare const DEFAULT_JOB_SORT = "createdAt";
+//# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,gBAAgB,SAAS,CAAA;AACtC,eAAO,MAAM,gBAAgB,UAAU,CAAA;AAEvC;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,UAAU,CAAA;AAE1C;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,cAAc,CAAA;AAEpC,qEAAqE;AACrE,eAAO,MAAM,gBAAgB,cAAc,CAAA"}

package/build/consts.js

@@ -0,0 +1,26 @@
+/**
+ * The alias root a target app gets when its declaration names none, and the path segment the
+ * group answers under.
+ */
+export const DEFAULT_JOB_ROOT = 'jobs';
+export const DEFAULT_JOB_PATH = '/jobs';
+/**
+ * Where the owner is recorded inside a job's payload.
+ *
+ * A `JobRecord` has no owner column — the broker keeps only what the contract declares — so the
+ * producer writes the subject into the job's own `data`, and every read here filters on
+ * `data.<field>`. Change it per declaration when the app's payloads already name the subject
+ * something else.
+ */
+export const DEFAULT_OWNER_FIELD = 'owner';
+/**
+ * The socket event a `JobEvent` frame is pushed under.
+ *
+ * This name, and the `<root>:<verb>` alias shape in `entrypoints.ts`, are the whole contract
+ * between this package and `@owlmeans/client-job` — the two halves cannot share a module without
+ * dragging fastify into a browser bundle, so they each state it and the skills pin it.
+ */
+export const JOB_EVENT = 'job-event';
+/** Newest first: a job list is read to see what is happening now. */
+export const DEFAULT_JOB_SORT = 'createdAt';
+//# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAA;AACtC,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAA;AAEvC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAA;AAE1C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,WAAW,CAAA;AAEpC,qEAAqE;AACrE,MAAM,CAAC,MAAM,gBAAgB,GAAG,WAAW,CAAA"}

package/build/entrypoints.d.ts

@@ -0,0 +1,21 @@
+import type { CommonEntrypoint } from '@owlmeans/entrypoint';
+import type { JobEntrypointAliases, JobEntrypointOptions } from './types.js';
+/**
+ * The aliases one job group answers under.
+ *
+ * The shape — `<root>` and `<root>:<verb>` — is the contract `@owlmeans/client-job` addresses the
+ * same group by, so a group renamed here is renamed there by passing the same root.
+ */
+export declare const jobEntrypointAliases: (root: string) => JobEntrypointAliases;
+/**
+ * Declare the list/get/cancel/watch entrypoints of one job group.
+ *
+ * It belongs in the SHARED package of a target app — the one both the API and the browser import —
+ * so that the server elevates and the client calls the very declarations, and neither side ever
+ * writes a path. Declaring a second group is the same call with another root.
+ *
+ * The guard rides on the base alone: guards are inherited, so stating it once is what keeps the
+ * four from drifting apart.
+ */
+export declare const declareJobEntrypoints: (root: string, opts?: JobEntrypointOptions) => CommonEntrypoint[];
+//# sourceMappingURL=entrypoints.d.ts.map

package/build/entrypoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entrypoints.d.ts","sourceRoot":"","sources":["../src/entrypoints.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAM5D,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAE5E;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,SAAU,MAAM,KAAG,oBAMlD,CAAA;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,SAC1B,MAAM,SAAS,oBAAoB,KACxC,gBAAgB,EAoBlB,CAAA"}