@agentuity/core 1.0.31 → 1.0.33

package/src/api/session/list.ts

@@ -0,0 +1,136 @@
+import type { SortDirection } from '../../services/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 interface SessionListOptions {
+	/** @deprecated Use `limit` instead. Will be removed in a future version. */
+	count?: number;
+	limit?: number;
+	offset?: number;
+	sort?: SessionSortField;
+	direction?: SortDirection;
+	orgId?: string;
+	projectId?: string;
+	deploymentId?: string;
+	trigger?: string;
+	env?: string;
+	devmode?: boolean;
+	success?: boolean;
+	threadId?: string;
+	agentIdentifier?: string;
+	startAfter?: string;
+	startBefore?: string;
+	metadata?: Record<string, unknown>;
+}
+
+/**
+ * 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/api/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/api/session/util.ts

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

package/src/api/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/api/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';

package/src/api/storage/objects.ts

@@ -0,0 +1,250 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import {
+	StorageListResponseSchema,
+	StorageDeleteResponseSchema,
+	StoragePresignResponseSchema,
+	StorageStatsResponseSchema,
+	StorageAnalyticsResponseSchema,
+	type StorageListResponse,
+	type StorageDeleteResponse,
+	type StoragePresignResponse,
+	type StorageStatsResponse,
+	type StorageAnalyticsResponse,
+} from './types.ts';
+import { StorageObjectsResponseError } from './util.ts';
+
+export const StorageListAPIResponseSchema = APIResponseSchema(StorageListResponseSchema);
+export const StorageDeleteAPIResponseSchema = APIResponseSchema(StorageDeleteResponseSchema);
+export const StoragePresignAPIResponseSchema = APIResponseSchema(StoragePresignResponseSchema);
+export const StorageStatsAPIResponseSchema = APIResponseSchema(StorageStatsResponseSchema);
+export const StorageAnalyticsAPIResponseSchema = APIResponseSchema(StorageAnalyticsResponseSchema);
+
+export interface ListStorageObjectsOptions {
+	prefix?: string;
+	limit?: number;
+	offset?: number;
+}
+
+/**
+ * List objects in a storage bucket with optional prefix filtering and pagination.
+ *
+ * @param client - The API client to use for the request
+ * @param bucketName - Name of the bucket to list objects from
+ * @param options - Optional filtering/pagination options
+ * @param extraHeaders - Optional extra headers (e.g. x-agentuity-orgid for CLI auth)
+ * @returns Paginated list of objects with total count
+ * @throws {StorageObjectsResponseError} If the request fails
+ */
+export async function listStorageObjects(
+	client: APIClient,
+	bucketName: string,
+	options?: ListStorageObjectsOptions,
+	extraHeaders?: Record<string, string>
+): Promise<StorageListResponse> {
+	const params = new URLSearchParams();
+	if (options?.prefix) params.set('prefix', options.prefix);
+	if (options?.limit !== undefined) {
+		if (
+			!Number.isFinite(options.limit) ||
+			!Number.isInteger(options.limit) ||
+			options.limit < 0
+		) {
+			throw new TypeError('limit must be a non-negative integer');
+		}
+		params.set('limit', String(options.limit));
+	}
+	if (options?.offset !== undefined) {
+		if (
+			!Number.isFinite(options.offset) ||
+			!Number.isInteger(options.offset) ||
+			options.offset < 0
+		) {
+			throw new TypeError('offset must be a non-negative integer');
+		}
+		params.set('offset', String(options.offset));
+	}
+
+	const query = params.toString();
+	const url = `/storage/objects/${encodeURIComponent(bucketName)}${query ? `?${query}` : ''}`;
+
+	const resp = await client.get<z.infer<typeof StorageListAPIResponseSchema>>(
+		url,
+		StorageListAPIResponseSchema,
+		undefined,
+		extraHeaders
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new StorageObjectsResponseError({ message: resp.message });
+}
+
+export interface DeleteStorageObjectsOptions {
+	key?: string;
+	prefix?: string;
+}
+
+/**
+ * Delete objects from a storage bucket.
+ * Provide either `key` (single object) or `prefix` (all matching objects), but not both.
+ *
+ * @param client - The API client to use for the request
+ * @param bucketName - Name of the bucket to delete from
+ * @param options - Must include either key or prefix (mutually exclusive)
+ * @param extraHeaders - Optional extra headers (e.g. x-agentuity-orgid for CLI auth)
+ * @returns The count of deleted objects
+ * @throws {StorageObjectsResponseError} If the request fails
+ */
+export async function deleteStorageObjects(
+	client: APIClient,
+	bucketName: string,
+	options: DeleteStorageObjectsOptions,
+	extraHeaders?: Record<string, string>
+): Promise<StorageDeleteResponse> {
+	if (!options.key && !options.prefix) {
+		throw new StorageObjectsResponseError({ message: "Either 'key' or 'prefix' is required" });
+	}
+	if (options.key && options.prefix) {
+		throw new StorageObjectsResponseError({
+			message: "Provide either 'key' or 'prefix', not both",
+		});
+	}
+
+	const params = new URLSearchParams();
+	if (options.key) params.set('key', options.key);
+	if (options.prefix) params.set('prefix', options.prefix);
+
+	const url = `/storage/objects/${encodeURIComponent(bucketName)}?${params.toString()}`;
+
+	const resp = await client.delete<z.infer<typeof StorageDeleteAPIResponseSchema>>(
+		url,
+		StorageDeleteAPIResponseSchema,
+		undefined,
+		extraHeaders
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new StorageObjectsResponseError({ message: resp.message });
+}
+
+/**
+ * Generate a presigned URL for downloading or uploading an object.
+ *
+ * @param client - The API client to use for the request
+ * @param bucketName - Name of the bucket
+ * @param key - Object key
+ * @param operation - 'download' (default) or 'upload'
+ * @param extraHeaders - Optional extra headers (e.g. x-agentuity-orgid for CLI auth)
+ * @returns Presigned URL and expiry info
+ * @throws {StorageObjectsResponseError} If the request fails
+ */
+export async function presignStorageObject(
+	client: APIClient,
+	bucketName: string,
+	key: string,
+	operation: 'download' | 'upload' = 'download',
+	extraHeaders?: Record<string, string>
+): Promise<StoragePresignResponse> {
+	if (!key) {
+		throw new StorageObjectsResponseError({ message: "'key' must be a non-empty string" });
+	}
+	const params = new URLSearchParams();
+	params.set('key', key);
+	if (operation !== 'download') {
+		params.set('operation', operation);
+	}
+
+	const url = `/storage/presign/${encodeURIComponent(bucketName)}?${params.toString()}`;
+
+	const resp = await client.get<z.infer<typeof StoragePresignAPIResponseSchema>>(
+		url,
+		StoragePresignAPIResponseSchema,
+		undefined,
+		extraHeaders
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new StorageObjectsResponseError({ message: resp.message });
+}
+
+/**
+ * Get aggregate stats for a storage bucket (object count, total size).
+ *
+ * @param client - The API client to use for the request
+ * @param bucketName - Name of the bucket
+ * @param extraHeaders - Optional extra headers (e.g. x-agentuity-orgid for CLI auth)
+ * @returns Bucket statistics
+ * @throws {StorageObjectsResponseError} If the request fails
+ */
+export async function getStorageStats(
+	client: APIClient,
+	bucketName: string,
+	extraHeaders?: Record<string, string>
+): Promise<StorageStatsResponse> {
+	const url = `/storage/stats/${encodeURIComponent(bucketName)}`;
+
+	const resp = await client.get<z.infer<typeof StorageStatsAPIResponseSchema>>(
+		url,
+		StorageStatsAPIResponseSchema,
+		undefined,
+		extraHeaders
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new StorageObjectsResponseError({ message: resp.message });
+}
+
+export interface GetStorageAnalyticsOptions {
+	days?: number;
+}
+
+/**
+ * Get storage analytics for the org: summary totals, per-bucket breakdown, and daily snapshots.
+ *
+ * @param client - The API client to use for the request
+ * @param options - Optional options (days for sparkline history, default 180)
+ * @param extraHeaders - Optional extra headers (e.g. x-agentuity-orgid for CLI auth)
+ * @returns Analytics data with summary, buckets, and daily snapshots
+ * @throws {StorageObjectsResponseError} If the request fails
+ */
+export async function getStorageAnalytics(
+	client: APIClient,
+	options?: GetStorageAnalyticsOptions,
+	extraHeaders?: Record<string, string>
+): Promise<StorageAnalyticsResponse> {
+	const params = new URLSearchParams();
+	if (options?.days !== undefined) {
+		if (!Number.isFinite(options.days) || !Number.isInteger(options.days) || options.days < 0) {
+			throw new TypeError('days must be a non-negative integer');
+		}
+		params.set('days', String(options.days));
+	}
+
+	const query = params.toString();
+	const url = `/storage/analytics${query ? `?${query}` : ''}`;
+
+	const resp = await client.get<z.infer<typeof StorageAnalyticsAPIResponseSchema>>(
+		url,
+		StorageAnalyticsAPIResponseSchema,
+		undefined,
+		extraHeaders
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new StorageObjectsResponseError({ message: resp.message });
+}