@naturalpay/sdk 0.2.1 → 0.4.0

package/src/client.ts

@@ -61,6 +61,24 @@ import {
   DelegationListAgentDelegationsResponse,
   Delegations,
 } from './resources/delegations';
+import {
+  EscalationApproveParams,
+  EscalationApproveResponse,
+  EscalationDenyParams,
+  EscalationDenyResponse,
+  EscalationGetParams,
+  EscalationGetResponse,
+  EscalationListParams,
+  EscalationListResponse,
+  Escalations,
+} from './resources/escalations';
+import {
+  ExternalAccountListParams,
+  ExternalAccountListResponse,
+  ExternalAccountRemoveParams,
+  ExternalAccountRemoveResponse,
+  ExternalAccounts,
+} from './resources/external-accounts';
 import {
   InvitationCreateParams,
   InvitationCreateResponse,
@@ -76,19 +94,35 @@ import {
   PartyGetResponse,
   PartyListMembersParams,
   PartyListMembersResponse,
+  PartyRemoveMemberParams,
+  PartyRemoveMemberResponse,
   PartyUpdateParams,
   PartyUpdateResponse,
 } from './resources/parties';
 import {
   PaymentRequestCreateParams,
   PaymentRequestCreateResponse,
+  PaymentRequestDeclineParams,
+  PaymentRequestDeclineResponse,
+  PaymentRequestFulfillParams,
+  PaymentRequestFulfillResponse,
   PaymentRequestGetParams,
   PaymentRequestGetResponse,
+  PaymentRequestListIncomingParams,
+  PaymentRequestListIncomingResponse,
   PaymentRequestListParams,
   PaymentRequestListResponse,
   PaymentRequests,
 } from './resources/payment-requests';
-import { PaymentCreateParams, PaymentCreateResponse, Payments } from './resources/payments';
+import {
+  PaymentCreateParams,
+  PaymentCreateResponse,
+  PaymentGetParams,
+  PaymentGetResponse,
+  PaymentListParams,
+  PaymentListResponse,
+  Payments,
+} from './resources/payments';
 import {
   TransactionGetParams,
   TransactionGetResponse,
@@ -96,21 +130,39 @@ import {
   TransactionListResponse,
   Transactions,
 } from './resources/transactions';
+import {
+  TransferGetParams,
+  TransferGetResponse,
+  TransferInitiateDepositParams,
+  TransferInitiateDepositResponse,
+  TransferInitiateWithdrawalParams,
+  TransferInitiateWithdrawalResponse,
+  TransferListParams,
+  TransferListResponse,
+  Transfers,
+} from './resources/transfers';
 import {
   Wallet,
-  WalletGetBalanceParams,
-  WalletGetBalanceResponse,
-  WalletGetDepositInstructionsParams,
-  WalletGetDepositInstructionsResponse,
-  WalletInitiateDepositParams,
-  WalletInitiateDepositResponse,
-  WalletInitiateWithdrawalParams,
-  WalletInitiateWithdrawalResponse,
-  WalletListPaymentInstrumentsParams,
-  WalletListPaymentInstrumentsResponse,
-  WalletRemovePaymentInstrumentParams,
-  WalletRemovePaymentInstrumentResponse,
+  WalletGetParams,
+  WalletGetResponse,
+  WalletListParams,
+  WalletListResponse,
 } from './resources/wallet';
+import {
+  WebhookCreateParams,
+  WebhookCreateResponse,
+  WebhookGetParams,
+  WebhookGetResponse,
+  WebhookListParams,
+  WebhookListResponse,
+  WebhookRemoveParams,
+  WebhookRemoveResponse,
+  WebhookRotateSecretParams,
+  WebhookRotateSecretResponse,
+  WebhookUpdateParams,
+  WebhookUpdateResponse,
+  Webhooks,
+} from './resources/webhooks';
 import { type Fetch } from './internal/builtin-types';
 import { HeadersLike, NullableHeaders, buildHeaders } from './internal/headers';
 import { FinalRequestOptions, RequestOptions } from './internal/request-options';
@@ -132,7 +184,7 @@ type Environment = keyof typeof environments;
 
 export interface ClientOptions {
   /**
-   * Defaults to process.env['NATURALPAY_API_KEY'].
+   * Defaults to process.env['NATURAL_API_KEY'].
    */
   apiKey?: string | undefined;
 
@@ -235,7 +287,7 @@ export class Natural {
   /**
    * API Client for interfacing with the Naturalpay API.
    *
-   * @param {string | undefined} [opts.apiKey=process.env['NATURALPAY_API_KEY'] ?? undefined]
+   * @param {string | undefined} [opts.apiKey=process.env['NATURAL_API_KEY'] ?? undefined]
    * @param {Environment} [opts.environment=production] - Specifies the environment URL to use for the API.
    * @param {string} [opts.baseURL=process.env['NATURALPAY_BASE_URL'] ?? https://api.natural.co] - Override the default base URL for the API.
    * @param {number} [opts.timeout=1 minute] - The maximum amount of time (in milliseconds) the client will wait for a response before timing out.
@@ -247,12 +299,12 @@ export class Natural {
    */
   constructor({
     baseURL = readEnv('NATURALPAY_BASE_URL'),
-    apiKey = readEnv('NATURALPAY_API_KEY'),
+    apiKey = readEnv('NATURAL_API_KEY'),
     ...opts
   }: ClientOptions = {}) {
     if (apiKey === undefined) {
       throw new Errors.NaturalError(
-        "The NATURALPAY_API_KEY environment variable is missing or empty; either provide it, or instantiate the Natural client with an apiKey option, like new Natural({ apiKey: 'My API Key' }).",
+        "The NATURAL_API_KEY environment variable is missing or empty; either provide it, or instantiate the Natural client with an apiKey option, like new Natural({ apiKey: 'My API Key' }).",
       );
     }
 
@@ -878,17 +930,33 @@ export class Natural {
    */
   paymentRequests: API.PaymentRequests = new API.PaymentRequests(this);
   /**
-   * Payment and transaction operations
+   * Payment operations
    */
   payments: API.Payments = new API.Payments(this);
   /**
-   * Payment and transaction operations
+   * Transaction activity and history operations
    */
   transactions: API.Transactions = new API.Transactions(this);
   /**
-   * Wallet balance, deposits, withdrawals, and external funding sources
+   * Payment approval escalation operations
+   */
+  escalations: API.Escalations = new API.Escalations(this);
+  /**
+   * Deposit and withdrawal operations
+   */
+  transfers: API.Transfers = new API.Transfers(this);
+  /**
+   * Webhook endpoint management
+   */
+  webhooks: API.Webhooks = new API.Webhooks(this);
+  /**
+   * Wallet balance, deposits, withdrawals, and external accounts
    */
   wallet: API.Wallet = new API.Wallet(this);
+  /**
+   * Linked external bank accounts
+   */
+  externalAccounts: API.ExternalAccounts = new API.ExternalAccounts(this);
 }
 
 Natural.Agents = Agents;
@@ -901,7 +969,11 @@ Natural.Parties = Parties;
 Natural.PaymentRequests = PaymentRequests;
 Natural.Payments = Payments;
 Natural.Transactions = Transactions;
+Natural.Escalations = Escalations;
+Natural.Transfers = Transfers;
+Natural.Webhooks = Webhooks;
 Natural.Wallet = Wallet;
+Natural.ExternalAccounts = ExternalAccounts;
 
 export declare namespace Natural {
   export type RequestOptions = Opts.RequestOptions;
@@ -973,25 +1045,37 @@ export declare namespace Natural {
     type PartyUpdateResponse as PartyUpdateResponse,
     type PartyGetResponse as PartyGetResponse,
     type PartyListMembersResponse as PartyListMembersResponse,
+    type PartyRemoveMemberResponse as PartyRemoveMemberResponse,
     type PartyUpdateParams as PartyUpdateParams,
     type PartyGetParams as PartyGetParams,
     type PartyListMembersParams as PartyListMembersParams,
+    type PartyRemoveMemberParams as PartyRemoveMemberParams,
   };
 
   export {
     PaymentRequests as PaymentRequests,
     type PaymentRequestCreateResponse as PaymentRequestCreateResponse,
     type PaymentRequestListResponse as PaymentRequestListResponse,
+    type PaymentRequestDeclineResponse as PaymentRequestDeclineResponse,
+    type PaymentRequestFulfillResponse as PaymentRequestFulfillResponse,
     type PaymentRequestGetResponse as PaymentRequestGetResponse,
+    type PaymentRequestListIncomingResponse as PaymentRequestListIncomingResponse,
     type PaymentRequestCreateParams as PaymentRequestCreateParams,
     type PaymentRequestListParams as PaymentRequestListParams,
+    type PaymentRequestDeclineParams as PaymentRequestDeclineParams,
+    type PaymentRequestFulfillParams as PaymentRequestFulfillParams,
     type PaymentRequestGetParams as PaymentRequestGetParams,
+    type PaymentRequestListIncomingParams as PaymentRequestListIncomingParams,
   };
 
   export {
     Payments as Payments,
     type PaymentCreateResponse as PaymentCreateResponse,
+    type PaymentListResponse as PaymentListResponse,
+    type PaymentGetResponse as PaymentGetResponse,
     type PaymentCreateParams as PaymentCreateParams,
+    type PaymentListParams as PaymentListParams,
+    type PaymentGetParams as PaymentGetParams,
   };
 
   export {
@@ -1002,19 +1086,59 @@ export declare namespace Natural {
     type TransactionGetParams as TransactionGetParams,
   };
 
+  export {
+    Escalations as Escalations,
+    type EscalationListResponse as EscalationListResponse,
+    type EscalationApproveResponse as EscalationApproveResponse,
+    type EscalationDenyResponse as EscalationDenyResponse,
+    type EscalationGetResponse as EscalationGetResponse,
+    type EscalationListParams as EscalationListParams,
+    type EscalationApproveParams as EscalationApproveParams,
+    type EscalationDenyParams as EscalationDenyParams,
+    type EscalationGetParams as EscalationGetParams,
+  };
+
+  export {
+    Transfers as Transfers,
+    type TransferListResponse as TransferListResponse,
+    type TransferGetResponse as TransferGetResponse,
+    type TransferInitiateDepositResponse as TransferInitiateDepositResponse,
+    type TransferInitiateWithdrawalResponse as TransferInitiateWithdrawalResponse,
+    type TransferListParams as TransferListParams,
+    type TransferGetParams as TransferGetParams,
+    type TransferInitiateDepositParams as TransferInitiateDepositParams,
+    type TransferInitiateWithdrawalParams as TransferInitiateWithdrawalParams,
+  };
+
+  export {
+    Webhooks as Webhooks,
+    type WebhookCreateResponse as WebhookCreateResponse,
+    type WebhookUpdateResponse as WebhookUpdateResponse,
+    type WebhookListResponse as WebhookListResponse,
+    type WebhookGetResponse as WebhookGetResponse,
+    type WebhookRemoveResponse as WebhookRemoveResponse,
+    type WebhookRotateSecretResponse as WebhookRotateSecretResponse,
+    type WebhookCreateParams as WebhookCreateParams,
+    type WebhookUpdateParams as WebhookUpdateParams,
+    type WebhookListParams as WebhookListParams,
+    type WebhookGetParams as WebhookGetParams,
+    type WebhookRemoveParams as WebhookRemoveParams,
+    type WebhookRotateSecretParams as WebhookRotateSecretParams,
+  };
+
   export {
     Wallet as Wallet,
-    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,
+  };
+
+  export {
+    ExternalAccounts as ExternalAccounts,
+    type ExternalAccountListResponse as ExternalAccountListResponse,
+    type ExternalAccountRemoveResponse as ExternalAccountRemoveResponse,
+    type ExternalAccountListParams as ExternalAccountListParams,
+    type ExternalAccountRemoveParams as ExternalAccountRemoveParams,
   };
 }

package/src/resources/agents.ts

@@ -11,7 +11,7 @@ import { path } from '../internal/utils/path';
  */
 export class Agents extends APIResource {
   /**
-   * Create a new agent for the authenticated party.
+   * Create a new agent for your party.
    *
    * @example
    * ```ts
@@ -43,7 +43,7 @@ export class Agents extends APIResource {
   }
 
   /**
-   * Update an existing agent's mutable fields or revoke it.
+   * Update an existing agent's mutable fields.
    *
    * @example
    * ```ts
@@ -64,7 +64,7 @@ export class Agents extends APIResource {
       'X-Instance-ID': xInstanceID,
       ...body
     } = params;
-    return this._client.put(path`/agents/${agentID}`, {
+    return this._client.patch(path`/agents/${agentID}`, {
       body,
       ...options,
       headers: buildHeaders([
@@ -79,7 +79,7 @@ export class Agents extends APIResource {
   }
 
   /**
-   * List agents for the authenticated user's party.
+   * List agents in your party.
    *
    * @example
    * ```ts
@@ -202,7 +202,7 @@ export class Agents extends APIResource {
   }
 
   /**
-   * Delete an agent and clean up its delegations and policies.
+   * Revoke an agent.
    *
    * @example
    * ```ts
@@ -294,25 +294,10 @@ export namespace AgentCreateResponse {
        */
       name: string;
 
-      /**
-       * Observability stats (null when unavailable)
-       */
-      observability: Attributes.Observability | null;
-
       /**
        * Agent status
        */
       status: 'ACTIVE' | 'REVOKED';
-
-      /**
-       * When this agent was last updated
-       */
-      updatedAt: string | null;
-
-      /**
-       * User who last updated this agent (usr\_\*)
-       */
-      updatedBy: string | null;
     }
 
     export namespace Attributes {
@@ -326,26 +311,6 @@ export namespace AgentCreateResponse {
          */
         perTransaction?: number | null;
       }
-
-      /**
-       * Observability stats (null when unavailable)
-       */
-      export interface Observability {
-        /**
-         * Errors in last 24h
-         */
-        errorCount: number;
-
-        /**
-         * Last activity timestamp
-         */
-        lastActiveAt: string | null;
-
-        /**
-         * Requests in last 24h
-         */
-        requestCount: number;
-      }
     }
 
     /**
@@ -444,25 +409,10 @@ export namespace AgentUpdateResponse {
        */
       name: string;
 
-      /**
-       * Observability stats (null when unavailable)
-       */
-      observability: Attributes.Observability | null;
-
       /**
        * Agent status
        */
       status: 'ACTIVE' | 'REVOKED';
-
-      /**
-       * When this agent was last updated
-       */
-      updatedAt: string | null;
-
-      /**
-       * User who last updated this agent (usr\_\*)
-       */
-      updatedBy: string | null;
     }
 
     export namespace Attributes {
@@ -476,26 +426,6 @@ export namespace AgentUpdateResponse {
          */
         perTransaction?: number | null;
       }
-
-      /**
-       * Observability stats (null when unavailable)
-       */
-      export interface Observability {
-        /**
-         * Errors in last 24h
-         */
-        errorCount: number;
-
-        /**
-         * Last activity timestamp
-         */
-        lastActiveAt: string | null;
-
-        /**
-         * Requests in last 24h
-         */
-        requestCount: number;
-      }
     }
 
     /**
@@ -596,25 +526,10 @@ export namespace AgentListResponse {
        */
       name: string;
 
-      /**
-       * Observability stats (null when unavailable)
-       */
-      observability: Attributes.Observability | null;
-
       /**
        * Agent status
        */
       status: 'ACTIVE' | 'REVOKED';
-
-      /**
-       * When this agent was last updated
-       */
-      updatedAt: string | null;
-
-      /**
-       * User who last updated this agent (usr\_\*)
-       */
-      updatedBy: string | null;
     }
 
     export namespace Attributes {
@@ -628,26 +543,6 @@ export namespace AgentListResponse {
          */
         perTransaction?: number | null;
       }
-
-      /**
-       * Observability stats (null when unavailable)
-       */
-      export interface Observability {
-        /**
-         * Errors in last 24h
-         */
-        errorCount: number;
-
-        /**
-         * Last activity timestamp
-         */
-        lastActiveAt: string | null;
-
-        /**
-         * Requests in last 24h
-         */
-        requestCount: number;
-      }
     }
 
     /**
@@ -1014,25 +909,10 @@ export namespace AgentGetResponse {
        */
       name: string;
 
-      /**
-       * Observability stats (null when unavailable)
-       */
-      observability: Attributes.Observability | null;
-
       /**
        * Agent status
        */
       status: 'ACTIVE' | 'REVOKED';
-
-      /**
-       * When this agent was last updated
-       */
-      updatedAt: string | null;
-
-      /**
-       * User who last updated this agent (usr\_\*)
-       */
-      updatedBy: string | null;
     }
 
     export namespace Attributes {
@@ -1046,26 +926,6 @@ export namespace AgentGetResponse {
          */
         perTransaction?: number | null;
       }
-
-      /**
-       * Observability stats (null when unavailable)
-       */
-      export interface Observability {
-        /**
-         * Errors in last 24h
-         */
-        errorCount: number;
-
-        /**
-         * Last activity timestamp
-         */
-        lastActiveAt: string | null;
-
-        /**
-         * Requests in last 24h
-         */
-        requestCount: number;
-      }
     }
 
     /**
@@ -1417,25 +1277,10 @@ export namespace AgentRemoveResponse {
        */
       name: string;
 
-      /**
-       * Observability stats (null when unavailable)
-       */
-      observability: Attributes.Observability | null;
-
       /**
        * Agent status
        */
       status: 'ACTIVE' | 'REVOKED';
-
-      /**
-       * When this agent was last updated
-       */
-      updatedAt: string | null;
-
-      /**
-       * User who last updated this agent (usr\_\*)
-       */
-      updatedBy: string | null;
     }
 
     export namespace Attributes {
@@ -1449,26 +1294,6 @@ export namespace AgentRemoveResponse {
          */
         perTransaction?: number | null;
       }
-
-      /**
-       * Observability stats (null when unavailable)
-       */
-      export interface Observability {
-        /**
-         * Errors in last 24h
-         */
-        errorCount: number;
-
-        /**
-         * Last activity timestamp
-         */
-        lastActiveAt: string | null;
-
-        /**
-         * Requests in last 24h
-         */
-        requestCount: number;
-      }
     }
 
     /**
@@ -1585,11 +1410,6 @@ export interface AgentUpdateParams {
    */
   name?: string | null;
 
-  /**
-   * Body param: Updated status
-   */
-  status?: 'ACTIVE' | 'REVOKED' | null;
-
   /**
    * Header param: Agent ID (agt_xxx) identifying which agent is making the request.
    */

package/src/resources/api-keys.ts

@@ -90,19 +90,26 @@ export class APIKeys extends APIResource {
    *
    * @example
    * ```ts
-   * const response = await client.apiKeys.revoke('keyId');
+   * const response = await client.apiKeys.revoke('keyId', {
+   *   'Idempotency-Key': 'Idempotency-Key',
+   * });
    * ```
    */
   revoke(
     keyID: string,
-    params: APIKeyRevokeParams | null | undefined = {},
+    params: APIKeyRevokeParams,
     options?: RequestOptions,
   ): APIPromise<APIKeyRevokeResponse> {
-    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID } = params ?? {};
-    return this._client.put(path`/api-keys/${keyID}/revoke`, {
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'X-Agent-ID': xAgentID,
+      'X-Instance-ID': xInstanceID,
+    } = params;
+    return this._client.delete(path`/api-keys/${keyID}`, {
       ...options,
       headers: buildHeaders([
         {
+          'Idempotency-Key': idempotencyKey,
           ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
           ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
         },
@@ -499,6 +506,8 @@ export namespace APIKeyGetResponse {
 
 export interface APIKeyRevokeResponse {
   data: APIKeyRevokeResponse.Data;
+
+  meta: APIKeyRevokeResponse.Meta;
 }
 
 export namespace APIKeyRevokeResponse {
@@ -617,6 +626,13 @@ export namespace APIKeyRevokeResponse {
       }
     }
   }
+
+  export interface Meta {
+    /**
+     * Indicates the resource was deleted
+     */
+    deleted: true;
+  }
 }
 
 export interface APIKeyCreateParams {
@@ -717,6 +733,12 @@ export interface APIKeyGetParams {
 }
 
 export interface APIKeyRevokeParams {
+  /**
+   * Unique key for idempotent request handling. If a request with the same key was
+   * already processed, the original response is returned.
+   */
+  'Idempotency-Key': string;
+
   /**
    * Agent ID (agt_xxx) identifying which agent is making the request.
    */