@agentuity/core 1.0.32 → 1.0.33

package/src/api/region/create.ts

@@ -0,0 +1,207 @@
+import { z } from 'zod';
+import { APIResponseSchema, APIClient } from '../api.ts';
+import { RegionResponseError } from './util.ts';
+
+/**
+ * Database name validation regex - must match catalyst server validation:
+ * - Must start with a letter or underscore
+ * - Can contain only lowercase letters, digits, and underscores
+ * - Must be lowercase
+ */
+const DATABASE_NAME_REGEX = /^[a-z_][a-z0-9_]*$/;
+const MAX_DATABASE_NAME_LENGTH = 63;
+const MIN_DATABASE_NAME_LENGTH = 1;
+
+/**
+ * S3 bucket name validation - must match catalyst server validation (AWS S3 rules):
+ * - Length [3, 63]
+ * - Only lowercase, numbers, dots, hyphens
+ * - No adjacent periods
+ * - Starts with lowercase or number
+ * - Ends with lowercase or number
+ * - No xn-- prefix
+ * - No -s3alias suffix
+ * - Not an IP address
+ */
+const BUCKET_NAME_REGEX = /^[a-z0-9.-]+$/;
+const MAX_BUCKET_NAME_LENGTH = 63;
+const MIN_BUCKET_NAME_LENGTH = 3;
+const IPV4_REGEX = /^(\d{1,3}\.){3}\d{1,3}$/;
+
+/**
+ * Validates a database name for PostgreSQL compatibility.
+ * Matches the server-side validation in catalyst.
+ */
+export function validateDatabaseName(name: string): { valid: boolean; error?: string } {
+	if (name.length < MIN_DATABASE_NAME_LENGTH) {
+		return { valid: false, error: 'database name is too short (minimum 1 character)' };
+	}
+	if (name.length > MAX_DATABASE_NAME_LENGTH) {
+		return {
+			valid: false,
+			error: `database name is too long (maximum ${MAX_DATABASE_NAME_LENGTH} characters)`,
+		};
+	}
+	if (name !== name.toLowerCase()) {
+		return { valid: false, error: 'database name must be lowercase' };
+	}
+	if (!DATABASE_NAME_REGEX.test(name)) {
+		return {
+			valid: false,
+			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 };
+}
+
+/**
+ * Validates an S3 bucket name according to AWS S3 naming rules.
+ * Matches the server-side validation in catalyst.
+ */
+export function validateBucketName(name: string): { valid: boolean; error?: string } {
+	if (name.length < MIN_BUCKET_NAME_LENGTH) {
+		return {
+			valid: false,
+			error: `bucket name is too short (minimum ${MIN_BUCKET_NAME_LENGTH} characters)`,
+		};
+	}
+	if (name.length > MAX_BUCKET_NAME_LENGTH) {
+		return {
+			valid: false,
+			error: `bucket name is too long (maximum ${MAX_BUCKET_NAME_LENGTH} characters)`,
+		};
+	}
+	if (!BUCKET_NAME_REGEX.test(name)) {
+		return {
+			valid: false,
+			error: 'bucket name can only contain lowercase letters, numbers, dots, and hyphens',
+		};
+	}
+	if (name.includes('..')) {
+		return { valid: false, error: 'bucket name cannot contain adjacent periods' };
+	}
+	const firstChar = name[0];
+	if (
+		firstChar === undefined ||
+		!((firstChar >= 'a' && firstChar <= 'z') || (firstChar >= '0' && firstChar <= '9'))
+	) {
+		return { valid: false, error: 'bucket name must start with a lowercase letter or number' };
+	}
+	const lastChar = name[name.length - 1];
+	if (
+		lastChar === undefined ||
+		!((lastChar >= 'a' && lastChar <= 'z') || (lastChar >= '0' && lastChar <= '9'))
+	) {
+		return { valid: false, error: 'bucket name must end with a lowercase letter or number' };
+	}
+	if (name.startsWith('xn--')) {
+		return { valid: false, error: 'bucket name cannot start with xn--' };
+	}
+	if (name.endsWith('-s3alias')) {
+		return { valid: false, error: 'bucket name cannot end with -s3alias' };
+	}
+	if (isIPv4Address(name)) {
+		return { valid: false, error: 'bucket name cannot be an IP address' };
+	}
+	// Reserved prefixes (system-generated names)
+	if (name.startsWith('ag-') || name.startsWith('ago-') || name.startsWith('agentuity')) {
+		return {
+			valid: false,
+			error: 'bucket names starting with "ag-", "ago-", or "agentuity" are reserved for system use',
+		};
+	}
+	return { valid: true };
+}
+
+function isIPv4Address(s: string): boolean {
+	if (!IPV4_REGEX.test(s)) {
+		return false;
+	}
+	const parts = s.split('.');
+	for (const part of parts) {
+		const num = parseInt(part, 10);
+		if (Number.isNaN(num) || num < 0 || num > 255) {
+			return false;
+		}
+	}
+	return true;
+}
+
+export const ResourceSpec = z.object({
+	type: z.enum(['db', 's3']).describe('the resource type'),
+	name: z.string().optional().describe('optional custom name for db'),
+	description: z.string().optional().describe('optional description for db'),
+});
+
+export const CreateResourcesRequest = z.object({
+	resources: z.array(ResourceSpec).describe('list of resources to create'),
+});
+
+export const CreatedResource = z.object({
+	type: z.string().describe('the resource type'),
+	name: z.string().describe('the resource name'),
+	env: z.record(z.string(), z.string()).describe('environment variables for the resource'),
+});
+
+export const CreateResourcesResponse = z.object({
+	created: z.array(CreatedResource),
+});
+
+export const CreateResourcesResponseSchema = APIResponseSchema(CreateResourcesResponse);
+
+export type CreateResourcesRequest = z.infer<typeof CreateResourcesRequest>;
+export type CreateResourcesResponse = z.infer<typeof CreateResourcesResponseSchema>;
+export type CreatedResource = z.infer<typeof CreatedResource>;
+
+/**
+ * Create one or more resources (DB or S3) for an organization in a specific region
+ * Requires CLI authentication
+ *
+ * @param client - Catalyst API client
+ * @param orgId - Organization ID
+ * @param region - Cloud region
+ * @param resources - Array of resources to create
+ * @returns
+ */
+export async function createResources(
+	client: APIClient,
+	orgId: string,
+	region: string,
+	resources: Array<{ type: 'db' | 's3'; name?: string; description?: string }>
+): Promise<CreatedResource[]> {
+	// Validate resource names before sending to server
+	for (const resource of resources) {
+		if (resource.type === 'db' && resource.name) {
+			const validation = validateDatabaseName(resource.name);
+			if (!validation.valid) {
+				throw new RegionResponseError({ message: validation.error! });
+			}
+		}
+		if (resource.type === 's3' && resource.name) {
+			const validation = validateBucketName(resource.name);
+			if (!validation.valid) {
+				throw new RegionResponseError({ message: validation.error! });
+			}
+		}
+	}
+
+	const resp = await client.request<CreateResourcesResponse, CreateResourcesRequest>(
+		'POST',
+		`/resource/${orgId}/${region}`,
+		CreateResourcesResponseSchema,
+		{ resources },
+		CreateResourcesRequest
+	);
+	if (resp.success) {
+		return resp.data.created;
+	}
+	throw new RegionResponseError({
+		message: resp.message,
+	});
+}

package/src/api/region/delete.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+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'),
+	name: z.string().describe('the resource name (bucket_name for S3, db_name for DB)'),
+});
+
+export const DeleteResourcesRequest = z.object({
+	resources: z.array(DeleteResourceSpec).describe('list of resources to delete'),
+});
+
+export const DeletedResource = z.object({
+	type: z.string().describe('the resource type'),
+	name: z.string().describe('the resource name'),
+	env_keys: z.array(z.string()).describe('environment variable keys to remove'),
+});
+
+export const DeleteResourcesResponse = z.object({
+	deleted: z.array(DeletedResource).describe('list of deleted resources'),
+});
+
+export const DeleteResourcesResponseSchema = APIResponseSchema(DeleteResourcesResponse);
+
+export type DeleteResourcesRequest = z.infer<typeof DeleteResourcesRequest>;
+export type DeleteResourcesResponse = z.infer<typeof DeleteResourcesResponseSchema>;
+export type DeletedResource = z.infer<typeof DeletedResource>;
+
+/**
+ * Delete one or more resources (DB or S3) for an organization in a specific region
+ * Requires CLI authentication
+ *
+ * @param client - Catalyst API client
+ * @param orgId - Organization ID
+ * @param region - Cloud region
+ * @param resources - Array of resources to delete
+ * @returns
+ */
+export async function deleteResources(
+	client: APIClient,
+	orgId: string,
+	region: string,
+	resources: Array<{ type: 'db' | 's3'; name: string }>
+): Promise<DeletedResource[]> {
+	const resp = await client.request<DeleteResourcesResponse, DeleteResourcesRequest>(
+		'DELETE',
+		`/resource/${orgId}/${region}`,
+		DeleteResourcesResponseSchema,
+		{ resources },
+		DeleteResourcesRequest
+	);
+	if (resp.success) {
+		return resp.data.deleted;
+	}
+	throw new RegionResponseError({ message: resp.message });
+}

