@agentuity/server 1.0.31 → 1.0.33

package/src/api/queue/destinations.ts

@@ -1,259 +0,0 @@
-import { z } from 'zod';
-import { type APIClient, APIResponseSchema, APIResponseSchemaNoData } from '../api.ts';
-import {
-	type CreateDestinationRequest,
-	CreateDestinationRequestSchema,
-	type Destination,
-	DestinationSchema,
-	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 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 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 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 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',
-	});
-}

package/src/api/queue/dlq.ts

@@ -1,243 +0,0 @@
-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',
-	});
-}