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,339 @@
1
+ "use strict";
2
+ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
3
+ if (kind === "m") throw new TypeError("Private method is not writable");
4
+ if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
5
+ if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
6
+ return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
7
+ };
8
+ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
9
+ if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
10
+ if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
11
+ return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
12
+ };
13
+ var __importDefault = (this && this.__importDefault) || function (mod) {
14
+ return (mod && mod.__esModule) ? mod : { "default": mod };
15
+ };
16
+ var _StripePaymentProvider_stripe, _StripeWebhookAdapter_secret, _StripeWebhookAdapter_toleranceSeconds;
17
+ Object.defineProperty(exports, "__esModule", { value: true });
18
+ exports.StripeWebhookAdapter = exports.StripePaymentProviderFactory = exports.StripePaymentProvider = void 0;
19
+ const stripe_1 = __importDefault(require("stripe"));
20
+ const node_crypto_1 = require("node:crypto");
21
+ const errors_1 = require("../errors");
22
+ const provider_http_1 = require("./provider-http");
23
+ const errors_2 = require("../errors");
24
+ const defaultTimeoutMs = 15000;
25
+ function readApiKey(credentials) {
26
+ const apiKey = credentials.apiKey;
27
+ if (typeof apiKey !== "string" ||
28
+ !/^sk_(?:test|live)_[A-Za-z0-9_]+$/.test(apiKey)) {
29
+ throw new errors_1.ConfigurationError("Stripe secret API key is missing or invalid.");
30
+ }
31
+ return apiKey;
32
+ }
33
+ function stripeMinorUnits(amount, currency) {
34
+ const minorUnits = (0, provider_http_1.toMinorUnits)(amount, currency);
35
+ if (currency === "ISK" || currency === "UGX") {
36
+ const compatibleAmount = minorUnits * 100;
37
+ if (!Number.isSafeInteger(compatibleAmount)) {
38
+ throw new errors_1.ProviderError("Stripe payment amount exceeds its supported range.");
39
+ }
40
+ return compatibleAmount;
41
+ }
42
+ return minorUnits;
43
+ }
44
+ function stripeAmountFromMinorUnits(amount, currency) {
45
+ if (currency === "ISK" || currency === "UGX") {
46
+ if (!Number.isSafeInteger(amount) || amount <= 0 || amount % 100 !== 0) {
47
+ throw new errors_1.ProviderError("Stripe returned an invalid whole-unit currency amount.");
48
+ }
49
+ return amount / 100;
50
+ }
51
+ return (0, provider_http_1.fromMinorUnits)(amount, currency);
52
+ }
53
+ function apiOrigin(apiBaseUrl) {
54
+ if (apiBaseUrl === undefined) {
55
+ return {};
56
+ }
57
+ let url;
58
+ try {
59
+ url = new URL(apiBaseUrl);
60
+ }
61
+ catch {
62
+ throw new errors_1.ConfigurationError("Stripe API base URL is invalid.");
63
+ }
64
+ const loopback = url.hostname === "localhost" ||
65
+ url.hostname === "127.0.0.1" ||
66
+ url.hostname === "::1";
67
+ if ((url.protocol !== "https:" && !(loopback && url.protocol === "http:")) ||
68
+ url.username !== "" ||
69
+ url.password !== "" ||
70
+ url.pathname !== "/" ||
71
+ url.search !== "" ||
72
+ url.hash !== "") {
73
+ throw new errors_1.ConfigurationError("Stripe API base URL must be HTTPS, or HTTP on loopback for tests.");
74
+ }
75
+ return {
76
+ host: url.hostname,
77
+ port: url.port || undefined,
78
+ protocol: url.protocol.slice(0, -1)
79
+ };
80
+ }
81
+ function paymentIntentStatus(intent) {
82
+ if (intent.status === "succeeded") {
83
+ return "guuleystay";
84
+ }
85
+ if (intent.status === "canceled") {
86
+ return "joojiyay";
87
+ }
88
+ if (intent.status === "requires_payment_method" &&
89
+ intent.last_payment_error !== null &&
90
+ intent.last_payment_error !== undefined) {
91
+ return "fashilmay";
92
+ }
93
+ if (intent.status !== "requires_payment_method" &&
94
+ intent.status !== "requires_confirmation" &&
95
+ intent.status !== "requires_action" &&
96
+ intent.status !== "processing" &&
97
+ intent.status !== "requires_capture") {
98
+ throw new errors_1.ProviderError("Stripe returned an unsupported PaymentIntent status.");
99
+ }
100
+ return "sugaya";
101
+ }
102
+ function paymentFromIntent(intent) {
103
+ const metadata = (0, provider_http_1.record)(intent?.metadata) ? intent.metadata : undefined;
104
+ const reference = metadata?.iskubixi_reference;
105
+ if (!(0, provider_http_1.record)(intent) ||
106
+ typeof intent.id !== "string" ||
107
+ intent.id.trim() === "" ||
108
+ !Number.isSafeInteger(intent.amount) ||
109
+ intent.amount <= 0 ||
110
+ typeof intent.currency !== "string" ||
111
+ !/^[a-z]{3}$/.test(intent.currency) ||
112
+ typeof reference !== "string" ||
113
+ reference.trim() === "" ||
114
+ (intent.client_secret !== null &&
115
+ (typeof intent.client_secret !== "string" || intent.client_secret.trim() === ""))) {
116
+ throw new errors_1.ProviderError("Stripe returned invalid PaymentIntent details.");
117
+ }
118
+ const payment = {
119
+ id: intent.id,
120
+ amount: stripeAmountFromMinorUnits(intent.amount, intent.currency.toUpperCase()),
121
+ currency: intent.currency.toUpperCase(),
122
+ reference,
123
+ status: paymentIntentStatus(intent),
124
+ providerStatus: intent.status
125
+ };
126
+ return intent.client_secret !== null &&
127
+ intent.client_secret.trim() !== "" &&
128
+ payment.status === "sugaya"
129
+ ? {
130
+ ...payment,
131
+ nextAction: {
132
+ type: "client_secret",
133
+ clientSecret: intent.client_secret
134
+ }
135
+ }
136
+ : payment;
137
+ }
138
+ function paymentIntentMissing(error) {
139
+ return (0, provider_http_1.record)(error) &&
140
+ error.statusCode === 404 &&
141
+ error.code === "resource_missing";
142
+ }
143
+ function refundStatus(status) {
144
+ if (status === "succeeded") {
145
+ return "guuleystay";
146
+ }
147
+ if (status === "pending" || status === "requires_action") {
148
+ return "sugaya";
149
+ }
150
+ if (status === "failed" || status === "canceled") {
151
+ return "fashilmay";
152
+ }
153
+ throw new errors_1.ProviderError("Stripe returned an unsupported refund status.");
154
+ }
155
+ class StripePaymentProvider {
156
+ constructor(credentials, options = {}) {
157
+ this.capabilities = Object.freeze({
158
+ paymentCreation: true,
159
+ paymentLookup: true,
160
+ paymentVerification: true,
161
+ paymentConfirmation: true,
162
+ paymentCancellation: true,
163
+ refundCreation: true,
164
+ refundStatusLookup: true,
165
+ paymentIdempotency: true
166
+ });
167
+ _StripePaymentProvider_stripe.set(this, void 0);
168
+ const apiKey = readApiKey(credentials);
169
+ const environment = options.environment ?? "test";
170
+ if (environment !== "test" && environment !== "live") {
171
+ throw new errors_1.ConfigurationError("Stripe environment must be test or live.");
172
+ }
173
+ if (environment === "test" && !apiKey.startsWith("sk_test_")) {
174
+ throw new errors_1.ConfigurationError("Stripe test mode requires a test secret key.");
175
+ }
176
+ if (environment === "live" && !apiKey.startsWith("sk_live_")) {
177
+ throw new errors_1.ConfigurationError("Stripe live mode requires an explicitly configured live secret key.");
178
+ }
179
+ const timeoutMs = options.timeoutMs ?? defaultTimeoutMs;
180
+ if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
181
+ throw new errors_1.ConfigurationError("Stripe request timeout must be a positive integer.");
182
+ }
183
+ __classPrivateFieldSet(this, _StripePaymentProvider_stripe, new stripe_1.default(apiKey, {
184
+ timeout: timeoutMs,
185
+ maxNetworkRetries: 0,
186
+ telemetry: false,
187
+ ...apiOrigin(options.apiBaseUrl)
188
+ }), "f");
189
+ }
190
+ async createPayment(request) {
191
+ const amount = stripeMinorUnits(request.amount, request.currency);
192
+ const intent = await this.call("create payment", () => __classPrivateFieldGet(this, _StripePaymentProvider_stripe, "f").paymentIntents.create({
193
+ amount,
194
+ currency: request.currency.toLowerCase(),
195
+ automatic_payment_methods: { enabled: true },
196
+ metadata: { iskubixi_reference: request.reference }
197
+ }, request.idempotencyKey === undefined
198
+ ? undefined
199
+ : { idempotencyKey: request.idempotencyKey }));
200
+ if (typeof intent.client_secret !== "string" ||
201
+ intent.client_secret.trim() === "") {
202
+ throw new errors_1.ProviderError("Stripe PaymentIntent response omitted the client confirmation secret.");
203
+ }
204
+ const payment = paymentFromIntent(intent);
205
+ if (payment.amount !== request.amount ||
206
+ payment.currency !== request.currency ||
207
+ payment.reference !== request.reference) {
208
+ throw new errors_1.ProviderError("Stripe PaymentIntent did not match the payment request.");
209
+ }
210
+ return payment;
211
+ }
212
+ async findPayment(request) {
213
+ const intent = await this.call("retrieve payment", () => __classPrivateFieldGet(this, _StripePaymentProvider_stripe, "f").paymentIntents.retrieve(request.paymentId), true);
214
+ return intent ? paymentFromIntent(intent) : undefined;
215
+ }
216
+ async confirmPayment(request) {
217
+ const intent = await this.call("confirm payment", () => __classPrivateFieldGet(this, _StripePaymentProvider_stripe, "f").paymentIntents.confirm(request.paymentId, {}, { idempotencyKey: request.idempotencyKey }));
218
+ return paymentFromIntent(intent);
219
+ }
220
+ async cancelPayment(request) {
221
+ await this.call("cancel payment", () => __classPrivateFieldGet(this, _StripePaymentProvider_stripe, "f").paymentIntents.cancel(request.paymentId, {}, {
222
+ idempotencyKey: (0, node_crypto_1.createHash)("sha256")
223
+ .update(`iskubixi:stripe:cancel:${request.paymentId}`)
224
+ .digest("hex")
225
+ }));
226
+ }
227
+ async verifyPayment(request) {
228
+ const payment = await this.findPayment(request);
229
+ return payment
230
+ ? { exists: true, payment, source: "adapter" }
231
+ : { exists: false, source: "adapter" };
232
+ }
233
+ async refundPayment(request) {
234
+ const refund = await this.call("refund payment", () => __classPrivateFieldGet(this, _StripePaymentProvider_stripe, "f").refunds.create({ payment_intent: request.paymentId }, { idempotencyKey: request.idempotencyKey }));
235
+ if (typeof refund.id !== "string" || refund.id.trim() === "") {
236
+ throw new errors_1.ProviderError("Stripe returned an invalid refund ID.");
237
+ }
238
+ return { id: refund.id, status: refundStatus(refund.status) };
239
+ }
240
+ async findRefundStatus(request) {
241
+ const refund = await this.call("retrieve refund", () => __classPrivateFieldGet(this, _StripePaymentProvider_stripe, "f").refunds.retrieve(request.refundId), true);
242
+ return refund
243
+ ? { id: refund.id, status: refundStatus(refund.status) }
244
+ : undefined;
245
+ }
246
+ async call(operation, request, allowNotFound = false) {
247
+ try {
248
+ return await request();
249
+ }
250
+ catch (error) {
251
+ if (allowNotFound && paymentIntentMissing(error)) {
252
+ return undefined;
253
+ }
254
+ throw new errors_1.ProviderError(`Stripe ${operation} failed.`, {
255
+ context: { provider: "stripe", operation }
256
+ });
257
+ }
258
+ }
259
+ }
260
+ exports.StripePaymentProvider = StripePaymentProvider;
261
+ _StripePaymentProvider_stripe = new WeakMap();
262
+ class StripePaymentProviderFactory {
263
+ constructor(options = {}) {
264
+ this.options = options;
265
+ }
266
+ create(credentials) {
267
+ return new StripePaymentProvider(credentials, this.options);
268
+ }
269
+ }
270
+ exports.StripePaymentProviderFactory = StripePaymentProviderFactory;
271
+ class StripeWebhookAdapter {
272
+ constructor(options) {
273
+ _StripeWebhookAdapter_secret.set(this, void 0);
274
+ _StripeWebhookAdapter_toleranceSeconds.set(this, void 0);
275
+ if (!options || typeof options.secret !== "string" || options.secret.trim() === "") {
276
+ throw new errors_1.ConfigurationError("Stripe webhook signing secret is required.");
277
+ }
278
+ __classPrivateFieldSet(this, _StripeWebhookAdapter_secret, options.secret, "f");
279
+ __classPrivateFieldSet(this, _StripeWebhookAdapter_toleranceSeconds, options.toleranceSeconds ?? 300, "f");
280
+ if (!Number.isInteger(__classPrivateFieldGet(this, _StripeWebhookAdapter_toleranceSeconds, "f")) || __classPrivateFieldGet(this, _StripeWebhookAdapter_toleranceSeconds, "f") <= 0) {
281
+ throw new errors_1.ConfigurationError("Stripe webhook tolerance must be a positive integer.");
282
+ }
283
+ }
284
+ async verifyAndParse(request) {
285
+ if (!request ||
286
+ request.bixiye !== "stripe" ||
287
+ !(request.rawBody instanceof Uint8Array) ||
288
+ request.rawBody.byteLength === 0 ||
289
+ !request.headers ||
290
+ typeof request.headers !== "object" ||
291
+ Array.isArray(request.headers)) {
292
+ throw new errors_2.WebhookVerificationError("Stripe webhook request is invalid.");
293
+ }
294
+ const signatures = Object.entries(request.headers)
295
+ .filter(([name]) => name.toLowerCase() === "stripe-signature")
296
+ .map(([, value]) => value);
297
+ if (signatures.length !== 1 || typeof signatures[0] !== "string") {
298
+ throw new errors_2.WebhookVerificationError("Stripe webhook signature header is missing or ambiguous.");
299
+ }
300
+ let event;
301
+ try {
302
+ event = stripe_1.default.webhooks.constructEvent(Buffer.from(request.rawBody), signatures[0], __classPrivateFieldGet(this, _StripeWebhookAdapter_secret, "f"), __classPrivateFieldGet(this, _StripeWebhookAdapter_toleranceSeconds, "f"));
303
+ }
304
+ catch {
305
+ throw new errors_2.WebhookVerificationError("Stripe webhook signature or body is invalid.");
306
+ }
307
+ if (event.type === "payment_intent.succeeded" ||
308
+ event.type === "payment_intent.payment_failed" ||
309
+ event.type === "payment_intent.processing" ||
310
+ event.type === "payment_intent.canceled") {
311
+ const intent = event.data.object;
312
+ let payment;
313
+ try {
314
+ payment = paymentFromIntent(intent);
315
+ }
316
+ catch {
317
+ throw new errors_2.WebhookVerificationError("Stripe payment event details are invalid.");
318
+ }
319
+ if (event.type === "payment_intent.payment_failed") {
320
+ payment.status = "fashilmay";
321
+ }
322
+ else if (event.type === "payment_intent.processing") {
323
+ payment.status = "sugaya";
324
+ }
325
+ return {
326
+ bixiye: "stripe",
327
+ dhacdoId: event.id,
328
+ xaalad: payment.status,
329
+ lacagId: payment.id,
330
+ tixraac: payment.reference,
331
+ qadarka: payment.amount,
332
+ lacagta: payment.currency
333
+ };
334
+ }
335
+ return { bixiye: "stripe", dhacdoId: event.id, laIskaIndhoTiray: true };
336
+ }
337
+ }
338
+ exports.StripeWebhookAdapter = StripeWebhookAdapter;
339
+ _StripeWebhookAdapter_secret = new WeakMap(), _StripeWebhookAdapter_toleranceSeconds = new WeakMap();
@@ -1,5 +1,6 @@
1
1
  import type { PaymentIdRequest, PaymentProvider, PaymentProviderFactory, PaymentRequest, PaymentVerification, ProviderCredentials, ProviderPayment } from "./payment-provider";
