@inneropen/marvin-sdk 2.0.1 → 3.0.1

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
         });
       }
       /**
@@ -437,113 +869,54 @@ var init_entry = __esm({
   "src/entries/entry.ts"() {
     "use strict";
     Entry = class {
-      constructor(data, http, workspaceSlug) {
-        this.data = data;
-        this.http = http;
-        this.workspaceSlug = workspaceSlug;
-      }
-      data;
-      http;
-      workspaceSlug;
-      // Expose all entry data as properties
-      get id() {
-        return this.data.id;
+      constructor(raw) {
+        this.raw = raw;
       }
+      raw;
       get title() {
-        return this.data.title;
+        return this.raw.title;
       }
       get slug() {
-        return this.data.slug;
+        return this.raw.slug;
       }
       get summary() {
-        return this.data.summary;
+        return this.raw.summary;
       }
-      get description() {
-        return this.data.description;
-      }
-      /**
-       * @deprecated Use field('body') or dataJson instead. Will be removed in v3.0.0
-       */
-      get contentMarkdown() {
-        return this.data.contentMarkdown;
+      get entryType() {
+        return this.raw.entryType;
       }
-      /**
-       * Schema-driven content data (replaces contentMarkdown in v2.0.0).
-       * Access specific fields using the field() helper method.
-       * @since 2.0.0
-       */
-      get dataJson() {
-        return this.data.dataJson;
+      get entryTypeInfo() {
+        return this.raw.entryTypeInfo;
       }
-      get metadata() {
-        return this.data.metadata;
+      get data() {
+        return this.raw.data;
       }
-      get status() {
-        return this.data.status;
+      get metadataJson() {
+        return this.raw.metadataJson;
       }
       get publishedAt() {
-        return this.data.publishedAt;
+        return this.raw.publishedAt;
       }
-      get createdAt() {
-        return this.data.createdAt;
+      get order() {
+        return this.raw.order;
       }
-      get updatedAt() {
-        return this.data.updatedAt;
-      }
-      get entryTypeId() {
-        return this.data.entryTypeId;
-      }
-      get entryType() {
-        return this.data.entryType;
-      }
-      /**
-       * Get entry assets
-       */
       get assets() {
-        return this.data.assets || [];
+        return this.raw.assets;
       }
-      /**
-       * Get entry collections
-       */
       get collections() {
-        return this.data.collections || [];
+        return this.raw.collections;
+      }
+      get resources() {
+        return this.raw.resources;
       }
-      /**
-       * Get a specific field value from the entry's schema-driven content (dataJson).
-       *
-       * @param key - Field key as defined in the entry type's schema
-       * @returns The field value, or undefined if not present
-       * @since 2.0.0
-       *
-       * @example
-       * ```typescript
-       * const entry = await client.entries.get('my-entry');
-       * const body = entry.field('body');           // Get markdown body
-       * const difficulty = entry.field('difficulty'); // Get difficulty level
-       * const heroImage = entry.field('heroImage');  // Get hero image UUID
-       * ```
-       */
       field(key) {
-        return this.data.dataJson?.[key];
+        return this.raw.data[key];
       }
-      /**
-       * Get all fields from the entry's schema-driven content.
-       * @since 2.0.0
-       */
       get fields() {
-        return this.data.dataJson || {};
-      }
-      /**
-       * Get related entries (future)
-       */
-      async relatedEntries() {
-        throw new Error("Related entries not yet implemented");
+        return this.raw.data;
       }
-      /**
-       * Get raw entry data
-       */
       toJSON() {
-        return this.data;
+        return this.raw;
       }
     };
   }
@@ -555,6 +928,7 @@ var init_entries = __esm({
   "src/entries/entries.ts"() {
     "use strict";
     init_entry();
+    init_errors();
     EntriesModule = class {
       constructor(http, workspaceSlug) {
         this.http = http;
@@ -571,7 +945,6 @@ var init_entries = __esm({
           collection: options.collection,
           limit: options.limit,
           offset: options.offset
-          // Don't send status - backend always returns published
         });
         const endpoint = `/api/publish/${this.workspaceSlug}/entries${queryString}`;
         const response = await this.http.fetch(endpoint);
@@ -579,11 +952,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);
+        } catch (error) {
+          if (error instanceof MarvinNotFoundError) {
+            return null;
+          }
+          throw error;
+        }
       }
       /**
        * Convenience: Get all pages
@@ -613,18 +994,10 @@ var init_collection = __esm({
   "src/collections/collection.ts"() {
     "use strict";
     Collection = class {
-      constructor(data, http, workspaceSlug) {
+      constructor(data) {
         this.data = data;
-        this.http = http;
-        this.workspaceSlug = workspaceSlug;
       }
       data;
-      http;
-      workspaceSlug;
-      // Expose all collection data as properties
-      get id() {
-        return this.data.id;
-      }
       get name() {
         return this.data.name;
       }
@@ -634,48 +1007,21 @@ var init_collection = __esm({
       get description() {
         return this.data.description;
       }
-      get icon() {
-        return this.data.icon;
-      }
-      get color() {
-        return this.data.color;
-      }
-      get sortOrder() {
-        return this.data.sortOrder;
-      }
       get isSmart() {
         return this.data.isSmart;
       }
       get smartRules() {
         return this.data.smartRules;
       }
-      get createdAt() {
-        return this.data.createdAt;
+      get metadataJson() {
+        return this.data.metadataJson;
       }
-      get updatedAt() {
-        return this.data.updatedAt;
+      get entryCount() {
+        return this.data.entryCount;
       }
-      /**
-       * Get all entries in this collection
-       */
-      async entries() {
-        return this.data.entries || [];
-      }
-      /**
-       * Get assets in this collection (future)
-       */
-      async assets() {
-        throw new Error("Collection assets not yet implemented");
-      }
-      /**
-       * Get collection metadata (future)
-       */
-      async metadata() {
-        throw new Error("Collection metadata not yet implemented");
+      get entries() {
+        return this.data.entries;
       }
-      /**
-       * Get raw collection data
-       */
       toJSON() {
         return this.data;
       }
@@ -689,6 +1035,7 @@ var init_collections = __esm({
   "src/collections/collections.ts"() {
     "use strict";
     init_collection();
+    init_errors();
     CollectionsModule = class {
       constructor(http, workspaceSlug) {
         this.http = http;
@@ -706,18 +1053,52 @@ 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);
+        } 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);
-        return collection.entries();
+        if (!collection) {
+          return [];
+        }
+        return collection.entries;
+      }
+      /**
+       * Try multiple collection slugs in fallback order
+       * Returns the first collection that exists and has entries
+       */
+      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 = collection.entries;
+            if (!requireEntries || entries.length > 0) {
+              return entries;
+            }
+          } catch (error) {
+            continue;
+          }
+        }
+        return [];
       }
     };
   }
@@ -783,18 +1164,10 @@ var init_resource = __esm({
   "src/resources/resource.ts"() {
     "use strict";
     Resource = class {
-      constructor(data, http, workspaceSlug) {
+      constructor(data) {
         this.data = data;
-        this.http = http;
-        this.workspaceSlug = workspaceSlug;
       }
       data;
-      http;
-      workspaceSlug;
-      // Expose all resource data as properties
-      get id() {
-        return this.data.id;
-      }
       get name() {
         return this.data.name;
       }
@@ -813,31 +1186,12 @@ var init_resource = __esm({
       get url() {
         return this.data.url;
       }
-      get metadata() {
-        return this.data.metadata;
-      }
-      get createdAt() {
-        return this.data.createdAt;
-      }
-      get updatedAt() {
-        return this.data.updatedAt;
+      get metadataJson() {
+        return this.data.metadataJson;
       }
-      /**
-       * Get all entries that reference this resource
-       */
-      async entries() {
-        const endpoint = `/api/publish/${this.workspaceSlug}/resources/${this.data.slug}/entries`;
-        return this.http.fetch(endpoint);
-      }
-      /**
-       * Get assets related to this resource (future)
-       */
-      async assets() {
-        throw new Error("Resource assets not yet implemented");
+      get entries() {
+        return this.data.entries;
       }
-      /**
-       * Get raw resource data
-       */
       toJSON() {
         return this.data;
       }
@@ -877,14 +1231,34 @@ var init_resources = __esm({
       async get(slug) {
         const endpoint = `/api/publish/${this.workspaceSlug}/resources/${slug}`;
         const data = await this.http.fetch(endpoint);
-        return new Resource(data, this.http, this.workspaceSlug);
+        return new Resource(data);
       }
       /**
-       * Get entries that reference this resource
+       * Get entry slugs that reference this resource
        */
       async entries(slug) {
         const resource = await this.get(slug);
-        return resource.entries();
+        return resource.entries;
+      }
+    };
+  }
+});
+
+// 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);
       }
     };
   }
@@ -899,6 +1273,7 @@ var init_workspace = __esm({
     init_collections();
     init_assets();
     init_resources();
+    init_renderers();
     Workspace = class {
       constructor(http, slug) {
         this.http = http;
@@ -907,6 +1282,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 +1291,7 @@ var init_workspace = __esm({
       collections;
       assets;
       resources;
+      renderers;
       /**
        * Get workspace slug
        */
@@ -942,12 +1319,6 @@ var init_workspace = __esm({
         const endpoint = `/api/publish/${this._slug}`;
         return this.http.fetch(endpoint);
       }
-      /**
-       * Get workspace settings (future)
-       */
-      async settings() {
-        throw new Error("Workspace settings not yet implemented");
-      }
     };
   }
 });
@@ -966,8 +1337,11 @@ var init_marvin = __esm({
     init_core();
     init_workspace();
     MarvinClient = class {
+      http;
+      cache;
+      workspace;
+      initialized = false;
       constructor(config) {
-        this.config = config;
         validateConfig(config);
         this.http = new MarvinHttpClient(config);
         this.cache = new MarvinCache(config.cacheDuration);
@@ -976,11 +1350,6 @@ var init_marvin = __esm({
           this.initialize();
         }
       }
-      config;
-      http;
-      cache;
-      workspace;
-      initialized = false;
       /**
        * Initialize the SDK
        * Preloads site configuration and metadata
@@ -1042,6 +1411,12 @@ var init_marvin = __esm({
       get resources() {
         return this.workspace.resources;
       }
+      /**
+       * Get renderers module
+       */
+      get renderers() {
+        return this.workspace.renderers;
+      }
       // ======================
       // Convenience Methods
       // ======================
@@ -1081,70 +1456,74 @@ 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
+       */
+      async collectionFallback(slugs, options) {
+        return this.workspace.collections.fallback(slugs, options);
+      }
       // ======================
       // Backwards-Compatible Publishing API
       // ======================
       /**
        * @deprecated Use workspace.site or marvin.site instead
-       * Get site configuration
        */
       async getSite() {
         return this.workspace.loadSite();
       }
       /**
        * @deprecated Use workspace.entries.list() instead
-       * Get all published entries
        */
       async getEntries(options) {
         return this.workspace.entries.list(options);
       }
       /**
        * @deprecated Use workspace.entries.get() instead
-       * Get a single published entry by slug
        */
       async getEntry(slug) {
         const entry = await this.workspace.entries.get(slug);
+        if (!entry) {
+          return null;
+        }
         return entry.toJSON();
       }
       /**
        * @deprecated Use workspace.collections.list() instead
-       * Get all collections
        */
       async getCollections() {
         return this.workspace.collections.list();
       }
       /**
        * @deprecated Use workspace.collections.get() instead
-       * Get a single collection by slug
        */
       async getCollection(slug) {
         const collection = await this.workspace.collections.get(slug);
+        if (!collection) {
+          return null;
+        }
         return collection.toJSON();
       }
       /**
        * @deprecated Use workspace.collections.entries() instead
-       * Get all entries in a collection
        */
       async getCollectionEntries(slug) {
         return this.workspace.collections.entries(slug);
       }
       /**
        * @deprecated Use workspace.assets.list() instead
-       * Get all published assets
        */
       async getAssets(options) {
         return this.workspace.assets.list(options);
       }
       /**
        * @deprecated Use workspace.resources.list() instead
-       * Get all published resources
        */
       async getResources(options) {
         return this.workspace.resources.list(options);
       }
       /**
        * @deprecated Use workspace.resources.get() instead
-       * Get a single resource by slug
        */
       async getResource(slug) {
         const resource = await this.workspace.resources.get(slug);
@@ -1152,7 +1531,6 @@ var init_marvin = __esm({
       }
       /**
        * @deprecated Use workspace.resources.entries() instead
-       * Get entries that reference a resource
        */
       async getResourceEntries(slug) {
         return this.workspace.resources.entries(slug);
@@ -1175,6 +1553,9 @@ __export(index_exports, {
   MarvinClient: () => MarvinClient,
   MarvinConfigError: () => MarvinConfigError,
   MarvinError: () => MarvinError,
+  MarvinNetworkError: () => MarvinNetworkError,
+  MarvinNotFoundError: () => MarvinNotFoundError,
+  MarvinServerError: () => MarvinServerError,
   MarvinValidationError: () => MarvinValidationError,
   NoAuth: () => NoAuth,
   Resource: () => Resource,
@@ -1209,12 +1590,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 +1654,9 @@ function createMarvinClient(config) {
   MarvinClient,
   MarvinConfigError,
   MarvinError,
+  MarvinNetworkError,
+  MarvinNotFoundError,
+  MarvinServerError,
   MarvinValidationError,
   NoAuth,
   Resource,