@naturalpay/sdk 0.9.0 → 0.11.0

package/src/resources/payments.ts

@@ -18,10 +18,12 @@ export class Payments extends APIResource {
    * const payment = await client.payments.create({
    *   amount: 1,
    *   counterparty: {
-   *     type: 'type',
+   *     type: 'email',
    *     value: 'dev@stainless.com',
    *   },
    *   'Idempotency-Key': 'Idempotency-Key',
+   *   'X-Agent-ID': 'X-Agent-ID',
+   *   'X-Instance-ID': 'X-Instance-ID',
    * });
    * ```
    */
@@ -36,11 +38,7 @@ export class Payments extends APIResource {
       body,
       ...options,
       headers: buildHeaders([
-        {
-          'Idempotency-Key': idempotencyKey,
-          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
-          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
-        },
+        { 'Idempotency-Key': idempotencyKey, 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID },
         options?.headers,
       ]),
     });
@@ -51,22 +49,50 @@ export class Payments extends APIResource {
    *
    * @example
    * ```ts
-   * const payments = await client.payments.list();
+   * const payments = await client.payments.list({
+   *   'X-Agent-ID': 'X-Agent-ID',
+   *   'X-Instance-ID': 'X-Instance-ID',
+   * });
    * ```
    */
-  list(
-    params: PaymentListParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<PaymentListResponse> {
-    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID, ...query } = params ?? {};
+  list(params: PaymentListParams, options?: RequestOptions): APIPromise<PaymentListResponse> {
+    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID, ...query } = params;
     return this._client.get('/payments', {
       query,
+      ...options,
+      headers: buildHeaders([{ 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID }, options?.headers]),
+    });
+  }
+
+  /**
+   * Cancel a pending-claim payment before the recipient starts claiming it.
+   *
+   * @example
+   * ```ts
+   * const response = await client.payments.cancel(
+   *   'pay_ecc2efdd09bd231a9ad9bd2aada37aa7',
+   *   {
+   *     'Idempotency-Key': 'Idempotency-Key',
+   *     'X-Agent-ID': 'X-Agent-ID',
+   *     'X-Instance-ID': 'X-Instance-ID',
+   *   },
+   * );
+   * ```
+   */
+  cancel(
+    paymentID: string,
+    params: PaymentCancelParams,
+    options?: RequestOptions,
+  ): APIPromise<PaymentCancelResponse> {
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'X-Agent-ID': xAgentID,
+      'X-Instance-ID': xInstanceID,
+    } = params;
+    return this._client.post(path`/payments/${paymentID}/cancel`, {
       ...options,
       headers: buildHeaders([
-        {
-          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
-          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
-        },
+        { 'Idempotency-Key': idempotencyKey, 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID },
         options?.headers,
       ]),
     });
@@ -79,25 +105,19 @@ export class Payments extends APIResource {
    * ```ts
    * const payment = await client.payments.get(
    *   'pay_ecc2efdd09bd231a9ad9bd2aada37aa7',
+   *   {
+   *     'X-Agent-ID': 'X-Agent-ID',
+   *     'X-Instance-ID': 'X-Instance-ID',
+   *   },
    * );
    * ```
    */
-  get(
-    paymentID: string,
-    params: PaymentGetParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<PaymentGetResponse> {
-    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID, ...query } = params ?? {};
+  get(paymentID: string, params: PaymentGetParams, options?: RequestOptions): APIPromise<PaymentGetResponse> {
+    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID, ...query } = params;
     return this._client.get(path`/payments/${paymentID}`, {
       query,
       ...options,
-      headers: buildHeaders([
-        {
-          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
-          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
-        },
-        options?.headers,
-      ]),
+      headers: buildHeaders([{ 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID }, options?.headers]),
     });
   }
 }
@@ -120,7 +140,7 @@ export namespace PaymentCreateResponse {
      */
     relationships: Data.Relationships;
 
-    type: string;
+    type: 'payment';
   }
 
   export namespace Data {
@@ -158,6 +178,7 @@ export namespace PaymentCreateResponse {
         | 'IN_REVIEW'
         | 'COMPLETED'
         | 'FAILED'
+        | 'RETURNED'
         | 'APPROVAL_DENIED'
         | 'CANCELLED';
 
@@ -171,11 +192,22 @@ export namespace PaymentCreateResponse {
      * Resource relationships
      */
     export interface Relationships {
+      /**
+       * Payment request that produced this payment, when applicable.
+       */
+      paymentRequest: Relationships.PaymentRequest;
+
       /**
        * Recipient party for this payment, when known.
        */
       recipient: Relationships.Recipient;
 
+      /**
+       * Recipient agent when the caller addressed an agent ID. Null otherwise, including
+       * when the recipient was addressed as an email, phone, or party ID.
+       */
+      recipientAgent: Relationships.RecipientAgent;
+
       /**
        * Party that initiated the payment
        */
@@ -188,6 +220,30 @@ export namespace PaymentCreateResponse {
     }
 
     export namespace Relationships {
+      /**
+       * Payment request that produced this payment, when applicable.
+       */
+      export interface PaymentRequest {
+        /**
+         * Related resource identifier
+         */
+        data: PaymentRequest.Data | null;
+      }
+
+      export namespace PaymentRequest {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'paymentRequest';
+        }
+      }
+
       /**
        * Recipient party for this payment, when known.
        */
@@ -208,7 +264,32 @@ export namespace PaymentCreateResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'party';
+        }
+      }
+
+      /**
+       * Recipient agent when the caller addressed an agent ID. Null otherwise, including
+       * when the recipient was addressed as an email, phone, or party ID.
+       */
+      export interface RecipientAgent {
+        /**
+         * Related resource identifier
+         */
+        data: RecipientAgent.Data | null;
+      }
+
+      export namespace RecipientAgent {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'agent';
         }
       }
 
@@ -232,7 +313,7 @@ export namespace PaymentCreateResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'party';
         }
       }
 
@@ -256,7 +337,7 @@ export namespace PaymentCreateResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'transaction';
         }
       }
     }
@@ -283,7 +364,7 @@ export namespace PaymentListResponse {
      */
     relationships: Data.Relationships;
 
-    type: string;
+    type: 'payment';
   }
 
   export namespace Data {
@@ -321,6 +402,7 @@ export namespace PaymentListResponse {
         | 'IN_REVIEW'
         | 'COMPLETED'
         | 'FAILED'
+        | 'RETURNED'
         | 'APPROVAL_DENIED'
         | 'CANCELLED';
 
@@ -334,11 +416,22 @@ export namespace PaymentListResponse {
      * Resource relationships
      */
     export interface Relationships {
+      /**
+       * Payment request that produced this payment, when applicable.
+       */
+      paymentRequest: Relationships.PaymentRequest;
+
       /**
        * Recipient party for this payment, when known.
        */
       recipient: Relationships.Recipient;
 
+      /**
+       * Recipient agent when the caller addressed an agent ID. Null otherwise, including
+       * when the recipient was addressed as an email, phone, or party ID.
+       */
+      recipientAgent: Relationships.RecipientAgent;
+
       /**
        * Party that initiated the payment
        */
@@ -351,6 +444,30 @@ export namespace PaymentListResponse {
     }
 
     export namespace Relationships {
+      /**
+       * Payment request that produced this payment, when applicable.
+       */
+      export interface PaymentRequest {
+        /**
+         * Related resource identifier
+         */
+        data: PaymentRequest.Data | null;
+      }
+
+      export namespace PaymentRequest {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'paymentRequest';
+        }
+      }
+
       /**
        * Recipient party for this payment, when known.
        */
@@ -371,7 +488,32 @@ export namespace PaymentListResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'party';
+        }
+      }
+
+      /**
+       * Recipient agent when the caller addressed an agent ID. Null otherwise, including
+       * when the recipient was addressed as an email, phone, or party ID.
+       */
+      export interface RecipientAgent {
+        /**
+         * Related resource identifier
+         */
+        data: RecipientAgent.Data | null;
+      }
+
+      export namespace RecipientAgent {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'agent';
         }
       }
 
@@ -395,7 +537,7 @@ export namespace PaymentListResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'party';
         }
       }
 
@@ -419,7 +561,7 @@ export namespace PaymentListResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'transaction';
         }
       }
     }
@@ -438,6 +580,228 @@ export namespace PaymentListResponse {
   }
 }
 
+export interface PaymentCancelResponse {
+  data: PaymentCancelResponse.Data;
+}
+
+export namespace PaymentCancelResponse {
+  export interface Data {
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
+    type: 'payment';
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * Amount in cents
+       */
+      amount: number;
+
+      /**
+       * When this payment was created
+       */
+      createdAt: string;
+
+      /**
+       * Currency code
+       */
+      currency: string;
+
+      /**
+       * Payment description
+       */
+      description: string | null;
+
+      /**
+       * Payment status
+       */
+      status:
+        | 'CREATED'
+        | 'PROCESSING'
+        | 'PENDING_CLAIM'
+        | 'IN_REVIEW'
+        | 'COMPLETED'
+        | 'FAILED'
+        | 'RETURNED'
+        | 'APPROVAL_DENIED'
+        | 'CANCELLED';
+
+      /**
+       * When this payment was last updated
+       */
+      updatedAt: string | null;
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Payment request that produced this payment, when applicable.
+       */
+      paymentRequest: Relationships.PaymentRequest;
+
+      /**
+       * Recipient party for this payment, when known.
+       */
+      recipient: Relationships.Recipient;
+
+      /**
+       * Recipient agent when the caller addressed an agent ID. Null otherwise, including
+       * when the recipient was addressed as an email, phone, or party ID.
+       */
+      recipientAgent: Relationships.RecipientAgent;
+
+      /**
+       * Party that initiated the payment
+       */
+      sender: Relationships.Sender;
+
+      /**
+       * Sender-side transaction row for this payment, when available.
+       */
+      transaction: Relationships.Transaction;
+    }
+
+    export namespace Relationships {
+      /**
+       * Payment request that produced this payment, when applicable.
+       */
+      export interface PaymentRequest {
+        /**
+         * Related resource identifier
+         */
+        data: PaymentRequest.Data | null;
+      }
+
+      export namespace PaymentRequest {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'paymentRequest';
+        }
+      }
+
+      /**
+       * Recipient party for this payment, when known.
+       */
+      export interface Recipient {
+        /**
+         * Related resource identifier
+         */
+        data: Recipient.Data | null;
+      }
+
+      export namespace Recipient {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'party';
+        }
+      }
+
+      /**
+       * Recipient agent when the caller addressed an agent ID. Null otherwise, including
+       * when the recipient was addressed as an email, phone, or party ID.
+       */
+      export interface RecipientAgent {
+        /**
+         * Related resource identifier
+         */
+        data: RecipientAgent.Data | null;
+      }
+
+      export namespace RecipientAgent {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'agent';
+        }
+      }
+
+      /**
+       * Party that initiated the payment
+       */
+      export interface Sender {
+        /**
+         * Related resource identifier
+         */
+        data: Sender.Data;
+      }
+
+      export namespace Sender {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'party';
+        }
+      }
+
+      /**
+       * Sender-side transaction row for this payment, when available.
+       */
+      export interface Transaction {
+        /**
+         * Related resource identifier
+         */
+        data: Transaction.Data | null;
+      }
+
+      export namespace Transaction {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'transaction';
+        }
+      }
+    }
+  }
+}
+
 export interface PaymentGetResponse {
   data: PaymentGetResponse.Data;
 }
@@ -456,7 +820,7 @@ export namespace PaymentGetResponse {
      */
     relationships: Data.Relationships;
 
-    type: string;
+    type: 'payment';
   }
 
   export namespace Data {
@@ -494,6 +858,7 @@ export namespace PaymentGetResponse {
         | 'IN_REVIEW'
         | 'COMPLETED'
         | 'FAILED'
+        | 'RETURNED'
         | 'APPROVAL_DENIED'
         | 'CANCELLED';
 
@@ -507,11 +872,22 @@ export namespace PaymentGetResponse {
      * Resource relationships
      */
     export interface Relationships {
+      /**
+       * Payment request that produced this payment, when applicable.
+       */
+      paymentRequest: Relationships.PaymentRequest;
+
       /**
        * Recipient party for this payment, when known.
        */
       recipient: Relationships.Recipient;
 
+      /**
+       * Recipient agent when the caller addressed an agent ID. Null otherwise, including
+       * when the recipient was addressed as an email, phone, or party ID.
+       */
+      recipientAgent: Relationships.RecipientAgent;
+
       /**
        * Party that initiated the payment
        */
@@ -524,6 +900,30 @@ export namespace PaymentGetResponse {
     }
 
     export namespace Relationships {
+      /**
+       * Payment request that produced this payment, when applicable.
+       */
+      export interface PaymentRequest {
+        /**
+         * Related resource identifier
+         */
+        data: PaymentRequest.Data | null;
+      }
+
+      export namespace PaymentRequest {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'paymentRequest';
+        }
+      }
+
       /**
        * Recipient party for this payment, when known.
        */
@@ -544,7 +944,32 @@ export namespace PaymentGetResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'party';
+        }
+      }
+
+      /**
+       * Recipient agent when the caller addressed an agent ID. Null otherwise, including
+       * when the recipient was addressed as an email, phone, or party ID.
+       */
+      export interface RecipientAgent {
+        /**
+         * Related resource identifier
+         */
+        data: RecipientAgent.Data | null;
+      }
+
+      export namespace RecipientAgent {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'agent';
         }
       }
 
@@ -568,7 +993,7 @@ export namespace PaymentGetResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'party';
         }
       }
 
@@ -592,7 +1017,7 @@ export namespace PaymentGetResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'transaction';
         }
       }
     }
@@ -609,7 +1034,11 @@ export interface PaymentCreateParams {
    * Body param: Recipient identifier. Provide exactly one typed email, phone, party
    * ID, or agent ID value.
    */
-  counterparty: PaymentCreateParams.UnionMember0 | PaymentCreateParams.UnionMember1;
+  counterparty:
+    | PaymentCreateParams.UnionMember0
+    | PaymentCreateParams.UnionMember1
+    | PaymentCreateParams.UnionMember2
+    | PaymentCreateParams.UnionMember3;
 
   /**
    * Header param: Unique key for idempotent request handling. If a request with the
@@ -617,6 +1046,16 @@ export interface PaymentCreateParams {
    */
   'Idempotency-Key': string;
 
+  /**
+   * Header param: Agent ID (agt_xxx) used for attribution and audit.
+   */
+  'X-Agent-ID': string;
+
+  /**
+   * Header param: Stable run, session, or conversation ID for agent observability.
+   */
+  'X-Instance-ID': string;
+
   /**
    * Body param: Currency code
    */
@@ -632,22 +1071,11 @@ export interface PaymentCreateParams {
    * Body param: Payment description. Maximum 500 characters.
    */
   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 namespace PaymentCreateParams {
   export interface UnionMember0 {
-    type: string;
+    type: 'email';
 
     /**
      * Email address
@@ -656,16 +1084,44 @@ export namespace PaymentCreateParams {
   }
 
   export interface UnionMember1 {
-    type: string;
+    type: 'phone';
 
     /**
      * Phone number in E.164 format
      */
     value: string;
   }
+
+  export interface UnionMember2 {
+    type: 'party_id';
+
+    /**
+     * Natural party ID (pty\_\*)
+     */
+    value: string;
+  }
+
+  export interface UnionMember3 {
+    type: 'agent_id';
+
+    /**
+     * Natural agent ID (agt\_\*)
+     */
+    value: string;
+  }
 }
 
 export interface PaymentListParams {
+  /**
+   * Header param: Agent ID (agt_xxx) used for attribution and audit.
+   */
+  'X-Agent-ID': string;
+
+  /**
+   * Header param: Stable run, session, or conversation ID for agent observability.
+   */
+  'X-Instance-ID': string;
+
   /**
    * Query param: Pagination cursor from previous response
    */
@@ -680,44 +1136,52 @@ export interface PaymentListParams {
    * Query param: Party ID for delegated payment lookup
    */
   partyId?: string;
+}
+
+export interface PaymentCancelParams {
+  /**
+   * Unique key for idempotent request handling. If a request with the same key was
+   * already processed, the original response is returned.
+   */
+  'Idempotency-Key': string;
 
   /**
-   * Header param: Agent ID (agt_xxx) identifying which agent is making the request.
+   * Agent ID (agt_xxx) used for attribution and audit.
    */
-  'X-Agent-ID'?: string;
+  'X-Agent-ID': string;
 
   /**
-   * Header param: Required when X-Agent-ID is present. Session or conversation ID
-   * for agent observability.
+   * Stable run, session, or conversation ID for agent observability.
    */
-  'X-Instance-ID'?: string;
+  'X-Instance-ID': string;
 }
 
 export interface PaymentGetParams {
   /**
-   * Query param: Party ID for delegated payment lookup
+   * Header param: Agent ID (agt_xxx) used for attribution and audit.
    */
-  partyId?: string;
+  'X-Agent-ID': string;
 
   /**
-   * Header param: Agent ID (agt_xxx) identifying which agent is making the request.
+   * Header param: Stable run, session, or conversation ID for agent observability.
    */
-  'X-Agent-ID'?: string;
+  'X-Instance-ID': string;
 
   /**
-   * Header param: Required when X-Agent-ID is present. Session or conversation ID
-   * for agent observability.
+   * Query param: Party ID for delegated payment lookup
    */
-  'X-Instance-ID'?: string;
+  partyId?: string;
 }
 
 export declare namespace Payments {
   export {
     type PaymentCreateResponse as PaymentCreateResponse,
     type PaymentListResponse as PaymentListResponse,
+    type PaymentCancelResponse as PaymentCancelResponse,
     type PaymentGetResponse as PaymentGetResponse,
     type PaymentCreateParams as PaymentCreateParams,
     type PaymentListParams as PaymentListParams,
+    type PaymentCancelParams as PaymentCancelParams,
     type PaymentGetParams as PaymentGetParams,
   };
 }