@aniket-lodh/veyra-sdk 0.1.0 → 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.
Files changed (50) hide show
  1. package/README.md +209 -120
  2. package/dist/cjs/client.d.ts +204 -0
  3. package/dist/cjs/client.js +647 -0
  4. package/dist/cjs/errors.d.ts +147 -0
  5. package/dist/cjs/errors.js +262 -0
  6. package/dist/cjs/handlers.d.ts +165 -0
  7. package/dist/cjs/handlers.js +46 -0
  8. package/dist/cjs/index.d.ts +15 -0
  9. package/dist/cjs/index.js +37 -0
  10. package/dist/cjs/package.json +3 -0
  11. package/dist/cjs/standard-schema.d.ts +86 -0
  12. package/dist/cjs/standard-schema.js +49 -0
  13. package/dist/cjs/types.d.ts +430 -0
  14. package/dist/cjs/types.js +6 -0
  15. package/dist/cjs/webhook.d.ts +98 -0
  16. package/dist/cjs/webhook.js +165 -0
  17. package/dist/cjs/worker.d.ts +101 -0
  18. package/dist/cjs/worker.js +497 -0
  19. package/dist/client.d.ts +159 -25
  20. package/dist/client.js +501 -122
  21. package/dist/errors.d.ts +123 -10
  22. package/dist/errors.js +192 -19
  23. package/dist/handlers.d.ts +165 -0
  24. package/dist/handlers.js +42 -0
  25. package/dist/index.d.ts +13 -6
  26. package/dist/index.js +12 -6
  27. package/dist/standard-schema.d.ts +86 -0
  28. package/dist/standard-schema.js +45 -0
  29. package/dist/types.d.ts +281 -36
  30. package/dist/types.js +2 -2
  31. package/dist/webhook.d.ts +98 -0
  32. package/dist/webhook.js +128 -0
  33. package/dist/worker.d.ts +80 -55
  34. package/dist/worker.js +308 -195
  35. package/package.json +27 -13
  36. package/dist/client.d.ts.map +0 -1
  37. package/dist/client.js.map +0 -1
  38. package/dist/errors.d.ts.map +0 -1
  39. package/dist/errors.js.map +0 -1
  40. package/dist/index.d.ts.map +0 -1
  41. package/dist/index.js.map +0 -1
  42. package/dist/types.d.ts.map +0 -1
  43. package/dist/types.js.map +0 -1
  44. package/dist/worker.d.ts.map +0 -1
  45. package/dist/worker.js.map +0 -1
  46. package/src/client.ts +0 -389
  47. package/src/errors.ts +0 -82
  48. package/src/index.ts +0 -8
  49. package/src/types.ts +0 -217
  50. package/src/worker.ts +0 -472
package/dist/client.d.ts CHANGED
@@ -1,70 +1,204 @@
1
1
  /**
2
- * Veyra HTTP Client
2
+ * Veyra HTTP client.
3
3
  */
4
- import type { ClaimParams, CompleteJobResponse, EnqueueJobInput, FailJobParams, FailJobResponse, HeartbeatResponse, Job, JobClaim, RenewLeaseResponse, VeyraClientConfig, VeyraWorkerOptions, WorkerRecord, WorkerRegisterParams } from './types.js';
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
- export declare class VeyraClient {
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
- readonly apiKey: string;
28
+ /** Queue used when `enqueue` omits `queue`. */
9
29
  readonly defaultQueue: string;
10
- private readonly customFetch?;
11
- private readonly defaultTimeoutMs;
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
- * Enqueues a job into Veyra's queue.
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
- enqueue<TPayload = unknown, TResult = unknown>(input: EnqueueJobInput<TPayload>): Promise<Job<TPayload, TResult>>;
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
- * Retrieves a job by ID.
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<TPayload = unknown, TResult = unknown>(jobId: string): Promise<Job<TPayload, TResult>>;
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 job by ID.
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 in the Veyra cluster.
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 a job for execution. Returns null if queue is empty (204 No Content).
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 state to draining.
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 VeyraWorker managed instance tied to this client.
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