@weaverse/hydrogen 5.17.0 → 5.18.0

package/dist/types/weaverse-client.d.ts

@@ -0,0 +1,227 @@
+import { createWithCache } from '@shopify/hydrogen';
+import type { CachingStrategy, CustomPageEntry, FetchProjectRequestBody, HydrogenComponentData, HydrogenPageData, LoadPageParams, ThemeSettingsResponse, WeaverseClientArgs, WeaverseLoaderData, WeaverseProjectConfigs } from './types';
+/** Builder API resource whose freshness policy should be used for a request. */
+export type BuilderApiCacheTarget = 'custom-pages' | 'merchant-overrides' | 'project' | 'theme-settings';
+/** Fetch options accepted by {@link WeaverseClient.fetchWithCache}. */
+export interface WeaverseFetchWithCacheOptions extends RequestInit {
+    /** Builder API resource whose default freshness policy should be used. */
+    cacheTarget?: BuilderApiCacheTarget;
+    /** Explicit Hydrogen caching strategy overriding the resource default. */
+    strategy?: CachingStrategy;
+}
+/** Pagination and locale options for {@link WeaverseClient.fetchCustomPages}. */
+export interface FetchCustomPagesOptions {
+    /** Maximum number of custom pages requested per API page. */
+    limit?: number;
+    /** Locale whose published custom pages should be returned. */
+    locale?: string;
+}
+/**
+ * Request-scoped client for loading Weaverse pages and theme settings in Hydrogen.
+ *
+ * Create one client from the Hydrogen app context, then call
+ * {@link WeaverseClient.loadPage} from route loaders and
+ * {@link WeaverseClient.loadThemeSettings} from the root loader.
+ */
+export declare class WeaverseClient {
+    /** Builder API version used by this client. */
+    API: "v1";
+    /** Stable project configuration shared by page requests. */
+    basePageConfigs: Omit<WeaverseProjectConfigs, 'requestInfo'>;
+    /** Stable request body fields shared by page requests. */
+    basePageRequestBody: Omit<FetchProjectRequestBody, 'url'>;
+    /** Resolved project and rendering-mode configuration. */
+    configs: WeaverseProjectConfigs;
+    /** Hydrogen cache wrapper used for Builder API requests. */
+    withCache: ReturnType<typeof createWithCache>;
+    /** Incoming request associated with this client instance. */
+    request: WeaverseClientArgs['request'];
+    /** Hydrogen customer-account client, when configured. */
+    customerAccount: WeaverseClientArgs['customerAccount'];
+    /** Hydrogen Storefront API client and locale context. */
+    storefront: WeaverseClientArgs['storefront'];
+    /** Components registered for page rendering and component loaders. */
+    components: WeaverseClientArgs['components'];
+    /** Theme schema used for defaults and Studio editing. */
+    themeSchema: WeaverseClientArgs['themeSchema'];
+    /** Hydrogen runtime environment variables. */
+    env: WeaverseClientArgs['env'];
+    /** Cache storage supplied by the Hydrogen runtime. */
+    cache: WeaverseClientArgs['cache'];
+    /** Background execution hook supplied by the Oxygen runtime. */
+    waitUntil: WeaverseClientArgs['waitUntil'];
+    private readonly parsedUrl;
+    private readonly componentsByType;
+    private readonly fetchTimeoutMs;
+    /** Creates a request-scoped client from the Hydrogen app context. */
+    constructor(args: WeaverseClientArgs);
+    /**
+     * Initialize Hydrogen cache with proper configuration.
+     * Logs warning if waitUntil is missing.
+     */
+    private initializeCache;
+    /**
+     * Initialize configs with projectId resolution and fail-fast validation.
+     * Throws WeaverseError if projectId cannot be resolved.
+     */
+    private initializeConfigs;
+    /**
+     * Build component lookup map for O(1) access by type.
+     * Significantly improves performance for large component lists.
+     */
+    private buildComponentLookupMap;
+    /**
+     * Extract comprehensive error information from unknown error type.
+     * Preserves error context, codes, and stack traces for debugging.
+     *
+     * @param error - Unknown error to extract information from
+     * @returns Structured error information with message, code, stack, and context
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   // ... operation
+     * } catch (error) {
+     *   const errorInfo = this.extractErrorInfo(error)
+     *   console.error('Operation failed:', errorInfo.message, errorInfo.context)
+     * }
+     * ```
+     */
+    private extractErrorInfo;
+    /**
+     * Extract error message only (for backward compatibility).
+     * Use extractErrorInfo() for more detailed error information.
+     *
+     * @deprecated Use extractErrorInfo() instead to preserve error context
+     */
+    private extractErrorMessage;
+    /**
+     * Validates projectId format (alphanumeric, hyphens, underscores only).
+     * Returns detailed validation result with error message.
+     *
+     * @param projectId - Project identifier to validate
+     * @returns Validation result with error message if invalid
+     */
+    private validateProjectId;
+    /**
+     * Resolves projectId with multi-project architecture support.
+     * Uses priority chain to determine the correct project ID.
+     *
+     * @param projectId - Project identifier (string, function, or undefined)
+     * @param request - HTTP request for context access
+     * @param env - Hydrogen environment with variables
+     * @param baseConfigs - Pre-fetched base configs to avoid duplicate calls
+     * @returns Resolved project ID string (empty string if none found)
+     */
+    private resolveProjectIdSync;
+    /**
+     * Priority 1: Resolve projectId from URL query parameters.
+     * Used for design mode and preview mode overrides.
+     */
+    private resolveFromQueryParams;
+    /**
+     * Priority 2: Resolve projectId from function parameter.
+     * Detects and rejects async functions with helpful error.
+     */
+    private resolveFromFunction;
+    /**
+     * Priority 3: Resolve projectId from explicit string parameter.
+     */
+    private resolveFromString;
+    /**
+     * Priority 4: Resolve projectId from environment variables.
+     */
+    private resolveFromEnvironment;
+    /**
+     * Helper method for direct fetching in design mode.
+     * Returns same format as withCache.fetch for consistency.
+     * Includes 10-second timeout to prevent hanging requests.
+     */
+    private readonly fetchOnce;
+    private readonly directFetch;
+    private getApiUrl;
+    private isExternalPublicApiUrl;
+    /**
+     * 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: <T = unknown>(url: string, options?: WeaverseFetchWithCacheOptions) => Promise<T>;
+    /**
+     * 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: (strategy?: CachingStrategy) => Promise<ThemeSettingsResponse>;
+    /**
+     * Fetch locale-specific merchant overrides from the translation API.
+     * Returns a nested JSON object with translated values.
+     * Falls back to empty object on error to avoid blocking theme rendering.
+     */
+    private fetchMerchantOverrides;
+    /**
+     * 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: string) => HydrogenPageData;
+    /**
+     * Fetch all published custom pages for sitemap generation.
+     * Paginates automatically, never throws, returns accumulated results on partial failure.
+     */
+    fetchCustomPages(opts?: FetchCustomPagesOptions): Promise<CustomPageEntry[]>;
+    /**
+     * 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 (INDEX, 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: 'INDEX' })
+     *
+     * // Route-level project override
+     * const data = await weaverse.loadPage({
+     *   type: 'PAGE',
+     *   handle: 'about',
+     *   projectId: 'campaign-project-123'
+     * })
+     * ```
+     */
+    loadPage: (params?: LoadPageParams) => Promise<WeaverseLoaderData | null>;
+    /** Executes the registered loader for one component and attaches its result. */
+    execComponentLoader: (item: HydrogenComponentData) => Promise<HydrogenComponentData>;
+}
+//# sourceMappingURL=weaverse-client.d.ts.map

