@agentuity/core 1.0.32 → 1.0.33

package/src/api/storage/types.ts

@@ -0,0 +1,174 @@
+import { z } from 'zod';
+
+/** Valid storage tier values */
+export const StorageTierValues = ['STANDARD', 'INFREQUENT_ACCESS', 'ARCHIVE'] as const;
+
+/** Storage tier enum schema */
+export const StorageTierSchema = z.enum(StorageTierValues).describe('Storage tier for the bucket');
+
+/** Storage tier type */
+export type StorageTier = z.infer<typeof StorageTierSchema>;
+
+/** CORS configuration for a bucket */
+export const CORSConfigSchema = z.object({
+	allowed_origins: z
+		.array(z.string().describe('An allowed origin URL'))
+		.optional()
+		.describe('List of allowed origin URLs for CORS requests'),
+	allowed_methods: z
+		.array(z.string().describe('An allowed HTTP method'))
+		.optional()
+		.describe('List of allowed HTTP methods for CORS requests'),
+	allowed_headers: z
+		.array(z.string().describe('An allowed request header'))
+		.optional()
+		.describe('List of allowed request headers for CORS requests'),
+	expose_headers: z
+		.array(z.string().describe('A response header to expose'))
+		.optional()
+		.describe('List of response headers to expose to the browser'),
+	max_age_seconds: z
+		.number()
+		.int()
+		.min(0)
+		.nullable()
+		.optional()
+		.describe('Maximum time in seconds that preflight results can be cached'),
+});
+
+/** Full bucket config (response from GET/PUT) */
+export const BucketConfigSchema = z.object({
+	bucket_name: z.string().describe('The name of the storage bucket'),
+	storage_tier: StorageTierSchema.nullable().optional().describe('Storage tier for the bucket'),
+	ttl: z.number().int().min(0).nullable().optional().describe('Object TTL in seconds'),
+	public: z.boolean().nullable().optional().describe('Whether the bucket is publicly accessible'),
+	cache_control: z
+		.string()
+		.nullable()
+		.optional()
+		.describe('Default Cache-Control header for objects'),
+	cors: CORSConfigSchema.nullable().optional().describe('Custom CORS configuration'),
+	additional_headers: z
+		.record(z.string(), z.string())
+		.nullable()
+		.optional()
+		.describe('Additional response headers as key-value pairs'),
+	bucket_location: z.string().nullable().optional().describe('Bucket location or region override'),
+});
+
+/**
+ * Update request body (all fields optional — partial update).
+ * Send a field with a value to set it, send null to unset it, omit to leave unchanged.
+ */
+export const BucketConfigUpdateSchema = z.object({
+	storage_tier: StorageTierSchema.nullable().optional().describe('Storage tier for the bucket'),
+	ttl: z
+		.number()
+		.int()
+		.min(0)
+		.nullable()
+		.optional()
+		.describe('Object TTL in seconds (0 to clear)'),
+	public: z.boolean().nullable().optional().describe('Whether the bucket is publicly accessible'),
+	cache_control: z
+		.string()
+		.nullable()
+		.optional()
+		.describe('Default Cache-Control header for objects'),
+	cors: CORSConfigSchema.nullable().optional().describe('Custom CORS configuration'),
+	additional_headers: z
+		.record(z.string(), z.string())
+		.nullable()
+		.optional()
+		.describe('Additional response headers as key-value pairs'),
+});
+
+/** TypeScript types derived from Zod schemas */
+export type CORSConfig = z.infer<typeof CORSConfigSchema>;
+export type BucketConfig = z.infer<typeof BucketConfigSchema>;
+export type BucketConfigUpdate = z.infer<typeof BucketConfigUpdateSchema>;
+
+// --- Storage Objects types ---
+
+/** A storage object in a bucket */
+export const StorageObjectSchema = z.object({
+	bucket_name: z.string().describe('The bucket this object belongs to'),
+	key: z.string().describe('Object key (path)'),
+	size: z.number().int().nonnegative().describe('Object size in bytes'),
+	etag: z.string().optional().describe('Object ETag'),
+	content_type: z.string().optional().describe('Object content type'),
+	last_modified: z.string().optional().describe('Last modified timestamp (ISO8601)'),
+});
+
+/** Paginated list of storage objects */
+export const StorageListResponseSchema = z.object({
+	objects: z.array(StorageObjectSchema).describe('List of objects'),
+	total: z.number().int().nonnegative().describe('Total count matching the query'),
+	prefix: z.string().describe('Prefix filter applied'),
+	limit: z.number().int().nonnegative().describe('Page size'),
+	offset: z.number().int().nonnegative().describe('Page offset'),
+});
+
+/** Delete response */
+export const StorageDeleteResponseSchema = z.object({
+	deleted_count: z.number().int().nonnegative().describe('Number of objects deleted'),
+});
+
+/** Presigned URL response */
+export const StoragePresignResponseSchema = z.object({
+	presigned_url: z.string().describe('The presigned URL'),
+	expiry_seconds: z.number().int().nonnegative().describe('URL expiry time in seconds'),
+});
+
+/** Bucket stats response */
+export const StorageStatsResponseSchema = z.object({
+	bucket_name: z.string().describe('The bucket name'),
+	object_count: z.number().int().nonnegative().describe('Number of objects'),
+	total_size: z.number().int().nonnegative().describe('Total size in bytes'),
+	last_event_at: z.string().optional().describe('Last event timestamp (ISO8601)'),
+});
+
+// --- Storage Analytics types ---
+
+/** Summary totals across all buckets */
+export const StorageAnalyticsSummarySchema = z.object({
+	total_object_count: z.number().int().nonnegative().describe('Total objects across all buckets'),
+	total_size: z.number().int().nonnegative().describe('Total size in bytes across all buckets'),
+	estimated_monthly_cost: z.number().describe('Estimated monthly cost in USD'),
+	cost_per_gb_month: z.number().describe('Cost rate per GB per month in USD'),
+});
+
+/** Per-bucket breakdown */
+export const StorageAnalyticsBucketSchema = z.object({
+	bucket_name: z.string().describe('The bucket name'),
+	object_count: z.number().int().nonnegative().describe('Number of objects in this bucket'),
+	total_size: z.number().int().nonnegative().describe('Total size in bytes for this bucket'),
+	last_event_at: z.string().optional().describe('Last event timestamp (ISO8601)'),
+	estimated_monthly_cost: z.number().describe('Estimated monthly cost for this bucket in USD'),
+});
+
+/** Daily snapshot for sparklines */
+export const StorageAnalyticsDailySnapshotSchema = z.object({
+	date: z.string().describe('Snapshot date (YYYY-MM-DD)'),
+	total_object_count: z.number().int().nonnegative().describe('Total objects on this date'),
+	total_size: z.number().int().nonnegative().describe('Total size in bytes on this date'),
+	estimated_cost: z.number().describe('Estimated monthly cost at this snapshot in USD'),
+});
+
+/** Full analytics response */
+export const StorageAnalyticsResponseSchema = z.object({
+	summary: StorageAnalyticsSummarySchema.describe('Org-wide totals'),
+	buckets: z.array(StorageAnalyticsBucketSchema).describe('Per-bucket breakdown'),
+	daily: z.array(StorageAnalyticsDailySnapshotSchema).describe('Daily snapshots for sparklines'),
+	days: z.number().int().nonnegative().describe('Number of days requested'),
+});
+
+export type StorageObject = z.infer<typeof StorageObjectSchema>;
+export type StorageListResponse = z.infer<typeof StorageListResponseSchema>;
+export type StorageDeleteResponse = z.infer<typeof StorageDeleteResponseSchema>;
+export type StoragePresignResponse = z.infer<typeof StoragePresignResponseSchema>;
+export type StorageStatsResponse = z.infer<typeof StorageStatsResponseSchema>;
+export type StorageAnalyticsSummary = z.infer<typeof StorageAnalyticsSummarySchema>;
+export type StorageAnalyticsBucket = z.infer<typeof StorageAnalyticsBucketSchema>;
+export type StorageAnalyticsDailySnapshot = z.infer<typeof StorageAnalyticsDailySnapshotSchema>;
+export type StorageAnalyticsResponse = z.infer<typeof StorageAnalyticsResponseSchema>;

