@agentuity/server 0.0.35 → 0.0.37

package/src/api/api-example.md

@@ -0,0 +1,155 @@
+# APIClient Usage Examples
+
+The `APIClient` has a friendly interface with built-in Zod schema validation.
+
+## Public API (no authentication)
+
+```typescript
+import { APIClient } from '@agentuity/server';
+
+// Simple - just URL and optional config
+const client = new APIClient('https://api.agentuity.com');
+
+// With config
+const client = new APIClient('https://api.agentuity.com', {
+	skipVersionCheck: true,
+	userAgent: 'MyApp/1.0.0',
+});
+```
+
+## Authenticated API
+
+```typescript
+import { APIClient } from '@agentuity/server';
+
+const apiKey = 'your-api-key';
+
+// With API key
+const client = new APIClient('https://api.agentuity.com', apiKey);
+
+// With API key and config
+const client = new APIClient('https://api.agentuity.com', apiKey, {
+	skipVersionCheck: true,
+	userAgent: 'MyApp/1.0.0',
+});
+```
+
+## Making Requests
+
+All requests require a response schema for validation:
+
+```typescript
+import { APIClient, z, ValidationError } from '@agentuity/server';
+
+// Define schemas
+const UserSchema = z.object({
+	id: z.string(),
+	name: z.string(),
+	email: z.string().email(),
+});
+
+const CreateUserSchema = z.object({
+	name: z.string(),
+	email: z.string().email(),
+});
+
+const client = new APIClient('https://api.agentuity.com', apiKey);
+
+// GET request with response validation
+try {
+	const user = await client.request(
+		'GET',
+		'/users/123',
+		UserSchema // response schema (required)
+	);
+	console.log(user.name); // Fully typed!
+} catch (error) {
+	if (error instanceof ValidationError) {
+		console.error('Validation failed:', error.issues);
+	}
+}
+
+// POST request with request and response validation
+const newUser = await client.request(
+	'POST',
+	'/users',
+	UserSchema, // response schema (required)
+	{
+		// request body
+		name: 'John Doe',
+		email: 'john@example.com',
+	},
+	CreateUserSchema // request body schema (optional)
+);
+```
+
+## API Response Wrapper Pattern
+
+For APIs that wrap responses in a standard format:
+
+```typescript
+import { z } from '@agentuity/server';
+
+// Generic wrapper schema
+const APIResponseSchema = <T extends z.ZodType>(dataSchema: T) =>
+	z.object({
+		success: z.boolean(),
+		message: z.string(),
+		data: dataSchema.optional(),
+	});
+
+// Use it
+const UserDataSchema = z.object({ id: z.string(), name: z.string() });
+
+const response = await client.request('GET', '/users/123', APIResponseSchema(UserDataSchema));
+
+if (response.success && response.data) {
+	console.log(response.data.name);
+}
+```
+
+## CLI-specific Usage
+
+The CLI wrapper automatically handles version checking and user agent:
+
+```typescript
+import { APIClient, z } from '@agentuity/cli';
+import type { Config } from '@agentuity/cli';
+
+const config: Config = {
+	/* ... */
+};
+
+// Public API
+const client = new APIClient('https://api.agentuity.com', config);
+
+// Authenticated API
+const client = new APIClient('https://api.agentuity.com', apiKey, config);
+
+// Making requests (schema validation is built-in)
+const ResponseSchema = z.object({
+	/* ... */
+});
+const data = await client.request('GET', '/endpoint', ResponseSchema);
+```
+
+## Error Handling
+
+```typescript
+import { APIClient, APIError, ValidationError, UpgradeRequiredError } from '@agentuity/server';
+
+try {
+	const data = await client.request('GET', '/endpoint', schema);
+} catch (error) {
+	if (error instanceof ValidationError) {
+		// Response didn't match schema
+		console.error('Validation error:', error.issues);
+	} else if (error instanceof APIError) {
+		// HTTP error from API
+		console.error(`API error ${error.status}:`, error.message);
+	} else if (error instanceof UpgradeRequiredError) {
+		// Client needs upgrade
+		console.error('Please upgrade:', error.message);
+	}
+}
+```

package/src/api/api.ts