package/src/api/region/index.ts

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

package/src/api/region/list.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { APIResponseSchema, APIClient } from '../api.ts';
+import { RegionResponseError } from './util.ts';
+
+export const ListRegionsResponse = z.array(
+	z.object({
+		region: z.string().describe('the region identifier'),
+		description: z.string().describe('the human-readable description of the region'),
+	})
+);
+export const ListRegionsResponseSchema = APIResponseSchema(ListRegionsResponse);
+
+export type ListRegionsResponse = z.infer<typeof ListRegionsResponseSchema>;
+export type RegionList = z.infer<typeof ListRegionsResponse>;
+
+/**
+ * List all available cloud regions
+ *
+ * @param client
+ * @returns
+ */
+export async function listRegions(client: APIClient): Promise<RegionList> {
+	const resp = await client.request<ListRegionsResponse>(
+		'GET',
+		'/cli/region',
+		ListRegionsResponseSchema
+	);
+	if (resp.success) {
+		return resp.data;
+	}
+	throw new RegionResponseError({ message: resp.message });
+}

package/src/api/region/resources.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import { APIResponseSchema, APIClient } from '../api.ts';
+import { RegionResponseError } from './util.ts';
+
+export const ResourceListResponse = z.object({
+	s3: z.array(
+		z.object({
+			bucket_name: z.string().describe('the S3 bucket name'),
+			access_key: z.string().nullable().optional().describe('the S3 access key'),
+			secret_key: z.string().nullable().optional().describe('the S3 secret key'),
+			region: z.string().nullable().optional().describe('the S3 region'),
+			endpoint: z.string().nullable().optional().describe('the S3 endpoint'),
+			cname: z.string().nullable().optional().describe('the S3 CNAME'),
+			env: z.record(z.string(), z.string()).describe('environment variables for the resource'),
+			bucket_type: z.string().describe('the bucket type (user or snapshots)'),
+			internal: z.boolean().describe('whether this is a system-managed bucket'),
+			description: z
+				.string()
+				.nullable()
+				.optional()
+				.describe('optional description of the bucket'),
+		})
+	),
+	db: z.array(
+		z.object({
+			name: z.string().describe('the database name'),
+			username: z.string().nullable().optional().describe('the database username'),
+			password: z.string().nullable().optional().describe('the database password'),
+			url: z.string().nullable().optional().describe('the full database connection URL'),
+			env: z.record(z.string(), z.string()).describe('environment variables for the resource'),
+			internal: z
+				.boolean()
+				.describe('whether this is a system-managed database (KV/Vector/Queue)'),
+		})
+	),
+	redis: z
+		.object({
+			url: z.string().describe('the Redis connection URL'),
+		})
+		.optional(),
+});
+export const ResourceListResponseSchema = APIResponseSchema(ResourceListResponse);
+
+export type ResourceListResponse = z.infer<typeof ResourceListResponseSchema>;
+export type ResourceList = z.infer<typeof ResourceListResponse>;
+
+/**
+ * List all resources for a given organization and region
+ *
+ * @param client
+ * @param orgId
+ * @param region
+ * @returns
+ */
+export async function listResources(
+	client: APIClient,
+	orgId: string,
+	region: string
+): Promise<ResourceList> {
+	const resp = await client.request<ResourceListResponse>(
+		'GET',
+		`/resource/${orgId}/${region}`,
+		ResourceListResponseSchema
+	);
+	if (resp.success) {
+		return resp.data;
+	}
+	throw new RegionResponseError({ message: resp.message });
+}

