@nile-squad/nylonpay-ts 1.2.1 → 1.3.0

package/dist/index.d.cts

@@ -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,

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,

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,6 +70,7 @@ 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"
 };
@@ -698,19 +699,13 @@ function verifyWebhookSignature(input) {
 }
 
 // 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;
 }
@@ -977,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);
   }
@@ -987,6 +995,8 @@ function createSdkInstance(config) {
     makePayoutAndResolve,
     getStatus,
     getTransaction,
+    listTransactions,
+    getTransactionsByTag,
     verifyPhone,
     createInvoice,
     verifyWebhookSignature: verifyWebhook