@spooled/sdk 1.2.1 → 1.4.0

package/dist/{index-CWVI9LRo.d.cts → index-DzTC8ld3.d.cts}

@@ -1,10 +1,124 @@
 import * as grpc from '@grpc/grpc-js';
 
+/**
+ * Circuit Breaker Utility
+ *
+ * Implements the circuit breaker pattern to prevent cascading failures.
+ * States: CLOSED (normal) -> OPEN (failing) -> HALF_OPEN (testing) -> CLOSED
+ */
+
+/** Circuit breaker states */
+declare enum CircuitState {
+    /** Normal operation - requests flow through */
+    CLOSED = "CLOSED",
+    /** Circuit is open - requests are rejected immediately */
+    OPEN = "OPEN",
+    /** Testing state - limited requests allowed to test recovery */
+    HALF_OPEN = "HALF_OPEN"
+}
+/** Circuit breaker state change event */
+interface CircuitStateChange {
+    from: CircuitState;
+    to: CircuitState;
+    timestamp: Date;
+    failureCount: number;
+}
+/** Circuit breaker options */
+interface CircuitBreakerOptions extends CircuitBreakerConfig {
+    /** Callback when state changes */
+    onStateChange?: (event: CircuitStateChange) => void;
+    /**
+     * Custom function to determine if an error should count as a failure.
+     * Defaults to {@link isCircuitBreakerFailure}.
+     */
+    isFailure?: (error: Error) => boolean;
+}
+/**
+ * Default circuit breaker failure predicate.
+ *
+ * Counts the errors that say the API or the network is unhealthy: the
+ * retryable ones (network errors, timeouts, 5xx, 408). A 429 never counts. A
+ * rate-limit 429 is the API working as designed and telling this client to
+ * slow down for `Retry-After` seconds; counting it let a burst above the plan
+ * limit open the breaker and fail every call on the client for the breaker
+ * timeout (30 s by default), including the retries that `Retry-After` had
+ * already scheduled. The retry layer handles rate limiting on its own. A quota
+ * 429 (`RateLimitError.isQuota`) was already excluded.
+ */
+declare function isCircuitBreakerFailure(error: Error): boolean;
+/**
+ * Circuit Breaker implementation
+ *
+ * Tracks failures and prevents requests when the failure threshold is reached.
+ */
+declare class CircuitBreaker {
+    private state;
+    private failureCount;
+    private successCount;
+    private lastFailureTime;
+    private readonly config;
+    constructor(config: CircuitBreakerOptions);
+    /**
+     * Get current circuit state
+     */
+    getState(): CircuitState;
+    /**
+     * Check if circuit breaker is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Check if requests are currently allowed
+     */
+    isAllowed(): boolean;
+    /**
+     * Record a successful request
+     */
+    recordSuccess(): void;
+    /**
+     * Record a failed request
+     */
+    recordFailure(error: Error): void;
+    /**
+     * Transition to a new state
+     */
+    private transitionTo;
+    /**
+     * Reset the circuit breaker to closed state
+     */
+    reset(): void;
+    /**
+     * Execute a function with circuit breaker protection
+     *
+     * @param fn - Async function to execute
+     * @returns Promise resolving to the function result
+     * @throws CircuitBreakerOpenError if circuit is open
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Get circuit breaker statistics
+     */
+    getStats(): {
+        state: CircuitState;
+        failureCount: number;
+        successCount: number;
+        lastFailureTime: Date | null;
+        config: CircuitBreakerConfig;
+    };
+}
+/**
+ * Create a circuit breaker instance from configuration.
+ *
+ * Unless the config carries its own `isFailure`, rate-limit 429s do not count
+ * as failures (the constructor defaults to {@link isCircuitBreakerFailure}).
+ */
+declare function createCircuitBreaker(config: CircuitBreakerOptions): CircuitBreaker;
+
 /**
  * SDK Configuration
  *
  * Defines configuration types and defaults for the Spooled SDK.
  */
