@nile-squad/nylonpay-ts 1.1.0 → 1.2.1

package/README.md

@@ -41,7 +41,7 @@ Use your test keys to work in sandbox, or your production keys to go live. There
 |---|---|---|---|
 | `apiKey` | Yes | | Must start with `npk_` |
 | `apiSecret` | Yes | | Must start with `nps_` |
-| `baseUrl` | No | Default is used | Override only if self-hosting |
+| `baseUrl` | No | Default is used | Override for a custom endpoint |
 | `timeoutMs` | No | `30000` | Request timeout in milliseconds |
 | `maxRetries` | No | `3` | Retry count for failed requests |
 | `maxPollIntervalMs` | No | `2000` | Polling interval for async payments |
@@ -231,16 +231,13 @@ if (!result.isOk) {
 
 `USD`, `EUR`, `GBP`, `KES`, `UGX`, `TZS`, `RWF`
 
-## Development
+## Links
 
-Maintainer notes and pending work live in [`dev-note.md`](./dev-note.md).
-
-```sh
-pnpm install
-pnpm test        # vitest
-pnpm typecheck   # tsc --noEmit
-pnpm build       # tsup
-```
+- [Documentation](https://docs.nylonpay.nilesquad.com/docs)
+- [SDK Spec](https://github.com/nile-squad/specs/blob/main/nylonpay-sdk-spec/spec.md)
+- [GitHub Repository](https://github.com/nile-squad/nylonpay-ts)
+- [Python SDK](https://github.com/nile-squad/nylonpay-py)
+- [Nylon Pay](https://nylonpay.nilesquad.com)
 
 ## License
 

package/dist/index.cjs

@@ -76,6 +76,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:${os.type()}`,
@@ -255,13 +256,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, {
@@ -270,6 +271,17 @@ function createTransport({
           body: bodyString,
           signal: controller.signal
         });
+        const contentLength = response.headers?.get("content-length");
+        if (contentLength && Number(contentLength) > MAX_RESPONSE_BYTES) {
+          cleanup();
+          return slangTs.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);
@@ -300,7 +312,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 +325,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 +340,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 +356,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) {
@@ -410,10 +422,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 = {
@@ -450,7 +468,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;
     }
@@ -472,7 +491,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();
   }
@@ -492,11 +511,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;
@@ -616,6 +641,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");
@@ -641,27 +669,34 @@ function extractSignedTimestampMs(payloadString) {
   return null;
 }
 function verifyWebhookSignature(input) {
-  const payloadString = decodePayload(input.payload);
-  const payloadBytes = Buffer.from(payloadString, "utf8");
-  const expectedSignature = crypto.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 (!crypto.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 = crypto.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 (!crypto.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
@@ -712,6 +747,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,
@@ -735,23 +820,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
@@ -759,35 +836,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
@@ -795,7 +864,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);
@@ -803,28 +872,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
@@ -832,40 +884,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
@@ -873,7 +908,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);
@@ -907,6 +942,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 }