@nile-squad/nylonpay-ts 1.0.10 → 1.2.0

package/dist/index.cjs

@@ -255,13 +255,13 @@ function createTransport({
   async function send(request) {
     const envelope = buildEnvelope(request);
     const signedPayload = envelope.payload;
-    const headers = buildAuthHeaders({
-      apiKey,
-      apiSecret,
-      payload: signedPayload
-    });
     const bodyString = JSON.stringify(envelope);
     async function attempt(currentAttempt) {
+      const headers = buildAuthHeaders({
+        apiKey,
+        apiSecret,
+        payload: signedPayload
+      });
       const { controller, cleanup } = withTimeout(timeoutMs);
       try {
         const response = await fetchImpl(baseUrl, {
@@ -300,7 +300,7 @@ function createTransport({
           return slangTs.Err(
             JSON.stringify({
               category: "internal",
-              message: "Response missing status field",
+              message: "Received an invalid response from the server",
               retryable: false
             })
           );
@@ -313,7 +313,7 @@ function createTransport({
             return slangTs.Err(
               JSON.stringify({
                 category: "internal",
-                message: "Response signature missing",
+                message: "Could not verify the server response",
                 retryable: false
               })
             );
@@ -328,7 +328,7 @@ function createTransport({
             return slangTs.Err(
               JSON.stringify({
                 category: "internal",
-                message: "Response signature verification failed",
+                message: "Could not verify the server response",
                 retryable: false
               })
             );
@@ -344,7 +344,7 @@ function createTransport({
         const isAbort = error instanceof DOMException && error.name === "AbortError";
         const sdkError = {
           category: isAbort ? "timeout" : "network",
-          message: isAbort ? `Request timed out after ${timeoutMs}ms` : String(error),
+          message: isAbort ? "The request timed out" : "Could not reach the server, check your network connection and try again",
           retryable: true
         };
         if (currentAttempt < maxRetries) {
@@ -375,6 +375,7 @@ function parseError(error) {
 
 // src/payment.ts
 var STATUS_TO_EVENT = {
+  pending: "processing",
   successful: "success",
   failed: "failed",
   processing: "processing",
@@ -398,6 +399,7 @@ function createPaymentInstance(initialResponse, deps) {
     status: normalizeStatus(initialResponse.status),
     transaction: null,
     pollingTimer: null,
+    lastStatusEvent: null,
     resolved: false,
     pollAttempts: 0,
     pollStartTime: Date.now(),
@@ -408,14 +410,21 @@ function createPaymentInstance(initialResponse, deps) {
     maxPollDuration: deps.maxPollDuration ?? 3e5,
     maxPollAttempts: deps.maxPollAttempts ?? 150
   };
-  function resolveWithError(error) {
+  function resolveWithError(error, category, retryable) {
     state.resolved = true;
     stopUpdates();
-    emitEvent("error", parseError(error).message);
+    const parsed = parseError(error);
+    emitEvent(
+      "error",
+      parsed.message,
+      category ?? parsed.category,
+      parsed.retryable
+    );
   }
   function emitEvent(event, error, category, retryable) {
     const data = {
       event,
+      reference: state.reference,
       transaction: state.transaction ?? void 0,
       error,
       category,
@@ -447,30 +456,30 @@ function createPaymentInstance(initialResponse, deps) {
     }
     if (response.reference !== state.reference) {
       resolveWithError(
-        `Reference mismatch: expected ${state.reference} but got ${response.reference}`
+        "Received a status update for a different transaction",
+        "internal"
       );
       return;
     }
     const newStatus = normalizeStatus(response.status);
-    const oldStatus = state.status;
     state.status = newStatus;
-    if (newStatus !== oldStatus) {
-      const event = statusToEvent(newStatus);
-      if (event) {
-        if (TERMINAL_STATES.has(newStatus)) {
-          await handleTerminalState(newStatus);
-          return;
-        }
-        emitEvent(event);
-      }
+    const event = statusToEvent(newStatus);
+    if (!event || event === state.lastStatusEvent) {
+      return;
     }
+    state.lastStatusEvent = event;
+    if (TERMINAL_STATES.has(newStatus)) {
+      await handleTerminalState(newStatus);
+      return;
+    }
+    emitEvent(event);
   }
   function handlePollError(error) {
     const parsed = parseError(error);
     if (parsed.category === "not_found") {
       return;
     }
-    emitEvent("error", parsed.message);
+    emitEvent("error", parsed.message, parsed.category, parsed.retryable);
     state.resolved = true;
     stopUpdates();
   }
@@ -490,11 +499,17 @@ function createPaymentInstance(initialResponse, deps) {
       return;
     }
     if (state.pollAttempts >= state.maxPollAttempts) {
-      resolveWithError("Polling timeout: exceeded maximum attempts");
+      resolveWithError(
+        "Timed out waiting for the transaction status to update",
+        "timeout"
+      );
       return;
     }
     if (Date.now() - state.pollStartTime >= state.maxPollDuration) {
-      resolveWithError("Polling timeout: exceeded maximum duration");
+      resolveWithError(
+        "Timed out waiting for the transaction status to update",
+        "timeout"
+      );
       return;
     }
     state.pollAttempts += 1;
@@ -517,6 +532,15 @@ function createPaymentInstance(initialResponse, deps) {
       }, 0);
       return;
     }
+    const initialEvent = statusToEvent(state.status);
+    if (initialEvent) {
+      state.lastStatusEvent = initialEvent;
+      setTimeout(() => {
+        if (!state.resolved) {
+          emitEvent(initialEvent);
+        }
+      }, 0);
+    }
     scheduleNextPoll();
   }
   function stopUpdates() {
@@ -605,6 +629,9 @@ function normalizePhone(phone) {
   }
   return normalized;
 }
+function isValidPhoneFormat(normalizedPhone) {
+  return /^\d{9,15}$/.test(normalizedPhone);
+}
 var DEFAULT_TOLERANCE_SECONDS = 300;
 function decodePayload(payload) {
   return typeof payload === "string" ? payload : Buffer.from(payload).toString("utf8");
@@ -701,6 +728,56 @@ function validateNonEmpty(value, fieldName) {
     throwValidation(`${fieldName} is required`);
   }
 }
+function validatePhoneFormat(normalizedPhone, fieldName) {
+  if (!isValidPhoneFormat(normalizedPhone)) {
+    throwValidation(`${fieldName} must be a valid phone number`);
+  }
+}
+function prepareCollectPayload(input) {
+  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);
+  validatePhoneFormat(normalizedPhone, "customer.phoneNumber");
+  validateNonEmpty(input.description, "description");
+  if (input.method === "bank" && !input.bank) {
+    throwValidation('bank details are required when method is "bank"');
+  }
+  return {
+    ...input,
+    reference,
+    customer: { ...input.customer, phoneNumber: normalizedPhone }
+  };
+}
+function preparePayoutPayload(input) {
+  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);
+  validatePhoneFormat(normalizedPhone, "customer.phoneNumber");
+  validateNonEmpty(input.description, "description");
+  validateNonEmpty(
+    input.destination.accountHolderName,
+    "destination.accountHolderName"
+  );
+  validateNonEmpty(
+    input.destination.accountNumber,
+    "destination.accountNumber"
+  );
+  return {
+    ...input,
+    reference,
+    customer: { ...input.customer, phoneNumber: normalizedPhone }
+  };
+}
+function applyBeforeHookMutation(mutated, current, prepare) {
+  return prepare({
+    ...mutated,
+    reference: mutated.reference ?? current.reference
+  });
+}
 function createSdkInstance(config) {
   const transport = createTransport({
     apiKey: config.apiKey,
@@ -724,23 +801,15 @@ function createSdkInstance(config) {
     maxPollAttempts: config.maxPollAttempts
   };
   async function collectPayment(input) {
-    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,
-      customer: { ...input.customer, phoneNumber: normalizedPhone }
-    };
+    let payload = prepareCollectPayload(input);
     const mutated = await runHook(config.hooks?.beforeCollect, payload);
-    if (mutated != null)
-      payload = { ...mutated, reference: mutated.reference ?? reference };
+    if (mutated != null) {
+      payload = applyBeforeHookMutation(
+        mutated,
+        payload,
+        prepareCollectPayload
+      );
+    }
     const result = await transport.send({
       action: SDK_ACTIONS.collectPayment,
       payload
@@ -748,35 +817,27 @@ function createSdkInstance(config) {
     await runHook(
       config.hooks?.afterCollect,
       result.isOk ? slangTs.Ok({ reference: result.value.reference, status: result.value.status }) : slangTs.Err(result.error),
-      payload
+      { ...payload, raw: input }
     );
     if (result.isErr) {
       const sdkErr = parseError(result.error);
       return createPaymentInstance(
-        { reference, status: "pending" },
+        { reference: payload.reference, status: "pending" },
         { ...commonDeps, initialError: sdkErr }
       );
     }
     return createPaymentInstance(result.value, commonDeps);
   }
   async function collectPaymentAndResolve(input) {
-    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,
-      customer: { ...input.customer, phoneNumber: normalizedPhone }
-    };
+    let payload = prepareCollectPayload(input);
     const mutated = await runHook(config.hooks?.beforeCollect, payload);
-    if (mutated != null)
-      payload = { ...mutated, reference: mutated.reference ?? reference };
+    if (mutated != null) {
+      payload = applyBeforeHookMutation(
+        mutated,
+        payload,
+        prepareCollectPayload
+      );
+    }
     const result = await transport.send({
       action: SDK_ACTIONS.collectPaymentAndResolve,
       payload
@@ -784,7 +845,7 @@ function createSdkInstance(config) {
     await runHook(
       config.hooks?.afterCollect,
       result.isOk ? slangTs.Ok({ reference: result.value.reference, status: result.value.status }) : slangTs.Err(result.error),
-      payload
+      { ...payload, raw: input }
     );
     if (result.isOk) {
       return slangTs.Ok(result.value);
@@ -792,28 +853,11 @@ function createSdkInstance(config) {
     return slangTs.Err(result.error);
   }
   async function makePayout(input) {
-    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,
-      "destination.accountHolderName"
-    );
-    validateNonEmpty(
-      input.destination.accountNumber,
-      "destination.accountNumber"
-    );
-    let payload = {
-      ...input,
-      reference,
-      customer: { ...input.customer, phoneNumber: normalizedPhone }
-    };
+    let payload = preparePayoutPayload(input);
     const mutated = await runHook(config.hooks?.beforePayout, payload);
-    if (mutated != null)
-      payload = { ...mutated, reference: mutated.reference ?? reference };
+    if (mutated != null) {
+      payload = applyBeforeHookMutation(mutated, payload, preparePayoutPayload);
+    }
     const result = await transport.send({
       action: SDK_ACTIONS.makePayout,
       payload
@@ -821,40 +865,23 @@ function createSdkInstance(config) {
     await runHook(
       config.hooks?.afterPayout,
       result.isOk ? slangTs.Ok({ reference: result.value.reference, status: result.value.status }) : slangTs.Err(result.error),
-      payload
+      { ...payload, raw: input }
     );
     if (result.isErr) {
       const sdkErr = parseError(result.error);
       return createPaymentInstance(
-        { reference, status: "pending" },
+        { reference: payload.reference, status: "pending" },
         { ...commonDeps, initialError: sdkErr }
       );
     }
     return createPaymentInstance(result.value, commonDeps);
   }
   async function makePayoutAndResolve(input) {
-    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,
-      "destination.accountHolderName"
-    );
-    validateNonEmpty(
-      input.destination.accountNumber,
-      "destination.accountNumber"
-    );
-    let payload = {
-      ...input,
-      reference,
-      customer: { ...input.customer, phoneNumber: normalizedPhone }
-    };
+    let payload = preparePayoutPayload(input);
     const mutated = await runHook(config.hooks?.beforePayout, payload);
-    if (mutated != null)
-      payload = { ...mutated, reference: mutated.reference ?? reference };
+    if (mutated != null) {
+      payload = applyBeforeHookMutation(mutated, payload, preparePayoutPayload);
+    }
     const result = await transport.send({
       action: SDK_ACTIONS.makePayoutAndResolve,
       payload
@@ -862,7 +889,7 @@ function createSdkInstance(config) {
     await runHook(
       config.hooks?.afterPayout,
       result.isOk ? slangTs.Ok({ reference: result.value.reference, status: result.value.status }) : slangTs.Err(result.error),
-      payload
+      { ...payload, raw: input }
     );
     if (result.isOk) {
       return slangTs.Ok(result.value);
@@ -896,6 +923,7 @@ function createSdkInstance(config) {
   async function verifyPhone(input) {
     validateNonEmpty(input.phoneNumber, "phoneNumber");
     const normalizedPhone = normalizePhone(input.phoneNumber);
+    validatePhoneFormat(normalizedPhone, "phoneNumber");
     const result = await transport.send({
       action: SDK_ACTIONS.verifyPhone,
       payload: { ...input, phoneNumber: normalizedPhone }