iskubixi 0.0.0-stage → 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 (95) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/LICENSE +21 -0
  3. package/README.md +209 -3
  4. package/assets/iskubixi-logo.png +0 -0
  5. package/assets/iskubixi-logo.svg +31 -0
  6. package/assets/iskubixi-mark.png +0 -0
  7. package/assets/iskubixi-mark.svg +20 -0
  8. package/dist/amaanood.d.ts +68 -0
  9. package/dist/amaanood.js +415 -0
  10. package/dist/errors.d.ts +61 -0
  11. package/dist/errors.js +113 -0
  12. package/dist/index.d.ts +38 -0
  13. package/dist/index.js +53 -0
  14. package/dist/iskubixi.d.ts +103 -0
  15. package/dist/iskubixi.js +2299 -0
  16. package/dist/providers/amaanood-auth-adapter.d.ts +58 -0
  17. package/dist/providers/amaanood-auth-adapter.js +2 -0
  18. package/dist/providers/idempotency-store.d.ts +25 -0
  19. package/dist/providers/idempotency-store.js +75 -0
  20. package/dist/providers/in-memory-payment-store.d.ts +10 -0
  21. package/dist/providers/in-memory-payment-store.js +52 -0
  22. package/dist/providers/payment-authorization-store.d.ts +56 -0
  23. package/dist/providers/payment-authorization-store.js +114 -0
  24. package/dist/providers/payment-provider.d.ts +71 -0
  25. package/dist/providers/payment-provider.js +2 -0
  26. package/dist/providers/payment-store.d.ts +13 -0
  27. package/dist/providers/payment-store.js +2 -0
  28. package/dist/providers/payment-transaction-store.d.ts +66 -0
  29. package/dist/providers/payment-transaction-store.js +123 -0
  30. package/dist/providers/payment-webhook-adapter.d.ts +37 -0
  31. package/dist/providers/payment-webhook-adapter.js +2 -0
  32. package/dist/providers/paypal-payment-provider.d.ts +41 -0
  33. package/dist/providers/paypal-payment-provider.js +457 -0
  34. package/dist/providers/provider-http.d.ts +15 -0
  35. package/dist/providers/provider-http.js +140 -0
  36. package/dist/providers/qr-payment-store.d.ts +28 -0
  37. package/dist/providers/qr-payment-store.js +34 -0
  38. package/dist/providers/refund-store.d.ts +32 -0
  39. package/dist/providers/refund-store.js +77 -0
  40. package/dist/providers/simulated-payment-provider.d.ts +24 -0
  41. package/dist/providers/simulated-payment-provider.js +88 -0
  42. package/dist/providers/stripe-payment-provider.d.ts +43 -0
  43. package/dist/providers/stripe-payment-provider.js +339 -0
  44. package/dist/providers/waafipay-payment-provider.d.ts +27 -0
  45. package/dist/providers/waafipay-payment-provider.js +200 -0
  46. package/dist/providers/waafipay-webhook-adapter.d.ts +11 -0
  47. package/dist/providers/waafipay-webhook-adapter.js +179 -0
  48. package/dist/providers/webauthn-store.d.ts +70 -0
  49. package/dist/providers/webauthn-store.js +116 -0
  50. package/dist/providers/webhook-event-store.d.ts +32 -0
  51. package/dist/providers/webhook-event-store.js +103 -0
  52. package/dist/types/configuration.d.ts +33 -0
  53. package/dist/types/configuration.js +2 -0
  54. package/dist/types/payment.d.ts +147 -0
  55. package/dist/types/payment.js +2 -0
  56. package/dist/types/provider-capabilities.d.ts +23 -0
  57. package/dist/types/provider-capabilities.js +2 -0
  58. package/dist/types/webhook.d.ts +47 -0
  59. package/dist/types/webhook.js +2 -0
  60. package/docs/api-reference.md +93 -0
  61. package/docs/architecture.md +25 -0
  62. package/docs/authentication.md +36 -0
  63. package/docs/biometric-adapters.md +55 -0
  64. package/docs/configuration.md +57 -0
  65. package/docs/contributing.md +30 -0
  66. package/docs/custom-providers.md +50 -0
  67. package/docs/errors.md +35 -0
  68. package/docs/examples.md +46 -0
  69. package/docs/getting-started.md +64 -0
  70. package/docs/idempotency.md +26 -0
  71. package/docs/index.md +56 -0
  72. package/docs/installation.md +28 -0
  73. package/docs/javascript.md +22 -0
  74. package/docs/limitations.md +31 -0
  75. package/docs/passkeys.md +38 -0
  76. package/docs/payment-authorization.md +49 -0
  77. package/docs/payment-lifecycle.md +34 -0
  78. package/docs/payment-verification.md +18 -0
  79. package/docs/payments.md +68 -0
  80. package/docs/provider-development.md +33 -0
  81. package/docs/providers.md +123 -0
  82. package/docs/qr-payments.md +42 -0
  83. package/docs/refunds.md +20 -0
  84. package/docs/security.md +37 -0
  85. package/docs/storage.md +36 -0
  86. package/docs/testing.md +24 -0
  87. package/docs/troubleshooting.md +28 -0
  88. package/docs/typescript.md +25 -0
  89. package/docs/webhook-security.md +22 -0
  90. package/docs/webhooks.md +59 -0
  91. package/examples/frontend/passkey-authorization.ts +239 -0
  92. package/examples/javascript/payment-authorization.js +183 -0
  93. package/examples/typescript/payment-authorization.ts +146 -0
  94. package/examples/typescript/payment-providers.ts +83 -0
  95. package/package.json +56 -6
