@weaverse/hydrogen 5.7.0 → 5.8.0

package/dist/index.d.mts

@@ -74,7 +74,92 @@ declare class WeaverseClient {
     env: WeaverseClientArgs['env'];
     cache: WeaverseClientArgs['cache'];
     waitUntil: WeaverseClientArgs['waitUntil'];
+    private readonly parsedUrl;
+    private readonly componentsByType;
+    private readonly fetchTimeoutMs;
     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 directFetch;
     private isLocalhost;
     private getApiUrl;
@@ -83,12 +168,7 @@ declare class WeaverseClient {
     }) => Promise<T>;
     loadThemeSettings: (strategy?: AllCacheOptions) => Promise<ThemeSettingsResponse>;
     generateFallbackPage: (message: string) => HydrogenPageData;
-    loadPage: (params?: {
-        type?: PageType;
-        locale?: string;
-        handle?: string;
-        strategy?: AllCacheOptions;
-    }) => Promise<WeaverseLoaderData | null>;
+    loadPage: (params?: LoadPageParams) => Promise<WeaverseLoaderData | null>;
     execComponentLoader: (item: HydrogenComponentData) => Promise<HydrogenComponentData>;
 }
 
@@ -221,7 +301,7 @@ type WeaverseLoaderData = {
     };
     page: HydrogenPageData;
     project: HydrogenProjectType;
