@nile-squad/nylonpay-ts 1.1.0 → 1.2.1

package/dist/index.js

@@ -74,6 +74,7 @@ var SDK_ACTIONS = {
   createInvoice: "sdk-create-invoice"
 };
 var RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
+var MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
 function generateFingerprint() {
   const components = [
     `type:${type()}`,
@@ -253,13 +254,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, {
@@ -268,6 +269,17 @@ function createTransport({
           body: bodyString,
           signal: controller.signal
         });
+        const contentLength = response.headers?.get("content-length");
+        if (contentLength && Number(contentLength) > MAX_RESPONSE_BYTES) {
+          cleanup();
+          return Err(
+            JSON.stringify({
+              category: "internal",
+              message: "Received an invalid response from the server",
+              retryable: false
+            })
+          );
+        }
         if (!response.ok) {
           const statusCode = response.status;
           const retryable = RETRYABLE_STATUS_CODES.has(statusCode);
@@ -298,7 +310,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 +323,7 @@ function createTransport({
             return Err(
               JSON.stringify({
                 category: "internal",
-                message: "Response signature missing",
+                message: "Could not verify the server response",
                 retryable: false
               })
             );
@@ -326,7 +338,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 +354,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 +420,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 +466,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 +489,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 +509,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 +639,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");
@@ -639,27 +667,34 @@ function extractSignedTimestampMs(payloadString) {
   return null;
 }
 function verifyWebhookSignature(input) {
-  const payloadString = decodePayload(input.payload);
-  const payloadBytes = Buffer.from(payloadString, "utf8");
-  const expectedSignature = createHmac("sha256", input.secret).update(payloadBytes).digest("hex");
-  const providedBuffer = Buffer.from(input.signature, "hex");
-  const expectedBuffer = Buffer.from(expectedSignature, "hex");
-  if (providedBuffer.length !== expectedBuffer.length) {
-    return false;
-  }
-  if (!timingSafeEqual(providedBuffer, expectedBuffer)) {
-    return false;
-  }
-  const toleranceSeconds = input.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
-  if (toleranceSeconds <= 0) {
-    return true;
-  }
-  const timestampMs = extractSignedTimestampMs(payloadString);
-  if (timestampMs === null) {
+  try {
+    const payloadString = decodePayload(input.payload);
+    const payloadBytes = Buffer.from(payloadString, "utf8");
+    const expectedSignature = createHmac("sha256", input.secret).update(payloadBytes).digest("hex");
+    const providedBuffer = Buffer.from(input.signature, "hex");
+    const expectedBuffer = Buffer.from(expectedSignature, "hex");
+    if (providedBuffer.length !== expectedBuffer.length) {
+      return false;
+    }
+    if (!timingSafeEqual(providedBuffer, expectedBuffer)) {
+      return false;
+    }
+    const toleranceSeconds = input.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+    if (toleranceSeconds === 0) {
+      return true;
+    }
+    if (toleranceSeconds < 0) {
+      return false;
+    }
+    const timestampMs = extractSignedTimestampMs(payloadString);
+    if (timestampMs === null) {
+      return false;
+    }
+    const ageMs = Math.abs(Date.now() - timestampMs);
+    return ageMs <= toleranceSeconds * 1e3;
+  } catch {
     return false;
   }
-  const ageMs = Math.abs(Date.now() - timestampMs);
-  return ageMs <= toleranceSeconds * 1e3;
 }
 
 // src/sdk.ts
@@ -710,6 +745,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 +818,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 +834,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 +862,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 +870,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 +882,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 +906,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 +940,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 }