package/dist/types/weaverse-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"weaverse-client.d.ts","sourceRoot":"","sources":["../../src/weaverse-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,eAAe,EAGhB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EAEf,uBAAuB,EAEvB,qBAAqB,EACrB,gBAAgB,EAChB,cAAc,EAGd,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EAGvB,MAAM,SAAS,CAAA;AA6EhB,gFAAgF;AAChF,MAAM,MAAM,qBAAqB,GAC7B,cAAc,GACd,oBAAoB,GACpB,SAAS,GACT,gBAAgB,CAAA;AAEpB,uEAAuE;AACvE,MAAM,WAAW,6BAA8B,SAAQ,WAAW;IAChE,0EAA0E;IAC1E,WAAW,CAAC,EAAE,qBAAqB,CAAA;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,eAAe,CAAA;CAC3B;AAED,iFAAiF;AACjF,MAAM,WAAW,uBAAuB;IACtC,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAcD;;;;;;GAMG;AACH,qBAAa,cAAc;IACzB,+CAA+C;IAC/C,GAAG,OAAW;IACd,4DAA4D;IAC5D,eAAe,EAAE,IAAI,CAAC,sBAAsB,EAAE,aAAa,CAAC,CAAA;IAC5D,0DAA0D;IAC1D,mBAAmB,EAAE,IAAI,CAAC,uBAAuB,EAAE,KAAK,CAAC,CAAA;IACzD,yDAAyD;IACzD,OAAO,EAAE,sBAAsB,CAAA;IAC/B,4DAA4D;IAC5D,SAAS,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC,CAAA;IAE7C,6DAA6D;IAC7D,OAAO,EAAE,kBAAkB,CAAC,SAAS,CAAC,CAAA;IACtC,yDAAyD;IACzD,eAAe,EAAE,kBAAkB,CAAC,iBAAiB,CAAC,CAAA;IACtD,yDAAyD;IACzD,UAAU,EAAE,kBAAkB,CAAC,YAAY,CAAC,CAAA;IAC5C,sEAAsE;IACtE,UAAU,EAAE,kBAAkB,CAAC,YAAY,CAAC,CAAA;IAC5C,yDAAyD;IACzD,WAAW,EAAE,kBAAkB,CAAC,aAAa,CAAC,CAAA;IAC9C,8CAA8C;IAC9C,GAAG,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAA;IAC9B,sDAAsD;IACtD,KAAK,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAA;IAClC,gEAAgE;IAChE,SAAS,EAAE,kBAAkB,CAAC,WAAW,CAAC,CAAA;IAG1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAK;IAC/B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAgC;IAGjE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAQ;IAEvC,qEAAqE;gBACzD,IAAI,EAAE,kBAAkB;IAuBpC;;;OAGG;IACH,OAAO,CAAC,eAAe;IAcvB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAsDzB;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAM/B;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,gBAAgB;IA2BxB;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAoBzB;;;;;;;;;OASG;IACH,OAAO,CAAC,oBAAoB;IAe5B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAK9B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IA4D3B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAwBzB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAc9B;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAsDzB;IAED,OAAO,CAAC,QAAQ,CAAC,WAAW,CAoB3B;IAGD,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,sBAAsB;IAQ9B;;;;;;;;;;;;;;;;OAgBG;IACI,cAAc,GAAU,CAAC,GAAG,OAAO,EACxC,KAAK,MAAM,EACX,UAAS,6BAAkC,KAC1C,OAAO,CAAC,CAAC,CAAC,CAkDZ;IAED;;;;;;;;;;;;OAYG;IACH,iBAAiB,GACf,WAAW,eAAe,KACzB,OAAO,CAAC,qBAAqB,CAAC,CA8GhC;IAED;;;;OAIG;IACH,OAAO,CAAC,sBAAsB,CAqD7B;IAED;;;;;;OAMG;IACH,oBAAoB,GAAI,SAAS,MAAM,KAAG,gBAAgB,CAczD;IAED;;;OAGG;IACG,gBAAgB,CACpB,IAAI,CAAC,EAAE,uBAAuB,GAC7B,OAAO,CAAC,eAAe,EAAE,CAAC;IAmD7B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,QAAQ,GACN,SAAQ,cAAmB,KAC1B,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAgLpC;IAED,gFAAgF;IAChF,mBAAmB,GAAU,MAAM,qBAAqB,oCAqBvD;CACF"}

