@nile-squad/nylonpay-ts 1.0.10 → 1.2.0

package/dist/index.d.ts

@@ -178,6 +178,13 @@ type Transaction = {
      * payment was initiated; use a fresh reference to start a new one.
      */
     duplicate?: boolean;
+    /**
+     * The underlying operator's (telco's/bank's) own transaction id — what the
+     * paying customer sees on their receipt. Use it to cross-validate customer
+     * pay claims. Null until the operator reports it (typically at terminal
+     * status); may be absent on older backend versions.
+     */
+    operatorTid?: string | null;
     phone: string;
     email: string | null;
     failureReason: string | null;
@@ -235,16 +242,27 @@ type WebhookPayload = {
  * Async hooks are awaited before the transport call proceeds.
  */
 type BeforeCollectHook = (input: CollectPaymentInput) => CollectPaymentInput | undefined | Promise<CollectPaymentInput | undefined>;
+/**
+ * The input handed to an `after*` hook. It is the final wire payload — reference
+ * resolved, phone normalized, and any `before*`-hook mutations applied — so a
+ * hook observes exactly what was sent. The `raw` property additionally carries
+ * the untouched original merchant input (pre-normalization, pre-`before*`-hook),
+ * so audit logs can record both what the merchant typed and what hit the wire.
+ */
+type AfterHookInput<TInput> = TInput & {
+    raw: TInput;
+};
 /**
  * Called after every collect call (both fire-and-forget and resolve variants)
  * regardless of outcome. Use for logging, analytics, or side-effects.
  * The result is normalized to `{ reference, status }` across both variants.
+ * `input` is the sent payload; `input.raw` is the original merchant input.
  * Return value is ignored.
  */
 type AfterCollectHook = (result: Result<{
     reference: string;
     status: string;
-}, string>, input: CollectPaymentInput) => void | Promise<void>;
+}, string>, input: AfterHookInput<CollectPaymentInput>) => void | Promise<void>;
 /**
  * Called before a payout payload is sent to the server.
  * Same semantics as {@link BeforeCollectHook}.
@@ -258,7 +276,7 @@ type BeforePayoutHook = (input: MakePayoutInput) => MakePayoutInput | undefined
 type AfterPayoutHook = (result: Result<{
     reference: string;
     status: string;
-}, string>, input: MakePayoutInput) => void | Promise<void>;
+}, string>, input: AfterHookInput<MakePayoutInput>) => void | Promise<void>;
 /**
  * Wrapper applied to every lifecycle hook. The SDK runs `fn` inside `safeTry`,
  * so a throw or rejection in merchant code never bubbles into the payment flow —
@@ -348,15 +366,17 @@ type SdkError = {
     retryable?: boolean;
 };
 /**
- * Data passed to every payment event handler. `transaction` is populated
- * for status-change events (`processing`, `success`, `failed`, `cancelled`);
- * `error` is populated for the `"error"` event (network failure, timeout,
- * reference mismatch).
+ * Data passed to every payment event handler. `reference` is always present;
+ * `transaction` is populated for terminal status events (`success`, `failed`,
+ * `cancelled`) — the `processing` event can fire before the full record is
+ * fetched, so use `reference` there. `error` is populated for the `"error"`
+ * event (network failure, timeout, reference mismatch).
  *
  * @example
  * ```ts
  * payment.on("success", (data: EventData) => {
- *   console.log(data.transaction?.reference); // "ORDER-2026-001"
+ *   console.log(data.reference);              // "ORDER-2026-001"
+ *   console.log(data.transaction?.id);
  *   console.log(data.timestamp);              // "2026-05-30T12:00:00.000Z"
  * });
  * ```
@@ -364,7 +384,13 @@ type SdkError = {
 type EventData = {
     /** The event that triggered this handler. */
     event: PaymentEvent;
-    /** Full transaction record. Present for status-change events. */
+    /**
+     * The transaction reference. Always present — available on every event,
+     * including lifecycle events fired before the full transaction record
+     * has been fetched.
+     */
+    reference: string;
+    /** Full transaction record. Present for terminal status events. */
     transaction?: Transaction;
     /** Error message. Present for the `"error"` event. */
     error?: string;
@@ -713,4 +739,4 @@ declare function parseError(error: string): SdkError;
  */
 declare function verifyWebhookSignature(input: VerifyWebhookInput): boolean;
 
-export { type AfterCollectHook, type AfterPayoutHook, type BankDetails, type BeforeCollectHook, type BeforePayoutHook, type CollectPaymentInput, type CreateInvoiceInput, type Currency, type Customer, type Destination, type EventData, type GetStatusInput, type GetTransactionInput, type InvoiceItem, type InvoiceResponse, type MakePayoutInput, type NylonPayConfig, type NylonPaySdk, type PaymentEvent, type PaymentEventHandler, type PaymentInstance, type PaymentMethod, type PhoneVerification, type SdkError, type SdkErrorCategory, type SdkHooks, type StatusResponse, type Transaction, type TransactionMode, type TransactionStatus, type TransactionType, type VerifyPhoneInput, type VerifyWebhookInput, type WebhookEventType, type WebhookPayload, createNylonPay, createSdkError, parseError, verifyWebhookSignature };
+export { type AfterCollectHook, type AfterHookInput, type AfterPayoutHook, type BankDetails, type BeforeCollectHook, type BeforePayoutHook, type CollectPaymentInput, type CreateInvoiceInput, type Currency, type Customer, type Destination, type EventData, type GetStatusInput, type GetTransactionInput, type InvoiceItem, type InvoiceResponse, type MakePayoutInput, type NylonPayConfig, type NylonPaySdk, type PaymentEvent, type PaymentEventHandler, type PaymentInstance, type PaymentMethod, type PhoneVerification, type SdkError, type SdkErrorCategory, type SdkHooks, type StatusResponse, type Transaction, type TransactionMode, type TransactionStatus, type TransactionType, type VerifyPhoneInput, type VerifyWebhookInput, type WebhookEventType, type WebhookPayload, createNylonPay, createSdkError, parseError, verifyWebhookSignature };

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) {
@@ -373,6 +373,7 @@ function parseError(error) {
 
 // src/payment.ts
 var STATUS_TO_EVENT = {
+  pending: "processing",
   successful: "success",
   failed: "failed",
   processing: "processing",
@@ -396,6 +397,7 @@ function createPaymentInstance(initialResponse, deps) {
     status: normalizeStatus(initialResponse.status),
     transaction: null,
     pollingTimer: null,
+    lastStatusEvent: null,
     resolved: false,
     pollAttempts: 0,
     pollStartTime: Date.now(),
@@ -406,14 +408,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,
@@ -445,30 +454,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();
   }
@@ -488,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;
@@ -515,6 +530,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() {
@@ -603,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");
@@ -699,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,
@@ -722,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
@@ -746,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
@@ -782,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);
@@ -790,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
@@ -819,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
@@ -860,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);
@@ -894,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 }