@naturalpay/sdk 0.2.1 → 0.3.0

package/resources/webhooks.d.mts

@@ -0,0 +1,775 @@
+import { APIResource } from "../core/resource.mjs";
+import { APIPromise } from "../core/api-promise.mjs";
+import { RequestOptions } from "../internal/request-options.mjs";
+/**
+ * Webhook endpoint management
+ */
+export declare class Webhooks extends APIResource {
+    /**
+     * Create a new webhook endpoint. The signing secret is returned only once.
+     *
+     * @example
+     * ```ts
+     * const webhook = await client.webhooks.create({
+     *   enabledEvents: ['*'],
+     *   url: 'https://example.com',
+     *   'Idempotency-Key': 'Idempotency-Key',
+     * });
+     * ```
+     */
+    create(params: WebhookCreateParams, options?: RequestOptions): APIPromise<WebhookCreateResponse>;
+    /**
+     * Partially update a webhook endpoint.
+     *
+     * @example
+     * ```ts
+     * const webhook = await client.webhooks.update('webhookId', {
+     *   'Idempotency-Key': 'Idempotency-Key',
+     * });
+     * ```
+     */
+    update(webhookID: string, params: WebhookUpdateParams, options?: RequestOptions): APIPromise<WebhookUpdateResponse>;
+    /**
+     * List webhook endpoints for the authenticated party.
+     *
+     * @example
+     * ```ts
+     * const webhooks = await client.webhooks.list();
+     * ```
+     */
+    list(params?: WebhookListParams | null | undefined, options?: RequestOptions): APIPromise<WebhookListResponse>;
+    /**
+     * Get details of a specific webhook endpoint.
+     *
+     * @example
+     * ```ts
+     * const webhook = await client.webhooks.get('webhookId');
+     * ```
+     */
+    get(webhookID: string, params?: WebhookGetParams | null | undefined, options?: RequestOptions): APIPromise<WebhookGetResponse>;
+    /**
+     * Soft-delete a webhook endpoint.
+     *
+     * @example
+     * ```ts
+     * const webhook = await client.webhooks.remove('webhookId', {
+     *   'Idempotency-Key': 'Idempotency-Key',
+     * });
+     * ```
+     */
+    remove(webhookID: string, params: WebhookRemoveParams, options?: RequestOptions): APIPromise<WebhookRemoveResponse>;
+    /**
+     * Generate a new signing secret. The previous secret remains valid for the
+     * specified grace period. Requires Idempotency-Key header.
+     *
+     * @example
+     * ```ts
+     * const response = await client.webhooks.rotateSecret(
+     *   'webhookId',
+     *   {
+     *     expiresInSeconds: 0,
+     *     'Idempotency-Key': 'Idempotency-Key',
+     *   },
+     * );
+     * ```
+     */
+    rotateSecret(webhookID: string, params: WebhookRotateSecretParams, options?: RequestOptions): APIPromise<WebhookRotateSecretResponse>;
+}
+export interface WebhookCreateResponse {
+    data: WebhookCreateResponse.Data;
+}
+export declare namespace WebhookCreateResponse {
+    interface Data {
+        /**
+         * Resource ID (whk_xxx)
+         */
+        id: string;
+        /**
+         * Resource attributes
+         */
+        attributes: Data.Attributes;
+        /**
+         * Resource relationships
+         */
+        relationships: Data.Relationships;
+        /**
+         * Resource type
+         */
+        type: string;
+    }
+    namespace Data {
+        /**
+         * Resource attributes
+         */
+        interface Attributes {
+            /**
+             * Creation timestamp (ISO 8601)
+             */
+            createdAt: string;
+            /**
+             * Human-readable description
+             */
+            description: string;
+            /**
+             * Event types this webhook listens to
+             */
+            enabledEvents: Array<'*' | 'party.updated' | 'party.delegation_granted' | 'wallet.created' | 'external_account.connected' | 'agent_delegation_invitation.created' | 'agent_delegation_invitation.accepted' | 'agent_delegation_invitation.declined' | 'agent_delegation_invitation.cancelled' | 'agent_delegation.revoked' | 'delegation.activated' | 'delegation.revoked' | 'deposit.created' | 'deposit.completed' | 'deposit.failed' | 'deposit.returned' | 'withdrawal.created' | 'withdrawal.completed' | 'withdrawal.failed' | 'withdrawal.returned' | 'payment.created' | 'payment.completed' | 'payment.failed' | 'payment_request.created' | 'payment_request.completed' | 'payment_request.failed' | 'payment_request.returned'>;
+            /**
+             * Webhook signing secret (shown only once — store securely!)
+             */
+            signingSecret: string;
+            /**
+             * Webhook status
+             */
+            status: 'ENABLED' | 'DISABLED';
+            /**
+             * Custom metadata tags
+             */
+            tags: {
+                [key: string]: string;
+            };
+            /**
+             * Last update timestamp (ISO 8601)
+             */
+            updatedAt: string;
+            /**
+             * Webhook endpoint URL
+             */
+            url: string;
+        }
+        /**
+         * Resource relationships
+         */
+        interface Relationships {
+            /**
+             * Party that owns the webhook
+             */
+            party: Relationships.Party;
+        }
+        namespace Relationships {
+            /**
+             * Party that owns the webhook
+             */
+            interface Party {
+                /**
+                 * Related resource identifier
+                 */
+                data: Party.Data;
+            }
+            namespace Party {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: string;
+                }
+            }
+        }
+    }
+}
+export interface WebhookUpdateResponse {
+    data: WebhookUpdateResponse.Data;
+}
+export declare namespace WebhookUpdateResponse {
+    interface Data {
+        /**
+         * Resource ID (whk_xxx)
+         */
+        id: string;
+        /**
+         * Resource attributes
+         */
+        attributes: Data.Attributes;
+        /**
+         * Resource relationships
+         */
+        relationships: Data.Relationships;
+        /**
+         * Resource type
+         */
+        type: string;
+    }
+    namespace Data {
+        /**
+         * Resource attributes
+         */
+        interface Attributes {
+            /**
+             * Creation timestamp (ISO 8601)
+             */
+            createdAt: string;
+            /**
+             * Human-readable description
+             */
+            description: string;
+            /**
+             * Event types this webhook listens to
+             */
+            enabledEvents: Array<'*' | 'party.updated' | 'party.delegation_granted' | 'wallet.created' | 'external_account.connected' | 'agent_delegation_invitation.created' | 'agent_delegation_invitation.accepted' | 'agent_delegation_invitation.declined' | 'agent_delegation_invitation.cancelled' | 'agent_delegation.revoked' | 'delegation.activated' | 'delegation.revoked' | 'deposit.created' | 'deposit.completed' | 'deposit.failed' | 'deposit.returned' | 'withdrawal.created' | 'withdrawal.completed' | 'withdrawal.failed' | 'withdrawal.returned' | 'payment.created' | 'payment.completed' | 'payment.failed' | 'payment_request.created' | 'payment_request.completed' | 'payment_request.failed' | 'payment_request.returned'>;
+            /**
+             * Webhook status
+             */
+            status: 'ENABLED' | 'DISABLED';
+            /**
+             * Custom metadata tags
+             */
+            tags: {
+                [key: string]: string;
+            };
+            /**
+             * Last update timestamp (ISO 8601)
+             */
+            updatedAt: string;
+            /**
+             * Webhook endpoint URL
+             */
+            url: string;
+        }
+        /**
+         * Resource relationships
+         */
+        interface Relationships {
+            /**
+             * Party that owns the webhook
+             */
+            party: Relationships.Party;
+        }
+        namespace Relationships {
+            /**
+             * Party that owns the webhook
+             */
+            interface Party {
+                /**
+                 * Related resource identifier
+                 */
+                data: Party.Data;
+            }
+            namespace Party {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: string;
+                }
+            }
+        }
+    }
+}
+export interface WebhookListResponse {
+    data: Array<WebhookListResponse.Data>;
+    meta: WebhookListResponse.Meta;
+}
+export declare namespace WebhookListResponse {
+    interface Data {
+        /**
+         * Resource ID (whk_xxx)
+         */
+        id: string;
+        /**
+         * Resource attributes
+         */
+        attributes: Data.Attributes;
+        /**
+         * Resource relationships
+         */
+        relationships: Data.Relationships;
+        /**
+         * Resource type
+         */
+        type: string;
+    }
+    namespace Data {
+        /**
+         * Resource attributes
+         */
+        interface Attributes {
+            /**
+             * Creation timestamp (ISO 8601)
+             */
+            createdAt: string;
+            /**
+             * Human-readable description
+             */
+            description: string;
+            /**
+             * Event types this webhook listens to
+             */
+            enabledEvents: Array<'*' | 'party.updated' | 'party.delegation_granted' | 'wallet.created' | 'external_account.connected' | 'agent_delegation_invitation.created' | 'agent_delegation_invitation.accepted' | 'agent_delegation_invitation.declined' | 'agent_delegation_invitation.cancelled' | 'agent_delegation.revoked' | 'delegation.activated' | 'delegation.revoked' | 'deposit.created' | 'deposit.completed' | 'deposit.failed' | 'deposit.returned' | 'withdrawal.created' | 'withdrawal.completed' | 'withdrawal.failed' | 'withdrawal.returned' | 'payment.created' | 'payment.completed' | 'payment.failed' | 'payment_request.created' | 'payment_request.completed' | 'payment_request.failed' | 'payment_request.returned'>;
+            /**
+             * Webhook status
+             */
+            status: 'ENABLED' | 'DISABLED';
+            /**
+             * Custom metadata tags
+             */
+            tags: {
+                [key: string]: string;
+            };
+            /**
+             * Last update timestamp (ISO 8601)
+             */
+            updatedAt: string;
+            /**
+             * Webhook endpoint URL
+             */
+            url: string;
+        }
+        /**
+         * Resource relationships
+         */
+        interface Relationships {
+            /**
+             * Party that owns the webhook
+             */
+            party: Relationships.Party;
+        }
+        namespace Relationships {
+            /**
+             * Party that owns the webhook
+             */
+            interface Party {
+                /**
+                 * Related resource identifier
+                 */
+                data: Party.Data;
+            }
+            namespace Party {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: string;
+                }
+            }
+        }
+    }
+    interface Meta {
+        pagination: Meta.Pagination;
+    }
+    namespace Meta {
+        interface Pagination {
+            hasMore: boolean;
+            nextCursor: string | null;
+        }
+    }
+}
+export interface WebhookGetResponse {
+    data: WebhookGetResponse.Data;
+}
+export declare namespace WebhookGetResponse {
+    interface Data {
+        /**
+         * Resource ID (whk_xxx)
+         */
+        id: string;
+        /**
+         * Resource attributes
+         */
+        attributes: Data.Attributes;
+        /**
+         * Resource relationships
+         */
+        relationships: Data.Relationships;
+        /**
+         * Resource type
+         */
+        type: string;
+    }
+    namespace Data {
+        /**
+         * Resource attributes
+         */
+        interface Attributes {
+            /**
+             * Creation timestamp (ISO 8601)
+             */
+            createdAt: string;
+            /**
+             * Human-readable description
+             */
+            description: string;
+            /**
+             * Event types this webhook listens to
+             */
+            enabledEvents: Array<'*' | 'party.updated' | 'party.delegation_granted' | 'wallet.created' | 'external_account.connected' | 'agent_delegation_invitation.created' | 'agent_delegation_invitation.accepted' | 'agent_delegation_invitation.declined' | 'agent_delegation_invitation.cancelled' | 'agent_delegation.revoked' | 'delegation.activated' | 'delegation.revoked' | 'deposit.created' | 'deposit.completed' | 'deposit.failed' | 'deposit.returned' | 'withdrawal.created' | 'withdrawal.completed' | 'withdrawal.failed' | 'withdrawal.returned' | 'payment.created' | 'payment.completed' | 'payment.failed' | 'payment_request.created' | 'payment_request.completed' | 'payment_request.failed' | 'payment_request.returned'>;
+            /**
+             * Webhook status
+             */
+            status: 'ENABLED' | 'DISABLED';
+            /**
+             * Custom metadata tags
+             */
+            tags: {
+                [key: string]: string;
+            };
+            /**
+             * Last update timestamp (ISO 8601)
+             */
+            updatedAt: string;
+            /**
+             * Webhook endpoint URL
+             */
+            url: string;
+        }
+        /**
+         * Resource relationships
+         */
+        interface Relationships {
+            /**
+             * Party that owns the webhook
+             */
+            party: Relationships.Party;
+        }
+        namespace Relationships {
+            /**
+             * Party that owns the webhook
+             */
+            interface Party {
+                /**
+                 * Related resource identifier
+                 */
+                data: Party.Data;
+            }
+            namespace Party {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: string;
+                }
+            }
+        }
+    }
+}
+export interface WebhookRemoveResponse {
+    data: WebhookRemoveResponse.Data;
+    meta: WebhookRemoveResponse.Meta;
+}
+export declare namespace WebhookRemoveResponse {
+    interface Data {
+        /**
+         * Resource ID (whk_xxx)
+         */
+        id: string;
+        /**
+         * Resource attributes
+         */
+        attributes: Data.Attributes;
+        /**
+         * Resource relationships
+         */
+        relationships: Data.Relationships;
+        /**
+         * Resource type
+         */
+        type: string;
+    }
+    namespace Data {
+        /**
+         * Resource attributes
+         */
+        interface Attributes {
+            /**
+             * Creation timestamp (ISO 8601)
+             */
+            createdAt: string;
+            /**
+             * Human-readable description
+             */
+            description: string;
+            /**
+             * Event types this webhook listens to
+             */
+            enabledEvents: Array<'*' | 'party.updated' | 'party.delegation_granted' | 'wallet.created' | 'external_account.connected' | 'agent_delegation_invitation.created' | 'agent_delegation_invitation.accepted' | 'agent_delegation_invitation.declined' | 'agent_delegation_invitation.cancelled' | 'agent_delegation.revoked' | 'delegation.activated' | 'delegation.revoked' | 'deposit.created' | 'deposit.completed' | 'deposit.failed' | 'deposit.returned' | 'withdrawal.created' | 'withdrawal.completed' | 'withdrawal.failed' | 'withdrawal.returned' | 'payment.created' | 'payment.completed' | 'payment.failed' | 'payment_request.created' | 'payment_request.completed' | 'payment_request.failed' | 'payment_request.returned'>;
+            /**
+             * Webhook status
+             */
+            status: 'ENABLED' | 'DISABLED';
+            /**
+             * Custom metadata tags
+             */
+            tags: {
+                [key: string]: string;
+            };
+            /**
+             * Last update timestamp (ISO 8601)
+             */
+            updatedAt: string;
+            /**
+             * Webhook endpoint URL
+             */
+            url: string;
+        }
+        /**
+         * Resource relationships
+         */
+        interface Relationships {
+            /**
+             * Party that owns the webhook
+             */
+            party: Relationships.Party;
+        }
+        namespace Relationships {
+            /**
+             * Party that owns the webhook
+             */
+            interface Party {
+                /**
+                 * Related resource identifier
+                 */
+                data: Party.Data;
+            }
+            namespace Party {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: string;
+                }
+            }
+        }
+    }
+    interface Meta {
+        /**
+         * Indicates the resource was deleted
+         */
+        deleted: true;
+    }
+}
+export interface WebhookRotateSecretResponse {
+    data: WebhookRotateSecretResponse.Data;
+}
+export declare namespace WebhookRotateSecretResponse {
+    interface Data {
+        /**
+         * Resource ID (whk_xxx)
+         */
+        id: string;
+        /**
+         * Resource attributes
+         */
+        attributes: Data.Attributes;
+        /**
+         * Resource relationships
+         */
+        relationships: Data.Relationships;
+        /**
+         * Resource type
+         */
+        type: string;
+    }
+    namespace Data {
+        /**
+         * Resource attributes
+         */
+        interface Attributes {
+            /**
+             * When the previous secret expires (null if immediate cutover)
+             */
+            previousSecretExpiresAt: string | null;
+            /**
+             * New webhook signing secret (shown only once — store securely!)
+             */
+            signingSecret: string;
+        }
+        /**
+         * Resource relationships
+         */
+        interface Relationships {
+            /**
+             * Party that owns the webhook
+             */
+            party: Relationships.Party;
+        }
+        namespace Relationships {
+            /**
+             * Party that owns the webhook
+             */
+            interface Party {
+                /**
+                 * Related resource identifier
+                 */
+                data: Party.Data;
+            }
+            namespace Party {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: string;
+                }
+            }
+        }
+    }
+}
+export interface WebhookCreateParams {
+    /**
+     * Body param: Event types to subscribe to
+     */
+    enabledEvents: Array<'*' | 'party.updated' | 'party.delegation_granted' | 'wallet.created' | 'external_account.connected' | 'agent_delegation_invitation.created' | 'agent_delegation_invitation.accepted' | 'agent_delegation_invitation.declined' | 'agent_delegation_invitation.cancelled' | 'agent_delegation.revoked' | 'delegation.activated' | 'delegation.revoked' | 'deposit.created' | 'deposit.completed' | 'deposit.failed' | 'deposit.returned' | 'withdrawal.created' | 'withdrawal.completed' | 'withdrawal.failed' | 'withdrawal.returned' | 'payment.created' | 'payment.completed' | 'payment.failed' | 'payment_request.created' | 'payment_request.completed' | 'payment_request.failed' | 'payment_request.returned'>;
+    /**
+     * Body param: Webhook endpoint URL
+     */
+    url: string;
+    /**
+     * 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: Human-readable description
+     */
+    description?: string;
+    /**
+     * Body param: Custom metadata tags
+     */
+    tags?: {
+        [key: string]: 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 WebhookUpdateParams {
+    /**
+     * 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: New description
+     */
+    description?: string;
+    /**
+     * Body param: Event types to subscribe to
+     */
+    enabledEvents?: Array<'*' | 'party.updated' | 'party.delegation_granted' | 'wallet.created' | 'external_account.connected' | 'agent_delegation_invitation.created' | 'agent_delegation_invitation.accepted' | 'agent_delegation_invitation.declined' | 'agent_delegation_invitation.cancelled' | 'agent_delegation.revoked' | 'delegation.activated' | 'delegation.revoked' | 'deposit.created' | 'deposit.completed' | 'deposit.failed' | 'deposit.returned' | 'withdrawal.created' | 'withdrawal.completed' | 'withdrawal.failed' | 'withdrawal.returned' | 'payment.created' | 'payment.completed' | 'payment.failed' | 'payment_request.created' | 'payment_request.completed' | 'payment_request.failed' | 'payment_request.returned'>;
+    /**
+     * Body param: New status
+     */
+    status?: 'ENABLED' | 'DISABLED';
+    /**
+     * Body param: Tag updates (set value to empty string to remove key)
+     */
+    tags?: {
+        [key: string]: string;
+    };
+    /**
+     * Body param: New webhook endpoint URL
+     */
+    url?: 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 WebhookListParams {
+    /**
+     * Query param: Cursor for keyset pagination
+     */
+    cursor?: string;
+    /**
+     * Query param: Max items per page (1-100)
+     */
+    limit?: number;
+    /**
+     * Query param: Filter by status
+     */
+    status?: 'ENABLED' | 'DISABLED';
+    /**
+     * 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 WebhookGetParams {
+    /**
+     * 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 WebhookRemoveParams {
+    /**
+     * 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 WebhookRotateSecretParams {
+    /**
+     * Body param: Grace period in seconds for the previous secret (0 = immediate
+     * cutover, max 86400)
+     */
+    expiresInSeconds: number;
+    /**
+     * 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;
+    /**
+     * 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 Webhooks {
+    export { 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, };
+}
+//# sourceMappingURL=webhooks.d.mts.map