npm - @maravilla-labs/platform - Versions diffs - 0.1.18 → 0.1.20 - Mend

@maravilla-labs/platform 0.1.18 → 0.1.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/dist/index.d.ts CHANGED Viewed

@@ -263,9 +263,234 @@ interface DbFindOptions {
     /** Sort order specification (MongoDB-style: { field: 1 } for ascending, { field: -1 } for descending) */
     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.
+ */
+type StoragePutStreamSource = Uint8Array | ArrayBuffer | string | Blob | ReadableStream<Uint8Array | ArrayBuffer | string | number[]> | Iterable<Uint8Array | ArrayBuffer | string | number[]> | AsyncIterable<Uint8Array | ArrayBuffer | string | number[]>;
+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.
  */
 interface PlatformEnv {
     /**
@@ -280,6 +505,8 @@ interface PlatformEnv {
     KV: Record<string, KvNamespace>;
     /** Database interface for document operations */
     DB: Database;
+    /** Object/file storage interface */
+    STORAGE: Storage;
 }
 /**
  * Main platform interface providing access to all Maravilla runtime services.
@@ -423,4 +650,4 @@ declare function getPlatform(options?: {
  */
 declare function clearPlatformCache(): void;
-export { type Database, type DbFindOptions, type KvListResult, type KvNamespace, type Platform, type PlatformEnv, clearPlatformCache, getPlatform };
+export { type Database, type DbFindOptions, type KvListResult, type KvNamespace, type Platform, type PlatformEnv, type Storage, type StoragePutStreamSource, clearPlatformCache, getPlatform };

package/dist/index.js CHANGED Viewed

@@ -119,6 +119,151 @@ var RemoteDatabase = class {
     return this.deleteOne(collection, filter);
   }
 };
+var RemoteStorage = class _RemoteStorage {
+  constructor(baseUrl, headers) {
+    this.baseUrl = baseUrl;
+    this.headers = headers;
+  }
+  /**
+   * Internal method for making HTTP requests to the dev server.
+   * Handles error responses and authentication headers.
+   *
+   * @internal
+   */
+  async fetch(url, options = {}) {
+    const response = await fetch(url, {
+      ...options,
+      headers: { ...this.headers, ...options.headers }
+    });
+    if (!response.ok && response.status !== 404) {
+      const error = await response.text();
+      throw new Error(`Platform API error: ${response.status} - ${error}`);
+    }
+    return response;
+  }
+  async generateUploadUrl(key, contentType, options) {
+    return {
+      url: `${this.baseUrl}/api/storage/${encodeURIComponent(key)}`,
+      method: "PUT",
+      headers: {
+        "Content-Type": contentType,
+        ...this.headers
+        // Include tenant headers
+      },
+      expiresIn: 3600
+      // 1 hour
+    };
+  }
+  async generateDownloadUrl(key, options) {
+    return {
+      url: `${this.baseUrl}/api/storage/${encodeURIComponent(key)}`,
+      method: "GET",
+      headers: {},
+      expiresIn: options?.expiresIn || 3600
+      // Default 1 hour
+    };
+  }
+  async get(key) {
+    const response = await this.fetch(`${this.baseUrl}/api/storage/${encodeURIComponent(key)}`);
+    if (response.status === 404) return null;
+    const arrayBuffer = await response.arrayBuffer();
+    return new Uint8Array(arrayBuffer);
+  }
+  async put(key, data, metadata) {
+    const bodyData = typeof data === "string" ? new TextEncoder().encode(data) : data;
+    await this.fetch(`${this.baseUrl}/api/storage/${encodeURIComponent(key)}`, {
+      method: "PUT",
+      headers: metadata ? { "X-Metadata": JSON.stringify(metadata) } : {},
+      // Cast because TypeScript's lib.dom.d.ts BodyInit union sometimes misses Uint8Array
+      body: bodyData
+    });
+  }
+  async putStream(key, source, metadata) {
+    if (typeof Blob !== "undefined" && source instanceof Blob) {
+      await this.fetch(`${this.baseUrl}/api/storage/${encodeURIComponent(key)}`, {
+        method: "PUT",
+        headers: {
+          ...metadata ? { "X-Metadata": JSON.stringify(metadata) } : {},
+          "Content-Type": source.type || "application/octet-stream"
+        },
+        body: source
+      });
+      return;
+    }
+    if (source && typeof source.getReader === "function") {
+      await this.fetch(`${this.baseUrl}/api/storage/${encodeURIComponent(key)}`, {
+        method: "PUT",
+        headers: metadata ? { "X-Metadata": JSON.stringify(metadata) } : {},
+        body: source
+      });
+      return;
+    }
+    if (Symbol.asyncIterator in Object(source ?? {})) {
+      const asyncIt = source;
+      const stream = new ReadableStream({
+        async pull(controller) {
+          const { value, done } = await asyncIt[Symbol.asyncIterator]().next();
+          if (done) {
+            controller.close();
+            return;
+          }
+          controller.enqueue(_RemoteStorage.normalizeChunk(value));
+        }
+      });
+      await this.fetch(`${this.baseUrl}/api/storage/${encodeURIComponent(key)}`, {
+        method: "PUT",
+        headers: metadata ? { "X-Metadata": JSON.stringify(metadata) } : {},
+        body: stream
+      });
+      return;
+    }
+    if (Symbol.iterator in Object(source ?? {})) {
+      const it = source[Symbol.iterator]();
+      const stream = new ReadableStream({
+        pull(controller) {
+          const res = it.next();
+          if (res.done) {
+            controller.close();
+            return;
+          }
+          controller.enqueue(_RemoteStorage.normalizeChunk(res.value));
+        }
+      });
+      await this.fetch(`${this.baseUrl}/api/storage/${encodeURIComponent(key)}`, {
+        method: "PUT",
+        headers: metadata ? { "X-Metadata": JSON.stringify(metadata) } : {},
+        body: stream
+      });
+      return;
+    }
+    await this.put(key, _RemoteStorage.normalizeChunk(source), metadata);
+  }
+  static normalizeChunk(c) {
+    if (c == null) return new Uint8Array();
+    if (typeof c === "string") return new TextEncoder().encode(c);
+    if (c instanceof Uint8Array) return c;
+    if (c instanceof ArrayBuffer) return new Uint8Array(c);
+    if (Array.isArray(c)) return Uint8Array.from(c);
+    throw new Error("Unsupported chunk type in putStream");
+  }
+  async delete(key) {
+    await this.fetch(`${this.baseUrl}/api/storage/${encodeURIComponent(key)}`, {
+      method: "DELETE"
+    });
+  }
+  async list(options) {
+    const params = new URLSearchParams();
+    if (options?.prefix) params.set("prefix", options.prefix);
+    if (options?.limit) params.set("limit", options.limit.toString());
+    const response = await this.fetch(`${this.baseUrl}/api/storage?${params}`);
+    return response.json();
+  }
+  async getMetadata(key) {
+    const response = await this.fetch(`${this.baseUrl}/api/storage/${encodeURIComponent(key)}/metadata`);
+    if (response.status === 404) return null;
+    return response.json();
+  }
+};
 function createRemoteClient(baseUrl, tenant) {
   const headers = {
     "Content-Type": "application/json",
@@ -130,10 +275,12 @@ function createRemoteClient(baseUrl, tenant) {
     }
   });
   const db = new RemoteDatabase(baseUrl, headers);
