@agentuity/server 0.1.15 → 0.1.17

package/src/api/queue/analytics.ts

@@ -0,0 +1,313 @@
+import { z } from 'zod';
+import { APIClient, APIResponseSchema } from '../api';
+import {
+	OrgAnalyticsSchema,
+	QueueAnalyticsSchema,
+	TimeSeriesDataSchema,
+	SSEStatsEventSchema,
+	type OrgAnalytics,
+	type QueueAnalytics,
+	type TimeSeriesData,
+	type SSEStatsEvent,
+	type AnalyticsOptions,
+	type StreamAnalyticsOptions,
+} from './types';
+import { QueueError, QueueNotFoundError, queueApiPathWithQuery, buildQueueHeaders } from './util';
+import { validateQueueName } from './validation';
+
+const OrgAnalyticsResponseSchema = APIResponseSchema(z.object({ analytics: OrgAnalyticsSchema }));
+const QueueAnalyticsResponseSchema = APIResponseSchema(
+	z.object({ analytics: QueueAnalyticsSchema })
+);
+const TimeSeriesResponseSchema = APIResponseSchema(z.object({ timeseries: TimeSeriesDataSchema }));
+
+/**
+ * Build query string from analytics options.
+ */
+function buildAnalyticsQuery(options?: AnalyticsOptions): 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);
+	if (options.projectId) params.set('project_id', options.projectId);
+	if (options.agentId) params.set('agent_id', options.agentId);
+
+	const query = params.toString();
+	return query || undefined;
+}
+
+/**
+ * Get org-level analytics for all queues.
+ *
+ * Returns aggregated statistics across all queues in the organization.
+ *
+ * @param client - The API client instance
+ * @param options - Analytics options (time range, filters)
+ * @returns Org-level analytics summary
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const analytics = await getOrgAnalytics(client, {
+ *   start: '2026-01-14T00:00:00Z',
+ *   end: '2026-01-15T00:00:00Z',
+ * });
+ * console.log(`Total queues: ${analytics.summary.total_queues}`);
+ * console.log(`Messages published: ${analytics.summary.total_messages_published}`);
+ * ```
+ */
+export async function getOrgAnalytics(
+	client: APIClient,
+	options?: AnalyticsOptions
+): Promise<OrgAnalytics> {
+	const queryString = buildAnalyticsQuery(options);
+	const url = queueApiPathWithQuery('analytics/org', queryString);
+	const resp = await client.get(
+		url,
+		OrgAnalyticsResponseSchema,
+		undefined,
+		buildQueueHeaders(options?.orgId)
+	);
+
+	if (resp.success) {
+		return resp.data.analytics;
+	}
+
+	throw new QueueError({
+		message: resp.message || 'Failed to get org analytics',
+	});
+}
+
+/**
+ * Get detailed analytics for a specific queue.
+ *
+ * Returns current state, period statistics, latency metrics, and destination stats.
+ *
+ * @param client - The API client instance
+ * @param name - The queue name
+ * @param options - Analytics options (time range, filters)
+ * @returns Queue analytics
+ * @throws {QueueNotFoundError} If the queue does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const analytics = await getQueueAnalytics(client, 'order-processing', {
+ *   start: '2026-01-14T00:00:00Z',
+ * });
+ * console.log(`Backlog: ${analytics.current.backlog}`);
+ * console.log(`P95 latency: ${analytics.latency.p95_ms}ms`);
+ * ```
+ */
+export async function getQueueAnalytics(
+	client: APIClient,
+	name: string,
+	options?: AnalyticsOptions
+): Promise<QueueAnalytics> {
+	validateQueueName(name);
+	const queryString = buildAnalyticsQuery(options);
+	const url = queueApiPathWithQuery('analytics/queue', queryString, name);
+	const resp = await client.get(
+		url,
+		QueueAnalyticsResponseSchema,
+		undefined,
+		buildQueueHeaders(options?.orgId)
+	);
+
+	if (resp.success) {
+		return resp.data.analytics;
+	}
+
+	if (resp.message?.includes('not found')) {
+		throw new QueueNotFoundError({
+			queueName: name,
+			message: resp.message,
+		});
+	}
+
+	throw new QueueError({
+		queueName: name,
+		message: resp.message || 'Failed to get queue analytics',
+	});
+}
+
+/**
+ * Get time series analytics data for a queue.
+ *
+ * Returns time-bucketed metrics for visualization in charts and graphs.
+ *
+ * @param client - The API client instance
+ * @param name - The queue name
+ * @param options - Analytics options (time range, granularity)
+ * @returns Time series data
+ * @throws {QueueNotFoundError} If the queue does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const timeseries = await getQueueTimeSeries(client, 'order-processing', {
+ *   granularity: 'hour',
+ *   start: '2026-01-14T00:00:00Z',
+ * });
+ * for (const point of timeseries.series) {
+ *   console.log(`${point.timestamp}: ${point.throughput} msg/h`);
+ * }
+ * ```
+ */
+export async function getQueueTimeSeries(
+	client: APIClient,
+	name: string,
+	options?: AnalyticsOptions
+): Promise<TimeSeriesData> {
+	validateQueueName(name);
+	const queryString = buildAnalyticsQuery(options);
+	const url = queueApiPathWithQuery('analytics/timeseries', queryString, name);
+	const resp = await client.get(
+		url,
+		TimeSeriesResponseSchema,
+		undefined,
+		buildQueueHeaders(options?.orgId)
+	);
+
+	if (resp.success) {
+		return resp.data.timeseries;
+	}
+
+	if (resp.message?.includes('not found')) {
+		throw new QueueNotFoundError({
+			queueName: name,
+			message: resp.message,
+		});
+	}
+
+	throw new QueueError({
+		queueName: name,
+		message: resp.message || 'Failed to get queue time series',
+	});
+}
+
+/**
+ * Stream real-time analytics for all queues via SSE.
+ *
+ * Returns an async iterator that yields stats events at the specified interval.
+ * The connection stays open until the iterator is closed or an error occurs.
+ *
+ * @param client - The API client instance
+ * @param options - Stream options (interval, orgId)
+ * @returns Async iterator of SSE stats events
+ *
+ * @example
+ * ```typescript
+ * const stream = streamOrgAnalytics(client, { interval: 5 });
+ * for await (const event of stream) {
+ *   console.log(`Backlog: ${event.backlog}, Throughput: ${event.throughput_1m}/min`);
+ * }
+ * ```
+ */
+export async function* streamOrgAnalytics(
+	client: APIClient,
+	options?: StreamAnalyticsOptions
+): AsyncGenerator<SSEStatsEvent, void, unknown> {
+	const params = new URLSearchParams();
+	if (options?.interval) params.set('interval', String(options.interval));
+	const queryString = params.toString() || undefined;
+
+	const url = queueApiPathWithQuery('analytics/stream', queryString);
+
+	yield* streamSSE(client, url, options?.orgId);
+}
+
+/**
+ * Stream real-time analytics for a specific queue via SSE.
+ *
+ * Returns an async iterator that yields stats events at the specified interval.
+ *
+ * @param client - The API client instance
+ * @param name - The queue name
+ * @param options - Stream options (interval, orgId)
+ * @returns Async iterator of SSE stats events
+ *
+ * @example
+ * ```typescript
+ * const stream = streamQueueAnalytics(client, 'order-processing', { interval: 5 });
+ * for await (const event of stream) {
+ *   console.log(`Backlog: ${event.backlog}, In-flight: ${event.messages_in_flight}`);
+ * }
+ * ```
+ */
+export async function* streamQueueAnalytics(
+	client: APIClient,
+	name: string,
+	options?: StreamAnalyticsOptions
+): AsyncGenerator<SSEStatsEvent, void, unknown> {
+	validateQueueName(name);
+
+	const params = new URLSearchParams();
+	if (options?.interval) params.set('interval', String(options.interval));
+	const queryString = params.toString() || undefined;
+
+	const url = queueApiPathWithQuery('analytics/stream', queryString, name);
+
+	yield* streamSSE(client, url, options?.orgId, name);
+}
+
+/**
+ * Internal helper to stream SSE events from a URL.
+ * Uses rawGet for streaming response access.
+ */
+async function* streamSSE(
+	client: APIClient,
+	url: string,
+	orgId?: string,
+	queueName?: string
+): AsyncGenerator<SSEStatsEvent, void, unknown> {
+	const response = await client.rawGet(url, undefined, buildQueueHeaders(orgId));
+
+	if (!response.ok) {
+		if (response.status === 404 && queueName) {
+			throw new QueueNotFoundError({ queueName });
+		}
+		throw new QueueError({
+			message: `SSE connection failed: ${response.status} ${response.statusText}`,
+		});
+	}
+
+	const reader = response.body?.getReader();
+	if (!reader) {
+		throw new QueueError({ message: 'No response body for SSE stream' });
+	}
+
+	const decoder = new TextDecoder();
+	let buffer = '';
+
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+
+			buffer += decoder.decode(value, { stream: true });
+			const lines = buffer.split('\n');
+			buffer = lines.pop() || '';
+
+			for (const line of lines) {
+				if (line.startsWith('data: ')) {
+					const jsonStr = line.slice(6).trim();
+					if (jsonStr && jsonStr !== '{}') {
+						try {
+							const parsed = JSON.parse(jsonStr);
+							const event = SSEStatsEventSchema.parse(parsed);
+							yield event;
+						} catch {
+							// Skip malformed events
+						}
+					}
+				}
+			}
+		}
+	} finally {
+		await reader.cancel();
+		reader.releaseLock();
+	}
+}

