@commerce-blocks/sdk 1.2.0 → 1.3.0

package/README.md

@@ -61,16 +61,29 @@ Storefront API is opt-in. Enable it for richer product data (metafields, full va
 | `layersBaseUrl`     | `string`      | No       | Custom API URL                                       |
 | `fetch`             | `CustomFetch` | No       | Custom fetch implementation (SSR, testing, proxying) |
 
+Layers API supports identity tracking for personalization. Pass identity fields via request context:
+
+```typescript
+// Identity fields available in browse/search contexts
+interface LayersIdentity {
+  deviceId?: string // Device identifier
+  sessionId?: string // Session identifier
+  customerId?: string // Customer identifier
+}
+```
+
 ### Product
 
-| Option              | Type                           | Description                   |
-| ------------------- | ------------------------------ | ----------------------------- |
-| `currencyCode`      | `string`                       | Currency for price formatting |
-| `formatPrice`       | `(amount, currency) => string` | Custom price formatter        |
-| `swatches`          | `Swatch[]`                     | Color swatch definitions      |
-| `options`           | `string[]`                     | Product options to expose     |
-| `productMetafields` | `{ namespace, key }[]`         | Product metafields to fetch   |
-| `variantMetafields` | `{ namespace, key }[]`         | Variant metafields to fetch   |
+| Option                 | Type                           | Description                    |
+| ---------------------- | ------------------------------ | ------------------------------ |
+| `currencyCode`         | `string`                       | Currency for price formatting  |
+| `formatPrice`          | `(amount, currency) => string` | Custom price formatter         |
+| `swatches`             | `Swatch[]`                     | Color swatch definitions       |
+| `options`              | `string[]`                     | Product options to expose      |
+| `productMetafields`    | `{ namespace, key }[]`         | Product metafields to fetch    |
+| `variantMetafields`    | `{ namespace, key }[]`         | Variant metafields to fetch    |
+| `collectionMetafields` | `{ namespace, key }[]`         | Collection metafields to fetch |
+| `pageMetafields`       | `{ namespace, key }[]`         | Page metafields to fetch       |
 
 ### Extensibility
 
@@ -79,6 +92,7 @@ Storefront API is opt-in. Enable it for richer product data (metafields, full va
 | `extendProduct`    | `({ base, raw, shopify }) => P` | Transform products after hydration |
 | `extendCollection` | `(result, raw) => result`       | Transform collection results       |
 | `extendSearch`     | `(result, raw) => result`       | Transform search results           |
+| `extendBlock`      | `(result, raw) => result`       | Transform blocks results           |
 | `transformFilters` | `(filters) => FilterGroup`      | Custom filter transformation       |
 | `filterMap`        | `FilterMap`                     | URL-friendly filter key mapping    |
 
@@ -113,6 +127,13 @@ await collection.execute({ filters: { color: 'Red' } }) // filterMap applied
 | `cacheMaxEntries`  | `number` | Max query entries in cache |
 | `cacheTtl`         | `number` | TTL in milliseconds        |
 
+### Data Hydration
+
+| Option               | Type                                    | Description                               |
+| -------------------- | --------------------------------------- | ----------------------------------------- |
+| `initialData`        | `{ products?, queries?, collections? }` | Pre-populate cache at init                |
+| `restoreFromStorage` | `boolean`                               | Auto-restore from storage (default: true) |
+
 ## SDK Methods
 
 ### `sdk.collection()` - Browse Collections
@@ -162,13 +183,18 @@ collection.dispose()
 
 **Execute parameters:**
 
-| Parameter       | Type          | Description                     |
-| --------------- | ------------- | ------------------------------- |
-| `page`          | `number`      | Page number (default: 1)        |
-| `limit`         | `number`      | Products per page (default: 24) |
-| `sortOrderCode` | `string`      | Sort option code                |
-| `filters`       | `unknown`     | Filter criteria                 |
-| `signal`        | `AbortSignal` | External abort signal           |
+| Parameter        | Type                      | Description                           |
+| ---------------- | ------------------------- | ------------------------------------- |
+| `page`           | `number`                  | Page number (default: 1)              |
+| `limit`          | `number`                  | Products per page (default: 24)       |
+| `sortOrderCode`  | `string`                  | Sort option code                      |
+| `filters`        | `unknown`                 | Filter criteria                       |
+| `signal`         | `AbortSignal`             | External abort signal                 |
+| `includeMeta`    | `boolean`                 | Fetch collection metadata             |
+| `includeFilters` | `boolean`                 | Include filter counts in response     |
+| `dynamicLinking` | `Record<string, unknown>` | Custom dynamic linking parameters     |
+| `params`         | `Record<string, unknown>` | Additional request parameters         |
+| `transformBody`  | `(body) => body`          | Custom request body mutation function |
 
 ### `sdk.blocks()` - Product Recommendations
 
@@ -220,14 +246,17 @@ blocks.dispose()
 
 **Execute parameters:**
 
-| Parameter              | Type                    | Description                     |
-| ---------------------- | ----------------------- | ------------------------------- |
-| `page`                 | `number`                | Page number (default: 1)        |
-| `limit`                | `number`                | Products per page (default: 24) |
-| `filters`              | `unknown`               | Filter criteria                 |
-| `signal`               | `AbortSignal`           | External abort signal           |
-| `discountEntitlements` | `DiscountEntitlement[]` | Discount entitlements to apply  |
-| `context`              | `BlocksContext`         | Cart, geo, and custom context   |
+| Parameter              | Type                      | Description                           |
+| ---------------------- | ------------------------- | ------------------------------------- |
+| `page`                 | `number`                  | Page number (default: 1)              |
+| `limit`                | `number`                  | Products per page (default: 24)       |
+| `filters`              | `unknown`                 | Filter criteria                       |
+| `signal`               | `AbortSignal`             | External abort signal                 |
+| `discountEntitlements` | `DiscountEntitlement[]`   | Discount entitlements to apply        |
+| `context`              | `BlocksContext`           | Cart, geo, and custom context         |
+| `dynamicLinking`       | `Record<string, unknown>` | Custom dynamic linking parameters     |
+| `params`               | `Record<string, unknown>` | Additional request parameters         |
+| `transformBody`        | `(body) => body`          | Custom request body mutation function |
 
 **`BlocksContext`:**
 
@@ -237,6 +266,23 @@ blocks.dispose()
 | `geo`            | `{ country?, province?, city? }`         | Geographic context   |
 | `custom`         | `Record<string, unknown>`                | Custom context data  |
 
+**`DiscountEntitlement`:**
+
+```typescript
+interface DiscountEntitlement {
+  entitled: {
+    all?: boolean // Apply to all products
+    products?: string[] // Product IDs
+    variants?: (string | number)[] // Variant IDs
+    collections?: string[] // Collection handles
+  }
+  discount: {
+    type: 'PERCENTAGE' | 'FIXED_AMOUNT'
+    value: number
+  }
+}
+```
+
 ### `sdk.autocomplete()` - Predictive Search
 
 Creates a standalone autocomplete controller with debounced search and local caching. Only full words (completed by a trailing space) are cached — partial input filters cached results client-side.
@@ -316,14 +362,26 @@ search.dispose()
 
 **Search parameters:**
 
-| Parameter | Type           | Description                     |
-| --------- | -------------- | ------------------------------- |
-| `query`   | `string`       | Search query                    |
-| `page`    | `number`       | Page number (default: 1)        |
-| `limit`   | `number`       | Products per page (default: 24) |
-| `filters` | `unknown`      | Filter criteria                 |
-| `tuning`  | `LayersTuning` | Search tuning parameters        |
-| `signal`  | `AbortSignal`  | External abort signal           |
+| Parameter        | Type                      | Description                           |
+| ---------------- | ------------------------- | ------------------------------------- |
+| `query`          | `string`                  | Search query                          |
+| `page`           | `number`                  | Page number (default: 1)              |
+| `limit`          | `number`                  | Products per page (default: 24)       |
+| `filters`        | `unknown`                 | Filter criteria                       |
+| `tuning`         | `LayersTuning`            | Search tuning parameters              |
+| `signal`         | `AbortSignal`             | External abort signal                 |
+| `dynamicLinking` | `Record<string, unknown>` | Custom dynamic linking parameters     |
+| `params`         | `Record<string, unknown>` | Additional request parameters         |
+| `transformBody`  | `(body) => body`          | Custom request body mutation function |
+
+**`LayersTuning`:**
+
+| Property         | Type     | Description                                 |
+| ---------------- | -------- | ------------------------------------------- |
+| `textualWeight`  | `number` | Weight for text-based matching (0-1)        |
+| `visualWeight`   | `number` | Weight for visual similarity matching (0-1) |
+| `multipleFactor` | `number` | Factor for multiple keyword matching        |
+| `minimumMatch`   | `number` | Minimum match threshold                     |
 
 ### `sdk.uploadImage()` - Upload Image for Search
 
@@ -441,7 +499,10 @@ interface CollectionResult {
   totalResults: number
   totalPages: number
   page: number
+  resultsPerPage?: number
   facets: Record<string, Record<string, number>>
+  facetRanges?: Record<string, { min: number; max: number }>
+  attributionToken: string
   collection?: ShopifyCollection
 }
 
@@ -450,7 +511,10 @@ interface SearchResult {
   totalResults: number
   totalPages: number
   page: number
+  resultsPerPage?: number
   facets: Record<string, Record<string, number>>
+  facetRanges?: Record<string, { min: number; max: number }>
+  attributionToken: string
 }
 
 interface BlocksResult {
@@ -458,7 +522,10 @@ interface BlocksResult {
   totalResults: number
   totalPages: number
   page: number
+  resultsPerPage?: number
   facets: Record<string, Record<string, number>>
+  facetRanges?: Record<string, { min: number; max: number }>
+  attributionToken: string
   block?: BlocksInfo // { id, title, anchor_type, strategy_type, strategy_key }
 }
 
@@ -703,13 +770,54 @@ store.queries.invalidate('browse:*') // invalidate by pattern
 // Collection metadata
 const meta = store.collections.get('shirts')
 
+// Page metadata
+const page = store.pages.get('about')
+store.pages.set('about', { title: 'About Us', body: '...' })
+store.pages.delete('about')
+
 // Persistence
-store.persist() // save to localStorage
-store.restore() // restore from localStorage
+store.persist() // save to storage
+store.restore() // restore from storage
 store.clear() // clear all caches
 
 // Stats
-console.log(store.stats) // { products, queries, collections }
+console.log(store.stats) // { products, queries, collections, pages }
+```
+
+## Storage Adapters
+
+Configure how the SDK persists cache data. By default, the SDK uses `localStorage` in browsers.
+
+### Built-in Adapters
+
+```typescript
+import { localStorageAdapter, jsonFileAdapter } from '@commerce-blocks/sdk'
+
+// Browser: localStorage (returns null if unavailable)
+const browserAdapter = localStorageAdapter('my-cache-key')
+
+// Node.js: JSON file
+import fs from 'fs'
+const nodeAdapter = jsonFileAdapter('./cache.json', fs)
+```
+
+### Custom Adapter
+
+Implement the `StorageAdapter` interface:
+
+```typescript
+interface StorageAdapter {
+  read(): string | null
+  write(data: string): void
+  remove(): void
+}
+
+// Example: sessionStorage adapter
+const sessionAdapter: StorageAdapter = {
+  read: () => sessionStorage.getItem('my-key'),
+  write: (data) => sessionStorage.setItem('my-key', data),
+  remove: () => sessionStorage.removeItem('my-key'),
+}
 ```
 
 ## Standalone Utilities

package/dist/index.d.ts

@@ -68,9 +68,12 @@ declare interface BaseProduct {
     calculated?: Record<string, unknown>;
     isGiftCard: boolean;
     onlineStoreUrl: string | null;
+    /** @deprecated Use variant `inventoryLevels` for location-specific inventory */
     totalInventory: number;
 }
 
+declare type BaseResult<P extends Product = Product> = QueryResult<P>;
+
 export { batch }
 
 declare interface BlocksContext {
@@ -124,10 +127,7 @@ export declare interface BlocksOptions {
     anchorHandle?: string;
 }
 
-export declare interface BlocksResult<P extends Product = Product> extends LayersPagination {
-    products: P[];
-    facets: Record<string, Record<string, number>>;
-    _meta?: LayersMeta;
+export declare interface BlocksResult<P extends Product = Product> extends BaseResult<P> {
     block?: BlocksInfo;
 }
 
@@ -183,13 +183,12 @@ export declare interface CollectionOptions {
     defaultSort?: string;
 }
 
-export declare interface CollectionResult<P extends Product = Product> extends LayersPagination {
-    products: P[];
-    facets: Record<string, Record<string, number>>;
-    _meta?: LayersMeta;
+export declare interface CollectionResult<P extends Product = Product> extends BaseResult<P> {
     collection?: ShopifyCollection;
 }
 
+declare type Collections = Record<string, Omit<CollectionMeta, 'handle'>>;
+
 declare type CommerceBlocksID = `${CommerceBlocksType}-${OptionSegment}` | `${CommerceBlocksType}-${OptionSegment}-${OptionSegment}` | `${CommerceBlocksType}-${OptionSegment}-${OptionSegment}-${OptionSegment}`;
 
 declare type CommerceBlocksType = 'Product' | 'ProductVariant';
@@ -244,6 +243,13 @@ declare interface FeaturedMedia {
     height: number;
 }
 
+declare interface FileSystem_2 {
+    readFileSync(path: string, encoding: 'utf-8'): string;
+    writeFileSync(path: string, data: string, encoding: 'utf-8'): void;
+    unlinkSync(path: string): void;
+}
+export { FileSystem_2 as FileSystem }
+
 export declare function filter(expression: FilterExpression | FilterGroup): FilterGroupParam;
 
 declare enum FilterConditional {
@@ -363,12 +369,17 @@ export declare interface ImageSearchOptions {
 
 export declare function inValues(property: string, values: FilterValue[]): FilterExpression;
 
+/** Map of location ID to available quantity */
+declare type InventoryLevels = Record<string, number>;
+
 export declare function isInitialized(): boolean;
 
 export declare function isRetryable(error: SdkError): boolean;
 
 export declare function isSdkError(error: unknown): error is SdkError;
 
+export declare function jsonFileAdapter(filePath: string, fs: FileSystem_2): StorageAdapter;
+
 declare interface LayersClientConfig extends LayersFetchConfig {
     sorts: Sort[];
     facets: string[];
@@ -395,11 +406,7 @@ declare interface LayersMeta {
         group: 'control' | 'variation';
     }[];
     appliedRules?: string[];
-    variantBreakouts?: {
-        id: string;
-        name: string;
-        optionCode: string;
-    }[];
+    variantBreakouts?: Record<string, string | number>[];
 }
 
 declare interface LayersPagination {
@@ -413,8 +420,9 @@ declare type LayersProduct = ProductResult;
 
 declare interface LayersResponse extends LayersPagination, LayersFacets {
     results: (ProductResult | VariantResult_2)[];
-    attributionToken: string;
+    attributionToken?: string;
     _meta?: LayersMeta;
+    _workflow?: unknown;
 }
 
 declare interface LayersTuning {
@@ -445,9 +453,12 @@ declare interface LayersVariant {
     updated_at?: string;
     requires_selling_plan?: boolean;
     has_selling_plan?: boolean;
-    inventory_levels?: Record<number, number>;
+    inventory_levels?: InventoryLevels;
+    in_stock_location_ids?: number[];
 }
 
+export declare function localStorageAdapter(key: string): StorageAdapter | null;
+
 export declare function lt(property: string, value: number): FilterExpression;
 
 export declare function lte(property: string, value: number): FilterExpression;
@@ -457,6 +468,7 @@ declare interface MatchedVariant extends LayersVariant {
     inventory_policy?: string;
     inventory_quantity?: number;
     product_id?: number;
+    rn?: number;
 }
 
 export declare interface Metafield extends MetafieldIdentifier {
@@ -666,6 +678,7 @@ export declare interface ProductVariant {
     title: string;
     availableForSale: boolean;
     currentlyNotInStock: boolean;
+    /** @deprecated Use `inventoryLevels` for location-specific inventory */
     quantityAvailable: number;
     sku: string | null;
     barcode: string | null;
@@ -677,15 +690,26 @@ export declare interface ProductVariant {
     image: Image_2 | null;
     selectedOptions: ProductOption[];
     metafields: Metafield[];
-    inventoryLevels: Record<number, number>;
+    inventoryLevels: InventoryLevels;
+    inStockLocationIds: number[];
 }
 
+declare type Queries<P extends Product = Product> = Record<string, QueryResult<P>>;
+
 declare interface QueryResult<P extends Product = Product> {
     products: P[];
     totalResults: number;
     totalPages: number;
     page: number;
-    facets?: Record<string, Record<string, number>>;
+    resultsPerPage?: number;
+    facets: Record<string, Record<string, number>>;
+    facetRanges?: Record<string, {
+        min: number;
+        max: number;
+    }>;
+    attributionToken?: string;
+    _meta?: LayersMeta;
+    _workflow?: unknown;
 }
 
 export declare interface QueryState<T> {
@@ -760,12 +784,22 @@ export declare interface SdkConfig<P extends Product = Product> extends LayersCl
     cacheMaxProducts?: number;
     cacheMaxEntries?: number;
     cacheTtl?: number;
+    /** Custom storage adapter for cache persistence. Defaults to localStorage in browser. */
+    storageAdapter?: StorageAdapter;
     extendProduct?: ProductExtender<P>;
     transformFilters?: FilterTransformer;
     filterMap?: FilterMap;
     extendCollection?: CollectionExtender<P>;
     extendSearch?: SearchExtender<P>;
     extendBlock?: BlocksExtender<P>;
+    /** Initial data to hydrate into the store */
+    initialData?: {
+        products?: P[];
+        queries?: Queries<P>;
+        collections?: Collections;
+    };
+    /** Restore cache from storage on init (default: true) */
+    restoreFromStorage?: boolean;
 }
 
 export declare type SdkError = NetworkError | ApiError | ValidationError | ConfigError;
@@ -793,11 +827,7 @@ export declare interface SearchQuery {
     transformBody?: BodyTransformer;
 }
 
-export declare interface SearchResult<P extends Product = Product> extends LayersPagination {
-    products: P[];
-    facets: Record<string, Record<string, number>>;
-    _meta?: LayersMeta;
-}
+export declare type SearchResult<P extends Product = Product> = BaseResult<P>;
 
 declare interface SelectedOptionResult {
     name: string;
@@ -877,6 +907,12 @@ declare interface Sort {
     code: string;
 }
 
+export declare interface StorageAdapter {
+    read(): string | null;
+    write(data: string): void;
+    remove(): void;
+}
+
 declare interface Store<P extends Product = Product> {
     products: {
         get(gid: ProductGID): P | undefined;
@@ -884,7 +920,7 @@ declare interface Store<P extends Product = Product> {
             cached: P[];
             missing: ProductGID[];
         };
-        set(products: P[]): void;
+        set(products: P | P[]): void;
         has(gid: ProductGID): boolean;
     };
     queries: {
@@ -953,6 +989,15 @@ export declare interface StorefrontResult<P extends Product = Product> {
     page?: ShopifyPage;
 }
 
+export declare interface StoreOptions {
+    ttl?: number;
+    maxProducts?: number;
+    maxQueries?: number;
+    storageKey?: string;
+    /** Custom storage adapter. Defaults to localStorage in browser. */
+    storageAdapter?: StorageAdapter;
+}
+
 export declare interface Swatch {
     name: string | null;
     value: string;