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
@@ -1,118 +1,55 @@
1
- # Biometric authentication adapters
1
+ # Biometric adapters
2
2
 
3
- IskuBixi does not include biometric sensors, vendor SDKs, or biometric
4
- verification endpoints. Its modality methods are available only when the
5
- application configures a trusted adapter that declares support for that method.
6
- The adapter is a security boundary: the SDK cannot independently inspect a
7
- sensor or establish that a provider's statement is true.
3
+ IskuBixi provides adapter interfaces for:
8
4
 
9
- ## What the method names mean
5
+ - `waji`: face
6
+ - `faraha`: fingerprint/thumb
7
+ - `isha`: eye/iris
8
+ - `calaacal`: palm
10
9
 
11
- | Method | Intended modality | Required evidence |
12
- | --- | --- | --- |
13
- | `waji()` | Face | A trusted, documented authenticator or provider verifies face use for this ceremony. |
14
- | `faraha()` | Fingerprint or thumb | A trusted, documented authenticator or provider verifies fingerprint use for this ceremony. |
15
- | `isha()` | Eye or iris | A compatible authenticator/provider explicitly documents and verifies this modality. |
16
- | `calaacal()` | Palm | A compatible authenticator/provider explicitly documents and verifies this modality. |
10
+ The package does not perform hardware capture or universal biometric matching.
11
+ It does not store raw biometric templates or samples.
17
12
 
18
- These are requests, not claims about device support. Unsupported methods must
19
- fail clearly. A phone camera is not an iris or palm authenticator.
20
-
21
- WebAuthn can require user verification, which may involve a device PIN,
22
- fingerprint, face recognition, or another authenticator mechanism. Standard
23
- WebAuthn does not tell the relying party which method the user selected.
24
- Therefore, a generic WebAuthn user-verification result is not proof of face,
25
- fingerprint, iris, or palm use. In particular, ordinary WebAuthn alone cannot
26
- confirm one of these modality-specific payment authorization requests.
27
-
28
- ## Adapter contract
29
-
30
- The package exports `AmaanoodLaqabsade`, `AmaanoodHab`,
31
- `AmaanoodBilowLaqabsade`, and `AmaanoodXaqiijinLaqabsade`. A configured adapter
32
- declares support by listing actual methods in `supportedMethods` and implements
33
- `start()` and `verify()`. For payment authorization it must also set
34
- `supportsPaymentAuthorization: true`; this is an explicit trust declaration,
35
- not proof that the integration is correct.
13
+ ## Register an adapter
36
14
 
37
15
  ```ts
38
- import type { AmaanoodLaqabsade } from "iskubixi";
39
-
40
- declare const trustedVendorAdapter: AmaanoodLaqabsade;
41
-
42
- const configuration = {
43
- bixiyeyaasha: { edahab: { apiKey: process.env.EDAHAB_API_KEY! } },
44
- amaanood: { laqabsadayaal: [trustedVendorAdapter] }
16
+ const adapter: AmaanoodLaqabsade = {
17
+ id: "trusted-face-provider",
18
+ supportedMethods: ["waji"],
19
+ supportsPaymentAuthorization: true,
20
+ async start({ userId, method, paymentBinding }) {
21
+ return {
22
+ options: { ceremony: "face-verification" },
23
+ adapterSessionId: "opaque-adapter-session",
24
+ expiresAt: Date.now() + 60_000
25
+ };
26
+ },
27
+ async verify({ userId, method, adapterSessionId, response, paymentBinding }) {
28
+ return {
29
+ authenticated: true,
30
+ userVerified: true,
31
+ verifiedMethod: "waji"
32
+ };
33
+ }
45
34
  };
46
- ```
47
-
48
- Do not copy the placeholder into a running application. Implement this interface
49
- using the chosen vendor's current official documentation and security guidance:
50
-
51
- 1. In `start()`, bind the authenticated application `userId`, requested method,
52
- short expiry, and (for payments) `paymentBinding` into the vendor/WebAuthn
53
- challenge. Generate fresh unpredictable challenge material.
54
- 2. Return only client-safe ceremony options, an opaque server-side adapter
55
- session reference, and its expiry. Keep credentials and provider secrets on
56
- the backend.
57
- 3. In `verify()`, retrieve the original server-side session and verify its
58
- challenge, user, method, expiry, response signature, and user-verification
59
- result. For payment authorization, verify the exact original
60
- `paymentBinding`.
61
- 4. Return `authenticated: true` and `userVerified: true` only after successful
62
- verification. Set `verifiedMethod` to a biometric method only if the
63
- trusted integration proves that exact method was used. Otherwise return
64
- `"user-verification"` or omit it; the IskuBixi modality API will not set
65
- `methodConfirmed` based on generic user verification.
66
- 5. Persist sessions in an application-owned store with atomic consume semantics
67
- across application instances. Derive `userId` from the backend's
68
- authenticated session, not a browser-supplied identity.
69
-
70
- The `start()` options must never contain a private key, secret, biometric
71
- image, template, or measurement. Do not collect, transmit, log, or store raw
72
- biometric data in IskuBixi. Follow the vendor's privacy and retention rules for
73
- any data handled outside the SDK.
74
35
 
