iskubixi 1.1.0 → 1.2.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 +26 -0
- package/README.md +125 -720
- package/dist/index.d.ts +6 -2
- package/dist/index.js +9 -1
- package/dist/iskubixi.d.ts +3 -1
- package/dist/iskubixi.js +165 -16
- package/dist/providers/payment-provider.d.ts +17 -0
- package/dist/providers/paypal-payment-provider.d.ts +41 -0
- package/dist/providers/paypal-payment-provider.js +457 -0
- package/dist/providers/provider-http.d.ts +15 -0
- package/dist/providers/provider-http.js +140 -0
- package/dist/providers/stripe-payment-provider.d.ts +43 -0
- package/dist/providers/stripe-payment-provider.js +339 -0
- package/dist/providers/waafipay-payment-provider.d.ts +1 -0
- package/dist/providers/waafipay-payment-provider.js +4 -0
- package/dist/types/configuration.d.ts +3 -1
- package/dist/types/payment.d.ts +7 -1
- package/dist/types/provider-capabilities.d.ts +2 -1
- package/docs/api-reference.md +93 -0
- package/docs/architecture.md +25 -0
- package/docs/authentication.md +36 -0
- package/docs/biometric-adapters.md +44 -107
- package/docs/configuration.md +57 -0
- package/docs/contributing.md +30 -0
- package/docs/custom-providers.md +50 -0
- package/docs/errors.md +35 -0
- package/docs/examples.md +46 -0
- package/docs/getting-started.md +64 -0
- package/docs/idempotency.md +26 -0
- package/docs/index.md +56 -0
- package/docs/installation.md +28 -0
- package/docs/javascript.md +22 -0
- package/docs/limitations.md +31 -0
- package/docs/passkeys.md +38 -0
- package/docs/payment-authorization.md +33 -141
- package/docs/payment-lifecycle.md +34 -0
- package/docs/payment-verification.md +18 -0
- package/docs/payments.md +68 -0
- package/docs/provider-development.md +33 -0
- package/docs/providers.md +123 -0
- package/docs/qr-payments.md +42 -0
- package/docs/refunds.md +20 -0
- package/docs/security.md +37 -0
- package/docs/storage.md +36 -0
- package/docs/testing.md +24 -0
- package/docs/troubleshooting.md +28 -0
- package/docs/typescript.md +25 -0
- package/docs/webhook-security.md +22 -0
- package/docs/webhooks.md +59 -0
- package/examples/javascript/payment-authorization.js +1 -0
- package/examples/typescript/payment-providers.ts +83 -0
- package/package.json +18 -2
package/README.md
CHANGED
|
@@ -2,803 +2,208 @@
|
|
|
2
2
|
|
|
3
3
|
### One SDK. Many Payments. Smarter Authentication.
|
|
4
4
|
|
|
5
|
-

