barkapay 0.0.0-stage → 2.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.
package/README.md CHANGED
@@ -1,3 +1,517 @@
1
- # Temporary Holding Version
1
+ # barkapay Node.js SDK
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Official Node.js / TypeScript client for the [barkapay API](https://barkapay.com/developers) —
4
+ mobile money collections, payouts and payment links across West Africa, behind one API.
5
+
6
+ - **Zero runtime dependencies** — the global `fetch` (Node 18+) and `node:crypto`, nothing else.
7
+ - Dual **ESM + CommonJS** build with bundled **type definitions**.
8
+ - Typed payments, transfers, payment links, balance and errors.
9
+ - Webhook signature verification built in.
10
+ - Safe by default: timeouts, retries only where a retry cannot move money twice,
11
+ redirects never followed, API key never printed.
12
+
13
+ ## Requirements
14
+
15
+ Node **18 or later**.
16
+
17
+ ## Install
18
+
19
+ ```bash
20
+ npm install barkapay
21
+ ```
22
+
23
+ ## Quick start
24
+
25
+ ```ts
26
+ import { BarkaPay } from 'barkapay';
27
+
28
+ const barkapay = new BarkaPay({
29
+ apiKey: process.env.BARKAPAY_API_KEY, // "key_id:secret", copied from your dashboard
30
+ country: 'bf', // default country, overridable per call
31
+ });
32
+
33
+ const payment = await barkapay.payments.create({
34
+ operator: 'ORANGE',
35
+ phone_number: '74000000', // national format, without the country code
36
+ amount: 10000,
37
+ otp: '123456', // only for operators that take the payer's OTP up-front
38
+ order: { id: 'ORDER-2026-001', unique: true },
39
+ });
40
+
41
+ console.log(payment.publicId, payment.status);
42
+ ```
43
+
44
+ CommonJS works too:
45
+
46
+ ```js
47
+ const { BarkaPay } = require('barkapay');
48
+ ```
49
+
50
+ > **Authentication** — pass the raw `key_id:secret` (or `keyId` and `secret` separately).
51
+ > The SDK adds the `Bearer` prefix itself. Keep the key on your server: never ship it
52
+ > in a browser or a mobile app.
53
+
54
+ ### Countries, operators and phone numbers
55
+
56
+ Every call targets one country: `bf` (Burkina Faso), `bj` (Bénin) or `sn` (Sénégal).
57
+ Set a default on the client and override it per call when needed:
58
+
59
+ ```ts
60
+ await barkapay.balance.get({ country: 'sn' });
61
+ await barkapay.ping('bj');
62
+ ```
63
+
64
+ - **Operators** are upper-case codes (`ORANGE`, `MOOV`, `MTN`, `WAVE`); the list for a
65
+ country, with amount bounds and OTP requirement, comes from `operators.info()`.
66
+ - **Phone numbers** are in national format, **without the country code**: 8 digits in
67
+ Burkina Faso, 9 in Sénégal, 10 in Bénin. A number that does not belong to the
68
+ operator is refused with a `ValidationError`.
69
+
70
+ ## Payments
71
+
72
+ ```ts
73
+ // Charge a payer.
74
+ const payment = await barkapay.payments.create({
75
+ operator: 'MOOV',
76
+ phone_number: payerPhone,
77
+ amount: 5000,
78
+ order: { id: 'ORDER-2026-002', unique: true, data: { cart: '42' } },
79
+ });
80
+
81
+ // Look it up later, by its publicId or by your order id.
82
+ await barkapay.payments.get(payment.publicId);
83
+ await barkapay.payments.get('ORDER-2026-002');
84
+ // (An order id shaped like a UUID or containing "/" cannot be used here:
85
+ // filter the list instead — list({ order_id }).)
86
+
87
+ // List, newest first.
88
+ const page = await barkapay.payments.list({
89
+ status: 'SUCCESSFUL',
90
+ per_page: 50,
91
+ page: 1,
92
+ });
93
+ console.log(page.data.length, page.meta?.total);
94
+ ```
95
+
96
+ What happens next depends on the operator — **always branch on `status`**:
97
+
98
+ | `status` | Meaning | What to do |
99
+ | --------------------------------- | ------------------------------------------------------------ | ----------------------------------- |
100
+ | `SUCCESSFUL` | Paid. | Deliver. |
101
+ | `AWAITING_OTP` | The payer received a code by SMS. | Ask for it, then call `confirmOtp`. |
102
+ | `PROCESSING_OPERATOR` | The payer is approving on their phone (or on `redirectUrl`). | Wait for the webhook. |
103
+ | `FAILED` / `EXPIRED` / `CANCELED` | Final, not paid. | See `reasonCode`. |
104
+
105
+ ```ts
106
+ // OTP step, for operators that send the code after creation
107
+ // (today: MOOV in Burkina Faso — these two calls only exist on `bf`).
108
+ // The OTP is a string: a leading zero is significant.
109
+ const confirmed = await barkapay.payments.confirmOtp(publicId, otpFromPayer);
110
+ await barkapay.payments.resendOtp(publicId); // the payer did not get the SMS
111
+ ```
112
+
113
+ `barkapay.operators.info()` tells you, per operator, whether an OTP is required
114
+ (`otp_required`), the amount bounds and the instructions to show the payer.
115
+
116
+ A payment the operator or the payer **refuses** rejects with `PaymentFailedError`;
117
+ the refused payment is on the error:
118
+
119
+ ```ts
120
+ import { PaymentFailedError } from 'barkapay';
121
+
122
+ try {
123
+ await barkapay.payments.create({
124
+ operator: 'ORANGE',
125
+ phone_number: payerPhone,
126
+ amount: 10000,
127
+ otp: '123456',
128
+ order: { id: orderId, unique: true },
129
+ });
130
+ } catch (error) {
131
+ if (error instanceof PaymentFailedError) {
132
+ console.log(error.payment?.publicId, error.payment?.reasonCode); // e.g. "payer_insufficient_funds"
133
+ } else {
134
+ throw error;
135
+ }
136
+ }
137
+ ```
138
+
139
+ List filters: `status`, `operator`, `phone_number`, `channel`, `order_id`, `page`,
140
+ `per_page` (max 200), `amount` **with** `amount_operator` (`<`, `=`, `>`, `<=`, `>=`),
141
+ and `from_date` **with** `to_date` (a date range needs both ends).
142
+
143
+ ### Sending the payer back to your site
144
+
145
+ With an operator that redirects the payer (WAVE in Sénégal today), pass
146
+ `return_url` and, optionally, `cancel_url` to choose where the payer lands
147
+ afterwards. Other operators accept and ignore them.
148
+
149
+ ```ts
150
+ const wave = await barkapay.payments.create(
151
+ {
152
+ operator: 'WAVE',
153
+ phone_number: payerPhone,
154
+ amount: 5000,
155
+ order: { id: orderId },
156
+ return_url: 'https://shop.example/thanks?cart=42', // after the payment
157
+ cancel_url: 'https://shop.example/cart', // after a failure or cancellation
158
+ },
159
+ { country: 'sn' },
160
+ );
161
+ console.log(wave.redirectUrl); // send the payer there
162
+ ```
163
+
164
+ - Absolute `https` URLs only, at most 2000 characters, no `user:pass@`, no
165
+ `#fragment`: the API answers 422 otherwise (`ValidationError`, details in
166
+ `error.errors.return_url`).
167
+ - Leave them out to use the URLs set on your API application, or a barkapay
168
+ page by default. Without `cancel_url`, a failed or cancelled payment goes back
169
+ to `return_url`.
170
+ - The API appends `payment_id` and `order_id` to your URL (your query string is
171
+ kept), never a status. Neither field is returned on the payment.
172
+
173
+ > **The payer coming back is not a proof of payment.** Anyone can open that URL.
174
+ > Fulfil the order on the webhook, or after `barkapay.payments.get(paymentId)`
175
+ > says `SUCCESSFUL`.
176
+
177
+ ## Payment links
178
+
179
+ A payment link is a page on the barkapay-hosted checkout: your customer opens it,
180
+ picks an operator and pays. No checkout to build.
181
+
182
+ ```ts
183
+ const link = await barkapay.paymentLinks.create({
184
+ title: 'Invoice #1234',
185
+ amount: { type: 'fixed', value: 25000 }, // or { type: 'open' } / { type: 'range', min, max }
186
+ usage: 'single', // closed by the first successful payment; 'multi' = reusable
187
+ order: { id: 'INV-1234' },
188
+ redirect: { success_url: 'https://shop.example/thanks' },
189
+ });
190
+
191
+ console.log(link.url); // share it with your customer
192
+ ```
193
+
194
+ ```ts
195
+ await barkapay.paymentLinks.get(linkId); // by "PL-…" id or by slug
196
+ await barkapay.paymentLinks.list({ status: 'active', per_page: 25 });
197
+ await barkapay.paymentLinks.update(linkId, {
198
+ title: 'Invoice #1234 (updated)',
199
+ description: null,
200
+ });
201
+ await barkapay.paymentLinks.pause(linkId); // the checkout refuses new payers
202
+ await barkapay.paymentLinks.resume(linkId);
203
+ await barkapay.paymentLinks.cancel(linkId); // for good
204
+
205
+ // Payments made through the link (in the country you call).
206
+ const paid = await barkapay.paymentLinks.listPayments(linkId, { status: 'SUCCESSFUL' });
207
+ console.log(paid.data.length, paid.paymentLink?.stats.totalCollected);
208
+ ```
209
+
210
+ Only `title`, `description`, `expires_at` and `redirect` can change after creation.
211
+ `pause` and `resume` return the link unchanged when it is not in the expected state:
212
+ check `status` on the result. Payments made through a link carry
213
+ `channel: 'hosted'` and `linkPublicId`.
214
+
215
+ `payments.create` is always a direct payment: the hosted checkout is created
216
+ with `paymentLinks.create` only.
217
+
218
+ ## Transfers
219
+
220
+ ```ts
221
+ const transfer = await barkapay.transfers.create({
222
+ operator: 'ORANGE',
223
+ phone_number: recipientPhone,
224
+ amount: 50000,
225
+ order: { id: 'PAYOUT-2026-001', unique: true },
226
+ });
227
+
228
+ await barkapay.transfers.get(transfer.publicId); // or by your order id
229
+ await barkapay.transfers.list({ from_date: '2026-11-01', to_date: '2026-11-30' });
230
+ ```
231
+
232
+ - `status: 'UNCERTAIN'` means the transfer was accepted but the operator has not
233
+ confirmed yet. **Do not send it again** — the verdict arrives by webhook.
234
+ - The same transfer (same order id, number, amount and operator) sent again within
235
+ 60 seconds is refused with `ConflictError` — even when the first attempt was
236
+ itself refused. Wait a minute, or use a new order id for a new attempt.
237
+ - `list({ status })` accepts neither `UNCERTAIN` nor `UNRESOLVED`: filter those on
238
+ your side.
239
+ - Errors: `InsufficientBalanceError` (top up first), `TransferFailedError`
240
+ (the operator refused; `error.transfer` holds the details).
241
+
242
+ ## Balance & operators
243
+
244
+ ```ts
245
+ const balance = await barkapay.balance.get(); // available / total / holds, as decimal strings
246
+ console.log(balance.available, balance.currency);
247
+
248
+ const { operators } = await barkapay.operators.info(); // authoritative operator list
249
+ const { services } = await barkapay.operators.availability(); // operational / degraded / down
250
+
251
+ await barkapay.ping(); // liveness
252
+ const me = await barkapay.me(); // merchant + API application (scopes, permissions)
253
+ console.log(operators, services, me.api_app?.scopes);
254
+ ```
255
+
256
+ ## Webhooks
257
+
258
+ barkapay POSTs a JSON body to your endpoint when a payment or a transfer reaches a
259
+ final state, signed in the **`Barkapay-Signature`** header
260
+ (`t=<unix time>,v1=<HMAC-SHA256 of "{t}.{raw body}">`, keyed with your `whsec_…` secret).
261
+
262
+ ```ts
263
+ import { createServer } from 'node:http';
264
+ import { parseWebhook, SignatureVerificationError } from 'barkapay';
265
+
266
+ createServer((req, res) => {
267
+ const chunks: Buffer[] = [];
268
+ req.on('data', (chunk: Buffer) => chunks.push(chunk));
269
+ req.on('end', () => {
270
+ try {
271
+ const event = parseWebhook(
272
+ Buffer.concat(chunks), // the RAW body
273
+ req.headers['barkapay-signature'],
274
+ process.env.BARKAPAY_WEBHOOK_SECRET ?? '',
275
+ );
276
+
277
+ if (event.type === 'payment' && event.status === 'SUCCESSFUL') {
278
+ // mark the order `event.order_id` as paid — once per `event.event_id`
279
+ }
280
+ res.writeHead(200).end();
281
+ } catch (error) {
282
+ res.writeHead(error instanceof SignatureVerificationError ? 400 : 500).end();
283
+ }
284
+ });
285
+ }).listen(3000);
286
+ ```
287
+
288
+ **The signature covers the raw bytes of the body.** A body that has been parsed and
289
+ serialised again is different text and will never verify. With Express, that means
290
+ `express.json()` must not run on the webhook route — use `express.raw()` there:
291
+
292
+ ```ts
293
+ import express from 'express';
294
+ import { parseWebhook } from 'barkapay';
295
+
296
+ const app = express();
297
+
298
+ // BEFORE any app.use(express.json()): keep the body as a Buffer on this route.
299
+ app.post('/webhooks/barkapay', express.raw({ type: 'application/json' }), (req, res) => {
300
+ const event = parseWebhook(
301
+ req.body, // a Buffer, thanks to express.raw()
302
+ req.headers['barkapay-signature'],
303
+ process.env.BARKAPAY_WEBHOOK_SECRET ?? '',
304
+ );
305
+ console.log(event.type, event.status, event.public_id);
306
+ res.sendStatus(200);
307
+ });
308
+ ```
309
+
310
+ Passing a parsed object throws a `ConfigurationError` that says so, rather than
311
+ failing silently.
312
+
313
+ Good to know:
314
+
315
+ - There is no `event` field in the body. Derive the event from `type` + `status`:
316
+ `payment` + `SUCCESSFUL` is `payment.succeeded`, `FAILED` is `payment.failed`,
317
+ `EXPIRED` is `payment.expired`; same for `transfer`.
318
+ - Deliveries are **at-least-once**: deduplicate on `event_id`, which is stable
319
+ across re-deliveries.
320
+ - Answer with any `2xx` quickly; anything else is retried with a growing delay.
321
+ - A timestamp more than 300 seconds away from your clock is rejected (replay
322
+ protection). Change it with the 4th argument — a positive number of seconds:
323
+ `0`, a negative or a non-finite value throws a `ConfigurationError`, as does an
324
+ empty secret.
325
+ - `verifyWebhookSignature(rawBody, header, secret)` returns a boolean if you prefer
326
+ to parse the body yourself.
327
+
328
+ ## Errors
329
+
330
+ Every failure throws an error that extends `BarkaPayError`. API errors extend
331
+ `ApiError` and carry `code`, `httpStatus`, `requestId` (quote it to support),
332
+ `errors` (field → messages), `data`, `retryAfter` and `headers` (`retry-after`,
333
+ `x-ratelimit-limit`, `x-ratelimit-remaining`, `x-request-id`). A `NetworkError`
334
+ carries the `requestId` the SDK sent.
335
+
336
+ A `2xx` whose body is not the expected JSON envelope (an HTML page, an empty body,
337
+ a JSON object without the resource) throws an `ApiError` with
338
+ `code: 'invalid_response'` — never an empty object passed off as a success. After a
339
+ create call it means "outcome unknown", not "refused": look the operation up.
340
+
341
+ | Error | HTTP | When |
342
+ | ---------------------------- | --------------- | ------------------------------------------------------------------------ |
343
+ | `ValidationError` | 422 / 400 | Invalid request — see `error.errors`. |
344
+ | `AuthenticationError` | 401 | Missing or wrong API key. |
345
+ | `AuthorizationError` | 403 / 410 / 451 | Missing scope, IP not allowed, account suspended or closed. |
346
+ | `NotFoundError` | 404 | Unknown resource, endpoint or country. |
347
+ | `ConflictError` | 409 | Duplicate (`order.unique`, or the same transfer sent again within 60 s). |
348
+ | `InsufficientBalanceError` | 400 | Your balance does not cover the transfer and its fees. |
349
+ | `PaymentFailedError` | 424 | The payer or the operator refused — `error.payment`. |
350
+ | `TransferFailedError` | 424 | The operator refused — `error.transfer`. |
351
+ | `RateLimitError` | 429 | Too many requests — wait `error.retryAfter` seconds. |
352
+ | `ServiceUnavailableError` | 503 | barkapay or the operator is temporarily unavailable. |
353
+ | `ServerError` | other 5xx | Something broke on our side. |
354
+ | `NetworkError` | — | No response (connection failed, or timed out: `error.timedOut`). |
355
+ | `ConfigurationError` | — | The SDK was called with invalid arguments. |
356
+ | `SignatureVerificationError` | — | A webhook could not be verified. |
357
+
358
+ ```ts
359
+ import { BarkaPayError, RateLimitError, ValidationError } from 'barkapay';
360
+
361
+ try {
362
+ await barkapay.transfers.create({
363
+ operator: 'ORANGE',
364
+ phone_number: recipientPhone,
365
+ amount: 50000,
366
+ order: { id: orderId, unique: true },
367
+ });
368
+ } catch (error) {
369
+ if (error instanceof ValidationError) {
370
+ console.error(error.errors); // { phone_number: ["…"] }
371
+ } else if (error instanceof RateLimitError) {
372
+ console.error(`Retry in ${error.retryAfter ?? '?'} s`);
373
+ } else if (error instanceof BarkaPayError) {
374
+ console.error(error.name, error.message);
375
+ } else {
376
+ throw error;
377
+ }
378
+ }
379
+ ```
380
+
381
+ Failed payments and transfers explain themselves with a stable `reasonCode`
382
+ (`payer_insufficient_funds`, `payer_refused`, `invalid_otp`, `otp_expired`,
383
+ `recipient_invalid`, `operator_unavailable`, …; the full list is exported as
384
+ `REASON_CODES`). Branch on the code; `reason` is its human-readable phrase and
385
+ `providerReason` the operator's own wording, for your support team.
386
+
387
+ ## Retries, timeouts and safe replays
388
+
389
+ - **Timeout** — each attempt is abandoned after `timeoutMs` (40 s by default: the
390
+ hub itself answers 503 after 30 s, so you receive its verdict rather than an
391
+ ambiguous local timeout).
392
+ - **Automatic retries** (`maxRetries`, 2 by default, exponential backoff with
393
+ jitter, `Retry-After` honoured up to 10 s — a longer wait is handed back to you
394
+ as a `RateLimitError` with `retryAfter`):
395
+ - reads (`get`, `list`, `balance`, …) are retried on connection failures,
396
+ timeouts and `429 / 502 / 503 / 504`;
397
+ - writes (`payments.create`, `payments.confirmOtp`, `payments.resendOtp`,
398
+ `transfers.create`, `paymentLinks.create` / `update` / `cancel` / `pause` /
399
+ `resume`) are retried on `429` only — the one answer that guarantees nothing
400
+ was done.
401
+ - **After a timeout or a 5xx on a create call, the outcome is unknown.** The API has
402
+ no idempotency-key header, so the SDK never re-sends it for you. Do this instead:
403
+
404
+ ```ts
405
+ import { ApiError, NetworkError } from 'barkapay';
406
+
407
+ const params = {
408
+ operator: 'ORANGE',
409
+ phone_number: recipientPhone,
410
+ amount: 50000,
411
+ order: { id: orderId, unique: true }, // 1. one order id per operation, declared unique
412
+ };
413
+
414
+ try {
415
+ await barkapay.transfers.create(params);
416
+ } catch (error) {
417
+ const outcomeUnknown =
418
+ error instanceof NetworkError ||
419
+ (error instanceof ApiError && error.httpStatus >= 500);
420
+ if (!outcomeUnknown) throw error;
421
+
422
+ // 2. Did it go through after all? (A failed attempt carries it: error.transfer.)
423
+ const { data } = await barkapay.transfers.list({ order_id: orderId });
424
+ if (data.length > 0) {
425
+ console.log('Already created:', data[0]?.publicId, data[0]?.status);
426
+ } else {
427
+ // 3. It did not: send it again. `unique` guards the race. A ConflictError
428
+ // here means the first attempt reached the API less than 60 seconds ago
429
+ // (still in progress, or refused): wait a minute and check again.
430
+ await barkapay.transfers.create(params);
431
+ }
432
+ }
433
+ ```
434
+
435
+ ## Pagination
436
+
437
+ `list` calls return `{ data, meta }` where `meta` is
438
+ `{ currentPage, lastPage, perPage, total }` (`lastPage` is not returned for
439
+ payment links — compute it from `total` and `perPage`).
440
+
441
+ ```ts
442
+ let page = 1;
443
+ let lastPage = 1;
444
+
445
+ do {
446
+ const { data, meta } = await barkapay.payments.list({ page, per_page: 100 });
447
+ for (const payment of data) {
448
+ console.log(payment.publicId, payment.status);
449
+ }
450
+ lastPage = meta?.lastPage ?? page;
451
+ page += 1;
452
+ } while (page <= lastPage);
453
+ ```
454
+
455
+ ## Configuration
456
+
457
+ ```ts
458
+ import { BarkaPay } from 'barkapay';
459
+
460
+ const client = new BarkaPay({
461
+ apiKey: process.env.BARKAPAY_API_KEY, // or keyId + secret
462
+ country: 'bf',
463
+ baseUrl: 'https://hub.barkapay.com', // default
464
+ timeoutMs: 40000, // per attempt
465
+ maxRetries: 2, // 0 disables automatic retries
466
+ fetch: globalThis.fetch, // any fetch-compatible function (proxy, tests)
467
+ });
468
+ ```
469
+
470
+ `baseUrl` must be `https://`. Plain `http://` is accepted for a loopback host only
471
+ (`localhost`, `127.0.0.1`, `[::1]`) — or, when you pass your own `fetch`, for a mock
472
+ server on another host. It is always refused for a barkapay host.
473
+
474
+ Rate limits apply per route family; every response of the API carries
475
+ `x-ratelimit-limit` and `x-ratelimit-remaining`, and a `429` carries `Retry-After`
476
+ (exposed as `error.retryAfter`, the others as `error.headers`).
477
+
478
+ ## Security notes
479
+
480
+ - The API key is held in private fields: it does not appear in `console.log`,
481
+ `util.inspect` or `JSON.stringify` output, nor in the errors the SDK throws.
482
+ - Redirects are never followed (a `3xx` is an error), so the key cannot be replayed
483
+ against another URL; plain `http://` is refused outside of loopback (see
484
+ Configuration).
485
+ - Identifiers and country codes are validated and encoded before they are placed
486
+ in a URL: an empty identifier, `.`, `..`, or one containing `/`, `?`, `#` or a
487
+ control character is refused before any request; a country code is two letters.
488
+ - A response body larger than 10 MiB is refused (`NetworkError`).
489
+ - Webhook signatures are compared in constant time; verify every delivery before
490
+ trusting it.
491
+
492
+ Report a vulnerability privately — see [SECURITY.md](./SECURITY.md).
493
+
494
+ ## Upgrading from 1.x
495
+
496
+ 2.0 is the same SDK under its final name: the package and a few exports were
497
+ renamed, nothing else changed.
498
+
499
+ ```bash
500
+ npm uninstall barkapay-payhub
501
+ npm install barkapay@^2
502
+ ```
503
+
504
+ - import from `'barkapay'` instead of `'barkapay-payhub'`;
505
+ - `PayHub` → `BarkaPay`, `PayHubOptions` → `BarkaPayOptions`, `PayHubError` →
506
+ `BarkaPayError`;
507
+ - `PayHubRequestInit` / `PayHubResponse` / `PayHubResponseHeaders` →
508
+ `BarkaPayRequestInit` / `BarkaPayResponse` / `BarkaPayResponseHeaders`;
509
+ - the `User-Agent` sent to the API is now `barkapay-node/2.0.0 …`.
510
+
511
+ Still on 1.0? Also read the 1.1 notes in the [changelog](./CHANGELOG.md): writes
512
+ are no longer replayed after a network error, a timeout or a 5xx (they could be
513
+ executed twice), redirects are never followed and the default timeout is 40 s.
514
+
515
+ ## License
516
+
517
+ MIT.