+  const storage = new RemoteStorage(baseUrl, headers);
   return {
     env: {
       KV: kvProxy,
-      DB: db
+      DB: db,
+      STORAGE: storage
     }
   };
 }

package/dist/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../src/remote-client.ts","../src/index.ts"],"sourcesContent":["import type { KvNamespace, KvListResult, Database, DbFindOptions } from './types.js';\n\n/*\n Remote KV namespace implementation that communicates with a development server.\n * This class provides the KV interface by making HTTP requests to the dev server.\n * \n * @internal\n /\nclass RemoteKvNamespace implements KvNamespace {\n constructor(\n private baseUrl: string,\n private namespace: string,\n private headers: Record<string, string>\n ) {}\n\n /\n Internal method for making HTTP requests to the dev server.\n * Handles error responses and authentication headers.\n * \n * @internal\n /\n private async fetch(url: string, options: RequestInit = {}) {\n const response = await fetch(url, {\n ...options,\n headers: { ...this.headers, ...options.headers },\n });\n\n if (!response.ok && response.status !== 404) {\n const error = await response.text();\n throw new Error(`Platform API error: ${response.status} - ${error}`);\n }\n\n return response;\n }\n\n async get(key: string): Promise<any> {\n const response = await this.fetch(`${this.baseUrl}/api/kv/${this.namespace}/${key}`);\n if (response.status === 404) return null;\n return response.json();\n }\n\n async put(key: string, value: any, options?: { expirationTtl?: number }): Promise<void> {\n const headers: Record<string, string> = {};\n if (options?.expirationTtl) {\n headers['X-TTL'] = options.expirationTtl.toString();\n }\n\n await this.fetch(`${this.baseUrl}/api/kv/${this.namespace}/${key}`, {\n method: 'PUT',\n headers,\n body: JSON.stringify(value),\n });\n }\n\n async delete(key: string): Promise<void> {\n await this.fetch(`${this.baseUrl}/api/kv/${this.namespace}/${key}`, {\n method: 'DELETE',\n });\n }\n\n async list(options?: { prefix?: string; limit?: number; cursor?: string }): Promise<KvListResult> {\n const response = await this.fetch(`${this.baseUrl}/api/kv/${this.namespace}`, {\n method: 'POST',\n body: JSON.stringify(options \|\| {}),\n });\n const data = await response.json() as any;\n return {\n keys: data.result \|\| [],\n list_complete: !data.result_info?.cursor,\n cursor: data.result_info?.cursor,\n };\n }\n}\n\n/\n Remote Database implementation that communicates with a development server.\n * This class provides the Database interface by making HTTP requests to the dev server.\n * \n * @internal\n /\nclass RemoteDatabase implements Database {\n constructor(\n private baseUrl: string,\n private headers: Record<string, string>\n ) {}\n\n /\n Internal method for making HTTP requests to the dev server.\n * Handles error responses and authentication headers.\n * \n * @internal\n /\n private async fetch(url: string, options: RequestInit = {}) {\n const response = await fetch(url, {\n ...options,\n headers: { ...this.headers, ...options.headers },\n });\n\n if (!response.ok && response.status !== 404) {\n const error = await response.text();\n throw new Error(`Platform API error: ${response.status} - ${error}`);\n }\n\n return response;\n }\n\n async find(collection: string, filter: any = {}, options: DbFindOptions = {}): Promise<any[]> {\n const response = await this.fetch(`${this.baseUrl}/api/db/${collection}`, {\n method: 'POST',\n body: JSON.stringify({ filter, options }),\n });\n return response.json() as Promise<any[]>;\n }\n\n async findOne(collection: string, filter: any): Promise<any \| null> {\n const response = await this.fetch(`${this.baseUrl}/api/db/${collection}/findOne`, {\n method: 'POST',\n body: JSON.stringify(filter),\n });\n if (response.status === 404) return null;\n return response.json();\n }\n\n async insertOne(collection: string, document: any): Promise<string> {\n const response = await this.fetch(`${this.baseUrl}/api/db/${collection}`, {\n method: 'PUT',\n body: JSON.stringify(document),\n });\n const result = await response.json() as any;\n return result.id;\n }\n\n async updateOne(collection: string, filter: any, update: any): Promise<{ modified: number }> {\n const response = await this.fetch(`${this.baseUrl}/api/db/${collection}/update`, {\n method: 'POST',\n body: JSON.stringify({ filter, update }),\n });\n return response.json() as Promise<{ modified: number }>;\n }\n\n async deleteOne(collection: string, filter: any): Promise<{ deleted: number }> {\n const response = await this.fetch(`${this.baseUrl}/api/db/${collection}/delete`, {\n method: 'DELETE',\n body: JSON.stringify(filter),\n });\n return response.json() as Promise<{ deleted: number }>;\n }\n\n async deleteMany(collection: string, filter: any): Promise<{ deleted: number }> {\n // For now, deleteMany is the same as deleteOne in the remote client\n // This would need to be implemented properly in the dev server\n return this.deleteOne(collection, filter);\n }\n}\n\n/\n Create a remote platform client for development environments.\n * \n * This function creates a platform instance that communicates with a development\n * server over HTTP. It's used internally by getPlatform() when running in development\n * mode and no native platform is available.\n * \n * @param baseUrl - The base URL of the development server\n * @param tenant - The tenant identifier for multi-tenancy support\n * @returns A platform instance that proxies requests to the development server\n * \n * @internal\n * \n * @example\n * ```typescript\n * // This is typically called internally by getPlatform()\n * const platform = createRemoteClient('http://localhost:3001', 'dev-tenant');\n * \n * // The returned platform works the same as the native one\n * await platform.env.KV.cache.put('key', 'value');\n * await platform.env.DB.insertOne('users', { name: 'John' });\n * ```\n /\nexport function createRemoteClient(baseUrl: string, tenant: string) {\n const headers = {\n 'Content-Type': 'application/json',\n 'X-Tenant-Id': tenant,\n };\n\n // Create KV namespaces proxy that dynamically creates namespace instances\n const kvProxy = new Proxy({} as Record<string, KvNamespace>, {\n get(_, namespace: string) {\n return new RemoteKvNamespace(baseUrl, namespace, headers);\n }\n });\n\n const db = new RemoteDatabase(baseUrl, headers);\n\n return {\n env: {\n KV: kvProxy,\n DB: db,\n }\n };\n}","/\n @fileoverview Maravilla Platform SDK\n * \n * This package provides the main interface for accessing Maravilla runtime services\n * including Key-Value storage and Database operations. It automatically detects the\n * runtime environment and provides the appropriate implementation.\n * \n * ## Environment Detection\n * \n * The SDK automatically detects and adapts to different environments:\n * - Production: Uses native Maravilla runtime APIs\n * - Development: Connects to development server via HTTP\n * - Testing: Can be mocked or use development server\n * \n * ## Key Features\n * \n * - KV Storage: Cloudflare Workers KV-compatible API for key-value operations\n * - Database: MongoDB-style document database operations\n * - Multi-tenancy: Built-in tenant isolation and support\n * - TypeScript: Fully typed APIs with comprehensive JSDoc comments\n * - Development-friendly: Seamless development server integration\n * \n * @example\n * ```typescript\n * import { getPlatform } from '@maravilla/platform';\n * \n * const platform = getPlatform();\n * \n * // KV operations\n * await platform.env.KV.cache.put('user:123', { name: 'John' });\n * const user = await platform.env.KV.cache.get('user:123');\n * \n * // Database operations\n * const userId = await platform.env.DB.insertOne('users', {\n * name: 'John Doe',\n * email: 'john@example.com'\n * });\n * \n * const users = await platform.env.DB.find('users', { active: true });\n * ```\n * \n * @author Maravilla Team\n * @since 1.0.0\n /\n\nimport type { Platform } from './types.js';\nimport { createRemoteClient } from './remote-client.js';\n\nexport from './types.js';\n\n/*\n Global platform instance injected by Maravilla runtime or development tools.\n * This should not be accessed directly - use getPlatform() instead.\n * \n * @internal\n /\n\ndeclare global {\n var __maravilla_platform: Platform \| undefined;\n var platform: Platform \| undefined;\n}\n\nlet cachedPlatform: Platform \| null = null;\n\n/\n Get the platform instance. This will:\n * 1. Check if running in Maravilla runtime (global.platform exists)\n * 2. Check if a platform was injected via vite plugin or hooks\n * 3. Fall back to remote client for development\n * \n * The platform provides access to KV storage and database operations,\n * with automatic environment detection for seamless development and production.\n * \n * @param options - Optional configuration for development mode\n * @param options.devServerUrl - URL of the development server (defaults to MARAVILLA_DEV_SERVER env var or http://localhost:3001)\n * @param options.tenant - Tenant identifier for multi-tenancy (defaults to MARAVILLA_TENANT env var or 'dev-tenant')\n * @returns Platform instance with access to KV and database services\n * \n * @example\n * ```typescript\n * import { getPlatform } from '@maravilla/platform';\n * \n * // Basic usage (auto-detects environment)\n * const platform = getPlatform();\n * \n * // Development with custom server\n * const platform = getPlatform({\n * devServerUrl: 'http://localhost:3001',\n * tenant: 'my-app'\n * });\n * \n * // Use KV storage\n * await platform.env.KV.cache.put('user:123', { name: 'John' });\n * const user = await platform.env.KV.cache.get('user:123');\n * \n * // Use database\n * const userId = await platform.env.DB.insertOne('users', {\n * name: 'John Doe',\n * email: 'john@example.com'\n * });\n * ```\n /\nexport function getPlatform(options?: {\n devServerUrl?: string;\n tenant?: string;\n}): Platform {\n // Return cached if available\n if (cachedPlatform) {\n return cachedPlatform;\n }\n\n // 1. Check if we're in the real Maravilla runtime\n if (typeof globalThis !== 'undefined') {\n // Check for native platform (in production runtime)\n if (globalThis.platform) {\n console.log('[platform] Using native Maravilla platform');\n cachedPlatform = globalThis.platform;\n return cachedPlatform;\n }\n\n // Check for injected platform (from vite plugin or hooks)\n if (globalThis.__maravilla_platform) {\n console.log('[platform] Using injected platform');\n cachedPlatform = globalThis.__maravilla_platform;\n return cachedPlatform;\n }\n }\n\n // 2. Fall back to remote client for development\n const devServerUrl = options?.devServerUrl \|\| process.env.MARAVILLA_DEV_SERVER \|\| 'http://localhost:3001';\n const tenant = options?.tenant \|\| process.env.MARAVILLA_TENANT \|\| 'dev-tenant';\n \n console.log(`[platform] Creating remote client for ${devServerUrl}`);\n cachedPlatform = createRemoteClient(devServerUrl, tenant);\n \n // Cache it globally for other modules\n if (typeof globalThis !== 'undefined') {\n globalThis.__maravilla_platform = cachedPlatform;\n }\n \n return cachedPlatform;\n}\n\n/\n Clear the cached platform instance (useful for testing).\n * \n * This function resets the internal platform cache and clears any globally\n * injected platform instances. Subsequent calls to getPlatform() will\n * re-initialize the platform based on the current environment.\n * \n * @example\n * ```typescript\n * import { clearPlatformCache, getPlatform } from '@maravilla/platform';\n * \n * // In tests, clear cache between test cases\n * afterEach(() => {\n * clearPlatformCache();\n * });\n * \n * // Or when switching between different environments\n * clearPlatformCache();\n * const newPlatform = getPlatform({ devServerUrl: 'http://localhost:3002' });\n * ```\n */\nexport function clearPlatformCache(): void {\n cachedPlatform = null;\n if (typeof globalThis !== 'undefined') {\n globalThis.__maravilla_platform = undefined;\n }\n}"],"mappings":"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","names":[]}
1	+ {"version":3,"sources":["../src/remote-client.ts","../src/index.ts"],"sourcesContent":["import type { KvNamespace, KvListResult, Database, DbFindOptions, Storage } from './types.js';\n\n/*\n Remote KV namespace implementation that communicates with a development server.\n * This class provides the KV interface by making HTTP requests to the dev server.\n * \n * @internal\n /\nclass RemoteKvNamespace implements KvNamespace {\n constructor(\n private baseUrl: string,\n private namespace: string,\n private headers: Record<string, string>\n ) {}\n\n /\n Internal method for making HTTP requests to the dev server.\n * Handles error responses and authentication headers.\n * \n * @internal\n /\n private async fetch(url: string, options: RequestInit = {}) {\n const response = await fetch(url, {\n ...options,\n headers: { ...this.headers, ...options.headers },\n });\n\n if (!response.ok && response.status !== 404) {\n const error = await response.text();\n throw new Error(`Platform API error: ${response.status} - ${error}`);\n }\n\n return response;\n }\n\n async get(key: string): Promise<any> {\n const response = await this.fetch(`${this.baseUrl}/api/kv/${this.namespace}/${key}`);\n if (response.status === 404) return null;\n return response.json();\n }\n\n async put(key: string, value: any, options?: { expirationTtl?: number }): Promise<void> {\n const headers: Record<string, string> = {};\n if (options?.expirationTtl) {\n headers['X-TTL'] = options.expirationTtl.toString();\n }\n\n await this.fetch(`${this.baseUrl}/api/kv/${this.namespace}/${key}`, {\n method: 'PUT',\n headers,\n body: JSON.stringify(value),\n });\n }\n\n async delete(key: string): Promise<void> {\n await this.fetch(`${this.baseUrl}/api/kv/${this.namespace}/${key}`, {\n method: 'DELETE',\n });\n }\n\n async list(options?: { prefix?: string; limit?: number; cursor?: string }): Promise<KvListResult> {\n const response = await this.fetch(`${this.baseUrl}/api/kv/${this.namespace}`, {\n method: 'POST',\n body: JSON.stringify(options \|\| {}),\n });\n const data = await response.json() as any;\n return {\n keys: data.result \|\| [],\n list_complete: !data.result_info?.cursor,\n cursor: data.result_info?.cursor,\n };\n }\n}\n\n/\n Remote Database implementation that communicates with a development server.\n * This class provides the Database interface by making HTTP requests to the dev server.\n * \n * @internal\n /\nclass RemoteDatabase implements Database {\n constructor(\n private baseUrl: string,\n private headers: Record<string, string>\n ) {}\n\n /\n Internal method for making HTTP requests to the dev server.\n * Handles error responses and authentication headers.\n * \n * @internal\n /\n private async fetch(url: string, options: RequestInit = {}) {\n const response = await fetch(url, {\n ...options,\n headers: { ...this.headers, ...options.headers },\n });\n\n if (!response.ok && response.status !== 404) {\n const error = await response.text();\n throw new Error(`Platform API error: ${response.status} - ${error}`);\n }\n\n return response;\n }\n\n async find(collection: string, filter: any = {}, options: DbFindOptions = {}): Promise<any[]> {\n const response = await this.fetch(`${this.baseUrl}/api/db/${collection}`, {\n method: 'POST',\n body: JSON.stringify({ filter, options }),\n });\n return response.json() as Promise<any[]>;\n }\n\n async findOne(collection: string, filter: any): Promise<any \| null> {\n const response = await this.fetch(`${this.baseUrl}/api/db/${collection}/findOne`, {\n method: 'POST',\n body: JSON.stringify(filter),\n });\n if (response.status === 404) return null;\n return response.json();\n }\n\n async insertOne(collection: string, document: any): Promise<string> {\n const response = await this.fetch(`${this.baseUrl}/api/db/${collection}`, {\n method: 'PUT',\n body: JSON.stringify(document),\n });\n const result = await response.json() as any;\n return result.id;\n }\n\n async updateOne(collection: string, filter: any, update: any): Promise<{ modified: number }> {\n const response = await this.fetch(`${this.baseUrl}/api/db/${collection}/update`, {\n method: 'POST',\n body: JSON.stringify({ filter, update }),\n });\n return response.json() as Promise<{ modified: number }>;\n }\n\n async deleteOne(collection: string, filter: any): Promise<{ deleted: number }> {\n const response = await this.fetch(`${this.baseUrl}/api/db/${collection}/delete`, {\n method: 'DELETE',\n body: JSON.stringify(filter),\n });\n return response.json() as Promise<{ deleted: number }>;\n }\n\n async deleteMany(collection: string, filter: any): Promise<{ deleted: number }> {\n // For now, deleteMany is the same as deleteOne in the remote client\n // This would need to be implemented properly in the dev server\n return this.deleteOne(collection, filter);\n }\n}\n\n/\n Remote Storage implementation that communicates with a development server.\n * This class provides the Storage interface by making HTTP requests to the dev server.\n * \n * @internal\n /\nclass RemoteStorage implements Storage {\n constructor(\n private baseUrl: string,\n private headers: Record<string, string>\n ) {}\n\n /\n Internal method for making HTTP requests to the dev server.\n * Handles error responses and authentication headers.\n * \n * @internal\n /\n private async fetch(url: string, options: RequestInit = {}) {\n const response = await fetch(url, {\n ...options,\n headers: { ...this.headers, ...options.headers },\n });\n\n if (!response.ok && response.status !== 404) {\n const error = await response.text();\n throw new Error(`Platform API error: ${response.status} - ${error}`);\n }\n\n return response;\n }\n\n async generateUploadUrl(key: string, contentType: string, options?: { sizeLimit?: number }): Promise<{\n url: string;\n method: string;\n headers: Record<string, string>;\n expiresIn: number;\n }> {\n // For development, return a direct upload URL to the dev server\n // The dev server supports PUT directly to /api/storage/{key}\n return {\n url: `${this.baseUrl}/api/storage/${encodeURIComponent(key)}`,\n method: 'PUT',\n headers: {\n 'Content-Type': contentType,\n ...this.headers, // Include tenant headers\n },\n expiresIn: 3600, // 1 hour\n };\n }\n\n async generateDownloadUrl(key: string, options?: { expiresIn?: number }): Promise<{\n url: string;\n method: string;\n headers: Record<string, string>;\n expiresIn: number;\n }> {\n // For development, return a direct download URL to the dev server\n // In production, this would call the actual storage service for presigned URLs\n return {\n url: `${this.baseUrl}/api/storage/${encodeURIComponent(key)}`,\n method: 'GET',\n headers: {},\n expiresIn: options?.expiresIn \|\| 3600, // Default 1 hour\n };\n }\n\n async get(key: string): Promise<Uint8Array \| null> {\n const response = await this.fetch(`${this.baseUrl}/api/storage/${encodeURIComponent(key)}`);\n if (response.status === 404) return null;\n const arrayBuffer = await response.arrayBuffer();\n return new Uint8Array(arrayBuffer);\n }\n\n async put(key: string, data: Uint8Array \| string, metadata?: any): Promise<void> {\n // Convert string to Uint8Array if needed\n const bodyData = typeof data === 'string' \n ? new TextEncoder().encode(data)\n : data;\n\n await this.fetch(`${this.baseUrl}/api/storage/${encodeURIComponent(key)}`, {\n method: 'PUT',\n headers: metadata ? { 'X-Metadata': JSON.stringify(metadata) } : {},\n // Cast because TypeScript's lib.dom.d.ts BodyInit union sometimes misses Uint8Array\n body: bodyData as any,\n });\n }\n\n async putStream(key: string, source: any, metadata?: any): Promise<void> {\n // If it's a Blob we can send directly\n if (typeof Blob !== 'undefined' && source instanceof Blob) {\n await this.fetch(`${this.baseUrl}/api/storage/${encodeURIComponent(key)}`, {\n method: 'PUT',\n headers: {\n ...(metadata ? { 'X-Metadata': JSON.stringify(metadata) } : {}),\n 'Content-Type': source.type \|\| 'application/octet-stream'\n },\n body: source as any,\n });\n return;\n }\n\n // ReadableStream\n if (source && typeof source.getReader === 'function') {\n await this.fetch(`${this.baseUrl}/api/storage/${encodeURIComponent(key)}`, {\n method: 'PUT',\n headers: metadata ? { 'X-Metadata': JSON.stringify(metadata) } : {},\n body: source as any,\n });\n return;\n }\n\n // Async iterable -> wrap in ReadableStream\n if (Symbol.asyncIterator in Object(source ?? {})) {\n const asyncIt = source as AsyncIterable<any>;\n const stream = new ReadableStream({\n async pull(controller) {\n const { value, done } = await asyncIt[Symbol.asyncIterator]().next();\n if (done) { controller.close(); return; }\n controller.enqueue(RemoteStorage.normalizeChunk(value));\n }\n });\n await this.fetch(`${this.baseUrl}/api/storage/${encodeURIComponent(key)}`, {\n method: 'PUT',\n headers: metadata ? { 'X-Metadata': JSON.stringify(metadata) } : {},\n body: stream as any,\n });\n return;\n }\n\n // Synchronous iterable\n if (Symbol.iterator in Object(source ?? {})) {\n const it = (source as Iterable<any>)[Symbol.iterator]();\n const stream = new ReadableStream({\n pull(controller) {\n const res = it.next();\n if (res.done) { controller.close(); return; }\n controller.enqueue(RemoteStorage.normalizeChunk(res.value));\n }\n });\n await this.fetch(`${this.baseUrl}/api/storage/${encodeURIComponent(key)}`, {\n method: 'PUT',\n headers: metadata ? { 'X-Metadata': JSON.stringify(metadata) } : {},\n body: stream as any,\n });\n return;\n }\n\n // Fallback: primitive/string/Uint8Array/ArrayBuffer\n await this.put(key, RemoteStorage.normalizeChunk(source), metadata);\n }\n private static normalizeChunk(c: any): Uint8Array {\n if (c == null) return new Uint8Array();\n if (typeof c === 'string') return new TextEncoder().encode(c);\n if (c instanceof Uint8Array) return c;\n if (c instanceof ArrayBuffer) return new Uint8Array(c);\n if (Array.isArray(c)) return Uint8Array.from(c);\n throw new Error('Unsupported chunk type in putStream');\n }\n async delete(key: string): Promise<void> {\n await this.fetch(`${this.baseUrl}/api/storage/${encodeURIComponent(key)}`, {\n method: 'DELETE',\n });\n }\n\n async list(options?: { prefix?: string; limit?: number }): Promise<Array<{\n key: string;\n size: number;\n lastModified: string;\n metadata?: any;\n }>> {\n const params = new URLSearchParams();\n if (options?.prefix) params.set('prefix', options.prefix);\n if (options?.limit) params.set('limit', options.limit.toString());\n\n const response = await this.fetch(`${this.baseUrl}/api/storage?${params}`);\n return response.json();\n }\n\n async getMetadata(key: string): Promise<{\n size: number;\n contentType?: string;\n lastModified: string;\n metadata?: any;\n } \| null> {\n const response = await this.fetch(`${this.baseUrl}/api/storage/${encodeURIComponent(key)}/metadata`);\n if (response.status === 404) return null;\n return response.json();\n }\n}\n\n/\n Create a remote platform client for development environments.\n * \n * This function creates a platform instance that communicates with a development\n * server over HTTP. It's used internally by getPlatform() when running in development\n * mode and no native platform is available.\n * \n * @param baseUrl - The base URL of the development server\n * @param tenant - The tenant identifier for multi-tenancy support\n * @returns A platform instance that proxies requests to the development server\n * \n * @internal\n * \n * @example\n * ```typescript\n * // This is typically called internally by getPlatform()\n * const platform = createRemoteClient('http://localhost:3001', 'dev-tenant');\n * \n * // The returned platform works the same as the native one\n * await platform.env.KV.cache.put('key', 'value');\n * await platform.env.DB.insertOne('users', { name: 'John' });\n * await platform.env.STORAGE.put('file.pdf', pdfData);\n * ```\n /\nexport function createRemoteClient(baseUrl: string, tenant: string) {\n const headers = {\n 'Content-Type': 'application/json',\n 'X-Tenant-Id': tenant,\n };\n\n // Create KV namespaces proxy that dynamically creates namespace instances\n const kvProxy = new Proxy({} as Record<string, KvNamespace>, {\n get(_, namespace: string) {\n return new RemoteKvNamespace(baseUrl, namespace, headers);\n }\n });\n\n const db = new RemoteDatabase(baseUrl, headers);\n const storage = new RemoteStorage(baseUrl, headers);\n\n return {\n env: {\n KV: kvProxy,\n DB: db,\n STORAGE: storage,\n }\n };\n}","/\n @fileoverview Maravilla Platform SDK\n * \n * This package provides the main interface for accessing Maravilla runtime services\n * including Key-Value storage and Database operations. It automatically detects the\n * runtime environment and provides the appropriate implementation.\n * \n * ## Environment Detection\n * \n * The SDK automatically detects and adapts to different environments:\n * - Production: Uses native Maravilla runtime APIs\n * - Development: Connects to development server via HTTP\n * - Testing: Can be mocked or use development server\n * \n * ## Key Features\n * \n * - KV Storage: Cloudflare Workers KV-compatible API for key-value operations\n * - Database: MongoDB-style document database operations\n * - Multi-tenancy: Built-in tenant isolation and support\n * - TypeScript: Fully typed APIs with comprehensive JSDoc comments\n * - Development-friendly: Seamless development server integration\n * \n * @example\n * ```typescript\n * import { getPlatform } from '@maravilla/platform';\n * \n * const platform = getPlatform();\n * \n * // KV operations\n * await platform.env.KV.cache.put('user:123', { name: 'John' });\n * const user = await platform.env.KV.cache.get('user:123');\n * \n * // Database operations\n * const userId = await platform.env.DB.insertOne('users', {\n * name: 'John Doe',\n * email: 'john@example.com'\n * });\n * \n * const users = await platform.env.DB.find('users', { active: true });\n * ```\n * \n * @author Maravilla Team\n * @since 1.0.0\n /\n\nimport type { Platform } from './types.js';\nimport { createRemoteClient } from './remote-client.js';\n\nexport from './types.js';\n\n/*\n Global platform instance injected by Maravilla runtime or development tools.\n * This should not be accessed directly - use getPlatform() instead.\n * \n * @internal\n /\n\ndeclare global {\n var __maravilla_platform: Platform \| undefined;\n var platform: Platform \| undefined;\n}\n\nlet cachedPlatform: Platform \| null = null;\n\n/\n Get the platform instance. This will:\n * 1. Check if running in Maravilla runtime (global.platform exists)\n * 2. Check if a platform was injected via vite plugin or hooks\n * 3. Fall back to remote client for development\n * \n * The platform provides access to KV storage and database operations,\n * with automatic environment detection for seamless development and production.\n * \n * @param options - Optional configuration for development mode\n * @param options.devServerUrl - URL of the development server (defaults to MARAVILLA_DEV_SERVER env var or http://localhost:3001)\n * @param options.tenant - Tenant identifier for multi-tenancy (defaults to MARAVILLA_TENANT env var or 'dev-tenant')\n * @returns Platform instance with access to KV and database services\n * \n * @example\n * ```typescript\n * import { getPlatform } from '@maravilla/platform';\n * \n * // Basic usage (auto-detects environment)\n * const platform = getPlatform();\n * \n * // Development with custom server\n * const platform = getPlatform({\n * devServerUrl: 'http://localhost:3001',\n * tenant: 'my-app'\n * });\n * \n * // Use KV storage\n * await platform.env.KV.cache.put('user:123', { name: 'John' });\n * const user = await platform.env.KV.cache.get('user:123');\n * \n * // Use database\n * const userId = await platform.env.DB.insertOne('users', {\n * name: 'John Doe',\n * email: 'john@example.com'\n * });\n * ```\n /\nexport function getPlatform(options?: {\n devServerUrl?: string;\n tenant?: string;\n}): Platform {\n // Return cached if available\n if (cachedPlatform) {\n return cachedPlatform;\n }\n\n // 1. Check if we're in the real Maravilla runtime\n if (typeof globalThis !== 'undefined') {\n // Check for native platform (in production runtime)\n if (globalThis.platform) {\n console.log('[platform] Using native Maravilla platform');\n cachedPlatform = globalThis.platform;\n return cachedPlatform;\n }\n\n // Check for injected platform (from vite plugin or hooks)\n if (globalThis.__maravilla_platform) {\n console.log('[platform] Using injected platform');\n cachedPlatform = globalThis.__maravilla_platform;\n return cachedPlatform;\n }\n }\n\n // 2. Fall back to remote client for development\n const devServerUrl = options?.devServerUrl \|\| process.env.MARAVILLA_DEV_SERVER \|\| 'http://localhost:3001';\n const tenant = options?.tenant \|\| process.env.MARAVILLA_TENANT \|\| 'dev-tenant';\n \n console.log(`[platform] Creating remote client for ${devServerUrl}`);\n cachedPlatform = createRemoteClient(devServerUrl, tenant);\n \n // Cache it globally for other modules\n if (typeof globalThis !== 'undefined') {\n globalThis.__maravilla_platform = cachedPlatform;\n }\n \n return cachedPlatform;\n}\n\n/\n Clear the cached platform instance (useful for testing).\n * \n * This function resets the internal platform cache and clears any globally\n * injected platform instances. Subsequent calls to getPlatform() will\n * re-initialize the platform based on the current environment.\n * \n * @example\n * ```typescript\n * import { clearPlatformCache, getPlatform } from '@maravilla/platform';\n * \n * // In tests, clear cache between test cases\n * afterEach(() => {\n * clearPlatformCache();\n * });\n * \n * // Or when switching between different environments\n * clearPlatformCache();\n * const newPlatform = getPlatform({ devServerUrl: 'http://localhost:3002' });\n * ```\n */\nexport function clearPlatformCache(): void {\n cachedPlatform = null;\n if (typeof globalThis !== 'undefined') {\n globalThis.__maravilla_platform = undefined;\n }\n}"],"mappings":"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","names":[]}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@maravilla-labs/platform",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "Universal platform client for Maravilla runtime",
   "type": "module",
   "main": "./dist/index.js",