75
- ## Modality-specific expectations
76
-
77
- ### Face
78
-
79
- Use only a compatible, documented authenticator/provider that can verify face
80
- authentication for the current ceremony. A generic WebAuthn assertion can
81
- establish user verification but cannot establish that face, rather than a PIN
82
- or another method, was used. Do not infer face support from a camera or
83
- `userVerification: "required"`.
84
-
85
- ### Fingerprint or thumb
86
-
87
- Use only an authenticator/provider that documents fingerprint use and can
88
- associate it with this verified ceremony. WebAuthn does not disclose whether
89
- the user used a fingerprint or another local verification method. Do not claim
90
- thumb-specific confirmation unless the trusted integration explicitly proves
91
- it.
92
-
93
- ### Eye or iris
94
-
95
- Require a compatible authenticator and documented platform/vendor API that
96
- explicitly establishes eye/iris verification. WebAuthn does not universally
97
- support or identify iris recognition. Do not infer it from a camera, face
98
- verification, or generic user verification. If the capability is absent, do
99
- not advertise or configure `isha`.
100
-
101
- ### Palm
102
-
103
- Require a compatible trusted device/provider with a documented palm
104
- authentication interface and verifiable result. Ordinary phone cameras and
105
- generic WebAuthn do not establish palm recognition. If the integration cannot
106
- prove it, do not advertise or configure `calaacal`.
36
+ const sdk = new IskuBixi({
37
+ bixiyeyaasha: { edahab: { apiKey: "local-demo-only" } },
38
+ allowSimulation: true,
39
+ amaanood: {
40
+ laqabsadayaal: [adapter]
41
+ }
42
+ });
43
+ ```
107
44
 
108
- ## Testing and operations
45
+ Use a trusted adapter that:
109
46
 
110
- Use mocks only in isolated tests and label them as mocks. A mock proves that
111
- application code handles the adapter contract; it does not test hardware,
112
- provider claims, or real-device behavior. Test unsupported methods, failed and
113
- expired sessions, replay, wrong-user attempts, concurrent verification,
114
- storage failures, and privacy of returned data. Conduct a vendor and
115
- real-device security review before enabling an adapter in production.
47
+ - creates an unpredictable user-bound challenge;
48
+ - verifies the exact response and session;
49
+ - verifies user presence/user verification;
50
+ - checks `paymentBinding` when present;
51
+ - never exposes raw biometric data to IskuBixi.
116
52
 
117
- For payment-specific requirements and recovery behavior, see
118
- [Payment authorization](./payment-authorization.md).
53
+ Ordinary WebAuthn user verification may be `"user-verification"` but does not
54
+ prove a named face, fingerprint, eye, or palm modality. Authentication approval
55
+ also does not make a payment successful.
@@ -0,0 +1,57 @@
1
+ # Configuration
2
+
3
+ `IskuBixiQaabeyn` defines provider credentials, adapters, storage, and optional
4
+ authentication adapters.
5
+
6
+ ```ts
7
+ import { IskuBixi, StripePaymentProviderFactory } from "iskubixi";
8
+
9
+ const sdk = new IskuBixi({
10
+ bixiyeyaasha: {
11
+ stripe: { apiKey: process.env.STRIPE_SECRET_KEY! }
12
+ },
13
+ laqabsadayaasha: {
14
+ stripe: new StripePaymentProviderFactory({ environment: "test" })
15
+ }
16
+ });
17
+ ```
18
+
19
+ ## Configuration fields
20
+
21
+ | Field | Purpose |
22
+ |---|---|
23
+ | `bixiyeyaasha` | Provider credentials |
24
+ | `allowSimulation` | Explicit opt-in for local development |
25
+ | `laqabsadayaasha` | Payment provider factories |
26
+ | `laqabsadayaashaWebhook` | Provider webhook adapters |
27
+ | `keydkaIdempotency` | Payment idempotency store |
28
+ | `keydkaCelin` | Refund idempotency store |
29
+ | `keydkaCelinDiiwaanka` | Refund records |
30
+ | `keydkaLacagaha` | Transaction history |
31
+ | `keydkaLacagahaBixiyaha` | Provider payment state used by the simulator |
32
+ | `keydkaQr` | QR records |
33
+ | `keydkaWebhook` | Webhook event and retry state |
34
+ | `keydkaOgolaanshaha` | Payment authorization records |
35
+ | `amaanood` | Passkey and external authentication configuration |
36
+
37
+ ## Environment variables
38
+
39
+ IskuBixi does not load `.env` files automatically. Read variables in the
40
+ application process and pass them to the SDK.
41
+
42
+ ```ts
43
+ const apiKey = process.env.STRIPE_SECRET_KEY;
44
+ if (!apiKey) throw new Error("STRIPE_SECRET_KEY is required");
45
+ ```
46
+
47
+ `.env` is configuration storage, not encryption at rest. Use a deployment
48
+ secret manager and rotate credentials according to provider guidance.
49
+
50
+ ## Environment modes
51
+
52
+ - Stripe test mode requires `sk_test_` and `environment: "test"`.
53
+ - Stripe live mode requires `sk_live_` and `environment: "live"`.
54
+ - PayPal has `sandbox` and `live` factory environments.
55
+ - WaafiPay currently has only `sandbox`.
56
+ - Live legacy provider identifiers require a real adapter and never silently
57
+ fall back to simulation.
@@ -0,0 +1,30 @@
1
+ # Contributing
2
+
3
+ Keep changes focused and preserve public API compatibility.
4
+
5
+ ## Before changes
6
+
7
+ ```sh
8
+ npm ci
9
+ npm test
10
+ ```
11
+
12
+ Add or update tests for behavior changes. Do not delete security, duplicate,
13
+ idempotency, validation, or error-handling coverage.
14
+
15
+ ## Provider changes
16
+
17
+ Use only official provider documentation and authorized merchant credentials.
18
+ Never invent endpoints or response fields. Keep provider-specific credentials
19
+ server-side and redacted.
20
+
21
+ ## Pull requests
22
+
23
+ Include:
24
+
25
+ - summary of behavior and security impact;
26
+ - affected files;
27
+ - unit/mock test coverage;
28
+ - official sandbox/live test evidence if available;
29
+ - documentation updates;
30
+ - package validation results.
@@ -0,0 +1,50 @@
1
+ # Custom providers
2
+
3
+ Implement `PaymentProviderFactory` and `PaymentProvider` for an officially
4
+ documented provider.
5
+
6
+ ```ts
7
+ import type {
8
+ PaymentProvider,
9
+ PaymentProviderFactory,
10
+ ProviderCredentials
11
+ } from "iskubixi";
12
+
13
+ class ApplicationProvider implements PaymentProvider {
14
+ readonly capabilities = {
15
+ paymentCreation: true,
16
+ paymentLookup: true,
17
+ paymentVerification: true,
18
+ paymentCancellation: false,
19
+ refundCreation: false,
20
+ refundStatusLookup: false
21
+ };
22
+
23
+ constructor(private readonly credentials: ProviderCredentials) {}
24
+
25
+ async createPayment(request) {
26
+ // Call the official provider API with server-side credentials.
27
+ throw new Error("Implement against your provider's official API");
28
+ }
29
+
30
+ async findPayment({ paymentId }) {
31
+ // Retrieve and normalize provider state.
32
+ throw new Error(`Implement lookup for ${paymentId}`);
33
+ }
34
+
35
+ async verifyPayment({ paymentId }) {
36
+ // Return exists, payment, and source: "adapter".
37
+ throw new Error(`Implement verification for ${paymentId}`);
38
+ }
39
+ }
40
+
41
+ export const applicationProviderFactory: PaymentProviderFactory = {
42
+ create(credentials) {
43
+ return new ApplicationProvider(credentials);
44
+ }
45
+ };
46
+ ```
47
+
48
+ The custom provider must validate responses, exact payment IDs, amounts,
49
+ currencies, references, terminal states, timeout behavior, idempotency, and
50
+ credential redaction. Do not add an unofficial endpoint or response mapping.
package/docs/errors.md ADDED
@@ -0,0 +1,35 @@
1
+ # Errors
2
+
3
+ All SDK errors extend `IskuBixiError` and expose stable `code` values.
4
+
5
+ | Class | Typical use |
6
+ |---|---|
7
+ | `ConfigurationError` | invalid SDK/provider configuration |
8
+ | `ValidationError` | invalid public input |
9
+ | `PaymentError` | payment operation failure |
10
+ | `ProviderError` | provider response or transport failure |
11
+ | `RefundError` | refund failure |
12
+ | `IdempotencyError` | conflicting duplicate request |
13
+ | `StorageError` | custom storage failure |
14
+ | `WebhookVerificationError` | invalid or untrusted webhook |
15
+ | `UnsupportedOperationError` | provider capability unavailable |
16
+ | `WebAuthnError` | passkey or authentication failure |
17
+
18
+ ```ts
19
+ try {
20
+ await sdk.lacag.samee(request);
21
+ } catch (error) {
22
+ if (error instanceof ValidationError) {
23
+ // Correct application input.
24
+ } else if (error instanceof UnsupportedOperationError) {
25
+ // Select a provider with the required capability.
26
+ } else if (error instanceof ProviderError) {
27
+ // Reconcile provider state; do not assume failure or success.
28
+ } else {
29
+ throw error;
30
+ }
31
+ }
32
+ ```
33
+
34
+ After uncertain network/provider failures, reconcile by payment ID before
35
+ creating a new write.
@@ -0,0 +1,46 @@
1
+ # Examples
2
+
3
+ ## Server initialization
4
+
5
+ See [Getting started](./getting-started.md) and
6
+ [Configuration](./configuration.md).
7
+
8
+ ## Payment
9
+
10
+ ```ts
11
+ const created = await sdk.lacag.samee({
12
+ qadarka: 25,
13
+ lacagta: "USD",
14
+ bixiye: "stripe",
15
+ tixraac: "ORDER-1001",
16
+ furahaIdempotency: "order-1001-create"
17
+ });
18
+
19
+ const status = await sdk.lacag.xaalad({ lacagId: created.id });
20
+ ```
21
+
22
+ ## QR
23
+
24
+ ```ts
25
+ const qr = await sdk.qr.samee({
26
+ qadarka: 20,
27
+ lacagta: "USD",
28
+ bixiye: "edahab",
29
+ lambarka: "252611111111",
30
+ dhacayaa: new Date(Date.now() + 900000).toISOString()
31
+ });
32
+ ```
33
+
34
+ ## Webhook
35
+
36
+ ```ts
37
+ await sdk.webhook.kaShaqee({
38
+ bixiye: "stripe",
39
+ rawBody,
40
+ headers
41
+ });
42
+ ```
43
+
44
+ ## Passkey
45
+
46
+ See [Passkeys](./passkeys.md).
@@ -0,0 +1,64 @@
1
+ # Getting started
2
+
3
+ IskuBixi runs inside your application backend. It does not host payments or
4
+ replace your provider merchant account.
5
+
6
+ ## Requirements
7
+
8
+ - Node.js 20 or later
9
+ - HTTPS for deployed WebAuthn origins
10
+ - A real provider account and credentials, or local simulation
11
+
12
+ ## Install
13
+
14
+ ```sh
15
+ npm install iskubixi
16
+ ```
17
+
18
+ ## Local simulation
19
+
20
+ ```js
21
+ const { IskuBixi } = require("iskubixi");
22
+
23
+ const sdk = new IskuBixi({
24
+ allowSimulation: true,
25
+ bixiyeyaasha: {
26
+ edahab: { apiKey: "local-demo-only" }
27
+ }
28
+ });
29
+ ```
30
+
31
+ Simulation IDs and statuses are not real payment confirmations.
32
+
33
+ ## Real Stripe provider
34
+
35
+ ```ts
36
+ import { IskuBixi, StripePaymentProviderFactory } from "iskubixi";
37
+
38
+ const sdk = new IskuBixi({
39
+ bixiyeyaasha: {
40
+ stripe: { apiKey: process.env.STRIPE_SECRET_KEY! }
41
+ },
42
+ laqabsadayaasha: {
43
+ stripe: new StripePaymentProviderFactory({ environment: "test" })
44
+ }
45
+ });
46
+ ```
47
+
48
+ ## Create a payment
49
+
50
+ ```ts
51
+ const payment = await sdk.lacag.samee({
52
+ qadarka: 25,
53
+ lacagta: "USD",
54
+ bixiye: "stripe",
55
+ tixraac: "ORDER-1001",
56
+ furahaIdempotency: "order-1001-create"
57
+ });
58
+
59
+ console.log(payment.xaalad);
60
+ ```
61
+
62
+ A result can remain pending or contain a provider handoff. Confirm success only
63
+ through provider lookup, verification, capture/confirmation, or a verified
64
+ webhook.
@@ -0,0 +1,26 @@
1
+ # Idempotency
2
+
3
+ Payment creation and confirmation accept idempotency values:
4
+
5
+ ```ts
6
+ const payment = await sdk.lacag.samee({
7
+ qadarka: 25,
8
+ lacagta: "USD",
9
+ bixiye: "stripe",
10
+ tixraac: "ORDER-1001",
11
+ furahaIdempotency: "order-1001-create"
12
+ });
13
+ ```
14
+
15
+ The SDK:
16
+
17
+ - stores an SDK fingerprint for duplicate detection;
18
+ - rejects reuse with changed amount, currency, provider, reference, or expiry;
19
+ - coalesces concurrent identical requests;
20
+ - hashes provider-facing keys and forwards them only when the adapter declares
21
+ provider-side idempotency support.
22
+
23
+ Refund idempotency keys are separate from payment idempotency keys. Confirmation
24
+ keys are also separated.
25
+
26
+ Use a replaceable persistent idempotency store in production.
package/docs/index.md ADDED
@@ -0,0 +1,56 @@
1
+ # IskuBixi documentation
2
+
3
+ IskuBixi is an open-source SDK installed into an application backend. It
4
+ provides payment-provider adapters, payment lifecycle helpers, QR workflows,
5
+ passkey authentication, and adapter-based biometric authorization.
6
+
7
+ ## Start here
8
+
9
+ 1. [Getting started](./getting-started.md)
10
+ 2. [Configuration](./configuration.md)
11
+ 3. [Payments](./payments.md)
12
+ 4. [Providers](./providers.md)
13
+ 5. [Testing](./testing.md)
14
+
15
+ ## Documentation
16
+
17
+ ### Core
18
+
19
+ - [Installation](./installation.md)
20
+ - [Architecture](./architecture.md)
21
+ - [Configuration](./configuration.md)
22
+ - [Payments](./payments.md)
23
+ - [Payment lifecycle](./payment-lifecycle.md)
24
+ - [Payment verification and status](./payment-verification.md)
25
+ - [Refunds](./refunds.md)
26
+ - [Idempotency](./idempotency.md)
27
+
28
+ ### Providers and integrations
29
+
30
+ - [Provider implementations](./providers.md)
31
+ - [Provider development](./provider-development.md)
32
+ - [Custom providers](./custom-providers.md)
33
+ - [QR payments](./qr-payments.md)
34
+ - [Webhooks](./webhooks.md)
35
+ - [Webhook security](./webhook-security.md)
36
+
37
+ ### Authentication
38
+
39
+ - [Authentication overview](./authentication.md)
40
+ - [Passkeys](./passkeys.md)
41
+ - [Biometric adapters](./biometric-adapters.md)
42
+ - [Payment authorization](./payment-authorization.md)
43
+
44
+ ### Operations
45
+
46
+ - [Storage](./storage.md)
47
+ - [Security](./security.md)
48
+ - [Errors](./errors.md)
49
+ - [TypeScript](./typescript.md)
50
+ - [JavaScript](./javascript.md)
51
+ - [Examples](./examples.md)
52
+ - [Troubleshooting](./troubleshooting.md)
53
+ - [API reference](./api-reference.md)
54
+ - [Testing](./testing.md)
55
+ - [Limitations](./limitations.md)
56
+ - [Contributing](./contributing.md)
@@ -0,0 +1,28 @@
1
+ # Installation
2
+
3
+ ## Requirements
4
+
5
+ - Node.js 20 or later
6
+ - npm
7
+ - HTTPS for deployed WebAuthn origins
8
+
9
+ ## npm
10
+
11
+ ```sh
12
+ npm install iskubixi
13
+ ```
14
+
15
+ ## CommonJS
16
+
17
+ ```js
18
+ const { IskuBixi } = require("iskubixi");
19
+ ```
20
+
21
+ ## TypeScript
22
+
23
+ ```ts
24
+ import { IskuBixi } from "iskubixi";
25
+ ```
26
+
27
+ The package is published as CommonJS with TypeScript declarations. It does not
28
+ publish a separate native ESM entry.
@@ -0,0 +1,22 @@
1
+ # JavaScript
2
+
3
+ The package uses CommonJS:
4
+
5
+ ```js
6
+ const {
7
+ IskuBixi,
8
+ StripePaymentProviderFactory
9
+ } = require("iskubixi");
10
+
11
+ const sdk = new IskuBixi({
12
+ bixiyeyaasha: {
13
+ stripe: { apiKey: process.env.STRIPE_SECRET_KEY }
14
+ },
15
+ laqabsadayaasha: {
16
+ stripe: new StripePaymentProviderFactory({ environment: "test" })
17
+ }
18
+ });
19
+ ```
20
+
21
+ There is no separate native ESM build. JavaScript users can also consume the
22
+ package through tools that support require-compatible CommonJS interop.
@@ -0,0 +1,31 @@
1
+ # Limitations
2
+
3
+ ## Provider coverage
4
+
5
+ - Stripe and PayPal have implemented adapters.
6
+ - WaafiPay supports sandbox purchase creation and webhook verification only.
7
+ - EVC, eDahab, Zaad, and banks are not direct public provider adapters.
8
+ - Google Pay is not a processor adapter.
9
+ - Local legacy providers use only explicit simulator behavior or custom adapters.
10
+
11
+ No official sandbox or live provider test is claimed in this repository.
12
+
13
+ ## Credentials
14
+
15
+ The SDK cannot provide merchant accounts or official API credentials. Obtain
16
+ provider documentation and approval for real integration.
17
+
18
+ ## Biometrics
19
+
20
+ The SDK does not perform modality-specific capture or matching. It requires a
21
+ trusted external adapter.
22
+
23
+ ## Storage
24
+
25
+ Default stores are in-memory. Production applications must provide durable,
26
+ atomic application-owned storage.
27
+
28
+ ## Authentication
29
+
30
+ WebAuthn and authentication approval do not establish payment success. Provider
31
+ confirmation remains required.
@@ -0,0 +1,38 @@
1
+ # Passkeys and WebAuthn
2
+
3
+ ## Registration
4
+
5
+ ```ts
6
+ const options = await passkeys.furahaAbuur({
7
+ userId: "user-123",
8
+ userName: "alice",
9
+ displayName: "Alice"
10
+ });
11
+ ```
12
+
13
+ Send `options` to the browser WebAuthn API. Verify the response:
14
+
15
+ ```ts
16
+ const registered = await passkeys.furahaDiiwaangeli({
17
+ userId: "user-123",
18
+ response: browserRegistrationResponse
19
+ });
20
+ ```
21
+
22
+ ## Authentication
23
+
24
+ ```ts
25
+ const options = await passkeys.saxiix({ userId: "user-123" });
26
+ const result = await passkeys.saxiixXaqiiji({
27
+ userId: "user-123",
28
+ response: browserAuthenticationResponse
29
+ });
30
+ ```
31
+
32
+ For HTTPS deployments, `rpId` must match the relying-party hostname and every
33
+ origin must be HTTPS or localhost HTTP. Challenges expire and can be consumed
34
+ only once.
35
+
36
+ Ordinary WebAuthn user verification does not prove that a particular face,
37
+ fingerprint, iris, or palm modality was used. Use a trusted external adapter
38
+ and modality-specific support for that claim.