@maravilla-labs/platform 0.1.18 → 0.1.21

package/dist/index.d.ts

@@ -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$1 {
+    /**
+     * 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$1;
 }
 /**
  * Main platform interface providing access to all Maravilla runtime services.
@@ -303,6 +530,50 @@ interface Platform {
     env: PlatformEnv;
 }
 
+interface RenEvent {
+    t: string;
+    r: string;
+    k?: string;
+    v?: string;
+    ts?: number;
+    src?: string;
+    ns?: string;
+    [extra: string]: any;
+}
+interface RenClientOptions {
+    endpoint?: string;
+    subscriptions?: string[];
+    clientId?: string;
+    autoReconnect?: boolean;
+    maxBackoffMs?: number;
+    debug?: boolean;
+}
+type Listener = (event: RenEvent) => void;
+declare class RenClient {
+    private endpoint;
+    private subs;
+    private clientId;
+    private listeners;
+    private es;
+    private closed;
+    private attempt;
+    private autoReconnect;
+    private maxBackoff;
+    private debug;
+    constructor(opts?: RenClientOptions);
+    private detectEndpoint;
+    private log;
+    private buildUrl;
+    private connect;
+    on(listener: Listener): () => void;
+    getClientId(): string;
+    close(): void;
+}
+declare function getOrCreateClientId(storage?: Storage): string;
+declare function renFetch(input: string | URL | Request, init?: RequestInit, clientId?: string): Promise<Response>;
+declare function storageUpload(path: string, file: Blob | File, clientId?: string): Promise<any>;
+declare function storageDelete(path: string, clientId?: string): Promise<any>;
+
 /**
  * @fileoverview Maravilla Platform SDK
  *
@@ -423,4 +694,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, RenClient, type RenClientOptions, type RenEvent, type Storage$1 as Storage, type StoragePutStreamSource, clearPlatformCache, getOrCreateClientId, getPlatform, renFetch, storageDelete, storageUpload };

package/dist/index.js

@@ -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,14 +275,181 @@ 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
     }
   };
 }
 
+// src/ren.ts
+var RenClient = class {
+  endpoint;
+  subs;
+  clientId;
+  listeners = /* @__PURE__ */ new Set();
+  es = null;
+  closed = false;
+  attempt = 0;
+  autoReconnect;
+  maxBackoff;
+  debug;
+  constructor(opts = {}) {
+    this.endpoint = opts.endpoint || this.detectEndpoint();
+    this.subs = opts.subscriptions && opts.subscriptions.length ? opts.subscriptions : ["*"];
+    this.clientId = opts.clientId || getOrCreateClientId();
+    this.autoReconnect = opts.autoReconnect !== false;
+    this.maxBackoff = opts.maxBackoffMs ?? 15e3;
+    this.debug = !!opts.debug || typeof localStorage !== "undefined" && localStorage.getItem("REN_DEBUG") === "1";
+    this.connect();
+  }
+  detectEndpoint() {
+    console.log("[REN detectEndpoint] Starting detection...");
+    console.log("[REN detectEndpoint] globalThis:", typeof globalThis);
+    console.log("[REN detectEndpoint] globalThis.platform:", globalThis?.platform);
+    console.log("[REN detectEndpoint] globalThis.__maravilla_platform:", globalThis?.__maravilla_platform);
+    console.log("[REN detectEndpoint] window:", typeof window);
+    console.log("[REN detectEndpoint] window.location:", typeof window !== "undefined" ? window.location.href : "N/A");
+    if (typeof globalThis !== "undefined" && globalThis.platform) {
+      console.log("[REN detectEndpoint] Detected production runtime, using relative endpoint");
+      return "/api/maravilla/ren";
+    }
+    if (typeof window !== "undefined" && window.location.port === "5173") {
+      const devServerUrl = `http://${window.location.hostname}:3001`;
+      console.log("[REN detectEndpoint] Detected Vite dev server (port 5173), using dev server:", devServerUrl);
+      return `${devServerUrl}/api/maravilla/ren`;
+    }
+    if (typeof globalThis !== "undefined" && globalThis.__maravilla_platform) {
+      let devServerUrl = "http://localhost:3001";
+      if (typeof window !== "undefined" && window.location.hostname !== "localhost") {
+        devServerUrl = `http://${window.location.hostname}:3001`;
+      }
+      console.log("[REN detectEndpoint] Detected injected platform, using dev server:", devServerUrl);
+      return `${devServerUrl}/api/maravilla/ren`;
+    }
+    console.log("[REN detectEndpoint] Using default relative endpoint (preview/production mode)");
+    return "/api/maravilla/ren";
+  }
+  log(...args) {
+    if (this.debug) console.debug("[RenClient]", ...args);
+  }
+  buildUrl() {
+    const s = this.subs.length === 1 && this.subs[0] === "*" ? "*" : this.subs.join(",");
+    const qs = new URLSearchParams({ cid: this.clientId, s });
+    return `${this.endpoint}?${qs.toString()}`;
+  }
+  connect() {
+    const url = this.buildUrl();
+    this.log("connecting", { url });
+    this.es = new EventSource(url);
+    this.closed = false;
+    const forward = (e) => {
+      try {
+        const evt = JSON.parse(e.data);
+        this.log("event", evt);
+        this.listeners.forEach((l) => l(evt));
+      } catch (err) {
+        this.log("malformed event data", e.data, err);
+      }
+    };
+    this.es.onmessage = forward;
+    const knownEventTypes = [
+      // Database events
+      "db.document.created",
+      "db.document.updated",
+      "db.document.deleted",
+      // KV events
+      "kv.put",
+      "kv.delete",
+      "kv.expired",
+      // Storage events
+      "storage.object.created",
+      "storage.object.updated",
+      "storage.object.deleted",
+      // Runtime events
+      "runtime.snapshot.ready",
+      "runtime.worker.started",
+      "runtime.worker.stopped",
+      // Meta events
+      "ren.meta"
+    ];
+    knownEventTypes.forEach((k) => this.es?.addEventListener(k, forward));
+    this.es.onerror = (ev) => {
+      this.log("error", ev);
+      if (this.closed) return;
+      this.es?.close();
+      if (!this.autoReconnect) return;
+      const delay = Math.min(1e3 * Math.pow(2, this.attempt++), this.maxBackoff);
+      this.log("reconnecting in", delay, "ms");
+      setTimeout(() => this.connect(), delay);
+    };
+    this.es.onopen = () => {
+      this.attempt = 0;
+      this.log("open");
+    };
+  }
+  on(listener) {
+    this.listeners.add(listener);
+    this.log("listener added; total", this.listeners.size);
+    return () => {
+      this.listeners.delete(listener);
+      this.log("listener removed; total", this.listeners.size);
+    };
+  }
+  getClientId() {
+    return this.clientId;
+  }
+  close() {
+    this.closed = true;
+    this.es?.close();
+    this.log("closed");
+  }
+};
+function getOrCreateClientId(storage) {
+  if (!storage) {
+    storage = typeof window !== "undefined" && window.localStorage ? window.localStorage : typeof globalThis !== "undefined" && globalThis.localStorage ? globalThis.localStorage : void 0;
+    if (!storage) {
+      return globalThis.crypto?.randomUUID?.() || randomFallback();
+    }
+  }
+  const key = "maravillaClientId";
+  let id = storage.getItem(key);
+  if (!id) {
+    id = globalThis.crypto?.randomUUID?.() || randomFallback();
+    try {
+      storage.setItem(key, id);
+    } catch {
+    }
+  }
+  return id;
+}
+function randomFallback() {
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    const v = c === "x" ? r : r & 3 | 8;
+    return v.toString(16);
+  });
+}
+async function renFetch(input, init = {}, clientId) {
+  const cid = clientId || getOrCreateClientId();
+  const headers = new Headers(init.headers || {});
+  headers.set("X-Ren-Client", cid);
+  return fetch(input, { ...init, headers });
+}
+async function storageUpload(path, file, clientId) {
+  const res = await renFetch(`/api/storage/upload?path=${encodeURIComponent(path)}`, { method: "POST", body: file }, clientId);
+  if (!res.ok) throw new Error("upload failed");
+  return res.json().catch(() => ({}));
+}
+async function storageDelete(path, clientId) {
+  const res = await renFetch(`/api/storage/delete?path=${encodeURIComponent(path)}`, { method: "DELETE" }, clientId);
+  if (!res.ok) throw new Error("delete failed");
+  return res.json().catch(() => ({}));
+}
+
 // src/index.ts
 var cachedPlatform = null;
 function getPlatform(options) {
@@ -172,7 +484,12 @@ function clearPlatformCache() {
   }
 }
 export {
+  RenClient,
   clearPlatformCache,
-  getPlatform
+  getOrCreateClientId,
+  getPlatform,
+  renFetch,
+  storageDelete,
+  storageUpload
 };
 //# sourceMappingURL=index.js.map