@nile-squad/nylonpay-ts 1.0.8 → 1.0.10

package/README.md

@@ -2,7 +2,7 @@
 
 Server-side SDK for integrating Nylon Pay into merchant applications. Supports TypeScript and JavaScript (ESM and CJS).
 
-This package is the reference implementation of the [Nylon Pay SDK Spec](https://github.com/nile-squad/specs/blob/main/nylon-pay/sdk-spec.md) — the canonical, language-agnostic contract for building Nylon Pay SDKs in any language.
+This package is the reference implementation of the [Nylon Pay SDK Spec](https://github.com/nile-squad/specs/blob/main/nylonpay-sdk-spec/spec.md) — the canonical, language-agnostic contract for building Nylon Pay SDKs in any language.
 
 [Full documentation](https://docs.nylonpay.nilesquad.com/docs)
 
@@ -61,14 +61,16 @@ const payment = await nylonpay.collectPayment({
   customer: { name: "Jane", phoneNumber: "+256700000000" },
   description: "Order #1234",
   method: "mobileMoney",
-  reference: "ORDER-123",
+  reference: "ORDER-2026-001",
 });
 
 payment.on("success", ({ transaction }) => { /* ... */ });
 payment.on("failed", ({ error }) => { /* ... */ });
 ```
 
-`reference` is optional and auto-generated if omitted.
+`reference` is optional and auto-generated if omitted. A supplied reference must be
+**13 to 15 characters**; the SDK throws a `validation` error otherwise. A raw UUID is
+36 characters and will be rejected, so use a short id of your own or omit the field.
 
 ### collectPaymentAndResolve
 
@@ -120,7 +122,7 @@ const result = await nylonpay.makePayoutAndResolve({
 One-shot status check for a transaction. Does not poll, returns the current server-side state.
 
 ```ts
-const result = await nylonpay.getStatus({ reference: "ORDER-123" });
+const result = await nylonpay.getStatus({ reference: "ORDER-2026-001" });
 if (result.isOk) console.log(result.value.status);
 ```
 
@@ -129,7 +131,7 @@ if (result.isOk) console.log(result.value.status);
 Look up a full transaction record by `id` or `reference`. At least one must be provided.
 
 ```ts
-const result = await nylonpay.getTransaction({ reference: "ORDER-123" });
+const result = await nylonpay.getTransaction({ reference: "ORDER-2026-001" });
 if (result.isOk) console.log(result.value.failureReason);
 ```
 
@@ -216,7 +218,7 @@ All operations return `Result<T, string>` from [slang-ts](https://github.com/nil
 ```ts
 import { parseError } from "@nile-squad/nylonpay-ts";
 
-const result = await nylonpay.getStatus({ reference: "ORDER-123" });
+const result = await nylonpay.getStatus({ reference: "ORDER-2026-001" });
 if (!result.isOk) {
   const error = parseError(result.error);
   if (error.retryable) {

package/dist/index.cjs

@@ -149,6 +149,7 @@ var KNOWN_CATEGORIES = /* @__PURE__ */ new Set([
   "rate_limit",
   "account",
   "provider",
+  "duplicate",
   "not_found",
   "internal",
   "network",
@@ -595,6 +596,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");
@@ -647,6 +657,19 @@ function verifyWebhookSignature(input) {
 function generateReference() {
   return crypto.randomBytes(16).toString("hex").slice(0, 15);
 }
+var REFERENCE_MIN_LENGTH = 13;
+var REFERENCE_MAX_LENGTH = 15;
+function resolveReference(reference) {
+  if (reference === void 0) {
+    return generateReference();
+  }
+  if (reference.length < REFERENCE_MIN_LENGTH || reference.length > REFERENCE_MAX_LENGTH) {
+    throwValidation(
+      `reference must be ${REFERENCE_MIN_LENGTH}\u2013${REFERENCE_MAX_LENGTH} characters`
+    );
+  }
+  return reference;
+}
 async function runHook(hook, ...args) {
   if (!hook || hook.enabled === false) return void 0;
   const result = await slangTs.safeTry(async () => hook.fn(...args));
@@ -657,10 +680,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() === "") {
@@ -690,15 +724,20 @@ function createSdkInstance(config) {
     maxPollAttempts: config.maxPollAttempts
   };
   async function collectPayment(input) {
-    const reference = input.reference ?? generateReference();
-    validateAmount(input.amount);
+    const reference = resolveReference(input.reference);
+    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 };
@@ -721,15 +760,20 @@ function createSdkInstance(config) {
     return createPaymentInstance(result.value, commonDeps);
   }
   async function collectPaymentAndResolve(input) {
-    const reference = input.reference ?? generateReference();
-    validateAmount(input.amount);
+    const reference = resolveReference(input.reference);
+    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 };
@@ -748,10 +792,11 @@ function createSdkInstance(config) {
     return slangTs.Err(result.error);
   }
   async function makePayout(input) {
-    const reference = input.reference ?? generateReference();
-    validateAmount(input.amount);
+    const reference = resolveReference(input.reference);
+    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,
@@ -761,7 +806,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 };
@@ -784,10 +833,11 @@ function createSdkInstance(config) {
     return createPaymentInstance(result.value, commonDeps);
   }
   async function makePayoutAndResolve(input) {
-    const reference = input.reference ?? generateReference();
-    validateAmount(input.amount);
+    const reference = resolveReference(input.reference);
+    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,
@@ -797,7 +847,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 };
@@ -841,9 +895,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 slangTs.Ok(result.value);
@@ -851,8 +906,8 @@ function createSdkInstance(config) {
     return slangTs.Err(result.error);
   }
   async function createInvoice(input) {
-    const reference = input.reference ?? generateReference();
-    validateAmount(input.amount);
+    const reference = resolveReference(input.reference);
+    validateCollectionAmount(input.amount);
     validateNonEmpty(input.description, "description");
     if (input.items) {
       if (input.items.length > 50) {