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
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# TypeScript
|
|
2
|
+
|
|
3
|
+
Import runtime classes normally and use `import type` for declarations:
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
import {
|
|
7
|
+
IskuBixi,
|
|
8
|
+
StripePaymentProviderFactory,
|
|
9
|
+
type IskuBixiQaabeyn
|
|
10
|
+
} from "iskubixi";
|
|
11
|
+
|
|
12
|
+
const config: IskuBixiQaabeyn = {
|
|
13
|
+
bixiyeyaasha: {
|
|
14
|
+
stripe: { apiKey: process.env.STRIPE_SECRET_KEY! }
|
|
15
|
+
},
|
|
16
|
+
laqabsadayaasha: {
|
|
17
|
+
stripe: new StripePaymentProviderFactory({ environment: "test" })
|
|
18
|
+
}
|
|
19
|
+
};
|
|
20
|
+
|
|
21
|
+
const sdk = new IskuBixi(config);
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
The package publishes declarations under `dist/index.d.ts` and its package
|
|
25
|
+
entry points resolve to `dist/index.js` and `dist/index.d.ts`.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Webhook security
|
|
2
|
+
|
|
3
|
+
Provider adapters must authenticate raw bytes before parsing provider JSON.
|
|
4
|
+
Never verify a re-serialized or reformatted request body.
|
|
5
|
+
|
|
6
|
+
## Required controls
|
|
7
|
+
|
|
8
|
+
- exact provider signature validation;
|
|
9
|
+
- timestamp/replay tolerance where the provider format supports it;
|
|
10
|
+
- event ID deduplication;
|
|
11
|
+
- exact payment ID, amount, currency, and reference matching;
|
|
12
|
+
- terminal status transition validation;
|
|
13
|
+
- refund event normalization;
|
|
14
|
+
- retry only from the original signed request;
|
|
15
|
+
- secret-safe error handling.
|
|
16
|
+
|
|
17
|
+
Webhook success is not sufficient by itself if the event details do not match
|
|
18
|
+
the locally stored payment.
|
|
19
|
+
|
|
20
|
+
Stripe uses its official Node SDK signature constructor. PayPal verifies
|
|
21
|
+
signatures through PayPal's verification API. WaafiPay uses its separate
|
|
22
|
+
timestamp and HMAC adapter.
|
package/docs/webhooks.md
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# Webhooks
|
|
2
|
+
|
|
3
|
+
Configure one signature-verifying adapter per provider.
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
const sdk = new IskuBixi({
|
|
7
|
+
bixiyeyaasha: {
|
|
8
|
+
stripe: { apiKey: process.env.STRIPE_SECRET_KEY! }
|
|
9
|
+
},
|
|
10
|
+
laqabsadayaasha: {
|
|
11
|
+
stripe: new StripePaymentProviderFactory({ environment: "test" })
|
|
12
|
+
},
|
|
13
|
+
laqabsadayaashaWebhook: {
|
|
14
|
+
stripe: new StripeWebhookAdapter({
|
|
15
|
+
secret: process.env.STRIPE_WEBHOOK_SECRET!
|
|
16
|
+
})
|
|
17
|
+
},
|
|
18
|
+
keydkaWebhook: new InMemoryWebhookEventStore()
|
|
19
|
+
});
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Verify only
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
const verification = await sdk.webhook.cadee({
|
|
26
|
+
bixiye: "stripe",
|
|
27
|
+
rawBody: requestBody,
|
|
28
|
+
headers: requestHeaders
|
|
29
|
+
});
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Verify and apply
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
const result = await sdk.webhook.kaShaqee({
|
|
36
|
+
bixiye: "stripe",
|
|
37
|
+
rawBody: requestBody,
|
|
38
|
+
headers: requestHeaders
|
|
39
|
+
});
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
The implementation verifies the provider signature before parsing or applying
|
|
43
|
+
events. Stripe and other adapters require the unchanged raw request bytes.
|
|
44
|
+
Events are deduplicated and conflicting terminal transitions are rejected.
|
|
45
|
+
|
|
46
|
+
## Retry failures
|
|
47
|
+
|
|
48
|
+
```ts
|
|
49
|
+
const failed = await sdk.webhook.fashilmay({ bixiye: "stripe" });
|
|
50
|
+
|
|
51
|
+
const retried = await sdk.webhook.dibUshaqee({
|
|
52
|
+
bixiye: "stripe",
|
|
53
|
+
dhacdoId: "evt_123",
|
|
54
|
+
codsi: originalWebhookRequest
|
|
55
|
+
});
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
A retry requires an recoverable webhook store and re-verifies the original
|
|
59
|
+
signed request.
|
|
@@ -60,6 +60,7 @@ function createDemoAuthenticationAdapter() {
|
|
|
60
60
|
}
|
|
61
61
|
|
|
62
62
|
const iskubixi = new IskuBixi({
|
|
63
|
+
allowSimulation: true,
|
|
63
64
|
bixiyeyaasha: {
|
|
64
65
|
// The SDK's default provider is simulated. This value does not connect to eDahab.
|
|
65
66
|
edahab: { apiKey: process.env.EDAHAB_API_KEY || "local-demo-not-a-secret" }
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
import {
|
|
2
|
+
IskuBixi,
|
|
3
|
+
PayPalPaymentProviderFactory,
|
|
4
|
+
PayPalWebhookAdapter,
|
|
5
|
+
StripePaymentProviderFactory,
|
|
6
|
+
StripeWebhookAdapter,
|
|
7
|
+
type IskuBixi as IskuBixiInstance,
|
|
8
|
+
type WebhookHeaders
|
|
9
|
+
} from "iskubixi";
|
|
10
|
+
|
|
11
|
+
function requiredEnvironment(name: string): string {
|
|
12
|
+
const value = process.env[name];
|
|
13
|
+
if (typeof value !== "string" || value.trim() === "") {
|
|
14
|
+
throw new Error(`Missing required environment variable: ${name}`);
|
|
15
|
+
}
|
|
16
|
+
return value;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
function createProviderSdkFromEnvironment(): IskuBixiInstance {
|
|
20
|
+
const paypalEnvironment = requiredEnvironment("PAYPAL_ENVIRONMENT");
|
|
21
|
+
if (paypalEnvironment !== "sandbox" && paypalEnvironment !== "live") {
|
|
22
|
+
throw new Error("PAYPAL_ENVIRONMENT must be sandbox or live.");
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
const paypalCredentials = {
|
|
26
|
+
clientId: requiredEnvironment("PAYPAL_CLIENT_ID"),
|
|
27
|
+
clientSecret: requiredEnvironment("PAYPAL_CLIENT_SECRET")
|
|
28
|
+
};
|
|
29
|
+
return new IskuBixi({
|
|
30
|
+
bixiyeyaasha: {
|
|
31
|
+
stripe: { apiKey: requiredEnvironment("STRIPE_SECRET_KEY") },
|
|
32
|
+
paypal: paypalCredentials
|
|
33
|
+
},
|
|
34
|
+
laqabsadayaasha: {
|
|
35
|
+
stripe: new StripePaymentProviderFactory(),
|
|
36
|
+
paypal: new PayPalPaymentProviderFactory({
|
|
37
|
+
environment: paypalEnvironment
|
|
38
|
+
})
|
|
39
|
+
},
|
|
40
|
+
laqabsadayaashaWebhook: {
|
|
41
|
+
stripe: new StripeWebhookAdapter({
|
|
42
|
+
secret: requiredEnvironment("STRIPE_WEBHOOK_SECRET")
|
|
43
|
+
}),
|
|
44
|
+
paypal: new PayPalWebhookAdapter(paypalCredentials, {
|
|
45
|
+
environment: paypalEnvironment,
|
|
46
|
+
webhookId: requiredEnvironment("PAYPAL_WEBHOOK_ID")
|
|
47
|
+
})
|
|
48
|
+
}
|
|
49
|
+
});
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
export async function createProviderExamples(
|
|
53
|
+
sdk: IskuBixiInstance
|
|
54
|
+
): Promise<void> {
|
|
55
|
+
await sdk.lacag.samee({
|
|
56
|
+
qadarka: 25,
|
|
57
|
+
lacagta: "USD",
|
|
58
|
+
bixiye: "stripe",
|
|
59
|
+
tixraac: "ORDER-STRIPE-1003",
|
|
60
|
+
furahaIdempotency: "stripe-order-1003-attempt-1"
|
|
61
|
+
});
|
|
62
|
+
await sdk.lacag.samee({
|
|
63
|
+
qadarka: 25,
|
|
64
|
+
lacagta: "USD",
|
|
65
|
+
bixiye: "paypal",
|
|
66
|
+
tixraac: "ORDER-PAYPAL-1003",
|
|
67
|
+
furahaIdempotency: "paypal-order-1003-attempt-1"
|
|
68
|
+
});
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
export async function processStripeWebhook(
|
|
72
|
+
sdk: IskuBixiInstance,
|
|
73
|
+
rawBody: Uint8Array,
|
|
74
|
+
headers: WebhookHeaders
|
|
75
|
+
): Promise<void> {
|
|
76
|
+
await sdk.webhook.kaShaqee({
|
|
77
|
+
bixiye: "stripe",
|
|
78
|
+
rawBody,
|
|
79
|
+
headers
|
|
80
|
+
});
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
export { createProviderSdkFromEnvironment };
|
package/package.json
CHANGED
|
@@ -1,8 +1,14 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "iskubixi",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.2.0",
|
|
4
4
|
"description": "Somali-first JavaScript and TypeScript SDK for payments and WebAuthn passkey authentication.",
|
|
5
5
|
"license": "MIT",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/Amad55a/iskubixi.git",
|
|
9
|
+
"directory": "javascript-typescript"
|
|
10
|
+
},
|
|
11
|
+
"homepage": "https://github.com/Amad55a/iskubixi/tree/version1/javascript-typescript#readme",
|
|
6
12
|
"keywords": [
|
|
7
13
|
"payments",
|
|
8
14
|
"passkeys",
|
|
@@ -14,12 +20,21 @@
|
|
|
14
20
|
"type": "commonjs",
|
|
15
21
|
"main": "dist/index.js",
|
|
16
22
|
"types": "dist/index.d.ts",
|
|
23
|
+
"exports": {
|
|
24
|
+
".": {
|
|
25
|
+
"types": "./dist/index.d.ts",
|
|
26
|
+
"require": "./dist/index.js",
|
|
27
|
+
"import": "./dist/index.js",
|
|
28
|
+
"default": "./dist/index.js"
|
|
29
|
+
}
|
|
30
|
+
},
|
|
17
31
|
"files": [
|
|
18
32
|
"assets",
|
|
19
33
|
"dist",
|
|
20
34
|
"docs",
|
|
21
35
|
"examples",
|
|
22
36
|
"README.md",
|
|
37
|
+
"CHANGELOG.md",
|
|
23
38
|
"LICENSE"
|
|
24
39
|
],
|
|
25
40
|
"scripts": {
|
|
@@ -35,6 +50,7 @@
|
|
|
35
50
|
"typescript": "^5.8.3"
|
|
36
51
|
},
|
|
37
52
|
"dependencies": {
|
|
38
|
-
"@simplewebauthn/server": "13.3.2"
|
|
53
|
+
"@simplewebauthn/server": "13.3.2",
|
|
54
|
+
"stripe": "^23.1.0"
|
|
39
55
|
}
|
|
40
56
|
}
|