@swell/apps-sdk 1.0.142 → 1.0.144

package/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2025-present Swell Commerce Corp.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, sell and/or create
+derivative works of the Software or any part thereof, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The rights granted above may only be exercised to develop storefront apps that integrate
+or interoperate with Swell software or services, and, if applicable, to
+distribute, offer for sale or otherwise make available any such storefront apps via the Swell App Store. All other uses of the Software are strictly prohibited.
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR
+A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,304 @@
+# Swell Apps SDK
+
+The Swell Apps SDK is a TypeScript-based library designed to simplify the development of isomorphic Swell apps by providing streamlined API access, theme rendering capabilities, and comprehensive caching solutions.
+
+## Features
+
+### Core functionality
+- **Unified API access** - Seamless integration with both Swell Backend API and Storefront API
+- **Authentication handling** - Automatic scoped access token management based on app permissions
+- **Theme rendering** - Complete Shopify-compatible theme system with Liquid templating
+- **Resource management** - Deferred loading of storefront resources (products, categories, etc.)
+- **Caching system** - Multi-tier caching with Cloudflare KV integration
+- **Shopify compatibility** - Full compatibility layer for migrating Shopify themes and apps
+
+### Theme capabilities
+- **Liquid templating** - Enhanced Liquid engine with Swell-specific objects and filters
+- **Section rendering** - Dynamic section management with schema support
+- **Settings resolution** - Automatic theme and section settings processing
+- **Layout system** - Flexible layout rendering with section groups
+- **Asset management** - Optimized asset loading and URL generation
+- **Localization** - Multi-language support with translation rendering
+
+### Developer experience
+- **TypeScript support** - Full type safety with comprehensive type definitions
+- **Isomorphic design** - Works seamlessly in both browser and server environments
+- **Error handling** - Robust error management with detailed debugging information
+- **Performance optimized** - Built-in caching and resource optimization
+- **Extensible architecture** - Plugin system for custom resource types
+
+## Installation
+
+```bash
+npm install @swell/apps-sdk
+```
+
+## Getting started
+
+### Basic setup
+
+```typescript
+import { Swell } from '@swell/apps-sdk';
+
+// Initialize Swell instance in your app frontend
+const swell = new Swell({
+  serverHeaders: context.request.headers, // Headers from worker environment
+});
+
+// Make backend API calls
+const products = await swell.backend.get('/products');
+
+// Make storefront API calls
+const cart = await swell.storefront.get('/cart');
+```
+
+### Headers and app proxying
+
+When your Swell app is deployed, it runs behind Swell's proxy infrastructure. The proxy automatically injects essential headers that contain authentication tokens, store configuration, and storefront context. These headers are critical for the SDK to function properly:
+
+```typescript
+// Headers passed from Swell's proxy contain:
+// - swell-store-id: The store identifier
+// - swell-public-key: Frontend API access key
+// - swell-access-token: Backend API access token (scoped to app permissions)
+// - swell-storefront-id: Current storefront instance
+// - swell-environment-id: Environment (development, staging, production)
+// - swell-theme-id: Active theme identifier
+// - swell-storefront-context: Preloaded cart/account data
+
+const swell = new Swell({
+  serverHeaders: context.request.headers, // Contains all proxy-injected headers
+  getCookie: (name) => getCookieValue(name),
+  setCookie: (name, value, options) => setCookieValue(name, value, options),
+});
+```
+
+Without these headers, the SDK cannot:
+- Authenticate with Swell APIs
+- Determine which store and storefront to operate on
+- Access cached resources or maintain session state
+- Render themes with proper configuration
+
+The `serverHeaders` parameter should always be passed the complete headers object from your app's request context to ensure full functionality.
+
+### Theme rendering
+
+```typescript
+import { Swell, SwellTheme, SwellProduct } from '@swell/apps-sdk';
+
+const swell = new Swell({
+  serverHeaders: context.request.headers,
+  ...options,
+});
+
+// Initialize theme with optional configuration
+const theme = new SwellTheme(swell, {
+  forms: formConfigs,
+  resources: customResources,
+  globals: additionalGlobals,
+});
+
+// Fetch settings and set global context
+await theme.initGlobals('product'); // page ID
+
+// Create page data with deferred resource loading
+const data = {
+  product: new SwellProduct(swell, context.params.id),
+};
+
+// Render theme page
+const renderedPage = await theme.renderPage(data);
+```
+
+## API reference
+
+### Swell class
+
+The main entry point for SDK functionality:
+
+```typescript
+class Swell {
+  // API access
+  backend: SwellBackendAPI;
+  storefront: typeof SwellJS;
+  
+  // Configuration
+  config: SwellAppConfig;
+  url: URL;
+  headers: Record<string, string>;
+  queryParams: ParsedQs;
+  
+  // State
+  isEditor: boolean;
+  isPreview: boolean;
+  storefrontContext: SwellData;
+  
+  // Methods
+  get<T>(url: string, query?: SwellData): Promise<T>;
+  post<T>(url: string, data: SwellData): Promise<T>;
+  put<T>(url: string, data: SwellData): Promise<T>;
+  delete<T>(url: string, data?: SwellData): Promise<T>;
+  getCachedResource<T>(key: string, args: unknown[], handler: () => T, isCacheble = true): Promise<T>;
+}
+```
+
+### SwellTheme class
+
+Handles theme rendering and management:
+
+```typescript
+class SwellTheme {
+  // Core properties
+  swell: Swell;
+  globals: ThemeGlobals;
+  liquidSwell: LiquidSwell;
+  
+  // Methods
+  initGlobals(pageId: string, altTemplate?: string): Promise<void>;
+  renderPage(pageData?: SwellData, altTemplate?: string): Promise<string>;
+  renderSection(sectionId: string, pageData?: SwellData): Promise<string>;
+  renderLayout(layoutName?: string, data?: SwellData): Promise<string>;
+  getSectionSchema(sectionName: string): Promise<ThemeSectionSchema>;
+  setGlobals(globals: Partial<ThemeGlobals>): void;
+}
+```
+
+### Resource classes
+
+Built-in storefront resource classes for deferred loading:
+
+#### Standard resources
+- `SwellAccount` - Customer account management
+- `SwellBlog` - Blog post content
+- `SwellBlogCategory` - Blog categorization
+- `SwellCart` - Shopping cart state
+- `SwellCategory` - Product categories
+- `SwellOrder` - Order information
+- `SwellPage` - Static pages
+- `SwellProduct` - Product details
+- `SwellVariant` - Product variants
+
+#### Primitive resources
+- `SwellStorefrontCollection` - Collection results with pagination
+- `SwellStorefrontRecord` - Individual records
+- `SwellStorefrontSingleton` - Unique resources (cart, account)
+
+```typescript
+// Create custom resource class
+class MyAppCollection extends SwellStorefrontCollection {
+  constructor(swell: Swell, query: SwellData = {}) {
+    super(swell, 'my-app-collection', query);
+    return this._getProxy();
+  }
+}
+
+// Usage in theme data
+const data = {
+  myCollection: new MyAppCollection(swell, { limit: 20 }),
+};
+```
+
+## Caching
+
+### Memory caching
+Resources are automatically cached in memory per worker instance:
+
+```typescript
+// Cached resource with custom handler
+const cachedData = await swell.getCachedResource(
+  'expensive-operation',
+  [param1, param2],
+  async () => {
+    return await performExpensiveOperation(param1, param2);
+  }
+);
+```
+
+### Cloudflare KV caching
+For production scalability, enable KV caching:
+
+```typescript
+const swell = new Swell({
+  serverHeaders: context.request.headers,
+  workerEnv: context.locals.runtime.env, // Contains THEME KV binding
+  workerCtx: context.locals.runtime.ctx,  // Worker context
+});
+```
+
+### Cache invalidation
+Caches are automatically invalidated based on:
+- Session cookies (for cart/account data)
+- Theme configuration versions
+- Storefront environment changes
+
+## Shopify compatibility
+
+The SDK includes comprehensive Shopify compatibility for theme migration.
+
+### Supported Shopify features
+- **Template mapping** - Direct file path compatibility
+- **Liquid objects** - Full object structure compatibility
+- **Form handling** - Compatible form endpoints and validation
+- **Section schemas** - Shopify section configuration format
+- **Settings data** - `settings_data.json` and `settings_schema.json`
+
+## Liquid templating
+
+Enhanced Liquid templating with Swell-specific features. See [Swell Liquid documentation](https://developers.swell.is/storefronts/swell-liquid-reference) for details.
+
+## Performance optimization
+
+### Lazy loading
+Resources are loaded only when accessed in templates:
+
+```liquid
+<!-- Product data is fetched only when this line executes -->
+{{ product.name }}
+
+<!-- Collection is fetched only when iteration begins -->
+{% for item in collection.products %}
+  {{ item.name }}
+{% endfor %}
+```
+
+## Development
+
+### Building the SDK
+```bash
+# Install dependencies
+npm install
+
+# Build for production
+npm run build
+
+# Watch for changes
+npm run watch
+
+# Run tests
+npm test
+```
+
+### Project structure
+```
+src/
+├── api.ts              # Core Swell class and API handling
+├── theme.ts            # SwellTheme class and rendering
+├── resources.ts        # Storefront resource classes
+├── liquid/             # Liquid templating engine
+├── compatibility/      # Shopify compatibility layer
+├── cache/              # Caching implementations
+├── utils/              # Utility functions
+└── index.ts            # Main exports
+```
+
+## Resources
+
+- [Swell Documentation](https://developers.swell.is/)
+- [Apps Development Guide](https://developers.swell.is/apps/overview)
+- [Proxima Example App](https://developers.swell.is/storefronts/proxima)
+- [Swell Liquid Reference](https://developers.swell.is/storefronts/swell-liquid-reference)
+- [GitHub Repository](https://github.com/swellstores/swell-apps-sdk)
+
+## 📄 License
+
+See the [LICENSE](LICENSE) file for details.

package/dist/index.cjs

@@ -649,6 +649,12 @@ async function forEachKeyDeep(obj, fn) {
 }
 
 // src/resources.ts
+var NOT_CACHEBLE_COLLECTIONS = Object.freeze(
+  /* @__PURE__ */ new Set(["accounts:addresses", "accounts:orders", "accounts:subscriptions"])
+);
+function isResourceCacheble(name) {
+  return !NOT_CACHEBLE_COLLECTIONS.has(name);
+}
 var MAX_QUERY_PAGE_LIMIT = 100;
 var DEFAULT_QUERY_PAGE_LIMIT = 15;
 var StorefrontResource = class {
@@ -935,7 +941,8 @@ var SwellStorefrontCollection = class _SwellStorefrontCollection extends SwellSt
           this._swell.queryParams,
           this._getterHash
         ],
-        getter
+        getter,
+        isResourceCacheble(this._collection)
       ).then((result) => {
         this._result = result;
         if (result) {
@@ -1049,7 +1056,8 @@ var SwellStorefrontRecord = class extends SwellStorefrontResource {
           this._swell.queryParams,
           this._getterHash
         ],
-        getter
+        getter,
+        isResourceCacheble(this._collection)
       ).then((result) => {
         return this._transformResult(result);
       }).then((result) => {
@@ -7216,16 +7224,18 @@ var Cache = class {
    *
    * This will always return the cached value immediately if exists
    */
-  async fetchSWR(key, fetchFn, ttl = DEFAULT_SWR_TTL) {
+  async fetchSWR(key, fetchFn, ttl = DEFAULT_SWR_TTL, isCacheble = true) {
     const trace = createTraceId();
     logger.debug("[SDK] Cache fetch start", { key, trace });
-    const cacheValue = await this.client.get(key);
+    const cacheValue = isCacheble ? await this.client.get(key) : void 0;
     let promise = SWR_PROMISE_MAP.get(key);
     if (promise === void 0) {
       promise = Promise.resolve().then(fetchFn).then(resolveAsyncResources).then(async (value) => {
         const isNull = value === null || value === void 0;
-        await this.client.set(key, isNull ? NULL_VALUE : value, ttl);
-        logger.debug("[SDK] Cache update done", { key, trace });
+        if (isCacheble) {
+          await this.client.set(key, isNull ? NULL_VALUE : value, ttl);
+          logger.debug("[SDK] Cache update done", { key, trace });
+        }
         return value;
       }).finally(() => {
         SWR_PROMISE_MAP.delete(key);
@@ -7536,6 +7546,16 @@ function transformSwellVariant(params, product, variant) {
 }
 
 // src/resources/product.ts
+var SORT_OPTIONS = [
+  { value: "", name: "Featured" },
+  { value: "popularity", name: "Popularity", query: "popularity desc" },
+  { value: "price_asc", name: "Price, low to high", query: "price asc" },
+  { value: "price_desc", name: "Price, high to low", query: "price desc" },
+  { value: "date_asc", name: "Date, old to new", query: "date asc" },
+  { value: "date_desc", name: "Date, new to old", query: "date desc" },
+  { value: "name_asc", name: "Product name, A-Z", query: "name asc" },
+  { value: "name_desc", name: "Product name, Z-A", query: "name desc" }
+];
 function transformSwellProduct(params, product) {
   if (!product) {
     return product;
@@ -7572,6 +7592,28 @@ var SwellProduct = class extends SwellStorefrontRecord {
     return res;
   }
 };
+function productQueryWithFilters(swell, query = {}) {
+  const sortBy = swell.queryParams.sort || "";
+  const filters2 = Object.entries(swell.queryParams).reduce(
+    (acc, [key, value]) => {
+      if (key.startsWith("filter_")) {
+        const qkey = key.replace("filter_", "");
+        if (value?.gte !== void 0 || value?.lte !== void 0) {
+          acc[qkey] = [value.gte || 0, value.lte || void 0];
+        } else {
+          acc[qkey] = value;
+        }
+      }
+      return acc;
+    },
+    {}
+  );
+  return {
+    sort: SORT_OPTIONS.find((option) => option.value === sortBy)?.query || void 0,
+    $filters: filters2,
+    ...query
+  };
+}
 
 // src/api.ts
 var DEFAULT_API_HOST = "https://api.schema.io";
@@ -7699,9 +7741,14 @@ var Swell = class _Swell {
    * Fetches a resource.
    * First attempts to fetch from cache.
    */
-  async getCachedResource(key, args, handler) {
+  async getCachedResource(key, args, handler, isCacheble = true) {
     const cacheKey = getCacheKey(key, [this.instanceId, args]);
-    return this.getResourceCache().fetchSWR(cacheKey, handler);
+    return this.getResourceCache().fetchSWR(
+      cacheKey,
+      handler,
+      void 0,
+      isCacheble
+    );
   }
   async getAppSettings() {
     const settings = await this.get(
@@ -7713,15 +7760,16 @@ var Swell = class _Swell {
     return settings || {};
   }
   async getStorefrontSettings(force = false) {
+    const storefrontSettings = this.storefront.settings;
     try {
-      const { settings, menus, payments, subscriptions, session } = await this.storefront.request(
+      const allSettings = await this.storefront.request(
         "get",
         "/settings/all",
         void 0,
         force ? { $cache: false } : void 0,
         { force }
       );
-      const storefrontSettings = this.storefront.settings;
+      const { settings, menus, payments, subscriptions, session } = allSettings;
       storefrontSettings.localizedState = {};
       storefrontSettings.set({
         value: settings
@@ -7749,7 +7797,7 @@ var Swell = class _Swell {
       }
       logger.error(err);
     }
-    return this.storefront.settings.get();
+    return storefrontSettings;
   }
   getStorefrontMenus() {
     const menus = this.storefront.settings.getState(
@@ -15012,9 +15060,11 @@ function ShopifyCollection(instance, category) {
   if (category instanceof StorefrontResource) {
     category = cloneStorefrontResource(category);
   }
+  const productMapper = (product) => ShopifyProduct(instance, product);
   const resolveProducts = makeProductsCollectionResolve(
+    instance,
     category,
-    (product) => ShopifyProduct(instance, product)
+    productMapper
   );
   return new ShopifyResource({
     all_products_count: defer(
@@ -15066,8 +15116,9 @@ function ShopifyCollection(instance, category) {
       category,
       (category2) => getFirstImage(instance, category2)
     ),
-    filters: defer(
-      async () => ((await resolveProducts())?.filter_options ?? []).map(
+    filters: deferWith(
+      category,
+      (category2) => (category2?.filter_options ?? []).map(
         (filter) => ShopifyFilter(instance, filter)
       )
     ),
@@ -15077,9 +15128,7 @@ function ShopifyCollection(instance, category) {
     metafields: {},
     next_product: void 0,
     previous_product: void 0,
-    products: defer(async () => {
-      return (await resolveProducts())?.results ?? [];
-    }),
+    products: getProducts(instance, category, productMapper),
     products_count: defer(
       async () => (await resolveProducts())?.results?.length || 0
     ),
@@ -15118,28 +15167,35 @@ function convertToShopifySorting(value) {
       return "manual";
   }
 }
-function makeProductsCollectionResolve(object, mapper) {
-  const productResults = deferWith(object, (object2) => {
-    if (object2.products) {
-      if (object2.products instanceof SwellStorefrontCollection) {
-        return object2.products._cloneWithCompatibilityResult((products) => {
-          return {
-            ...products,
-            results: products.results.map(mapper)
-          };
-        });
+function getProducts(instance, object, mapper) {
+  return deferWith(object, (object2) => {
+    const { page, limit: limit2 } = instance.swell.queryParams;
+    const categoryFilter = object2.id && object2.id !== "all" ? object2.id : void 0;
+    const productQuery = categoryFilter ? { category: categoryFilter, $variants: true } : { $variants: true };
+    const filterQuery = productQueryWithFilters(instance.swell, productQuery);
+    const products = new SwellStorefrontCollection(
+      instance.swell,
+      "products",
+      {
+        page,
+        limit: limit2,
+        ...filterQuery
+      },
+      async function() {
+        return this._defaultGetter().call(this);
       }
-      if (Array.isArray(object2.products?.results)) {
-        return {
-          ...object2.products,
-          results: object2.products.results.map(mapper)
-        };
+    );
+    return products._cloneWithCompatibilityResult(
+      (products2) => {
+        return { ...products2, results: products2.results.map(mapper) };
       }
-    }
-    return null;
+    );
   });
+}
+function makeProductsCollectionResolve(instance, object, mapper) {
+  const products = getProducts(instance, object, mapper);
   async function resolveProducts() {
-    const resolved = await productResults.resolve();
+    const resolved = await products.resolve();
     if (resolved && "_resolve" in resolved) {
       return resolved._resolve();
     }
@@ -15173,6 +15229,9 @@ function ShopifyAddress(instance, address, account) {
   if (address instanceof StorefrontResource) {
     address = cloneStorefrontResource(address);
   }
+  if (!address) {
+    address = {};
+  }
   return new ShopifyResource({
     address1: defer(() => address.address1),
     address2: defer(() => address.address2),
@@ -15903,11 +15962,15 @@ function ShopifySearch(instance, search) {
   if (search instanceof ShopifyResource) {
     return search.clone();
   }
-  const resolveProducts = makeProductsCollectionResolve(search, (product) => {
-    const shopifyProduct = ShopifyProduct(instance, product);
-    shopifyProduct.object_type = "product";
-    return shopifyProduct;
-  });
+  const resolveProducts = makeProductsCollectionResolve(
+    instance,
+    search,
+    (product) => {
+      const shopifyProduct = ShopifyProduct(instance, product);
+      shopifyProduct.object_type = "product";
+      return shopifyProduct;
+    }
+  );
   return new ShopifyResource({
     default_sort_by: deferWith(
       search,
@@ -16643,6 +16706,10 @@ ${injects.join("\n")}</script>`;
             pageId = "account/order";
             urlParams.id = segment3;
             break;
+          case "subscriptions":
+            pageId = "account/subscription";
+            urlParams.id = segment3;
+            break;
           case "register":
             pageId = "account/login";
             break;
@@ -19390,14 +19457,15 @@ var SwellTheme3 = class {
     logger.debug("[SDK] Theme init start", { page: pageId, trace });
     await this.themeLoader.init(this.themeConfigs || void 0);
     logger.debug("[SDK] ThemeLoader init done", { page: pageId, trace });
-    const { store, session, menus, geo, configs } = await this.getSettingsAndConfigs();
+    const { store, session, menus, geo, configs, storefrontSettings } = await this.getSettingsAndConfigs();
     logger.debug("[SDK] Theme settings load done", { page: pageId, trace });
     const { settings, request, page, cart, account, customer } = await this.resolvePageData(store, configs, pageId, altTemplate);
     logger.debug("[SDK] Theme page data load done", { page: pageId, trace });
     this.page = page;
     const globals = {
       ...this.globalData,
-      store,
+      // return all storefront settings in the store
+      store: { ...storefrontSettings, ...store },
       settings,
       session,
       request,
@@ -19463,7 +19531,10 @@ var SwellTheme3 = class {
         {}
       )
     };
-    const session = await this.swell.storefront.settings.session();
+    const [session, storeSettings] = await Promise.all([
+      storefrontSettings.session(),
+      storefrontSettings.get()
+    ]);
     if (configs.translations) {
       configs.language = configs.translations;
     }
@@ -19476,11 +19547,13 @@ var SwellTheme3 = class {
     await this.setCompatibilityConfigs(configs);
     const menus = await this.resolveMenuSettings();
     return {
-      store: storefrontSettings?.store,
+      store: storeSettings?.store,
       session,
       menus,
       geo,
-      configs
+      configs,
+      // all settings
+      storefrontSettings
     };
   }
   async resolvePageData(store, configs, pageId, altTemplate) {
@@ -19569,7 +19642,8 @@ var SwellTheme3 = class {
       this.fetchSingletonResourceCached(
         "account",
         () => this.fetchAccount(),
-        () => null
+        () => null,
+        false
       )
     ]);
     if (!cart) {
@@ -19589,7 +19663,7 @@ var SwellTheme3 = class {
       // Shopify only
     };
   }
-  async fetchSingletonResourceCached(key, handler, defaultValue) {
+  async fetchSingletonResourceCached(key, handler, defaultValue, isCacheble = true) {
     const cacheKey = this.swell.storefront.session.getCookie();
     if (!cacheKey) {
       return defaultValue();
@@ -19597,7 +19671,8 @@ var SwellTheme3 = class {
     const result = await this.swell.getCachedResource(
       `${key}-${cacheKey}`,
       [],
-      handler
+      handler,
+      isCacheble
     );
     return result ?? defaultValue();
   }
@@ -21128,6 +21203,7 @@ function createStorefrontRecord(resource, swell, path, parent_slug, parent_query
 }
 function createCollection(resource, swell, path, parent_slug, parent_query) {
   const query = getResourceQuery(parent_slug, parent_query);
+  query.$resource_path = path;
   return new SwellStorefrontCollection(
     swell,
     resource,