2
2
  export interface WaafiPayPaymentProviderOptions {
3
+ environment?: "sandbox";
3
4
  formatTimestamp: () => string;
4
5
  fetch?: typeof fetch;
5
6
  timeoutMs?: number;
@@ -122,6 +122,9 @@ class WaafiPayPaymentProvider {
122
122
  if (!options || typeof options !== "object") {
123
123
  throw new errors_1.ConfigurationError("WaafiPay provider options are required.");
124
124
  }
125
+ if (options.environment !== undefined && options.environment !== "sandbox") {
126
+ throw new errors_1.ConfigurationError("WaafiPay is currently available only in sandbox mode.");
127
+ }
125
128
  __classPrivateFieldSet(this, _WaafiPayPaymentProvider_credentials, Object.freeze(readCredentials(credentials)), "f");
126
129
  __classPrivateFieldSet(this, _WaafiPayPaymentProvider_formatTimestamp, options.formatTimestamp, "f");
127
130
  __classPrivateFieldSet(this, _WaafiPayPaymentProvider_fetch, options.fetch ?? globalThis.fetch, "f");
@@ -146,6 +149,7 @@ class WaafiPayPaymentProvider {
146
149
  method: "POST",
147
150
  headers: { "content-type": "application/json" },
148
151
  body: JSON.stringify(payload),
152
+ redirect: "error",
149
153
  signal: controller.signal
150
154
  });
151
155
  if (!response.ok) {
@@ -9,7 +9,7 @@ import type { PaymentStateStore } from "../providers/payment-store";
9
9
  import type { AmaanoodLaqabsade } from "../providers/amaanood-auth-adapter";
10
10
  import type { AmaanoodAuthenticationSessionStore } from "../providers/webauthn-store";
11
11
  import type { PaymentAuthorizationStore } from "../providers/payment-authorization-store";
12
- export type Bixiye = "edahab" | "evc" | "zaad" | "bank" | "waafipay";
12
+ export type Bixiye = "edahab" | "evc" | "zaad" | "bank" | "waafipay" | "stripe" | "paypal";
13
13
  export type AqoonsigaBixiyaha = ProviderCredentials;
14
14
  export interface AmaanoodIskuXir {
15
15
  laqabsadayaal: readonly AmaanoodLaqabsade[];
@@ -17,6 +17,8 @@ export interface AmaanoodIskuXir {
17
17
  }
18
18
  export interface IskuBixiQaabeyn {
19
19
  bixiyeyaasha: Partial<Record<Bixiye, AqoonsigaBixiyaha>>;
20
+ /** Opt in explicitly for local simulator behavior. Never enable for live payments. */
21
+ allowSimulation?: boolean;
20
22
  laqabsadayaasha?: Partial<Record<Bixiye, PaymentProviderFactory>>;
21
23
  amaanood?: AmaanoodIskuXir;
22
24
  keydkaIdempotency?: PaymentIdempotencyStore;
@@ -1,5 +1,5 @@
1
1
  import type { Bixiye } from "./configuration";
2
- import type { PaymentVerificationSource } from "../providers/payment-provider";
2
+ import type { PaymentVerificationSource, ProviderPaymentAction } from "../providers/payment-provider";
3
3
  import type { XaaladdaQr } from "../providers/qr-payment-store";
4
4
  import type { AmaanoodHab, AmaanoodMacluumaadDoorasho } from "../providers/amaanood-auth-adapter";
5
5
  import type { PaymentAuthorizationFailure, PaymentAuthorizationStatus } from "../providers/payment-authorization-store";
@@ -10,6 +10,10 @@ export interface CodsiCelin {
10
10
  lacagId: string;
11
11
  furahaIdempotency: string;
12
12
  }
13
+ export interface CodsiLacagQabso {
14
+ lacagId: string;
15
+ furahaIdempotency: string;
16
+ }
13
17
  export interface CodsiCelinXaalad {
14
18
  celinId: string;
15
19
  }
@@ -73,6 +77,8 @@ export interface NatiijoLacag {
73
77
  lacagta: string;
74
78
  xaalad: XaaladdaLacagta;
75
79
  tixraac: string;
80
+ providerStatus?: string;
81
+ nextAction?: ProviderPaymentAction;
76
82
  dhacayaa?: string;
77
83
  celin?: NatiijoCelin;
78
84
  }
@@ -3,13 +3,14 @@ export interface ProviderCapabilities {
3
3
  paymentCreation: boolean;
4
4
  paymentLookup: boolean;
5
5
  paymentVerification: boolean;
6
+ paymentConfirmation?: boolean;
6
7
  paymentCancellation: boolean;
7
8
  refundCreation: boolean;
8
9
  refundStatusLookup: boolean;
9
10
  qrPayment: boolean;
10
11
  webhookSignatureVerification: boolean;
11
12
  }
12
- export type ProviderCapabilityOverrides = Partial<Pick<ProviderCapabilities, "paymentCreation" | "paymentLookup" | "paymentVerification" | "paymentCancellation" | "refundCreation" | "refundStatusLookup">> & {
13
+ export type ProviderCapabilityOverrides = Partial<Pick<ProviderCapabilities, "paymentCreation" | "paymentLookup" | "paymentVerification" | "paymentConfirmation" | "paymentCancellation" | "refundCreation" | "refundStatusLookup">> & {
13
14
  /** True only when the remote provider documents idempotency-key semantics. */
14
15
  paymentIdempotency?: boolean;
15
16
  };
@@ -0,0 +1,93 @@
1
+ # API reference
2
+
3
+ Names below are the public SDK entry points implemented in `src/index.ts`.
4
+
5
+ ## SDK
6
+
7
+ ### `new IskuBixi(configuration)`
8
+
9
+ Creates SDK instances and initializes provider, storage, webhook, and
10
+ authentication adapters.
11
+
12
+ ### `sdk.lacag.samee(request)`
13
+
14
+ Creates a payment. Fields: `qadarka`, `lacagta`, `bixiye`, `tixraac`,
15
+ optional `lambarka`, `furahaIdempotency`, and `dhacayaa`.
16
+
17
+ ### `sdk.lacag.qabso(request)`
18
+
19
+ Confirms or captures a provider payment. Fields: `lacagId`,
20
+ `furahaIdempotency`. Requires provider confirmation support.
21
+
22
+ ### `sdk.lacag.xaalad(request)`
23
+
24
+ Retrieves provider status. Input: `lacagId`.
25
+
26
+ ### `sdk.lacag.cadee(request)`
27
+
28
+ Verifies provider existence and exact stored payment identity. Input:
29
+ `lacagId`.
30
+
31
+ ### `sdk.lacag.celi(request)`
32
+
33
+ Creates a full refund. Fields: `lacagId`, `furahaIdempotency`.
34
+
35
+ ### `sdk.lacag.celintaXaalad(request)`
36
+
37
+ Retrieves refund status. Field: `celinId`.
38
+
39
+ ### `sdk.lacag.liiska(request?)`
40
+
41
+ Lists stored transactions. Optional filters: `bixiye`, `xaalad`, `lacagta`,
42
+ `lagaBilaabo`, `ilaa`, `bogga`, `xadka`.
43
+
44
+ ### `sdk.bixiye.awood(request)`
45
+
46
+ Reports provider capabilities. Input: `bixiye`.
47
+
48
+ ## QR
49
+
50
+ - `sdk.qr.samee(request)`
51
+ - `sdk.qr.cadee({ tixraac })`
52
+ - `sdk.qr.akhriso({ nuxur })`
53
+ - `sdk.qr.xaalad({ tixraac })`
54
+ - `sdk.qr.jooji({ tixraac })`
55
+ - `sdk.qr.xog({ tixraac })`
56
+
57
+ QR creation requires `dhacayaa`.
58
+
59
+ ## Webhooks
60
+
61
+ - `sdk.webhook.cadee(request)`
62
+ - `sdk.webhook.kaShaqee(request)`
63
+ - `sdk.webhook.fashilmay({ bixiye? })`
64
+ - `sdk.webhook.dibUshaqee({ bixiye, dhacdoId, codsi? })`
65
+
66
+ Webhook requests contain `bixiye`, unchanged `rawBody`, and `headers`.
67
+
68
+ ## Payment authorization
69
+
70
+ - `sdk.lacag.ogolaanshoAbuur(request)`
71
+ - `sdk.lacag.ogolaanshoXaqiiji(request)`
72
+ - `sdk.lacag.ogolaanshoXaalad(request)`
73
+
74
+ ## Biometric/adapters
75
+
76
+ - `sdk.amaanood.waji(request)`
77
+ - `sdk.amaanood.faraha(request)`
78
+ - `sdk.amaanood.isha(request)`
79
+ - `sdk.amaanood.calaacal(request)`
80
+ - `sdk.amaanood.xaqiiji(request)`
81
+
82
+ These require matching configured external adapters.
83
+
84
+ ## Passkeys
85
+
86
+ `Amaanood` public methods:
87
+
88
+ - `furahaAbuur()`
89
+ - `furahaDiiwaangeli()`
90
+ - `saxiix()`
91
+ - `saxiixXaqiiji()`
92
+ - `furahaLiiska()`
93
+ - `furahaJooji()`
@@ -0,0 +1,25 @@
1
+ # Architecture
2
+
3
+ ```text
4
+ Developer application
5
+ ├─ users and business rules
6
+ ├─ application database and storage
7
+ ├─ server-side provider credentials
8
+ └─ IskuBixi SDK
9
+ ├─ payment routing
10
+ ├─ idempotency
11
+ ├─ QR state
12
+ ├─ webhook normalization
13
+ └─ passkey/adapter authorization
14
+ |
15
+ v
16
+ Provider or custom PaymentProvider
17
+ ```
18
+
19
+ IskuBixi is not a hosted backend. It does not own credentials, users, or a
20
+ database. Developers choose providers for each payment and deploy their own
21
+ backend.
22
+
23
+ The SDK is suitable for server-side use in CommonJS Node.js applications.
24
+ Browser code should only receive provider/client handoff values intentionally
25
+ returned by the server, never API secrets or webhook signing secrets.
@@ -0,0 +1,36 @@
1
+ # Authentication
2
+
3
+ IskuBixi separates passkeys/WebAuthn from external modality adapters.
4
+
5
+ ## Passkeys
6
+
7
+ Create an `Amaanood` instance with relying-party configuration:
8
+
9
+ ```ts
10
+ import { Amaanood } from "iskubixi";
11
+
12
+ const passkeys = new Amaanood({
13
+ rpId: "example.com",
14
+ rpName: "Example",
15
+ origins: ["https://example.com"],
16
+ requireUserVerification: true
17
+ });
18
+ ```
19
+
20
+ Public methods:
21
+
22
+ - `furahaAbuur()` generates registration options.
23
+ - `furahaDiiwaangeli()` verifies registration.
24
+ - `saxiix()` generates authentication options.
25
+ - `saxiixXaqiiji()` verifies authentication.
26
+ - `furahaLiiska()` lists public credential metadata.
27
+ - `furahaJooji()` revokes a credential.
28
+
29
+ ## External modality adapters
30
+
31
+ `IskuBixi.amaanood.waji`, `faraha`, `isha`, and `calaacal` require a matching
32
+ `AmaanoodLaqabsade` in configuration. Adapter support does not mean the SDK
33
+ contains hardware or biometric templates.
34
+
35
+ The SDK stores opaque session identifiers and challenge state, not raw biometric
36
+ information.