@agentuity/server 1.0.17 → 1.0.19

package/src/api/queue/queues.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { type APIClient, APIResponseSchema, APIResponseSchemaNoData } from '../api';
+import { type APIClient, APIResponseSchema, APIResponseSchemaNoData } from '../api.ts';
 import {
 	type CreateQueueRequest,
 	CreateQueueRequestSchema,
@@ -9,14 +9,14 @@ import {
 	QueueSchema,
 	type UpdateQueueRequest,
 	UpdateQueueRequestSchema,
-} from './types';
+} from './types.ts';
 import {
 	buildQueueHeaders,
 	QueueError,
-	QueueNotFoundError,
 	queueApiPath,
 	queueApiPathWithQuery,
-} from './util';
+	withQueueErrorHandling,
+} from './util.ts';
 import {
 	validateDescription,
 	validateLimit,
@@ -27,7 +27,7 @@ import {
 	validateQueueType,
 	validateTTL,
 	validateVisibilityTimeout,
-} from './validation';
+} from './validation.ts';
 
 export const QueueResponseSchema = APIResponseSchema(z.object({ queue: QueueSchema }));
 export const QueuesListResponseSchema = APIResponseSchema(
@@ -138,24 +138,15 @@ export async function getQueue(
 ): Promise<Queue> {
 	validateQueueName(name);
 	const url = queueApiPath('get', name);
-	const resp = await client.get(
-		url,
-		QueueResponseSchema,
-		undefined,
-		buildQueueHeaders(options?.orgId)
+	const resp = await withQueueErrorHandling(
+		() => client.get(url, QueueResponseSchema, undefined, buildQueueHeaders(options?.orgId)),
+		{ queueName: name }
 	);
 
 	if (resp.success) {
 		return resp.data.queue;
 	}
 
-	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',
@@ -302,26 +293,23 @@ export async function updateQueue(
 	}
 
 	const url = queueApiPath('update', name);
-	const resp = await client.patch(
-		url,
-		params,
-		QueueResponseSchema,
-		UpdateQueueRequestSchema,
-		undefined,
-		buildQueueHeaders(options?.orgId)
+	const resp = await withQueueErrorHandling(
+		() =>
+			client.patch(
+				url,
+				params,
+				QueueResponseSchema,
+				UpdateQueueRequestSchema,
+				undefined,
+				buildQueueHeaders(options?.orgId)
+			),
+		{ queueName: name }
 	);
 
 	if (resp.success) {
 		return resp.data.queue;
 	}
 
-	if (resp.message?.includes('not found')) {
-		throw new QueueNotFoundError({
-			queueName: name,
-			message: resp.message,
-		});
-	}
-
 	throw new QueueError({
 		queueName: name,
 		message: resp.message || 'Failed to update queue',
@@ -352,24 +340,21 @@ export async function deleteQueue(
 ): Promise<void> {
 	validateQueueName(name);
 	const url = queueApiPath('delete', name);
-	const resp = await client.delete(
-		url,
-		DeleteQueueResponseSchema,
-		undefined,
-		buildQueueHeaders(options?.orgId)
+	const resp = await withQueueErrorHandling(
+		() =>
+			client.delete(
+				url,
+				DeleteQueueResponseSchema,
+				undefined,
+				buildQueueHeaders(options?.orgId)
+			),
+		{ queueName: name }
 	);
 
 	if (resp.success) {
 		return;
 	}
 
-	if (resp.message?.includes('not found')) {
-		throw new QueueNotFoundError({
-			queueName: name,
-			message: resp.message,
-		});
-	}
-
 	throw new QueueError({
 		queueName: name,
 		message: resp.message || 'Failed to delete queue',
@@ -402,26 +387,23 @@ export async function pauseQueue(
 ): Promise<Queue> {
 	validateQueueName(name);
 	const url = queueApiPath('pause', name);
-	const resp = await client.post(
-		url,
-		{},
-		QueueResponseSchema,
-		z.object({}),
-		undefined,
-		buildQueueHeaders(options?.orgId)
+	const resp = await withQueueErrorHandling(
+		() =>
+			client.post(
+				url,
+				{},
+				QueueResponseSchema,
+				z.object({}),
+				undefined,
+				buildQueueHeaders(options?.orgId)
+			),
+		{ queueName: name }
 	);
 
 	if (resp.success) {
 		return resp.data.queue;
 	}
 
-	if (resp.message?.includes('not found')) {
-		throw new QueueNotFoundError({
-			queueName: name,
-			message: resp.message,
-		});
-	}
-
 	throw new QueueError({
 		queueName: name,
 		message: resp.message || 'Failed to pause queue',
@@ -454,26 +436,23 @@ export async function resumeQueue(
 ): Promise<Queue> {
 	validateQueueName(name);
 	const url = queueApiPath('resume', name);
-	const resp = await client.post(
-		url,
-		{},
-		QueueResponseSchema,
-		z.object({}),
-		undefined,
-		buildQueueHeaders(options?.orgId)
+	const resp = await withQueueErrorHandling(
+		() =>
+			client.post(
+				url,
+				{},
+				QueueResponseSchema,
+				z.object({}),
+				undefined,
+				buildQueueHeaders(options?.orgId)
+			),
+		{ queueName: name }
 	);
 
 	if (resp.success) {
 		return resp.data.queue;
 	}
 
-	if (resp.message?.includes('not found')) {
-		throw new QueueNotFoundError({
-			queueName: name,
-			message: resp.message,
-		});
-	}
-
 	throw new QueueError({
 		queueName: name,
 		message: resp.message || 'Failed to resume queue',

package/src/api/queue/sources.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { type APIClient, APIError, APIResponseSchema, APIResponseSchemaNoData } from '../api';
+import { type APIClient, APIResponseSchema, APIResponseSchemaNoData } from '../api.ts';
 import {
 	type CreateSourceRequest,
 	CreateSourceRequestSchema,
@@ -8,16 +8,9 @@ import {
 	SourceSchema,
 	type UpdateSourceRequest,
 	UpdateSourceRequestSchema,
-} from './types';
-import {
-	buildQueueHeaders,
-	QueueError,
-	QueueNotFoundError,
-	queueApiPath,
-	SourceAlreadyExistsError,
-	SourceNotFoundError,
-} from './util';
-import { validateQueueName, validateSourceId, validateSourceName } from './validation';
+} from './types.ts';
+import { buildQueueHeaders, QueueError, queueApiPath, withQueueErrorHandling } from './util.ts';
+import { validateQueueName, validateSourceId, validateSourceName } from './validation.ts';
 
 export const SourceResponseSchema = APIResponseSchema(z.object({ source: SourceSchema }));
 export const SourcesListResponseSchema = APIResponseSchema(
@@ -64,63 +57,27 @@ export async function createSource(
 	validateSourceName(params.name);
 
 	const url = queueApiPath('sources/create', queueName);
+	const resp = await withQueueErrorHandling(
+		() =>
+			client.post(
+				url,
+				params,
+				SourceResponseSchema,
+				CreateSourceRequestSchema,
+				undefined,
+				buildQueueHeaders(options?.orgId)
+			),
+		{ queueName, sourceName: params.name }
+	);
 
-	try {
-		const resp = await client.post(
-			url,
-			params,
-			SourceResponseSchema,
-			CreateSourceRequestSchema,
-			undefined,
-			buildQueueHeaders(options?.orgId)
-		);
-
-		if (resp.success) {
-			return resp.data.source;
-		}
-
-		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 SourceAlreadyExistsError({
-				queueName,
-				name: params.name,
-				message: `A source with name "${params.name}" already exists for queue "${queueName}"`,
-			});
-		}
-
-		throw new QueueError({
-			queueName,
-			message: resp.message || 'Failed to create source',
-		});
-	} catch (error) {
-		if (error instanceof APIError) {
-			const message = error.message || '';
-			if (message.includes('already exists')) {
-				throw new SourceAlreadyExistsError({
-					queueName,
-					name: params.name,
-					message: `A source with name "${params.name}" 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 source',
-			});
-		}
-		throw error;
+	if (resp.success) {
+		return resp.data.source;
 	}
+
+	throw new QueueError({
+		queueName,
+		message: resp.message || 'Failed to create source',
+	});
 }
 
 /**
@@ -153,24 +110,16 @@ export async function listSources(
 ): Promise<Source[]> {
 	validateQueueName(queueName);
 	const url = queueApiPath('sources/list', queueName);
-	const resp = await client.get(
-		url,
-		SourcesListResponseSchema,
-		undefined,
-		buildQueueHeaders(options?.orgId)
+	const resp = await withQueueErrorHandling(
+		() =>
+			client.get(url, SourcesListResponseSchema, undefined, buildQueueHeaders(options?.orgId)),
+		{ queueName }
 	);
 
 	if (resp.success) {
 		return resp.data.sources;
 	}
 
-	if (resp.message?.includes('not found')) {
-		throw new QueueNotFoundError({
-			queueName,
-			message: resp.message,
-		});
-	}
-
 	throw new QueueError({
 		queueName,
 		message: resp.message || 'Failed to list sources',
@@ -210,32 +159,15 @@ export async function getSource(
 	validateSourceId(sourceId);
 
 	const url = queueApiPath('sources/get', queueName, sourceId);
-	const resp = await client.get(
-		url,
-		SourceResponseSchema,
-		undefined,
-		buildQueueHeaders(options?.orgId)
+	const resp = await withQueueErrorHandling(
+		() => client.get(url, SourceResponseSchema, undefined, buildQueueHeaders(options?.orgId)),
+		{ queueName, sourceId }
 	);
 
 	if (resp.success) {
 		return resp.data.source;
 	}
 
-	if (resp.message?.includes('source') && resp.message?.includes('not found')) {
-		throw new SourceNotFoundError({
-			queueName,
-			sourceId,
-			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 get source',
@@ -286,34 +218,23 @@ export async function updateSource(
 	}
 
 	const url = queueApiPath('sources/update', queueName, sourceId);
-	const resp = await client.patch(
-		url,
-		params,
-		SourceResponseSchema,
-		UpdateSourceRequestSchema,
-		undefined,
-		buildQueueHeaders(options?.orgId)
+	const resp = await withQueueErrorHandling(
+		() =>
+			client.patch(
+				url,
+				params,
+				SourceResponseSchema,
+				UpdateSourceRequestSchema,
+				undefined,
+				buildQueueHeaders(options?.orgId)
+			),
+		{ queueName, sourceId }
 	);
 
 	if (resp.success) {
 		return resp.data.source;
 	}
 
-	if (resp.message?.includes('source') && resp.message?.includes('not found')) {
-		throw new SourceNotFoundError({
-			queueName,
-			sourceId,
-			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 source',
@@ -351,32 +272,21 @@ export async function deleteSource(
 	validateSourceId(sourceId);
 
 	const url = queueApiPath('sources/delete', queueName, sourceId);
-	const resp = await client.delete(
-		url,
-		DeleteSourceResponseSchema,
-		undefined,
-		buildQueueHeaders(options?.orgId)
+	const resp = await withQueueErrorHandling(
+		() =>
+			client.delete(
+				url,
+				DeleteSourceResponseSchema,
+				undefined,
+				buildQueueHeaders(options?.orgId)
+			),
+		{ queueName, sourceId }
 	);
 
 	if (resp.success) {
 		return;
 	}
 
-	if (resp.message?.includes('source') && resp.message?.includes('not found')) {
-		throw new SourceNotFoundError({
-			queueName,
-			sourceId,
-			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 source',

package/src/api/queue/util.ts

@@ -1,4 +1,5 @@
 import { StructuredError } from '@agentuity/core';
+import { APIError } from '../api.ts';
 
 /**
  * General queue operation error.
@@ -202,3 +203,76 @@ export function buildQueueHeaders(orgId?: string): Record<string, string> | unde
 	}
 	return undefined;
 }
+
+/**
+ * Wraps an API call and translates APIError with HTTP status codes to domain-specific queue errors.
+ *
+ * - 404 → QueueNotFoundError / MessageNotFoundError / DestinationNotFoundError / SourceNotFoundError
+ * - 409 with "already exists" → DestinationAlreadyExistsError / SourceAlreadyExistsError
+ *
+ * @internal
+ */
+export async function withQueueErrorHandling<T>(
+	apiCall: () => Promise<T>,
+	context: {
+		queueName?: string;
+		messageId?: string;
+		destinationId?: string;
+		sourceId?: string;
+		sourceName?: string;
+		destinationUrl?: string;
+	}
+): Promise<T> {
+	try {
+		return await apiCall();
+	} catch (error) {
+		if (error instanceof APIError) {
+			if (error.status === 404) {
+				if (context.messageId && context.queueName) {
+					throw new MessageNotFoundError({
+						queueName: context.queueName,
+						messageId: context.messageId,
+						message: error.message,
+					});
+				}
+				if (context.destinationId && context.queueName) {
+					throw new DestinationNotFoundError({
+						queueName: context.queueName,
+						destinationId: context.destinationId,
+						message: error.message,
+					});
+				}
+				if (context.sourceId && context.queueName) {
+					throw new SourceNotFoundError({
+						queueName: context.queueName,
+						sourceId: context.sourceId,
+						message: error.message,
+					});
+				}
+				if (context.queueName) {
+					throw new QueueNotFoundError({
+						queueName: context.queueName,
+						message: error.message,
+					});
+				}
+			}
+			if (error.status === 409) {
+				if (context.destinationUrl && context.queueName) {
+					throw new DestinationAlreadyExistsError({
+						queueName: context.queueName,
+						url: context.destinationUrl,
+						message: error.message,
+					});
+				}
+				if (context.sourceName && context.queueName) {
+					throw new SourceAlreadyExistsError({
+						queueName: context.queueName,
+						name: context.sourceName,
+						message: error.message,
+					});
+				}
+			}
+		}
+		throw error;
+	}
+}

package/src/api/queue/websocket.ts

@@ -41,10 +41,10 @@
  * ```
  */
 
-import type { Message } from './types';
-import { WebSocketAuthResponseSchema, WebSocketMessageSchema } from './types';
-import { QueueError } from './util';
-import { validateQueueName } from './validation';
+import type { Message } from './types.ts';
+import { WebSocketAuthResponseSchema, WebSocketMessageSchema } from './types.ts';
+import { QueueError } from './util.ts';
+import { validateQueueName } from './validation.ts';
 
 // ============================================================================
 // Types
@@ -210,7 +210,7 @@ export function createQueueWebSocket(options: QueueWebSocketOptions): QueueWebSo
 					message: `Failed to create WebSocket connection: ${err instanceof Error ? err.message : String(err)}`,
 					queueName,
 					cause: err instanceof Error ? err : undefined,
-				}),
+				})
 			);
 			scheduleReconnect();
 			return;
@@ -319,7 +319,7 @@ export function createQueueWebSocket(options: QueueWebSocketOptions): QueueWebSo
 				new QueueError({
 					message: 'WebSocket connection error',
 					queueName,
-				}),
+				})
 			);
 		};
 	}
@@ -331,7 +331,7 @@ export function createQueueWebSocket(options: QueueWebSocketOptions): QueueWebSo
 				new QueueError({
 					message: `Exceeded maximum reconnection attempts (${maxReconnectAttempts})`,
 					queueName,
-				}),
+				})
 			);
 			return;
 		}
@@ -405,7 +405,7 @@ export function createQueueWebSocket(options: QueueWebSocketOptions): QueueWebSo
  * ```
  */
 export async function* subscribeToQueue(
-	options: SubscribeToQueueOptions,
+	options: SubscribeToQueueOptions
 ): AsyncGenerator<Message, void, unknown> {
 	const { signal } = options;
 

package/src/api/region/create.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { APIResponseSchema, APIClient } from '../api';
-import { RegionResponseError } from './util';
+import { APIResponseSchema, APIClient } from '../api.ts';
+import { RegionResponseError } from './util.ts';
 
 /**
  * Database name validation regex - must match catalyst server validation:
@@ -51,6 +51,12 @@ export function validateDatabaseName(name: string): { valid: boolean; error?: st
 			error: 'database name must start with a letter or underscore and contain only lowercase letters, digits, and underscores',
 		};
 	}
+	if (name.startsWith('pg_')) {
+		return {
+			valid: false,
+			error: "database name cannot start with 'pg_' (reserved by PostgreSQL)",
+		};
+	}
 	return { valid: true };
 }
 

package/src/api/region/delete.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { APIResponseSchema, APIClient } from '../api';
-import { RegionResponseError } from './util';
+import { APIResponseSchema, APIClient } from '../api.ts';
+import { RegionResponseError } from './util.ts';
 
 export const DeleteResourceSpec = z.object({
 	type: z.enum(['db', 's3']).describe('the resource type'),

package/src/api/region/index.ts

@@ -1,4 +1,4 @@
-export * from './list';
-export * from './resources';
-export * from './create';
-export * from './delete';
+export * from './list.ts';
+export * from './resources.ts';
+export * from './create.ts';
+export * from './delete.ts';

package/src/api/region/list.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { APIResponseSchema, APIClient } from '../api';
-import { RegionResponseError } from './util';
+import { APIResponseSchema, APIClient } from '../api.ts';
+import { RegionResponseError } from './util.ts';
 
 export const ListRegionsResponse = z.array(
 	z.object({

package/src/api/region/resources.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { APIResponseSchema, APIClient } from '../api';
-import { RegionResponseError } from './util';
+import { APIResponseSchema, APIClient } from '../api.ts';
+import { RegionResponseError } from './util.ts';
 
 export const ResourceListResponse = z.object({
 	s3: z.array(

package/src/api/sandbox/cli-list.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { type APIClient, APIResponseSchema } from '../api';
-import { SandboxResponseError } from './util';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import { SandboxResponseError } from './util.ts';
 
 export const SandboxInfoSchema = z.object({
 	id: z.string().describe('the sandbox id'),
@@ -45,7 +45,15 @@ export interface CLISandboxListOptions {
 	/**
 	 * Filter by sandbox status
 	 */
-	status?: 'creating' | 'idle' | 'running' | 'paused' | 'stopping' | 'suspended' | 'terminated' | 'failed';
+	status?:
+		| 'creating'
+		| 'idle'
+		| 'running'
+		| 'paused'
+		| 'stopping'
+		| 'suspended'
+		| 'terminated'
+		| 'failed';
 	/**
 	 * Maximum number of sandboxes to return (default: 50, max: 100)
 	 */