+
 /** Retry configuration options */
 interface RetryConfig {
     /** Maximum number of retry attempts (default: 3) */
@@ -57,8 +171,11 @@ interface SpooledClientConfig {
     retryDelay?: number;
     /** Full retry configuration */
     retry?: Partial<RetryConfig>;
-    /** Circuit breaker configuration */
-    circuitBreaker?: Partial<CircuitBreakerConfig>;
+    /**
+     * Circuit breaker configuration. Besides the thresholds it takes
+     * `isFailure` (which errors count as failures) and `onStateChange`.
+     */
+    circuitBreaker?: Partial<CircuitBreakerOptions>;
     /** Additional headers to include in all requests */
     headers?: Record<string, string>;
     /** Custom fetch implementation (for testing or special runtimes) */
@@ -81,7 +198,7 @@ interface ResolvedConfig {
     grpcAddress: string;
     timeout: number;
     retry: RetryConfig;
-    circuitBreaker: CircuitBreakerConfig;
+    circuitBreaker: CircuitBreakerOptions;
     headers: Record<string, string>;
     fetch: typeof fetch;
     userAgent: string;
@@ -107,11 +224,11 @@ declare const DEFAULT_CONFIG: {
         successThreshold: number;
         timeout: number;
     };
-    readonly userAgent: "@spooled/sdk-nodejs/1.2.1";
+    readonly userAgent: "@spooled/sdk-nodejs/1.4.0";
     readonly autoRefreshToken: true;
 };
 /** SDK version */
-declare const SDK_VERSION = "1.2.1";
+declare const SDK_VERSION = "1.4.0";
 /** API version prefix */
 declare const API_VERSION = "v1";
 /**
@@ -125,98 +242,206 @@ declare function resolveConfig(options: SpooledClientConfig): ResolvedConfig;
 declare function validateConfig(config: ResolvedConfig): void;
 
 /**
- * Circuit Breaker Utility
+ * Custom Error Classes
  *
- * Implements the circuit breaker pattern to prevent cascading failures.
- * States: CLOSED (normal) -> OPEN (failing) -> HALF_OPEN (testing) -> CLOSED
+ * Provides a hierarchy of error types for the Spooled SDK.
  */
-
-/** Circuit breaker states */
-declare enum CircuitState {
-    /** Normal operation - requests flow through */
-    CLOSED = "CLOSED",
-    /** Circuit is open - requests are rejected immediately */
-    OPEN = "OPEN",
-    /** Testing state - limited requests allowed to test recovery */
-    HALF_OPEN = "HALF_OPEN"
-}
-/** Circuit breaker state change event */
-interface CircuitStateChange {
-    from: CircuitState;
-    to: CircuitState;
-    timestamp: Date;
-    failureCount: number;
-}
-/** Circuit breaker options */
-interface CircuitBreakerOptions extends CircuitBreakerConfig {
-    /** Callback when state changes */
-    onStateChange?: (event: CircuitStateChange) => void;
-    /** Custom function to determine if an error should count as a failure */
-    isFailure?: (error: Error) => boolean;
+/** Error response body from the API */
+interface ApiErrorBody {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
 }
 /**
- * Circuit Breaker implementation
+ * Rate limit information parsed from headers.
  *
- * Tracks failures and prevents requests when the failure threshold is reached.
+ * Authenticated responses that went through the plan rate limiter carry
+ * `X-RateLimit-Limit`, `-Remaining`, `-Reset` and `-Scope` (API 0.1.122+); a
+ * 429 adds `Retry-After`. Every field is optional: the headers are left out
+ * when no rate-limit check ran (public and admin routes, a server without
+ * Redis, older servers).
  */
-declare class CircuitBreaker {
-    private state;
-    private failureCount;
-    private successCount;
-    private lastFailureTime;
-    private readonly config;
-    constructor(config: CircuitBreakerOptions);
-    /**
-     * Get current circuit state
-     */
-    getState(): CircuitState;
-    /**
-     * Check if circuit breaker is enabled
-     */
-    isEnabled(): boolean;
+interface RateLimitInfo {
     /**
-     * Check if requests are currently allowed
-     */
-    isAllowed(): boolean;
-    /**
-     * Record a successful request
+     * The limit the other fields describe: the plan burst (organization token
+     * bucket) or an API key's own requests per minute.
      */
-    recordSuccess(): void;
-    /**
-     * Record a failed request
-     */
-    recordFailure(error: Error): void;
+    limit?: number;
+    /** Whole requests left after this one */
+    remaining?: number;
     /**
-     * Transition to a new state
+     * When `remaining` next goes up (`X-RateLimit-Reset`, a Unix time in
+     * seconds; the current time while the bucket is full).
      */
-    private transitionTo;
+    reset?: Date;
+    /** Seconds to wait before retrying (`Retry-After`, on a 429) */
+    retryAfter?: number;
     /**
-     * Reset the circuit breaker to closed state
+     * Which limit the headers describe (`X-RateLimit-Scope`): `organization`
+     * (the plan's token bucket) or `api_key` (the key's `rateLimit`).
      */
-    reset(): void;
-    /**
-     * Execute a function with circuit breaker protection
+    scope?: "organization" | "api_key" | (string & {});
+}
+/**
+ * Base error class for all Spooled SDK errors
+ */
+declare class SpooledError extends Error {
+    /** HTTP status code (if applicable) */
+    readonly statusCode: number;
+    /** Error code from API response */
+    readonly code: string;
+    /** Additional error details */
+    readonly details?: Record<string, unknown>;
+    /** Request ID for debugging */
+    readonly requestId?: string;
+    /** Original cause of the error */
+    readonly cause?: Error;
+    constructor(message: string, statusCode?: number, code?: string, details?: Record<string, unknown>, requestId?: string, cause?: Error);
+    /**
+     * Whether this error is retryable.
      *
-     * @param fn - Async function to execute
-     * @returns Promise resolving to the function result
-     * @throws CircuitBreakerOpenError if circuit is open
+     * Only 408 (Request Timeout) is retryable among the plain 4xx statuses: the
+     * server gave up waiting for the request, so it never ran. Subclasses
+     * override this (5xx, network, timeout, rate limit).
      */
-    execute<T>(fn: () => Promise<T>): Promise<T>;
+    isRetryable(): boolean;
+    /** Convert to plain object for logging */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Authentication error (401)
+ * Thrown when authentication fails (invalid/expired token or API key)
+ */
+declare class AuthenticationError extends SpooledError {
+    constructor(message?: string, code?: string, details?: Record<string, unknown>, requestId?: string);
+}
+/**
+ * Authorization error (403)
+ * Thrown when the authenticated user lacks permission
+ */
+declare class AuthorizationError extends SpooledError {
+    constructor(message?: string, code?: string, details?: Record<string, unknown>, requestId?: string);
+}
+/**
+ * Not found error (404)
+ * Thrown when a requested resource doesn't exist
+ */
+declare class NotFoundError extends SpooledError {
+    constructor(message?: string, code?: string, details?: Record<string, unknown>, requestId?: string);
+}
+/**
+ * Conflict error (409)
+ * Thrown when there's a conflict (e.g., duplicate resource)
+ */
+declare class ConflictError extends SpooledError {
+    constructor(message?: string, code?: string, details?: Record<string, unknown>, requestId?: string);
+}
+/**
+ * Validation error (400 or 422)
+ * Thrown when request validation fails.
+ *
+ * The API answers a field-rule failure (length, range) with 400 but a missing
+ * or mistyped JSON field with 422; both are the caller's request being invalid,
+ * so both surface as this class. `statusCode` tells them apart.
+ */
+declare class ValidationError extends SpooledError {
+    constructor(message?: string, code?: string, details?: Record<string, unknown>, requestId?: string, statusCode?: 400 | 422);
+}
+/**
+ * Payload too large error (413)
+ * Thrown when request body exceeds size limit
+ */
+declare class PayloadTooLargeError extends SpooledError {
+    constructor(message?: string, code?: string, details?: Record<string, unknown>, requestId?: string);
+}
+/**
+ * Rate limit error (429)
+ * Thrown when rate limit is exceeded, or a plan quota is (see `isQuota`)
+ */
+declare class RateLimitError extends SpooledError {
+    /** Rate limit information */
+    readonly rateLimitInfo: RateLimitInfo;
+    constructor(message?: string, code?: string, rateLimitInfo?: RateLimitInfo, details?: Record<string, unknown>, requestId?: string);
     /**
-     * Get circuit breaker statistics
+     * True when this 429 is a plan quota or limit (daily job cap, active jobs,
+     * queue/worker/webhook caps) rather than per-second rate limiting.
+     *
+     * A quota does not clear for minutes or hours, so retrying it only blocks the
+     * caller for the whole backoff and, via the circuit breaker, takes every
+     * other call on the client down with it. It is never retried and never
+     * counted as a circuit breaker failure.
+     *
+     * Detection: the `QUOTA_EXCEEDED` code, or, for older plan-limit paths that
+     * answer with plain text wrapped as `RATE_LIMIT_EXCEEDED`, a "... limit
+     * reached" message that carries no `Retry-After`.
      */
-    getStats(): {
-        state: CircuitState;
-        failureCount: number;
-        successCount: number;
-        lastFailureTime: Date | null;
-        config: CircuitBreakerConfig;
-    };
+    get isQuota(): boolean;
+    isRetryable(): boolean;
+    /** Get the number of seconds to wait before retrying */
+    getRetryAfter(): number;
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Server error (5xx)
+ * Thrown when the server encounters an error
+ */
+declare class ServerError extends SpooledError {
+    constructor(message?: string, statusCode?: number, code?: string, details?: Record<string, unknown>, requestId?: string);
+    isRetryable(): boolean;
+}
+/**
+ * Network error
+ * Thrown when a network request fails (no response received)
+ */
+declare class NetworkError extends SpooledError {
+    constructor(message?: string, cause?: Error);
+    isRetryable(): boolean;
+}
+/**
+ * Timeout error
+ * Thrown when a request times out
+ */
+declare class TimeoutError extends SpooledError {
+    /** Timeout duration in milliseconds */
+    readonly timeoutMs: number;
+    constructor(message?: string, timeoutMs?: number);
+    isRetryable(): boolean;
+}
+/**
+ * Circuit breaker open error
+ * Thrown when the circuit breaker is open and rejecting requests
+ */
+declare class CircuitBreakerOpenError extends SpooledError {
+    constructor(message?: string);
+    isRetryable(): boolean;
+}
+/**
+ * Unsupported operation error
+ * Thrown by SDK methods whose route the Spooled API does not provide (or
+ * always rejects). It is raised before any network call, so code that still
+ * calls such a method fails loudly with an explanation instead of a 404.
+ */
+declare class UnsupportedOperationError extends SpooledError {
+    /** The SDK method that is not supported, e.g. `ingest.github` */
+    readonly operation: string;
+    constructor(operation: string, reason: string);
 }
 /**
- * Create a circuit breaker instance from configuration
+ * Parse rate limit headers from a Response
+ */
+declare function parseRateLimitHeaders(headers: Headers): RateLimitInfo;
+/**
+ * Create an appropriate error from an HTTP response
+ */
+declare function createErrorFromResponse(response: Response): Promise<SpooledError>;
+/**
+ * Check if an error is a SpooledError instance
+ */
+declare function isSpooledError(error: unknown): error is SpooledError;
+/**
+ * Check if an error is retryable
  */
-declare function createCircuitBreaker(config: CircuitBreakerConfig): CircuitBreaker;
+declare function isRetryableError(error: unknown): boolean;
 
 /**
  * HTTP Client Utility
@@ -262,6 +487,20 @@ interface HttpRequestOptions {
     skipResponseConversion?: boolean;
     /** Whether to skip retry logic */
     skipRetry?: boolean;
+    /**
+     * The request is safe to replay even though it is a POST/PATCH, so network
+     * errors, timeouts, 5xx and 408 are retried like they are for a GET.
+     *
+     * Use it only for calls the server makes idempotent: lease-fenced job and
+     * worker acks (complete/fail/heartbeat answer a replay with 409) and job
+     * creation with an idempotency key (the server returns the existing job).
+     */
+    idempotent?: boolean;
+    /**
+     * Never try to refresh the access token when this request gets a 401.
+     * Set on the auth calls that the refresh itself makes.
+     */
+    skipAuthRefresh?: boolean;
     /** Optional abort signal */
     signal?: AbortSignal;
 }
@@ -287,13 +526,25 @@ declare class HttpClient {
     private authToken;
     /** Optional function to mint a fresh access token (set when auto-refresh is enabled) */
     private refreshTokenFn;
-    /** Guard to prevent a refresh request from recursively triggering another refresh */
-    private isRefreshing;
+    /**
+     * The refresh currently in flight, shared by every request that gets a 401
+     * meanwhile. A boolean guard here made the second concurrent 401 skip the
+     * refresh and fail even though the token was about to be replaced.
+     */
+    private refreshInFlight;
+    /** Rate-limit headers of the most recent response that carried them */
+    private lastRateLimit;
     constructor(config: ResolvedConfig, circuitBreaker: CircuitBreaker);
     /**
      * Set the authentication token
      */
     setAuthToken(token: string): void;
+    /**
+     * The `X-RateLimit-*` (and `Retry-After`) values of the most recent
+     * response that carried them, successful or not. `undefined` until such a
+     * response arrives. With concurrent requests it is the last one to finish.
+     */
+    getLastRateLimitInfo(): RateLimitInfo | undefined;
     /**
      * Set the token refresh function.
      *
@@ -301,6 +552,13 @@ declare class HttpClient {
      * refresh + retry of the original request with the new token.
      */
     setRefreshTokenFn(fn: () => Promise<string>): void;
+    /**
+     * Refresh the access token once for all callers.
+     *
+     * Resolves true when a new token is installed, false when the refresh failed
+     * (the caller then surfaces its original 401).
+     */
+    private refreshAuthToken;
     /**
      * Build full URL with query parameters
      */
@@ -317,6 +575,8 @@ declare class HttpClient {
      * Execute a single HTTP request (no retry)
      */
     private executeRequest;
+    /** Remember the rate-limit headers of a response that has them. */
+    private recordRateLimit;
     /**
      * Make an HTTP request with retry and circuit breaker
      */
@@ -329,12 +589,13 @@ declare class HttpClient {
     /**
      * Resolve the retry configuration for a request.
      *
-     * Idempotent methods (GET/PUT/DELETE) and any request carrying an
-     * idempotency key retry normally. Non-idempotent methods (POST/PATCH)
-     * without an idempotency key must NOT be retried on ambiguous failures
+     * Idempotent methods (GET/PUT/DELETE), any request carrying an idempotency
+     * key and any request marked `idempotent` retry normally. Non-idempotent
+     * methods (POST/PATCH) otherwise must NOT be retried on ambiguous failures
      * (network/timeout/5xx) — doing so risks duplicate jobs, double claims,
-     * etc. They are still retried on 429, which is rejected before the
-     * server processes the request and is therefore side-effect-free.
+     * etc. They are still retried on a rate-limit 429, which is rejected before
+     * the server processes the request and is therefore side-effect-free. A
+     * quota 429 is never retried: it does not clear for hours.
      */
     private resolveRetryConfig;
     /**
@@ -509,8 +770,32 @@ type PlanTier = "free" | "starter" | "pro" | "enterprise";
 type ScheduleRunStatus = "pending" | "running" | "completed" | "failed";
 /** Webhook delivery status */
 type WebhookDeliveryStatus = "pending" | "success" | "failed";
-/** Webhook event types */
-type WebhookEventType = "job.created" | "job.started" | "job.completed" | "job.failed" | "job.cancelled" | "queue.paused" | "queue.resumed" | "worker.registered" | "worker.deregistered" | "schedule.triggered";
+/**
+ * Webhook event types.
+ *
+ * `job.deadlettered`, `job.retried`, `workflow.completed` and
+ * `workflow.failed` need API 0.1.122 or later. The SDK does not check event
+ * names in responses: a name newer than this list is passed through as a
+ * string, so give a `switch` over it a `default` branch.
+ */
+type WebhookEventType = "job.created" | "job.started" | "job.completed" | "job.failed" | "job.cancelled" | "queue.paused" | "queue.resumed" | "worker.registered" | "worker.deregistered" | "schedule.triggered"
+/** Sent next to every `job.failed` whose `data.status` is `deadletter`. */
+ | "job.deadlettered"
+/** A manual retry (job, DLQ or workflow retry) put the job back to pending. */
+ | "job.retried"
+/** A workflow finished; announced at most once, up to ~10 s late. */
+ | "workflow.completed"
+/** A workflow failed; announced at most once, up to ~10 s late. */
+ | "workflow.failed";
+/**
+ * Body format of an outgoing webhook (API 0.1.122+).
+ *
+ * `json` (the default) is the signed JSON envelope. `slack`, `discord` and
+ * `teams` send one short chat message built from the event, so a chat
+ * service's incoming-webhook URL can be used as it is (`teams` is the legacy
+ * Office 365 connector `MessageCard`; Teams Workflows URLs reject it).
+ */
+type WebhookFormat = "json" | "slack" | "discord" | "teams";
 /** Dependency mode for workflows */
 type DependencyMode = "all" | "any";
 /** Pagination parameters */
@@ -540,6 +825,22 @@ interface PaginatedResponse<T> {
     /** Whether there are more results */
     hasMore: boolean;
 }
+/**
+ * One page of a list endpoint that reports `X-Has-More` (API 0.1.122+):
+ * `GET /jobs`, `GET /jobs/dlq` and `GET /jobs/{id}/history`.
+ *
+ * The response body stays a bare array; `hasMore` comes from the header.
+ */
+interface ListPage<T> {
+    /** Items of this page, in the server's order */
+    data: T[];
+    /**
+     * `true` when another page follows: ask again with
+     * `offset + data.length`. From the `X-Has-More` header; an older server
+     * without it gets a guess from the page size (a full page means "maybe").
+     */
+    hasMore: boolean;
+}
 /**
  * Helper to create a paginated response from an array
  */
@@ -624,18 +925,44 @@ interface CreateJobParams {
     parentJobId?: string;
     /** Webhook URL for completion notification */
     completionWebhook?: string;
+    /** HMAC secret used to sign the `completionWebhook` request (never returned by the API) */
+    completionWebhookSecret?: string;
 }
 /** Result of creating a job */
 interface CreateJobResult {
     id: string;
     created: boolean;
 }
+/**
+ * Server-side job search filters (API 0.1.122+), shared by `GET /jobs` and
+ * `GET /jobs/dlq`. All filters combine with AND. An invalid value is a 400
+ * `ValidationError`; an older server ignores them.
+ */
+interface JobSearchParams {
+    /**
+     * Search text, case-insensitive: matches a job whose id starts with it, or
+     * whose queue name or `payload.job_type` contains it (at most 255 bytes).
+     */
+    q?: string;
+    /** Exact `payload.job_type` (at most 255 bytes) */
+    jobType?: string;
+    /**
+     * Only jobs created at or after this instant. A `Date` is sent as an
+     * ISO 8601 UTC string; a string must be RFC 3339.
+     */
+    createdAfter?: Date | string;
+    /** Only jobs created before this instant (exclusive); see `createdAfter` */
+    createdBefore?: Date | string;
+}
 /** Parameters for listing jobs */
-interface ListJobsParams extends ListParams {
+interface ListJobsParams extends ListParams, JobSearchParams {
     /** Filter by queue name */
     queueName?: string;
-    /** Filter by status */
-    status?: JobStatus;
+    /**
+     * Filter by status: one status, or several (sent as the comma list
+     * `status=failed,deadletter`, which needs API 0.1.122+).
+     */
+    status?: JobStatus | readonly JobStatus[];
     /** Filter by a single tag (matches Postgres `tags ? tag` semantics) */
     tag?: string;
 }
@@ -669,10 +996,9 @@ interface ClaimedJob {
     timeoutSeconds: number;
     leaseExpiresAt?: string;
     /**
-     * Lease fencing token for this claim. Echo it back on
-     * complete/fail/heartbeat so the operation applies only to the lease this
-     * worker actually holds (backend rejects stale leases with 409
-     * LEASE_EXPIRED). Omitted = legacy behavior.
+     * Lease fencing token for this claim. Send it back on
+     * complete/fail/heartbeat: the API requires it (a call without it is a 422
+     * `ValidationError`, since 2026-07) and rejects a stale lease with 409.
      */
     leaseId?: string | null;
 }
@@ -697,7 +1023,10 @@ interface CompleteJobParams {
     workerId: string;
     /** Optional result payload (any JSON) */
     result?: JsonValue;
-    /** Lease fencing token from the claimed job (rejects stale leases when set) */
+    /**
+     * Lease fencing token from the claimed job (`ClaimedJob.leaseId`). The API
+     * requires it: without it the call is a 422 `ValidationError`.
+     */
     leaseId?: string;
 }
 /** Parameters for failing a job */
@@ -706,7 +1035,10 @@ interface FailJobParams {
     workerId: string;
     /** Error message (1-2048 chars) */
     error: string;
-    /** Lease fencing token from the claimed job (rejects stale leases when set) */
+    /**
+     * Lease fencing token from the claimed job (`ClaimedJob.leaseId`). The API
+     * requires it: without it the call is a 422 `ValidationError`.
+     */
     leaseId?: string;
 }
 /** Parameters for job heartbeat */
@@ -715,7 +1047,10 @@ interface HeartbeatJobParams {
     workerId: string;
     /** Lease duration in seconds (5-3600) */
     leaseDurationSecs: number;
-    /** Lease fencing token from the claimed job (rejects stale leases when set) */
+    /**
+     * Lease fencing token from the claimed job (`ClaimedJob.leaseId`). The API
+     * requires it: without it the call is a 422 `ValidationError`.
+     */
     leaseId?: string;
 }
 /** Response for priority boost */
@@ -760,10 +1095,37 @@ interface BulkEnqueueResponse {
     failureCount: number;
 }
 /** Parameters for listing DLQ */
-interface ListDlqParams extends ListParams {
+interface ListDlqParams extends ListParams, JobSearchParams {
     /** Filter by queue name */
     queueName?: string;
 }
+/**
+ * Event types of `GET /jobs/{id}/history`. The server records `processing`
+ * (REST claim), `completed` (REST complete), `retry_scheduled` and
+ * `deadlettered` (REST fail, scheduler sweeps); `created` is defined but not
+ * written today, and jobs settled over gRPC have sparse history. Any other
+ * string the server sends is passed through.
+ */
+type JobHistoryEventType = "created" | "processing" | "completed" | "retry_scheduled" | "deadlettered" | (string & {});
+/** One recorded lifecycle event of a job (`GET /jobs/{id}/history`) */
+interface JobHistoryEvent {
+    id: string;
+    jobId: string;
+    eventType: JobHistoryEventType;
+    /** The worker that caused the event, when known */
+    workerId?: string | null;
+    /**
+     * Event details as stored (any JSON, keys left in snake_case as the server
+     * wrote them).
+     */
+    details: JsonValue;
+    createdAt: string;
+}
+/** Parameters for `jobs.history()` (API 0.1.122+) */
+interface JobHistoryParams extends PaginationParams {
+    /** `asc` (default, oldest first) or `desc` (newest first) */
+    order?: "asc" | "desc";
+}
 /** Parameters for retrying DLQ jobs */
 interface RetryDlqParams {
     /** Specific job IDs to retry */
@@ -802,6 +1164,11 @@ interface PurgeDlqResponse {
 interface DlqOperations {
     /** List jobs in dead-letter queue */
     list(params?: ListDlqParams): Promise<JobSummary[]>;
+    /**
+     * List one page of the dead-letter queue with `hasMore` from the
+     * `X-Has-More` header (API 0.1.122+).
+     */
+    listPage(params?: ListDlqParams): Promise<ListPage<JobSummary>>;
     /** Retry jobs from DLQ */
     retry(params: RetryDlqParams): Promise<RetryDlqResponse>;
     /** Purge jobs from DLQ */
@@ -822,8 +1189,33 @@ declare class JobsResource {
     createAndGet(params: CreateJobParams): Promise<Job>;
     /**
      * List jobs with optional filtering
+     *
+     * `status` takes one status or several, and `q`, `jobType`, `createdAfter`
+     * and `createdBefore` filter on the server (API 0.1.122+). Use
+     * {@link JobsResource.listPage} to also learn whether another page follows.
      */
     list(params?: ListJobsParams): Promise<JobSummary[]>;
+    /**
+     * List one page of jobs with `hasMore` from the `X-Has-More` header
+     * (API 0.1.122+). Takes the same filters as {@link JobsResource.list}.
+     *
+     * @example
+     * ```typescript
+     * let offset = 0;
+     * for (;;) {
+     *   const page = await client.jobs.listPage({
+     *     status: ["failed", "deadletter"],
+     *     createdAfter: new Date(Date.now() - 86_400_000),
+     *     limit: 100,
+     *     offset,
+     *   });
+     *   handle(page.data);
+     *   if (!page.hasMore) break;
+     *   offset += page.data.length;
+     * }
+     * ```
+     */
+    listPage(params?: ListJobsParams): Promise<ListPage<JobSummary>>;
     /**
      * Get a job by ID
      */
@@ -840,6 +1232,21 @@ declare class JobsResource {
      * Boost job priority
      */
     boostPriority(id: string, priority: number): Promise<BoostPriorityResponse>;
+    /**
+     * Get the recorded lifecycle events of a job (`GET /jobs/{id}/history`,
+     * API 0.1.122+), oldest first unless `order: "desc"`.
+     *
+     * The history is sparse: the server records REST claims (`processing`),
+     * completions (`completed`) and failures (`retry_scheduled`,
+     * `deadlettered`) and the scheduler's dead-letter sweeps, so a job settled
+     * over gRPC may have few or no events. An unknown job is a `NotFoundError`.
+     */
+    history(id: string, params?: JobHistoryParams): Promise<JobHistoryEvent[]>;
+    /**
+     * One page of {@link JobsResource.history} with `hasMore` from the
+     * `X-Has-More` header. `limit` defaults to 100 (at most 500).
+     */
+    historyPage(id: string, params?: JobHistoryParams): Promise<ListPage<JobHistoryEvent>>;
     /**
      * Get job statistics
      */
@@ -858,12 +1265,20 @@ declare class JobsResource {
     claim(params: ClaimJobsParams): Promise<ClaimJobsResult>;
     /**
      * Complete a job (worker ack)
+     *
+     * Lease-fenced and idempotent on the server, so a network error, timeout or
+     * 5xx is retried: a lost ack would otherwise re-run a finished job.
      */
     complete(id: string, params: CompleteJobParams): Promise<{
         success: boolean;
     }>;
     /**
      * Fail a job (worker nack)
+     *
+     * `params.error` is made acceptable first: empty text becomes "Job failed"
+     * and text over 2048 characters is truncated, because the API rejects both
+     * with a 400 that would leave the job processing until its lease expires.
+     * Retried like {@link JobsResource.complete}.
      */
     fail(id: string, params: FailJobParams): Promise<{
         success: boolean;
@@ -871,11 +1286,16 @@ declare class JobsResource {
     }>;
     /**
      * Extend job lease (heartbeat)
+     *
+     * Retried like {@link JobsResource.complete}: with the default 30 s lease and
+     * 15 s heartbeat, one lost heartbeat leaves no slack.
      */
     heartbeat(id: string, params: HeartbeatJobParams): Promise<{
         success: boolean;
     }>;
     private listDlq;
+    private listDlqPage;
+    private listSummaries;
     private retryDlq;
     private purgeDlq;
 }
@@ -946,6 +1366,14 @@ interface ResumeQueueResponse {
     resumed: boolean;
     pausedDurationSecs: number;
 }
+/** Options for deleting a queue */
+interface DeleteQueueOptions {
+    /**
+     * Also delete every job (and dead-letter row) of the queue. Required to
+     * delete a queue with pending/processing jobs or one without a stored config.
+     */
+    deleteJobs?: boolean;
+}
 
 /**
  * Queues Resource
@@ -982,8 +1410,14 @@ declare class QueuesResource {
     resume(name: string): Promise<ResumeQueueResponse>;
     /**
      * Delete a queue configuration
+     *
+     * Without `deleteJobs` the API only deletes an explicit queue config of an
+     * idle queue, and answers 409 otherwise: a queue that exists only because
+     * jobs were posted to it has no config to delete, and a queue with pending
+     * or processing jobs is not idle. Pass `{ deleteJobs: true }` to delete the
+     * queue's jobs (and DLQ rows) along with it.
      */
-    delete(name: string): Promise<void>;
+    delete(name: string, options?: DeleteQueueOptions): Promise<void>;
 }
 
 /**
@@ -1012,6 +1446,17 @@ interface Worker {
     registeredAt: string;
     /** Last row update (detail response). */
     updatedAt?: string;
+    /**
+     * Jobs this worker completed while it held the lease (API 0.1.122+; counts
+     * start at 0 with that release).
+     */
+    jobsProcessed?: number;
+    /**
+     * Failed attempts this worker reported while it held the lease: a fail
+     * that was retried or dead-lettered (API 0.1.122+). Lease-expiry recovery
+     * does not count.
+     */
+    jobsFailed?: number;
 }
 /** Worker summary for list responses */
 interface WorkerSummary {
@@ -1022,6 +1467,10 @@ interface WorkerSummary {
     currentJobs: number;
     maxConcurrency: number;
     lastHeartbeat: string;
+    /** See {@link Worker.jobsProcessed} (API 0.1.122+). */
+    jobsProcessed?: number;
+    /** See {@link Worker.jobsFailed} (API 0.1.122+). */
+    jobsFailed?: number;
 }
 /** Parameters for registering a worker */
 interface RegisterWorkerParams {
@@ -1090,6 +1539,8 @@ declare class WorkersResource {
     register(params: RegisterWorkerParams): Promise<RegisterWorkerResponse>;
     /**
      * Send worker heartbeat
+     *
+     * Idempotent on the server, so network errors, timeouts and 5xx are retried.
      */
     heartbeat(id: string, params: WorkerHeartbeatParams): Promise<void>;
     /**
@@ -1359,8 +1810,12 @@ interface WorkflowJob {
     id: string;
     /** Workflow ID this job belongs to */
     workflowId: string;
-    /** Job key within the workflow */
-    key: string;
+    /**
+     * Job key within the workflow. The API does not return it (a job stores only
+     * its workflow step), so this is undefined today; take the key to job ID
+     * mapping from the `jobIds` of `workflows.create()`.
+     */
+    key?: string;
     /** Queue name */
     queueName: string;
     /** Current job status */
@@ -1392,8 +1847,8 @@ interface WorkflowJob {
 interface WorkflowJobStatus {
     /** Job ID */
     jobId: string;
-    /** Job key within the workflow */
-    key: string;
+    /** Job key within the workflow; undefined, see {@link WorkflowJob.key} */
+    key?: string;
     /** Current status */
     status: string;
     /** Progress percentage (0-100) */
@@ -1415,7 +1870,7 @@ interface WorkflowJobOperations {
      * @example
      * ```typescript
      * const jobs = await client.workflows.jobs.list('wf_123');
-     * console.log('Jobs:', jobs.map(j => j.key));
+     * console.log('Jobs:', jobs.map(j => j.id));
      * ```
      */
     list(workflowId: string): Promise<WorkflowJob[]>;
@@ -1434,14 +1889,16 @@ interface WorkflowJobOperations {
     /**
      * Get the status of all jobs in a workflow.
      *
-     * Returns a summary of each job's status and progress.
+     * Returns a summary of each job's status. The API does not store or return
+     * the `key` a job was created with, so `key` is undefined; map keys to job
+     * IDs from the `jobIds` array that `workflows.create()` returns.
      *
      * @param workflowId - The workflow ID
      * @example
      * ```typescript
      * const statuses = await client.workflows.jobs.getStatus('wf_123');
      * for (const s of statuses) {
-     *   console.log(`${s.key}: ${s.status}`);
+     *   console.log(`${s.jobId}: ${s.status}`);
      * }
      * ```
      */
@@ -1538,6 +1995,12 @@ interface OutgoingWebhook {
      * it is re-enabled with `update(id, { enabled: true })`.
      */
     lastStatus?: "success" | "failed" | "auto_disabled";
+    /**
+     * Body format of the deliveries (API 0.1.122+; absent from older servers,
+     * which only send `json`). A format newer than this SDK is passed through
+     * as a string.
+     */
+    format?: WebhookFormat | (string & {});
     createdAt: string;
     updatedAt: string;
 }
@@ -1553,6 +2016,11 @@ interface CreateOutgoingWebhookParams {
     secret?: string;
     /** Whether enabled (default: true) */
     enabled?: boolean;
+    /**
+     * Body format (default `json`; API 0.1.122+). `slack`, `discord` and
+     * `teams` post a chat message to that service's incoming-webhook URL.
+     */
+    format?: WebhookFormat;
 }
 /**
  * Parameters for updating an outgoing webhook.
@@ -1583,6 +2051,8 @@ interface UpdateOutgoingWebhookParams {
      * `QUOTA_EXCEEDED` even though no webhook is being created.
      */
     enabled?: boolean;
+    /** New body format; omit it to keep the current one (API 0.1.122+). */
+    format?: WebhookFormat;
 }
 /** Response for webhook test */
 interface TestWebhookResponse {
@@ -1951,14 +2421,12 @@ declare class OrganizationsResource {
     /**
      * Clear/delete the webhook token for the current organization.
      *
-     * POST /organizations/webhook-token/clear requires `{ confirm: true }`.
-     * An empty body 422s. The API currently rejects the operation and tells
-     * callers to use regenerateWebhookToken() instead.
-     *
-     * @example
-     * ```typescript
-     * await client.organizations.clearWebhookToken();
-     * ```
+     * @deprecated The API refuses this operation on purpose (an org without a
+     * webhook token would have an open public ingestion endpoint) and always
+     * answers with an error. This method now throws
+     * {@link UnsupportedOperationError} without a network call; rotate the token
+     * with {@link OrganizationsResource.regenerateWebhookToken} instead. It will
+     * be removed in the next major release.
      */
     clearWebhookToken(): Promise<void>;
 }
@@ -2271,8 +2739,9 @@ declare class AdminResource {
 /**
  * Webhook Ingestion Types
  *
- * These endpoints are primarily intended to be called by external webhook providers (GitHub/Stripe)
- * and are authenticated via signatures (not API keys).
+ * The custom endpoint is called by external webhook providers and is
+ * authenticated by the org webhook token (not an API key). The GitHub and
+ * Stripe option types are kept only so existing code still compiles.
  */
 
 interface IngestCustomWebhookParams {
@@ -2288,6 +2757,39 @@ interface IngestCustomWebhookResponse {
     queueName?: string;
     status?: string;
 }
+/** `status` of an inbound webhook log entry */
+type InboundDeliveryStatus = "created" | "duplicate";
+/** Parameters for `ingest.listDeliveries()` (`GET /webhooks/deliveries`) */
+interface ListInboundDeliveriesParams extends PaginationParams {
+    /** `created` (a new job) or `duplicate` (an idempotent replay) */
+    status?: InboundDeliveryStatus;
+    /**
+     * Only entries received at or after this instant. A `Date` is sent as an
+     * ISO 8601 UTC string; a string must be RFC 3339.
+     */
+    since?: Date | string;
+    /** Only entries whose job went to this queue (exact match) */
+    queueName?: string;
+}
+/**
+ * One accepted request to `POST /webhooks/{org_id}/custom`, from the inbound
+ * webhook log (API 0.1.122+). The log never holds the payload or a signature.
+ */
+interface InboundWebhookDelivery {
+    id: string;
+    /** `custom` today */
+    provider: string;
+    /** The request's event type, `custom` when it had none */
+    eventType: string;
+    /** Queue of the job the request resolved to */
+    matchedQueue: string | null;
+    /** Job the request created or matched (`null` for entries before 0.1.122) */
+    jobId: string | null;
+    /** `created` or `duplicate` (`null` for entries before 0.1.122) */
+    status: InboundDeliveryStatus | (string & {}) | null;
+    createdAt: string;
+}
+/** @deprecated The API has no GitHub webhook route; `ingest.github` throws. */
 interface IngestGitHubWebhookOptions {
     /** Value for X-GitHub-Event header (e.g. "pull_request") */
     githubEvent: string;
@@ -2300,6 +2802,7 @@ interface IngestGitHubWebhookOptions {
     /** If provided, the SDK will compute the signature for you */
     secret?: string;
 }
+/** @deprecated The API has no Stripe webhook route; `ingest.stripe` throws. */
 interface IngestStripeWebhookOptions {
     /** Optional org-scoped webhook token (X-Webhook-Token) */
     webhookToken?: string;
@@ -2316,8 +2819,9 @@ interface IngestStripeWebhookOptions {
 /**
  * Webhook Ingestion Resource
  *
- * These endpoints are intended for webhook providers (GitHub/Stripe/custom) to enqueue jobs.
- * They are authenticated via signatures (not API keys).
+ * The Spooled API ingests webhooks on one route:
+ * `POST /api/v1/webhooks/{org_id}/custom`, authenticated by the org's webhook
+ * token. The GitHub and Stripe routes were removed from the API.
  */
 
 declare class WebhookIngestionResource {
@@ -2326,15 +2830,23 @@ declare class WebhookIngestionResource {
     /**
      * Ingest a GitHub webhook.
      *
-     * POST /api/v1/webhooks/{org_id}/github
+     * @deprecated The API has no `/webhooks/{org_id}/github` route (it always
+     * answered 404). This method now throws {@link UnsupportedOperationError}
+     * without a network call; point the GitHub webhook at `ingest.custom` /
+     * `POST /api/v1/webhooks/{org_id}/custom` instead. It will be removed in the
+     * next major release.
      */
-    github(orgId: string, body: string | Uint8Array | ArrayBuffer, options: IngestGitHubWebhookOptions): Promise<void>;
+    github(_orgId: string, _body: string | Uint8Array | ArrayBuffer, _options: IngestGitHubWebhookOptions): Promise<void>;
     /**
      * Ingest a Stripe webhook.
      *
-     * POST /api/v1/webhooks/{org_id}/stripe
+     * @deprecated The API has no `/webhooks/{org_id}/stripe` route (it always
+     * answered 404). This method now throws {@link UnsupportedOperationError}
+     * without a network call; point the Stripe webhook at `ingest.custom` /
+     * `POST /api/v1/webhooks/{org_id}/custom` instead. It will be removed in the
+     * next major release.
      */
-    stripe(orgId: string, body: string | Uint8Array | ArrayBuffer, options?: IngestStripeWebhookOptions): Promise<void>;
+    stripe(_orgId: string, _body: string | Uint8Array | ArrayBuffer, _options?: IngestStripeWebhookOptions): Promise<void>;
     /**
      * Ingest a custom webhook.
      *
@@ -2345,6 +2857,17 @@ declare class WebhookIngestionResource {
         webhookToken?: string;
         forwardedProto?: string;
     }): Promise<IngestCustomWebhookResponse>;
+    /**
+     * The inbound webhook log: accepted requests to
+     * `POST /webhooks/{org_id}/custom`, newest first
+     * (`GET /webhooks/deliveries`, API 0.1.122+).
+     *
+     * Needs an API key without a queue restriction (a queue-scoped key gets a
+     * 403 `AuthorizationError`). Entries carry no payload and no signature;
+     * requests that were rejected are not logged. `limit` defaults to 50 (at
+     * most 100); an invalid filter is a 400 `ValidationError`.
+     */
+    listDeliveries(params?: ListInboundDeliveriesParams): Promise<InboundWebhookDelivery[]>;
 }
 
 /**
@@ -2758,8 +3281,11 @@ interface GrpcCompleteRequest {
     workerId: string;
     /** Result as object (will be converted to google.protobuf.Struct) */
     result?: Record<string, unknown>;
-    /** Lease fencing token from the dequeued job (proto `lease_id`) */
-    leaseId?: string;
+    /**
+     * Lease fencing token from the dequeued job (proto `lease_id`). Required: the
+     * server rejects a settlement without it with INVALID_ARGUMENT.
+     */
+    leaseId: string;
 }
 /** Complete response */
 interface GrpcCompleteResponse {
@@ -2770,9 +3296,20 @@ interface GrpcFailRequest {
     jobId: string;
     workerId: string;
     error: string;
+    /**
+     * Retry the job (until its `maxRetries` run out) instead of dead-lettering it
+     * at once. Defaults to `true`, which the SDK sends explicitly, so servers
+     * from before proto field 4 became `optional bool` (where an absent field
+     * read as `false` and dead-lettered the job on its first failure) behave the
+     * same. Pass `false` to dead-letter the job now, whatever `maxRetries` says:
+     * the SDK puts `retry = false` on the wire with field presence.
+     */
     retry?: boolean;
-    /** Lease fencing token from the dequeued job (proto `lease_id`) */
-    leaseId?: string;
+    /**
+     * Lease fencing token from the dequeued job (proto `lease_id`). Required: the
+     * server rejects a settlement without it with INVALID_ARGUMENT.
+     */
+    leaseId: string;
 }
 /** Fail response */
 interface GrpcFailResponse {
@@ -2785,8 +3322,11 @@ interface GrpcRenewLeaseRequest {
     jobId: string;
     workerId: string;
     extensionSecs: number;
-    /** Lease fencing token from the dequeued job (proto `lease_id`) */
-    leaseId?: string;
+    /**
+     * Lease fencing token from the dequeued job (proto `lease_id`). Required: the
+     * server rejects a renewal without it with INVALID_ARGUMENT.
+     */
+    leaseId: string;
 }
 /** Renew lease response */
 interface GrpcRenewLeaseResponse {
@@ -2851,6 +3391,17 @@ interface GrpcRegisterWorkerRequest {
     maxConcurrency?: number;
     version?: string;
     metadata?: Record<string, string>;
+    /**
+     * Stable worker id (proto `optional string worker_id = 7`): 1-128
+     * characters, letters, digits, `-`, `_` and `.`.
+     *
+     * Send the same id after a restart and the server updates that worker
+     * instead of adding one, so a restarting worker does not count twice against
+     * the plan's worker limit. Omitted or empty: the server assigns a new id. An
+     * id that another organization already uses fails with ALREADY_EXISTS
+     * (`ConflictError`). Servers older than API 0.1.119 ignore the field.
+     */
+    workerId?: string;
 }
 /** Register worker response */
 interface GrpcRegisterWorkerResponse {
@@ -3319,6 +3870,13 @@ declare class SpooledClient {
     /**
      * Exchange the API key for a JWT via /auth/login and cache the result.
      *
+     * The JWT belongs to the realtime transport only. It must NOT replace the
+     * REST bearer: an API-key client has no refresh token wired into its HTTP
+     * layer, so after the JWT's 24 h lifetime every REST call (claim, complete,
+     * heartbeat, create) would have failed with 401 for good. REST keeps using
+     * the API key; realtime re-mints its own JWT near expiry (see
+     * `getJwtToken`).
+     *
      * Concurrent callers share a single in-flight login so a burst of reconnects
      * (e.g. WebSocket and SSE at once) issues just one request.
      */
@@ -3339,6 +3897,15 @@ declare class SpooledClient {
      * Get current configuration (read-only)
      */
     getConfig(): Readonly<ResolvedConfig>;
+    /**
+     * Rate-limit state from the most recent response that carried
+     * `X-RateLimit-*` headers (API 0.1.122+): `limit`, `remaining`, `reset`
+     * (from the Unix-seconds header), `scope` and, after a 429, `retryAfter`.
+     * `undefined` until such a response arrives, and for servers or routes that
+     * do not send the headers. A 429 also carries the same values on
+     * `RateLimitError.rateLimitInfo`.
+     */
+    getRateLimitInfo(): RateLimitInfo | undefined;
     /**
      * Get circuit breaker statistics
      */
@@ -3416,7 +3983,10 @@ interface SpooledWorkerOptions {
     version?: string;
     /** Additional worker metadata */
     metadata?: JsonObject;
-    /** Graceful shutdown timeout in ms (default: 30000) */
+    /**
+     * Graceful shutdown timeout in ms (default: 30000): how long `stop()` lets
+     * running handlers finish before aborting and failing them.
+     */
     shutdownTimeout?: number;
 }
 /** Worker state */
@@ -3433,7 +4003,12 @@ interface JobContext {
     retryCount: number;
     /** Maximum retries */
     maxRetries: number;
-    /** Abort signal for graceful shutdown */
+    /**
+     * Abort signal. Aborted when the job exceeds its `timeoutSeconds` or when a
+     * stop outlives `shutdownTimeout`; NOT aborted merely because a stop was
+     * requested (the handler gets the grace period to finish and be acked).
+     * `signal.reason` carries the cause.
+     */
     signal: AbortSignal;
     /** Log local job progress (0-100); backend progress persistence is not yet available. */
     progress: (percent: number, message?: string) => Promise<void>;
@@ -3493,7 +4068,16 @@ interface ActiveJob {
     job: ClaimedJob;
     startedAt: Date;
     heartbeatTimer?: ReturnType<typeof setInterval>;
+    /** Fires when the job exceeds its `timeoutSeconds` */
+    timeoutTimer?: ReturnType<typeof setTimeout>;
     abortController: AbortController;
+    /**
+     * The outcome of this execution is decided (acked, or about to be): nothing
+     * else may ack it. Set when the handler settles or the shutdown fails it.
+     */
+    settled?: boolean;
+    /** The complete/fail request for this execution, once started. */
+    ack?: Promise<void>;
 }
 
 /**
@@ -3542,6 +4126,10 @@ declare class SpooledWorker {
     private pollTimer;
     private workerHeartbeatTimer;
     private shutdownPromise;
+    /** The claim request currently on the wire, so a stop can wait for its jobs. */
+    private pollInFlight;
+    /** Wakes the shutdown drain when the last active job has been acked. */
+    private drainWaiter;
     private eventHandlers;
     constructor(client: SpooledClient, options: SpooledWorkerOptions);
     /**
@@ -3565,7 +4153,15 @@ declare class SpooledWorker {
      */
     start(): Promise<void>;
     /**
-     * Stop the worker gracefully
+     * Stop the worker gracefully.
+     *
+     * Drains: the worker stops claiming, then lets running handlers finish for
+     * up to `shutdownTimeout`. A handler that returns completes its job and one
+     * that throws fails it, even though a stop was requested meanwhile; its
+     * `signal` is NOT aborted during the grace period. Only handlers still
+     * running when the timeout ends are aborted and failed with "Worker shutdown
+     * timeout". The worker deregisters last, because deregistering returns every
+     * job the worker still holds to the queue.
      */
     stop(): Promise<void>;
     private doStop;
@@ -3582,13 +4178,24 @@ declare class SpooledWorker {
     private poll;
     private processJob;
     private executeHandler;
+    /**
+     * Run the handler, racing it against the job's `timeoutSeconds`.
+     * Never rejects: a throw (sync or async) is reported as an outcome.
+     */
+    private runHandler;
+    /** Abort a handler that outlived the shutdown grace period and fail its job. */
+    private abandonJob;
     private completeJob;
     private failJob;
+    private clearTimeoutTimer;
     private cleanupJob;
     private sendJobHeartbeat;
     private sendWorkerHeartbeat;
-    private waitForActiveJobs;
-    private sleep;
+    /**
+     * Resolve once no job is active, or after `timeoutMs`. The timer is always
+     * cleared, so a clean stop leaves nothing that keeps the process alive.
+     */
+    private waitForDrain;
 }
 
-export { type CreateWorkflowParams as $, API_VERSION as A, type BatchJobStatus as B, type ConnectionState as C, type BulkEnqueueResponse as D, type BulkJobItem as E, type CheckEmailResponse as F, type CheckSlugResponse as G, CircuitBreaker as H, type CircuitBreakerConfig as I, CircuitState as J, type ClaimJobsParams as K, type ClaimJobsResult as L, type ClaimedJob as M, type CompleteJobParams as N, type CreateApiKeyParams as O, type CreateApiKeyResponse as P, type CreateBillingPortalParams as Q, type RealtimeConnectionOptions as R, type SubscriptionFilter as S, type CreateBillingPortalResponse as T, type CreateJobParams as U, type CreateJobResult as V, type CreateOrganizationParams as W, type CreateOrganizationResponse as X, type CreateOutgoingWebhookParams as Y, type CreateScheduleParams as Z, type CreateScheduleResponse as _, type RealtimeEventType as a, type IngestGitHubWebhookOptions as a$, type CreateWorkflowResponse as a0, type CurrentUserResponse as a1, DEFAULT_CONFIG as a2, type DashboardData as a3, DashboardResource as a4, type DashboardWorkerSummary as a5, type DebugFn as a6, type DependencyInfo as a7, type DependencyMode as a8, type FailJobParams as a9, type GrpcHeartbeatRequest as aA, type GrpcHeartbeatResponse as aB, type GrpcHeartbeatResponse_Legacy as aC, type GrpcJob as aD, GrpcJobStatus as aE, GrpcJobStatusNumber as aF, type GrpcProcessRequest as aG, type GrpcProcessResponse as aH, GrpcQueueOperations as aI, type GrpcRegisterWorkerParams as aJ, type GrpcRegisterWorkerRequest as aK, type GrpcRegisterWorkerResponse as aL, type GrpcRegisterWorkerResponse_Legacy as aM, type GrpcRenewLeaseParams as aN, type GrpcRenewLeaseRequest as aO, type GrpcRenewLeaseResponse as aP, type GrpcRenewLeaseResponse_Legacy as aQ, type GrpcStreamJobsRequest as aR, type GrpcTimestamp as aS, GrpcWorkerOperations as aT, HealthResource as aU, type HealthResponse as aV, type HeartbeatEvent as aW, type HeartbeatJobParams as aX, HttpClient as aY, type IngestCustomWebhookParams as aZ, type IngestCustomWebhookResponse as a_, type GrpcClientOptions as aa, type GrpcCompleteJobParams as ab, type GrpcCompleteJobResponse as ac, type GrpcCompleteRequest as ad, type GrpcCompleteResponse as ae, type GrpcDequeueJobParams as af, type GrpcDequeueJobResponse as ag, type GrpcDequeueRequest as ah, type GrpcDequeueResponse as ai, type GrpcDeregisterRequest as aj, type GrpcDeregisterResponse as ak, type GrpcEnqueueJobParams as al, type GrpcEnqueueJobResponse as am, type GrpcEnqueueRequest as an, type GrpcEnqueueResponse as ao, type GrpcErrorResponse as ap, type GrpcFailJobParams as aq, type GrpcFailJobResponse as ar, type GrpcFailRequest as as, type GrpcFailResponse as at, type GrpcGetJobRequest as au, type GrpcGetJobResponse as av, type GrpcGetQueueStatsRequest as aw, type GrpcGetQueueStatsResponse as ax, type GrpcGetQueueStatsResponse_Legacy as ay, type GrpcHeartbeatParams as az, type RealtimeEvent as b, type RetryDlqParams as b$, type IngestStripeWebhookOptions as b0, type InitialApiKey as b1, type Job as b2, type JobCompletedEvent as b3, type JobContext as b4, type JobCreatedEvent as b5, type JobFailedEvent as b6, type JobHandler as b7, type JobProgressEvent as b8, type JobResult as b9, type OutgoingWebhook as bA, type OutgoingWebhookDelivery as bB, type PaginatedResponse as bC, type PaginationParams as bD, type PauseQueueResponse as bE, type PlanCount as bF, type PlanLimits as bG, type PlanTier as bH, type ProcessJobsStream as bI, type PurgeDlqParams as bJ, type PurgeDlqResponse as bK, type QueueConfig as bL, type QueueConfigSummary as bM, type QueuePausedEvent as bN, type QueueResumedEvent as bO, type QueueStats as bP, type QueueSummary as bQ, QueuesResource as bR, type RealtimeEventData as bS, type RecentActivity as bT, type RefreshTokenParams as bU, type RefreshTokenResponse as bV, type RegisterWorkerParams as bW, type RegisterWorkerResponse as bX, type ResolvedConfig as bY, type ResourceUsage as bZ, type ResumeQueueResponse as b_, type JobStartedEvent as ba, type JobStats as bb, type JobStatus as bc, type JobStatusChangedEvent as bd, type JobStream as be, type JobSummary as bf, type JobSummaryStats as bg, type JobWithDependencies as bh, JobsResource as bi, type JsonArray as bj, type JsonObject as bk, type JsonPrimitive as bl, type JsonValue as bm, type ListDlqParams as bn, type ListJobsParams as bo, type ListParams as bp, type ListSchedulesParams as bq, type ListWorkflowsParams as br, type LoginParams as bs, type LoginResponse as bt, MetricsResource as bu, type Organization as bv, type OrganizationMember as bw, type OrganizationSummary as bx, type OrganizationUsage as by, OrganizationsResource as bz, type RetryConfig as c, type RetryDlqResponse as c0, SDK_VERSION as c1, type Schedule as c2, type ScheduleRun as c3, type ScheduleRunStatus as c4, type ScheduleTriggeredEvent as c5, SchedulesResource as c6, SpooledClient as c7, type SpooledClientConfig as c8, SpooledGrpcClient as c9, type WorkerEvent as cA, type WorkerEventData as cB, type WorkerHeartbeatParams as cC, type WorkerRegisteredEvent as cD, type WorkerState as cE, type WorkerStatus as cF, type WorkerSummary as cG, WorkersResource as cH, type Workflow as cI, type WorkflowJob as cJ, type WorkflowJobDefinition as cK, type WorkflowJobStatus as cL, type WorkflowResponse as cM, type WorkflowStatus as cN, WorkflowsResource as cO, asyncIterableFromStream as cP, createCircuitBreaker as cQ, createClient as cR, createHttpClient as cS, createJobStream as cT, createPaginatedResponse as cU, createProcessJobsStream as cV, dateToTimestamp as cW, resolveConfig as cX, timestampToDate as cY, validateConfig as cZ, type ActiveJob as c_, SpooledRealtime as ca, type SpooledRealtimeOptions as cb, SpooledWorker as cc, type SpooledWorkerOptions as cd, type StartEmailLoginResponse as ce, type StreamOptions as cf, type SystemInfo as cg, type TestWebhookResponse as ch, type TokenClaims as ci, type TriggerScheduleResponse as cj, type UpdateApiKeyParams as ck, type UpdateOrganizationParams as cl, type UpdateOutgoingWebhookParams as cm, type UpdateQueueConfigParams as cn, type UpdateScheduleParams as co, type UsageItem as cp, type UsageWarning as cq, type ValidateTokenParams as cr, type ValidateTokenResponse as cs, type WebhookDeliveryStatus as ct, type WebhookEventType as cu, WebhookIngestionResource as cv, type WebhookTokenResponse as cw, WebhooksResource as cx, type Worker as cy, type WorkerDeregisteredEvent as cz, type AddDependenciesParams as d, type AddDependenciesResponse as e, type AdminApiKeyResponse as f, type AdminCreateApiKeyParams as g, type AdminCreateOrganizationParams as h, type AdminCreateOrganizationResponse as i, type AdminDeleteOrganizationParams as j, type AdminListOrganizationsParams as k, type AdminOrganizationDetail as l, type AdminOrganizationList as m, type AdminOrganizationSummary as n, type AdminPlanLimits as o, type AdminPlatformStats as p, AdminResource as q, type AdminUpdateOrganizationParams as r, type AdminUsageStats as s, type ApiKeySummary as t, ApiKeysResource as u, AuthResource as v, BillingResource as w, type BillingStatus as x, type BoostPriorityResponse as y, type BulkEnqueueParams as z };
+export { type CreateJobParams as $, API_VERSION as A, type BatchJobStatus as B, type ConnectionState as C, type BillingStatus as D, type BoostPriorityResponse as E, type BulkEnqueueParams as F, type BulkEnqueueResponse as G, type BulkJobItem as H, type CheckEmailResponse as I, type CheckSlugResponse as J, CircuitBreaker as K, type CircuitBreakerConfig as L, CircuitBreakerOpenError as M, type CircuitBreakerOptions as N, CircuitState as O, type CircuitStateChange as P, type ClaimJobsParams as Q, type RealtimeConnectionOptions as R, type SubscriptionFilter as S, type ClaimJobsResult as T, type ClaimedJob as U, type CompleteJobParams as V, ConflictError as W, type CreateApiKeyParams as X, type CreateApiKeyResponse as Y, type CreateBillingPortalParams as Z, type CreateBillingPortalResponse as _, type RealtimeEventType as a, GrpcWorkerOperations as a$, type CreateJobResult as a0, type CreateOrganizationParams as a1, type CreateOrganizationResponse as a2, type CreateOutgoingWebhookParams as a3, type CreateScheduleParams as a4, type CreateScheduleResponse as a5, type CreateWorkflowParams as a6, type CreateWorkflowResponse as a7, type CurrentUserResponse as a8, DEFAULT_CONFIG as a9, type GrpcFailRequest as aA, type GrpcFailResponse as aB, type GrpcGetJobRequest as aC, type GrpcGetJobResponse as aD, type GrpcGetQueueStatsRequest as aE, type GrpcGetQueueStatsResponse as aF, type GrpcGetQueueStatsResponse_Legacy as aG, type GrpcHeartbeatParams as aH, type GrpcHeartbeatRequest as aI, type GrpcHeartbeatResponse as aJ, type GrpcHeartbeatResponse_Legacy as aK, type GrpcJob as aL, GrpcJobStatus as aM, GrpcJobStatusNumber as aN, type GrpcProcessRequest as aO, type GrpcProcessResponse as aP, GrpcQueueOperations as aQ, type GrpcRegisterWorkerParams as aR, type GrpcRegisterWorkerRequest as aS, type GrpcRegisterWorkerResponse as aT, type GrpcRegisterWorkerResponse_Legacy as aU, type GrpcRenewLeaseParams as aV, type GrpcRenewLeaseRequest as aW, type GrpcRenewLeaseResponse as aX, type GrpcRenewLeaseResponse_Legacy as aY, type GrpcStreamJobsRequest as aZ, type GrpcTimestamp as a_, type DashboardData as aa, DashboardResource as ab, type DashboardWorkerSummary as ac, type DebugFn as ad, type DeleteQueueOptions as ae, type DependencyInfo as af, type DependencyMode as ag, type FailJobParams as ah, type GrpcClientOptions as ai, type GrpcCompleteJobParams as aj, type GrpcCompleteJobResponse as ak, type GrpcCompleteRequest as al, type GrpcCompleteResponse as am, type GrpcDequeueJobParams as an, type GrpcDequeueJobResponse as ao, type GrpcDequeueRequest as ap, type GrpcDequeueResponse as aq, type GrpcDeregisterRequest as ar, type GrpcDeregisterResponse as as, type GrpcEnqueueJobParams as at, type GrpcEnqueueJobResponse as au, type GrpcEnqueueRequest as av, type GrpcEnqueueResponse as aw, type GrpcErrorResponse as ax, type GrpcFailJobParams as ay, type GrpcFailJobResponse as az, type RealtimeEvent as b, type ProcessJobsStream as b$, HealthResource as b0, type HealthResponse as b1, type HeartbeatEvent as b2, type HeartbeatJobParams as b3, HttpClient as b4, type InboundDeliveryStatus as b5, type InboundWebhookDelivery as b6, type IngestCustomWebhookParams as b7, type IngestCustomWebhookResponse as b8, type IngestGitHubWebhookOptions as b9, type JsonValue as bA, type ListDlqParams as bB, type ListInboundDeliveriesParams as bC, type ListJobsParams as bD, type ListPage as bE, type ListParams as bF, type ListSchedulesParams as bG, type ListWorkflowsParams as bH, type LoginParams as bI, type LoginResponse as bJ, MetricsResource as bK, NetworkError as bL, NotFoundError as bM, type Organization as bN, type OrganizationMember as bO, type OrganizationSummary as bP, type OrganizationUsage as bQ, OrganizationsResource as bR, type OutgoingWebhook as bS, type OutgoingWebhookDelivery as bT, type PaginatedResponse as bU, type PaginationParams as bV, type PauseQueueResponse as bW, PayloadTooLargeError as bX, type PlanCount as bY, type PlanLimits as bZ, type PlanTier as b_, type IngestStripeWebhookOptions as ba, type InitialApiKey as bb, type Job as bc, type JobCompletedEvent as bd, type JobContext as be, type JobCreatedEvent as bf, type JobFailedEvent as bg, type JobHandler as bh, type JobHistoryEvent as bi, type JobHistoryEventType as bj, type JobHistoryParams as bk, type JobProgressEvent as bl, type JobResult as bm, type JobSearchParams as bn, type JobStartedEvent as bo, type JobStats as bp, type JobStatus as bq, type JobStatusChangedEvent as br, type JobStream as bs, type JobSummary as bt, type JobSummaryStats as bu, type JobWithDependencies as bv, JobsResource as bw, type JsonArray as bx, type JsonObject as by, type JsonPrimitive as bz, type RetryConfig as c, type WorkerEvent as c$, type PurgeDlqParams as c0, type PurgeDlqResponse as c1, type QueueConfig as c2, type QueueConfigSummary as c3, type QueuePausedEvent as c4, type QueueResumedEvent as c5, type QueueStats as c6, type QueueSummary as c7, QueuesResource as c8, RateLimitError as c9, type SpooledWorkerOptions as cA, type StartEmailLoginResponse as cB, type StreamOptions as cC, type SystemInfo as cD, type TestWebhookResponse as cE, TimeoutError as cF, type TokenClaims as cG, type TriggerScheduleResponse as cH, UnsupportedOperationError as cI, type UpdateApiKeyParams as cJ, type UpdateOrganizationParams as cK, type UpdateOutgoingWebhookParams as cL, type UpdateQueueConfigParams as cM, type UpdateScheduleParams as cN, type UsageItem as cO, type UsageWarning as cP, type ValidateTokenParams as cQ, type ValidateTokenResponse as cR, ValidationError as cS, type WebhookDeliveryStatus as cT, type WebhookEventType as cU, type WebhookFormat as cV, WebhookIngestionResource as cW, type WebhookTokenResponse as cX, WebhooksResource as cY, type Worker as cZ, type WorkerDeregisteredEvent as c_, type RateLimitInfo as ca, type RealtimeEventData as cb, type RecentActivity as cc, type RefreshTokenParams as cd, type RefreshTokenResponse as ce, type RegisterWorkerParams as cf, type RegisterWorkerResponse as cg, type ResolvedConfig as ch, type ResourceUsage as ci, type ResumeQueueResponse as cj, type RetryDlqParams as ck, type RetryDlqResponse as cl, SDK_VERSION as cm, type Schedule as cn, type ScheduleRun as co, type ScheduleRunStatus as cp, type ScheduleTriggeredEvent as cq, SchedulesResource as cr, ServerError as cs, SpooledClient as ct, type SpooledClientConfig as cu, SpooledError as cv, SpooledGrpcClient as cw, SpooledRealtime as cx, type SpooledRealtimeOptions as cy, SpooledWorker as cz, type AddDependenciesParams as d, type WorkerEventData as d0, type WorkerHeartbeatParams as d1, type WorkerRegisteredEvent as d2, type WorkerState as d3, type WorkerStatus as d4, type WorkerSummary as d5, WorkersResource as d6, type Workflow as d7, type WorkflowJob as d8, type WorkflowJobDefinition as d9, type WorkflowJobStatus as da, type WorkflowResponse as db, type WorkflowStatus as dc, WorkflowsResource as dd, asyncIterableFromStream as de, createCircuitBreaker as df, createClient as dg, createErrorFromResponse as dh, createHttpClient as di, createJobStream as dj, createPaginatedResponse as dk, createProcessJobsStream as dl, dateToTimestamp as dm, isCircuitBreakerFailure as dn, isRetryableError as dp, isSpooledError as dq, parseRateLimitHeaders as dr, resolveConfig as ds, timestampToDate as dt, validateConfig as du, type ActiveJob as dv, type AddDependenciesResponse as e, type AdminApiKeyResponse as f, type AdminCreateApiKeyParams as g, type AdminCreateOrganizationParams as h, type AdminCreateOrganizationResponse as i, type AdminDeleteOrganizationParams as j, type AdminListOrganizationsParams as k, type AdminOrganizationDetail as l, type AdminOrganizationList as m, type AdminOrganizationSummary as n, type AdminPlanLimits as o, type AdminPlatformStats as p, AdminResource as q, type AdminUpdateOrganizationParams as r, type AdminUsageStats as s, type ApiErrorBody as t, type ApiKeySummary as u, ApiKeysResource as v, AuthResource as w, AuthenticationError as x, AuthorizationError as y, BillingResource as z };