bunqueue-client 0.1.5 → 0.1.7

package/src/observability.ts

@@ -0,0 +1,158 @@
+/**
+ * Observability primitives: a pluggable structured logger and a telemetry
+ * sink. Zero hard dependencies — wire your own OpenTelemetry / Prometheus /
+ * logging stack through these interfaces. Defaults are no-ops, so the SDK is
+ * silent unless you opt in.
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export interface Logger {
+  debug(message: string, meta?: Record<string, unknown>): void;
+  info(message: string, meta?: Record<string, unknown>): void;
+  warn(message: string, meta?: Record<string, unknown>): void;
+  error(message: string, meta?: Record<string, unknown>): void;
+}
+
+/** Silent logger (the default). */
+export const noopLogger: Logger = {
+  debug() {},
+  info() {},
+  warn() {},
+  error() {},
+};
+
+const LEVELS: Record<LogLevel, number> = { debug: 10, info: 20, warn: 30, error: 40 };
+
+/**
+ * A console-backed logger. Levels below `min` are dropped. Opt-in — pass it as
+ * `logger` when you want the SDK to log to the console.
+ */
+export function consoleLogger(min: LogLevel = 'info'): Logger {
+  const floor = LEVELS[min];
+  const line = (lvl: LogLevel, msg: string, meta?: Record<string, unknown>) => {
+    if (LEVELS[lvl] < floor) return;
+    const suffix = meta && Object.keys(meta).length > 0 ? ` ${JSON.stringify(meta)}` : '';
+    const sink = lvl === 'debug' ? console.log : console[lvl];
+    sink(`[bunqueue] ${lvl} ${msg}${suffix}`);
+  };
+  return {
+    debug: (m, meta) => line('debug', m, meta),
+    info: (m, meta) => line('info', m, meta),
+    warn: (m, meta) => line('warn', m, meta),
+    error: (m, meta) => line('error', m, meta),
+  };
+}
+
+/** A single telemetry data point. A discriminated union keyed on `type`. */
+export type TelemetryEvent =
+  | { type: 'command'; cmd: string; reqId: string; durationMs: number; ok: boolean }
+  | { type: 'command_timeout'; cmd: string; reqId: string }
+  | { type: 'connect'; host: string; port: number; generation: number; durationMs: number }
+  | { type: 'disconnect'; host: string; port: number; generation: number }
+  | { type: 'reconnect_scheduled'; host: string; port: number; attempt: number; delayMs: number }
+  | { type: 'auth'; ok: boolean }
+  | { type: 'backpressure'; inFlight: number; maxInFlight: number };
+
+export type TelemetryHandler = (event: TelemetryEvent) => void;
+
+/** Lifecycle telemetry types that are ALSO emitted as EventEmitter events. */
+export const LIFECYCLE_EVENTS = ['connect', 'disconnect', 'reconnect_scheduled'] as const;
+
+export interface Observability {
+  /** Structured logger; defaults to {@link noopLogger}. */
+  logger?: Logger;
+  /**
+   * Telemetry sink for metrics and tracing. Receives every command's latency,
+   * connect/disconnect/reconnect, auth and backpressure events. Bridge it to
+   * OpenTelemetry spans or Prometheus counters without the SDK depending on
+   * either.
+   */
+  onTelemetry?: TelemetryHandler;
+}
+
+/** High-resolution monotonic clock (Node/Bun/Deno all expose `performance`). */
+export const nowMs = (): number => performance.now();
+
+/**
+ * Fans a telemetry event out to (1) the telemetry sink, (2) the logger, and
+ * (3) — for lifecycle events — the owning EventEmitter, so users can both
+ * scrape metrics and attach imperative `connection.on('connect', …)` handlers.
+ */
+export class Telemetry {
+  private readonly logger: Logger;
+  private readonly sink: TelemetryHandler | undefined;
+  private readonly emit: (event: string, payload: unknown) => void;
+
+  constructor(obs: Observability | undefined, emit: (event: string, payload: unknown) => void) {
+    // Wrap the user logger so a throwing logger can never break the transport
+    // hot path (dispatch runs inside socket 'data' handlers and connect).
+    const inner = obs?.logger ?? noopLogger;
+    this.logger =
+      inner === noopLogger
+        ? inner
+        : {
+            debug: (m, meta) => Telemetry.safely(() => inner.debug(m, meta)),
+            info: (m, meta) => Telemetry.safely(() => inner.info(m, meta)),
+            warn: (m, meta) => Telemetry.safely(() => inner.warn(m, meta)),
+            error: (m, meta) => Telemetry.safely(() => inner.error(m, meta)),
+          };
+    this.sink = obs?.onTelemetry;
+    this.emit = emit;
+  }
+
+  /** Observability must never break the client: swallow consumer errors. */
+  private static safely(fn: () => void): void {
+    try {
+      fn();
+    } catch {
+      /* consumer logging/telemetry error — intentionally ignored */
+    }
+  }
+
+  get log(): Logger {
+    return this.logger;
+  }
+
+  /** Record a completed command's latency and outcome. */
+  command(cmd: string, reqId: string, startMs: number, ok: boolean): void {
+    this.dispatch({ type: 'command', cmd, reqId, durationMs: nowMs() - startMs, ok });
+  }
+
+  timeout(cmd: string, reqId: string): void {
+    this.logger.warn('command timed out', { cmd, reqId });
+    this.dispatch({ type: 'command_timeout', cmd, reqId });
+  }
+
+  connected(host: string, port: number, generation: number, startMs: number): void {
+    this.logger.info('connected', { host, port, generation });
+    this.dispatch({ type: 'connect', host, port, generation, durationMs: nowMs() - startMs });
+  }
+
+  disconnected(host: string, port: number, generation: number): void {
+    this.logger.info('disconnected', { host, port, generation });
+    this.dispatch({ type: 'disconnect', host, port, generation });
+  }
+
+  reconnectScheduled(host: string, port: number, attempt: number, delayMs: number): void {
+    this.logger.warn('reconnect scheduled', { host, port, attempt, delayMs });
+    this.dispatch({ type: 'reconnect_scheduled', host, port, attempt, delayMs });
+  }
+
+  auth(ok: boolean): void {
+    this.dispatch({ type: 'auth', ok });
+  }
+
+  backpressure(inFlight: number, maxInFlight: number): void {
+    this.dispatch({ type: 'backpressure', inFlight, maxInFlight });
+  }
+
+  private dispatch(event: TelemetryEvent): void {
+    // A throwing sink or lifecycle listener must never break the transport:
+    // dispatch runs inside socket 'data' handlers and the connect path.
+    Telemetry.safely(() => this.sink?.(event));
+    if ((LIFECYCLE_EVENTS as readonly string[]).includes(event.type)) {
+      Telemetry.safely(() => this.emit(event.type, event));
+    }
+  }
+}

