@agentuity/server 1.0.22 → 1.0.23

package/src/api/webhook/destinations.ts

@@ -0,0 +1,224 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema, APIResponseSchemaNoData } from '../api.ts';
+import {
+	type CreateWebhookDestinationRequest,
+	CreateWebhookDestinationRequestSchema,
+	type UpdateWebhookDestinationRequest,
+	UpdateWebhookDestinationRequestSchema,
+	type WebhookApiOptions,
+	type WebhookDestination,
+	WebhookDestinationSchema,
+} from './types.ts';
+import {
+	buildWebhookHeaders,
+	WebhookError,
+	webhookApiPath,
+	withWebhookErrorHandling,
+} from './util.ts';
+
+export const WebhookDestinationResponseSchema = APIResponseSchema(WebhookDestinationSchema);
+export const WebhookDestinationsListResponseSchema = APIResponseSchema(
+	z.array(WebhookDestinationSchema)
+);
+export const DeleteWebhookDestinationResponseSchema = APIResponseSchemaNoData();
+
+/**
+ * Create a destination for a webhook.
+ *
+ * Destinations define where incoming webhook payloads are forwarded to.
+ * When a webhook receives a payload, it will be delivered to all configured destinations.
+ *
+ * @param client - The API client instance
+ * @param webhookId - The webhook ID (prefixed with wh_)
+ * @param params - Destination configuration including type and config
+ * @param options - Optional API options (e.g., orgId)
+ * @returns The created destination
+ * @throws {WebhookNotFoundError} If the webhook does not exist
+ * @throws {WebhookError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const destination = await createWebhookDestination(client, 'wh_abc123', {
+ *   type: 'url',
+ *   config: { url: 'https://api.example.com/webhook' },
+ * });
+ * console.log(`Created destination ${destination.id}`);
+ * ```
+ */
+export async function createWebhookDestination(
+	client: APIClient,
+	webhookId: string,
+	params: CreateWebhookDestinationRequest,
+	options?: WebhookApiOptions
+): Promise<WebhookDestination> {
+	const url = webhookApiPath('destination-create', webhookId);
+	const resp = await withWebhookErrorHandling(
+		() =>
+			client.post(
+				url,
+				params,
+				WebhookDestinationResponseSchema,
+				CreateWebhookDestinationRequestSchema,
+				undefined,
+				buildWebhookHeaders(options?.orgId)
+			),
+		{ webhookId }
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new WebhookError({
+		webhookId,
+		message: resp.message || 'Failed to create webhook destination',
+	});
+}
+
+/**
+ * List all destinations for a webhook.
+ *
+ * Retrieves all destinations configured for a webhook.
+ *
+ * @param client - The API client instance
+ * @param webhookId - The webhook ID (prefixed with wh_)
+ * @param options - Optional API options (e.g., orgId)
+ * @returns Array of destinations configured for the webhook
+ * @throws {WebhookNotFoundError} If the webhook does not exist
+ * @throws {WebhookError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const destinations = await listWebhookDestinations(client, 'wh_abc123');
+ * for (const dest of destinations) {
+ *   console.log(`Destination ${dest.id}: type=${dest.type}`);
+ * }
+ * ```
+ */
+export async function listWebhookDestinations(
+	client: APIClient,
+	webhookId: string,
+	options?: WebhookApiOptions
+): Promise<WebhookDestination[]> {
+	const url = webhookApiPath('destination-list', webhookId);
+	const resp = await withWebhookErrorHandling(
+		() =>
+			client.get(
+				url,
+				WebhookDestinationsListResponseSchema,
+				undefined,
+				buildWebhookHeaders(options?.orgId)
+			),
+		{ webhookId }
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new WebhookError({
+		webhookId,
+		message: resp.message || 'Failed to list webhook destinations',
+	});
+}
+
+/**
+ * Update a webhook destination's configuration.
+ *
+ * Modifies an existing destination's config. Only the fields provided in params will be updated.
+ *
+ * @param client - The API client instance
+ * @param webhookId - The webhook ID (prefixed with wh_)
+ * @param destinationId - The destination ID to update (prefixed with whds_)
+ * @param params - Fields to update
+ * @param options - Optional API options (e.g., orgId)
+ * @returns The updated destination
+ * @throws {WebhookDestinationNotFoundError} If the destination does not exist
+ * @throws {WebhookNotFoundError} If the webhook does not exist
+ * @throws {WebhookError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const updated = await updateWebhookDestination(client, 'wh_abc123', 'whds_def456', {
+ *   config: { url: 'https://api.example.com/webhook/v2' },
+ * });
+ * ```
+ */
+export async function updateWebhookDestination(
+	client: APIClient,
+	webhookId: string,
+	destinationId: string,
+	params: UpdateWebhookDestinationRequest,
+	options?: WebhookApiOptions
+): Promise<WebhookDestination> {
+	const url = webhookApiPath('destination-update', webhookId, destinationId);
+	const resp = await withWebhookErrorHandling(
+		() =>
+			client.put(
+				url,
+				params,
+				WebhookDestinationResponseSchema,
+				UpdateWebhookDestinationRequestSchema,
+				undefined,
+				buildWebhookHeaders(options?.orgId)
+			),
+		{ webhookId, destinationId }
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new WebhookError({
+		webhookId,
+		message: resp.message || 'Failed to update webhook destination',
+	});
+}
+
+/**
+ * Delete a webhook destination.
+ *
+ * Permanently removes a destination. Webhook payloads will no longer be
+ * forwarded to this endpoint. This action cannot be undone.
+ *
+ * @param client - The API client instance
+ * @param webhookId - The webhook ID (prefixed with wh_)
+ * @param destinationId - The destination ID to delete (prefixed with whds_)
+ * @param options - Optional API options (e.g., orgId)
+ * @throws {WebhookDestinationNotFoundError} If the destination does not exist
+ * @throws {WebhookNotFoundError} If the webhook does not exist
+ * @throws {WebhookError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * await deleteWebhookDestination(client, 'wh_abc123', 'whds_def456');
+ * console.log('Destination deleted');
+ * ```
+ */
+export async function deleteWebhookDestination(
+	client: APIClient,
+	webhookId: string,
+	destinationId: string,
+	options?: WebhookApiOptions
+): Promise<void> {
+	const url = webhookApiPath('destination-delete', webhookId, destinationId);
+	const resp = await withWebhookErrorHandling(
+		() =>
+			client.delete(
+				url,
+				DeleteWebhookDestinationResponseSchema,
+				undefined,
+				buildWebhookHeaders(options?.orgId)
+			),
+		{ webhookId, destinationId }
+	);
+
+	if (resp.success) {
+		return;
+	}
+
+	throw new WebhookError({
+		webhookId,
+		message: resp.message || 'Failed to delete webhook destination',
+	});
+}

package/src/api/webhook/index.ts

@@ -0,0 +1,133 @@
+/**
+ * @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,
+	type WebhookDelivery,
+	WebhookDeliverySchema,
+	type WebhookDeliveryStatus,
+	WebhookDeliveryStatusSchema,
+	type WebhookDestination,
+	WebhookDestinationSchema,
+	type WebhookDestinationType,
+	WebhookDestinationTypeSchema,
+	type WebhookReceipt,
+	WebhookReceiptSchema,
+	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';

package/src/api/webhook/receipts.ts

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import {
+	type ListWebhookReceiptsRequest,
+	type WebhookApiOptions,
+	type WebhookReceipt,
+	WebhookReceiptSchema,
+} from './types.ts';
+import {
+	buildWebhookHeaders,
+	WebhookError,
+	webhookApiPath,
+	webhookApiPathWithQuery,
+	withWebhookErrorHandling,
+} from './util.ts';
+
+export const WebhookReceiptResponseSchema = APIResponseSchema(WebhookReceiptSchema);
+export const WebhookReceiptsListResponseSchema = APIResponseSchema(z.array(WebhookReceiptSchema));
+
+/**
+ * List receipts for a webhook with optional pagination.
+ *
+ * Receipts represent incoming webhook payloads that were received.
+ *
+ * @param client - The API client instance
+ * @param webhookId - The webhook ID (prefixed with wh_)
+ * @param params - Optional pagination parameters
+ * @param options - Optional API options (e.g., orgId)
+ * @returns Object containing the list of receipts
+ * @throws {WebhookNotFoundError} If the webhook does not exist
+ * @throws {WebhookError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const { receipts } = await listWebhookReceipts(client, 'wh_abc123', { limit: 10 });
+ * for (const receipt of receipts) {
+ *   console.log(`Receipt ${receipt.id}: received at ${receipt.date}`);
+ * }
+ * ```
+ */
+export async function listWebhookReceipts(
+	client: APIClient,
+	webhookId: string,
+	params?: ListWebhookReceiptsRequest,
+	options?: WebhookApiOptions
+): Promise<{ receipts: WebhookReceipt[] }> {
+	const searchParams = new URLSearchParams();
+	if (params?.limit !== undefined) {
+		searchParams.set('limit', String(params.limit));
+	}
+	if (params?.offset !== undefined) {
+		searchParams.set('offset', String(params.offset));
+	}
+
+	const queryString = searchParams.toString();
+	const url = webhookApiPathWithQuery('receipt-list', queryString || undefined, webhookId);
+	const resp = await withWebhookErrorHandling(
+		() =>
+			client.get(
+				url,
+				WebhookReceiptsListResponseSchema,
+				undefined,
+				buildWebhookHeaders(options?.orgId)
+			),
+		{ webhookId }
+	);
+
+	if (resp.success) {
+		return { receipts: resp.data };
+	}
+
+	throw new WebhookError({
+		webhookId,
+		message: resp.message || 'Failed to list webhook receipts',
+	});
+}
+
+/**
+ * Get a specific receipt for a webhook.
+ *
+ * Retrieves the full receipt details including headers and payload.
+ *
+ * @param client - The API client instance
+ * @param webhookId - The webhook ID (prefixed with wh_)
+ * @param receiptId - The receipt ID (prefixed with whrc_)
+ * @param options - Optional API options (e.g., orgId)
+ * @returns The receipt details
+ * @throws {WebhookReceiptNotFoundError} If the receipt does not exist
+ * @throws {WebhookNotFoundError} If the webhook does not exist
+ * @throws {WebhookError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const receipt = await getWebhookReceipt(client, 'wh_abc123', 'whrc_def456');
+ * console.log(`Receipt payload:`, receipt.payload);
+ * ```
+ */
+export async function getWebhookReceipt(
+	client: APIClient,
+	webhookId: string,
+	receiptId: string,
+	options?: WebhookApiOptions
+): Promise<WebhookReceipt> {
+	const url = webhookApiPath('receipt-get', webhookId, receiptId);
+	const resp = await withWebhookErrorHandling(
+		() =>
+			client.get(
+				url,
+				WebhookReceiptResponseSchema,
+				undefined,
+				buildWebhookHeaders(options?.orgId)
+			),
+		{ webhookId, receiptId }
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new WebhookError({
+		webhookId,
+		message: resp.message || 'Failed to get webhook receipt',
+	});
+}