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
package/dist/index.d.ts CHANGED
@@ -6,11 +6,15 @@ export { ConfigurationError, IdempotencyError, IskuBixiError, IskuBixiErrorCode,
6
6
  export type { IskuBixiErrorCode as IskuBixiErrorCodeType, IskuBixiErrorContext, IskuBixiErrorOptions } from "./errors";
7
7
  export { WaafiPayPaymentProvider, WaafiPayPaymentProviderFactory } from "./providers/waafipay-payment-provider";
8
8
  export type { WaafiPayPaymentProviderOptions } from "./providers/waafipay-payment-provider";
9
+ export { StripePaymentProvider, StripePaymentProviderFactory, StripeWebhookAdapter } from "./providers/stripe-payment-provider";
10
+ export type { StripePaymentProviderOptions, StripeWebhookAdapterOptions } from "./providers/stripe-payment-provider";
11
+ export { PayPalPaymentProvider, PayPalPaymentProviderFactory, PayPalWebhookAdapter } from "./providers/paypal-payment-provider";
12
+ export type { PayPalEnvironment, PayPalPaymentProviderOptions, PayPalWebhookAdapterOptions } from "./providers/paypal-payment-provider";
9
13
  export type { AqoonsigaBixiyaha, AmaanoodIskuXir, Bixiye, IskuBixiQaabeyn } from "./types/configuration";
10
14
  export type { AmaanoodBilowLaqabsade, AmaanoodHab, AmaanoodHabLaXaqiijiyay, AmaanoodLaqabsade, AmaanoodMacluumaadDoorasho, AmaanoodXaqiijinLaqabsade, CodsiAmaanoodBilow, CodsiAmaanoodXaqiiji, NatiijoAmaanoodBilow, NatiijoAmaanoodXaqiiji } from "./providers/amaanood-auth-adapter";
11
15
  export type { CodsiBixiyeAwood, NatiijoBixiyeAwood, ProviderCapabilities, ProviderCapabilityOverrides } from "./types/provider-capabilities";
12
- export type { CodsiCelin, CodsiCelinXaalad, CodsiLacag, CodsiLacagId, CodsiLiiskaLacag, CodsiOgolaanshoAbuur, CodsiOgolaanshoXaqiiji, CodsiOgolaanshoXaalad, CodsiQrLacag, CodsiQrNuxur, CodsiQrTixraac, CodsiTijaabiXaalad, NatiijoLiiskaLacag, NatiijoLacag, NatiijoLacagLiiska, NatiijoOgolaanshoAbuur, NatiijoOgolaanshoXaqiiji, NatiijoOgolaanshoXaalad, KoobanLacagOgolaansho, NatiijoCelin, NatiijoQr, NatiijoQrXaalad, NatiijoQrXaqiijin, NatiijoXaqiijin, XaaladLacagDhamaad, XaaladdaCelin, XaaladdaLacagta } from "./types/payment";
13
- export type { PaymentIdRequest, PaymentRefundRequest, PaymentRefundStatusRequest, PaymentProvider, PaymentProviderFactory, PaymentRequest, PaymentVerification, PaymentVerificationSource, ProviderCredentials, ProviderPayment, ProviderRefund, ProviderRefundStatus } from "./providers/payment-provider";
16
+ export type { CodsiCelin, CodsiCelinXaalad, CodsiLacagQabso, CodsiLacag, CodsiLacagId, CodsiLiiskaLacag, CodsiOgolaanshoAbuur, CodsiOgolaanshoXaqiiji, CodsiOgolaanshoXaalad, CodsiQrLacag, CodsiQrNuxur, CodsiQrTixraac, CodsiTijaabiXaalad, NatiijoLiiskaLacag, NatiijoLacag, NatiijoLacagLiiska, NatiijoOgolaanshoAbuur, NatiijoOgolaanshoXaqiiji, NatiijoOgolaanshoXaalad, KoobanLacagOgolaansho, NatiijoCelin, NatiijoQr, NatiijoQrXaalad, NatiijoQrXaqiijin, NatiijoXaqiijin, XaaladLacagDhamaad, XaaladdaCelin, XaaladdaLacagta } from "./types/payment";
17
+ export type { PaymentIdRequest, PaymentConfirmationRequest, PaymentRefundRequest, PaymentRefundStatusRequest, PaymentProvider, PaymentProviderFactory, PaymentRequest, PaymentVerification, PaymentVerificationSource, ProviderCredentials, ProviderPayment, ProviderPaymentAction, ProviderRefund, ProviderRefundStatus } from "./providers/payment-provider";
14
18
  export { InMemoryPaymentIdempotencyStore } from "./providers/idempotency-store";
15
19
  export type { PaymentIdempotencyStore, RefundIdempotencyStore } from "./providers/idempotency-store";
16
20
  export { InMemoryPaymentAuthorizationStore } from "./providers/payment-authorization-store";
package/dist/index.js CHANGED
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.WaafiPayWebhookAdapter = exports.InMemoryWebhookEventStore = exports.InMemoryQrPaymentStore = exports.InMemoryAmaanoodCredentialStore = exports.InMemoryAmaanoodChallengeStore = exports.InMemoryAmaanoodAuthenticationSessionStore = exports.InMemoryRefundStore = exports.InMemoryPaymentTransactionStore = exports.InMemoryPaymentStore = exports.InMemoryRefundIdempotencyStore = exports.InMemoryPaymentAuthorizationStore = exports.InMemoryPaymentIdempotencyStore = exports.WaafiPayPaymentProviderFactory = exports.WaafiPayPaymentProvider = exports.WebhookVerificationError = exports.WebAuthnError = exports.ValidationError = exports.UnsupportedOperationError = exports.StorageError = exports.RefundError = exports.ProviderError = exports.PaymentError = exports.IskuBixiErrorCode = exports.IskuBixiError = exports.IdempotencyError = exports.ConfigurationError = exports.Amaanood = exports.IskuBixi = void 0;
3
+ exports.WaafiPayWebhookAdapter = exports.InMemoryWebhookEventStore = exports.InMemoryQrPaymentStore = exports.InMemoryAmaanoodCredentialStore = exports.InMemoryAmaanoodChallengeStore = exports.InMemoryAmaanoodAuthenticationSessionStore = exports.InMemoryRefundStore = exports.InMemoryPaymentTransactionStore = exports.InMemoryPaymentStore = exports.InMemoryRefundIdempotencyStore = exports.InMemoryPaymentAuthorizationStore = exports.InMemoryPaymentIdempotencyStore = exports.PayPalWebhookAdapter = exports.PayPalPaymentProviderFactory = exports.PayPalPaymentProvider = exports.StripeWebhookAdapter = exports.StripePaymentProviderFactory = exports.StripePaymentProvider = exports.WaafiPayPaymentProviderFactory = exports.WaafiPayPaymentProvider = exports.WebhookVerificationError = exports.WebAuthnError = exports.ValidationError = exports.UnsupportedOperationError = exports.StorageError = exports.RefundError = exports.ProviderError = exports.PaymentError = exports.IskuBixiErrorCode = exports.IskuBixiError = exports.IdempotencyError = exports.ConfigurationError = exports.Amaanood = exports.IskuBixi = void 0;
4
4
  var iskubixi_1 = require("./iskubixi");
5
5
  Object.defineProperty(exports, "IskuBixi", { enumerable: true, get: function () { return iskubixi_1.IskuBixi; } });
6
6
  var amaanood_1 = require("./amaanood");
@@ -21,6 +21,14 @@ Object.defineProperty(exports, "WebhookVerificationError", { enumerable: true, g
21
21
  var waafipay_payment_provider_1 = require("./providers/waafipay-payment-provider");
22
22
  Object.defineProperty(exports, "WaafiPayPaymentProvider", { enumerable: true, get: function () { return waafipay_payment_provider_1.WaafiPayPaymentProvider; } });
23
23
  Object.defineProperty(exports, "WaafiPayPaymentProviderFactory", { enumerable: true, get: function () { return waafipay_payment_provider_1.WaafiPayPaymentProviderFactory; } });
24
+ var stripe_payment_provider_1 = require("./providers/stripe-payment-provider");
25
+ Object.defineProperty(exports, "StripePaymentProvider", { enumerable: true, get: function () { return stripe_payment_provider_1.StripePaymentProvider; } });
26
+ Object.defineProperty(exports, "StripePaymentProviderFactory", { enumerable: true, get: function () { return stripe_payment_provider_1.StripePaymentProviderFactory; } });
27
+ Object.defineProperty(exports, "StripeWebhookAdapter", { enumerable: true, get: function () { return stripe_payment_provider_1.StripeWebhookAdapter; } });
28
+ var paypal_payment_provider_1 = require("./providers/paypal-payment-provider");
29
+ Object.defineProperty(exports, "PayPalPaymentProvider", { enumerable: true, get: function () { return paypal_payment_provider_1.PayPalPaymentProvider; } });
30
+ Object.defineProperty(exports, "PayPalPaymentProviderFactory", { enumerable: true, get: function () { return paypal_payment_provider_1.PayPalPaymentProviderFactory; } });
31
+ Object.defineProperty(exports, "PayPalWebhookAdapter", { enumerable: true, get: function () { return paypal_payment_provider_1.PayPalWebhookAdapter; } });
24
32
  var idempotency_store_1 = require("./providers/idempotency-store");
25
33
  Object.defineProperty(exports, "InMemoryPaymentIdempotencyStore", { enumerable: true, get: function () { return idempotency_store_1.InMemoryPaymentIdempotencyStore; } });
26
34
  var payment_authorization_store_1 = require("./providers/payment-authorization-store");
@@ -2,12 +2,13 @@ import type { IskuBixiQaabeyn } from "./types/configuration";
2
2
  import type { CodsiAmaanoodBilow, CodsiAmaanoodXaqiiji, NatiijoAmaanoodBilow, NatiijoAmaanoodXaqiiji } from "./providers/amaanood-auth-adapter";
3
3
  import type { CodsiBixiyeAwood, NatiijoBixiyeAwood } from "./types/provider-capabilities";
4
4
  import type { CodsiWebhook } from "./providers/payment-webhook-adapter";
5
- import type { CodsiLacag, CodsiLacagId, CodsiCelin, CodsiCelinXaalad, CodsiLiiskaLacag, CodsiQrLacag, CodsiQrNuxur, CodsiQrTixraac, CodsiTijaabiXaalad, NatiijoCelin, NatiijoLiiskaLacag, NatiijoLacag, NatiijoQr, NatiijoQrXaalad, NatiijoQrXaqiijin, NatiijoXaqiijin, CodsiOgolaanshoAbuur, CodsiOgolaanshoXaqiiji, CodsiOgolaanshoXaalad, NatiijoOgolaanshoAbuur, NatiijoOgolaanshoXaqiiji, NatiijoOgolaanshoXaalad } from "./types/payment";
5
+ import type { CodsiLacag, CodsiLacagId, CodsiCelin, CodsiLacagQabso, CodsiCelinXaalad, CodsiLiiskaLacag, CodsiQrLacag, CodsiQrNuxur, CodsiQrTixraac, CodsiTijaabiXaalad, NatiijoCelin, NatiijoLiiskaLacag, NatiijoLacag, NatiijoQr, NatiijoQrXaalad, NatiijoQrXaqiijin, NatiijoXaqiijin, CodsiOgolaanshoAbuur, CodsiOgolaanshoXaqiiji, CodsiOgolaanshoXaalad, NatiijoOgolaanshoAbuur, NatiijoOgolaanshoXaqiiji, NatiijoOgolaanshoXaalad } from "./types/payment";
6
6
  import type { CodsiWebhookDibUshaqee, CodsiWebhookFashilmay, NatiijoWebhookCadee, NatiijoWebhookDhacdoFashilmay, NatiijoWebhookShaqeeyay } from "./types/webhook";
7
7
  export declare class IskuBixi {
8
8
  #private;
9
9
  readonly lacag: {
10
10
  samee: (codsi: CodsiLacag) => Promise<NatiijoLacag>;
11
+ qabso: (codsi: CodsiLacagQabso) => Promise<NatiijoLacag>;
11
12
  xaalad: (codsi: CodsiLacagId) => Promise<NatiijoLacag>;
12
13
  cadee: (codsi: CodsiLacagId) => Promise<NatiijoXaqiijin>;
13
14
  celi: (codsi: CodsiCelin) => Promise<NatiijoCelin>;
@@ -87,6 +88,7 @@ export declare class IskuBixi {
87
88
  private paymentRequestFingerprint;
88
89
  private hashValue;
89
90
  private lacagXaalad;
91
+ private lacagQabso;
90
92
  private celinDiiwaangashanKaHel;
91
93
  private lacagCadee;
92
94
  private lacagTijaabiXaalad;
package/dist/iskubixi.js CHANGED
@@ -31,7 +31,18 @@ const bixiyeyaashaLaTaageero = new Set([
31
31
  "evc",
32
32
  "zaad",
33
33
  "bank",
34
- "waafipay"
34
+ "waafipay",
35
+ "stripe",
36
+ "paypal"
37
+ ]);
38
+ const providersRequiringAdapters = new Set([
39
+ "stripe",
40
+ "paypal",
41
+ "waafipay",
42
+ "edahab",
43
+ "evc",
44
+ "zaad",
45
+ "bank"
35
46
  ]);
36
47
  const hababkaAqoonsiga = new Set([
37
48
  "waji",
@@ -54,6 +65,7 @@ const methodToCapability = {
54
65
  createPayment: "paymentCreation",
55
66
  findPayment: "paymentLookup",
56
67
  verifyPayment: "paymentVerification",
68
+ confirmPayment: "paymentConfirmation",
57
69
  cancelPayment: "paymentCancellation",
58
70
  refundPayment: "refundCreation",
59
71
  findRefundStatus: "refundStatusLookup"
@@ -135,6 +147,29 @@ function waaNatiijadaLacag(value) {
135
147
  if (typeof value !== "object" || value === null || Array.isArray(value)) {
136
148
  return false;
137
149
  }
150
+ const validNextAction = (action) => {
151
+ if (!waaDiiwaan(action)) {
152
+ return false;
153
+ }
154
+ if (action.type === "redirect") {
155
+ if (typeof action.url !== "string" || action.url.length === 0 || action.url.length > 2048) {
156
+ return false;
157
+ }
158
+ try {
159
+ const url = new URL(action.url);
160
+ return url.protocol === "https:" &&
161
+ url.username === "" &&
162
+ url.password === "";
163
+ }
164
+ catch {
165
+ return false;
166
+ }
167
+ }
168
+ return action.type === "client_secret" &&
169
+ typeof action.clientSecret === "string" &&
170
+ action.clientSecret.trim() !== "" &&
171
+ action.clientSecret.length <= 512;
172
+ };
138
173
  return ("id" in value &&
139
174
  typeof value.id === "string" &&
140
175
  value.id.trim() !== "" &&
@@ -149,7 +184,21 @@ function waaNatiijadaLacag(value) {
149
184
  typeof value.reference === "string" &&
150
185
  value.reference.trim() !== "" &&
151
186
  "status" in value &&
152
- waaXaaladdaLacagta(value.status));
187
+ waaXaaladdaLacagta(value.status) &&
188
+ (!("providerStatus" in value) ||
189
+ (typeof value.providerStatus === "string" &&
190
+ value.providerStatus.length > 0 &&
191
+ value.providerStatus.length <= 128)) &&
192
+ (!("nextAction" in value) ||
193
+ value.nextAction === undefined ||
194
+ validNextAction(value.nextAction)));
195
+ }
196
+ function providerPaymentMatches(value, expected) {
197
+ return waaNatiijadaLacag(value) &&
198
+ value.id === expected.id &&
199
+ value.amount === expected.amount &&
200
+ value.currency === expected.currency &&
201
+ value.reference === expected.reference;
153
202
  }
154
203
  function waaXaaladdaProviderCelin(value) {
155
204
  return value === "sugaya" || value === "guuleystay" || value === "fashilmay";
@@ -189,10 +238,10 @@ function waaAwoodahaLaqabsade(value) {
189
238
  "paymentCreation",
190
239
  "paymentLookup",
191
240
  "paymentVerification",
241
+ "paymentConfirmation",
192
242
  "paymentCancellation",
193
243
  "refundCreation",
194
244
  "refundStatusLookup",
195
- "paymentIdempotency",
196
245
  "paymentIdempotency"
197
246
  ]);
198
247
  return Object.entries(value).every(([name, enabled]) => allowed.has(name) && typeof enabled === "boolean");
@@ -207,6 +256,12 @@ function waaLaqabsadeBixiye(value) {
207
256
  "verifyPayment" in value &&
208
257
  typeof value.verifyPayment === "function" &&
209
258
  (!("capabilities" in value) || waaAwoodahaLaqabsade(value.capabilities)) &&
259
+ (!("confirmPayment" in value) ||
260
+ value.confirmPayment === undefined ||
261
+ typeof value.confirmPayment === "function") &&
262
+ (!("cancelPayment" in value) ||
263
+ value.cancelPayment === undefined ||
264
+ typeof value.cancelPayment === "function") &&
210
265
  (!("refundPayment" in value) ||
211
266
  value.refundPayment === undefined ||
212
267
  typeof value.refundPayment === "function") &&
@@ -291,6 +346,7 @@ class IskuBixi {
291
346
  _IskuBixi_paymentProvidersByPaymentId.set(this, new Map());
292
347
  this.lacag = {
293
348
  samee: (codsi) => this.apiCall(() => this.lacagSamee(codsi), (message) => new errors_1.PaymentError(message)),
349
+ qabso: (codsi) => this.apiCall(() => this.lacagQabso(codsi), (message) => new errors_1.PaymentError(message)),
294
350
  xaalad: (codsi) => this.apiCall(() => this.lacagXaalad(codsi), (message) => new errors_1.PaymentError(message)),
295
351
  cadee: (codsi) => this.apiCall(() => this.lacagCadee(codsi), (message) => new errors_1.PaymentError(message)),
296
352
  celi: (codsi) => this.apiCall(() => this.lacagCeli(codsi), (message) => new errors_1.RefundError(message)),
@@ -495,6 +551,17 @@ class IskuBixi {
495
551
  for (const bixiye of bixiyeyaashaLaQaabeeyay) {
496
552
  const warshad = laqabsadayaasha?.[bixiye];
497
553
  if (!warshad) {
554
+ const environment = aqoonsiyadaBixiyeyaasha.get(bixiye)?.environment;
555
+ const mode = aqoonsiyadaBixiyeyaasha.get(bixiye)?.mode;
556
+ if (environment === "live" || mode === "live") {
557
+ throw new errors_1.ConfigurationError(`Provider "${bixiye}" requires an explicitly registered adapter for live mode.`);
558
+ }
559
+ if (bixiye !== "edahab" && bixiye !== "evc" && bixiye !== "zaad" && bixiye !== "bank") {
560
+ throw new errors_1.ConfigurationError(`Provider "${bixiye}" requires an explicitly registered payment adapter.`);
561
+ }
562
+ if (qaabeyn.allowSimulation === false) {
563
+ throw new errors_1.ConfigurationError(`Provider "${bixiye}" has no real adapter and simulation is disabled.`);
564
+ }
498
565
  paymentProviders.set(bixiye, simulatedPaymentProvider);
499
566
  continue;
500
567
  }
@@ -956,6 +1023,7 @@ class IskuBixi {
956
1023
  paymentCreation,
957
1024
  paymentLookup,
958
1025
  paymentVerification: laFuliyo("verifyPayment"),
1026
+ paymentConfirmation: laFuliyo("confirmPayment"),
959
1027
  paymentCancellation: laFuliyo("cancelPayment"),
960
1028
  refundCreation: laFuliyo("refundPayment"),
961
1029
  refundStatusLookup: laFuliyo("findRefundStatus"),
@@ -1007,6 +1075,10 @@ class IskuBixi {
1007
1075
  }
1008
1076
  dhacayaa = new Date(Date.parse(codsi.dhacayaa)).toISOString();
1009
1077
  }
1078
+ const effectiveProviderIdempotencyKey = providerIdempotencyKey ??
1079
+ (codsi.furahaIdempotency === undefined
1080
+ ? undefined
1081
+ : this.hashValue(`iskubixi:payment:${codsi.bixiye}:${codsi.furahaIdempotency}`));
1010
1082
  const createProviderPayment = () => {
1011
1083
  if (dhacayaa !== undefined && Date.parse(dhacayaa) <= Date.now()) {
1012
1084
  throw new errors_1.ValidationError("Payment expiry (dhacayaa) must be in the future.");
@@ -1016,9 +1088,9 @@ class IskuBixi {
1016
1088
  currency: codsi.lacagta,
1017
1089
  reference: codsi.tixraac,
1018
1090
  accountNumber: codsi.lambarka,
1019
- ...(providerIdempotencyKey !== undefined &&
1091
+ ...(effectiveProviderIdempotencyKey !== undefined &&
1020
1092
  __classPrivateFieldGet(this, _IskuBixi_providersWithIdempotency, "f").has(codsi.bixiye)
1021
- ? { idempotencyKey: providerIdempotencyKey }
1093
+ ? { idempotencyKey: effectiveProviderIdempotencyKey }
1022
1094
  : {})
1023
1095
  }));
1024
1096
  };
@@ -1066,8 +1138,12 @@ class IskuBixi {
1066
1138
  codsiIdempotencyFingerprint
1067
1139
  });
1068
1140
  __classPrivateFieldGet(this, _IskuBixi_paymentProvidersByPaymentId, "f").set(providerPayment.id, {
1141
+ id: providerPayment.id,
1069
1142
  bixiye: codsi.bixiye,
1070
1143
  laqabsade: paymentProvider,
1144
+ amount: providerPayment.amount,
1145
+ currency: providerPayment.currency,
1146
+ reference: providerPayment.reference,
1071
1147
  furahaIdempotencyHash: idempotencyKeyHash,
1072
1148
  codsiIdempotencyFingerprint,
1073
1149
  laAbuuray,
@@ -1076,8 +1152,12 @@ class IskuBixi {
1076
1152
  }
1077
1153
  else if (!existingPayment && storedPayment) {
1078
1154
  __classPrivateFieldGet(this, _IskuBixi_paymentProvidersByPaymentId, "f").set(providerPayment.id, {
1155
+ id: storedPayment.id,
1079
1156
  bixiye: storedPayment.bixiye,
1080
1157
  laqabsade: paymentProvider,
1158
+ amount: storedPayment.amount,
1159
+ currency: storedPayment.currency,
1160
+ reference: storedPayment.reference,
1081
1161
  furahaIdempotencyHash: storedPayment.furahaIdempotencyHash,
1082
1162
  codsiIdempotencyFingerprint: storedPayment.codsiIdempotencyFingerprint,
1083
1163
  laAbuuray: storedPayment.laAbuuray,
@@ -1138,7 +1218,7 @@ class IskuBixi {
1138
1218
  const refund = await __classPrivateFieldGet(this, _IskuBixi_refundIdempotencyStore, "f").getOrCreate(codsi.furahaIdempotency, fingerprint, paymentIdentity, async () => {
1139
1219
  const result = await this.adapterCall(bixiye, "refund payment", () => refundPayment({
1140
1220
  paymentId: codsi.lacagId,
1141
- idempotencyKey: codsi.furahaIdempotency
1221
+ idempotencyKey: this.hashValue(`iskubixi:refund:${bixiye}:${codsi.lacagId}:${codsi.furahaIdempotency}`)
1142
1222
  }));
1143
1223
  if (!waaNatiijadaCelin(result)) {
1144
1224
  throw new errors_1.ProviderError(`Payment provider "${bixiye}" returned an invalid refund result.`);
@@ -1456,8 +1536,8 @@ class IskuBixi {
1456
1536
  }
1457
1537
  this.awoodHubi(record.bixiye, "payment lookup for QR payment", "paymentLookup");
1458
1538
  const payment = await this.adapterCall(record.bixiye, "retrieve QR payment status", () => provider.findPayment({ paymentId: record.lacagId }));
1459
- if (!payment || payment.id !== record.lacagId) {
1460
- throw new Error("Payment provider could not find the QR payment.");
1539
+ if (!providerPaymentMatches(payment, storedPayment)) {
1540
+ throw new errors_1.ProviderError("Payment provider returned details that do not match the QR payment.");
1461
1541
  }
1462
1542
  await __classPrivateFieldGet(this, _IskuBixi_transactionStore, "f").save(this.paymentToTransaction(payment, record.bixiye, record.laAbuuray, record.dhacayaa));
1463
1543
  const expiredAfterLookup = await this.lacagDhacayKaHel(record.bixiye, record.lacagId, record.dhacayaa);
@@ -1950,6 +2030,55 @@ class IskuBixi {
1950
2030
  const celin = await this.celinDiiwaangashanKaHel(route.bixiye, codsi.lacagId);
1951
2031
  return this.paymentToResult(providerPayment, route.dhacayaa, celin);
1952
2032
  }
2033
+ async lacagQabso(codsi) {
2034
+ if (!codsi || typeof codsi !== "object" || Array.isArray(codsi)) {
2035
+ throw new errors_1.ValidationError("Payment confirmation request is required.");
2036
+ }
2037
+ if (typeof codsi.lacagId !== "string" || codsi.lacagId.trim() === "") {
2038
+ throw new errors_1.ValidationError("Payment ID (lacagId) is required for confirmation.");
2039
+ }
2040
+ if (typeof codsi.furahaIdempotency !== "string" ||
2041
+ codsi.furahaIdempotency.trim() === "") {
2042
+ throw new errors_1.ValidationError("Payment confirmation idempotency key must be non-empty.");
2043
+ }
2044
+ if (Object.keys(codsi).some((furaha) => furaha !== "lacagId" && furaha !== "furahaIdempotency")) {
2045
+ throw new errors_1.ValidationError("Only a payment ID and idempotency key are accepted for confirmation.");
2046
+ }
2047
+ const paymentId = codsi.lacagId;
2048
+ const route = await this.bixiyeLacagKaHel(paymentId);
2049
+ this.awoodHubi(route.bixiye, "payment confirmation", "paymentConfirmation");
2050
+ const currentPayment = await this.raadiLacag({ lacagId: paymentId });
2051
+ if (currentPayment.status === "guuleystay") {
2052
+ return this.paymentToResult(currentPayment, route.dhacayaa);
2053
+ }
2054
+ if (currentPayment.status !== "sugaya") {
2055
+ throw new errors_1.PaymentError("Only a pending payment can be confirmed.");
2056
+ }
2057
+ if (route.dhacayaa !== undefined &&
2058
+ await this.lacagDhacayKaHel(route.bixiye, paymentId, route.dhacayaa)) {
2059
+ throw new errors_1.PaymentError("Expired payments cannot be confirmed.");
2060
+ }
2061
+ const confirmPayment = route.laqabsade.confirmPayment;
2062
+ if (typeof confirmPayment !== "function") {
2063
+ throw new errors_1.UnsupportedOperationError(route.bixiye, "payment confirmation");
2064
+ }
2065
+ const confirmedPayment = await this.adapterCall(route.bixiye, "confirm payment", () => confirmPayment.call(route.laqabsade, {
2066
+ paymentId,
2067
+ idempotencyKey: this.hashValue(`iskubixi:confirmation:${route.bixiye}:${paymentId}:${codsi.furahaIdempotency}`)
2068
+ }));
2069
+ if (!waaNatiijadaLacag(confirmedPayment) ||
2070
+ confirmedPayment.id !== paymentId ||
2071
+ confirmedPayment.amount !== currentPayment.amount ||
2072
+ confirmedPayment.currency !== currentPayment.currency ||
2073
+ confirmedPayment.reference !== currentPayment.reference) {
2074
+ throw new errors_1.ProviderError(`Payment provider "${route.bixiye}" returned invalid confirmation details.`);
2075
+ }
2076
+ await __classPrivateFieldGet(this, _IskuBixi_transactionStore, "f").save(this.paymentToTransaction(confirmedPayment, route.bixiye, route.laAbuuray, route.dhacayaa));
2077
+ const expiredPayment = route.dhacayaa === undefined
2078
+ ? undefined
2079
+ : await this.lacagDhacayKaHel(route.bixiye, paymentId, route.dhacayaa);
2080
+ return this.paymentToResult(expiredPayment ?? confirmedPayment, route.dhacayaa);
2081
+ }
1953
2082
  async celinDiiwaangashanKaHel(bixiye, lacagId) {
1954
2083
  const refund = await __classPrivateFieldGet(this, _IskuBixi_refundStore, "f").findByPaymentId(bixiye, lacagId);
1955
2084
  return refund ? this.refundToResult(refund) : undefined;
@@ -1959,17 +2088,23 @@ class IskuBixi {
1959
2088
  throw new errors_1.ValidationError("Payment verification request is required.");
1960
2089
  }
1961
2090
  const paymentId = this.lacagIdXaqiiji(codsi);
1962
- const { bixiye, laqabsade, laAbuuray, dhacayaa } = await this.bixiyeLacagKaHel(paymentId);
2091
+ const route = await this.bixiyeLacagKaHel(paymentId);
2092
+ const { bixiye, laqabsade, laAbuuray, dhacayaa } = route;
1963
2093
  this.awoodHubi(bixiye, "payment verification", "paymentVerification");
1964
2094
  const expiredPayment = dhacayaa === undefined
1965
2095
  ? undefined
1966
2096
  : await this.lacagDhacayKaHel(bixiye, paymentId, dhacayaa);
1967
2097
  const verification = await this.adapterCall(bixiye, "verify payment", () => laqabsade.verifyPayment({ paymentId }));
2098
+ if (!waaDiiwaan(verification) ||
2099
+ typeof verification.exists !== "boolean" ||
2100
+ (verification.source !== "adapter" && verification.source !== "simulated")) {
2101
+ throw new errors_1.ProviderError(`Payment provider "${bixiye}" returned an invalid verification result.`);
2102
+ }
1968
2103
  if (!verification.exists) {
1969
2104
  throw new Error(`Payment "${paymentId}" was not found.`);
1970
2105
  }
1971
- if (!verification.payment || verification.payment.id !== paymentId) {
1972
- throw new Error(`Payment provider returned an invalid verification result for "${paymentId}".`);
2106
+ if (!providerPaymentMatches(verification.payment, route)) {
2107
+ throw new errors_1.ProviderError(`Payment provider "${bixiye}" returned verification details that do not match the stored payment.`);
1973
2108
  }
1974
2109
  if (!expiredPayment) {
1975
2110
  await __classPrivateFieldGet(this, _IskuBixi_transactionStore, "f").save(this.paymentToTransaction(verification.payment, bixiye, laAbuuray, dhacayaa));
@@ -2008,8 +2143,8 @@ class IskuBixi {
2008
2143
  throw new Error("Status simulation is only available for simulated payments.");
2009
2144
  }
2010
2145
  const payment = await laqabsade.simulateStatus(lacagId, codsi.xaalad);
2011
- if (!payment) {
2012
- throw new Error(`Payment "${lacagId}" was not found.`);
2146
+ if (!providerPaymentMatches(payment, route)) {
2147
+ throw new errors_1.ProviderError(`Payment provider "${route.bixiye}" returned payment details that do not match the stored payment.`);
2013
2148
  }
2014
2149
  const paymentRoute = __classPrivateFieldGet(this, _IskuBixi_paymentProvidersByPaymentId, "f").get(lacagId);
2015
2150
  if (paymentRoute) {
@@ -2025,7 +2160,8 @@ class IskuBixi {
2025
2160
  throw new errors_1.ValidationError("Payment lookup request is required.");
2026
2161
  }
2027
2162
  const lacagId = this.lacagIdXaqiiji(codsi);
2028
- const { bixiye, laqabsade, laAbuuray, dhacayaa } = await this.bixiyeLacagKaHel(lacagId);
2163
+ const route = await this.bixiyeLacagKaHel(lacagId);
2164
+ const { bixiye, laqabsade, laAbuuray, dhacayaa } = route;
2029
2165
  this.awoodHubi(bixiye, "payment lookup", "paymentLookup");
2030
2166
  const expiredPayment = dhacayaa === undefined
2031
2167
  ? undefined
@@ -2034,8 +2170,8 @@ class IskuBixi {
2034
2170
  return expiredPayment;
2035
2171
  }
2036
2172
  const payment = await this.adapterCall(bixiye, "retrieve payment status", () => laqabsade.findPayment({ paymentId: lacagId }));
2037
- if (!payment) {
2038
- throw new Error(`Payment "${lacagId}" was not found.`);
2173
+ if (!providerPaymentMatches(payment, route)) {
2174
+ throw new errors_1.ProviderError(`Payment provider "${bixiye}" returned payment details that do not match the stored payment.`);
2039
2175
  }
2040
2176
  await __classPrivateFieldGet(this, _IskuBixi_transactionStore, "f").save(this.paymentToTransaction(payment, bixiye, laAbuuray, dhacayaa));
2041
2177
  const savedTransaction = waaKeydkaCelinLacagaha(__classPrivateFieldGet(this, _IskuBixi_transactionStore, "f"))
@@ -2087,8 +2223,12 @@ class IskuBixi {
2087
2223
  throw new Error(`Stored payment "${lacagId}" contains invalid routing or expiration data.`);
2088
2224
  }
2089
2225
  const route = {
2226
+ id: transaction.id,
2090
2227
  bixiye: transaction.bixiye,
2091
2228
  laqabsade: provider,
2229
+ amount: transaction.amount,
2230
+ currency: transaction.currency,
2231
+ reference: transaction.reference,
2092
2232
  furahaIdempotencyHash: transaction.furahaIdempotencyHash,
2093
2233
  codsiIdempotencyFingerprint: transaction.codsiIdempotencyFingerprint,
2094
2234
  laAbuuray: transaction.laAbuuray,
@@ -2122,6 +2262,12 @@ class IskuBixi {
2122
2262
  lacagta: payment.currency,
2123
2263
  xaalad: payment.status,
2124
2264
  tixraac: payment.reference,
2265
+ ...(payment.providerStatus === undefined
2266
+ ? {}
2267
+ : { providerStatus: payment.providerStatus }),
2268
+ ...(payment.nextAction === undefined
2269
+ ? {}
2270
+ : { nextAction: payment.nextAction }),
2125
2271
  ...(dhacayaa === undefined ? {} : { dhacayaa }),
2126
2272
  ...(celin === undefined ? {} : { celin })
2127
2273
  };
@@ -2140,6 +2286,9 @@ class IskuBixi {
2140
2286
  currency: payment.currency,
2141
2287
  reference: payment.reference,
2142
2288
  status: payment.status,
2289
+ ...(payment.providerStatus === undefined
2290
+ ? {}
2291
+ : { providerStatus: payment.providerStatus }),
2143
2292
  bixiye,
2144
2293
  laAbuuray,
2145
2294
  ...(dhacayaa === undefined ? {} : { dhacayaa })
@@ -12,6 +12,9 @@ export interface PaymentRequest {
12
12
  export interface PaymentIdRequest {
13
13
  paymentId: string;
14
14
  }
15
+ export interface PaymentConfirmationRequest extends PaymentIdRequest {
16
+ idempotencyKey: string;
17
+ }
15
18
  export interface PaymentRefundRequest extends PaymentIdRequest {
16
19
  idempotencyKey: string;
17
20
  }
@@ -29,6 +32,19 @@ export interface ProviderPayment {
29
32
  currency: string;
30
33
  reference: string;
31
34
  status: XaaladdaLacagta;
35
+ providerStatus?: string;
36
+ nextAction?: ProviderPaymentAction;
37
+ }
38
+ export type ProviderPaymentAction = {
39
+ type: "redirect";
40
+ url: string;
41
+ } | {
42
+ type: "client_secret";
43
+ clientSecret: string;
44
+ };
45
+ export interface ProviderPaymentFactoryOptions {
46
+ fetch?: typeof fetch;
47
+ timeoutMs?: number;
32
48
  }
33
49
  export type PaymentVerificationSource = "simulated" | "adapter";
34
50
  export interface PaymentVerification {
@@ -45,6 +61,7 @@ export interface PaymentProvider {
45
61
  createPayment(request: PaymentRequest): Promise<ProviderPayment>;
46
62
  findPayment(request: PaymentIdRequest): Promise<ProviderPayment | undefined>;
47
63
  verifyPayment(request: PaymentIdRequest): Promise<PaymentVerification>;
64
+ confirmPayment?(request: PaymentConfirmationRequest): Promise<ProviderPayment>;
48
65
  cancelPayment?(request: PaymentIdRequest): Promise<void>;
49
66
  refundPayment?(request: PaymentRefundRequest): Promise<ProviderRefund>;
50
67
  findRefundStatus?(request: PaymentRefundStatusRequest): Promise<ProviderRefund | undefined>;
@@ -0,0 +1,41 @@
1
+ import type { PaymentConfirmationRequest, PaymentIdRequest, PaymentProvider, PaymentProviderFactory, PaymentRefundRequest, PaymentRefundStatusRequest, PaymentRequest, PaymentVerification, ProviderCredentials, ProviderPayment, ProviderRefund } from "./payment-provider";
2
+ import type { CodsiWebhook, PaymentWebhookAdapter, PaymentWebhookEvent } from "./payment-webhook-adapter";
3
+ export type PayPalEnvironment = "sandbox" | "live";
4
+ export interface PayPalPaymentProviderOptions {
5
+ environment: PayPalEnvironment;
6
+ fetch?: typeof fetch;
7
+ timeoutMs?: number;
8
+ }
9
+ export interface PayPalWebhookAdapterOptions extends PayPalPaymentProviderOptions {
10
+ webhookId: string;
11
+ }
12
+ export declare class PayPalPaymentProvider implements PaymentProvider {
13
+ #private;
14
+ readonly capabilities: Readonly<{
15
+ paymentCreation: true;
16
+ paymentLookup: true;
17
+ paymentVerification: true;
18
+ paymentConfirmation: true;
19
+ paymentCancellation: false;
20
+ refundCreation: true;
21
+ refundStatusLookup: true;
22
+ paymentIdempotency: true;
23
+ }>;
24
+ constructor(credentials: ProviderCredentials, options: PayPalPaymentProviderOptions);
25
+ createPayment(request: PaymentRequest): Promise<ProviderPayment>;
26
+ findPayment(request: PaymentIdRequest): Promise<ProviderPayment | undefined>;
27
+ verifyPayment(request: PaymentIdRequest): Promise<PaymentVerification>;
28
+ confirmPayment(request: PaymentConfirmationRequest): Promise<ProviderPayment>;
29
+ refundPayment(request: PaymentRefundRequest): Promise<ProviderRefund>;
30
+ findRefundStatus(request: PaymentRefundStatusRequest): Promise<ProviderRefund | undefined>;
31
+ }
32
+ export declare class PayPalPaymentProviderFactory implements PaymentProviderFactory {
33
+ private readonly options;
34
+ constructor(options: PayPalPaymentProviderOptions);
35
+ create(credentials: ProviderCredentials): PaymentProvider;
36
+ }
37
+ export declare class PayPalWebhookAdapter implements PaymentWebhookAdapter {
38
+ #private;
39
+ constructor(credentials: ProviderCredentials, options: PayPalWebhookAdapterOptions);
40
+ verifyAndParse(request: CodsiWebhook): Promise<PaymentWebhookEvent>;
41
+ }