@nile-squad/nylonpay-ts 1.0.3 → 1.0.5

package/dist/index.js

@@ -1,5 +1,5 @@
 import { createHash, createHmac, timingSafeEqual, randomBytes } from 'crypto';
-import { Ok, Err } from 'slang-ts';
+import { Ok, Err, safeTry } from 'slang-ts';
 import { type, platform, arch, release, hostname } from 'os';
 
 // src/sdk.ts
@@ -53,21 +53,6 @@ function createEmitter() {
   const emitter = { on, once, off, emit, clear, listenerCount };
   return emitter;
 }
-function generateFingerprint() {
-  const components = [
-    `type:${type()}`,
-    `platform:${platform()}`,
-    `arch:${arch()}`,
-    `release:${release()}`,
-    `hostname:${hostname()}`,
-    `node:${process.versions.node}`,
-    `v8:${process.versions.v8}`
-  ].join("|");
-  return createHash("sha256").update(components).digest("hex");
-}
-function generateNonce(length = 16) {
-  return randomBytes(length).toString("hex");
-}
 
 // src/sdk.config.ts
 var DEFAULT_BASE_URL = "https://api.nylonpay.nilesquad.com/api/services";
@@ -76,6 +61,9 @@ 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 SDK_SERVICE = "sdk";
 var SDK_ACTIONS = {
   collectPayment: "sdk-collect-payment",
@@ -88,6 +76,21 @@ var SDK_ACTIONS = {
   createInvoice: "sdk-create-invoice"
 };
 var RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
+function generateFingerprint() {
+  const components = [
+    `type:${type()}`,
+    `platform:${platform()}`,
+    `arch:${arch()}`,
+    `release:${release()}`,
+    `hostname:${hostname()}`,
+    `node:${process.versions.node}`,
+    `v8:${process.versions.v8}`
+  ].join("|");
+  return createHash("sha256").update(components).digest("hex");
+}
+function generateNonce(length = 16) {
+  return randomBytes(length).toString("hex");
+}
 function sortValue(value) {
   if (Array.isArray(value)) {
     return value.map((entry) => sortValue(entry));
@@ -118,6 +121,42 @@ 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 = createHmac("sha256", secret).update(createCanonicalPayload(data)).digest("hex");
   const providedBuffer = Buffer.from(signature, "hex");
@@ -130,6 +169,55 @@ 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",
+  "limit",
+  "rate_limit",
+  "account",
+  "provider",
+  "not_found",
+  "internal",
+  "network",
+  "timeout"
+]);
+var STATUS_CATEGORY = {
+  408: "timeout",
+  429: "rate_limit"
+};
+var ERROR_TYPE_SUFFIX = /^(.*?)\s*--\s*error-type:\s*([a-z_]+)\s*$/is;
+function parseCategoryFromMessage(message) {
+  const match = ERROR_TYPE_SUFFIX.exec(message);
+  if (match?.[2] && KNOWN_CATEGORIES.has(match[2])) {
+    return {
+      category: match[2],
+      message: match[1] ?? message
+    };
+  }
+  return { category: null, message };
+}
+function buildHttpError(params) {
+  const parsed = parseCategoryFromMessage(params.message);
+  const category = parsed.category ?? STATUS_CATEGORY[params.statusCode] ?? (params.statusCode >= 500 ? "internal" : "validation");
+  return {
+    category,
+    message: parsed.message,
+    retryable: RETRYABLE_STATUS_CODES.has(params.statusCode)
+  };
+}
+function createSdkError(error) {
+  return Object.assign(new Error(error.message), {
+    category: error.category,
+    retryable: error.retryable
+  });
+}
 function calculateBackoff(attempt) {
   const base = 2 ** attempt * 1e3;
   const jitter = Math.random() * 500;
@@ -232,21 +320,19 @@ function createTransport({
             await delay(calculateBackoff(currentAttempt));
             return attempt(currentAttempt + 1);
           }
-          const sdkError = {
-            code: `HTTP_${statusCode}`,
-            message: errorMessage,
-            statusCode,
-            retryable
-          };
           cleanup();
-          return Err(JSON.stringify(sdkError));
+          return Err(
+            JSON.stringify(
+              buildHttpError({ message: errorMessage, statusCode })
+            )
+          );
         }
         const responseBody = await response.json();
         if (!responseBody || typeof responseBody !== "object" || !("status" in responseBody)) {
           cleanup();
           return Err(
             JSON.stringify({
-              code: "INVALID_RESPONSE",
+              category: "internal",
               message: "Response missing status field",
               retryable: false
             })
@@ -265,7 +351,7 @@ function createTransport({
               cleanup();
               return Err(
                 JSON.stringify({
-                  code: "RESPONSE_TAMPERED",
+                  category: "internal",
                   message: "Response signature verification failed",
                   retryable: false
                 })
@@ -282,7 +368,7 @@ function createTransport({
         cleanup();
         const isAbort = error instanceof DOMException && error.name === "AbortError";
         const sdkError = {
-          code: isAbort ? "TIMEOUT" : "NETWORK_ERROR",
+          category: isAbort ? "timeout" : "network",
           message: isAbort ? `Request timed out after ${timeoutMs}ms` : String(error),
           retryable: true
         };
@@ -295,17 +381,105 @@ function createTransport({
     }
     return attempt(0);
   }
-  return { send, parseError };
+  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 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 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 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 safeTry(
+              () => JSON.parse(message.data)
+            );
+            if (statusResult.isOk) {
+              input.onStatus(statusResult.value);
+            }
+          } else if (message.event === "error") {
+            const errDataResult = await 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 };
 }
 function parseError(error) {
   try {
     const parsed = JSON.parse(error);
-    if (parsed && typeof parsed === "object" && "code" in parsed && "message" in parsed && typeof parsed.code === "string" && typeof parsed.message === "string") {
+    if (parsed && typeof parsed === "object" && "category" in parsed && "message" in parsed && typeof parsed.category === "string" && typeof parsed.message === "string") {
       return parsed;
     }
   } catch {
   }
-  return { code: "UNKNOWN", message: error };
+  const fromSuffix = parseCategoryFromMessage(error);
+  return {
+    category: fromSuffix.category ?? "internal",
+    message: fromSuffix.message
+  };
 }
 
 // src/payment.ts
@@ -323,10 +497,14 @@ var TERMINAL_STATES = /* @__PURE__ */ new Set([
   "failed",
   "cancelled"
 ]);
+function normalizeStatus(raw) {
+  if (raw === "completed") return "successful";
+  return raw;
+}
 function createPaymentInstance(initialResponse, deps) {
   const state = {
     reference: initialResponse.reference,
-    status: initialResponse.status,
+    status: normalizeStatus(initialResponse.status),
     transaction: null,
     pollingTimer: null,
     resolved: false,
@@ -337,11 +515,15 @@ function createPaymentInstance(initialResponse, deps) {
     fetchTransaction: deps.fetchTransaction,
     pollIntervalMs: deps.pollIntervalMs ?? 2e3,
     maxPollDuration: deps.maxPollDuration ?? 3e5,
-    maxPollAttempts: deps.maxPollAttempts ?? 150
+    maxPollAttempts: deps.maxPollAttempts ?? 150,
+    streaming: deps.streaming ?? false,
+    openStream: deps.openStream,
+    streamHandle: null,
+    streamReconnects: 0
   };
   function resolveWithError(error) {
     state.resolved = true;
-    stopPolling();
+    stopUpdates();
     emitEvent("error", parseError(error).message);
   }
   function emitEvent(event, error) {
@@ -361,13 +543,14 @@ function createPaymentInstance(initialResponse, deps) {
       state.transaction = txResult.value;
       const event = statusToEvent(status);
       if (event) {
-        emitEvent(event);
+        const error = status === "failed" ? state.transaction.failureReason ?? void 0 : void 0;
+        emitEvent(event, error);
       }
     } else {
       emitEvent("error", `Failed to fetch transaction: ${txResult.error}`);
     }
     state.resolved = true;
-    stopPolling();
+    stopUpdates();
   }
   async function handleStatusUpdate(response) {
     if (response.reference !== state.reference) {
@@ -376,7 +559,7 @@ function createPaymentInstance(initialResponse, deps) {
       );
       return;
     }
-    const newStatus = response.status;
+    const newStatus = normalizeStatus(response.status);
     const oldStatus = state.status;
     state.status = newStatus;
     if (newStatus !== oldStatus) {
@@ -391,13 +574,13 @@ function createPaymentInstance(initialResponse, deps) {
     }
   }
   function handlePollError(error) {
-    const isNotFound = error.includes("not found") || error.includes("NOT_FOUND");
-    if (isNotFound) {
+    const parsed = parseError(error);
+    if (parsed.category === "not_found") {
       return;
     }
-    emitEvent("error", parseError(error).message);
+    emitEvent("error", parsed.message);
     state.resolved = true;
-    stopPolling();
+    stopUpdates();
   }
   function scheduleNextPoll() {
     if (state.resolved || state.pollingTimer) {
@@ -410,7 +593,7 @@ function createPaymentInstance(initialResponse, deps) {
   }
   async function pollStatus() {
     if (state.resolved) {
-      stopPolling();
+      stopUpdates();
       return;
     }
     if (state.pollAttempts >= state.maxPollAttempts) {
@@ -429,19 +612,66 @@ function createPaymentInstance(initialResponse, deps) {
       handlePollError(result.error);
     }
     if (state.resolved) {
-      stopPolling();
+      stopUpdates();
       return;
     }
     scheduleNextPoll();
   }
-  function startPolling() {
+  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 stopPolling() {
+  function startUpdates() {
+    if (TERMINAL_STATES.has(state.status)) {
+      setTimeout(() => {
+        void handleTerminalState(state.status);
+      }, 0);
+      return;
+    }
+    if (state.streaming && state.openStream) {
+      startStream();
+      return;
+    }
+    scheduleNextPoll();
+  }
+  function stopUpdates() {
     if (state.pollingTimer) {
       clearTimeout(state.pollingTimer);
       state.pollingTimer = null;
     }
+    closeStream();
   }
   function on(event, handler) {
     state.emitter.on(event, handler);
@@ -456,37 +686,28 @@ function createPaymentInstance(initialResponse, deps) {
     return paymentInstance;
   }
   function wait() {
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve) => {
       if (state.resolved) {
-        if (state.status === "successful" && state.transaction) {
-          resolve(state.transaction);
-        } else {
-          reject(new Error(`Payment ${state.status ?? "error"}`));
-        }
+        resolve(
+          state.status === "successful" && state.transaction ? state.transaction : null
+        );
         return;
       }
       function onSuccess() {
         cleanup();
-        if (state.transaction) {
-          resolve(state.transaction);
-        } else {
-          reject(
-            new Error("Payment successful but transaction data unavailable")
-          );
-        }
+        resolve(state.transaction ?? null);
       }
       function onFailed() {
         cleanup();
-        reject(new Error("Payment failed"));
+        resolve(null);
       }
       function onCancelled() {
         cleanup();
-        reject(new Error("Payment cancelled"));
+        resolve(null);
       }
-      function onError(data) {
+      function onError() {
         cleanup();
-        const eventData = data;
-        reject(new Error(eventData.error ?? "Payment error"));
+        resolve(null);
       }
       function cleanup() {
         state.emitter.off("success", onSuccess);
@@ -512,7 +733,7 @@ function createPaymentInstance(initialResponse, deps) {
     off,
     wait
   };
-  startPolling();
+  startUpdates();
   return paymentInstance;
 }
 function verifyWebhookSignature(input) {
@@ -530,14 +751,17 @@ function verifyWebhookSignature(input) {
 function generateReference() {
   return randomBytes(16).toString("hex").slice(0, 15);
 }
+function throwValidation(message) {
+  throw createSdkError({ category: "validation", message });
+}
 function validateAmount(amount) {
   if (!Number.isInteger(amount) || amount <= 0) {
-    throw new Error("amount must be a positive integer");
+    throwValidation("amount must be a positive integer");
   }
 }
 function validateNonEmpty(value, fieldName) {
   if (!value || value.trim() === "") {
-    throw new Error(`${fieldName} is required`);
+    throwValidation(`${fieldName} is required`);
   }
 }
 function createSdkInstance(config) {
@@ -560,7 +784,9 @@ function createSdkInstance(config) {
     }),
     pollIntervalMs: config.maxPollIntervalMs,
     maxPollDuration: config.maxPollDurationMs,
-    maxPollAttempts: config.maxPollAttempts
+    maxPollAttempts: config.maxPollAttempts,
+    streaming: config.streaming,
+    openStream: config.streaming ? transport.openStream : void 0
   };
   async function collectPayment(input) {
     const reference = input.reference ?? generateReference();
@@ -569,7 +795,7 @@ function createSdkInstance(config) {
     validateNonEmpty(input.customer.phoneNumber, "customer.phoneNumber");
     validateNonEmpty(input.description, "description");
     if (input.method === "bank" && !input.bank) {
-      throw new Error('bank details are required when method is "bank"');
+      throwValidation('bank details are required when method is "bank"');
     }
     let payload = { ...input, reference };
     if (config.hooks?.beforeCollect) {
@@ -590,19 +816,10 @@ function createSdkInstance(config) {
         payload
       );
     }
-    if (result.isOk) {
-      return createPaymentInstance(result.value, commonDeps);
-    }
-    return createPaymentInstance(
-      { reference, status: "pending" },
-      {
-        fetchStatus: async () => Err(result.error),
-        fetchTransaction: async () => Err(result.error),
-        pollIntervalMs: 0,
-        maxPollAttempts: 1,
-        maxPollDuration: Number.MAX_SAFE_INTEGER
-      }
-    );
+    if (result.isErr) {
+      throw createSdkError(parseError(result.error));
+    }
+    return createPaymentInstance(result.value, commonDeps);
   }
   async function collectPaymentAndResolve(input) {
     const reference = input.reference ?? generateReference();
@@ -611,7 +828,7 @@ function createSdkInstance(config) {
     validateNonEmpty(input.customer.phoneNumber, "customer.phoneNumber");
     validateNonEmpty(input.description, "description");
     if (input.method === "bank" && !input.bank) {
-      throw new Error('bank details are required when method is "bank"');
+      throwValidation('bank details are required when method is "bank"');
     }
     let payload = { ...input, reference };
     if (config.hooks?.beforeCollect) {
@@ -670,19 +887,10 @@ function createSdkInstance(config) {
         payload
       );
     }
-    if (result.isOk) {
-      return createPaymentInstance(result.value, commonDeps);
-    }
-    return createPaymentInstance(
-      { reference, status: "pending" },
-      {
-        fetchStatus: async () => Err(result.error),
-        fetchTransaction: async () => Err(result.error),
-        pollIntervalMs: 0,
-        maxPollAttempts: 1,
-        maxPollDuration: Number.MAX_SAFE_INTEGER
-      }
-    );
+    if (result.isErr) {
+      throw createSdkError(parseError(result.error));
+    }
+    return createPaymentInstance(result.value, commonDeps);
   }
   async function makePayoutAndResolve(input) {
     const reference = input.reference ?? generateReference();
@@ -735,7 +943,7 @@ function createSdkInstance(config) {
   }
   async function getTransaction(input) {
     if (!input.id && !input.reference) {
-      throw new Error("id or reference is required");
+      throwValidation("id or reference is required");
     }
     const result = await transport.send({
       action: SDK_ACTIONS.getTransaction,
@@ -763,14 +971,14 @@ function createSdkInstance(config) {
     validateNonEmpty(input.description, "description");
     if (input.items) {
       if (input.items.length > 50) {
-        throw new Error("items must not exceed 50");
+        throwValidation("items must not exceed 50");
       }
       for (const item of input.items) {
         if (!Number.isInteger(item.quantity) || item.quantity <= 0) {
-          throw new Error("item quantity must be a positive integer");
+          throwValidation("item quantity must be a positive integer");
         }
         if (!Number.isInteger(item.unitPrice) || item.unitPrice <= 0) {
-          throw new Error("item unitPrice must be a positive integer");
+          throwValidation("item unitPrice must be a positive integer");
         }
       }
     }
@@ -830,6 +1038,7 @@ 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
   };
@@ -838,6 +1047,6 @@ function createNylonPay(config) {
   return instance;
 }
 
-export { createNylonPay, parseError, verifyWebhookSignature };
+export { createNylonPay, createSdkError, parseError, verifyWebhookSignature };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map