@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.
Files changed (50) hide show
  1. package/README.md +205 -116
  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 -192
  35. package/package.json +21 -12
  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 -469
@@ -0,0 +1,147 @@
1
+ /**
2
+ * Error types thrown by the Veyra SDK.
3
+ */
4
+ import type { StandardSchemaV1 } from './standard-schema.js';
5
+ /**
6
+ * Base error for every SDK failure.
7
+ */
8
+ export declare class VeyraError extends Error {
9
+ /** Error code identifying the failure class. */
10
+ readonly code: string;
11
+ /** Underlying cause if available. */
12
+ readonly cause?: unknown;
13
+ constructor(message: string, options?: {
14
+ code?: string;
15
+ cause?: unknown;
16
+ });
17
+ }
18
+ /**
19
+ * A payload, result, or configuration argument did not satisfy validation rules.
20
+ * Permanent by design: retrying without fixing input cannot succeed.
21
+ */
22
+ export declare class VeyraValidationError extends VeyraError {
23
+ /** Context label, e.g. `handler 'send_email' payload`. */
24
+ readonly label: string;
25
+ /** Structured issues describing the validation failures. */
26
+ readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
27
+ /** Signals permanent failure to the Veyra worker runtime. */
28
+ readonly permanent = true;
29
+ constructor(label: string, issues: ReadonlyArray<StandardSchemaV1.Issue>, options?: {
30
+ cause?: unknown;
31
+ });
32
+ }
33
+ /** Parameters object accepted by {@link VeyraApiError}. */
34
+ export interface VeyraApiErrorParams {
35
+ status: number;
36
+ statusText: string;
37
+ message: string;
38
+ body: unknown;
39
+ requestId?: string;
40
+ retryable?: boolean;
41
+ code?: string;
42
+ cause?: unknown;
43
+ }
44
+ /**
45
+ * Non-2xx HTTP response from the Veyra API.
46
+ */
47
+ export declare class VeyraApiError extends VeyraError {
48
+ /** HTTP status code. */
49
+ readonly status: number;
50
+ /** HTTP status text. */
51
+ readonly statusText: string;
52
+ /** Unique request ID assigned by Veyra API (`X-Request-Id`), if present. */
53
+ readonly requestId?: string;
54
+ /** Whether this failure is safe to retry automatically. */
55
+ readonly retryable: boolean;
56
+ /** Parsed response body or error excerpt. */
57
+ readonly body: unknown;
58
+ constructor(statusOrParams: number | VeyraApiErrorParams, statusText?: string, message?: string, body?: unknown, options?: {
59
+ requestId?: string;
60
+ retryable?: boolean;
61
+ code?: string;
62
+ cause?: unknown;
63
+ });
64
+ }
65
+ /** `401` or `403`: missing, invalid, or insufficiently scoped API key. */
66
+ export declare class VeyraAuthError extends VeyraApiError {
67
+ constructor(statusOrParams: number | VeyraApiErrorParams, statusText?: string, message?: string, body?: unknown, options?: {
68
+ requestId?: string;
69
+ cause?: unknown;
70
+ });
71
+ }
72
+ /** `404`: the requested job, worker, or resource was not found. */
73
+ export declare class VeyraNotFoundError extends VeyraApiError {
74
+ constructor(statusOrParams: number | VeyraApiErrorParams, statusText?: string, message?: string, body?: unknown, options?: {
75
+ requestId?: string;
76
+ cause?: unknown;
77
+ });
78
+ }
79
+ /** `409`: the request conflicts with current queue or worker state. */
80
+ export declare class VeyraConflictError extends VeyraApiError {
81
+ constructor(statusOrParams: number | VeyraApiErrorParams, statusText?: string, message?: string, body?: unknown, options?: {
82
+ requestId?: string;
83
+ cause?: unknown;
84
+ code?: string;
85
+ });
86
+ }
87
+ /**
88
+ * `409` caused by an expired, reclaimed, or reassigned job lease.
89
+ * The worker aborts the job's execution context signal when this is raised.
90
+ */
91
+ export declare class LeaseLostError extends VeyraConflictError {
92
+ constructor(message?: string, options?: {
93
+ requestId?: string;
94
+ cause?: unknown;
95
+ });
96
+ }
97
+ /** `429`: rate limit exceeded. Automatically retried when retries are enabled. */
98
+ export declare class VeyraRateLimitError extends VeyraApiError {
99
+ /** Suggested backoff in milliseconds parsed from `Retry-After` header, if provided. */
100
+ readonly retryAfterMs?: number;
101
+ constructor(statusOrParams: number | (VeyraApiErrorParams & {
102
+ retryAfterMs?: number;
103
+ }), statusText?: string, message?: string, body?: unknown, options?: {
104
+ requestId?: string;
105
+ retryAfterMs?: number;
106
+ cause?: unknown;
107
+ });
108
+ }
109
+ /** Request exceeded its timeout deadline. */
110
+ export declare class VeyraTimeoutError extends VeyraError {
111
+ /** Configured timeout in milliseconds that was exceeded. */
112
+ readonly timeoutMs: number;
113
+ /** Timeouts are safe to retry on idempotent requests. */
114
+ readonly retryable = true;
115
+ constructor(message: string, timeoutMs: number, options?: {
116
+ cause?: unknown;
117
+ });
118
+ }
119
+ /** Network-level transport error (DNS lookup failure, connection refused, connection reset). */
120
+ export declare class VeyraNetworkError extends VeyraError {
121
+ /** Network transport errors are safe to retry on idempotent requests. */
122
+ readonly retryable = true;
123
+ constructor(message: string, options?: {
124
+ cause?: unknown;
125
+ });
126
+ }
127
+ /** Webhook HMAC signature verification failure or malformed webhook payload. */
128
+ export declare class VeyraWebhookError extends VeyraError {
129
+ constructor(message: string, options?: {
130
+ cause?: unknown;
131
+ });
132
+ }
133
+ /**
134
+ * Throw from a worker handler to fail the job permanently: no further attempts,
135
+ * the job is dead-lettered immediately.
136
+ */
137
+ export declare class NonRetryableError extends Error {
138
+ /** Signals permanent failure to the Veyra worker runtime. */
139
+ readonly permanent = true;
140
+ constructor(message: string);
141
+ }
142
+ /**
143
+ * Returns `true` when an error asks the worker to skip retries.
144
+ * Honours {@link NonRetryableError}, {@link VeyraValidationError}, and any
145
+ * error object with `permanent: true`.
146
+ */
147
+ export declare function isNonRetryable(err: unknown): boolean;
@@ -0,0 +1,262 @@
1
+ "use strict";
2
+ /**
3
+ * Error types thrown by the Veyra SDK.
4
+ */
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.NonRetryableError = exports.VeyraWebhookError = exports.VeyraNetworkError = exports.VeyraTimeoutError = exports.VeyraRateLimitError = exports.LeaseLostError = exports.VeyraConflictError = exports.VeyraNotFoundError = exports.VeyraAuthError = exports.VeyraApiError = exports.VeyraValidationError = exports.VeyraError = void 0;
7
+ exports.isNonRetryable = isNonRetryable;
8
+ function formatIssuePath(path) {
9
+ if (!path || path.length === 0) {
10
+ return '';
11
+ }
12
+ return path
13
+ .map((segment) => typeof segment === 'object' && segment !== null && 'key' in segment
14
+ ? String(segment.key)
15
+ : String(segment))
16
+ .join('.');
17
+ }
18
+ /**
19
+ * Base error for every SDK failure.
20
+ */
21
+ class VeyraError extends Error {
22
+ /** Error code identifying the failure class. */
23
+ code;
24
+ /** Underlying cause if available. */
25
+ cause;
26
+ constructor(message, options) {
27
+ super(message);
28
+ this.name = 'VeyraError';
29
+ this.code = options?.code ?? 'VEYRA_ERROR';
30
+ this.cause = options?.cause;
31
+ Object.setPrototypeOf(this, new.target.prototype);
32
+ }
33
+ }
34
+ exports.VeyraError = VeyraError;
35
+ /**
36
+ * A payload, result, or configuration argument did not satisfy validation rules.
37
+ * Permanent by design: retrying without fixing input cannot succeed.
38
+ */
39
+ class VeyraValidationError extends VeyraError {
40
+ /** Context label, e.g. `handler 'send_email' payload`. */
41
+ label;
42
+ /** Structured issues describing the validation failures. */
43
+ issues;
44
+ /** Signals permanent failure to the Veyra worker runtime. */
45
+ permanent = true;
46
+ constructor(label, issues, options) {
47
+ const detail = issues
48
+ .map((issue) => {
49
+ const path = formatIssuePath(issue.path);
50
+ return path ? `${path}: ${issue.message}` : issue.message;
51
+ })
52
+ .join('; ');
53
+ super(`${label} validation failed${detail ? `: ${detail}` : ''}`, {
54
+ code: 'VALIDATION_ERROR',
55
+ cause: options?.cause,
56
+ });
57
+ this.name = 'VeyraValidationError';
58
+ this.label = label;
59
+ this.issues = issues;
60
+ Object.setPrototypeOf(this, new.target.prototype);
61
+ }
62
+ }
63
+ exports.VeyraValidationError = VeyraValidationError;
64
+ /**
65
+ * Non-2xx HTTP response from the Veyra API.
66
+ */
67
+ class VeyraApiError extends VeyraError {
68
+ /** HTTP status code. */
69
+ status;
70
+ /** HTTP status text. */
71
+ statusText;
72
+ /** Unique request ID assigned by Veyra API (`X-Request-Id`), if present. */
73
+ requestId;
74
+ /** Whether this failure is safe to retry automatically. */
75
+ retryable;
76
+ /** Parsed response body or error excerpt. */
77
+ body;
78
+ constructor(statusOrParams, statusText, message, body, options) {
79
+ if (typeof statusOrParams === 'object') {
80
+ const p = statusOrParams;
81
+ super(p.message, { code: p.code ?? 'API_ERROR', cause: p.cause });
82
+ this.name = 'VeyraApiError';
83
+ this.status = p.status;
84
+ this.statusText = p.statusText;
85
+ this.body = p.body;
86
+ this.requestId = p.requestId;
87
+ this.retryable = p.retryable ?? (p.status >= 500 && p.status !== 501);
88
+ }
89
+ else {
90
+ super(message ?? `HTTP ${statusOrParams}`, {
91
+ code: options?.code ?? 'API_ERROR',
92
+ cause: options?.cause,
93
+ });
94
+ this.name = 'VeyraApiError';
95
+ this.status = statusOrParams;
96
+ this.statusText = statusText ?? '';
97
+ this.body = body;
98
+ this.requestId = options?.requestId;
99
+ this.retryable = options?.retryable ?? (statusOrParams >= 500 && statusOrParams !== 501);
100
+ }
101
+ Object.setPrototypeOf(this, new.target.prototype);
102
+ }
103
+ }
104
+ exports.VeyraApiError = VeyraApiError;
105
+ /** `401` or `403`: missing, invalid, or insufficiently scoped API key. */
106
+ class VeyraAuthError extends VeyraApiError {
107
+ constructor(statusOrParams, statusText, message, body, options) {
108
+ if (typeof statusOrParams === 'object') {
109
+ super({ ...statusOrParams, code: 'AUTH_ERROR', retryable: false });
110
+ }
111
+ else {
112
+ super(statusOrParams, statusText, message, body, {
113
+ ...options,
114
+ code: 'AUTH_ERROR',
115
+ retryable: false,
116
+ });
117
+ }
118
+ this.name = 'VeyraAuthError';
119
+ Object.setPrototypeOf(this, new.target.prototype);
120
+ }
121
+ }
122
+ exports.VeyraAuthError = VeyraAuthError;
123
+ /** `404`: the requested job, worker, or resource was not found. */
124
+ class VeyraNotFoundError extends VeyraApiError {
125
+ constructor(statusOrParams, statusText, message, body, options) {
126
+ if (typeof statusOrParams === 'object') {
127
+ super({ ...statusOrParams, code: 'NOT_FOUND', retryable: false });
128
+ }
129
+ else {
130
+ super(statusOrParams, statusText, message, body, {
131
+ ...options,
132
+ code: 'NOT_FOUND',
133
+ retryable: false,
134
+ });
135
+ }
136
+ this.name = 'VeyraNotFoundError';
137
+ Object.setPrototypeOf(this, new.target.prototype);
138
+ }
139
+ }
140
+ exports.VeyraNotFoundError = VeyraNotFoundError;
141
+ /** `409`: the request conflicts with current queue or worker state. */
142
+ class VeyraConflictError extends VeyraApiError {
143
+ constructor(statusOrParams, statusText, message, body, options) {
144
+ if (typeof statusOrParams === 'object') {
145
+ super({
146
+ ...statusOrParams,
147
+ code: statusOrParams.code ?? 'CONFLICT',
148
+ retryable: false,
149
+ });
150
+ }
151
+ else {
152
+ super(statusOrParams, statusText, message, body, {
153
+ ...options,
154
+ code: options?.code ?? 'CONFLICT',
155
+ retryable: false,
156
+ });
157
+ }
158
+ this.name = 'VeyraConflictError';
159
+ Object.setPrototypeOf(this, new.target.prototype);
160
+ }
161
+ }
162
+ exports.VeyraConflictError = VeyraConflictError;
163
+ /**
164
+ * `409` caused by an expired, reclaimed, or reassigned job lease.
165
+ * The worker aborts the job's execution context signal when this is raised.
166
+ */
167
+ class LeaseLostError extends VeyraConflictError {
168
+ constructor(message = 'Job lease was lost or expired', options) {
169
+ super(409, 'Conflict', message, { error: message }, {
170
+ requestId: options?.requestId,
171
+ cause: options?.cause,
172
+ code: 'LEASE_LOST',
173
+ });
174
+ this.name = 'LeaseLostError';
175
+ Object.setPrototypeOf(this, new.target.prototype);
176
+ }
177
+ }
178
+ exports.LeaseLostError = LeaseLostError;
179
+ /** `429`: rate limit exceeded. Automatically retried when retries are enabled. */
180
+ class VeyraRateLimitError extends VeyraApiError {
181
+ /** Suggested backoff in milliseconds parsed from `Retry-After` header, if provided. */
182
+ retryAfterMs;
183
+ constructor(statusOrParams, statusText, message, body, options) {
184
+ if (typeof statusOrParams === 'object') {
185
+ super({ ...statusOrParams, code: 'RATE_LIMIT_EXCEEDED', retryable: true });
186
+ this.retryAfterMs = statusOrParams.retryAfterMs;
187
+ }
188
+ else {
189
+ super(statusOrParams, statusText, message, body, {
190
+ ...options,
191
+ code: 'RATE_LIMIT_EXCEEDED',
192
+ retryable: true,
193
+ });
194
+ this.retryAfterMs = options?.retryAfterMs;
195
+ }
196
+ this.name = 'VeyraRateLimitError';
197
+ Object.setPrototypeOf(this, new.target.prototype);
198
+ }
199
+ }
200
+ exports.VeyraRateLimitError = VeyraRateLimitError;
201
+ /** Request exceeded its timeout deadline. */
202
+ class VeyraTimeoutError extends VeyraError {
203
+ /** Configured timeout in milliseconds that was exceeded. */
204
+ timeoutMs;
205
+ /** Timeouts are safe to retry on idempotent requests. */
206
+ retryable = true;
207
+ constructor(message, timeoutMs, options) {
208
+ super(message, { code: 'TIMEOUT', cause: options?.cause });
209
+ this.name = 'VeyraTimeoutError';
210
+ this.timeoutMs = timeoutMs;
211
+ Object.setPrototypeOf(this, new.target.prototype);
212
+ }
213
+ }
214
+ exports.VeyraTimeoutError = VeyraTimeoutError;
215
+ /** Network-level transport error (DNS lookup failure, connection refused, connection reset). */
216
+ class VeyraNetworkError extends VeyraError {
217
+ /** Network transport errors are safe to retry on idempotent requests. */
218
+ retryable = true;
219
+ constructor(message, options) {
220
+ super(message, { code: 'NETWORK_ERROR', cause: options?.cause });
221
+ this.name = 'VeyraNetworkError';
222
+ Object.setPrototypeOf(this, new.target.prototype);
223
+ }
224
+ }
225
+ exports.VeyraNetworkError = VeyraNetworkError;
226
+ /** Webhook HMAC signature verification failure or malformed webhook payload. */
227
+ class VeyraWebhookError extends VeyraError {
228
+ constructor(message, options) {
229
+ super(message, { code: 'WEBHOOK_ERROR', cause: options?.cause });
230
+ this.name = 'VeyraWebhookError';
231
+ Object.setPrototypeOf(this, new.target.prototype);
232
+ }
233
+ }
234
+ exports.VeyraWebhookError = VeyraWebhookError;
235
+ /**
236
+ * Throw from a worker handler to fail the job permanently: no further attempts,
237
+ * the job is dead-lettered immediately.
238
+ */
239
+ class NonRetryableError extends Error {
240
+ /** Signals permanent failure to the Veyra worker runtime. */
241
+ permanent = true;
242
+ constructor(message) {
243
+ super(message);
244
+ this.name = 'NonRetryableError';
245
+ Object.setPrototypeOf(this, new.target.prototype);
246
+ }
247
+ }
248
+ exports.NonRetryableError = NonRetryableError;
249
+ /**
250
+ * Returns `true` when an error asks the worker to skip retries.
251
+ * Honours {@link NonRetryableError}, {@link VeyraValidationError}, and any
252
+ * error object with `permanent: true`.
253
+ */
254
+ function isNonRetryable(err) {
255
+ if (err instanceof NonRetryableError) {
256
+ return true;
257
+ }
258
+ if (typeof err === 'object' && err !== null && 'permanent' in err) {
259
+ return Boolean(err.permanent);
260
+ }
261
+ return false;
262
+ }
@@ -0,0 +1,165 @@
1
+ /**
2
+ * Handler contracts: built-in platform handlers, custom handler definitions,
3
+ * and the generic handler map used to type `VeyraClient` and `VeyraWorker`.
4
+ */
5
+ import type { SchemaLike } from './standard-schema.js';
6
+ import type { JsonValue } from './types.js';
7
+ /** Payload accepted by the built-in `http_request` handler. */
8
+ export interface HttpRequestPayload {
9
+ /** Absolute URL to call. Required. */
10
+ url: string;
11
+ /** HTTP method. Defaults to `POST`. */
12
+ method?: string;
13
+ /** Headers applied verbatim to the outbound request. */
14
+ headers?: Record<string, string>;
15
+ /**
16
+ * Request body. Strings are sent as-is; objects, arrays, numbers, and
17
+ * booleans are JSON-encoded by the worker.
18
+ */
19
+ body?: JsonValue;
20
+ /** Per-request timeout in seconds. Defaults to `30`, capped at `300`. */
21
+ timeoutSeconds?: number;
22
+ }
23
+ /** Result recorded for a successful `http_request` job (2xx response). */
24
+ export interface HttpRequestResult {
25
+ /** Upstream HTTP status code. */
26
+ statusCode: number;
27
+ /** Wall-clock request duration in milliseconds. */
28
+ durationMs: number;
29
+ /** Upstream `Content-Type` header, or an empty string. */
30
+ contentType: string;
31
+ /** First 2 KiB of the upstream response body. */
32
+ responseExcerpt: string;
33
+ }
34
+ /** Payload accepted by the built-in `send_email` handler. */
35
+ export interface SendEmailPayload {
36
+ /** One address or a list of addresses. */
37
+ to: string | string[];
38
+ /** Sender address. Falls back to the worker's `VEYRA_SMTP_FROM`. */
39
+ from?: string;
40
+ /** Subject line. Required. */
41
+ subject: string;
42
+ /** Plain-text body. At least one of `text` or `html` is required. */
43
+ text?: string;
44
+ /** HTML body. At least one of `text` or `html` is required. */
45
+ html?: string;
46
+ /** Carbon-copy recipients. */
47
+ cc?: string | string[];
48
+ /** Blind carbon-copy recipients. */
49
+ bcc?: string | string[];
50
+ /** Reply-To address. */
51
+ replyTo?: string;
52
+ /** Extra MIME headers. A caller-supplied `Message-ID` wins. */
53
+ headers?: Record<string, string>;
54
+ }
55
+ /** Result recorded for a successful `send_email` job. */
56
+ export interface SendEmailResult {
57
+ /** Message-ID used for delivery, without angle brackets. */
58
+ messageId: string;
59
+ /** Recipients the message was sent to. */
60
+ to: string[];
61
+ /** SMTP send duration in milliseconds. */
62
+ durationMs: number;
63
+ }
64
+ /** The built-in `noop` handler ignores its payload. */
65
+ export type NoopPayload = unknown;
66
+ /** Result recorded for a successful `noop` job. */
67
+ export interface NoopResult {
68
+ /** Always `true`; marks the result as synthetic. */
69
+ simulated: boolean;
70
+ /** Time spent in the handler, in milliseconds. */
71
+ durationMs: number;
72
+ }
73
+ /**
74
+ * Handlers shipped with the Veyra Go worker. Each entry maps a handler name to
75
+ * its payload and result types.
76
+ */
77
+ export interface BuiltInHandlers {
78
+ http_request: {
79
+ payload: HttpRequestPayload;
80
+ result: HttpRequestResult;
81
+ };
82
+ send_email: {
83
+ payload: SendEmailPayload;
84
+ result: SendEmailResult;
85
+ };
86
+ noop: {
87
+ payload: NoopPayload;
88
+ result: NoopResult;
89
+ };
90
+ }
91
+ /** Shape of one handler entry in a {@link HandlerMap}. */
92
+ export interface HandlerContract<TPayload = unknown, TResult = unknown> {
93
+ payload: TPayload;
94
+ result: TResult;
95
+ }
96
+ /** A map of handler name to payload/result contract. */
97
+ export type HandlerMap = Record<string, HandlerContract<any, any>>;
98
+ /**
99
+ * A reusable handler definition carrying its name, optional default queue,
100
+ * and optional Standard Schemas for payload and result.
101
+ */
102
+ export interface HandlerDefinition<TName extends string = string, TPayload = unknown, TResult = unknown, TQueue extends string | undefined = string | undefined> {
103
+ /** Handler name matched by the Veyra API and worker. */
104
+ readonly name: TName;
105
+ /** Default queue used by `client.enqueue(definition, payload)`. */
106
+ readonly queue?: TQueue;
107
+ /** Optional payload schema: validated on enqueue and before execution. */
108
+ readonly payload?: SchemaLike<TPayload>;
109
+ /** Optional result schema: validated after execution and on retrieval. */
110
+ readonly result?: SchemaLike<TResult>;
111
+ /** @internal Phantom type carrier. Never set at runtime. */
112
+ readonly __types?: {
113
+ readonly payload: TPayload;
114
+ readonly result: TResult;
115
+ };
116
+ }
117
+ /** Configuration accepted by {@link defineHandler}. */
118
+ export interface HandlerConfig<TName extends string, TPayload, TResult, TQueue extends string | undefined> {
119
+ /** Handler name matched by the Veyra API and worker. */
120
+ name: TName;
121
+ /** Default queue used when enqueueing with this definition. */
122
+ queue?: TQueue;
123
+ /** Optional Standard Schema (or {@link staticSchema}) for the payload. */
124
+ payload?: SchemaLike<TPayload>;
125
+ /** Optional Standard Schema (or {@link staticSchema}) for the result. */
126
+ result?: SchemaLike<TResult>;
127
+ }
128
+ /**
129
+ * Defines a typed handler once and reuse it on producers, workers, and
130
+ * webhook consumers.
131
+ *
132
+ * Payload and result types are inferred from the supplied schemas. Use explicit
133
+ * generics when you only need types: `defineHandler<Payload, Result>({ name })`.
134
+ *
135
+ * @example
136
+ * ```ts
137
+ * const sendEmail = defineHandler({
138
+ * name: 'send_email',
139
+ * queue: 'emails',
140
+ * payload: z.object({ to: z.string(), subject: z.string() }),
141
+ * result: z.object({ messageId: z.string() }),
142
+ * });
143
+ * ```
144
+ *
145
+ * @throws {VeyraError} When `name` is empty.
146
+ */
147
+ export declare function defineHandler<TPayload = unknown, TResult = unknown, const TName extends string = string, const TQueue extends string | undefined = undefined>(config: HandlerConfig<TName, TPayload, TResult, TQueue>): HandlerDefinition<TName, TPayload, TResult, TQueue>;
148
+ /** Built-ins plus user handlers, with user definitions winning on collisions. */
149
+ export type ResolvedHandlers<THandlers extends object> = Omit<BuiltInHandlers, keyof THandlers> & THandlers;
150
+ /** String keys of a handler map. */
151
+ export type HandlerName<THandlers extends object> = Extract<keyof THandlers, string>;
152
+ /** Payload type of a named handler. */
153
+ export type HandlerPayload<THandlers extends object, TName extends HandlerName<THandlers>> = THandlers[TName] extends HandlerContract<infer TPayload, any> ? TPayload : unknown;
154
+ /** Result type of a named handler. */
155
+ export type HandlerResult<THandlers extends object, TName extends HandlerName<THandlers>> = THandlers[TName] extends HandlerContract<any, infer TResult> ? TResult : unknown;
156
+ /** Payload type of a known handler, or a fallback for arbitrary names. */
157
+ export type HandlerPayloadFor<THandlers extends object, TName extends string, TFallback = unknown> = TName extends HandlerName<THandlers> ? HandlerPayload<THandlers, TName> : TFallback;
158
+ /** Result type of a known handler, or a fallback for arbitrary names. */
159
+ export type HandlerResultFor<THandlers extends object, TName extends string, TFallback = unknown> = TName extends HandlerName<THandlers> ? HandlerResult<THandlers, TName> : TFallback;
160
+ /** Payload type carried by a {@link HandlerDefinition}. */
161
+ export type DefinitionPayload<TDefinition> = TDefinition extends HandlerDefinition<any, infer TPayload, any, any> ? TPayload : unknown;
162
+ /** Result type carried by a {@link HandlerDefinition}. */
163
+ export type DefinitionResult<TDefinition> = TDefinition extends HandlerDefinition<any, any, infer TResult, any> ? TResult : unknown;
164
+ /** Returns `true` for a {@link HandlerDefinition} (and not an enqueue input). */
165
+ export declare function isHandlerDefinition(value: unknown): value is HandlerDefinition;
@@ -0,0 +1,46 @@
1
+ "use strict";
2
+ /**
3
+ * Handler contracts: built-in platform handlers, custom handler definitions,
4
+ * and the generic handler map used to type `VeyraClient` and `VeyraWorker`.
5
+ */
6
+ Object.defineProperty(exports, "__esModule", { value: true });
7
+ exports.defineHandler = defineHandler;
8
+ exports.isHandlerDefinition = isHandlerDefinition;
9
+ const errors_js_1 = require("./errors.js");
10
+ /**
11
+ * Defines a typed handler once and reuse it on producers, workers, and
12
+ * webhook consumers.
13
+ *
14
+ * Payload and result types are inferred from the supplied schemas. Use explicit
15
+ * generics when you only need types: `defineHandler<Payload, Result>({ name })`.
16
+ *
17
+ * @example
18
+ * ```ts
19
+ * const sendEmail = defineHandler({
20
+ * name: 'send_email',
21
+ * queue: 'emails',
22
+ * payload: z.object({ to: z.string(), subject: z.string() }),
23
+ * result: z.object({ messageId: z.string() }),
24
+ * });
25
+ * ```
26
+ *
27
+ * @throws {VeyraError} When `name` is empty.
28
+ */
29
+ function defineHandler(config) {
30
+ if (typeof config.name !== 'string' || config.name.trim() === '') {
31
+ throw new errors_js_1.VeyraError('defineHandler: name must not be empty');
32
+ }
33
+ return {
34
+ name: config.name.trim(),
35
+ queue: config.queue,
36
+ payload: config.payload,
37
+ result: config.result,
38
+ };
39
+ }
40
+ /** Returns `true` for a {@link HandlerDefinition} (and not an enqueue input). */
41
+ function isHandlerDefinition(value) {
42
+ return (typeof value === 'object' &&
43
+ value !== null &&
44
+ 'name' in value &&
45
+ !('handler' in value));
46
+ }
@@ -0,0 +1,15 @@
1
+ /**
2
+ * @aniket-lodh/veyra-sdk - Lightweight, zero-dependency TypeScript & Node.js SDK
3
+ * for the Veyra Distributed Execution Platform.
4
+ */
5
+ export { VeyraClient } from './client.js';
6
+ export { VeyraWorker } from './worker.js';
7
+ export { defineHandler, isHandlerDefinition } from './handlers.js';
8
+ export { staticSchema } from './standard-schema.js';
9
+ export { parseWebhook, verifyWebhookSignature } from './webhook.js';
10
+ export { VeyraError, VeyraValidationError, VeyraApiError, VeyraAuthError, VeyraNotFoundError, VeyraConflictError, LeaseLostError, VeyraRateLimitError, VeyraTimeoutError, VeyraNetworkError, VeyraWebhookError, NonRetryableError, isNonRetryable, } from './errors.js';
11
+ export type { VeyraClientConfig, VeyraWorkerOptions, VeyraLogger, EnqueueOptions, EnqueueJobInput, DefinitionEnqueueInput, TypedEnqueueInput, TypedEnqueuePayload, TypedEnqueueResult, RequestOptions, Job, JobStatus, StorageJobStatus, JobError, JobAttempt, BackoffStrategy, CallbackStatus, JobClaim, JobContext, HandlerFn, WorkerRecord, WorkerState, WorkerLease, WorkerRegisterParams, ClaimParams, CompleteJobResponse, FailJobParams, FailJobResponse, HeartbeatResponse, RenewLeaseResponse, DeregisterWorkerResponse, JsonValue, } from './types.js';
12
+ export type { BuiltInHandlers, HttpRequestPayload, HttpRequestResult, SendEmailPayload, SendEmailResult, NoopPayload, NoopResult, HandlerDefinition, HandlerConfig, HandlerContract, HandlerMap, DefinitionPayload, DefinitionResult, HandlerName, HandlerPayload, HandlerResult, HandlerPayloadFor, HandlerResultFor, ResolvedHandlers, } from './handlers.js';
13
+ export type { StandardSchemaV1, StaticSchema, SchemaLike, InferSchemaOutput, } from './standard-schema.js';
14
+ export type { WebhookEvent, WebhookJobStatus, WebhookVerificationOptions, } from './webhook.js';
15
+ export type { VeyraApiErrorParams } from './errors.js';
@@ -0,0 +1,37 @@
1
+ "use strict";
2
+ /**
3
+ * @aniket-lodh/veyra-sdk - Lightweight, zero-dependency TypeScript & Node.js SDK
4
+ * for the Veyra Distributed Execution Platform.
5
+ */
6
+ Object.defineProperty(exports, "__esModule", { value: true });
7
+ exports.isNonRetryable = exports.NonRetryableError = exports.VeyraWebhookError = exports.VeyraNetworkError = exports.VeyraTimeoutError = exports.VeyraRateLimitError = exports.LeaseLostError = exports.VeyraConflictError = exports.VeyraNotFoundError = exports.VeyraAuthError = exports.VeyraApiError = exports.VeyraValidationError = exports.VeyraError = exports.verifyWebhookSignature = exports.parseWebhook = exports.staticSchema = exports.isHandlerDefinition = exports.defineHandler = exports.VeyraWorker = exports.VeyraClient = void 0;
8
+ // Public Classes
9
+ var client_js_1 = require("./client.js");
10
+ Object.defineProperty(exports, "VeyraClient", { enumerable: true, get: function () { return client_js_1.VeyraClient; } });
11
+ var worker_js_1 = require("./worker.js");
12
+ Object.defineProperty(exports, "VeyraWorker", { enumerable: true, get: function () { return worker_js_1.VeyraWorker; } });
13
+ // Handler Definitions & Schema Helpers
14
+ var handlers_js_1 = require("./handlers.js");
15
+ Object.defineProperty(exports, "defineHandler", { enumerable: true, get: function () { return handlers_js_1.defineHandler; } });
16
+ Object.defineProperty(exports, "isHandlerDefinition", { enumerable: true, get: function () { return handlers_js_1.isHandlerDefinition; } });
17
+ var standard_schema_js_1 = require("./standard-schema.js");
18
+ Object.defineProperty(exports, "staticSchema", { enumerable: true, get: function () { return standard_schema_js_1.staticSchema; } });
19
+ // Webhook Helpers
20
+ var webhook_js_1 = require("./webhook.js");
21
+ Object.defineProperty(exports, "parseWebhook", { enumerable: true, get: function () { return webhook_js_1.parseWebhook; } });
22
+ Object.defineProperty(exports, "verifyWebhookSignature", { enumerable: true, get: function () { return webhook_js_1.verifyWebhookSignature; } });
23
+ // Error Classes & Helpers
24
+ var errors_js_1 = require("./errors.js");
25
+ Object.defineProperty(exports, "VeyraError", { enumerable: true, get: function () { return errors_js_1.VeyraError; } });
26
+ Object.defineProperty(exports, "VeyraValidationError", { enumerable: true, get: function () { return errors_js_1.VeyraValidationError; } });
27
+ Object.defineProperty(exports, "VeyraApiError", { enumerable: true, get: function () { return errors_js_1.VeyraApiError; } });
28
+ Object.defineProperty(exports, "VeyraAuthError", { enumerable: true, get: function () { return errors_js_1.VeyraAuthError; } });
29
+ Object.defineProperty(exports, "VeyraNotFoundError", { enumerable: true, get: function () { return errors_js_1.VeyraNotFoundError; } });
30
+ Object.defineProperty(exports, "VeyraConflictError", { enumerable: true, get: function () { return errors_js_1.VeyraConflictError; } });
31
+ Object.defineProperty(exports, "LeaseLostError", { enumerable: true, get: function () { return errors_js_1.LeaseLostError; } });
32
+ Object.defineProperty(exports, "VeyraRateLimitError", { enumerable: true, get: function () { return errors_js_1.VeyraRateLimitError; } });
33
+ Object.defineProperty(exports, "VeyraTimeoutError", { enumerable: true, get: function () { return errors_js_1.VeyraTimeoutError; } });
34
+ Object.defineProperty(exports, "VeyraNetworkError", { enumerable: true, get: function () { return errors_js_1.VeyraNetworkError; } });
35
+ Object.defineProperty(exports, "VeyraWebhookError", { enumerable: true, get: function () { return errors_js_1.VeyraWebhookError; } });
36
+ Object.defineProperty(exports, "NonRetryableError", { enumerable: true, get: function () { return errors_js_1.NonRetryableError; } });
37
+ Object.defineProperty(exports, "isNonRetryable", { enumerable: true, get: function () { return errors_js_1.isNonRetryable; } });
@@ -0,0 +1,3 @@
1
+ {
2
+ "type": "commonjs"
3
+ }