@spooled/sdk 1.3.0 → 1.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +81 -9
- package/dist/{index-BVWKEr6p.d.cts → index-Bqgiu-NN.d.cts} +569 -95
- package/dist/{index-BVWKEr6p.d.ts → index-Bqgiu-NN.d.ts} +569 -95
- package/dist/index.cjs +341 -125
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +3 -186
- package/dist/index.d.ts +3 -186
- package/dist/index.js +341 -126
- package/dist/index.js.map +1 -1
- package/dist/worker/index.cjs +1 -1
- package/dist/worker/index.cjs.map +1 -1
- package/dist/worker/index.d.cts +1 -1
- package/dist/worker/index.d.ts +1 -1
- package/dist/worker/index.js +1 -1
- package/dist/worker/index.js.map +1 -1
- package/package.json +8 -7
- package/proto/spooled.proto +19 -1
|
@@ -1,10 +1,124 @@
|
|
|
1
1
|
import * as grpc from '@grpc/grpc-js';
|
|
2
2
|
|
|
3
|
+
/**
|
|
4
|
+
* Circuit Breaker Utility
|
|
5
|
+
*
|
|
6
|
+
* Implements the circuit breaker pattern to prevent cascading failures.
|
|
7
|
+
* States: CLOSED (normal) -> OPEN (failing) -> HALF_OPEN (testing) -> CLOSED
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
/** Circuit breaker states */
|
|
11
|
+
declare enum CircuitState {
|
|
12
|
+
/** Normal operation - requests flow through */
|
|
13
|
+
CLOSED = "CLOSED",
|
|
14
|
+
/** Circuit is open - requests are rejected immediately */
|
|
15
|
+
OPEN = "OPEN",
|
|
16
|
+
/** Testing state - limited requests allowed to test recovery */
|
|
17
|
+
HALF_OPEN = "HALF_OPEN"
|
|
18
|
+
}
|
|
19
|
+
/** Circuit breaker state change event */
|
|
20
|
+
interface CircuitStateChange {
|
|
21
|
+
from: CircuitState;
|
|
22
|
+
to: CircuitState;
|
|
23
|
+
timestamp: Date;
|
|
24
|
+
failureCount: number;
|
|
25
|
+
}
|
|
26
|
+
/** Circuit breaker options */
|
|
27
|
+
interface CircuitBreakerOptions extends CircuitBreakerConfig {
|
|
28
|
+
/** Callback when state changes */
|
|
29
|
+
onStateChange?: (event: CircuitStateChange) => void;
|
|
30
|
+
/**
|
|
31
|
+
* Custom function to determine if an error should count as a failure.
|
|
32
|
+
* Defaults to {@link isCircuitBreakerFailure}.
|
|
33
|
+
*/
|
|
34
|
+
isFailure?: (error: Error) => boolean;
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Default circuit breaker failure predicate.
|
|
38
|
+
*
|
|
39
|
+
* Counts the errors that say the API or the network is unhealthy: the
|
|
40
|
+
* retryable ones (network errors, timeouts, 5xx, 408). A 429 never counts. A
|
|
41
|
+
* rate-limit 429 is the API working as designed and telling this client to
|
|
42
|
+
* slow down for `Retry-After` seconds; counting it let a burst above the plan
|
|
43
|
+
* limit open the breaker and fail every call on the client for the breaker
|
|
44
|
+
* timeout (30 s by default), including the retries that `Retry-After` had
|
|
45
|
+
* already scheduled. The retry layer handles rate limiting on its own. A quota
|
|
46
|
+
* 429 (`RateLimitError.isQuota`) was already excluded.
|
|
47
|
+
*/
|
|
48
|
+
declare function isCircuitBreakerFailure(error: Error): boolean;
|
|
49
|
+
/**
|
|
50
|
+
* Circuit Breaker implementation
|
|
51
|
+
*
|
|
52
|
+
* Tracks failures and prevents requests when the failure threshold is reached.
|
|
53
|
+
*/
|
|
54
|
+
declare class CircuitBreaker {
|
|
55
|
+
private state;
|
|
56
|
+
private failureCount;
|
|
57
|
+
private successCount;
|
|
58
|
+
private lastFailureTime;
|
|
59
|
+
private readonly config;
|
|
60
|
+
constructor(config: CircuitBreakerOptions);
|
|
61
|
+
/**
|
|
62
|
+
* Get current circuit state
|
|
63
|
+
*/
|
|
64
|
+
getState(): CircuitState;
|
|
65
|
+
/**
|
|
66
|
+
* Check if circuit breaker is enabled
|
|
67
|
+
*/
|
|
68
|
+
isEnabled(): boolean;
|
|
69
|
+
/**
|
|
70
|
+
* Check if requests are currently allowed
|
|
71
|
+
*/
|
|
72
|
+
isAllowed(): boolean;
|
|
73
|
+
/**
|
|
74
|
+
* Record a successful request
|
|
75
|
+
*/
|
|
76
|
+
recordSuccess(): void;
|
|
77
|
+
/**
|
|
78
|
+
* Record a failed request
|
|
79
|
+
*/
|
|
80
|
+
recordFailure(error: Error): void;
|
|
81
|
+
/**
|
|
82
|
+
* Transition to a new state
|
|
83
|
+
*/
|
|
84
|
+
private transitionTo;
|
|
85
|
+
/**
|
|
86
|
+
* Reset the circuit breaker to closed state
|
|
87
|
+
*/
|
|
88
|
+
reset(): void;
|
|
89
|
+
/**
|
|
90
|
+
* Execute a function with circuit breaker protection
|
|
91
|
+
*
|
|
92
|
+
* @param fn - Async function to execute
|
|
93
|
+
* @returns Promise resolving to the function result
|
|
94
|
+
* @throws CircuitBreakerOpenError if circuit is open
|
|
95
|
+
*/
|
|
96
|
+
execute<T>(fn: () => Promise<T>): Promise<T>;
|
|
97
|
+
/**
|
|
98
|
+
* Get circuit breaker statistics
|
|
99
|
+
*/
|
|
100
|
+
getStats(): {
|
|
101
|
+
state: CircuitState;
|
|
102
|
+
failureCount: number;
|
|
103
|
+
successCount: number;
|
|
104
|
+
lastFailureTime: Date | null;
|
|
105
|
+
config: CircuitBreakerConfig;
|
|
106
|
+
};
|
|
107
|
+
}
|
|
108
|
+
/**
|
|
109
|
+
* Create a circuit breaker instance from configuration.
|
|
110
|
+
*
|
|
111
|
+
* Unless the config carries its own `isFailure`, rate-limit 429s do not count
|
|
112
|
+
* as failures (the constructor defaults to {@link isCircuitBreakerFailure}).
|
|
113
|
+
*/
|
|
114
|
+
declare function createCircuitBreaker(config: CircuitBreakerOptions): CircuitBreaker;
|
|
115
|
+
|
|
3
116
|
/**
|
|
4
117
|
* SDK Configuration
|
|
5
118
|
*
|
|
6
119
|
* Defines configuration types and defaults for the Spooled SDK.
|
|
7
120
|
*/
|
|
121
|
+
|
|
8
122
|
/** Retry configuration options */
|
|
9
123
|
interface RetryConfig {
|
|
10
124
|
/** Maximum number of retry attempts (default: 3) */
|
|
@@ -57,8 +171,11 @@ interface SpooledClientConfig {
|
|
|
57
171
|
retryDelay?: number;
|
|
58
172
|
/** Full retry configuration */
|
|
59
173
|
retry?: Partial<RetryConfig>;
|
|
60
|
-
/**
|
|
61
|
-
|
|
174
|
+
/**
|
|
175
|
+
* Circuit breaker configuration. Besides the thresholds it takes
|
|
176
|
+
* `isFailure` (which errors count as failures) and `onStateChange`.
|
|
177
|
+
*/
|
|
178
|
+
circuitBreaker?: Partial<CircuitBreakerOptions>;
|
|
62
179
|
/** Additional headers to include in all requests */
|
|
63
180
|
headers?: Record<string, string>;
|
|
64
181
|
/** Custom fetch implementation (for testing or special runtimes) */
|
|
@@ -81,7 +198,7 @@ interface ResolvedConfig {
|
|
|
81
198
|
grpcAddress: string;
|
|
82
199
|
timeout: number;
|
|
83
200
|
retry: RetryConfig;
|
|
84
|
-
circuitBreaker:
|
|
201
|
+
circuitBreaker: CircuitBreakerOptions;
|
|
85
202
|
headers: Record<string, string>;
|
|
86
203
|
fetch: typeof fetch;
|
|
87
204
|
userAgent: string;
|
|
@@ -107,11 +224,11 @@ declare const DEFAULT_CONFIG: {
|
|
|
107
224
|
successThreshold: number;
|
|
108
225
|
timeout: number;
|
|
109
226
|
};
|
|
110
|
-
readonly userAgent: "@spooled/sdk-nodejs/1.
|
|
227
|
+
readonly userAgent: "@spooled/sdk-nodejs/1.4.1";
|
|
111
228
|
readonly autoRefreshToken: true;
|
|
112
229
|
};
|
|
113
230
|
/** SDK version */
|
|
114
|
-
declare const SDK_VERSION = "1.
|
|
231
|
+
declare const SDK_VERSION = "1.4.1";
|
|
115
232
|
/** API version prefix */
|
|
116
233
|
declare const API_VERSION = "v1";
|
|
117
234
|
/**
|
|
@@ -125,98 +242,206 @@ declare function resolveConfig(options: SpooledClientConfig): ResolvedConfig;
|
|
|
125
242
|
declare function validateConfig(config: ResolvedConfig): void;
|
|
126
243
|
|
|
127
244
|
/**
|
|
128
|
-
*
|
|
245
|
+
* Custom Error Classes
|
|
129
246
|
*
|
|
130
|
-
*
|
|
131
|
-
* States: CLOSED (normal) -> OPEN (failing) -> HALF_OPEN (testing) -> CLOSED
|
|
247
|
+
* Provides a hierarchy of error types for the Spooled SDK.
|
|
132
248
|
*/
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
/** Circuit is open - requests are rejected immediately */
|
|
139
|
-
OPEN = "OPEN",
|
|
140
|
-
/** Testing state - limited requests allowed to test recovery */
|
|
141
|
-
HALF_OPEN = "HALF_OPEN"
|
|
142
|
-
}
|
|
143
|
-
/** Circuit breaker state change event */
|
|
144
|
-
interface CircuitStateChange {
|
|
145
|
-
from: CircuitState;
|
|
146
|
-
to: CircuitState;
|
|
147
|
-
timestamp: Date;
|
|
148
|
-
failureCount: number;
|
|
149
|
-
}
|
|
150
|
-
/** Circuit breaker options */
|
|
151
|
-
interface CircuitBreakerOptions extends CircuitBreakerConfig {
|
|
152
|
-
/** Callback when state changes */
|
|
153
|
-
onStateChange?: (event: CircuitStateChange) => void;
|
|
154
|
-
/** Custom function to determine if an error should count as a failure */
|
|
155
|
-
isFailure?: (error: Error) => boolean;
|
|
249
|
+
/** Error response body from the API */
|
|
250
|
+
interface ApiErrorBody {
|
|
251
|
+
code: string;
|
|
252
|
+
message: string;
|
|
253
|
+
details?: Record<string, unknown>;
|
|
156
254
|
}
|
|
157
255
|
/**
|
|
158
|
-
*
|
|
256
|
+
* Rate limit information parsed from headers.
|
|
159
257
|
*
|
|
160
|
-
*
|
|
258
|
+
* Authenticated responses that went through the plan rate limiter carry
|
|
259
|
+
* `X-RateLimit-Limit`, `-Remaining`, `-Reset` and `-Scope` (API 0.1.122+); a
|
|
260
|
+
* 429 adds `Retry-After`. Every field is optional: the headers are left out
|
|
261
|
+
* when no rate-limit check ran (public and admin routes, a server without
|
|
262
|
+
* Redis, older servers).
|
|
161
263
|
*/
|
|
162
|
-
|
|
163
|
-
private state;
|
|
164
|
-
private failureCount;
|
|
165
|
-
private successCount;
|
|
166
|
-
private lastFailureTime;
|
|
167
|
-
private readonly config;
|
|
168
|
-
constructor(config: CircuitBreakerOptions);
|
|
169
|
-
/**
|
|
170
|
-
* Get current circuit state
|
|
171
|
-
*/
|
|
172
|
-
getState(): CircuitState;
|
|
173
|
-
/**
|
|
174
|
-
* Check if circuit breaker is enabled
|
|
175
|
-
*/
|
|
176
|
-
isEnabled(): boolean;
|
|
177
|
-
/**
|
|
178
|
-
* Check if requests are currently allowed
|
|
179
|
-
*/
|
|
180
|
-
isAllowed(): boolean;
|
|
181
|
-
/**
|
|
182
|
-
* Record a successful request
|
|
183
|
-
*/
|
|
184
|
-
recordSuccess(): void;
|
|
264
|
+
interface RateLimitInfo {
|
|
185
265
|
/**
|
|
186
|
-
*
|
|
266
|
+
* The limit the other fields describe: the plan burst (organization token
|
|
267
|
+
* bucket) or an API key's own requests per minute.
|
|
187
268
|
*/
|
|
188
|
-
|
|
269
|
+
limit?: number;
|
|
270
|
+
/** Whole requests left after this one */
|
|
271
|
+
remaining?: number;
|
|
189
272
|
/**
|
|
190
|
-
*
|
|
273
|
+
* When `remaining` next goes up (`X-RateLimit-Reset`, a Unix time in
|
|
274
|
+
* seconds; the current time while the bucket is full).
|
|
191
275
|
*/
|
|
192
|
-
|
|
276
|
+
reset?: Date;
|
|
277
|
+
/** Seconds to wait before retrying (`Retry-After`, on a 429) */
|
|
278
|
+
retryAfter?: number;
|
|
193
279
|
/**
|
|
194
|
-
*
|
|
280
|
+
* Which limit the headers describe (`X-RateLimit-Scope`): `organization`
|
|
281
|
+
* (the plan's token bucket) or `api_key` (the key's `rateLimit`).
|
|
195
282
|
*/
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
283
|
+
scope?: "organization" | "api_key" | (string & {});
|
|
284
|
+
}
|
|
285
|
+
/**
|
|
286
|
+
* Base error class for all Spooled SDK errors
|
|
287
|
+
*/
|
|
288
|
+
declare class SpooledError extends Error {
|
|
289
|
+
/** HTTP status code (if applicable) */
|
|
290
|
+
readonly statusCode: number;
|
|
291
|
+
/** Error code from API response */
|
|
292
|
+
readonly code: string;
|
|
293
|
+
/** Additional error details */
|
|
294
|
+
readonly details?: Record<string, unknown>;
|
|
295
|
+
/** Request ID for debugging */
|
|
296
|
+
readonly requestId?: string;
|
|
297
|
+
/** Original cause of the error */
|
|
298
|
+
readonly cause?: Error;
|
|
299
|
+
constructor(message: string, statusCode?: number, code?: string, details?: Record<string, unknown>, requestId?: string, cause?: Error);
|
|
300
|
+
/**
|
|
301
|
+
* Whether this error is retryable.
|
|
199
302
|
*
|
|
200
|
-
*
|
|
201
|
-
*
|
|
202
|
-
*
|
|
303
|
+
* Only 408 (Request Timeout) is retryable among the plain 4xx statuses: the
|
|
304
|
+
* server gave up waiting for the request, so it never ran. Subclasses
|
|
305
|
+
* override this (5xx, network, timeout, rate limit).
|
|
203
306
|
*/
|
|
204
|
-
|
|
307
|
+
isRetryable(): boolean;
|
|
308
|
+
/** Convert to plain object for logging */
|
|
309
|
+
toJSON(): Record<string, unknown>;
|
|
310
|
+
}
|
|
311
|
+
/**
|
|
312
|
+
* Authentication error (401)
|
|
313
|
+
* Thrown when authentication fails (invalid/expired token or API key)
|
|
314
|
+
*/
|
|
315
|
+
declare class AuthenticationError extends SpooledError {
|
|
316
|
+
constructor(message?: string, code?: string, details?: Record<string, unknown>, requestId?: string);
|
|
317
|
+
}
|
|
318
|
+
/**
|
|
319
|
+
* Authorization error (403)
|
|
320
|
+
* Thrown when the authenticated user lacks permission
|
|
321
|
+
*/
|
|
322
|
+
declare class AuthorizationError extends SpooledError {
|
|
323
|
+
constructor(message?: string, code?: string, details?: Record<string, unknown>, requestId?: string);
|
|
324
|
+
}
|
|
325
|
+
/**
|
|
326
|
+
* Not found error (404)
|
|
327
|
+
* Thrown when a requested resource doesn't exist
|
|
328
|
+
*/
|
|
329
|
+
declare class NotFoundError extends SpooledError {
|
|
330
|
+
constructor(message?: string, code?: string, details?: Record<string, unknown>, requestId?: string);
|
|
331
|
+
}
|
|
332
|
+
/**
|
|
333
|
+
* Conflict error (409)
|
|
334
|
+
* Thrown when there's a conflict (e.g., duplicate resource)
|
|
335
|
+
*/
|
|
336
|
+
declare class ConflictError extends SpooledError {
|
|
337
|
+
constructor(message?: string, code?: string, details?: Record<string, unknown>, requestId?: string);
|
|
338
|
+
}
|
|
339
|
+
/**
|
|
340
|
+
* Validation error (400 or 422)
|
|
341
|
+
* Thrown when request validation fails.
|
|
342
|
+
*
|
|
343
|
+
* The API answers a field-rule failure (length, range) with 400 but a missing
|
|
344
|
+
* or mistyped JSON field with 422; both are the caller's request being invalid,
|
|
345
|
+
* so both surface as this class. `statusCode` tells them apart.
|
|
346
|
+
*/
|
|
347
|
+
declare class ValidationError extends SpooledError {
|
|
348
|
+
constructor(message?: string, code?: string, details?: Record<string, unknown>, requestId?: string, statusCode?: 400 | 422);
|
|
349
|
+
}
|
|
350
|
+
/**
|
|
351
|
+
* Payload too large error (413)
|
|
352
|
+
* Thrown when request body exceeds size limit
|
|
353
|
+
*/
|
|
354
|
+
declare class PayloadTooLargeError extends SpooledError {
|
|
355
|
+
constructor(message?: string, code?: string, details?: Record<string, unknown>, requestId?: string);
|
|
356
|
+
}
|
|
357
|
+
/**
|
|
358
|
+
* Rate limit error (429)
|
|
359
|
+
* Thrown when rate limit is exceeded, or a plan quota is (see `isQuota`)
|
|
360
|
+
*/
|
|
361
|
+
declare class RateLimitError extends SpooledError {
|
|
362
|
+
/** Rate limit information */
|
|
363
|
+
readonly rateLimitInfo: RateLimitInfo;
|
|
364
|
+
constructor(message?: string, code?: string, rateLimitInfo?: RateLimitInfo, details?: Record<string, unknown>, requestId?: string);
|
|
205
365
|
/**
|
|
206
|
-
*
|
|
366
|
+
* True when this 429 is a plan quota or limit (daily job cap, active jobs,
|
|
367
|
+
* queue/worker/webhook caps) rather than per-second rate limiting.
|
|
368
|
+
*
|
|
369
|
+
* A quota does not clear for minutes or hours, so retrying it only blocks the
|
|
370
|
+
* caller for the whole backoff and, via the circuit breaker, takes every
|
|
371
|
+
* other call on the client down with it. It is never retried and never
|
|
372
|
+
* counted as a circuit breaker failure.
|
|
373
|
+
*
|
|
374
|
+
* Detection: the `QUOTA_EXCEEDED` code, or, for older plan-limit paths that
|
|
375
|
+
* answer with plain text wrapped as `RATE_LIMIT_EXCEEDED`, a "... limit
|
|
376
|
+
* reached" message that carries no `Retry-After`.
|
|
207
377
|
*/
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
378
|
+
get isQuota(): boolean;
|
|
379
|
+
isRetryable(): boolean;
|
|
380
|
+
/** Get the number of seconds to wait before retrying */
|
|
381
|
+
getRetryAfter(): number;
|
|
382
|
+
toJSON(): Record<string, unknown>;
|
|
383
|
+
}
|
|
384
|
+
/**
|
|
385
|
+
* Server error (5xx)
|
|
386
|
+
* Thrown when the server encounters an error
|
|
387
|
+
*/
|
|
388
|
+
declare class ServerError extends SpooledError {
|
|
389
|
+
constructor(message?: string, statusCode?: number, code?: string, details?: Record<string, unknown>, requestId?: string);
|
|
390
|
+
isRetryable(): boolean;
|
|
391
|
+
}
|
|
392
|
+
/**
|
|
393
|
+
* Network error
|
|
394
|
+
* Thrown when a network request fails (no response received)
|
|
395
|
+
*/
|
|
396
|
+
declare class NetworkError extends SpooledError {
|
|
397
|
+
constructor(message?: string, cause?: Error);
|
|
398
|
+
isRetryable(): boolean;
|
|
399
|
+
}
|
|
400
|
+
/**
|
|
401
|
+
* Timeout error
|
|
402
|
+
* Thrown when a request times out
|
|
403
|
+
*/
|
|
404
|
+
declare class TimeoutError extends SpooledError {
|
|
405
|
+
/** Timeout duration in milliseconds */
|
|
406
|
+
readonly timeoutMs: number;
|
|
407
|
+
constructor(message?: string, timeoutMs?: number);
|
|
408
|
+
isRetryable(): boolean;
|
|
215
409
|
}
|
|
216
410
|
/**
|
|
217
|
-
*
|
|
411
|
+
* Circuit breaker open error
|
|
412
|
+
* Thrown when the circuit breaker is open and rejecting requests
|
|
218
413
|
*/
|
|
219
|
-
declare
|
|
414
|
+
declare class CircuitBreakerOpenError extends SpooledError {
|
|
415
|
+
constructor(message?: string);
|
|
416
|
+
isRetryable(): boolean;
|
|
417
|
+
}
|
|
418
|
+
/**
|
|
419
|
+
* Unsupported operation error
|
|
420
|
+
* Thrown by SDK methods whose route the Spooled API does not provide (or
|
|
421
|
+
* always rejects). It is raised before any network call, so code that still
|
|
422
|
+
* calls such a method fails loudly with an explanation instead of a 404.
|
|
423
|
+
*/
|
|
424
|
+
declare class UnsupportedOperationError extends SpooledError {
|
|
425
|
+
/** The SDK method that is not supported, e.g. `ingest.github` */
|
|
426
|
+
readonly operation: string;
|
|
427
|
+
constructor(operation: string, reason: string);
|
|
428
|
+
}
|
|
429
|
+
/**
|
|
430
|
+
* Parse rate limit headers from a Response
|
|
431
|
+
*/
|
|
432
|
+
declare function parseRateLimitHeaders(headers: Headers): RateLimitInfo;
|
|
433
|
+
/**
|
|
434
|
+
* Create an appropriate error from an HTTP response
|
|
435
|
+
*/
|
|
436
|
+
declare function createErrorFromResponse(response: Response): Promise<SpooledError>;
|
|
437
|
+
/**
|
|
438
|
+
* Check if an error is a SpooledError instance
|
|
439
|
+
*/
|
|
440
|
+
declare function isSpooledError(error: unknown): error is SpooledError;
|
|
441
|
+
/**
|
|
442
|
+
* Check if an error is retryable
|
|
443
|
+
*/
|
|
444
|
+
declare function isRetryableError(error: unknown): boolean;
|
|
220
445
|
|
|
221
446
|
/**
|
|
222
447
|
* HTTP Client Utility
|
|
@@ -307,11 +532,19 @@ declare class HttpClient {
|
|
|
307
532
|
* refresh and fail even though the token was about to be replaced.
|
|
308
533
|
*/
|
|
309
534
|
private refreshInFlight;
|
|
535
|
+
/** Rate-limit headers of the most recent response that carried them */
|
|
536
|
+
private lastRateLimit;
|
|
310
537
|
constructor(config: ResolvedConfig, circuitBreaker: CircuitBreaker);
|
|
311
538
|
/**
|
|
312
539
|
* Set the authentication token
|
|
313
540
|
*/
|
|
314
541
|
setAuthToken(token: string): void;
|
|
542
|
+
/**
|
|
543
|
+
* The `X-RateLimit-*` (and `Retry-After`) values of the most recent
|
|
544
|
+
* response that carried them, successful or not. `undefined` until such a
|
|
545
|
+
* response arrives. With concurrent requests it is the last one to finish.
|
|
546
|
+
*/
|
|
547
|
+
getLastRateLimitInfo(): RateLimitInfo | undefined;
|
|
315
548
|
/**
|
|
316
549
|
* Set the token refresh function.
|
|
317
550
|
*
|
|
@@ -342,6 +575,8 @@ declare class HttpClient {
|
|
|
342
575
|
* Execute a single HTTP request (no retry)
|
|
343
576
|
*/
|
|
344
577
|
private executeRequest;
|
|
578
|
+
/** Remember the rate-limit headers of a response that has them. */
|
|
579
|
+
private recordRateLimit;
|
|
345
580
|
/**
|
|
346
581
|
* Make an HTTP request with retry and circuit breaker
|
|
347
582
|
*/
|
|
@@ -535,8 +770,32 @@ type PlanTier = "free" | "starter" | "pro" | "enterprise";
|
|
|
535
770
|
type ScheduleRunStatus = "pending" | "running" | "completed" | "failed";
|
|
536
771
|
/** Webhook delivery status */
|
|
537
772
|
type WebhookDeliveryStatus = "pending" | "success" | "failed";
|
|
538
|
-
/**
|
|
539
|
-
|
|
773
|
+
/**
|
|
774
|
+
* Webhook event types.
|
|
775
|
+
*
|
|
776
|
+
* `job.deadlettered`, `job.retried`, `workflow.completed` and
|
|
777
|
+
* `workflow.failed` need API 0.1.122 or later. The SDK does not check event
|
|
778
|
+
* names in responses: a name newer than this list is passed through as a
|
|
779
|
+
* string, so give a `switch` over it a `default` branch.
|
|
780
|
+
*/
|
|
781
|
+
type WebhookEventType = "job.created" | "job.started" | "job.completed" | "job.failed" | "job.cancelled" | "queue.paused" | "queue.resumed" | "worker.registered" | "worker.deregistered" | "schedule.triggered"
|
|
782
|
+
/** Sent next to every `job.failed` whose `data.status` is `deadletter`. */
|
|
783
|
+
| "job.deadlettered"
|
|
784
|
+
/** A manual retry (job, DLQ or workflow retry) put the job back to pending. */
|
|
785
|
+
| "job.retried"
|
|
786
|
+
/** A workflow finished; announced at most once, up to ~10 s late. */
|
|
787
|
+
| "workflow.completed"
|
|
788
|
+
/** A workflow failed; announced at most once, up to ~10 s late. */
|
|
789
|
+
| "workflow.failed";
|
|
790
|
+
/**
|
|
791
|
+
* Body format of an outgoing webhook (API 0.1.122+).
|
|
792
|
+
*
|
|
793
|
+
* `json` (the default) is the signed JSON envelope. `slack`, `discord` and
|
|
794
|
+
* `teams` send one short chat message built from the event, so a chat
|
|
795
|
+
* service's incoming-webhook URL can be used as it is (`teams` is the legacy
|
|
796
|
+
* Office 365 connector `MessageCard`; Teams Workflows URLs reject it).
|
|
797
|
+
*/
|
|
798
|
+
type WebhookFormat = "json" | "slack" | "discord" | "teams";
|
|
540
799
|
/** Dependency mode for workflows */
|
|
541
800
|
type DependencyMode = "all" | "any";
|
|
542
801
|
/** Pagination parameters */
|
|
@@ -566,6 +825,22 @@ interface PaginatedResponse<T> {
|
|
|
566
825
|
/** Whether there are more results */
|
|
567
826
|
hasMore: boolean;
|
|
568
827
|
}
|
|
828
|
+
/**
|
|
829
|
+
* One page of a list endpoint that reports `X-Has-More` (API 0.1.122+):
|
|
830
|
+
* `GET /jobs`, `GET /jobs/dlq` and `GET /jobs/{id}/history`.
|
|
831
|
+
*
|
|
832
|
+
* The response body stays a bare array; `hasMore` comes from the header.
|
|
833
|
+
*/
|
|
834
|
+
interface ListPage<T> {
|
|
835
|
+
/** Items of this page, in the server's order */
|
|
836
|
+
data: T[];
|
|
837
|
+
/**
|
|
838
|
+
* `true` when another page follows: ask again with
|
|
839
|
+
* `offset + data.length`. From the `X-Has-More` header; an older server
|
|
840
|
+
* without it gets a guess from the page size (a full page means "maybe").
|
|
841
|
+
*/
|
|
842
|
+
hasMore: boolean;
|
|
843
|
+
}
|
|
569
844
|
/**
|
|
570
845
|
* Helper to create a paginated response from an array
|
|
571
846
|
*/
|
|
@@ -658,12 +933,36 @@ interface CreateJobResult {
|
|
|
658
933
|
id: string;
|
|
659
934
|
created: boolean;
|
|
660
935
|
}
|
|
936
|
+
/**
|
|
937
|
+
* Server-side job search filters (API 0.1.122+), shared by `GET /jobs` and
|
|
938
|
+
* `GET /jobs/dlq`. All filters combine with AND. An invalid value is a 400
|
|
939
|
+
* `ValidationError`; an older server ignores them.
|
|
940
|
+
*/
|
|
941
|
+
interface JobSearchParams {
|
|
942
|
+
/**
|
|
943
|
+
* Search text, case-insensitive: matches a job whose id starts with it, or
|
|
944
|
+
* whose queue name or `payload.job_type` contains it (at most 255 bytes).
|
|
945
|
+
*/
|
|
946
|
+
q?: string;
|
|
947
|
+
/** Exact `payload.job_type` (at most 255 bytes) */
|
|
948
|
+
jobType?: string;
|
|
949
|
+
/**
|
|
950
|
+
* Only jobs created at or after this instant. A `Date` is sent as an
|
|
951
|
+
* ISO 8601 UTC string; a string must be RFC 3339.
|
|
952
|
+
*/
|
|
953
|
+
createdAfter?: Date | string;
|
|
954
|
+
/** Only jobs created before this instant (exclusive); see `createdAfter` */
|
|
955
|
+
createdBefore?: Date | string;
|
|
956
|
+
}
|
|
661
957
|
/** Parameters for listing jobs */
|
|
662
|
-
interface ListJobsParams extends ListParams {
|
|
958
|
+
interface ListJobsParams extends ListParams, JobSearchParams {
|
|
663
959
|
/** Filter by queue name */
|
|
664
960
|
queueName?: string;
|
|
665
|
-
/**
|
|
666
|
-
|
|
961
|
+
/**
|
|
962
|
+
* Filter by status: one status, or several (sent as the comma list
|
|
963
|
+
* `status=failed,deadletter`, which needs API 0.1.122+).
|
|
964
|
+
*/
|
|
965
|
+
status?: JobStatus | readonly JobStatus[];
|
|
667
966
|
/** Filter by a single tag (matches Postgres `tags ? tag` semantics) */
|
|
668
967
|
tag?: string;
|
|
669
968
|
}
|
|
@@ -697,10 +996,9 @@ interface ClaimedJob {
|
|
|
697
996
|
timeoutSeconds: number;
|
|
698
997
|
leaseExpiresAt?: string;
|
|
699
998
|
/**
|
|
700
|
-
* Lease fencing token for this claim.
|
|
701
|
-
* complete/fail/heartbeat
|
|
702
|
-
*
|
|
703
|
-
* LEASE_EXPIRED). Omitted = legacy behavior.
|
|
999
|
+
* Lease fencing token for this claim. Send it back on
|
|
1000
|
+
* complete/fail/heartbeat: the API requires it (a call without it is a 422
|
|
1001
|
+
* `ValidationError`, since 2026-07) and rejects a stale lease with 409.
|
|
704
1002
|
*/
|
|
705
1003
|
leaseId?: string | null;
|
|
706
1004
|
}
|
|
@@ -725,7 +1023,10 @@ interface CompleteJobParams {
|
|
|
725
1023
|
workerId: string;
|
|
726
1024
|
/** Optional result payload (any JSON) */
|
|
727
1025
|
result?: JsonValue;
|
|
728
|
-
/**
|
|
1026
|
+
/**
|
|
1027
|
+
* Lease fencing token from the claimed job (`ClaimedJob.leaseId`). The API
|
|
1028
|
+
* requires it: without it the call is a 422 `ValidationError`.
|
|
1029
|
+
*/
|
|
729
1030
|
leaseId?: string;
|
|
730
1031
|
}
|
|
731
1032
|
/** Parameters for failing a job */
|
|
@@ -734,7 +1035,10 @@ interface FailJobParams {
|
|
|
734
1035
|
workerId: string;
|
|
735
1036
|
/** Error message (1-2048 chars) */
|
|
736
1037
|
error: string;
|
|
737
|
-
/**
|
|
1038
|
+
/**
|
|
1039
|
+
* Lease fencing token from the claimed job (`ClaimedJob.leaseId`). The API
|
|
1040
|
+
* requires it: without it the call is a 422 `ValidationError`.
|
|
1041
|
+
*/
|
|
738
1042
|
leaseId?: string;
|
|
739
1043
|
}
|
|
740
1044
|
/** Parameters for job heartbeat */
|
|
@@ -743,7 +1047,10 @@ interface HeartbeatJobParams {
|
|
|
743
1047
|
workerId: string;
|
|
744
1048
|
/** Lease duration in seconds (5-3600) */
|
|
745
1049
|
leaseDurationSecs: number;
|
|
746
|
-
/**
|
|
1050
|
+
/**
|
|
1051
|
+
* Lease fencing token from the claimed job (`ClaimedJob.leaseId`). The API
|
|
1052
|
+
* requires it: without it the call is a 422 `ValidationError`.
|
|
1053
|
+
*/
|
|
747
1054
|
leaseId?: string;
|
|
748
1055
|
}
|
|
749
1056
|
/** Response for priority boost */
|
|
@@ -788,10 +1095,37 @@ interface BulkEnqueueResponse {
|
|
|
788
1095
|
failureCount: number;
|
|
789
1096
|
}
|
|
790
1097
|
/** Parameters for listing DLQ */
|
|
791
|
-
interface ListDlqParams extends ListParams {
|
|
1098
|
+
interface ListDlqParams extends ListParams, JobSearchParams {
|
|
792
1099
|
/** Filter by queue name */
|
|
793
1100
|
queueName?: string;
|
|
794
1101
|
}
|
|
1102
|
+
/**
|
|
1103
|
+
* Event types of `GET /jobs/{id}/history`. The server records `processing`
|
|
1104
|
+
* (REST claim), `completed` (REST complete), `retry_scheduled` and
|
|
1105
|
+
* `deadlettered` (REST fail, scheduler sweeps); `created` is defined but not
|
|
1106
|
+
* written today, and jobs settled over gRPC have sparse history. Any other
|
|
1107
|
+
* string the server sends is passed through.
|
|
1108
|
+
*/
|
|
1109
|
+
type JobHistoryEventType = "created" | "processing" | "completed" | "retry_scheduled" | "deadlettered" | (string & {});
|
|
1110
|
+
/** One recorded lifecycle event of a job (`GET /jobs/{id}/history`) */
|
|
1111
|
+
interface JobHistoryEvent {
|
|
1112
|
+
id: string;
|
|
1113
|
+
jobId: string;
|
|
1114
|
+
eventType: JobHistoryEventType;
|
|
1115
|
+
/** The worker that caused the event, when known */
|
|
1116
|
+
workerId?: string | null;
|
|
1117
|
+
/**
|
|
1118
|
+
* Event details as stored (any JSON, keys left in snake_case as the server
|
|
1119
|
+
* wrote them).
|
|
1120
|
+
*/
|
|
1121
|
+
details: JsonValue;
|
|
1122
|
+
createdAt: string;
|
|
1123
|
+
}
|
|
1124
|
+
/** Parameters for `jobs.history()` (API 0.1.122+) */
|
|
1125
|
+
interface JobHistoryParams extends PaginationParams {
|
|
1126
|
+
/** `asc` (default, oldest first) or `desc` (newest first) */
|
|
1127
|
+
order?: "asc" | "desc";
|
|
1128
|
+
}
|
|
795
1129
|
/** Parameters for retrying DLQ jobs */
|
|
796
1130
|
interface RetryDlqParams {
|
|
797
1131
|
/** Specific job IDs to retry */
|
|
@@ -830,6 +1164,11 @@ interface PurgeDlqResponse {
|
|
|
830
1164
|
interface DlqOperations {
|
|
831
1165
|
/** List jobs in dead-letter queue */
|
|
832
1166
|
list(params?: ListDlqParams): Promise<JobSummary[]>;
|
|
1167
|
+
/**
|
|
1168
|
+
* List one page of the dead-letter queue with `hasMore` from the
|
|
1169
|
+
* `X-Has-More` header (API 0.1.122+).
|
|
1170
|
+
*/
|
|
1171
|
+
listPage(params?: ListDlqParams): Promise<ListPage<JobSummary>>;
|
|
833
1172
|
/** Retry jobs from DLQ */
|
|
834
1173
|
retry(params: RetryDlqParams): Promise<RetryDlqResponse>;
|
|
835
1174
|
/** Purge jobs from DLQ */
|
|
@@ -850,8 +1189,33 @@ declare class JobsResource {
|
|
|
850
1189
|
createAndGet(params: CreateJobParams): Promise<Job>;
|
|
851
1190
|
/**
|
|
852
1191
|
* List jobs with optional filtering
|
|
1192
|
+
*
|
|
1193
|
+
* `status` takes one status or several, and `q`, `jobType`, `createdAfter`
|
|
1194
|
+
* and `createdBefore` filter on the server (API 0.1.122+). Use
|
|
1195
|
+
* {@link JobsResource.listPage} to also learn whether another page follows.
|
|
853
1196
|
*/
|
|
854
1197
|
list(params?: ListJobsParams): Promise<JobSummary[]>;
|
|
1198
|
+
/**
|
|
1199
|
+
* List one page of jobs with `hasMore` from the `X-Has-More` header
|
|
1200
|
+
* (API 0.1.122+). Takes the same filters as {@link JobsResource.list}.
|
|
1201
|
+
*
|
|
1202
|
+
* @example
|
|
1203
|
+
* ```typescript
|
|
1204
|
+
* let offset = 0;
|
|
1205
|
+
* for (;;) {
|
|
1206
|
+
* const page = await client.jobs.listPage({
|
|
1207
|
+
* status: ["failed", "deadletter"],
|
|
1208
|
+
* createdAfter: new Date(Date.now() - 86_400_000),
|
|
1209
|
+
* limit: 100,
|
|
1210
|
+
* offset,
|
|
1211
|
+
* });
|
|
1212
|
+
* handle(page.data);
|
|
1213
|
+
* if (!page.hasMore) break;
|
|
1214
|
+
* offset += page.data.length;
|
|
1215
|
+
* }
|
|
1216
|
+
* ```
|
|
1217
|
+
*/
|
|
1218
|
+
listPage(params?: ListJobsParams): Promise<ListPage<JobSummary>>;
|
|
855
1219
|
/**
|
|
856
1220
|
* Get a job by ID
|
|
857
1221
|
*/
|
|
@@ -868,6 +1232,21 @@ declare class JobsResource {
|
|
|
868
1232
|
* Boost job priority
|
|
869
1233
|
*/
|
|
870
1234
|
boostPriority(id: string, priority: number): Promise<BoostPriorityResponse>;
|
|
1235
|
+
/**
|
|
1236
|
+
* Get the recorded lifecycle events of a job (`GET /jobs/{id}/history`,
|
|
1237
|
+
* API 0.1.122+), oldest first unless `order: "desc"`.
|
|
1238
|
+
*
|
|
1239
|
+
* The history is sparse: the server records REST claims (`processing`),
|
|
1240
|
+
* completions (`completed`) and failures (`retry_scheduled`,
|
|
1241
|
+
* `deadlettered`) and the scheduler's dead-letter sweeps, so a job settled
|
|
1242
|
+
* over gRPC may have few or no events. An unknown job is a `NotFoundError`.
|
|
1243
|
+
*/
|
|
1244
|
+
history(id: string, params?: JobHistoryParams): Promise<JobHistoryEvent[]>;
|
|
1245
|
+
/**
|
|
1246
|
+
* One page of {@link JobsResource.history} with `hasMore` from the
|
|
1247
|
+
* `X-Has-More` header. `limit` defaults to 100 (at most 500).
|
|
1248
|
+
*/
|
|
1249
|
+
historyPage(id: string, params?: JobHistoryParams): Promise<ListPage<JobHistoryEvent>>;
|
|
871
1250
|
/**
|
|
872
1251
|
* Get job statistics
|
|
873
1252
|
*/
|
|
@@ -915,6 +1294,8 @@ declare class JobsResource {
|
|
|
915
1294
|
success: boolean;
|
|
916
1295
|
}>;
|
|
917
1296
|
private listDlq;
|
|
1297
|
+
private listDlqPage;
|
|
1298
|
+
private listSummaries;
|
|
918
1299
|
private retryDlq;
|
|
919
1300
|
private purgeDlq;
|
|
920
1301
|
}
|
|
@@ -1065,6 +1446,17 @@ interface Worker {
|
|
|
1065
1446
|
registeredAt: string;
|
|
1066
1447
|
/** Last row update (detail response). */
|
|
1067
1448
|
updatedAt?: string;
|
|
1449
|
+
/**
|
|
1450
|
+
* Jobs this worker completed while it held the lease (API 0.1.122+; counts
|
|
1451
|
+
* start at 0 with that release).
|
|
1452
|
+
*/
|
|
1453
|
+
jobsProcessed?: number;
|
|
1454
|
+
/**
|
|
1455
|
+
* Failed attempts this worker reported while it held the lease: a fail
|
|
1456
|
+
* that was retried or dead-lettered (API 0.1.122+). Lease-expiry recovery
|
|
1457
|
+
* does not count.
|
|
1458
|
+
*/
|
|
1459
|
+
jobsFailed?: number;
|
|
1068
1460
|
}
|
|
1069
1461
|
/** Worker summary for list responses */
|
|
1070
1462
|
interface WorkerSummary {
|
|
@@ -1075,6 +1467,10 @@ interface WorkerSummary {
|
|
|
1075
1467
|
currentJobs: number;
|
|
1076
1468
|
maxConcurrency: number;
|
|
1077
1469
|
lastHeartbeat: string;
|
|
1470
|
+
/** See {@link Worker.jobsProcessed} (API 0.1.122+). */
|
|
1471
|
+
jobsProcessed?: number;
|
|
1472
|
+
/** See {@link Worker.jobsFailed} (API 0.1.122+). */
|
|
1473
|
+
jobsFailed?: number;
|
|
1078
1474
|
}
|
|
1079
1475
|
/** Parameters for registering a worker */
|
|
1080
1476
|
interface RegisterWorkerParams {
|
|
@@ -1599,6 +1995,12 @@ interface OutgoingWebhook {
|
|
|
1599
1995
|
* it is re-enabled with `update(id, { enabled: true })`.
|
|
1600
1996
|
*/
|
|
1601
1997
|
lastStatus?: "success" | "failed" | "auto_disabled";
|
|
1998
|
+
/**
|
|
1999
|
+
* Body format of the deliveries (API 0.1.122+; absent from older servers,
|
|
2000
|
+
* which only send `json`). A format newer than this SDK is passed through
|
|
2001
|
+
* as a string.
|
|
2002
|
+
*/
|
|
2003
|
+
format?: WebhookFormat | (string & {});
|
|
1602
2004
|
createdAt: string;
|
|
1603
2005
|
updatedAt: string;
|
|
1604
2006
|
}
|
|
@@ -1614,6 +2016,11 @@ interface CreateOutgoingWebhookParams {
|
|
|
1614
2016
|
secret?: string;
|
|
1615
2017
|
/** Whether enabled (default: true) */
|
|
1616
2018
|
enabled?: boolean;
|
|
2019
|
+
/**
|
|
2020
|
+
* Body format (default `json`; API 0.1.122+). `slack`, `discord` and
|
|
2021
|
+
* `teams` post a chat message to that service's incoming-webhook URL.
|
|
2022
|
+
*/
|
|
2023
|
+
format?: WebhookFormat;
|
|
1617
2024
|
}
|
|
1618
2025
|
/**
|
|
1619
2026
|
* Parameters for updating an outgoing webhook.
|
|
@@ -1644,6 +2051,8 @@ interface UpdateOutgoingWebhookParams {
|
|
|
1644
2051
|
* `QUOTA_EXCEEDED` even though no webhook is being created.
|
|
1645
2052
|
*/
|
|
1646
2053
|
enabled?: boolean;
|
|
2054
|
+
/** New body format; omit it to keep the current one (API 0.1.122+). */
|
|
2055
|
+
format?: WebhookFormat;
|
|
1647
2056
|
}
|
|
1648
2057
|
/** Response for webhook test */
|
|
1649
2058
|
interface TestWebhookResponse {
|
|
@@ -2348,6 +2757,38 @@ interface IngestCustomWebhookResponse {
|
|
|
2348
2757
|
queueName?: string;
|
|
2349
2758
|
status?: string;
|
|
2350
2759
|
}
|
|
2760
|
+
/** `status` of an inbound webhook log entry */
|
|
2761
|
+
type InboundDeliveryStatus = "created" | "duplicate";
|
|
2762
|
+
/** Parameters for `ingest.listDeliveries()` (`GET /webhooks/deliveries`) */
|
|
2763
|
+
interface ListInboundDeliveriesParams extends PaginationParams {
|
|
2764
|
+
/** `created` (a new job) or `duplicate` (an idempotent replay) */
|
|
2765
|
+
status?: InboundDeliveryStatus;
|
|
2766
|
+
/**
|
|
2767
|
+
* Only entries received at or after this instant. A `Date` is sent as an
|
|
2768
|
+
* ISO 8601 UTC string; a string must be RFC 3339.
|
|
2769
|
+
*/
|
|
2770
|
+
since?: Date | string;
|
|
2771
|
+
/** Only entries whose job went to this queue (exact match) */
|
|
2772
|
+
queueName?: string;
|
|
2773
|
+
}
|
|
2774
|
+
/**
|
|
2775
|
+
* One accepted request to `POST /webhooks/{org_id}/custom`, from the inbound
|
|
2776
|
+
* webhook log (API 0.1.122+). The log never holds the payload or a signature.
|
|
2777
|
+
*/
|
|
2778
|
+
interface InboundWebhookDelivery {
|
|
2779
|
+
id: string;
|
|
2780
|
+
/** `custom` today */
|
|
2781
|
+
provider: string;
|
|
2782
|
+
/** The request's event type, `custom` when it had none */
|
|
2783
|
+
eventType: string;
|
|
2784
|
+
/** Queue of the job the request resolved to */
|
|
2785
|
+
matchedQueue: string | null;
|
|
2786
|
+
/** Job the request created or matched (`null` for entries before 0.1.122) */
|
|
2787
|
+
jobId: string | null;
|
|
2788
|
+
/** `created` or `duplicate` (`null` for entries before 0.1.122) */
|
|
2789
|
+
status: InboundDeliveryStatus | (string & {}) | null;
|
|
2790
|
+
createdAt: string;
|
|
2791
|
+
}
|
|
2351
2792
|
/** @deprecated The API has no GitHub webhook route; `ingest.github` throws. */
|
|
2352
2793
|
interface IngestGitHubWebhookOptions {
|
|
2353
2794
|
/** Value for X-GitHub-Event header (e.g. "pull_request") */
|
|
@@ -2416,6 +2857,17 @@ declare class WebhookIngestionResource {
|
|
|
2416
2857
|
webhookToken?: string;
|
|
2417
2858
|
forwardedProto?: string;
|
|
2418
2859
|
}): Promise<IngestCustomWebhookResponse>;
|
|
2860
|
+
/**
|
|
2861
|
+
* The inbound webhook log: accepted requests to
|
|
2862
|
+
* `POST /webhooks/{org_id}/custom`, newest first
|
|
2863
|
+
* (`GET /webhooks/deliveries`, API 0.1.122+).
|
|
2864
|
+
*
|
|
2865
|
+
* Needs an API key without a queue restriction (a queue-scoped key gets a
|
|
2866
|
+
* 403 `AuthorizationError`). Entries carry no payload and no signature;
|
|
2867
|
+
* requests that were rejected are not logged. `limit` defaults to 50 (at
|
|
2868
|
+
* most 100); an invalid filter is a 400 `ValidationError`.
|
|
2869
|
+
*/
|
|
2870
|
+
listDeliveries(params?: ListInboundDeliveriesParams): Promise<InboundWebhookDelivery[]>;
|
|
2419
2871
|
}
|
|
2420
2872
|
|
|
2421
2873
|
/**
|
|
@@ -2846,9 +3298,11 @@ interface GrpcFailRequest {
|
|
|
2846
3298
|
error: string;
|
|
2847
3299
|
/**
|
|
2848
3300
|
* Retry the job (until its `maxRetries` run out) instead of dead-lettering it
|
|
2849
|
-
* at once. Defaults to `true
|
|
2850
|
-
*
|
|
2851
|
-
* `false`
|
|
3301
|
+
* at once. Defaults to `true`, which the SDK sends explicitly, so servers
|
|
3302
|
+
* from before proto field 4 became `optional bool` (where an absent field
|
|
3303
|
+
* read as `false` and dead-lettered the job on its first failure) behave the
|
|
3304
|
+
* same. Pass `false` to dead-letter the job now, whatever `maxRetries` says:
|
|
3305
|
+
* the SDK puts `retry = false` on the wire with field presence.
|
|
2852
3306
|
*/
|
|
2853
3307
|
retry?: boolean;
|
|
2854
3308
|
/**
|
|
@@ -2937,6 +3391,17 @@ interface GrpcRegisterWorkerRequest {
|
|
|
2937
3391
|
maxConcurrency?: number;
|
|
2938
3392
|
version?: string;
|
|
2939
3393
|
metadata?: Record<string, string>;
|
|
3394
|
+
/**
|
|
3395
|
+
* Stable worker id (proto `optional string worker_id = 7`): 1-128
|
|
3396
|
+
* characters, letters, digits, `-`, `_` and `.`.
|
|
3397
|
+
*
|
|
3398
|
+
* Send the same id after a restart and the server updates that worker
|
|
3399
|
+
* instead of adding one, so a restarting worker does not count twice against
|
|
3400
|
+
* the plan's worker limit. Omitted or empty: the server assigns a new id. An
|
|
3401
|
+
* id that another organization already uses fails with ALREADY_EXISTS
|
|
3402
|
+
* (`ConflictError`). Servers older than API 0.1.119 ignore the field.
|
|
3403
|
+
*/
|
|
3404
|
+
workerId?: string;
|
|
2940
3405
|
}
|
|
2941
3406
|
/** Register worker response */
|
|
2942
3407
|
interface GrpcRegisterWorkerResponse {
|
|
@@ -3432,6 +3897,15 @@ declare class SpooledClient {
|
|
|
3432
3897
|
* Get current configuration (read-only)
|
|
3433
3898
|
*/
|
|
3434
3899
|
getConfig(): Readonly<ResolvedConfig>;
|
|
3900
|
+
/**
|
|
3901
|
+
* Rate-limit state from the most recent response that carried
|
|
3902
|
+
* `X-RateLimit-*` headers (API 0.1.122+): `limit`, `remaining`, `reset`
|
|
3903
|
+
* (from the Unix-seconds header), `scope` and, after a 429, `retryAfter`.
|
|
3904
|
+
* `undefined` until such a response arrives, and for servers or routes that
|
|
3905
|
+
* do not send the headers. A 429 also carries the same values on
|
|
3906
|
+
* `RateLimitError.rateLimitInfo`.
|
|
3907
|
+
*/
|
|
3908
|
+
getRateLimitInfo(): RateLimitInfo | undefined;
|
|
3435
3909
|
/**
|
|
3436
3910
|
* Get circuit breaker statistics
|
|
3437
3911
|
*/
|
|
@@ -3724,4 +4198,4 @@ declare class SpooledWorker {
|
|
|
3724
4198
|
private waitForDrain;
|
|
3725
4199
|
}
|
|
3726
4200
|
|
|
3727
|
-
export { type
|
|
4201
|
+
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 };
|