@agentuity/core 1.0.33 → 1.0.35

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

@@ -0,0 +1,374 @@
+import { FetchAdapter } from '../adapter.ts';
+import type { CreateWebhookDestinationRequest, CreateWebhookRequest, UpdateWebhookRequest, Webhook, WebhookDelivery, WebhookDestination, WebhookOrgAnalytics, WebhookReceipt } from './types.ts';
+/**
+ * Parameters for creating a new webhook.
+ */
+export type CreateWebhookParams = CreateWebhookRequest;
+/**
+ * Parameters for updating a webhook.
+ */
+export type UpdateWebhookParams = UpdateWebhookRequest;
+/**
+ * Parameters for creating a new webhook destination.
+ */
+export type CreateWebhookDestinationParams = CreateWebhookDestinationRequest;
+/**
+ * Paginated list of webhooks.
+ */
+export type WebhookListResult = {
+    /** Array of webhooks. */
+    webhooks: Webhook[];
+    /** Total number of webhooks. */
+    total: number;
+};
+/**
+ * Result of fetching a single webhook, including its configured destinations.
+ */
+export type WebhookGetResult = {
+    /** The requested webhook. */
+    webhook: Webhook;
+    /** Array of destinations configured for this webhook. */
+    destinations: WebhookDestination[];
+};
+/**
+ * Result of creating a webhook.
+ */
+export type WebhookCreateResult = {
+    /** The newly created webhook. */
+    webhook: Webhook;
+};
+/**
+ * Result of updating a webhook.
+ */
+export type UpdateWebhookResult = {
+    /** The updated webhook. */
+    webhook: Webhook;
+};
+/**
+ * Result of creating a webhook destination.
+ */
+export type CreateDestinationResult = {
+    /** The newly created destination. */
+    destination: WebhookDestination;
+};
+/**
+ * List of destinations for a webhook.
+ */
+export type ListDestinationsResult = {
+    /** Array of destinations. */
+    destinations: WebhookDestination[];
+};
+/**
+ * List of receipts (incoming requests) for a webhook.
+ */
+export type WebhookReceiptListResult = {
+    /** Array of receipt records. */
+    receipts: WebhookReceipt[];
+};
+/**
+ * List of delivery attempts for a webhook.
+ */
+export type 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>;
+    /**
+     * Get org-level webhook analytics summary.
+     *
+     * Returns total received, delivered, and failed counts for all webhooks
+     * in the org within the specified time period.
+     *
+     * @param options - Analytics options (start, end, granularity)
+     * @returns Org-level webhook analytics with period and summary
+     * @throws {@link ServiceException} if the API request fails
+     */
+    getOrgAnalytics(options?: {
+        start?: string;
+        end?: string;
+        granularity?: string;
+    }): Promise<WebhookOrgAnalytics>;
+    /**
+     * Get org-level webhook time series data.
+     *
+     * Returns time-bucketed received, delivered, and failed counts for all webhooks
+     * in the org within the specified time period.
+     *
+     * @param options - Analytics options (start, end, granularity)
+     * @returns Webhook time series data with period and series array
+     * @throws {@link ServiceException} if the API request fails
+     */
+    getOrgTimeSeries(options?: {
+        start?: string;
+        end?: string;
+        granularity?: string;
+    }): Promise<{
+        period: {
+            start: string;
+            end: string;
+            granularity?: string;
+        };
+        series: Array<{
+            timestamp: string;
+            received: number;
+            delivered: number;
+            failed: number;
+        }>;
+    }>;
+}
+//# sourceMappingURL=service.d.ts.map

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

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