@nile-squad/nylonpay-ts 1.0.9 → 1.0.10

package/dist/index.d.cts

@@ -172,6 +172,12 @@ type Transaction = {
     type: TransactionType;
     method: PaymentMethod;
     description: string;
+    /**
+     * Present (true) when this response replayed an existing transaction because
+     * the reference was already used — same reference, same transaction. No new
+     * payment was initiated; use a fresh reference to start a new one.
+     */
+    duplicate?: boolean;
     phone: string;
     email: string | null;
     failureReason: string | null;
@@ -321,12 +327,15 @@ type NylonPayConfig = {
  * - `rate_limit` — too many requests.
  * - `account` — merchant account missing or not active.
  * - `provider` — payment provider/engine rejected the operation.
+ * - `duplicate` — the reference was already used for another transaction.
+ *   Retrying with a NEW reference will pass; reusing the same reference
+ *   replays the existing transaction instead of charging again.
  * - `not_found` — referenced transaction does not exist.
  * - `internal` — unexpected server-side failure.
  * - `network` — request never reached the server (DNS, TLS, connection).
  * - `timeout` — request exceeded the configured timeout.
  */
-type SdkErrorCategory = "auth" | "validation" | "limit" | "rate_limit" | "account" | "provider" | "not_found" | "internal" | "network" | "timeout";
+type SdkErrorCategory = "auth" | "validation" | "limit" | "rate_limit" | "account" | "provider" | "duplicate" | "not_found" | "internal" | "network" | "timeout";
 /**
  * Structured error returned by SDK operations. `category` is machine-readable
  * for branching logic; `message` is human-readable for logs and alerts.

package/dist/index.d.ts

@@ -172,6 +172,12 @@ type Transaction = {
     type: TransactionType;
     method: PaymentMethod;
     description: string;
+    /**
+     * Present (true) when this response replayed an existing transaction because
+     * the reference was already used — same reference, same transaction. No new
+     * payment was initiated; use a fresh reference to start a new one.
+     */
+    duplicate?: boolean;
     phone: string;
     email: string | null;
     failureReason: string | null;
@@ -321,12 +327,15 @@ type NylonPayConfig = {
  * - `rate_limit` — too many requests.
  * - `account` — merchant account missing or not active.
  * - `provider` — payment provider/engine rejected the operation.
+ * - `duplicate` — the reference was already used for another transaction.
+ *   Retrying with a NEW reference will pass; reusing the same reference
+ *   replays the existing transaction instead of charging again.
  * - `not_found` — referenced transaction does not exist.
  * - `internal` — unexpected server-side failure.
  * - `network` — request never reached the server (DNS, TLS, connection).
  * - `timeout` — request exceeded the configured timeout.
  */
-type SdkErrorCategory = "auth" | "validation" | "limit" | "rate_limit" | "account" | "provider" | "not_found" | "internal" | "network" | "timeout";
+type SdkErrorCategory = "auth" | "validation" | "limit" | "rate_limit" | "account" | "provider" | "duplicate" | "not_found" | "internal" | "network" | "timeout";
 /**
  * Structured error returned by SDK operations. `category` is machine-readable
  * for branching logic; `message` is human-readable for logs and alerts.

package/dist/index.js

@@ -147,6 +147,7 @@ var KNOWN_CATEGORIES = /* @__PURE__ */ new Set([
   "rate_limit",
   "account",
   "provider",
+  "duplicate",
   "not_found",
   "internal",
   "network",
@@ -593,6 +594,15 @@ function createPaymentInstance(initialResponse, deps) {
   }
   return paymentInstance;
 }
+
+// src/phone.ts
+function normalizePhone(phone) {
+  let normalized = phone.replace(/\s+/g, "").replace(/^\+/, "");
+  if (normalized.startsWith("0") && normalized.length === 10) {
+    normalized = `256${normalized.slice(1)}`;
+  }
+  return normalized;
+}
 var DEFAULT_TOLERANCE_SECONDS = 300;
 function decodePayload(payload) {
   return typeof payload === "string" ? payload : Buffer.from(payload).toString("utf8");
@@ -668,10 +678,21 @@ async function runHook(hook, ...args) {
 function throwValidation(message) {
   throw createSdkError({ category: "validation", message });
 }
-function validateAmount(amount) {
+function validateCollectionAmount(amount) {
+  if (!Number.isInteger(amount) || amount <= 0) {
+    throwValidation("amount must be a positive integer");
+  }
+  if (amount < 500) {
+    throwValidation("Collection amount must be at least 500 UGX");
+  }
+}
+function validatePayoutAmount(amount) {
   if (!Number.isInteger(amount) || amount <= 0) {
     throwValidation("amount must be a positive integer");
   }
+  if (amount < 5e3) {
+    throwValidation("Payout amount must be at least 5000 UGX");
+  }
 }
 function validateNonEmpty(value, fieldName) {
   if (!value || value.trim() === "") {
@@ -702,14 +723,19 @@ function createSdkInstance(config) {
   };
   async function collectPayment(input) {
     const reference = resolveReference(input.reference);
-    validateAmount(input.amount);
+    validateCollectionAmount(input.amount);
     validateNonEmpty(input.customer.name, "customer.name");
     validateNonEmpty(input.customer.phoneNumber, "customer.phoneNumber");
+    const normalizedPhone = normalizePhone(input.customer.phoneNumber);
     validateNonEmpty(input.description, "description");
     if (input.method === "bank" && !input.bank) {
       throwValidation('bank details are required when method is "bank"');
     }
-    let payload = { ...input, reference };
+    let payload = {
+      ...input,
+      reference,
+      customer: { ...input.customer, phoneNumber: normalizedPhone }
+    };
     const mutated = await runHook(config.hooks?.beforeCollect, payload);
     if (mutated != null)
       payload = { ...mutated, reference: mutated.reference ?? reference };
@@ -733,14 +759,19 @@ function createSdkInstance(config) {
   }
   async function collectPaymentAndResolve(input) {
     const reference = resolveReference(input.reference);
-    validateAmount(input.amount);
+    validateCollectionAmount(input.amount);
     validateNonEmpty(input.customer.name, "customer.name");
     validateNonEmpty(input.customer.phoneNumber, "customer.phoneNumber");
+    const normalizedPhone = normalizePhone(input.customer.phoneNumber);
     validateNonEmpty(input.description, "description");
     if (input.method === "bank" && !input.bank) {
       throwValidation('bank details are required when method is "bank"');
     }
-    let payload = { ...input, reference };
+    let payload = {
+      ...input,
+      reference,
+      customer: { ...input.customer, phoneNumber: normalizedPhone }
+    };
     const mutated = await runHook(config.hooks?.beforeCollect, payload);
     if (mutated != null)
       payload = { ...mutated, reference: mutated.reference ?? reference };
@@ -760,9 +791,10 @@ function createSdkInstance(config) {
   }
   async function makePayout(input) {
     const reference = resolveReference(input.reference);
-    validateAmount(input.amount);
+    validatePayoutAmount(input.amount);
     validateNonEmpty(input.customer.name, "customer.name");
     validateNonEmpty(input.customer.phoneNumber, "customer.phoneNumber");
+    const normalizedPhone = normalizePhone(input.customer.phoneNumber);
     validateNonEmpty(input.description, "description");
     validateNonEmpty(
       input.destination.accountHolderName,
@@ -772,7 +804,11 @@ function createSdkInstance(config) {
       input.destination.accountNumber,
       "destination.accountNumber"
     );
-    let payload = { ...input, reference };
+    let payload = {
+      ...input,
+      reference,
+      customer: { ...input.customer, phoneNumber: normalizedPhone }
+    };
     const mutated = await runHook(config.hooks?.beforePayout, payload);
     if (mutated != null)
       payload = { ...mutated, reference: mutated.reference ?? reference };
@@ -796,9 +832,10 @@ function createSdkInstance(config) {
   }
   async function makePayoutAndResolve(input) {
     const reference = resolveReference(input.reference);
-    validateAmount(input.amount);
+    validatePayoutAmount(input.amount);
     validateNonEmpty(input.customer.name, "customer.name");
     validateNonEmpty(input.customer.phoneNumber, "customer.phoneNumber");
+    const normalizedPhone = normalizePhone(input.customer.phoneNumber);
     validateNonEmpty(input.description, "description");
     validateNonEmpty(
       input.destination.accountHolderName,
@@ -808,7 +845,11 @@ function createSdkInstance(config) {
       input.destination.accountNumber,
       "destination.accountNumber"
     );
-    let payload = { ...input, reference };
+    let payload = {
+      ...input,
+      reference,
+      customer: { ...input.customer, phoneNumber: normalizedPhone }
+    };
     const mutated = await runHook(config.hooks?.beforePayout, payload);
     if (mutated != null)
       payload = { ...mutated, reference: mutated.reference ?? reference };
@@ -852,9 +893,10 @@ function createSdkInstance(config) {
   }
   async function verifyPhone(input) {
     validateNonEmpty(input.phoneNumber, "phoneNumber");
+    const normalizedPhone = normalizePhone(input.phoneNumber);
     const result = await transport.send({
       action: SDK_ACTIONS.verifyPhone,
-      payload: input
+      payload: { ...input, phoneNumber: normalizedPhone }
     });
     if (result.isOk) {
       return Ok(result.value);
@@ -863,7 +905,7 @@ function createSdkInstance(config) {
   }
   async function createInvoice(input) {
     const reference = resolveReference(input.reference);
-    validateAmount(input.amount);
+    validateCollectionAmount(input.amount);
     validateNonEmpty(input.description, "description");
     if (input.items) {
       if (input.items.length > 50) {