@agentuity/core 1.0.33 → 1.0.34

package/dist/services/webhook.d.ts

@@ -1,454 +0,0 @@
-import { FetchAdapter } from './adapter.ts';
-/**
- * A webhook endpoint that can receive HTTP requests. Each webhook has a unique
- * ingest URL and can forward received payloads to configured destinations.
- */
-export interface Webhook {
-    /** Unique identifier for the webhook. */
-    id: string;
-    /** ISO 8601 timestamp when the webhook was created. */
-    created_at: string;
-    /** ISO 8601 timestamp when the webhook was last modified. */
-    updated_at: string;
-    /** ID of the user who created the webhook. */
-    created_by: string;
-    /** Human-readable name for the webhook. */
-    name: string;
-    /** Optional description of the webhook's purpose. */
-    description: string | null;
-    /**
-     * The fully-qualified ingest URL where HTTP requests should be sent.
-     * Only present when the webhook is first created.
-     *
-     * @remarks Format: `https://<catalyst-url>/webhook/<orgId>-<webhookId>`
-     */
-    url?: string;
-}
-/**
- * A delivery target for a webhook. When an HTTP request is received at the
- * webhook's ingest URL, the payload is forwarded to each of its destinations.
- */
-export interface WebhookDestination {
-    /** Unique identifier for the destination. */
-    id: string;
-    /** The ID of the parent webhook. */
-    webhook_id: string;
-    /** ISO 8601 timestamp when the destination was created. */
-    created_at: string;
-    /** ISO 8601 timestamp when the destination was last modified. */
-    updated_at: string;
-    /** ID of the user who created the destination. */
-    created_by: string;
-    /**
-     * The destination type.
-     *
-     * @remarks Currently only `'url'` is supported.
-     */
-    type: string;
-    /**
-     * Destination-specific configuration.
-     *
-     * @remarks For `'url'` type: `{ url: string, headers?: Record<string, string> }`.
-     * The URL must use http or https.
-     */
-    config: Record<string, unknown>;
-}
-/**
- * A record of an HTTP request received at a webhook's ingest URL. Each receipt
- * captures the request headers and payload for auditing and replay.
- */
-export interface WebhookReceipt {
-    /** Unique identifier for the receipt. */
-    id: string;
-    /** ISO 8601 timestamp when the request was received. */
-    date: string;
-    /** The ID of the webhook that received the request. */
-    webhook_id: string;
-    /** HTTP headers from the incoming request. */
-    headers: Record<string, string>;
-    /** The request body/payload, preserved in its original form. */
-    payload: unknown;
-}
-/**
- * A record of a delivery attempt from a webhook receipt to a destination.
- * Tracks the forwarding status and supports retries for failed deliveries.
- */
-export interface WebhookDelivery {
-    /** Unique identifier for the delivery attempt. */
-    id: string;
-    /** ISO 8601 timestamp when the delivery was attempted. */
-    date: string;
-    /** The ID of the parent webhook. */
-    webhook_id: string;
-    /** The ID of the destination this delivery was sent to. */
-    webhook_destination_id: string;
-    /** The ID of the receipt that triggered this delivery. */
-    webhook_receipt_id: string;
-    /**
-     * Delivery status.
-     *
-     * - `'pending'` — Queued for delivery.
-     * - `'success'` — Successfully delivered.
-     * - `'failed'` — Delivery error occurred.
-     */
-    status: 'pending' | 'success' | 'failed';
-    /** Number of retry attempts made. */
-    retries: number;
-    /** Error message if delivery failed, `null` on success. */
-    error: string | null;
-    /** The response received from the destination endpoint, or `null`. */
-    response: Record<string, unknown> | null;
-}
-/**
- * Parameters for creating a new webhook.
- */
-export interface CreateWebhookParams {
-    /** Human-readable name for the webhook (required). */
-    name: string;
-    /** Optional description of the webhook's purpose. */
-    description?: string;
-}
-/**
- * Parameters for updating a webhook. Only provided fields are modified.
- */
-export interface UpdateWebhookParams {
-    /** Updated name. */
-    name?: string;
-    /** Updated description. */
-    description?: string;
-}
-/**
- * Parameters for creating a new webhook destination.
- */
-export interface CreateWebhookDestinationParams {
-    /**
-     * The destination type.
-     *
-     * @remarks Currently only `'url'` is supported.
-     */
-    type: string;
-    /**
-     * Type-specific configuration.
-     *
-     * @remarks For `'url'` type: `{ url: string, headers?: Record<string, string> }`.
-     */
-    config: Record<string, unknown>;
-}
-/**
- * Paginated list of webhooks.
- */
-export interface WebhookListResult {
-    /** Array of webhooks. */
-    webhooks: Webhook[];
-    /** Total number of webhooks. */
-    total: number;
-}
-/**
- * Result of fetching a single webhook, including its configured destinations.
- */
-export interface WebhookGetResult {
-    /** The requested webhook. */
-    webhook: Webhook;
-    /** Array of destinations configured for this webhook. */
-    destinations: WebhookDestination[];
-}
-/**
- * Result of creating a webhook.
- */
-export interface WebhookCreateResult {
-    /** The newly created webhook. */
-    webhook: Webhook;
-}
-/**
- * Result of updating a webhook.
- */
-export interface UpdateWebhookResult {
-    /** The updated webhook. */
-    webhook: Webhook;
-}
-/**
- * Result of creating a webhook destination.
- */
-export interface CreateDestinationResult {
-    /** The newly created destination. */
-    destination: WebhookDestination;
-}
-/**
- * List of destinations for a webhook.
- */
-export interface ListDestinationsResult {
-    /** Array of destinations. */
-    destinations: WebhookDestination[];
-}
-/**
- * List of receipts (incoming requests) for a webhook.
- */
-export interface WebhookReceiptListResult {
-    /** Array of receipt records. */
-    receipts: WebhookReceipt[];
-}
-/**
- * List of delivery attempts for a webhook.
- */
-export interface WebhookDeliveryListResult {
-    /** Array of delivery records. */
-    deliveries: WebhookDelivery[];
-}
-/**
- * Client for the Agentuity Webhook service.
- *
- * Provides methods for creating and managing webhook endpoints that can receive
- * HTTP requests and forward them to configured destinations. The service supports:
- *
- * - **Webhooks**: Named endpoints with unique ingest URLs
- * - **Destinations**: URL-based targets that receive forwarded payloads
- * - **Receipts**: Records of incoming HTTP requests for auditing
- * - **Deliveries**: Records of forwarding attempts with retry support
- *
- * When an HTTP request hits a webhook's ingest URL, it is recorded as a receipt
- * and then delivered to all configured destinations. Failed deliveries can be
- * retried via {@link WebhookService.retryDelivery}.
- *
- * All methods are instrumented with OpenTelemetry spans for observability.
- *
- * @example
- * ```typescript
- * const webhooks = new WebhookService(baseUrl, adapter);
- *
- * // Create a webhook
- * const { webhook } = await webhooks.create({ name: 'GitHub Events' });
- * console.log('Ingest URL:', webhook.url);
- *
- * // Add a destination
- * await webhooks.createDestination(webhook.id, {
- *   type: 'url',
- *   config: { url: 'https://example.com/handle-github' },
- * });
- *
- * // Check delivery history
- * const { deliveries } = await webhooks.listDeliveries(webhook.id);
- * ```
- */
-export declare class WebhookService {
-    #private;
-    /**
-     * Creates a new WebhookService instance.
-     *
-     * @param baseUrl - The base URL of the webhook API
-     * @param adapter - The HTTP fetch adapter used for making API requests
-     */
-    constructor(baseUrl: string, adapter: FetchAdapter);
-    /**
-     * Create a new webhook endpoint.
-     *
-     * @param params - The webhook creation parameters including name and optional description
-     * @returns The newly created webhook with its unique ingest URL
-     * @throws {@link ServiceException} if the API request fails
-     *
-     * @example
-     * ```typescript
-     * const { webhook } = await webhooks.create({
-     *   name: 'Stripe Events',
-     *   description: 'Receives payment webhooks from Stripe',
-     * });
-     * console.log('Ingest URL:', webhook.url);
-     * ```
-     */
-    create(params: CreateWebhookParams): Promise<WebhookCreateResult>;
-    /**
-     * List all webhooks with optional pagination.
-     *
-     * @param params - Optional pagination parameters
-     * @returns Paginated list of webhooks with total count
-     * @throws {@link ServiceException} if the API request fails
-     *
-     * @example
-     * ```typescript
-     * const { webhooks, total } = await webhooks.list({ limit: 10, offset: 0 });
-     * console.log(`Showing ${webhooks.length} of ${total} webhooks`);
-     * for (const wh of webhooks) {
-     *   console.log(`${wh.name}: ${wh.url}`);
-     * }
-     * ```
-     */
-    list(params?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<WebhookListResult>;
-    /**
-     * Get a webhook by its ID, including its configured destinations.
-     *
-     * @param webhookId - The unique webhook identifier
-     * @returns The webhook and its list of destinations
-     * @throws {@link ServiceException} if the API request fails
-     *
-     * @example
-     * ```typescript
-     * const { webhook, destinations } = await webhooks.get('wh_abc123');
-     * console.log(`${webhook.name} has ${destinations.length} destination(s)`);
-     * ```
-     */
-    get(webhookId: string): Promise<WebhookGetResult>;
-    /**
-     * Update a webhook's name and/or description.
-     *
-     * @param webhookId - The unique webhook identifier
-     * @param params - Fields to update; only provided fields are changed
-     * @returns The updated webhook
-     * @throws {@link ServiceException} if the API request fails
-     *
-     * @example
-     * ```typescript
-     * const { webhook } = await webhooks.update('wh_abc123', {
-     *   name: 'GitHub Events (Production)',
-     *   description: 'Production webhook for GitHub push events',
-     * });
-     * console.log('Updated:', webhook.name);
-     * ```
-     */
-    update(webhookId: string, params: UpdateWebhookParams): Promise<UpdateWebhookResult>;
-    /**
-     * Delete a webhook and all its associated destinations, receipts, and deliveries.
-     *
-     * @param webhookId - The unique webhook identifier
-     * @throws {@link ServiceException} if the API request fails
-     *
-     * @example
-     * ```typescript
-     * await webhooks.delete('wh_abc123');
-     * console.log('Webhook deleted');
-     * ```
-     */
-    delete(webhookId: string): Promise<void>;
-    /**
-     * Create a new destination for a webhook. When the webhook receives a request,
-     * the payload will be forwarded to this destination.
-     *
-     * @param webhookId - The ID of the parent webhook
-     * @param params - Destination configuration including type and type-specific config
-     * @returns The newly created destination
-     * @throws {@link ServiceException} if the API request fails
-     *
-     * @example
-     * ```typescript
-     * const { destination } = await webhooks.createDestination('wh_abc123', {
-     *   type: 'url',
-     *   config: {
-     *     url: 'https://example.com/webhook-handler',
-     *     headers: { 'X-Custom-Header': 'my-value' },
-     *   },
-     * });
-     * console.log('Destination created:', destination.id);
-     * ```
-     */
-    createDestination(webhookId: string, params: CreateWebhookDestinationParams): Promise<CreateDestinationResult>;
-    /**
-     * List all destinations configured for a webhook.
-     *
-     * @param webhookId - The ID of the webhook
-     * @returns List of destinations
-     * @throws {@link ServiceException} if the API request fails
-     *
-     * @example
-     * ```typescript
-     * const { destinations } = await webhooks.listDestinations('wh_abc123');
-     * for (const dest of destinations) {
-     *   console.log(`${dest.type}: ${JSON.stringify(dest.config)}`);
-     * }
-     * ```
-     */
-    listDestinations(webhookId: string): Promise<ListDestinationsResult>;
-    /**
-     * Delete a destination from a webhook.
-     *
-     * @param webhookId - The ID of the parent webhook
-     * @param destinationId - The ID of the destination to delete
-     * @throws {@link ServiceException} if the API request fails
-     *
-     * @example
-     * ```typescript
-     * await webhooks.deleteDestination('wh_abc123', 'dest_xyz789');
-     * console.log('Destination deleted');
-     * ```
-     */
-    deleteDestination(webhookId: string, destinationId: string): Promise<void>;
-    /**
-     * List receipts (records of incoming HTTP requests) for a webhook.
-     *
-     * @param webhookId - The ID of the webhook
-     * @param params - Optional pagination parameters
-     * @returns List of receipt records
-     * @throws {@link ServiceException} if the API request fails
-     *
-     * @example
-     * ```typescript
-     * const { receipts } = await webhooks.listReceipts('wh_abc123', {
-     *   limit: 50,
-     * });
-     * for (const receipt of receipts) {
-     *   console.log(`${receipt.date}: ${JSON.stringify(receipt.headers)}`);
-     * }
-     * ```
-     */
-    listReceipts(webhookId: string, params?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<WebhookReceiptListResult>;
-    /**
-     * Get a single receipt by its ID, including the full payload.
-     *
-     * @param webhookId - The ID of the webhook
-     * @param receiptId - The unique receipt identifier
-     * @returns The receipt record with headers and payload
-     * @throws {@link ServiceException} if the API request fails
-     *
-     * @example
-     * ```typescript
-     * const receipt = await webhooks.getReceipt('wh_abc123', 'rcpt_def456');
-     * console.log('Payload:', receipt.payload);
-     * console.log('Headers:', receipt.headers);
-     * ```
-     */
-    getReceipt(webhookId: string, receiptId: string): Promise<WebhookReceipt>;
-    /**
-     * List delivery attempts for a webhook with optional pagination.
-     *
-     * @param webhookId - The ID of the webhook
-     * @param params - Optional pagination parameters
-     * @returns List of delivery records showing forwarding status
-     * @throws {@link ServiceException} if the API request fails
-     *
-     * @example
-     * ```typescript
-     * const { deliveries } = await webhooks.listDeliveries('wh_abc123');
-     * for (const d of deliveries) {
-     *   console.log(`${d.status} → dest ${d.webhook_destination_id} (retries: ${d.retries})`);
-     * }
-     * ```
-     */
-    listDeliveries(webhookId: string, params?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<WebhookDeliveryListResult>;
-    /**
-     * Retry a failed delivery attempt. Only deliveries with `'failed'` status can be retried.
-     *
-     * @param webhookId - The ID of the parent webhook
-     * @param deliveryId - The ID of the failed delivery to retry
-     * @throws {@link ServiceException} if the API request fails
-     *
-     * @example
-     * ```typescript
-     * // Find and retry failed deliveries
-     * const { deliveries } = await webhooks.listDeliveries('wh_abc123');
-     * for (const d of deliveries) {
-     *   if (d.status === 'failed') {
-     *     await webhooks.retryDelivery('wh_abc123', d.id);
-     *     console.log('Retrying delivery:', d.id);
-     *   }
-     * }
-     * ```
-     */
-    retryDelivery(webhookId: string, deliveryId: string): Promise<void>;
-}
-//# sourceMappingURL=webhook.d.ts.map

package/dist/services/webhook.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../src/services/webhook.ts"],"names":[],"mappings":"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"}