package/package.json

@@ -2,10 +2,10 @@
   "name": "@weaverse/hydrogen",
   "author": "Weaverse Team",
   "description": "Components, hooks, and utilities for building Shopify Hydrogen websites with Weaverse",
-  "version": "5.17.0",
+  "version": "5.18.0",
   "license": "MIT",
   "main": "dist/index.js",
-  "typings": "dist/index.d.ts",
+  "typings": "dist/types/index.d.ts",
   "module": "dist/index.mjs",
   "publishConfig": {
     "access": "public",
@@ -16,14 +16,15 @@
     "directory": "packages/hydrogen"
   },
   "files": [
-    "dist/*"
+    "dist",
+    "src"
   ],
   "engines": {
     "node": ">=20"
   },
   "scripts": {
     "dev": "tsup --watch",
-    "build": "tsup",
+    "build": "tsup && node ../../scripts/build-declarations.mjs",
     "clean": "rimraf dist",
     "test": "vp test --run",
     "typecheck": "tsc --noEmit"
@@ -45,8 +46,8 @@
   "dependencies": {
     "@shopify/hydrogen": ">=2025.5",
     "@shopify/remix-oxygen": "3",
-    "@weaverse/react": "5.17.0",
-    "@weaverse/schema": "0.11.0",
+    "@weaverse/react": "5.18.0",
+    "@weaverse/schema": "0.12.0",
     "react": ">=19",
     "react-dom": ">=19",
     "react-error-boundary": "^6",