@inneropen/marvin-sdk 2.0.0-next.13 → 2.0.0-next.15

package/dist/index.cjs

@@ -30,19 +30,97 @@ function validateConfig(config) {
   const receivedKeys = Object.keys(config).join(", ");
   if (!config.apiUrl) {
     throw new Error(
-      `Missing required config parameter 'apiUrl'. Received config keys: ${receivedKeys || "(none)"}. Set this to your MARVIN_API_URL environment variable value.`
+      `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(
-      `Missing required config parameter 'siteClientToken'. Received config keys: ${receivedKeys}. Set this to your MARVIN_SITE_CLIENT_TOKEN environment variable value.`
+      `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(
-      `Missing required config parameter 'workspaceSlug'. Received config keys: ${receivedKeys}. Set this to your MARVIN_WORKSPACE_SLUG environment variable value.`
+      `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 createConfigFromEnv(overrides) {
   return {
@@ -170,15 +248,46 @@ var init_HttpClient = __esm({
       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
@@ -212,9 +321,69 @@ 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
        */
-      async request(method, endpoint, options) {
+      calculateRetryDelay(attempt) {
+        const delay = this.retryConfig.initialDelay * Math.pow(2, attempt);
+        return Math.min(delay, this.retryConfig.maxDelay);
+      }
+      /**
+       * Sleep for specified milliseconds
+       */
+      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);
@@ -250,6 +419,18 @@ var init_HttpClient = __esm({
                 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}`,
@@ -282,8 +463,8 @@ var init_HttpClient = __esm({
           }
           const data = await response.json();
           if (this.debug) {
-            const preview = typeof data === "object" && data !== null ? Array.isArray(data) ? `Array(${data.length})` : `Object with keys: ${Object.keys(data).join(", ")}` : String(data);
-            this.logger.log(`[Marvin] Response: ${preview}`);
+            const sanitized = this.sanitizeForLogging(data);
+            this.logger.log("[Marvin] Response:", JSON.stringify(sanitized, null, 2));
           }
           return data;
         } catch (error) {
@@ -292,6 +473,17 @@ var init_HttpClient = __esm({
             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 MarvinNetworkError(
                 `Request timeout after ${this.timeout}ms`,
@@ -372,10 +564,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) {
@@ -383,7 +592,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 {
@@ -443,11 +654,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;
@@ -458,25 +675,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"() {
@@ -486,6 +827,7 @@ var init_core = __esm({
     init_errors();
     init_pagination();
     init_cache();
+    init_validation();
   }
 });
 
@@ -1373,12 +1715,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);
   }
   /**