@agentuity/core 1.0.32 → 1.0.34

package/src/services/queue/queues.ts

@@ -0,0 +1,460 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema, APIResponseSchemaNoData } from '../api.ts';
+import {
+	type CreateQueueRequest,
+	CreateQueueRequestSchema,
+	type ListQueuesRequest,
+	type Queue,
+	type QueueApiOptions,
+	QueueSchema,
+	type UpdateQueueRequest,
+	UpdateQueueRequestSchema,
+} from './types.ts';
+import {
+	buildQueueHeaders,
+	QueueError,
+	queueApiPath,
+	queueApiPathWithQuery,
+	withQueueErrorHandling,
+} from './util.ts';
+import {
+	validateDescription,
+	validateLimit,
+	validateMaxInFlight,
+	validateMaxRetries,
+	validateOffset,
+	validateQueueName,
+	validateQueueType,
+	validateTTL,
+	validateVisibilityTimeout,
+} from './validation.ts';
+
+export const QueueResponseSchema = APIResponseSchema(z.object({ queue: QueueSchema }));
+export const QueuesListResponseSchema = APIResponseSchema(
+	z.object({
+		queues: z.array(QueueSchema),
+		total: z.number().optional(),
+	})
+);
+export const DeleteQueueResponseSchema = APIResponseSchemaNoData();
+
+/**
+ * Create a new message queue.
+ *
+ * Creates a queue with the specified type and settings. The queue name is optional
+ * and will be auto-generated if not provided.
+ *
+ * @param client - The API client instance
+ * @param params - Queue creation parameters
+ * @returns The created queue
+ * @throws {QueueValidationError} If validation fails
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * // Create a worker queue with custom settings
+ * const queue = await createQueue(client, {
+ *   name: 'order-processing',
+ *   queue_type: 'worker',
+ *   description: 'Processes customer orders',
+ *   settings: {
+ *     default_max_retries: 3,
+ *     default_visibility_timeout_seconds: 60,
+ *   },
+ * });
+ * console.log(`Created queue: ${queue.id}`);
+ * ```
+ */
+export async function createQueue(
+	client: APIClient,
+	params: CreateQueueRequest,
+	options?: QueueApiOptions
+): Promise<Queue> {
+	// Validate before sending to API
+	validateQueueType(params.queue_type);
+	if (params.name) {
+		validateQueueName(params.name);
+	}
+	if (params.description) {
+		validateDescription(params.description);
+	}
+	// Validate settings if provided
+	if (params.settings) {
+		if (params.settings.default_ttl_seconds !== undefined) {
+			validateTTL(params.settings.default_ttl_seconds ?? undefined);
+		}
+		if (params.settings.default_visibility_timeout_seconds !== undefined) {
+			validateVisibilityTimeout(params.settings.default_visibility_timeout_seconds);
+		}
+		if (params.settings.default_max_retries !== undefined) {
+			validateMaxRetries(params.settings.default_max_retries);
+		}
+		if (params.settings.max_in_flight_per_client !== undefined) {
+			validateMaxInFlight(params.settings.max_in_flight_per_client);
+		}
+	}
+
+	const url = queueApiPath('create');
+	const resp = await client.post(
+		url,
+		params,
+		QueueResponseSchema,
+		CreateQueueRequestSchema,
+		undefined,
+		buildQueueHeaders(options?.orgId)
+	);
+
+	if (resp.success) {
+		return resp.data.queue;
+	}
+
+	throw new QueueError({
+		message: resp.message || 'Failed to create queue',
+	});
+}
+
+/**
+ * Get a queue by name.
+ *
+ * Retrieves the queue details including settings and statistics.
+ *
+ * @param client - The API client instance
+ * @param name - The queue name
+ * @returns The queue details
+ * @throws {QueueValidationError} If the queue name is invalid
+ * @throws {QueueNotFoundError} If the queue does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const queue = await getQueue(client, 'order-processing');
+ * console.log(`Queue has ${queue.stats?.message_count} messages`);
+ * ```
+ */
+export async function getQueue(
+	client: APIClient,
+	name: string,
+	options?: QueueApiOptions
+): Promise<Queue> {
+	validateQueueName(name);
+	const url = queueApiPath('get', name);
+	const resp = await withQueueErrorHandling(
+		() => client.get(url, QueueResponseSchema, undefined, buildQueueHeaders(options?.orgId)),
+		{ queueName: name }
+	);
+
+	if (resp.success) {
+		return resp.data.queue;
+	}
+
+	throw new QueueError({
+		queueName: name,
+		message: resp.message || 'Failed to get queue',
+	});
+}
+
+/**
+ * List all queues with optional pagination.
+ *
+ * @param client - The API client instance
+ * @param params - Optional pagination parameters
+ * @returns Object containing the list of queues and optional total count
+ * @throws {QueueValidationError} If pagination parameters are invalid
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * // List first 10 queues
+ * const { queues, total } = await listQueues(client, { limit: 10 });
+ * console.log(`Found ${total} queues`);
+ *
+ * // Paginate through all queues
+ * const { queues: page2 } = await listQueues(client, { limit: 10, offset: 10 });
+ * ```
+ */
+export async function listQueues(
+	client: APIClient,
+	params?: ListQueuesRequest,
+	options?: QueueApiOptions
+): Promise<{ queues: Queue[]; total?: number }> {
+	// Validate pagination params
+	if (params?.limit !== undefined) {
+		validateLimit(params.limit);
+	}
+	if (params?.offset !== undefined) {
+		validateOffset(params.offset);
+	}
+
+	// Validate filter params
+	if (params?.queue_type) {
+		const validTypes = ['worker', 'pubsub'];
+		if (!validTypes.includes(params.queue_type)) {
+			throw new QueueError({
+				message: `Invalid queue_type filter: '${params.queue_type}'. Must be one of: ${validTypes.join(', ')}`,
+			});
+		}
+	}
+	if (params?.status) {
+		const validStatuses = ['active', 'paused'];
+		if (!validStatuses.includes(params.status)) {
+			throw new QueueError({
+				message: `Invalid status filter: '${params.status}'. Must be one of: ${validStatuses.join(', ')}`,
+			});
+		}
+	}
+
+	const searchParams = new URLSearchParams();
+	if (params?.limit !== undefined) {
+		searchParams.set('limit', String(params.limit));
+	}
+	if (params?.offset !== undefined) {
+		searchParams.set('offset', String(params.offset));
+	}
+	if (params?.name) {
+		searchParams.set('name', params.name);
+	}
+	if (params?.queue_type) {
+		searchParams.set('queue_type', params.queue_type);
+	}
+	if (params?.status) {
+		searchParams.set('status', params.status);
+	}
+	if (params?.sort) {
+		searchParams.set('sort', params.sort);
+	}
+	if (params?.direction) {
+		searchParams.set('direction', params.direction);
+	}
+
+	const queryString = searchParams.toString();
+	const url = queueApiPathWithQuery('list', queryString || undefined);
+	const resp = await client.get(
+		url,
+		QueuesListResponseSchema,
+		undefined,
+		buildQueueHeaders(options?.orgId)
+	);
+
+	if (resp.success) {
+		return { queues: resp.data.queues, total: resp.data.total };
+	}
+
+	throw new QueueError({
+		message: resp.message || 'Failed to list queues',
+	});
+}
+
+/**
+ * Update an existing queue.
+ *
+ * Updates the queue description and/or settings. Only provided fields are updated.
+ *
+ * @param client - The API client instance
+ * @param name - The queue name
+ * @param params - Update parameters
+ * @returns The updated queue
+ * @throws {QueueValidationError} If validation fails
+ * @throws {QueueNotFoundError} If the queue does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const queue = await updateQueue(client, 'order-processing', {
+ *   description: 'Updated description',
+ *   settings: { default_max_retries: 5 },
+ * });
+ * ```
+ */
+export async function updateQueue(
+	client: APIClient,
+	name: string,
+	params: UpdateQueueRequest,
+	options?: QueueApiOptions
+): Promise<Queue> {
+	// Validate before sending to API
+	validateQueueName(name);
+	if (params.description) {
+		validateDescription(params.description);
+	}
+	// Validate settings if provided
+	if (params.settings) {
+		if (params.settings.default_ttl_seconds !== undefined) {
+			validateTTL(params.settings.default_ttl_seconds ?? undefined);
+		}
+		if (params.settings.default_visibility_timeout_seconds !== undefined) {
+			validateVisibilityTimeout(params.settings.default_visibility_timeout_seconds);
+		}
+		if (params.settings.default_max_retries !== undefined) {
+			validateMaxRetries(params.settings.default_max_retries);
+		}
+		if (params.settings.max_in_flight_per_client !== undefined) {
+			validateMaxInFlight(params.settings.max_in_flight_per_client);
+		}
+	}
+
+	const url = queueApiPath('update', name);
+	const resp = await withQueueErrorHandling(
+		() =>
+			client.patch(
+				url,
+				params,
+				QueueResponseSchema,
+				UpdateQueueRequestSchema,
+				undefined,
+				buildQueueHeaders(options?.orgId)
+			),
+		{ queueName: name }
+	);
+
+	if (resp.success) {
+		return resp.data.queue;
+	}
+
+	throw new QueueError({
+		queueName: name,
+		message: resp.message || 'Failed to update queue',
+	});
+}
+
+/**
+ * Delete a queue.
+ *
+ * Permanently deletes a queue and all its messages. This action cannot be undone.
+ *
+ * @param client - The API client instance
+ * @param name - The queue name
+ * @throws {QueueValidationError} If the queue name is invalid
+ * @throws {QueueNotFoundError} If the queue does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * await deleteQueue(client, 'order-processing');
+ * console.log('Queue deleted');
+ * ```
+ */
+export async function deleteQueue(
+	client: APIClient,
+	name: string,
+	options?: QueueApiOptions
+): Promise<void> {
+	validateQueueName(name);
+	const url = queueApiPath('delete', name);
+	const resp = await withQueueErrorHandling(
+		() =>
+			client.delete(
+				url,
+				DeleteQueueResponseSchema,
+				undefined,
+				buildQueueHeaders(options?.orgId)
+			),
+		{ queueName: name }
+	);
+
+	if (resp.success) {
+		return;
+	}
+
+	throw new QueueError({
+		queueName: name,
+		message: resp.message || 'Failed to delete queue',
+	});
+}
+
+/**
+ * Pause a queue.
+ *
+ * Pauses message processing for the queue. Messages can still be published
+ * but will not be delivered to consumers until the queue is resumed.
+ *
+ * @param client - The API client instance
+ * @param name - The queue name
+ * @returns The updated queue with paused_at timestamp
+ * @throws {QueueValidationError} If the queue name is invalid
+ * @throws {QueueNotFoundError} If the queue does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const queue = await pauseQueue(client, 'order-processing');
+ * console.log(`Queue paused at: ${queue.paused_at}`);
+ * ```
+ */
+export async function pauseQueue(
+	client: APIClient,
+	name: string,
+	options?: QueueApiOptions
+): Promise<Queue> {
+	validateQueueName(name);
+	const url = queueApiPath('pause', name);
+	const resp = await withQueueErrorHandling(
+		() =>
+			client.post(
+				url,
+				{},
+				QueueResponseSchema,
+				z.object({}),
+				undefined,
+				buildQueueHeaders(options?.orgId)
+			),
+		{ queueName: name }
+	);
+
+	if (resp.success) {
+		return resp.data.queue;
+	}
+
+	throw new QueueError({
+		queueName: name,
+		message: resp.message || 'Failed to pause queue',
+	});
+}
+
+/**
+ * Resume a paused queue.
+ *
+ * Resumes message processing for a paused queue. Consumers will start
+ * receiving messages again.
+ *
+ * @param client - The API client instance
+ * @param name - The queue name
+ * @returns The updated queue with paused_at cleared
+ * @throws {QueueValidationError} If the queue name is invalid
+ * @throws {QueueNotFoundError} If the queue does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const queue = await resumeQueue(client, 'order-processing');
+ * console.log(`Queue resumed, paused_at: ${queue.paused_at}`); // null
+ * ```
+ */
+export async function resumeQueue(
+	client: APIClient,
+	name: string,
+	options?: QueueApiOptions
+): Promise<Queue> {
+	validateQueueName(name);
+	const url = queueApiPath('resume', name);
+	const resp = await withQueueErrorHandling(
+		() =>
+			client.post(
+				url,
+				{},
+				QueueResponseSchema,
+				z.object({}),
+				undefined,
+				buildQueueHeaders(options?.orgId)
+			),
+		{ queueName: name }
+	);
+
+	if (resp.success) {
+		return resp.data.queue;
+	}
+
+	throw new QueueError({
+		queueName: name,
+		message: resp.message || 'Failed to resume queue',
+	});
+}

