@agentuity/core 1.0.32 → 1.0.34

package/src/services/queue/destinations.ts

@@ -0,0 +1,329 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema, APIResponseSchemaNoData } from '../api.ts';
+import {
+	type CreateDestinationRequest,
+	CreateDestinationRequestSchema,
+	type DeliveryLog,
+	DeliveryLogSchema,
+	type Destination,
+	DestinationSchema,
+	type ListDeliveryLogsRequest,
+	type QueueApiOptions,
+	type UpdateDestinationRequest,
+	UpdateDestinationRequestSchema,
+} from './types.ts';
+import { buildQueueHeaders, QueueError, queueApiPath, withQueueErrorHandling } from './util.ts';
+import {
+	validateDestinationConfig,
+	validateDestinationId,
+	validateQueueName,
+} from './validation.ts';
+
+export const DestinationResponseSchema = APIResponseSchema(
+	z.object({ destination: DestinationSchema })
+);
+export const DestinationsListResponseSchema = APIResponseSchema(
+	z.object({
+		destinations: z.array(DestinationSchema),
+	})
+);
+export 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);
+	const resp = await withQueueErrorHandling(
+		() =>
+			client.post(
+				url,
+				params,
+				DestinationResponseSchema,
+				CreateDestinationRequestSchema,
+				undefined,
+				buildQueueHeaders(options?.orgId)
+			),
+		{ queueName, destinationUrl: params.config?.url }
+	);
+
+	if (resp.success) {
+		return resp.data.destination;
+	}
+
+	throw new QueueError({
+		queueName,
+		message: resp.message || 'Failed to create destination',
+	});
+}
+
+/**
+ * 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 withQueueErrorHandling(
+		() =>
+			client.get(
+				url,
+				DestinationsListResponseSchema,
+				undefined,
+				buildQueueHeaders(options?.orgId)
+			),
+		{ queueName }
+	);
+
+	if (resp.success) {
+		return resp.data.destinations;
+	}
+
+	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 qdest_)
+ * @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', 'qdest_abc123', {
+ *   enabled: false,
+ * });
+ *
+ * // Update URL and retry settings
+ * const updated = await updateDestination(client, 'order-events', 'qdest_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 withQueueErrorHandling(
+		() =>
+			client.patch(
+				url,
+				params,
+				DestinationResponseSchema,
+				UpdateDestinationRequestSchema,
+				undefined,
+				buildQueueHeaders(options?.orgId)
+			),
+		{ queueName, destinationId }
+	);
+
+	if (resp.success) {
+		return resp.data.destination;
+	}
+
+	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 qdest_)
+ * @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', 'qdest_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 withQueueErrorHandling(
+		() =>
+			client.delete(
+				url,
+				DeleteDestinationResponseSchema,
+				undefined,
+				buildQueueHeaders(options?.orgId)
+			),
+		{ queueName, destinationId }
+	);
+
+	if (resp.success) {
+		return;
+	}
+
+	throw new QueueError({
+		queueName,
+		message: resp.message || 'Failed to delete destination',
+	});
+}
+
+export const DeliveryLogsListResponseSchema = APIResponseSchema(
+	z.object({
+		deliveries: z.array(DeliveryLogSchema),
+	})
+);
+
+/**
+ * List delivery attempts for a queue destination.
+ *
+ * Returns the most recent delivery attempts to a configured webhook destination,
+ * including HTTP status codes, timing, and error details for failed deliveries.
+ *
+ * @param client - The API client instance
+ * @param queueName - The name of the queue
+ * @param destinationId - The destination ID (prefixed with qdest_)
+ * @param params - Optional filtering and pagination
+ * @returns Array of delivery log entries
+ * @throws {QueueValidationError} If validation fails
+ * @throws {DestinationNotFoundError} If the destination does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const deliveries = await listDestinationDeliveries(client, 'order-events', 'qdest_abc123', {
+ *   limit: 50,
+ *   status: 'failed',
+ * });
+ * ```
+ */
+export async function listDestinationDeliveries(
+	client: APIClient,
+	queueName: string,
+	destinationId: string,
+	params?: ListDeliveryLogsRequest,
+	options?: QueueApiOptions
+): Promise<DeliveryLog[]> {
+	validateQueueName(queueName);
+	validateDestinationId(destinationId);
+
+	const queryParts: string[] = [];
+	if (params?.limit !== undefined) queryParts.push(`limit=${params.limit}`);
+	if (params?.offset !== undefined) queryParts.push(`offset=${params.offset}`);
+	if (params?.status) queryParts.push(`status=${params.status}`);
+	const queryString = queryParts.length > 0 ? `?${queryParts.join('&')}` : '';
+
+	const url = queueApiPath('destinations/deliveries', queueName, destinationId) + queryString;
+	const resp = await withQueueErrorHandling(
+		() =>
+			client.get(
+				url,
+				DeliveryLogsListResponseSchema,
+				undefined,
+				buildQueueHeaders(options?.orgId)
+			),
+		{ queueName, destinationId }
+	);
+
+	if (resp.success) {
+		return resp.data.deliveries;
+	}
+
+	throw new QueueError({
+		queueName,
+		message: resp.message || 'Failed to list destination deliveries',
+	});
+}

