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
|
@@ -1,118 +1,55 @@
|
|
|
1
|
-
# Biometric
|
|
1
|
+
# Biometric adapters
|
|
2
2
|
|
|
3
|
-
IskuBixi
|
|
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
|
-
|
|
5
|
+
- `waji`: face
|
|
6
|
+
- `faraha`: fingerprint/thumb
|
|
7
|
+
- `isha`: eye/iris
|
|
8
|
+
- `calaacal`: palm
|
|
10
9
|
|
|
11
|
-
|
|
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
|
-
|
|
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
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
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
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
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
|
-
|
|
45
|
+
Use a trusted adapter that:
|
|
109
46
|
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
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
|
-
|
|
118
|
-
|
|
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.
|
package/docs/examples.md
ADDED
|
@@ -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.
|
package/docs/passkeys.md
ADDED
|
@@ -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.
|