package/src/services/{queue.ts → queue/service.ts}

@@ -18,9 +18,10 @@
  * ```
  */
 
-import { FetchAdapter } from './adapter.ts';
-import { buildUrl, toServiceException, toPayload } from './_util.ts';
-import { StructuredError } from '../error.ts';
+import { FetchAdapter } from '../adapter.ts';
+import { buildUrl, toServiceException, toPayload } from '../_util.ts';
+import { StructuredError } from '../../error.ts';
+import { z } from 'zod';
 
 /**
  * Parameters for publishing a message to a queue.
@@ -35,50 +36,55 @@ import { StructuredError } from '../error.ts';
  * };
  * ```
  */
-export interface QueuePublishParams {
+export const QueuePublishParamsSchema = z.object({
 	/**
 	 * Optional metadata to attach to the message.
 	 * Can contain any JSON-serializable data for message routing or filtering.
 	 */
-	metadata?: Record<string, unknown>;
+	metadata: z
+		.record(z.string(), z.unknown())
+		.optional()
+		.describe('Optional metadata to attach to the message.'),
 
 	/**
 	 * Optional partition key for message ordering.
 	 * Messages with the same partition key are guaranteed to be processed in order.
 	 */
-	partitionKey?: string;
+	partitionKey: z.string().optional().describe('Optional partition key for message ordering.'),
 
 	/**
 	 * Optional idempotency key for deduplication.
 	 * If a message with the same key was recently published, it will be deduplicated.
 	 */
-	idempotencyKey?: string;
+	idempotencyKey: z.string().optional().describe('Optional idempotency key for deduplication.'),
 
 	/**
 	 * Optional time-to-live in seconds.
 	 * Messages will expire and be removed after this duration.
 	 */
-	ttl?: number;
+	ttl: z.number().optional().describe('Optional time-to-live in seconds.'),
 
 	/**
 	 * Optional project ID for cross-project publishing.
 	 * If not specified, uses the current project context.
 	 */
-	projectId?: string;
+	projectId: z.string().optional().describe('Optional project ID for cross-project publishing.'),
 
 	/**
 	 * Optional agent ID for attribution.
 	 * If not specified, uses the current agent context.
 	 */
-	agentId?: string;
+	agentId: z.string().optional().describe('Optional agent ID for attribution.'),
 
 	/**
 	 * Whether to publish synchronously.
 	 * When true, the API waits for the message to be fully persisted before returning.
 	 * When false (default), the API returns immediately with a pending message.
 	 */
-	sync?: boolean;
-}
+	sync: z.boolean().optional().describe('Whether to publish synchronously.'),
+});
+
+export type QueuePublishParams = z.infer<typeof QueuePublishParamsSchema>;
 
 /**
  * Result of publishing a message to a queue.
@@ -89,24 +95,26 @@ export interface QueuePublishParams {
  * console.log(`Message ${result.id} published at offset ${result.offset}`);
  * ```
  */
