@agentuity/server 1.0.22 → 1.0.23

package/src/api/webhook/types.ts

@@ -0,0 +1,309 @@
+import { z } from 'zod';
+
+// ============================================================================
+// Webhook Destination Types
+// ============================================================================
+
+/**
+ * Webhook destination type schema.
+ *
+ * Currently only 'url' destinations are supported.
+ *
+ * @example
+ * ```typescript
+ * const destType = WebhookDestinationTypeSchema.parse('url');
+ * ```
+ */
+export const WebhookDestinationTypeSchema = z.enum(['url']);
+
+/**
+ * Webhook destination type.
+ */
+export type WebhookDestinationType = z.infer<typeof WebhookDestinationTypeSchema>;
+
+// ============================================================================
+// Webhook Delivery Status
+// ============================================================================
+
+/**
+ * Webhook delivery status schema.
+ *
+ * - `pending`: Delivery is queued and waiting to be sent.
+ * - `success`: Delivery was completed successfully.
+ * - `failed`: Delivery failed after all retry attempts.
+ *
+ * @example
+ * ```typescript
+ * const status = WebhookDeliveryStatusSchema.parse('success');
+ * ```
+ */
+export const WebhookDeliveryStatusSchema = z.enum(['pending', 'success', 'failed']);
+
+/**
+ * Webhook delivery status type.
+ */
+export type WebhookDeliveryStatus = z.infer<typeof WebhookDeliveryStatusSchema>;
+
+// ============================================================================
+// Core Schemas
+// ============================================================================
+
+/**
+ * Webhook schema representing a webhook endpoint.
+ *
+ * @example
+ * ```typescript
+ * const webhook = await getWebhook(client, 'wh_abc123');
+ * console.log(`Webhook: ${webhook.name} (${webhook.id})`);
+ * ```
+ */
+export const WebhookSchema = z.object({
+	/** Unique identifier for the webhook (prefixed with wh_). */
+	id: z.string(),
+	/** ISO 8601 timestamp when the webhook was created. */
+	created_at: z.string(),
+	/** ISO 8601 timestamp when the webhook was last updated. */
+	updated_at: z.string(),
+	/** ID of the user who created the webhook. */
+	created_by: z.string(),
+	/** Human-readable webhook name. */
+	name: z.string(),
+	/** Optional description of the webhook's purpose. */
+	description: z.string().nullable().optional(),
+	/** Fully-qualified ingest URL for sending events to this webhook. Only present on create. */
+	url: z.string().optional(),
+});
+
+/**
+ * Webhook type.
+ */
+export type Webhook = z.infer<typeof WebhookSchema>;
+
+/**
+ * Webhook destination schema representing a delivery target for webhook events.
+ *
+ * Destinations define where incoming webhook payloads are forwarded to.
+ *
+ * @example
+ * ```typescript
+ * const destinations = await listWebhookDestinations(client, 'wh_abc123');
+ * for (const dest of destinations) {
+ *   console.log(`Destination ${dest.id}: type=${dest.type}`);
+ * }
+ * ```
+ */
+export const WebhookDestinationSchema = z.object({
+	/** Unique identifier for the destination (prefixed with whds_). */
+	id: z.string(),
+	/** ISO 8601 timestamp when the destination was created. */
+	created_at: z.string(),
+	/** ISO 8601 timestamp when the destination was last updated. */
+	updated_at: z.string(),
+	/** ID of the user who created the destination. */
+	created_by: z.string(),
+	/** ID of the webhook this destination belongs to. */
+	webhook_id: z.string(),
+	/** Type of destination (currently only 'url'). */
+	type: WebhookDestinationTypeSchema,
+	/** Configuration object for the destination (e.g., URL, headers). */
+	config: z.record(z.string(), z.unknown()),
+});
+
+/**
+ * Webhook destination type.
+ */
+export type WebhookDestination = z.infer<typeof WebhookDestinationSchema>;
+
+/**
+ * Webhook receipt schema representing an incoming webhook payload that was received.
+ *
+ * Receipts capture the raw payload and headers of each incoming webhook request.
+ *
+ * @example
+ * ```typescript
+ * const receipt = await getWebhookReceipt(client, 'wh_abc123', 'whrc_def456');
+ * console.log(`Receipt ${receipt.id}: received at ${receipt.date}`);
+ * ```
+ */
+export const WebhookReceiptSchema = z.object({
+	/** Unique identifier for the receipt (prefixed with whrc_). */
+	id: z.string(),
+	/** ISO 8601 timestamp when the receipt was recorded. */
+	date: z.string(),
+	/** ID of the webhook this receipt belongs to. */
+	webhook_id: z.string(),
+	/** HTTP headers from the incoming webhook request. */
+	headers: z.record(z.string(), z.unknown()),
+	/** Raw payload from the incoming webhook request (can be any type). */
+	payload: z.unknown(),
+});
+
+/**
+ * Webhook receipt type.
+ */
+export type WebhookReceipt = z.infer<typeof WebhookReceiptSchema>;
+
+/**
+ * Webhook delivery schema representing a delivery attempt to a destination.
+ *
+ * Deliveries track the status and result of forwarding a received webhook
+ * payload to a configured destination.
+ *
+ * @example
+ * ```typescript
+ * const deliveries = await listWebhookDeliveries(client, 'wh_abc123');
+ * for (const delivery of deliveries) {
+ *   console.log(`Delivery ${delivery.id}: ${delivery.status}`);
+ * }
+ * ```
+ */
+export const WebhookDeliverySchema = z.object({
+	/** Unique identifier for the delivery (prefixed with whdv_). */
+	id: z.string(),
+	/** ISO 8601 timestamp when the delivery was attempted. */
+	date: z.string(),
+	/** ID of the webhook this delivery belongs to. */
+	webhook_id: z.string(),
+	/** ID of the destination this delivery was sent to. */
+	webhook_destination_id: z.string(),
+	/** ID of the receipt that triggered this delivery. */
+	webhook_receipt_id: z.string(),
+	/** Current status of the delivery. */
+	status: WebhookDeliveryStatusSchema,
+	/** Number of retry attempts made. */
+	retries: z.number(),
+	/** Error message if the delivery failed. */
+	error: z.string().nullable().optional(),
+	/** Response data from the destination (if available). */
+	response: z.record(z.string(), z.unknown()).nullable().optional(),
+});
+
+/**
+ * Webhook delivery type.
+ */
+export type WebhookDelivery = z.infer<typeof WebhookDeliverySchema>;
+
+// ============================================================================
+// API Options
+// ============================================================================
+
+/**
+ * Common options for webhook API calls.
+ *
+ * Used to pass organization context when calling from CLI or other
+ * contexts where the org is not implicit in the authentication token.
+ */
+export interface WebhookApiOptions {
+	/**
+	 * Organization ID for the request.
+	 * Required when using user authentication (CLI) instead of SDK key.
+	 */
+	orgId?: string;
+}
+
+// ============================================================================
+// Request Schemas
+// ============================================================================
+
+/**
+ * Request schema for creating a new webhook.
+ *
+ * @example
+ * ```typescript
+ * const request: CreateWebhookRequest = {
+ *   name: 'github-events',
+ *   description: 'Receives GitHub webhook events',
+ * };
+ * ```
+ */
+export const CreateWebhookRequestSchema = z.object({
+	/** Human-readable name for the webhook. */
+	name: z.string(),
+	/** Optional description of the webhook's purpose. */
+	description: z.string().optional(),
+});
+
+/** Request type for creating a webhook. */
+export type CreateWebhookRequest = z.infer<typeof CreateWebhookRequestSchema>;
+
+/**
+ * Request schema for updating an existing webhook.
+ *
+ * @example
+ * ```typescript
+ * const request: UpdateWebhookRequest = {
+ *   name: 'github-events-v2',
+ *   description: 'Updated description',
+ * };
+ * ```
+ */
+export const UpdateWebhookRequestSchema = z.object({
+	/** New name for the webhook. */
+	name: z.string(),
+	/** New description for the webhook. */
+	description: z.string().optional(),
+});
+
+/** Request type for updating a webhook. */
+export type UpdateWebhookRequest = z.infer<typeof UpdateWebhookRequestSchema>;
+
+/**
+ * Request schema for creating a webhook destination.
+ *
+ * @example
+ * ```typescript
+ * const request: CreateWebhookDestinationRequest = {
+ *   type: 'url',
+ *   config: { url: 'https://api.example.com/webhook' },
+ * };
+ * ```
+ */
+export const CreateWebhookDestinationRequestSchema = z.object({
+	/** Type of destination to create. */
+	type: WebhookDestinationTypeSchema,
+	/** Configuration object for the destination. */
+	config: z.record(z.string(), z.unknown()),
+});
+
+/** Request type for creating a webhook destination. */
+export type CreateWebhookDestinationRequest = z.infer<typeof CreateWebhookDestinationRequestSchema>;
+
+/**
+ * Request schema for updating a webhook destination.
+ *
+ * @example
+ * ```typescript
+ * const request: UpdateWebhookDestinationRequest = {
+ *   config: { url: 'https://api.example.com/webhook/v2' },
+ * };
+ * ```
+ */
+export const UpdateWebhookDestinationRequestSchema = z.object({
+	/** Updated configuration object for the destination. */
+	config: z.record(z.string(), z.unknown()).optional(),
+});
+
+/** Request type for updating a webhook destination. */
+export type UpdateWebhookDestinationRequest = z.infer<typeof UpdateWebhookDestinationRequestSchema>;
+
+export const PaginationRequestSchema = z.object({
+	limit: z.number().optional(),
+	offset: z.number().optional(),
+});
+
+export type PaginationRequest = z.infer<typeof PaginationRequestSchema>;
+
+export const ListWebhooksRequestSchema = PaginationRequestSchema;
+
+/** Request type for listing webhooks. */
+export type ListWebhooksRequest = z.infer<typeof ListWebhooksRequestSchema>;
+
+export const ListWebhookReceiptsRequestSchema = PaginationRequestSchema;
+
+/** Request type for listing webhook receipts. */
+export type ListWebhookReceiptsRequest = z.infer<typeof ListWebhookReceiptsRequestSchema>;
+
+export const ListWebhookDeliveriesRequestSchema = PaginationRequestSchema;
+
+/** Request type for listing webhook deliveries. */
+export type ListWebhookDeliveriesRequest = z.infer<typeof ListWebhookDeliveriesRequestSchema>;

