SDK changelog

​

v3.0.0

​

Highlights

• createSDK / getSDK / resetSDK replace createClient / getClient; both return { data, error }
• trackingToken is now required alongside storefrontAccessToken (renamed from token)
• Stateless controllers — identity params go at controller creation, query params at get(); overrides shallow-merge and never accumulate
• controller.get() replaces execute() (kept as a deprecated alias); controller.state replaces state.value
• No Preact signals — subscribe(controller, cb) and controller.subscribe(cb) work with plain callbacks
• QueryState.loading replaces isFetching (kept as a deprecated alias); errors are plain Error
• New controllers: sdk.similarProducts(), sdk.facets(), sdk.sortOrders() — facets and sort orders are now fetched at runtime instead of declared at init
• New direct calls: sdk.searchFeedback() for search-quality feedback and sdk.trackingEvent() for analytics via sendBeacon with a fetch fallback
• autocomplete() unbundled from debounce — use createDebounce from @commerce-blocks/sdk/utils to debounce calls; suggest() remains as a deprecated wrapper
• Filter operator renames: notEq → neq, exists → notNull, notExists → isNull; added between, notBetween, contains, doesNotContain, beginsWith, endsWith
• Storage simplified — storage accepts any StorageBackend (getItem/setItem/removeItem/clear), so localStorage can be passed directly
• Cache is internal-only — removed the public client.cache API; configure via cache: { ttl, maxSize } on createSDK
• Removed: filterAliases, initialData, restoreCache, ClientError hierarchy, isClientError, isRetryable, localStorageAdapter, fileStorage

​

v2.0.3

• Breaking: Removed tuning parameter and SearchTuning type from search(), searchContent(), searchByImage(), and prepare(). Search tuning is now managed exclusively in the Layers dashboard.
• Fix: Stale preparedSearchId is now discarded when execute() provides new query, filter, or linking parameters
• Fix: Empty or whitespace-only strings are now rejected by required field validation
• Fix: Resolved multiple SDK bugs across cache, controllers, and validation
• Note: priceRange in query results now requires { name: 'Price', code: 'variants.price' } in your facets configuration

​

v2.0.2

• Fix: Separated LRU timestamp from TTL expiry to prevent premature cache eviction
• Fix: Resolved cache key gaps, race conditions, and LRU eviction edge cases
• Fix: Resolved cache key, price leak, search race, and URL encoding bugs
• Fix: Resolved multiple SDK bugs across cache, layers, and filters

​

v2.0.0

​

Highlights

• New createClient API replacing createSdk with a cleaner configuration interface
• Signal-based controllers with built-in subscribe() on all controllers (Collection, Search, Blocks, Suggest)
• Layers-only architecture — Storefront API hydration removed; products are built entirely from Layers data
• Reactive createProductCard controller with signal-based state for variant selection, pricing, and images
• Content search via the new searchContent controller for article/blog search
• Shallow products by default — only the matched variant is included, significantly reducing payload size
• Structured error types with ClientError replacing SdkError, and isRetryable caller predicate
• Request deduplication via a new RequestCoordinator that prevents redundant in-flight API calls
• Simplified cache API replacing the store module with a flat cache interface
• Renamed public API surface — Sdk is now Client, autocomplete is now suggest, filterMap is now filterAliases, and more
• Variant breakout support with breakoutOptions for expanding variants into individual tiles
• Formatted price ranges included in query results

​

v1.3.0

• Feature: Pluggable storage adapters for cache persistence (localStorageAdapter, fileStorage, or custom StorageAdapter)
• Feature: initialData and restoreFromStorage options on createSdk for hydrating the cache at initialization
• Feature: Exposed additional Layers response fields (e.g. attributionToken) in SDK results
• Fix: Made attributionToken optional to prevent runtime errors when absent

​

v1.2.1

• Feature: Exposed variant inventory levels on the Product type
• Fix: Compile issue resolved
• Chore: Switched npm publish to OIDC trusted publishers

​

v1.1.0

• Feature: Dynamic linking — dynamicLinking promoted to a first-class field on all Layers endpoints
• Feature: Dynamic parameter injection for Layers API requests
• Chore: Renamed package to @commerce-blocks/sdk and published to npm

​

v0.2.0

• Feature: Added onReady lifecycle hook for detecting when the SDK is fully initialized
• Feature: Optimized variant attribute requests to reduce payload size

​

v0.1.1

• Fix: Stable signal reference in providers to prevent unnecessary re-renders
• Breaking: Auto-wrap filter conditions in AND groups — filters are now automatically grouped

​

v0.1.0

• Feature: App-ready promise pattern and theme injection support
• Feature: Template validation and Preact subpath export
• Feature: Explicit component registration and cache configuration options
• Test: Build verification and API contract tests

​

v0.0.3

• Browse, search, predictive search, and image similarity APIs
• Caching mechanism with LRU eviction
• Filter utilities and DSL
• Preact-based playground for development