@zizq-labs/zizq 0.1.0

package/dist/client.js

@@ -0,0 +1,902 @@
+// Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+// Licensed under the MIT License. See LICENSE file for details.
+/**
+ * Low-level HTTP client for the Zizq job queue server.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { Client } from "@zizq-labs/zizq";
+ *
+ * const client = new Client({ url: "http://localhost:7890" });
+ *
+ * // Enqueue a job
+ * const job = await client.enqueue({
+ *   type: "send_email",
+ *   queue: "emails",
+ *   payload: { to: "user@example.com", subject: "Hello" },
+ * });
+ * console.log(job.id); // "03fvqh..."
+ *
+ * // Take and process jobs (streaming)
+ * for await (const job of client.take({ prefetch: 5, queues: ["emails"] })) {
+ *   try {
+ *     await processJob(job);
+ *     await client.reportSuccess(job.id);
+ *   } catch (err) {
+ *     await client.reportFailure(job.id, { message: err.message });
+ *   }
+ * }
+ *
+ * await client.close();
+ * ```
+ *
+ * @module
+ */
+import { Pool } from "undici";
+import { encode as msgpackEncode, decode as msgpackDecode } from "@msgpack/msgpack";
+import { Job, JobPage, ErrorRecord, ErrorPage } from "./resources.js";
+import { JobQuery } from "./query.js";
+// Re-export resource types so consumers can import from client.ts.
+export { Job, JobPage, ErrorRecord, ErrorPage } from "./resources.js";
+/** Base error class for all Zizq errors. */
+export class ZizqError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ZizqError";
+    }
+}
+/**
+ * Network-level failure (connection refused, DNS, timeout, etc.).
+ *
+ * These are always transient and safe to retry.
+ */
+export class ConnectionError extends ZizqError {
+    constructor(message) {
+        super(message);
+        this.name = "ConnectionError";
+    }
+}
+/**
+ * HTTP error — the server returned a non-success status code.
+ *
+ * Carries the HTTP status code and (when available) the parsed response
+ * body, which typically contains an `error` field with a human-readable
+ * message from the server.
+ */
+export class ResponseError extends ZizqError {
+    /** HTTP status code from the server. */
+    status;
+    /** Parsed response body, if available. */
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.name = "ResponseError";
+        this.status = status;
+        this.body = body;
+    }
+}
+/** 4xx client error — the request was invalid. Not retryable. */
+export class ClientError extends ResponseError {
+    constructor(message, status, body) {
+        super(message, status, body);
+        this.name = "ClientError";
+    }
+}
+/** 404 specifically — job not found, etc. */
+export class NotFoundError extends ClientError {
+    constructor(message, body) {
+        super(message, 404, body);
+        this.name = "NotFoundError";
+    }
+}
+/** 5xx server error — something went wrong on the server. Retryable. */
+export class ServerError extends ResponseError {
+    constructor(message, status, body) {
+        super(message, status, body);
+        this.name = "ServerError";
+    }
+}
+/** Content-type headers for each format. */
+const CONTENT_TYPES = {
+    json: "application/json",
+    msgpack: "application/msgpack",
+};
+/** Accept headers for the streaming take endpoint. */
+const STREAM_ACCEPT = {
+    json: "application/x-ndjson",
+    msgpack: "application/vnd.zizq.msgpack-stream",
+};
+/**
+ * Low-level HTTP client for the Zizq job queue server.
+ *
+ * Maintains a persistent connection (HTTP/2 when available) for efficient
+ * request multiplexing. All methods map directly to server API endpoints.
+ *
+ * Call {@link close} when done to wait for in-flight requests to complete and
+ * release the underlying connection.
+ *
+ * @example
+ * ```ts
+ * const client = new Client({ url: "http://localhost:7890" });
+ *
+ * const job = await client.enqueue({
+ *   type: "send_email",
+ *   queue: "emails",
+ *   payload: { to: "user@example.com" },
+ * });
+ *
+ * await client.close();
+ * ```
+ */
+export class Client {
+    /** Pool for request/response traffic (enqueue, ack, failure, get). */
+    http;
+    /** Separate pool for long-lived streaming connections (take). */
+    streamHttp;
+    /** The base URL of the Zizq server. */
+    url;
+    /** Serialization format. */
+    format;
+    /** Content-type for requests. */
+    contentType;
+    /** Accept header for request/response endpoints. */
+    accept;
+    /** Accept header for the streaming take endpoint. */
+    streamAccept;
+    constructor(options) {
+        this.url = options.url.replace(/\/+$/, "");
+        this.format = options.format ?? "json";
+        this.contentType = CONTENT_TYPES[this.format];
+        this.accept = CONTENT_TYPES[this.format];
+        this.streamAccept = STREAM_ACCEPT[this.format];
+        if (options.dispatcher) {
+            // Testing: use the same dispatcher for both.
+            this.http = options.dispatcher;
+            this.streamHttp = options.dispatcher;
+        }
+        else {
+            const connectOpts = options.tls ? {
+                ca: options.tls.ca,
+                cert: options.tls.cert,
+                key: options.tls.key,
+            } : undefined;
+            // HTTP/2 for request/response traffic (multiplexed acks, enqueues).
+            this.http = new Pool(this.url, {
+                allowH2: true,
+                connect: connectOpts,
+            });
+            // HTTP/1.1 for the long-lived take stream. HTTP/2 adds framing
+            // overhead and flow control with no multiplexing benefit on a
+            // single long-lived response, resulting in measurably lower
+            // throughput compared to HTTP/1.1 chunked transfer.
+            this.streamHttp = new Pool(this.url, {
+                allowH2: false,
+                connect: connectOpts,
+            });
+        }
+    }
+    /**
+     * Enqueue a single job.
+     *
+     * @returns The created job, including its server-assigned `id` and `status`.
+     * @throws {ZizqError} If the server rejects the request (e.g. invalid queue name).
+     *
+     * @example
+     * ```ts
+     * const job = await client.enqueue({
+     *   type: "send_email",
+     *   queue: "emails",
+     *   payload: { to: "user@example.com" },
+     * });
+     * ```
+     */
+    async enqueue(options) {
+        const api = enqueueToApi(options);
+        return this.wrapJob(await this.handleResponse(await this.post("/jobs", api)));
+    }
+    /**
+     * Enqueue multiple jobs in a single request.
+     *
+     * @returns An array of created jobs in the same order as the input.
+     *
+     * @example
+     * ```ts
+     * const jobs = await client.enqueueBulk([
+     *   { type: "send_email", queue: "emails", payload: { to: "a@b.com" } },
+     *   { type: "send_email", queue: "emails", payload: { to: "c@d.com" } },
+     * ]);
+     * ```
+     */
+    async enqueueBulk(jobs) {
+        const api = { jobs: jobs.map(enqueueToApi) };
+        const data = await this.handleResponse(await this.post("/jobs/bulk", api));
+        return data.jobs.map((j) => this.wrapJob(j));
+    }
+    /**
+     * Acknowledge a job as successfully completed.
+     *
+     * @param id - The job ID to acknowledge.
+     * @throws {ZizqError} If the job is not found or not in-flight.
+     */
+    async reportSuccess(id) {
+        const res = await this.request("POST", `/jobs/${encodeURIComponent(id)}/success`);
+        if (res.statusCode !== 204) {
+            await this.throwOnError(res);
+        }
+    }
+    /**
+     * Acknowledge multiple jobs as successfully completed in a single request.
+     *
+     * Jobs that have already been acknowledged or that don't exist are
+     * silently ignored (the server returns 422 but the client treats it
+     * as success).
+     *
+     * @param ids - Array of job IDs to acknowledge.
+     */
+    async reportSuccessBulk(ids) {
+        const res = await this.post("/jobs/success", { ids });
+        // 204 = all found, 422 = some not found (still accepted).
+        if (res.statusCode !== 204 && res.statusCode !== 422) {
+            await this.throwOnError(res);
+        }
+    }
+    /**
+     * Report a job as failed.
+     *
+     * The server will either reschedule the job with backoff or move it to
+     * the dead list if the retry limit has been exceeded.
+     *
+     * @param id - The job ID to report failure for.
+     * @param options - Error details (message, stack trace, etc.).
+     * @returns The updated job with its new status and attempt count.
+     */
+    async reportFailure(id, options) {
+        const api = failureToApi(options);
+        return this.wrapJob(await this.handleResponse(await this.post(`/jobs/${encodeURIComponent(id)}/failure`, api)));
+    }
+    /**
+     * Fetch a single job by ID.
+     *
+     * @param id - The job ID to fetch.
+     * @returns The full job data including payload.
+     * @throws {ZizqError} If the job is not found (404).
+     */
+    async getJob(id) {
+        return this.wrapJob(await this.handleResponse(await this.request("GET", `/jobs/${encodeURIComponent(id)}`)));
+    }
+    /**
+     * Delete a single job by ID.
+     *
+     * @param id - The job ID to delete.
+     * @throws {NotFoundError} If the job is not found.
+     */
+    async deleteJob(id) {
+        const res = await this.request("DELETE", `/jobs/${encodeURIComponent(id)}`);
+        if (res.statusCode !== 204) {
+            await this.throwOnError(res);
+        }
+    }
+    /**
+     * Delete jobs matching the given filters.
+     *
+     * An empty options object deletes all jobs.
+     *
+     * @returns The number of deleted jobs.
+     *
+     * @example
+     * ```ts
+     * const count = await client.deleteAllJobs({ queue: "emails", status: "dead" });
+     * ```
+     */
+    async deleteAllJobs(options = {}) {
+        assertOnlyKeys("deleteAllJobs", options, ["where"]);
+        const where = options.where ?? {};
+        assertOnlyKeys("deleteAllJobs.where", where, ["id", "status", "queue", "type", "filter"]);
+        // Build the multi-value filters first so we can short-circuit if any
+        // resolves to an empty string. An empty filter matches nothing — we
+        // don't want to pass it as "no filter" and accidentally delete everything.
+        const id = where.id != null ? toCommaList(where.id) : undefined;
+        const status = where.status != null ? toCommaList(where.status) : undefined;
+        const queue = where.queue != null ? toCommaList(where.queue) : undefined;
+        const type = where.type != null ? toCommaList(where.type) : undefined;
+        if (id === "" || status === "" || queue === "" || type === "")
+            return 0;
+        const params = new URLSearchParams();
+        if (id != null)
+            params.set("id", id);
+        if (status != null)
+            params.set("status", status);
+        if (queue != null)
+            params.set("queue", queue);
+        if (type != null)
+            params.set("type", type);
+        if (where.filter != null)
+            params.set("filter", where.filter);
+        const qs = params.toString();
+        const path = `/jobs${qs ? "?" + qs : ""}`;
+        const data = await this.handleResponse(await this.request("DELETE", path));
+        return data.deleted;
+    }
+    /**
+     * Update a single job's mutable fields.
+     *
+     * Field semantics:
+     * - **omitted or `undefined`** — leave unchanged
+     * - **`null`** — clear the field (only valid for nullable fields)
+     * - **a value** — update to that value
+     *
+     * @param id - The job ID to update.
+     * @param options - Fields to update.
+     * @returns The updated job.
+     * @throws {NotFoundError} If the job is not found.
+     *
+     * @example
+     * ```ts
+     * // Change priority and clear the retry limit
+     * await client.updateJob("job-id", {
+     *   priority: 100,
+     *   retryLimit: null,
+     * });
+     * ```
+     */
+    async updateJob(id, options) {
+        const api = updateToApi(options);
+        return this.wrapJob(await this.handleResponse(await this.patch(`/jobs/${encodeURIComponent(id)}`, api)));
+    }
+    /**
+     * Bulk update jobs matching a filter.
+     *
+     * @returns The number of updated jobs.
+     *
+     * @example
+     * ```ts
+     * const count = await client.updateAllJobs({
+     *   where: { queue: "emails", status: "ready" },
+     *   apply: { priority: 1000 },
+     * });
+     * ```
+     */
+    async updateAllJobs(options) {
+        assertOnlyKeys("updateAllJobs", options, ["where", "apply"]);
+        const where = options.where ?? {};
+        assertOnlyKeys("updateAllJobs.where", where, ["id", "status", "queue", "type", "filter"]);
+        // Same empty-filter short-circuit as deleteAllJobs.
+        const id = where.id != null ? toCommaList(where.id) : undefined;
+        const status = where.status != null ? toCommaList(where.status) : undefined;
+        const queue = where.queue != null ? toCommaList(where.queue) : undefined;
+        const type = where.type != null ? toCommaList(where.type) : undefined;
+        if (id === "" || status === "" || queue === "" || type === "")
+            return 0;
+        const params = new URLSearchParams();
+        if (id != null)
+            params.set("id", id);
+        if (status != null)
+            params.set("status", status);
+        if (queue != null)
+            params.set("queue", queue);
+        if (type != null)
+            params.set("type", type);
+        if (where.filter != null)
+            params.set("filter", where.filter);
+        const qs = params.toString();
+        const path = `/jobs${qs ? "?" + qs : ""}`;
+        const api = updateToApi(options.apply);
+        const data = await this.handleResponse(await this.patch(path, api));
+        return data.patched;
+    }
+    /**
+     * List jobs with cursor-based pagination.
+     *
+     * Returns a single page of jobs. Use `page.nextPage()` and
+     * `page.prevPage()` to navigate between pages.
+     *
+     * @example
+     * ```ts
+     * const page = await client.listJobs({ queue: ["emails"], limit: 10 });
+     * for (const job of page.jobs) {
+     *   console.log(job.id, job.status);
+     * }
+     * if (page.hasNext) {
+     *   const next = await page.nextPage();
+     * }
+     * ```
+     */
+    async listJobs(options = {}) {
+        const params = new URLSearchParams();
+        if (options.from != null)
+            params.set("from", options.from);
+        if (options.order != null)
+            params.set("order", options.order);
+        if (options.limit != null)
+            params.set("limit", String(options.limit));
+        if (options.status)
+            params.set("status", toCommaList(options.status));
+        if (options.queue)
+            params.set("queue", toCommaList(options.queue));
+        if (options.type)
+            params.set("type", toCommaList(options.type));
+        if (options.id)
+            params.set("id", toCommaList(options.id));
+        if (options.filter != null)
+            params.set("filter", options.filter);
+        const qs = params.toString();
+        const path = `/jobs${qs ? "?" + qs : ""}`;
+        return this.listJobsByPath(path);
+    }
+    /**
+     * Fetch a page of jobs by a raw path (used internally for pagination links).
+     *
+     * @internal
+     */
+    async listJobsByPath(path) {
+        const data = await this.handleResponse(await this.request("GET", path));
+        const jobs = data.jobs.map((j) => this.wrapJob(j));
+        return new JobPage(this, jobs, data.pages);
+    }
+    /**
+     * Health check.
+     *
+     * @returns The parsed response body, e.g. `{ status: "ok" }`.
+     */
+    async health() {
+        return await this.handleResponse(await this.request("GET", "/health"));
+    }
+    /**
+     * Server version.
+     *
+     * @returns The server's version string.
+     */
+    async serverVersion() {
+        const data = await this.handleResponse(await this.request("GET", "/version"));
+        return data.version;
+    }
+    /**
+     * Start a composable, lazy query over jobs.
+     *
+     * Returns a {@link JobQuery} that can be chained with filter and
+     * ordering methods, then iterated or used with terminal methods like
+     * `first()`, `toArray()`, `updateAll()`, and `deleteAll()`.
+     *
+     * No HTTP request is made until the query is consumed.
+     *
+     * Accepts an optional {@link JobQueryOptions} to seed the query's initial
+     * filter, order, limit, and page size — handy as a shorthand for
+     * `client.jobs().byQueue(...).limit(...)` etc.
+     *
+     * @example
+     * ```ts
+     * const dead = await client.jobs()
+     *   .byQueue("emails")
+     *   .byStatus("dead")
+     *   .toArray();
+     *
+     * // Shorthand with seeded options
+     * const ready = await client.jobs({ queue: "emails", status: "ready" }).toArray();
+     *
+     * for await (const job of client.jobs().byStatus("ready")) {
+     *   console.log(job.id);
+     * }
+     * ```
+     */
+    jobs(options) {
+        return new JobQuery(this, options);
+    }
+    /**
+     * List all distinct queue names on the server.
+     *
+     * @returns An array of queue name strings, sorted alphabetically.
+     */
+    async queues() {
+        const data = await this.handleResponse(await this.request("GET", "/queues"));
+        return data.queues;
+    }
+    /**
+     * List error records for a job with cursor-based pagination.
+     *
+     * @param id - The job ID to list errors for.
+     * @param options - Pagination and ordering options.
+     *
+     * @example
+     * ```ts
+     * const page = await client.listErrors("job-id", { order: "desc" });
+     * for (const error of page) {
+     *   console.log(`Attempt ${error.attempt}: ${error.message}`);
+     * }
+     * ```
+     */
+    async listErrors(id, options = {}) {
+        const params = new URLSearchParams();
+        if (options.from != null)
+            params.set("from", String(options.from));
+        if (options.order != null)
+            params.set("order", options.order);
+        if (options.limit != null)
+            params.set("limit", String(options.limit));
+        const qs = params.toString();
+        const path = `/jobs/${encodeURIComponent(id)}/errors${qs ? "?" + qs : ""}`;
+        return this.listErrorsByPath(path);
+    }
+    /**
+     * Fetch a page of errors by a raw path (used internally for pagination links).
+     *
+     * @internal
+     */
+    async listErrorsByPath(path) {
+        const data = await this.handleResponse(await this.request("GET", path));
+        const errors = data.errors.map((e) => this.wrapError(e));
+        return new ErrorPage(this, errors, data.pages);
+    }
+    /**
+     * Fetch a single error record for a job by attempt number.
+     *
+     * @param id - The job ID.
+     * @param attempt - The attempt number (1-based).
+     * @returns The error record for that attempt.
+     * @throws {NotFoundError} If the job or attempt is not found.
+     */
+    async getError(id, attempt) {
+        const raw = await this.handleResponse(await this.request("GET", `/jobs/${encodeURIComponent(id)}/errors/${encodeURIComponent(String(attempt))}`));
+        return this.wrapError(raw);
+    }
+    /**
+     * Connect to the streaming take endpoint and return an async generator
+     * of jobs.
+     *
+     * The returned promise resolves once the HTTP connection is established.
+     * The async generator then yields jobs as they arrive. Heartbeats in
+     * the stream are silently skipped.
+     *
+     * The generator completes when the server closes the connection. The
+     * caller may also break out of the loop explicitly to end the stream,
+     * or provide an AbortSignal to explicitly signal cancellation.
+     *
+     * @example
+     * ```ts
+     * for await (const job of await client.take({ prefetch: 5, queues: ["emails"] })) {
+     *   await processJob(job.payload);
+     *   await client.reportSuccess(job.id);
+     * }
+     * ```
+     */
+    async take(options = {}) {
+        const params = new URLSearchParams();
+        if (options.prefetch != null) {
+            params.set("prefetch", String(options.prefetch));
+        }
+        if (options.queues?.length) {
+            params.set("queue", options.queues.join(","));
+        }
+        const qs = params.toString();
+        const path = `/jobs/take${qs ? "?" + qs : ""}`;
+        const res = await this.streamHttp.request({
+            method: "GET",
+            path,
+            headers: { accept: this.streamAccept },
+            signal: options.signal ?? null,
+        });
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+            await this.throwOnError(res);
+        }
+        const body = res.body;
+        // Use the response content-type to pick the stream parser, not the
+        // requested format — the server may respond differently (e.g. 406).
+        const contentType = String(res.headers["content-type"] ?? "");
+        if (contentType.includes("msgpack")) {
+            return this.iterateMsgpackStream(body);
+        }
+        return this.iterateNdjson(body);
+    }
+    /** Parse an NDJSON stream, yielding jobs. Empty lines are heartbeats. */
+    async *iterateNdjson(body) {
+        const decoder = new TextDecoder();
+        let buffer = "";
+        try {
+            for await (const chunk of body) {
+                buffer += decoder.decode(chunk, { stream: true });
+                let newlineIdx;
+                while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
+                    const line = buffer.slice(0, newlineIdx).trim();
+                    buffer = buffer.slice(newlineIdx + 1);
+                    if (line.length === 0)
+                        continue;
+                    yield this.wrapJob(JSON.parse(line));
+                }
+            }
+        }
+        finally {
+            body.destroy();
+        }
+    }
+    /**
+     * Parse a length-prefixed MessagePack stream, yielding jobs.
+     *
+     * Frame format: [4-byte big-endian length][MessagePack payload].
+     * A zero-length frame is a heartbeat and is silently skipped.
+     */
+    async *iterateMsgpackStream(body) {
+        let buffer = Buffer.alloc(0);
+        try {
+            for await (const chunk of body) {
+                buffer = Buffer.concat([buffer, chunk]);
+                while (buffer.length >= 4) {
+                    const frameLen = buffer.readUInt32BE(0);
+                    // Zero-length frame is a heartbeat.
+                    if (frameLen === 0) {
+                        buffer = buffer.subarray(4);
+                        continue;
+                    }
+                    // Wait for the full frame.
+                    if (buffer.length < 4 + frameLen)
+                        break;
+                    const payload = buffer.subarray(4, 4 + frameLen);
+                    buffer = buffer.subarray(4 + frameLen);
+                    yield this.wrapJob(msgpackDecode(payload));
+                }
+            }
+        }
+        finally {
+            body.destroy();
+        }
+    }
+    /** Wrap raw API data as a Job instance. */
+    wrapJob(raw) {
+        return new Job(this, jobFromApi(raw));
+    }
+    /** Wrap raw API data as an ErrorRecord instance. */
+    wrapError(raw) {
+        return new ErrorRecord(errorFromApi(raw));
+    }
+    /**
+     * Gracefully close the underlying HTTP connection.
+     *
+     * Waits for in-flight requests to complete. If a streaming `take()`
+     * connection is open, this will block until it ends — use
+     * {@link destroy} for hard immediate shutdown.
+     */
+    async close() {
+        await Promise.all([this.http.close(), this.streamHttp.close()]);
+    }
+    /**
+     * Forcefully destroy the underlying HTTP connection.
+     *
+     * Immediately terminates all in-flight requests including any open
+     * `take()` stream. Use this when `close()` would block (e.g. after
+     * an unclean interruption in the REPL).
+     */
+    async destroy() {
+        await Promise.all([this.http.destroy(), this.streamHttp.destroy()]);
+    }
+    async request(method, path, extraHeaders) {
+        try {
+            return await this.http.request({
+                method: method,
+                path,
+                headers: {
+                    accept: this.accept,
+                    ...extraHeaders,
+                },
+            });
+        }
+        catch (err) {
+            throw toConnectionError(err);
+        }
+    }
+    async post(path, body) {
+        return this.requestWithBody("POST", path, body);
+    }
+    async patch(path, body) {
+        return this.requestWithBody("PATCH", path, body);
+    }
+    async requestWithBody(method, path, body) {
+        try {
+            return await this.http.request({
+                method,
+                path,
+                headers: {
+                    "content-type": this.contentType,
+                    accept: this.accept,
+                },
+                body: this.encode(body),
+            });
+        }
+        catch (err) {
+            throw toConnectionError(err);
+        }
+    }
+    /** Encode a value in the configured format. */
+    encode(value) {
+        if (this.format === "msgpack") {
+            return Buffer.from(msgpackEncode(value));
+        }
+        return JSON.stringify(value);
+    }
+    async handleResponse(res) {
+        if (res.statusCode === 204) {
+            // Drain the body to release the connection.
+            for await (const _ of res.body) { }
+            return undefined;
+        }
+        const body = await this.readBody(res);
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+            throw buildResponseError(res.statusCode, body);
+        }
+        return body;
+    }
+    async throwOnError(res) {
+        let body;
+        try {
+            body = await this.readBody(res);
+        }
+        catch {
+            body = undefined;
+        }
+        throw buildResponseError(res.statusCode, body);
+    }
+    /** Read and decode a response body, using the content-type header to
+     *  pick the correct decoder rather than assuming the requested format. */
+    async readBody(res) {
+        const chunks = [];
+        for await (const chunk of res.body) {
+            chunks.push(chunk);
+        }
+        const data = Buffer.concat(chunks);
+        const contentType = String(res.headers["content-type"] ?? "");
+        if (contentType.includes("msgpack")) {
+            return msgpackDecode(data);
+        }
+        return JSON.parse(new TextDecoder().decode(data));
+    }
+}
+// --- API format translation ---
+//
+// The server uses snake_case keys. The client exposes camelCase. These
+// helpers translate at the boundary. `undefined` values are stripped via
+// delete so they don't appear as keys in the JSON body, while `null`
+// values are preserved (needed for PATCH resets).
+/** Normalize a scalar or array to a comma-separated string. */
+function toCommaList(value) {
+    return Array.isArray(value) ? value.join(",") : value;
+}
+/**
+ * Throw if `obj` contains keys not in the allowed list.
+ *
+ * Catches typos and structural mistakes in options objects (e.g. passing
+ * `{ status: "ready" }` to `deleteAllJobs` instead of `{ where: { status: "ready" } }`)
+ * which would otherwise silently delete or update everything.
+ */
+function assertOnlyKeys(context, obj, allowed) {
+    for (const key of Object.keys(obj)) {
+        if (!allowed.includes(key)) {
+            throw new Error(`${context}: unknown option "${key}". Allowed: ${allowed.join(", ")}`);
+        }
+    }
+}
+/** Strip keys whose value is `undefined` from an object (in place). */
+function stripUndefined(obj) {
+    for (const k in obj)
+        if (obj[k] === undefined)
+            delete obj[k];
+    return obj;
+}
+/** Convert an EnqueueOptions to the server's snake_case API format. */
+function enqueueToApi(opts) {
+    return stripUndefined({
+        type: opts.type,
+        queue: opts.queue,
+        payload: opts.payload,
+        priority: opts.priority,
+        ready_at: opts.readyAt,
+        retry_limit: opts.retryLimit,
+        backoff: opts.backoff && backoffToApi(opts.backoff),
+        retention: opts.retention && retentionToApi(opts.retention),
+        unique_key: opts.uniqueKey,
+        unique_while: opts.uniqueWhile,
+    });
+}
+/**
+ * Convert an UpdateJobOptions to the server's snake_case patch format.
+ *
+ * `undefined` values are stripped (leave field unchanged), `null` values
+ * are preserved (clear field on the server). Nested backoff and retention
+ * objects are translated when present, passed through as `null` when null.
+ */
+function updateToApi(opts) {
+    return stripUndefined({
+        queue: opts.queue,
+        priority: opts.priority,
+        ready_at: opts.readyAt,
+        retry_limit: opts.retryLimit,
+        backoff: opts.backoff && backoffToApi(opts.backoff),
+        retention: opts.retention && retentionToApi(opts.retention),
+    });
+}
+/** Convert a FailureOptions to the server's snake_case API format. */
+function failureToApi(opts) {
+    return stripUndefined({
+        message: opts.message,
+        error_type: opts.errorType,
+        backtrace: opts.backtrace,
+        retry_at: opts.retryAt,
+        kill: opts.kill,
+    });
+}
+/** Convert a BackoffConfig to API format. */
+function backoffToApi(b) {
+    return { base_ms: b.baseMs, exponent: b.exponent, jitter_ms: b.jitterMs };
+}
+/** Convert a RetentionConfig to API format. */
+function retentionToApi(r) {
+    return stripUndefined({
+        completed_ms: r.completedMs,
+        dead_ms: r.deadMs,
+    });
+}
+/** Convert an API-format job object to a camelCase JobData. */
+function jobFromApi(raw) {
+    const r = raw;
+    return stripUndefined({
+        id: r.id,
+        type: r.type,
+        queue: r.queue,
+        priority: r.priority,
+        status: r.status,
+        payload: r.payload,
+        readyAt: r.ready_at,
+        attempts: r.attempts,
+        retryLimit: r.retry_limit,
+        backoff: r.backoff != null ? backoffFromApi(r.backoff) : undefined,
+        dequeuedAt: r.dequeued_at,
+        failedAt: r.failed_at,
+        completedAt: r.completed_at,
+        retention: r.retention != null ? retentionFromApi(r.retention) : undefined,
+        purgeAt: r.purge_at,
+        uniqueKey: r.unique_key,
+        uniqueWhile: r.unique_while,
+        duplicate: r.duplicate,
+    });
+}
+/** Convert an API-format backoff to camelCase. */
+function backoffFromApi(raw) {
+    const r = raw;
+    return {
+        baseMs: r.base_ms,
+        exponent: r.exponent,
+        jitterMs: r.jitter_ms,
+    };
+}
+/** Convert an API-format retention to camelCase. */
+function retentionFromApi(raw) {
+    const r = raw;
+    return stripUndefined({
+        completedMs: r.completed_ms,
+        deadMs: r.dead_ms,
+    });
+}
+/** Build the appropriate ResponseError subclass for an HTTP status code. */
+/** Convert an API-format error record to camelCase. */
+function errorFromApi(raw) {
+    const r = raw;
+    return stripUndefined({
+        attempt: r.attempt,
+        message: r.message,
+        errorType: r.error_type,
+        backtrace: r.backtrace,
+        dequeuedAt: r.dequeued_at,
+        failedAt: r.failed_at,
+    });
+}
+function buildResponseError(status, body) {
+    const message = body?.error ?? `HTTP ${status}`;
+    if (status === 404)
+        return new NotFoundError(message, body);
+    if (status >= 400 && status < 500)
+        return new ClientError(message, status, body);
+    if (status >= 500)
+        return new ServerError(message, status, body);
+    return new ResponseError(message, status, body);
+}
+/** Wrap a low-level error (from undici) as a ConnectionError. */
+function toConnectionError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return new ConnectionError(message);
+}