@naturalpay/sdk 0.2.1 → 0.4.0

package/src/resources/wallet.ts

@@ -7,151 +7,19 @@ import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
 /**
- * Wallet balance, deposits, withdrawals, and external funding sources
+ * Wallet balance, deposits, withdrawals, and external accounts
  */
 export class Wallet extends APIResource {
   /**
-   * Get spendable and total wallet ledger balance.
-   *
-   * @example
-   * ```ts
-   * const response = await client.wallet.getBalance();
-   * ```
+   * List wallets for the authenticated party, including balance and ACH deposit
+   * instructions when available. Currently returns at most one wallet.
    */
-  getBalance(
-    params: WalletGetBalanceParams | null | undefined = {},
+  list(
+    params: WalletListParams | 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> {
+  ): APIPromise<WalletListResponse> {
     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,
+    return this._client.get('/wallets', {
       ...options,
       headers: buildHeaders([
         {
@@ -164,23 +32,16 @@ export class Wallet extends APIResource {
   }
 
   /**
-   * Remove (unlink) a bank account.
-   *
-   * @example
-   * ```ts
-   * const response =
-   *   await client.wallet.removePaymentInstrument(
-   *     'efs_ecc2efdd09bd231a9ad9bd2aada37aa7',
-   *   );
-   * ```
+   * Get a wallet visible to the authenticated party, including balance and ACH
+   * deposit instructions when available.
    */
-  removePaymentInstrument(
-    externalFundingSourceID: string,
-    params: WalletRemovePaymentInstrumentParams | null | undefined = {},
+  get(
+    walletID: string,
+    params: WalletGetParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<WalletRemovePaymentInstrumentResponse> {
+  ): APIPromise<WalletGetResponse> {
     const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID } = params ?? {};
-    return this._client.delete(path`/wallet/external-funding-sources/${externalFundingSourceID}`, {
+    return this._client.get(path`/wallets/${walletID}`, {
       ...options,
       headers: buildHeaders([
         {
@@ -193,11 +54,13 @@ export class Wallet extends APIResource {
   }
 }
 
-export interface WalletGetBalanceResponse {
-  data: WalletGetBalanceResponse.Data;
+export interface WalletListResponse {
+  data: Array<WalletListResponse.Data>;
+
+  meta: WalletListResponse.Meta;
 }
 
-export namespace WalletGetBalanceResponse {
+export namespace WalletListResponse {
   export interface Data {
     /**
      * Resource ID
@@ -226,314 +89,81 @@ export namespace WalletGetBalanceResponse {
      */
     export interface Attributes {
       /**
-       * Amount currently available to spend or withdraw (cents)
+       * Wallet ledger balance
        */
-      availableAmountMinor: number;
+      balance: Attributes.Balance;
 
       /**
-       * Currency code
+       * Claimable payment totals
        */
-      currency: 'USD';
+      claims: Attributes.Claims;
 
       /**
-       * Total wallet ledger balance (cents)
+       * ACH deposit instructions for this wallet, when available
        */
-      totalAmountMinor: number;
-    }
+      depositInstructions: Attributes.DepositInstructions | null;
 
-    /**
-     * Resource relationships
-     */
-    export interface Relationships {
       /**
-       * Party that owns the wallet
+       * Wallet readiness status
        */
-      party: Relationships.Party;
+      status: 'active';
     }
 
-    export namespace Relationships {
+    export namespace Attributes {
       /**
-       * Party that owns the wallet
+       * Wallet ledger balance
        */
-      export interface Party {
+      export interface Balance {
         /**
-         * Related resource identifier
+         * Amount currently available to spend or withdraw (cents)
          */
-        data: Party.Data;
-      }
+        available: number;
 
-      export namespace Party {
         /**
-         * Related resource identifier
+         * Currency code
          */
-        export interface Data {
-          id: string;
+        currency: 'USD';
 
-          /**
-           * Resource type
-           */
-          type: string;
-        }
+        /**
+         * Total wallet ledger balance (cents)
+         */
+        total: number;
       }
-    }
-  }
-}
-
-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
+       * Claimable payment totals
        */
-      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;
+      export interface Claims {
+        /**
+         * Total unclaimed product-payment amount (cents)
+         */
+        amount: number;
 
-      /**
-       * When the funding source was linked
-       */
-      createdAt: string;
+        /**
+         * Number of unclaimed product payments
+         */
+        count: number;
+      }
 
       /**
-       * Last 4 digits of account
+       * ACH deposit instructions for this wallet, when available
        */
-      lastFour: string;
+      export interface DepositInstructions {
+        /**
+         * Account number for ACH deposits
+         */
+        accountNumber: string;
 
-      /**
-       * Status (new, active, disabled)
-       */
-      status: 'new' | 'active' | 'disabled' | 'deleted' | 'unknown';
+        /**
+         * Name of the receiving bank
+         */
+        bankName: string;
 
-      /**
-       * Verification state
-       */
-      verificationState: string | null;
+        /**
+         * Bank routing number for ACH deposits
+         */
+        routingNumber: string;
+      }
     }
 
     /**
@@ -541,14 +171,14 @@ export namespace WalletListPaymentInstrumentsResponse {
      */
     export interface Relationships {
       /**
-       * Party that owns the funding source
+       * Party that owns the wallet
        */
       party: Relationships.Party;
     }
 
     export namespace Relationships {
       /**
-       * Party that owns the funding source
+       * Party that owns the wallet
        */
       export interface Party {
         /**
@@ -586,13 +216,11 @@ export namespace WalletListPaymentInstrumentsResponse {
   }
 }
 
-export interface WalletRemovePaymentInstrumentResponse {
-  data: WalletRemovePaymentInstrumentResponse.Data;
-
-  meta: WalletRemovePaymentInstrumentResponse.Meta;
+export interface WalletGetResponse {
+  data: WalletGetResponse.Data;
 }
 
-export namespace WalletRemovePaymentInstrumentResponse {
+export namespace WalletGetResponse {
   export interface Data {
     /**
      * Resource ID
@@ -621,39 +249,81 @@ export namespace WalletRemovePaymentInstrumentResponse {
      */
     export interface Attributes {
       /**
-       * Account display name
+       * Wallet ledger balance
        */
-      accountName: string | null;
+      balance: Attributes.Balance;
 
       /**
-       * Account type (checking, savings)
+       * Claimable payment totals
        */
-      accountType: 'checking' | 'savings' | 'unknown' | null;
+      claims: Attributes.Claims;
 
       /**
-       * Bank institution name
+       * ACH deposit instructions for this wallet, when available
        */
-      bankName: string | null;
+      depositInstructions: Attributes.DepositInstructions | null;
 
       /**
-       * When the funding source was linked
+       * Wallet readiness status
        */
-      createdAt: string;
+      status: 'active';
+    }
 
+    export namespace Attributes {
       /**
-       * Last 4 digits of account
+       * Wallet ledger balance
        */
-      lastFour: string;
+      export interface Balance {
+        /**
+         * Amount currently available to spend or withdraw (cents)
+         */
+        available: number;
+
+        /**
+         * Currency code
+         */
+        currency: 'USD';
+
+        /**
+         * Total wallet ledger balance (cents)
+         */
+        total: number;
+      }
 
       /**
-       * Status (new, active, disabled)
+       * Claimable payment totals
        */
-      status: 'new' | 'active' | 'disabled' | 'deleted' | 'unknown';
+      export interface Claims {
+        /**
+         * Total unclaimed product-payment amount (cents)
+         */
+        amount: number;
+
+        /**
+         * Number of unclaimed product payments
+         */
+        count: number;
+      }
 
       /**
-       * Verification state
+       * ACH deposit instructions for this wallet, when available
        */
-      verificationState: string | null;
+      export interface DepositInstructions {
+        /**
+         * Account number for ACH deposits
+         */
+        accountNumber: string;
+
+        /**
+         * Name of the receiving bank
+         */
+        bankName: string;
+
+        /**
+         * Bank routing number for ACH deposits
+         */
+        routingNumber: string;
+      }
     }
 
     /**
@@ -661,14 +331,14 @@ export namespace WalletRemovePaymentInstrumentResponse {
      */
     export interface Relationships {
       /**
-       * Party that owns the funding source
+       * Party that owns the wallet
        */
       party: Relationships.Party;
     }
 
     export namespace Relationships {
       /**
-       * Party that owns the funding source
+       * Party that owns the wallet
        */
       export interface Party {
         /**
@@ -692,34 +362,9 @@ export namespace WalletRemovePaymentInstrumentResponse {
       }
     }
   }
-
-  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 {
+export interface WalletListParams {
   /**
    * Agent ID (agt_xxx) identifying which agent is making the request.
    */
@@ -732,108 +377,7 @@ export interface WalletGetDepositInstructionsParams {
   '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 {
+export interface WalletGetParams {
   /**
    * Agent ID (agt_xxx) identifying which agent is making the request.
    */
@@ -848,17 +392,9 @@ export interface WalletRemovePaymentInstrumentParams {
 
 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,
+    type WalletListResponse as WalletListResponse,
+    type WalletGetResponse as WalletGetResponse,
+    type WalletListParams as WalletListParams,
+    type WalletGetParams as WalletGetParams,
   };
 }