|
|
6
|
-
|
|
7
5
|
**Payments · QR Codes · Face · Fingerprint · Eye · Palm · Passkeys**
|
|
8
6
|
|
|
9
|
-
[ | Public adapter-backed API; compatible trusted adapter required |
|
|
54
|
-
| Fingerprint/thumb (`faraha`) | Public adapter-backed API; compatible trusted adapter required |
|
|
55
|
-
| Eye/iris (`isha`) | Public adapter-backed API; documented compatible hardware/provider required |
|
|
56
|
-
| Palm (`calaacal`) | Public adapter-backed API; documented compatible hardware/provider required |
|
|
57
|
-
|
|
58
|
-
No biometric modality is enabled by default. Ordinary WebAuthn user
|
|
59
|
-
verification alone cannot satisfy a payment authorization for a named
|
|
60
|
-
modality. See [Biometric adapters](./docs/biometric-adapters.md).
|
|
61
|
-
|
|
62
|
-
## Requirements
|
|
63
|
-
|
|
64
|
-
- Node.js 20 or later
|
|
65
|
-
- npm (npm 10 or later recommended)
|
|
66
|
-
- HTTPS for deployed WebAuthn origins; localhost is suitable for local
|
|
67
|
-
development
|
|
7
|
+
[](https://nodejs.org/)
|
|
8
|
+
[](https://www.typescriptlang.org/)
|
|
9
|
+
[](./LICENSE)
|
|
10
|
+
|
|
11
|
+
IskuBixi is an open-source JavaScript and TypeScript SDK for applications that
|
|
12
|
+
need payment-provider routing, QR workflows, passkey authentication, and
|
|
13
|
+
adapter-based biometric authorization.
|
|
14
|
+
|
|
15
|
+
You install the SDK in your backend or application server. You configure your
|
|
16
|
+
own provider accounts and credentials, own your application users and database,
|
|
17
|
+
and control all business decisions. IskuBixi does not require a central API key,
|
|
18
|
+
a hosted IskuBixi payment backend, or an IskuBixi database.
|
|
19
|
+
|
|
20
|
+
## Problems it addresses
|
|
21
|
+
|
|
22
|
+
- A consistent payment API across multiple provider adapters.
|
|
23
|
+
- Explicit provider selection for each payment.
|
|
24
|
+
- Idempotency and duplicate-payment protection.
|
|
25
|
+
- Verified provider and webhook status before marking a payment successful.
|
|
26
|
+
- QR creation, reading, expiry, status, and cancellation.
|
|
27
|
+
- WebAuthn/passkey registration and authentication.
|
|
28
|
+
- External, modality-specific biometric adapters.
|
|
29
|
+
- Payment authorization bound to user, amount, currency, provider, and reference.
|
|
30
|
+
|
|
31
|
+
## Major features
|
|
32
|
+
|
|
33
|
+
| Area | Implemented capability |
|
|
34
|
+
|---|---|
|
|
35
|
+
| Payments | Create, lookup, verify, confirm, list, expire, and refund through the payment API |
|
|
36
|
+
| Providers | Stripe, PayPal, and WaafiPay adapters; custom `PaymentProvider` registration |
|
|
37
|
+
| QR | Create, encode/read, verify, inspect status, and cancel where supported |
|
|
38
|
+
| Passkeys | Server-side WebAuthn registration, authentication, credential listing, and revocation |
|
|
39
|
+
| Biometrics | Adapter interfaces for face, fingerprint, eye, and palm verification |
|
|
40
|
+
| Authorization | Short-lived, exact-payment authorization bound to a verified authentication result |
|
|
41
|
+
| Webhooks | Raw-body signature verification, normalized events, deduplication, retry, and replay protection |
|
|
42
|
+
| Storage | Replaceable in-memory or application-owned stores |
|
|
68
43
|
|
|
69
44
|
## Installation
|
|
70
45
|
|
|
46
|
+
Requires Node.js 20 or later.
|
|
47
|
+
|
|
71
48
|
```sh
|
|
72
49
|
npm install iskubixi
|
|
73
50
|
```
|
|
74
51
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
```js
|
|
78
|
-
const { IskuBixi, Amaanood } = require("iskubixi");
|
|
79
|
-
```
|
|
52
|
+
## Quick example
|
|
80
53
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
```ts
|
|
84
|
-
import { IskuBixi, Amaanood } from "iskubixi";
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
## Quick start
|
|
88
|
-
|
|
89
|
-
This short example uses the built-in **simulated** provider. It creates a
|
|
90
|
-
local pending payment; it does not contact a payment provider or move money.
|
|
54
|
+
The simulator is for local development only. For real providers, register an
|
|
55
|
+
explicit provider factory and keep credentials on the server.
|
|
91
56
|
|
|
92
57
|
### JavaScript
|
|
93
58
|
|
|
94
59
|
```js
|
|
95
60
|
const { IskuBixi } = require("iskubixi");
|
|
96
61
|
|
|
97
|
-
const
|
|
62
|
+
const sdk = new IskuBixi({
|
|
63
|
+
allowSimulation: true,
|
|
98
64
|
bixiyeyaasha: {
|
|
99
|
-
|
|
100
|
-
|
|
65
|
+
edahab: {
|
|
66
|
+
apiKey: "local-demo-only"
|
|
67
|
+
}
|
|
101
68
|
}
|
|
102
69
|
});
|
|
103
70
|
|
|
104
71
|
async function main() {
|
|
105
|
-
const payment = await
|
|
72
|
+
const payment = await sdk.lacag.samee({
|
|
106
73
|
qadarka: 20,
|
|
107
74
|
lacagta: "USD",
|
|
108
75
|
bixiye: "edahab",
|
|
109
|
-
tixraac: "LOCAL-
|
|
76
|
+
tixraac: "LOCAL-ORDER-1",
|
|
77
|
+
furahaIdempotency: "LOCAL-ORDER-1-ATTEMPT-1"
|
|
110
78
|
});
|
|
111
79
|
|
|
112
|
-
|
|
113
|
-
console.log(payment.xaalad); // "sugaya" (pending)
|
|
114
|
-
console.log(verification.xaqiijin); // "simulated"
|
|
80
|
+
console.log(payment.xaalad); // "sugaya"
|
|
115
81
|
}
|
|
116
82
|
|
|
117
|
-
main().catch(
|
|
118
|
-
console.error(error);
|
|
119
|
-
process.exitCode = 1;
|
|
120
|
-
});
|
|
83
|
+
main().catch(console.error);
|
|
121
84
|
```
|
|
122
85
|
|
|
123
86
|
### TypeScript
|
|
124
87
|
|
|
125
88
|
```ts
|
|
126
|
-
import { IskuBixi
|
|
89
|
+
import { IskuBixi } from "iskubixi";
|
|
127
90
|
|
|
128
|
-
const
|
|
91
|
+
const sdk = new IskuBixi({
|
|
92
|
+
allowSimulation: true,
|
|
129
93
|
bixiyeyaasha: {
|
|
130
|
-
edahab: {
|
|
131
|
-
apiKey: process.env.EDAHAB_API_KEY ?? "local-demo-only"
|
|
132
|
-
}
|
|
94
|
+
edahab: { apiKey: "local-demo-only" }
|
|
133
95
|
}
|
|
134
|
-
};
|
|
96
|
+
});
|
|
135
97
|
|
|
136
|
-
const
|
|
137
|
-
const payment = await iskubixi.lacag.samee({
|
|
98
|
+
const payment = await sdk.lacag.samee({
|
|
138
99
|
qadarka: 20,
|
|
139
100
|
lacagta: "USD",
|
|
140
101
|
bixiye: "edahab",
|
|
141
|
-
tixraac: "LOCAL-
|
|
102
|
+
tixraac: "LOCAL-ORDER-1"
|
|
142
103
|
});
|
|
143
|
-
const verification = await iskubixi.lacag.cadee({ lacagId: payment.id });
|
|
144
|
-
|
|
145
|
-
console.log(payment.xaalad, verification.xaqiijin);
|
|
146
104
|
```
|
|
147
105
|
|
|
148
|
-
The
|
|
149
|
-
credentials are configured. Do not interpret its results as real payments.
|
|
150
|
-
To process payments, register a provider adapter that calls the real provider
|
|
151
|
-
and verifies its responses.
|
|
152
|
-
|
|
153
|
-
## Payment providers
|
|
154
|
-
|
|
155
|
-
The public provider contract is `PaymentProvider`; provider factories implement
|
|
156
|
-
`PaymentProviderFactory`. Provider credentials remain server-side.
|
|
157
|
-
|
|
158
|
-
```ts
|
|
159
|
-
import {
|
|
160
|
-
IskuBixi,
|
|
161
|
-
type IskuBixiQaabeyn,
|
|
162
|
-
type PaymentProviderFactory
|
|
163
|
-
} from "iskubixi";
|
|
164
|
-
|
|
165
|
-
// Implement this factory against the provider's current official API.
|
|
166
|
-
declare const applicationProviderFactory: PaymentProviderFactory;
|
|
106
|
+
The published package is CommonJS with TypeScript declarations.
|
|
167
107
|
|
|
168
|
-
|
|
169
|
-
bixiyeyaasha: {
|
|
170
|
-
edahab: { apiKey: process.env.EDAHAB_API_KEY! }
|
|
171
|
-
},
|
|
172
|
-
laqabsadayaasha: {
|
|
173
|
-
edahab: applicationProviderFactory
|
|
174
|
-
}
|
|
175
|
-
};
|
|
108
|
+
## Providers
|
|
176
109
|
|
|
177
|
-
|
|
178
|
-
|
|
110
|
+
| Provider | Actual status |
|
|
111
|
+
|---|---|
|
|
112
|
+
| Stripe | PaymentIntents, lookup, verification, confirmation, cancellation, refunds, and raw-body webhooks |
|
|
113
|
+
| PayPal | Orders, OAuth, capture, lookup, refunds, and remote webhook verification |
|
|
114
|
+
| WaafiPay | Sandbox purchase creation and webhook verification; lookup and refunds are not implemented |
|
|
115
|
+
| EVC | No direct API adapter |
|
|
116
|
+
| eDahab | No direct API adapter |
|
|
117
|
+
| Zaad | No direct API adapter |
|
|
118
|
+
| Banks | No direct API adapters |
|
|
119
|
+
| Google Pay | Processor-dependent architecture only |
|
|
120
|
+
| Simulator | Local development/testing only |
|
|
179
121
|
|
|
180
|
-
|
|
181
|
-
|
|
122
|
+
No official sandbox or live transaction test is claimed without credentials and
|
|
123
|
+
actual evidence. Legacy provider identifiers never silently replace live-mode
|
|
124
|
+
requests with a successful local payment.
|
|
182
125
|
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
The package exports `WaafiPayPaymentProviderFactory`. It sends purchase
|
|
186
|
-
requests to the adapter's configured WaafiPay sandbox endpoint. The adapter
|
|
187
|
-
requires valid sandbox credentials and a timestamp formatter matching the
|
|
188
|
-
provider's current documentation.
|
|
126
|
+
For real Stripe configuration:
|
|
189
127
|
|
|
190
128
|
```ts
|
|
191
|
-
import {
|
|
192
|
-
IskuBixi,
|
|
193
|
-
WaafiPayPaymentProviderFactory
|
|
194
|
-
} from "iskubixi";
|
|
195
|
-
|
|
196
|
-
const waafipay = new WaafiPayPaymentProviderFactory({
|
|
197
|
-
// Return the provider-documented 20-character timestamp format.
|
|
198
|
-
formatTimestamp: providerDocumentedTimestamp
|
|
199
|
-
});
|
|
129
|
+
import { IskuBixi, StripePaymentProviderFactory } from "iskubixi";
|
|
200
130
|
|
|
201
|
-
const
|
|
131
|
+
const sdk = new IskuBixi({
|
|
202
132
|
bixiyeyaasha: {
|
|
203
|
-
|
|
204
|
-
merchantUid: process.env.WAAFI_MERCHANT_UID!,
|
|
205
|
-
apiUserId: process.env.WAAFI_API_USER_ID!,
|
|
206
|
-
apiKey: process.env.WAAFI_API_KEY!
|
|
207
|
-
}
|
|
133
|
+
stripe: { apiKey: process.env.STRIPE_SECRET_KEY! }
|
|
208
134
|
},
|
|
209
|
-
laqabsadayaasha: {
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
lacagta: "USD",
|
|
215
|
-
bixiye: "waafipay",
|
|
216
|
-
tixraac: "ORDER-1002",
|
|
217
|
-
lambarka: process.env.CUSTOMER_WALLET_NUMBER!
|
|
218
|
-
});
|
|
219
|
-
```
|
|
220
|
-
|
|
221
|
-
`providerDocumentedTimestamp` above is supplied by your application; use the
|
|
222
|
-
format required by your provider account and current provider documentation.
|
|
223
|
-
Never put these credentials in frontend code or logs. WaafiPay's bundled
|
|
224
|
-
adapter currently supports payment creation only. It does not claim lookup,
|
|
225
|
-
payment verification, cancellation, refunds, or remote idempotency.
|
|
226
|
-
|
|
227
|
-
## Payments
|
|
228
|
-
|
|
229
|
-
### Create, check, and verify
|
|
230
|
-
|
|
231
|
-
```js
|
|
232
|
-
const payment = await iskubixi.lacag.samee({
|
|
233
|
-
qadarka: 49.99,
|
|
234
|
-
lacagta: "USD",
|
|
235
|
-
bixiye: "edahab",
|
|
236
|
-
tixraac: "ORDER-1001",
|
|
237
|
-
furahaIdempotency: "order-1001-attempt-1",
|
|
238
|
-
dhacayaa: "2026-12-31T23:59:59Z"
|
|
239
|
-
});
|
|
240
|
-
|
|
241
|
-
const current = await iskubixi.lacag.xaalad({ lacagId: payment.id });
|
|
242
|
-
const verification = await iskubixi.lacag.cadee({ lacagId: payment.id });
|
|
243
|
-
|
|
244
|
-
console.log(current.xaalad);
|
|
245
|
-
console.log(verification.xaqiijin); // "adapter" or "simulated"
|
|
246
|
-
```
|
|
247
|
-
|
|
248
|
-
Amounts must be positive finite numbers, currencies three-letter uppercase
|
|
249
|
-
codes, and references non-empty strings. `lambarka` is provider-specific;
|
|
250
|
-
WaafiPay requires a valid wallet number. Expiry is an ISO 8601 date-time with
|
|
251
|
-
timezone and must be supported by the configured transaction store.
|
|
252
|
-
|
|
253
|
-
### Refunds and listing
|
|
254
|
-
|
|
255
|
-
```ts
|
|
256
|
-
const page = await iskubixi.lacag.liiska({
|
|
257
|
-
bixiye: "edahab",
|
|
258
|
-
xaalad: "sugaya",
|
|
259
|
-
lacagta: "USD",
|
|
260
|
-
bogga: 1,
|
|
261
|
-
xadka: 20
|
|
262
|
-
});
|
|
263
|
-
|
|
264
|
-
const refund = await iskubixi.lacag.celi({
|
|
265
|
-
lacagId: "provider-payment-id",
|
|
266
|
-
furahaIdempotency: "refund-order-1001"
|
|
267
|
-
});
|
|
268
|
-
const refundStatus = await iskubixi.lacag.celintaXaalad({
|
|
269
|
-
celinId: refund.id
|
|
135
|
+
laqabsadayaasha: {
|
|
136
|
+
stripe: new StripePaymentProviderFactory({
|
|
137
|
+
environment: "test"
|
|
138
|
+
})
|
|
139
|
+
}
|
|
270
140
|
});
|
|
271
141
|
```
|
|
272
142
|
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
separate.
|
|
276
|
-
|
|
277
|
-
There is no general `lacag.jooji()` method. `qr.jooji()` can cancel a pending
|
|
278
|
-
QR-linked payment only when the configured provider supports cancellation.
|
|
279
|
-
|
|
280
|
-
### Simulated status controls
|
|
281
|
-
|
|
282
|
-
`lacag.tijaabiXaalad({ lacagId, xaalad })` is for simulated payments and tests
|
|
283
|
-
only. It cannot change a real provider payment and must not be used to confirm
|
|
284
|
-
production payments.
|
|
143
|
+
Use `environment: "live"` only with a live key and a production checkout
|
|
144
|
+
verified through provider APIs and webhooks.
|
|
285
145
|
|
|
286
146
|
## QR payments
|
|
287
147
|
|
|
288
|
-
Create a QR payment with an explicit future expiry:
|
|
289
|
-
|
|
290
148
|
```ts
|
|
291
|
-
const qr = await
|
|
292
|
-
qadarka:
|
|
293
|
-
lacagta: "USD",
|
|
294
|
-
bixiye: "edahab",
|
|
295
|
-
dhacayaa: new Date(Date.now() + 15 * 60 * 1000).toISOString()
|
|
296
|
-
});
|
|
297
|
-
|
|
298
|
-
// Render qr.nuxur with your application's QR library.
|
|
299
|
-
console.log(qr.nuxur, qr.tixraac, qr.xaaladQr);
|
|
300
|
-
```
|
|
301
|
-
|
|
302
|
-
The SDK creates the linked payment and a random QR reference. `nuxur` is the
|
|
303
|
-
SDK payload `iskubixi:qr:v1:<reference>`; your frontend may render that string
|
|
304
|
-
as a QR image using its own QR display library. The payload is a reference, not
|
|
305
|
-
a signed proof of payment.
|
|
306
|
-
|
|
307
|
-
JavaScript (inside an async route or function):
|
|
308
|
-
|
|
309
|
-
```js
|
|
310
|
-
const qr = await iskubixi.qr.samee({
|
|
311
|
-
qadarka: 75,
|
|
149
|
+
const qr = await sdk.qr.samee({
|
|
150
|
+
qadarka: 20,
|
|
312
151
|
lacagta: "USD",
|
|
313
152
|
bixiye: "edahab",
|
|
153
|
+
lambarka: "252611111111",
|
|
314
154
|
dhacayaa: new Date(Date.now() + 15 * 60 * 1000).toISOString()
|
|
315
155
|
});
|
|
316
|
-
const activeReference = await iskubixi.qr.cadee({ tixraac: qr.tixraac });
|
|
317
|
-
const scannedPayload = await iskubixi.qr.akhriso({ nuxur: qr.nuxur });
|
|
318
|
-
const status = await iskubixi.qr.xaalad({ tixraac: qr.tixraac });
|
|
319
|
-
```
|
|
320
|
-
|
|
321
|
-
TypeScript validation:
|
|
322
156
|
|
|
323
|
-
|
|
324
|
-
const byReference = await iskubixi.qr.cadee({ tixraac: qr.tixraac });
|
|
325
|
-
const byPayload = await iskubixi.qr.akhriso({ nuxur: qr.nuxur });
|
|
326
|
-
const status = await iskubixi.qr.xaalad({ tixraac: qr.tixraac });
|
|
327
|
-
const details = await iskubixi.qr.xog({ tixraac: qr.tixraac });
|
|
328
|
-
```
|
|
329
|
-
|
|
330
|
-
Validation checks that the reference exists and is still open, not that money
|
|
331
|
-
has been received. `qr.xaalad()` reports both the payment state and QR state.
|
|
332
|
-
QR references can be `furan` (open), `joojiyay` (cancelled), `dhacay` (expired),
|
|
333
|
-
or `laIsticmaalay` (used). Expired, cancelled, and already-used references
|
|
334
|
-
cannot be validated as active.
|
|
335
|
-
|
|
336
|
-
```ts
|
|
337
|
-
const cancelled = await iskubixi.qr.jooji({ tixraac: qr.tixraac });
|
|
157
|
+
const scanned = await sdk.qr.akhriso({ nuxur: qr.nuxur });
|
|
338
158
|
```
|
|
339
159
|
|
|
340
|
-
|
|
341
|
-
provider supports payment cancellation. Scanning or validating a QR code does
|
|
342
|
-
not confirm a successful payment. Check the provider's verified payment status
|
|
343
|
-
or process its authenticated webhook before fulfilling an order.
|
|
160
|
+
QR scanning does not create or fulfill another payment.
|
|
344
161
|
|
|
345
|
-
##
|
|
162
|
+
## Authentication and biometrics
|
|
346
163
|
|
|
347
|
-
`
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
The WebAuthn client must convert JSON-encoded binary fields to browser
|
|
351
|
-
`ArrayBuffer` values and serialize the credential response back to JSON. See
|
|
352
|
-
the [frontend example](./examples/frontend/passkey-authorization.ts) for an
|
|
353
|
-
assertion conversion using native browser APIs.
|
|
164
|
+
`IskuBixi.amaanood.waji`, `faraha`, `isha`, and `calaacal` are adapter-backed
|
|
165
|
+
entry points. The SDK does not include universal face, fingerprint, iris, or
|
|
166
|
+
palm hardware. It does not store raw biometric data.
|
|
354
167
|
|
|
355
|
-
|
|
168
|
+
WebAuthn/passkey operations are available through `Amaanood` and through
|
|
169
|
+
`IskuBixi.amaanood` when external adapters are configured. An authentication
|
|
170
|
+
challenge can authorize a payment only after the exact user, amount, currency,
|
|
171
|
+
provider, and reference are bound and verified.
|
|
356
172
|
|
|
357
|
-
|
|
358
|
-
|
|
173
|
+
Authentication approval is not payment success; the provider or verified
|
|
174
|
+
webhook must confirm the payment.
|
|
359
175
|
|
|
360
|
-
|
|
361
|
-
rpId: "example.com",
|
|
362
|
-
rpName: "Example App",
|
|
363
|
-
origins: ["https://example.com"],
|
|
364
|
-
requireUserVerification: true
|
|
365
|
-
});
|
|
176
|
+
## Security
|
|
366
177
|
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
178
|
+
- Keep provider secrets and webhook secrets in server-side secret management.
|
|
179
|
+
- Never send credentials to browser code.
|
|
180
|
+
- Never log credentials or full provider responses containing secrets.
|
|
181
|
+
- Use HTTPS in deployed WebAuthn origins.
|
|
182
|
+
- Use `lacag.cadee()` or provider/webhook confirmation rather than client success messages.
|
|
183
|
+
- Store idempotency and payment state in durable application-owned storage for production.
|
|
184
|
+
- Use explicit live configuration; `.env` is not encryption at rest.
|
|
373
185
|
|
|
374
|
-
|
|
186
|
+
## Documentation
|
|
375
187
|
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
displayName: authenticatedUser.name
|
|
390
|
-
});
|
|
391
|
-
// Send options to the application frontend and run navigator.credentials.create()
|
|
392
|
-
// through a WebAuthn client that handles JSON/ArrayBuffer conversion.
|
|
393
|
-
|
|
394
|
-
const registration = await amaanood.furahaDiiwaangeli({
|
|
395
|
-
userId: authenticatedUser.id,
|
|
396
|
-
response: registrationResponseFromFrontend
|
|
397
|
-
});
|
|
398
|
-
|
|
399
|
-
const signInOptions = await amaanood.saxiix({
|
|
400
|
-
userId: authenticatedUser.id
|
|
401
|
-
});
|
|
402
|
-
// Send options to the frontend, run navigator.credentials.get(), and return
|
|
403
|
-
// the serialized authentication response to the backend.
|
|
404
|
-
const signedIn = await amaanood.saxiixXaqiiji({
|
|
405
|
-
userId: authenticatedUser.id,
|
|
406
|
-
response: authenticationResponseFromFrontend
|
|
407
|
-
});
|
|
408
|
-
```
|
|
409
|
-
|
|
410
|
-
Use the authenticated application's account ID, not an unauthenticated
|
|
411
|
-
browser-supplied identity. The SDK checks challenges, expiry, replay, origin,
|
|
412
|
-
RP ID, credential ownership, signatures, and user verification. It stores
|
|
413
|
-
credential IDs and public keys for verification—not biometric images or
|
|
414
|
-
templates. Challenges and credentials use in-memory stores by default; replace
|
|
415
|
-
them with durable application-owned stores in production.
|
|
416
|
-
|
|
417
|
-
## Biometric authentication API
|
|
418
|
-
|
|
419
|
-
The following methods are implemented on `iskubixi.amaanood`. Each start method
|
|
420
|
-
accepts `{ userId: string }` and returns
|
|
421
|
-
`Promise<NatiijoAmaanoodBilow>`: a short-lived `sessionId`, requested `method`,
|
|
422
|
-
`expiresAt`, and client-safe adapter `options`.
|
|
423
|
-
|
|
424
|
-
| Public method | Requested method | Available by default? |
|
|
425
|
-
| --- | --- | --- |
|
|
426
|
-
| `iskubixi.amaanood.waji({ userId })` | Face | No; trusted compatible adapter required |
|
|
427
|
-
| `iskubixi.amaanood.faraha({ userId })` | Fingerprint or thumb | No; trusted compatible adapter required |
|
|
428
|
-
| `iskubixi.amaanood.isha({ userId })` | Eye or iris | No; documented compatible hardware/provider required |
|
|
429
|
-
| `iskubixi.amaanood.calaacal({ userId })` | Palm | No; documented compatible hardware/provider required |
|
|
430
|
-
| `iskubixi.amaanood.xaqiiji({ userId, sessionId, response })` | Verify a started adapter session | Uses the adapter stored with that session |
|
|
431
|
-
|
|
432
|
-
The four modality methods and `xaqiiji()` are real exported and implemented
|
|
433
|
-
methods. They do not scan a face, finger, iris, or palm themselves.
|
|
434
|
-
`xaqiiji()` returns a successful authentication only after the configured
|
|
435
|
-
adapter verifies the response and user verification. Its result includes
|
|
436
|
-
`methodConfirmed`; this is true only when the trusted adapter confirms the
|
|
437
|
-
requested modality.
|
|
438
|
-
|
|
439
|
-
Configure an application-owned adapter implementing the exported
|
|
440
|
-
`AmaanoodLaqabsade` interface:
|
|
441
|
-
|
|
442
|
-
```ts
|
|
443
|
-
import {
|
|
444
|
-
IskuBixi,
|
|
445
|
-
type AmaanoodLaqabsade
|
|
446
|
-
} from "iskubixi";
|
|
447
|
-
|
|
448
|
-
declare const trustedAdapter: AmaanoodLaqabsade;
|
|
449
|
-
|
|
450
|
-
const iskubixi = new IskuBixi({
|
|
451
|
-
bixiyeyaasha: { edahab: { apiKey: process.env.EDAHAB_API_KEY! } },
|
|
452
|
-
amaanood: { laqabsadayaal: [trustedAdapter] }
|
|
453
|
-
});
|
|
454
|
-
|
|
455
|
-
const session = await iskubixi.amaanood.waji({
|
|
456
|
-
userId: authenticatedUser.id
|
|
457
|
-
});
|
|
458
|
-
// Return session.options to the application frontend for the adapter ceremony.
|
|
459
|
-
const result = await iskubixi.amaanood.xaqiiji({
|
|
460
|
-
userId: authenticatedUser.id,
|
|
461
|
-
sessionId: session.sessionId,
|
|
462
|
-
response: responseFromFrontend
|
|
463
|
-
});
|
|
464
|
-
if (!result.methodConfirmed) {
|
|
465
|
-
throw new Error("The requested modality was not confirmed.");
|
|
466
|
-
}
|
|
467
|
-
```
|
|
468
|
-
|
|
469
|
-
JavaScript (the adapter must be supplied by your application):
|
|
470
|
-
|
|
471
|
-
```js
|
|
472
|
-
async function authenticateWithFace(userId) {
|
|
473
|
-
const session = await iskubixi.amaanood.waji({ userId });
|
|
474
|
-
const response = await trustedBiometricClient.complete(session.options);
|
|
475
|
-
return iskubixi.amaanood.xaqiiji({
|
|
476
|
-
userId,
|
|
477
|
-
sessionId: session.sessionId,
|
|
478
|
-
response
|
|
479
|
-
});
|
|
480
|
-
}
|
|
481
|
-
```
|
|
482
|
-
|
|
483
|
-
The placeholder adapter above is application-supplied; this package includes no
|
|
484
|
-
vendor or biometric hardware adapter. A generic WebAuthn passkey adapter can
|
|
485
|
-
require user verification, but WebAuthn does not disclose whether the user
|
|
486
|
-
verified with face, fingerprint, PIN, or another authenticator method. Do not
|
|
487
|
-
claim a specific method unless a trusted adapter can establish it. Iris
|
|
488
|
-
recognition is not universally available through WebAuthn. Read the
|
|
489
|
-
[adapter guide](./docs/biometric-adapters.md) before integrating a modality.
|
|
490
|
-
|
|
491
|
-
## Payment authorization
|
|
492
|
-
|
|
493
|
-
Payment authorization binds a trusted, user-verified authentication ceremony to
|
|
494
|
-
one saved payment request. A successful authorization initiates the stored
|
|
495
|
-
payment request; it does **not** mean the provider completed or settled it.
|
|
496
|
-
|
|
497
|
-
```ts
|
|
498
|
-
const authorization = await iskubixi.lacag.ogolaanshoAbuur({
|
|
499
|
-
userId: authenticatedUser.id, // derive on the backend
|
|
500
|
-
lacag: {
|
|
501
|
-
qadarka: order.total,
|
|
502
|
-
lacagta: order.currency,
|
|
503
|
-
bixiye: "edahab",
|
|
504
|
-
tixraac: order.reference
|
|
505
|
-
},
|
|
506
|
-
hab: "waji"
|
|
507
|
-
});
|
|
508
|
-
|
|
509
|
-
// Send the safe summary and authenticationOptions to the frontend.
|
|
510
|
-
const result = await iskubixi.lacag.ogolaanshoXaqiiji({
|
|
511
|
-
userId: authenticatedUser.id, // derive again from the backend session
|
|
512
|
-
authorizationId: authorization.authorizationId,
|
|
513
|
-
response: responseFromFrontend
|
|
514
|
-
});
|
|
515
|
-
|
|
516
|
-
const status = await iskubixi.lacag.ogolaanshoXaalad({
|
|
517
|
-
userId: authenticatedUser.id,
|
|
518
|
-
authorizationId: authorization.authorizationId
|
|
519
|
-
});
|
|
520
|
-
```
|
|
521
|
-
|
|
522
|
-
JavaScript (inside an authenticated backend route):
|
|
523
|
-
|
|
524
|
-
```js
|
|
525
|
-
const authorization = await iskubixi.lacag.ogolaanshoAbuur({
|
|
526
|
-
userId: request.authenticatedUser.id,
|
|
527
|
-
lacag: {
|
|
528
|
-
qadarka: order.total,
|
|
529
|
-
lacagta: order.currency,
|
|
530
|
-
bixiye: "edahab",
|
|
531
|
-
tixraac: order.reference
|
|
532
|
-
},
|
|
533
|
-
hab: "waji"
|
|
534
|
-
});
|
|
535
|
-
response.json(authorization);
|
|
536
|
-
|
|
537
|
-
// In the verification route, derive userId from the backend session again.
|
|
538
|
-
const result = await iskubixi.lacag.ogolaanshoXaqiiji({
|
|
539
|
-
userId: request.authenticatedUser.id,
|
|
540
|
-
authorizationId: request.body.authorizationId,
|
|
541
|
-
response: request.body.authenticationResponse
|
|
542
|
-
});
|
|
543
|
-
```
|
|
544
|
-
|
|
545
|
-
Verification does not accept replacement amount, currency, provider, or
|
|
546
|
-
reference values. The configured adapter must explicitly support payment
|
|
547
|
-
authorization, require user verification, bind the original payment digest,
|
|
548
|
-
and verify the requested modality. Generic WebAuthn user verification alone
|
|
549
|
-
does not meet that modality requirement. Production authorization and
|
|
550
|
-
authentication-session stores must be durable and atomic across application
|
|
551
|
-
instances.
|
|
552
|
-
|
|
553
|
-
Authorization states (`pending`, `verifying`, `authorized`, `failed`,
|
|
554
|
-
`expired`, `processing`, `reconciliation_required`) are separate from payment
|
|
555
|
-
states. If a provider outcome is uncertain, the SDK does not automatically
|
|
556
|
-
retry that authorization; reconcile with provider evidence first. A local
|
|
557
|
-
idempotency key does not guarantee remote provider idempotency. See the full
|
|
558
|
-
[payment authorization guide](./docs/payment-authorization.md).
|
|
559
|
-
|
|
560
|
-
## Webhooks
|
|
561
|
-
|
|
562
|
-
Use a configured `PaymentWebhookAdapter` to authenticate provider signatures.
|
|
563
|
-
The SDK's WaafiPay webhook adapter verifies signatures against the original
|
|
564
|
-
raw request bytes. Preserve those bytes in your HTTP framework; do not parse
|
|
565
|
-
and reserialize the body before verification.
|
|
566
|
-
|
|
567
|
-
```ts
|
|
568
|
-
const event = await iskubixi.webhook.cadee({
|
|
569
|
-
bixiye: "waafipay",
|
|
570
|
-
rawBody: rawRequestBody,
|
|
571
|
-
headers: requestHeaders
|
|
572
|
-
});
|
|
573
|
-
|
|
574
|
-
// For an adapter configured to apply verified events:
|
|
575
|
-
const processed = await iskubixi.webhook.kaShaqee({
|
|
576
|
-
bixiye: "waafipay",
|
|
577
|
-
rawBody: rawRequestBody,
|
|
578
|
-
headers: requestHeaders
|
|
579
|
-
});
|
|
580
|
-
```
|
|
581
|
-
|
|
582
|
-
JavaScript (inside an HTTP handler; preserve the raw request bytes):
|
|
583
|
-
|
|
584
|
-
```js
|
|
585
|
-
const processed = await iskubixi.webhook.kaShaqee({
|
|
586
|
-
bixiye: "waafipay",
|
|
587
|
-
rawBody: rawRequestBytes,
|
|
588
|
-
headers: requestHeaders
|
|
589
|
-
});
|
|
590
|
-
if (processed.horeLooShaqeeyay) {
|
|
591
|
-
console.log("Duplicate delivery was already applied.");
|
|
592
|
-
}
|
|
593
|
-
```
|
|
594
|
-
|
|
595
|
-
`cadee()` verifies and normalizes an event; it does not apply the event.
|
|
596
|
-
`kaShaqee()` verifies and applies supported events with deduplication.
|
|
597
|
-
`fashilmay({ bixiye? })` inspects failed events when the configured webhook
|
|
598
|
-
store supports recovery. `dibUshaqee({ bixiye, dhacdoId, codsi? })` retries a
|
|
599
|
-
failed event only after re-verifying the signed request. Webhook verification
|
|
600
|
-
is not available unless an adapter for that provider is configured.
|
|
601
|
-
|
|
602
|
-
## Provider capabilities and public API reference
|
|
603
|
-
|
|
604
|
-
`await iskubixi.bixiye.awood({ bixiye })` returns
|
|
605
|
-
`Promise<NatiijoBixiyeAwood>` with the configured provider name and capability
|
|
606
|
-
flags: `paymentCreation`, `paymentLookup`, `paymentVerification`,
|
|
607
|
-
`paymentCancellation`, `refundCreation`, `refundStatusLookup`, `qrPayment`,
|
|
608
|
-
and `webhookSignatureVerification`. Inspect these flags; never assume a
|
|
609
|
-
provider supports an operation simply because the SDK method exists.
|
|
610
|
-
|
|
611
|
-
### Payment methods
|
|
612
|
-
|
|
613
|
-
All payment methods are available on `iskubixi.lacag`:
|
|
614
|
-
|
|
615
|
-
| Method | Request type | Return type |
|
|
616
|
-
| --- | --- | --- |
|
|
617
|
-
| `samee(request)` | `CodsiLacag` | `Promise<NatiijoLacag>` |
|
|
618
|
-
| `xaalad({ lacagId })` | `CodsiLacagId` | `Promise<NatiijoLacag>` |
|
|
619
|
-
| `cadee({ lacagId })` | `CodsiLacagId` | `Promise<NatiijoXaqiijin>` |
|
|
620
|
-
| `celi({ lacagId, furahaIdempotency })` | `CodsiCelin` | `Promise<NatiijoCelin>` |
|
|
621
|
-
| `celintaXaalad({ celinId })` | `CodsiCelinXaalad` | `Promise<NatiijoCelin>` |
|
|
622
|
-
| `liiska(filters?)` | `CodsiLiiskaLacag` (optional) | `Promise<NatiijoLiiskaLacag>` |
|
|
623
|
-
| `tijaabiXaalad({ lacagId, xaalad })` | `CodsiTijaabiXaalad` | `Promise<NatiijoLacag>`; simulated payments only |
|
|
624
|
-
| `ogolaanshoAbuur(request)` | `CodsiOgolaanshoAbuur` | `Promise<NatiijoOgolaanshoAbuur>` |
|
|
625
|
-
| `ogolaanshoXaqiiji(request)` | `CodsiOgolaanshoXaqiiji` | `Promise<NatiijoOgolaanshoXaqiiji>` |
|
|
626
|
-
| `ogolaanshoXaalad(request)` | `CodsiOgolaanshoXaalad` | `Promise<NatiijoOgolaanshoXaalad>` |
|
|
627
|
-
|
|
628
|
-
There is no public general payment-cancellation method. Cancellation is
|
|
629
|
-
available only through `qr.jooji()` for a supported pending QR payment.
|
|
630
|
-
|
|
631
|
-
### QR methods
|
|
632
|
-
|
|
633
|
-
All QR methods are available on `iskubixi.qr`:
|
|
634
|
-
|
|
635
|
-
| Method | Request type | Return type |
|
|
636
|
-
| --- | --- | --- |
|
|
637
|
-
| `samee(request)` | `CodsiQrLacag` | `Promise<NatiijoQr>` |
|
|
638
|
-
| `cadee({ tixraac })` | `CodsiQrTixraac` | `Promise<NatiijoQrXaqiijin>` |
|
|
639
|
-
| `akhriso({ nuxur })` | `CodsiQrNuxur` | `Promise<NatiijoQrXaqiijin>` |
|
|
640
|
-
| `xaalad({ tixraac })` | `CodsiQrTixraac` | `Promise<NatiijoQrXaalad>` |
|
|
641
|
-
| `jooji({ tixraac })` | `CodsiQrTixraac` | `Promise<NatiijoQr>` |
|
|
642
|
-
| `xog({ tixraac })` | `CodsiQrTixraac` | `Promise<NatiijoQr>` |
|
|
643
|
-
|
|
644
|
-
### Webhook methods
|
|
645
|
-
|
|
646
|
-
All webhook methods are available on `iskubixi.webhook`:
|
|
647
|
-
|
|
648
|
-
| Method | Request type | Return type |
|
|
649
|
-
| --- | --- | --- |
|
|
650
|
-
| `cadee(request)` | `CodsiWebhook` | `Promise<NatiijoWebhookCadee>` |
|
|
651
|
-
| `kaShaqee(request)` | `CodsiWebhook` | `Promise<NatiijoWebhookShaqeeyay>` |
|
|
652
|
-
| `fashilmay(request?)` | `CodsiWebhookFashilmay` (optional) | `Promise<readonly NatiijoWebhookDhacdoFashilmay[]>` |
|
|
653
|
-
| `dibUshaqee(request)` | `CodsiWebhookDibUshaqee` | `Promise<NatiijoWebhookShaqeeyay>` |
|
|
654
|
-
|
|
655
|
-
### Passkey methods
|
|
656
|
-
|
|
657
|
-
All passkey methods belong to an `Amaanood` instance:
|
|
658
|
-
|
|
659
|
-
| Method | Request type | Return type |
|
|
660
|
-
| --- | --- | --- |
|
|
661
|
-
| `furahaAbuur(request)` | `CodsiFurahaAbuur` | `Promise<PublicKeyCredentialCreationOptionsJSON>` |
|
|
662
|
-
| `furahaDiiwaangeli(request)` | `CodsiFurahaDiiwaangeli` | `Promise<NatiijoFurahaDiiwaangeli>` |
|
|
663
|
-
| `saxiix({ userId })` | `CodsiAmaanoodSaxiix` | `Promise<PublicKeyCredentialRequestOptionsJSON>` |
|
|
664
|
-
| `saxiixXaqiiji(request)` | `CodsiSaxiixXaqiiji` | `Promise<NatiijoSaxiix>` |
|
|
665
|
-
| `furahaLiiska({ userId })` | `CodsiAmaanood` | `Promise<readonly FurahaDiiwaangashan[]>` |
|
|
666
|
-
| `furahaJooji({ userId, credentialId })` | `CodsiAmaanood & { credentialId: string }` | `Promise<boolean>` |
|
|
667
|
-
|
|
668
|
-
The top-level package also exports provider, storage, request/result, webhook,
|
|
669
|
-
authentication-adapter, and error types.
|
|
670
|
-
|
|
671
|
-
## Configuration and storage
|
|
672
|
-
|
|
673
|
-
`IskuBixiQaabeyn` accepts provider credentials, provider factories, webhook
|
|
674
|
-
adapters, authentication adapters, and application-provided stores. The main
|
|
675
|
-
storage configuration fields are:
|
|
676
|
-
|
|
677
|
-
- `keydkaIdempotency`
|
|
678
|
-
- `keydkaOgolaanshaha`
|
|
679
|
-
- `keydkaCelin` and `keydkaCelinDiiwaanka`
|
|
680
|
-
- `keydkaLacagaha` and `keydkaLacagahaBixiyaha`
|
|
681
|
-
- `keydkaQr`
|
|
682
|
-
- `keydkaWebhook`
|
|
683
|
-
- `amaanood.keydkaKulamada`
|
|
684
|
-
|
|
685
|
-
```ts
|
|
686
|
-
import {
|
|
687
|
-
IskuBixi,
|
|
688
|
-
type AmaanoodAuthenticationSessionStore,
|
|
689
|
-
type IskuBixiQaabeyn,
|
|
690
|
-
type PaymentAuthorizationStore
|
|
691
|
-
} from "iskubixi";
|
|
692
|
-
|
|
693
|
-
declare const durableAuthorizationStore: PaymentAuthorizationStore;
|
|
694
|
-
declare const durableAuthenticationSessions: AmaanoodAuthenticationSessionStore;
|
|
695
|
-
|
|
696
|
-
const configuration: IskuBixiQaabeyn = {
|
|
697
|
-
bixiyeyaasha: { edahab: { apiKey: process.env.EDAHAB_API_KEY! } },
|
|
698
|
-
amaanood: {
|
|
699
|
-
laqabsadayaal: [trustedAdapter],
|
|
700
|
-
keydkaKulamada: durableAuthenticationSessions
|
|
701
|
-
},
|
|
702
|
-
keydkaOgolaanshaha: durableAuthorizationStore
|
|
703
|
-
};
|
|
704
|
-
const iskubixi = new IskuBixi(configuration);
|
|
705
|
-
```
|
|
706
|
-
|
|
707
|
-
The default in-memory stores are useful for development and tests only. They
|
|
708
|
-
are lost on restart and do not coordinate between server processes. In
|
|
709
|
-
production, implement the exported store interfaces using your own durable
|
|
710
|
-
database and provide atomic claim, consume, idempotency, and event-processing
|
|
711
|
-
operations as required by each contract.
|
|
712
|
-
|
|
713
|
-
The `Amaanood` constructor additionally accepts `keydkaLoolan` and
|
|
714
|
-
`keydkaFuraha` for WebAuthn challenges and credentials. Protect these records
|
|
715
|
-
and use atomic challenge consumption in production.
|
|
716
|
-
|
|
717
|
-
## Security and privacy
|
|
718
|
-
|
|
719
|
-
- Keep all payment and authentication secrets on the backend.
|
|
720
|
-
- Derive user IDs from your authenticated application session.
|
|
721
|
-
- Use HTTPS and configure exact WebAuthn origins and RP IDs.
|
|
722
|
-
- Require user verification where the operation requires it; user presence
|
|
723
|
-
alone is not user verification.
|
|
724
|
-
- Never treat successful authentication as proof of payment.
|
|
725
|
-
- Verify payment through a capable provider adapter or authenticated webhook.
|
|
726
|
-
- Do not log credential responses, private keys, provider secrets, or signed
|
|
727
|
-
webhook payloads.
|
|
728
|
-
- IskuBixi does not collect or store raw face images, fingerprints, iris scans,
|
|
729
|
-
palm images, biometric templates, or measurements.
|
|
730
|
-
- A trusted external adapter is responsible for any modality-specific claim.
|
|
731
|
-
|
|
732
|
-
## Troubleshooting
|
|
733
|
-
|
|
734
|
-
| Problem | What to check |
|
|
735
|
-
| --- | --- |
|
|
736
|
-
| `UnsupportedOperationError` for a provider operation | Inspect `bixiye.awood()` and configure an adapter that implements the operation |
|
|
737
|
-
| Biometric method is unsupported | Configure a trusted adapter whose `supportedMethods` includes the method |
|
|
738
|
-
| Payment authorization rejects a passkey response | The adapter must require user verification, bind the payment digest, and prove the requested modality |
|
|
739
|
-
| Passkey origin/RP ID validation fails | Match the configured RP ID to the browser domain and allow only the exact HTTPS origin |
|
|
740
|
-
| QR reference is invalid or inactive | Check its exact payload/reference, expiry, cancellation, and current payment status |
|
|
741
|
-
| Webhook verification fails | Preserve the exact raw body and check provider signature headers, secret, and timestamp |
|
|
742
|
-
| Payment becomes `reconciliation_required` | Do not retry; reconcile with provider evidence before taking another payment action |
|
|
743
|
-
| Payment remains pending | Check the provider's authenticated status lookup or webhook; authorization alone is not settlement |
|
|
744
|
-
|
|
745
|
-
Errors extend `IskuBixiError` and expose stable `code` values. Common exports
|
|
746
|
-
include `ConfigurationError`, `ValidationError`, `UnsupportedOperationError`,
|
|
747
|
-
`PaymentError`, `RefundError`, `StorageError`, `WebhookVerificationError`, and
|
|
748
|
-
`WebAuthnError`.
|
|
749
|
-
|
|
750
|
-
## Testing
|
|
751
|
-
|
|
752
|
-
```sh
|
|
753
|
-
npm install
|
|
754
|
-
npm run build
|
|
755
|
-
npm test
|
|
756
|
-
```
|
|
757
|
-
|
|
758
|
-
The tests include mocks for provider/authentication adapters and controlled
|
|
759
|
-
WebAuthn fixtures. They do not represent real payment processing or real
|
|
760
|
-
biometric-device testing. The TypeScript examples are compiled as part of the
|
|
761
|
-
test script.
|
|
762
|
-
|
|
763
|
-
## Production responsibilities and limitations
|
|
764
|
-
|
|
765
|
-
You are responsible for:
|
|
766
|
-
|
|
767
|
-
- user accounts, authorization policy, and recovery
|
|
768
|
-
- provider integrations, credentials, and provider-side payment confirmation
|
|
769
|
-
- durable storage and cross-instance atomicity
|
|
770
|
-
- HTTPS deployment, webhook routing, and raw-body preservation
|
|
771
|
-
- trusted authentication adapters and evidence for any modality-specific claim
|
|
772
|
-
- unsupported-device and lost-authenticator fallback paths
|
|
773
|
-
|
|
774
|
-
The SDK does not provide a hosted service, mandatory database, live integration
|
|
775
|
-
for every provider identifier, or biometric hardware. The bundled WaafiPay
|
|
776
|
-
adapter is sandbox-focused and has limited operations. No generic WebAuthn API
|
|
777
|
-
guarantees iris recognition or identifies which local user-verification method
|
|
778
|
-
was used. Confirm provider and device capabilities from their current official
|
|
779
|
-
documentation before enabling them.
|
|
780
|
-
|
|
781
|
-
## Examples and guides
|
|
782
|
-
|
|
783
|
-
- [JavaScript payment authorization example](./examples/javascript/payment-authorization.js) — explicitly mocked local demo
|
|
784
|
-
- [TypeScript payment authorization example](./examples/typescript/payment-authorization.ts) — strongly typed, explicitly mocked local demo
|
|
785
|
-
- [Frontend passkey authorization example](./examples/frontend/passkey-authorization.ts) — browser WebAuthn ceremony and modality limitations
|
|
786
|
-
- [Payment authorization guide](./docs/payment-authorization.md)
|
|
787
|
-
- [Biometric adapter guide](./docs/biometric-adapters.md)
|
|
188
|
+
- [Documentation index](./docs/index.md)
|
|
189
|
+
- [Getting started](./docs/getting-started.md)
|
|
190
|
+
- [Payments](./docs/payments.md)
|
|
191
|
+
- [Provider integrations](./docs/providers.md)
|
|
192
|
+
- [QR payments](./docs/qr-payments.md)
|
|
193
|
+
- [Webhooks](./docs/webhooks.md)
|
|
194
|
+
- [Authentication](./docs/authentication.md)
|
|
195
|
+
- [Biometric adapters](./docs/biometric-adapters.md)
|
|
196
|
+
- [Payment authorization](./docs/payment-authorization.md)
|
|
197
|
+
- [Storage](./docs/storage.md)
|
|
198
|
+
- [API reference](./docs/api-reference.md)
|
|
199
|
+
- [Testing](./docs/testing.md)
|
|
200
|
+
- [Limitations](./docs/limitations.md)
|
|
788
201
|
|
|
789
202
|
## Contributing
|
|
790
203
|
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
1. Read the existing implementation and public types.
|
|
794
|
-
2. Keep provider capabilities and authentication claims aligned with
|
|
795
|
-
documented behavior.
|
|
796
|
-
3. Add focused tests and update the documentation for public API changes.
|
|
797
|
-
4. Run `npm run build` and `npm test`.
|
|
798
|
-
|
|
799
|
-
Do not include credentials, real customer information, or biometric data in
|
|
800
|
-
issues, tests, examples, or pull requests.
|
|
204
|
+
See [Contributing](./docs/contributing.md). No real credentials or live money
|
|
205
|
+
transactions are needed for normal development; use unit and mock HTTP tests.
|
|
801
206
|
|
|
802
207
|
## License
|
|
803
208
|
|
|
804
|
-
|
|
209
|
+
MIT. See [LICENSE](./LICENSE).
|