@@ -0,0 +1,241 @@
+/**
+ * API Client for Agentuity Platform
+ *
+ * Handles HTTP requests to the API with automatic error parsing and User-Agent headers.
+ *
+ * Error handling:
+ * - UPGRADE_REQUIRED (409): Throws UpgradeRequiredError
+ * - Other errors: Throws Error with API message or status text
+ */
+
+import { z } from 'zod';
+
+export interface APIErrorResponse {
+	success: boolean;
+	code?: string;
+	message: string;
+	details?: Record<string, unknown>;
+}
+
+export interface APIClientConfig {
+	skipVersionCheck?: boolean;
+	userAgent?: string;
+}
+
+export class ValidationError extends Error {
+	constructor(
+		message: string,
+		public issues: z.ZodIssue[]
+	) {
+		super(message);
+		this.name = 'ValidationError';
+	}
+}
+
+export class UpgradeRequiredError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = 'UpgradeRequiredError';
+	}
+}
+
+export class APIError extends Error {
+	constructor(
+		message: string,
+		public status: number,
+		public code?: string
+	) {
+		super(message);
+		this.name = 'APIError';
+	}
+}
+
+export class APIClient {
+	private baseUrl: string;
+	private apiKey?: string;
+	private config?: APIClientConfig;
+
+	constructor(baseUrl: string, config?: APIClientConfig);
+	constructor(baseUrl: string, apiKey: string, config?: APIClientConfig);
+	constructor(
+		baseUrl: string,
+		apiKeyOrConfig?: string | APIClientConfig,
+		config?: APIClientConfig
+	) {
+		this.baseUrl = baseUrl;
+
+		// Detect if second parameter is apiKey (string) or config (object)
+		if (typeof apiKeyOrConfig === 'string') {
+			this.apiKey = apiKeyOrConfig;
+			this.config = config;
+		} else {
+			this.apiKey = undefined;
+			this.config = apiKeyOrConfig;
+		}
+	}
+
+	async request<TResponse, TBody = unknown>(
+		method: string,
+		endpoint: string,
+		responseSchema: z.ZodType<TResponse>,
+		body?: TBody,
+		bodySchema?: z.ZodType<TBody>
+	): Promise<TResponse> {
+		// Validate request body if schema provided
+		if (body !== undefined && bodySchema) {
+			const validationResult = bodySchema.safeParse(body);
+			if (!validationResult.success) {
+				throw new ValidationError(
+					'Request body validation failed',
+					validationResult.error.issues
+				);
+			}
+		}
+
+		const response = await this.makeRequest(method, endpoint, body);
+
+		// Handle empty responses (204 or zero-length body)
+		let data: unknown;
+		if (response.status === 204 || response.headers.get('content-length') === '0') {
+			data = null;
+		} else {
+			const text = await response.text();
+			if (text === '') {
+				data = null;
+			} else {
+				const contentType = response.headers.get('content-type');
+				if (contentType && contentType.includes('application/json')) {
+					data = JSON.parse(text);
+				} else {
+					data = text;
+				}
+			}
+		}
+
+		// Validate response
+		const validationResult = responseSchema.safeParse(data);
+		if (!validationResult.success) {
+			throw new ValidationError('Response validation failed', validationResult.error.issues);
+		}
+
+		return validationResult.data;
+	}
+
+	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',
+		};
+
+		if (this.config?.userAgent) {
+			headers['User-Agent'] = this.config.userAgent;
+		}
+
+		if (this.apiKey) {
+			headers['Authorization'] = `Bearer ${this.apiKey}`;
+		}
+
+		const response = await fetch(url, {
+			method,
+			headers,
+			body: body !== undefined ? JSON.stringify(body) : undefined,
+		});
+
+		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
+			}
+
+			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';
+					}
+				}
+
+				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);
+			}
+
+			// 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)');
+					}
+					// 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'
+				);
+			}
+
+			// 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
+			);
+		}
+
+		// 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 });
+		}
+
+		return response;
+	}
+}
+
+export function getAPIBaseURL(overrides?: { api_url?: string }): string {
+	if (process.env.AGENTUITY_API_URL) {
+		return process.env.AGENTUITY_API_URL;
+	}
+
+	if (overrides?.api_url) {
+		return overrides.api_url;
+	}
+
+	return 'https://api.agentuity.com';
+}
+
+export function getAppBaseURL(overrides?: { app_url?: string }): string {
+	if (process.env.AGENTUITY_APP_URL) {
+		return process.env.AGENTUITY_APP_URL;
+	}
+
+	if (overrides?.app_url) {
+		return overrides.app_url;
+	}
+
+	return 'https://app.agentuity.com';
+}
+
+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(),
+	});

package/src/api/index.ts

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

package/src/api/org/index.ts

@@ -0,0 +1 @@
+export * from './list';

package/src/api/org/list.ts

@@ -0,0 +1,28 @@
+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'),
+		})
+	)
+);
+
+export type ListOrganizationsResponse = z.infer<typeof ListOrganizationsResponseSchema>;
+export type OrganizationList = NonNullable<ListOrganizationsResponse['data']>;
+
+/**
+ * List all organizations
+ *
+ * @param client
+ * @returns
+ */
+export async function listOrganizations(client: APIClient): Promise<ListOrganizationsResponse> {
+	return client.request<ListOrganizationsResponse>(
+		'GET',
+		'/cli/organization',
+		ListOrganizationsResponseSchema
+	);
+}

