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.
Files changed (52) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/README.md +125 -720
  3. package/dist/index.d.ts +6 -2
  4. package/dist/index.js +9 -1
  5. package/dist/iskubixi.d.ts +3 -1
  6. package/dist/iskubixi.js +165 -16
  7. package/dist/providers/payment-provider.d.ts +17 -0
  8. package/dist/providers/paypal-payment-provider.d.ts +41 -0
  9. package/dist/providers/paypal-payment-provider.js +457 -0
  10. package/dist/providers/provider-http.d.ts +15 -0
  11. package/dist/providers/provider-http.js +140 -0
  12. package/dist/providers/stripe-payment-provider.d.ts +43 -0
  13. package/dist/providers/stripe-payment-provider.js +339 -0
  14. package/dist/providers/waafipay-payment-provider.d.ts +1 -0
  15. package/dist/providers/waafipay-payment-provider.js +4 -0
  16. package/dist/types/configuration.d.ts +3 -1
  17. package/dist/types/payment.d.ts +7 -1
  18. package/dist/types/provider-capabilities.d.ts +2 -1
  19. package/docs/api-reference.md +93 -0
  20. package/docs/architecture.md +25 -0
  21. package/docs/authentication.md +36 -0
  22. package/docs/biometric-adapters.md +44 -107
  23. package/docs/configuration.md +57 -0
  24. package/docs/contributing.md +30 -0
  25. package/docs/custom-providers.md +50 -0
  26. package/docs/errors.md +35 -0
  27. package/docs/examples.md +46 -0
  28. package/docs/getting-started.md +64 -0
  29. package/docs/idempotency.md +26 -0
  30. package/docs/index.md +56 -0
  31. package/docs/installation.md +28 -0
  32. package/docs/javascript.md +22 -0
  33. package/docs/limitations.md +31 -0
  34. package/docs/passkeys.md +38 -0
  35. package/docs/payment-authorization.md +33 -141
  36. package/docs/payment-lifecycle.md +34 -0
  37. package/docs/payment-verification.md +18 -0
  38. package/docs/payments.md +68 -0
  39. package/docs/provider-development.md +33 -0
  40. package/docs/providers.md +123 -0
  41. package/docs/qr-payments.md +42 -0
  42. package/docs/refunds.md +20 -0
  43. package/docs/security.md +37 -0
  44. package/docs/storage.md +36 -0
  45. package/docs/testing.md +24 -0
  46. package/docs/troubleshooting.md +28 -0
  47. package/docs/typescript.md +25 -0
  48. package/docs/webhook-security.md +22 -0
  49. package/docs/webhooks.md +59 -0
  50. package/examples/javascript/payment-authorization.js +1 -0
  51. package/examples/typescript/payment-providers.ts +83 -0
  52. 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
- ![IskuBixi logo](./assets/iskubixi-logo.svg)
6
-
7
5
  **Payments · QR Codes · Face · Fingerprint · Eye · Palm · Passkeys**
8
6
 
