> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselayers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK changelog

> Release history and changelog entries for the @commerce-blocks/sdk package, including new features, breaking changes, and bug fixes for each version.

<Update label="April 16, 2026" description="v2.0.3" tags={["Breaking", "Fix"]}>
  ## v2.0.3

  Breaking removal of client-side search tuning, plus controller and validation fixes.

  * **Breaking:** Removed `tuning` parameter and `SearchTuning` type from `search()`, `searchContent()`, `searchByImage()`, and `prepare()`. Search tuning is now managed exclusively in the [Layers dashboard](/platform/ranking-relevancy).
  * **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
</Update>

<Update label="April 2, 2026" description="v2.0.2" tags={["Fix"]}>
  ## v2.0.2

  Patch release with stability improvements to cache and CI workflows.

  * **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
</Update>

<Update label="February 25, 2026" description="v2.0.0" tags={["Major", "Breaking"]}>
  ## v2.0.0

  Major release with a redesigned API surface, signal-based reactivity throughout, and a simplified architecture that removes the Shopify Storefront API dependency.

  See the [v1 to v2 Upgrade Guide](/developers/sdk/upgrade-v2) for migration instructions.

  ### 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
</Update>

<Update label="February 5, 2026" description="v1.3.0" tags={["Feature"]}>
  ## 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
</Update>

<Update label="February 4, 2026" description="v1.2.1" tags={["Feature", "Fix"]}>
  ## v1.2.1

  * **Feature:** Exposed variant inventory levels on the `Product` type
  * **Fix:** Compile issue resolved
  * **Chore:** Switched npm publish to OIDC trusted publishers
</Update>

<Update label="February 3, 2026" description="v1.1.0" tags={["Feature"]}>
  ## v1.1.0

  First stable release under the `@commerce-blocks/sdk` package name on npm.

  * **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
</Update>

<Update label="December 15, 2025 (minor)" description="v0.2.0" tags={["Feature"]}>
  ## 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
</Update>

<Update label="December 15, 2025 (patch)" description="v0.1.1" tags={["Fix", "Breaking"]}>
  ## 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
</Update>

<Update label="December 14, 2025" description="v0.1.0" tags={["Feature"]}>
  ## 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
</Update>

<Update label="December 12, 2025" description="v0.0.3" tags={["Feature"]}>
  ## v0.0.3

  Initial pre-release of the SDK with core functionality.

  * Browse, search, predictive search, and image similarity APIs
  * Caching mechanism with LRU eviction
  * Filter utilities and DSL
  * Preact-based playground for development
</Update>