@naturalpay/sdk 0.1.4 → 0.2.1

package/src/resources/wallet.ts

@@ -0,0 +1,864 @@
+// 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';
+
+/**
+ * Wallet balance, deposits, withdrawals, and external funding sources
+ */
+export class Wallet extends APIResource {
+  /**
+   * Get spendable and total wallet ledger balance.
+   *
+   * @example
+   * ```ts
+   * const response = await client.wallet.getBalance();
+   * ```
+   */
+  getBalance(
+    params: WalletGetBalanceParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<WalletGetBalanceResponse> {
+    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID, ...query } = params ?? {};
+    return this._client.get('/wallet/balance', {
+      query,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Get account and routing numbers for ACH deposits.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.wallet.getDepositInstructions();
+   * ```
+   */
+  getDepositInstructions(
+    params: WalletGetDepositInstructionsParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<WalletGetDepositInstructionsResponse> {
+    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID } = params ?? {};
+    return this._client.get('/wallet/deposit-instructions', {
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Initiate a wallet deposit.
+   *
+   * @example
+   * ```ts
+   * const response = await client.wallet.initiateDeposit({
+   *   amount: 1,
+   *   externalFundingSourceId:
+   *     'efs_ecc2efdd09bd231a9ad9bd2aada37aa7',
+   *   'Idempotency-Key': 'Idempotency-Key',
+   * });
+   * ```
+   */
+  initiateDeposit(
+    params: WalletInitiateDepositParams,
+    options?: RequestOptions,
+  ): APIPromise<WalletInitiateDepositResponse> {
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'X-Agent-ID': xAgentID,
+      'X-Instance-ID': xInstanceID,
+      ...body
+    } = params;
+    return this._client.post('/wallet/deposit', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          'Idempotency-Key': idempotencyKey,
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Initiate a wallet withdrawal.
+   *
+   * @example
+   * ```ts
+   * const response = await client.wallet.initiateWithdrawal({
+   *   amount: 1,
+   *   externalFundingSourceId:
+   *     'efs_ecc2efdd09bd231a9ad9bd2aada37aa7',
+   *   'Idempotency-Key': 'Idempotency-Key',
+   * });
+   * ```
+   */
+  initiateWithdrawal(
+    params: WalletInitiateWithdrawalParams,
+    options?: RequestOptions,
+  ): APIPromise<WalletInitiateWithdrawalResponse> {
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'X-Agent-ID': xAgentID,
+      'X-Instance-ID': xInstanceID,
+      ...body
+    } = params;
+    return this._client.post('/wallet/withdraw', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          'Idempotency-Key': idempotencyKey,
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * List linked external funding sources with cursor pagination.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.wallet.listPaymentInstruments();
+   * ```
+   */
+  listPaymentInstruments(
+    params: WalletListPaymentInstrumentsParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<WalletListPaymentInstrumentsResponse> {
+    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID, ...query } = params ?? {};
+    return this._client.get('/wallet/external-funding-sources', {
+      query,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Remove (unlink) a bank account.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.wallet.removePaymentInstrument(
+   *     'efs_ecc2efdd09bd231a9ad9bd2aada37aa7',
+   *   );
+   * ```
+   */
+  removePaymentInstrument(
+    externalFundingSourceID: string,
+    params: WalletRemovePaymentInstrumentParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<WalletRemovePaymentInstrumentResponse> {
+    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID } = params ?? {};
+    return this._client.delete(path`/wallet/external-funding-sources/${externalFundingSourceID}`, {
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export interface WalletGetBalanceResponse {
+  data: WalletGetBalanceResponse.Data;
+}
+
+export namespace WalletGetBalanceResponse {
+  export interface Data {
+    /**
+     * Resource ID
+     */
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
+    /**
+     * Resource type
+     */
+    type: string;
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * Amount currently available to spend or withdraw (cents)
+       */
+      availableAmountMinor: number;
+
+      /**
+       * Currency code
+       */
+      currency: 'USD';
+
+      /**
+       * Total wallet ledger balance (cents)
+       */
+      totalAmountMinor: number;
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Party that owns the wallet
+       */
+      party: Relationships.Party;
+    }
+
+    export namespace Relationships {
+      /**
+       * Party that owns the wallet
+       */
+      export interface Party {
+        /**
+         * Related resource identifier
+         */
+        data: Party.Data;
+      }
+
+      export namespace Party {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+    }
+  }
+}
+
+export interface WalletGetDepositInstructionsResponse {
+  data: WalletGetDepositInstructionsResponse.Data;
+}
+
+export namespace WalletGetDepositInstructionsResponse {
+  export interface Data {
+    /**
+     * Resource ID (the wallet handle)
+     */
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource type
+     */
+    type: string;
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * Account number for ACH deposits
+       */
+      accountNumber: string;
+
+      /**
+       * Name of the receiving bank
+       */
+      bankName: string;
+
+      /**
+       * Bank routing number for ACH deposits
+       */
+      routingNumber: string;
+    }
+  }
+}
+
+export interface WalletInitiateDepositResponse {
+  data: WalletInitiateDepositResponse.Data;
+}
+
+export namespace WalletInitiateDepositResponse {
+  export interface Data {
+    /**
+     * Transaction handle (txn_xxx). Empty when the operation failed before a
+     * transaction was created.
+     */
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource type
+     */
+    type: string;
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * Amount in cents
+       */
+      amount: number;
+
+      /**
+       * Currency code
+       */
+      currency: string;
+
+      /**
+       * Error message if failed
+       */
+      error: string | null;
+
+      /**
+       * Detailed error information
+       */
+      errorDetails: string | null;
+
+      /**
+       * Estimated settlement time
+       */
+      estimatedSettlement: string | null;
+
+      /**
+       * Operation status
+       */
+      status: 'PROCESSING' | 'IN_REVIEW' | 'COMPLETED' | 'FAILED' | 'RETURNED';
+    }
+  }
+}
+
+export interface WalletInitiateWithdrawalResponse {
+  data: WalletInitiateWithdrawalResponse.Data;
+}
+
+export namespace WalletInitiateWithdrawalResponse {
+  export interface Data {
+    /**
+     * Transaction handle (txn_xxx). Empty when the operation failed before a
+     * transaction was created.
+     */
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource type
+     */
+    type: string;
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * Amount in cents
+       */
+      amount: number;
+
+      /**
+       * Currency code
+       */
+      currency: string;
+
+      /**
+       * Error message if failed
+       */
+      error: string | null;
+
+      /**
+       * Detailed error information
+       */
+      errorDetails: string | null;
+
+      /**
+       * Estimated settlement time
+       */
+      estimatedSettlement: string | null;
+
+      /**
+       * Payment instruction ID
+       */
+      instructionId: string | null;
+
+      /**
+       * MFA challenge ID
+       */
+      mfaChallengeId: string | null;
+
+      /**
+       * MFA challenge expiration
+       */
+      mfaExpiresAt: string | null;
+
+      /**
+       * Whether MFA is required
+       */
+      mfaRequired: boolean;
+
+      /**
+       * Operation status
+       */
+      status: 'PROCESSING' | 'IN_REVIEW' | 'COMPLETED' | 'FAILED' | 'RETURNED';
+    }
+  }
+}
+
+export interface WalletListPaymentInstrumentsResponse {
+  data: Array<WalletListPaymentInstrumentsResponse.Data>;
+
+  meta: WalletListPaymentInstrumentsResponse.Meta;
+}
+
+export namespace WalletListPaymentInstrumentsResponse {
+  export interface Data {
+    /**
+     * Resource ID
+     */
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
+    /**
+     * Resource type
+     */
+    type: string;
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * Account display name
+       */
+      accountName: string | null;
+
+      /**
+       * Account type (checking, savings)
+       */
+      accountType: 'checking' | 'savings' | 'unknown' | null;
+
+      /**
+       * Bank institution name
+       */
+      bankName: string | null;
+
+      /**
+       * When the funding source was linked
+       */
+      createdAt: string;
+
+      /**
+       * Last 4 digits of account
+       */
+      lastFour: string;
+
+      /**
+       * Status (new, active, disabled)
+       */
+      status: 'new' | 'active' | 'disabled' | 'deleted' | 'unknown';
+
+      /**
+       * Verification state
+       */
+      verificationState: string | null;
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Party that owns the funding source
+       */
+      party: Relationships.Party;
+    }
+
+    export namespace Relationships {
+      /**
+       * Party that owns the funding source
+       */
+      export interface Party {
+        /**
+         * Related resource identifier
+         */
+        data: Party.Data;
+      }
+
+      export namespace Party {
+        /**
+         * 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 WalletRemovePaymentInstrumentResponse {
+  data: WalletRemovePaymentInstrumentResponse.Data;
+
+  meta: WalletRemovePaymentInstrumentResponse.Meta;
+}
+
+export namespace WalletRemovePaymentInstrumentResponse {
+  export interface Data {
+    /**
+     * Resource ID
+     */
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
+    /**
+     * Resource type
+     */
+    type: string;
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * Account display name
+       */
+      accountName: string | null;
+
+      /**
+       * Account type (checking, savings)
+       */
+      accountType: 'checking' | 'savings' | 'unknown' | null;
+
+      /**
+       * Bank institution name
+       */
+      bankName: string | null;
+
+      /**
+       * When the funding source was linked
+       */
+      createdAt: string;
+
+      /**
+       * Last 4 digits of account
+       */
+      lastFour: string;
+
+      /**
+       * Status (new, active, disabled)
+       */
+      status: 'new' | 'active' | 'disabled' | 'deleted' | 'unknown';
+
+      /**
+       * Verification state
+       */
+      verificationState: string | null;
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Party that owns the funding source
+       */
+      party: Relationships.Party;
+    }
+
+    export namespace Relationships {
+      /**
+       * Party that owns the funding source
+       */
+      export interface Party {
+        /**
+         * Related resource identifier
+         */
+        data: Party.Data;
+      }
+
+      export namespace Party {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+    }
+  }
+
+  export interface Meta {
+    /**
+     * Indicates the resource was deleted
+     */
+    deleted: true;
+  }
+}
+
+export interface WalletGetBalanceParams {
+  /**
+   * Query param
+   */
+  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 interface WalletGetDepositInstructionsParams {
+  /**
+   * Agent ID (agt_xxx) identifying which agent is making the request.
+   */
+  'X-Agent-ID'?: string;
+
+  /**
+   * Required when X-Agent-ID is present. Session or conversation ID for agent
+   * observability.
+   */
+  'X-Instance-ID'?: string;
+}
+
+export interface WalletInitiateDepositParams {
+  /**
+   * Body param: Amount in cents
+   */
+  amount: number;
+
+  /**
+   * Body param: External funding source ID (efs\_\*)
+   */
+  externalFundingSourceId: string;
+
+  /**
+   * Header param: Unique key for idempotent request handling. If a request with the
+   * same key was already processed, the original response is returned.
+   */
+  'Idempotency-Key': string;
+
+  /**
+   * Body param: Currency code
+   */
+  currency?: string;
+
+  /**
+   * Body param: Deposit description
+   */
+  description?: 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 interface WalletInitiateWithdrawalParams {
+  /**
+   * Body param: Amount in cents
+   */
+  amount: number;
+
+  /**
+   * Body param: External funding source ID (efs\_\*)
+   */
+  externalFundingSourceId: string;
+
+  /**
+   * Header param: Unique key for idempotent request handling. If a request with the
+   * same key was already processed, the original response is returned.
+   */
+  'Idempotency-Key': string;
+
+  /**
+   * Body param: Currency code
+   */
+  currency?: string;
+
+  /**
+   * Body param: Withdrawal description
+   */
+  description?: 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 interface WalletListPaymentInstrumentsParams {
+  /**
+   * Query param
+   */
+  cursor?: string;
+
+  /**
+   * Query param
+   */
+  limit?: number;
+
+  /**
+   * 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 WalletRemovePaymentInstrumentParams {
+  /**
+   * Agent ID (agt_xxx) identifying which agent is making the request.
+   */
+  'X-Agent-ID'?: string;
+
+  /**
+   * Required when X-Agent-ID is present. Session or conversation ID for agent
+   * observability.
+   */
+  'X-Instance-ID'?: string;
+}
+
+export declare namespace Wallet {
+  export {
+    type WalletGetBalanceResponse as WalletGetBalanceResponse,
+    type WalletGetDepositInstructionsResponse as WalletGetDepositInstructionsResponse,
+    type WalletInitiateDepositResponse as WalletInitiateDepositResponse,
+    type WalletInitiateWithdrawalResponse as WalletInitiateWithdrawalResponse,
+    type WalletListPaymentInstrumentsResponse as WalletListPaymentInstrumentsResponse,
+    type WalletRemovePaymentInstrumentResponse as WalletRemovePaymentInstrumentResponse,
+    type WalletGetBalanceParams as WalletGetBalanceParams,
+    type WalletGetDepositInstructionsParams as WalletGetDepositInstructionsParams,
+    type WalletInitiateDepositParams as WalletInitiateDepositParams,
+    type WalletInitiateWithdrawalParams as WalletInitiateWithdrawalParams,
+    type WalletListPaymentInstrumentsParams as WalletListPaymentInstrumentsParams,
+    type WalletRemovePaymentInstrumentParams as WalletRemovePaymentInstrumentParams,
+  };
+}