package/CHANGELOG.md ADDED
@@ -0,0 +1,26 @@
1
+ # Changelog
2
+
3
+ ## 1.2.0 - Unreleased
4
+
5
+ ### Added
6
+
7
+ - Add explicit local-simulation opt-in and live-mode provider safeguards.
8
+ - Add explicit Stripe and PayPal payment provider adapters, factories,
9
+ webhook adapters, and capability reporting.
10
+ - Add provider selection, confirmation handoffs, and provider operation tests.
11
+ - Add provider integration guidance and a type-checked multi-provider example.
12
+
13
+ ### Security and compatibility
14
+
15
+ - Validate provider payment identities and redirect actions before accepting
16
+ lookup and verification responses.
17
+ - Reject HTTP redirects in provider transports to avoid forwarding credentials
18
+ to another location.
19
+ - Preserve existing APIs and keep unsupported provider operations explicit.
20
+
21
+ ### Validation status
22
+
23
+ - Locally mock-tested; no official provider sandbox or live transactions were
24
+ performed for this release.
25
+ - Stripe and PayPal account eligibility depends on the provider. No direct
26
+ Salam/Salaam Bank, Amal Bank, or Premier Bank adapter is claimed.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 IskuBixi contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,209 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
1
+ # IskuBixi
2
+
3
+ ### One SDK. Many Payments. Smarter Authentication.
4
+
5
+ **Payments · QR Codes · Face · Fingerprint · Eye · Palm · Passkeys**
6
+
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 |
43
+
44
+ ## Installation
45
+
46
+ Requires Node.js 20 or later.
47
+
48
+ ```sh
49
+ npm install iskubixi
50
+ ```
51
+
52
+ ## Quick example
53
+
54
+ The simulator is for local development only. For real providers, register an
55
+ explicit provider factory and keep credentials on the server.
56
+
57
+ ### JavaScript
58
+
59
+ ```js
60
+ const { IskuBixi } = require("iskubixi");
61
+
62
+ const sdk = new IskuBixi({
63
+ allowSimulation: true,
64
+ bixiyeyaasha: {
65
+ edahab: {
66
+ apiKey: "local-demo-only"
67
+ }
68
+ }
69
+ });
70
+
71
+ async function main() {
72
+ const payment = await sdk.lacag.samee({
73
+ qadarka: 20,
74
+ lacagta: "USD",
75
+ bixiye: "edahab",
76
+ tixraac: "LOCAL-ORDER-1",
77
+ furahaIdempotency: "LOCAL-ORDER-1-ATTEMPT-1"
78
+ });
79
+
80
+ console.log(payment.xaalad); // "sugaya"
81
+ }
82
+
83
+ main().catch(console.error);
84
+ ```
85
+
86
+ ### TypeScript
87
+
88
+ ```ts
89
+ import { IskuBixi } from "iskubixi";
90
+
91
+ const sdk = new IskuBixi({
92
+ allowSimulation: true,
93
+ bixiyeyaasha: {
94
+ edahab: { apiKey: "local-demo-only" }
95
+ }
96
+ });
97
+
98
+ const payment = await sdk.lacag.samee({
99
+ qadarka: 20,
100
+ lacagta: "USD",
101
+ bixiye: "edahab",
102
+ tixraac: "LOCAL-ORDER-1"
103
+ });
104
+ ```
105
+
106
+ The published package is CommonJS with TypeScript declarations.
107
+
108
+ ## Providers
109
+
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 |
121
+
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.
125
+
126
+ For real Stripe configuration:
127
+
128
+ ```ts
129
+ import { IskuBixi, StripePaymentProviderFactory } from "iskubixi";
130
+
131
+ const sdk = new IskuBixi({
132
+ bixiyeyaasha: {
133
+ stripe: { apiKey: process.env.STRIPE_SECRET_KEY! }
134
+ },
135
+ laqabsadayaasha: {
136
+ stripe: new StripePaymentProviderFactory({
137
+ environment: "test"
138
+ })
139
+ }
140
+ });
141
+ ```
142
+
143
+ Use `environment: "live"` only with a live key and a production checkout
144
+ verified through provider APIs and webhooks.
145
+
146
+ ## QR payments
147
+
148
+ ```ts
149
+ const qr = await sdk.qr.samee({
150
+ qadarka: 20,
151
+ lacagta: "USD",
152
+ bixiye: "edahab",
153
+ lambarka: "252611111111",
154
+ dhacayaa: new Date(Date.now() + 15 * 60 * 1000).toISOString()
155
+ });
156
+
157
+ const scanned = await sdk.qr.akhriso({ nuxur: qr.nuxur });
158
+ ```
159
+
160
+ QR scanning does not create or fulfill another payment.
161
+
162
+ ## Authentication and biometrics
163
+
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.
167
+
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.
172
+
173
+ Authentication approval is not payment success; the provider or verified
174
+ webhook must confirm the payment.
175
+
176
+ ## Security
177
+
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.
185
+
186
+ ## Documentation
187
+
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)
201
+
202
+ ## Contributing
203
+
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.
206
+
207
+ ## License
208
+
209
+ MIT. See [LICENSE](./LICENSE).
Binary file
@@ -0,0 +1,31 @@
1
+ <svg width="1600" height="520" viewBox="0 0 1600 520" fill="none" xmlns="http://www.w3.org/2000/svg">
2
+ <defs>
3
+ <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
4
+ <stop offset="0%" stop-color="#0B2F73"/>
5
+ <stop offset="50%" stop-color="#1C5CC7"/>
6
+ <stop offset="100%" stop-color="#32B7F0"/>
7
+ </linearGradient>
8
+ <linearGradient id="wave" x1="0" y1="0" x2="1" y2="1">
9
+ <stop offset="0%" stop-color="#EAF8FF"/>
10
+ <stop offset="100%" stop-color="#C7EBFF"/>
11
+ </linearGradient>
12
+ <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
13
+ <feDropShadow dx="0" dy="18" stdDeviation="18" flood-color="#0B2F73" flood-opacity="0.22"/>
14
+ </filter>
15
+ </defs>
16
+
17
+ <g filter="url(#shadow)" transform="translate(52 48)">
18
+ <path d="M200 0L355 90V270L200 360L45 270V90L200 0Z" fill="url(#bg)"/>
19
+ <path d="M200 28L323 97V263L200 332L77 263V97L200 28Z" fill="none" stroke="#C7E7FF" stroke-opacity="0.46" stroke-width="6"/>
20
+
21
+ <rect x="110" y="96" width="52" height="208" rx="18" fill="white"/>
22
+ <path d="M120 120H215C235 120 249 135 249 155V158C249 176 236 191 218 191H162V210H214C236 210 252 225 252 246V248C252 268 236 284 212 284H120V120Z" fill="white"/>
23
+ <path d="M202 118C257 135 287 160 287 208C287 254 262 283 208 296L228 244C246 239 257 228 257 211C257 196 247 186 228 178L202 118Z" fill="url(#wave)"/>
24
+ </g>
25
+
26
+ <g transform="translate(484 158)">
27
+ <text x="0" y="118" font-family="Segoe UI, Arial, sans-serif" font-size="132" font-weight="700" fill="#0B2F73" letter-spacing="-3">IskuBixi</text>
28
+ <text x="6" y="190" font-family="Segoe UI, Arial, sans-serif" font-size="36" font-weight="600" fill="#4867A8" letter-spacing="3">SOMALI-FIRST PAYMENTS + PASSKEYS</text>
29
+ <rect x="0" y="218" width="500" height="8" rx="4" fill="#8CCBF8"/>
30
+ </g>
31
+ </svg>
Binary file
@@ -0,0 +1,20 @@
1
+ <svg width="512" height="512" viewBox="0 0 512 512" fill="none" xmlns="http://www.w3.org/2000/svg">
2
+ <defs>
3
+ <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
4
+ <stop offset="0%" stop-color="#0B2F73"/>
5
+ <stop offset="55%" stop-color="#1C5CC7"/>
6
+ <stop offset="100%" stop-color="#32B7F0"/>
7
+ </linearGradient>
8
+ <linearGradient id="wave" x1="0" y1="0" x2="1" y2="1">
9
+ <stop offset="0%" stop-color="#EAF8FF"/>
10
+ <stop offset="100%" stop-color="#C7EBFF"/>
11
+ </linearGradient>
12
+ </defs>
13
+ <g>
14
+ <path d="M256 40L402 128V296L256 384L110 296V128L256 40Z" fill="url(#bg)"/>
15
+ <path d="M256 72L367 136V288L256 352L145 288V136L256 72Z" fill="none" stroke="#C7E7FF" stroke-opacity="0.5" stroke-width="6"/>
16
+ <rect x="176" y="150" width="66" height="220" rx="20" fill="white"/>
17
+ <path d="M184 170H280C303 170 319 186 319 206V210C319 230 303 246 280 246H228V272H282C307 272 325 289 325 311V315C325 338 307 354 281 354H184V170Z" fill="white"/>
18
+ <path d="M284 170C349 188 387 220 387 276C387 332 347 369 282 385L308 322C333 318 348 306 348 287C348 266 334 251 295 239L284 170Z" fill="url(#wave)"/>
19
+ </g>
20
+ </svg>
@@ -0,0 +1,68 @@
1
+ import { type AuthenticationResponseJSON, type PublicKeyCredentialCreationOptionsJSON, type PublicKeyCredentialRequestOptionsJSON, type RegistrationResponseJSON } from "@simplewebauthn/server";
2
+ import { type AmaanoodChallengeStore, type AmaanoodCredential, type AmaanoodCredentialStore } from "./providers/webauthn-store";
3
+ export interface AmaanoodQaabeyn {
4
+ rpId: string;
5
+ rpName: string;
6
+ origins: readonly string[];
7
+ requireUserVerification?: boolean;
8
+ keydkaLoolan?: AmaanoodChallengeStore;
9
+ keydkaFuraha?: AmaanoodCredentialStore;
10
+ }
11
+ export interface CodsiFurahaAbuur {
12
+ userId: string;
13
+ userName: string;
14
+ displayName?: string;
15
+ }
16
+ export interface CodsiAmaanood {
17
+ userId: string;
18
+ }
19
+ export interface CodsiAmaanoodSaxiix extends CodsiAmaanood {
20
+ /** Internal payment-authorization binding supplied by a trusted server adapter. */
21
+ paymentBinding?: string;
22
+ }
23
+ export interface CodsiFurahaDiiwaangeli extends CodsiAmaanood {
24
+ response: RegistrationResponseJSON;
25
+ }
26
+ export interface CodsiSaxiixXaqiiji extends CodsiAmaanood {
27
+ response: AuthenticationResponseJSON;
28
+ /** Must match the binding supplied when authentication options were created. */
29
+ paymentBinding?: string;
30
+ }
31
+ export interface NatiijoFurahaDiiwaangeli {
32
+ credentialId: string;
33
+ userVerified: boolean;
34
+ }
35
+ export interface NatiijoSaxiix {
36
+ authenticated: true;
37
+ userId: string;
38
+ credentialId: string;
39
+ userVerified: boolean;
40
+ }
41
+ export interface FurahaDiiwaangashan {
42
+ credentialId: string;
43
+ createdAt: string;
44
+ deviceType: AmaanoodCredential["deviceType"];
45
+ backedUp: boolean;
46
+ transports?: readonly NonNullable<AmaanoodCredential["transports"]>[number][];
47
+ }
48
+ export declare class Amaanood {
49
+ private readonly rpId;
50
+ private readonly rpName;
51
+ private readonly origins;
52
+ private readonly requireUserVerification;
53
+ private readonly challengeStore;
54
+ private readonly credentialStore;
55
+ constructor(configuration: AmaanoodQaabeyn);
56
+ furahaAbuur(request: CodsiFurahaAbuur): Promise<PublicKeyCredentialCreationOptionsJSON>;
57
+ furahaDiiwaangeli(request: CodsiFurahaDiiwaangeli): Promise<NatiijoFurahaDiiwaangeli>;
58
+ saxiix(request: CodsiAmaanoodSaxiix): Promise<PublicKeyCredentialRequestOptionsJSON>;
59
+ saxiixXaqiiji(request: CodsiSaxiixXaqiiji): Promise<NatiijoSaxiix>;
60
+ furahaLiiska(request: CodsiAmaanood): Promise<readonly FurahaDiiwaangashan[]>;
61
+ furahaJooji(request: CodsiAmaanood & {
62
+ credentialId: string;
63
+ }): Promise<boolean>;
64
+ private storeChallenge;
65
+ private consumeChallenge;
66
+ private requireChallenge;
67
+ private storageCall;
68
+ }