@agentuity/core 1.0.32 → 1.0.34

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/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/services/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/services/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/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/apikey/util.ts

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

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,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/services/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/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/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/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/services/email/index.ts

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