package/src/api/webhook/util.ts

@@ -0,0 +1,237 @@
+import { StructuredError } from '@agentuity/core';
+import { APIError } from '../api.ts';
+
+// ============================================================================
+// Error Types
+// ============================================================================
+
+/**
+ * General webhook operation error.
+ *
+ * Thrown when a webhook operation fails for reasons other than not-found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await createWebhook(client, { name: 'my-webhook' });
+ * } catch (error) {
+ *   if (error instanceof WebhookError) {
+ *     console.error(`Webhook operation failed: ${error.message}`);
+ *   }
+ * }
+ * ```
+ */
+export const WebhookError = StructuredError('WebhookError')<{ webhookId?: string }>();
+
+/**
+ * Error thrown when a webhook is not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await getWebhook(client, 'wh_nonexistent');
+ * } catch (error) {
+ *   if (error instanceof WebhookNotFoundError) {
+ *     console.error(`Webhook not found: ${error.webhookId}`);
+ *   }
+ * }
+ * ```
+ */
+export const WebhookNotFoundError = StructuredError('WebhookNotFoundError')<{
+	webhookId: string;
+}>();
+
+/**
+ * Error thrown when a webhook destination is not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await deleteWebhookDestination(client, 'wh_abc', 'whds_nonexistent');
+ * } catch (error) {
+ *   if (error instanceof WebhookDestinationNotFoundError) {
+ *     console.error(`Destination ${error.destinationId} not found`);
+ *   }
+ * }
+ * ```
+ */
+export const WebhookDestinationNotFoundError = StructuredError('WebhookDestinationNotFoundError')<{
+	webhookId: string;
+	destinationId: string;
+}>();
+
+/**
+ * Error thrown when a webhook receipt is not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await getWebhookReceipt(client, 'wh_abc', 'whrc_nonexistent');
+ * } catch (error) {
+ *   if (error instanceof WebhookReceiptNotFoundError) {
+ *     console.error(`Receipt ${error.receiptId} not found`);
+ *   }
+ * }
+ * ```
+ */
+export const WebhookReceiptNotFoundError = StructuredError('WebhookReceiptNotFoundError')<{
+	webhookId: string;
+	receiptId: string;
+}>();
+
+/**
+ * Error thrown when a webhook delivery is not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await retryWebhookDelivery(client, 'wh_abc', 'whdv_nonexistent');
+ * } catch (error) {
+ *   if (error instanceof WebhookDeliveryNotFoundError) {
+ *     console.error(`Delivery ${error.deliveryId} not found`);
+ *   }
+ * }
+ * ```
+ */
+export const WebhookDeliveryNotFoundError = StructuredError('WebhookDeliveryNotFoundError')<{
+	webhookId: string;
+	deliveryId: string;
+}>();
+
+// ============================================================================
+// API Path Helpers
+// ============================================================================
+
+/** Current Webhook API version. */
+const WEBHOOK_API_VERSION = '2026-02-24';
+
+/**
+ * Constructs a full API path for webhook operations.
+ *
+ * Pattern: `/webhook/${VERSION}/${verb}/${segments.join('/')}`
+ * Each verb is unique to avoid route conflicts with the Go mux.
+ *
+ * @param verb - The action verb (e.g., 'create', 'list', 'get', 'destination-list')
+ * @param segments - Additional path segments (e.g., webhook ID, sub-resource ID)
+ * @returns The full API path with version and verb prefix
+ *
+ * @internal
+ */
+export function webhookApiPath(verb: string, ...segments: string[]): string {
+	const encoded = segments.map((s) => encodeURIComponent(s)).join('/');
+	if (encoded) {
+		return `/webhook/${WEBHOOK_API_VERSION}/${verb}/${encoded}`;
+	}
+	return `/webhook/${WEBHOOK_API_VERSION}/${verb}`;
+}
+
+/**
+ * Constructs a full API path for webhook operations with query string.
+ *
+ * @param verb - The action verb
+ * @param queryString - Query string to append (without leading ?)
+ * @param segments - Additional path segments
+ * @returns The full API path with version, verb, and query string
+ *
+ * @internal
+ */
+export function webhookApiPathWithQuery(
+	verb: string,
+	queryString: string | undefined,
+	...segments: string[]
+): string {
+	const basePath = webhookApiPath(verb, ...segments);
+	return queryString ? `${basePath}?${queryString}` : basePath;
+}
+
+/**
+ * Constructs the public ingest URL for a webhook.
+ *
+ * Pattern: `/webhook/{orgId}-{webhookId}` (non-versioned, public)
+ *
+ * @param orgId - The organization ID
+ * @param webhookId - The webhook ID (prefixed with wh_)
+ * @returns The public ingest URL
+ *
+ * @internal
+ */
+export function webhookIngestPath(orgId: string, webhookId: string): string {
+	return `/webhook/${encodeURIComponent(orgId)}-${encodeURIComponent(webhookId)}`;
+}
+
+// ============================================================================
+// Header Builder
+// ============================================================================
+
+/**
+ * Builds headers for webhook API requests.
+ *
+ * @param orgId - Optional organization ID for CLI authentication
+ * @returns Headers object to pass to API client
+ *
+ * @internal
+ */
+export function buildWebhookHeaders(orgId?: string): Record<string, string> | undefined {
+	if (orgId) {
+		return { 'x-agentuity-orgid': orgId };
+	}
+	return undefined;
+}
+
+// ============================================================================
+// Error Handling
+// ============================================================================
+
+/**
+ * Wraps an API call and translates APIError with HTTP status codes to domain-specific webhook errors.
+ *
+ * - 404 → WebhookNotFoundError / WebhookDestinationNotFoundError / WebhookReceiptNotFoundError / WebhookDeliveryNotFoundError
+ *
+ * @internal
+ */
+export async function withWebhookErrorHandling<T>(
+	apiCall: () => Promise<T>,
+	context: {
+		webhookId?: string;
+		destinationId?: string;
+		receiptId?: string;
+		deliveryId?: string;
+	}
+): Promise<T> {
+	try {
+		return await apiCall();
+	} catch (error) {
+		if (error instanceof APIError) {
+			if (error.status === 404) {
+				if (context.deliveryId && context.webhookId) {
+					throw new WebhookDeliveryNotFoundError({
+						webhookId: context.webhookId,
+						deliveryId: context.deliveryId,
+						message: error.message,
+					});
+				}
+				if (context.receiptId && context.webhookId) {
+					throw new WebhookReceiptNotFoundError({
+						webhookId: context.webhookId,
+						receiptId: context.receiptId,
+						message: error.message,
+					});
+				}
+				if (context.destinationId && context.webhookId) {
+					throw new WebhookDestinationNotFoundError({
+						webhookId: context.webhookId,
+						destinationId: context.destinationId,
+						message: error.message,
+					});
+				}
+				if (context.webhookId) {
+					throw new WebhookNotFoundError({
+						webhookId: context.webhookId,
+						message: error.message,
+					});
+				}
+			}
+		}
+		throw error;
+	}
+}