@inneropen/marvin-sdk 2.0.1 → 3.0.0

package/dist/index.cjs

@@ -27,24 +27,117 @@ __export(config_exports, {
   validateConfig: () => validateConfig
 });
 function validateConfig(config) {
+  const receivedKeys = Object.keys(config).join(", ");
   if (!config.apiUrl) {
-    throw new Error("MARVIN_API_URL is required");
+    throw new Error(
+      `Missing required config: 'apiUrl'
+
+The API URL is the base URL of your Marvin server.
+
+Examples:
+  - Production: https://marvin.example.com
+  - Development: http://localhost:8080
+
+Solutions:
+  1. Set environment variable: MARVIN_API_URL=https://marvin.example.com
+  2. Pass directly: createMarvinClient({ apiUrl: 'https://marvin.example.com' })
+
+Received config keys: ${receivedKeys || "(none)"}`
+    );
   }
   if (!config.siteClientToken) {
-    throw new Error("MARVIN_SITE_CLIENT_TOKEN is required");
+    throw new Error(
+      `Missing required config: 'siteClientToken'
+
+The site client token provides read-only access to published content.
+
+How to get it:
+  1. Log into Marvin admin panel
+  2. Navigate to: Settings \u2192 API Clients
+  3. Copy the token for your workspace
+
+Examples:
+  - site_client_abc123xyz
+  - sc_1234567890abcdef
+
+Solutions:
+  1. Set environment variable: MARVIN_SITE_CLIENT_TOKEN=site_client_abc123
+  2. Pass directly: createMarvinClient({ siteClientToken: 'site_client_abc123' })
+
+Received config keys: ${receivedKeys}`
+    );
   }
   if (!config.workspaceSlug) {
-    throw new Error("MARVIN_WORKSPACE_SLUG is required");
+    throw new Error(
+      `Missing required config: 'workspaceSlug'
+
+The workspace slug identifies which workspace to access.
+
+Examples:
+  - my-blog
+  - company-website
+  - acme-corp
+
+How to find it:
+  1. Check your workspace URL: https://marvin.example.com/workspace/[slug]
+  2. Or find it in: Settings \u2192 General \u2192 Workspace Slug
+
+Solutions:
+  1. Set environment variable: MARVIN_WORKSPACE_SLUG=my-blog
+  2. Pass directly: createMarvinClient({ workspaceSlug: 'my-blog' })
+
+Received config keys: ${receivedKeys}`
+    );
+  }
+  if (config.apiUrl) {
+    try {
+      new URL(config.apiUrl);
+    } catch {
+      throw new Error(
+        `Invalid 'apiUrl' format: "${config.apiUrl}"
+
+The API URL must be a valid HTTP or HTTPS URL.
+
+Valid examples:
+  \u2713 https://marvin.example.com
+  \u2713 http://localhost:8080
+  \u2713 https://api.marvin.io
+
+Invalid examples:
+  \u2717 marvin.example.com (missing protocol)
+  \u2717 ftp://marvin.example.com (wrong protocol)
+  \u2717 /api (not a full URL)`
+      );
+    }
+    const url = new URL(config.apiUrl);
+    if (!["http:", "https:"].includes(url.protocol)) {
+      throw new Error(
+        `Invalid 'apiUrl' protocol: "${url.protocol}"
+
+Only HTTP and HTTPS protocols are supported.
+
+Your URL: ${config.apiUrl}
+Change to: ${config.apiUrl.replace(url.protocol, "https:")}`
+      );
+    }
+  }
+}
+function getEnv(key) {
+  if (typeof process !== "undefined" && process.env) {
+    return process.env[key];
   }
+  return void 0;
 }
 function createConfigFromEnv(overrides) {
   return {
-    apiUrl: overrides?.apiUrl || process.env.MARVIN_API_URL || "",
-    siteClientToken: overrides?.siteClientToken || process.env.MARVIN_SITE_CLIENT_TOKEN || "",
-    workspaceSlug: overrides?.workspaceSlug || process.env.MARVIN_WORKSPACE_SLUG || "",
+    apiUrl: overrides?.apiUrl || getEnv("MARVIN_API_URL") || "",
+    siteClientToken: overrides?.siteClientToken || getEnv("MARVIN_SITE_CLIENT_TOKEN") || "",
+    workspaceSlug: overrides?.workspaceSlug || getEnv("MARVIN_WORKSPACE_SLUG") || "",
     autoInitialize: overrides?.autoInitialize ?? false,
-    cacheDuration: overrides?.cacheDuration ?? 5 * 60 * 1e3
+    cacheDuration: overrides?.cacheDuration ?? 5 * 60 * 1e3,
     // 5 minutes
+    debug: overrides?.debug ?? getEnv("MARVIN_DEBUG") === "true",
+    logger: overrides?.logger ?? console
   };
 }
 var init_config = __esm({
@@ -54,7 +147,7 @@ var init_config = __esm({
 });
 
 // src/core/errors/MarvinError.ts
-var MarvinError, MarvinApiError, MarvinAuthError, MarvinConfigError, MarvinValidationError;
+var MarvinError, MarvinApiError, MarvinAuthError, MarvinConfigError, MarvinValidationError, MarvinNotFoundError, MarvinNetworkError, MarvinServerError;
 var init_MarvinError = __esm({
   "src/core/errors/MarvinError.ts"() {
     "use strict";
@@ -110,6 +203,33 @@ ${body}` : ""}`;
       }
       field;
     };
+    MarvinNotFoundError = class _MarvinNotFoundError extends MarvinError {
+      constructor(message, endpoint) {
+        super(message, "NOT_FOUND", 404);
+        this.endpoint = endpoint;
+        this.name = "MarvinNotFoundError";
+        Object.setPrototypeOf(this, _MarvinNotFoundError.prototype);
+      }
+      endpoint;
+    };
+    MarvinNetworkError = class _MarvinNetworkError extends MarvinError {
+      constructor(message, originalError) {
+        super(message, "NETWORK_ERROR");
+        this.originalError = originalError;
+        this.name = "MarvinNetworkError";
+        Object.setPrototypeOf(this, _MarvinNetworkError.prototype);
+      }
+      originalError;
+    };
+    MarvinServerError = class _MarvinServerError extends MarvinError {
+      constructor(message, statusCode, endpoint) {
+        super(message, "SERVER_ERROR", statusCode);
+        this.endpoint = endpoint;
+        this.name = "MarvinServerError";
+        Object.setPrototypeOf(this, _MarvinServerError.prototype);
+      }
+      endpoint;
+    };
   }
 });
 
