@aniket-lodh/veyra-sdk 0.1.1 → 0.2.0
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 +205 -116
- package/dist/cjs/client.d.ts +204 -0
- package/dist/cjs/client.js +647 -0
- package/dist/cjs/errors.d.ts +147 -0
- package/dist/cjs/errors.js +262 -0
- package/dist/cjs/handlers.d.ts +165 -0
- package/dist/cjs/handlers.js +46 -0
- package/dist/cjs/index.d.ts +15 -0
- package/dist/cjs/index.js +37 -0
- package/dist/cjs/package.json +3 -0
- package/dist/cjs/standard-schema.d.ts +86 -0
- package/dist/cjs/standard-schema.js +49 -0
- package/dist/cjs/types.d.ts +430 -0
- package/dist/cjs/types.js +6 -0
- package/dist/cjs/webhook.d.ts +98 -0
- package/dist/cjs/webhook.js +165 -0
- package/dist/cjs/worker.d.ts +101 -0
- package/dist/cjs/worker.js +497 -0
- package/dist/client.d.ts +159 -25
- package/dist/client.js +501 -122
- package/dist/errors.d.ts +123 -10
- package/dist/errors.js +192 -19
- package/dist/handlers.d.ts +165 -0
- package/dist/handlers.js +42 -0
- package/dist/index.d.ts +13 -6
- package/dist/index.js +12 -6
- package/dist/standard-schema.d.ts +86 -0
- package/dist/standard-schema.js +45 -0
- package/dist/types.d.ts +281 -36
- package/dist/types.js +2 -2
- package/dist/webhook.d.ts +98 -0
- package/dist/webhook.js +128 -0
- package/dist/worker.d.ts +80 -55
- package/dist/worker.js +308 -192
- package/package.json +21 -12
- package/dist/client.d.ts.map +0 -1
- package/dist/client.js.map +0 -1
- package/dist/errors.d.ts.map +0 -1
- package/dist/errors.js.map +0 -1
- package/dist/index.d.ts.map +0 -1
- package/dist/index.js.map +0 -1
- package/dist/types.d.ts.map +0 -1
- package/dist/types.js.map +0 -1
- package/dist/worker.d.ts.map +0 -1
- package/dist/worker.js.map +0 -1
- package/src/client.ts +0 -389
- package/src/errors.ts +0 -82
- package/src/index.ts +0 -8
- package/src/types.ts +0 -217
- package/src/worker.ts +0 -469
package/dist/client.d.ts
CHANGED
|
@@ -1,70 +1,204 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Veyra HTTP
|
|
2
|
+
* Veyra HTTP client.
|
|
3
3
|
*/
|
|
4
|
-
import type {
|
|
4
|
+
import type { BuiltInHandlers, DefinitionPayload, DefinitionResult, HandlerDefinition, HandlerName, HandlerPayload, HandlerResult, ResolvedHandlers } from './handlers.js';
|
|
5
|
+
import type { ClaimParams, CompleteJobResponse, DefinitionEnqueueInput, DeregisterWorkerResponse, EnqueueOptions, FailJobParams, FailJobResponse, HeartbeatResponse, Job, JobClaim, RenewLeaseResponse, RequestOptions, TypedEnqueueInput, TypedEnqueuePayload, TypedEnqueueResult, VeyraClientConfig, VeyraWorkerOptions, WorkerRecord, WorkerRegisterParams } from './types.js';
|
|
5
6
|
import { VeyraWorker } from './worker.js';
|
|
6
|
-
|
|
7
|
+
/**
|
|
8
|
+
* Typed client for the Veyra REST API.
|
|
9
|
+
*
|
|
10
|
+
* @typeParam THandlers - Extra handler contracts merged over {@link BuiltInHandlers}.
|
|
11
|
+
* Register handlers here to get autocomplete and payload/result checking on
|
|
12
|
+
* string-based `enqueue` calls shared across services.
|
|
13
|
+
*
|
|
14
|
+
* @example
|
|
15
|
+
* ```ts
|
|
16
|
+
* interface MyHandlers {
|
|
17
|
+
* send_email: { payload: { to: string }; result: { messageId: string } };
|
|
18
|
+
* }
|
|
19
|
+
* const client = new VeyraClient<MyHandlers>({ baseUrl, apiKey });
|
|
20
|
+
* const job = await client.enqueue({ handler: 'send_email', payload: { to: 'a@b.c' } });
|
|
21
|
+
* job.result?.messageId; // string
|
|
22
|
+
* ```
|
|
23
|
+
*/
|
|
24
|
+
export declare class VeyraClient<THandlers extends object = BuiltInHandlers> {
|
|
25
|
+
#private;
|
|
26
|
+
/** API origin without a trailing slash. */
|
|
7
27
|
readonly baseUrl: string;
|
|
8
|
-
|
|
28
|
+
/** Queue used when `enqueue` omits `queue`. */
|
|
9
29
|
readonly defaultQueue: string;
|
|
10
|
-
|
|
11
|
-
|
|
30
|
+
/**
|
|
31
|
+
* @param config - API origin, API key, and transport settings.
|
|
32
|
+
* @throws {VeyraValidationError} When `baseUrl` or `apiKey` is invalid.
|
|
33
|
+
*/
|
|
12
34
|
constructor(config: VeyraClientConfig);
|
|
13
35
|
/**
|
|
14
|
-
*
|
|
36
|
+
* Safe JSON representation redacting all sensitive credentials.
|
|
37
|
+
*/
|
|
38
|
+
toJSON(): Record<string, unknown>;
|
|
39
|
+
/**
|
|
40
|
+
* Enqueues a job from a {@link HandlerDefinition}. The payload is validated
|
|
41
|
+
* against the definition's schema before the request is sent.
|
|
42
|
+
*
|
|
43
|
+
* @param handler - Definition created with `defineHandler`.
|
|
44
|
+
* @param payload - Payload matching the definition.
|
|
45
|
+
* @param options - Per-call overrides. `options.queue` wins over the definition's queue.
|
|
46
|
+
* @returns The created (or idempotently replayed) job.
|
|
47
|
+
* @throws {VeyraValidationError} When the payload fails schema validation or inputs are invalid.
|
|
48
|
+
*
|
|
49
|
+
* @example
|
|
50
|
+
* ```ts
|
|
51
|
+
* await client.enqueue(sendEmail, { to: 'a@b.c', subject: 'Hi' });
|
|
52
|
+
* ```
|
|
53
|
+
*/
|
|
54
|
+
enqueue<TName extends string, TPayload, TResult, TQueue extends string | undefined>(handler: HandlerDefinition<TName, TPayload, TResult, TQueue>, payload: TPayload, options?: EnqueueOptions): Promise<Job<TPayload, TResult>>;
|
|
55
|
+
/**
|
|
56
|
+
* Enqueues a job using an object containing a {@link HandlerDefinition}.
|
|
57
|
+
* The payload is validated against the definition's schema before sending.
|
|
58
|
+
*
|
|
59
|
+
* @param input - Definition handler, payload, and optional enqueue options.
|
|
60
|
+
* @returns The created (or idempotently replayed) job.
|
|
61
|
+
* @throws {VeyraValidationError} When the payload fails schema validation or inputs are invalid.
|
|
62
|
+
*
|
|
63
|
+
* @example
|
|
64
|
+
* ```ts
|
|
65
|
+
* await client.enqueue({ handler: sendEmail, payload: { to: 'a@b.c', subject: 'Hi' } });
|
|
66
|
+
* ```
|
|
67
|
+
*/
|
|
68
|
+
enqueue<TDefinition extends HandlerDefinition<any, any, any, any>>(input: DefinitionEnqueueInput<TDefinition>): Promise<Job<DefinitionPayload<TDefinition>, DefinitionResult<TDefinition>>>;
|
|
69
|
+
/**
|
|
70
|
+
* Enqueues a job using the object form.
|
|
71
|
+
*
|
|
72
|
+
* Known handler names (built-ins plus `THandlers`) autocomplete and constrain
|
|
73
|
+
* `payload` and type `result`; unknown string names fall back to the supplied generics.
|
|
74
|
+
*
|
|
75
|
+
* @param input - Handler name, payload, and optional enqueue options.
|
|
76
|
+
* @returns The created (or idempotently replayed) job.
|
|
77
|
+
* @throws {VeyraApiError} When the API rejects the request.
|
|
78
|
+
*
|
|
79
|
+
* @example
|
|
80
|
+
* ```ts
|
|
81
|
+
* await client.enqueue({ handler: 'http_request', payload: { url: 'https://example.com' } });
|
|
82
|
+
* ```
|
|
83
|
+
*/
|
|
84
|
+
enqueue<TPayload = unknown, TResult = unknown, const TName extends HandlerName<ResolvedHandlers<THandlers>> | (string & {}) = HandlerName<ResolvedHandlers<THandlers>> | (string & {})>(input: TypedEnqueueInput<ResolvedHandlers<THandlers>, TName, TPayload>): Promise<Job<TypedEnqueuePayload<ResolvedHandlers<THandlers>, TName, TPayload>, TypedEnqueueResult<ResolvedHandlers<THandlers>, TName, TResult>>>;
|
|
85
|
+
/**
|
|
86
|
+
* Fetches a job and validates its result with the definition's schema.
|
|
87
|
+
*
|
|
88
|
+
* @param jobId - Job ULID.
|
|
89
|
+
* @param handler - Definition whose result schema should validate `job.result`.
|
|
90
|
+
* @param options - Request cancellation and retry options.
|
|
91
|
+
* @returns The job with `result` typed as the definition's result.
|
|
92
|
+
*/
|
|
93
|
+
getJob<TName extends string, TPayload, TResult, TQueue extends string | undefined>(jobId: string, handler: HandlerDefinition<TName, TPayload, TResult, TQueue>, options?: RequestOptions): Promise<Job<TPayload, TResult>>;
|
|
94
|
+
/**
|
|
95
|
+
* Fetches a job for a known built-in or registered handler name.
|
|
96
|
+
*
|
|
97
|
+
* @param jobId - Job ULID.
|
|
98
|
+
* @param handler - Known handler name string.
|
|
99
|
+
* @param options - Request cancellation and retry options.
|
|
100
|
+
* @returns The job with `payload` and `result` typed according to the handler contract.
|
|
15
101
|
*/
|
|
16
|
-
|
|
102
|
+
getJob<const TName extends HandlerName<ResolvedHandlers<THandlers>>>(jobId: string, handler: TName, options?: RequestOptions): Promise<Job<HandlerPayload<ResolvedHandlers<THandlers>, TName>, HandlerResult<ResolvedHandlers<THandlers>, TName>>>;
|
|
17
103
|
/**
|
|
18
|
-
*
|
|
104
|
+
* Fetches a job with only the result type specified.
|
|
105
|
+
*
|
|
106
|
+
* @param jobId - Job ULID.
|
|
107
|
+
* @param options - Request cancellation and retry options.
|
|
108
|
+
* @returns The job with `result` typed as `TResult`.
|
|
19
109
|
*/
|
|
20
|
-
getJob<
|
|
110
|
+
getJob<TResult = unknown>(jobId: string, options?: RequestOptions): Promise<Job<unknown, TResult>>;
|
|
111
|
+
/** @deprecated Prefer `getJob<TResult>(jobId)` or `getJob(jobId, handler)`. */
|
|
112
|
+
getJob<TPayload = unknown, TResult = unknown>(jobId: string, options?: RequestOptions): Promise<Job<TPayload, TResult>>;
|
|
21
113
|
/**
|
|
22
|
-
* Cancels a
|
|
114
|
+
* Cancels a queued, scheduled, failed, or running job.
|
|
115
|
+
*
|
|
116
|
+
* @param jobId - Job ULID.
|
|
117
|
+
* @param options - Request cancellation and retry options.
|
|
118
|
+
* @returns The cancelled job.
|
|
119
|
+
* @throws {VeyraConflictError} When the job already succeeded or was dead-lettered.
|
|
23
120
|
*/
|
|
24
|
-
cancelJob(jobId: string): Promise<Job>;
|
|
121
|
+
cancelJob(jobId: string, options?: RequestOptions): Promise<Job>;
|
|
25
122
|
/**
|
|
26
123
|
* Retries a failed, cancelled, or dead-lettered job.
|
|
124
|
+
*
|
|
125
|
+
* @param jobId - Job ULID.
|
|
126
|
+
* @param options - Request cancellation and retry options.
|
|
127
|
+
* @returns The retried job.
|
|
128
|
+
* @throws {VeyraConflictError} When the job is not in a retryable state.
|
|
27
129
|
*/
|
|
28
|
-
retryJob(jobId: string): Promise<Job>;
|
|
130
|
+
retryJob(jobId: string, options?: RequestOptions): Promise<Job>;
|
|
29
131
|
/**
|
|
30
|
-
* Registers a worker
|
|
132
|
+
* Registers a worker with the cluster.
|
|
133
|
+
*
|
|
134
|
+
* @param params - Identity, queues, handlers, and concurrency.
|
|
135
|
+
* @returns The stored worker record.
|
|
31
136
|
*/
|
|
32
137
|
registerWorker(params: WorkerRegisterParams): Promise<WorkerRecord>;
|
|
33
138
|
/**
|
|
34
139
|
* Sends a worker-level heartbeat.
|
|
140
|
+
*
|
|
141
|
+
* @param workerId - Worker id.
|
|
142
|
+
* @returns The worker's current state and heartbeat timestamp.
|
|
143
|
+
* @throws {VeyraNotFoundError} When the worker no longer exists.
|
|
35
144
|
*/
|
|
36
145
|
heartbeatWorker(workerId: string): Promise<HeartbeatResponse>;
|
|
37
146
|
/**
|
|
38
|
-
* Claims
|
|
147
|
+
* Claims the next runnable job for a worker.
|
|
148
|
+
*
|
|
149
|
+
* @param workerId - Worker id.
|
|
150
|
+
* @param params - Optional queue/handler filter.
|
|
151
|
+
* @returns The claimed job, or `null` on `204 No Content`.
|
|
39
152
|
*/
|
|
40
153
|
claimJob<TPayload = unknown>(workerId: string, params?: ClaimParams): Promise<JobClaim<TPayload> | null>;
|
|
41
154
|
/**
|
|
42
155
|
* Renews the lease for an in-flight job.
|
|
156
|
+
*
|
|
157
|
+
* @param workerId - Worker id.
|
|
158
|
+
* @param jobId - Job ULID.
|
|
159
|
+
* @returns The renewed lease.
|
|
160
|
+
* @throws {LeaseLostError} When the lease expired or was reassigned.
|
|
43
161
|
*/
|
|
44
162
|
renewJobLease(workerId: string, jobId: string): Promise<RenewLeaseResponse>;
|
|
45
163
|
/**
|
|
46
|
-
* Marks a job as completed with optional result payload.
|
|
164
|
+
* Marks a job as completed with an optional result payload.
|
|
165
|
+
*
|
|
166
|
+
* @param workerId - Worker id.
|
|
167
|
+
* @param jobId - Job ULID.
|
|
168
|
+
* @param result - JSON result recorded on the job.
|
|
169
|
+
* @returns The completion acknowledgement.
|
|
170
|
+
* @throws {LeaseLostError} When the lease expired or was reassigned.
|
|
47
171
|
*/
|
|
48
172
|
completeJob(workerId: string, jobId: string, result?: unknown): Promise<CompleteJobResponse>;
|
|
49
173
|
/**
|
|
50
174
|
* Reports a job execution failure.
|
|
175
|
+
*
|
|
176
|
+
* @param workerId - Worker id.
|
|
177
|
+
* @param jobId - Job ULID.
|
|
178
|
+
* @param params - Error class, message, stack trace, and permanence.
|
|
179
|
+
* @returns The failure acknowledgement.
|
|
51
180
|
*/
|
|
52
181
|
failJob(workerId: string, jobId: string, params: FailJobParams): Promise<FailJobResponse>;
|
|
53
182
|
/**
|
|
54
|
-
* Transitions worker
|
|
183
|
+
* Transitions a worker to `draining` so it stops claiming new jobs.
|
|
184
|
+
*
|
|
185
|
+
* @param workerId - Worker id.
|
|
186
|
+
* @returns The updated worker record.
|
|
55
187
|
*/
|
|
56
188
|
drainWorker(workerId: string): Promise<WorkerRecord>;
|
|
57
189
|
/**
|
|
58
190
|
* Deregisters a worker from the active fleet.
|
|
191
|
+
*
|
|
192
|
+
* @param workerId - Worker id.
|
|
193
|
+
* @returns The deregistration acknowledgement.
|
|
194
|
+
* @throws {VeyraConflictError} When the worker still holds active leases.
|
|
59
195
|
*/
|
|
60
|
-
deregisterWorker(workerId: string): Promise<
|
|
61
|
-
deregistered: boolean;
|
|
62
|
-
workerId: string;
|
|
63
|
-
}>;
|
|
196
|
+
deregisterWorker(workerId: string): Promise<DeregisterWorkerResponse>;
|
|
64
197
|
/**
|
|
65
|
-
* Creates a
|
|
198
|
+
* Creates a managed {@link VeyraWorker} bound to this client.
|
|
199
|
+
*
|
|
200
|
+
* @param options - Queues, concurrency, and lifecycle callbacks.
|
|
201
|
+
* @returns A worker that inherits this client's handler map.
|
|
66
202
|
*/
|
|
67
|
-
createWorker(options: VeyraWorkerOptions): VeyraWorker
|
|
68
|
-
private request;
|
|
203
|
+
createWorker(options: VeyraWorkerOptions): VeyraWorker<THandlers>;
|
|
69
204
|
}
|
|
70
|
-
//# sourceMappingURL=client.d.ts.map
|