9
- [![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
10
- [![TypeScript](https://img.shields.io/badge/TypeScript-ready-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
11
- [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
12
-
13
- IskuBixi is a Somali-first JavaScript and TypeScript SDK that gives developers
14
- a unified way to integrate payment providers, QR payment workflows, and secure
15
- authentication into their applications.
16
-
17
- **IskuBixi is a developer SDK, not a hosted payment platform.** You own your
18
- application, user accounts, provider credentials, database, authentication
19
- sessions, and deployment. The SDK does not host payments or collect raw
20
- biometric data.
21
-
22
- > **Biometric support is adapter-based.** IskuBixi includes no face,
23
- > fingerprint, iris, or palm scanner. WebAuthn can request device user
24
- > verification, but it does not tell the application whether the user chose
25
- > face, fingerprint, PIN, or another method. Modality-specific claims require
26
- > a trusted adapter that can prove that method.
27
-
28
- ## Features
29
-
30
- | Area | What the SDK provides |
31
- | --- | --- |
32
- | Payments | A common API for creating, checking, verifying, listing, and refunding payments |
33
- | Provider adapters | A `PaymentProvider` contract, capability inspection, and a sandbox-focused WaafiPay adapter |
34
- | QR payments | Expiring QR references, payload reading, validation, status, and supported cancellation |
35
- | Passkeys | WebAuthn registration, assertion verification, credential listing, and revocation |
36
- | Biometric adapters | Modality-specific entry points for face, fingerprint/thumb, eye/iris, and palm when a trusted adapter supports them |
37
- | Payment authorization | One-time authentication bound to the exact saved payment request |
38
- | Webhooks | Provider signature verification, event processing, failure inspection, and retry |
39
- | Reliability | Local idempotency, transaction listing, replaceable storage contracts, and separate payment/authentication states |
40
-
41
- ### Provider and modality reality check
42
-
43
- The package accepts these provider identifiers: `edahab`, `evc`, `zaad`,
44
- `bank`, and `waafipay`. An identifier is not a bundled live provider
45
- integration. When no provider adapter is registered, the SDK uses its
46
- **simulated provider**. The included WaafiPay adapter is sandbox-focused; it
47
- does not claim transaction lookup, verification, refunds, cancellation, or
48
- documented provider-side idempotency.
49
-
50
- | Authentication request | Included capability |
51
- | --- | --- |
52
- | Passkey registration and sign-in | Server-side WebAuthn options and verification through `Amaanood` |
53
- | Face (`waji`) | 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
+ [![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-339933)](https://nodejs.org/)
8
+ [![TypeScript](https://img.shields.io/badge/TypeScript-ready-3178C6)](https://www.typescriptlang.org/)
9
+ [![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](./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
- CommonJS:
76
-
77
- ```js
78
- const { IskuBixi, Amaanood } = require("iskubixi");
79
- ```
52
+ ## Quick example
80
53
 
81
- TypeScript / ES modules:
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 iskubixi = new IskuBixi({
62
+ const sdk = new IskuBixi({
63
+ allowSimulation: true,
98
64
  bixiyeyaasha: {
99
- // The local fallback value is not a credential and does not connect to eDahab.
100
- edahab: { apiKey: process.env.EDAHAB_API_KEY || "local-demo-only" }
65
+ edahab: {
66
+ apiKey: "local-demo-only"
67
+ }
101
68
  }
102
69
  });
103
70
 
104
71
  async function main() {
105
- const payment = await iskubixi.lacag.samee({
72
+ const payment = await sdk.lacag.samee({
106
73
  qadarka: 20,
107
74
  lacagta: "USD",
108
75
  bixiye: "edahab",
109
- tixraac: "LOCAL-DEMO-1"
76
+ tixraac: "LOCAL-ORDER-1",
77
+ furahaIdempotency: "LOCAL-ORDER-1-ATTEMPT-1"
110
78
  });
111
79
 
112
- const verification = await iskubixi.lacag.cadee({ lacagId: payment.id });
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((error) => {
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, type IskuBixiQaabeyn } from "iskubixi";
89
+ import { IskuBixi } from "iskubixi";
127
90
 
128
- const configuration: IskuBixiQaabeyn = {
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 iskubixi = new IskuBixi(configuration);
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-DEMO-1"
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 default provider is a simulator, even when a provider name and placeholder
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
- const configuration: IskuBixiQaabeyn = {
169
- bixiyeyaasha: {
170
- edahab: { apiKey: process.env.EDAHAB_API_KEY! }
171
- },
172
- laqabsadayaasha: {
173
- edahab: applicationProviderFactory
174
- }
175
- };
108
+ ## Providers
176
109
 
177
- const iskubixi = new IskuBixi(configuration);
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
- IskuBixi does not include live eDahab, EVC, ZAAD, or bank integrations. Do not
181
- register a placeholder adapter as a real provider.
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
- ### WaafiPay sandbox adapter
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 iskubixi = new IskuBixi({
131
+ const sdk = new IskuBixi({
202
132
  bixiyeyaasha: {
203
- waafipay: {
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: { waafipay }
210
- });
211
-
212
- const payment = await iskubixi.lacag.samee({
213
- qadarka: 10,
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
- Only full refunds are accepted. Refund support and refund-status lookup depend
274
- on the provider adapter. The returned payment state and refund state are
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 iskubixi.qr.samee({
292
- qadarka: 75,
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
- ```ts
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
- Cancellation works only while the linked payment is pending and only if the
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
- ## Passkeys and WebAuthn
162
+ ## Authentication and biometrics
346
163
 
347
- `Amaanood` provides server-side WebAuthn/passkey registration options,
348
- authentication options, response verification, credential listing, and
349
- revocation. The browser or mobile application runs the user-facing ceremony.
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
- JavaScript (server-side; browser responses come from your WebAuthn client):
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
- ```js
358
- const { Amaanood } = require("iskubixi");
173
+ Authentication approval is not payment success; the provider or verified
174
+ webhook must confirm the payment.
359
175
 
360
- const amaanood = new Amaanood({
361
- rpId: "example.com",
362
- rpName: "Example App",
363
- origins: ["https://example.com"],
364
- requireUserVerification: true
365
- });
176
+ ## Security
366
177
 
367
- async function passkeySignIn(user) {
368
- const options = await amaanood.saxiix({ userId: user.id });
369
- const response = await sendOptionsToBrowserAndGetAssertion(options);
370
- return amaanood.saxiixXaqiiji({ userId: user.id, response });
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
- TypeScript registration and sign-in:
186
+ ## Documentation
375
187
 
376
- ```ts
377
- import { Amaanood } from "iskubixi";
378
-
379
- const amaanood = new Amaanood({
380
- rpId: "example.com",
381
- rpName: "Example App",
382
- origins: ["https://example.com"],
383
- requireUserVerification: true
384
- });
385
-
386
- const registrationOptions = await amaanood.furahaAbuur({
387
- userId: authenticatedUser.id,
388
- userName: authenticatedUser.email,
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
- Contributions are welcome. Before opening a change:
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
- IskuBixi is licensed under the [MIT License](./LICENSE).
209
+ MIT. See [LICENSE](./LICENSE).