@weaverse/hydrogen 5.8.6 → 5.8.8

package/dist/index.mjs

@@ -914,6 +914,23 @@ var WeaverseClient = class {
     }
     return `${weaverseHost}/api/public/${endpoint}`;
   }
+  /**
+   * Fetch data with caching support for both design mode and production.
+   * Uses direct fetch in design mode, Hydrogen's withCache in production.
+   * Automatically includes projectId in cache key for multi-project isolation.
+   *
+   * @param url - The URL to fetch from
+   * @param options - Fetch options including optional cache strategy
+   * @returns Promise resolving to the fetched data
+   *
+   * @example
+   * ```typescript
+   * const data = await weaverse.fetchWithCache<MyData>(
+   *   'https://api.example.com/data',
+   *   { method: 'POST', body: JSON.stringify({ key: 'value' }) }
+   * )
+   * ```
+   */
   fetchWithCache = async (url, options = {}) => {
     const strategy = options.strategy || CacheCustom(DEFAULT_CACHE_STRATEGY);
     const cacheKey = [
@@ -938,6 +955,19 @@ var WeaverseClient = class {
     }
     return result.data;
   };
+  /**
+   * Load theme settings from Weaverse API with fallback to schema defaults.
+   * Merges remote settings with local theme schema and handles design mode serialization.
+   *
+   * @param strategy - Optional cache strategy override
+   * @returns Promise resolving to theme settings response
+   *
+   * @example
+   * ```typescript
+   * const settings = await weaverse.loadThemeSettings()
+   * const primaryColor = settings.theme.colors?.primary
+   * ```
+   */
   loadThemeSettings = async (strategy) => {
     const defaultThemeSettings = generateDataFromSchema(this.themeSchema);
     try {
@@ -1013,6 +1043,13 @@ var WeaverseClient = class {
       };
     }
   };
+  /**
+   * Generate fallback page with default structure when page data is unavailable.
+   * Used internally when API returns no page or when page needs default content.
+   *
+   * @param message - Custom message to display in the fallback page
+   * @returns HydrogenPageData with single main component containing the message
+   */
   generateFallbackPage = (message) => {
     const rootId = crypto.randomUUID();
     return {
@@ -1028,6 +1065,34 @@ var WeaverseClient = class {
       ]
     };
   };
+  /**
+   * Load page data from Weaverse API with optional route-level project override.
+   * Fetches page content, executes component loaders, and handles empty items fallback.
+   *
+   * @param params - Optional page loading parameters
+   * @param params.type - Page type (HOME, PAGE, PRODUCT, COLLECTION, etc.)
+   * @param params.handle - Page handle for dynamic routes
+   * @param params.locale - Locale override
+   * @param params.projectId - Route-level project ID override (for multi-project)
+   * @param params.strategy - Custom cache strategy override
+   * @returns Promise resolving to page data or null on error
+   *
+   * @example
+   * ```typescript
+   * // Basic usage
+   * const data = await weaverse.loadPage()
+   *
+   * // With page type
+   * const data = await weaverse.loadPage({ type: 'HOME' })
+   *
+   * // Route-level project override
+   * const data = await weaverse.loadPage({
+   *   type: 'PAGE',
+   *   handle: 'about',
+   *   projectId: 'campaign-project-123'
+   * })
+   * ```
+   */
   loadPage = async (params = {}) => {
     try {
       const { request, storefront, basePageRequestBody, basePageConfigs } = this;
@@ -1112,6 +1177,13 @@ var WeaverseClient = class {
       if (!page) {
         page = this.generateFallbackPage("Please add new section to start.");
       }
+      if (page?.items?.length === 0) {
+        page.items.push({
+          type: "main",
+          id: page.rootId || crypto.randomUUID(),
+          data: {}
+        });
+      }
       if (page?.items) {
         const items = page.items;
         page.items = await Promise.all(items.map(this.execComponentLoader));