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
@@ -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.
@@ -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.1.0",
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
  }