@agentuity/core 1.0.32 → 1.0.34

package/src/services/session/list.ts

@@ -0,0 +1,143 @@
+import { SortDirectionSchema } from '../pagination.ts';
+import { z } from 'zod';
+import { APIClient, APIResponseSchema } from '../api.ts';
+import { SessionResponseError } from './util.ts';
+
+const SessionSchema = z.object({
+	id: z.string().describe('the session id'),
+	created_at: z.string().describe('the creation timestamp'),
+	updated_at: z.string().describe('the last update timestamp'),
+	deleted: z.boolean().describe('whether the session is deleted'),
+	deleted_at: z.string().nullable().describe('the deletion timestamp'),
+	deleted_by: z.string().nullable().describe('who deleted the session'),
+	start_time: z.string().describe('the session start time'),
+	end_time: z.string().nullable().describe('the session end time'),
+	duration: z.number().nullable().describe('the session duration in nanoseconds'),
+	org_id: z.string().describe('the organization id'),
+	project_id: z.string().describe('the project id'),
+	deployment_id: z.string().describe('the deployment id'),
+	agent_ids: z.array(z.string()).describe('the agent ids involved'),
+	trigger: z.string().describe('how the session was triggered'),
+	env: z.string().describe('the environment'),
+	devmode: z.boolean().describe('whether dev mode was enabled'),
+	pending: z.boolean().describe('whether the session is pending'),
+	success: z.boolean().describe('whether the session succeeded'),
+	error: z.string().nullable().describe('the error message if failed'),
+	metadata: z
+		.record(z.string(), z.unknown())
+		.nullable()
+		.optional()
+		.describe('unencrypted key-value metadata'),
+	cpu_time: z.number().nullable().describe('the CPU time in nanoseconds'),
+	llm_cost: z.number().nullable().describe('the LLM cost'),
+	llm_prompt_token_count: z.number().nullable().describe('the LLM prompt token count'),
+	llm_completion_token_count: z.number().nullable().describe('the LLM completion token count'),
+	total_cost: z.number().nullable().describe('the total cost'),
+	method: z.string().nullable().describe('the HTTP method'),
+	url: z.string().nullable().describe('the request URL'),
+	route_id: z.string().nullable().describe('the route id'),
+	thread_id: z.string().nullable().describe('the thread id'),
+	timeline: z.unknown().nullable().optional().describe('the session timeline tree'),
+	user_data: z.string().nullable().optional().describe('the user data as JSON'),
+});
+
+export { SessionSchema };
+
+export const SessionListResponse = z.array(SessionSchema);
+
+export const SessionListResponseSchema = APIResponseSchema(SessionListResponse);
+
+export type SessionListResponse = z.infer<typeof SessionListResponseSchema>;
+export type SessionList = z.infer<typeof SessionListResponse>;
+export type Session = z.infer<typeof SessionSchema>;
+
+export type SessionSortField = 'created' | 'updated' | 'duration' | 'startTime';
+
+export const SessionListOptionsSchema = z.object({
+	count: z.number().optional().describe('Deprecated alias for limit'),
+	limit: z.number().optional().describe('Maximum number of sessions to return'),
+	offset: z.number().optional().describe('Pagination offset'),
+	sort: z
+		.enum(['created', 'updated', 'duration', 'startTime'])
+		.optional()
+		.describe('Field to sort sessions by'),
+	direction: SortDirectionSchema.optional().describe('Sort direction for session listing'),
+	orgId: z.string().optional().describe('Optional organization id filter'),
+	projectId: z.string().optional().describe('Optional project id filter'),
+	deploymentId: z.string().optional().describe('Optional deployment id filter'),
+	trigger: z.string().optional().describe('Optional trigger filter'),
+	env: z.string().optional().describe('Optional environment filter'),
+	devmode: z.boolean().optional().describe('Optional devmode filter'),
+	success: z.boolean().optional().describe('Optional success status filter'),
+	threadId: z.string().optional().describe('Optional thread id filter'),
+	agentIdentifier: z.string().optional().describe('Optional agent identifier filter'),
+	startAfter: z.string().optional().describe('Filter sessions starting after this timestamp'),
+	startBefore: z.string().optional().describe('Filter sessions starting before this timestamp'),
+	metadata: z
+		.record(z.string(), z.unknown())
+		.optional()
+		.describe('Optional metadata match filter serialized as JSON'),
+});
+
+export type SessionListOptions = z.infer<typeof SessionListOptionsSchema>;
+
+/**
+ * List sessions
+ *
+ * @param client
+ * @param options filtering and pagination options
+ * @returns
+ */
+export async function sessionList(
+	client: APIClient,
+	options: SessionListOptions = {}
+): Promise<SessionList> {
+	const {
+		count,
+		limit,
+		offset,
+		sort,
+		direction,
+		orgId,
+		projectId,
+		deploymentId,
+		trigger,
+		env,
+		devmode,
+		success,
+		threadId,
+		agentIdentifier,
+		startAfter,
+		startBefore,
+		metadata,
+	} = options;
+	const resolvedLimit = limit ?? count ?? 10;
+	const params = new URLSearchParams({ limit: resolvedLimit.toString() });
+	if (orgId) params.set('orgId', orgId);
+	if (projectId) params.set('projectId', projectId);
+	if (deploymentId) params.set('deploymentId', deploymentId);
+	if (trigger) params.set('trigger', trigger);
+	if (env) params.set('env', env);
+	if (offset !== undefined) params.set('offset', offset.toString());
+	if (sort) params.set('sort', sort);
+	if (direction) params.set('direction', direction);
+	if (devmode !== undefined) params.set('devmode', devmode.toString());
+	if (success !== undefined) params.set('success', success.toString());
+	if (threadId) params.set('threadId', threadId);
+	if (agentIdentifier) params.set('agentIdentifier', agentIdentifier);
+	if (startAfter) params.set('startAfter', startAfter);
+	if (startBefore) params.set('startBefore', startBefore);
+	if (metadata) params.set('metadata', JSON.stringify(metadata));
+
+	const resp = await client.request<SessionListResponse>(
+		'GET',
+		`/session?${params.toString()}`,
+		SessionListResponseSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new SessionResponseError({ message: resp.message });
+}

package/src/services/session/logs.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { APIClient, APIResponseSchema } from '../api.ts';
+import { SessionResponseError } from './util.ts';
+
+export const _SessionLogsRequestSchema = z.object({
+	id: z.string().describe('the session id'),
+});
+
+export const LogSchema = z.object({
+	body: z.string().describe('the log body'),
+	severity: z.string().describe('the log severity'),
+	timestamp: z.string().describe('the log timestamp'),
+});
+
+export const SessionLogsResponse = z.array(LogSchema);
+
+export const SessionLogsResponseSchema = APIResponseSchema(SessionLogsResponse);
+
+type SessionLogsRequest = z.infer<typeof _SessionLogsRequestSchema>;
+type SessionLogsResponse = z.infer<typeof SessionLogsResponseSchema>;
+
+export type SessionLog = z.infer<typeof LogSchema>;
+export type SessionLogs = SessionLog[];
+
+/**
+ * Get logs for a session from the App API
+ *
+ * @param client APIClient configured for the App API base URL
+ * @param request
+ * @returns
+ */
+export async function sessionLogs(
+	client: APIClient,
+	request: SessionLogsRequest
+): Promise<SessionLogs> {
+	const resp = await client.request<SessionLogsResponse>(
+		'GET',
+		`/cli/session/${request.id}/logs`,
+		SessionLogsResponseSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new SessionResponseError({ message: resp.message });
+}

package/src/services/session/util.ts

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

package/src/services/stats.ts

@@ -0,0 +1,232 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from './api.ts';
+import { StructuredError } from '../error.ts';
+
+// --- Error ---
+
+export const ServiceStatsError = StructuredError('ServiceStatsError')<{
+	message: string;
+}>();
+
+// --- Per-Service Stat Schemas ---
+
+export const KeyValueStatSchema = z
+	.object({
+		namespaceCount: z.number().describe('Total number of key-value namespaces.'),
+		keyCount: z.number().describe('Total number of keys across all namespaces.'),
+		totalSizeBytes: z.number().describe('Total storage size in bytes across all namespaces.'),
+	})
+	.describe('Key-value service statistics.');
+
+export const VectorStatSchema = z
+	.object({
+		namespaceCount: z.number().describe('Total number of vector namespaces.'),
+		documentCount: z.number().describe('Total number of documents across all namespaces.'),
+		totalSizeBytes: z.number().describe('Total storage size in bytes across all namespaces.'),
+	})
+	.describe('Vector service statistics.');
+
+export const QueueStatSchema = z
+	.object({
+		queueCount: z.number().describe('Total number of queues.'),
+		totalMessages: z.number().describe('Total number of messages across all queues.'),
+		totalDlq: z
+			.number()
+			.describe('Total number of dead letter queue messages across all queues.'),
+	})
+	.describe('Queue service statistics.');
+
+export const StreamStatSchema = z
+	.object({
+		streamCount: z.number().describe('Total number of streams.'),
+		totalSizeBytes: z.number().describe('Total storage size in bytes across all streams.'),
+	})
+	.describe('Stream service statistics.');
+
+export const SandboxStatSchema = z
+	.object({
+		totalActive: z.number().describe('Total number of active sandboxes.'),
+		running: z.number().describe('Number of sandboxes currently running.'),
+		idle: z.number().describe('Number of sandboxes currently idle.'),
+		creating: z.number().describe('Number of sandboxes being created.'),
+		totalExecutions: z.number().describe('Total number of sandbox executions.'),
+		totalCpuTimeMs: z.number().describe('Total CPU time consumed in milliseconds.'),
+		totalMemoryByteSec: z.number().describe('Total memory usage in byte-seconds.'),
+		totalNetworkEgressBytes: z.number().describe('Total network egress in bytes.'),
+	})
+	.describe('Sandbox service statistics.');
+
+export const EmailStatSchema = z
+	.object({
+		addressCount: z.number().describe('Total number of email addresses.'),
+		inboundCount: z.number().describe('Total number of inbound emails received.'),
+		outboundCount: z.number().describe('Total number of outbound emails sent.'),
+		outboundSuccess: z.number().describe('Number of outbound emails delivered successfully.'),
+		outboundFailed: z.number().describe('Number of outbound emails that failed delivery.'),
+	})
+	.describe('Email service statistics.');
+
+export const TaskStatSchema = z
+	.object({
+		total: z.number().default(0).describe('Total number of tasks.'),
+		open: z.number().default(0).describe('Number of open tasks.'),
+		inProgress: z.number().default(0).describe('Number of tasks currently in progress.'),
+		done: z.number().default(0).describe('Number of completed tasks.'),
+		closed: z.number().default(0).describe('Number of closed tasks.'),
+		cancelled: z.number().default(0).describe('Number of cancelled tasks.'),
+	})
+	.describe('Task service statistics.');
+
+export const ScheduleStatSchema = z
+	.object({
+		scheduleCount: z.number().describe('Total number of schedules.'),
+		totalDeliveries: z.number().describe('Total number of scheduled deliveries.'),
+		successDeliveries: z.number().describe('Number of successful scheduled deliveries.'),
+		failedDeliveries: z.number().describe('Number of failed scheduled deliveries.'),
+	})
+	.describe('Schedule service statistics.');
+
+export const DatabaseStatSchema = z
+	.object({
+		databaseCount: z.number().describe('Total number of databases.'),
+		totalTableCount: z.number().describe('Total number of tables across all databases.'),
+		totalRecordCount: z.number().describe('Total number of records across all tables.'),
+		totalSizeBytes: z.number().describe('Total storage size in bytes across all databases.'),
+	})
+	.describe('Database service statistics.');
+
+// --- Aggregate Schema ---
+
+export const ServiceStatsDataSchema = z
+	.object({
+		services: z
+			.object({
+				database: DatabaseStatSchema.optional().describe('Database service statistics.'),
+				keyvalue: KeyValueStatSchema.optional().describe('Key-value service statistics.'),
+				vector: VectorStatSchema.optional().describe('Vector service statistics.'),
+				queue: QueueStatSchema.optional().describe('Queue service statistics.'),
+				stream: StreamStatSchema.optional().describe('Stream service statistics.'),
+				sandbox: SandboxStatSchema.optional().describe('Sandbox service statistics.'),
+				email: EmailStatSchema.optional().describe('Email service statistics.'),
+				task: TaskStatSchema.optional().describe('Task service statistics.'),
+				schedule: ScheduleStatSchema.optional().describe('Schedule service statistics.'),
+			})
+			.describe('Per-service statistics breakdown.'),
+	})
+	.describe('Aggregated service statistics data.');
+
+export const ServiceStatsResponseSchema = APIResponseSchema(ServiceStatsDataSchema);
+
+// --- Types ---
+
+export type KeyValueStat = z.infer<typeof KeyValueStatSchema>;
+export type VectorStat = z.infer<typeof VectorStatSchema>;
+export type QueueStat = z.infer<typeof QueueStatSchema>;
+export type StreamStat = z.infer<typeof StreamStatSchema>;
+export type SandboxStat = z.infer<typeof SandboxStatSchema>;
+export type EmailStat = z.infer<typeof EmailStatSchema>;
+export type TaskStat = z.infer<typeof TaskStatSchema>;
+export type ScheduleStat = z.infer<typeof ScheduleStatSchema>;
+export type DatabaseStat = z.infer<typeof DatabaseStatSchema>;
+export type ServiceStatsData = z.infer<typeof ServiceStatsDataSchema>;
+export type ServiceStatsResponse = z.infer<typeof ServiceStatsResponseSchema>;
+
+// --- Valid Services ---
+
+/**
+ * Valid service names that can be used to filter stats.
+ */
+export const VALID_SERVICES = [
+	'database',
+	'keyvalue',
+	'email',
+	'vector',
+	'schedule',
+	'task',
+	'stream',
+	'sandbox',
+	'queue',
+] as const;
+
+export type ServiceName = (typeof VALID_SERVICES)[number];
+
+// --- Options ---
+
+export const ServiceStatsOptionsSchema = z.object({
+	service: z
+		.enum(VALID_SERVICES)
+		.optional()
+		.describe('Optional service filter; when omitted returns all services'),
+	start: z.string().optional().describe('Optional start timestamp (ISO 8601)'),
+	end: z.string().optional().describe('Optional end timestamp (ISO 8601)'),
+	orgIdHeader: z
+		.string()
+		.optional()
+		.describe('Optional org id header for CLI token authentication'),
+});
+
+export type ServiceStatsOptions = z.infer<typeof ServiceStatsOptionsSchema>;
+
+// --- API Function ---
+
+/**
+ * Get aggregated stats for services used by an organization.
+ *
+ * Returns per-service stats with service-specific fields (counts, sizes, etc.).
+ * Services that error on the backend are omitted from the response.
+ * Services with no provisioned tenant DB return zero values.
+ *
+ * @param client - The API client instance
+ * @param orgId - The organization ID
+ * @param options - Optional filtering (service, time range)
+ * @returns Service stats data with per-service breakdown
+ * @throws {ServiceStatsError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * // Get stats for all services
+ * const stats = await getServiceStats(client, 'org_123');
+ * console.log(`KV keys: ${stats.services.keyvalue?.keyCount}`);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Get stats for a specific service
+ * const stats = await getServiceStats(client, 'org_123', {
+ *   service: 'keyvalue',
+ * });
+ * ```
+ */
+export async function getServiceStats(
+	client: APIClient,
+	orgId: string,
+	options?: ServiceStatsOptions
+): Promise<ServiceStatsData> {
+	const params = new URLSearchParams();
+	if (options?.service) params.set('service', options.service);
+	if (options?.start) params.set('start', options.start);
+	if (options?.end) params.set('end', options.end);
+
+	const queryString = params.toString();
+	const url = `/services/stats/${encodeURIComponent(orgId)}${queryString ? `?${queryString}` : ''}`;
+
+	const headers: Record<string, string> = {};
+	if (options?.orgIdHeader) {
+		headers['x-agentuity-orgid'] = options.orgIdHeader;
+	}
+
+	const resp = await client.get(
+		url,
+		ServiceStatsResponseSchema,
+		undefined,
+		Object.keys(headers).length > 0 ? headers : undefined
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new ServiceStatsError({
+		message: resp.message || 'Failed to get service stats',
+	});
+}

package/src/services/storage/config.ts

@@ -0,0 +1,111 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema, APIResponseSchemaNoData } from '../api.ts';
+import {
+	BucketConfigSchema,
+	BucketConfigUpdateSchema,
+	type BucketConfig,
+	type BucketConfigUpdate,
+} from './types.ts';
+import { BucketConfigResponseError } from './util.ts';
+
+export const BucketConfigGetResponseSchema = APIResponseSchema(BucketConfigSchema);
+export const BucketConfigUpdateResponseSchema = APIResponseSchema(BucketConfigSchema);
+export const BucketConfigDeleteResponseSchema = APIResponseSchemaNoData();
+
+/**
+ * Get the configuration for a bucket.
+ * Returns the current config with null for any fields using system defaults.
+ *
+ * @param client - The API client to use for the request
+ * @param bucketName - Name of the bucket to get config for
+ * @param extraHeaders - Optional extra headers (e.g. x-agentuity-orgid for CLI auth)
+ * @returns The bucket configuration
+ * @throws {BucketConfigResponseError} If the request fails
+ */
+export async function getBucketConfig(
+	client: APIClient,
+	bucketName: string,
+	extraHeaders?: Record<string, string>
+): Promise<BucketConfig> {
+	const url = `/bucket/config/${encodeURIComponent(bucketName)}`;
+
+	const resp = await client.get<z.infer<typeof BucketConfigGetResponseSchema>>(
+		url,
+		BucketConfigGetResponseSchema,
+		undefined,
+		extraHeaders
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new BucketConfigResponseError({ message: resp.message });
+}
+
+/**
+ * Update (upsert) bucket configuration.
+ * Partial update: only fields present in the request are changed.
+ * Send null for a field to reset it to system default.
+ * Omit a field to leave it unchanged.
+ *
+ * @param client - The API client to use for the request
+ * @param bucketName - Name of the bucket to update config for
+ * @param config - Partial config update (fields to set, null to unset, omit to leave)
+ * @param extraHeaders - Optional extra headers (e.g. x-agentuity-orgid for CLI auth)
+ * @returns The updated bucket configuration
+ * @throws {BucketConfigResponseError} If the request fails
+ */
+export async function updateBucketConfig(
+	client: APIClient,
+	bucketName: string,
+	config: BucketConfigUpdate,
+	extraHeaders?: Record<string, string>
+): Promise<BucketConfig> {
+	const url = `/bucket/config/${encodeURIComponent(bucketName)}`;
+
+	const resp = await client.put<
+		z.infer<typeof BucketConfigUpdateResponseSchema>,
+		BucketConfigUpdate
+	>(
+		url,
+		config,
+		BucketConfigUpdateResponseSchema,
+		BucketConfigUpdateSchema,
+		undefined,
+		extraHeaders
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new BucketConfigResponseError({ message: resp.message });
+}
+
+/**
+ * Delete all custom configuration for a bucket (reset to system defaults).
+ *
+ * @param client - The API client to use for the request
+ * @param bucketName - Name of the bucket to reset config for
+ * @param extraHeaders - Optional extra headers (e.g. x-agentuity-orgid for CLI auth)
+ * @throws {BucketConfigResponseError} If the request fails
+ */
+export async function deleteBucketConfig(
+	client: APIClient,
+	bucketName: string,
+	extraHeaders?: Record<string, string>
+): Promise<void> {
+	const url = `/bucket/config/${encodeURIComponent(bucketName)}`;
+
+	const resp = await client.delete<z.infer<typeof BucketConfigDeleteResponseSchema>>(
+		url,
+		BucketConfigDeleteResponseSchema,
+		undefined,
+		extraHeaders
+	);
+
+	if (!resp.success) {
+		throw new BucketConfigResponseError({ message: resp.message });
+	}
+}

package/src/services/storage/index.ts

@@ -0,0 +1,4 @@
+export * from './config.ts';
+export * from './objects.ts';
+export * from './types.ts';
+export { BucketConfigResponseError, StorageObjectsResponseError } from './util.ts';