-export interface QueuePublishResult {
+export const QueuePublishResultSchema = z.object({
 	/**
 	 * The unique message ID (prefixed with msg_).
 	 * Use this ID to track, acknowledge, or delete the message.
 	 */
-	id: string;
+	id: z.string().describe('The unique message ID (prefixed with msg_).'),
 
 	/**
 	 * The sequential offset of the message in the queue.
 	 * Offsets are monotonically increasing and can be used for log-style consumption.
 	 */
-	offset: number;
+	offset: z.number().describe('The sequential offset of the message in the queue.'),
 
 	/**
 	 * ISO 8601 timestamp when the message was published.
 	 */
-	publishedAt: string;
-}
+	publishedAt: z.string().describe('ISO 8601 timestamp when the message was published.'),
+});
+
+export type QueuePublishResult = z.infer<typeof QueuePublishResultSchema>;
 
 /**
  * Parameters for creating a queue.
@@ -119,47 +127,70 @@ export interface QueuePublishResult {
  * });
  * ```
  */
-export interface QueueCreateParams {
+export const QueueCreateParamsSchema = z.object({
 	/**
 	 * Type of queue to create.
 	 * - `worker`: Messages are consumed by exactly one consumer with acknowledgment.
 	 * - `pubsub`: Messages are broadcast to all subscribers.
 	 * @default 'worker'
 	 */
-	queueType?: 'worker' | 'pubsub';
+	queueType: z.enum(['worker', 'pubsub']).optional().describe('Type of queue to create.'),
 
 	/**
 	 * Optional description of the queue's purpose.
 	 */
-	description?: string;
+	description: z.string().optional().describe("Optional description of the queue's purpose."),
 
 	/**
 	 * Optional settings to customize queue behavior.
 	 * Only provided fields are applied; others use server defaults.
 	 */
-	settings?: {
-		/** Default time-to-live for messages in seconds. Null means no expiration. */
-		defaultTtlSeconds?: number | null;
-		/** Time in seconds a message is invisible after being received. */
-		defaultVisibilityTimeoutSeconds?: number;
-		/** Maximum number of delivery attempts before moving to DLQ. */
-		defaultMaxRetries?: number;
-		/** Maximum number of messages a single client can process concurrently. */
-		maxInFlightPerClient?: number;
-		/** Retention period for acknowledged messages in seconds. */
-		retentionSeconds?: number;
-	};
-}
+	settings: z
+		.object({
+			/** Default time-to-live for messages in seconds. Null means no expiration. */
+			defaultTtlSeconds: z
+				.number()
+				.nullable()
+				.optional()
+				.describe('Default time-to-live for messages in seconds. Null means no expiration.'),
+			/** Time in seconds a message is invisible after being received. */
+			defaultVisibilityTimeoutSeconds: z
+				.number()
+				.optional()
+				.describe('Time in seconds a message is invisible after being received.'),
+			/** Maximum number of delivery attempts before moving to DLQ. */
+			defaultMaxRetries: z
+				.number()
+				.optional()
+				.describe('Maximum number of delivery attempts before moving to DLQ.'),
+			/** Maximum number of messages a single client can process concurrently. */
+			maxInFlightPerClient: z
+				.number()
+				.optional()
+				.describe('Maximum number of messages a single client can process concurrently.'),
+			/** Retention period for acknowledged messages in seconds. */
+			retentionSeconds: z
+				.number()
+				.optional()
+				.describe('Retention period for acknowledged messages in seconds.'),
+		})
+		.optional()
+		.describe('Optional settings to customize queue behavior.'),
+});
+
+export type QueueCreateParams = z.infer<typeof QueueCreateParamsSchema>;
 
 /**
  * Result of creating a queue.
  */
