@maravilla-labs/platform 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,426 @@
+/**
+ * Key-Value namespace interface for storing and retrieving data.
+ * Similar to Cloudflare Workers KV API for familiar developer experience.
+ *
+ * @example
+ * ```typescript
+ * const platform = getPlatform();
+ * const userKv = platform.env.KV.users;
+ *
+ * // Store user data
+ * await userKv.put('user:123', { name: 'John', email: 'john@example.com' });
+ *
+ * // Retrieve user data
+ * const user = await userKv.get('user:123');
+ *
+ * // List all user keys
+ * const result = await userKv.list({ prefix: 'user:' });
+ * ```
+ */
+interface KvNamespace {
+    /**
+     * Retrieve a value from the KV namespace.
+     *
+     * @param key - The key to retrieve
+     * @returns Promise that resolves to the stored value, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const user = await kv.get('user:123');
+     * if (user) {
+     *   console.log(`Welcome back, ${user.name}!`);
+     * }
+     * ```
+     */
+    get(key: string): Promise<any>;
+    /**
+     * Store a value in the KV namespace.
+     *
+     * @param key - The key to store under
+     * @param value - The value to store (will be JSON serialized)
+     * @param options - Optional configuration
+     * @param options.expirationTtl - Time to live in seconds before the key expires
+     * @returns Promise that resolves when the operation completes
+     *
+     * @example
+     * ```typescript
+     * // Store permanent data
+     * await kv.put('config:theme', { dark: true });
+     *
+     * // Store temporary data (expires in 1 hour)
+     * await kv.put('session:abc123', sessionData, { expirationTtl: 3600 });
+     * ```
+     */
+    put(key: string, value: any, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+    /**
+     * Delete a key from the KV namespace.
+     *
+     * @param key - The key to delete
+     * @returns Promise that resolves when the operation completes
+     *
+     * @example
+     * ```typescript
+     * await kv.delete('user:123');
+     * ```
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * List keys in the KV namespace with optional filtering.
+     *
+     * @param options - Optional filtering and pagination options
+     * @param options.prefix - Only return keys that start with this prefix
+     * @param options.limit - Maximum number of keys to return (default varies by implementation)
+     * @param options.cursor - Pagination cursor from previous list call
+     * @returns Promise that resolves to a list result with keys and pagination info
+     *
+     * @example
+     * ```typescript
+     * // List all keys
+     * const all = await kv.list();
+     *
+     * // List user keys only
+     * const users = await kv.list({ prefix: 'user:' });
+     *
+     * // Paginated listing
+     * const page1 = await kv.list({ limit: 10 });
+     * if (!page1.list_complete) {
+     *   const page2 = await kv.list({ limit: 10, cursor: page1.cursor });
+     * }
+     * ```
+     */
+    list(options?: {
+        prefix?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<KvListResult>;
+}
+/**
+ * Result object returned by KV list operations.
+ * Contains the matching keys and pagination information.
+ */
+interface KvListResult {
+    /** Array of matching keys with their metadata */
+    keys: Array<{
+        /** The key name */
+        name: string;
+        /** Unix timestamp when the key expires (if set) */
+        expiration?: number;
+        /** Custom metadata associated with the key */
+        metadata?: any;
+    }>;
+    /** Whether this result contains all matching keys (true) or more results are available (false) */
+    list_complete: boolean;
+    /** Pagination cursor to use for the next list call, if list_complete is false */
+    cursor?: string;
+}
+/**
+ * Database interface for document-based operations.
+ * Provides MongoDB-like API for storing and querying structured data.
+ *
+ * @example
+ * ```typescript
+ * const platform = getPlatform();
+ * const db = platform.env.DB;
+ *
+ * // Insert a new user
+ * const userId = await db.insertOne('users', {
+ *   name: 'John Doe',
+ *   email: 'john@example.com',
+ *   createdAt: new Date()
+ * });
+ *
+ * // Find users by criteria
+ * const activeUsers = await db.find('users', { active: true });
+ *
+ * // Update a user
+ * await db.updateOne('users',
+ *   { _id: userId },
+ *   { $set: { lastLogin: new Date() } }
+ * );
+ * ```
+ */
+interface Database {
+    /**
+     * Find multiple documents in a collection.
+     *
+     * @param collection - The collection name
+     * @param filter - Query filter object (MongoDB-style)
+     * @param options - Optional query options for pagination and sorting
+     * @returns Promise that resolves to an array of matching documents
+     *
+     * @example
+     * ```typescript
+     * // Find all active users
+     * const users = await db.find('users', { active: true });
+     *
+     * // Find with pagination and sorting
+     * const recentPosts = await db.find('posts',
+     *   { published: true },
+     *   { limit: 10, sort: { createdAt: -1 } }
+     * );
+     * ```
+     */
+    find(collection: string, filter?: any, options?: DbFindOptions): Promise<any[]>;
+    /**
+     * Find a single document in a collection.
+     *
+     * @param collection - The collection name
+     * @param filter - Query filter object to match the document
+     * @returns Promise that resolves to the matching document, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const user = await db.findOne('users', { email: 'john@example.com' });
+     * if (user) {
+     *   console.log(`Found user: ${user.name}`);
+     * }
+     * ```
+     */
+    findOne(collection: string, filter: any): Promise<any | null>;
+    /**
+     * Insert a single document into a collection.
+     *
+     * @param collection - The collection name
+     * @param document - The document to insert
+     * @returns Promise that resolves to the ID of the inserted document
+     *
+     * @example
+     * ```typescript
+     * const postId = await db.insertOne('posts', {
+     *   title: 'Hello World',
+     *   content: 'This is my first post',
+     *   author: 'john@example.com',
+     *   createdAt: new Date()
+     * });
+     * ```
+     */
+    insertOne(collection: string, document: any): Promise<string>;
+    /**
+     * Update a single document in a collection.
+     *
+     * @param collection - The collection name
+     * @param filter - Query filter to match the document to update
+     * @param update - Update operations (MongoDB-style with $set, $inc, etc.)
+     * @returns Promise that resolves to an object with the number of modified documents
+     *
+     * @example
+     * ```typescript
+     * const result = await db.updateOne('users',
+     *   { email: 'john@example.com' },
+     *   { $set: { lastLogin: new Date() }, $inc: { loginCount: 1 } }
+     * );
+     * console.log(`Modified ${result.modified} documents`);
+     * ```
+     */
+    updateOne(collection: string, filter: any, update: any): Promise<{
+        modified: number;
+    }>;
+    /**
+     * Delete a single document from a collection.
+     *
+     * @param collection - The collection name
+     * @param filter - Query filter to match the document to delete
+     * @returns Promise that resolves to an object with the number of deleted documents
+     *
+     * @example
+     * ```typescript
+     * const result = await db.deleteOne('posts', { _id: postId });
+     * console.log(`Deleted ${result.deleted} documents`);
+     * ```
+     */
+    deleteOne(collection: string, filter: any): Promise<{
+        deleted: number;
+    }>;
+    /**
+     * Delete multiple documents from a collection.
+     *
+     * @param collection - The collection name
+     * @param filter - Query filter to match documents to delete
+     * @returns Promise that resolves to an object with the number of deleted documents
+     *
+     * @example
+     * ```typescript
+     * // Delete all inactive users
+     * const result = await db.deleteMany('users', { active: false });
+     * console.log(`Deleted ${result.deleted} inactive users`);
+     * ```
+     */
+    deleteMany(collection: string, filter: any): Promise<{
+        deleted: number;
+    }>;
+}
+/**
+ * Options for database find operations.
+ * Provides MongoDB-style query options for pagination, sorting, and limiting results.
+ */
+interface DbFindOptions {
+    /** Maximum number of documents to return */
+    limit?: number;
+    /** Number of documents to skip (for pagination) */
+    skip?: number;
+    /** Sort order specification (MongoDB-style: { field: 1 } for ascending, { field: -1 } for descending) */
+    sort?: any;
+}
+/**
+ * Platform environment containing all available services.
+ * This is the main interface for accessing KV storage and database operations.
+ */
+interface PlatformEnv {
+    /**
+     * Key-Value storage namespaces. Access different KV namespaces by property name.
+     *
+     * @example
+     * ```typescript
+     * const userCache = platform.env.KV.users;
+     * const sessionStore = platform.env.KV.sessions;
+     * ```
+     */
+    KV: Record<string, KvNamespace>;
+    /** Database interface for document operations */
+    DB: Database;
+}
+/**
+ * Main platform interface providing access to all Maravilla runtime services.
+ * This is the primary interface developers will interact with.
+ *
+ * @example
+ * ```typescript
+ * import { getPlatform } from '@maravilla/platform';
+ *
+ * const platform = getPlatform();
+ *
+ * // Use KV storage
+ * await platform.env.KV.cache.put('key', 'value');
+ *
+ * // Use database
+ * await platform.env.DB.insertOne('users', { name: 'John' });
+ * ```
+ */
+interface Platform {
+    /** Environment containing all available platform services */
+    env: PlatformEnv;
+}
+
+/**
+ * @fileoverview Maravilla Platform SDK
+ *
+ * This package provides the main interface for accessing Maravilla runtime services
+ * including Key-Value storage and Database operations. It automatically detects the
+ * runtime environment and provides the appropriate implementation.
+ *
+ * ## Environment Detection
+ *
+ * The SDK automatically detects and adapts to different environments:
+ * - **Production**: Uses native Maravilla runtime APIs
+ * - **Development**: Connects to development server via HTTP
+ * - **Testing**: Can be mocked or use development server
+ *
+ * ## Key Features
+ *
+ * - **KV Storage**: Cloudflare Workers KV-compatible API for key-value operations
+ * - **Database**: MongoDB-style document database operations
+ * - **Multi-tenancy**: Built-in tenant isolation and support
+ * - **TypeScript**: Fully typed APIs with comprehensive JSDoc comments
+ * - **Development-friendly**: Seamless development server integration
+ *
+ * @example
+ * ```typescript
+ * import { getPlatform } from '@maravilla/platform';
+ *
+ * const platform = getPlatform();
+ *
+ * // KV operations
+ * await platform.env.KV.cache.put('user:123', { name: 'John' });
+ * const user = await platform.env.KV.cache.get('user:123');
+ *
+ * // Database operations
+ * const userId = await platform.env.DB.insertOne('users', {
+ *   name: 'John Doe',
+ *   email: 'john@example.com'
+ * });
+ *
+ * const users = await platform.env.DB.find('users', { active: true });
+ * ```
+ *
+ * @author Maravilla Team
+ * @since 1.0.0
+ */
+
+/**
+ * Global platform instance injected by Maravilla runtime or development tools.
+ * This should not be accessed directly - use getPlatform() instead.
+ *
+ * @internal
+ */
+declare global {
+    var __maravilla_platform: Platform | undefined;
+    var platform: Platform | undefined;
+}
+/**
+ * Get the platform instance. This will:
+ * 1. Check if running in Maravilla runtime (global.platform exists)
+ * 2. Check if a platform was injected via vite plugin or hooks
+ * 3. Fall back to remote client for development
+ *
+ * The platform provides access to KV storage and database operations,
+ * with automatic environment detection for seamless development and production.
+ *
+ * @param options - Optional configuration for development mode
+ * @param options.devServerUrl - URL of the development server (defaults to MARAVILLA_DEV_SERVER env var or http://localhost:3001)
+ * @param options.tenant - Tenant identifier for multi-tenancy (defaults to MARAVILLA_TENANT env var or 'dev-tenant')
+ * @returns Platform instance with access to KV and database services
+ *
+ * @example
+ * ```typescript
+ * import { getPlatform } from '@maravilla/platform';
+ *
+ * // Basic usage (auto-detects environment)
+ * const platform = getPlatform();
+ *
+ * // Development with custom server
+ * const platform = getPlatform({
+ *   devServerUrl: 'http://localhost:3001',
+ *   tenant: 'my-app'
+ * });
+ *
+ * // Use KV storage
+ * await platform.env.KV.cache.put('user:123', { name: 'John' });
+ * const user = await platform.env.KV.cache.get('user:123');
+ *
+ * // Use database
+ * const userId = await platform.env.DB.insertOne('users', {
+ *   name: 'John Doe',
+ *   email: 'john@example.com'
+ * });
+ * ```
+ */
+declare function getPlatform(options?: {
+    devServerUrl?: string;
+    tenant?: string;
+}): Platform;
+/**
+ * Clear the cached platform instance (useful for testing).
+ *
+ * This function resets the internal platform cache and clears any globally
+ * injected platform instances. Subsequent calls to getPlatform() will
+ * re-initialize the platform based on the current environment.
+ *
+ * @example
+ * ```typescript
+ * import { clearPlatformCache, getPlatform } from '@maravilla/platform';
+ *
+ * // In tests, clear cache between test cases
+ * afterEach(() => {
+ *   clearPlatformCache();
+ * });
+ *
+ * // Or when switching between different environments
+ * clearPlatformCache();
+ * const newPlatform = getPlatform({ devServerUrl: 'http://localhost:3002' });
+ * ```
+ */
+declare function clearPlatformCache(): void;
+
+export { type Database, type DbFindOptions, type KvListResult, type KvNamespace, type Platform, type PlatformEnv, clearPlatformCache, getPlatform };

package/dist/index.js

@@ -0,0 +1,178 @@
+// src/remote-client.ts
+var RemoteKvNamespace = class {
+  constructor(baseUrl, namespace, headers) {
+    this.baseUrl = baseUrl;
+    this.namespace = namespace;
+    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 get(key) {
+    const response = await this.fetch(`${this.baseUrl}/api/kv/${this.namespace}/${key}`);
+    if (response.status === 404) return null;
+    return response.json();
+  }
+  async put(key, value, options) {
+    const headers = {};
+    if (options?.expirationTtl) {
+      headers["X-TTL"] = options.expirationTtl.toString();
+    }
+    await this.fetch(`${this.baseUrl}/api/kv/${this.namespace}/${key}`, {
+      method: "PUT",
+      headers,
+      body: JSON.stringify(value)
+    });
+  }
+  async delete(key) {
+    await this.fetch(`${this.baseUrl}/api/kv/${this.namespace}/${key}`, {
+      method: "DELETE"
+    });
+  }
+  async list(options) {
+    const response = await this.fetch(`${this.baseUrl}/api/kv/${this.namespace}`, {
+      method: "POST",
+      body: JSON.stringify(options || {})
+    });
+    const data = await response.json();
+    return {
+      keys: data.result || [],
+      list_complete: !data.result_info?.cursor,
+      cursor: data.result_info?.cursor
+    };
+  }
+};
+var RemoteDatabase = class {
+  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 find(collection, filter = {}, options = {}) {
+    const response = await this.fetch(`${this.baseUrl}/api/db/${collection}`, {
+      method: "POST",
+      body: JSON.stringify({ filter, options })
+    });
+    return response.json();
+  }
+  async findOne(collection, filter) {
+    const response = await this.fetch(`${this.baseUrl}/api/db/${collection}/findOne`, {
+      method: "POST",
+      body: JSON.stringify(filter)
+    });
+    if (response.status === 404) return null;
+    return response.json();
+  }
+  async insertOne(collection, document) {
+    const response = await this.fetch(`${this.baseUrl}/api/db/${collection}`, {
+      method: "PUT",
+      body: JSON.stringify(document)
+    });
+    const result = await response.json();
+    return result.id;
+  }
+  async updateOne(collection, filter, update) {
+    const response = await this.fetch(`${this.baseUrl}/api/db/${collection}/update`, {
+      method: "POST",
+      body: JSON.stringify({ filter, update })
+    });
+    return response.json();
+  }
+  async deleteOne(collection, filter) {
+    const response = await this.fetch(`${this.baseUrl}/api/db/${collection}/delete`, {
+      method: "DELETE",
+      body: JSON.stringify(filter)
+    });
+    return response.json();
+  }
+  async deleteMany(collection, filter) {
+    return this.deleteOne(collection, filter);
+  }
+};
+function createRemoteClient(baseUrl, tenant) {
+  const headers = {
+    "Content-Type": "application/json",
+    "X-Tenant-Id": tenant
+  };
+  const kvProxy = new Proxy({}, {
+    get(_, namespace) {
+      return new RemoteKvNamespace(baseUrl, namespace, headers);
+    }
+  });
+  const db = new RemoteDatabase(baseUrl, headers);
+  return {
+    env: {
+      KV: kvProxy,
+      DB: db
+    }
+  };
+}
+
+// src/index.ts
+var cachedPlatform = null;
+function getPlatform(options) {
+  if (cachedPlatform) {
+    return cachedPlatform;
+  }
+  if (typeof globalThis !== "undefined") {
+    if (globalThis.platform) {
+      console.log("[platform] Using native Maravilla platform");
+      cachedPlatform = globalThis.platform;
+      return cachedPlatform;
+    }
+    if (globalThis.__maravilla_platform) {
+      console.log("[platform] Using injected platform");
+      cachedPlatform = globalThis.__maravilla_platform;
+      return cachedPlatform;
+    }
+  }
+  const devServerUrl = options?.devServerUrl || process.env.MARAVILLA_DEV_SERVER || "http://localhost:3001";
+  const tenant = options?.tenant || process.env.MARAVILLA_TENANT || "dev-tenant";
+  console.log(`[platform] Creating remote client for ${devServerUrl}`);
+  cachedPlatform = createRemoteClient(devServerUrl, tenant);
+  if (typeof globalThis !== "undefined") {
+    globalThis.__maravilla_platform = cachedPlatform;
+  }
+  return cachedPlatform;
+}
+function clearPlatformCache() {
+  cachedPlatform = null;
+  if (typeof globalThis !== "undefined") {
+    globalThis.__maravilla_platform = void 0;
+  }
+}
+export {
+  clearPlatformCache,
+  getPlatform
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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":[]}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@maravilla-labs/platform",
+  "version": "0.1.0",
+  "description": "Universal platform client for Maravilla runtime",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.6",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2"
+  },
+  "dependencies": {},
+  "publishConfig": {
+    "access": "public"
+  }
+}