@nile-squad/nylonpay-ts 1.2.0 → 1.3.0

package/dist/index.d.ts

@@ -89,6 +89,13 @@ type CollectPaymentInput = {
     method?: PaymentMethod;
     bank?: BankDetails;
     metadata?: Record<string, string>;
+    /**
+     * Business labels to attach to the transaction. Normalized to lowercase;
+     * reserved tags (`"live"`, `"test"`) are managed automatically. Max 10 tags,
+     * each up to 50 characters. Useful for grouping payments by campaign, product,
+     * team, or any merchant-defined dimension.
+     */
+    tags?: string[];
 };
 /**
  * Input for initiating a payout. Use this to disburse funds to a
@@ -102,6 +109,8 @@ type MakePayoutInput = {
     description: string;
     reference?: string;
     metadata?: Record<string, string>;
+    /** Business labels — same normalization rules as {@link CollectPaymentInput.tags}. */
+    tags?: string[];
 };
 /**
  * Input for a one-shot status check. Does not start polling; returns
@@ -140,6 +149,8 @@ type CreateInvoiceInput = {
     redirectUrl?: string;
     reference?: string;
     metadata?: Record<string, string>;
+    /** Business labels — same normalization rules as {@link CollectPaymentInput.tags}. */
+    tags?: string[];
 };
 /**
  * Input for verifying a webhook signature. Operates on raw payload bytes
@@ -414,6 +425,59 @@ type EventData = {
  * data (if available), and timestamp.
  */
 type PaymentEventHandler = (data: EventData) => void;
+/**
+ * Lightweight transaction summary returned by `listTransactions`. Carries the
+ * fields needed for listing and aggregation without the full provider detail
+ * that `getTransaction` exposes. `tags` is included so merchants can see which
+ * labels a row carries while paginating.
+ */
+type TransactionSummary = {
+    id: string;
+    reference: string;
+    amount: number;
+    currency: Currency;
+    status: TransactionStatus;
+    type: TransactionType;
+    method: string | null;
+    mode: TransactionMode;
+    /** Smart tags on the transaction (system + developer). */
+    tags: string[];
+    createdAt: string;
+    updatedAt: string;
+};
+/**
+ * Input for listing and filtering transactions. All fields are optional —
+ * omitting filters returns the most recent transactions for the calling
+ * key's account and mode.
+ */
+type ListTransactionsInput = {
+    /** Filter to transactions carrying ALL of these tags (AND semantics). */
+    tags?: string[];
+    status?: TransactionStatus;
+    type?: TransactionType;
+    /** Maximum number of results (1–100, default 20). */
+    limit?: number;
+    /** Zero-based offset for pagination (default 0). */
+    offset?: number;
+    /** ISO 8601 datetime — only transactions created at or after this time. */
+    createdAfter?: string;
+    /** ISO 8601 datetime — only transactions created at or before this time. */
+    createdBefore?: string;
+};
+/**
+ * Response from `listTransactions`. Includes the page of summaries, the count
+ * returned, and the effective pagination/filter parameters so callers can build
+ * pagination UIs without round-tripping for metadata.
+ */
+type ListTransactionsResponse = {
+    transactions: TransactionSummary[];
+    /** Number of transactions in this page (≤ limit). */
+    count: number;
+    limit: number;
+    offset: number;
+    /** The normalized tags that were applied as filters (empty if no tag filter). */
+    tags: string[];
+};
 /**
  * SDK instance returned by the factory. Provides all payment operations
  * and the webhook verification utility.
@@ -569,6 +633,38 @@ interface NylonPaySdk {
      * ```
      */
     createInvoice(input: CreateInvoiceInput): Promise<Result<InvoiceResponse, string>>;
