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 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.