@agentuity/core 1.0.41 → 1.0.43

package/src/services/apikey/api-reference.ts

@@ -0,0 +1,99 @@
+import type { Service } from '../api-reference.ts';
+import { APIKeyCreateRequestSchema, APIKeyCreateResponseSchema } from './create.ts';
+import { APIKeySchema } from './list.ts';
+
+const service: Service = {
+	name: 'API Keys',
+	slug: 'api-keys',
+	description: 'Create and manage API keys for authentication',
+	endpoints: [
+		{
+			id: 'create-api-key',
+			title: 'Create API Key',
+			method: 'POST',
+			path: '/cli/apikey',
+			description: 'Create a new API key. The key value is only returned at creation time.',
+			pathParams: [],
+			queryParams: [],
+			requestBody: {
+				description: 'API key creation payload.',
+				fields: { schema: APIKeyCreateRequestSchema },
+			},
+			responseDescription:
+				'Returns the new key ID and value. The value is only returned at creation time.',
+			responseFields: { schema: APIKeyCreateResponseSchema },
+			statuses: [
+				{ code: 201, description: 'API key created' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+			],
+			examplePath: '/cli/apikey',
+			exampleBody: { name: 'My API Key', expiresAt: '2026-12-31T23:59:59Z' },
+		},
+		{
+			id: 'list-api-keys',
+			title: 'List API Keys',
+			method: 'GET',
+			path: '/cli/apikey',
+			description: 'List API keys with optional filtering by organization or project.',
+			pathParams: [],
+			queryParams: [
+				{
+					name: 'orgId',
+					type: 'string',
+					description: 'Filter by organization ID',
+					required: false,
+				},
+				{
+					name: 'projectId',
+					type: 'string',
+					description: 'Filter by project ID',
+					required: false,
+				},
+			],
+			requestBody: null,
+			responseDescription: 'Array of API key objects.',
+			responseFields: { schema: APIKeySchema },
+			statuses: [
+				{ code: 200, description: 'API keys returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+			],
+			examplePath: '/cli/apikey',
+		},
+		{
+			id: 'get-api-key',
+			title: 'Get API Key',
+			method: 'GET',
+			path: '/cli/apikey/{id}',
+			description: 'Get a specific API key by ID.',
+			pathParams: [{ name: 'id', type: 'string', description: 'API key ID', required: true }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'API key object.',
+			statuses: [
+				{ code: 200, description: 'API key returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'API key not found' },
+			],
+			examplePath: '/cli/apikey/ak_abc123',
+		},
+		{
+			id: 'delete-api-key',
+			title: 'Delete API Key',
+			method: 'DELETE',
+			path: '/cli/apikey/{id}',
+			description: 'Delete an API key by ID.',
+			pathParams: [{ name: 'id', type: 'string', description: 'API key ID', required: true }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Empty response on success.',
+			statuses: [
+				{ code: 204, description: 'API key deleted' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'API key not found' },
+			],
+			examplePath: '/cli/apikey/ak_abc123',
+		},
+	],
+};
+
+export default service;

package/src/services/db/api-reference.ts

@@ -0,0 +1,152 @@
+import { DbExecuteQueryRequestSchema } from './types.ts';
+import type { Service } from '../api-reference.ts';
+
+const service: Service = {
+	name: 'Databases',
+	slug: 'database',
+	description: 'Execute queries, inspect tables, and monitor database performance',
+	endpoints: [
+		{
+			id: 'get-query-logs',
+			title: 'Get Query Logs',
+			method: 'GET',
+			path: '/resource/{orgId}/{region}/{database}/logs',
+			description: 'Get query logs for a database with optional filtering.',
+			pathParams: [
+				{ name: 'orgId', type: 'string', description: 'Organization ID', required: true },
+				{ name: 'region', type: 'string', description: 'Region identifier', required: true },
+				{ name: 'database', type: 'string', description: 'Database name', required: true },
+			],
+			queryParams: [
+				{
+					name: 'startDate',
+					type: 'string',
+					description: 'Start date filter',
+					required: false,
+				},
+				{ name: 'endDate', type: 'string', description: 'End date filter', required: false },
+				{
+					name: 'username',
+					type: 'string',
+					description: 'Filter by username',
+					required: false,
+				},
+				{
+					name: 'command',
+					type: 'string',
+					description: 'Filter by SQL command type',
+					required: false,
+				},
+				{
+					name: 'hasError',
+					type: 'boolean',
+					description: 'Filter for queries with errors',
+					required: false,
+				},
+				{
+					name: 'sessionId',
+					type: 'string',
+					description: 'Filter by session ID',
+					required: false,
+				},
+				{
+					name: 'limit',
+					type: 'number',
+					description: 'Maximum logs to return',
+					required: false,
+				},
+			],
+			requestBody: null,
+			responseDescription: 'Array of query log entries.',
+			statuses: [
+				{ code: 200, description: 'Query logs returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Database not found' },
+			],
+			examplePath: '/resource/org_abc123/usw/mydb/logs',
+		},
+		{
+			id: 'execute-query',
+			title: 'Execute Query',
+			method: 'POST',
+			path: '/resource/{orgId}/{region}/{database}/query',
+			description: 'Execute a SQL query against a database.',
+			pathParams: [
+				{ name: 'orgId', type: 'string', description: 'Organization ID', required: true },
+				{ name: 'region', type: 'string', description: 'Region identifier', required: true },
+				{ name: 'database', type: 'string', description: 'Database name', required: true },
+			],
+			queryParams: [],
+			requestBody: {
+				description: 'SQL query payload.',
+				fields: { schema: DbExecuteQueryRequestSchema },
+			},
+			responseDescription:
+				'Returns columns, rows, row count, and whether results were truncated (max 1000 rows).',
+			statuses: [
+				{ code: 200, description: 'Query executed successfully' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Database not found' },
+			],
+			examplePath: '/resource/org_abc123/usw/mydb/query',
+			exampleBody: { query: 'SELECT * FROM users LIMIT 10' },
+		},
+		{
+			id: 'get-query-stats',
+			title: 'Get Query Stats',
+			method: 'GET',
+			path: '/resource/{orgId}/{region}/{database}/logs/stats',
+			description: 'Get aggregate query statistics for a database over a date range.',
+			pathParams: [
+				{ name: 'orgId', type: 'string', description: 'Organization ID', required: true },
+				{ name: 'region', type: 'string', description: 'Region identifier', required: true },
+				{ name: 'database', type: 'string', description: 'Database name', required: true },
+			],
+			queryParams: [
+				{
+					name: 'startDate',
+					type: 'string',
+					description: 'Start date for stats range',
+					required: true,
+				},
+				{
+					name: 'endDate',
+					type: 'string',
+					description: 'End date for stats range',
+					required: true,
+				},
+			],
+			requestBody: null,
+			responseDescription: 'Aggregate query statistics.',
+			statuses: [
+				{ code: 200, description: 'Query stats returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Database not found' },
+			],
+			examplePath: '/resource/org_abc123/usw/mydb/logs/stats',
+		},
+		{
+			id: 'list-tables',
+			title: 'List Tables',
+			method: 'GET',
+			path: '/resource/{orgId}/{region}/{database}/tables',
+			description: 'List all tables in a database.',
+			pathParams: [
+				{ name: 'orgId', type: 'string', description: 'Organization ID', required: true },
+				{ name: 'region', type: 'string', description: 'Region identifier', required: true },
+				{ name: 'database', type: 'string', description: 'Database name', required: true },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Array of table names and metadata.',
+			statuses: [
+				{ code: 200, description: 'Tables returned' },
+				{ code: 401, description: 'Unauthorized — invalid or missing Bearer token' },
+				{ code: 404, description: 'Database not found' },
+			],
+			examplePath: '/resource/org_abc123/usw/mydb/tables',
+		},
+	],
+};
+
+export default service;

package/src/services/db/types.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// API-level Zod schemas for the Database HTTP API.
+// ---------------------------------------------------------------------------
+
+/** Request body for POST /resource/{orgId}/{region}/{database}/query */
+export const DbExecuteQueryRequestSchema = z.object({
+	query: z.string().describe('SQL query to execute'),
+});
+
+export type DbExecuteQueryRequest = z.infer<typeof DbExecuteQueryRequestSchema>;

package/src/services/email/api-reference.ts

@@ -0,0 +1,349 @@
+import {
+	EmailActivityResultSchema,
+	EmailConnectionConfigSchema,
+	EmailSendParamsSchema,
+} from './service.ts';
+import { CreateAddressRequestSchema, CreateEmailDestinationRequestSchema } from './types.ts';
+import type { Service } from '../api-reference.ts';
+
+const service: Service = {
+	name: 'Emails',
+	slug: 'email',
+	description: 'Send and receive emails with managed addresses and webhook destinations',
+	endpoints: [
+		{
+			id: 'create-address',
+			title: 'Create Address',
+			sectionTitle: 'Address Management',
+			method: 'POST',
+			path: '/email/addresses',
+			description: 'Create a managed address at the `@agentuity.email` domain.',
+			pathParams: [],
+			queryParams: [],
+			requestBody: {
+				description: 'Address creation payload.',
+				fields: { schema: CreateAddressRequestSchema },
+			},
+			responseDescription: 'Created `EmailAddress` object.',
+			statuses: [
+				{ code: 200, description: 'Address created' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/email/addresses',
+			exampleBody: { local_part: 'support' },
+		},
+		{
+			id: 'list-addresses',
+			title: 'List Addresses',
+			sectionTitle: 'Address Management',
+			method: 'GET',
+			path: '/email/addresses',
+			description: 'List managed email addresses.',
+			pathParams: [],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Array of `EmailAddress` objects.',
+			statuses: [
+				{ code: 200, description: 'Addresses returned' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/email/addresses',
+		},
+		{
+			id: 'get-address',
+			title: 'Get Address',
+			sectionTitle: 'Address Management',
+			method: 'GET',
+			path: '/email/addresses/{id}',
+			description: 'Get a managed address by ID (`eaddr_...`).',
+			pathParams: [{ name: 'id', type: 'string', description: 'Address ID (`eaddr_...`)' }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: '`EmailAddress` object.',
+			statuses: [
+				{ code: 200, description: 'Address returned' },
+				{ code: 401, description: 'Unauthorized' },
+				{ code: 404, description: 'Address not found' },
+			],
+			examplePath: '/email/addresses/eaddr_abc123',
+		},
+		{
+			id: 'get-connection-config',
+			title: 'Get Connection Config',
+			sectionTitle: 'Address Management',
+			method: 'GET',
+			path: '/email/addresses/{id}/connection',
+			description: 'Get IMAP/POP3 connection settings and credentials for an address.',
+			pathParams: [{ name: 'id', type: 'string', description: 'Address ID' }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Connection configuration including IMAP and POP3 details.',
+			responseFields: { schema: EmailConnectionConfigSchema },
+			statuses: [
+				{ code: 200, description: 'Connection config returned' },
+				{ code: 401, description: 'Unauthorized' },
+				{ code: 404, description: 'Address not found' },
+			],
+			examplePath: '/email/addresses/eaddr_abc123/connection',
+		},
+		{
+			id: 'delete-address',
+			title: 'Delete Address',
+			sectionTitle: 'Address Management',
+			method: 'DELETE',
+			path: '/email/addresses/{id}',
+			description: 'Delete a managed email address.',
+			pathParams: [{ name: 'id', type: 'string', description: 'Address ID' }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Empty response on success.',
+			statuses: [
+				{ code: 200, description: 'Address deleted' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/email/addresses/eaddr_abc123',
+		},
+		{
+			id: 'create-email-destination',
+			title: 'Create Destination',
+			sectionTitle: 'Email Destinations',
+			method: 'POST',
+			path: '/email/addresses/{addressId}/destinations',
+			description: 'Create an inbound webhook destination for an address.',
+			pathParams: [{ name: 'addressId', type: 'string', description: 'Address ID' }],
+			queryParams: [],
+			requestBody: {
+				description: 'Destination creation payload.',
+				fields: { schema: CreateEmailDestinationRequestSchema },
+			},
+			responseDescription: 'Created `EmailDestination` object.',
+			statuses: [
+				{ code: 200, description: 'Destination created' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/email/addresses/eaddr_abc123/destinations',
+			exampleBody: {
+				type: 'url',
+				config: { url: 'https://example.com/email-hook', method: 'POST' },
+			},
+		},
+		{
+			id: 'list-email-destinations',
+			title: 'List Destinations',
+			sectionTitle: 'Email Destinations',
+			method: 'GET',
+			path: '/email/addresses/{addressId}/destinations',
+			description: 'List inbound destinations for an address.',
+			pathParams: [{ name: 'addressId', type: 'string', description: 'Address ID' }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Array of `EmailDestination` objects.',
+			statuses: [
+				{ code: 200, description: 'Destinations returned' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/email/addresses/eaddr_abc123/destinations',
+		},
+		{
+			id: 'delete-email-destination',
+			title: 'Delete Destination',
+			sectionTitle: 'Email Destinations',
+			method: 'DELETE',
+			path: '/email/addresses/{addressId}/destinations/{destinationId}',
+			description: 'Delete an inbound destination.',
+			pathParams: [
+				{ name: 'addressId', type: 'string', description: 'Address ID' },
+				{ name: 'destinationId', type: 'string', description: 'Destination ID' },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Empty response on success.',
+			statuses: [
+				{ code: 200, description: 'Destination deleted' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/email/addresses/eaddr_abc123/destinations/edst_abc123',
+		},
+		{
+			id: 'send-email',
+			title: 'Send Email',
+			sectionTitle: 'Sending Email',
+			method: 'POST',
+			path: '/email/outbound/send',
+			description:
+				'Send an email from an owned address. Delivery is asynchronous and total payload (including attachments) is capped at 25MB.',
+			pathParams: [],
+			queryParams: [],
+			requestBody: {
+				description: 'Outbound email payload.',
+				fields: { schema: EmailSendParamsSchema },
+			},
+			responseDescription: 'Created `EmailOutbound` object with initial `pending` status.',
+			statuses: [
+				{ code: 200, description: 'Outbound email accepted' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/email/outbound/send',
+			exampleBody: {
+				from: 'support@agentuity.email',
+				to: ['user@example.com'],
+				subject: 'Welcome!',
+				text: 'Thanks for joining Agentuity.',
+			},
+		},
+		{
+			id: 'list-inbound',
+			title: 'List Inbound',
+			sectionTitle: 'Inbound Email',
+			method: 'GET',
+			path: '/email/inbound',
+			description: 'List inbound emails, optionally filtered by address.',
+			pathParams: [],
+			queryParams: [
+				{
+					name: 'address_id',
+					type: 'string',
+					description: 'Filter by address ID',
+					required: false,
+				},
+			],
+			requestBody: null,
+			responseDescription: 'Array of `EmailInbound` objects.',
+			statuses: [
+				{ code: 200, description: 'Inbound emails returned' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/email/inbound?address_id=eaddr_abc123',
+		},
+		{
+			id: 'get-inbound',
+			title: 'Get Inbound',
+			sectionTitle: 'Inbound Email',
+			method: 'GET',
+			path: '/email/inbound/{id}',
+			description: 'Get a specific inbound email by ID (`einb_...`).',
+			pathParams: [{ name: 'id', type: 'string', description: 'Inbound email ID (`einb_...`)' }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: '`EmailInbound` object.',
+			statuses: [
+				{ code: 200, description: 'Inbound email returned' },
+				{ code: 401, description: 'Unauthorized' },
+				{ code: 404, description: 'Inbound email not found' },
+			],
+			examplePath: '/email/inbound/einb_abc123',
+		},
+		{
+			id: 'delete-inbound',
+			title: 'Delete Inbound',
+			sectionTitle: 'Inbound Email',
+			method: 'DELETE',
+			path: '/email/inbound/{id}',
+			description: 'Delete an inbound email record.',
+			pathParams: [{ name: 'id', type: 'string', description: 'Inbound email ID' }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Empty response on success.',
+			statuses: [
+				{ code: 200, description: 'Inbound email deleted' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/email/inbound/einb_abc123',
+		},
+		{
+			id: 'list-outbound',
+			title: 'List Outbound',
+			sectionTitle: 'Outbound Email',
+			method: 'GET',
+			path: '/email/outbound',
+			description: 'List outbound emails, optionally filtered by address.',
+			pathParams: [],
+			queryParams: [
+				{
+					name: 'address_id',
+					type: 'string',
+					description: 'Filter by address ID',
+					required: false,
+				},
+			],
+			requestBody: null,
+			responseDescription: 'Array of `EmailOutbound` objects.',
+			statuses: [
+				{ code: 200, description: 'Outbound emails returned' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/email/outbound?address_id=eaddr_abc123',
+		},
+		{
+			id: 'get-outbound',
+			title: 'Get Outbound',
+			sectionTitle: 'Outbound Email',
+			method: 'GET',
+			path: '/email/outbound/{id}',
+			description: 'Get an outbound email by ID (`eout_...`).',
+			pathParams: [
+				{ name: 'id', type: 'string', description: 'Outbound email ID (`eout_...`)' },
+			],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: '`EmailOutbound` object including delivery status and error details.',
+			statuses: [
+				{ code: 200, description: 'Outbound email returned' },
+				{ code: 401, description: 'Unauthorized' },
+				{ code: 404, description: 'Outbound email not found' },
+			],
+			examplePath: '/email/outbound/eout_abc123',
+		},
+		{
+			id: 'delete-outbound',
+			title: 'Delete Outbound',
+			sectionTitle: 'Outbound Email',
+			method: 'DELETE',
+			path: '/email/outbound/{id}',
+			description: 'Delete an outbound email record.',
+			pathParams: [{ name: 'id', type: 'string', description: 'Outbound email ID' }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Empty response on success.',
+			statuses: [
+				{ code: 200, description: 'Outbound email deleted' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/email/outbound/eout_abc123',
+		},
+		{
+			id: 'get-email-activity',
+			title: 'Get Activity',
+			sectionTitle: 'Activity',
+			method: 'GET',
+			path: '/email/activity/{date}',
+			description: 'Get daily inbound/outbound activity over a date window.',
+			pathParams: [
+				{
+					name: 'date',
+					type: 'string',
+					description: 'Date for activity lookup (YYYY-MM-DD format)',
+					required: true,
+				},
+			],
+			queryParams: [
+				{
+					name: 'days',
+					type: 'number',
+					description: 'Range in days (7–365, default: 7)',
+					required: false,
+				},
+			],
+			requestBody: null,
+			responseDescription: 'Activity time series grouped by date.',
+			responseFields: { schema: EmailActivityResultSchema },
+			statuses: [
+				{ code: 200, description: 'Activity returned' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/email/activity/2026-02-28?days=30',
+		},
+	],
+};
+
+export default service;

package/src/services/email/service.ts

@@ -749,8 +749,6 @@ function unwrap<T>(payload: unknown, key: string): T {
 	return payload as T;
 }
 
-const EMAIL_ACTIVITY_API_VERSION = '2026-02-28';
-
 /**
  * Client for the Agentuity Email service.
  *
@@ -1449,10 +1447,7 @@ export class EmailStorageService implements EmailService {
 		}
 
 		const queryString = queryParams.toString();
-		const url = buildUrl(
-			this.#baseUrl,
-			`/email/activity/${EMAIL_ACTIVITY_API_VERSION}${queryString ? `?${queryString}` : ''}`
-		);
+		const url = buildUrl(this.#baseUrl, `/email/activity${queryString ? `?${queryString}` : ''}`);
 		const signal = AbortSignal.timeout(30_000);
 
 		const days = queryParams.get('days');

package/src/services/email/types.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+
+/** Request payload for creating an email address */
+export const CreateAddressRequestSchema = z.object({
+	local_part: z.string().describe('Local part before `@agentuity.email`'),
+});
+
+/** Request payload for creating an email destination */
+export const CreateEmailDestinationRequestSchema = z.object({
+	type: z.string().describe('Destination type (`url`)'),
+	config: z.record(z.string(), z.unknown()).describe('Destination config including URL'),
+});
+
+export type CreateAddressRequest = z.infer<typeof CreateAddressRequestSchema>;
+export type CreateEmailDestinationRequest = z.infer<typeof CreateEmailDestinationRequestSchema>;