package/src/api/queue/destinations.ts

@@ -0,0 +1,321 @@
+import { z } from 'zod';
+import { APIClient, APIResponseSchema, APIResponseSchemaNoData, APIError } from '../api';
+import {
+	DestinationSchema,
+	type Destination,
+	type CreateDestinationRequest,
+	type UpdateDestinationRequest,
+	type QueueApiOptions,
+	CreateDestinationRequestSchema,
+	UpdateDestinationRequestSchema,
+} from './types';
+import {
+	QueueError,
+	QueueNotFoundError,
+	DestinationNotFoundError,
+	DestinationAlreadyExistsError,
+	queueApiPath,
+	buildQueueHeaders,
+} from './util';
+import { validateQueueName, validateDestinationId, validateDestinationConfig } from './validation';
+
+const DestinationResponseSchema = APIResponseSchema(z.object({ destination: DestinationSchema }));
+const DestinationsListResponseSchema = APIResponseSchema(
+	z.object({
+		destinations: z.array(DestinationSchema),
+	})
+);
+const DeleteDestinationResponseSchema = APIResponseSchemaNoData();
+
+/**
+ * Create a destination for a queue.
+ *
+ * Destinations are webhook endpoints that automatically receive messages when
+ * they are published to a queue. When a message is published, it will be
+ * delivered via HTTP POST to all active destinations configured for that queue.
+ *
+ * @param client - The API client instance
+ * @param queueName - The name of the queue to add the destination to
+ * @param params - Destination configuration including URL and optional settings
+ * @returns The created destination with assigned ID
+ * @throws {QueueValidationError} If validation fails (invalid queue name or config)
+ * @throws {QueueNotFoundError} If the queue does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const destination = await createDestination(client, 'order-events', {
+ *   url: 'https://api.example.com/webhooks/orders',
+ *   config: {
+ *     retry_attempts: 3,
+ *     timeout_seconds: 30,
+ *   },
+ * });
+ * console.log(`Created destination ${destination.id}`);
+ * ```
+ */
+export async function createDestination(
+	client: APIClient,
+	queueName: string,
+	params: CreateDestinationRequest,
+	options?: QueueApiOptions
+): Promise<Destination> {
+	validateQueueName(queueName);
+	if (params.config) {
+		validateDestinationConfig(params.config);
+	}
+
+	const url = queueApiPath('destinations/create', queueName);
+
+	try {
+		const resp = await client.post(
+			url,
+			params,
+			DestinationResponseSchema,
+			CreateDestinationRequestSchema,
+			undefined,
+			buildQueueHeaders(options?.orgId)
+		);
+
+		if (resp.success) {
+			return resp.data.destination;
+		}
+
+		if (resp.message?.includes('queue') && resp.message?.includes('not found')) {
+			throw new QueueNotFoundError({
+				queueName,
+				message: resp.message,
+			});
+		}
+
+		if (resp.message?.includes('already exists')) {
+			throw new DestinationAlreadyExistsError({
+				queueName,
+				url: params.config?.url,
+				message: `A destination with URL "${params.config?.url}" already exists for queue "${queueName}"`,
+			});
+		}
+
+		throw new QueueError({
+			queueName,
+			message: resp.message || 'Failed to create destination',
+		});
+	} catch (error) {
+		if (error instanceof APIError) {
+			const message = error.message || '';
+			if (message.includes('already exists')) {
+				throw new DestinationAlreadyExistsError({
+					queueName,
+					url: params.config?.url,
+					message: `A destination with URL "${params.config?.url}" already exists for queue "${queueName}"`,
+				});
+			}
+			if (message.includes('queue') && message.includes('not found')) {
+				throw new QueueNotFoundError({
+					queueName,
+					message,
+				});
+			}
+			throw new QueueError({
+				queueName,
+				message: message || 'Failed to create destination',
+			});
+		}
+		throw error;
+	}
+}
+
+/**
+ * List all destinations for a queue.
+ *
+ * Retrieves all webhook destinations configured for a queue. Each destination
+ * represents an endpoint that receives messages when they are published.
+ *
+ * @param client - The API client instance
+ * @param queueName - The name of the queue
+ * @returns Array of destinations configured for the queue
+ * @throws {QueueValidationError} If validation fails (invalid queue name)
+ * @throws {QueueNotFoundError} If the queue does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const destinations = await listDestinations(client, 'order-events');
+ * for (const dest of destinations) {
+ *   console.log(`Destination ${dest.id}: ${dest.url} (${dest.enabled ? 'enabled' : 'disabled'})`);
+ * }
+ * ```
+ */
+export async function listDestinations(
+	client: APIClient,
+	queueName: string,
+	options?: QueueApiOptions
+): Promise<Destination[]> {
+	validateQueueName(queueName);
+	const url = queueApiPath('destinations/list', queueName);
+	const resp = await client.get(
+		url,
+		DestinationsListResponseSchema,
+		undefined,
+		buildQueueHeaders(options?.orgId)
+	);
+
+	if (resp.success) {
+		return resp.data.destinations;
+	}
+
+	if (resp.message?.includes('not found')) {
+		throw new QueueNotFoundError({
+			queueName,
+			message: resp.message,
+		});
+	}
+
+	throw new QueueError({
+		queueName,
+		message: resp.message || 'Failed to list destinations',
+	});
+}
+
+/**
+ * Update a destination's configuration.
+ *
+ * Modifies an existing destination's settings such as URL, enabled status,
+ * or retry configuration. Only the fields provided in params will be updated.
+ *
+ * @param client - The API client instance
+ * @param queueName - The name of the queue
+ * @param destinationId - The destination ID to update (prefixed with dest_)
+ * @param params - Fields to update (partial update supported)
+ * @returns The updated destination
+ * @throws {QueueValidationError} If validation fails (invalid queue name, destination ID, or config)
+ * @throws {DestinationNotFoundError} If the destination does not exist
+ * @throws {QueueNotFoundError} If the queue does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * // Disable a destination temporarily
+ * const updated = await updateDestination(client, 'order-events', 'dest_abc123', {
+ *   enabled: false,
+ * });
+ *
+ * // Update URL and retry settings
+ * const updated = await updateDestination(client, 'order-events', 'dest_abc123', {
+ *   url: 'https://api.example.com/v2/webhooks/orders',
+ *   config: {
+ *     retry_attempts: 5,
+ *   },
+ * });
+ * ```
+ */
+export async function updateDestination(
+	client: APIClient,
+	queueName: string,
+	destinationId: string,
+	params: UpdateDestinationRequest,
+	options?: QueueApiOptions
+): Promise<Destination> {
+	validateQueueName(queueName);
+	validateDestinationId(destinationId);
+	if (params.config) {
+		validateDestinationConfig(params.config);
+	}
+
+	const url = queueApiPath('destinations/update', queueName, destinationId);
+	const resp = await client.patch(
+		url,
+		params,
+		DestinationResponseSchema,
+		UpdateDestinationRequestSchema,
+		undefined,
+		buildQueueHeaders(options?.orgId)
+	);
+
+	if (resp.success) {
+		return resp.data.destination;
+	}
+
+	if (resp.message?.includes('destination') && resp.message?.includes('not found')) {
+		throw new DestinationNotFoundError({
+			queueName,
+			destinationId,
+			message: resp.message,
+		});
+	}
+
+	if (resp.message?.includes('queue') && resp.message?.includes('not found')) {
+		throw new QueueNotFoundError({
+			queueName,
+			message: resp.message,
+		});
+	}
+
+	throw new QueueError({
+		queueName,
+		message: resp.message || 'Failed to update destination',
+	});
+}
+
+/**
+ * Delete a destination from a queue.
+ *
+ * Permanently removes a webhook destination. Messages will no longer be
+ * delivered to this endpoint. This action cannot be undone.
+ *
+ * @param client - The API client instance
+ * @param queueName - The name of the queue
+ * @param destinationId - The destination ID to delete (prefixed with dest_)
+ * @returns void
+ * @throws {QueueValidationError} If validation fails (invalid queue name or destination ID)
+ * @throws {DestinationNotFoundError} If the destination does not exist
+ * @throws {QueueNotFoundError} If the queue does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * await deleteDestination(client, 'order-events', 'dest_abc123');
+ * console.log('Destination deleted');
+ * ```
+ */
+export async function deleteDestination(
+	client: APIClient,
+	queueName: string,
+	destinationId: string,
+	options?: QueueApiOptions
+): Promise<void> {
+	validateQueueName(queueName);
+	validateDestinationId(destinationId);
+
+	const url = queueApiPath('destinations/delete', queueName, destinationId);
+	const resp = await client.delete(
+		url,
+		DeleteDestinationResponseSchema,
+		undefined,
+		buildQueueHeaders(options?.orgId)
+	);
+
+	if (resp.success) {
+		return;
+	}
+
+	if (resp.message?.includes('destination') && resp.message?.includes('not found')) {
+		throw new DestinationNotFoundError({
+			queueName,
+			destinationId,
+			message: resp.message,
+		});
+	}
+
+	if (resp.message?.includes('queue') && resp.message?.includes('not found')) {
+		throw new QueueNotFoundError({
+			queueName,
+			message: resp.message,
+		});
+	}
+
+	throw new QueueError({
+		queueName,
+		message: resp.message || 'Failed to delete destination',
+	});
+}