@@ -133,12 +253,47 @@ var init_HttpClient = __esm({
       defaultHeaders;
       credentials;
       timeout;
+      debug;
+      retryConfig;
+      logger;
       constructor(config) {
         this.baseUrl = config.baseUrl;
         this.auth = config.auth;
         this.defaultHeaders = config.defaultHeaders || {};
         this.credentials = config.credentials || "same-origin";
-        this.timeout = config.timeout || 3e4;
+        const MAX_TIMEOUT = 12e4;
+        this.timeout = Math.min(config.timeout || 3e4, MAX_TIMEOUT);
+        this.debug = config.debug ?? false;
+        this.logger = config.logger ?? console;
+        this.retryConfig = {
+          maxRetries: config.retry?.maxRetries ?? 3,
+          initialDelay: config.retry?.initialDelay ?? 1e3,
+          maxDelay: config.retry?.maxDelay ?? 1e4,
+          retryableStatuses: config.retry?.retryableStatuses ?? [408, 429, 500, 502, 503, 504]
+        };
+      }
+      /**
+       * Validate path parameter to prevent path traversal attacks
+       */
+      validatePathParam(param, paramName = "parameter") {
+        if (typeof param === "number") {
+          return String(param);
+        }
+        if (!param || typeof param !== "string") {
+          throw new MarvinValidationError(`Invalid ${paramName}: must be a non-empty string or number`);
+        }
+        if (param.includes("..") || param.includes("/") || param.includes("\\")) {
+          throw new MarvinValidationError(
+            `Invalid ${paramName}: cannot contain path traversal characters (.. / \\)`
+          );
+        }
+        if (param.includes("\0")) {
+          throw new MarvinValidationError(`Invalid ${paramName}: cannot contain null bytes`);
+        }
+        if (param.length > 255) {
+          throw new MarvinValidationError(`Invalid ${paramName}: exceeds maximum length of 255 characters`);
+        }
+        return param;
       }
       /**
        * Build full URL from endpoint
@@ -172,14 +327,78 @@ var init_HttpClient = __esm({
         return filtered.length > 0 ? `?${filtered.join("&")}` : "";
       }
       /**
-       * Perform HTTP request
+       * Sanitize data for logging by redacting sensitive fields
+       */
+      sanitizeForLogging(data) {
+        if (!data || typeof data !== "object") {
+          return data;
+        }
+        const sensitiveFields = [
+          "token",
+          "access_token",
+          "refresh_token",
+          "password",
+          "secret",
+          "apiKey",
+          "api_key",
+          "bearer",
+          "authorization",
+          "csrf_token",
+          "session",
+          "cookie"
+        ];
+        const sanitize = (obj) => {
+          const sanitized = {};
+          for (const [key, value] of Object.entries(obj)) {
+            const keyLower = key.toLowerCase();
+            const isSensitive = sensitiveFields.some((field) => keyLower.includes(field));
+            if (isSensitive) {
+              sanitized[key] = "[REDACTED]";
+            } else if (value && typeof value === "object" && !Array.isArray(value)) {
+              sanitized[key] = sanitize(value);
+            } else if (Array.isArray(value)) {
+              sanitized[key] = value.map(
+                (item) => item && typeof item === "object" ? sanitize(item) : item
+              );
+            } else {
+              sanitized[key] = value;
+            }
+          }
+          return sanitized;
+        };
+        if (Array.isArray(data)) {
+          return data.map(
+            (item) => item && typeof item === "object" ? sanitize(item) : item
+          );
+        }
+        return sanitize(data);
+      }
+      /**
+       * Calculate delay for retry with exponential backoff
+       */
+      calculateRetryDelay(attempt) {
+        const delay = this.retryConfig.initialDelay * Math.pow(2, attempt);
+        return Math.min(delay, this.retryConfig.maxDelay);
+      }
+      /**
+       * Sleep for specified milliseconds
        */
-      async request(method, endpoint, options) {
+      sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+      }
+      /**
+       * Perform HTTP request with automatic retry on transient failures
+       */
+      async request(method, endpoint, options, retryAttempt = 0) {
         const url = this.buildUrl(endpoint) + (options?.params ? this.buildQueryString(options.params) : "");
         const isFormData = options?.body instanceof FormData;
         const headers = this.buildHeaders(options?.headers, isFormData);
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        const startTime = Date.now();
+        if (this.debug) {
+          this.logger.log(`[Marvin] ${method} ${url}`);
+        }
         try {
           const response = await fetch(url, {
             method,
@@ -189,11 +408,54 @@ var init_HttpClient = __esm({
             signal: controller.signal
           });
           clearTimeout(timeoutId);
+          const duration = Date.now() - startTime;
+          if (this.debug) {
+            this.logger.log(
+              `[Marvin] ${response.status} ${response.statusText} (${duration}ms)`
+            );
+          }
           if (response.status === 401 && this.auth.handleUnauthorized) {
             await this.auth.handleUnauthorized();
           }
           if (!response.ok) {
             const errorText = await response.text().catch(() => "");
+            if (this.debug) {
+              this.logger.error(
+                `[Marvin] Error response: ${response.status} ${response.statusText}`,
+                errorText ? `Body: ${errorText}` : ""
+              );
+            }
+            const isRetryable = this.retryConfig.retryableStatuses.includes(response.status);
+            const canRetry = retryAttempt < this.retryConfig.maxRetries;
+            if (isRetryable && canRetry) {
+              const delay = this.calculateRetryDelay(retryAttempt);
+              if (this.debug) {
+                this.logger.warn(
+                  `[Marvin] Retry ${retryAttempt + 1}/${this.retryConfig.maxRetries} after ${delay}ms (status: ${response.status})`
+                );
+              }
+              await this.sleep(delay);
+              return this.request(method, endpoint, options, retryAttempt + 1);
+            }
+            if (response.status === 404) {
+              throw new MarvinNotFoundError(
+                `Resource not found: ${endpoint}`,
+                endpoint
+              );
+            }
+            if (response.status === 401 || response.status === 403) {
+              throw new MarvinAuthError(
+                `Authentication failed: ${response.statusText}`,
+                response.status
+              );
+            }
+            if (response.status >= 500) {
+              throw new MarvinServerError(
+                `Server error: ${response.status} ${response.statusText}`,
+                response.status,
+                endpoint
+              );
+            }
             throw MarvinApiError.fromResponse(
               response.status,
               response.statusText,
@@ -205,21 +467,39 @@ var init_HttpClient = __esm({
           if (!contentType || !contentType.includes("application/json")) {
             return void 0;
           }
-          return await response.json();
+          const data = await response.json();
+          if (this.debug) {
+            const sanitized = this.sanitizeForLogging(data);
+            this.logger.log("[Marvin] Response:", JSON.stringify(sanitized, null, 2));
+          }
+          return data;
         } catch (error) {
           clearTimeout(timeoutId);
-          if (error instanceof MarvinApiError) {
+          if (error instanceof MarvinApiError || error instanceof MarvinNotFoundError || error instanceof MarvinAuthError || error instanceof MarvinServerError) {
             throw error;
           }
           if (error instanceof Error) {
+            const canRetry = retryAttempt < this.retryConfig.maxRetries;
+            if (canRetry && error.name !== "AbortError") {
+              const delay = this.calculateRetryDelay(retryAttempt);
+              if (this.debug) {
+                this.logger.warn(
+                  `[Marvin] Retry ${retryAttempt + 1}/${this.retryConfig.maxRetries} after ${delay}ms (network error)`
+                );
+              }
+              await this.sleep(delay);
+              return this.request(method, endpoint, options, retryAttempt + 1);
+            }
             if (error.name === "AbortError") {
-              throw new MarvinApiError(
+              throw new MarvinNetworkError(
                 `Request timeout after ${this.timeout}ms`,
-                408,
-                endpoint
+                error
               );
             }
-            throw new MarvinApiError(error.message, 0, endpoint);
+            throw new MarvinNetworkError(
+              `Network error: ${error.message}`,
+              error
+            );
           }
           throw error;
         }
@@ -290,10 +570,27 @@ var init_AuthStrategy = __esm({
       }
       sessionToken;
       onUnauthorized;
+      csrfToken;
+      /**
+       * Set CSRF token for cross-site request forgery protection
+       * The token should be obtained from the server after login
+       */
+      setCsrfToken(token) {
+        this.csrfToken = token;
+      }
+      /**
+       * Get current CSRF token
+       */
+      getCsrfToken() {
+        return this.csrfToken;
+      }
       injectAuth(headers) {
         if (this.sessionToken) {
           headers.set("Authorization", `Bearer ${this.sessionToken}`);
         }
+        if (this.csrfToken) {
+          headers.set("X-CSRF-Token", this.csrfToken);
+        }
       }
       async handleUnauthorized() {
         if (this.onUnauthorized) {
@@ -301,7 +598,9 @@ var init_AuthStrategy = __esm({
         }
       }
       getDescription() {
-        return this.sessionToken ? "Session authentication (explicit token)" : "Session authentication (cookies)";
+        const auth = this.sessionToken ? "Session authentication (explicit token)" : "Session authentication (cookies)";
+        const csrf = this.csrfToken ? " with CSRF protection" : "";
+        return auth + csrf;
       }
     };
     NoAuth = class {
@@ -361,11 +660,17 @@ var init_cache = __esm({
   "src/core/cache.ts"() {
     "use strict";
     MarvinCache = class {
-      constructor(duration = 5 * 60 * 1e3) {
+      constructor(duration = 5 * 60 * 1e3, maxEntries = 1e3) {
         this.duration = duration;
+        this.maxEntries = maxEntries;
       }
       duration;
+      maxEntries;
       cache = /* @__PURE__ */ new Map();
+      /**
+       * Get cached data by key
+       * Returns undefined if not found or expired
+       */
       get(key) {
         const entry = this.cache.get(key);
         if (!entry) return void 0;
@@ -376,25 +681,149 @@ var init_cache = __esm({
         }
         return entry.data;
       }
-      set(key, data) {
+      /**
+       * Set cached data with optional tags for invalidation
+       */
+      set(key, data, tags) {
+        if (this.cache.size >= this.maxEntries) {
+          const oldestKey = this.cache.keys().next().value;
+          if (oldestKey) {
+            this.cache.delete(oldestKey);
+          }
+        }
         this.cache.set(key, {
           data,
-          timestamp: Date.now()
+          timestamp: Date.now(),
+          tags
         });
       }
+      /**
+       * Check if key exists and is not expired
+       */
       has(key) {
         return this.get(key) !== void 0;
       }
+      /**
+       * Clear all cached entries
+       */
       clear() {
         this.cache.clear();
       }
+      /**
+       * Delete a specific cache entry
+       */
       delete(key) {
         this.cache.delete(key);
       }
+      /**
+       * Invalidate all cache entries with a specific tag
+       * Useful for invalidating related data after mutations
+       *
+       * @example
+       * ```typescript
+       * // Cache entries with tags
+       * cache.set('entry:1', data, ['entries', 'entry:1']);
+       * cache.set('entries:list', data, ['entries']);
+       *
+       * // Invalidate all entries
+       * cache.invalidateByTag('entries');
+       * ```
+       */
+      invalidateByTag(tag) {
+        let count = 0;
+        for (const [key, entry] of this.cache.entries()) {
+          if (entry.tags?.includes(tag)) {
+            this.cache.delete(key);
+            count++;
+          }
+        }
+        return count;
+      }
+      /**
+       * Get cache statistics
+       */
+      getStats() {
+        let oldest = null;
+        let newest = null;
+        for (const entry of this.cache.values()) {
+          if (oldest === null || entry.timestamp < oldest) {
+            oldest = entry.timestamp;
+          }
+          if (newest === null || entry.timestamp > newest) {
+            newest = entry.timestamp;
+          }
+        }
+        return {
+          size: this.cache.size,
+          maxEntries: this.maxEntries,
+          oldestEntry: oldest,
+          newestEntry: newest
+        };
+      }
+      /**
+       * Remove expired entries (garbage collection)
+       * Returns number of entries removed
+       */
+      prune() {
+        let count = 0;
+        const now = Date.now();
+        for (const [key, entry] of this.cache.entries()) {
+          const age = now - entry.timestamp;
+          if (age > this.duration) {
+            this.cache.delete(key);
+            count++;
+          }
+        }
+        return count;
+      }
     };
   }
 });
 
+// src/core/validation.ts
+function validateEmail(email, fieldName = "Email") {
+  if (!email || typeof email !== "string") {
+    throw new MarvinValidationError(`${fieldName} is required and must be a string`);
+  }
+  const trimmed = email.trim();
+  if (trimmed.length === 0) {
+    throw new MarvinValidationError(`${fieldName} cannot be empty`);
+  }
+  if (trimmed.length < 5) {
+    throw new MarvinValidationError(`${fieldName} is too short`);
+  }
+  if (trimmed.length > 254) {
+    throw new MarvinValidationError(`${fieldName} exceeds maximum length of 254 characters`);
+  }
+  if (!EMAIL_REGEX.test(trimmed)) {
+    throw new MarvinValidationError(
+      `${fieldName} format is invalid. Expected format: user@example.com`
+    );
+  }
+  const [localPart, domain] = trimmed.split("@");
+  if (localPart.length > 64) {
+    throw new MarvinValidationError(`${fieldName} local part exceeds 64 characters`);
+  }
+  if (domain.length > 253) {
+    throw new MarvinValidationError(`${fieldName} domain exceeds 253 characters`);
+  }
+  if (trimmed.includes("..")) {
+    throw new MarvinValidationError(`${fieldName} cannot contain consecutive dots`);
+  }
+  if (localPart.startsWith(".") || localPart.endsWith(".")) {
+    throw new MarvinValidationError(`${fieldName} local part cannot start or end with a dot`);
+  }
+  return trimmed;
+}
+var EMAIL_REGEX;
+var init_validation = __esm({
+  "src/core/validation.ts"() {
+    "use strict";
+    init_errors();
+    EMAIL_REGEX = /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
+  }
+});
+
 // src/core/index.ts
 var init_core = __esm({
   "src/core/index.ts"() {
@@ -404,6 +833,7 @@ var init_core = __esm({
     init_errors();
     init_pagination();
     init_cache();
+    init_validation();
   }
 });
 
@@ -418,7 +848,9 @@ var init_http2 = __esm({
         super({
           baseUrl: config.apiUrl,
           auth: new BearerTokenAuth(config.siteClientToken),
-          credentials: "same-origin"
+          credentials: "same-origin",
+          debug: config.debug,
+          logger: config.logger
         });
       }
       /**
@@ -555,6 +987,7 @@ var init_entries = __esm({
   "src/entries/entries.ts"() {
     "use strict";
     init_entry();
+    init_errors();
     EntriesModule = class {
       constructor(http, workspaceSlug) {
         this.http = http;
@@ -579,11 +1012,19 @@ var init_entries = __esm({
       }
       /**
        * Get a single entry by slug
+       * Returns null if entry is not found (404)
        */
       async get(slug) {
-        const endpoint = `/api/publish/${this.workspaceSlug}/entries/${slug}`;
-        const data = await this.http.fetch(endpoint);
-        return new Entry(data, this.http, this.workspaceSlug);
+        try {
+          const endpoint = `/api/publish/${this.workspaceSlug}/entries/${slug}`;
+          const data = await this.http.fetch(endpoint);
+          return new Entry(data, this.http, this.workspaceSlug);
+        } catch (error) {
+          if (error instanceof MarvinNotFoundError) {
+            return null;
+          }
+          throw error;
+        }
       }
       /**
        * Convenience: Get all pages
@@ -689,6 +1130,7 @@ var init_collections = __esm({
   "src/collections/collections.ts"() {
     "use strict";
     init_collection();
+    init_errors();
     CollectionsModule = class {
       constructor(http, workspaceSlug) {
         this.http = http;
@@ -706,19 +1148,63 @@ var init_collections = __esm({
       }
       /**
        * Get a single collection by slug
+       * Returns null if collection is not found (404)
        */
       async get(slug) {
-        const endpoint = `/api/publish/${this.workspaceSlug}/collections/${slug}`;
-        const data = await this.http.fetch(endpoint);
-        return new Collection(data, this.http, this.workspaceSlug);
+        try {
+          const endpoint = `/api/publish/${this.workspaceSlug}/collections/${slug}`;
+          const data = await this.http.fetch(endpoint);
+          return new Collection(data, this.http, this.workspaceSlug);
+        } catch (error) {
+          if (error instanceof MarvinNotFoundError) {
+            return null;
+          }
+          throw error;
+        }
       }
       /**
        * Get entries in a collection
+       * Returns empty array if collection is not found
        */
       async entries(slug) {
         const collection = await this.get(slug);
+        if (!collection) {
+          return [];
+        }
         return collection.entries();
       }
+      /**
+       * Try multiple collection slugs in fallback order
+       * Returns the first collection that exists and has entries
+       *
+       * @param slugs - Collection slugs to try in order
+       * @param options - Options for fallback behavior
+       * @returns Entries from the first matching collection, or empty array
+       *
+       * @example
+       * ```ts
+       * // Try bench-notes, then journal, then blog
+       * const entries = await collections.fallback(['bench-notes', 'journal', 'blog']);
+       * ```
+       */
+      async fallback(slugs, options = {}) {
+        const { requireEntries = true } = options;
+        for (const slug of slugs) {
+          try {
+            const collection = await this.get(slug);
+            if (!collection) {
+              continue;
+            }
+            const entries = await collection.entries();
+            if (!requireEntries || entries.length > 0) {
+              return entries;
+            }
+          } catch (error) {
+            continue;
+          }
+        }
+        return [];
+      }
     };
   }
 });
@@ -890,6 +1376,26 @@ var init_resources = __esm({
   }
 });
 
+// src/renderers/renderers.ts
+var RenderersModule;
+var init_renderers = __esm({
+  "src/renderers/renderers.ts"() {
+    "use strict";
+    RenderersModule = class {
+      constructor(http, workspaceSlug) {
+        this.http = http;
+        this.workspaceSlug = workspaceSlug;
+      }
+      http;
+      workspaceSlug;
+      async list() {
+        const endpoint = `/api/publish/${this.workspaceSlug}/entry-types`;
+        return this.http.fetch(endpoint);
+      }
+    };
+  }
+});
+
 // src/workspaces/workspace.ts
 var Workspace;
 var init_workspace = __esm({
@@ -899,6 +1405,7 @@ var init_workspace = __esm({
     init_collections();
     init_assets();
     init_resources();
+    init_renderers();
     Workspace = class {
       constructor(http, slug) {
         this.http = http;
@@ -907,6 +1414,7 @@ var init_workspace = __esm({
         this.collections = new CollectionsModule(http, slug);
         this.assets = new AssetsModule(http, slug);
         this.resources = new ResourcesModule(http, slug);
+        this.renderers = new RenderersModule(http, slug);
       }
       http;
       _site = null;
@@ -915,6 +1423,7 @@ var init_workspace = __esm({
       collections;
       assets;
       resources;
+      renderers;
       /**
        * Get workspace slug
        */
@@ -1042,6 +1551,12 @@ var init_marvin = __esm({
       get resources() {
         return this.workspace.resources;
       }
+      /**
+       * Get renderers module
+       */
+      get renderers() {
+        return this.workspace.renderers;
+      }
       // ======================
       // Convenience Methods
       // ======================
@@ -1081,6 +1596,23 @@ var init_marvin = __esm({
       async resource(slug) {
         return this.workspace.resources.get(slug);
       }
+      /**
+       * Try multiple collection slugs in fallback order
+       * Returns entries from the first collection that exists and has content
+       *
+       * @param slugs - Collection slugs to try in order
+       * @param options - Options for fallback behavior
+       * @returns Entries from the first matching collection, or empty array
+       *
+       * @example
+       * ```ts
+       * // Try bench-notes, then journal, then blog
+       * const entries = await client.collectionFallback(['bench-notes', 'journal', 'blog']);
+       * ```
+       */
+      async collectionFallback(slugs, options) {
+        return this.workspace.collections.fallback(slugs, options);
+      }
       // ======================
       // Backwards-Compatible Publishing API
       // ======================
@@ -1104,6 +1636,9 @@ var init_marvin = __esm({
        */
       async getEntry(slug) {
         const entry = await this.workspace.entries.get(slug);
+        if (!entry) {
+          return null;
+        }
         return entry.toJSON();
       }
       /**
@@ -1119,6 +1654,9 @@ var init_marvin = __esm({
        */
       async getCollection(slug) {
         const collection = await this.workspace.collections.get(slug);
+        if (!collection) {
+          return null;
+        }
         return collection.toJSON();
       }
       /**
@@ -1175,6 +1713,9 @@ __export(index_exports, {
   MarvinClient: () => MarvinClient,
   MarvinConfigError: () => MarvinConfigError,
   MarvinError: () => MarvinError,
+  MarvinNetworkError: () => MarvinNetworkError,
+  MarvinNotFoundError: () => MarvinNotFoundError,
+  MarvinServerError: () => MarvinServerError,
   MarvinValidationError: () => MarvinValidationError,
   NoAuth: () => NoAuth,
   Resource: () => Resource,
@@ -1209,12 +1750,14 @@ var AuthClient = class extends HttpClient {
    * Returns the created user object
    */
   async register(data) {
+    validateEmail(data.email, "Email");
     return this.post("/api/users/register", data);
   }
   /**
    * Request password reset (sends email with token)
    */
   async forgotPassword(data) {
+    validateEmail(data.email, "Email");
     return this.post("/api/users/forgot-password", data);
   }
   /**
@@ -1271,6 +1814,9 @@ function createMarvinClient(config) {
   MarvinClient,
   MarvinConfigError,
   MarvinError,
+  MarvinNetworkError,
+  MarvinNotFoundError,
+  MarvinServerError,
   MarvinValidationError,
   NoAuth,
   Resource,