@mbanq/core-sdk-js 1.0.0-alpha.10
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 +669 -0
- package/dist/chunk-5PEETHWV.mjs +1 -0
- package/dist/chunk-6YLCCDXD.mjs +1 -0
- package/dist/chunk-BDI3SHA2.js +1 -0
- package/dist/chunk-OGW7GTJP.js +1 -0
- package/dist/chunk-RX3BFHHX.mjs +1 -0
- package/dist/chunk-TL2MJ56S.js +1 -0
- package/dist/client/index.d.mts +5 -0
- package/dist/client/index.d.ts +5 -0
- package/dist/client/index.js +1 -0
- package/dist/client/index.mjs +1 -0
- package/dist/commands/index.d.mts +96 -0
- package/dist/commands/index.d.ts +96 -0
- package/dist/commands/index.js +1 -0
- package/dist/commands/index.mjs +1 -0
- package/dist/config.d-CyK6ZM6s.d.mts +53 -0
- package/dist/config.d-CyK6ZM6s.d.ts +53 -0
- package/dist/index-5Sj83ZJ4.d.mts +209 -0
- package/dist/index-CCyptSZo.d.mts +3973 -0
- package/dist/index-DXK5OdKW.d.ts +209 -0
- package/dist/index-Dn5rWIBE.d.ts +3973 -0
- package/dist/index.d.mts +71 -0
- package/dist/index.d.ts +71 -0
- package/dist/index.js +1 -0
- package/dist/index.mjs +1 -0
- package/package.json +93 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Mbanq Cloud Devs
|
|
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,669 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://avatars.githubusercontent.com/u/26124358?s=200&v=4" alt="Mbanq Logo" width="120"/>
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
# Core SDK JS
|
|
6
|
+
|
|
7
|
+

