@naturalpay/sdk 0.3.0 → 0.4.0

package/src/resources/payments.ts

@@ -4,19 +4,23 @@ 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';
 
 /**
- * Payment and transaction operations
+ * Payment operations
  */
 export class Payments extends APIResource {
   /**
-   * Create a payment with delegation validation and limit enforcement.
+   * Create a payment.
    *
    * @example
    * ```ts
    * const payment = await client.payments.create({
    *   amount: 1,
-   *   counterparty: 'counterparty',
+   *   counterparty: {
+   *     type: 'type',
+   *     value: 'dev@stainless.com',
+   *   },
    *   'Idempotency-Key': 'Idempotency-Key',
    * });
    * ```
@@ -41,6 +45,61 @@ export class Payments extends APIResource {
       ]),
     });
   }
+
+  /**
+   * List payments initiated by the authenticated party.
+   *
+   * @example
+   * ```ts
+   * const payments = await client.payments.list();
+   * ```
+   */
+  list(
+    params: PaymentListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<PaymentListResponse> {
+    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID, ...query } = params ?? {};
+    return this._client.get('/payments', {
+      query,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Get a payment initiated by the authenticated party.
+   *
+   * @example
+   * ```ts
+   * const payment = await client.payments.get(
+   *   'pay_ecc2efdd09bd231a9ad9bd2aada37aa7',
+   * );
+   * ```
+   */
+  get(
+    paymentID: string,
+    params: PaymentGetParams | null | undefined = {},
+    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,
+      ]),
+    });
+  }
 }
 
 export interface PaymentCreateResponse {
@@ -49,9 +108,169 @@ export interface PaymentCreateResponse {
 
 export namespace PaymentCreateResponse {
   export interface Data {
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
+    type: string;
+  }
+
+  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'
+        | 'APPROVAL_DENIED'
+        | 'CANCELLED';
+
+      /**
+       * When this payment was last updated
+       */
+      updatedAt: string | null;
+    }
+
     /**
-     * Resource ID
+     * Resource relationships
      */
+    export interface Relationships {
+      /**
+       * Recipient party for this payment, when known.
+       */
+      recipient: Relationships.Recipient;
+
+      /**
+       * Party that initiated the payment
+       */
+      sender: Relationships.Sender;
+
+      /**
+       * Sender-side transaction row for this payment, when available.
+       */
+      transaction: Relationships.Transaction;
+    }
+
+    export namespace Relationships {
+      /**
+       * 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: string;
+        }
+      }
+
+      /**
+       * 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: string;
+        }
+      }
+
+      /**
+       * 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: string;
+        }
+      }
+    }
+  }
+}
+
+export interface PaymentListResponse {
+  data: Array<PaymentListResponse.Data>;
+
+  meta: PaymentListResponse.Meta;
+}
+
+export namespace PaymentListResponse {
+  export interface Data {
     id: string;
 
     /**
@@ -78,9 +297,177 @@ export namespace PaymentCreateResponse {
       amount: number;
 
       /**
-       * Claim link for unclaimed payments
+       * 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'
+        | 'APPROVAL_DENIED'
+        | 'CANCELLED';
+
+      /**
+       * When this payment was last updated
+       */
+      updatedAt: string | null;
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Recipient party for this payment, when known.
+       */
+      recipient: Relationships.Recipient;
+
+      /**
+       * Party that initiated the payment
+       */
+      sender: Relationships.Sender;
+
+      /**
+       * Sender-side transaction row for this payment, when available.
+       */
+      transaction: Relationships.Transaction;
+    }
+
+    export namespace Relationships {
+      /**
+       * 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: string;
+        }
+      }
+
+      /**
+       * 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: string;
+        }
+      }
+
+      /**
+       * 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: string;
+        }
+      }
+    }
+  }
+
+  export interface Meta {
+    pagination: Meta.Pagination;
+  }
+
+  export namespace Meta {
+    export interface Pagination {
+      hasMore: boolean;
+
+      nextCursor: string | null;
+    }
+  }
+}
+
+export interface PaymentGetResponse {
+  data: PaymentGetResponse.Data;
+}
+
+export namespace PaymentGetResponse {
+  export interface Data {
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
+    type: string;
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * Amount in cents
        */
-      claimLink: string | null;
+      amount: number;
 
       /**
        * When this payment was created
@@ -100,12 +487,20 @@ export namespace PaymentCreateResponse {
       /**
        * Payment status
        */
-      status: 'PROCESSING' | 'PENDING_CLAIM' | 'IN_REVIEW' | 'COMPLETED' | 'FAILED' | 'CANCELLED';
+      status:
+        | 'CREATED'
+        | 'PROCESSING'
+        | 'PENDING_CLAIM'
+        | 'IN_REVIEW'
+        | 'COMPLETED'
+        | 'FAILED'
+        | 'APPROVAL_DENIED'
+        | 'CANCELLED';
 
       /**
        * When this payment was last updated
        */
-      updatedAt: string;
+      updatedAt: string | null;
     }
 
     /**
@@ -113,28 +508,33 @@ export namespace PaymentCreateResponse {
      */
     export interface Relationships {
       /**
-       * Party receiving the payment
+       * Recipient party for this payment, when known.
+       */
+      recipient: Relationships.Recipient;
+
+      /**
+       * Party that initiated the payment
        */
-      counterparty: Relationships.Counterparty;
+      sender: Relationships.Sender;
 
       /**
-       * Party that made the payment
+       * Sender-side transaction row for this payment, when available.
        */
-      customerParty: Relationships.CustomerParty;
+      transaction: Relationships.Transaction;
     }
 
     export namespace Relationships {
       /**
-       * Party receiving the payment
+       * Recipient party for this payment, when known.
        */
-      export interface Counterparty {
+      export interface Recipient {
         /**
          * Related resource identifier
          */
-        data: Counterparty.Data | null;
+        data: Recipient.Data | null;
       }
 
-      export namespace Counterparty {
+      export namespace Recipient {
         /**
          * Related resource identifier
          */
@@ -149,16 +549,40 @@ export namespace PaymentCreateResponse {
       }
 
       /**
-       * Party that made the payment
+       * Party that initiated the payment
        */
-      export interface CustomerParty {
+      export interface Sender {
         /**
          * Related resource identifier
          */
-        data: CustomerParty.Data;
+        data: Sender.Data;
       }
 
-      export namespace CustomerParty {
+      export namespace Sender {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+
+      /**
+       * 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
          */
@@ -182,9 +606,10 @@ export interface PaymentCreateParams {
   amount: number;
 
   /**
-   * Body param: Recipient: party ID (pty*\*), agent ID (agt*\*), email, or phone
+   * Body param: Recipient identifier. Provide exactly one typed email, phone, party
+   * ID, or agent ID value.
    */
-  counterparty: string;
+  counterparty: PaymentCreateParams.UnionMember0 | PaymentCreateParams.UnionMember1;
 
   /**
    * Header param: Unique key for idempotent request handling. If a request with the
@@ -204,7 +629,7 @@ export interface PaymentCreateParams {
   customerPartyId?: string;
 
   /**
-   * Body param: Payment description
+   * Body param: Payment description. Maximum 500 characters.
    */
   description?: string;
 
@@ -220,9 +645,79 @@ export interface PaymentCreateParams {
   'X-Instance-ID'?: string;
 }
 
+export namespace PaymentCreateParams {
+  export interface UnionMember0 {
+    type: string;
+
+    /**
+     * Email address
+     */
+    value: string;
+  }
+
+  export interface UnionMember1 {
+    type: string;
+
+    /**
+     * Phone number in E.164 format
+     */
+    value: string;
+  }
+}
+
+export interface PaymentListParams {
+  /**
+   * Query param: Pagination cursor from previous response
+   */
+  cursor?: string;
+
+  /**
+   * Query param: Results per page
+   */
+  limit?: number;
+
+  /**
+   * Query param: Party ID for delegated payment lookup
+   */
+  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 PaymentGetParams {
+  /**
+   * Query param: Party ID for delegated payment lookup
+   */
+  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 declare namespace Payments {
   export {
     type PaymentCreateResponse as PaymentCreateResponse,
+    type PaymentListResponse as PaymentListResponse,
+    type PaymentGetResponse as PaymentGetResponse,
     type PaymentCreateParams as PaymentCreateParams,
+    type PaymentListParams as PaymentListParams,
+    type PaymentGetParams as PaymentGetParams,
   };
 }