@agentuity/core 1.0.32 → 1.0.33

package/src/api/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',
+	});
+}

package/src/api/queue/index.ts

@@ -0,0 +1,308 @@
+/**
+ * @module queue
+ *
+ * Queue API client for managing message queues, messages, destinations, and dead letter queues.
+ *
+ * This module provides a complete client for the Agentuity Queue API, supporting:
+ * - **Queue Management**: Create, read, update, and delete message queues
+ * - **Message Operations**: Publish, consume, acknowledge, and manage messages
+ * - **Destinations**: Configure webhook endpoints for automatic message delivery
+ * - **Dead Letter Queue**: Handle failed messages that exceeded retry limits
+ *
+ * @example Basic Queue Operations
+ * ```typescript
+ * import { createQueue, publishMessage, receiveMessage, ackMessage } from '@agentuity/server';
+ *
+ * // Create a worker queue
+ * const queue = await createQueue(client, {
+ *   name: 'order-processing',
+ *   queue_type: 'worker',
+ * });
+ *
+ * // Publish a message
+ * await publishMessage(client, 'order-processing', {
+ *   payload: { orderId: 123 },
+ * });
+ *
+ * // Receive and acknowledge a message
+ * const message = await receiveMessage(client, 'order-processing');
+ * if (message) {
+ *   // Process the message...
+ *   await ackMessage(client, 'order-processing', message.id);
+ * }
+ * ```
+ *
+ * @example Webhook Destinations
+ * ```typescript
+ * import { createDestination } from '@agentuity/server';
+ *
+ * // Messages are automatically delivered to this URL
+ * await createDestination(client, 'order-processing', {
+ *   destination_type: 'http',
+ *   config: { url: 'https://api.example.com/webhook' },
+ * });
+ * ```
+ */
+
+// ============================================================================
+// Types & Schemas
+// ============================================================================
+
+export {
+	type AnalyticsGranularity,
+	// Analytics types
+	AnalyticsGranularitySchema,
+	type AnalyticsOptions,
+	type BatchPublishMessagesRequest,
+	BatchPublishMessagesRequestSchema,
+	type ConsumeMessagesRequest,
+	ConsumeMessagesRequestSchema,
+	type CreateDestinationRequest,
+	CreateDestinationRequestSchema,
+	type CreateQueueRequest,
+	CreateQueueRequestSchema,
+	type CreateSourceRequest,
+	CreateSourceRequestSchema,
+	type DeadLetterMessage,
+	DeadLetterMessageSchema,
+	type Destination,
+	type DestinationAnalytics,
+	DestinationAnalyticsSchema,
+	DestinationSchema,
+	type DestinationStats,
+	DestinationStatsSchema,
+	type DestinationType,
+	DestinationTypeSchema,
+	type HttpDestinationConfig,
+	HttpDestinationConfigSchema,
+	type LatencyStats,
+	LatencyStatsSchema,
+	type ListDlqRequest,
+	ListDlqRequestSchema,
+	type ListMessagesRequest,
+	ListMessagesRequestSchema,
+	type ListQueuesRequest,
+	ListQueuesRequestSchema,
+	type Message,
+	MessageSchema,
+	type MessageState,
+	MessageStateSchema,
+	type OrgAnalytics,
+	OrgAnalyticsSchema,
+	type OrgAnalyticsSummary,
+	OrgAnalyticsSummarySchema,
+	type PublishMessageRequest,
+	PublishMessageRequestSchema,
+	type Queue,
+	type QueueAnalytics,
+	QueueAnalyticsSchema,
+	type QueueApiOptions,
+	type QueueCurrentStats,
+	QueueCurrentStatsSchema,
+	type QueuePeriodStats,
+	QueuePeriodStatsSchema,
+	QueueSchema,
+	type QueueSettings,
+	QueueSettingsSchema,
+	type QueueStats,
+	QueueStatsSchema,
+	type QueueSummary,
+	QueueSummarySchema,
+	type QueueType,
+	QueueTypeSchema,
+	type Source,
+	type SourceAuthType,
+	// Source types
+	SourceAuthTypeSchema,
+	SourceSchema,
+	type SSEStatsEvent,
+	SSEStatsEventSchema,
+	type StreamAnalyticsOptions,
+	type TimePeriod,
+	TimePeriodSchema,
+	type TimeSeriesData,
+	TimeSeriesDataSchema,
+	type TimeSeriesPoint,
+	TimeSeriesPointSchema,
+	type UpdateDestinationRequest,
+	UpdateDestinationRequestSchema,
+	type UpdateQueueRequest,
+	UpdateQueueRequestSchema,
+	type UpdateSourceRequest,
+	UpdateSourceRequestSchema,
+	type WebSocketAuthRequest,
+	WebSocketAuthRequestSchema,
+	type WebSocketAuthResponse,
+	WebSocketAuthResponseSchema,
+	type WebSocketMessage,
+	WebSocketMessageSchema,
+} from './types.ts';
+
+// ============================================================================
+// Errors
+// ============================================================================
+
+export {
+	DestinationAlreadyExistsError,
+	DestinationNotFoundError,
+	MessageNotFoundError,
+	QueueError,
+	QueueInvalidArgumentError,
+	QueueNotFoundError,
+	SourceAlreadyExistsError,
+	SourceNotFoundError,
+} from './util.ts';
+
+// ============================================================================
+// Queue Operations
+// ============================================================================
+
+export {
+	createQueue,
+	DeleteQueueResponseSchema,
+	deleteQueue,
+	getQueue,
+	listQueues,
+	pauseQueue,
+	QueueResponseSchema,
+	QueuesListResponseSchema,
+	resumeQueue,
+	updateQueue,
+} from './queues.ts';
+
+// ============================================================================
+// Message Operations
+// ============================================================================
+
+export {
+	AckNackResponseSchema,
+	ackMessage,
+	BatchPublishResponseSchema,
+	batchPublishMessages,
+	consumeMessages,
+	DeleteMessageResponseSchema,
+	deleteMessage,
+	getMessage,
+	getMessageByOffset,
+	getQueueHead,
+	getQueueTail,
+	listMessages,
+	MessageResponseSchema,
+	MessagesListResponseSchema,
+	nackMessage,
+	OffsetResponseSchema,
+	publishMessage,
+	ReceiveResponseSchema,
+	receiveMessage,
+	replayMessage,
+} from './messages.ts';
+
+// ============================================================================
+// Dead Letter Queue Operations
+// ============================================================================
+
+export {
+	DeleteDlqResponseSchema,
+	DlqListResponseSchema,
+	deleteDeadLetterMessage,
+	listDeadLetterMessages,
+	purgeDeadLetter,
+	ReplayDlqResponseSchema,
+	replayDeadLetterMessage,
+} from './dlq.ts';
+
+// ============================================================================
+// Destination Operations
+// ============================================================================
+
+export {
+	createDestination,
+	DeleteDestinationResponseSchema,
+	DestinationResponseSchema,
+	DestinationsListResponseSchema,
+	deleteDestination,
+	listDestinations,
+	updateDestination,
+} from './destinations.ts';
+
+// ============================================================================
+// Source Operations
+// ============================================================================
+
+export {
+	createSource,
+	DeleteSourceResponseSchema,
+	deleteSource,
+	getSource,
+	listSources,
+	SourceResponseSchema,
+	SourcesListResponseSchema,
+	updateSource,
+} from './sources.ts';
+
+// ============================================================================
+// Analytics Operations
+// ============================================================================
+
+export {
+	getOrgAnalytics,
+	getQueueAnalytics,
+	getQueueTimeSeries,
+	OrgAnalyticsResponseSchema,
+	QueueAnalyticsResponseSchema,
+	streamOrgAnalytics,
+	streamQueueAnalytics,
+	TimeSeriesResponseSchema,
+} from './analytics.ts';
+
+// ============================================================================
+// WebSocket Operations
+// ============================================================================
+
+export {
+	createQueueWebSocket,
+	subscribeToQueue,
+	type QueueWebSocketOptions,
+	type QueueWebSocketConnection,
+	type QueueWebSocketState,
+	type SubscribeToQueueOptions,
+} from './websocket.ts';
+
+// ============================================================================
+// Validation Utilities
+// ============================================================================
+
+export {
+	MAX_BATCH_SIZE,
+	MAX_DESCRIPTION_LENGTH,
+	MAX_IDEMPOTENCY_KEY_LENGTH,
+	MAX_IN_FLIGHT,
+	MAX_METADATA_SIZE,
+	MAX_PARTITION_KEY_LENGTH,
+	MAX_PAYLOAD_SIZE,
+	MAX_QUEUE_NAME_LENGTH,
+	MAX_RETRIES,
+	MAX_SOURCE_NAME_LENGTH,
+	MAX_VISIBILITY_TIMEOUT,
+	MIN_QUEUE_NAME_LENGTH,
+	QueueValidationError,
+	validateBatchSize,
+	validateDescription,
+	validateDestinationConfig,
+	validateDestinationId,
+	validateIdempotencyKey,
+	validateLimit,
+	validateMaxInFlight,
+	validateMaxRetries,
+	validateMessageId,
+	validateOffset,
+	validatePartitionKey,
+	validatePayload,
+	validateQueueName,
+	validateQueueType,
+	validateSourceId,
+	validateSourceName,
+	validateTTL,
+	validateVisibilityTimeout,
+	validateWebhookUrl,
+} from './validation.ts';