|
|
8
|
+
[](https://www.npmjs.com/package/@mbanq/core-sdk-js)
|
|
9
|
+

|
|
10
|
+
|
|
11
|
+
## Table of Contents
|
|
12
|
+
|
|
13
|
+
- [Introduction](#introduction)
|
|
14
|
+
- [Installation](#installation)
|
|
15
|
+
- [Quick Start](#quick-start)
|
|
16
|
+
- [Setup](#setup)
|
|
17
|
+
- [Axios Instance Logger](#axios-instance-logger)
|
|
18
|
+
- [Middleware](#middleware)
|
|
19
|
+
- [Logging Middleware](#logging-middleware)
|
|
20
|
+
- [Metrics Middleware](#metrics-middleware)
|
|
21
|
+
- [Custom Middleware](#custom-middleware)
|
|
22
|
+
- [API Reference](#api-reference)
|
|
23
|
+
- [Payment Operations](#payment-operations)
|
|
24
|
+
- [Create Payment](#create-payment)
|
|
25
|
+
- [Get Payment](#get-payment)
|
|
26
|
+
- [Update Payment](#update-payment)
|
|
27
|
+
- [List Payments](#list-payments)
|
|
28
|
+
- [Multi-Tenant Support](#multi-tenant-support)
|
|
29
|
+
- [Type Safety & Validation](#type-safety--validation)
|
|
30
|
+
- [Error Handling](#error-handling)
|
|
31
|
+
- [Examples](#examples)
|
|
32
|
+
|
|
33
|
+
## Introduction
|
|
34
|
+
This library provides a comprehensive JavaScript SDK for interacting with the Mbanq payment API. It offers type-safe payment operations with built-in validation, multi-tenant support, and a modern fluent API design.
|
|
35
|
+
## Installation
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
npm install @mbanq/core-sdk-js
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Quick Start
|
|
42
|
+
|
|
43
|
+
```javascript
|
|
44
|
+
import { createClient } from '@mbanq/core-sdk-js';
|
|
45
|
+
|
|
46
|
+
// Initialize the client
|
|
47
|
+
const apiClient = createClient({
|
|
48
|
+
secret: 'your-api-secret',
|
|
49
|
+
signee: 'YOUR-SIGNEE',
|
|
50
|
+
baseUrl: 'https://api.cloud.mbanq.com',
|
|
51
|
+
tenantId: 'your-tenant-id'
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
// Create a payment
|
|
55
|
+
const payment = await apiClient.payment.create({
|
|
56
|
+
amount: 1000,
|
|
57
|
+
currency: 'USD',
|
|
58
|
+
paymentRail: 'ACH',
|
|
59
|
+
paymentType: 'CREDIT',
|
|
60
|
+
debtor: {
|
|
61
|
+
name: 'John Sender',
|
|
62
|
+
identifier: '123456789',
|
|
63
|
+
agent: {
|
|
64
|
+
name: 'First Bank',
|
|
65
|
+
identifier: '021000021'
|
|
66
|
+
}
|
|
67
|
+
},
|
|
68
|
+
creditor: {
|
|
69
|
+
name: 'Jane Receiver',
|
|
70
|
+
identifier: '987654321',
|
|
71
|
+
agent: {
|
|
72
|
+
name: 'Second Bank',
|
|
73
|
+
identifier: '121000248'
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
});
|
|
77
|
+
|
|
78
|
+
// List payments with filtering
|
|
79
|
+
const payments = await apiClient.payment.list()
|
|
80
|
+
.where('status').eq('DRAFT')
|
|
81
|
+
.where('paymentRail').eq('ACH')
|
|
82
|
+
.limit(10)
|
|
83
|
+
.execute();
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## Setup
|
|
87
|
+
|
|
88
|
+
### Authentication Options
|
|
89
|
+
|
|
90
|
+
The SDK supports multiple authentication methods. Choose the one that fits your integration:
|
|
91
|
+
|
|
92
|
+
#### 1. JWT Token Authentication (Recommended)
|
|
93
|
+
Use your API secret and signee for JWT-based authentication:
|
|
94
|
+
|
|
95
|
+
```javascript
|
|
96
|
+
const client = createClient({
|
|
97
|
+
secret: 'your-jwt-secret',
|
|
98
|
+
signee: 'YOUR-SIGNEE',
|
|
99
|
+
baseUrl: 'https://api.cloud.mbanq.com',
|
|
100
|
+
tenantId: 'your-tenant-id'
|
|
101
|
+
});
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
#### 2. Bearer Token Authentication
|
|
105
|
+
If you already have a valid access token:
|
|
106
|
+
|
|
107
|
+
```javascript
|
|
108
|
+
// With "Bearer " prefix (recommended)
|
|
109
|
+
const client = createClient({
|
|
110
|
+
bearerToken: 'Bearer your-access-token',
|
|
111
|
+
baseUrl: 'https://api.cloud.mbanq.com',
|
|
112
|
+
tenantId: 'your-tenant-id'
|
|
113
|
+
});
|
|
114
|
+
|
|
115
|
+
// Without "Bearer " prefix (automatically added)
|
|
116
|
+
const client = createClient({
|
|
117
|
+
bearerToken: 'your-access-token', // "Bearer " will be added automatically
|
|
118
|
+
baseUrl: 'https://api.cloud.mbanq.com',
|
|
119
|
+
tenantId: 'your-tenant-id'
|
|
120
|
+
});
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
#### 3. OAuth Credential Authentication
|
|
124
|
+
For OAuth 2.0 password grant flow:
|
|
125
|
+
|
|
126
|
+
```javascript
|
|
127
|
+
const client = createClient({
|
|
128
|
+
credential: {
|
|
129
|
+
client_id: 'your-client-id',
|
|
130
|
+
client_secret: 'your-client-secret',
|
|
131
|
+
username: 'your-username',
|
|
132
|
+
password: 'your-password',
|
|
133
|
+
grant_type: 'password'
|
|
134
|
+
},
|
|
135
|
+
baseUrl: 'https://api.cloud.mbanq.com',
|
|
136
|
+
tenantId: 'your-tenant-id'
|
|
137
|
+
});
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
#### Authentication Priority
|
|
141
|
+
When multiple authentication methods are provided, the SDK uses them in this order:
|
|
142
|
+
1. **`bearerToken`** - Takes highest priority if provided
|
|
143
|
+
2. **`credential`** - OAuth flow is used if no bearerToken
|
|
144
|
+
3. **`secret` + `signee`** - JWT authentication used as fallback
|
|
145
|
+
|
|
146
|
+
#### Additional Configuration Options
|
|
147
|
+
```javascript
|
|
148
|
+
const client = createClient({
|
|
149
|
+
// Choose one authentication method from above
|
|
150
|
+
secret: 'your-jwt-secret',
|
|
151
|
+
signee: 'YOUR-SIGNEE',
|
|
152
|
+
|
|
153
|
+
// Required configuration
|
|
154
|
+
baseUrl: 'https://api.cloud.mbanq.com',
|
|
155
|
+
tenantId: 'your-tenant-id',
|
|
156
|
+
|
|
157
|
+
// Optional configuration
|
|
158
|
+
traceId: 'custom-trace-id', // Custom request tracing identifier
|
|
159
|
+
axiosConfig: {
|
|
160
|
+
timeout: 30000, // Request timeout in milliseconds (default: 29000)
|
|
161
|
+
keepAlive: true, // HTTP keep-alive for connection reuse
|
|
162
|
+
headers: {
|
|
163
|
+
'Custom-Header': 'custom-value' // Additional HTTP headers
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
});
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
### Security Best Practices
|
|
170
|
+
|
|
171
|
+
#### Credential Management
|
|
172
|
+
- **Never hardcode credentials** in your source code
|
|
173
|
+
- Use environment variables or secure credential management systems
|
|
174
|
+
- Rotate API secrets and tokens regularly
|
|
175
|
+
- Use the minimum required permissions for your integration
|
|
176
|
+
|
|
177
|
+
#### Environment Variables Example
|
|
178
|
+
```javascript
|
|
179
|
+
const client = createClient({
|
|
180
|
+
secret: process.env.MBANQ_API_SECRET,
|
|
181
|
+
signee: process.env.MBANQ_API_SIGNEE,
|
|
182
|
+
baseUrl: process.env.MBANQ_API_URL,
|
|
183
|
+
tenantId: process.env.MBANQ_TENANT_ID
|
|
184
|
+
});
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
#### Production Considerations
|
|
188
|
+
- Use HTTPS endpoints only (`https://`)
|
|
189
|
+
- Implement proper error handling to avoid credential leakage in logs
|
|
190
|
+
- Configure appropriate request timeouts
|
|
191
|
+
- Use connection pooling for high-volume applications
|
|
192
|
+
|
|
193
|
+
### Axios Instance Logger
|
|
194
|
+
You can also configure an Axios instance logger to set up interceptors or other axios-specific configurations:
|
|
195
|
+
|
|
196
|
+
```javascript
|
|
197
|
+
const axiosLogger = (axiosInstance) => {
|
|
198
|
+
// Add request interceptor
|
|
199
|
+
axiosInstance.interceptors.request.use(
|
|
200
|
+
(config) => {
|
|
201
|
+
console.log('Request:', config.method?.toUpperCase(), config.url);
|
|
202
|
+
return config;
|
|
203
|
+
}
|
|
204
|
+
);
|
|
205
|
+
|
|
206
|
+
// Add response interceptor
|
|
207
|
+
axiosInstance.interceptors.response.use(
|
|
208
|
+
(response) => {
|
|
209
|
+
console.log('Response:', response.status, response.config.url);
|
|
210
|
+
return response;
|
|
211
|
+
}
|
|
212
|
+
);
|
|
213
|
+
};
|
|
214
|
+
|
|
215
|
+
const coreSDK = createClient({
|
|
216
|
+
secret: 'testing123',
|
|
217
|
+
signee: 'TESTING',
|
|
218
|
+
baseUrl: 'https://example.com',
|
|
219
|
+
tenantId: 'testing',
|
|
220
|
+
logger: axiosLogger // Configure Axios instance
|
|
221
|
+
});
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
## Middleware
|
|
225
|
+
The SDK supports middleware for cross-cutting concerns like logging and metrics. Middleware functions are executed automatically around command execution.
|
|
226
|
+
|
|
227
|
+
**Note**: This is different from the Axios instance logger above. Middleware loggers handle command-level logging, while the Axios logger handles HTTP request/response logging.
|
|
228
|
+
|
|
229
|
+
### Available Middleware
|
|
230
|
+
|
|
231
|
+
#### Logging Middleware
|
|
232
|
+
Logs command execution details including inputs, outputs, and errors.
|
|
233
|
+
|
|
234
|
+
```javascript
|
|
235
|
+
import { createClient, createLoggingMiddleware } from '@mbanq/core-sdk-js';
|
|
236
|
+
|
|
237
|
+
const loggingMiddleware = createLoggingMiddleware(console); // or custom logger
|
|
238
|
+
|
|
239
|
+
const client = createClient({
|
|
240
|
+
secret: 'testing123',
|
|
241
|
+
signee: 'TESTING',
|
|
242
|
+
baseUrl: 'https://example.com',
|
|
243
|
+
tenantId: 'testing',
|
|
244
|
+
middlewares: [loggingMiddleware]
|
|
245
|
+
});
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
#### Logger Interface
|
|
249
|
+
For custom loggers, implement the Logger interface:
|
|
250
|
+
|
|
251
|
+
```typescript
|
|
252
|
+
interface Logger {
|
|
253
|
+
info: (message: string, ...args: unknown[]) => void;
|
|
254
|
+
error: (message: string, ...args: unknown[]) => void;
|
|
255
|
+
warn?: (message: string, ...args: unknown[]) => void; // Optional
|
|
256
|
+
log?: (message: string, ...args: unknown[]) => void; // Optional
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
// Example with a custom logger
|
|
260
|
+
const customLogger = {
|
|
261
|
+
info: (message, ...args) => myLoggingService.info(message, args),
|
|
262
|
+
error: (message, ...args) => myLoggingService.error(message, args),
|
|
263
|
+
warn: (message, ...args) => myLoggingService.warn(message, args)
|
|
264
|
+
};
|
|
265
|
+
|
|
266
|
+
const middleware = createLoggingMiddleware(customLogger);
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
#### Metrics Middleware
|
|
270
|
+
Tracks command execution metrics including counters for started, completed, and error events.
|
|
271
|
+
|
|
272
|
+
```javascript
|
|
273
|
+
import { createClient, createMetricsMiddleware } from '@mbanq/core-sdk-js';
|
|
274
|
+
|
|
275
|
+
// Your metrics client must implement the MetricsClient interface
|
|
276
|
+
const metricsClient = {
|
|
277
|
+
incrementCounter: (counterName) => {
|
|
278
|
+
// Increment your counter (e.g., Prometheus, StatsD, etc.)
|
|
279
|
+
console.log(`Counter: ${counterName}`);
|
|
280
|
+
},
|
|
281
|
+
recordError: (error) => {
|
|
282
|
+
// Optional: Record error details
|
|
283
|
+
console.error('Command error:', error);
|
|
284
|
+
}
|
|
285
|
+
};
|
|
286
|
+
|
|
287
|
+
const metricsMiddleware = createMetricsMiddleware(metricsClient);
|
|
288
|
+
|
|
289
|
+
const client = createClient({
|
|
290
|
+
secret: 'testing123',
|
|
291
|
+
signee: 'TESTING',
|
|
292
|
+
baseUrl: 'https://example.com',
|
|
293
|
+
tenantId: 'testing',
|
|
294
|
+
middlewares: [metricsMiddleware]
|
|
295
|
+
});
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
#### MetricsClient Interface
|
|
299
|
+
```typescript
|
|
300
|
+
interface MetricsClient {
|
|
301
|
+
incrementCounter: (counterName: string) => void;
|
|
302
|
+
recordError?: (error: Error) => void; // Optional
|
|
303
|
+
}
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
#### Using Multiple Middleware
|
|
307
|
+
```javascript
|
|
308
|
+
const client = createClient({
|
|
309
|
+
// ... other config
|
|
310
|
+
middlewares: [
|
|
311
|
+
createLoggingMiddleware(console),
|
|
312
|
+
createMetricsMiddleware(metricsClient)
|
|
313
|
+
]
|
|
314
|
+
});
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
#### Custom Middleware
|
|
318
|
+
You can create custom middleware by implementing the Middleware interface:
|
|
319
|
+
|
|
320
|
+
```javascript
|
|
321
|
+
const customMiddleware = {
|
|
322
|
+
before: async (command) => {
|
|
323
|
+
// Called before command execution
|
|
324
|
+
console.log(`Starting ${command.metadata.commandName}`);
|
|
325
|
+
},
|
|
326
|
+
after: async (command, response) => {
|
|
327
|
+
// Called after successful execution
|
|
328
|
+
console.log(`Completed ${command.metadata.commandName}`, response);
|
|
329
|
+
},
|
|
330
|
+
onError: async (command, error) => {
|
|
331
|
+
// Called when command fails
|
|
332
|
+
console.error(`Error in ${command.metadata.commandName}`, error);
|
|
333
|
+
}
|
|
334
|
+
};
|
|
335
|
+
|
|
336
|
+
const client = createClient({
|
|
337
|
+
// ... other config
|
|
338
|
+
middlewares: [customMiddleware]
|
|
339
|
+
});
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
## API Reference
|
|
343
|
+
|
|
344
|
+
### Payment Operations
|
|
345
|
+
|
|
346
|
+
#### Create Payment
|
|
347
|
+
|
|
348
|
+
Creates a new payment with comprehensive validation.
|
|
349
|
+
|
|
350
|
+
```javascript
|
|
351
|
+
const payment = await apiClient.payment.create({
|
|
352
|
+
// Required fields
|
|
353
|
+
amount: 1000,
|
|
354
|
+
currency: 'USD',
|
|
355
|
+
paymentRail: 'ACH', // ACH, WIRE, SWIFT, INTERNAL, FXPAY, CARD
|
|
356
|
+
paymentType: 'CREDIT', // CREDIT or DEBIT
|
|
357
|
+
|
|
358
|
+
// Originator (sender)
|
|
359
|
+
debtor: {
|
|
360
|
+
name: 'John Sender',
|
|
361
|
+
identifier: '123456789', // Account number
|
|
362
|
+
accountType: 'CHECKING', // Optional: CHECKING or SAVINGS
|
|
363
|
+
agent: {
|
|
364
|
+
name: 'First Bank',
|
|
365
|
+
identifier: '021000021' // Routing code
|
|
366
|
+
}
|
|
367
|
+
},
|
|
368
|
+
|
|
369
|
+
// Recipient (receiver)
|
|
370
|
+
creditor: {
|
|
371
|
+
name: 'Jane Receiver',
|
|
372
|
+
identifier: '987654321',
|
|
373
|
+
accountType: 'SAVINGS',
|
|
374
|
+
address: { // Required for WIRE transfers
|
|
375
|
+
streetAddress: '123 Main St',
|
|
376
|
+
city: 'New York',
|
|
377
|
+
state: 'NY',
|
|
378
|
+
country: 'US',
|
|
379
|
+
postalCode: '10001'
|
|
380
|
+
},
|
|
381
|
+
agent: {
|
|
382
|
+
name: 'Second Bank',
|
|
383
|
+
identifier: '121000248'
|
|
384
|
+
}
|
|
385
|
+
},
|
|
386
|
+
|
|
387
|
+
// Optional fields
|
|
388
|
+
clientId: 'client-123',
|
|
389
|
+
reference: ['Invoice-001', 'Payment-ABC'],
|
|
390
|
+
exchangeRate: 1.25,
|
|
391
|
+
chargeBearer: 'OUR', // For SWIFT: OUR, BEN, SHA
|
|
392
|
+
valueDate: '2025-01-15',
|
|
393
|
+
paymentRailMetaData: {
|
|
394
|
+
priority: 'high',
|
|
395
|
+
category: 'business'
|
|
396
|
+
}
|
|
397
|
+
}).execute();
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
#### Get Payment
|
|
401
|
+
|
|
402
|
+
Retrieves a specific payment by ID.
|
|
403
|
+
|
|
404
|
+
```javascript
|
|
405
|
+
const payment = await apiClient.payment.get('payment-456').execute();
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
#### Update Payment
|
|
409
|
+
|
|
410
|
+
Updates an existing payment. All fields are optional.
|
|
411
|
+
|
|
412
|
+
```javascript
|
|
413
|
+
const updatedPayment = await apiClient.payment.update('payment-456', {
|
|
414
|
+
amount: 1500,
|
|
415
|
+
status: 'EXECUTION_SCHEDULED',
|
|
416
|
+
creditor: {
|
|
417
|
+
name: 'Updated Recipient Name'
|
|
418
|
+
},
|
|
419
|
+
errorCode: 'E001',
|
|
420
|
+
errorMessage: 'Insufficient funds',
|
|
421
|
+
exchangeRate: 1.30,
|
|
422
|
+
reference: ['Updated-Reference'],
|
|
423
|
+
paymentRailMetaData: {
|
|
424
|
+
updated: true
|
|
425
|
+
}
|
|
426
|
+
}).execute();
|
|
427
|
+
```
|
|
428
|
+
|
|
429
|
+
#### List Payments
|
|
430
|
+
|
|
431
|
+
Retrieves payments with powerful filtering capabilities.
|
|
432
|
+
|
|
433
|
+
```javascript
|
|
434
|
+
// Simple list
|
|
435
|
+
const payments = await apiClient.payment.list().execute();
|
|
436
|
+
|
|
437
|
+
// With filters and pagination
|
|
438
|
+
const payments = await apiClient.payment.list()
|
|
439
|
+
.where('status').eq('DRAFT')
|
|
440
|
+
.where('paymentRail').eq('ACH')
|
|
441
|
+
.where('paymentType').eq('CREDIT')
|
|
442
|
+
.where('originatorName').eq('John Doe')
|
|
443
|
+
.limit(50)
|
|
444
|
+
.offset(0)
|
|
445
|
+
.execute();
|
|
446
|
+
|
|
447
|
+
// Available filter fields
|
|
448
|
+
// originatorName, originatorAccount, originatorBankRoutingCode
|
|
449
|
+
// recipientName, recipientAccount, recipientBankRoutingCode
|
|
450
|
+
// reference, traceNumber, externalId, clientId
|
|
451
|
+
// dateFormat, locale, originatedBy, paymentRail, paymentType
|
|
452
|
+
// fromValueDate, toValueDate, fromExecuteDate, toExecuteDate
|
|
453
|
+
// status, fromReturnDate, toReturnDate, isSettlement, orderBy, sortOrder
|
|
454
|
+
```
|
|
455
|
+
|
|
456
|
+
### Multi-Tenant Support
|
|
457
|
+
|
|
458
|
+
The SDK supports multi-tenant operations through tenant context.
|
|
459
|
+
|
|
460
|
+
#### Default Tenant Operations
|
|
461
|
+
Uses the `tenantId` from client configuration:
|
|
462
|
+
|
|
463
|
+
```javascript
|
|
464
|
+
const payment = await apiClient.payment.create(paymentData).execute();
|
|
465
|
+
const payments = await apiClient.payment.list().execute();
|
|
466
|
+
```
|
|
467
|
+
|
|
468
|
+
#### Tenant-Specific Operations
|
|
469
|
+
Override tenant for specific operations:
|
|
470
|
+
|
|
471
|
+
```javascript
|
|
472
|
+
// Create payment for specific tenant
|
|
473
|
+
const payment = await apiClient.tenant('tenant-123').payment.create(paymentData).execute();
|
|
474
|
+
|
|
475
|
+
// Get payment from specific tenant
|
|
476
|
+
const payment = await apiClient.tenant('tenant-123').payment.get('payment-456').execute();
|
|
477
|
+
|
|
478
|
+
// Update payment in specific tenant
|
|
479
|
+
await apiClient.tenant('tenant-123').payment.update('payment-456', updateData).execute();
|
|
480
|
+
|
|
481
|
+
// List payments from specific tenant with filters
|
|
482
|
+
const payments = await apiClient.tenant('tenant-123').payment.list()
|
|
483
|
+
.where('status').eq('DRAFT')
|
|
484
|
+
.limit(10)
|
|
485
|
+
.execute();
|
|
486
|
+
```
|
|
487
|
+
|
|
488
|
+
## Type Safety & Validation
|
|
489
|
+
|
|
490
|
+
The SDK uses [Zod](https://zod.dev/) for runtime type validation and TypeScript for compile-time type safety.
|
|
491
|
+
|
|
492
|
+
### Supported Payment Rails
|
|
493
|
+
- `ACH` - Automated Clearing House
|
|
494
|
+
- `SAMEDAYACH` - Same Day ACH
|
|
495
|
+
- `WIRE` - Domestic Wire Transfer
|
|
496
|
+
- `SWIFT` - International Wire Transfer
|
|
497
|
+
- `INTERNAL` - Internal Transfer
|
|
498
|
+
- `FXPAY` - Foreign Exchange Payment
|
|
499
|
+
- `CARD` - Card Payment
|
|
500
|
+
|
|
501
|
+
### Payment Statuses
|
|
502
|
+
- `DRAFT`, `AML_SCREENING`, `AML_REJECTED`
|
|
503
|
+
- `EXECUTION_SCHEDULED`, `EXECUTION_PROCESSING`, `EXECUTION_SUCCESS`, `EXECUTION_FAILURE`
|
|
504
|
+
- `RETURNED`, `CANCELLED`, `COMPLIANCE_FAILURE`, `DELETED`, `UNKNOWN`
|
|
505
|
+
|
|
506
|
+
### Validation Features
|
|
507
|
+
- **Input Validation**: All create/update operations validate data structure
|
|
508
|
+
- **Response Validation**: API responses are validated before returning
|
|
509
|
+
- **Custom Rules**: WIRE transfers require recipient address with state/country
|
|
510
|
+
- **Type Safety**: Full TypeScript support with inferred types
|
|
511
|
+
|
|
512
|
+
## Error Handling
|
|
513
|
+
The library uses a consistent error handling pattern. All API calls may throw the following errors:
|
|
514
|
+
|
|
515
|
+
### Error Types
|
|
516
|
+
- **`CommandError`**: Base error type with `code`, `message`, `statusCode`, and optional `requestId`
|
|
517
|
+
- **Authentication Errors**: Invalid or missing API credentials
|
|
518
|
+
- Invalid JWT secret/signee combination
|
|
519
|
+
- Expired or invalid bearer token
|
|
520
|
+
- OAuth credential authentication failure
|
|
521
|
+
- **Validation Errors**: Invalid parameters provided (uses Zod validation)
|
|
522
|
+
- **API Errors**: Server-side errors with specific error codes
|
|
523
|
+
- **Network Errors**: Network connectivity or timeout issues
|
|
524
|
+
|
|
525
|
+
### Common Authentication Error Scenarios
|
|
526
|
+
- **Missing credentials**: No authentication method provided
|
|
527
|
+
- **Invalid JWT**: Incorrect secret or signee values
|
|
528
|
+
- **Expired token**: Bearer token has expired and needs refresh
|
|
529
|
+
- **OAuth failure**: Invalid username/password or client credentials
|
|
530
|
+
|
|
531
|
+
## Examples
|
|
532
|
+
|
|
533
|
+
### Complete Payment Flow Example
|
|
534
|
+
|
|
535
|
+
```javascript
|
|
536
|
+
import { createClient } from '@mbanq/core-sdk-js';
|
|
537
|
+
|
|
538
|
+
// Initialize the client
|
|
539
|
+
const apiClient = createClient({
|
|
540
|
+
secret: 'your-secret',
|
|
541
|
+
signee: 'YOUR-SIGNEE',
|
|
542
|
+
baseUrl: 'https://api.cloud.mbanq.com',
|
|
543
|
+
tenantId: 'your-tenant-id'
|
|
544
|
+
});
|
|
545
|
+
|
|
546
|
+
// Create an ACH payment
|
|
547
|
+
const achPayment = await apiClient.payment.create({
|
|
548
|
+
amount: 1500,
|
|
549
|
+
currency: 'USD',
|
|
550
|
+
paymentRail: 'ACH',
|
|
551
|
+
paymentType: 'CREDIT',
|
|
552
|
+
debtor: {
|
|
553
|
+
name: 'Alice Corporation',
|
|
554
|
+
identifier: '111222333',
|
|
555
|
+
accountType: 'CHECKING',
|
|
556
|
+
agent: {
|
|
557
|
+
name: 'First National Bank',
|
|
558
|
+
identifier: '021000021'
|
|
559
|
+
}
|
|
560
|
+
},
|
|
561
|
+
creditor: {
|
|
562
|
+
name: 'Bob Enterprises',
|
|
563
|
+
identifier: '444555666',
|
|
564
|
+
accountType: 'CHECKING',
|
|
565
|
+
agent: {
|
|
566
|
+
name: 'Second Federal Bank',
|
|
567
|
+
identifier: '121000248'
|
|
568
|
+
}
|
|
569
|
+
},
|
|
570
|
+
clientId: 'client-abc123',
|
|
571
|
+
reference: ['Invoice-2025-001']
|
|
572
|
+
}).execute();
|
|
573
|
+
|
|
574
|
+
console.log('Created payment:', achPayment.id);
|
|
575
|
+
|
|
576
|
+
// Create an international WIRE payment
|
|
577
|
+
const wirePayment = await apiClient.payment.create({
|
|
578
|
+
amount: 5000,
|
|
579
|
+
currency: 'USD',
|
|
580
|
+
paymentRail: 'SWIFT',
|
|
581
|
+
paymentType: 'CREDIT',
|
|
582
|
+
debtor: {
|
|
583
|
+
name: 'US Company',
|
|
584
|
+
identifier: '123456789',
|
|
585
|
+
agent: {
|
|
586
|
+
name: 'Chase Bank',
|
|
587
|
+
identifier: 'CHASUS33XXX'
|
|
588
|
+
}
|
|
589
|
+
},
|
|
590
|
+
creditor: {
|
|
591
|
+
name: 'European Partner',
|
|
592
|
+
identifier: '987654321',
|
|
593
|
+
address: {
|
|
594
|
+
streetAddress: '123 Business Ave',
|
|
595
|
+
city: 'London',
|
|
596
|
+
state: 'England',
|
|
597
|
+
country: 'GB',
|
|
598
|
+
postalCode: 'SW1A 1AA'
|
|
599
|
+
},
|
|
600
|
+
agent: {
|
|
601
|
+
name: 'HSBC Bank',
|
|
602
|
+
identifier: 'HBUKGB4BXXX'
|
|
603
|
+
}
|
|
604
|
+
},
|
|
605
|
+
chargeBearer: 'OUR',
|
|
606
|
+
reference: ['Contract-2025-002'],
|
|
607
|
+
exchangeRate: 0.85
|
|
608
|
+
}).execute();
|
|
609
|
+
|
|
610
|
+
// Retrieve and monitor payments
|
|
611
|
+
const payment = await apiClient.payment.get(achPayment.id).execute();
|
|
612
|
+
console.log('Payment status:', payment.status);
|
|
613
|
+
|
|
614
|
+
// Update payment if needed
|
|
615
|
+
if (payment.status === 'DRAFT') {
|
|
616
|
+
await apiClient.payment.update(payment.id, {
|
|
617
|
+
status: 'EXECUTION_SCHEDULED',
|
|
618
|
+
reference: ['Updated-Reference']
|
|
619
|
+
});
|
|
620
|
+
}
|
|
621
|
+
|
|
622
|
+
// List recent payments with filters
|
|
623
|
+
const recentPayments = await apiClient.payment.list()
|
|
624
|
+
.where('status').eq('EXECUTION_SCHEDULED')
|
|
625
|
+
.where('paymentRail').eq('ACH')
|
|
626
|
+
.where('fromExecuteDate').eq('2025-01-01')
|
|
627
|
+
.where('toExecuteDate').eq('2025-01-31')
|
|
628
|
+
.limit(25)
|
|
629
|
+
.execute();
|
|
630
|
+
|
|
631
|
+
console.log(`Found ${recentPayments.length} scheduled ACH payments`);
|
|
632
|
+
|
|
633
|
+
// Multi-tenant example
|
|
634
|
+
const tenantPayment = await apiClient.tenant('different-tenant').payment.create({
|
|
635
|
+
amount: 750,
|
|
636
|
+
currency: 'USD',
|
|
637
|
+
paymentRail: 'INTERNAL',
|
|
638
|
+
paymentType: 'CREDIT',
|
|
639
|
+
debtor: { name: 'Internal Sender', identifier: '111111' },
|
|
640
|
+
creditor: { name: 'Internal Receiver', identifier: '222222' }
|
|
641
|
+
}).execute();
|
|
642
|
+
```
|
|
643
|
+
|
|
644
|
+
### Error Handling Example
|
|
645
|
+
|
|
646
|
+
```javascript
|
|
647
|
+
import { isCommandError } from '@mbanq/core-sdk-js';
|
|
648
|
+
|
|
649
|
+
try {
|
|
650
|
+
const payment = await apiClient.payment.create({
|
|
651
|
+
amount: -100, // Invalid: negative amount
|
|
652
|
+
currency: 'INVALID', // Invalid: not 3-character code
|
|
653
|
+
// Missing required fields
|
|
654
|
+
}).execute();
|
|
655
|
+
} catch (error) {
|
|
656
|
+
if (isCommandError(error)) {
|
|
657
|
+
console.error('Payment creation failed:');
|
|
658
|
+
console.error('Code:', error.code);
|
|
659
|
+
console.error('Message:', error.message);
|
|
660
|
+
if (error.requestId) {
|
|
661
|
+
console.error('Request ID:', error.requestId);
|
|
662
|
+
}
|
|
663
|
+
} else {
|
|
664
|
+
console.error('Unexpected error:', error);
|
|
665
|
+
}
|
|
666
|
+
}
|
|
667
|
+
```
|
|
668
|
+
|
|
669
|
+
For more detailed information or support, please contact our support team or visit our developer portal.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
import{a as s,c as d,d as r}from"./chunk-RX3BFHHX.mjs";var I=t=>{let e=t.skipNotification&&"?skipNotification=true"||"",i=t.card.cardType==="CREDIT"?"creditcards":"cards",n={...t.payload,query:e,flag:t.flag};return{input:t,metadata:{commandName:"SendAuthorizationToCore",path:`/${i}/${t.card.internalCardId}/authorization${e}`,method:"POST"},execute:async a=>{t.tenantId&&(a.tenantId=t.tenantId);let o=await r(a);try{return await o.post(`/${i}/${t.card.internalCardId}/authorization${e}`,n)}catch(c){d(c)}}}},p=t=>({input:t,metadata:{commandName:"UpdateCardID",path:`/clients/${t.clientId}`,method:"PUT"},execute:async e=>{t.tenantId&&(e.tenantId=t.tenantId);let i=await r(e);try{await i.put(`/clients/${t.clientId}`,{businessCardIDURL:t.businessCardIDURL,businessCardIDQRCode:t.businessCardIDQRCode})}catch(n){d(n)}}});var h=t=>({input:t,metadata:{commandName:"GetClientData",path:`/v1/clients/${t.clientId}`,method:"GET"},execute:async e=>{t.tenantId&&(e.tenantId=t.tenantId);let i=await r(e),n={clientData:void 0,riskRatingData:void 0,clientAddressData:void 0,clientIdentifierData:void 0};try{return n.clientData=await i.get(`/v1/clients/${t.clientId}`),t.riskRating&&(n.riskRatingData=await i.get(`/v1/clients/${t.clientId}/riskrating`)),t.clientAddress&&(n.clientAddressData=await i.get(`/v1/client/${t.clientId}/addresses`)),t.clientIdentifier&&(n.clientIdentifierData=await i.get(`/v1/clients/${t.clientId}/identifiers?unmaskValue=true`)),n}catch(a){d(a)}}}),b=t=>({input:t,metadata:{commandName:"UpdateClient",path:`/v1/clients/${t.clientId}`,method:"PUT"},execute:async e=>{t.tenantId&&(e.tenantId=t.tenantId);let i=await r(e);try{return(await i.put(`/v1/clients/${t.clientId}`,{...t.updates})).data}catch(n){d(n)}}}),y=t=>({input:t,metadata:{commandName:"UpdateClientIdentifier",path:`/v1/clients/${t.clientId}/identifiers/${t.identifierId}`,method:"PUT"},execute:async e=>{t.tenantId&&(e.tenantId=t.tenantId);let i=await r(e);try{return(await i.put(`/v1/clients/${t.clientId}/identifiers/${t.identifierId}`,{...t.updates})).data}catch(n){d(n)}}});import{print as l}from"graphql";var $=t=>({input:t,metadata:{commandName:t.operationName||"GraphQL",path:"/graphql",method:"POST"},execute:async e=>{t.tenantId&&(e.tenantId=t.tenantId);let i=await r(e),n=e.graphqlPath||"/graphql";try{let a=typeof t.command=="string"?t.command:l(t.command),{data:o}=await i.post(n,{query:a,variables:t.variables,operationName:t.operationName});if(o.errors?.length)throw s({message:o.errors[0].message,code:"graphql_error",originalError:o.errors[0]});if(!o.data)throw s({message:"No data returned from GraphQL query",code:"graphql_no_data"});return o.data}catch(a){throw a.name==="CommandError"?a:s({message:a.message,code:"graphql_request_failed",originalError:a})}}});export{I as a,p as b,h as c,b as d,y as e,$ as f};
|