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

package/dist/{HttpClient-CLtgQGXH.d.cts → HttpClient-BX5Gqd0w.d.cts}

@@ -60,6 +60,12 @@ interface HttpClientConfig {
     defaultHeaders?: Record<string, string>;
     credentials?: RequestCredentials;
     timeout?: number;
+    debug?: boolean;
+    logger?: {
+        log: (message: string, ...args: unknown[]) => void;
+        warn: (message: string, ...args: unknown[]) => void;
+        error: (message: string, ...args: unknown[]) => void;
+    };
 }
 declare class HttpClient {
     private baseUrl;
@@ -67,6 +73,8 @@ declare class HttpClient {
     private defaultHeaders;
     private credentials;
     private timeout;
+    private debug;
+    private logger;
     constructor(config: HttpClientConfig);
     /**
      * Build full URL from endpoint

package/dist/{HttpClient-CLtgQGXH.d.ts → HttpClient-BX5Gqd0w.d.ts}

@@ -60,6 +60,12 @@ interface HttpClientConfig {
     defaultHeaders?: Record<string, string>;
     credentials?: RequestCredentials;
     timeout?: number;
+    debug?: boolean;
+    logger?: {
+        log: (message: string, ...args: unknown[]) => void;
+        warn: (message: string, ...args: unknown[]) => void;
+        error: (message: string, ...args: unknown[]) => void;
+    };
 }
 declare class HttpClient {
     private baseUrl;
@@ -67,6 +73,8 @@ declare class HttpClient {
     private defaultHeaders;
     private credentials;
     private timeout;
+    private debug;
+    private logger;
     constructor(config: HttpClientConfig);
     /**
      * Build full URL from endpoint

package/dist/{chunk-25F3IF6S.js → chunk-DYC2BEA4.js}

@@ -20,7 +20,7 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // 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";
@@ -76,6 +76,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;
+    };
   }
 });
 
@@ -99,12 +126,16 @@ var init_HttpClient = __esm({
       defaultHeaders;
       credentials;
       timeout;
+      debug;
+      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;
+        this.debug = config.debug ?? false;
+        this.logger = config.logger ?? console;
       }
       /**
        * Build full URL from endpoint
@@ -146,6 +177,10 @@ var init_HttpClient = __esm({
         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,
@@ -155,11 +190,42 @@ 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}` : ""
+              );
+            }
+            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,
@@ -171,21 +237,28 @@ 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 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}`);
+          }
+          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) {
             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;
         }
@@ -382,6 +455,10 @@ export {
   MarvinAuthError,
   MarvinConfigError,
   MarvinValidationError,
+  MarvinNotFoundError,
+  MarvinNetworkError,
+  MarvinServerError,
+  init_errors,
   HttpClient,
   BearerTokenAuth,
   SessionAuth,

package/dist/index.cjs

@@ -27,14 +27,21 @@ __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 parameter 'apiUrl'. Received config keys: ${receivedKeys || "(none)"}. Set this to your MARVIN_API_URL environment variable value.`
+    );
   }
   if (!config.siteClientToken) {
-    throw new Error("MARVIN_SITE_CLIENT_TOKEN is required");
+    throw new Error(
+      `Missing required config parameter 'siteClientToken'. Received config keys: ${receivedKeys}. Set this to your MARVIN_SITE_CLIENT_TOKEN environment variable value.`
+    );
   }
   if (!config.workspaceSlug) {
-    throw new Error("MARVIN_WORKSPACE_SLUG is required");
+    throw new Error(
+      `Missing required config parameter 'workspaceSlug'. Received config keys: ${receivedKeys}. Set this to your MARVIN_WORKSPACE_SLUG environment variable value.`
+    );
   }
 }
 function createConfigFromEnv(overrides) {
@@ -43,8 +50,10 @@ function createConfigFromEnv(overrides) {
     siteClientToken: overrides?.siteClientToken || process.env.MARVIN_SITE_CLIENT_TOKEN || "",
     workspaceSlug: overrides?.workspaceSlug || process.env.MARVIN_WORKSPACE_SLUG || "",
     autoInitialize: overrides?.autoInitialize ?? false,
-    cacheDuration: overrides?.cacheDuration ?? 5 * 60 * 1e3
+    cacheDuration: overrides?.cacheDuration ?? 5 * 60 * 1e3,
     // 5 minutes
+    debug: overrides?.debug ?? process.env.MARVIN_DEBUG === "true",
+    logger: overrides?.logger ?? console
   };
 }
 var init_config = __esm({
@@ -54,7 +63,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 +119,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 +169,16 @@ var init_HttpClient = __esm({
       defaultHeaders;
       credentials;
       timeout;
+      debug;
+      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;
+        this.debug = config.debug ?? false;
+        this.logger = config.logger ?? console;
       }
       /**
        * Build full URL from endpoint
@@ -180,6 +220,10 @@ var init_HttpClient = __esm({
         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 +233,42 @@ 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}` : ""
+              );
+            }
+            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 +280,28 @@ 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 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}`);
+          }
+          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) {
             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;
         }
@@ -418,7 +500,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 +639,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 +664,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 +782,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 +800,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 [];
+      }
     };
   }
 });
@@ -1081,6 +1219,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 +1259,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 +1277,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 +1336,9 @@ __export(index_exports, {
   MarvinClient: () => MarvinClient,
   MarvinConfigError: () => MarvinConfigError,
   MarvinError: () => MarvinError,
+  MarvinNetworkError: () => MarvinNetworkError,
+  MarvinNotFoundError: () => MarvinNotFoundError,
+  MarvinServerError: () => MarvinServerError,
   MarvinValidationError: () => MarvinValidationError,
   NoAuth: () => NoAuth,
   Resource: () => Resource,
@@ -1271,6 +1435,9 @@ function createMarvinClient(config) {
   MarvinClient,
   MarvinConfigError,
   MarvinError,
+  MarvinNetworkError,
+  MarvinNotFoundError,
+  MarvinServerError,
   MarvinValidationError,
   NoAuth,
   Resource,

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { MarvinResource, MarvinEntry, MarvinAsset, MarvinCollection, MarvinEntryType, MarvinSite, GetResourcesOptions as GetResourcesOptions$1 } from './types/index.cjs';
 export { GetAssetsOptions, GetEntriesOptions, MarvinPublishResponse } from './types/index.cjs';
-import { H as HttpClient } from './HttpClient-CLtgQGXH.cjs';
-export { A as AuthStrategy, B as BearerTokenAuth, a as HttpClientConfig, N as NoAuth, S as SessionAuth } from './HttpClient-CLtgQGXH.cjs';
+import { H as HttpClient } from './HttpClient-BX5Gqd0w.cjs';
+export { A as AuthStrategy, B as BearerTokenAuth, a as HttpClientConfig, N as NoAuth, S as SessionAuth } from './HttpClient-BX5Gqd0w.cjs';
 
 /**
  * Marvin SDK Configuration
@@ -14,6 +14,14 @@ interface MarvinConfig {
     autoInitialize?: boolean;
     /** Cache duration in milliseconds (default: 5 minutes) */
     cacheDuration?: number;
+    /** Enable debug logging for HTTP requests and responses */
+    debug?: boolean;
+    /** Custom logger function (defaults to console) */
+    logger?: {
+        log: (message: string, ...args: unknown[]) => void;
+        warn: (message: string, ...args: unknown[]) => void;
+        error: (message: string, ...args: unknown[]) => void;
+    };
 }
 declare function createConfigFromEnv(overrides?: Partial<MarvinConfig>): MarvinConfig;
 
@@ -54,6 +62,27 @@ declare class MarvinValidationError extends MarvinError {
     readonly field?: string | undefined;
     constructor(message: string, field?: string | undefined);
 }
+/**
+ * Resource not found errors (404)
+ */
+declare class MarvinNotFoundError extends MarvinError {
+    readonly endpoint: string;
+    constructor(message: string, endpoint: string);
+}
+/**
+ * Network/connectivity errors
+ */
+declare class MarvinNetworkError extends MarvinError {
+    readonly originalError?: Error | undefined;
+    constructor(message: string, originalError?: Error | undefined);
+}
+/**
+ * Server errors (5xx)
+ */
+declare class MarvinServerError extends MarvinError {
+    readonly endpoint: string;
+    constructor(message: string, statusCode: number, endpoint: string);
+}
 
 /**
  * Pagination response types and helpers
@@ -270,12 +299,31 @@ declare class CollectionsModule {
     list(): Promise<MarvinCollection[]>;
     /**
      * Get a single collection by slug
+     * Returns null if collection is not found (404)
      */
-    get(slug: string): Promise<Collection>;
+    get(slug: string): Promise<Collection | null>;
     /**
      * Get entries in a collection
+     * Returns empty array if collection is not found
      */
     entries(slug: string): Promise<MarvinEntry[]>;
+    /**
+     * 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']);
+     * ```
+     */
+    fallback(slugs: string[], options?: {
+        requireEntries?: boolean;
+    }): Promise<MarvinEntry[]>;
 }
 
 declare class Entry {
@@ -365,8 +413,9 @@ declare class EntriesModule {
     list(options?: GetEntriesOptions): Promise<MarvinEntry[]>;
     /**
      * Get a single entry by slug
+     * Returns null if entry is not found (404)
      */
-    get(slug: string): Promise<Entry>;
+    get(slug: string): Promise<Entry | null>;
     /**
      * Convenience: Get all pages
      */
@@ -465,11 +514,11 @@ declare class MarvinClient {
     /**
      * Get a single entry by slug
      */
-    entry(slug: string): Promise<Entry>;
+    entry(slug: string): Promise<Entry | null>;
     /**
      * Get a single collection by slug
      */
-    collection(slug: string): Promise<Collection>;
+    collection(slug: string): Promise<Collection | null>;
     /**
      * Get all pages
      */
@@ -486,6 +535,23 @@ declare class MarvinClient {
      * Get a single resource by slug
      */
     resource(slug: string): Promise<Resource>;
+    /**
+     * 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']);
+     * ```
+     */
+    collectionFallback(slugs: string[], options?: {
+        requireEntries?: boolean;
+    }): Promise<MarvinEntry[]>;
     /**
      * @deprecated Use workspace.site or marvin.site instead
      * Get site configuration
@@ -500,7 +566,7 @@ declare class MarvinClient {
      * @deprecated Use workspace.entries.get() instead
      * Get a single published entry by slug
      */
-    getEntry(slug: string): Promise<MarvinEntry>;
+    getEntry(slug: string): Promise<MarvinEntry | null>;
     /**
      * @deprecated Use workspace.collections.list() instead
      * Get all collections
@@ -510,7 +576,7 @@ declare class MarvinClient {
      * @deprecated Use workspace.collections.get() instead
      * Get a single collection by slug
      */
-    getCollection(slug: string): Promise<MarvinCollection>;
+    getCollection(slug: string): Promise<MarvinCollection | null>;
     /**
      * @deprecated Use workspace.collections.entries() instead
      * Get all entries in a collection
@@ -621,4 +687,4 @@ declare function createAuthClient(apiUrl: string): AuthClient;
  */
 declare function createMarvinClient(config?: Partial<MarvinConfig>): MarvinClient;
 
-export { AuthClient, type AuthToken, Collection, Entry, type ForgotPasswordRequest, GetResourcesOptions$1 as GetResourcesOptions, HttpClient, type LoginRequest, MarvinApiError, MarvinAsset, MarvinAuthError, MarvinCache, MarvinClient, MarvinCollection, type MarvinConfig, MarvinConfigError, MarvinEntry, MarvinEntryType, MarvinError, MarvinResource, MarvinSite, MarvinValidationError, type PaginatedResponse, type PaginationMeta, type PaginationParams, type ResetPasswordRequest, Resource, type UserRegistration, Workspace, createAuthClient, createConfigFromEnv, createMarvinClient, createPaginatedResponse, extractData, isPaginatedResponse, offsetToPage, pageToOffset };
+export { AuthClient, type AuthToken, Collection, Entry, type ForgotPasswordRequest, GetResourcesOptions$1 as GetResourcesOptions, HttpClient, type LoginRequest, MarvinApiError, MarvinAsset, MarvinAuthError, MarvinCache, MarvinClient, MarvinCollection, type MarvinConfig, MarvinConfigError, MarvinEntry, MarvinEntryType, MarvinError, MarvinNetworkError, MarvinNotFoundError, MarvinResource, MarvinServerError, MarvinSite, MarvinValidationError, type PaginatedResponse, type PaginationMeta, type PaginationParams, type ResetPasswordRequest, Resource, type UserRegistration, Workspace, createAuthClient, createConfigFromEnv, createMarvinClient, createPaginatedResponse, extractData, isPaginatedResponse, offsetToPage, pageToOffset };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { MarvinResource, MarvinEntry, MarvinAsset, MarvinCollection, MarvinEntryType, MarvinSite, GetResourcesOptions as GetResourcesOptions$1 } from './types/index.js';
 export { GetAssetsOptions, GetEntriesOptions, MarvinPublishResponse } from './types/index.js';
-import { H as HttpClient } from './HttpClient-CLtgQGXH.js';
-export { A as AuthStrategy, B as BearerTokenAuth, a as HttpClientConfig, N as NoAuth, S as SessionAuth } from './HttpClient-CLtgQGXH.js';
+import { H as HttpClient } from './HttpClient-BX5Gqd0w.js';
+export { A as AuthStrategy, B as BearerTokenAuth, a as HttpClientConfig, N as NoAuth, S as SessionAuth } from './HttpClient-BX5Gqd0w.js';
 
 /**
  * Marvin SDK Configuration
@@ -14,6 +14,14 @@ interface MarvinConfig {
     autoInitialize?: boolean;
     /** Cache duration in milliseconds (default: 5 minutes) */
     cacheDuration?: number;
+    /** Enable debug logging for HTTP requests and responses */
+    debug?: boolean;
+    /** Custom logger function (defaults to console) */
+    logger?: {
+        log: (message: string, ...args: unknown[]) => void;
+        warn: (message: string, ...args: unknown[]) => void;
+        error: (message: string, ...args: unknown[]) => void;
+    };
 }
 declare function createConfigFromEnv(overrides?: Partial<MarvinConfig>): MarvinConfig;
 
@@ -54,6 +62,27 @@ declare class MarvinValidationError extends MarvinError {
     readonly field?: string | undefined;
     constructor(message: string, field?: string | undefined);
 }
+/**
+ * Resource not found errors (404)
+ */
+declare class MarvinNotFoundError extends MarvinError {
+    readonly endpoint: string;
+    constructor(message: string, endpoint: string);
+}
+/**
+ * Network/connectivity errors
+ */
+declare class MarvinNetworkError extends MarvinError {
+    readonly originalError?: Error | undefined;
+    constructor(message: string, originalError?: Error | undefined);
+}
+/**
+ * Server errors (5xx)
+ */
+declare class MarvinServerError extends MarvinError {
+    readonly endpoint: string;
+    constructor(message: string, statusCode: number, endpoint: string);
+}
 
 /**
  * Pagination response types and helpers
@@ -270,12 +299,31 @@ declare class CollectionsModule {
     list(): Promise<MarvinCollection[]>;
     /**
      * Get a single collection by slug
+     * Returns null if collection is not found (404)
      */
-    get(slug: string): Promise<Collection>;
+    get(slug: string): Promise<Collection | null>;
     /**
      * Get entries in a collection
+     * Returns empty array if collection is not found
      */
     entries(slug: string): Promise<MarvinEntry[]>;
+    /**
+     * 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']);
+     * ```
+     */
+    fallback(slugs: string[], options?: {
+        requireEntries?: boolean;
+    }): Promise<MarvinEntry[]>;
 }
 
 declare class Entry {
@@ -365,8 +413,9 @@ declare class EntriesModule {
     list(options?: GetEntriesOptions): Promise<MarvinEntry[]>;
     /**
      * Get a single entry by slug
+     * Returns null if entry is not found (404)
      */
-    get(slug: string): Promise<Entry>;
+    get(slug: string): Promise<Entry | null>;
     /**
      * Convenience: Get all pages
      */
@@ -465,11 +514,11 @@ declare class MarvinClient {
     /**
      * Get a single entry by slug
      */
-    entry(slug: string): Promise<Entry>;
+    entry(slug: string): Promise<Entry | null>;
     /**
      * Get a single collection by slug
      */
-    collection(slug: string): Promise<Collection>;
+    collection(slug: string): Promise<Collection | null>;
     /**
      * Get all pages
      */
@@ -486,6 +535,23 @@ declare class MarvinClient {
      * Get a single resource by slug
      */
     resource(slug: string): Promise<Resource>;
+    /**
+     * 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']);
+     * ```
+     */
+    collectionFallback(slugs: string[], options?: {
+        requireEntries?: boolean;
+    }): Promise<MarvinEntry[]>;
     /**
      * @deprecated Use workspace.site or marvin.site instead
      * Get site configuration
@@ -500,7 +566,7 @@ declare class MarvinClient {
      * @deprecated Use workspace.entries.get() instead
      * Get a single published entry by slug
      */
-    getEntry(slug: string): Promise<MarvinEntry>;
+    getEntry(slug: string): Promise<MarvinEntry | null>;
     /**
      * @deprecated Use workspace.collections.list() instead
      * Get all collections
@@ -510,7 +576,7 @@ declare class MarvinClient {
      * @deprecated Use workspace.collections.get() instead
      * Get a single collection by slug
      */
-    getCollection(slug: string): Promise<MarvinCollection>;
+    getCollection(slug: string): Promise<MarvinCollection | null>;
     /**
      * @deprecated Use workspace.collections.entries() instead
      * Get all entries in a collection
@@ -621,4 +687,4 @@ declare function createAuthClient(apiUrl: string): AuthClient;
  */
 declare function createMarvinClient(config?: Partial<MarvinConfig>): MarvinClient;
 
-export { AuthClient, type AuthToken, Collection, Entry, type ForgotPasswordRequest, GetResourcesOptions$1 as GetResourcesOptions, HttpClient, type LoginRequest, MarvinApiError, MarvinAsset, MarvinAuthError, MarvinCache, MarvinClient, MarvinCollection, type MarvinConfig, MarvinConfigError, MarvinEntry, MarvinEntryType, MarvinError, MarvinResource, MarvinSite, MarvinValidationError, type PaginatedResponse, type PaginationMeta, type PaginationParams, type ResetPasswordRequest, Resource, type UserRegistration, Workspace, createAuthClient, createConfigFromEnv, createMarvinClient, createPaginatedResponse, extractData, isPaginatedResponse, offsetToPage, pageToOffset };
+export { AuthClient, type AuthToken, Collection, Entry, type ForgotPasswordRequest, GetResourcesOptions$1 as GetResourcesOptions, HttpClient, type LoginRequest, MarvinApiError, MarvinAsset, MarvinAuthError, MarvinCache, MarvinClient, MarvinCollection, type MarvinConfig, MarvinConfigError, MarvinEntry, MarvinEntryType, MarvinError, MarvinNetworkError, MarvinNotFoundError, MarvinResource, MarvinServerError, MarvinSite, MarvinValidationError, type PaginatedResponse, type PaginationMeta, type PaginationParams, type ResetPasswordRequest, Resource, type UserRegistration, Workspace, createAuthClient, createConfigFromEnv, createMarvinClient, createPaginatedResponse, extractData, isPaginatedResponse, offsetToPage, pageToOffset };

package/dist/index.js

@@ -6,6 +6,9 @@ import {
   MarvinCache,
   MarvinConfigError,
   MarvinError,
+  MarvinNetworkError,
+  MarvinNotFoundError,
+  MarvinServerError,
   MarvinValidationError,
   NoAuth,
   SessionAuth,
@@ -15,10 +18,11 @@ import {
   createPaginatedResponse,
   extractData,
   init_core,
+  init_errors,
   isPaginatedResponse,
   offsetToPage,
   pageToOffset
-} from "./chunk-25F3IF6S.js";
+} from "./chunk-DYC2BEA4.js";
 
 // src/client/config.ts
 var config_exports = {};
@@ -27,14 +31,21 @@ __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 parameter 'apiUrl'. Received config keys: ${receivedKeys || "(none)"}. Set this to your MARVIN_API_URL environment variable value.`
+    );
   }
   if (!config.siteClientToken) {
-    throw new Error("MARVIN_SITE_CLIENT_TOKEN is required");
+    throw new Error(
+      `Missing required config parameter 'siteClientToken'. Received config keys: ${receivedKeys}. Set this to your MARVIN_SITE_CLIENT_TOKEN environment variable value.`
+    );
   }
   if (!config.workspaceSlug) {
-    throw new Error("MARVIN_WORKSPACE_SLUG is required");
+    throw new Error(
+      `Missing required config parameter 'workspaceSlug'. Received config keys: ${receivedKeys}. Set this to your MARVIN_WORKSPACE_SLUG environment variable value.`
+    );
   }
 }
 function createConfigFromEnv(overrides) {
@@ -43,8 +54,10 @@ function createConfigFromEnv(overrides) {
     siteClientToken: overrides?.siteClientToken || process.env.MARVIN_SITE_CLIENT_TOKEN || "",
     workspaceSlug: overrides?.workspaceSlug || process.env.MARVIN_WORKSPACE_SLUG || "",
     autoInitialize: overrides?.autoInitialize ?? false,
-    cacheDuration: overrides?.cacheDuration ?? 5 * 60 * 1e3
+    cacheDuration: overrides?.cacheDuration ?? 5 * 60 * 1e3,
     // 5 minutes
+    debug: overrides?.debug ?? process.env.MARVIN_DEBUG === "true",
+    logger: overrides?.logger ?? console
   };
 }
 var init_config = __esm({
@@ -64,7 +77,9 @@ var init_http = __esm({
         super({
           baseUrl: config.apiUrl,
           auth: new BearerTokenAuth(config.siteClientToken),
-          credentials: "same-origin"
+          credentials: "same-origin",
+          debug: config.debug,
+          logger: config.logger
         });
       }
       /**
@@ -201,6 +216,7 @@ var init_entries = __esm({
   "src/entries/entries.ts"() {
     "use strict";
     init_entry();
+    init_errors();
     EntriesModule = class {
       constructor(http, workspaceSlug) {
         this.http = http;
@@ -225,11 +241,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
@@ -335,6 +359,7 @@ var init_collections = __esm({
   "src/collections/collections.ts"() {
     "use strict";
     init_collection();
+    init_errors();
     CollectionsModule = class {
       constructor(http, workspaceSlug) {
         this.http = http;
@@ -352,19 +377,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 [];
+      }
     };
   }
 });
@@ -727,6 +796,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
       // ======================
@@ -750,6 +836,9 @@ var init_marvin = __esm({
        */
       async getEntry(slug) {
         const entry = await this.workspace.entries.get(slug);
+        if (!entry) {
+          return null;
+        }
         return entry.toJSON();
       }
       /**
@@ -765,6 +854,9 @@ var init_marvin = __esm({
        */
       async getCollection(slug) {
         const collection = await this.workspace.collections.get(slug);
+        if (!collection) {
+          return null;
+        }
         return collection.toJSON();
       }
       /**
@@ -888,6 +980,9 @@ export {
   MarvinClient,
   MarvinConfigError,
   MarvinError,
+  MarvinNetworkError,
+  MarvinNotFoundError,
+  MarvinServerError,
   MarvinValidationError,
   NoAuth,
   Resource,

package/dist/platform.cjs

@@ -77,6 +77,40 @@ ${body}` : ""}`;
     return new _MarvinApiError(message, status, endpoint, body);
   }
 };
+var MarvinAuthError = class _MarvinAuthError extends MarvinError {
+  constructor(message, statusCode) {
+    super(message, "AUTH_ERROR", statusCode);
+    this.name = "MarvinAuthError";
+    Object.setPrototypeOf(this, _MarvinAuthError.prototype);
+  }
+};
+var 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;
+};
+var MarvinNetworkError = class _MarvinNetworkError extends MarvinError {
+  constructor(message, originalError) {
+    super(message, "NETWORK_ERROR");
+    this.originalError = originalError;
+    this.name = "MarvinNetworkError";
+    Object.setPrototypeOf(this, _MarvinNetworkError.prototype);
+  }
+  originalError;
+};
+var 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;
+};
 
 // src/core/http/HttpClient.ts
 var HttpClient = class {
@@ -85,12 +119,16 @@ var HttpClient = class {
   defaultHeaders;
   credentials;
   timeout;
+  debug;
+  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;
+    this.debug = config.debug ?? false;
+    this.logger = config.logger ?? console;
   }
   /**
    * Build full URL from endpoint
@@ -132,6 +170,10 @@ var HttpClient = class {
     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,
@@ -141,11 +183,42 @@ var HttpClient = class {
         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}` : ""
+          );
+        }
+        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,
@@ -157,21 +230,28 @@ var HttpClient = class {
       if (!contentType || !contentType.includes("application/json")) {
         return void 0;
       }
-      return await response.json();
+      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}`);
+      }
+      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) {
         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;
     }

package/dist/platform.d.cts

@@ -1,4 +1,4 @@
-import { H as HttpClient } from './HttpClient-CLtgQGXH.cjs';
+import { H as HttpClient } from './HttpClient-BX5Gqd0w.cjs';
 
 interface components {
     schemas: {

package/dist/platform.d.ts

@@ -1,4 +1,4 @@
-import { H as HttpClient } from './HttpClient-CLtgQGXH.js';
+import { H as HttpClient } from './HttpClient-BX5Gqd0w.js';
 
 interface components {
     schemas: {

package/dist/platform.js

@@ -2,7 +2,7 @@ import {
   HttpClient,
   SessionAuth,
   init_core
-} from "./chunk-25F3IF6S.js";
+} from "./chunk-DYC2BEA4.js";
 
 // src/platform/client.ts
 init_core();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inneropen/marvin-sdk",
-  "version": "2.0.0-next.11",
+  "version": "2.0.0-next.13",
   "description": "Official TypeScript SDK for Marvin CMS",
   "type": "module",
   "main": "./dist/index.cjs",