pycer-sdk 0.0.0-stage → 1.0.3

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.
@@ -0,0 +1,264 @@
1
+ 'use strict';
2
+
3
+ var crypto = require('crypto');
4
+
5
+ // src/core/errors.ts
6
+ var OwnPayError = class extends Error {
7
+ /** The error type identifier */
8
+ type;
9
+ /** HTTP status code (if applicable) */
10
+ status;
11
+ /** Unique request identifier for debugging */
12
+ requestId;
13
+ /** Raw error response from the API */
14
+ rawResponse;
15
+ constructor(message, type, status, requestId, rawResponse) {
16
+ super(message);
17
+ this.name = "OwnPayError";
18
+ this.type = type;
19
+ this.status = status;
20
+ this.requestId = requestId;
21
+ this.rawResponse = rawResponse;
22
+ Object.setPrototypeOf(this, new.target.prototype);
23
+ }
24
+ /**
25
+ * Returns a JSON representation of the error for logging.
26
+ */
27
+ toJSON() {
28
+ return {
29
+ name: this.name,
30
+ type: this.type,
31
+ message: this.message,
32
+ status: this.status,
33
+ requestId: this.requestId
34
+ };
35
+ }
36
+ };
37
+ var AuthenticationError = class extends OwnPayError {
38
+ constructor(message, requestId, rawResponse) {
39
+ super(message, "AUTHENTICATION_ERROR", 401, requestId, rawResponse);
40
+ this.name = "AuthenticationError";
41
+ }
42
+ };
43
+ var PermissionError = class extends OwnPayError {
44
+ constructor(message, requestId, rawResponse) {
45
+ super(message, "PERMISSION_ERROR", 403, requestId, rawResponse);
46
+ this.name = "PermissionError";
47
+ }
48
+ };
49
+ var NotFoundError = class extends OwnPayError {
50
+ /** The resource type that was not found */
51
+ resource;
52
+ /** The identifier that was searched for */
53
+ resourceId;
54
+ constructor(message, resource, resourceId, requestId, rawResponse) {
55
+ super(message, "NOT_FOUND", 404, requestId, rawResponse);
56
+ this.name = "NotFoundError";
57
+ this.resource = resource;
58
+ this.resourceId = resourceId;
59
+ }
60
+ };
61
+ var ValidationError = class extends OwnPayError {
62
+ /** Array of individual validation errors */
63
+ errors;
64
+ constructor(message, errors, requestId, rawResponse) {
65
+ super(message, "VALIDATION_ERROR", 422, requestId, rawResponse);
66
+ this.name = "ValidationError";
67
+ this.errors = errors;
68
+ }
69
+ /**
70
+ * Returns errors grouped by field name.
71
+ */
72
+ getFieldErrors() {
73
+ const fieldErrors = {};
74
+ for (const error of this.errors) {
75
+ const field = error.field ?? "_general";
76
+ if (!fieldErrors[field]) {
77
+ fieldErrors[field] = [];
78
+ }
79
+ fieldErrors[field].push(error.message);
80
+ }
81
+ return fieldErrors;
82
+ }
83
+ /**
84
+ * Returns the first error message for a specific field.
85
+ */
86
+ getFirstFieldError(field) {
87
+ const error = this.errors.find((e) => e.field === field);
88
+ return error?.message;
89
+ }
90
+ };
91
+ var RateLimitError = class extends OwnPayError {
92
+ /** Seconds to wait before retrying */
93
+ retryAfter;
94
+ constructor(message, retryAfter, requestId, rawResponse) {
95
+ super(message, "RATE_LIMIT_ERROR", 429, requestId, rawResponse);
96
+ this.name = "RateLimitError";
97
+ this.retryAfter = retryAfter;
98
+ }
99
+ };
100
+ var IdempotencyError = class extends OwnPayError {
101
+ constructor(message, requestId, rawResponse) {
102
+ super(message, "IDEMPOTENCY_ERROR", 409, requestId, rawResponse);
103
+ this.name = "IdempotencyError";
104
+ }
105
+ };
106
+ var ApiError = class extends OwnPayError {
107
+ /** The error code from the API */
108
+ errorCode;
109
+ constructor(message, errorCode, status = 500, requestId, rawResponse) {
110
+ super(message, "API_ERROR", status, requestId, rawResponse);
111
+ this.name = "ApiError";
112
+ this.errorCode = errorCode;
113
+ }
114
+ };
115
+ var NetworkError = class extends OwnPayError {
116
+ /** The underlying cause */
117
+ cause;
118
+ constructor(message, cause) {
119
+ super(message, "NETWORK_ERROR");
120
+ this.name = "NetworkError";
121
+ this.cause = cause;
122
+ }
123
+ };
124
+ var AbortError = class extends OwnPayError {
125
+ constructor(message = "Request was aborted") {
126
+ super(message, "ABORT_ERROR");
127
+ this.name = "AbortError";
128
+ }
129
+ };
130
+ var WebhookVerificationError = class extends OwnPayError {
131
+ constructor(message) {
132
+ super(message, "WEBHOOK_VERIFICATION_ERROR");
133
+ this.name = "WebhookVerificationError";
134
+ }
135
+ };
136
+ function createErrorFromResponse(status, body) {
137
+ const message = body.error ?? "An unexpected error occurred";
138
+ const requestId = body.request_id;
139
+ const errors = body.errors ?? [];
140
+ const rawResponse = body;
141
+ switch (status) {
142
+ case 401:
143
+ return new AuthenticationError(message, requestId, rawResponse);
144
+ case 403:
145
+ return new PermissionError(message, requestId, rawResponse);
146
+ case 404:
147
+ return new NotFoundError(message, void 0, void 0, requestId, rawResponse);
148
+ case 409:
149
+ return new IdempotencyError(message, requestId, rawResponse);
150
+ case 422:
151
+ return new ValidationError(message, errors, requestId, rawResponse);
152
+ case 429: {
153
+ const retryAfter = body.retry_after;
154
+ return new RateLimitError(
155
+ message,
156
+ typeof retryAfter === "number" && Number.isFinite(retryAfter) && retryAfter >= 0 ? retryAfter : void 0,
157
+ requestId,
158
+ rawResponse
159
+ );
160
+ }
161
+ default:
162
+ if (status >= 500) {
163
+ const errorCode = errors[0]?.code;
164
+ return new ApiError(message, errorCode, status, requestId, rawResponse);
165
+ }
166
+ return new OwnPayError(message, "UNKNOWN_ERROR", status, requestId, rawResponse);
167
+ }
168
+ }
169
+ var DEFAULT_TOLERANCE_SECONDS = 300;
170
+ var MILLISECOND_THRESHOLD = 1e12;
171
+ function verifyWebhookSignature(params) {
172
+ const { payload, signature, secret, timestamp, tolerance = DEFAULT_TOLERANCE_SECONDS } = params;
173
+ if (!payload) {
174
+ throw new WebhookVerificationError("Webhook payload is required");
175
+ }
176
+ if (!signature) {
177
+ throw new WebhookVerificationError("Webhook signature is required");
178
+ }
179
+ if (!secret) {
180
+ throw new WebhookVerificationError("Webhook secret is required");
181
+ }
182
+ const expectedSignature = crypto.createHmac("sha256", secret).update(payload).digest("hex");
183
+ if (!timingSafeCompare(signature.replace(/^sha256=/, ""), expectedSignature)) {
184
+ throw new WebhookVerificationError(
185
+ "Invalid webhook signature. The payload may have been tampered with."
186
+ );
187
+ }
188
+ if (timestamp !== void 0 && timestamp !== null) {
189
+ verifyTimestamp(timestamp, tolerance);
190
+ }
191
+ return true;
192
+ }
193
+ function generateSignature(payload, secret) {
194
+ if (!payload || !secret) {
195
+ throw new WebhookVerificationError("Payload and secret are required for signature generation");
196
+ }
197
+ return crypto.createHmac("sha256", secret).update(payload).digest("hex");
198
+ }
199
+ function verifyTimestamp(timestamp, tolerance) {
200
+ if (!Number.isFinite(tolerance) || tolerance <= 0) {
201
+ throw new WebhookVerificationError(
202
+ `Invalid tolerance value: ${tolerance}. Must be a positive number.`
203
+ );
204
+ }
205
+ let timestampSeconds;
206
+ if (typeof timestamp === "string") {
207
+ if (timestamp.trim() === "") {
208
+ throw new WebhookVerificationError("Invalid webhook timestamp format");
209
+ }
210
+ timestampSeconds = Number(timestamp);
211
+ } else {
212
+ timestampSeconds = timestamp;
213
+ }
214
+ if (!Number.isFinite(timestampSeconds) || timestampSeconds <= 0) {
215
+ throw new WebhookVerificationError("Webhook timestamp must be a positive number");
216
+ }
217
+ if (timestampSeconds > MILLISECOND_THRESHOLD) {
218
+ timestampSeconds = Math.floor(timestampSeconds / 1e3);
219
+ }
220
+ const currentTime = Math.floor(Date.now() / 1e3);
221
+ const age = Math.abs(currentTime - timestampSeconds);
222
+ if (age > tolerance) {
223
+ throw new WebhookVerificationError(
224
+ `Webhook timestamp is too old. Age: ${age}s, Tolerance: ${tolerance}s. This may indicate a replay attack.`
225
+ );
226
+ }
227
+ }
228
+ function timingSafeCompare(a, b) {
229
+ const bufA = Buffer.from(a, "utf8");
230
+ const bufB = Buffer.from(b, "utf8");
231
+ const maxLen = Math.max(bufA.length, bufB.length);
232
+ const paddedA = Buffer.alloc(maxLen);
233
+ const paddedB = Buffer.alloc(maxLen);
234
+ bufA.copy(paddedA);
235
+ bufB.copy(paddedB);
236
+ const sameLength = bufA.length === bufB.length;
237
+ return crypto.timingSafeEqual(paddedA, paddedB) && sameLength;
238
+ }
239
+ function parseWebhookPayload(body) {
240
+ const bodyStr = typeof body === "string" ? body : body.toString("utf-8");
241
+ try {
242
+ return JSON.parse(bodyStr);
243
+ } catch {
244
+ throw new WebhookVerificationError("Invalid webhook payload: not valid JSON");
245
+ }
246
+ }
247
+
248
+ exports.AbortError = AbortError;
249
+ exports.ApiError = ApiError;
250
+ exports.AuthenticationError = AuthenticationError;
251
+ exports.IdempotencyError = IdempotencyError;
252
+ exports.NetworkError = NetworkError;
253
+ exports.NotFoundError = NotFoundError;
254
+ exports.OwnPayError = OwnPayError;
255
+ exports.PermissionError = PermissionError;
256
+ exports.RateLimitError = RateLimitError;
257
+ exports.ValidationError = ValidationError;
258
+ exports.WebhookVerificationError = WebhookVerificationError;
259
+ exports.createErrorFromResponse = createErrorFromResponse;
260
+ exports.generateSignature = generateSignature;
261
+ exports.parseWebhookPayload = parseWebhookPayload;
262
+ exports.verifyWebhookSignature = verifyWebhookSignature;
263
+ //# sourceMappingURL=chunk-ANI325UM.cjs.map
264
+ //# sourceMappingURL=chunk-ANI325UM.cjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/core/errors.ts","../src/webhooks/verify.ts"],"names":["createHmac","cryptoTimingSafeEqual"],"mappings":";;;;;AAaO,IAAM,WAAA,GAAN,cAA0B,KAAA,CAAM;AAAA;AAAA,EAE5B,IAAA;AAAA;AAAA,EAEA,MAAA;AAAA;AAAA,EAEA,SAAA;AAAA;AAAA,EAEA,WAAA;AAAA,EAET,WAAA,CACE,OAAA,EACA,IAAA,EACA,MAAA,EACA,WACA,WAAA,EACA;AACA,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,aAAA;AACZ,IAAA,IAAA,CAAK,IAAA,GAAO,IAAA;AACZ,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AACd,IAAA,IAAA,CAAK,SAAA,GAAY,SAAA;AACjB,IAAA,IAAA,CAAK,WAAA,GAAc,WAAA;AAGnB,IAAA,MAAA,CAAO,cAAA,CAAe,IAAA,EAAM,GAAA,CAAA,MAAA,CAAW,SAAS,CAAA;AAAA,EAClD;AAAA;AAAA;AAAA;AAAA,EAKA,MAAA,GAAkC;AAChC,IAAA,OAAO;AAAA,MACL,MAAM,IAAA,CAAK,IAAA;AAAA,MACX,MAAM,IAAA,CAAK,IAAA;AAAA,MACX,SAAS,IAAA,CAAK,OAAA;AAAA,MACd,QAAQ,IAAA,CAAK,MAAA;AAAA,MACb,WAAW,IAAA,CAAK;AAAA,KAClB;AAAA,EACF;AACF;AAMO,IAAM,mBAAA,GAAN,cAAkC,WAAA,CAAY;AAAA,EACnD,WAAA,CAAY,OAAA,EAAiB,SAAA,EAAoB,WAAA,EAAuB;AACtE,IAAA,KAAA,CAAM,OAAA,EAAS,sBAAA,EAAwB,GAAA,EAAK,SAAA,EAAW,WAAW,CAAA;AAClE,IAAA,IAAA,CAAK,IAAA,GAAO,qBAAA;AAAA,EACd;AACF;AAMO,IAAM,eAAA,GAAN,cAA8B,WAAA,CAAY;AAAA,EAC/C,WAAA,CAAY,OAAA,EAAiB,SAAA,EAAoB,WAAA,EAAuB;AACtE,IAAA,KAAA,CAAM,OAAA,EAAS,kBAAA,EAAoB,GAAA,EAAK,SAAA,EAAW,WAAW,CAAA;AAC9D,IAAA,IAAA,CAAK,IAAA,GAAO,iBAAA;AAAA,EACd;AACF;AAKO,IAAM,aAAA,GAAN,cAA4B,WAAA,CAAY;AAAA;AAAA,EAEpC,QAAA;AAAA;AAAA,EAEA,UAAA;AAAA,EAET,WAAA,CACE,OAAA,EACA,QAAA,EACA,UAAA,EACA,WACA,WAAA,EACA;AACA,IAAA,KAAA,CAAM,OAAA,EAAS,WAAA,EAAa,GAAA,EAAK,SAAA,EAAW,WAAW,CAAA;AACvD,IAAA,IAAA,CAAK,IAAA,GAAO,eAAA;AACZ,IAAA,IAAA,CAAK,QAAA,GAAW,QAAA;AAChB,IAAA,IAAA,CAAK,UAAA,GAAa,UAAA;AAAA,EACpB;AACF;AAMO,IAAM,eAAA,GAAN,cAA8B,WAAA,CAAY;AAAA;AAAA,EAEtC,MAAA;AAAA,EAET,WAAA,CACE,OAAA,EACA,MAAA,EACA,SAAA,EACA,WAAA,EACA;AACA,IAAA,KAAA,CAAM,OAAA,EAAS,kBAAA,EAAoB,GAAA,EAAK,SAAA,EAAW,WAAW,CAAA;AAC9D,IAAA,IAAA,CAAK,IAAA,GAAO,iBAAA;AACZ,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA,EAKA,cAAA,GAA2C;AACzC,IAAA,MAAM,cAAwC,EAAC;AAC/C,IAAA,KAAA,MAAW,KAAA,IAAS,KAAK,MAAA,EAAQ;AAC/B,MAAA,MAAM,KAAA,GAAQ,MAAM,KAAA,IAAS,UAAA;AAC7B,MAAA,IAAI,CAAC,WAAA,CAAY,KAAK,CAAA,EAAG;AACvB,QAAA,WAAA,CAAY,KAAK,IAAI,EAAC;AAAA,MACxB;AACA,MAAA,WAAA,CAAY,KAAK,CAAA,CAAE,IAAA,CAAK,KAAA,CAAM,OAAO,CAAA;AAAA,IACvC;AACA,IAAA,OAAO,WAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA,EAKA,mBAAmB,KAAA,EAAmC;AACpD,IAAA,MAAM,KAAA,GAAQ,KAAK,MAAA,CAAO,IAAA,CAAK,CAAC,CAAA,KAAM,CAAA,CAAE,UAAU,KAAK,CAAA;AACvD,IAAA,OAAO,KAAA,EAAO,OAAA;AAAA,EAChB;AACF;AAMO,IAAM,cAAA,GAAN,cAA6B,WAAA,CAAY;AAAA;AAAA,EAErC,UAAA;AAAA,EAET,WAAA,CACE,OAAA,EACA,UAAA,EACA,SAAA,EACA,WAAA,EACA;AACA,IAAA,KAAA,CAAM,OAAA,EAAS,kBAAA,EAAoB,GAAA,EAAK,SAAA,EAAW,WAAW,CAAA;AAC9D,IAAA,IAAA,CAAK,IAAA,GAAO,gBAAA;AACZ,IAAA,IAAA,CAAK,UAAA,GAAa,UAAA;AAAA,EACpB;AACF;AAMO,IAAM,gBAAA,GAAN,cAA+B,WAAA,CAAY;AAAA,EAChD,WAAA,CAAY,OAAA,EAAiB,SAAA,EAAoB,WAAA,EAAuB;AACtE,IAAA,KAAA,CAAM,OAAA,EAAS,mBAAA,EAAqB,GAAA,EAAK,SAAA,EAAW,WAAW,CAAA;AAC/D,IAAA,IAAA,CAAK,IAAA,GAAO,kBAAA;AAAA,EACd;AACF;AAKO,IAAM,QAAA,GAAN,cAAuB,WAAA,CAAY;AAAA;AAAA,EAE/B,SAAA;AAAA,EAET,YACE,OAAA,EACA,SAAA,EACA,MAAA,GAAiB,GAAA,EACjB,WACA,WAAA,EACA;AACA,IAAA,KAAA,CAAM,OAAA,EAAS,WAAA,EAAa,MAAA,EAAQ,SAAA,EAAW,WAAW,CAAA;AAC1D,IAAA,IAAA,CAAK,IAAA,GAAO,UAAA;AACZ,IAAA,IAAA,CAAK,SAAA,GAAY,SAAA;AAAA,EACnB;AACF;AAKO,IAAM,YAAA,GAAN,cAA2B,WAAA,CAAY;AAAA;AAAA,EAE1B,KAAA;AAAA,EAElB,WAAA,CAAY,SAAiB,KAAA,EAAe;AAC1C,IAAA,KAAA,CAAM,SAAS,eAAe,CAAA;AAC9B,IAAA,IAAA,CAAK,IAAA,GAAO,cAAA;AACZ,IAAA,IAAA,CAAK,KAAA,GAAQ,KAAA;AAAA,EACf;AACF;AAKO,IAAM,UAAA,GAAN,cAAyB,WAAA,CAAY;AAAA,EAC1C,WAAA,CAAY,UAAkB,qBAAA,EAAuB;AACnD,IAAA,KAAA,CAAM,SAAS,aAAa,CAAA;AAC5B,IAAA,IAAA,CAAK,IAAA,GAAO,YAAA;AAAA,EACd;AACF;AAKO,IAAM,wBAAA,GAAN,cAAuC,WAAA,CAAY;AAAA,EACxD,YAAY,OAAA,EAAiB;AAC3B,IAAA,KAAA,CAAM,SAAS,4BAA4B,CAAA;AAC3C,IAAA,IAAA,CAAK,IAAA,GAAO,0BAAA;AAAA,EACd;AACF;AAOO,SAAS,uBAAA,CACd,QACA,IAAA,EAMa;AACb,EAAA,MAAM,OAAA,GAAU,KAAK,KAAA,IAAS,8BAAA;AAC9B,EAAA,MAAM,YAAY,IAAA,CAAK,UAAA;AACvB,EAAA,MAAM,MAAA,GAAS,IAAA,CAAK,MAAA,IAAU,EAAC;AAC/B,EAAA,MAAM,WAAA,GAAc,IAAA;AAEpB,EAAA,QAAQ,MAAA;AAAQ,IACd,KAAK,GAAA;AACH,MAAA,OAAO,IAAI,mBAAA,CAAoB,OAAA,EAAS,SAAA,EAAW,WAAW,CAAA;AAAA,IAEhE,KAAK,GAAA;AACH,MAAA,OAAO,IAAI,eAAA,CAAgB,OAAA,EAAS,SAAA,EAAW,WAAW,CAAA;AAAA,IAE5D,KAAK,GAAA;AACH,MAAA,OAAO,IAAI,aAAA,CAAc,OAAA,EAAS,MAAA,EAAW,MAAA,EAAW,WAAW,WAAW,CAAA;AAAA,IAEhF,KAAK,GAAA;AACH,MAAA,OAAO,IAAI,gBAAA,CAAiB,OAAA,EAAS,SAAA,EAAW,WAAW,CAAA;AAAA,IAE7D,KAAK,GAAA;AACH,MAAA,OAAO,IAAI,eAAA,CAAgB,OAAA,EAAS,MAAA,EAAQ,WAAW,WAAW,CAAA;AAAA,IAEpE,KAAK,GAAA,EAAK;AAER,MAAA,MAAM,aAAa,IAAA,CAAK,WAAA;AACxB,MAAA,OAAO,IAAI,cAAA;AAAA,QACT,OAAA;AAAA,QACA,OAAO,eAAe,QAAA,IAAY,MAAA,CAAO,SAAS,UAAU,CAAA,IAAK,UAAA,IAAc,CAAA,GAC3E,UAAA,GACA,MAAA;AAAA,QACJ,SAAA;AAAA,QACA;AAAA,OACF;AAAA,IACF;AAAA,IAEA;AACE,MAAA,IAAI,UAAU,GAAA,EAAK;AACjB,QAAA,MAAM,SAAA,GAAY,MAAA,CAAO,CAAC,CAAA,EAAG,IAAA;AAC7B,QAAA,OAAO,IAAI,QAAA,CAAS,OAAA,EAAS,SAAA,EAAW,MAAA,EAAQ,WAAW,WAAW,CAAA;AAAA,MACxE;AAEA,MAAA,OAAO,IAAI,WAAA,CAAY,OAAA,EAAS,eAAA,EAAiB,MAAA,EAAQ,WAAW,WAAW,CAAA;AAAA;AAErF;AC5QA,IAAM,yBAAA,GAA4B,GAAA;AAMlC,IAAM,qBAAA,GAAwB,IAAA;AAsCvB,SAAS,uBAAuB,MAAA,EAA4C;AACjF,EAAA,MAAM,EAAE,OAAA,EAAS,SAAA,EAAW,QAAQ,SAAA,EAAW,SAAA,GAAY,2BAA0B,GAAI,MAAA;AAGzF,EAAA,IAAI,CAAC,OAAA,EAAS;AACZ,IAAA,MAAM,IAAI,yBAAyB,6BAA6B,CAAA;AAAA,EAClE;AAEA,EAAA,IAAI,CAAC,SAAA,EAAW;AACd,IAAA,MAAM,IAAI,yBAAyB,+BAA+B,CAAA;AAAA,EACpE;AAEA,EAAA,IAAI,CAAC,MAAA,EAAQ;AACX,IAAA,MAAM,IAAI,yBAAyB,4BAA4B,CAAA;AAAA,EACjE;AAGA,EAAA,MAAM,iBAAA,GAAoBA,kBAAW,QAAA,EAAU,MAAM,EAAE,MAAA,CAAO,OAAO,CAAA,CAAE,MAAA,CAAO,KAAK,CAAA;AAGnF,EAAA,IAAI,CAAC,kBAAkB,SAAA,CAAU,OAAA,CAAQ,YAAY,EAAE,CAAA,EAAG,iBAAiB,CAAA,EAAG;AAC5E,IAAA,MAAM,IAAI,wBAAA;AAAA,MACR;AAAA,KACF;AAAA,EACF;AAGA,EAAA,IAAI,SAAA,KAAc,MAAA,IAAa,SAAA,KAAc,IAAA,EAAM;AACjD,IAAA,eAAA,CAAgB,WAAW,SAAS,CAAA;AAAA,EACtC;AAEA,EAAA,OAAO,IAAA;AACT;AAgBO,SAAS,iBAAA,CAAkB,SAAiB,MAAA,EAAwB;AACzE,EAAA,IAAI,CAAC,OAAA,IAAW,CAAC,MAAA,EAAQ;AACvB,IAAA,MAAM,IAAI,yBAAyB,0DAA0D,CAAA;AAAA,EAC/F;AAEA,EAAA,OAAOA,iBAAA,CAAW,UAAU,MAAM,CAAA,CAAE,OAAO,OAAO,CAAA,CAAE,OAAO,KAAK,CAAA;AAClE;AASA,SAAS,eAAA,CAAgB,WAA4B,SAAA,EAAyB;AAE5E,EAAA,IAAI,CAAC,MAAA,CAAO,QAAA,CAAS,SAAS,CAAA,IAAK,aAAa,CAAA,EAAG;AACjD,IAAA,MAAM,IAAI,wBAAA;AAAA,MACR,4BAA4B,SAAS,CAAA,4BAAA;AAAA,KACvC;AAAA,EACF;AAEA,EAAA,IAAI,gBAAA;AAEJ,EAAA,IAAI,OAAO,cAAc,QAAA,EAAU;AACjC,IAAA,IAAI,SAAA,CAAU,IAAA,EAAK,KAAM,EAAA,EAAI;AAC3B,MAAA,MAAM,IAAI,yBAAyB,kCAAkC,CAAA;AAAA,IACvE;AACA,IAAA,gBAAA,GAAmB,OAAO,SAAS,CAAA;AAAA,EACrC,CAAA,MAAO;AACL,IAAA,gBAAA,GAAmB,SAAA;AAAA,EACrB;AAGA,EAAA,IAAI,CAAC,MAAA,CAAO,QAAA,CAAS,gBAAgB,CAAA,IAAK,oBAAoB,CAAA,EAAG;AAC/D,IAAA,MAAM,IAAI,yBAAyB,6CAA6C,CAAA;AAAA,EAClF;AAIA,EAAA,IAAI,mBAAmB,qBAAA,EAAuB;AAC5C,IAAA,gBAAA,GAAmB,IAAA,CAAK,KAAA,CAAM,gBAAA,GAAmB,GAAI,CAAA;AAAA,EACvD;AAEA,EAAA,MAAM,cAAc,IAAA,CAAK,KAAA,CAAM,IAAA,CAAK,GAAA,KAAQ,GAAI,CAAA;AAChD,EAAA,MAAM,GAAA,GAAM,IAAA,CAAK,GAAA,CAAI,WAAA,GAAc,gBAAgB,CAAA;AAEnD,EAAA,IAAI,MAAM,SAAA,EAAW;AACnB,IAAA,MAAM,IAAI,wBAAA;AAAA,MACR,CAAA,mCAAA,EAAsC,GAAG,CAAA,cAAA,EAAiB,SAAS,CAAA,qCAAA;AAAA,KAErE;AAAA,EACF;AACF;AAUA,SAAS,iBAAA,CAAkB,GAAW,CAAA,EAAoB;AACxD,EAAA,MAAM,IAAA,GAAO,MAAA,CAAO,IAAA,CAAK,CAAA,EAAG,MAAM,CAAA;AAClC,EAAA,MAAM,IAAA,GAAO,MAAA,CAAO,IAAA,CAAK,CAAA,EAAG,MAAM,CAAA;AAGlC,EAAA,MAAM,SAAS,IAAA,CAAK,GAAA,CAAI,IAAA,CAAK,MAAA,EAAQ,KAAK,MAAM,CAAA;AAChD,EAAA,MAAM,OAAA,GAAU,MAAA,CAAO,KAAA,CAAM,MAAM,CAAA;AACnC,EAAA,MAAM,OAAA,GAAU,MAAA,CAAO,KAAA,CAAM,MAAM,CAAA;AACnC,EAAA,IAAA,CAAK,KAAK,OAAO,CAAA;AACjB,EAAA,IAAA,CAAK,KAAK,OAAO,CAAA;AAEjB,EAAA,MAAM,UAAA,GAAa,IAAA,CAAK,MAAA,KAAW,IAAA,CAAK,MAAA;AACxC,EAAA,OAAOC,sBAAA,CAAsB,OAAA,EAAS,OAAO,CAAA,IAAK,UAAA;AACpD;AAiBO,SAAS,oBACd,IAAA,EACG;AACH,EAAA,MAAM,UAAU,OAAO,IAAA,KAAS,WAAW,IAAA,GAAO,IAAA,CAAK,SAAS,OAAO,CAAA;AAEvE,EAAA,IAAI;AACF,IAAA,OAAO,IAAA,CAAK,MAAM,OAAO,CAAA;AAAA,EAC3B,CAAA,CAAA,MAAQ;AACN,IAAA,MAAM,IAAI,yBAAyB,yCAAyC,CAAA;AAAA,EAC9E;AACF","file":"chunk-ANI325UM.cjs","sourcesContent":["/**\n * OwnPay Node.js SDK - Error Classes\n *\n * Comprehensive error hierarchy for the OwnPay API.\n * Each error class provides specific context for different failure scenarios.\n */\n\nimport type { ApiErrorDetail } from './types.js';\n\n/**\n * Base error class for all OwnPay SDK errors.\n * Provides common properties and methods for error handling.\n */\nexport class OwnPayError extends Error {\n /** The error type identifier */\n readonly type: string;\n /** HTTP status code (if applicable) */\n readonly status: number | undefined;\n /** Unique request identifier for debugging */\n readonly requestId: string | undefined;\n /** Raw error response from the API */\n readonly rawResponse: unknown;\n\n constructor(\n message: string,\n type: string,\n status?: number,\n requestId?: string,\n rawResponse?: unknown\n ) {\n super(message);\n this.name = 'OwnPayError';\n this.type = type;\n this.status = status;\n this.requestId = requestId;\n this.rawResponse = rawResponse;\n\n // Maintains proper prototype chain for instanceof checks\n Object.setPrototypeOf(this, new.target.prototype);\n }\n\n /**\n * Returns a JSON representation of the error for logging.\n */\n toJSON(): Record<string, unknown> {\n return {\n name: this.name,\n type: this.type,\n message: this.message,\n status: this.status,\n requestId: this.requestId,\n };\n }\n}\n\n/**\n * Thrown when API authentication fails (401).\n * Indicates an invalid, missing, or revoked API key.\n */\nexport class AuthenticationError extends OwnPayError {\n constructor(message: string, requestId?: string, rawResponse?: unknown) {\n super(message, 'AUTHENTICATION_ERROR', 401, requestId, rawResponse);\n this.name = 'AuthenticationError';\n }\n}\n\n/**\n * Thrown when the API key lacks required permissions (403).\n * Indicates insufficient scope (e.g., read-only key attempting a write operation).\n */\nexport class PermissionError extends OwnPayError {\n constructor(message: string, requestId?: string, rawResponse?: unknown) {\n super(message, 'PERMISSION_ERROR', 403, requestId, rawResponse);\n this.name = 'PermissionError';\n }\n}\n\n/**\n * Thrown when a requested resource is not found (404).\n */\nexport class NotFoundError extends OwnPayError {\n /** The resource type that was not found */\n readonly resource: string | undefined;\n /** The identifier that was searched for */\n readonly resourceId: string | undefined;\n\n constructor(\n message: string,\n resource?: string,\n resourceId?: string,\n requestId?: string,\n rawResponse?: unknown\n ) {\n super(message, 'NOT_FOUND', 404, requestId, rawResponse);\n this.name = 'NotFoundError';\n this.resource = resource;\n this.resourceId = resourceId;\n }\n}\n\n/**\n * Thrown when request validation fails (422).\n * Contains structured error details for each invalid field.\n */\nexport class ValidationError extends OwnPayError {\n /** Array of individual validation errors */\n readonly errors: ApiErrorDetail[];\n\n constructor(\n message: string,\n errors: ApiErrorDetail[],\n requestId?: string,\n rawResponse?: unknown\n ) {\n super(message, 'VALIDATION_ERROR', 422, requestId, rawResponse);\n this.name = 'ValidationError';\n this.errors = errors;\n }\n\n /**\n * Returns errors grouped by field name.\n */\n getFieldErrors(): Record<string, string[]> {\n const fieldErrors: Record<string, string[]> = {};\n for (const error of this.errors) {\n const field = error.field ?? '_general';\n if (!fieldErrors[field]) {\n fieldErrors[field] = [];\n }\n fieldErrors[field].push(error.message);\n }\n return fieldErrors;\n }\n\n /**\n * Returns the first error message for a specific field.\n */\n getFirstFieldError(field: string): string | undefined {\n const error = this.errors.find((e) => e.field === field);\n return error?.message;\n }\n}\n\n/**\n * Thrown when the API rate limit is exceeded (429).\n * Includes retry-after information when available.\n */\nexport class RateLimitError extends OwnPayError {\n /** Seconds to wait before retrying */\n readonly retryAfter: number | undefined;\n\n constructor(\n message: string,\n retryAfter?: number,\n requestId?: string,\n rawResponse?: unknown\n ) {\n super(message, 'RATE_LIMIT_ERROR', 429, requestId, rawResponse);\n this.name = 'RateLimitError';\n this.retryAfter = retryAfter;\n }\n}\n\n/**\n * Thrown when an idempotency key conflict occurs (409).\n * Indicates a request with the same key is still processing.\n */\nexport class IdempotencyError extends OwnPayError {\n constructor(message: string, requestId?: string, rawResponse?: unknown) {\n super(message, 'IDEMPOTENCY_ERROR', 409, requestId, rawResponse);\n this.name = 'IdempotencyError';\n }\n}\n\n/**\n * Thrown when the API returns a server error (500, 502, 503, 504).\n */\nexport class ApiError extends OwnPayError {\n /** The error code from the API */\n readonly errorCode: string | undefined;\n\n constructor(\n message: string,\n errorCode?: string,\n status: number = 500,\n requestId?: string,\n rawResponse?: unknown\n ) {\n super(message, 'API_ERROR', status, requestId, rawResponse);\n this.name = 'ApiError';\n this.errorCode = errorCode;\n }\n}\n\n/**\n * Thrown when a network error occurs (connection failure, timeout, etc.).\n */\nexport class NetworkError extends OwnPayError {\n /** The underlying cause */\n override readonly cause: Error | undefined;\n\n constructor(message: string, cause?: Error) {\n super(message, 'NETWORK_ERROR');\n this.name = 'NetworkError';\n this.cause = cause;\n }\n}\n\n/**\n * Thrown when a request is aborted (via AbortSignal or timeout).\n */\nexport class AbortError extends OwnPayError {\n constructor(message: string = 'Request was aborted') {\n super(message, 'ABORT_ERROR');\n this.name = 'AbortError';\n }\n}\n\n/**\n * Thrown when webhook signature verification fails.\n */\nexport class WebhookVerificationError extends OwnPayError {\n constructor(message: string) {\n super(message, 'WEBHOOK_VERIFICATION_ERROR');\n this.name = 'WebhookVerificationError';\n }\n}\n\n/**\n * Creates the appropriate error class from an API error response.\n *\n * @internal\n */\nexport function createErrorFromResponse(\n status: number,\n body: {\n error?: string;\n errors?: ApiErrorDetail[];\n request_id?: string;\n [key: string]: unknown;\n }\n): OwnPayError {\n const message = body.error ?? 'An unexpected error occurred';\n const requestId = body.request_id;\n const errors = body.errors ?? [];\n const rawResponse = body;\n\n switch (status) {\n case 401:\n return new AuthenticationError(message, requestId, rawResponse);\n\n case 403:\n return new PermissionError(message, requestId, rawResponse);\n\n case 404:\n return new NotFoundError(message, undefined, undefined, requestId, rawResponse);\n\n case 409:\n return new IdempotencyError(message, requestId, rawResponse);\n\n case 422:\n return new ValidationError(message, errors, requestId, rawResponse);\n\n case 429: {\n // Extract retry-after from response if available\n const retryAfter = body.retry_after;\n return new RateLimitError(\n message,\n typeof retryAfter === 'number' && Number.isFinite(retryAfter) && retryAfter >= 0\n ? retryAfter\n : undefined,\n requestId,\n rawResponse\n );\n }\n\n default:\n if (status >= 500) {\n const errorCode = errors[0]?.code;\n return new ApiError(message, errorCode, status, requestId, rawResponse);\n }\n\n return new OwnPayError(message, 'UNKNOWN_ERROR', status, requestId, rawResponse);\n }\n}\n","/**\n * OwnPay Node.js SDK - Webhook Signature Verification\n *\n * Standalone utility for verifying OwnPay webhook signatures.\n * Uses HMAC-SHA256 for cryptographic verification.\n *\n * @module ownpay/webhooks\n */\n\nimport { createHmac, timingSafeEqual as cryptoTimingSafeEqual } from 'node:crypto';\nimport { WebhookVerificationError } from '../core/errors.js';\nimport type { WebhookVerificationParams } from '../core/types.js';\n\n/**\n * Default tolerance for timestamp validation (5 minutes).\n */\nconst DEFAULT_TOLERANCE_SECONDS = 300;\n\n/**\n * Unix timestamps in seconds will be between ~0 and ~1e11 (year ~5138).\n * Timestamps above this threshold are assumed to be in milliseconds.\n */\nconst MILLISECOND_THRESHOLD = 1e12;\n\n/**\n * Verifies an OwnPay webhook signature.\n *\n * This function verifies that the webhook payload was sent by OwnPay\n * and has not been tampered with. It supports optional timestamp\n * validation for legacy delivery diagnostics. The timestamp is outside the signature.\n *\n * @param params - Verification parameters\n * @returns true if the signature is valid\n * @throws {WebhookVerificationError} If the signature is invalid\n *\n * @example\n * ```typescript\n * import { verifyWebhookSignature } from 'pycer-sdk/webhooks';\n *\n * // In your webhook handler\n * app.post('/webhook', (req, res) => {\n * try {\n * verifyWebhookSignature({\n * payload: req.body,\n * signature: req.headers['x-signature'],\n * secret: process.env.OWNPAY_WEBHOOK_SECRET,\n * timestamp: req.headers['x-timestamp'],\n * });\n *\n * // Signature is valid, process the webhook\n * const event = JSON.parse(req.body);\n * handleWebhookEvent(event);\n *\n * res.status(200).json({ received: true });\n * } catch (error) {\n * res.status(400).json({ error: 'Invalid signature' });\n * }\n * });\n * ```\n */\nexport function verifyWebhookSignature(params: WebhookVerificationParams): boolean {\n const { payload, signature, secret, timestamp, tolerance = DEFAULT_TOLERANCE_SECONDS } = params;\n\n // Validate required parameters\n if (!payload) {\n throw new WebhookVerificationError('Webhook payload is required');\n }\n\n if (!signature) {\n throw new WebhookVerificationError('Webhook signature is required');\n }\n\n if (!secret) {\n throw new WebhookVerificationError('Webhook secret is required');\n }\n\n // Generate expected signature\n const expectedSignature = createHmac('sha256', secret).update(payload).digest('hex');\n\n // Verify signature using constant-time comparison\n if (!timingSafeCompare(signature.replace(/^sha256=/, ''), expectedSignature)) {\n throw new WebhookVerificationError(\n 'Invalid webhook signature. The payload may have been tampered with.'\n );\n }\n\n // Check the unsigned timestamp when supplied\n if (timestamp !== undefined && timestamp !== null) {\n verifyTimestamp(timestamp, tolerance);\n }\n\n return true;\n}\n\n/**\n * Generates an HMAC-SHA256 signature for a payload.\n *\n * @param payload - The payload string to sign\n * @param secret - The webhook secret key\n * @returns Hex-encoded signature\n *\n * @example\n * ```typescript\n * import { generateSignature } from 'pycer-sdk/webhooks';\n *\n * const signature = generateSignature('{\"event\":\"payment.completed\"}', 'whsec_...');\n * ```\n */\nexport function generateSignature(payload: string, secret: string): string {\n if (!payload || !secret) {\n throw new WebhookVerificationError('Payload and secret are required for signature generation');\n }\n\n return createHmac('sha256', secret).update(payload).digest('hex');\n}\n\n/**\n * Verifies that a webhook timestamp is within the acceptable tolerance.\n *\n * @param timestamp - The timestamp from the X-Timestamp header\n * @param tolerance - Maximum age in seconds (default: 300)\n * @throws {WebhookVerificationError} If the timestamp is too old or invalid\n */\nfunction verifyTimestamp(timestamp: string | number, tolerance: number): void {\n // Validate tolerance is a finite positive number\n if (!Number.isFinite(tolerance) || tolerance <= 0) {\n throw new WebhookVerificationError(\n `Invalid tolerance value: ${tolerance}. Must be a positive number.`\n );\n }\n\n let timestampSeconds: number;\n\n if (typeof timestamp === 'string') {\n if (timestamp.trim() === '') {\n throw new WebhookVerificationError('Invalid webhook timestamp format');\n }\n timestampSeconds = Number(timestamp);\n } else {\n timestampSeconds = timestamp;\n }\n\n // Validate timestamp is finite and positive\n if (!Number.isFinite(timestampSeconds) || timestampSeconds <= 0) {\n throw new WebhookVerificationError('Webhook timestamp must be a positive number');\n }\n\n // Convert to seconds if it looks like milliseconds\n // Unix timestamps in seconds won't exceed ~1e11 until year ~5138\n if (timestampSeconds > MILLISECOND_THRESHOLD) {\n timestampSeconds = Math.floor(timestampSeconds / 1000);\n }\n\n const currentTime = Math.floor(Date.now() / 1000);\n const age = Math.abs(currentTime - timestampSeconds);\n\n if (age > tolerance) {\n throw new WebhookVerificationError(\n `Webhook timestamp is too old. Age: ${age}s, Tolerance: ${tolerance}s. ` +\n 'This may indicate a replay attack.'\n );\n }\n}\n\n/**\n * Performs constant-time string comparison to prevent timing attacks.\n * Uses Node.js native crypto.timingSafeEqual with length padding.\n *\n * @param a - First string\n * @param b - Second string\n * @returns true if strings are equal\n */\nfunction timingSafeCompare(a: string, b: string): boolean {\n const bufA = Buffer.from(a, 'utf8');\n const bufB = Buffer.from(b, 'utf8');\n\n // Pad both buffers to the same length to avoid length-based timing leaks\n const maxLen = Math.max(bufA.length, bufB.length);\n const paddedA = Buffer.alloc(maxLen);\n const paddedB = Buffer.alloc(maxLen);\n bufA.copy(paddedA);\n bufB.copy(paddedB);\n\n const sameLength = bufA.length === bufB.length;\n return cryptoTimingSafeEqual(paddedA, paddedB) && sameLength;\n}\n\n/**\n * Parses a webhook payload from a raw request body.\n *\n * @param body - Raw request body (string or Buffer)\n * @returns Parsed webhook payload\n * @throws {WebhookVerificationError} If the payload is invalid JSON\n *\n * @example\n * ```typescript\n * import { parseWebhookPayload } from 'pycer-sdk/webhooks';\n *\n * const payload = parseWebhookPayload(req.body);\n * console.log(payload.event); // 'payment.completed'\n * ```\n */\nexport function parseWebhookPayload<T = Record<string, unknown>>(\n body: string | Buffer\n): T {\n const bodyStr = typeof body === 'string' ? body : body.toString('utf-8');\n\n try {\n return JSON.parse(bodyStr) as T;\n } catch {\n throw new WebhookVerificationError('Invalid webhook payload: not valid JSON');\n }\n}\n"]}
@@ -0,0 +1,248 @@
1
+ import { createHmac, timingSafeEqual } from 'crypto';
2
+
3
+ // src/core/errors.ts
4
+ var OwnPayError = class extends Error {
5
+ /** The error type identifier */
6
+ type;
7
+ /** HTTP status code (if applicable) */
8
+ status;
9
+ /** Unique request identifier for debugging */
10
+ requestId;
11
+ /** Raw error response from the API */
12
+ rawResponse;
13
+ constructor(message, type, status, requestId, rawResponse) {
14
+ super(message);
15
+ this.name = "OwnPayError";
16
+ this.type = type;
17
+ this.status = status;
18
+ this.requestId = requestId;
19
+ this.rawResponse = rawResponse;
20
+ Object.setPrototypeOf(this, new.target.prototype);
21
+ }
22
+ /**
23
+ * Returns a JSON representation of the error for logging.
24
+ */
25
+ toJSON() {
26
+ return {
27
+ name: this.name,
28
+ type: this.type,
29
+ message: this.message,
30
+ status: this.status,
31
+ requestId: this.requestId
32
+ };
33
+ }
34
+ };
35
+ var AuthenticationError = class extends OwnPayError {
36
+ constructor(message, requestId, rawResponse) {
37
+ super(message, "AUTHENTICATION_ERROR", 401, requestId, rawResponse);
38
+ this.name = "AuthenticationError";
39
+ }
40
+ };
41
+ var PermissionError = class extends OwnPayError {
42
+ constructor(message, requestId, rawResponse) {
43
+ super(message, "PERMISSION_ERROR", 403, requestId, rawResponse);
44
+ this.name = "PermissionError";
45
+ }
46
+ };
47
+ var NotFoundError = class extends OwnPayError {
48
+ /** The resource type that was not found */
49
+ resource;
50
+ /** The identifier that was searched for */
51
+ resourceId;
52
+ constructor(message, resource, resourceId, requestId, rawResponse) {
53
+ super(message, "NOT_FOUND", 404, requestId, rawResponse);
54
+ this.name = "NotFoundError";
55
+ this.resource = resource;
56
+ this.resourceId = resourceId;
57
+ }
58
+ };
59
+ var ValidationError = class extends OwnPayError {
60
+ /** Array of individual validation errors */
61
+ errors;
62
+ constructor(message, errors, requestId, rawResponse) {
63
+ super(message, "VALIDATION_ERROR", 422, requestId, rawResponse);
64
+ this.name = "ValidationError";
65
+ this.errors = errors;
66
+ }
67
+ /**
68
+ * Returns errors grouped by field name.
69
+ */
70
+ getFieldErrors() {
71
+ const fieldErrors = {};
72
+ for (const error of this.errors) {
73
+ const field = error.field ?? "_general";
74
+ if (!fieldErrors[field]) {
75
+ fieldErrors[field] = [];
76
+ }
77
+ fieldErrors[field].push(error.message);
78
+ }
79
+ return fieldErrors;
80
+ }
81
+ /**
82
+ * Returns the first error message for a specific field.
83
+ */
84
+ getFirstFieldError(field) {
85
+ const error = this.errors.find((e) => e.field === field);
86
+ return error?.message;
87
+ }
88
+ };
89
+ var RateLimitError = class extends OwnPayError {
90
+ /** Seconds to wait before retrying */
91
+ retryAfter;
92
+ constructor(message, retryAfter, requestId, rawResponse) {
93
+ super(message, "RATE_LIMIT_ERROR", 429, requestId, rawResponse);
94
+ this.name = "RateLimitError";
95
+ this.retryAfter = retryAfter;
96
+ }
97
+ };
98
+ var IdempotencyError = class extends OwnPayError {
99
+ constructor(message, requestId, rawResponse) {
100
+ super(message, "IDEMPOTENCY_ERROR", 409, requestId, rawResponse);
101
+ this.name = "IdempotencyError";
102
+ }
103
+ };
104
+ var ApiError = class extends OwnPayError {
105
+ /** The error code from the API */
106
+ errorCode;
107
+ constructor(message, errorCode, status = 500, requestId, rawResponse) {
108
+ super(message, "API_ERROR", status, requestId, rawResponse);
109
+ this.name = "ApiError";
110
+ this.errorCode = errorCode;
111
+ }
112
+ };
113
+ var NetworkError = class extends OwnPayError {
114
+ /** The underlying cause */
115
+ cause;
116
+ constructor(message, cause) {
117
+ super(message, "NETWORK_ERROR");
118
+ this.name = "NetworkError";
119
+ this.cause = cause;
120
+ }
121
+ };
122
+ var AbortError = class extends OwnPayError {
123
+ constructor(message = "Request was aborted") {
124
+ super(message, "ABORT_ERROR");
125
+ this.name = "AbortError";
126
+ }
127
+ };
128
+ var WebhookVerificationError = class extends OwnPayError {
129
+ constructor(message) {
130
+ super(message, "WEBHOOK_VERIFICATION_ERROR");
131
+ this.name = "WebhookVerificationError";
132
+ }
133
+ };
134
+ function createErrorFromResponse(status, body) {
135
+ const message = body.error ?? "An unexpected error occurred";
136
+ const requestId = body.request_id;
137
+ const errors = body.errors ?? [];
138
+ const rawResponse = body;
139
+ switch (status) {
140
+ case 401:
141
+ return new AuthenticationError(message, requestId, rawResponse);
142
+ case 403:
143
+ return new PermissionError(message, requestId, rawResponse);
144
+ case 404:
145
+ return new NotFoundError(message, void 0, void 0, requestId, rawResponse);
146
+ case 409:
147
+ return new IdempotencyError(message, requestId, rawResponse);
148
+ case 422:
149
+ return new ValidationError(message, errors, requestId, rawResponse);
150
+ case 429: {
151
+ const retryAfter = body.retry_after;
152
+ return new RateLimitError(
153
+ message,
154
+ typeof retryAfter === "number" && Number.isFinite(retryAfter) && retryAfter >= 0 ? retryAfter : void 0,
155
+ requestId,
156
+ rawResponse
157
+ );
158
+ }
159
+ default:
160
+ if (status >= 500) {
161
+ const errorCode = errors[0]?.code;
162
+ return new ApiError(message, errorCode, status, requestId, rawResponse);
163
+ }
164
+ return new OwnPayError(message, "UNKNOWN_ERROR", status, requestId, rawResponse);
165
+ }
166
+ }
167
+ var DEFAULT_TOLERANCE_SECONDS = 300;
168
+ var MILLISECOND_THRESHOLD = 1e12;
169
+ function verifyWebhookSignature(params) {
170
+ const { payload, signature, secret, timestamp, tolerance = DEFAULT_TOLERANCE_SECONDS } = params;
171
+ if (!payload) {
172
+ throw new WebhookVerificationError("Webhook payload is required");
173
+ }
174
+ if (!signature) {
175
+ throw new WebhookVerificationError("Webhook signature is required");
176
+ }
177
+ if (!secret) {
178
+ throw new WebhookVerificationError("Webhook secret is required");
179
+ }
180
+ const expectedSignature = createHmac("sha256", secret).update(payload).digest("hex");
181
+ if (!timingSafeCompare(signature.replace(/^sha256=/, ""), expectedSignature)) {
182
+ throw new WebhookVerificationError(
183
+ "Invalid webhook signature. The payload may have been tampered with."
184
+ );
185
+ }
186
+ if (timestamp !== void 0 && timestamp !== null) {
187
+ verifyTimestamp(timestamp, tolerance);
188
+ }
189
+ return true;
190
+ }
191
+ function generateSignature(payload, secret) {
192
+ if (!payload || !secret) {
193
+ throw new WebhookVerificationError("Payload and secret are required for signature generation");
194
+ }
195
+ return createHmac("sha256", secret).update(payload).digest("hex");
196
+ }
197
+ function verifyTimestamp(timestamp, tolerance) {
198
+ if (!Number.isFinite(tolerance) || tolerance <= 0) {
199
+ throw new WebhookVerificationError(
200
+ `Invalid tolerance value: ${tolerance}. Must be a positive number.`
201
+ );
202
+ }
203
+ let timestampSeconds;
204
+ if (typeof timestamp === "string") {
205
+ if (timestamp.trim() === "") {
206
+ throw new WebhookVerificationError("Invalid webhook timestamp format");
207
+ }
208
+ timestampSeconds = Number(timestamp);
209
+ } else {
210
+ timestampSeconds = timestamp;
211
+ }
212
+ if (!Number.isFinite(timestampSeconds) || timestampSeconds <= 0) {
213
+ throw new WebhookVerificationError("Webhook timestamp must be a positive number");
214
+ }
215
+ if (timestampSeconds > MILLISECOND_THRESHOLD) {
216
+ timestampSeconds = Math.floor(timestampSeconds / 1e3);
217
+ }
218
+ const currentTime = Math.floor(Date.now() / 1e3);
219
+ const age = Math.abs(currentTime - timestampSeconds);
220
+ if (age > tolerance) {
221
+ throw new WebhookVerificationError(
222
+ `Webhook timestamp is too old. Age: ${age}s, Tolerance: ${tolerance}s. This may indicate a replay attack.`
223
+ );
224
+ }
225
+ }
226
+ function timingSafeCompare(a, b) {
227
+ const bufA = Buffer.from(a, "utf8");
228
+ const bufB = Buffer.from(b, "utf8");
229
+ const maxLen = Math.max(bufA.length, bufB.length);
230
+ const paddedA = Buffer.alloc(maxLen);
231
+ const paddedB = Buffer.alloc(maxLen);
232
+ bufA.copy(paddedA);
233
+ bufB.copy(paddedB);
234
+ const sameLength = bufA.length === bufB.length;
235
+ return timingSafeEqual(paddedA, paddedB) && sameLength;
236
+ }
237
+ function parseWebhookPayload(body) {
238
+ const bodyStr = typeof body === "string" ? body : body.toString("utf-8");
239
+ try {
240
+ return JSON.parse(bodyStr);
241
+ } catch {
242
+ throw new WebhookVerificationError("Invalid webhook payload: not valid JSON");
243
+ }
244
+ }
245
+
246
+ export { AbortError, ApiError, AuthenticationError, IdempotencyError, NetworkError, NotFoundError, OwnPayError, PermissionError, RateLimitError, ValidationError, WebhookVerificationError, createErrorFromResponse, generateSignature, parseWebhookPayload, verifyWebhookSignature };
247
+ //# sourceMappingURL=chunk-ERUWKVNC.js.map
248
+ //# sourceMappingURL=chunk-ERUWKVNC.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/core/errors.ts","../src/webhooks/verify.ts"],"names":["cryptoTimingSafeEqual"],"mappings":"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","file":"chunk-ERUWKVNC.js","sourcesContent":["/**\n * OwnPay Node.js SDK - Error Classes\n *\n * Comprehensive error hierarchy for the OwnPay API.\n * Each error class provides specific context for different failure scenarios.\n */\n\nimport type { ApiErrorDetail } from './types.js';\n\n/**\n * Base error class for all OwnPay SDK errors.\n * Provides common properties and methods for error handling.\n */\nexport class OwnPayError extends Error {\n /** The error type identifier */\n readonly type: string;\n /** HTTP status code (if applicable) */\n readonly status: number | undefined;\n /** Unique request identifier for debugging */\n readonly requestId: string | undefined;\n /** Raw error response from the API */\n readonly rawResponse: unknown;\n\n constructor(\n message: string,\n type: string,\n status?: number,\n requestId?: string,\n rawResponse?: unknown\n ) {\n super(message);\n this.name = 'OwnPayError';\n this.type = type;\n this.status = status;\n this.requestId = requestId;\n this.rawResponse = rawResponse;\n\n // Maintains proper prototype chain for instanceof checks\n Object.setPrototypeOf(this, new.target.prototype);\n }\n\n /**\n * Returns a JSON representation of the error for logging.\n */\n toJSON(): Record<string, unknown> {\n return {\n name: this.name,\n type: this.type,\n message: this.message,\n status: this.status,\n requestId: this.requestId,\n };\n }\n}\n\n/**\n * Thrown when API authentication fails (401).\n * Indicates an invalid, missing, or revoked API key.\n */\nexport class AuthenticationError extends OwnPayError {\n constructor(message: string, requestId?: string, rawResponse?: unknown) {\n super(message, 'AUTHENTICATION_ERROR', 401, requestId, rawResponse);\n this.name = 'AuthenticationError';\n }\n}\n\n/**\n * Thrown when the API key lacks required permissions (403).\n * Indicates insufficient scope (e.g., read-only key attempting a write operation).\n */\nexport class PermissionError extends OwnPayError {\n constructor(message: string, requestId?: string, rawResponse?: unknown) {\n super(message, 'PERMISSION_ERROR', 403, requestId, rawResponse);\n this.name = 'PermissionError';\n }\n}\n\n/**\n * Thrown when a requested resource is not found (404).\n */\nexport class NotFoundError extends OwnPayError {\n /** The resource type that was not found */\n readonly resource: string | undefined;\n /** The identifier that was searched for */\n readonly resourceId: string | undefined;\n\n constructor(\n message: string,\n resource?: string,\n resourceId?: string,\n requestId?: string,\n rawResponse?: unknown\n ) {\n super(message, 'NOT_FOUND', 404, requestId, rawResponse);\n this.name = 'NotFoundError';\n this.resource = resource;\n this.resourceId = resourceId;\n }\n}\n\n/**\n * Thrown when request validation fails (422).\n * Contains structured error details for each invalid field.\n */\nexport class ValidationError extends OwnPayError {\n /** Array of individual validation errors */\n readonly errors: ApiErrorDetail[];\n\n constructor(\n message: string,\n errors: ApiErrorDetail[],\n requestId?: string,\n rawResponse?: unknown\n ) {\n super(message, 'VALIDATION_ERROR', 422, requestId, rawResponse);\n this.name = 'ValidationError';\n this.errors = errors;\n }\n\n /**\n * Returns errors grouped by field name.\n */\n getFieldErrors(): Record<string, string[]> {\n const fieldErrors: Record<string, string[]> = {};\n for (const error of this.errors) {\n const field = error.field ?? '_general';\n if (!fieldErrors[field]) {\n fieldErrors[field] = [];\n }\n fieldErrors[field].push(error.message);\n }\n return fieldErrors;\n }\n\n /**\n * Returns the first error message for a specific field.\n */\n getFirstFieldError(field: string): string | undefined {\n const error = this.errors.find((e) => e.field === field);\n return error?.message;\n }\n}\n\n/**\n * Thrown when the API rate limit is exceeded (429).\n * Includes retry-after information when available.\n */\nexport class RateLimitError extends OwnPayError {\n /** Seconds to wait before retrying */\n readonly retryAfter: number | undefined;\n\n constructor(\n message: string,\n retryAfter?: number,\n requestId?: string,\n rawResponse?: unknown\n ) {\n super(message, 'RATE_LIMIT_ERROR', 429, requestId, rawResponse);\n this.name = 'RateLimitError';\n this.retryAfter = retryAfter;\n }\n}\n\n/**\n * Thrown when an idempotency key conflict occurs (409).\n * Indicates a request with the same key is still processing.\n */\nexport class IdempotencyError extends OwnPayError {\n constructor(message: string, requestId?: string, rawResponse?: unknown) {\n super(message, 'IDEMPOTENCY_ERROR', 409, requestId, rawResponse);\n this.name = 'IdempotencyError';\n }\n}\n\n/**\n * Thrown when the API returns a server error (500, 502, 503, 504).\n */\nexport class ApiError extends OwnPayError {\n /** The error code from the API */\n readonly errorCode: string | undefined;\n\n constructor(\n message: string,\n errorCode?: string,\n status: number = 500,\n requestId?: string,\n rawResponse?: unknown\n ) {\n super(message, 'API_ERROR', status, requestId, rawResponse);\n this.name = 'ApiError';\n this.errorCode = errorCode;\n }\n}\n\n/**\n * Thrown when a network error occurs (connection failure, timeout, etc.).\n */\nexport class NetworkError extends OwnPayError {\n /** The underlying cause */\n override readonly cause: Error | undefined;\n\n constructor(message: string, cause?: Error) {\n super(message, 'NETWORK_ERROR');\n this.name = 'NetworkError';\n this.cause = cause;\n }\n}\n\n/**\n * Thrown when a request is aborted (via AbortSignal or timeout).\n */\nexport class AbortError extends OwnPayError {\n constructor(message: string = 'Request was aborted') {\n super(message, 'ABORT_ERROR');\n this.name = 'AbortError';\n }\n}\n\n/**\n * Thrown when webhook signature verification fails.\n */\nexport class WebhookVerificationError extends OwnPayError {\n constructor(message: string) {\n super(message, 'WEBHOOK_VERIFICATION_ERROR');\n this.name = 'WebhookVerificationError';\n }\n}\n\n/**\n * Creates the appropriate error class from an API error response.\n *\n * @internal\n */\nexport function createErrorFromResponse(\n status: number,\n body: {\n error?: string;\n errors?: ApiErrorDetail[];\n request_id?: string;\n [key: string]: unknown;\n }\n): OwnPayError {\n const message = body.error ?? 'An unexpected error occurred';\n const requestId = body.request_id;\n const errors = body.errors ?? [];\n const rawResponse = body;\n\n switch (status) {\n case 401:\n return new AuthenticationError(message, requestId, rawResponse);\n\n case 403:\n return new PermissionError(message, requestId, rawResponse);\n\n case 404:\n return new NotFoundError(message, undefined, undefined, requestId, rawResponse);\n\n case 409:\n return new IdempotencyError(message, requestId, rawResponse);\n\n case 422:\n return new ValidationError(message, errors, requestId, rawResponse);\n\n case 429: {\n // Extract retry-after from response if available\n const retryAfter = body.retry_after;\n return new RateLimitError(\n message,\n typeof retryAfter === 'number' && Number.isFinite(retryAfter) && retryAfter >= 0\n ? retryAfter\n : undefined,\n requestId,\n rawResponse\n );\n }\n\n default:\n if (status >= 500) {\n const errorCode = errors[0]?.code;\n return new ApiError(message, errorCode, status, requestId, rawResponse);\n }\n\n return new OwnPayError(message, 'UNKNOWN_ERROR', status, requestId, rawResponse);\n }\n}\n","/**\n * OwnPay Node.js SDK - Webhook Signature Verification\n *\n * Standalone utility for verifying OwnPay webhook signatures.\n * Uses HMAC-SHA256 for cryptographic verification.\n *\n * @module ownpay/webhooks\n */\n\nimport { createHmac, timingSafeEqual as cryptoTimingSafeEqual } from 'node:crypto';\nimport { WebhookVerificationError } from '../core/errors.js';\nimport type { WebhookVerificationParams } from '../core/types.js';\n\n/**\n * Default tolerance for timestamp validation (5 minutes).\n */\nconst DEFAULT_TOLERANCE_SECONDS = 300;\n\n/**\n * Unix timestamps in seconds will be between ~0 and ~1e11 (year ~5138).\n * Timestamps above this threshold are assumed to be in milliseconds.\n */\nconst MILLISECOND_THRESHOLD = 1e12;\n\n/**\n * Verifies an OwnPay webhook signature.\n *\n * This function verifies that the webhook payload was sent by OwnPay\n * and has not been tampered with. It supports optional timestamp\n * validation for legacy delivery diagnostics. The timestamp is outside the signature.\n *\n * @param params - Verification parameters\n * @returns true if the signature is valid\n * @throws {WebhookVerificationError} If the signature is invalid\n *\n * @example\n * ```typescript\n * import { verifyWebhookSignature } from 'pycer-sdk/webhooks';\n *\n * // In your webhook handler\n * app.post('/webhook', (req, res) => {\n * try {\n * verifyWebhookSignature({\n * payload: req.body,\n * signature: req.headers['x-signature'],\n * secret: process.env.OWNPAY_WEBHOOK_SECRET,\n * timestamp: req.headers['x-timestamp'],\n * });\n *\n * // Signature is valid, process the webhook\n * const event = JSON.parse(req.body);\n * handleWebhookEvent(event);\n *\n * res.status(200).json({ received: true });\n * } catch (error) {\n * res.status(400).json({ error: 'Invalid signature' });\n * }\n * });\n * ```\n */\nexport function verifyWebhookSignature(params: WebhookVerificationParams): boolean {\n const { payload, signature, secret, timestamp, tolerance = DEFAULT_TOLERANCE_SECONDS } = params;\n\n // Validate required parameters\n if (!payload) {\n throw new WebhookVerificationError('Webhook payload is required');\n }\n\n if (!signature) {\n throw new WebhookVerificationError('Webhook signature is required');\n }\n\n if (!secret) {\n throw new WebhookVerificationError('Webhook secret is required');\n }\n\n // Generate expected signature\n const expectedSignature = createHmac('sha256', secret).update(payload).digest('hex');\n\n // Verify signature using constant-time comparison\n if (!timingSafeCompare(signature.replace(/^sha256=/, ''), expectedSignature)) {\n throw new WebhookVerificationError(\n 'Invalid webhook signature. The payload may have been tampered with.'\n );\n }\n\n // Check the unsigned timestamp when supplied\n if (timestamp !== undefined && timestamp !== null) {\n verifyTimestamp(timestamp, tolerance);\n }\n\n return true;\n}\n\n/**\n * Generates an HMAC-SHA256 signature for a payload.\n *\n * @param payload - The payload string to sign\n * @param secret - The webhook secret key\n * @returns Hex-encoded signature\n *\n * @example\n * ```typescript\n * import { generateSignature } from 'pycer-sdk/webhooks';\n *\n * const signature = generateSignature('{\"event\":\"payment.completed\"}', 'whsec_...');\n * ```\n */\nexport function generateSignature(payload: string, secret: string): string {\n if (!payload || !secret) {\n throw new WebhookVerificationError('Payload and secret are required for signature generation');\n }\n\n return createHmac('sha256', secret).update(payload).digest('hex');\n}\n\n/**\n * Verifies that a webhook timestamp is within the acceptable tolerance.\n *\n * @param timestamp - The timestamp from the X-Timestamp header\n * @param tolerance - Maximum age in seconds (default: 300)\n * @throws {WebhookVerificationError} If the timestamp is too old or invalid\n */\nfunction verifyTimestamp(timestamp: string | number, tolerance: number): void {\n // Validate tolerance is a finite positive number\n if (!Number.isFinite(tolerance) || tolerance <= 0) {\n throw new WebhookVerificationError(\n `Invalid tolerance value: ${tolerance}. Must be a positive number.`\n );\n }\n\n let timestampSeconds: number;\n\n if (typeof timestamp === 'string') {\n if (timestamp.trim() === '') {\n throw new WebhookVerificationError('Invalid webhook timestamp format');\n }\n timestampSeconds = Number(timestamp);\n } else {\n timestampSeconds = timestamp;\n }\n\n // Validate timestamp is finite and positive\n if (!Number.isFinite(timestampSeconds) || timestampSeconds <= 0) {\n throw new WebhookVerificationError('Webhook timestamp must be a positive number');\n }\n\n // Convert to seconds if it looks like milliseconds\n // Unix timestamps in seconds won't exceed ~1e11 until year ~5138\n if (timestampSeconds > MILLISECOND_THRESHOLD) {\n timestampSeconds = Math.floor(timestampSeconds / 1000);\n }\n\n const currentTime = Math.floor(Date.now() / 1000);\n const age = Math.abs(currentTime - timestampSeconds);\n\n if (age > tolerance) {\n throw new WebhookVerificationError(\n `Webhook timestamp is too old. Age: ${age}s, Tolerance: ${tolerance}s. ` +\n 'This may indicate a replay attack.'\n );\n }\n}\n\n/**\n * Performs constant-time string comparison to prevent timing attacks.\n * Uses Node.js native crypto.timingSafeEqual with length padding.\n *\n * @param a - First string\n * @param b - Second string\n * @returns true if strings are equal\n */\nfunction timingSafeCompare(a: string, b: string): boolean {\n const bufA = Buffer.from(a, 'utf8');\n const bufB = Buffer.from(b, 'utf8');\n\n // Pad both buffers to the same length to avoid length-based timing leaks\n const maxLen = Math.max(bufA.length, bufB.length);\n const paddedA = Buffer.alloc(maxLen);\n const paddedB = Buffer.alloc(maxLen);\n bufA.copy(paddedA);\n bufB.copy(paddedB);\n\n const sameLength = bufA.length === bufB.length;\n return cryptoTimingSafeEqual(paddedA, paddedB) && sameLength;\n}\n\n/**\n * Parses a webhook payload from a raw request body.\n *\n * @param body - Raw request body (string or Buffer)\n * @returns Parsed webhook payload\n * @throws {WebhookVerificationError} If the payload is invalid JSON\n *\n * @example\n * ```typescript\n * import { parseWebhookPayload } from 'pycer-sdk/webhooks';\n *\n * const payload = parseWebhookPayload(req.body);\n * console.log(payload.event); // 'payment.completed'\n * ```\n */\nexport function parseWebhookPayload<T = Record<string, unknown>>(\n body: string | Buffer\n): T {\n const bodyStr = typeof body === 'string' ? body : body.toString('utf-8');\n\n try {\n return JSON.parse(bodyStr) as T;\n } catch {\n throw new WebhookVerificationError('Invalid webhook payload: not valid JSON');\n }\n}\n"]}