+    /**
+     * List transactions for the calling key's account, with optional filtering.
+     * Returns lightweight summaries — use `getTransaction` for full detail.
+     *
+     * Tag filters use AND semantics: `tags: ["vip", "promo"]` returns only
+     * transactions tagged with BOTH labels. Tags are normalized (lowercase) before
+     * matching, so `"VIP"` and `"vip"` match the same rows.
+     *
+     * @example
+     * ```ts
+     * // All transactions tagged "vip" from the last week
+     * const result = await nylonpay.listTransactions({
+     *   tags: ["vip"],
+     *   createdAfter: new Date(Date.now() - 7 * 24 * 3600 * 1000).toISOString(),
+     * });
+     * if (result.isOk) console.log(result.value.transactions);
+     * ```
+     */
+    listTransactions(input?: ListTransactionsInput): Promise<Result<ListTransactionsResponse, string>>;
+    /**
+     * Convenience wrapper around `listTransactions` that filters by a single tag.
+     * Equivalent to `listTransactions({ tags: [tag], ...options })`.
+     *
+     * @example
+     * ```ts
+     * const result = await nylonpay.getTransactionsByTag("campaign-q2");
+     * if (result.isOk) {
+     *   const total = result.value.transactions.reduce((s, t) => s + t.amount, 0);
+     * }
+     * ```
+     */
+    getTransactionsByTag(tag: string, options?: Omit<ListTransactionsInput, "tags">): Promise<Result<ListTransactionsResponse, string>>;
     /**
      * Verify that an incoming webhook payload was signed by Nylon Pay.
      * Operates on raw payload bytes (string or Uint8Array), not parsed JSON,
@@ -735,7 +831,7 @@ declare function parseError(error: string): SdkError;
  *    retries hours later, is re-stamped and re-signed, so this never rejects
  *    legitimate traffic. Pass `toleranceSeconds: 0` to skip this check.
  *
- * @returns True when the signature is valid and (when enforced) the webhook is fresh
+ * @returns True when the signature is valid and (when enforced) the webhook is fresh. Never throws — returns false on any error.
  */
 declare function verifyWebhookSignature(input: VerifyWebhookInput): boolean;
 

package/dist/index.js

@@ -1,4 +1,4 @@
-import { createHash, createHmac, timingSafeEqual, randomBytes } from 'crypto';
+import { createHash, createHmac, timingSafeEqual, randomUUID, randomBytes } from 'crypto';
 import { Ok, Err, safeTry } from 'slang-ts';
 import { type, platform, arch, release, hostname } from 'os';
 
@@ -70,10 +70,12 @@ var SDK_ACTIONS = {
   makePayoutAndResolve: "sdk-make-payout-and-resolve",
   getStatus: "sdk-get-status",
   getTransaction: "sdk-get-transaction",
+  listTransactions: "sdk-list-transactions",
   verifyPhone: "sdk-verify-phone",
   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()}`,
@@ -268,6 +270,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);
@@ -655,43 +668,44 @@ 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
-function generateReference() {
-  return randomBytes(16).toString("hex").slice(0, 15);
-}
-var REFERENCE_MIN_LENGTH = 13;
-var REFERENCE_MAX_LENGTH = 15;
+var UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function resolveReference(reference) {
   if (reference === void 0) {
-    return generateReference();
+    return randomUUID();
   }
-  if (reference.length < REFERENCE_MIN_LENGTH || reference.length > REFERENCE_MAX_LENGTH) {
-    throwValidation(
-      `reference must be ${REFERENCE_MIN_LENGTH}\u2013${REFERENCE_MAX_LENGTH} characters`
-    );
+  if (!UUID_REGEX.test(reference)) {
+    throwValidation("reference must be a valid UUID");
   }
   return reference;
 }
@@ -958,6 +972,19 @@ function createSdkInstance(config) {
     }
     return Err(result.error);
   }
+  async function listTransactions(input) {
+    const result = await transport.send({
+      action: SDK_ACTIONS.listTransactions,
+      payload: input ?? {}
+    });
+    if (result.isOk) {
+      return Ok(result.value);
+    }
+    return Err(result.error);
+  }
+  async function getTransactionsByTag(tag, options) {
+    return listTransactions({ ...options, tags: [tag] });
+  }
   function verifyWebhook(input) {
     return verifyWebhookSignature(input);
   }
@@ -968,6 +995,8 @@ function createSdkInstance(config) {
     makePayoutAndResolve,
     getStatus,
     getTransaction,
+    listTransactions,
+    getTransactionsByTag,
     verifyPhone,
     createInvoice,
     verifyWebhookSignature: verifyWebhook