@agentuity/core 1.0.41 → 1.0.42

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

@@ -0,0 +1,207 @@
+import {
+	BucketConfigSchema,
+	BucketConfigUpdateSchema,
+	StorageAnalyticsResponseSchema,
+	StorageDeleteResponseSchema,
+	StorageListResponseSchema,
+	StoragePresignResponseSchema,
+	StorageStatsResponseSchema,
+} from './types.ts';
+import type { Service } from '../api-reference.ts';
+
+const service: Service = {
+	name: 'Object Storage',
+	slug: 'object-storage',
+	description: 'Store and manage files and binary objects in buckets',
+	endpoints: [
+		{
+			id: 'list-objects',
+			title: 'List Objects',
+			method: 'GET',
+			path: '/storage/objects/{bucket}',
+			description: 'List objects in a bucket with optional prefix and pagination.',
+			pathParams: [{ name: 'bucket', type: 'string', description: 'Bucket name' }],
+			queryParams: [
+				{
+					name: 'prefix',
+					type: 'string',
+					description: 'Only return keys with this prefix',
+					required: false,
+				},
+				{
+					name: 'limit',
+					type: 'number',
+					description: 'Maximum objects to return',
+					required: false,
+				},
+				{
+					name: 'offset',
+					type: 'number',
+					description: 'Offset for pagination',
+					required: false,
+				},
+			],
+			requestBody: null,
+			responseDescription: 'Paginated object listing.',
+			responseFields: { schema: StorageListResponseSchema },
+			statuses: [
+				{ code: 200, description: 'Object list returned' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/storage/objects/my-bucket?prefix=images/&limit=50',
+		},
+		{
+			id: 'delete-objects',
+			title: 'Delete Objects',
+			method: 'DELETE',
+			path: '/storage/objects/{bucket}',
+			description:
+				'Delete objects by key or by prefix. `key` and `prefix` are mutually exclusive query parameters.',
+			pathParams: [{ name: 'bucket', type: 'string', description: 'Bucket name' }],
+			queryParams: [
+				{
+					name: 'key',
+					type: 'string',
+					description: 'Delete a single object key',
+					required: false,
+				},
+				{
+					name: 'prefix',
+					type: 'string',
+					description: 'Delete all objects matching prefix',
+					required: false,
+				},
+			],
+			requestBody: null,
+			responseDescription: 'JSON response with deleted object count.',
+			responseFields: { schema: StorageDeleteResponseSchema },
+			statuses: [
+				{ code: 200, description: 'Delete operation completed' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/storage/objects/my-bucket?key=images/photo.jpg',
+		},
+		{
+			id: 'generate-presigned-url',
+			title: 'Generate Presigned URL',
+			method: 'GET',
+			path: '/storage/presign/{bucket}',
+			description: 'Generate a time-limited URL for uploading or downloading an object.',
+			pathParams: [{ name: 'bucket', type: 'string', description: 'Bucket name' }],
+			queryParams: [
+				{ name: 'key', type: 'string', description: 'Object key to access', required: true },
+				{
+					name: 'operation',
+					type: 'string',
+					description: 'Operation type: `download` or `upload` (default: `download`)',
+					required: false,
+				},
+			],
+			requestBody: null,
+			responseDescription: 'JSON response containing presigned URL and expiry.',
+			responseFields: { schema: StoragePresignResponseSchema },
+			statuses: [
+				{ code: 200, description: 'Presigned URL generated' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/storage/presign/my-bucket?key=images/photo.jpg&operation=download',
+		},
+		{
+			id: 'get-bucket-stats',
+			title: 'Get Bucket Stats',
+			method: 'GET',
+			path: '/storage/stats/{bucket}',
+			description: 'Get object count and total size for a bucket.',
+			pathParams: [{ name: 'bucket', type: 'string', description: 'Bucket name' }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Bucket-level usage and activity statistics.',
+			responseFields: { schema: StorageStatsResponseSchema },
+			statuses: [
+				{ code: 200, description: 'Bucket stats returned' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/storage/stats/my-bucket',
+		},
+		{
+			id: 'get-storage-analytics',
+			title: 'Get Storage Analytics',
+			method: 'GET',
+			path: '/storage/analytics',
+			description: 'Get aggregated analytics across buckets and daily snapshots.',
+			pathParams: [],
+			queryParams: [
+				{
+					name: 'days',
+					type: 'number',
+					description: 'Days of history to include (default: 180)',
+					required: false,
+				},
+			],
+			requestBody: null,
+			responseDescription: 'Analytics summary, per-bucket breakdown, and daily trend data.',
+			responseFields: { schema: StorageAnalyticsResponseSchema },
+			statuses: [
+				{ code: 200, description: 'Analytics returned' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/storage/analytics?days=30',
+		},
+		{
+			id: 'get-bucket-config',
+			title: 'Get Bucket Config',
+			method: 'GET',
+			path: '/bucket/config/{bucket}',
+			description: 'Retrieve effective configuration for a bucket.',
+			pathParams: [{ name: 'bucket', type: 'string', description: 'Bucket name' }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Bucket configuration settings and location metadata.',
+			responseFields: { schema: BucketConfigSchema },
+			statuses: [
+				{ code: 200, description: 'Bucket config returned' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/bucket/config/my-bucket',
+		},
+		{
+			id: 'update-bucket-config',
+			title: 'Update Bucket Config',
+			method: 'PUT',
+			path: '/bucket/config/{bucket}',
+			description: 'Update bucket configuration fields. Omitted fields remain unchanged.',
+			pathParams: [{ name: 'bucket', type: 'string', description: 'Bucket name' }],
+			queryParams: [],
+			requestBody: {
+				description: 'Partial bucket config update payload.',
+				fields: { schema: BucketConfigUpdateSchema },
+			},
+			responseDescription: 'Updated bucket configuration object.',
+			responseFields: { schema: BucketConfigSchema },
+			statuses: [
+				{ code: 200, description: 'Bucket config updated' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/bucket/config/my-bucket',
+			exampleBody: { ttl: 86400, public: true, cache_control: 'max-age=3600' },
+		},
+		{
+			id: 'delete-bucket-config',
+			title: 'Delete Bucket Config',
+			method: 'DELETE',
+			path: '/bucket/config/{bucket}',
+			description: 'Delete custom bucket config and reset to defaults.',
+			pathParams: [{ name: 'bucket', type: 'string', description: 'Bucket name' }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Empty response on success.',
+			statuses: [
+				{ code: 200, description: 'Bucket config deleted/reset' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/bucket/config/my-bucket',
+		},
+	],
+};
+
+export default service;

package/src/services/storage/types.ts

@@ -4,7 +4,9 @@ import { z } from 'zod';
 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');
+export const StorageTierSchema = z
+	.enum(StorageTierValues)
+	.describe('Storage tier: `STANDARD`, `INFREQUENT_ACCESS`, or `ARCHIVE`');
 
 /** Storage tier type */
 export type StorageTier = z.infer<typeof StorageTierSchema>;
@@ -39,7 +41,9 @@ export const CORSConfigSchema = z.object({
 /** 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'),
+	storage_tier: StorageTierSchema.nullable()
+		.optional()
+		.describe('Storage tier: `STANDARD`, `INFREQUENT_ACCESS`, or `ARCHIVE`'),
 	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
@@ -61,7 +65,9 @@ export const BucketConfigSchema = z.object({
  * 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'),
+	storage_tier: StorageTierSchema.nullable()
+		.optional()
+		.describe('Storage tier: `STANDARD`, `INFREQUENT_ACCESS`, or `ARCHIVE`'),
 	ttl: z
 		.number()
 		.int()

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

@@ -0,0 +1,163 @@
+import {
+	CreateStreamApiRequestSchema,
+	CreateStreamApiResponseSchema,
+	ListStreamsApiRequestSchema,
+	ListStreamsApiResponseSchema,
+	StreamInfoApiSchema,
+} from './types.ts';
+import type { Service } from '../api-reference.ts';
+
+const service: Service = {
+	name: 'Durable Streams',
+	slug: 'streams',
+	description: 'Create durable, resumable data streams with public URLs',
+	host: 'streams',
+	endpoints: [
+		{
+			id: 'create-stream',
+			title: 'Create Stream',
+			method: 'POST',
+			path: '/stream',
+			description: 'Create a new stream and receive its stream ID.',
+			pathParams: [],
+			queryParams: [],
+			requestBody: {
+				description: 'Stream creation payload.',
+				fields: { schema: CreateStreamApiRequestSchema },
+			},
+			responseDescription: 'JSON response containing the new stream ID.',
+			responseFields: { schema: CreateStreamApiResponseSchema, stripRequired: true },
+			statuses: [
+				{ code: 200, description: 'Stream created successfully' },
+				{ code: 401, description: 'Unauthorized' },
+				{ code: 402, description: 'Payment required' },
+			],
+			examplePath: '/stream',
+			exampleBody: {
+				name: 'agent-logs',
+				metadata: { exportDate: '2024-01-15' },
+				headers: { 'content-type': 'application/json' },
+			},
+			ttlNote:
+				'TTL behavior:\n- **Omitted**: Stream expires after the service default period\n- **`null` or `0`**: Stream never expires\n- **60–7,776,000**: Expires after specified seconds (values outside range are clamped)',
+		},
+		{
+			id: 'get-stream-info',
+			title: 'Get Stream Info',
+			method: 'POST',
+			path: '/stream/{id}/info',
+			description: 'Get stream metadata, size, public URL, and expiration info.',
+			pathParams: [{ name: 'id', type: 'string', description: 'The stream ID' }],
+			queryParams: [],
+			requestBody: {
+				description: 'Empty JSON object is required.',
+			},
+			responseDescription: 'JSON object with stream details.',
+			responseFields: { schema: StreamInfoApiSchema, stripRequired: true },
+			statuses: [
+				{ code: 200, description: 'Stream info returned' },
+				{ code: 401, description: 'Unauthorized' },
+				{ code: 404, description: 'Stream not found' },
+			],
+			examplePath: '/stream/stream_abc123/info',
+			exampleBody: {},
+		},
+		{
+			id: 'download-stream',
+			title: 'Download Stream',
+			method: 'GET',
+			path: '/stream/{id}',
+			description: 'Download the finalized stream contents as raw binary data.',
+			pathParams: [{ name: 'id', type: 'string', description: 'The stream ID' }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Raw binary stream data with original content type.',
+			statuses: [
+				{ code: 200, description: 'Stream data returned' },
+				{ code: 401, description: 'Unauthorized' },
+				{ code: 404, description: 'Stream not found' },
+			],
+			examplePath: '/stream/stream_abc123',
+		},
+		{
+			id: 'list-streams',
+			title: 'List Streams',
+			method: 'POST',
+			path: '/stream/list',
+			description: 'List streams with filtering, pagination, and sorting.',
+			pathParams: [],
+			queryParams: [],
+			requestBody: {
+				description: 'Optional list filters and pagination controls.',
+				fields: { schema: ListStreamsApiRequestSchema },
+			},
+			responseDescription: 'JSON response with stream list and total count.',
+			responseFields: { schema: ListStreamsApiResponseSchema, stripRequired: true },
+			statuses: [
+				{ code: 200, description: 'Stream list returned' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/stream/list',
+			exampleBody: { name: 'agent-logs', limit: 50 },
+		},
+		{
+			id: 'delete-stream',
+			title: 'Delete Stream',
+			method: 'DELETE',
+			path: '/stream/{id}',
+			description: 'Delete a stream by ID.',
+			pathParams: [{ name: 'id', type: 'string', description: 'The stream ID' }],
+			queryParams: [],
+			requestBody: null,
+			responseDescription: 'Empty response on success.',
+			statuses: [
+				{ code: 200, description: 'Stream deleted' },
+				{ code: 401, description: 'Unauthorized' },
+				{ code: 404, description: 'Stream not found' },
+			],
+			examplePath: '/stream/stream_abc123',
+		},
+		{
+			id: 'append-data',
+			title: 'Append Data',
+			method: 'POST',
+			path: '/stream/{id}/append',
+			description: 'Append a binary chunk (up to 5MB) to an open stream.',
+			pathParams: [{ name: 'id', type: 'string', description: 'The stream ID' }],
+			queryParams: [],
+			requestBody: {
+				description: 'Raw binary body. Set `Content-Type: application/octet-stream`.',
+			},
+			responseDescription: 'Empty response on success.',
+			statuses: [
+				{ code: 200, description: 'Data appended' },
+				{ code: 401, description: 'Unauthorized' },
+				{ code: 413, description: 'Chunk too large' },
+			],
+			examplePath: '/stream/stream_abc123/append',
+			exampleHeaders: { 'Content-Type': 'application/octet-stream' },
+			exampleBody: '<binary data>',
+		},
+		{
+			id: 'complete-stream',
+			title: 'Complete Stream',
+			method: 'POST',
+			path: '/stream/{id}/complete',
+			description: 'Finalize stream writing and make it available for reading.',
+			pathParams: [{ name: 'id', type: 'string', description: 'The stream ID' }],
+			queryParams: [],
+			requestBody: {
+				description:
+					'Empty body. Optional header: `X-Compress: gzip` for server-side compression.',
+			},
+			responseDescription: 'Empty response on success.',
+			statuses: [
+				{ code: 200, description: 'Stream completed' },
+				{ code: 401, description: 'Unauthorized' },
+			],
+			examplePath: '/stream/stream_abc123/complete',
+		},
+	],
+};
+
+export default service;

package/src/services/stream/types.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// API-level Zod schemas for the Durable Streams HTTP API.
+//
+// These use snake_case field names matching the raw HTTP contract.
+// The SDK-layer schemas in service.ts use camelCase (JS convention).
+// ---------------------------------------------------------------------------
+
+/** Request body for POST /stream (create stream) */
+export const CreateStreamApiRequestSchema = z.object({
+	name: z.string().describe('The namespace/group name (1–254 chars)'),
+	metadata: z.record(z.string(), z.string()).optional().describe('Optional key-value metadata'),
+	headers: z
+		.record(z.string(), z.string())
+		.optional()
+		.describe('Optional headers map (commonly includes `content-type`)'),
+	ttl: z.number().nullable().optional().describe('Stream TTL in seconds'),
+});
+
+export type CreateStreamApiRequest = z.infer<typeof CreateStreamApiRequestSchema>;
+
+/** Response for POST /stream (create stream) */
+export const CreateStreamApiResponseSchema = z.object({
+	id: z.string().describe('Created stream ID'),
+});
+
+export type CreateStreamApiResponse = z.infer<typeof CreateStreamApiResponseSchema>;
+
+/** Request body for POST /stream/list (list streams) */
+export const ListStreamsApiRequestSchema = z.object({
+	name: z.string().optional().describe('Filter by namespace'),
+	metadata: z.record(z.string(), z.string()).optional().describe('Filter by metadata fields'),
+	limit: z.number().optional().describe('Maximum streams to return'),
+	offset: z.number().optional().describe('Offset for pagination'),
+	sort: z
+		.string()
+		.optional()
+		.describe('Sort by `name`, `created`, `updated`, `size`, `count`, or `lastUsed`'),
+	direction: z.string().optional().describe('Sort direction: `asc` or `desc`'),
+});
+
+export type ListStreamsApiRequest = z.infer<typeof ListStreamsApiRequestSchema>;
+
+/** Single stream info object (snake_case, matches API response) */
+export const StreamInfoApiSchema = z.object({
+	id: z.string().describe('Stream ID'),
+	name: z.string().describe('Namespace name'),
+	metadata: z.record(z.string(), z.string()).describe('Stream metadata'),
+	url: z.string().describe('Public stream URL'),
+	size_bytes: z.number().describe('Current stream size in bytes'),
+	expires_at: z.string().nullable().describe('ISO 8601 expiration timestamp'),
+});
+
+export type StreamInfoApi = z.infer<typeof StreamInfoApiSchema>;
+
+/** Response for POST /stream/list. */
+export const ListStreamsApiResponseSchema = z.object({
+	success: z.boolean().describe('Whether the request succeeded'),
+	streams: z.array(StreamInfoApiSchema).describe('Matching streams'),
+	total: z.number().describe('Total matches'),
+});
+
+export type ListStreamsApiResponse = z.infer<typeof ListStreamsApiResponseSchema>;