@agentuity/core 1.0.33 → 1.0.35

package/src/services/webhook/analytics.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import {
+	type WebhookAnalyticsOptions,
+	type WebhookOrgAnalytics,
+	WebhookOrgAnalyticsSchema,
+	type WebhookTimeSeriesData,
+	WebhookTimeSeriesDataSchema,
+} from './types.ts';
+import { buildWebhookHeaders, WebhookError, webhookApiPathWithQuery } from './util.ts';
+
+export const WebhookOrgAnalyticsResponseSchema = APIResponseSchema(
+	z.object({ analytics: WebhookOrgAnalyticsSchema })
+);
+
+export const WebhookTimeSeriesResponseSchema = APIResponseSchema(
+	z.object({ timeseries: WebhookTimeSeriesDataSchema })
+);
+
+function buildAnalyticsQuery(options?: WebhookAnalyticsOptions): string | undefined {
+	if (!options) return undefined;
+	const params = new URLSearchParams();
+	if (options.start) params.set('start', options.start);
+	if (options.end) params.set('end', options.end);
+	if (options.granularity) params.set('granularity', options.granularity);
+	const query = params.toString();
+	return query || undefined;
+}
+
+/**
+ * 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 client - The API client
+ * @param options - Analytics options (start, end, granularity)
+ * @returns Org-level webhook analytics
+ */
+export async function getWebhookOrgAnalytics(
+	client: APIClient,
+	options?: WebhookAnalyticsOptions
+): Promise<WebhookOrgAnalytics> {
+	const queryString = buildAnalyticsQuery(options);
+	const url = webhookApiPathWithQuery('analytics/org', queryString);
+	const resp = await client.get(
+		url,
+		WebhookOrgAnalyticsResponseSchema,
+		undefined,
+		buildWebhookHeaders(options?.orgId)
+	);
+	if (resp.success) return resp.data.analytics;
+	throw new WebhookError({ message: resp.message || 'Failed to get webhook org analytics' });
+}
+
+/**
+ * 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 client - The API client
+ * @param options - Analytics options (start, end, granularity)
+ * @returns Webhook time series data
+ */
+export async function getWebhookOrgTimeSeries(
+	client: APIClient,
+	options?: WebhookAnalyticsOptions
+): Promise<WebhookTimeSeriesData> {
+	const queryString = buildAnalyticsQuery(options);
+	const url = webhookApiPathWithQuery('analytics/org/timeseries', queryString);
+	const resp = await client.get(
+		url,
+		WebhookTimeSeriesResponseSchema,
+		undefined,
+		buildWebhookHeaders(options?.orgId)
+	);
+	if (resp.success) return resp.data.timeseries;
+	throw new WebhookError({ message: resp.message || 'Failed to get webhook org time series' });
+}

package/src/services/webhook/index.ts

