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/CHANGELOG.md +191 -0
- package/LICENSE +21 -0
- package/README.md +516 -2
- package/dist/index.cjs +1513 -0
- package/dist/index.d.cts +989 -0
- package/dist/index.d.ts +989 -0
- package/dist/index.mjs +1484 -0
- package/package.json +88 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are documented here. The format is based on
|
|
4
|
+
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project follows
|
|
5
|
+
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
6
|
+
|
|
7
|
+
## [Unreleased]
|
|
8
|
+
|
|
9
|
+
## [2.0.0] - 2026-11-18
|
|
10
|
+
|
|
11
|
+
The SDK takes its final name. 2.0 is a pure rename of 1.1.0: same resources,
|
|
12
|
+
same methods, same retry rules (reads replayed on 429 / 502 / 503 / 504 and
|
|
13
|
+
network errors; writes only on a 429 asking for 10 seconds or less), same
|
|
14
|
+
behaviour.
|
|
15
|
+
|
|
16
|
+
### Added
|
|
17
|
+
|
|
18
|
+
- `PaymentCreateParams` gains the optional `return_url` and `cancel_url` of
|
|
19
|
+
`payments.create`: where an operator that redirects the payer (WAVE in Sénégal
|
|
20
|
+
today) sends them back. Only sent when you pass them; the API validates them
|
|
21
|
+
(absolute `https`, ≤ 2000 characters, no credentials, no fragment — 422
|
|
22
|
+
`ValidationError` otherwise) and appends `payment_id` / `order_id`, never a
|
|
23
|
+
status: the return is not a proof of payment.
|
|
24
|
+
|
|
25
|
+
### Changed (breaking)
|
|
26
|
+
|
|
27
|
+
- npm package `barkapay-payhub` → **`barkapay`**. The old package is deprecated
|
|
28
|
+
and receives no further release.
|
|
29
|
+
- Client class `PayHub` → **`BarkaPay`**; options type `PayHubOptions` →
|
|
30
|
+
**`BarkaPayOptions`**.
|
|
31
|
+
- Base error class `PayHubError` → **`BarkaPayError`**.
|
|
32
|
+
- Transport types `PayHubRequestInit`, `PayHubResponse`,
|
|
33
|
+
`PayHubResponseHeaders` → **`BarkaPayRequestInit`**, **`BarkaPayResponse`**,
|
|
34
|
+
**`BarkaPayResponseHeaders`**.
|
|
35
|
+
- `User-Agent` sent to the API: `barkapay-node/<version> node/<version>`;
|
|
36
|
+
`JSON.stringify(client)` reports `"sdk": "barkapay"`.
|
|
37
|
+
- Repository moved to `github.com/BarkaPay/barkapay-nodejs`; documentation at
|
|
38
|
+
`https://barkapay.com/developers`.
|
|
39
|
+
|
|
40
|
+
### Migrating from 1.x
|
|
41
|
+
|
|
42
|
+
1. `npm uninstall barkapay-payhub && npm install barkapay@^2`
|
|
43
|
+
2. Import from `'barkapay'` instead of `'barkapay-payhub'`.
|
|
44
|
+
3. Rename `PayHub` → `BarkaPay`, `PayHubError` → `BarkaPayError` (and the
|
|
45
|
+
`PayHub*` transport types if you wrote a custom `fetch`).
|
|
46
|
+
|
|
47
|
+
## [1.1.0] - 2026-11-16
|
|
48
|
+
|
|
49
|
+
Backward compatible with 1.0.0: no export was removed or renamed and every 1.0.0
|
|
50
|
+
call site still compiles. Read **Changed** before upgrading — two defaults became
|
|
51
|
+
stricter on purpose.
|
|
52
|
+
|
|
53
|
+
### Security
|
|
54
|
+
|
|
55
|
+
- **A write is no longer replayed on a network failure, a timeout or a 5xx.**
|
|
56
|
+
1.0.0 retried every request — `payments.create` and `transfers.create`
|
|
57
|
+
included — on network errors, 429 and 503. The API has no idempotency-key
|
|
58
|
+
header, so a replay after a timeout could charge a payer or pay a recipient
|
|
59
|
+
twice. Every write (create, confirm/resend OTP, payment-link update / cancel /
|
|
60
|
+
pause / resume) is now retried on 429 only (the request was refused before any
|
|
61
|
+
work), and only when the API asks to wait 10 seconds or less. Reads are retried
|
|
62
|
+
on network failures, timeouts and 429 / 502 / 503 / 504.
|
|
63
|
+
- **Redirects are never followed** (`redirect: 'manual'`). 1.0.0 let the HTTP
|
|
64
|
+
stack follow a 3xx, which carries the `Authorization` header along to a
|
|
65
|
+
same-origin redirect target.
|
|
66
|
+
- **The API key can no longer leak through object dumps.** It used to sit in a
|
|
67
|
+
plain property, so `console.log(client)`, `util.inspect` and `JSON.stringify`
|
|
68
|
+
printed it. It now lives in private fields; dumps show `[redacted]`. Transport
|
|
69
|
+
errors are scrubbed as well.
|
|
70
|
+
- **Path injection closed.** Identifiers and country codes are validated before
|
|
71
|
+
being placed in a URL; `.`, `..`, empty values, control characters, `/`, `?`
|
|
72
|
+
and `#` are refused (1.0.0 only percent-encoded, which leaves dot segments
|
|
73
|
+
intact); a country code is two letters.
|
|
74
|
+
- **Webhook verification hardened**: an empty secret is refused instead of being
|
|
75
|
+
used as an HMAC key, a tolerance of 0 or less (which switched the replay check
|
|
76
|
+
off) is refused, the header is parsed strictly (exactly one numeric `t`,
|
|
77
|
+
well-formed 64-hex `v1` only, bounded size), digests are compared as bytes in
|
|
78
|
+
constant time, and several `v1` values are accepted for secret rotation.
|
|
79
|
+
- API keys containing whitespace, control or non-ASCII characters are refused at
|
|
80
|
+
construction (they could never be valid, and broke the HTTP layer loudly).
|
|
81
|
+
- **No clear-text key.** A plain-`http` `baseUrl` is refused unless it is a
|
|
82
|
+
loopback host (`localhost`, `127.0.0.1`, `[::1]`) or you pass your own `fetch`
|
|
83
|
+
(a mock server; a Node warning `BARKAPAY_INSECURE_BASE_URL` is then emitted
|
|
84
|
+
once); it is always refused for a barkapay host.
|
|
85
|
+
- A response body larger than 10 MiB is refused (`NetworkError`), whether it
|
|
86
|
+
announces its size or streams it.
|
|
87
|
+
|
|
88
|
+
### Added
|
|
89
|
+
|
|
90
|
+
- **Payment links** — `client.paymentLinks`: `create`, `list`, `get`, `update`,
|
|
91
|
+
`cancel`, `pause`, `resume`, `listPayments`, with the `PaymentLink` type.
|
|
92
|
+
- An `object` field on `Payment`, `Transfer` and `PaymentLink`
|
|
93
|
+
(`'payment'` / `'transfer'` / `'payment_link'`).
|
|
94
|
+
- New fields on `Payment` and `Transfer`: `reasonCode` (stable failure code),
|
|
95
|
+
`providerReason`, `providerReference`, plus `linkPublicId` and `redirectUrl`
|
|
96
|
+
on `Payment`. `ReasonCode` / `REASON_CODES` publish the catalogue.
|
|
97
|
+
- New statuses: `EXPIRED` (payments), `UNCERTAIN` (transfers).
|
|
98
|
+
`isPaymentStatusFinal('EXPIRED')` is `true`.
|
|
99
|
+
- New errors: `PaymentFailedError` and `TransferFailedError` (HTTP 424),
|
|
100
|
+
`InsufficientBalanceError` (HTTP 400). They extend `ApiError`.
|
|
101
|
+
- `ApiError.data`, `ApiError.payment` and `ApiError.transfer`: the refused
|
|
102
|
+
payment or transfer the API returns with a failure. `ApiError.retryAfter`:
|
|
103
|
+
the `Retry-After` header, in seconds. `ApiError.headers`: `retry-after`,
|
|
104
|
+
`x-ratelimit-limit`, `x-ratelimit-remaining` and `x-request-id`.
|
|
105
|
+
- `NetworkError.timedOut`, `NetworkError.requestId` (the `X-Request-Id` that was
|
|
106
|
+
sent) and the original error as `cause`.
|
|
107
|
+
- Webhooks: `Barkapay-Signature` is the header to read (constant
|
|
108
|
+
`WEBHOOK_SIGNATURE_HEADER`); the raw body may be a `Buffer` / `Uint8Array`;
|
|
109
|
+
the header may be passed straight from `req.headers`; `parseWebhook` returns a
|
|
110
|
+
typed `WebhookEvent`.
|
|
111
|
+
- Typed list filters (`PaymentListParams`, `TransferListParams`, …) including
|
|
112
|
+
`page`, and typed results for `ping()`, `me()`, `operators.info()` and
|
|
113
|
+
`operators.availability()`.
|
|
114
|
+
- Retries now use exponential backoff **with jitter** and honour `Retry-After`
|
|
115
|
+
(up to 10 s; a longer wait raises `RateLimitError` with `retryAfter` at once);
|
|
116
|
+
502 and 504 are retried for reads.
|
|
117
|
+
- The timeout now also covers reading the response body, and holds even with a
|
|
118
|
+
transport that ignores the abort signal.
|
|
119
|
+
|
|
120
|
+
### Changed
|
|
121
|
+
|
|
122
|
+
- **Default timeout raised from 30 to 40 seconds**, so the SDK receives the
|
|
123
|
+
hub's own answer (it gives a gateway 30 seconds, then answers 503) instead of
|
|
124
|
+
timing out on an unknown outcome.
|
|
125
|
+
- **Retry policy** (see Security). If you relied on `payments.create` or
|
|
126
|
+
`transfers.create` being retried automatically after a 503 or a network
|
|
127
|
+
error, handle it explicitly: look the operation up with
|
|
128
|
+
`list({ order_id })`, then decide. Use `order.unique: true`.
|
|
129
|
+
- **Stricter input validation**: an invalid country code, a malformed `baseUrl`,
|
|
130
|
+
a non-positive `timeoutMs` or an identifier such as `..` now throws a
|
|
131
|
+
`ConfigurationError` instead of producing a request that could only fail.
|
|
132
|
+
- `verifyWebhookSignature` / `parseWebhook` throw a `ConfigurationError` when
|
|
133
|
+
given a parsed object instead of the raw body, or an empty secret (1.0.0
|
|
134
|
+
returned `false`, hiding the mistake).
|
|
135
|
+
- A 2xx response whose body is empty or not a JSON object, or that lacks the
|
|
136
|
+
`data` the call must return (`ping()`, `me()`, `balance.get()`,
|
|
137
|
+
`operators.*` and every list included), now throws an `ApiError` with
|
|
138
|
+
`code: 'invalid_response'` instead of yielding an empty object or an empty
|
|
139
|
+
page.
|
|
140
|
+
- `fees` is always a string, also when the API sends the number `0`.
|
|
141
|
+
- Boolean query parameters are sent as `1` / `0`.
|
|
142
|
+
- The `User-Agent` is now `barkapay-payhub-node/<version> node/<node version>`.
|
|
143
|
+
- Documentation, error messages and examples use the brand name “barkapay”.
|
|
144
|
+
Package, class and export names are unchanged.
|
|
145
|
+
|
|
146
|
+
### Behaviour changes to check when upgrading
|
|
147
|
+
|
|
148
|
+
- Writes are no longer re-sent after a 503, a 5xx or a network error (see
|
|
149
|
+
Security): handle `ServiceUnavailableError`, `ServerError` and `NetworkError`
|
|
150
|
+
yourself, after checking with `list({ order_id })` that the operation was not
|
|
151
|
+
recorded.
|
|
152
|
+
- A `Retry-After` above 10 s is no longer slept on: `RateLimitError` is thrown at
|
|
153
|
+
once with `retryAfter`.
|
|
154
|
+
- A plain-`http` `baseUrl` on a non-loopback host now throws a
|
|
155
|
+
`ConfigurationError` unless you pass your own `fetch`.
|
|
156
|
+
- `verifyWebhookSignature` / `parseWebhook` throw a `ConfigurationError` for an
|
|
157
|
+
empty secret, a parsed body, or a tolerance of 0 or less (0 used to switch the
|
|
158
|
+
replay check off).
|
|
159
|
+
- An identifier containing `/`, `?` or `#` throws a `ConfigurationError` before
|
|
160
|
+
any request.
|
|
161
|
+
|
|
162
|
+
### Fixed
|
|
163
|
+
|
|
164
|
+
- `VERSION` (and therefore the `User-Agent`) reported `0.1.0` in the 1.0.0
|
|
165
|
+
package.
|
|
166
|
+
- A failed or timed-out body read surfaced as a raw `DOMException` instead of a
|
|
167
|
+
`NetworkError`.
|
|
168
|
+
- `README`: `transfers.list({ from_date })` alone was shown as a working filter;
|
|
169
|
+
the API only applies a date range when both `from_date` and `to_date` are sent.
|
|
170
|
+
- `README` and examples: the sample phone number (`50123456789`) was one the API
|
|
171
|
+
rejects. Numbers are in national format, without the country code; the payout
|
|
172
|
+
example no longer hard-codes a recipient.
|
|
173
|
+
- The type-check step failed on a clean checkout (the examples imported the
|
|
174
|
+
package under a name the compiler could not resolve before a build).
|
|
175
|
+
|
|
176
|
+
## [1.0.0] - 2026-06-28
|
|
177
|
+
|
|
178
|
+
### Added
|
|
179
|
+
|
|
180
|
+
- Initial Node.js / TypeScript SDK: `PayHub` client with `payments`, `transfers`,
|
|
181
|
+
`balance`, `operators` resources plus `ping()` / `me()`.
|
|
182
|
+
- Typed DTOs (`Payment`, `Transfer`, `Balance`, `Pagination`) and status string unions.
|
|
183
|
+
- Webhook signature verification (`verifyWebhookSignature` / `parseWebhook`).
|
|
184
|
+
- Typed error hierarchy mapped from the API error envelope.
|
|
185
|
+
- Zero runtime dependencies: global `fetch` + `node:crypto`, automatic retries on
|
|
186
|
+
429/503/network. Dual ESM + CJS + type-definition build.
|
|
187
|
+
|
|
188
|
+
[Unreleased]: https://github.com/BarkaPay/barkapay-nodejs/compare/v2.0.0...HEAD
|
|
189
|
+
[2.0.0]: https://github.com/BarkaPay/barkapay-nodejs/compare/v1.1.0...v2.0.0
|
|
190
|
+
[1.1.0]: https://github.com/BarkaPay/barkapay-nodejs/compare/f8c3be6...v1.1.0
|
|
191
|
+
[1.0.0]: https://www.npmjs.com/package/barkapay-payhub/v/1.0.0
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 BarkaPay
|
|
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.
|