package/src/api/region/util.ts

@@ -0,0 +1,3 @@
+import { StructuredError } from '../../error.ts';
+
+export const RegionResponseError = StructuredError('RegionResponseError');

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

@@ -0,0 +1,127 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import { SandboxResponseError } from './util.ts';
+
+export const SandboxInfoSchema = z.object({
+	id: z.string().describe('the sandbox id'),
+	name: z.string().nullable().describe('the sandbox name'),
+	description: z.string().nullable().describe('the sandbox description'),
+	status: z.string().describe('sandbox status'),
+	region: z.string().nullable().describe('cloud region'),
+	createdAt: z.string().nullable().describe('ISO 8601 creation timestamp'),
+	orgId: z.string().describe('the organization id'),
+	orgName: z.string().nullable().describe('the organization name'),
+	projectId: z.string().nullable().describe('the project id'),
+});
+
+export const SandboxListDataSchema = z.object({
+	sandboxes: z.array(SandboxInfoSchema).describe('list of sandboxes'),
+	total: z.number().describe('total count of matching sandboxes'),
+});
+
+export const SandboxListResponseSchema = APIResponseSchema(SandboxListDataSchema);
+
+export type CLISandboxListResponse = z.infer<typeof SandboxListResponseSchema>;
+export type CLISandboxListData = z.infer<typeof SandboxListDataSchema>;
+export type CLISandboxInfo = z.infer<typeof SandboxInfoSchema>;
+
+export interface CLISandboxListOptions {
+	/**
+	 * Filter by sandbox name
+	 */
+	name?: string;
+	/**
+	 * Filter by sandbox mode
+	 */
+	mode?: 'oneshot' | 'interactive';
+	/**
+	 * Filter by specific project ID
+	 */
+	projectId?: string;
+	/**
+	 * Filter by specific organization ID
+	 */
+	orgId?: string;
+	/**
+	 * Filter by sandbox status
+	 */
+	status?:
+		| 'creating'
+		| 'idle'
+		| 'running'
+		| 'paused'
+		| 'stopping'
+		| 'suspended'
+		| 'terminated'
+		| 'failed';
+	/**
+	 * Maximum number of sandboxes to return (default: 50, max: 100)
+	 */
+	limit?: number;
+	/**
+	 * Number of sandboxes to skip for pagination
+	 */
+	offset?: number;
+	/**
+	 * Field to sort by
+	 */
+	sort?: string;
+	/**
+	 * Sort direction (default: 'desc')
+	 */
+	direction?: 'asc' | 'desc';
+}
+
+/**
+ * List sandboxes with optional filtering using the CLI API endpoint.
+ *
+ * This endpoint searches across all organizations the user is a member of,
+ * unlike the Catalyst API which requires an orgId.
+ *
+ * @param client - The API client
+ * @param options - Filtering and pagination options
+ * @returns A promise that resolves to the list of sandboxes
+ *
+ * @example
+ * // List all sandboxes across all orgs
+ * const result = await cliSandboxList(client);
+ * console.log(`Found ${result.total} sandboxes`);
+ *
+ * @example
+ * // List running sandboxes
+ * const result = await cliSandboxList(client, { status: 'running' });
+ *
+ * @example
+ * // List sandboxes for a specific project
+ * const result = await cliSandboxList(client, { projectId: 'proj_123' });
+ */
+export async function cliSandboxList(
+	client: APIClient,
+	options: CLISandboxListOptions = {}
+): Promise<CLISandboxListData> {
+	const { projectId, orgId, status, limit, offset, sort, direction } = options;
+	const params = new URLSearchParams();
+
+	if (options.name) params.set('name', options.name);
+	if (options.mode) params.set('mode', options.mode);
+	if (projectId) params.set('projectId', projectId);
+	if (orgId) params.set('orgId', orgId);
+	if (status) params.set('status', status);
+	if (limit !== undefined) params.set('limit', limit.toString());
+	if (offset !== undefined) params.set('offset', offset.toString());
+	if (sort) params.set('sort', sort);
+	if (direction) params.set('direction', direction);
+
+	const queryString = params.toString();
+	const resp = await client.request<CLISandboxListResponse>(
+		'GET',
+		`/cli/sandbox${queryString ? `?${queryString}` : ''}`,
+		SandboxListResponseSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new SandboxResponseError({ message: resp.message });
+}