@naturalpay/sdk 0.3.0 → 0.4.0

package/src/resources/escalations.ts

@@ -0,0 +1,1422 @@
+// 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';
+
+/**
+ * Payment approval escalation operations
+ */
+export class Escalations extends APIResource {
+  /**
+   * List escalations awaiting or recording approval decisions for your party.
+   *
+   * @example
+   * ```ts
+   * const escalations = await client.escalations.list();
+   * ```
+   */
+  list(
+    params: EscalationListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<EscalationListResponse> {
+    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID, ...query } = params ?? {};
+    return this._client.get('/escalations', {
+      query,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Approve the payment that exceeded approval limits.
+   *
+   * @example
+   * ```ts
+   * const response = await client.escalations.approve(
+   *   'apr_ecc2efdd09bd231a9ad9bd2aada37aa7',
+   *   { 'Idempotency-Key': 'Idempotency-Key' },
+   * );
+   * ```
+   */
+  approve(
+    escalationID: string,
+    params: EscalationApproveParams,
+    options?: RequestOptions,
+  ): APIPromise<EscalationApproveResponse> {
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'X-Agent-ID': xAgentID,
+      'X-Instance-ID': xInstanceID,
+    } = params;
+    return this._client.post(path`/escalations/${escalationID}/approve`, {
+      ...options,
+      headers: buildHeaders([
+        {
+          'Idempotency-Key': idempotencyKey,
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Deny the payment that exceeded approval limits.
+   *
+   * @example
+   * ```ts
+   * const response = await client.escalations.deny(
+   *   'apr_ecc2efdd09bd231a9ad9bd2aada37aa7',
+   *   { 'Idempotency-Key': 'Idempotency-Key' },
+   * );
+   * ```
+   */
+  deny(
+    escalationID: string,
+    params: EscalationDenyParams,
+    options?: RequestOptions,
+  ): APIPromise<EscalationDenyResponse> {
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'X-Agent-ID': xAgentID,
+      'X-Instance-ID': xInstanceID,
+      ...body
+    } = params;
+    return this._client.post(path`/escalations/${escalationID}/deny`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          'Idempotency-Key': idempotencyKey,
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Get details of a specific escalation by approval request ID.
+   *
+   * @example
+   * ```ts
+   * const escalation = await client.escalations.get(
+   *   'apr_ecc2efdd09bd231a9ad9bd2aada37aa7',
+   * );
+   * ```
+   */
+  get(
+    escalationID: string,
+    params: EscalationGetParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<EscalationGetResponse> {
+    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID } = params ?? {};
+    return this._client.get(path`/escalations/${escalationID}`, {
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export interface EscalationListResponse {
+  data: Array<EscalationListResponse.Data>;
+
+  meta: EscalationListResponse.Meta;
+}
+
+export namespace EscalationListResponse {
+  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 {
+      /**
+       * Agent ID that initiated the payment, if actor was an agent
+       */
+      agentId: string | null;
+
+      /**
+       * Payment amount in minor units (cents)
+       */
+      amountMinor: number;
+
+      /**
+       * Product-safe subject that caused the approval
+       */
+      approvalScope: Attributes.ApprovalScope;
+
+      /**
+       * All breached limits covered by this approval
+       */
+      breachedLimits: Array<Attributes.BreachedLimit>;
+
+      /**
+       * When approval was created
+       */
+      createdAt: string;
+
+      /**
+       * Currency code (e.g., USD)
+       */
+      currency: string;
+
+      /**
+       * Optional note supplied when denied
+       */
+      denialReason: string | null;
+
+      /**
+       * PROGRAM or CUSTOMER
+       */
+      evaluationTier: 'PROGRAM' | 'CUSTOMER';
+
+      /**
+       * Configured per-payment limit from the approval snapshot, in minor units
+       */
+      exceededLimitAmountMinor: number | null;
+
+      /**
+       * Limit currency from the approval snapshot
+       */
+      exceededLimitCurrency: string | null;
+
+      /**
+       * Money Movement Request ID
+       */
+      moneyMovementRequestId: string | null;
+
+      /**
+       * Recipient label to display in approval UI
+       */
+      recipientDisplayName: string | null;
+
+      /**
+       * Recipient email or other claim identifier when available
+       */
+      recipientIdentifier: string | null;
+
+      /**
+       * Recipient party display name (enriched from identity)
+       */
+      recipientPartyName: string | null;
+
+      /**
+       * When approval was resolved (approved/denied)
+       */
+      resolvedAt: string | null;
+
+      /**
+       * Party that resolved the approval
+       */
+      resolvedByPartyId: string | null;
+
+      /**
+       * Sender party display name (enriched from identity)
+       */
+      senderPartyName: string | null;
+
+      /**
+       * Approval status
+       */
+      status: 'PENDING' | 'APPROVED' | 'DENIED' | 'CANCELLED';
+
+      /**
+       * User-facing transaction ID (txn_xxx) derived from the money movement request
+       */
+      transactionId: string | null;
+    }
+
+    export namespace Attributes {
+      /**
+       * Product-safe subject that caused the approval
+       */
+      export interface ApprovalScope {
+        /**
+         * Scope subject ID, when available
+         */
+        id: string | null;
+
+        /**
+         * Product-safe approval scope type
+         */
+        type: 'PROGRAM' | 'PARTY' | 'AGENT_DELEGATION' | 'AGENT' | 'UNKNOWN';
+      }
+
+      export interface BreachedLimit {
+        /**
+         * Actual payment amount in minor units
+         */
+        actualAmountMinor: number;
+
+        /**
+         * Configured limit threshold in minor units
+         */
+        amountMinor: number;
+
+        /**
+         * Limit currency
+         */
+        currency: string;
+
+        /**
+         * Approval gate order evaluated for this policy
+         */
+        gateOrder: number;
+
+        /**
+         * Policy version evaluated for this approval
+         */
+        policyDbVersion: number | null;
+
+        /**
+         * Approval policy that was breached
+         */
+        policyId: string;
+
+        /**
+         * Scope of the breached policy
+         */
+        scope: BreachedLimit.Scope;
+      }
+
+      export namespace BreachedLimit {
+        /**
+         * Scope of the breached policy
+         */
+        export interface Scope {
+          /**
+           * Scope subject ID, when available
+           */
+          id: string | null;
+
+          /**
+           * Product-safe approval scope type
+           */
+          type: 'PROGRAM' | 'PARTY' | 'AGENT_DELEGATION' | 'AGENT' | 'UNKNOWN';
+        }
+      }
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Party who can approve/deny
+       */
+      approverParty: Relationships.ApproverParty;
+
+      /**
+       * Recipient party
+       */
+      recipientParty: Relationships.RecipientParty;
+
+      /**
+       * Sender party
+       */
+      senderParty: Relationships.SenderParty;
+    }
+
+    export namespace Relationships {
+      /**
+       * Party who can approve/deny
+       */
+      export interface ApproverParty {
+        /**
+         * Related resource identifier
+         */
+        data: ApproverParty.Data | null;
+      }
+
+      export namespace ApproverParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+
+      /**
+       * Recipient party
+       */
+      export interface RecipientParty {
+        /**
+         * Related resource identifier
+         */
+        data: RecipientParty.Data | null;
+      }
+
+      export namespace RecipientParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+
+      /**
+       * Sender party
+       */
+      export interface SenderParty {
+        /**
+         * Related resource identifier
+         */
+        data: SenderParty.Data | null;
+      }
+
+      export namespace SenderParty {
+        /**
+         * 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 EscalationApproveResponse {
+  data: EscalationApproveResponse.Data;
+}
+
+export namespace EscalationApproveResponse {
+  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 {
+      /**
+       * Agent ID that initiated the payment, if actor was an agent
+       */
+      agentId: string | null;
+
+      /**
+       * Payment amount in minor units (cents)
+       */
+      amountMinor: number;
+
+      /**
+       * Product-safe subject that caused the approval
+       */
+      approvalScope: Attributes.ApprovalScope;
+
+      /**
+       * All breached limits covered by this approval
+       */
+      breachedLimits: Array<Attributes.BreachedLimit>;
+
+      /**
+       * When approval was created
+       */
+      createdAt: string;
+
+      /**
+       * Currency code (e.g., USD)
+       */
+      currency: string;
+
+      /**
+       * Optional note supplied when denied
+       */
+      denialReason: string | null;
+
+      /**
+       * PROGRAM or CUSTOMER
+       */
+      evaluationTier: 'PROGRAM' | 'CUSTOMER';
+
+      /**
+       * Configured per-payment limit from the approval snapshot, in minor units
+       */
+      exceededLimitAmountMinor: number | null;
+
+      /**
+       * Limit currency from the approval snapshot
+       */
+      exceededLimitCurrency: string | null;
+
+      /**
+       * Money Movement Request ID
+       */
+      moneyMovementRequestId: string | null;
+
+      /**
+       * Recipient label to display in approval UI
+       */
+      recipientDisplayName: string | null;
+
+      /**
+       * Recipient email or other claim identifier when available
+       */
+      recipientIdentifier: string | null;
+
+      /**
+       * Recipient party display name (enriched from identity)
+       */
+      recipientPartyName: string | null;
+
+      /**
+       * When approval was resolved (approved/denied)
+       */
+      resolvedAt: string | null;
+
+      /**
+       * Party that resolved the approval
+       */
+      resolvedByPartyId: string | null;
+
+      /**
+       * Sender party display name (enriched from identity)
+       */
+      senderPartyName: string | null;
+
+      /**
+       * Approval status
+       */
+      status: 'PENDING' | 'APPROVED' | 'DENIED' | 'CANCELLED';
+
+      /**
+       * User-facing transaction ID (txn_xxx) derived from the money movement request
+       */
+      transactionId: string | null;
+    }
+
+    export namespace Attributes {
+      /**
+       * Product-safe subject that caused the approval
+       */
+      export interface ApprovalScope {
+        /**
+         * Scope subject ID, when available
+         */
+        id: string | null;
+
+        /**
+         * Product-safe approval scope type
+         */
+        type: 'PROGRAM' | 'PARTY' | 'AGENT_DELEGATION' | 'AGENT' | 'UNKNOWN';
+      }
+
+      export interface BreachedLimit {
+        /**
+         * Actual payment amount in minor units
+         */
+        actualAmountMinor: number;
+
+        /**
+         * Configured limit threshold in minor units
+         */
+        amountMinor: number;
+
+        /**
+         * Limit currency
+         */
+        currency: string;
+
+        /**
+         * Approval gate order evaluated for this policy
+         */
+        gateOrder: number;
+
+        /**
+         * Policy version evaluated for this approval
+         */
+        policyDbVersion: number | null;
+
+        /**
+         * Approval policy that was breached
+         */
+        policyId: string;
+
+        /**
+         * Scope of the breached policy
+         */
+        scope: BreachedLimit.Scope;
+      }
+
+      export namespace BreachedLimit {
+        /**
+         * Scope of the breached policy
+         */
+        export interface Scope {
+          /**
+           * Scope subject ID, when available
+           */
+          id: string | null;
+
+          /**
+           * Product-safe approval scope type
+           */
+          type: 'PROGRAM' | 'PARTY' | 'AGENT_DELEGATION' | 'AGENT' | 'UNKNOWN';
+        }
+      }
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Party who can approve/deny
+       */
+      approverParty: Relationships.ApproverParty;
+
+      /**
+       * Recipient party
+       */
+      recipientParty: Relationships.RecipientParty;
+
+      /**
+       * Sender party
+       */
+      senderParty: Relationships.SenderParty;
+    }
+
+    export namespace Relationships {
+      /**
+       * Party who can approve/deny
+       */
+      export interface ApproverParty {
+        /**
+         * Related resource identifier
+         */
+        data: ApproverParty.Data | null;
+      }
+
+      export namespace ApproverParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+
+      /**
+       * Recipient party
+       */
+      export interface RecipientParty {
+        /**
+         * Related resource identifier
+         */
+        data: RecipientParty.Data | null;
+      }
+
+      export namespace RecipientParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+
+      /**
+       * Sender party
+       */
+      export interface SenderParty {
+        /**
+         * Related resource identifier
+         */
+        data: SenderParty.Data | null;
+      }
+
+      export namespace SenderParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+    }
+  }
+}
+
+export interface EscalationDenyResponse {
+  data: EscalationDenyResponse.Data;
+}
+
+export namespace EscalationDenyResponse {
+  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 {
+      /**
+       * Agent ID that initiated the payment, if actor was an agent
+       */
+      agentId: string | null;
+
+      /**
+       * Payment amount in minor units (cents)
+       */
+      amountMinor: number;
+
+      /**
+       * Product-safe subject that caused the approval
+       */
+      approvalScope: Attributes.ApprovalScope;
+
+      /**
+       * All breached limits covered by this approval
+       */
+      breachedLimits: Array<Attributes.BreachedLimit>;
+
+      /**
+       * When approval was created
+       */
+      createdAt: string;
+
+      /**
+       * Currency code (e.g., USD)
+       */
+      currency: string;
+
+      /**
+       * Optional note supplied when denied
+       */
+      denialReason: string | null;
+
+      /**
+       * PROGRAM or CUSTOMER
+       */
+      evaluationTier: 'PROGRAM' | 'CUSTOMER';
+
+      /**
+       * Configured per-payment limit from the approval snapshot, in minor units
+       */
+      exceededLimitAmountMinor: number | null;
+
+      /**
+       * Limit currency from the approval snapshot
+       */
+      exceededLimitCurrency: string | null;
+
+      /**
+       * Money Movement Request ID
+       */
+      moneyMovementRequestId: string | null;
+
+      /**
+       * Recipient label to display in approval UI
+       */
+      recipientDisplayName: string | null;
+
+      /**
+       * Recipient email or other claim identifier when available
+       */
+      recipientIdentifier: string | null;
+
+      /**
+       * Recipient party display name (enriched from identity)
+       */
+      recipientPartyName: string | null;
+
+      /**
+       * When approval was resolved (approved/denied)
+       */
+      resolvedAt: string | null;
+
+      /**
+       * Party that resolved the approval
+       */
+      resolvedByPartyId: string | null;
+
+      /**
+       * Sender party display name (enriched from identity)
+       */
+      senderPartyName: string | null;
+
+      /**
+       * Approval status
+       */
+      status: 'PENDING' | 'APPROVED' | 'DENIED' | 'CANCELLED';
+
+      /**
+       * User-facing transaction ID (txn_xxx) derived from the money movement request
+       */
+      transactionId: string | null;
+    }
+
+    export namespace Attributes {
+      /**
+       * Product-safe subject that caused the approval
+       */
+      export interface ApprovalScope {
+        /**
+         * Scope subject ID, when available
+         */
+        id: string | null;
+
+        /**
+         * Product-safe approval scope type
+         */
+        type: 'PROGRAM' | 'PARTY' | 'AGENT_DELEGATION' | 'AGENT' | 'UNKNOWN';
+      }
+
+      export interface BreachedLimit {
+        /**
+         * Actual payment amount in minor units
+         */
+        actualAmountMinor: number;
+
+        /**
+         * Configured limit threshold in minor units
+         */
+        amountMinor: number;
+
+        /**
+         * Limit currency
+         */
+        currency: string;
+
+        /**
+         * Approval gate order evaluated for this policy
+         */
+        gateOrder: number;
+
+        /**
+         * Policy version evaluated for this approval
+         */
+        policyDbVersion: number | null;
+
+        /**
+         * Approval policy that was breached
+         */
+        policyId: string;
+
+        /**
+         * Scope of the breached policy
+         */
+        scope: BreachedLimit.Scope;
+      }
+
+      export namespace BreachedLimit {
+        /**
+         * Scope of the breached policy
+         */
+        export interface Scope {
+          /**
+           * Scope subject ID, when available
+           */
+          id: string | null;
+
+          /**
+           * Product-safe approval scope type
+           */
+          type: 'PROGRAM' | 'PARTY' | 'AGENT_DELEGATION' | 'AGENT' | 'UNKNOWN';
+        }
+      }
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Party who can approve/deny
+       */
+      approverParty: Relationships.ApproverParty;
+
+      /**
+       * Recipient party
+       */
+      recipientParty: Relationships.RecipientParty;
+
+      /**
+       * Sender party
+       */
+      senderParty: Relationships.SenderParty;
+    }
+
+    export namespace Relationships {
+      /**
+       * Party who can approve/deny
+       */
+      export interface ApproverParty {
+        /**
+         * Related resource identifier
+         */
+        data: ApproverParty.Data | null;
+      }
+
+      export namespace ApproverParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+
+      /**
+       * Recipient party
+       */
+      export interface RecipientParty {
+        /**
+         * Related resource identifier
+         */
+        data: RecipientParty.Data | null;
+      }
+
+      export namespace RecipientParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+
+      /**
+       * Sender party
+       */
+      export interface SenderParty {
+        /**
+         * Related resource identifier
+         */
+        data: SenderParty.Data | null;
+      }
+
+      export namespace SenderParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+    }
+  }
+}
+
+export interface EscalationGetResponse {
+  data: EscalationGetResponse.Data;
+}
+
+export namespace EscalationGetResponse {
+  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 {
+      /**
+       * Agent ID that initiated the payment, if actor was an agent
+       */
+      agentId: string | null;
+
+      /**
+       * Payment amount in minor units (cents)
+       */
+      amountMinor: number;
+
+      /**
+       * Product-safe subject that caused the approval
+       */
+      approvalScope: Attributes.ApprovalScope;
+
+      /**
+       * All breached limits covered by this approval
+       */
+      breachedLimits: Array<Attributes.BreachedLimit>;
+
+      /**
+       * When approval was created
+       */
+      createdAt: string;
+
+      /**
+       * Currency code (e.g., USD)
+       */
+      currency: string;
+
+      /**
+       * Optional note supplied when denied
+       */
+      denialReason: string | null;
+
+      /**
+       * PROGRAM or CUSTOMER
+       */
+      evaluationTier: 'PROGRAM' | 'CUSTOMER';
+
+      /**
+       * Configured per-payment limit from the approval snapshot, in minor units
+       */
+      exceededLimitAmountMinor: number | null;
+
+      /**
+       * Limit currency from the approval snapshot
+       */
+      exceededLimitCurrency: string | null;
+
+      /**
+       * Money Movement Request ID
+       */
+      moneyMovementRequestId: string | null;
+
+      /**
+       * Recipient label to display in approval UI
+       */
+      recipientDisplayName: string | null;
+
+      /**
+       * Recipient email or other claim identifier when available
+       */
+      recipientIdentifier: string | null;
+
+      /**
+       * Recipient party display name (enriched from identity)
+       */
+      recipientPartyName: string | null;
+
+      /**
+       * When approval was resolved (approved/denied)
+       */
+      resolvedAt: string | null;
+
+      /**
+       * Party that resolved the approval
+       */
+      resolvedByPartyId: string | null;
+
+      /**
+       * Sender party display name (enriched from identity)
+       */
+      senderPartyName: string | null;
+
+      /**
+       * Approval status
+       */
+      status: 'PENDING' | 'APPROVED' | 'DENIED' | 'CANCELLED';
+
+      /**
+       * User-facing transaction ID (txn_xxx) derived from the money movement request
+       */
+      transactionId: string | null;
+    }
+
+    export namespace Attributes {
+      /**
+       * Product-safe subject that caused the approval
+       */
+      export interface ApprovalScope {
+        /**
+         * Scope subject ID, when available
+         */
+        id: string | null;
+
+        /**
+         * Product-safe approval scope type
+         */
+        type: 'PROGRAM' | 'PARTY' | 'AGENT_DELEGATION' | 'AGENT' | 'UNKNOWN';
+      }
+
+      export interface BreachedLimit {
+        /**
+         * Actual payment amount in minor units
+         */
+        actualAmountMinor: number;
+
+        /**
+         * Configured limit threshold in minor units
+         */
+        amountMinor: number;
+
+        /**
+         * Limit currency
+         */
+        currency: string;
+
+        /**
+         * Approval gate order evaluated for this policy
+         */
+        gateOrder: number;
+
+        /**
+         * Policy version evaluated for this approval
+         */
+        policyDbVersion: number | null;
+
+        /**
+         * Approval policy that was breached
+         */
+        policyId: string;
+
+        /**
+         * Scope of the breached policy
+         */
+        scope: BreachedLimit.Scope;
+      }
+
+      export namespace BreachedLimit {
+        /**
+         * Scope of the breached policy
+         */
+        export interface Scope {
+          /**
+           * Scope subject ID, when available
+           */
+          id: string | null;
+
+          /**
+           * Product-safe approval scope type
+           */
+          type: 'PROGRAM' | 'PARTY' | 'AGENT_DELEGATION' | 'AGENT' | 'UNKNOWN';
+        }
+      }
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Party who can approve/deny
+       */
+      approverParty: Relationships.ApproverParty;
+
+      /**
+       * Recipient party
+       */
+      recipientParty: Relationships.RecipientParty;
+
+      /**
+       * Sender party
+       */
+      senderParty: Relationships.SenderParty;
+    }
+
+    export namespace Relationships {
+      /**
+       * Party who can approve/deny
+       */
+      export interface ApproverParty {
+        /**
+         * Related resource identifier
+         */
+        data: ApproverParty.Data | null;
+      }
+
+      export namespace ApproverParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+
+      /**
+       * Recipient party
+       */
+      export interface RecipientParty {
+        /**
+         * Related resource identifier
+         */
+        data: RecipientParty.Data | null;
+      }
+
+      export namespace RecipientParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+
+      /**
+       * Sender party
+       */
+      export interface SenderParty {
+        /**
+         * Related resource identifier
+         */
+        data: SenderParty.Data | null;
+      }
+
+      export namespace SenderParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+    }
+  }
+}
+
+export interface EscalationListParams {
+  /**
+   * Query param: Maximum number to return
+   */
+  limit?: number;
+
+  /**
+   * Query param: Approval status to list. Defaults to pending approvals.
+   */
+  status?: 'PENDING' | 'APPROVED' | 'DENIED' | 'CANCELLED';
+
+  /**
+   * 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 EscalationApproveParams {
+  /**
+   * 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.
+   */
+  'X-Agent-ID'?: string;
+
+  /**
+   * Required when X-Agent-ID is present. Session or conversation ID for agent
+   * observability.
+   */
+  'X-Instance-ID'?: string;
+}
+
+export interface EscalationDenyParams {
+  /**
+   * 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: Reason for denial (optional)
+   */
+  reason?: 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 EscalationGetParams {
+  /**
+   * 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 Escalations {
+  export {
+    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,
+  };
+}