@nile-squad/nylonpay-ts 1.1.0 → 1.2.0

package/dist/index.js

@@ -253,13 +253,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, {
@@ -298,7 +298,7 @@ function createTransport({
           return Err(
             JSON.stringify({
               category: "internal",
-              message: "Response missing status field",
+              message: "Received an invalid response from the server",
               retryable: false
             })
           );
@@ -311,7 +311,7 @@ function createTransport({
             return Err(
               JSON.stringify({
                 category: "internal",
-                message: "Response signature missing",
+                message: "Could not verify the server response",
                 retryable: false
               })
             );
@@ -326,7 +326,7 @@ function createTransport({
             return Err(
               JSON.stringify({
                 category: "internal",
-                message: "Response signature verification failed",
+                message: "Could not verify the server response",
                 retryable: false
               })
             );
@@ -342,7 +342,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) {
@@ -408,10 +408,16 @@ 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 = {
@@ -448,7 +454,8 @@ 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;
     }
@@ -470,7 +477,7 @@ function createPaymentInstance(initialResponse, deps) {
     if (parsed.category === "not_found") {
       return;
     }
-    emitEvent("error", parsed.message);
+    emitEvent("error", parsed.message, parsed.category, parsed.retryable);
     state.resolved = true;
     stopUpdates();
   }
@@ -490,11 +497,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;
@@ -614,6 +627,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");
@@ -710,6 +726,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,
@@ -733,23 +799,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
@@ -757,35 +815,27 @@ function createSdkInstance(config) {
     await runHook(
       config.hooks?.afterCollect,
       result.isOk ? Ok({ reference: result.value.reference, status: result.value.status }) : 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
@@ -793,7 +843,7 @@ function createSdkInstance(config) {
     await runHook(
       config.hooks?.afterCollect,
       result.isOk ? Ok({ reference: result.value.reference, status: result.value.status }) : Err(result.error),
-      payload
+      { ...payload, raw: input }
     );
     if (result.isOk) {
       return Ok(result.value);
@@ -801,28 +851,11 @@ function createSdkInstance(config) {
     return 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
@@ -830,40 +863,23 @@ function createSdkInstance(config) {
     await runHook(
       config.hooks?.afterPayout,
       result.isOk ? Ok({ reference: result.value.reference, status: result.value.status }) : 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
@@ -871,7 +887,7 @@ function createSdkInstance(config) {
     await runHook(
       config.hooks?.afterPayout,
       result.isOk ? Ok({ reference: result.value.reference, status: result.value.status }) : Err(result.error),
-      payload
+      { ...payload, raw: input }
     );
     if (result.isOk) {
       return Ok(result.value);
@@ -905,6 +921,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 }