@maravilla-labs/platform 0.1.18 → 0.1.21

package/src/types.ts

@@ -263,9 +263,247 @@ export interface DbFindOptions {
   sort?: any;
 }
 
+/**
+ * Storage interface for object/file storage operations.
+ * Provides S3-compatible API for storing and retrieving files.
+ * 
+ * @example
+ * ```typescript
+ * const platform = getPlatform();
+ * const storage = platform.env.STORAGE;
+ * 
+ * // Generate presigned upload URL for direct browser upload
+ * const uploadUrl = await storage.generateUploadUrl(
+ *   'profile-pics/user123.jpg',
+ *   'image/jpeg',
+ *   { sizeLimit: 5 * 1024 * 1024 } // 5MB limit
+ * );
+ * 
+ * // Generate download URL
+ * const downloadUrl = await storage.generateDownloadUrl(
+ *   'profile-pics/user123.jpg',
+ *   { expiresIn: 3600 } // 1 hour
+ * );
+ * 
+ * // Direct storage operations
+ * await storage.put('docs/report.pdf', pdfData, { contentType: 'application/pdf' });
+ * const file = await storage.get('docs/report.pdf');
+ * ```
+ */
+/**
+ * Source types accepted by Storage.putStream for streaming uploads.
+ */
+export type StoragePutStreamSource =
+  | Uint8Array
+  | ArrayBuffer
+  | string
+  | Blob
+  | ReadableStream<Uint8Array | ArrayBuffer | string | number[]>
+  | Iterable<Uint8Array | ArrayBuffer | string | number[]>
+  | AsyncIterable<Uint8Array | ArrayBuffer | string | number[]>;
+
+export interface Storage {
+  /**
+   * Generate a presigned URL for uploading a file directly from the browser.
+   * 
+   * @param key - The storage key/path for the file
+   * @param contentType - MIME type of the file
+   * @param options - Upload options
+   * @param options.sizeLimit - Maximum file size in bytes
+   * @returns Promise that resolves to upload URL details
+   * 
+   * @example
+   * ```typescript
+   * const upload = await storage.generateUploadUrl(
+   *   'uploads/document.pdf',
+   *   'application/pdf',
+   *   { sizeLimit: 10 * 1024 * 1024 } // 10MB
+   * );
+   * 
+   * // Use the URL to upload from browser
+   * await fetch(upload.url, {
+   *   method: upload.method,
+   *   headers: upload.headers,
+   *   body: fileData
+   * });
+   * ```
+   */
+  generateUploadUrl(key: string, contentType: string, options?: { sizeLimit?: number }): Promise<{
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    expiresIn: number;
+  }>;
+
+  /**
+   * Generate a presigned URL for downloading a file.
+   * 
+   * @param key - The storage key/path for the file
+   * @param options - Download options
+   * @param options.expiresIn - URL expiration time in seconds (default: 3600)
+   * @returns Promise that resolves to download URL details
+   * 
+   * @example
+   * ```typescript
+   * const download = await storage.generateDownloadUrl(
+   *   'uploads/document.pdf',
+   *   { expiresIn: 7200 } // 2 hours
+   * );
+   * 
+   * // Provide URL to client for download
+   * return { downloadUrl: download.url };
+   * ```
+   */
+  generateDownloadUrl(key: string, options?: { expiresIn?: number }): Promise<{
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    expiresIn: number;
+  }>;
+
+  /**
+   * Retrieve a file from storage.
+   * 
+   * @param key - The storage key/path for the file
+   * @returns Promise that resolves to the file data, or null if not found
+   * 
+   * @example
+   * ```typescript
+   * const imageData = await storage.get('profile-pics/user123.jpg');
+   * if (imageData) {
+   *   // Process the image data
+   *   return new Response(imageData, {
+   *     headers: { 'Content-Type': 'image/jpeg' }
+   *   });
+   * }
+   * ```
+   */
+  get(key: string): Promise<Uint8Array | null>;
+
+  /**
+   * Store a file in storage.
+   * 
+   * @param key - The storage key/path for the file
+   * @param data - The file data to store
+   * @param metadata - Optional metadata for the file
+   * @returns Promise that resolves when the operation completes
+   * 
+   * @example
+   * ```typescript
+   * // Store an image with metadata
+   * await storage.put(
+   *   'profile-pics/user123.jpg',
+   *   imageData,
+   *   {
+   *     contentType: 'image/jpeg',
+   *     userId: 'user123',
+   *     uploadedAt: new Date().toISOString()
+   *   }
+   * );
+   * ```
+   */
+  put(key: string, data: Uint8Array | string, metadata?: any): Promise<void>;
+
+  /**
+   * Store a file in storage using streaming/chunked data sources.
+   *
+   * Accepts a variety of source types (ReadableStream, Blob, ArrayBuffer,
+   * Uint8Array, string, or (async) iterables of chunks) and efficiently
+   * uploads them without requiring the caller to fully buffer the file
+   * in memory first when running in the native runtime. In the remote
+   * development client this currently buffers in memory as a fallback.
+   *
+   * Chunk types inside iterables can be Uint8Array, ArrayBuffer, number[]
+   * or string; strings are UTF-8 encoded.
+   *
+   * @param key - The storage key/path for the file
+   * @param source - Streaming or buffered data source
+   * @param metadata - Optional metadata for the file
+   * @returns Promise that resolves when the operation completes
+   *
+   * @example
+   * ```typescript
+   * // Upload a Blob (e.g. from a file input in a web app)
+   * await storage.putStream('videos/clip.mp4', fileBlob, { contentType: fileBlob.type });
+   *
+   * // Upload using an async generator that yields chunks
+   * async function *generate() {
+   *   for await (const piece of someAsyncSource) {
+   *     yield piece; // Uint8Array | string | ArrayBuffer
+   *   }
+   * }
+   * await storage.putStream('logs/large.txt', generate(), { contentType: 'text/plain' });
+   * ```
+   */
+  putStream(
+    key: string,
+    source: StoragePutStreamSource,
+    metadata?: any
+  ): Promise<void>;
+
+  /**
+   * Delete a file from storage.
+   * 
+   * @param key - The storage key/path for the file
+   * @returns Promise that resolves when the operation completes
+   * 
+   * @example
+   * ```typescript
+   * await storage.delete('profile-pics/old-photo.jpg');
+   * ```
+   */
+  delete(key: string): Promise<void>;
+
+  /**
+   * List files in storage with optional prefix filtering.
+   * 
+   * @param options - Listing options
+   * @param options.prefix - Only return keys that start with this prefix
+   * @param options.limit - Maximum number of keys to return
+   * @returns Promise that resolves to list of file keys and metadata
+   * 
+   * @example
+   * ```typescript
+   * // List all profile pictures
+   * const pics = await storage.list({ prefix: 'profile-pics/' });
+   * 
+   * // List with pagination
+   * const files = await storage.list({ prefix: 'docs/', limit: 20 });
+   * ```
+   */
+  list(options?: { prefix?: string; limit?: number }): Promise<Array<{
+    key: string;
+    size: number;
+    lastModified: string;
+    metadata?: any;
+  }>>;
+
+  /**
+   * Get metadata for a file without retrieving its contents.
+   * 
+   * @param key - The storage key/path for the file
+   * @returns Promise that resolves to file metadata, or null if not found
+   * 
+   * @example
+   * ```typescript
+   * const meta = await storage.getMetadata('uploads/document.pdf');
+   * if (meta) {
+   *   console.log(`File size: ${meta.size} bytes`);
+   *   console.log(`Last modified: ${meta.lastModified}`);
+   * }
+   * ```
+   */
+  getMetadata(key: string): Promise<{
+    size: number;
+    contentType?: string;
+    lastModified: string;
+    metadata?: any;
+  } | null>;
+}
+
 /**
  * Platform environment containing all available services.
- * This is the main interface for accessing KV storage and database operations.
+ * This is the main interface for accessing KV storage, database, and object storage operations.
  */
 export interface PlatformEnv {
   /** 
@@ -280,6 +518,8 @@ export interface PlatformEnv {
   KV: Record<string, KvNamespace>;
   /** Database interface for document operations */
   DB: Database;
+  /** Object/file storage interface */
+  STORAGE: Storage;
 }
 
 /**

package/tsconfig.json

@@ -2,7 +2,7 @@
   "compilerOptions": {
     "target": "ES2022",
     "module": "ES2022",
-    "lib": ["ES2022"],
+    "lib": ["ES2022", "DOM"],
     "moduleResolution": "node",
     "rootDir": "./src",
     "outDir": "./dist",