@swell/apps-sdk 1.0.149 → 1.0.151

package/dist/src/resources.d.ts

@@ -1,6 +1,6 @@
 import type { Swell } from './api';
 import type { ShopifyCompatibility } from './compatibility/shopify';
-import type { SwellData, SwellRecord, SwellCollection, InferSwellCollection, SwellCollectionPages, StorefrontResourceGetter, StorefrontCollectionGetter } from '../types/swell';
+import type { SwellData, SwellRecord, SwellCollection, InferSwellCollection, SwellCollectionPages, StorefrontResourceGetter, StorefrontCollectionGetter, StorefrontSingletonGetter, StorefrontRecordGetter } from '../types/swell';
 export declare const MAX_QUERY_PAGE_LIMIT = 100;
 export declare const DEFAULT_QUERY_PAGE_LIMIT = 15;
 export declare class StorefrontResource<T extends SwellData = SwellData> {
@@ -12,7 +12,6 @@ export declare class StorefrontResource<T extends SwellData = SwellData> {
     constructor(getter?: StorefrontResourceGetter<T>);
     _getProxy(): StorefrontResource<T>;
     _getCollectionResultOrProp(instance: StorefrontResource<T>, prop: string | number): unknown;
-    _transformResult(result?: T | null): T | null | undefined;
     _get(..._args: unknown[]): Promise<T | null | undefined>;
     _setGetter(getter: StorefrontResourceGetter<T>): void;
     _resolve(): Promise<T | null>;
@@ -50,9 +49,9 @@ export declare class SwellStorefrontResource<T extends SwellData = SwellData> ex
     _getProxy(): SwellStorefrontResource<T>;
     getResourceObject(): StorefrontResourceFetcher<T>;
 }
-export declare class SwellStorefrontCollection<T extends SwellCollection<SwellData> = SwellCollection<SwellData>> extends SwellStorefrontResource<T> {
+export declare class SwellStorefrontCollection<T extends SwellData = SwellData> extends SwellStorefrontResource<SwellCollection<T>> {
     length: number;
-    results?: InferSwellCollection<T>[];
+    results?: T[];
     count?: number;
     page?: number;
     pages?: SwellCollectionPages;
@@ -62,30 +61,30 @@ export declare class SwellStorefrontCollection<T extends SwellCollection<SwellDa
     constructor(swell: Swell, collection: string, query?: SwellData, getter?: StorefrontCollectionGetter<T>);
     _getProxy(): SwellStorefrontCollection<T>;
     _initQuery(query: SwellData): SwellData;
-    _defaultGetter(): StorefrontResourceGetter<T>;
-    _get(query?: SwellData): Promise<T | null | undefined>;
+    _defaultGetter(): StorefrontResourceGetter<SwellCollection<T>>;
+    _get(query?: SwellData): Promise<SwellCollection<T> | null | undefined>;
     get size(): Promise<number> | number;
-    [Symbol.iterator](): ArrayIterator<InferSwellCollection<T>> | Promise<ArrayIterator<InferSwellCollection<T>>>;
-    iterator(): ArrayIterator<InferSwellCollection<T>> | Promise<ArrayIterator<InferSwellCollection<T>>>;
+    [Symbol.iterator](): ArrayIterator<T> | Promise<ArrayIterator<T>>;
+    iterator(): ArrayIterator<T> | Promise<ArrayIterator<T>>;
     private makeIterator;
     _clone(newProps?: SwellData): SwellStorefrontCollection<T>;
-    _cloneWithCompatibilityResult<R extends SwellCollection<SwellData> = SwellCollection<SwellData>>(compatibilityGetter: (result: T) => R): SwellStorefrontCollection<R>;
+    _cloneWithCompatibilityResult<R extends SwellData = SwellData>(compatibilityGetter: (result: SwellCollection<T>) => SwellCollection<R>): SwellStorefrontCollection<R>;
 }
 export declare class SwellStorefrontRecord<T extends SwellData = SwellRecord> extends SwellStorefrontResource<T> {
     _id: string;
     _params: SwellData;
-    constructor(swell: Swell, collection: string, id: string, query?: SwellData, getter?: StorefrontResourceGetter<T>);
+    constructor(swell: Swell, collection: string, id: string, query?: SwellData, getter?: StorefrontRecordGetter<T>);
     _getProxy(): SwellStorefrontRecord<T>;
     _defaultGetter(): StorefrontResourceGetter<T>;
     _get(id: string, query?: SwellData): Promise<T | null | undefined>;
 }
 export declare class SwellStorefrontSingleton<T extends SwellData = SwellData> extends SwellStorefrontResource<T> {
-    constructor(swell: Swell, collection: string, getter?: StorefrontResourceGetter<T>);
+    constructor(swell: Swell, collection: string, getter?: StorefrontSingletonGetter<T>);
     _getProxy(): SwellStorefrontSingleton<T>;
     _defaultGetter(): StorefrontResourceGetter<T>;
     _get(): Promise<T | null | undefined>;
 }
-export declare class SwellStorefrontPagination<T extends SwellCollection = SwellCollection> {
+export declare class SwellStorefrontPagination<T extends SwellData = SwellData> {
     _resource: SwellStorefrontCollection<T>;
     count: number;
     page: number;

package/dist/src/theme/theme-loader.d.ts

@@ -1,80 +1,72 @@
-import { ThemeCache } from '../cache';
 import type { Swell } from '@/api';
+import type { PutFilesResult } from '../cache';
 import type { SwellThemeConfig, SwellThemePreload } from 'types/swell';
 /**
- * Responsible for loading a theme.
+ * Responsible for loading and managing theme configurations.
+ * Uses a single batch loading strategy for optimal performance.
  */
 export declare class ThemeLoader {
-    private static cache;
     private swell;
-    private manifest;
     private configs;
-    private configPaths;
     constructor(swell: Swell);
-    init(themeConfigs?: Map<string, SwellThemeConfig>): Promise<void>;
-    /**
-     * Loads theme configs for this version.
-     */
-    loadTheme(): Promise<SwellThemeConfig[]>;
-    /**
-     * Returns the cache instance for this theme loader.
-     */
-    getCache(): ThemeCache;
     /**
-     * Load theme configs from internal data, typically in the editor.
+     * Initialize the theme loader with all configurations.
+     * Either uses provided configs (editor mode) or loads from storage.
      */
-    setConfigs(themeConfigs: Map<string, SwellThemeConfig>): void;
+    init(themeConfigs?: Map<string, SwellThemeConfig>): Promise<void>;
     /**
-     * Preloads a theme version and configs. This is used to optimize initial theme load.
+     * Get a single config by file path (synchronous).
+     * Returns null if config not found.
      */
-    preloadTheme(payload: SwellThemePreload): Promise<void>;
+    getConfig(filePath: string): SwellThemeConfig | null;
     /**
-     * Fetches a theme config by file path.
+     * Get all loaded configs.
+     * Used by theme getter to expose configs to editor/tests.
      */
-    fetchThemeConfig(filePath: string): Promise<SwellThemeConfig | null>;
-    fetchThemeConfigsByPath(pathPrefix: string, pathSuffix?: string): Promise<SwellThemeConfig[]>;
+    getConfigs(): Map<string, SwellThemeConfig>;
     /**
-     * Load all theme configs.
+     * Get multiple configs by path pattern (synchronous).
+     * Filters configs by prefix and optional suffix.
      */
-    private loadThemeAllConfigs;
+    getConfigsByPath(pathPrefix: string, pathSuffix?: string): SwellThemeConfig[];
     /**
-     * Load theme configs via manifest.
-     *
-     * This approach has the following optimizations:
-     *   - cached manifests and configs can be shared by other clients
-     *   - when fetching from source, only fetch the missing records
+     * Load theme configs from internal data, typically in the editor.
+     * Used when configs are provided externally (e.g., from editor).
      */
-    private loadThemeFromManifest;
+    setConfigs(themeConfigs: Map<string, SwellThemeConfig>): void;
     /**
-     * Caches a theme version manifest by hash.
+     * Updates KV with file_data for provided theme configs (warmup path).
+     * Uses the new ThemeFileStorage abstraction for optimized operations.
      */
-    private cacheManifest;
+    updateThemeCache(payload: SwellThemePreload): Promise<PutFilesResult>;
     /**
-     * Caches a theme config by hash.
+     * Main loading logic - loads all configs at once.
+     * 1. Fetches lightweight metadata (cached when possible)
+     * 2. Batch hydrates file_data from KV
+     * 3. Fetches missing file_data from API if needed
      */
-    private cacheThemeConfig;
+    private loadAllConfigs;
     /**
-     * Caches a CDN file url by config hash.
+     * Fetch lightweight config metadata from API or cache.
+     * Does NOT include file_data to minimize payload size.
      */
-    private cacheThemeFileUrl;
+    private fetchConfigMetadata;
     /**
-     * Fetches the manifest (set of config hashes) for a theme version.
+     * Helper to ensure all configs have file_data.
+     * Fetches missing data from API and updates KV cache.
      */
-    private fetchManifest;
+    private ensureConfigsHaveData;
     /**
-     * Fetches many theme configs via Swell Backend API.
+     * Fetches theme configs with file_data from Swell Backend API.
+     * Used to retrieve missing file_data for configs.
      */
     private fetchThemeConfigsFromSource;
     /**
-     * Fetches one theme config via Swell Backend API.
-     * This is used when a hash entry cannot be found.
-     * We may override the cached hash in order to ensure it is found on reload,
-     * but we probably need to find why that happens in the first place (TODO).
+     * Get the current theme ID from headers.
      */
-    private fetchThemeConfigsFromSourceByPath;
     private getThemeId;
     /**
-     * Generates a Swell API query filter for this theme version.
+     * Generate a Swell API query filter for this theme version.
      */
     private themeVersionQueryFilter;
 }

package/dist/src/theme.d.ts

@@ -2,6 +2,7 @@ import { Swell, StorefrontResource, SwellStorefrontCollection, SwellStorefrontRe
 import { ShopifyCompatibility } from './compatibility/shopify';
 import { LiquidSwell, ThemeFont, ThemeForm } from './liquid';
 import { ThemeLoader } from './theme/theme-loader';
+import type { PutFilesResult } from './cache';
 import type { FormatInput } from 'swell-js';
 import type { ThemeGlobals, ThemeConfigs, ThemeSettings, ThemeResources, ThemeFormConfig, ThemeInitGlobalsOptions, ThemeFormErrorMessages, ThemeLocaleConfig, ThemePresetSchema, ThemeSectionGroup, ThemeSectionGroupInfo, ThemeSectionSchema, ThemeSectionConfig, ThemeSectionSettings, ThemeSettingFieldSchema, ThemeSettingSectionSchema, ThemePage, ThemePageSectionSchema, ThemePageTemplateConfig, ThemeLayoutSectionGroupConfig, SwellData, SwellMenu, SwellRecord, SwellAppConfig, SwellThemeConfig, SwellThemePreload, SwellAppStorefrontThemeProps, SwellAppShopifyCompatibilityConfig, SwellPageRequest, SwellSettingsGeo } from '../types/swell';
 export declare class SwellTheme {
@@ -12,7 +13,6 @@ export declare class SwellTheme {
     resources?: ThemeResources;
     liquidSwell: LiquidSwell;
     themeLoader: ThemeLoader;
-    themeConfigs: Map<string, SwellThemeConfig> | null;
     page?: ThemePage;
     pageId: string | undefined;
     shopifyCompatibility: ShopifyCompatibility | null;
@@ -28,6 +28,16 @@ export declare class SwellTheme {
         globals?: ThemeGlobals;
         shopifyCompatibilityClass?: typeof ShopifyCompatibility;
     });
+    /**
+     * Getter for theme configs - returns the configs from the loader.
+     * Used by editor and tests to access loaded configs.
+     */
+    get themeConfigs(): Map<string, SwellThemeConfig> | null;
+    /**
+     * Setter for theme configs - directly sets configs in the loader.
+     * Used by editor and tests to inject configs without API/KV loading.
+     */
+    set themeConfigs(configs: Map<string, SwellThemeConfig> | null);
     getSwellAppThemeProps(swellConfig?: SwellAppConfig): SwellAppStorefrontThemeProps;
     initGlobals(pageId: string, options?: ThemeInitGlobalsOptions): Promise<void>;
     setGlobals(globals: Partial<ThemeGlobals>): void;
@@ -106,15 +116,20 @@ export declare class SwellTheme {
     resolveFontSetting(value: string): ThemeFont;
     resolveUrlSetting(value: string): string;
     resolveImageSetting(value: string): string;
-    getAllThemeConfigs(): Promise<Map<string, SwellThemeConfig>>;
-    /**
-     * Preloads updated theme configs. Used to optimize initial theme load.
-     */
-    preloadThemeConfigs(payload: SwellThemePreload): Promise<void>;
+    preloadThemeConfigs(payload: SwellThemePreload): Promise<PutFilesResult>;
     getPageConfigPath(pageId: string, altTemplate?: string): string | null;
     getThemeConfig(filePath: string): Promise<SwellThemeConfig | null>;
-    getThemeConfigsByPath(pathPrefix: string, pathSuffix?: string): Promise<Map<string, SwellThemeConfig>>;
+    getThemeConfigsByPath(pathPrefix: string, pathSuffix?: string): Map<string, SwellThemeConfig>;
     getThemeTemplateConfig(filePath: string): Promise<SwellThemeConfig | null>;
+    /**
+     * Internal synchronous helper for getting template configs by type.
+     * Used internally within theme.ts to avoid async overhead.
+     */
+    private _getTemplateConfigByType;
+    /**
+     * Internal synchronous helper for getting template configs.
+     */
+    private _getTemplateConfig;
     getThemeTemplateConfigByType(type: string, name: string, suffix?: string): Promise<SwellThemeConfig | null>;
     getAssetConfig(assetName: string): Promise<SwellThemeConfig | null>;
     getAssetUrl(filePath: string): Promise<string | null>;

package/dist/src/utils/index.d.ts

@@ -2,6 +2,7 @@ import { CURRENCY_COUNTRIES } from '../constants';
 import type { SwellData, SwellLocale, SwellThemeConfig, ThemeLayoutSectionGroupConfig, ThemePageSectionSchema, ThemeSectionConfig, ThemeSectionGroup, ThemeSectionSchema, ThemeSettings } from 'types/swell';
 export * from './md5';
 export { configureSdkLogger, type SdkLoggerConfig } from './logger';
+export { getKVFlavor, resetKVFlavorCache } from './kv-flavor';
 export declare function getAllSections(themeConfigs: Map<string, SwellThemeConfig>, renderTemplateSchema: (config: SwellThemeConfig) => Promise<ThemeSectionSchema | undefined>): Promise<ThemePageSectionSchema[]>;
 export declare function getLayoutSectionGroups(allSections: Map<string, SwellThemeConfig>, renderTemplateSchema: (config: SwellThemeConfig) => Promise<Partial<ThemeSectionSchema> | undefined>): Promise<ThemeLayoutSectionGroupConfig[]>;
 export declare function getPageSections(sectionGroup: ThemeSectionGroup, getSchema: (type: string) => Promise<Partial<ThemeSectionSchema> | undefined>): Promise<ThemeSectionConfig[]>;

package/dist/src/utils/kv-flavor.d.ts

@@ -0,0 +1,7 @@
+import type { KVFlavor } from '../cache';
+import type { CFThemeEnv } from '../../types/cloudflare';
+/**
+ * Get KV storage flavor. Priority: KV_FLAVOR env var > auto-detection > miniflare default
+ */
+export declare function getKVFlavor(workerEnv?: CFThemeEnv): KVFlavor;
+export declare function resetKVFlavorCache(): void;

package/dist/types/cloudflare.d.ts

@@ -4,15 +4,16 @@ export interface CFWorkerContext {
 }
 export interface CFThemeEnv {
     THEME?: CFWorkerKV;
+    KV_FLAVOR?: string;
 }
 export type CFWorkerKVGetType = 'text' | 'json' | 'arrayBuffer' | 'stream';
 export interface CFWorkerKVGetOptions<T extends CFWorkerKVGetType> {
-    cacheTtl: number;
-    type: T;
+    cacheTtl?: number;
+    type?: T;
 }
 export interface CFWorkerKVGetMetadataResponse<T> {
     value: T | null;
-    metadata: string | null;
+    metadata: string | Record<string, unknown> | null;
 }
 export interface CFWorkerKVPutOptions {
     expiration?: number;
@@ -39,10 +40,20 @@ export interface CFWorkerKV {
     get(key: string, type?: 'arrayBuffer', options?: CFWorkerKVGetOptions<'arrayBuffer'>): Promise<ArrayBuffer | null>;
     get(key: string, type?: 'stream', options?: CFWorkerKVGetOptions<'stream'>): Promise<ReadableStream<Uint8Array> | null>;
     get<T>(key: string, type?: 'json', options?: CFWorkerKVGetOptions<'json'>): Promise<T | null>;
+    get(keys: string[], type?: 'text', options?: CFWorkerKVGetOptions<'text'>): Promise<Map<string, string | null>>;
+    get(keys: string[], type?: 'json', options?: CFWorkerKVGetOptions<'json'>): Promise<Map<string, object | null>>;
     getWithMetadata(key: string, type?: 'text', options?: CFWorkerKVGetOptions<'text'>): Promise<CFWorkerKVGetMetadataResponse<string>>;
     getWithMetadata(key: string, type?: 'arrayBuffer', options?: CFWorkerKVGetOptions<'arrayBuffer'>): Promise<CFWorkerKVGetMetadataResponse<ArrayBuffer>>;
     getWithMetadata(key: string, type?: 'stream', options?: CFWorkerKVGetOptions<'stream'>): Promise<CFWorkerKVGetMetadataResponse<ReadableStream<Uint8Array>>>;
     getWithMetadata<T>(key: string, type?: 'json', options?: CFWorkerKVGetOptions<'json'>): Promise<CFWorkerKVGetMetadataResponse<T>>;
+    getWithMetadata(keys: string[], type?: 'text', options?: CFWorkerKVGetOptions<'text'>): Promise<Map<string, {
+        value: string | null;
+        metadata: string | Record<string, unknown> | null;
+    }>>;
+    getWithMetadata(keys: string[], type?: 'json', options?: CFWorkerKVGetOptions<'json'>): Promise<Map<string, {
+        value: object | null;
+        metadata: string | Record<string, unknown> | null;
+    }>>;
     put(key: string, value: string | ReadableStream | ArrayBuffer, options?: CFWorkerKVPutOptions): Promise<void>;
     delete(key: string): Promise<void>;
     list(options?: CFWorkerKVListOptions): Promise<CFWorkerKVListResponse>;

package/dist/types/shopify.d.ts

@@ -1,4 +1,4 @@
-import type { SwellData, SwellCollection, ThemeSectionEnabledDisabled } from './swell';
+import type { SwellData, ThemeSectionEnabledDisabled } from './swell';
 import type { ShopifyResource } from '../src/compatibility/shopify-objects/resource';
 import type { ShopifyCompatibility } from '../src/compatibility/shopify';
 import type { StorefrontResource, SwellStorefrontCollection } from '../src/resources';
@@ -446,7 +446,7 @@ export interface ShopifyCollection {
     metafields: Record<string, unknown>;
     next_product?: ShopifyProduct;
     previous_product?: ShopifyProduct;
-    products: SwellStorefrontCollection<SwellCollection<ShopifyResource<ShopifyProduct>>>;
+    products: SwellStorefrontCollection<ShopifyResource<ShopifyProduct>>;
     products_count: number;
     published_at: string;
     sort_by?: string;

package/dist/types/swell.d.ts

@@ -245,7 +245,9 @@ export interface SwellMenuItem {
 }
 export type QueryParams = import('qs').ParsedQs;
 export type StorefrontResourceGetter<T extends SwellData = SwellData> = (this: SwellStorefrontResource<T>) => Promise<T | null> | T | null;
-export type StorefrontCollectionGetter<T extends SwellCollection<SwellData> = SwellCollection<SwellData>> = (this: SwellStorefrontCollection<T>) => Promise<T | null> | T | null;
+export type StorefrontRecordGetter<T extends SwellData = SwellData> = (this: SwellStorefrontRecord<T>) => Promise<T | null> | T | null;
+export type StorefrontSingletonGetter<T extends SwellData = SwellData> = (this: SwellStorefrontSingleton<T>) => Promise<T | null> | T | null;
+export type StorefrontCollectionGetter<T extends SwellData = SwellData> = (this: SwellStorefrontCollection<T>) => Promise<SwellCollection<T> | null> | SwellCollection<T> | null;
 export interface ThemeSettings {
     [key: string]: any;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@swell/apps-sdk",
   "type": "module",
-  "version": "1.0.149",
+  "version": "1.0.151",
   "description": "Swell SDK for building isomorphic apps.",
   "author": "Swell",
   "license": "MIT",