pycer-sdk 0.0.0-stage → 1.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +890 -2
- package/dist/chunk-ANI325UM.cjs +264 -0
- package/dist/chunk-ANI325UM.cjs.map +1 -0
- package/dist/chunk-ERUWKVNC.js +248 -0
- package/dist/chunk-ERUWKVNC.js.map +1 -0
- package/dist/index-XbnGOTNP.d.cts +686 -0
- package/dist/index-XbnGOTNP.d.ts +686 -0
- package/dist/index.cjs +1323 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +831 -0
- package/dist/index.d.ts +831 -0
- package/dist/index.js +1246 -0
- package/dist/index.js.map +1 -0
- package/dist/webhooks/index.cjs +24 -0
- package/dist/webhooks/index.cjs.map +1 -0
- package/dist/webhooks/index.d.cts +1 -0
- package/dist/webhooks/index.d.ts +1 -0
- package/dist/webhooks/index.js +3 -0
- package/dist/webhooks/index.js.map +1 -0
- package/package.json +76 -4
|
@@ -0,0 +1,686 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* OwnPay Node.js SDK - Type Definitions
|
|
3
|
+
*
|
|
4
|
+
* Comprehensive type definitions for the OwnPay Payment Gateway API.
|
|
5
|
+
* All types are derived from the actual PHP API controllers.
|
|
6
|
+
*/
|
|
7
|
+
/**
|
|
8
|
+
* Configuration options for the OwnPay client.
|
|
9
|
+
*/
|
|
10
|
+
interface OwnPayConfig {
|
|
11
|
+
/** API key starting with 'op_' prefix */
|
|
12
|
+
apiKey: string;
|
|
13
|
+
/** Base URL for the self-hosted API (or set OWNPAY_BASE_URL) */
|
|
14
|
+
baseUrl?: string;
|
|
15
|
+
/** Public OwnPay-branded browser checkout URL when the API uses a gateway. */
|
|
16
|
+
checkoutBaseUrl?: string;
|
|
17
|
+
/** Request timeout in milliseconds (default: 30000) */
|
|
18
|
+
timeout?: number;
|
|
19
|
+
/** Maximum number of retry attempts (default: 2) */
|
|
20
|
+
maxRetries?: number;
|
|
21
|
+
/** Custom headers to include in all requests */
|
|
22
|
+
headers?: Record<string, string>;
|
|
23
|
+
/** API version (default: 'v1') */
|
|
24
|
+
apiVersion?: string;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* Request options that can be passed per-request.
|
|
28
|
+
*/
|
|
29
|
+
interface RequestOptions {
|
|
30
|
+
/** Idempotency key for safe request retries */
|
|
31
|
+
idempotencyKey?: string;
|
|
32
|
+
/** Custom headers for this specific request */
|
|
33
|
+
headers?: Record<string, string>;
|
|
34
|
+
/** Request timeout override in milliseconds */
|
|
35
|
+
timeout?: number;
|
|
36
|
+
/** AbortSignal for request cancellation */
|
|
37
|
+
signal?: AbortSignal;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Standard success response from the OwnPay API.
|
|
41
|
+
*/
|
|
42
|
+
interface ApiResponse<T = unknown> {
|
|
43
|
+
/** Always true for successful responses */
|
|
44
|
+
success: true;
|
|
45
|
+
/** Response data payload */
|
|
46
|
+
data: T;
|
|
47
|
+
/** Optional pagination or metadata */
|
|
48
|
+
meta?: PaginationMeta;
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Standard error response from the OwnPay API.
|
|
52
|
+
*/
|
|
53
|
+
interface ApiErrorResponse {
|
|
54
|
+
/** Always false for error responses */
|
|
55
|
+
success: false;
|
|
56
|
+
/** Human-readable error message */
|
|
57
|
+
error: string;
|
|
58
|
+
/** Structured error details */
|
|
59
|
+
errors: ApiErrorDetail[];
|
|
60
|
+
/** Unique request identifier for debugging */
|
|
61
|
+
request_id: string;
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* Individual error detail in an error response.
|
|
65
|
+
*/
|
|
66
|
+
interface ApiErrorDetail {
|
|
67
|
+
/** Machine-readable error code */
|
|
68
|
+
code: string;
|
|
69
|
+
/** Human-readable error message */
|
|
70
|
+
message: string;
|
|
71
|
+
/** Optional field name that caused the error */
|
|
72
|
+
field?: string | null;
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* Pagination metadata for list endpoints.
|
|
76
|
+
*/
|
|
77
|
+
interface PaginationMeta {
|
|
78
|
+
/** Current page number */
|
|
79
|
+
page: number;
|
|
80
|
+
/** Items per page */
|
|
81
|
+
per_page: number;
|
|
82
|
+
/** Total number of items */
|
|
83
|
+
total: number;
|
|
84
|
+
/** Total number of pages */
|
|
85
|
+
total_pages: number;
|
|
86
|
+
}
|
|
87
|
+
/**
|
|
88
|
+
* Parameters for creating a payment intent.
|
|
89
|
+
*/
|
|
90
|
+
interface CreatePaymentParams {
|
|
91
|
+
/** Payment amount (positive number) */
|
|
92
|
+
amount: string | number;
|
|
93
|
+
/** 3-letter ISO currency code (e.g., 'BDT', 'USD') */
|
|
94
|
+
currency: string;
|
|
95
|
+
/** Webhook notification URL */
|
|
96
|
+
callback_url?: string;
|
|
97
|
+
/** Success redirect URL */
|
|
98
|
+
redirect_url?: string;
|
|
99
|
+
/** Cancel redirect URL */
|
|
100
|
+
cancel_url?: string;
|
|
101
|
+
/** Customer email address */
|
|
102
|
+
customer_email?: string;
|
|
103
|
+
/** Customer full name (max 150 characters) */
|
|
104
|
+
customer_name?: string;
|
|
105
|
+
/** Customer phone number (max 30 characters) */
|
|
106
|
+
customer_phone?: string;
|
|
107
|
+
/** Merchant reference identifier */
|
|
108
|
+
reference?: string;
|
|
109
|
+
/** Preferred payment gateway slug */
|
|
110
|
+
gateway?: string;
|
|
111
|
+
/** Custom key-value metadata */
|
|
112
|
+
metadata?: Record<string, unknown>;
|
|
113
|
+
}
|
|
114
|
+
/**
|
|
115
|
+
* Payment intent returned after creation.
|
|
116
|
+
*/
|
|
117
|
+
interface PaymentIntent {
|
|
118
|
+
/** Unique payment identifier (UUID) */
|
|
119
|
+
payment_id: string;
|
|
120
|
+
/** Payment intent token for checkout */
|
|
121
|
+
token: string;
|
|
122
|
+
/** URL to redirect customer for payment */
|
|
123
|
+
checkout_url: string;
|
|
124
|
+
/** Current payment status */
|
|
125
|
+
status: PaymentStatus;
|
|
126
|
+
}
|
|
127
|
+
/**
|
|
128
|
+
* Detailed payment information.
|
|
129
|
+
*/
|
|
130
|
+
interface Payment {
|
|
131
|
+
/** Transaction ID (null if no transaction yet) */
|
|
132
|
+
id: number | null;
|
|
133
|
+
/** OwnPay transaction reference (e.g., 'OP-XXXX') */
|
|
134
|
+
trx_id: string | null;
|
|
135
|
+
/** Gateway transaction ID */
|
|
136
|
+
gateway_trx_id: string | null;
|
|
137
|
+
/** Payment amount */
|
|
138
|
+
amount: string | null;
|
|
139
|
+
/** Currency code */
|
|
140
|
+
currency: string | null;
|
|
141
|
+
/** Processing fee */
|
|
142
|
+
fee: string;
|
|
143
|
+
/** Current status */
|
|
144
|
+
status: string | null;
|
|
145
|
+
/** Payment gateway used */
|
|
146
|
+
gateway: string | null;
|
|
147
|
+
/** Payment method */
|
|
148
|
+
method: string | null;
|
|
149
|
+
/** Merchant reference */
|
|
150
|
+
reference: string | null;
|
|
151
|
+
/** Creation timestamp */
|
|
152
|
+
created_at: string | null;
|
|
153
|
+
/** Completion timestamp */
|
|
154
|
+
completed_at: string | null;
|
|
155
|
+
/** Customer information (if available) */
|
|
156
|
+
customer?: CustomerSummary;
|
|
157
|
+
}
|
|
158
|
+
/**
|
|
159
|
+
* Customer summary attached to a payment.
|
|
160
|
+
*/
|
|
161
|
+
interface CustomerSummary {
|
|
162
|
+
/** Customer name */
|
|
163
|
+
name: string | null;
|
|
164
|
+
/** Customer email */
|
|
165
|
+
email: string | null;
|
|
166
|
+
}
|
|
167
|
+
/**
|
|
168
|
+
* Possible payment statuses.
|
|
169
|
+
*/
|
|
170
|
+
type PaymentStatus = 'pending' | 'processing' | 'completed' | 'failed' | 'cancelled' | 'refunded';
|
|
171
|
+
/**
|
|
172
|
+
* Parameters for listing transactions.
|
|
173
|
+
*/
|
|
174
|
+
interface ListTransactionsParams {
|
|
175
|
+
/** Page number (default: 1) */
|
|
176
|
+
page?: number;
|
|
177
|
+
/** Items per page (default: 25, max: 100) */
|
|
178
|
+
per_page?: number;
|
|
179
|
+
/** Filter by status */
|
|
180
|
+
status?: string;
|
|
181
|
+
/** Filter by gateway slug */
|
|
182
|
+
gateway?: string;
|
|
183
|
+
/** Filter from date (ISO format) */
|
|
184
|
+
from?: string;
|
|
185
|
+
/** Filter to date (ISO format) */
|
|
186
|
+
to?: string;
|
|
187
|
+
}
|
|
188
|
+
/**
|
|
189
|
+
* Transaction record.
|
|
190
|
+
*/
|
|
191
|
+
interface Transaction {
|
|
192
|
+
/** Internal transaction ID */
|
|
193
|
+
id: number;
|
|
194
|
+
/** OwnPay transaction reference */
|
|
195
|
+
trx_id: string;
|
|
196
|
+
/** Gateway transaction ID */
|
|
197
|
+
gateway_trx_id: string | null;
|
|
198
|
+
/** Transaction amount */
|
|
199
|
+
amount: string;
|
|
200
|
+
/** Currency code */
|
|
201
|
+
currency: string;
|
|
202
|
+
/** Processing fee */
|
|
203
|
+
fee: string;
|
|
204
|
+
/** Net amount after fees */
|
|
205
|
+
net_amount: string | null;
|
|
206
|
+
/** Transaction status */
|
|
207
|
+
status: string;
|
|
208
|
+
/** Gateway slug */
|
|
209
|
+
gateway: string | null;
|
|
210
|
+
/** Payment method */
|
|
211
|
+
method: string | null;
|
|
212
|
+
/** Merchant reference */
|
|
213
|
+
reference: string | null;
|
|
214
|
+
/** Creation timestamp */
|
|
215
|
+
created_at: string;
|
|
216
|
+
/** Last update timestamp */
|
|
217
|
+
updated_at: string | null;
|
|
218
|
+
}
|
|
219
|
+
/**
|
|
220
|
+
* Parameters for creating a refund.
|
|
221
|
+
*/
|
|
222
|
+
interface CreateRefundParams {
|
|
223
|
+
/** Transaction ID or OwnPay reference */
|
|
224
|
+
transaction_id?: string | number;
|
|
225
|
+
/** OwnPay transaction reference */
|
|
226
|
+
trx_id?: string | number;
|
|
227
|
+
/** Refund amount (partial refund if less than original) */
|
|
228
|
+
amount?: string | number;
|
|
229
|
+
/** Reason for refund */
|
|
230
|
+
reason?: string;
|
|
231
|
+
}
|
|
232
|
+
/**
|
|
233
|
+
* Parameters for listing refunds.
|
|
234
|
+
*/
|
|
235
|
+
interface ListRefundsParams {
|
|
236
|
+
/** Page number (default: 1) */
|
|
237
|
+
page?: number;
|
|
238
|
+
/** Items per page (default: 25, max: 100) */
|
|
239
|
+
per_page?: number;
|
|
240
|
+
/** Filter by status */
|
|
241
|
+
status?: string;
|
|
242
|
+
/** Filter by transaction reference */
|
|
243
|
+
trx_id?: string;
|
|
244
|
+
/** Filter by transaction ID */
|
|
245
|
+
transaction_id?: string | number;
|
|
246
|
+
/** Filter from date (ISO format) */
|
|
247
|
+
from?: string;
|
|
248
|
+
/** Filter to date (ISO format) */
|
|
249
|
+
to?: string;
|
|
250
|
+
}
|
|
251
|
+
/**
|
|
252
|
+
* Refund record.
|
|
253
|
+
*/
|
|
254
|
+
interface Refund {
|
|
255
|
+
/** Internal refund ID */
|
|
256
|
+
id: number | null;
|
|
257
|
+
/** Refund UUID */
|
|
258
|
+
uuid: string | null;
|
|
259
|
+
/** Associated transaction ID */
|
|
260
|
+
transaction_id: number | null;
|
|
261
|
+
/** OwnPay transaction reference */
|
|
262
|
+
trx_id: string | null;
|
|
263
|
+
/** Gateway transaction ID */
|
|
264
|
+
gateway_trx_id: string | null;
|
|
265
|
+
/** Refund amount */
|
|
266
|
+
amount: string | null;
|
|
267
|
+
/** Refund reason */
|
|
268
|
+
reason: string | null;
|
|
269
|
+
/** Refund status */
|
|
270
|
+
status: string | null;
|
|
271
|
+
/** Processing timestamp */
|
|
272
|
+
processed_at: string | null;
|
|
273
|
+
/** Creation timestamp */
|
|
274
|
+
created_at: string | null;
|
|
275
|
+
}
|
|
276
|
+
/**
|
|
277
|
+
* Parameters for creating a customer.
|
|
278
|
+
*/
|
|
279
|
+
interface CreateCustomerParams {
|
|
280
|
+
/** Customer full name (required) */
|
|
281
|
+
name: string;
|
|
282
|
+
/** Customer email address */
|
|
283
|
+
email?: string;
|
|
284
|
+
/** Customer phone number */
|
|
285
|
+
phone?: string;
|
|
286
|
+
}
|
|
287
|
+
/**
|
|
288
|
+
* Parameters for listing customers.
|
|
289
|
+
*/
|
|
290
|
+
interface ListCustomersParams {
|
|
291
|
+
/** Page number (default: 1) */
|
|
292
|
+
page?: number;
|
|
293
|
+
/** Items per page (default: 25, max: 100) */
|
|
294
|
+
per_page?: number;
|
|
295
|
+
}
|
|
296
|
+
/**
|
|
297
|
+
* Customer record.
|
|
298
|
+
*/
|
|
299
|
+
interface Customer {
|
|
300
|
+
/** Internal customer ID */
|
|
301
|
+
id: number;
|
|
302
|
+
/** Customer UUID */
|
|
303
|
+
uuid: string;
|
|
304
|
+
/** Customer name */
|
|
305
|
+
name: string | null;
|
|
306
|
+
/** Customer email */
|
|
307
|
+
email: string | null;
|
|
308
|
+
/** Customer phone */
|
|
309
|
+
phone: string | null;
|
|
310
|
+
/** Masked email for display */
|
|
311
|
+
email_masked?: string | null;
|
|
312
|
+
/** Masked phone for display */
|
|
313
|
+
phone_masked?: string | null;
|
|
314
|
+
/** Creation timestamp */
|
|
315
|
+
created_at: string;
|
|
316
|
+
}
|
|
317
|
+
/**
|
|
318
|
+
* Parameters for generating an API key.
|
|
319
|
+
*/
|
|
320
|
+
interface GenerateApiKeyParams {
|
|
321
|
+
/** Key name/label (default: 'Default') */
|
|
322
|
+
name?: string;
|
|
323
|
+
/** Key permission scopes (default: ['read', 'write']) */
|
|
324
|
+
scopes?: ApiKeyScope[];
|
|
325
|
+
}
|
|
326
|
+
/**
|
|
327
|
+
* API key permission scope.
|
|
328
|
+
*/
|
|
329
|
+
type ApiKeyScope = 'read' | 'write' | 'admin';
|
|
330
|
+
/**
|
|
331
|
+
* API key metadata (without the actual key).
|
|
332
|
+
*/
|
|
333
|
+
interface ApiKey {
|
|
334
|
+
/** Internal key ID */
|
|
335
|
+
id: number;
|
|
336
|
+
/** Key name/label */
|
|
337
|
+
name: string;
|
|
338
|
+
/** Key prefix for identification */
|
|
339
|
+
prefix: string | null;
|
|
340
|
+
/** Key status */
|
|
341
|
+
status: 'active' | 'revoked';
|
|
342
|
+
/** Last usage timestamp */
|
|
343
|
+
last_used: string | null;
|
|
344
|
+
/** Expiration timestamp */
|
|
345
|
+
expires_at: string | null;
|
|
346
|
+
/** Creation timestamp */
|
|
347
|
+
created_at: string;
|
|
348
|
+
}
|
|
349
|
+
/**
|
|
350
|
+
* API key generation response (includes the actual key).
|
|
351
|
+
*/
|
|
352
|
+
interface GeneratedApiKey {
|
|
353
|
+
/** The actual API key (shown only once) */
|
|
354
|
+
key: string;
|
|
355
|
+
/** Key prefix for identification */
|
|
356
|
+
prefix: string | null;
|
|
357
|
+
/** Security warning */
|
|
358
|
+
warning: string;
|
|
359
|
+
}
|
|
360
|
+
/**
|
|
361
|
+
* Webhook test result.
|
|
362
|
+
*/
|
|
363
|
+
interface WebhookTestResult {
|
|
364
|
+
/** HTTP status code from the webhook endpoint */
|
|
365
|
+
status_code: number | null;
|
|
366
|
+
/** Response time in milliseconds */
|
|
367
|
+
response_time_ms: number | null;
|
|
368
|
+
}
|
|
369
|
+
/**
|
|
370
|
+
* Webhook delivery record.
|
|
371
|
+
*/
|
|
372
|
+
interface WebhookDelivery {
|
|
373
|
+
/** Delivery ID */
|
|
374
|
+
id: number;
|
|
375
|
+
/** Event name */
|
|
376
|
+
event: string;
|
|
377
|
+
/** Webhook URL */
|
|
378
|
+
url: string;
|
|
379
|
+
/** Delivery direction */
|
|
380
|
+
direction: 'outbound' | 'inbound';
|
|
381
|
+
/** HTTP status code */
|
|
382
|
+
status_code: number | null;
|
|
383
|
+
/** Response time in milliseconds */
|
|
384
|
+
response_time_ms: number | null;
|
|
385
|
+
/** Attempt number */
|
|
386
|
+
attempt: number;
|
|
387
|
+
/** Delivery status */
|
|
388
|
+
status: string;
|
|
389
|
+
/** Creation timestamp */
|
|
390
|
+
created_at: string;
|
|
391
|
+
}
|
|
392
|
+
/**
|
|
393
|
+
* Webhook event payload structure.
|
|
394
|
+
*/
|
|
395
|
+
interface WebhookPayload {
|
|
396
|
+
/** Event type (e.g., 'payment.completed') */
|
|
397
|
+
event: string;
|
|
398
|
+
/** OwnPay transaction reference */
|
|
399
|
+
transaction_id: string;
|
|
400
|
+
/** Gateway transaction ID */
|
|
401
|
+
gateway_trx_id: string;
|
|
402
|
+
/** Transaction amount */
|
|
403
|
+
amount: string;
|
|
404
|
+
/** Currency code */
|
|
405
|
+
currency: string;
|
|
406
|
+
/** Processing fee */
|
|
407
|
+
fee: string;
|
|
408
|
+
/** Gateway slug */
|
|
409
|
+
gateway: string;
|
|
410
|
+
/** Gateway type */
|
|
411
|
+
gateway_type: string;
|
|
412
|
+
/** Transaction status */
|
|
413
|
+
status: string;
|
|
414
|
+
/** Customer information */
|
|
415
|
+
customer: {
|
|
416
|
+
/** Customer name */
|
|
417
|
+
name: string;
|
|
418
|
+
/** Customer email */
|
|
419
|
+
email: string;
|
|
420
|
+
/** Customer phone */
|
|
421
|
+
phone: string;
|
|
422
|
+
};
|
|
423
|
+
/** Custom metadata */
|
|
424
|
+
metadata: Record<string, unknown>;
|
|
425
|
+
/** Event timestamp (ISO format) */
|
|
426
|
+
timestamp: string;
|
|
427
|
+
}
|
|
428
|
+
/**
|
|
429
|
+
* Parameters for webhook signature verification.
|
|
430
|
+
*/
|
|
431
|
+
interface WebhookVerificationParams {
|
|
432
|
+
/** Raw request body (string or Buffer) */
|
|
433
|
+
payload: string | Buffer;
|
|
434
|
+
/** Signature from X-OwnPay-Signature header */
|
|
435
|
+
signature: string;
|
|
436
|
+
/** Webhook secret key */
|
|
437
|
+
secret: string;
|
|
438
|
+
/** Optional: timestamp from X-OwnPay-Timestamp header for replay protection */
|
|
439
|
+
timestamp?: string | number;
|
|
440
|
+
/** Optional: maximum age in seconds for replay protection (default: 300) */
|
|
441
|
+
tolerance?: number;
|
|
442
|
+
}
|
|
443
|
+
/**
|
|
444
|
+
* System health check response.
|
|
445
|
+
*/
|
|
446
|
+
interface HealthStatus {
|
|
447
|
+
/** Overall system status */
|
|
448
|
+
status: 'healthy' | 'degraded';
|
|
449
|
+
/** Application version */
|
|
450
|
+
version: string;
|
|
451
|
+
/** Database connection status */
|
|
452
|
+
db: 'connected' | 'error';
|
|
453
|
+
/** Mobile companion app status */
|
|
454
|
+
mobile: {
|
|
455
|
+
/** Whether any device is connected */
|
|
456
|
+
connected: boolean;
|
|
457
|
+
/** Number of active devices */
|
|
458
|
+
active_devices: number;
|
|
459
|
+
};
|
|
460
|
+
/** Number of active payment gateways */
|
|
461
|
+
gateways: number;
|
|
462
|
+
/** Total customer count */
|
|
463
|
+
customers: number;
|
|
464
|
+
/** Server timestamp (ISO format) */
|
|
465
|
+
time: string;
|
|
466
|
+
}
|
|
467
|
+
/**
|
|
468
|
+
* HTTP methods supported by the API.
|
|
469
|
+
*/
|
|
470
|
+
type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
|
|
471
|
+
/**
|
|
472
|
+
* Internal request configuration.
|
|
473
|
+
*/
|
|
474
|
+
interface RequestConfig {
|
|
475
|
+
/** HTTP method */
|
|
476
|
+
method: HttpMethod;
|
|
477
|
+
/** Request path (relative to base URL) */
|
|
478
|
+
path: string;
|
|
479
|
+
/** Query parameters */
|
|
480
|
+
query?: Record<string, string | number | boolean | undefined>;
|
|
481
|
+
/** Request body (for POST/PUT/PATCH) */
|
|
482
|
+
body?: unknown;
|
|
483
|
+
/** Request options */
|
|
484
|
+
options?: RequestOptions;
|
|
485
|
+
}
|
|
486
|
+
/**
|
|
487
|
+
* Paginated list response.
|
|
488
|
+
*/
|
|
489
|
+
interface PaginatedList<T> {
|
|
490
|
+
/** Array of items */
|
|
491
|
+
items: T[];
|
|
492
|
+
/** Pagination metadata */
|
|
493
|
+
meta: PaginationMeta;
|
|
494
|
+
}
|
|
495
|
+
|
|
496
|
+
/**
|
|
497
|
+
* OwnPay Node.js SDK - Error Classes
|
|
498
|
+
*
|
|
499
|
+
* Comprehensive error hierarchy for the OwnPay API.
|
|
500
|
+
* Each error class provides specific context for different failure scenarios.
|
|
501
|
+
*/
|
|
502
|
+
|
|
503
|
+
/**
|
|
504
|
+
* Base error class for all OwnPay SDK errors.
|
|
505
|
+
* Provides common properties and methods for error handling.
|
|
506
|
+
*/
|
|
507
|
+
declare class OwnPayError extends Error {
|
|
508
|
+
/** The error type identifier */
|
|
509
|
+
readonly type: string;
|
|
510
|
+
/** HTTP status code (if applicable) */
|
|
511
|
+
readonly status: number | undefined;
|
|
512
|
+
/** Unique request identifier for debugging */
|
|
513
|
+
readonly requestId: string | undefined;
|
|
514
|
+
/** Raw error response from the API */
|
|
515
|
+
readonly rawResponse: unknown;
|
|
516
|
+
constructor(message: string, type: string, status?: number, requestId?: string, rawResponse?: unknown);
|
|
517
|
+
/**
|
|
518
|
+
* Returns a JSON representation of the error for logging.
|
|
519
|
+
*/
|
|
520
|
+
toJSON(): Record<string, unknown>;
|
|
521
|
+
}
|
|
522
|
+
/**
|
|
523
|
+
* Thrown when API authentication fails (401).
|
|
524
|
+
* Indicates an invalid, missing, or revoked API key.
|
|
525
|
+
*/
|
|
526
|
+
declare class AuthenticationError extends OwnPayError {
|
|
527
|
+
constructor(message: string, requestId?: string, rawResponse?: unknown);
|
|
528
|
+
}
|
|
529
|
+
/**
|
|
530
|
+
* Thrown when the API key lacks required permissions (403).
|
|
531
|
+
* Indicates insufficient scope (e.g., read-only key attempting a write operation).
|
|
532
|
+
*/
|
|
533
|
+
declare class PermissionError extends OwnPayError {
|
|
534
|
+
constructor(message: string, requestId?: string, rawResponse?: unknown);
|
|
535
|
+
}
|
|
536
|
+
/**
|
|
537
|
+
* Thrown when a requested resource is not found (404).
|
|
538
|
+
*/
|
|
539
|
+
declare class NotFoundError extends OwnPayError {
|
|
540
|
+
/** The resource type that was not found */
|
|
541
|
+
readonly resource: string | undefined;
|
|
542
|
+
/** The identifier that was searched for */
|
|
543
|
+
readonly resourceId: string | undefined;
|
|
544
|
+
constructor(message: string, resource?: string, resourceId?: string, requestId?: string, rawResponse?: unknown);
|
|
545
|
+
}
|
|
546
|
+
/**
|
|
547
|
+
* Thrown when request validation fails (422).
|
|
548
|
+
* Contains structured error details for each invalid field.
|
|
549
|
+
*/
|
|
550
|
+
declare class ValidationError extends OwnPayError {
|
|
551
|
+
/** Array of individual validation errors */
|
|
552
|
+
readonly errors: ApiErrorDetail[];
|
|
553
|
+
constructor(message: string, errors: ApiErrorDetail[], requestId?: string, rawResponse?: unknown);
|
|
554
|
+
/**
|
|
555
|
+
* Returns errors grouped by field name.
|
|
556
|
+
*/
|
|
557
|
+
getFieldErrors(): Record<string, string[]>;
|
|
558
|
+
/**
|
|
559
|
+
* Returns the first error message for a specific field.
|
|
560
|
+
*/
|
|
561
|
+
getFirstFieldError(field: string): string | undefined;
|
|
562
|
+
}
|
|
563
|
+
/**
|
|
564
|
+
* Thrown when the API rate limit is exceeded (429).
|
|
565
|
+
* Includes retry-after information when available.
|
|
566
|
+
*/
|
|
567
|
+
declare class RateLimitError extends OwnPayError {
|
|
568
|
+
/** Seconds to wait before retrying */
|
|
569
|
+
readonly retryAfter: number | undefined;
|
|
570
|
+
constructor(message: string, retryAfter?: number, requestId?: string, rawResponse?: unknown);
|
|
571
|
+
}
|
|
572
|
+
/**
|
|
573
|
+
* Thrown when an idempotency key conflict occurs (409).
|
|
574
|
+
* Indicates a request with the same key is still processing.
|
|
575
|
+
*/
|
|
576
|
+
declare class IdempotencyError extends OwnPayError {
|
|
577
|
+
constructor(message: string, requestId?: string, rawResponse?: unknown);
|
|
578
|
+
}
|
|
579
|
+
/**
|
|
580
|
+
* Thrown when the API returns a server error (500, 502, 503, 504).
|
|
581
|
+
*/
|
|
582
|
+
declare class ApiError extends OwnPayError {
|
|
583
|
+
/** The error code from the API */
|
|
584
|
+
readonly errorCode: string | undefined;
|
|
585
|
+
constructor(message: string, errorCode?: string, status?: number, requestId?: string, rawResponse?: unknown);
|
|
586
|
+
}
|
|
587
|
+
/**
|
|
588
|
+
* Thrown when a network error occurs (connection failure, timeout, etc.).
|
|
589
|
+
*/
|
|
590
|
+
declare class NetworkError extends OwnPayError {
|
|
591
|
+
/** The underlying cause */
|
|
592
|
+
readonly cause: Error | undefined;
|
|
593
|
+
constructor(message: string, cause?: Error);
|
|
594
|
+
}
|
|
595
|
+
/**
|
|
596
|
+
* Thrown when a request is aborted (via AbortSignal or timeout).
|
|
597
|
+
*/
|
|
598
|
+
declare class AbortError extends OwnPayError {
|
|
599
|
+
constructor(message?: string);
|
|
600
|
+
}
|
|
601
|
+
/**
|
|
602
|
+
* Thrown when webhook signature verification fails.
|
|
603
|
+
*/
|
|
604
|
+
declare class WebhookVerificationError extends OwnPayError {
|
|
605
|
+
constructor(message: string);
|
|
606
|
+
}
|
|
607
|
+
|
|
608
|
+
/**
|
|
609
|
+
* OwnPay Node.js SDK - Webhook Signature Verification
|
|
610
|
+
*
|
|
611
|
+
* Standalone utility for verifying OwnPay webhook signatures.
|
|
612
|
+
* Uses HMAC-SHA256 for cryptographic verification.
|
|
613
|
+
*
|
|
614
|
+
* @module ownpay/webhooks
|
|
615
|
+
*/
|
|
616
|
+
|
|
617
|
+
/**
|
|
618
|
+
* Verifies an OwnPay webhook signature.
|
|
619
|
+
*
|
|
620
|
+
* This function verifies that the webhook payload was sent by OwnPay
|
|
621
|
+
* and has not been tampered with. It supports optional timestamp
|
|
622
|
+
* validation for legacy delivery diagnostics. The timestamp is outside the signature.
|
|
623
|
+
*
|
|
624
|
+
* @param params - Verification parameters
|
|
625
|
+
* @returns true if the signature is valid
|
|
626
|
+
* @throws {WebhookVerificationError} If the signature is invalid
|
|
627
|
+
*
|
|
628
|
+
* @example
|
|
629
|
+
* ```typescript
|
|
630
|
+
* import { verifyWebhookSignature } from 'pycer-sdk/webhooks';
|
|
631
|
+
*
|
|
632
|
+
* // In your webhook handler
|
|
633
|
+
* app.post('/webhook', (req, res) => {
|
|
634
|
+
* try {
|
|
635
|
+
* verifyWebhookSignature({
|
|
636
|
+
* payload: req.body,
|
|
637
|
+
* signature: req.headers['x-signature'],
|
|
638
|
+
* secret: process.env.OWNPAY_WEBHOOK_SECRET,
|
|
639
|
+
* timestamp: req.headers['x-timestamp'],
|
|
640
|
+
* });
|
|
641
|
+
*
|
|
642
|
+
* // Signature is valid, process the webhook
|
|
643
|
+
* const event = JSON.parse(req.body);
|
|
644
|
+
* handleWebhookEvent(event);
|
|
645
|
+
*
|
|
646
|
+
* res.status(200).json({ received: true });
|
|
647
|
+
* } catch (error) {
|
|
648
|
+
* res.status(400).json({ error: 'Invalid signature' });
|
|
649
|
+
* }
|
|
650
|
+
* });
|
|
651
|
+
* ```
|
|
652
|
+
*/
|
|
653
|
+
declare function verifyWebhookSignature(params: WebhookVerificationParams): boolean;
|
|
654
|
+
/**
|
|
655
|
+
* Generates an HMAC-SHA256 signature for a payload.
|
|
656
|
+
*
|
|
657
|
+
* @param payload - The payload string to sign
|
|
658
|
+
* @param secret - The webhook secret key
|
|
659
|
+
* @returns Hex-encoded signature
|
|
660
|
+
*
|
|
661
|
+
* @example
|
|
662
|
+
* ```typescript
|
|
663
|
+
* import { generateSignature } from 'pycer-sdk/webhooks';
|
|
664
|
+
*
|
|
665
|
+
* const signature = generateSignature('{"event":"payment.completed"}', 'whsec_...');
|
|
666
|
+
* ```
|
|
667
|
+
*/
|
|
668
|
+
declare function generateSignature(payload: string, secret: string): string;
|
|
669
|
+
/**
|
|
670
|
+
* Parses a webhook payload from a raw request body.
|
|
671
|
+
*
|
|
672
|
+
* @param body - Raw request body (string or Buffer)
|
|
673
|
+
* @returns Parsed webhook payload
|
|
674
|
+
* @throws {WebhookVerificationError} If the payload is invalid JSON
|
|
675
|
+
*
|
|
676
|
+
* @example
|
|
677
|
+
* ```typescript
|
|
678
|
+
* import { parseWebhookPayload } from 'pycer-sdk/webhooks';
|
|
679
|
+
*
|
|
680
|
+
* const payload = parseWebhookPayload(req.body);
|
|
681
|
+
* console.log(payload.event); // 'payment.completed'
|
|
682
|
+
* ```
|
|
683
|
+
*/
|
|
684
|
+
declare function parseWebhookPayload<T = Record<string, unknown>>(body: string | Buffer): T;
|
|
685
|
+
|
|
686
|
+
export { type ApiKey as A, WebhookVerificationError as B, type CreateRefundParams as C, type WebhookVerificationParams as D, generateSignature as E, parseWebhookPayload as F, type GenerateApiKeyParams as G, type HealthStatus as H, IdempotencyError as I, verifyWebhookSignature as J, type ListTransactionsParams as L, NetworkError as N, type OwnPayConfig as O, type PaginatedList as P, type RequestConfig as R, type Transaction as T, ValidationError as V, type WebhookTestResult as W, type RequestOptions as a, type Refund as b, type ListRefundsParams as c, type CreateCustomerParams as d, type Customer as e, type ListCustomersParams as f, type GeneratedApiKey as g, type WebhookDelivery as h, type ApiResponse as i, AbortError as j, ApiError as k, type ApiErrorDetail as l, type ApiErrorResponse as m, type ApiKeyScope as n, AuthenticationError as o, type CreatePaymentParams as p, type CustomerSummary as q, NotFoundError as r, OwnPayError as s, type PaginationMeta as t, type Payment as u, type PaymentIntent as v, type PaymentStatus as w, PermissionError as x, RateLimitError as y, type WebhookPayload as z };
|