-export interface QueueCreateResult {
+export const QueueCreateResultSchema = z.object({
 	/** The queue name. */
-	name: string;
+	name: z.string().describe('The queue name.'),
 	/** The queue type ('worker' or 'pubsub'). */
-	queueType: string;
-}
+	queueType: z.string().describe("The queue type ('worker' or 'pubsub')."),
+});
+
+export type QueueCreateResult = z.infer<typeof QueueCreateResultSchema>;
 
 /**
  * Queue service interface for publishing messages.
@@ -424,7 +455,7 @@ export class QueueStorageService implements QueueService {
 			});
 		}
 
-		const basePath = `/queue/messages/publish/2026-01-15/${encodeURIComponent(queueName)}`;
+		const basePath = `/queue/messages/publish/${encodeURIComponent(queueName)}`;
 		const url = buildUrl(this.#baseUrl, params?.sync ? `${basePath}?sync=true` : basePath);
 
 		const requestBody: Record<string, unknown> = {
@@ -499,7 +530,7 @@ export class QueueStorageService implements QueueService {
 			};
 		}
 
-		const url = buildUrl(this.#baseUrl, '/queue/create/2026-01-15');
+		const url = buildUrl(this.#baseUrl, '/queue/create');
 
 		const requestBody: Record<string, unknown> = {
 			name: queueName,
@@ -573,10 +604,7 @@ export class QueueStorageService implements QueueService {
 	async deleteQueue(queueName: string): Promise<void> {
 		validateQueueNameInternal(queueName);
 
-		const url = buildUrl(
-			this.#baseUrl,
-			`/queue/delete/2026-01-15/${encodeURIComponent(queueName)}`
-		);
+		const url = buildUrl(this.#baseUrl, `/queue/delete/${encodeURIComponent(queueName)}`);
 
 		const signal = AbortSignal.timeout(30_000);
 		const res = await this.#adapter.invoke<void>(url, {