@agentuity/core 1.0.33 → 1.0.35

package/src/services/apikey/create.ts

@@ -0,0 +1,48 @@
+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 const APIKeyCreateRequestSchema = z.object({
+	name: z.string().describe('Name of the API key'),
+	expiresAt: z.string().describe('Expiration timestamp for the API key'),
+	projectId: z.string().nullable().optional().describe('Optional project scope for the key'),
+	orgId: z.string().nullable().optional().describe('Optional organization scope for the key'),
+});
+
+export type APIKeyCreateRequest = z.infer<typeof APIKeyCreateRequestSchema>;
+
+/**
+ * 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,
+		APIKeyCreateRequestSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new APIKeyResponseError({ message: resp.message });
+}

package/src/services/apikey/list.ts

@@ -0,0 +1,66 @@
+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 const APIKeyListRequestSchema = z.object({
+	orgId: z.string().optional().describe('Optional organization filter for listed keys'),
+	projectId: z.string().optional().describe('Optional project filter for listed keys'),
+});
+
+export type APIKeyListRequest = z.infer<typeof APIKeyListRequestSchema>;
+
+/**
+ * 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/services/config.ts

@@ -0,0 +1,65 @@
+import { getEnv } from './env.ts';
+import { z } from 'zod';
+
+export const ServiceUrlsSchema = z
+	.object({
+		keyvalue: z.string().describe('URL for the key-value storage service.'),
+		stream: z.string().describe('URL for the stream service.'),
+		vector: z.string().describe('URL for the vector storage service.'),
+		catalyst: z.string().describe('URL for the Catalyst API gateway.'),
+		otel: z.string().describe('URL for the OpenTelemetry collector.'),
+		sandbox: z.string().describe('URL for the sandbox service.'),
+		email: z.string().describe('URL for the email service.'),
+	})
+	.describe('Service endpoint URLs for the Agentuity platform.');
+
+export type ServiceUrls = z.infer<typeof ServiceUrlsSchema>;
+
+/**
+ * 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/services/db/index.ts

@@ -0,0 +1,42 @@
+export {
+	DbLogsAPIResponseSchema,
+	DbLogsRequestSchema,
+	DbLogsResponseSchema,
+	type DbQueryLog,
+	DbQueryLogSchema,
+	type DbQueryLogs,
+	dbLogs,
+} from './logs.ts';
+export {
+	DbLogStatsAPIResponseSchema,
+	DbLogStatsCommandBreakdownSchema,
+	type DbLogStatsCommandBreakdown,
+	DbLogStatsQueryPatternSchema,
+	type DbLogStatsQueryPattern,
+	DbLogStatsRequestSchema,
+	DbLogStatsResponseSchema,
+	type DbLogStatsResponse,
+	DbLogStatsSummarySchema,
+	type DbLogStatsSummary,
+	DbLogStatsTimeSeriesPointSchema,
+	type DbLogStatsTimeSeriesPoint,
+	dbLogStats,
+} from './stats.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/services/db/query.ts

@@ -0,0 +1,69 @@
+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>;
+
+const DbQueryRequestSchema = z.object({
+	database: z.string().describe('Database name to execute the query against'),
+	query: z.string().describe('SQL query text to execute'),
+	orgId: z.string().describe('Organization identifier for routing'),
+	region: z.string().describe('Cloud region where the database is provisioned'),
+});
+
+type DbQueryRequest = z.infer<typeof DbQueryRequestSchema>;
+
+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/services/db/stats.ts

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import { DbInvalidArgumentError, DbResponseError } from './util.ts';
+
+// Request schema
+export const DbLogStatsRequestSchema = 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().describe('start date filter (ISO 8601)'),
+	endDate: z.string().describe('end date filter (ISO 8601)'),
+});
+
+// Summary stats
+export const DbLogStatsSummarySchema = z.object({
+	totalQueries: z.number().describe('total number of queries'),
+	errorCount: z.number().describe('number of queries with errors'),
+	avgDuration: z.number().describe('average query duration in ms'),
+	p50Duration: z.number().describe('50th percentile duration in ms'),
+	p95Duration: z.number().describe('95th percentile duration in ms'),
+	p99Duration: z.number().describe('99th percentile duration in ms'),
+	maxDuration: z.number().describe('maximum query duration in ms'),
+	totalRows: z.number().describe('total rows affected/returned'),
+});
+
+// Time series point
+export const DbLogStatsTimeSeriesPointSchema = z.object({
+	timestamp: z.string().describe('bucket timestamp'),
+	queryCount: z.number().describe('queries in this bucket'),
+	errorCount: z.number().describe('errors in this bucket'),
+	avgDuration: z.number().describe('average duration in this bucket'),
+	p50Duration: z.number().describe('p50 duration in this bucket'),
+	p95Duration: z.number().describe('p95 duration in this bucket'),
+	p99Duration: z.number().describe('p99 duration in this bucket'),
+});
+
+// Query pattern
+export const DbLogStatsQueryPatternSchema = z.object({
+	pattern: z.string().describe('SQL query text'),
+	command: z.string().describe('SQL command type'),
+	calls: z.number().describe('number of executions'),
+	avgDuration: z.number().describe('average duration in ms'),
+	p95Duration: z.number().describe('95th percentile duration in ms'),
+	maxDuration: z.number().describe('maximum duration in ms'),
+	totalDuration: z.number().describe('total cumulative duration in ms'),
+	avgRows: z.number().describe('average rows affected'),
+	errors: z.number().describe('number of errors'),
+});
+
+// Command breakdown
+export const DbLogStatsCommandBreakdownSchema = z.object({
+	command: z.string().describe('SQL command type'),
+	queryCount: z.number().describe('number of queries'),
+	avgDuration: z.number().describe('average duration in ms'),
+	p95Duration: z.number().describe('95th percentile duration in ms'),
+	totalDuration: z.number().describe('total cumulative duration in ms'),
+	errorCount: z.number().describe('number of errors'),
+});
+
+// Combined response
+export const DbLogStatsResponseSchema = z.object({
+	summary: DbLogStatsSummarySchema,
+	timeSeries: z.array(DbLogStatsTimeSeriesPointSchema),
+	queryPatterns: z.array(DbLogStatsQueryPatternSchema),
+	commandBreakdown: z.array(DbLogStatsCommandBreakdownSchema),
+});
+
+export const DbLogStatsAPIResponseSchema = APIResponseSchema(DbLogStatsResponseSchema);
+
+// Type exports
+export type DbLogStatsSummary = z.infer<typeof DbLogStatsSummarySchema>;
+export type DbLogStatsTimeSeriesPoint = z.infer<typeof DbLogStatsTimeSeriesPointSchema>;
+export type DbLogStatsQueryPattern = z.infer<typeof DbLogStatsQueryPatternSchema>;
+export type DbLogStatsCommandBreakdown = z.infer<typeof DbLogStatsCommandBreakdownSchema>;
+export type DbLogStatsResponse = z.infer<typeof DbLogStatsResponseSchema>;
+
+type DbLogStatsRequest = z.infer<typeof DbLogStatsRequestSchema>;
+type DbLogStatsAPIResponse = z.infer<typeof DbLogStatsAPIResponseSchema>;
+
+/**
+ * Get query performance stats for a database
+ */
+export async function dbLogStats(
+	client: APIClient,
+	request: DbLogStatsRequest
+): Promise<DbLogStatsResponse> {
+	if (!request) {
+		throw new DbInvalidArgumentError({
+			message: 'request is required',
+			orgId: undefined,
+			region: undefined,
+		});
+	}
+
+	const { database, orgId, region, startDate, endDate } = request;
+
+	if (!orgId || !region || !database || !startDate || !endDate) {
+		throw new DbInvalidArgumentError({
+			message: 'orgId, region, database, startDate, and endDate are required',
+			orgId,
+			region,
+		});
+	}
+
+	const params = new URLSearchParams();
+	params.append('startDate', startDate);
+	params.append('endDate', endDate);
+
+	const url = `/resource/${encodeURIComponent(orgId)}/${encodeURIComponent(region)}/${encodeURIComponent(database)}/logs/stats?${params.toString()}`;
+
+	const resp = await client.get<DbLogStatsAPIResponse>(url, DbLogStatsAPIResponseSchema);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new DbResponseError({
+		database,
+		message: resp.message || 'Failed to fetch database performance stats',
+	});
+}

package/src/services/db/tables.ts

@@ -0,0 +1,94 @@
+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).describe('Array of table schemas in the database.'),
+	})
+);
+
+export type TableColumn = z.infer<typeof TableColumnSchema>;
+export type TableSchema = z.infer<typeof TableSchemaSchema>;
+
+const DbTablesRequestSchema = z.object({
+	database: z.string().describe('Database name to inspect'),
+	orgId: z.string().describe('Organization identifier for routing'),
+	region: z.string().describe('Cloud region where the database is provisioned'),
+});
+
+type DbTablesRequest = z.infer<typeof DbTablesRequestSchema>;
+
+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/services/email/index.ts

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