nodela-sdk 1.0.1
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 +654 -0
- package/dist/client.d.ts +17 -0
- package/dist/client.d.ts.map +1 -0
- package/dist/client.js +74 -0
- package/dist/client.js.map +1 -0
- package/dist/config.d.ts +22 -0
- package/dist/config.d.ts.map +1 -0
- package/dist/config.js +51 -0
- package/dist/config.js.map +1 -0
- package/dist/errors/api-error.d.ts +16 -0
- package/dist/errors/api-error.d.ts.map +1 -0
- package/dist/errors/api-error.js +41 -0
- package/dist/errors/api-error.js.map +1 -0
- package/dist/errors/base.d.ts +7 -0
- package/dist/errors/base.d.ts.map +1 -0
- package/dist/errors/base.js +15 -0
- package/dist/errors/base.js.map +1 -0
- package/dist/errors/index.d.ts +3 -0
- package/dist/errors/index.d.ts.map +1 -0
- package/dist/errors/index.js +19 -0
- package/dist/errors/index.js.map +1 -0
- package/dist/index.d.ts +14 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +36 -0
- package/dist/index.js.map +1 -0
- package/dist/resources/Invoices.d.ts +86 -0
- package/dist/resources/Invoices.d.ts.map +1 -0
- package/dist/resources/Invoices.js +86 -0
- package/dist/resources/Invoices.js.map +1 -0
- package/dist/resources/Transactions.d.ts +58 -0
- package/dist/resources/Transactions.d.ts.map +1 -0
- package/dist/resources/Transactions.js +14 -0
- package/dist/resources/Transactions.js.map +1 -0
- package/dist/resources/base.d.ts +9 -0
- package/dist/resources/base.d.ts.map +1 -0
- package/dist/resources/base.js +23 -0
- package/dist/resources/base.js.map +1 -0
- package/package.json +73 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Devkrea8 Technologies
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,654 @@
|
|
|
1
|
+
# Nodela JavaScript SDK
|
|
2
|
+
|
|
3
|
+
[](https://github.com/Devkrea8-Technologies/nodela-js-sdk/actions/workflows/ci.yml)
|
|
4
|
+
[](https://www.npmjs.com/package/nodela-sdk)
|
|
5
|
+
[](https://opensource.org/licenses/MIT)
|
|
6
|
+
[](https://nodejs.org/)
|
|
7
|
+
[](https://www.typescriptlang.org/)
|
|
8
|
+
|
|
9
|
+
The official JavaScript/TypeScript SDK for the [Nodela](https://nodela.com) stablecoin payments API. Accept crypto payments globally with support for 60+ fiat currencies, automatic currency conversion, and seamless checkout experiences.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Table of Contents
|
|
14
|
+
|
|
15
|
+
- [Features](#features)
|
|
16
|
+
- [Requirements](#requirements)
|
|
17
|
+
- [Installation](#installation)
|
|
18
|
+
- [Quick Start](#quick-start)
|
|
19
|
+
- [Configuration](#configuration)
|
|
20
|
+
- [Usage](#usage)
|
|
21
|
+
- [Invoices](#invoices)
|
|
22
|
+
- [Create an Invoice](#create-an-invoice)
|
|
23
|
+
- [Create an Invoice with Full Options](#create-an-invoice-with-full-options)
|
|
24
|
+
- [Verify an Invoice](#verify-an-invoice)
|
|
25
|
+
- [Transactions](#transactions)
|
|
26
|
+
- [List Transactions](#list-transactions)
|
|
27
|
+
- [Paginated Transactions](#paginated-transactions)
|
|
28
|
+
- [Error Handling](#error-handling)
|
|
29
|
+
- [Error Types](#error-types)
|
|
30
|
+
- [Error Handling Example](#error-handling-example)
|
|
31
|
+
- [Supported Currencies](#supported-currencies)
|
|
32
|
+
- [TypeScript Support](#typescript-support)
|
|
33
|
+
- [API Reference](#api-reference)
|
|
34
|
+
- [Nodela Class](#nodela-class)
|
|
35
|
+
- [nodela.invoices](#nodelainvoices)
|
|
36
|
+
- [nodela.transactions](#nodelatransactions)
|
|
37
|
+
- [Testing](#testing)
|
|
38
|
+
- [Contributing](#contributing)
|
|
39
|
+
- [License](#license)
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## Features
|
|
44
|
+
|
|
45
|
+
- **Invoice Management** -- Create payment invoices and verify their status with a simple API
|
|
46
|
+
- **Transaction Tracking** -- List and paginate through all your transactions
|
|
47
|
+
- **60+ Currencies** -- Accept payments denominated in fiat currencies from every continent
|
|
48
|
+
- **Automatic Conversion** -- Prices in local currency are automatically converted to stablecoin equivalents
|
|
49
|
+
- **Sandbox & Production** -- Switch between environments with a single config option
|
|
50
|
+
- **Full TypeScript Support** -- Strict types, interfaces, and autocompletion out of the box
|
|
51
|
+
- **Custom Error Hierarchy** -- Structured error types for authentication, rate limiting, validation, and API errors
|
|
52
|
+
- **Rate Limit Handling** -- Automatic extraction of `retry-after` headers on 429 responses
|
|
53
|
+
- **Lightweight** -- Only one runtime dependency (`axios`)
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## Requirements
|
|
58
|
+
|
|
59
|
+
- **Node.js** >= 14.0.0
|
|
60
|
+
- A Nodela API key (obtain one from the [Nodela Dashboard](https://nodela.com))
|
|
61
|
+
|
|
62
|
+
API keys follow the format:
|
|
63
|
+
| Prefix | Environment |
|
|
64
|
+
|------------|-------------|
|
|
65
|
+
| `nk_test_` | Sandbox |
|
|
66
|
+
| `nk_live_` | Production |
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## Installation
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
npm install nodela-sdk
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Or with Yarn:
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
yarn add nodela-sdk
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Or with pnpm:
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
pnpm add nodela-sdk
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## Quick Start
|
|
91
|
+
|
|
92
|
+
```typescript
|
|
93
|
+
import { Nodela } from 'nodela-sdk';
|
|
94
|
+
|
|
95
|
+
const nodela = new Nodela('nk_test_your_api_key');
|
|
96
|
+
|
|
97
|
+
// Create a payment invoice
|
|
98
|
+
const invoice = await nodela.invoices.create({
|
|
99
|
+
amount: 25.00,
|
|
100
|
+
currency: 'USD',
|
|
101
|
+
});
|
|
102
|
+
|
|
103
|
+
console.log(invoice.data?.checkout_url);
|
|
104
|
+
// => "https://checkout.nodela.com/inv_abc123..."
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## Configuration
|
|
110
|
+
|
|
111
|
+
The `Nodela` constructor accepts an API key and an optional configuration object:
|
|
112
|
+
|
|
113
|
+
```typescript
|
|
114
|
+
import { Nodela } from 'nodela-sdk';
|
|
115
|
+
|
|
116
|
+
const nodela = new Nodela('nk_live_your_api_key', {
|
|
117
|
+
timeout: 10000, // Request timeout in ms (default: 5000)
|
|
118
|
+
maxRetries: 5, // Max retry attempts (default: 3)
|
|
119
|
+
environment: 'sandbox', // 'production' | 'sandbox' (default: 'production')
|
|
120
|
+
});
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
### Configuration Options
|
|
124
|
+
|
|
125
|
+
| Option | Type | Default | Description |
|
|
126
|
+
|---------------|-------------------------------|----------------|------------------------------------------------|
|
|
127
|
+
| `timeout` | `number` | `5000` | HTTP request timeout in milliseconds. Must be a positive number. |
|
|
128
|
+
| `maxRetries` | `number` | `3` | Maximum number of retry attempts on failure. Must be a non-negative number. |
|
|
129
|
+
| `environment` | `'production' \| 'sandbox'` | `'production'` | API environment to target. Use `'sandbox'` for testing. |
|
|
130
|
+
|
|
131
|
+
### Inspecting Configuration
|
|
132
|
+
|
|
133
|
+
You can retrieve the active configuration at any time:
|
|
134
|
+
|
|
135
|
+
```typescript
|
|
136
|
+
const config = nodela.getConfig();
|
|
137
|
+
console.log(config);
|
|
138
|
+
// {
|
|
139
|
+
// apiKey: 'nk_live_your_api_key',
|
|
140
|
+
// baseURL: 'https://api.nodela.com',
|
|
141
|
+
// timeout: 10000,
|
|
142
|
+
// maxRetries: 5,
|
|
143
|
+
// environment: 'sandbox'
|
|
144
|
+
// }
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
## Usage
|
|
150
|
+
|
|
151
|
+
### Invoices
|
|
152
|
+
|
|
153
|
+
Invoices are the core payment primitive in Nodela. You create an invoice with a fiat amount and currency, and receive a hosted checkout URL where your customer can complete payment in stablecoins.
|
|
154
|
+
|
|
155
|
+
#### Create an Invoice
|
|
156
|
+
|
|
157
|
+
```typescript
|
|
158
|
+
const invoice = await nodela.invoices.create({
|
|
159
|
+
amount: 50.00,
|
|
160
|
+
currency: 'USD',
|
|
161
|
+
});
|
|
162
|
+
|
|
163
|
+
if (invoice.success && invoice.data) {
|
|
164
|
+
console.log('Invoice ID:', invoice.data.invoice_id);
|
|
165
|
+
console.log('Checkout URL:', invoice.data.checkout_url);
|
|
166
|
+
console.log('Stablecoin amount:', invoice.data.amount, invoice.data.currency);
|
|
167
|
+
console.log('Exchange rate:', invoice.data.exchange_rate);
|
|
168
|
+
}
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
#### Create an Invoice with Full Options
|
|
172
|
+
|
|
173
|
+
```typescript
|
|
174
|
+
const invoice = await nodela.invoices.create({
|
|
175
|
+
amount: 150.00,
|
|
176
|
+
currency: 'EUR',
|
|
177
|
+
title: 'Premium Subscription',
|
|
178
|
+
description: '12-month premium plan',
|
|
179
|
+
reference: 'order_2024_00123',
|
|
180
|
+
customer: {
|
|
181
|
+
name: 'Jane Doe',
|
|
182
|
+
email: 'jane@example.com',
|
|
183
|
+
},
|
|
184
|
+
success_url: 'https://yoursite.com/payment/success',
|
|
185
|
+
cancel_url: 'https://yoursite.com/payment/cancel',
|
|
186
|
+
webhook_url: 'https://yoursite.com/api/webhooks/nodela',
|
|
187
|
+
});
|
|
188
|
+
|
|
189
|
+
if (invoice.success && invoice.data) {
|
|
190
|
+
// Redirect your customer to the checkout page
|
|
191
|
+
console.log('Redirect to:', invoice.data.checkout_url);
|
|
192
|
+
}
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
##### `CreateInvoiceParams`
|
|
196
|
+
|
|
197
|
+
| Parameter | Type | Required | Description |
|
|
198
|
+
|---------------|----------|----------|------------------------------------------------------|
|
|
199
|
+
| `amount` | `number` | Yes | The payment amount in the specified fiat currency. |
|
|
200
|
+
| `currency` | `string` | Yes | A supported 3-letter ISO currency code (e.g. `"USD"`, `"NGN"`). Case-insensitive. |
|
|
201
|
+
| `title` | `string` | No | A title displayed on the checkout page. |
|
|
202
|
+
| `description` | `string` | No | A description displayed on the checkout page. |
|
|
203
|
+
| `reference` | `string` | No | Your internal order or reference ID. |
|
|
204
|
+
| `customer` | `object` | No | Customer details. `email` is required if provided; `name` is optional. |
|
|
205
|
+
| `success_url` | `string` | No | URL to redirect the customer to after successful payment. |
|
|
206
|
+
| `cancel_url` | `string` | No | URL to redirect the customer to if they cancel. |
|
|
207
|
+
| `webhook_url` | `string` | No | URL to receive webhook notifications for payment events. |
|
|
208
|
+
|
|
209
|
+
##### `CreateInvoiceResponse`
|
|
210
|
+
|
|
211
|
+
```typescript
|
|
212
|
+
{
|
|
213
|
+
success: boolean;
|
|
214
|
+
data?: {
|
|
215
|
+
id: string;
|
|
216
|
+
invoice_id: string;
|
|
217
|
+
original_amount: string; // Amount in the fiat currency you specified
|
|
218
|
+
original_currency: string; // The fiat currency code
|
|
219
|
+
amount: string; // Converted stablecoin amount
|
|
220
|
+
currency: string; // Stablecoin currency code
|
|
221
|
+
exchange_rate?: string;
|
|
222
|
+
webhook_url?: string;
|
|
223
|
+
customer?: { email: string; name?: string };
|
|
224
|
+
checkout_url: string; // Send your customer here
|
|
225
|
+
status?: string;
|
|
226
|
+
created_at: string;
|
|
227
|
+
};
|
|
228
|
+
error?: { code: string; message: string };
|
|
229
|
+
}
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
#### Verify an Invoice
|
|
233
|
+
|
|
234
|
+
Check the payment status and retrieve payment details for a specific invoice:
|
|
235
|
+
|
|
236
|
+
```typescript
|
|
237
|
+
const result = await nodela.invoices.verify('inv_abc123');
|
|
238
|
+
|
|
239
|
+
if (result.success && result.data) {
|
|
240
|
+
console.log('Status:', result.data.status);
|
|
241
|
+
console.log('Paid:', result.data.paid);
|
|
242
|
+
|
|
243
|
+
if (result.data.payment) {
|
|
244
|
+
console.log('Network:', result.data.payment.network);
|
|
245
|
+
console.log('Token:', result.data.payment.token);
|
|
246
|
+
console.log('Amount:', result.data.payment.amount);
|
|
247
|
+
console.log('Tx Hash:', result.data.payment.tx_hash);
|
|
248
|
+
}
|
|
249
|
+
}
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
##### `VerifyInvoiceResponse`
|
|
253
|
+
|
|
254
|
+
```typescript
|
|
255
|
+
{
|
|
256
|
+
success: boolean;
|
|
257
|
+
data?: {
|
|
258
|
+
id: string;
|
|
259
|
+
invoice_id: string;
|
|
260
|
+
reference?: string;
|
|
261
|
+
original_amount: string;
|
|
262
|
+
original_currency: string;
|
|
263
|
+
amount: number;
|
|
264
|
+
currency: string;
|
|
265
|
+
exchange_rate?: number;
|
|
266
|
+
title?: string;
|
|
267
|
+
description?: string;
|
|
268
|
+
status: string;
|
|
269
|
+
paid: boolean;
|
|
270
|
+
customer?: { email: string; name?: string };
|
|
271
|
+
created_at: string;
|
|
272
|
+
payment?: {
|
|
273
|
+
id: string;
|
|
274
|
+
network: string;
|
|
275
|
+
token: string;
|
|
276
|
+
address: string;
|
|
277
|
+
amount: number;
|
|
278
|
+
status: string;
|
|
279
|
+
tx_hash: string[];
|
|
280
|
+
transaction_type: string;
|
|
281
|
+
payer_email: string;
|
|
282
|
+
created_at: string;
|
|
283
|
+
};
|
|
284
|
+
};
|
|
285
|
+
error?: { code: string; message: string };
|
|
286
|
+
}
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
---
|
|
290
|
+
|
|
291
|
+
### Transactions
|
|
292
|
+
|
|
293
|
+
Retrieve a paginated list of all transactions associated with your account.
|
|
294
|
+
|
|
295
|
+
#### List Transactions
|
|
296
|
+
|
|
297
|
+
```typescript
|
|
298
|
+
const response = await nodela.transactions.list();
|
|
299
|
+
|
|
300
|
+
if (response.success) {
|
|
301
|
+
for (const tx of response.data.transactions) {
|
|
302
|
+
console.log(`${tx.invoice_id} - ${tx.original_amount} ${tx.original_currency} - ${tx.status}`);
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
#### Paginated Transactions
|
|
308
|
+
|
|
309
|
+
```typescript
|
|
310
|
+
const response = await nodela.transactions.list({
|
|
311
|
+
page: 2,
|
|
312
|
+
limit: 25,
|
|
313
|
+
});
|
|
314
|
+
|
|
315
|
+
if (response.success) {
|
|
316
|
+
const { transactions, pagination } = response.data;
|
|
317
|
+
|
|
318
|
+
console.log(`Page ${pagination.page} of ${pagination.total_pages}`);
|
|
319
|
+
console.log(`Showing ${transactions.length} of ${pagination.total} total transactions`);
|
|
320
|
+
console.log(`Has more pages: ${pagination.has_more}`);
|
|
321
|
+
|
|
322
|
+
for (const tx of transactions) {
|
|
323
|
+
console.log(`[${tx.status}] ${tx.reference} -- ${tx.amount} ${tx.currency}`);
|
|
324
|
+
|
|
325
|
+
if (tx.payment) {
|
|
326
|
+
console.log(` Network: ${tx.payment.network}`);
|
|
327
|
+
console.log(` Token: ${tx.payment.token}`);
|
|
328
|
+
console.log(` Tx Hash: ${tx.payment.tx_hash.join(', ')}`);
|
|
329
|
+
}
|
|
330
|
+
}
|
|
331
|
+
}
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
##### `ListTransactionsParams`
|
|
335
|
+
|
|
336
|
+
| Parameter | Type | Required | Description |
|
|
337
|
+
|-----------|----------|----------|----------------------------------------------|
|
|
338
|
+
| `page` | `number` | No | The page number to retrieve. |
|
|
339
|
+
| `limit` | `number` | No | Number of transactions per page. |
|
|
340
|
+
|
|
341
|
+
##### `ListTransactionsResponse`
|
|
342
|
+
|
|
343
|
+
```typescript
|
|
344
|
+
{
|
|
345
|
+
success: boolean;
|
|
346
|
+
data: {
|
|
347
|
+
transactions: Transaction[];
|
|
348
|
+
pagination: {
|
|
349
|
+
page: number;
|
|
350
|
+
limit: number;
|
|
351
|
+
total: number;
|
|
352
|
+
total_pages: number;
|
|
353
|
+
has_more: boolean;
|
|
354
|
+
};
|
|
355
|
+
};
|
|
356
|
+
}
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
##### `Transaction`
|
|
360
|
+
|
|
361
|
+
```typescript
|
|
362
|
+
{
|
|
363
|
+
id: string;
|
|
364
|
+
invoice_id: string;
|
|
365
|
+
reference: string;
|
|
366
|
+
original_amount: number;
|
|
367
|
+
original_currency: string;
|
|
368
|
+
amount: number;
|
|
369
|
+
currency: string;
|
|
370
|
+
exchange_rate: number;
|
|
371
|
+
title: string;
|
|
372
|
+
description: string;
|
|
373
|
+
status: string;
|
|
374
|
+
paid: boolean;
|
|
375
|
+
customer: { email: string; name: string };
|
|
376
|
+
created_at: string;
|
|
377
|
+
payment: {
|
|
378
|
+
id: string;
|
|
379
|
+
network: string;
|
|
380
|
+
token: string;
|
|
381
|
+
address: string;
|
|
382
|
+
amount: number;
|
|
383
|
+
status: string;
|
|
384
|
+
tx_hash: string[];
|
|
385
|
+
transaction_type: string;
|
|
386
|
+
payer_email: string;
|
|
387
|
+
created_at: string;
|
|
388
|
+
};
|
|
389
|
+
}
|
|
390
|
+
```
|
|
391
|
+
|
|
392
|
+
---
|
|
393
|
+
|
|
394
|
+
## Error Handling
|
|
395
|
+
|
|
396
|
+
The SDK provides a structured error hierarchy so you can handle different failure modes precisely.
|
|
397
|
+
|
|
398
|
+
### Error Types
|
|
399
|
+
|
|
400
|
+
All errors extend `SDKError`, which itself extends the native `Error` class.
|
|
401
|
+
|
|
402
|
+
| Error Class | Code | Status | When It Occurs |
|
|
403
|
+
|------------------------|--------------------------|--------|------------------------------------------------|
|
|
404
|
+
| `SDKError` | *(varies)* | -- | Base class for all SDK errors. |
|
|
405
|
+
| `APIError` | `API_ERROR` | varies | General API errors (4xx/5xx responses). |
|
|
406
|
+
| `AuthenticationError` | `AUTHENTICATION_ERROR` | 401 | Invalid or missing API key. |
|
|
407
|
+
| `RateLimitError` | `RATE_LIMIT_ERROR` | 429 | Too many requests. Has optional `retryAfter`. |
|
|
408
|
+
| `ValidationError` | `VALIDATION_ERROR` | -- | Client-side validation failures (e.g. invalid currency). |
|
|
409
|
+
|
|
410
|
+
All error objects include:
|
|
411
|
+
|
|
412
|
+
```typescript
|
|
413
|
+
{
|
|
414
|
+
message: string; // Human-readable error message
|
|
415
|
+
code: string; // Machine-readable error code
|
|
416
|
+
statusCode?: number; // HTTP status code (if applicable)
|
|
417
|
+
details?: unknown; // Additional error context
|
|
418
|
+
}
|
|
419
|
+
```
|
|
420
|
+
|
|
421
|
+
### Error Handling Example
|
|
422
|
+
|
|
423
|
+
```typescript
|
|
424
|
+
import { Nodela, AuthenticationError, RateLimitError, APIError, SDKError } from 'nodela-sdk';
|
|
425
|
+
|
|
426
|
+
const nodela = new Nodela('nk_test_your_api_key');
|
|
427
|
+
|
|
428
|
+
try {
|
|
429
|
+
const invoice = await nodela.invoices.create({
|
|
430
|
+
amount: 100,
|
|
431
|
+
currency: 'USD',
|
|
432
|
+
});
|
|
433
|
+
} catch (error) {
|
|
434
|
+
if (error instanceof AuthenticationError) {
|
|
435
|
+
// Invalid API key -- check your credentials
|
|
436
|
+
console.error('Auth failed:', error.message);
|
|
437
|
+
|
|
438
|
+
} else if (error instanceof RateLimitError) {
|
|
439
|
+
// Too many requests -- back off and retry
|
|
440
|
+
console.error('Rate limited. Retry after:', error.retryAfter, 'seconds');
|
|
441
|
+
|
|
442
|
+
} else if (error instanceof APIError) {
|
|
443
|
+
// Server returned an error response
|
|
444
|
+
console.error(`API error (${error.statusCode}):`, error.message);
|
|
445
|
+
console.error('Details:', error.details);
|
|
446
|
+
|
|
447
|
+
} else if (error instanceof SDKError) {
|
|
448
|
+
// Catch-all for any other SDK error
|
|
449
|
+
console.error(`SDK error [${error.code}]:`, error.message);
|
|
450
|
+
|
|
451
|
+
} else {
|
|
452
|
+
// Unexpected non-SDK error
|
|
453
|
+
console.error('Unexpected error:', error);
|
|
454
|
+
}
|
|
455
|
+
}
|
|
456
|
+
```
|
|
457
|
+
|
|
458
|
+
#### Currency Validation Errors
|
|
459
|
+
|
|
460
|
+
The SDK validates currency codes client-side before making any API request:
|
|
461
|
+
|
|
462
|
+
```typescript
|
|
463
|
+
try {
|
|
464
|
+
await nodela.invoices.create({ amount: 100, currency: 'XYZ' });
|
|
465
|
+
} catch (error) {
|
|
466
|
+
// Error: Unsupported currency: "XYZ". Supported currencies: USD, CAD, MXN, ...
|
|
467
|
+
console.error(error.message);
|
|
468
|
+
}
|
|
469
|
+
```
|
|
470
|
+
|
|
471
|
+
Currency codes are case-insensitive -- `"usd"`, `"Usd"`, and `"USD"` are all accepted and automatically normalized to uppercase.
|
|
472
|
+
|
|
473
|
+
---
|
|
474
|
+
|
|
475
|
+
## Supported Currencies
|
|
476
|
+
|
|
477
|
+
The SDK supports **60+ fiat currencies** across every major region:
|
|
478
|
+
|
|
479
|
+
| Region | Currencies |
|
|
480
|
+
|----------------|---------------------------------------------------------------------------|
|
|
481
|
+
| **Americas** | `USD`, `CAD`, `MXN`, `BRL`, `ARS`, `CLP`, `COP`, `PEN`, `JMD`, `TTD` |
|
|
482
|
+
| **Europe** | `EUR`, `GBP`, `CHF`, `SEK`, `NOK`, `DKK`, `PLN`, `CZK`, `HUF`, `RON`, `BGN`, `HRK`, `ISK`, `TRY`, `RUB`, `UAH` |
|
|
483
|
+
| **Africa** | `NGN`, `ZAR`, `KES`, `GHS`, `EGP`, `MAD`, `TZS`, `UGX`, `XOF`, `XAF`, `ETB` |
|
|
484
|
+
| **Asia** | `JPY`, `CNY`, `INR`, `KRW`, `IDR`, `MYR`, `THB`, `PHP`, `VND`, `SGD`, `HKD`, `TWD`, `BDT`, `PKR`, `LKR` |
|
|
485
|
+
| **Middle East** | `AED`, `SAR`, `QAR`, `KWD`, `BHD`, `OMR`, `ILS`, `JOD` |
|
|
486
|
+
| **Oceania** | `AUD`, `NZD`, `FJD` |
|
|
487
|
+
|
|
488
|
+
You can also access the full list programmatically:
|
|
489
|
+
|
|
490
|
+
```typescript
|
|
491
|
+
import { SUPPORTED_CURRENCIES } from 'nodela-sdk/dist/resources/Invoices';
|
|
492
|
+
|
|
493
|
+
console.log(SUPPORTED_CURRENCIES);
|
|
494
|
+
// ["USD", "CAD", "MXN", ...]
|
|
495
|
+
```
|
|
496
|
+
|
|
497
|
+
---
|
|
498
|
+
|
|
499
|
+
## TypeScript Support
|
|
500
|
+
|
|
501
|
+
The SDK is written in TypeScript with strict mode enabled and ships with full type declarations. All interfaces are exported for use in your own code:
|
|
502
|
+
|
|
503
|
+
```typescript
|
|
504
|
+
import { Nodela } from 'nodela-sdk';
|
|
505
|
+
import type {
|
|
506
|
+
CreateInvoiceParams,
|
|
507
|
+
CreateInvoiceResponse,
|
|
508
|
+
VerifyInvoiceResponse,
|
|
509
|
+
ListTransactionsParams,
|
|
510
|
+
ListTransactionsResponse,
|
|
511
|
+
Transaction,
|
|
512
|
+
Pagination,
|
|
513
|
+
SupportedCurrency,
|
|
514
|
+
} from 'nodela-sdk/dist/resources/Invoices';
|
|
515
|
+
```
|
|
516
|
+
|
|
517
|
+
Error types are exported directly from the package root:
|
|
518
|
+
|
|
519
|
+
```typescript
|
|
520
|
+
import {
|
|
521
|
+
SDKError,
|
|
522
|
+
APIError,
|
|
523
|
+
AuthenticationError,
|
|
524
|
+
RateLimitError,
|
|
525
|
+
ValidationError,
|
|
526
|
+
} from 'nodela-sdk';
|
|
527
|
+
```
|
|
528
|
+
|
|
529
|
+
---
|
|
530
|
+
|
|
531
|
+
## API Reference
|
|
532
|
+
|
|
533
|
+
### `Nodela` Class
|
|
534
|
+
|
|
535
|
+
The main entry point for the SDK.
|
|
536
|
+
|
|
537
|
+
```typescript
|
|
538
|
+
new Nodela(apiKey: string, options?: SDKConfigOptions)
|
|
539
|
+
```
|
|
540
|
+
|
|
541
|
+
| Property | Type | Description |
|
|
542
|
+
|----------------|----------------|-----------------------------------------------|
|
|
543
|
+
| `invoices` | `Invoices` | Invoice resource for creating and verifying invoices. |
|
|
544
|
+
| `transactions` | `Transactions` | Transaction resource for listing transactions. |
|
|
545
|
+
|
|
546
|
+
| Method | Returns | Description |
|
|
547
|
+
|----------------|------------------------------|-----------------------------------------------|
|
|
548
|
+
| `getConfig()` | `Required<SDKConfig>` | Returns a copy of the current SDK configuration. |
|
|
549
|
+
|
|
550
|
+
---
|
|
551
|
+
|
|
552
|
+
### `nodela.invoices`
|
|
553
|
+
|
|
554
|
+
| Method | Parameters | Returns | Description |
|
|
555
|
+
|-----------|--------------------------------|---------------------------------|------------------------------------------------------|
|
|
556
|
+
| `create` | `params: CreateInvoiceParams` | `Promise<CreateInvoiceResponse>` | Creates a new payment invoice and returns a checkout URL. |
|
|
557
|
+
| `verify` | `invoiceId: string` | `Promise<VerifyInvoiceResponse>` | Retrieves the payment status and details for an invoice. |
|
|
558
|
+
|
|
559
|
+
---
|
|
560
|
+
|
|
561
|
+
### `nodela.transactions`
|
|
562
|
+
|
|
563
|
+
| Method | Parameters | Returns | Description |
|
|
564
|
+
|--------|--------------------------------------|--------------------------------------|------------------------------------------------------|
|
|
565
|
+
| `list` | `params?: ListTransactionsParams` | `Promise<ListTransactionsResponse>` | Returns a paginated list of transactions. |
|
|
566
|
+
|
|
567
|
+
---
|
|
568
|
+
|
|
569
|
+
## Testing
|
|
570
|
+
|
|
571
|
+
The SDK includes comprehensive unit and integration tests with an enforced **80% coverage threshold**.
|
|
572
|
+
|
|
573
|
+
```bash
|
|
574
|
+
# Run all tests
|
|
575
|
+
npm test
|
|
576
|
+
|
|
577
|
+
# Run tests in watch mode
|
|
578
|
+
npm run test:watch
|
|
579
|
+
|
|
580
|
+
# Run with coverage report
|
|
581
|
+
npm run test:coverage
|
|
582
|
+
|
|
583
|
+
# Run only unit tests
|
|
584
|
+
npm run test:unit
|
|
585
|
+
|
|
586
|
+
# Run only integration tests
|
|
587
|
+
npm run test:integration
|
|
588
|
+
```
|
|
589
|
+
|
|
590
|
+
### Linting & Formatting
|
|
591
|
+
|
|
592
|
+
```bash
|
|
593
|
+
# Lint source code
|
|
594
|
+
npm run lint
|
|
595
|
+
|
|
596
|
+
# Lint and auto-fix
|
|
597
|
+
npm run lint:fix
|
|
598
|
+
|
|
599
|
+
# Check formatting
|
|
600
|
+
npm run format:check
|
|
601
|
+
|
|
602
|
+
# Format source code
|
|
603
|
+
npm run format
|
|
604
|
+
```
|
|
605
|
+
|
|
606
|
+
---
|
|
607
|
+
|
|
608
|
+
## Contributing
|
|
609
|
+
|
|
610
|
+
Contributions are welcome! Please follow these steps:
|
|
611
|
+
|
|
612
|
+
1. Fork the repository
|
|
613
|
+
2. Create a feature branch (`git checkout -b feature/my-feature`)
|
|
614
|
+
3. Make your changes
|
|
615
|
+
4. Run the full test suite (`npm test`)
|
|
616
|
+
5. Run linting and formatting (`npm run lint && npm run format:check`)
|
|
617
|
+
6. Create a changeset for your changes (`npm run changeset`)
|
|
618
|
+
7. Commit your changes and open a Pull Request
|
|
619
|
+
|
|
620
|
+
### Project Structure
|
|
621
|
+
|
|
622
|
+
```
|
|
623
|
+
nodela-js-sdk/
|
|
624
|
+
├── src/
|
|
625
|
+
│ ├── index.ts # SDK entry point & Nodela class
|
|
626
|
+
│ ├── client.ts # HTTP client (Axios wrapper)
|
|
627
|
+
│ ├── config.ts # Configuration & validation
|
|
628
|
+
│ ├── errors/
|
|
629
|
+
│ │ ├── index.ts # Error re-exports
|
|
630
|
+
│ │ ├── base.ts # SDKError base class
|
|
631
|
+
│ │ └── api-error.ts # APIError, AuthenticationError, etc.
|
|
632
|
+
│ └── resources/
|
|
633
|
+
│ ├── base.ts # BaseResource abstract class
|
|
634
|
+
│ ├── Invoices.ts # Invoice create & verify
|
|
635
|
+
│ └── Transactions.ts # Transaction listing
|
|
636
|
+
├── tests/
|
|
637
|
+
│ ├── unit/ # Unit tests (mirrors src/ structure)
|
|
638
|
+
│ └── integration/ # End-to-end integration tests
|
|
639
|
+
├── .github/workflows/
|
|
640
|
+
│ ├── ci.yml # CI pipeline (lint, format, build, test)
|
|
641
|
+
│ └── publish.yml # Automated npm publishing via changesets
|
|
642
|
+
├── tsconfig.json # TypeScript configuration
|
|
643
|
+
├── jest.config.js # Jest test configuration
|
|
644
|
+
├── .eslintrc.json # ESLint rules
|
|
645
|
+
└── .prettierrc # Prettier formatting rules
|
|
646
|
+
```
|
|
647
|
+
|
|
648
|
+
---
|
|
649
|
+
|
|
650
|
+
## License
|
|
651
|
+
|
|
652
|
+
This project is licensed under the [MIT License](LICENSE).
|
|
653
|
+
|
|
654
|
+
Built by [NodelaPay LTD](mailto:sayhello@nodela.co).
|
package/dist/client.d.ts
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import { AxiosRequestConfig } from 'axios';
|
|
2
|
+
import { Config } from './config';
|
|
3
|
+
export declare class HTTPClient {
|
|
4
|
+
private axiosInstance;
|
|
5
|
+
private config;
|
|
6
|
+
constructor(config: Config);
|
|
7
|
+
private createAxiosInstance;
|
|
8
|
+
private setupInterceptors;
|
|
9
|
+
private handleError;
|
|
10
|
+
request<T>(config: AxiosRequestConfig): Promise<T>;
|
|
11
|
+
get<T>(url: string, config?: AxiosRequestConfig): Promise<T>;
|
|
12
|
+
post<T>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<T>;
|
|
13
|
+
put<T>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<T>;
|
|
14
|
+
patch<T>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<T>;
|
|
15
|
+
delete<T>(url: string, config?: AxiosRequestConfig): Promise<T>;
|
|
16
|
+
}
|
|
17
|
+
//# sourceMappingURL=client.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAc,EAAiB,kBAAkB,EAA6B,MAAM,OAAO,CAAC;AAC5F,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAGlC,qBAAa,UAAU;IACrB,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,MAAM;IAM1B,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,iBAAiB;YAgBX,WAAW;IA2BnB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC;IAKlD,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC;IAI5D,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC;IAI7E,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC;IAI5E,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC;IAI9E,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC;CAGtE"}
|