@agentuity/server 1.0.29 → 1.0.30

package/src/api/storage/objects.ts

@@ -0,0 +1,240 @@
+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 { STORAGE_OBJECTS_API_VERSION, 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/${STORAGE_OBJECTS_API_VERSION}/${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/${STORAGE_OBJECTS_API_VERSION}/${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/${STORAGE_OBJECTS_API_VERSION}/${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/${STORAGE_OBJECTS_API_VERSION}/${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/${STORAGE_OBJECTS_API_VERSION}${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 });
+}

package/src/api/storage/types.ts

@@ -0,0 +1,134 @@
+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,10 @@
+import { StructuredError } from '@agentuity/core';
+
+export const BUCKET_CONFIG_API_VERSION = '2026-02-28';
+export const STORAGE_OBJECTS_API_VERSION = '2026-03-01';
+
+// Keep the old name exported for backward compat
+export const API_VERSION = BUCKET_CONFIG_API_VERSION;
+
+export const BucketConfigResponseError = StructuredError('BucketConfigResponseError');
+export const StorageObjectsResponseError = StructuredError('StorageObjectsResponseError');