rpay-sdk 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,474 @@
1
+ /**
2
+ * Canonical RPAY 15 Vietnamese Banks & E-Wallet Gateways
3
+ * Synchronized with `apps/backend/internal/model/bank_account.go`
4
+ * and `apps/backend/internal/service/bank_public_api_service.go`.
5
+ */
6
+ export const RPAY_DEFAULT_BASE_URL = "https://api.rpay.vn";
7
+ export const RPAY_DEFAULT_TIMEOUT_MS = 60000;
8
+
9
+ export const RPAY_BANKS = Object.freeze([
10
+ Object.freeze({
11
+ key: "vietcombank",
12
+ code: "VCB",
13
+ shortName: "Vietcombank",
14
+ fullName: "Ngân hàng TMCP Ngoại thương Việt Nam",
15
+ bin: "970436",
16
+ apiSlug: "vcb",
17
+ primarySlug: "vcb",
18
+ aliases: Object.freeze(["vcb", "vietcombank"]),
19
+ logo: "/ibankings/970436.png",
20
+ v3UsesPhonePin: false,
21
+ }),
22
+ Object.freeze({
23
+ key: "acb",
24
+ code: "ACB",
25
+ shortName: "ACB",
26
+ fullName: "Ngân hàng TMCP Á Châu",
27
+ bin: "970416",
28
+ apiSlug: "acb",
29
+ primarySlug: "acb",
30
+ aliases: Object.freeze(["acb"]),
31
+ logo: "/ibankings/970416.png",
32
+ v3UsesPhonePin: false,
33
+ }),
34
+ Object.freeze({
35
+ key: "mbbank",
36
+ code: "MB",
37
+ shortName: "MBBank",
38
+ fullName: "Ngân hàng TMCP Quân đội",
39
+ bin: "970422",
40
+ apiSlug: "mb",
41
+ primarySlug: "mb",
42
+ aliases: Object.freeze(["mb", "mbbank"]),
43
+ logo: "/ibankings/970422.png",
44
+ v3UsesPhonePin: false,
45
+ }),
46
+ Object.freeze({
47
+ key: "techcombank",
48
+ code: "TCB",
49
+ shortName: "Techcombank",
50
+ fullName: "Ngân hàng TMCP Kỹ thương Việt Nam",
51
+ bin: "970407",
52
+ apiSlug: "tcb",
53
+ primarySlug: "tcb",
54
+ aliases: Object.freeze(["tcb", "techcombank"]),
55
+ logo: "/ibankings/970407.png",
56
+ v3UsesPhonePin: false,
57
+ }),
58
+ Object.freeze({
59
+ key: "bidv",
60
+ code: "BIDV",
61
+ shortName: "BIDV",
62
+ fullName: "Ngân hàng TMCP Đầu tư và Phát triển Việt Nam",
63
+ bin: "970418",
64
+ apiSlug: "bidv",
65
+ primarySlug: "bidv",
66
+ aliases: Object.freeze(["bidv"]),
67
+ logo: "/ibankings/970418.png",
68
+ v3UsesPhonePin: false,
69
+ }),
70
+ Object.freeze({
71
+ key: "vietinbank",
72
+ code: "ICB",
73
+ shortName: "VietinBank",
74
+ fullName: "Ngân hàng TMCP Công thương Việt Nam",
75
+ bin: "970415",
76
+ apiSlug: "icb",
77
+ primarySlug: "icb",
78
+ aliases: Object.freeze(["icb", "vietinbank", "ctg", "vtb", "viettinbank"]),
79
+ logo: "/ibankings/970415.png",
80
+ v3UsesPhonePin: false,
81
+ }),
82
+ Object.freeze({
83
+ key: "vpbank",
84
+ code: "VPB",
85
+ shortName: "VPBank",
86
+ fullName: "Ngân hàng TMCP Việt Nam Thịnh Vượng",
87
+ bin: "970432",
88
+ apiSlug: "vpb",
89
+ primarySlug: "vpb",
90
+ aliases: Object.freeze(["vpb", "vpbank"]),
91
+ logo: "/ibankings/970432.png",
92
+ v3UsesPhonePin: false,
93
+ }),
94
+ Object.freeze({
95
+ key: "tpbank",
96
+ code: "TPB",
97
+ shortName: "TPBank",
98
+ fullName: "Ngân hàng TMCP Tiên Phong",
99
+ bin: "970423",
100
+ apiSlug: "tpb",
101
+ primarySlug: "tpb",
102
+ aliases: Object.freeze(["tpb", "tpbank"]),
103
+ logo: "/ibankings/970423.png",
104
+ v3UsesPhonePin: false,
105
+ }),
106
+ Object.freeze({
107
+ key: "agribank",
108
+ code: "VBA",
109
+ shortName: "Agribank",
110
+ fullName: "Ngân hàng Nông nghiệp và PTNT Việt Nam",
111
+ bin: "970405",
112
+ apiSlug: "vba",
113
+ primarySlug: "vba",
114
+ aliases: Object.freeze(["vba", "agribank"]),
115
+ logo: "/ibankings/970405.png",
116
+ v3UsesPhonePin: false,
117
+ }),
118
+ Object.freeze({
119
+ key: "msb",
120
+ code: "MSB",
121
+ shortName: "MSB",
122
+ fullName: "Ngân hàng TMCP Hàng Hải",
123
+ bin: "970426",
124
+ apiSlug: "msb",
125
+ primarySlug: "msb",
126
+ aliases: Object.freeze(["msb", "maritimebank"]),
127
+ logo: "/ibankings/970426.png",
128
+ v3UsesPhonePin: false,
129
+ }),
130
+ Object.freeze({
131
+ key: "ocb",
132
+ code: "OCB",
133
+ shortName: "OCB",
134
+ fullName: "Ngân hàng TMCP Phương Đông",
135
+ bin: "970448",
136
+ apiSlug: "ocb",
137
+ primarySlug: "ocb",
138
+ aliases: Object.freeze(["ocb", "oceanbank"]),
139
+ logo: "/ibankings/970448.png",
140
+ v3UsesPhonePin: false,
141
+ }),
142
+ Object.freeze({
143
+ key: "seabank",
144
+ code: "SEAB",
145
+ shortName: "SeABank",
146
+ fullName: "Ngân hàng TMCP Đông Nam Á",
147
+ bin: "970440",
148
+ apiSlug: "seab",
149
+ primarySlug: "seabank",
150
+ aliases: Object.freeze(["seabank", "ssb", "seab", "sebank"]),
151
+ logo: "/ibankings/970440.png",
152
+ v3UsesPhonePin: false,
153
+ }),
154
+ Object.freeze({
155
+ key: "eximbank",
156
+ code: "EIB",
157
+ shortName: "Eximbank",
158
+ fullName: "Ngân hàng TMCP Xuất Nhập khẩu Việt Nam",
159
+ bin: "970431",
160
+ apiSlug: "eib",
161
+ primarySlug: "eib",
162
+ aliases: Object.freeze(["eib", "eximbank", "exim"]),
163
+ logo: "/ibankings/970431.png",
164
+ v3UsesPhonePin: false,
165
+ }),
166
+ Object.freeze({
167
+ key: "bvbank",
168
+ code: "BVB",
169
+ shortName: "BVBank",
170
+ fullName: "Ngân hàng TMCP Bản Việt",
171
+ bin: "970454",
172
+ apiSlug: "bvb",
173
+ primarySlug: "bvb",
174
+ aliases: Object.freeze(["bvb", "bvbank", "banviet", "vietcapitalbank"]),
175
+ logo: "/ibankings/970454.png",
176
+ v3UsesPhonePin: false,
177
+ }),
178
+ Object.freeze({
179
+ key: "viettelpay",
180
+ code: "VTP",
181
+ shortName: "Viettel Money",
182
+ fullName: "Tổng công ty Dịch vụ số Viettel",
183
+ bin: "971005",
184
+ apiSlug: "vtp",
185
+ primarySlug: "vtm",
186
+ aliases: Object.freeze(["vtm", "vtp", "viettelmoney", "viettelpay", "viettel_money", "viettel-money"]),
187
+ logo: "/ibankings/971005.png",
188
+ v3UsesPhonePin: true,
189
+ }),
190
+ ]);
191
+
192
+ /**
193
+ * Canonical 18 Blockchain Networks for RPAY USDT / USDC Crypto Gateway.
194
+ * Synchronized with `apps/backend/internal/model/usdt_store.go`.
195
+ */
196
+ export const RPAY_USDT_NETWORKS = Object.freeze([
197
+ Object.freeze({
198
+ network: "TRC20",
199
+ name: "TRON (TRC-20)",
200
+ chainKey: "tron",
201
+ tokenStandard: "TRC-20",
202
+ decimals: 6,
203
+ usdtContract: "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
204
+ usdcContract: "TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8",
205
+ explorerBaseUrl: "https://tronscan.org",
206
+ avgConfirmSeconds: 6,
207
+ recommendedFeeText: "~1 - 2 USDT",
208
+ }),
209
+ Object.freeze({
210
+ network: "BEP20",
211
+ name: "BNB Smart Chain (BEP-20)",
212
+ chainKey: "bsc",
213
+ tokenStandard: "BEP-20",
214
+ decimals: 18,
215
+ usdtContract: "0x55d398326f99059fF775485246999027B3197955",
216
+ usdcContract: "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
217
+ explorerBaseUrl: "https://bscscan.com",
218
+ avgConfirmSeconds: 6,
219
+ recommendedFeeText: "~0.05 USDT",
220
+ }),
221
+ Object.freeze({
222
+ network: "ERC20",
223
+ name: "Ethereum (ERC-20)",
224
+ chainKey: "ethereum",
225
+ tokenStandard: "ERC-20",
226
+ decimals: 6,
227
+ usdtContract: "0xdAC17F958D2ee523a2206206994597C13D831ec7",
228
+ usdcContract: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
229
+ explorerBaseUrl: "https://etherscan.io",
230
+ avgConfirmSeconds: 24,
231
+ recommendedFeeText: "~2 - 8 USDT",
232
+ }),
233
+ Object.freeze({
234
+ network: "POLYGON",
235
+ name: "Polygon POS",
236
+ chainKey: "polygon",
237
+ tokenStandard: "ERC-20 (Polygon)",
238
+ decimals: 6,
239
+ usdtContract: "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
240
+ usdcContract: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
241
+ explorerBaseUrl: "https://polygonscan.com",
242
+ avgConfirmSeconds: 6,
243
+ recommendedFeeText: "< 0.02 USDT",
244
+ }),
245
+ Object.freeze({
246
+ network: "ARBITRUM",
247
+ name: "Arbitrum One",
248
+ chainKey: "arbitrum",
249
+ tokenStandard: "ERC-20 (Arbitrum)",
250
+ decimals: 6,
251
+ usdtContract: "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
252
+ usdcContract: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
253
+ explorerBaseUrl: "https://arbiscan.io",
254
+ avgConfirmSeconds: 4,
255
+ recommendedFeeText: "< 0.05 USDT",
256
+ }),
257
+ Object.freeze({
258
+ network: "OPTIMISM",
259
+ name: "OP Mainnet (Optimism)",
260
+ chainKey: "optimism",
261
+ tokenStandard: "ERC-20 (Optimism)",
262
+ decimals: 6,
263
+ usdtContract: "0x94b008aA00579c1307B0EF2c499aD98a8ce58e58",
264
+ usdcContract: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
265
+ explorerBaseUrl: "https://optimistic.etherscan.io",
266
+ avgConfirmSeconds: 4,
267
+ recommendedFeeText: "< 0.05 USDT",
268
+ }),
269
+ Object.freeze({
270
+ network: "SOLANA",
271
+ name: "Solana (SPL)",
272
+ chainKey: "solana",
273
+ tokenStandard: "SPL",
274
+ decimals: 6,
275
+ usdtContract: "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB",
276
+ usdcContract: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
277
+ explorerBaseUrl: "https://solscan.io",
278
+ avgConfirmSeconds: 3,
279
+ recommendedFeeText: "< 0.01 USDT",
280
+ }),
281
+ Object.freeze({
282
+ network: "TON",
283
+ name: "The Open Network (TON Jetton)",
284
+ chainKey: "ton",
285
+ tokenStandard: "Jetton",
286
+ decimals: 6,
287
+ usdtContract: "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
288
+ usdcContract: "",
289
+ explorerBaseUrl: "https://tonviewer.com",
290
+ avgConfirmSeconds: 6,
291
+ recommendedFeeText: "~0.05 USDT",
292
+ }),
293
+ Object.freeze({
294
+ network: "BASE",
295
+ name: "Base Mainnet",
296
+ chainKey: "base",
297
+ tokenStandard: "ERC-20 (Base)",
298
+ decimals: 6,
299
+ usdtContract: "0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2",
300
+ usdcContract: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
301
+ explorerBaseUrl: "https://basescan.org",
302
+ avgConfirmSeconds: 4,
303
+ recommendedFeeText: "< 0.02 USDT",
304
+ }),
305
+ Object.freeze({
306
+ network: "AVALANCHE",
307
+ name: "Avalanche C-Chain",
308
+ chainKey: "avalanche",
309
+ tokenStandard: "ARC-20",
310
+ decimals: 6,
311
+ usdtContract: "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
312
+ usdcContract: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
313
+ explorerBaseUrl: "https://snowtrace.io",
314
+ avgConfirmSeconds: 4,
315
+ recommendedFeeText: "< 0.05 USDT",
316
+ }),
317
+ Object.freeze({
318
+ network: "APTOS",
319
+ name: "Aptos Mainnet",
320
+ chainKey: "aptos",
321
+ tokenStandard: "Aptos Fungible Asset",
322
+ decimals: 6,
323
+ usdtContract: "0x357b0b74bc833e95a115ad22604854d6b0fca151cecd94111770e5d6ffc9dc2b",
324
+ usdcContract: "0xbae207659db88bea0cbead6da0ed00aac12edcdda169e591cd41c94180b46f3b",
325
+ explorerBaseUrl: "https://aptoscan.com",
326
+ avgConfirmSeconds: 3,
327
+ recommendedFeeText: "< 0.01 USDT",
328
+ }),
329
+ Object.freeze({
330
+ network: "SUI",
331
+ name: "Sui Network",
332
+ chainKey: "sui",
333
+ tokenStandard: "Sui Coin",
334
+ decimals: 6,
335
+ usdtContract: "0xc060006111016b8a020ad5b33834984a437aaa7d3c74c18e09a95d48aceab08c::coin::COIN",
336
+ usdcContract: "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
337
+ explorerBaseUrl: "https://suiscan.xyz/mainnet",
338
+ avgConfirmSeconds: 3,
339
+ recommendedFeeText: "< 0.01 USDT",
340
+ }),
341
+ Object.freeze({
342
+ network: "OPBNB",
343
+ name: "opBNB Mainnet",
344
+ chainKey: "opbnb",
345
+ tokenStandard: "BEP-20 (opBNB)",
346
+ decimals: 18,
347
+ usdtContract: "0x9e5AAC1Ba1a2e6aEd6b32689DFcF62A509Ca96f3",
348
+ usdcContract: "",
349
+ explorerBaseUrl: "https://opbnbscan.com",
350
+ avgConfirmSeconds: 3,
351
+ recommendedFeeText: "< 0.005 USDT",
352
+ }),
353
+ Object.freeze({
354
+ network: "CELO",
355
+ name: "Celo Mainnet",
356
+ chainKey: "celo",
357
+ tokenStandard: "ERC-20 (Celo)",
358
+ decimals: 6,
359
+ usdtContract: "0x48065fbBE25f71C9282ddf5e1cD6D6A887483D5e",
360
+ usdcContract: "0xcebA9300f2b948710d2653dD7B07f33A8B32118C",
361
+ explorerBaseUrl: "https://celoscan.io",
362
+ avgConfirmSeconds: 5,
363
+ recommendedFeeText: "< 0.01 USDT",
364
+ }),
365
+ Object.freeze({
366
+ network: "SCROLL",
367
+ name: "Scroll Mainnet",
368
+ chainKey: "scroll",
369
+ tokenStandard: "ERC-20 (Scroll)",
370
+ decimals: 6,
371
+ usdtContract: "0xf55BEC9cafDbE8730f096Aa55dad6D22d44099Df",
372
+ usdcContract: "0x06eFdBFf2a14a7c8E15944D1F4A48F9F95F663A4",
373
+ explorerBaseUrl: "https://scrollscan.com",
374
+ avgConfirmSeconds: 5,
375
+ recommendedFeeText: "< 0.05 USDT",
376
+ }),
377
+ Object.freeze({
378
+ network: "KAVA",
379
+ name: "Kava EVM",
380
+ chainKey: "kava",
381
+ tokenStandard: "ERC-20 (Kava)",
382
+ decimals: 6,
383
+ usdtContract: "0x919C1c267BC06a7039e03fcc2eF738525769109c",
384
+ usdcContract: "0xfa9343C3897324496A05fC75abeD6bAC29f8A40f",
385
+ explorerBaseUrl: "https://kavascan.com",
386
+ avgConfirmSeconds: 6,
387
+ recommendedFeeText: "< 0.01 USDT",
388
+ }),
389
+ Object.freeze({
390
+ network: "POLKADOT",
391
+ name: "Polkadot Asset Hub (Statemint)",
392
+ chainKey: "polkadot",
393
+ tokenStandard: "AssetHub #1984",
394
+ decimals: 6,
395
+ usdtContract: "1984",
396
+ usdcContract: "1337",
397
+ explorerBaseUrl: "https://assethub-polkadot.subscan.io",
398
+ avgConfirmSeconds: 12,
399
+ recommendedFeeText: "< 0.02 USDT",
400
+ }),
401
+ Object.freeze({
402
+ network: "OSMOSIS",
403
+ name: "Osmosis (Cosmos IBC)",
404
+ chainKey: "osmosis",
405
+ tokenStandard: "IBC Denom",
406
+ decimals: 6,
407
+ usdtContract: "ibc/4ABBEF4C8926DDDB320AE5188CFD63267ABBCEFC0583E4AE05D6E5AA2401DDAB",
408
+ usdcContract: "ibc/498A0751C798A0D9A389AA3691123DADA57DAA4FE165D5C75894505B876BA6E4",
409
+ explorerBaseUrl: "https://www.mintscan.io/osmosis",
410
+ avgConfirmSeconds: 6,
411
+ recommendedFeeText: "< 0.02 USDT",
412
+ }),
413
+ ]);
414
+
415
+ /**
416
+ * Resolves a bank specification by key, code, BIN, shortName, or alias (case-insensitive).
417
+ * @param {string} rawIdentifier
418
+ */
419
+ export function resolveBankSpec(rawIdentifier) {
420
+ const norm = String(rawIdentifier ?? "").trim().toLowerCase();
421
+ if (!norm) {
422
+ return null;
423
+ }
424
+ for (const bank of RPAY_BANKS) {
425
+ if (
426
+ bank.key === norm ||
427
+ bank.code.toLowerCase() === norm ||
428
+ bank.bin === norm ||
429
+ bank.shortName.toLowerCase() === norm ||
430
+ bank.apiSlug === norm ||
431
+ bank.primarySlug === norm ||
432
+ bank.aliases.includes(norm)
433
+ ) {
434
+ return bank;
435
+ }
436
+ }
437
+ return null;
438
+ }
439
+
440
+ /**
441
+ * Resolves a canonical USDT/USDC network specification by network code or chainKey.
442
+ * @param {string} rawNetwork
443
+ */
444
+ export function resolveUsdtNetworkSpec(rawNetwork) {
445
+ const norm = String(rawNetwork ?? "").trim().toUpperCase();
446
+ if (!norm) {
447
+ return null;
448
+ }
449
+ const aliasMap = {
450
+ TRX: "TRC20",
451
+ TRON: "TRC20",
452
+ "TRC-20": "TRC20",
453
+ BSC: "BEP20",
454
+ BNB: "BEP20",
455
+ "BEP-20": "BEP20",
456
+ ETH: "ERC20",
457
+ ETHEREUM: "ERC20",
458
+ "ERC-20": "ERC20",
459
+ MATIC: "POLYGON",
460
+ ARB: "ARBITRUM",
461
+ OP: "OPTIMISM",
462
+ SOL: "SOLANA",
463
+ AVAX: "AVALANCHE",
464
+ DOT: "POLKADOT",
465
+ OSMO: "OSMOSIS",
466
+ };
467
+ const target = aliasMap[norm] || norm;
468
+ for (const item of RPAY_USDT_NETWORKS) {
469
+ if (item.network === target || item.chainKey.toUpperCase() === target) {
470
+ return item;
471
+ }
472
+ }
473
+ return null;
474
+ }
package/src/errors.mjs ADDED
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Structured error class thrown by RPAY SDK operations.
3
+ */
4
+ export class RPayError extends Error {
5
+ /**
6
+ * @param {string} message
7
+ * @param {object} [options]
8
+ * @param {string} [options.code]
9
+ * @param {number} [options.status]
10
+ * @param {unknown} [options.details]
11
+ * @param {string} [options.endpoint]
12
+ * @param {string} [options.method]
13
+ * @param {unknown} [options.rawResponse]
14
+ */
15
+ constructor(message, options = {}) {
16
+ super(message);
17
+ this.name = "RPayError";
18
+ this.code = options.code || "RPAY_ERROR";
19
+ this.status = typeof options.status === "number" ? options.status : 0;
20
+ this.details = options.details ?? null;
21
+ this.endpoint = options.endpoint || "";
22
+ this.method = options.method || "";
23
+ this.rawResponse = options.rawResponse ?? null;
24
+
25
+ if (Error.captureStackTrace) {
26
+ Error.captureStackTrace(this, RPayError);
27
+ }
28
+ }
29
+ }