package/src/api/storage/util.ts

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

package/src/api/stream/get.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import { StreamResponseError } from './util.ts';
+
+export const StreamDetailSchema = z.object({
+	id: z.string().describe('the stream id'),
+	namespace: z.string().describe('the stream namespace'),
+	metadata: z.record(z.string(), z.string()).describe('stream metadata'),
+	url: z.string().describe('public URL to access the stream'),
+	sizeBytes: z.number().describe('size in bytes'),
+	createdAt: z.string().nullable().describe('ISO 8601 creation timestamp'),
+	updatedAt: z.string().nullable().describe('ISO 8601 last update timestamp'),
+	startedAt: z.string().nullable().describe('ISO 8601 stream start timestamp'),
+	endedAt: z.string().nullable().describe('ISO 8601 stream end timestamp'),
+	expiresAt: z.string().nullable().describe('ISO 8601 expiration timestamp or null'),
+	orgId: z.string().describe('the organization id'),
+	projectId: z.string().nullable().describe('the project id'),
+	completed: z.boolean().describe('whether the stream upload is completed'),
+	headers: z.record(z.string(), z.string()).describe('stream headers'),
+	chunks: z.number().describe('number of chunks'),
+});
+
+export const StreamDetailResponseSchema = APIResponseSchema(StreamDetailSchema);
+
+export type StreamDetailResponse = z.infer<typeof StreamDetailResponseSchema>;
+export type StreamDetail = z.infer<typeof StreamDetailSchema>;
+
+/**
+ * Get a specific stream by ID.
+ *
+ * @param client - The API client
+ * @param id - The stream ID
+ * @returns A promise that resolves to the stream details
+ *
+ * @example
+ * const stream = await streamGet(client, 'stream_abc123');
+ * console.log(`Namespace: ${stream.namespace}, Size: ${stream.sizeBytes} bytes`);
+ */
+export async function streamGet(client: APIClient, id: string): Promise<StreamDetail> {
+	const resp = await client.request<StreamDetailResponse>(
+		'GET',
+		`/cli/stream/${encodeURIComponent(id)}`,
+		StreamDetailResponseSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new StreamResponseError({ message: resp.message });
+}

package/src/api/stream/index.ts

@@ -0,0 +1,3 @@
+export * from './get.ts';
+export * from './list.ts';
+export * from './util.ts';

package/src/api/stream/list.ts

@@ -0,0 +1,127 @@
+import type { SortDirection } from '../../services/pagination.ts';
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import { StreamResponseError } from './util.ts';
+
+export const StreamInfoSchema = z.object({
+	id: z.string().describe('the stream id'),
+	namespace: z.string().describe('the stream namespace'),
+	metadata: z.record(z.string(), z.string()).describe('stream metadata'),
+	url: z.string().describe('public URL to access the stream'),
+	sizeBytes: z.number().describe('size in bytes'),
+	expiresAt: z.string().nullable().describe('ISO 8601 expiration timestamp or null'),
+	orgId: z.string().describe('the organization id'),
+	projectId: z.string().nullable().describe('the project id'),
+	projectName: z.string().nullable().describe('the project name'),
+});
+
+export const StreamListDataSchema = z.object({
+	streams: z.array(StreamInfoSchema).describe('list of streams'),
+	total: z.number().describe('total count of matching streams'),
+});
+
+export const StreamListResponseSchema = APIResponseSchema(StreamListDataSchema);
+
+export type StreamListResponse = z.infer<typeof StreamListResponseSchema>;
+export type StreamListData = z.infer<typeof StreamListDataSchema>;
+export type StreamInfo = z.infer<typeof StreamInfoSchema>;
+
+export interface StreamListOptions {
+	/**
+	 * Filter by specific project ID
+	 */
+	projectId?: string;
+	/**
+	 * Filter by specific organization ID
+	 */
+	orgId?: string;
+	/**
+	 * Filter by stream namespace
+	 */
+	namespace?: string;
+	/**
+	 * Filter by stream name
+	 */
+	name?: string;
+	/**
+	 * Maximum number of streams to return (default: 100, max: 1000)
+	 */
+	limit?: number;
+	/**
+	 * Number of streams to skip for pagination
+	 */
+	offset?: number;
+	/**
+	 * Filter by metadata key-value pairs
+	 */
+	metadata?: Record<string, string>;
+	/**
+	 * Field to sort by
+	 */
+	sort?: string;
+	/**
+	 * Sort direction (default: 'desc')
+	 */
+	direction?: SortDirection;
+}
+
+/**
+ * List streams with optional filtering.
+ *
+ * If no projectId or orgId is provided, returns streams from all orgs the user is a member of.
+ *
+ * @param client - The API client
+ * @param options - Filtering and pagination options
+ * @returns A promise that resolves to the list of streams with metadata
+ *
+ * @example
+ * // List all streams across all orgs
+ * const result = await streamList(client);
+ * console.log(`Found ${result.total} streams`);
+ *
+ * @example
+ * // List streams for a specific project
+ * const result = await streamList(client, { projectId: 'proj_123' });
+ *
+ * @example
+ * // List streams with namespace filter
+ * const result = await streamList(client, { namespace: 'agent-logs' });
+ *
+ * @example
+ * // List streams with metadata filter
+ * const result = await streamList(client, {
+ *   metadata: { type: 'export', env: 'production' }
+ * });
+ */
+export async function streamList(
+	client: APIClient,
+	options: StreamListOptions = {}
+): Promise<StreamListData> {
+	const { projectId, orgId, namespace, name, limit, offset, metadata } = options;
+	const params = new URLSearchParams();
+
+	if (projectId) params.set('projectId', projectId);
+	if (orgId) params.set('orgId', orgId);
+	if (namespace) params.set('namespace', namespace);
+	if (name) params.set('name', name);
+	if (limit !== undefined) params.set('limit', limit.toString());
+	if (offset !== undefined) params.set('offset', offset.toString());
+	if (metadata && Object.keys(metadata).length > 0) {
+		params.set('metadata', JSON.stringify(metadata));
+	}
+	if (options.sort) params.set('sort', options.sort);
+	if (options.direction) params.set('direction', options.direction);
+
+	const queryString = params.toString();
+	const resp = await client.request<StreamListResponse>(
+		'GET',
+		`/cli/stream${queryString ? `?${queryString}` : ''}`,
+		StreamListResponseSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new StreamResponseError({ message: resp.message });
+}

package/src/api/stream/util.ts

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

package/src/api/thread/delete.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { APIClient, APIResponseSchemaNoData } from '../api.ts';
+import { ThreadResponseError } from './util.ts';
+
+export const _ThreadDeleteRequestSchema = z.object({
+	id: z.string().describe('the thread id'),
+});
+
+export const ThreadDeleteResponseSchema = APIResponseSchemaNoData();
+
+export type ThreadDeleteRequest = z.infer<typeof _ThreadDeleteRequestSchema>;
+export type ThreadDeleteResponse = z.infer<typeof ThreadDeleteResponseSchema>;
+
+/**
+ * Delete a thread by id
+ *
+ * @param client
+ * @param request
+ * @returns
+ */
+export async function threadDelete(client: APIClient, request: ThreadDeleteRequest): Promise<void> {
+	const resp = await client.request<ThreadDeleteResponse>(
+		'DELETE',
+		`/thread/${request.id}`,
+		ThreadDeleteResponseSchema
+	);
+
+	if (!resp.success) {
+		throw new ThreadResponseError({ message: resp.message });
+	}
+}

package/src/api/thread/get.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { APIClient, APIResponseSchema } from '../api.ts';
+import { ThreadSchema, type Thread } from './list.ts';
+import { ThreadResponseError } from './util.ts';
+
+export const _ThreadGetRequestSchema = z.object({
+	id: z.string().describe('the thread id'),
+});
+
+export const ThreadGetResponseSchema = APIResponseSchema(ThreadSchema);
+
+export type ThreadGetRequest = z.infer<typeof _ThreadGetRequestSchema>;
+export type ThreadGetResponse = z.infer<typeof ThreadGetResponseSchema>;
+
+/**
+ * Get a single thread by id
+ *
+ * @param client
+ * @param request
+ * @returns
+ */
+export async function threadGet(client: APIClient, request: ThreadGetRequest): Promise<Thread> {
+	const resp = await client.request<ThreadGetResponse>(
+		'GET',
+		`/thread/${encodeURIComponent(request.id)}`,
+		ThreadGetResponseSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new ThreadResponseError({ message: resp.message });
+}

package/src/api/thread/index.ts

@@ -0,0 +1,4 @@
+export * from './get.ts';
+export * from './list.ts';
+export * from './delete.ts';
+export * from './util.ts';

package/src/api/thread/list.ts

@@ -0,0 +1,76 @@
+import type { SortDirection } from '../../services/pagination.ts';
+import { z } from 'zod';
+import { APIClient, APIResponseSchema } from '../api.ts';
+import { ThreadResponseError } from './util.ts';
+
+export const ThreadSchema = z.object({
+	id: z.string().describe('the thread id'),
+	created_at: z.string().describe('the creation timestamp'),
+	updated_at: z.string().describe('the last update timestamp'),
+	deleted: z.boolean().describe('whether the thread is deleted'),
+	deleted_at: z.string().nullable().describe('the deletion timestamp'),
+	deleted_by: z.string().nullable().describe('who deleted the thread'),
+	org_id: z.string().describe('the organization id'),
+	project_id: z.string().describe('the project id'),
+	user_data: z.string().nullable().optional().describe('the user data as JSON'),
+	metadata: z
+		.record(z.string(), z.unknown())
+		.nullable()
+		.optional()
+		.describe('unencrypted key-value metadata'),
+});
+
+export const ThreadListResponseData = z.array(ThreadSchema);
+
+export const ThreadListResponseSchema = APIResponseSchema(ThreadListResponseData);
+
+export type ThreadListResponse = z.infer<typeof ThreadListResponseSchema>;
+export type ThreadList = z.infer<typeof ThreadListResponseData>;
+export type Thread = z.infer<typeof ThreadSchema>;
+
+export type ThreadSortField = 'created' | 'updated';
+
+export interface ThreadListOptions {
+	count?: number;
+	limit?: number;
+	offset?: number;
+	sort?: ThreadSortField;
+	direction?: SortDirection;
+	orgId?: string;
+	projectId?: string;
+	metadata?: Record<string, unknown>;
+}
+
+/**
+ * List threads
+ *
+ * @param client
+ * @param options filtering and pagination options
+ * @returns
+ */
+export async function threadList(
+	client: APIClient,
+	options: ThreadListOptions = {}
+): Promise<ThreadList> {
+	const { limit, count, offset, sort, direction, orgId, projectId, 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 (offset !== undefined) params.set('offset', offset.toString());
+	if (sort) params.set('sort', sort);
+	if (direction) params.set('direction', direction);
+	if (metadata) params.set('metadata', JSON.stringify(metadata));
+
+	const resp = await client.request<ThreadListResponse>(
+		'GET',
+		`/thread?${params.toString()}`,
+		ThreadListResponseSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new ThreadResponseError({ message: resp.message });
+}

package/src/api/thread/util.ts

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

package/src/api/user/index.ts

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

package/src/api/user/util.ts

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

package/src/api/user/whoami.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { APIResponseSchema, APIClient } from '../api.ts';
+import { UserResponseError } from './util.ts';
+
+export const OrganizationSchema = z.object({
+	id: z.string().describe('the unique id for the organization'),
+	name: z.string().describe('the name of the organization'),
+});
+
+export const WhoamiResponse = z.object({
+	firstName: z.string().describe('the first name of the user'),
+	lastName: z.string().describe('the last name of the user'),
+	organizations: z.array(OrganizationSchema).describe('the organizations the user is a member of'),
+});
+export const WhoamiResponseSchema = APIResponseSchema(WhoamiResponse);
+
+export type WhoamiResponse = z.infer<typeof WhoamiResponseSchema>;
+export type User = z.infer<typeof WhoamiResponse>;
+
+/**
+ * Get the current authenticated user information
+ *
+ * @param client
+ * @returns
+ */
+export async function whoami(client: APIClient): Promise<User> {
+	const resp = await client.get<WhoamiResponse>('/cli/auth/user', WhoamiResponseSchema);
+	if (resp.success) {
+		return resp.data;
+	}
+	throw new UserResponseError({ message: resp.message });
+}