@naturalpay/sdk 0.2.1 → 0.3.0

package/src/resources/external-accounts.ts

@@ -0,0 +1,324 @@
+// 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';
+
+/**
+ * Linked external bank accounts
+ */
+export class ExternalAccounts extends APIResource {
+  /**
+   * List linked external accounts with cursor pagination.
+   */
+  list(
+    params: ExternalAccountListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ExternalAccountListResponse> {
+    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID, ...query } = params ?? {};
+    return this._client.get('/external-accounts', {
+      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.
+   */
+  remove(
+    externalAccountID: string,
+    params: ExternalAccountRemoveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ExternalAccountRemoveResponse> {
+    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID } = params ?? {};
+    return this._client.delete(path`/external-accounts/${externalAccountID}`, {
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export interface ExternalAccountListResponse {
+  data: Array<ExternalAccountListResponse.Data>;
+
+  meta: ExternalAccountListResponse.Meta;
+}
+
+export namespace ExternalAccountListResponse {
+  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 external account was linked
+       */
+      createdAt: string;
+
+      /**
+       * Last 4 digits of account
+       */
+      lastFour: string;
+
+      /**
+       * Status (pending, active, disabled)
+       */
+      status: 'pending' | 'new' | 'active' | 'disabled' | 'deleted' | 'unknown';
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Party that owns the external account
+       */
+      party: Relationships.Party;
+    }
+
+    export namespace Relationships {
+      /**
+       * Party that owns the external account
+       */
+      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 ExternalAccountRemoveResponse {
+  data: ExternalAccountRemoveResponse.Data;
+
+  meta: ExternalAccountRemoveResponse.Meta;
+}
+
+export namespace ExternalAccountRemoveResponse {
+  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 external account was linked
+       */
+      createdAt: string;
+
+      /**
+       * Last 4 digits of account
+       */
+      lastFour: string;
+
+      /**
+       * Status (pending, active, disabled)
+       */
+      status: 'pending' | 'new' | 'active' | 'disabled' | 'deleted' | 'unknown';
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Party that owns the external account
+       */
+      party: Relationships.Party;
+    }
+
+    export namespace Relationships {
+      /**
+       * Party that owns the external account
+       */
+      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 ExternalAccountListParams {
+  /**
+   * 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 ExternalAccountRemoveParams {
+  /**
+   * 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 ExternalAccounts {
+  export {
+    type ExternalAccountListResponse as ExternalAccountListResponse,
+    type ExternalAccountRemoveResponse as ExternalAccountRemoveResponse,
+    type ExternalAccountListParams as ExternalAccountListParams,
+    type ExternalAccountRemoveParams as ExternalAccountRemoveParams,
+  };
+}

package/src/resources/index.ts

@@ -43,6 +43,13 @@ export {
   type DelegationGetAgentDelegationParams,
   type DelegationListAgentDelegationsParams,
 } from './delegations';
+export {
+  ExternalAccounts,
+  type ExternalAccountListResponse,
+  type ExternalAccountRemoveResponse,
+  type ExternalAccountListParams,
+  type ExternalAccountRemoveParams,
+} from './external-accounts';
 export {
   Invitations,
   type InvitationCreateResponse,
@@ -80,16 +87,27 @@ export {
 } from './transactions';
 export {
   Wallet,
-  type WalletGetBalanceResponse,
-  type WalletGetDepositInstructionsResponse,
+  type WalletListResponse,
+  type WalletGetResponse,
   type WalletInitiateDepositResponse,
   type WalletInitiateWithdrawalResponse,
-  type WalletListPaymentInstrumentsResponse,
-  type WalletRemovePaymentInstrumentResponse,
-  type WalletGetBalanceParams,
-  type WalletGetDepositInstructionsParams,
+  type WalletListParams,
+  type WalletGetParams,
   type WalletInitiateDepositParams,
   type WalletInitiateWithdrawalParams,
-  type WalletListPaymentInstrumentsParams,
-  type WalletRemovePaymentInstrumentParams,
 } from './wallet';
+export {
+  Webhooks,
+  type WebhookCreateResponse,
+  type WebhookUpdateResponse,
+  type WebhookListResponse,
+  type WebhookGetResponse,
+  type WebhookRemoveResponse,
+  type WebhookRotateSecretResponse,
+  type WebhookCreateParams,
+  type WebhookUpdateParams,
+  type WebhookListParams,
+  type WebhookGetParams,
+  type WebhookRemoveParams,
+  type WebhookRotateSecretParams,
+} from './webhooks';

package/src/resources/invitations.ts

@@ -11,7 +11,7 @@ import { path } from '../internal/utils/path';
  */
 export class Invitations extends APIResource {
   /**
-   * Create one or more invitations to join the authenticated user's party.
+   * Send invitations to join your party.
    *
    * @example
    * ```ts

package/src/resources/parties.ts

@@ -10,7 +10,7 @@ import { RequestOptions } from '../internal/request-options';
  */
 export class Parties extends APIResource {
   /**
-   * Update the authenticated caller's party details.
+   * Update your party.
    *
    * @example
    * ```ts
@@ -19,7 +19,7 @@ export class Parties extends APIResource {
    */
   update(params: PartyUpdateParams, options?: RequestOptions): APIPromise<PartyUpdateResponse> {
     const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID, ...body } = params;
-    return this._client.put('/parties/me', {
+    return this._client.patch('/parties/me', {
       body,
       ...options,
       headers: buildHeaders([
@@ -33,7 +33,7 @@ export class Parties extends APIResource {
   }
 
   /**
-   * Retrieve the authenticated caller's party details.
+   * Get your party.
    *
    * @example
    * ```ts

package/src/resources/payment-requests.ts

@@ -18,7 +18,6 @@ export class PaymentRequests extends APIResource {
    * const paymentRequest = await client.paymentRequests.create({
    *   amount: 1,
    *   payer: { kind: 'email', value: 'dev@stainless.com' },
-   *   walletId: 'wal_ecc2efdd09bd231a9ad9bd2aada37aa7',
    *   'Idempotency-Key': 'Idempotency-Key',
    * });
    * ```
@@ -130,7 +129,7 @@ export namespace PaymentRequestCreateResponse {
      */
     export interface Attributes {
       /**
-       * Amount in minor units (cents for USD)
+       * Amount in cents
        */
       amount: number;
 
@@ -162,7 +161,7 @@ export namespace PaymentRequestCreateResponse {
       /**
        * Which identifier type was used to address the payer
        */
-      payerIdentifierType: 'email' | 'phone' | 'party_id';
+      payerIdentifierType: 'email' | 'phone' | 'party_id' | 'agent_id';
 
       /**
        * Display name of the payer
@@ -170,7 +169,7 @@ export namespace PaymentRequestCreateResponse {
       payerName: string | null;
 
       /**
-       * Natural party ID (pty\_\*) of the payer if addressed by party
+       * Natural party ID (pty\_\*) resolved for the payer, including agent owner parties
        */
       payerPartyId: string | null;
 
@@ -243,7 +242,7 @@ export namespace PaymentRequestListResponse {
      */
     export interface Attributes {
       /**
-       * Amount in minor units (cents for USD)
+       * Amount in cents
        */
       amount: number;
 
@@ -275,7 +274,7 @@ export namespace PaymentRequestListResponse {
       /**
        * Which identifier type was used to address the payer
        */
-      payerIdentifierType: 'email' | 'phone' | 'party_id';
+      payerIdentifierType: 'email' | 'phone' | 'party_id' | 'agent_id';
 
       /**
        * Display name of the payer
@@ -283,7 +282,7 @@ export namespace PaymentRequestListResponse {
       payerName: string | null;
 
       /**
-       * Natural party ID (pty\_\*) of the payer if addressed by party
+       * Natural party ID (pty\_\*) resolved for the payer, including agent owner parties
        */
       payerPartyId: string | null;
 
@@ -366,7 +365,7 @@ export namespace PaymentRequestGetResponse {
      */
     export interface Attributes {
       /**
-       * Amount in minor units (cents for USD)
+       * Amount in cents
        */
       amount: number;
 
@@ -398,7 +397,7 @@ export namespace PaymentRequestGetResponse {
       /**
        * Which identifier type was used to address the payer
        */
-      payerIdentifierType: 'email' | 'phone' | 'party_id';
+      payerIdentifierType: 'email' | 'phone' | 'party_id' | 'agent_id';
 
       /**
        * Display name of the payer
@@ -406,7 +405,7 @@ export namespace PaymentRequestGetResponse {
       payerName: string | null;
 
       /**
-       * Natural party ID (pty\_\*) of the payer if addressed by party
+       * Natural party ID (pty\_\*) resolved for the payer, including agent owner parties
        */
       payerPartyId: string | null;
 
@@ -451,22 +450,18 @@ export namespace PaymentRequestGetResponse {
 
 export interface PaymentRequestCreateParams {
   /**
-   * Body param: Amount in minor units (cents for USD)
+   * Body param: Amount in cents
    */
   amount: number;
 
   /**
-   * Body param: Who pays — exactly one of email, phone, or party.
+   * Body param: Who pays — exactly one of email, phone, party, or agent.
    */
   payer:
     | PaymentRequestCreateParams.UnionMember0
     | PaymentRequestCreateParams.UnionMember1
-    | PaymentRequestCreateParams.UnionMember2;
-
-  /**
-   * Body param: Wallet that should receive the funds
-   */
-  walletId: string;
+    | PaymentRequestCreateParams.UnionMember2
+    | PaymentRequestCreateParams.UnionMember3;
 
   /**
    * Header param: Unique key for idempotent request handling. If a request with the
@@ -501,6 +496,12 @@ export interface PaymentRequestCreateParams {
    */
   sendLink?: PaymentRequestCreateParams.SendLink;
 
+  /**
+   * Body param: Wallet that should receive the funds. Omit to use the requester
+   * party's default wallet.
+   */
+  walletId?: string;
+
   /**
    * Header param: Agent ID (agt_xxx) identifying which agent is making the request.
    */
@@ -541,6 +542,15 @@ export namespace PaymentRequestCreateParams {
     value: string;
   }
 
+  export interface UnionMember3 {
+    kind: 'agent_id';
+
+    /**
+     * Natural agent ID (agt\_\*) of the payer
+     */
+    value: string;
+  }
+
   /**
    * If provided, immediately deliver the payment link to the payer via the named
    * channel

package/src/resources/payments.ts

@@ -182,7 +182,7 @@ export interface PaymentCreateParams {
   amount: number;
 
   /**
-   * Body param: Recipient: party ID (pty\_\*), email, or phone
+   * Body param: Recipient: party ID (pty*\*), agent ID (agt*\*), email, or phone
    */
   counterparty: string;
 

package/src/resources/transactions.ts

@@ -11,7 +11,7 @@ import { path } from '../internal/utils/path';
  */
 export class Transactions extends APIResource {
   /**
-   * List transactions visible to the authenticated party and its delegated agents.
+   * List transactions visible to your party and its delegated agents.
    */
   list(
     params: TransactionListParams | null | undefined = {},
@@ -32,7 +32,7 @@ export class Transactions extends APIResource {
   }
 
   /**
-   * Get a single transaction visible to the authenticated party.
+   * Get a single transaction visible to your party.
    */
   get(
     transactionID: string,
@@ -96,10 +96,9 @@ export namespace TransactionListResponse {
       amount: number;
 
       /**
-       * Classification from the authenticated party's perspective. Derived from
-       * transactionType + direction: "sent"/"received" for wallet-to-wallet payments
-       * (OUTBOUND/INBOUND), "deposit"/"withdrawal" for external transfers
-       * (INBOUND/OUTBOUND).
+       * 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';
 
@@ -138,6 +137,12 @@ export namespace TransactionListResponse {
        */
       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
        */
@@ -351,10 +356,9 @@ export namespace TransactionGetResponse {
       amount: number;
 
       /**
-       * Classification from the authenticated party's perspective. Derived from
-       * transactionType + direction: "sent"/"received" for wallet-to-wallet payments
-       * (OUTBOUND/INBOUND), "deposit"/"withdrawal" for external transfers
-       * (INBOUND/OUTBOUND).
+       * 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';
 
@@ -393,6 +397,12 @@ export namespace TransactionGetResponse {
        */
       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
        */