@@ -0,0 +1,160 @@
+export * from './service.ts';
+/**
+ * @module webhook
+ *
+ * Webhook API client for managing webhooks, destinations, receipts, and deliveries.
+ *
+ * This module provides a complete client for the Agentuity Webhook API, supporting:
+ * - **Webhook Management**: Create, read, update, and delete webhooks
+ * - **Destinations**: Configure URL endpoints for webhook payload forwarding
+ * - **Receipts**: View incoming webhook payloads that were received
+ * - **Deliveries**: Track delivery attempts and retry failed deliveries
+ *
+ * @example Basic Webhook Operations
+ * ```typescript
+ * import { createWebhook, createWebhookDestination, listWebhookReceipts } from '@agentuity/server';
+ *
+ * // Create a webhook
+ * const webhook = await createWebhook(client, {
+ *   name: 'github-events',
+ *   description: 'Receives GitHub webhook events',
+ * });
+ *
+ * // Add a destination
+ * await createWebhookDestination(client, webhook.id, {
+ *   type: 'url',
+ *   config: { url: 'https://api.example.com/webhook' },
+ * });
+ *
+ * // List receipts
+ * const { receipts } = await listWebhookReceipts(client, webhook.id);
+ * for (const receipt of receipts) {
+ *   console.log(`Received: ${receipt.id} at ${receipt.date}`);
+ * }
+ * ```
+ */
+
+// ============================================================================
+// Types & Schemas
+// ============================================================================
+
+export {
+	type CreateWebhookDestinationRequest,
+	CreateWebhookDestinationRequestSchema,
+	type CreateWebhookRequest,
+	CreateWebhookRequestSchema,
+	type ListWebhookDeliveriesRequest,
+	ListWebhookDeliveriesRequestSchema,
+	type ListWebhookReceiptsRequest,
+	ListWebhookReceiptsRequestSchema,
+	type ListWebhooksRequest,
+	ListWebhooksRequestSchema,
+	type PaginationRequest,
+	PaginationRequestSchema,
+	type UpdateWebhookDestinationRequest,
+	UpdateWebhookDestinationRequestSchema,
+	type UpdateWebhookRequest,
+	UpdateWebhookRequestSchema,
+	type Webhook,
+	type WebhookApiOptions,
+	WebhookApiOptionsSchema,
+	type WebhookDelivery,
+	WebhookDeliverySchema,
+	type WebhookDeliveryStatus,
+	WebhookDeliveryStatusSchema,
+	type WebhookDestination,
+	WebhookDestinationSchema,
+	type WebhookDestinationType,
+	WebhookDestinationTypeSchema,
+	type WebhookReceipt,
+	WebhookReceiptSchema,
+	type WebhookAnalyticsGranularity,
+	WebhookAnalyticsGranularitySchema,
+	type WebhookAnalyticsOptions,
+	WebhookAnalyticsOptionsSchema,
+	type WebhookAnalyticsSummary,
+	WebhookAnalyticsSummarySchema,
+	type WebhookOrgAnalytics,
+	WebhookOrgAnalyticsSchema,
+	type WebhookTimePeriod,
+	WebhookTimePeriodSchema,
+	type WebhookTimeSeriesData,
+	WebhookTimeSeriesDataSchema,
+	type WebhookTimeSeriesPoint,
+	WebhookTimeSeriesPointSchema,
+	WebhookSchema,
+} from './types.ts';
+
+// ============================================================================
+// Errors
+// ============================================================================
+
+export {
+	WebhookDeliveryNotFoundError,
+	WebhookDestinationNotFoundError,
+	WebhookError,
+	WebhookNotFoundError,
+	WebhookReceiptNotFoundError,
+} from './util.ts';
+
+// ============================================================================
+// Webhook Operations
+// ============================================================================
+
+export {
+	createWebhook,
+	DeleteWebhookResponseSchema,
+	deleteWebhook,
+	getWebhook,
+	listWebhooks,
+	WebhookResponseSchema,
+	WebhooksListResponseSchema,
+	updateWebhook,
+} from './webhooks.ts';
+
+// ============================================================================
+// Destination Operations
+// ============================================================================
+
+export {
+	createWebhookDestination,
+	DeleteWebhookDestinationResponseSchema,
+	deleteWebhookDestination,
+	listWebhookDestinations,
+	updateWebhookDestination,
+	WebhookDestinationResponseSchema,
+	WebhookDestinationsListResponseSchema,
+} from './destinations.ts';
+
+// ============================================================================
+// Receipt Operations
+// ============================================================================
+
+export {
+	getWebhookReceipt,
+	listWebhookReceipts,
+	WebhookReceiptResponseSchema,
+	WebhookReceiptsListResponseSchema,
+} from './receipts.ts';
+
+// ============================================================================
+// Delivery Operations
+// ============================================================================
+
+export {
+	listWebhookDeliveries,
+	retryWebhookDelivery,
+	WebhookDeliveriesListResponseSchema,
+	WebhookDeliveryResponseSchema,
+} from './deliveries.ts';
+
+// ============================================================================
+// Analytics Operations
+// ============================================================================
+
+export {
+	getWebhookOrgAnalytics,
+	getWebhookOrgTimeSeries,
+	WebhookOrgAnalyticsResponseSchema,
+	WebhookTimeSeriesResponseSchema,
+} from './analytics.ts';