@naturalpay/sdk 0.2.0 → 0.3.0

package/src/resources/transactions.ts

@@ -0,0 +1,620 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+/**
+ * Payment and transaction operations
+ */
+export class Transactions extends APIResource {
+  /**
+   * List transactions visible to your party and its delegated agents.
+   */
+  list(
+    params: TransactionListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<TransactionListResponse> {
+    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID, ...query } = params ?? {};
+    return this._client.get('/transactions', {
+      query,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Get a single transaction visible to your party.
+   */
+  get(
+    transactionID: string,
+    params: TransactionGetParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<TransactionGetResponse> {
+    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID, ...query } = params ?? {};
+    return this._client.get(path`/transactions/${transactionID}`, {
+      query,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export interface TransactionListResponse {
+  data: Array<TransactionListResponse.Data>;
+
+  meta: TransactionListResponse.Meta;
+}
+
+export namespace TransactionListResponse {
+  export interface Data {
+    /**
+     * Transaction handle (txn_xxx)
+     */
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
+    type: string;
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * Agent that initiated this transaction. Null when initiated by a human user.
+       */
+      agentId: string | null;
+
+      /**
+       * Amount in cents
+       */
+      amount: number;
+
+      /**
+       * Classification from your party's perspective. Derived from transactionType +
+       * direction: "sent"/"received" for wallet-to-wallet payments (OUTBOUND/INBOUND),
+       * "deposit"/"withdrawal" for external transfers (INBOUND/OUTBOUND).
+       */
+      category: 'sent' | 'received' | 'deposit' | 'withdrawal';
+
+      /**
+       * When this transaction was created
+       */
+      createdAt: string;
+
+      /**
+       * Currency code
+       */
+      currency: string;
+
+      /**
+       * Customer name if delegated
+       */
+      customerName: string | null;
+
+      /**
+       * Payment description
+       */
+      description: string | null;
+
+      /**
+       * Direction: INBOUND | OUTBOUND
+       */
+      direction: 'INBOUND' | 'OUTBOUND';
+
+      /**
+       * Active dispute ID when a dispute has been filed for this transaction
+       */
+      disputeId: string | null;
+
+      /**
+       * Pending escalation ID when this transaction requires approval
+       */
+      escalationId: string | null;
+
+      /**
+       * Projected funds-available time for transfers (deposits/withdrawals). Null when
+       * no MMR settlement projection has arrived yet, and null for payments.
+       */
+      expectedAvailableAt: string | null;
+
+      /**
+       * Display name of the user or agent that initiated this transaction
+       */
+      initiatorName: string | null;
+
+      /**
+       * True if this is a delegated customer payment
+       */
+      isDelegated: boolean;
+
+      /**
+       * Recipient display name
+       */
+      recipientName: string | null;
+
+      /**
+       * Sender display name
+       */
+      senderName: string | null;
+
+      /**
+       * Transaction status
+       */
+      status: string;
+
+      /**
+       * Transaction type: payment | transfer
+       */
+      transactionType: 'payment' | 'transfer';
+
+      /**
+       * When this transaction was last updated
+       */
+      updatedAt: string | null;
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Destination party
+       */
+      destinationParty: Relationships.DestinationParty;
+
+      /**
+       * Destination wallet
+       */
+      destinationWallet: Relationships.DestinationWallet;
+
+      /**
+       * Source party
+       */
+      sourceParty: Relationships.SourceParty;
+
+      /**
+       * Source wallet
+       */
+      sourceWallet: Relationships.SourceWallet;
+    }
+
+    export namespace Relationships {
+      /**
+       * Destination party
+       */
+      export interface DestinationParty {
+        /**
+         * Related resource identifier
+         */
+        data: DestinationParty.Data | null;
+      }
+
+      export namespace DestinationParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+
+      /**
+       * Destination wallet
+       */
+      export interface DestinationWallet {
+        /**
+         * Related resource identifier
+         */
+        data: DestinationWallet.Data | null;
+      }
+
+      export namespace DestinationWallet {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+
+      /**
+       * Source party
+       */
+      export interface SourceParty {
+        /**
+         * Related resource identifier
+         */
+        data: SourceParty.Data | null;
+      }
+
+      export namespace SourceParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+
+      /**
+       * Source wallet
+       */
+      export interface SourceWallet {
+        /**
+         * Related resource identifier
+         */
+        data: SourceWallet.Data | null;
+      }
+
+      export namespace SourceWallet {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+    }
+  }
+
+  export interface Meta {
+    pagination: Meta.Pagination;
+  }
+
+  export namespace Meta {
+    export interface Pagination {
+      hasMore: boolean;
+
+      nextCursor: string | null;
+    }
+  }
+}
+
+export interface TransactionGetResponse {
+  data: TransactionGetResponse.Data;
+}
+
+export namespace TransactionGetResponse {
+  export interface Data {
+    /**
+     * Transaction handle (txn_xxx)
+     */
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
+    type: string;
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * Agent that initiated this transaction. Null when initiated by a human user.
+       */
+      agentId: string | null;
+
+      /**
+       * Amount in cents
+       */
+      amount: number;
+
+      /**
+       * Classification from your party's perspective. Derived from transactionType +
+       * direction: "sent"/"received" for wallet-to-wallet payments (OUTBOUND/INBOUND),
+       * "deposit"/"withdrawal" for external transfers (INBOUND/OUTBOUND).
+       */
+      category: 'sent' | 'received' | 'deposit' | 'withdrawal';
+
+      /**
+       * When this transaction was created
+       */
+      createdAt: string;
+
+      /**
+       * Currency code
+       */
+      currency: string;
+
+      /**
+       * Customer name if delegated
+       */
+      customerName: string | null;
+
+      /**
+       * Payment description
+       */
+      description: string | null;
+
+      /**
+       * Direction: INBOUND | OUTBOUND
+       */
+      direction: 'INBOUND' | 'OUTBOUND';
+
+      /**
+       * Active dispute ID when a dispute has been filed for this transaction
+       */
+      disputeId: string | null;
+
+      /**
+       * Pending escalation ID when this transaction requires approval
+       */
+      escalationId: string | null;
+
+      /**
+       * Projected funds-available time for transfers (deposits/withdrawals). Null when
+       * no MMR settlement projection has arrived yet, and null for payments.
+       */
+      expectedAvailableAt: string | null;
+
+      /**
+       * Display name of the user or agent that initiated this transaction
+       */
+      initiatorName: string | null;
+
+      /**
+       * True if this is a delegated customer payment
+       */
+      isDelegated: boolean;
+
+      /**
+       * Recipient display name
+       */
+      recipientName: string | null;
+
+      /**
+       * Sender display name
+       */
+      senderName: string | null;
+
+      /**
+       * Transaction status
+       */
+      status: string;
+
+      /**
+       * Transaction type: payment | transfer
+       */
+      transactionType: 'payment' | 'transfer';
+
+      /**
+       * When this transaction was last updated
+       */
+      updatedAt: string | null;
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Destination party
+       */
+      destinationParty: Relationships.DestinationParty;
+
+      /**
+       * Destination wallet
+       */
+      destinationWallet: Relationships.DestinationWallet;
+
+      /**
+       * Source party
+       */
+      sourceParty: Relationships.SourceParty;
+
+      /**
+       * Source wallet
+       */
+      sourceWallet: Relationships.SourceWallet;
+    }
+
+    export namespace Relationships {
+      /**
+       * Destination party
+       */
+      export interface DestinationParty {
+        /**
+         * Related resource identifier
+         */
+        data: DestinationParty.Data | null;
+      }
+
+      export namespace DestinationParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+
+      /**
+       * Destination wallet
+       */
+      export interface DestinationWallet {
+        /**
+         * Related resource identifier
+         */
+        data: DestinationWallet.Data | null;
+      }
+
+      export namespace DestinationWallet {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+
+      /**
+       * Source party
+       */
+      export interface SourceParty {
+        /**
+         * Related resource identifier
+         */
+        data: SourceParty.Data | null;
+      }
+
+      export namespace SourceParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+
+      /**
+       * Source wallet
+       */
+      export interface SourceWallet {
+        /**
+         * Related resource identifier
+         */
+        data: SourceWallet.Data | null;
+      }
+
+      export namespace SourceWallet {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+    }
+  }
+}
+
+export interface TransactionListParams {
+  /**
+   * Query param: Pagination cursor from previous response
+   */
+  cursor?: string;
+
+  /**
+   * Query param: Results per page
+   */
+  limit?: number;
+
+  /**
+   * Query param
+   */
+  type?: 'payment' | 'transfer' | 'all';
+
+  /**
+   * Header param: Agent ID (agt_xxx) identifying which agent is making the request.
+   */
+  'X-Agent-ID'?: string;
+
+  /**
+   * Header param: Required when X-Agent-ID is present. Session or conversation ID
+   * for agent observability.
+   */
+  'X-Instance-ID'?: string;
+}
+
+export interface TransactionGetParams {
+  /**
+   * Query param: Party ID for delegated transaction lookup
+   */
+  partyId?: string;
+
+  /**
+   * Header param: Agent ID (agt_xxx) identifying which agent is making the request.
+   */
+  'X-Agent-ID'?: string;
+
+  /**
+   * Header param: Required when X-Agent-ID is present. Session or conversation ID
+   * for agent observability.
+   */
+  'X-Instance-ID'?: string;
+}
+
+export declare namespace Transactions {
+  export {
+    type TransactionListResponse as TransactionListResponse,
+    type TransactionGetResponse as TransactionGetResponse,
+    type TransactionListParams as TransactionListParams,
+    type TransactionGetParams as TransactionGetParams,
+  };
+}