package/src/services/queue/dlq.ts

@@ -0,0 +1,243 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema, APIResponseSchemaNoData } from '../api.ts';
+import {
+	type DeadLetterMessage,
+	DeadLetterMessageSchema,
+	type ListDlqRequest,
+	type Message,
+	MessageSchema,
+	type QueueApiOptions,
+} from './types.ts';
+import {
+	buildQueueHeaders,
+	QueueError,
+	queueApiPath,
+	queueApiPathWithQuery,
+	withQueueErrorHandling,
+} from './util.ts';
+import {
+	validateLimit,
+	validateMessageId,
+	validateOffset,
+	validateQueueName,
+} from './validation.ts';
+
+export const DlqListResponseSchema = APIResponseSchema(
+	z.object({
+		messages: z.array(DeadLetterMessageSchema),
+		total: z.number().optional(),
+	})
+);
+export const ReplayDlqResponseSchema = APIResponseSchema(z.object({ message: MessageSchema }));
+export const DeleteDlqResponseSchema = APIResponseSchemaNoData();
+
+/**
+ * List messages in the dead letter queue.
+ *
+ * Retrieves messages that failed processing after exhausting all retries.
+ * These messages can be inspected, replayed back to the main queue, or deleted.
+ *
+ * @param client - The API client instance
+ * @param queueName - The name of the queue whose DLQ to list
+ * @param params - Optional pagination parameters (limit, offset)
+ * @returns Object containing dead letter messages and optional total count
+ * @throws {QueueValidationError} If validation fails (invalid queue name, limit, or offset)
+ * @throws {QueueNotFoundError} If the queue does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * // List first 10 dead letter messages
+ * const result = await listDeadLetterMessages(client, 'order-queue', { limit: 10 });
+ * for (const msg of result.messages) {
+ *   console.log(`Failed message ${msg.id}: ${msg.failure_reason}`);
+ *   console.log(`Attempts: ${msg.delivery_attempts}, Moved at: ${msg.moved_at}`);
+ * }
+ * ```
+ */
+export async function listDeadLetterMessages(
+	client: APIClient,
+	queueName: string,
+	params?: ListDlqRequest,
+	options?: QueueApiOptions
+): Promise<{ messages: DeadLetterMessage[]; total?: number }> {
+	validateQueueName(queueName);
+	if (params?.limit !== undefined) {
+		validateLimit(params.limit);
+	}
+	if (params?.offset !== undefined) {
+		validateOffset(params.offset);
+	}
+
+	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 = queueApiPathWithQuery('dlq/list', queryString || undefined, queueName);
+	const resp = await withQueueErrorHandling(
+		() => client.get(url, DlqListResponseSchema, undefined, buildQueueHeaders(options?.orgId)),
+		{ queueName }
+	);
+
+	if (resp.success) {
+		return { messages: resp.data.messages, total: resp.data.total };
+	}
+
+	throw new QueueError({
+		queueName,
+		message: resp.message || 'Failed to list dead letter messages',
+	});
+}
+
+/**
+ * Replay a dead letter message back to the main queue.
+ *
+ * Moves a message from the dead letter queue back to the main queue for
+ * reprocessing. The message state is reset to pending and retry count is
+ * preserved. Use this after fixing the underlying issue that caused the failure.
+ *
+ * @param client - The API client instance
+ * @param queueName - The name of the queue
+ * @param messageId - The message ID to replay (prefixed with msg_)
+ * @returns The replayed message with updated state
+ * @throws {QueueValidationError} If validation fails (invalid queue name or message ID)
+ * @throws {MessageNotFoundError} If the message does not exist in the DLQ
+ * @throws {QueueNotFoundError} If the queue does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * // Replay a failed message after fixing the bug
+ * const message = await replayDeadLetterMessage(client, 'order-queue', 'msg_abc123');
+ * console.log(`Replayed message ${message.id}, now in state: ${message.state}`);
+ * ```
+ */
+export async function replayDeadLetterMessage(
+	client: APIClient,
+	queueName: string,
+	messageId: string,
+	options?: QueueApiOptions
+): Promise<Message> {
+	validateQueueName(queueName);
+	validateMessageId(messageId);
+
+	const url = queueApiPath('dlq/replay', queueName, messageId);
+	const resp = await withQueueErrorHandling(
+		() =>
+			client.post(
+				url,
+				undefined,
+				ReplayDlqResponseSchema,
+				undefined,
+				undefined,
+				buildQueueHeaders(options?.orgId)
+			),
+		{ queueName, messageId }
+	);
+
+	if (resp.success) {
+		return resp.data.message;
+	}
+
+	throw new QueueError({
+		queueName,
+		message: resp.message || 'Failed to replay dead letter message',
+	});
+}
+
+/**
+ * Purge all messages from a dead letter queue.
+ *
+ * Permanently deletes all messages in the dead letter queue. This operation
+ * cannot be undone. Use with caution - consider reviewing or exporting
+ * messages before purging.
+ *
+ * @param client - The API client instance
+ * @param queueName - The name of the queue whose DLQ to purge
+ * @returns void
+ * @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
+ * // Purge all dead letter messages after investigation
+ * await purgeDeadLetter(client, 'order-queue');
+ * console.log('All dead letter messages have been deleted');
+ * ```
+ */
+export async function purgeDeadLetter(
+	client: APIClient,
+	queueName: string,
+	options?: QueueApiOptions
+): Promise<void> {
+	validateQueueName(queueName);
+	const url = queueApiPath('dlq/purge', queueName);
+	const resp = await withQueueErrorHandling(
+		() =>
+			client.delete(url, DeleteDlqResponseSchema, undefined, buildQueueHeaders(options?.orgId)),
+		{ queueName }
+	);
+
+	if (resp.success) {
+		return;
+	}
+
+	throw new QueueError({
+		queueName,
+		message: resp.message || 'Failed to purge dead letter queue',
+	});
+}
+
+/**
+ * Delete a specific message from the dead letter queue.
+ *
+ * Permanently removes a single message from the dead letter queue.
+ * Use this when you've determined that a specific failed message
+ * should not be retried and can be discarded.
+ *
+ * @param client - The API client instance
+ * @param queueName - The name of the queue
+ * @param messageId - The message ID to delete (prefixed with msg_)
+ * @returns void
+ * @throws {QueueValidationError} If validation fails (invalid queue name or message ID)
+ * @throws {MessageNotFoundError} If the message does not exist in the DLQ
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * // Delete a message that cannot be recovered
+ * await deleteDeadLetterMessage(client, 'order-queue', 'msg_abc123');
+ * console.log('Dead letter message deleted');
+ * ```
+ */
+export async function deleteDeadLetterMessage(
+	client: APIClient,
+	queueName: string,
+	messageId: string,
+	options?: QueueApiOptions
+): Promise<void> {
+	validateQueueName(queueName);
+	validateMessageId(messageId);
+
+	const url = queueApiPath('dlq/delete', queueName, messageId);
+	const resp = await withQueueErrorHandling(
+		() =>
+			client.delete(url, DeleteDlqResponseSchema, undefined, buildQueueHeaders(options?.orgId)),
+		{ queueName, messageId }
+	);
+
+	if (resp.success) {
+		return;
+	}
+
+	throw new QueueError({
+		queueName,
+		message: resp.message || 'Failed to delete dead letter message',
+	});
+}