@agentuity/core 1.0.32 → 1.0.33

package/src/api/apikey/create.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { APIClient, APIResponseSchema } from '../api.ts';
+import { APIKeyResponseError } from './util.ts';
+
+export const APIKeyCreateResponseSchema = z.object({
+	id: z.string().describe('the API key id'),
+	value: z.string().describe('the API key value'),
+});
+
+export const APIKeyCreateFullResponseSchema = APIResponseSchema(APIKeyCreateResponseSchema);
+
+type _APIKeyCreateFullResponse = z.infer<typeof APIKeyCreateFullResponseSchema>;
+
+export type APIKeyCreateResponse = z.infer<typeof APIKeyCreateResponseSchema>;
+
+export interface APIKeyCreateRequest {
+	name: string;
+	expiresAt: string;
+	projectId?: string | null;
+	orgId?: string | null;
+}
+
+/**
+ * Create a new API key
+ *
+ * @param client
+ * @param request the API key creation request
+ * @returns
+ */
+export async function apikeyCreate(
+	client: APIClient,
+	request: APIKeyCreateRequest
+): Promise<APIKeyCreateResponse> {
+	const resp = await client.post('/cli/apikey', request, APIKeyCreateFullResponseSchema);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new APIKeyResponseError({ message: resp.message });
+}