package/src/remote-client.ts CHANGED Viewed

@@ -1,4 +1,4 @@
-import type { KvNamespace, KvListResult, Database, DbFindOptions } from './types.js';
+import type { KvNamespace, KvListResult, Database, DbFindOptions, Storage } from './types.js';
 /**
  * Remote KV namespace implementation that communicates with a development server.
@@ -153,6 +153,197 @@ class RemoteDatabase implements Database {
   }
 }
+/**
+ * Remote Storage implementation that communicates with a development server.
+ * This class provides the Storage interface by making HTTP requests to the dev server.
+ *
+ * @internal
+ */
+class RemoteStorage implements Storage {
+  constructor(
+    private baseUrl: string,
+    private headers: Record<string, string>
+  ) {}
+  /**
+   * Internal method for making HTTP requests to the dev server.
+   * Handles error responses and authentication headers.
+   *
+   * @internal
+   */
+  private async fetch(url: string, options: RequestInit = {}) {
+    const response = await fetch(url, {
+      ...options,
+      headers: { ...this.headers, ...options.headers },
+    });
+    if (!response.ok && response.status !== 404) {
+      const error = await response.text();
+      throw new Error(`Platform API error: ${response.status} - ${error}`);
+    }
+    return response;
+  }
+  async generateUploadUrl(key: string, contentType: string, options?: { sizeLimit?: number }): Promise<{
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    expiresIn: number;
+  }> {
+    // For development, return a direct upload URL to the dev server
+    // The dev server supports PUT directly to /api/storage/{key}
+    return {
+      url: `${this.baseUrl}/api/storage/${encodeURIComponent(key)}`,
+      method: 'PUT',
+      headers: {
+        'Content-Type': contentType,
+        ...this.headers, // Include tenant headers
+      },
+      expiresIn: 3600, // 1 hour
+    };
+  }
+  async generateDownloadUrl(key: string, options?: { expiresIn?: number }): Promise<{
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    expiresIn: number;
+  }> {
+    // For development, return a direct download URL to the dev server
+    // In production, this would call the actual storage service for presigned URLs
+    return {
+      url: `${this.baseUrl}/api/storage/${encodeURIComponent(key)}`,
+      method: 'GET',
+      headers: {},
+      expiresIn: options?.expiresIn || 3600, // Default 1 hour
+    };
+  }
+  async get(key: string): Promise<Uint8Array | null> {
+    const response = await this.fetch(`${this.baseUrl}/api/storage/${encodeURIComponent(key)}`);
+    if (response.status === 404) return null;
+    const arrayBuffer = await response.arrayBuffer();
+    return new Uint8Array(arrayBuffer);
+  }
+  async put(key: string, data: Uint8Array | string, metadata?: any): Promise<void> {
+    // Convert string to Uint8Array if needed
+    const bodyData = typeof data === 'string'
+      ? new TextEncoder().encode(data)
+      : data;
+    await this.fetch(`${this.baseUrl}/api/storage/${encodeURIComponent(key)}`, {
+      method: 'PUT',
+      headers: metadata ? { 'X-Metadata': JSON.stringify(metadata) } : {},
+      // Cast because TypeScript's lib.dom.d.ts BodyInit union sometimes misses Uint8Array
+      body: bodyData as any,
+    });
+  }
+  async putStream(key: string, source: any, metadata?: any): Promise<void> {
+    // If it's a Blob we can send directly
+    if (typeof Blob !== 'undefined' && source instanceof Blob) {
+      await this.fetch(`${this.baseUrl}/api/storage/${encodeURIComponent(key)}`, {
+        method: 'PUT',
+        headers: {
+          ...(metadata ? { 'X-Metadata': JSON.stringify(metadata) } : {}),
+          'Content-Type': source.type || 'application/octet-stream'
+        },
+        body: source as any,
+      });
+      return;
+    }
+    // ReadableStream
+    if (source && typeof source.getReader === 'function') {
+      await this.fetch(`${this.baseUrl}/api/storage/${encodeURIComponent(key)}`, {
+        method: 'PUT',
+        headers: metadata ? { 'X-Metadata': JSON.stringify(metadata) } : {},
+        body: source as any,
+      });
+      return;
+    }
+    // Async iterable -> wrap in ReadableStream
+    if (Symbol.asyncIterator in Object(source ?? {})) {
+      const asyncIt = source as AsyncIterable<any>;
+      const stream = new ReadableStream({
+        async pull(controller) {
+          const { value, done } = await asyncIt[Symbol.asyncIterator]().next();
+          if (done) { controller.close(); return; }
+          controller.enqueue(RemoteStorage.normalizeChunk(value));
+        }
+      });
+      await this.fetch(`${this.baseUrl}/api/storage/${encodeURIComponent(key)}`, {
+        method: 'PUT',
+        headers: metadata ? { 'X-Metadata': JSON.stringify(metadata) } : {},
+        body: stream as any,
+      });
+      return;
+    }
+    // Synchronous iterable
+    if (Symbol.iterator in Object(source ?? {})) {
+      const it = (source as Iterable<any>)[Symbol.iterator]();
+      const stream = new ReadableStream({
+        pull(controller) {
+          const res = it.next();
+            if (res.done) { controller.close(); return; }
+            controller.enqueue(RemoteStorage.normalizeChunk(res.value));
+        }
+      });
+      await this.fetch(`${this.baseUrl}/api/storage/${encodeURIComponent(key)}`, {
+        method: 'PUT',
+        headers: metadata ? { 'X-Metadata': JSON.stringify(metadata) } : {},
+        body: stream as any,
+      });
+      return;
+    }
+    // Fallback: primitive/string/Uint8Array/ArrayBuffer
+  await this.put(key, RemoteStorage.normalizeChunk(source), metadata);
+  }
+  private static normalizeChunk(c: any): Uint8Array {
+    if (c == null) return new Uint8Array();
+    if (typeof c === 'string') return new TextEncoder().encode(c);
+    if (c instanceof Uint8Array) return c;
+    if (c instanceof ArrayBuffer) return new Uint8Array(c);
+    if (Array.isArray(c)) return Uint8Array.from(c);
+    throw new Error('Unsupported chunk type in putStream');
+  }
+  async delete(key: string): Promise<void> {
+    await this.fetch(`${this.baseUrl}/api/storage/${encodeURIComponent(key)}`, {
+      method: 'DELETE',
+    });
+  }
+  async list(options?: { prefix?: string; limit?: number }): Promise<Array<{
+    key: string;
+    size: number;
+    lastModified: string;
+    metadata?: any;
+  }>> {
+    const params = new URLSearchParams();
+    if (options?.prefix) params.set('prefix', options.prefix);
+    if (options?.limit) params.set('limit', options.limit.toString());
+    const response = await this.fetch(`${this.baseUrl}/api/storage?${params}`);
+    return response.json();
+  }
+  async getMetadata(key: string): Promise<{
+    size: number;
+    contentType?: string;
+    lastModified: string;
+    metadata?: any;
+  } | null> {
+    const response = await this.fetch(`${this.baseUrl}/api/storage/${encodeURIComponent(key)}/metadata`);
+    if (response.status === 404) return null;
+    return response.json();
+  }
+}
 /**
  * Create a remote platform client for development environments.
  *
@@ -174,6 +365,7 @@ class RemoteDatabase implements Database {
  * // The returned platform works the same as the native one
  * await platform.env.KV.cache.put('key', 'value');
  * await platform.env.DB.insertOne('users', { name: 'John' });
+ * await platform.env.STORAGE.put('file.pdf', pdfData);
  * ```
  */
 export function createRemoteClient(baseUrl: string, tenant: string) {
@@ -190,11 +382,13 @@ export function createRemoteClient(baseUrl: string, tenant: string) {
   });
   const db = new RemoteDatabase(baseUrl, headers);
+  const storage = new RemoteStorage(baseUrl, headers);
   return {
     env: {
       KV: kvProxy,
       DB: db,
+      STORAGE: storage,
     }
   };
 }

package/src/types.ts CHANGED Viewed

@@ -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;
 }
 /**