@nile-squad/nylonpay-ts 1.0.7 → 1.0.9

package/README.md

@@ -2,7 +2,7 @@
 
 Server-side SDK for integrating Nylon Pay into merchant applications. Supports TypeScript and JavaScript (ESM and CJS).
 
-This package is the reference implementation of the [Nylon Pay SDK Spec](https://github.com/nile-squad/specs/blob/main/nylon-pay/sdk-spec.md) — the canonical, language-agnostic contract for building Nylon Pay SDKs in any language.
+This package is the reference implementation of the [Nylon Pay SDK Spec](https://github.com/nile-squad/specs/blob/main/nylonpay-sdk-spec/spec.md) — the canonical, language-agnostic contract for building Nylon Pay SDKs in any language.
 
 [Full documentation](https://docs.nylonpay.nilesquad.com/docs)
 
@@ -61,14 +61,16 @@ const payment = await nylonpay.collectPayment({
   customer: { name: "Jane", phoneNumber: "+256700000000" },
   description: "Order #1234",
   method: "mobileMoney",
-  reference: "ORDER-123",
+  reference: "ORDER-2026-001",
 });
 
 payment.on("success", ({ transaction }) => { /* ... */ });
 payment.on("failed", ({ error }) => { /* ... */ });
 ```
 
-`reference` is optional and auto-generated if omitted.
+`reference` is optional and auto-generated if omitted. A supplied reference must be
+**13 to 15 characters**; the SDK throws a `validation` error otherwise. A raw UUID is
+36 characters and will be rejected, so use a short id of your own or omit the field.
 
 ### collectPaymentAndResolve
 
@@ -120,7 +122,7 @@ const result = await nylonpay.makePayoutAndResolve({
 One-shot status check for a transaction. Does not poll, returns the current server-side state.
 
 ```ts
-const result = await nylonpay.getStatus({ reference: "ORDER-123" });
+const result = await nylonpay.getStatus({ reference: "ORDER-2026-001" });
 if (result.isOk) console.log(result.value.status);
 ```
 
@@ -129,7 +131,7 @@ if (result.isOk) console.log(result.value.status);
 Look up a full transaction record by `id` or `reference`. At least one must be provided.
 
 ```ts
-const result = await nylonpay.getTransaction({ reference: "ORDER-123" });
+const result = await nylonpay.getTransaction({ reference: "ORDER-2026-001" });
 if (result.isOk) console.log(result.value.failureReason);
 ```
 
@@ -216,7 +218,7 @@ All operations return `Result<T, string>` from [slang-ts](https://github.com/nil
 ```ts
 import { parseError } from "@nile-squad/nylonpay-ts";
 
-const result = await nylonpay.getStatus({ reference: "ORDER-123" });
+const result = await nylonpay.getStatus({ reference: "ORDER-2026-001" });
 if (!result.isOk) {
   const error = parseError(result.error);
   if (error.retryable) {

package/dist/index.cjs

@@ -4,7 +4,7 @@ var crypto = require('crypto');
 var slangTs = require('slang-ts');
 var os = require('os');
 
-// src/sdk.ts
+// src/create-nylon-pay.ts
 
 // src/pubsub.ts
 function createEmitter() {
@@ -63,9 +63,7 @@ var DEFAULT_MAX_RETRIES = 3;
 var DEFAULT_MAX_POLL_INTERVAL_MS = 2e3;
 var DEFAULT_MAX_POLL_DURATION_MS = 3e5;
 var DEFAULT_MAX_POLL_ATTEMPTS = 150;
-var DEFAULT_STREAMING = true;
-var STREAM_PATH = "/sse/transaction";
-var MAX_STREAM_RECONNECTS = 2;
+var POLL_JITTER_MS = 250;
 var SDK_SERVICE = "sdk";
 var SDK_ACTIONS = {
   collectPayment: "sdk-collect-payment",
@@ -93,13 +91,22 @@ function generateFingerprint() {
 function generateNonce(length = 16) {
   return crypto.randomBytes(length).toString("hex");
 }
+function compareByCodePoint(first, second) {
+  if (first < second) {
+    return -1;
+  }
+  if (first > second) {
+    return 1;
+  }
+  return 0;
+}
 function sortValue(value) {
   if (Array.isArray(value)) {
     return value.map((entry) => sortValue(entry));
   }
   if (value && typeof value === "object") {
     const sortedEntries = Object.entries(value).sort(
-      ([firstKey], [secondKey]) => firstKey.localeCompare(secondKey)
+      ([firstKey], [secondKey]) => compareByCodePoint(firstKey, secondKey)
     );
     return Object.fromEntries(
       sortedEntries.map(([entryKey, entryValue]) => [
@@ -123,42 +130,6 @@ function createSignature(input) {
 function createTimestamp() {
   return Date.now().toString();
 }
-
-// src/sse-parse.ts
-function parseBlock(block) {
-  let event = "message";
-  const dataLines = [];
-  for (const rawLine of block.split("\n")) {
-    const line = rawLine.replace(/\r$/, "");
-    if (line.startsWith(":")) {
-      continue;
-    }
-    if (line.startsWith("event:")) {
-      event = line.slice("event:".length).trim();
-    } else if (line.startsWith("data:")) {
-      dataLines.push(line.slice("data:".length).trim());
-    }
-  }
-  if (dataLines.length === 0) {
-    return null;
-  }
-  return { event, data: dataLines.join("\n") };
-}
-function parseSseBuffer(buffer) {
-  const messages = [];
-  let rest = buffer;
-  let separator = rest.indexOf("\n\n");
-  while (separator !== -1) {
-    const block = rest.slice(0, separator);
-    rest = rest.slice(separator + 2);
-    const message = parseBlock(block);
-    if (message) {
-      messages.push(message);
-    }
-    separator = rest.indexOf("\n\n");
-  }
-  return { messages, rest };
-}
 function verifyResponseSignature(data, signature, secret) {
   const expectedSignature = crypto.createHmac("sha256", secret).update(createCanonicalPayload(data)).digest("hex");
   const providedBuffer = Buffer.from(signature, "hex");
@@ -171,13 +142,6 @@ function verifyResponseSignature(data, signature, secret) {
 
 // src/transport.ts
 var CACHED_FINGERPRINT = generateFingerprint();
-function streamUrl(baseUrl) {
-  try {
-    return new URL(baseUrl).origin + STREAM_PATH;
-  } catch {
-    return baseUrl.replace(/\/api\/services\/?$/u, "") + STREAM_PATH;
-  }
-}
 var KNOWN_CATEGORIES = /* @__PURE__ */ new Set([
   "auth",
   "validation",
@@ -343,22 +307,30 @@ function createTransport({
         const { status, message, data } = responseBody;
         if (status === true) {
           const { data: strippedData, responseSignature } = stripResponseSignature(data);
-          if (responseSignature) {
-            const isValid = verifyResponseSignature(
-              strippedData,
-              responseSignature,
-              apiSecret
+          if (!responseSignature) {
+            cleanup();
+            return slangTs.Err(
+              JSON.stringify({
+                category: "internal",
+                message: "Response signature missing",
+                retryable: false
+              })
+            );
+          }
+          const isValid = verifyResponseSignature(
+            strippedData,
+            responseSignature,
+            apiSecret
+          );
+          if (!isValid) {
+            cleanup();
+            return slangTs.Err(
+              JSON.stringify({
+                category: "internal",
+                message: "Response signature verification failed",
+                retryable: false
+              })
             );
-            if (!isValid) {
-              cleanup();
-              return slangTs.Err(
-                JSON.stringify({
-                  category: "internal",
-                  message: "Response signature verification failed",
-                  retryable: false
-                })
-              );
-            }
           }
           cleanup();
           return slangTs.Ok(strippedData);
@@ -383,91 +355,7 @@ function createTransport({
     }
     return attempt(0);
   }
-  function openStream(input) {
-    const controller = new AbortController();
-    let closed = false;
-    const close = () => {
-      if (closed) {
-        return;
-      }
-      closed = true;
-      controller.abort();
-    };
-    const payload = {
-      reference: input.reference,
-      _fingerprint: CACHED_FINGERPRINT
-    };
-    const headers = buildAuthHeaders({ apiKey, apiSecret, payload });
-    const url = streamUrl(baseUrl);
-    const run = async () => {
-      const fetchResult = await slangTs.safeTry(
-        () => fetchImpl(url, {
-          method: "POST",
-          headers,
-          body: JSON.stringify(payload),
-          signal: controller.signal
-        })
-      );
-      if (fetchResult.isErr) {
-        if (!closed) {
-          input.onError(fetchResult.error);
-        }
-        return;
-      }
-      const response = fetchResult.value;
-      if (!response.ok || !response.body) {
-        const textResult = await slangTs.safeTry(() => response.text());
-        const message = textResult.isOk ? textResult.value : `HTTP ${response.status}`;
-        if (!closed) {
-          input.onError(message || `HTTP ${response.status}`);
-        }
-        return;
-      }
-      const reader = response.body.getReader();
-      const decoder = new TextDecoder();
-      let buffer = "";
-      while (!closed) {
-        const chunkResult = await slangTs.safeTry(() => reader.read());
-        if (chunkResult.isErr) {
-          if (!closed) {
-            input.onError(chunkResult.error);
-          }
-          return;
-        }
-        const chunk = chunkResult.value;
-        if (chunk.done) {
-          break;
-        }
-        buffer += decoder.decode(chunk.value, { stream: true });
-        const { messages, rest } = parseSseBuffer(buffer);
-        buffer = rest;
-        for (const message of messages) {
-          if (message.event === "status") {
-            const statusResult = await slangTs.safeTry(
-              () => JSON.parse(message.data)
-            );
-            if (statusResult.isOk) {
-              input.onStatus(statusResult.value);
-            }
-          } else if (message.event === "error") {
-            const errDataResult = await slangTs.safeTry(
-              () => JSON.parse(message.data)
-            );
-            const text = errDataResult.isOk ? errDataResult.value.message ?? message.data : message.data;
-            close();
-            input.onError(text);
-            return;
-          }
-        }
-      }
-      if (!closed) {
-        input.onClose();
-      }
-    };
-    void run();
-    return { close };
-  }
-  return { send, openStream, parseError };
+  return { send, parseError };
 }
 function parseError(error) {
   try {
@@ -517,11 +405,7 @@ function createPaymentInstance(initialResponse, deps) {
     fetchTransaction: deps.fetchTransaction,
     pollIntervalMs: deps.pollIntervalMs ?? 2e3,
     maxPollDuration: deps.maxPollDuration ?? 3e5,
-    maxPollAttempts: deps.maxPollAttempts ?? 150,
-    streaming: deps.streaming ?? false,
-    openStream: deps.openStream,
-    streamHandle: null,
-    streamReconnects: 0
+    maxPollAttempts: deps.maxPollAttempts ?? 150
   };
   function resolveWithError(error) {
     state.resolved = true;
@@ -557,6 +441,9 @@ function createPaymentInstance(initialResponse, deps) {
     stopUpdates();
   }
   async function handleStatusUpdate(response) {
+    if (state.resolved) {
+      return;
+    }
     if (response.reference !== state.reference) {
       resolveWithError(
         `Reference mismatch: expected ${state.reference} but got ${response.reference}`
@@ -590,10 +477,11 @@ function createPaymentInstance(initialResponse, deps) {
     if (state.resolved || state.pollingTimer) {
       return;
     }
+    const delay2 = state.pollIntervalMs + Math.random() * POLL_JITTER_MS;
     state.pollingTimer = setTimeout(() => {
       state.pollingTimer = null;
       void pollStatus();
-    }, state.pollIntervalMs);
+    }, delay2);
   }
   async function pollStatus() {
     if (state.resolved) {
@@ -621,42 +509,6 @@ function createPaymentInstance(initialResponse, deps) {
     }
     scheduleNextPoll();
   }
-  function closeStream() {
-    if (state.streamHandle) {
-      state.streamHandle.close();
-      state.streamHandle = null;
-    }
-  }
-  function startStream() {
-    if (state.resolved || !state.openStream) {
-      return;
-    }
-    state.streamHandle = state.openStream({
-      reference: state.reference,
-      onStatus: (status) => {
-        void handleStatusUpdate(status);
-      },
-      onError: () => handleStreamFailure(),
-      onClose: () => handleStreamFailure()
-    });
-  }
-  function handleStreamFailure() {
-    closeStream();
-    if (state.resolved) {
-      return;
-    }
-    if (state.streamReconnects < MAX_STREAM_RECONNECTS) {
-      state.streamReconnects += 1;
-      const backoff = 500 * 2 ** (state.streamReconnects - 1) + Math.random() * 250;
-      setTimeout(() => {
-        if (!state.resolved) {
-          startStream();
-        }
-      }, backoff);
-      return;
-    }
-    scheduleNextPoll();
-  }
   function startUpdates() {
     if (TERMINAL_STATES.has(state.status)) {
       setTimeout(() => {
@@ -664,10 +516,6 @@ function createPaymentInstance(initialResponse, deps) {
       }, 0);
       return;
     }
-    if (state.streaming && state.openStream) {
-      startStream();
-      return;
-    }
     scheduleNextPoll();
   }
   function stopUpdates() {
@@ -675,7 +523,6 @@ function createPaymentInstance(initialResponse, deps) {
       clearTimeout(state.pollingTimer);
       state.pollingTimer = null;
     }
-    closeStream();
   }
   function on(event, handler) {
     state.emitter.on(event, handler);
@@ -748,21 +595,78 @@ function createPaymentInstance(initialResponse, deps) {
   }
   return paymentInstance;
 }
+var DEFAULT_TOLERANCE_SECONDS = 300;
+function decodePayload(payload) {
+  return typeof payload === "string" ? payload : Buffer.from(payload).toString("utf8");
+}
+function extractSignedTimestampMs(payloadString) {
+  let parsed;
+  try {
+    parsed = JSON.parse(payloadString);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") {
+    return null;
+  }
+  const raw = parsed.timestamp;
+  if (typeof raw === "number" && Number.isFinite(raw)) {
+    return raw < 1e12 ? raw * 1e3 : raw;
+  }
+  if (typeof raw === "string") {
+    const ms = Date.parse(raw);
+    return Number.isNaN(ms) ? null : ms;
+  }
+  return null;
+}
 function verifyWebhookSignature(input) {
-  const payloadBytes = typeof input.payload === "string" ? Buffer.from(input.payload, "utf8") : Buffer.from(input.payload);
+  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;
   }
-  return crypto.timingSafeEqual(providedBuffer, expectedBuffer);
+  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) {
+    return false;
+  }
+  const ageMs = Math.abs(Date.now() - timestampMs);
+  return ageMs <= toleranceSeconds * 1e3;
 }
 
 // src/sdk.ts
 function generateReference() {
   return crypto.randomBytes(16).toString("hex").slice(0, 15);
 }
+var REFERENCE_MIN_LENGTH = 13;
+var REFERENCE_MAX_LENGTH = 15;
+function resolveReference(reference) {
+  if (reference === void 0) {
+    return generateReference();
+  }
+  if (reference.length < REFERENCE_MIN_LENGTH || reference.length > REFERENCE_MAX_LENGTH) {
+    throwValidation(
+      `reference must be ${REFERENCE_MIN_LENGTH}\u2013${REFERENCE_MAX_LENGTH} characters`
+    );
+  }
+  return reference;
+}
+async function runHook(hook, ...args) {
+  if (!hook || hook.enabled === false) return void 0;
+  const result = await slangTs.safeTry(async () => hook.fn(...args));
+  if (result.isOk) return result.value;
+  await slangTs.safeTry(async () => hook.onError(result.error));
+  return void 0;
+}
 function throwValidation(message) {
   throw createSdkError({ category: "validation", message });
 }
@@ -796,12 +700,10 @@ function createSdkInstance(config) {
     }),
     pollIntervalMs: config.maxPollIntervalMs,
     maxPollDuration: config.maxPollDurationMs,
-    maxPollAttempts: config.maxPollAttempts,
-    streaming: config.streaming,
-    openStream: config.streaming ? transport.openStream : void 0
+    maxPollAttempts: config.maxPollAttempts
   };
   async function collectPayment(input) {
-    const reference = input.reference ?? generateReference();
+    const reference = resolveReference(input.reference);
     validateAmount(input.amount);
     validateNonEmpty(input.customer.name, "customer.name");
     validateNonEmpty(input.customer.phoneNumber, "customer.phoneNumber");
@@ -810,24 +712,18 @@ function createSdkInstance(config) {
       throwValidation('bank details are required when method is "bank"');
     }
     let payload = { ...input, reference };
-    if (config.hooks?.beforeCollect) {
-      const mutated = await config.hooks.beforeCollect(payload);
-      if (mutated != null)
-        payload = { ...mutated, reference: mutated.reference ?? reference };
-    }
+    const mutated = await runHook(config.hooks?.beforeCollect, payload);
+    if (mutated != null)
+      payload = { ...mutated, reference: mutated.reference ?? reference };
     const result = await transport.send({
       action: SDK_ACTIONS.collectPayment,
       payload
     });
-    if (config.hooks?.afterCollect) {
-      await config.hooks.afterCollect(
-        result.isOk ? slangTs.Ok({
-          reference: result.value.reference,
-          status: result.value.status
-        }) : slangTs.Err(result.error),
-        payload
-      );
-    }
+    await runHook(
+      config.hooks?.afterCollect,
+      result.isOk ? slangTs.Ok({ reference: result.value.reference, status: result.value.status }) : slangTs.Err(result.error),
+      payload
+    );
     if (result.isErr) {
       const sdkErr = parseError(result.error);
       return createPaymentInstance(
@@ -838,7 +734,7 @@ function createSdkInstance(config) {
     return createPaymentInstance(result.value, commonDeps);
   }
   async function collectPaymentAndResolve(input) {
-    const reference = input.reference ?? generateReference();
+    const reference = resolveReference(input.reference);
     validateAmount(input.amount);
     validateNonEmpty(input.customer.name, "customer.name");
     validateNonEmpty(input.customer.phoneNumber, "customer.phoneNumber");
@@ -847,31 +743,25 @@ function createSdkInstance(config) {
       throwValidation('bank details are required when method is "bank"');
     }
     let payload = { ...input, reference };
-    if (config.hooks?.beforeCollect) {
-      const mutated = await config.hooks.beforeCollect(payload);
-      if (mutated != null)
-        payload = { ...mutated, reference: mutated.reference ?? reference };
-    }
+    const mutated = await runHook(config.hooks?.beforeCollect, payload);
+    if (mutated != null)
+      payload = { ...mutated, reference: mutated.reference ?? reference };
     const result = await transport.send({
       action: SDK_ACTIONS.collectPaymentAndResolve,
       payload
     });
-    if (config.hooks?.afterCollect) {
-      await config.hooks.afterCollect(
-        result.isOk ? slangTs.Ok({
-          reference: result.value.reference,
-          status: result.value.status
-        }) : slangTs.Err(result.error),
-        payload
-      );
-    }
+    await runHook(
+      config.hooks?.afterCollect,
+      result.isOk ? slangTs.Ok({ reference: result.value.reference, status: result.value.status }) : slangTs.Err(result.error),
+      payload
+    );
     if (result.isOk) {
       return slangTs.Ok(result.value);
     }
     return slangTs.Err(result.error);
   }
   async function makePayout(input) {
-    const reference = input.reference ?? generateReference();
+    const reference = resolveReference(input.reference);
     validateAmount(input.amount);
     validateNonEmpty(input.customer.name, "customer.name");
     validateNonEmpty(input.customer.phoneNumber, "customer.phoneNumber");
@@ -885,24 +775,18 @@ function createSdkInstance(config) {
       "destination.accountNumber"
     );
     let payload = { ...input, reference };
-    if (config.hooks?.beforePayout) {
-      const mutated = await config.hooks.beforePayout(payload);
-      if (mutated != null)
-        payload = { ...mutated, reference: mutated.reference ?? reference };
-    }
+    const mutated = await runHook(config.hooks?.beforePayout, payload);
+    if (mutated != null)
+      payload = { ...mutated, reference: mutated.reference ?? reference };
     const result = await transport.send({
       action: SDK_ACTIONS.makePayout,
       payload
     });
-    if (config.hooks?.afterPayout) {
-      await config.hooks.afterPayout(
-        result.isOk ? slangTs.Ok({
-          reference: result.value.reference,
-          status: result.value.status
-        }) : slangTs.Err(result.error),
-        payload
-      );
-    }
+    await runHook(
+      config.hooks?.afterPayout,
+      result.isOk ? slangTs.Ok({ reference: result.value.reference, status: result.value.status }) : slangTs.Err(result.error),
+      payload
+    );
     if (result.isErr) {
       const sdkErr = parseError(result.error);
       return createPaymentInstance(
@@ -913,7 +797,7 @@ function createSdkInstance(config) {
     return createPaymentInstance(result.value, commonDeps);
   }
   async function makePayoutAndResolve(input) {
-    const reference = input.reference ?? generateReference();
+    const reference = resolveReference(input.reference);
     validateAmount(input.amount);
     validateNonEmpty(input.customer.name, "customer.name");
     validateNonEmpty(input.customer.phoneNumber, "customer.phoneNumber");
@@ -927,24 +811,18 @@ function createSdkInstance(config) {
       "destination.accountNumber"
     );
     let payload = { ...input, reference };
-    if (config.hooks?.beforePayout) {
-      const mutated = await config.hooks.beforePayout(payload);
-      if (mutated != null)
-        payload = { ...mutated, reference: mutated.reference ?? reference };
-    }
+    const mutated = await runHook(config.hooks?.beforePayout, payload);
+    if (mutated != null)
+      payload = { ...mutated, reference: mutated.reference ?? reference };
     const result = await transport.send({
       action: SDK_ACTIONS.makePayoutAndResolve,
       payload
     });
-    if (config.hooks?.afterPayout) {
-      await config.hooks.afterPayout(
-        result.isOk ? slangTs.Ok({
-          reference: result.value.reference,
-          status: result.value.status
-        }) : slangTs.Err(result.error),
-        payload
-      );
-    }
+    await runHook(
+      config.hooks?.afterPayout,
+      result.isOk ? slangTs.Ok({ reference: result.value.reference, status: result.value.status }) : slangTs.Err(result.error),
+      payload
+    );
     if (result.isOk) {
       return slangTs.Ok(result.value);
     }
@@ -986,7 +864,7 @@ function createSdkInstance(config) {
     return slangTs.Err(result.error);
   }
   async function createInvoice(input) {
-    const reference = input.reference ?? generateReference();
+    const reference = resolveReference(input.reference);
     validateAmount(input.amount);
     validateNonEmpty(input.description, "description");
     if (input.items) {
@@ -1044,7 +922,8 @@ function createNylonPay(config) {
     throw new Error('apiSecret must start with "nps_"');
   }
   const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
-  const instanceKey = `${config.apiKey}:${baseUrl}`;
+  const secretHash = crypto.createHash("sha256").update(config.apiSecret).digest("hex").slice(0, 16);
+  const instanceKey = `${config.apiKey}:${baseUrl}:${secretHash}`;
   if (!config.force) {
     const existing = instances.get(instanceKey);
     if (existing) return existing;
@@ -1058,7 +937,6 @@ function createNylonPay(config) {
     maxPollIntervalMs: config.maxPollIntervalMs ?? DEFAULT_MAX_POLL_INTERVAL_MS,
     maxPollDurationMs: config.maxPollDurationMs ?? DEFAULT_MAX_POLL_DURATION_MS,
     maxPollAttempts: config.maxPollAttempts ?? DEFAULT_MAX_POLL_ATTEMPTS,
-    streaming: config.streaming ?? DEFAULT_STREAMING,
     fetch: config.fetch ?? globalThis.fetch.bind(globalThis),
     hooks: config.hooks
   };