package/src/api/apikey/delete.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import { APIClient, APIResponseSchema } from '../api.ts';
+import { APIKeyResponseError } from './util.ts';
+
+export const APIKeyDeleteResponseSchema = APIResponseSchema(
+	z.number().describe('number of rows affected')
+);
+
+type APIKeyDeleteResponse = z.infer<typeof APIKeyDeleteResponseSchema>;
+
+/**
+ * Delete an API key (soft delete)
+ *
+ * @param client
+ * @param id the API key id to delete
+ * @returns number of rows affected
+ */
+export async function apikeyDelete(client: APIClient, id: string): Promise<number> {
+	const resp = await client.request<APIKeyDeleteResponse>(
+		'DELETE',
+		`/cli/apikey/${id}`,
+		APIKeyDeleteResponseSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new APIKeyResponseError({ message: resp.message });
+}

package/src/api/apikey/get.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { APIClient, APIResponseSchema } from '../api.ts';
+import { APIKeyResponseError } from './util.ts';
+
+export const APIKeyDetailSchema = z.object({
+	id: z.string().describe('the API key id'),
+	name: z.string().describe('the API key name'),
+	orgId: z.string().describe('the organization id'),
+	type: z.string().describe('the API key type'),
+	expiresAt: z.string().datetime().nullable().describe('the expiration date'),
+	lastUsedAt: z.string().datetime().nullable().optional().describe('the last used date'),
+	createdAt: z.string().datetime().describe('the creation date'),
+	project: z
+		.object({
+			id: z.string().describe('the project id'),
+			name: z.string().describe('the project name'),
+		})
+		.nullable()
+		.optional()
+		.describe('the associated project'),
+});
+
+export const APIKeyGetResponseSchema = APIResponseSchema(APIKeyDetailSchema);
+
+type APIKeyGetResponse = z.infer<typeof APIKeyGetResponseSchema>;
+
+export type APIKeyDetail = z.infer<typeof APIKeyDetailSchema>;
+
+/**
+ * Get a specific API key by id
+ *
+ * @param client
+ * @param id the API key id
+ * @returns
+ */
+export async function apikeyGet(client: APIClient, id: string): Promise<APIKeyDetail> {
+	const resp = await client.request<APIKeyGetResponse>(
+		'GET',
+		`/cli/apikey/${id}`,
+		APIKeyGetResponseSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new APIKeyResponseError({ message: resp.message });
+}

package/src/api/apikey/index.ts

@@ -0,0 +1,5 @@
+export * from './create.ts';
+export * from './delete.ts';
+export * from './get.ts';
+export * from './list.ts';
+export * from './util.ts';

package/src/api/apikey/list.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import { APIClient, APIResponseSchema } from '../api.ts';
+import { APIKeyResponseError } from './util.ts';
+
+export const APIKeySchema = z.object({
+	id: z.string().describe('the API key id'),
+	name: z.string().describe('the API key name'),
+	orgId: z.string().describe('the organization id'),
+	type: z.string().describe('the API key type'),
+	expiresAt: z.string().datetime().nullable().describe('the expiration date'),
+	lastUsedAt: z.string().datetime().nullable().optional().describe('the last used date'),
+	createdAt: z.string().datetime().describe('the creation date'),
+	project: z
+		.object({
+			id: z.string().describe('the project id'),
+			name: z.string().describe('the project name'),
+		})
+		.nullable()
+		.optional()
+		.describe('the associated project'),
+});
+
+export const APIKeyListResponseArray = z.array(APIKeySchema);
+
+export const APIKeyListResponseSchema = APIResponseSchema(APIKeyListResponseArray);
+
+export type APIKeyListResponse = z.infer<typeof APIKeyListResponseSchema>;
+export type APIKeyList = z.infer<typeof APIKeyListResponseArray>;
+export type APIKey = z.infer<typeof APIKeySchema>;
+
+export interface APIKeyListRequest {
+	orgId?: string;
+	projectId?: string;
+}
+
+/**
+ * List all API keys
+ *
+ * @param client
+ * @param request optional filters for orgId and projectId
+ * @returns
+ */
+export async function apikeyList(
+	client: APIClient,
+	request?: APIKeyListRequest
+): Promise<APIKeyList> {
+	const params = new URLSearchParams();
+	if (request?.orgId) {
+		params.set('orgId', request.orgId);
+	}
+	if (request?.projectId) {
+		params.set('projectId', request.projectId);
+	}
+	const queryString = params.toString();
+	const endpoint = `/cli/apikey${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.get<APIKeyListResponse>(endpoint, APIKeyListResponseSchema);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new APIKeyResponseError({ message: resp.message });
+}

package/src/api/apikey/util.ts

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

package/src/api/config.ts

@@ -0,0 +1,60 @@
+import { getEnv } from './env.ts';
+
+export interface ServiceUrls {
+	keyvalue: string;
+	stream: string;
+	vector: string;
+	catalyst: string;
+	otel: string;
+	sandbox: string;
+	email: string;
+}
+
+/**
+ * Resolve the region from the provided value or AGENTUITY_REGION environment variable.
+ * Throws an error if no region can be resolved.
+ */
+export function resolveRegion(region?: string): string {
+	const resolved = region ?? getEnv('AGENTUITY_REGION');
+	if (!resolved) {
+		throw new Error(
+			'Region is required but not provided. Set the AGENTUITY_REGION environment variable or pass region as a parameter.'
+		);
+	}
+	return resolved;
+}
+
+/**
+ * Get service URLs from environment variables with fallback defaults.
+ * Throws an error if region cannot be resolved (neither passed as parameter nor set via AGENTUITY_REGION).
+ */
+export function getServiceUrls(region?: string): ServiceUrls {
+	const resolvedRegion = resolveRegion(region);
+	const transportUrl =
+		getEnv('AGENTUITY_TRANSPORT_URL') || buildRegionalURL(resolvedRegion, 'catalyst');
+
+	return {
+		keyvalue: getEnv('AGENTUITY_KEYVALUE_URL') || transportUrl,
+		stream: getEnv('AGENTUITY_STREAM_URL') || buildRegionalURL(resolvedRegion, 'streams'),
+		vector: getEnv('AGENTUITY_VECTOR_URL') || transportUrl,
+		catalyst: getEnv('AGENTUITY_CATALYST_URL') || transportUrl,
+		otel: getEnv('AGENTUITY_OTLP_URL') || buildRegionalURL(resolvedRegion, 'otel'),
+		sandbox: getEnv('AGENTUITY_SANDBOX_URL') || transportUrl,
+		email: getEnv('AGENTUITY_EMAIL_URL') || transportUrl,
+	};
+}
+
+function getDomainSuffix(region?: string) {
+	if (region === 'local' || region === 'l') {
+		return 'agentuity.io';
+	}
+	return 'agentuity.cloud';
+}
+
+function buildRegionalURL(region?: string, hostname?: string) {
+	const suffix = getDomainSuffix(region);
+	if (suffix === 'agentuity.io') {
+		return `https://${hostname}.${suffix}`;
+	}
+	return `https://${hostname}-${region}.${suffix}`;
+}

package/src/api/db/index.ts

@@ -0,0 +1,27 @@
+export {
+	DbLogsAPIResponseSchema,
+	DbLogsRequestSchema,
+	DbLogsResponseSchema,
+	type DbQueryLog,
+	DbQueryLogSchema,
+	type DbQueryLogs,
+	dbLogs,
+} from './logs.ts';
+export {
+	dbQuery,
+	type QueryColumn,
+	QueryColumnSchema,
+	QueryResponseSchema,
+	type QueryResult,
+	QueryResultSchema,
+} from './query.ts';
+export {
+	dbTables,
+	generateCreateTableSQL,
+	type TableColumn,
+	TableColumnSchema,
+	type TableSchema,
+	TableSchemaSchema,
+	TablesResponseSchema,
+} from './tables.ts';
+export { DbInvalidArgumentError, DbResponseError } from './util.ts';

package/src/api/db/logs.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import { DbInvalidArgumentError, DbResponseError } from './util.ts';
+
+export const DbLogsRequestSchema = z.object({
+	database: z.string().describe('the database name'),
+	orgId: z.string().describe('the organization ID'),
+	region: z.string().describe('the region'),
+	startDate: z.string().optional().describe('start date filter'),
+	endDate: z.string().optional().describe('end date filter'),
+	username: z.string().optional().describe('username filter'),
+	command: z.string().optional().describe('command filter'),
+	hasError: z.boolean().optional().describe('filter by error status'),
+	sessionId: z.string().optional().describe('filter by session ID (trace ID)'),
+	limit: z.number().optional().describe('maximum number of logs to return'),
+});
+
+export const DbQueryLogSchema = z.object({
+	timestamp: z.string().describe('log timestamp'),
+	username: z.string().describe('username'),
+	database: z.string().describe('database name'),
+	duration: z.number().describe('query duration in milliseconds'),
+	txStatus: z.string().describe('transaction status'),
+	command: z.string().describe('SQL command type'),
+	rowCount: z.number().describe('number of rows affected'),
+	sql: z.string().describe('SQL query'),
+	error: z.string().optional().describe('error message if any'),
+	sessionId: z.string().optional().describe('session ID with sess_ prefix'),
+});
+
+export const DbLogsResponseSchema = z.array(DbQueryLogSchema);
+
+export const DbLogsAPIResponseSchema = APIResponseSchema(DbLogsResponseSchema);
+
+type DbLogsRequest = z.infer<typeof DbLogsRequestSchema>;
+type DbLogsAPIResponse = z.infer<typeof DbLogsAPIResponseSchema>;
+
+export type DbQueryLog = z.infer<typeof DbQueryLogSchema>;
+export type DbQueryLogs = DbQueryLog[];
+
+/**
+ * Get query logs for a database from the App API
+ *
+ * @param client APIClient configured for the App API base URL
+ * @param request
+ * @returns
+ */
+export async function dbLogs(client: APIClient, request: DbLogsRequest): Promise<DbQueryLogs> {
+	const { database, orgId, region, ...filters } = request;
+
+	if (!orgId || !region) {
+		throw new DbInvalidArgumentError({ message: 'orgId and region are required', orgId, region });
+	}
+
+	const params = new URLSearchParams();
+	Object.entries(filters).forEach(([key, value]) => {
+		if (value !== undefined) {
+			params.append(key, String(value));
+		}
+	});
+
+	const queryString = params.toString();
+	const url = `/resource/${orgId}/${region}/${database}/logs${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.get<DbLogsAPIResponse>(url, DbLogsAPIResponseSchema);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new DbResponseError({
+		database,
+		message: resp.message || 'Failed to fetch database logs',
+	});
+}

package/src/api/db/query.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import { APIClient, APIError } from '../api.ts';
+import { DbInvalidArgumentError, DbResponseError } from './util.ts';
+
+export const QueryColumnSchema = z.object({
+	name: z.string().describe('column name'),
+	type: z.string().describe('PostgreSQL data type OID'),
+});
+
+export const QueryResultSchema = z.object({
+	columns: z.array(QueryColumnSchema).describe('column metadata'),
+	rows: z.array(z.record(z.string(), z.any())).describe('query result rows'),
+	rowCount: z.number().describe('number of rows returned'),
+	truncated: z.boolean().describe('whether results were truncated (max 1000 rows)'),
+});
+
+export const QueryResponseSchema = z.object({
+	success: z.boolean(),
+	message: z.string().optional(),
+	data: QueryResultSchema.optional(),
+});
+
+export type QueryColumn = z.infer<typeof QueryColumnSchema>;
+export type QueryResult = z.infer<typeof QueryResultSchema>;
+
+interface DbQueryRequest {
+	database: string;
+	query: string;
+	orgId: string;
+	region: string;
+}
+
+export async function dbQuery(client: APIClient, request: DbQueryRequest): Promise<QueryResult> {
+	const { database, query, orgId, region } = request;
+
+	if (!orgId || !region) {
+		throw new DbInvalidArgumentError({ message: 'orgId and region are required', orgId, region });
+	}
+
+	if (!query) {
+		throw new DbInvalidArgumentError({ message: 'query is required', query });
+	}
+
+	const url = `/resource/${orgId}/${region}/${database}/query`;
+
+	try {
+		const resp = await client.post(url, { query }, QueryResponseSchema);
+
+		if (resp.success && resp.data) {
+			return resp.data;
+		}
+
+		throw new DbResponseError({
+			database,
+			message: resp.message ?? 'Failed to execute database query',
+		});
+	} catch (ex) {
+		if (ex instanceof APIError) {
+			let message = ex.message;
+			if (message?.startsWith('failed to execute query: ')) {
+				message = message.substring(25);
+			}
+			throw new DbResponseError({ database, message });
+		}
+		throw ex;
+	}
+}

package/src/api/db/tables.ts

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import { DbInvalidArgumentError, DbResponseError } from './util.ts';
+
+export const TableColumnSchema = z.object({
+	name: z.string().describe('column name'),
+	data_type: z.string().describe('PostgreSQL data type'),
+	is_nullable: z.boolean().describe('whether the column is nullable'),
+	default_value: z.string().optional().describe('default value'),
+	is_primary_key: z.boolean().describe('whether this column is part of the primary key'),
+});
+
+export const TableSchemaSchema = z.object({
+	table_name: z.string().describe('table name'),
+	columns: z.array(TableColumnSchema).describe('table columns'),
+});
+
+export const TablesResponseSchema = APIResponseSchema(
+	z.object({
+		tables: z.array(TableSchemaSchema),
+	})
+);
+
+export type TableColumn = z.infer<typeof TableColumnSchema>;
+export type TableSchema = z.infer<typeof TableSchemaSchema>;
+
+interface DbTablesRequest {
+	database: string;
+	orgId: string;
+	region: string;
+}
+
+export async function dbTables(
+	client: APIClient,
+	request: DbTablesRequest
+): Promise<TableSchema[]> {
+	const { database, orgId, region } = request;
+
+	if (!orgId || !region) {
+		throw new DbInvalidArgumentError({ message: 'orgId and region are required', orgId, region });
+	}
+
+	const url = `/resource/${orgId}/${region}/${database}/tables`;
+
+	const resp = await client.get(url, TablesResponseSchema);
+
+	if (resp.success) {
+		return resp.data.tables;
+	}
+
+	throw new DbResponseError({
+		database,
+		message: resp.message || 'Failed to fetch database tables',
+	});
+}
+
+export function generateCreateTableSQL(table: TableSchema): string {
+	const lines: string[] = [`CREATE TABLE ${table.table_name} (`];
+
+	// Collect primary key columns
+	const primaryKeyColumns: string[] = [];
+
+	const columnDefs = table.columns.map((col) => {
+		let def = `    ${col.name} ${col.data_type}`;
+
+		if (!col.is_nullable) {
+			def += ' NOT NULL';
+		}
+
+		if (col.default_value) {
+			def += ` DEFAULT ${col.default_value}`;
+		}
+
+		if (col.is_primary_key) {
+			primaryKeyColumns.push(col.name);
+		}
+
+		return def;
+	});
+
+	lines.push(columnDefs.join(',\n'));
+
+	// Add table-level PRIMARY KEY constraint if any columns are marked as primary keys
+	if (primaryKeyColumns.length > 0) {
+		lines.push(',');
+		lines.push(`    PRIMARY KEY (${primaryKeyColumns.join(', ')})`);
+	}
+
+	lines.push(');');
+
+	return lines.join('\n');
+}

package/src/api/db/util.ts

@@ -0,0 +1,9 @@
+import { StructuredError } from '../../error.ts';
+
+export const DbResponseError = StructuredError('DbResponseError')<{ database: string }>();
+
+export const DbInvalidArgumentError = StructuredError('DbInvalidArgumentError')<{
+	orgId?: string;
+	region?: string;
+	query?: string;
+}>();

package/src/api/env.ts

@@ -0,0 +1,9 @@
+/**
+ * Safe environment variable accessor that works in both browser and server environments.
+ */
+export function getEnv(key: string): string | undefined {
+	if (typeof process !== 'undefined' && process.env) {
+		return process.env[key];
+	}
+	return undefined;
+}

package/src/api/eval/get.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+
+export const EvaluationDetailSchema = z.object({
+	id: z.string().describe('Evaluation ID'),
+	name: z.string().describe('Evaluation name'),
+	description: z.string().nullable().describe('Evaluation description'),
+	identifier: z.string().nullable().describe('Stable evaluation identifier'),
+	agentIdentifier: z.string().describe('Agent identifier'),
+	projectId: z.string().describe('Project ID'),
+	orgId: z.string().describe('Organization ID'),
+	devmode: z.boolean().describe('Whether this is a devmode evaluation'),
+	createdAt: z.string().describe('Creation timestamp'),
+	updatedAt: z.string().describe('Last updated timestamp'),
+});
+
+export const EvalGetResponseSchema = APIResponseSchema(EvaluationDetailSchema);
+
+export type EvaluationDetail = z.infer<typeof EvaluationDetailSchema>;
+
+export async function evalGet(client: APIClient, id: string): Promise<EvaluationDetail> {
+	const resp = await client.request<z.infer<typeof EvalGetResponseSchema>>(
+		'GET',
+		`/cli/eval/${encodeURIComponent(id)}`,
+		EvalGetResponseSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new Error(resp.message || 'Failed to get evaluation');
+}

package/src/api/eval/index.ts

@@ -0,0 +1,28 @@
+export {
+	EvalGetResponseSchema,
+	type EvaluationDetail,
+	EvaluationDetailSchema,
+	evalGet,
+} from './get.ts';
+export {
+	EvalListResponseData,
+	EvalListResponseSchema,
+	type Evaluation,
+	type EvaluationListRequest,
+	EvaluationSchema,
+	evalList,
+} from './list.ts';
+export {
+	type EvalRunDetail,
+	EvalRunDetailSchema,
+	EvalRunGetResponseSchema,
+	evalRunGet,
+} from './run-get.ts';
+export {
+	type EvalRunListItem,
+	type EvalRunListRequest,
+	EvalRunListResponseData,
+	EvalRunListResponseSchema,
+	EvalRunSchema,
+	evalRunList,
+} from './run-list.ts';

package/src/api/eval/list.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+
+export const EvaluationSchema = z.object({
+	id: z.string().describe('Evaluation ID'),
+	name: z.string().describe('Evaluation name'),
+	description: z.string().nullable().describe('Evaluation description'),
+	identifier: z.string().nullable().describe('Stable evaluation identifier'),
+	agentIdentifier: z.string().describe('Agent identifier'),
+	projectId: z.string().describe('Project ID'),
+	devmode: z.boolean().describe('Whether this is a devmode evaluation'),
+	createdAt: z.string().describe('Creation timestamp'),
+	updatedAt: z.string().describe('Last updated timestamp'),
+});
+
+export const EvalListResponseData = z.array(EvaluationSchema);
+export const EvalListResponseSchema = APIResponseSchema(EvalListResponseData);
+
+export type Evaluation = z.infer<typeof EvaluationSchema>;
+export type EvaluationListRequest = {
+	projectId?: string;
+	agentId?: string;
+	orgId?: string;
+};
+
+export async function evalList(
+	client: APIClient,
+	request: EvaluationListRequest = {}
+): Promise<Evaluation[]> {
+	const params = new URLSearchParams();
+	if (request.orgId) params.set('orgId', request.orgId);
+	if (request.projectId) params.set('projectId', request.projectId);
+	if (request.agentId) params.set('agentId', request.agentId);
+
+	const queryString = params.toString();
+	const url = `/cli/eval${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.request<z.infer<typeof EvalListResponseSchema>>(
+		'GET',
+		url,
+		EvalListResponseSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new Error(resp.message || 'Failed to list evaluations');
+}