@agentuity/server 0.0.42 → 0.0.44

package/src/api/api.ts

@@ -9,6 +9,7 @@
  */
 
 import { z } from 'zod';
+import type { Logger } from '@agentuity/core';
 
 export interface APIErrorResponse {
 	success: boolean;
@@ -24,14 +25,19 @@ export interface APIErrorResponse {
 export interface APIClientConfig {
 	skipVersionCheck?: boolean;
 	userAgent?: string;
+	maxRetries?: number;
+	retryDelayMs?: number;
 }
 
 export class ValidationError extends Error {
+	public url: string;
 	constructor(
+		url: string,
 		message: string,
 		public issues: z.ZodIssue[]
 	) {
 		super(message);
+		this.url = url;
 		this.name = 'ValidationError';
 	}
 }
@@ -55,33 +61,39 @@ export class APIError extends Error {
 }
 
 export class APIClient {
-	private baseUrl: string;
-	private apiKey?: string;
-	private config?: APIClientConfig;
+	#baseUrl: string;
+	#apiKey?: string;
+	#config?: APIClientConfig;
+	#logger: Logger;
 
-	constructor(baseUrl: string, config?: APIClientConfig);
-	constructor(baseUrl: string, apiKey: string, config?: APIClientConfig);
+	constructor(baseUrl: string, logger: Logger, config?: APIClientConfig);
+	constructor(baseUrl: string, logger: Logger, apiKey: string, config?: APIClientConfig);
 	constructor(
 		baseUrl: string,
+		logger: Logger,
 		apiKeyOrConfig?: string | APIClientConfig,
 		config?: APIClientConfig
 	) {
-		this.baseUrl = baseUrl;
+		this.#baseUrl = baseUrl;
+		this.#logger = logger;
 
-		// Detect if second parameter is apiKey (string) or config (object)
+		// Detect if third parameter is apiKey (string) or config (object)
 		if (typeof apiKeyOrConfig === 'string') {
-			this.apiKey = apiKeyOrConfig;
-			this.config = config;
+			this.#apiKey = apiKeyOrConfig;
+			this.#config = config;
 		} else {
-			this.apiKey = undefined;
-			this.config = apiKeyOrConfig;
+			this.#apiKey = undefined;
+			this.#config = apiKeyOrConfig;
+		}
+		if (!this.#apiKey && process.env.AGENTUITY_SDK_KEY) {
+			this.#apiKey = process.env.AGENTUITY_SDK_KEY;
 		}
 	}
 
-	async request<TResponse, TBody = unknown>(
+	async request<TResponse = void, TBody = unknown>(
 		method: string,
 		endpoint: string,
-		responseSchema: z.ZodType<TResponse>,
+		responseSchema?: z.ZodType<TResponse>,
 		body?: TBody,
 		bodySchema?: z.ZodType<TBody>
 	): Promise<TResponse> {
@@ -90,13 +102,14 @@ export class APIClient {
 			const validationResult = bodySchema.safeParse(body);
 			if (!validationResult.success) {
 				throw new ValidationError(
+					endpoint,
 					'Request body validation failed',
 					validationResult.error.issues
 				);
 			}
 		}
 
-		const response = await this.makeRequest(method, endpoint, body);
+		const response = await this.#makeRequest(method, endpoint, body);
 
 		// Handle empty responses (204 or zero-length body)
 		let data: unknown;
@@ -108,7 +121,7 @@ export class APIClient {
 				data = null;
 			} else {
 				const contentType = response.headers.get('content-type');
-				if (contentType && contentType.includes('application/json')) {
+				if (contentType?.includes('application/json')) {
 					data = JSON.parse(text);
 				} else {
 					data = text;
@@ -116,105 +129,225 @@ export class APIClient {
 			}
 		}
 
-		// Validate response
-		const validationResult = responseSchema.safeParse(data);
-		if (!validationResult.success) {
-			throw new ValidationError('Response validation failed', validationResult.error.issues);
+		if (responseSchema) {
+			// Validate response
+			const validationResult = responseSchema.safeParse(data);
+			if (!validationResult.success) {
+				throw new ValidationError(
+					endpoint,
+					'Response validation failed',
+					validationResult.error.issues
+				);
+			}
+
+			return validationResult.data;
 		}
 
-		return validationResult.data;
+		return undefined as TResponse;
 	}
 
-	private async makeRequest(method: string, endpoint: string, body?: unknown): Promise<Response> {
-		const url = `${this.baseUrl}${endpoint}`;
-		const headers: Record<string, string> = {
-			'Content-Type': 'application/json',
-		};
+	async #makeRequest(method: string, endpoint: string, body?: unknown): Promise<Response> {
+		const maxRetries = this.#config?.maxRetries ?? 3;
+		const baseDelayMs = this.#config?.retryDelayMs ?? 100;
 
-		if (this.config?.userAgent) {
-			headers['User-Agent'] = this.config.userAgent;
-		}
+		for (let attempt = 0; attempt <= maxRetries; attempt++) {
+			try {
+				const url = `${this.#baseUrl}${endpoint}`;
+				const headers: Record<string, string> = {
+					'Content-Type': 'application/json',
+				};
 
-		if (this.apiKey) {
-			headers['Authorization'] = `Bearer ${this.apiKey}`;
-		}
+				if (this.#config?.userAgent) {
+					headers['User-Agent'] = this.#config.userAgent;
+				}
 
-		const response = await fetch(url, {
-			method,
-			headers,
-			body: body !== undefined ? JSON.stringify(body) : undefined,
-		});
+				if (this.#apiKey) {
+					headers['Authorization'] = `Bearer ${this.#apiKey}`;
+				}
 
-		if (!response.ok) {
-			const responseBody = await response.text();
+				const response = await fetch(url, {
+					method,
+					headers,
+					body: body !== undefined ? JSON.stringify(body) : undefined,
+				});
+
+				// Check if we should retry on specific status codes (409, 501, 503)
+				const retryableStatuses = [409, 501, 503];
+				if (retryableStatuses.includes(response.status) && attempt < maxRetries) {
+					let delayMs = this.#getRetryDelay(attempt, baseDelayMs);
+
+					// For 409, check for rate limit headers
+					if (response.status === 409) {
+						const rateLimitDelay = this.#getRateLimitDelay(response);
+						if (rateLimitDelay !== null) {
+							delayMs = rateLimitDelay;
+							this.#logger.debug(
+								`Got 409 with rate limit headers, waiting ${delayMs}ms (attempt ${attempt + 1}/${maxRetries + 1})`
+							);
+						} else {
+							this.#logger.debug(
+								`Got 409, retrying with backoff ${delayMs}ms (attempt ${attempt + 1}/${maxRetries + 1})`
+							);
+						}
+					} else {
+						this.#logger.debug(
+							`Got ${response.status}, retrying (attempt ${attempt + 1}/${maxRetries + 1})`
+						);
+					}
 
-			// Try to parse error response
-			let errorData: APIErrorResponse | null = null;
-			try {
-				errorData = JSON.parse(responseBody) as APIErrorResponse;
-			} catch {
-				// Not JSON, ignore
-			}
+					await this.#sleep(delayMs);
+					continue;
+				}
 
-			if (process.env.DEBUG) {
-				// Sanitize headers to avoid leaking API keys
-				const sanitizedHeaders = { ...headers };
-				for (const key in sanitizedHeaders) {
-					if (key.toLowerCase() === 'authorization') {
-						sanitizedHeaders[key] = 'REDACTED';
+				// Handle error responses
+				if (!response.ok) {
+					const responseBody = await response.text();
+
+					// Try to parse error response
+					let errorData: APIErrorResponse | null = null;
+					try {
+						errorData = JSON.parse(responseBody) as APIErrorResponse;
+					} catch {
+						// Not JSON, ignore
 					}
-				}
 
-				console.error('API Error Details:');
-				console.error('  URL:', url);
-				console.error('  Method:', method);
-				console.error('  Status:', response.status, response.statusText);
-				console.error('  Headers:', JSON.stringify(sanitizedHeaders, null, 2));
-				console.error('  Response:', responseBody);
-			}
+					// Sanitize headers to avoid leaking API keys
+					const sanitizedHeaders = { ...headers };
+					for (const key in sanitizedHeaders) {
+						if (key.toLowerCase() === 'authorization') {
+							sanitizedHeaders[key] = 'REDACTED';
+						}
+					}
+
+					this.#logger.debug('API Error Details:');
+					this.#logger.debug('  URL:', url);
+					this.#logger.debug('  Method:', method);
+					this.#logger.debug('  Status:', response.status, response.statusText);
+					this.#logger.debug('  Headers:', JSON.stringify(sanitizedHeaders, null, 2));
+					this.#logger.debug('  Response:', responseBody);
+
+					// Check for UPGRADE_REQUIRED error
+					if (errorData?.code === 'UPGRADE_REQUIRED') {
+						// Skip version check if configured
+						if (this.#config?.skipVersionCheck) {
+							this.#logger.debug('Skipping version check (configured to skip)');
+							// Request is still rejected, but throw UpgradeRequiredError so callers
+							// can detect it and handle UI behavior (e.g., suppress banner) based on skip flag
+							throw new UpgradeRequiredError(
+								errorData.message ||
+									'Version check skipped, but request failed. Try upgrading the client.'
+							);
+						}
+
+						throw new UpgradeRequiredError(
+							errorData.message || 'Please upgrade to the latest version'
+						);
+					}
 
-			// Check for UPGRADE_REQUIRED error
-			if (errorData?.code === 'UPGRADE_REQUIRED') {
-				// Skip version check if configured
-				if (this.config?.skipVersionCheck) {
-					if (process.env.DEBUG) {
-						console.error('[DEBUG] Skipping version check (configured to skip)');
+					// Handle Zod validation errors from the API
+					if (errorData?.error?.name === 'ZodError' && errorData.error.issues) {
+						throw new ValidationError(url, 'API validation failed', errorData.error.issues);
 					}
-					// Request is still rejected, but throw UpgradeRequiredError so callers
-					// can detect it and handle UI behavior (e.g., suppress banner) based on skip flag
-					throw new UpgradeRequiredError(
-						errorData.message ||
-							'Version check skipped, but request failed. Try upgrading the client.'
+
+					// Throw with message from API if available
+					if (errorData?.message) {
+						throw new APIError(errorData.message, response.status, errorData.code);
+					}
+
+					throw new APIError(
+						`API error: ${response.status} ${response.statusText}`,
+						response.status
 					);
 				}
 
-				throw new UpgradeRequiredError(
-					errorData.message || 'Please upgrade to the latest version'
-				);
-			}
+				// Successful response; handle empty bodies (e.g., 204 No Content)
+				if (response.status === 204 || response.headers.get('content-length') === '0') {
+					return new Response(null, { status: 204 });
+				}
 
-			// Handle Zod validation errors from the API
-			if (errorData?.error?.name === 'ZodError' && errorData.error.issues) {
-				throw new ValidationError('API validation failed', errorData.error.issues);
-			}
+				return response;
+			} catch (error) {
+				// Check if it's a retryable connection error
+				const isRetryable = this.#isRetryableError(error);
+
+				if (isRetryable && attempt < maxRetries) {
+					this.#logger.debug(
+						`Connection error, retrying (attempt ${attempt + 1}/${maxRetries + 1}):`,
+						error
+					);
+					await this.#sleep(this.#getRetryDelay(attempt, baseDelayMs));
+					continue;
+				}
 
-			// Throw with message from API if available
-			if (errorData?.message) {
-				throw new APIError(errorData.message, response.status, errorData.code);
+				throw error;
 			}
+		}
+
+		throw new Error('Max retries exceeded');
+	}
 
-			throw new APIError(
-				`API error: ${response.status} ${response.statusText}`,
-				response.status
+	#isRetryableError(error: unknown): boolean {
+		if (error && typeof error === 'object') {
+			const err = error as { code?: string; errno?: number };
+			// Retryable connection errors
+			return (
+				err.code === 'ECONNRESET' ||
+				err.code === 'ETIMEDOUT' ||
+				err.code === 'ECONNREFUSED' ||
+				err.code === 'ENOTFOUND'
 			);
 		}
+		return false;
+	}
 
-		// Successful response; handle empty bodies (e.g., 204 No Content)
-		if (response.status === 204 || response.headers.get('content-length') === '0') {
-			return new Response(null, { status: 204 });
+	#getRetryDelay(attempt: number, baseDelayMs: number): number {
+		// Exponential backoff with jitter: delay = base * 2^attempt * (0.5 + random(0, 0.5))
+		const exponentialDelay = baseDelayMs * Math.pow(2, attempt);
+		const jitter = 0.5 + Math.random() * 0.5;
+		return Math.floor(exponentialDelay * jitter);
+	}
+
+	#sleep(ms: number): Promise<void> {
+		return new Promise((resolve) => setTimeout(resolve, ms));
+	}
+
+	#getRateLimitDelay(response: Response): number | null {
+		// Check for Retry-After header (standard HTTP)
+		const retryAfter = response.headers.get('Retry-After');
+		if (retryAfter) {
+			// Can be either seconds or HTTP date
+			const seconds = parseInt(retryAfter, 10);
+			if (!isNaN(seconds)) {
+				return seconds * 1000; // Convert to milliseconds
+			}
+			// Try parsing as HTTP date
+			const retryDate = new Date(retryAfter);
+			if (!isNaN(retryDate.getTime())) {
+				const delayMs = retryDate.getTime() - Date.now();
+				return Math.max(0, delayMs);
+			}
+		}
+
+		// Check for X-RateLimit-Reset (Unix timestamp in seconds)
+		const rateLimitReset = response.headers.get('X-RateLimit-Reset');
+		if (rateLimitReset) {
+			const resetTime = parseInt(rateLimitReset, 10);
+			if (!isNaN(resetTime)) {
+				const delayMs = resetTime * 1000 - Date.now();
+				return Math.max(0, delayMs);
+			}
+		}
+
+		// Check for X-RateLimit-Retry-After (seconds)
+		const rateLimitRetryAfter = response.headers.get('X-RateLimit-Retry-After');
+		if (rateLimitRetryAfter) {
+			const seconds = parseInt(rateLimitRetryAfter, 10);
+			if (!isNaN(seconds)) {
+				return seconds * 1000;
+			}
 		}
 
-		return response;
+		return null;
 	}
 }
 
@@ -243,8 +376,36 @@ export function getAppBaseURL(overrides?: { app_url?: string }): string {
 }
 
 export const APIResponseSchema = <T extends z.ZodType>(dataSchema: T) =>
-	z.object({
-		success: z.boolean(),
-		message: z.string().optional().describe('the error message if success=false'),
-		data: dataSchema.optional(),
-	});
+	z.discriminatedUnion('success', [
+		z.object({
+			success: z.literal<false>(false),
+			message: z.string().describe('the error message'),
+		}),
+		z.object({
+			success: z.literal<true>(true),
+			data: dataSchema,
+		}),
+	]);
+
+export const APIResponseSchemaOptionalData = <T extends z.ZodType>(dataSchema: T) =>
+	z.discriminatedUnion('success', [
+		z.object({
+			success: z.literal<false>(false),
+			message: z.string().describe('the error message'),
+		}),
+		z.object({
+			success: z.literal<true>(true),
+			data: dataSchema.optional(),
+		}),
+	]);
+
+export const APIResponseSchemaNoData = () =>
+	z.discriminatedUnion('success', [
+		z.object({
+			success: z.literal<false>(false),
+			message: z.string().describe('the error message'),
+		}),
+		z.object({
+			success: z.literal<true>(true),
+		}),
+	]);

package/src/api/index.ts

@@ -1,3 +1,5 @@
 export * from './api';
 export * from './org';
 export * from './project';
+export * from './region';
+export * from './user';

package/src/api/org/list.ts

@@ -1,17 +1,16 @@
 import { z } from 'zod';
 import { APIResponseSchema, APIClient } from '../api';
 
-const ListOrganizationsResponseSchema = APIResponseSchema(
-	z.array(
-		z.object({
-			id: z.string().describe('the unique id for the organization'),
-			name: z.string().describe('the name of the organization'),
-		})
-	)
+const ListOrganizationsResponse = z.array(
+	z.object({
+		id: z.string().describe('the unique id for the organization'),
+		name: z.string().describe('the name of the organization'),
+	})
 );
+const ListOrganizationsResponseSchema = APIResponseSchema(ListOrganizationsResponse);
 
 export type ListOrganizationsResponse = z.infer<typeof ListOrganizationsResponseSchema>;
-export type OrganizationList = NonNullable<ListOrganizationsResponse['data']>;
+export type OrganizationList = z.infer<typeof ListOrganizationsResponse>;
 
 /**
  * List all organizations
@@ -19,10 +18,14 @@ export type OrganizationList = NonNullable<ListOrganizationsResponse['data']>;
  * @param client
  * @returns
  */
-export async function listOrganizations(client: APIClient): Promise<ListOrganizationsResponse> {
-	return client.request<ListOrganizationsResponse>(
+export async function listOrganizations(client: APIClient): Promise<OrganizationList> {
+	const resp = await client.request<ListOrganizationsResponse>(
 		'GET',
 		'/cli/organization',
 		ListOrganizationsResponseSchema
 	);
+	if (resp.success) {
+		return resp.data;
+	}
+	throw new Error(resp.message);
 }

package/src/api/project/create.ts

@@ -11,16 +11,17 @@ const CreateProjectRequestSchema = z.object({
 	provider: z.string().max(255).min(1),
 });
 
-const CreateProjectResponseSchema = APIResponseSchema(
-	z.object({
-		id: z.string().describe('the unique id for the project'),
-		api_key: z.string().describe('the SDK api key for the project'),
-		projectKey: z.string().describe('the Project api key for the project'),
-	})
-);
+const CreateProjectResponse = z.object({
+	id: z.string().describe('the unique id for the project'),
+	api_key: z.string().describe('the SDK api key for the project'),
+	projectKey: z.string().describe('the Project api key for the project'),
+});
+
+const CreateProjectResponseSchema = APIResponseSchema(CreateProjectResponse);
 
 export type CreateProjectRequest = z.infer<typeof CreateProjectRequestSchema>;
 export type CreateProjectResponse = z.infer<typeof CreateProjectResponseSchema>;
+export type NewProject = Omit<z.infer<typeof CreateProjectResponse>, 'projectKey'>;
 
 /**
  * Create a new Project
@@ -32,12 +33,16 @@ export type CreateProjectResponse = z.infer<typeof CreateProjectResponseSchema>;
 export async function projectCreate(
 	client: APIClient,
 	body: CreateProjectRequest
-): Promise<Omit<CreateProjectResponse, 'projectKey'>> {
-	return client.request<CreateProjectResponse, CreateProjectRequest>(
+): Promise<NewProject> {
+	const resp = await client.request<CreateProjectResponse, CreateProjectRequest>(
 		'POST',
 		'/cli/project',
 		CreateProjectResponseSchema,
 		body,
 		CreateProjectRequestSchema
 	);
+	if (resp.success) {
+		return resp.data;
+	}
+	throw new Error(resp.message);
 }

package/src/api/project/delete.ts

@@ -7,7 +7,7 @@ const ProjectDeleteResponseSchema = APIResponseSchema(z.array(z.string()));
 type ProjectDeleteRequest = z.infer<typeof ProjectDeleteRequestSchema>;
 type ProjectDeleteResponse = z.infer<typeof ProjectDeleteResponseSchema>;
 
-export async function projectDelete(client: APIClient, ...ids: string[]) {
+export async function projectDelete(client: APIClient, ...ids: string[]): Promise<string[]> {
 	const resp = await client.request<ProjectDeleteResponse, ProjectDeleteRequest>(
 		'DELETE',
 		'/cli/project',
@@ -16,7 +16,7 @@ export async function projectDelete(client: APIClient, ...ids: string[]) {
 		ProjectDeleteRequestSchema
 	);
 
-	if (resp.data) {
+	if (resp.success) {
 		return resp.data;
 	}