package/src/queue-admin.ts

@@ -3,6 +3,7 @@
  * monitoring and webhooks. Merged onto Queue.prototype by queue.ts.
  */
 
+import { CommandError } from './errors.js';
 import { compact } from './frame.js';
 import type { Queue } from './queue.js';
 import { type JobOptions, jobPayload, wireJobOptions } from './types.js';
@@ -95,6 +96,10 @@ export const adminMethods = {
     repeat: SchedulerOptions,
     template: { name?: string; data?: unknown; opts?: JobOptions } = {}
   ): Promise<void> {
+    // Priority and deduplication of spawned jobs travel as TOP-LEVEL Cron
+    // fields (the handler reads cmd.priority/uniqueKey/dedup); inside
+    // jobOptions the server's CronJobOptions silently ignores them.
+    const dedup = template.opts?.deduplication;
     await this.call(
       compact({
         cmd: 'Cron',
@@ -103,9 +108,14 @@ export const adminMethods = {
         data: jobPayload(template.name ?? schedulerId, template.data ?? {}),
         schedule: repeat.pattern,
         repeatEvery: repeat.every,
+        priority: template.opts?.priority,
         timezone: repeat.tz,
         immediately: repeat.immediately,
         maxLimit: repeat.limit,
+        uniqueKey: dedup?.id,
+        dedup: dedup
+          ? compact({ ttl: dedup.ttl, extend: dedup.extend, replace: dedup.replace })
+          : undefined,
         skipMissedOnRestart: repeat.skipMissedOnRestart,
         skipIfNoWorker: repeat.skipIfNoWorker,
         preventOverlap: repeat.preventOverlap,
@@ -122,8 +132,11 @@ export const adminMethods = {
     try {
       const response = await this.call({ cmd: 'CronGet', name: schedulerId });
       return (response.cron ?? response.data ?? null) as Raw | null;
-    } catch {
-      return null; // not-found surfaces as a CommandError
+    } catch (err) {
+      // Only 'Cron job not found' maps to null; connection loss, timeouts and
+      // real server errors must surface, not masquerade as a missing scheduler.
+      if (err instanceof CommandError && /not found/i.test(err.message)) return null;
+      throw err;
     }
   },
 

package/src/queue-control.ts

@@ -3,9 +3,12 @@
  * mutations. Methods are merged onto Queue.prototype by queue.ts.
  */
 
+import { UnrecoverableError } from './errors.js';
 import { compact } from './frame.js';
 import type { Queue } from './queue.js';
+import type { CountResponse, PausedResponse } from './responses.js';
 import type { JobStateName } from './types.js';
+import { MAX_STACK_LINES } from './worker-types.js';
 
 type Ctx = Queue<unknown>;
 
@@ -19,8 +22,7 @@ export const controlMethods = {
   },
 
   async isPaused(this: Ctx): Promise<boolean> {
-    const response = await this.call({ cmd: 'IsPaused', queue: this.name });
-    return response.paused === true;
+    return (await this.call<PausedResponse>({ cmd: 'IsPaused', queue: this.name })).paused === true;
   },
 
   async drain(this: Ctx): Promise<void> {
@@ -33,10 +35,10 @@ export const controlMethods = {
 
   /** Remove old jobs; returns how many were removed. */
   async clean(this: Ctx, graceMs: number, limit?: number, state?: JobStateName): Promise<number> {
-    const response = await this.call(
+    const response = await this.call<CountResponse>(
       compact({ cmd: 'Clean', queue: this.name, grace: graceMs, limit, state }) as { cmd: string }
     );
-    return Number(response.count ?? 0);
+    return response.count ?? 0;
   },
 
   async remove(this: Ctx, id: string): Promise<void> {
@@ -53,10 +55,10 @@ export const controlMethods = {
 
   /** Promote delayed jobs to waiting; returns how many were promoted. */
   async promoteJobs(this: Ctx, opts: { count?: number } = {}): Promise<number> {
-    const response = await this.call(
+    const response = await this.call<CountResponse>(
       compact({ cmd: 'PromoteJobs', queue: this.name, count: opts.count }) as { cmd: string }
     );
-    return Number(response.count ?? 0);
+    return response.count ?? 0;
   },
 
   /** BullMQ contract: failed → waiting. */
@@ -72,9 +74,11 @@ export const controlMethods = {
       await this.call({ cmd: 'RetryCompleted', queue: this.name });
       return;
     }
-    // `count` is accepted for API parity but not sent: the server has no
-    // partial RetryDlq — it retries the whole DLQ (BullMQ semantics).
-    await this.call({ cmd: 'RetryDlq', queue: this.name });
+    // `count` caps how many DLQ entries are retried (server >= 2.8.29). Older
+    // servers ignore the field and retry the whole DLQ — forward-compatible.
+    await this.call(
+      compact({ cmd: 'RetryDlq', queue: this.name, count: opts.count }) as { cmd: string }
+    );
   },
 
   async retryCompleted(this: Ctx, id?: string): Promise<void> {
@@ -129,14 +133,33 @@ export const controlMethods = {
     await this.call(compact({ cmd: 'ACK', id, result: returnValue, token }) as { cmd: string });
   },
 
+  /**
+   * Explicit failure path: mirrors the worker's FAIL wire so the stacktrace
+   * and the UnrecoverableError "do not retry" intent are persisted (#111
+   * silent-loss class), not just the message.
+   */
   async moveJobToFailed(
     this: Ctx,
     id: string,
     error: Error | string,
     token?: string
   ): Promise<void> {
-    const message = typeof error === 'string' ? error : error.message;
-    await this.call(compact({ cmd: 'FAIL', id, error: message, token }) as { cmd: string });
+    const err = typeof error === 'string' ? undefined : error;
+    const message = err ? err.message || err.name : (error as string);
+    // Keep the FIRST lines (message + throw site), like the worker path.
+    const stack = err
+      ? (err.stack ?? err.message).split('\n').slice(0, MAX_STACK_LINES)
+      : undefined;
+    await this.call(
+      compact({
+        cmd: 'FAIL',
+        id,
+        error: message,
+        stack,
+        unrecoverable: err instanceof UnrecoverableError ? true : undefined,
+        token,
+      }) as { cmd: string }
+    );
   },
 };
 

package/src/queue-query.ts

@@ -7,12 +7,23 @@ import { CommandError, CommandTimeoutError } from './errors.js';
 import { compact } from './frame.js';
 import { Job } from './job.js';
 import type { Queue } from './queue.js';
+import type {
+  CountResponse,
+  DataResponse,
+  JobCountsResponse,
+  JobResponse,
+  JobsResponse,
+  ProgressResponse,
+  ResultResponse,
+  StateResponse,
+  WaitJobResponse,
+} from './responses.js';
 import type { JobCounts } from './types.js';
 
 type Ctx = Queue<unknown>;
 type Raw = Record<string, unknown>;
 
-function unwrapValues<R>(response: Raw): Record<string, R> {
+function unwrapValues<R>(response: { data?: unknown; values?: unknown }): Record<string, R> {
   const data = (response.data ?? {}) as Raw;
   return (data.values ?? response.values ?? data ?? {}) as Record<string, R>;
 }
@@ -20,22 +31,22 @@ function unwrapValues<R>(response: Raw): Record<string, R> {
 export const queryMethods = {
   async getJob<T = unknown>(this: Ctx, id: string): Promise<Job<T> | null> {
     try {
-      const response = await this.call({ cmd: 'GetJob', id });
-      const raw = response.job as Raw | null;
-      return raw ? new Job<T>(raw, this.connection) : null;
+      const response = await this.call<JobResponse>({ cmd: 'GetJob', id });
+      return response.job ? new Job<T>(response.job, this.connection) : null;
     } catch (err) {
-      if (err instanceof CommandError) return null; // server: 'Job not found'
+      // Only the server's 'Job not found' maps to null; connection loss,
+      // timeouts and other server errors must surface.
+      if (err instanceof CommandError && /not found/i.test(err.message)) return null;
       throw err;
     }
   },
 
   async getJobByCustomId<T = unknown>(this: Ctx, customId: string): Promise<Job<T> | null> {
     try {
-      const response = await this.call({ cmd: 'GetJobByCustomId', customId });
-      const raw = response.job as Raw | null;
-      return raw ? new Job<T>(raw, this.connection) : null;
+      const response = await this.call<JobResponse>({ cmd: 'GetJobByCustomId', customId });
+      return response.job ? new Job<T>(response.job, this.connection) : null;
     } catch (err) {
-      if (err instanceof CommandError) return null;
+      if (err instanceof CommandError && /not found/i.test(err.message)) return null;
       throw err;
     }
   },
@@ -52,7 +63,7 @@ export const queryMethods = {
   ): Promise<Job<T>[]> {
     const start = opts.start ?? 0;
     const end = opts.end !== undefined && opts.end >= 0 ? opts.end : 1000;
-    const response = await this.call(
+    const response = await this.call<JobsResponse>(
       compact({
         cmd: 'GetJobs',
         queue: this.name,
@@ -61,8 +72,7 @@ export const queryMethods = {
         limit: end - start,
       }) as { cmd: string }
     );
-    const jobs = (response.jobs ?? []) as Raw[];
-    return jobs.map((raw) => new Job<T>(raw, this.connection));
+    return (response.jobs ?? []).map((raw) => new Job<T>(raw, this.connection));
   },
 
   getWaiting<T = unknown>(this: Ctx, start?: number, end?: number): Promise<Job<T>[]> {
@@ -96,25 +106,27 @@ export const queryMethods = {
   },
 
   async getJobState(this: Ctx, id: string): Promise<string> {
-    const response = await this.call({ cmd: 'GetState', id });
-    return String(response.state);
+    return (await this.call<StateResponse>({ cmd: 'GetState', id })).state;
   },
 
   async getResult<R = unknown>(this: Ctx, id: string): Promise<R> {
-    const response = await this.call({ cmd: 'GetResult', id });
-    return response.result as R;
+    return (await this.call<ResultResponse<R>>({ cmd: 'GetResult', id })).result;
   },
 
   async getChildrenValues<R = unknown>(this: Ctx, id: string): Promise<Record<string, R>> {
-    return unwrapValues<R>(await this.call({ cmd: 'GetChildrenValues', id }));
+    return unwrapValues<R>(await this.call<DataResponse>({ cmd: 'GetChildrenValues', id }));
   },
 
   async getFailedChildrenValues(this: Ctx, id: string): Promise<Record<string, string>> {
-    return unwrapValues<string>(await this.call({ cmd: 'GetFailedChildrenValues', id }));
+    return unwrapValues<string>(
+      await this.call<DataResponse>({ cmd: 'GetFailedChildrenValues', id })
+    );
   },
 
   async getIgnoredChildrenFailures(this: Ctx, id: string): Promise<Record<string, string>> {
-    return unwrapValues<string>(await this.call({ cmd: 'GetIgnoredChildrenFailures', id }));
+    return unwrapValues<string>(
+      await this.call<DataResponse>({ cmd: 'GetIgnoredChildrenFailures', id })
+    );
   },
 
   /** Detach a child job from its parent's dependency list. */
@@ -136,7 +148,10 @@ export const queryMethods = {
    * will not complete), everything else throws CommandTimeoutError.
    */
   async waitForJob<R = unknown>(this: Ctx, id: string, ttlMs = 30_000): Promise<R> {
-    const response = await this.call({ cmd: 'WaitJob', id, timeout: ttlMs }, ttlMs + 5000);
+    const response = await this.call<WaitJobResponse<R>>(
+      { cmd: 'WaitJob', id, timeout: ttlMs },
+      ttlMs + 5000
+    );
     if (response.completed !== true) {
       let state: string | undefined;
       try {
@@ -161,18 +176,14 @@ export const queryMethods = {
   },
 
   async getProgress(this: Ctx, id: string): Promise<{ progress: number; message: string | null }> {
-    const response = await this.call({ cmd: 'GetProgress', id });
-    return {
-      progress: Number(response.progress ?? 0),
-      message: (response.message as string | null) ?? null,
-    };
+    const response = await this.call<ProgressResponse>({ cmd: 'GetProgress', id });
+    return { progress: response.progress ?? 0, message: response.message ?? null };
   },
 
   // ------------------------------------------------------------------- counts
 
   async getJobCounts(this: Ctx): Promise<JobCounts> {
-    const response = await this.call({ cmd: 'GetJobCounts', queue: this.name });
-    return response.counts as JobCounts;
+    return (await this.call<JobCountsResponse>({ cmd: 'GetJobCounts', queue: this.name })).counts;
   },
 
   async getWaitingCount(this: Ctx): Promise<number> {
@@ -206,8 +217,7 @@ export const queryMethods = {
   },
 
   async count(this: Ctx): Promise<number> {
-    const response = await this.call({ cmd: 'Count', queue: this.name });
-    return Number(response.count ?? 0);
+    return (await this.call<CountResponse>({ cmd: 'Count', queue: this.name })).count ?? 0;
   },
 
   async getCountsPerPriority(this: Ctx): Promise<Record<string, number>> {

package/src/queue.ts

@@ -10,19 +10,29 @@
  */
 
 import { Connection, type Response, type TlsOption } from './connection.js';
+import { ConnectionPool } from './connection-pool.js';
+import type { ConnectionLike } from './connection-types.js';
 import { Job } from './job.js';
+import type { Observability } from './observability.js';
 import { adminMethods, type QueueAdminApi } from './queue-admin.js';
 import { controlMethods, type QueueControlApi } from './queue-control.js';
 import { type QueueQueryApi, queryMethods } from './queue-query.js';
 import { type JobOptions, jobPayload, wireJobOptions } from './types.js';
 
-export interface QueueOptions {
+export interface QueueOptions extends Observability {
   host?: string;
   port?: number;
   token?: string;
   tls?: TlsOption;
   connection?: Connection;
   commandTimeoutMs?: number;
+  /** Max in-flight commands before backpressure kicks in (0 = unbounded). */
+  maxInFlight?: number;
+  /**
+   * Fan producer commands across N connections (round-robin) for throughput.
+   * >1 builds a ConnectionPool; default 1 = a single connection.
+   */
+  poolSize?: number;
 }
 
 export interface BulkJobEntry<T = unknown> {
@@ -34,26 +44,35 @@ export interface BulkJobEntry<T = unknown> {
 // biome-ignore lint/suspicious/noUnsafeDeclarationMerging: prototype-mixin composition — Object.assign at the bottom installs exactly the methods the merged interface declares
 export class Queue<T = unknown> {
   readonly name: string;
-  readonly connection: Connection;
+  readonly connection: ConnectionLike;
   private readonly ownsConnection: boolean;
 
   constructor(name: string, opts: QueueOptions = {}) {
     this.name = name;
+    const connOptions = {
+      host: opts.host,
+      port: opts.port,
+      token: opts.token,
+      tls: opts.tls,
+      commandTimeoutMs: opts.commandTimeoutMs,
+      maxInFlight: opts.maxInFlight,
+      logger: opts.logger,
+      onTelemetry: opts.onTelemetry,
+    };
     this.connection =
       opts.connection ??
-      new Connection({
-        host: opts.host,
-        port: opts.port,
-        token: opts.token,
-        tls: opts.tls,
-        commandTimeoutMs: opts.commandTimeoutMs,
-      });
+      (opts.poolSize && opts.poolSize > 1
+        ? new ConnectionPool(opts.poolSize, connOptions)
+        : new Connection(connOptions));
     this.ownsConnection = opts.connection === undefined;
   }
 
   /** Send a raw command on this queue's connection (used by area modules). */
-  call(command: Record<string, unknown> & { cmd: string }, timeoutMs?: number): Promise<Response> {
-    return this.connection.call(command, timeoutMs);
+  call<R = Response>(
+    command: Record<string, unknown> & { cmd: string },
+    timeoutMs?: number
+  ): Promise<R> {
+    return this.connection.call<R>(command, timeoutMs);
   }
 
   // ------------------------------------------------------------------ produce

package/src/responses.ts

@@ -0,0 +1,96 @@
+/**
+ * Typed server-response shapes, mirroring the server's response builders
+ * (src/domain/types/response.ts). `Connection.call<R>()` and `Queue.call<R>()`
+ * are generic over these, so call sites read `response.job` / `response.counts`
+ * with real types instead of casting `as Record<string, unknown>`.
+ *
+ * These narrow the loose transport `Response`; the runtime value is whatever
+ * the server sent, so only assert the shape a given command actually returns.
+ */
+
+import type { JobRaw } from './job.js';
+import type { JobCounts, JobStateName } from './types.js';
+
+interface Ok {
+  ok: true;
+  reqId?: string;
+  // Index signature so these satisfy the loose transport `Response`
+  // (Record<string, unknown> & { ok }). Named fields still win for reads.
+  [key: string]: unknown;
+}
+
+/** PUSH → id, or a bare ok ack. */
+export interface OkResponse extends Ok {
+  id?: string;
+}
+
+/** PUSHB → ids. */
+export interface BatchResponse extends Ok {
+  ids: string[];
+}
+
+/** GetJob → job (null when not found is surfaced as a CommandError instead). */
+export interface JobResponse extends Ok {
+  job: JobRaw | null;
+}
+
+/** PULL → job + lock token. */
+export interface PulledJobResponse extends Ok {
+  job: JobRaw | null;
+  token: string | null;
+}
+
+/** PULLB → jobs + lock tokens (same order). */
+export interface PulledJobsResponse extends Ok {
+  jobs: JobRaw[];
+  tokens: string[];
+}
+
+/** GetJobs → jobs. */
+export interface JobsResponse extends Ok {
+  jobs: JobRaw[];
+}
+
+/** GetState → state. */
+export interface StateResponse extends Ok {
+  id: string;
+  state: JobStateName;
+}
+
+/** GetResult → result. */
+export interface ResultResponse<R = unknown> extends Ok {
+  result: R;
+}
+
+/** WaitJob → completed flag + (on completion) result. */
+export interface WaitJobResponse<R = unknown> extends Ok {
+  completed: boolean;
+  result?: R;
+}
+
+/** GetJobCounts → counts. */
+export interface JobCountsResponse extends Ok {
+  counts: JobCounts;
+}
+
+/** GetProgress → progress + message. */
+export interface ProgressResponse extends Ok {
+  progress: number;
+  message: string | null;
+}
+
+/** IsPaused → paused. */
+export interface PausedResponse extends Ok {
+  paused: boolean;
+}
+
+/** Count / Clean / PromoteJobs / RetryDlq → count (+ optional removed ids). */
+export interface CountResponse extends Ok {
+  count: number;
+  ids?: string[];
+}
+
+/** Generic data-wrapped payload (logs, workers, values, webhookId, …). */
+export interface DataResponse<T = unknown> extends Ok {
+  data: T;
+}