-    pageAssignment: HydrogenPageAssignment;
+    pageAssignment?: HydrogenPageAssignment;
 };
 interface HydrogenPageData extends WeaverseProjectDataType {
     id: string;
@@ -271,11 +351,131 @@ type FetchProjectPayload = {
     error?: string;
     [key: string]: any;
 };
+/**
+ * Project identifier value - can be static string or dynamic function.
+ *
+ * **Static String**: Direct project ID reference
+ * ```ts
+ * 'project-abc-123'
+ * ```
+ *
+ * **Synchronous Function**: Returns project ID based on request context
+ * ```ts
+ * () => {
+ *   const host = new URL(request.url).hostname
+ *   return PROJECT_MAP[host] || 'default-project'
+ * }
+ * ```
+ *
+ * **Asynchronous Function**: Async project resolution (must be awaited before passing)
+ * ```ts
+ * async () => {
+ *   return await database.getProjectId(userId)
+ * }
+ * ```
+ */
+type ProjectIdValue = string | (() => string) | (() => Promise<string>);
+/**
+ * Type guard for detecting function-based projectId.
+ *
+ * Used internally by WeaverseClient constructor to determine
+ * if projectId needs evaluation or can be used directly.
+ */
+declare function isProjectIdFunction(projectId: ProjectIdValue | undefined): projectId is (() => string) | (() => Promise<string>);
+/**
+ * Extended WeaverseClient constructor arguments supporting multi-project architecture.
+ *
+ * @example Static project (existing pattern - backward compatible)
+ * ```ts
+ * const weaverse = new WeaverseClient({
+ *   ...hydrogenContext,
+ *   projectId: 'project-default-123'
+ * })
+ * ```
+ *
+ * @example Dynamic project selection (new capability)
+ * ```ts
+ * const weaverse = new WeaverseClient({
+ *   ...hydrogenContext,
+ *   projectId: () => {
+ *     const origin = new URL(request.url).origin
+ *     if (origin === 'https://mystore.se') return process.env.WEAVERSE_PROJECT_SWEDEN!
+ *     if (origin === 'https://mystore.fr') return process.env.WEAVERSE_PROJECT_FRANCE!
+ *     return process.env.WEAVERSE_PROJECT_ID!
+ *   }
+ * })
+ * ```
+ *
+ * **Priority Chain** (highest to lowest):
+ * 1. URL query parameter: `?weaverseProjectId=...` (design mode, preview mode)
+ * 2. Function result (if function provided)
+ * 3. Explicit string value (if string provided)
+ * 4. Environment variable: `WEAVERSE_PROJECT_ID` (Hydrogen env or process.env)
+ * 5. Empty string (triggers validation error in methods)
+ *
+ * **Function Requirements**:
+ * - Must return non-empty string
+ * - Can access request via closure for routing decisions
+ * - Evaluated once per WeaverseClient instance (request-scoped)
+ * - Async functions must be awaited before passing to constructor
+ * - Should handle edge cases (missing headers, invalid domains, etc.)
+ *
+ * **Request Context Access**:
+ * Functions access request via closure from constructor arguments.
+ */
 type WeaverseClientArgs = HydrogenContext & {
+    /**
+     * React components registered with Weaverse CMS.
+     * Each component must have a schema defining its properties and settings.
+     */
     components: HydrogenComponent[];
+    /**
+     * Theme schema defining global theme settings (colors, fonts, layouts).
+     * Used to generate default theme configuration and validate theme data.
+     */
     themeSchema: HydrogenThemeSchema;
+    /**
+     * Incoming HTTP request object from React Router loader.
+     * Provides access to URL, headers, cookies for dynamic routing decisions.
+     */
     request: Request;
+    /**
+     * Hydrogen cache instance for content caching.
+     *Supports multi-tenant caching with project-specific cache keys.
+     */
     cache: Cache;
+    /**
+     * Project identifier for loading content from Weaverse CMS.
+     *
+     * **Value Types**:
+     * - Static string: 'project-123' (existing usage)
+     * - Synchronous function: () => determineProject(request)
+     * - Asynchronous function: async () => await getProject(request) (must be awaited)
+     *
+     * **Backward Compatibility**:
+     * - Optional parameter (defaults to environment variable)
+     * - Existing code without projectId continues to work unchanged
+     *
+     * **Cache Isolation**:
+     * ProjectId is included in cache keys to prevent cross-project content pollution.
+     * Each project's content is cached separately, ensuring multi-tenant isolation.
+     */
+    projectId?: ProjectIdValue;
+    /**
+     * Fetch timeout in milliseconds for API requests.
+     * Defaults to 10000ms (10 seconds) if not specified.
+     * Useful for adjusting based on network conditions or deployment environment.
+     *
+     * @default 10000
+     * @example
+     * ```typescript
+     * new WeaverseClient({
+     *   // ... other args
+     *   fetchTimeoutMs: 5000 // 5 second timeout
+     * })
+     * ```
+     */
+    fetchTimeoutMs?: number;
 };
 type WeaverseProduct = WeaverseResourcePickerData;
 type WeaverseCollection = WeaverseResourcePickerData;
@@ -293,6 +493,8 @@ type ThemeSettingsResponse = {
     theme?: HydrogenThemeSettings;
     schema?: HydrogenThemeSchema;
     publicEnv?: PublicEnv;
+    _error?: string;
+    _loadFailed?: boolean;
 };
 type DirectFetchResponse<T = unknown> = {
     data?: T;
@@ -305,6 +507,14 @@ declare class WeaverseError extends Error {
     readonly context?: Record<string, unknown>;
     constructor(message: string, code?: string, statusCode?: number, context?: Record<string, unknown>);
 }
+/**
+ * Validation result type for project ID validation.
+ * Returns validation status with optional error message.
+ */
+type ProjectIdValidationResult = {
+    valid: boolean;
+    error?: string;
+};
 /**
  * Type guards for response validation
  */
@@ -319,7 +529,20 @@ declare function isThemeSettingsResponse(data: unknown): data is ThemeSettingsRe
  */
 type HydrogenSchemaValidationResult = SchemaValidationResult<HydrogenComponentSchema>;
 /**
- * Type guard to check if a schema is valid
+ * Type guard to check if a schema is valid.
+ * Leverages validation from @weaverse/schema package which provides
+ * comprehensive Zod-based validation with the ElementSchema.
+ *
+ * @param schema - Unknown value to validate
+ * @returns True if schema is a valid HydrogenComponentSchema
+ *
+ * @example
+ * ```typescript
+ * if (isValidHydrogenSchema(userInput)) {
+ *   // userInput is now typed as HydrogenComponentSchema
+ *   console.log(userInput.type)
+ * }
+ * ```
  */
 declare function isValidHydrogenSchema(schema: unknown): schema is HydrogenComponentSchema;
 /**
@@ -370,6 +593,101 @@ declare module '@shopify/hydrogen' {
         PUBLIC_SHOPIFY_INBOX_SHOP_ID: string;
     }
 }
+/**
+ * Parameters for loadPage method supporting route-level project override.
+ *
+ * @example Basic usage (uses client-level project)
+ * ```ts
+ * const weaverseData = await weaverse.loadPage({
+ *   type: 'PRODUCT',
+ *   handle: params.productHandle
+ * })
+ * ```
+ *
+ * @example Route-level project override
+ * ```ts
+ * export async function loader({ params, context }: LoaderFunctionArgs) {
+ *   const { weaverse } = context
+ *
+ *   // Use special campaign project for this route only
+ *   const weaverseData = await weaverse.loadPage({
+ *     type: 'PRODUCT',
+ *     handle: params.productHandle,
+ *     projectId: process.env.WEAVERSE_PROJECT_CAMPAIGN  // Override
+ *   })
+ *
+ *   return { weaverseData }
+ * }
+ * ```
+ */
+type LoadPageParams = {
+    /**
+     * Page type to load from Weaverse CMS.
+     *
+     * Determines which template to use for rendering the page.
+     * Falls back to 'INDEX' if not specified or if page type doesn't exist.
+     *
+     * @default 'INDEX'
+     */
+    type?: PageType;
+    /**
+     * Locale for internationalization.
+     *
+     * Format: IETF BCP 47 language tag (e.g., 'en-US', 'fr-FR', 'de-DE')
+     * Used to load locale-specific content and translations.
+     */
+    locale?: string;
+    /**
+     * Page handle for dynamic pages.
+     *
+     * Identifies specific resource within page type:
+     * - Product handle: 'red-sneakers'
+     * - Collection handle: 'summer-sale'
+     * - Page handle: 'about-us'
+     * - Article handle: 'how-to-style-sneakers'
+     */
+    handle?: string;
+    /**
+     * Cache strategy override for this specific page load.
+     *
+     * Overrides default cache strategy for special use cases:
+     * - Fresh content for checkout pages (no cache)
+     * - Long-lived cache for static pages (1 hour+)
+     * - Short-lived cache for frequently updated content (5 minutes)
+     */
+    strategy?: AllCacheOptions;
+    /**
+     * Optional project override for this specific page load.
+     *
+     * **Precedence**: Route-level projectId takes precedence over client-level projectId.
+     *
+     * **Use Cases**:
+     * - Campaign landing pages with custom content
+     * - VIP customer experiences with dedicated projects
+     * - A/B testing specific pages without changing global config
+     * - Seasonal promotions with limited-time content
+     *
+     * **Validation**:
+     * - Must be non-empty string
+     * - Validated before API call
+     * - Falls back to client-level projectId if undefined
+     * - Does NOT support function (string only)
+     *
+     * **Cache Isolation**:
+     * Override projectId is included in cache key, ensuring separate caches
+     * for different projects even on the same route.
+     *
+     * @example Campaign page override
+     * ```ts
+     * const campaignData = await weaverse.loadPage({
+     *   type: 'PAGE',
+     *   handle: 'summer-sale',
+     *   projectId: process.env.WEAVERSE_PROJECT_CAMPAIGN
+     * })
+     * ```
+     */
+    projectId?: string;
+};
 
 declare let defaultComponents: HydrogenComponent[];
 
@@ -390,8 +708,37 @@ declare function useWeaverseDataContext(): WeaverseDataContext;
  */
 declare function createWeaverseDataContext(matches: UIMatch<unknown, unknown>[]): WeaverseDataContext;
 
-declare function getRequestQueries<T = Record<string, string | boolean>>(request: Request): T;
+/**
+ * Extract and parse query parameters from a request URL.
+ * Supports optional allowlist for security-sensitive applications.
+ *
+ * @param request - The incoming request
+ * @param options - Optional configuration
+ * @param options.allowedKeys - If provided, only these keys will be extracted
+ * @returns Parsed query parameters with type coercion for booleans
+ *
+ * @example
+ * ```typescript
+ * // Extract all params
+ * const queries = getRequestQueries(request)
+ *
+ * // Extract only allowed params (security-sensitive)
+ * const queries = getRequestQueries(request, {
+ *   allowedKeys: ['weaverseProjectId', 'weaverseHost']
+ * })
+ * ```
+ */
+declare function getRequestQueries<T = Record<string, string | boolean>>(request: Request, options?: {
+    allowedKeys?: string[];
+}): T;
 declare function getWeaverseConfigs(request: Request, env: HydrogenEnv): WeaverseProjectConfigs;
+/**
+ * Generate default data from component or theme schema.
+ * Results are memoized using WeakMap for performance.
+ *
+ * @param schema - Component or theme schema
+ * @returns Default data object extracted from schema inputs
+ */
 declare function generateDataFromSchema(schema: HydrogenComponentSchema | HydrogenThemeSchema): Record<string, any>;
 declare function getPreviewData(type: string, components: HydrogenComponent[], weaverseHost: string): WeaverseLoaderData;
 
@@ -428,4 +775,4 @@ declare const IMAGES_PLACEHOLDERS: {
     product_18: string;
 };
 
-export { type AllCacheOptions, type CacheResponseValidator, type ComponentLoaderArgs, type CreateHydrogenSchemaOptions, type DirectFetchResponse, type FetchProjectPayload, type FetchProjectRequestBody, type HydrogenComponent, type HydrogenComponentData, type HydrogenComponentPresets, type HydrogenComponentProps, type HydrogenComponentSchema, type HydrogenElement, type HydrogenPageAssignment, type HydrogenPageData, type HydrogenProjectType, type HydrogenSchemaValidationResult, type HydrogenThemeSchema, type HydrogenThemeSettings, IMAGES_PLACEHOLDERS, type PublicEnv, type RouteLoaderArgs, type ThemeSettingsResponse, type WeaverseArticle, type WeaverseBlog, WeaverseClient, type WeaverseClientArgs, type WeaverseCollection, type WeaverseDataContext, WeaverseError, WeaverseHydrogen, WeaverseHydrogenItem, type WeaverseHydrogenParams, WeaverseHydrogenRoot, type WeaverseI18n, type WeaverseInternal, type WeaverseLoaderData, type WeaverseLoaderRequestInfo, type WeaverseMetaObject, type WeaverseProduct, type WeaverseProjectConfigs, type WeaverseStudioQueries, type WithCacheFetchResponse, createWeaverseDataContext, defaultComponents, generateDataFromSchema, getPreviewData, getRequestQueries, getSelectedProductOptions, getWeaverseConfigs, hasError, isFetchProjectPayload, isThemeSettingsResponse, isValidHydrogenSchema, isWithCacheFetchResponse, registerComponent, useThemeSettings, useWeaverseDataContext, withWeaverse };
+export { type AllCacheOptions, type CacheResponseValidator, type ComponentLoaderArgs, type CreateHydrogenSchemaOptions, type DirectFetchResponse, type FetchProjectPayload, type FetchProjectRequestBody, type HydrogenComponent, type HydrogenComponentData, type HydrogenComponentPresets, type HydrogenComponentProps, type HydrogenComponentSchema, type HydrogenElement, type HydrogenPageAssignment, type HydrogenPageData, type HydrogenProjectType, type HydrogenSchemaValidationResult, type HydrogenThemeSchema, type HydrogenThemeSettings, IMAGES_PLACEHOLDERS, type LoadPageParams, type ProjectIdValidationResult, type ProjectIdValue, type PublicEnv, type RouteLoaderArgs, type ThemeSettingsResponse, type WeaverseArticle, type WeaverseBlog, WeaverseClient, type WeaverseClientArgs, type WeaverseCollection, type WeaverseDataContext, WeaverseError, WeaverseHydrogen, WeaverseHydrogenItem, type WeaverseHydrogenParams, WeaverseHydrogenRoot, type WeaverseI18n, type WeaverseInternal, type WeaverseLoaderData, type WeaverseLoaderRequestInfo, type WeaverseMetaObject, type WeaverseProduct, type WeaverseProjectConfigs, type WeaverseStudioQueries, type WithCacheFetchResponse, createWeaverseDataContext, defaultComponents, generateDataFromSchema, getPreviewData, getRequestQueries, getSelectedProductOptions, getWeaverseConfigs, hasError, isFetchProjectPayload, isProjectIdFunction, isThemeSettingsResponse, isValidHydrogenSchema, isWithCacheFetchResponse, registerComponent, useThemeSettings, useWeaverseDataContext, withWeaverse };