package/src/api/project/create.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { APIClient, APIResponseSchema } from '../api';
+
+const CreateProjectRequestSchema = z.object({
+	name: z.string().max(255).min(1).describe('the name of the new project'),
+	organization_id: z
+		.string()
+		.max(255)
+		.min(1)
+		.describe('the organization id to create the project in'),
+	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'),
+	})
+);
+
+export type CreateProjectRequest = z.infer<typeof CreateProjectRequestSchema>;
+export type CreateProjectResponse = z.infer<typeof CreateProjectResponseSchema>;
+
+/**
+ * Create a new Project
+ *
+ * @param client
+ * @param body
+ * @returns
+ */
+export async function createProject(
+	client: APIClient,
+	body: CreateProjectRequest
+): Promise<Omit<CreateProjectResponse, 'projectKey'>> {
+	return client.request<CreateProjectResponse, CreateProjectRequest>(
+		'POST',
+		'/cli/project',
+		CreateProjectResponseSchema,
+		body,
+		CreateProjectRequestSchema
+	);
+}

package/src/api/project/exists.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+import { APIClient, APIResponseSchema, APIError } from '../api';
+
+// func ProjectWithNameExists(ctx context.Context, logger logger.Logger, baseUrl string, token string, orgId string, name string) (bool, error) {
+// 	client := util.NewAPIClient(ctx, logger, baseUrl, token)
+
+// 	var resp Response[bool]
+// 	if err := client.Do("GET", fmt.Sprintf("/cli/project/exists/%s?orgId=%s", url.PathEscape(name), url.PathEscape(orgId)), nil, &resp); err != nil {
+// 		var apiErr *util.APIError
+// 		if errors.As(err, &apiErr) {
+// 			if apiErr.Status == http.StatusConflict {
+// 				return true, nil
+// 			}
+// 			if apiErr.Status == http.StatusUnprocessableEntity {
+// 				return false, apiErr
+// 			}
+// 		}
+// 		return false, fmt.Errorf("error validating project name: %w", err)
+// 	}
+// 	return resp.Data, nil
+// }
+
+const _ProjectExistsRequestSchema = z.object({
+	name: z.string().max(255).min(1).describe('the name of the new project'),
+	organization_id: z
+		.string()
+		.max(255)
+		.min(1)
+		.describe('the organization id to create the project in'),
+});
+
+const ProjectExistsResponseSchema = APIResponseSchema(z.boolean());
+
+export type ProjectExistsRequest = z.infer<typeof _ProjectExistsRequestSchema>;
+export type ProjectExistsResponse = z.infer<typeof ProjectExistsResponseSchema>;
+
+/**
+ * Create a new Project
+ *
+ * @param client
+ * @param body
+ * @returns
+ */
+export async function projectExists(
+	client: APIClient,
+	body: ProjectExistsRequest
+): Promise<boolean> {
+	const qs = new URLSearchParams();
+	qs.set('orgId', body.organization_id);
+	try {
+		const resp = await client.request<ProjectExistsResponse, ProjectExistsRequest>(
+			'GET',
+			`/cli/project/exists/${encodeURIComponent(body.name)}?${qs.toString()}`,
+			ProjectExistsResponseSchema
+		);
+
+		if (resp.data) {
+			return resp.data;
+		}
+
+		return false;
+	} catch (ex) {
+		const _ex = ex as Error;
+		if (_ex.name === 'APIError') {
+			const apiError = _ex as APIError;
+			switch (apiError.status) {
+				case 409:
+					return true;
+				case 422:
+					return false;
+				default:
+			}
+		}
+		throw ex;
+	}
+}

package/src/api/project/index.ts

@@ -0,0 +1,2 @@
+export * from './create';
+export * from './exists';

package/src/config.ts

@@ -0,0 +1,20 @@
+export interface ServiceUrls {
+	keyvalue: string;
+	objectstore: string;
+	stream: string;
+	vector: string;
+}
+
+/**
+ * Get service URLs from environment variables with fallback defaults
+ */
+export function getServiceUrls(): ServiceUrls {
+	const transportUrl = process.env.AGENTUITY_TRANSPORT_URL || 'https://agentuity.ai';
+
+	return {
+		keyvalue: process.env.AGENTUITY_KEYVALUE_URL || transportUrl,
+		objectstore: process.env.AGENTUITY_OBJECTSTORE_URL || transportUrl,
+		stream: process.env.AGENTUITY_STREAM_URL || 'https://streams.agentuity.cloud',
+		vector: process.env.AGENTUITY_VECTOR_URL || transportUrl,
+	};
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export * from './config';
+export * from './server';
+export * from './api';
+export { z } from 'zod';
+export type {
+	FetchAdapter,
+	FetchRequest,
+	FetchResponse,
+	FetchSuccessResponse,
+	FetchErrorResponse,
+	Body,
+	ServiceException,
+} from '@agentuity/core';
+export { buildUrl, toServiceException, toPayload, fromResponse } from '@agentuity/core';