@commerce-blocks/sdk 1.0.0

package/README.md

@@ -0,0 +1,816 @@
+# @commerce-blocks/sdk
+
+ES module SDK for Shopify storefronts with Layers API integration.
+
+## Installation
+
+```bash
+npm install @commerce-blocks/sdk
+```
+
+## Quick Start
+
+```typescript
+import { createSdk } from '@commerce-blocks/sdk'
+
+const result = createSdk({
+  // Layers API
+  layersPublicToken: 'your-layers-token',
+  sorts: [
+    { label: 'Featured', code: 'featured' },
+    { label: 'Price: Low to High', code: 'price_asc' },
+  ],
+  facets: ['options.color', 'options.size', 'vendor'],
+
+  // Opt in to Shopify Storefront API for richer product data
+  // enableStorefront: true,
+  // shop: 'your-store.myshopify.com',
+  // storefrontPublicToken: 'your-storefront-token',
+})
+
+if (result.error) {
+  console.error('SDK init failed:', result.error.message)
+} else {
+  const sdk = result.data
+  // Ready to use
+}
+```
+
+## Configuration
+
+### Shopify (optional)
+
+Storefront API is opt-in. Enable it for richer product data (metafields, full variant info, collection/page metadata).
+
+| Option                  | Type          | Required                      | Description                                          |
+| ----------------------- | ------------- | ----------------------------- | ---------------------------------------------------- |
+| `enableStorefront`      | `boolean`     | No                            | Enable Storefront API hydration (default: `false`)   |
+| `shop`                  | `string`      | When `enableStorefront: true` | Store domain                                         |
+| `storefrontPublicToken` | `string`      | When `enableStorefront: true` | Storefront API public access token                   |
+| `storefrontApiVersion`  | `string`      | No                            | API version (default: `2025-01`)                     |
+| `fetch`                 | `CustomFetch` | No                            | Custom fetch implementation (SSR, testing, proxying) |
+
+### Layers
+
+| Option              | Type          | Required | Description                                          |
+| ------------------- | ------------- | -------- | ---------------------------------------------------- |
+| `layersPublicToken` | `string`      | Yes      | Layers API public token                              |
+| `sorts`             | `Sort[]`      | Yes      | Sort options (`{ label, code }`)                     |
+| `facets`            | `string[]`    | Yes      | Facet fields for filtering                           |
+| `attributes`        | `string[]`    | No       | Product attributes to fetch                          |
+| `layersBaseUrl`     | `string`      | No       | Custom API URL                                       |
+| `fetch`             | `CustomFetch` | No       | Custom fetch implementation (SSR, testing, proxying) |
+
+### 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   |
+
+### Extensibility
+
+| Option             | Type                            | Description                        |
+| ------------------ | ------------------------------- | ---------------------------------- |
+| `extendProduct`    | `({ base, raw, shopify }) => P` | Transform products after hydration |
+| `extendCollection` | `(result, raw) => result`       | Transform collection results       |
+| `extendSearch`     | `(result, raw) => result`       | Transform search results           |
+| `transformFilters` | `(filters) => FilterGroup`      | Custom filter transformation       |
+| `filterMap`        | `FilterMap`                     | URL-friendly filter key mapping    |
+
+Once configured, extenders and transformers are applied automatically. You pass simple inputs and receive transformed outputs—no manual transformation needed on each call.
+
+```typescript
+// Configure once at initialization
+const sdk = createSdk({
+  // ... base config
+  extendProduct: ({ base, raw, shopify }) => ({
+    ...base,
+    isNew: raw.tags?.includes('new') ?? false,
+    rating: raw.calculated?.average_rating,
+  }),
+  filterMap: {
+    color: 'options.color',
+    size: 'options.size',
+  },
+})
+
+// All SDK methods automatically use your transformers
+const collection = sdk.collection({ handle: 'shirts' })
+await collection.execute({ filters: { color: 'Red' } }) // filterMap applied
+// → result.products have isNew and rating properties
+```
+
+### Cache
+
+| Option             | Type     | Description                |
+| ------------------ | -------- | -------------------------- |
+| `cacheMaxProducts` | `number` | Max products in cache      |
+| `cacheMaxEntries`  | `number` | Max query entries in cache |
+| `cacheTtl`         | `number` | TTL in milliseconds        |
+
+## SDK Methods
+
+### `sdk.collection()` - Browse Collections
+
+Creates a collection controller for browsing products in a collection. Controllers expose two ways to consume results:
+
+- **Reactive**: Subscribe to `controller.state` (a `ReadonlySignal<QueryState<T>>`) via `effect()` — state updates automatically on each execute
+- **Imperative**: `await controller.execute()` returns `Result<T, SdkError>` directly
+
+This pattern applies to all controllers (`collection`, `search`, `blocks`).
+
+```typescript
+import { effect } from '@preact/signals-core'
+
+const collection = sdk.collection({
+  handle: 'shirts',
+  defaultSort: 'featured', // optional, uses first sort if omitted
+})
+
+// Subscribe to state changes
+effect(() => {
+  const { data, error, isFetching } = collection.state.value
+  if (isFetching) console.log('Loading...')
+  if (error) console.error('Error:', error.message)
+  if (data) console.log('Products:', data.products)
+})
+
+// Execute queries — returns Result<CollectionResult, SdkError>
+const result = await collection.execute() // initial load
+if (result.error) console.error(result.error.message)
+if (result.data) console.log('Got', result.data.totalResults, 'results')
+
+await collection.execute({ page: 2 }) // pagination
+await collection.execute({ sortOrderCode: 'price_asc' }) // change sort
+await collection.execute({ filters: { color: 'Red' } }) // with filters
+
+// Cleanup
+collection.dispose()
+```
+
+**Options:**
+
+| Parameter     | Type     | Required | Description                                    |
+| ------------- | -------- | -------- | ---------------------------------------------- |
+| `handle`      | `string` | Yes      | Collection URL handle                          |
+| `defaultSort` | `string` | No       | Default sort code (uses first configured sort) |
+
+**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           |
+
+### `sdk.blocks()` - Product Recommendations
+
+Creates a blocks controller for product recommendations powered by Layers blocks. Blocks can be anchored to a product, collection, or cart for contextual recommendations.
+
+```typescript
+const blocks = sdk.blocks({
+  blockId: 'block-abc123',
+  anchorHandle: 'gold-necklace', // anchor by product handle
+})
+
+// Subscribe to state changes
+effect(() => {
+  const { data, error, isFetching } = blocks.state.value
+  if (data) {
+    console.log('Recommendations:', data.products)
+    console.log('Block info:', data.block) // { title, anchor_type, strategy_type, ... }
+  }
+})
+
+// Execute queries
+await blocks.execute()
+await blocks.execute({ page: 2, limit: 12 })
+
+// With cart context for personalized recommendations
+await blocks.execute({
+  context: {
+    productsInCart: [{ productId: '123', variantId: '456', quantity: 1 }],
+    geo: { country: 'US' },
+  },
+})
+
+// With discount entitlements
+await blocks.execute({
+  discountEntitlements: [{ id: 'discount-123' }],
+})
+
+// Cleanup
+blocks.dispose()
+```
+
+**Options:**
+
+| Parameter      | Type     | Required | Description                      |
+| -------------- | -------- | -------- | -------------------------------- |
+| `blockId`      | `string` | Yes      | Layers block ID                  |
+| `anchorId`     | `string` | No       | Anchor product/collection ID     |
+| `anchorHandle` | `string` | No       | Anchor product/collection handle |
+
+**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   |
+
+**`BlocksContext`:**
+
+| Property         | Type                                     | Description          |
+| ---------------- | ---------------------------------------- | -------------------- |
+| `productsInCart` | `{ productId, variantId?, quantity? }[]` | Products in the cart |
+| `geo`            | `{ country?, province?, city? }`         | Geographic context   |
+| `custom`         | `Record<string, unknown>`                | Custom context data  |
+
+### `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.
+
+```typescript
+const autocomplete = sdk.autocomplete({ debounceMs: 300 })
+
+// Subscribe to state
+effect(() => {
+  const { data, isFetching, error } = autocomplete.state.value
+  if (isFetching) console.log('Loading suggestions...')
+  if (data) renderSuggestions(data.matchedQueries)
+})
+
+// Wire to input (debounced automatically)
+input.addEventListener('input', (e) => {
+  autocomplete.execute(e.target.value)
+})
+
+// Cleanup
+autocomplete.dispose()
+```
+
+**Options:**
+
+| Parameter    | Type          | Description                                                |
+| ------------ | ------------- | ---------------------------------------------------------- |
+| `debounceMs` | `number`      | Debounce delay (default: 300)                              |
+| `signal`     | `AbortSignal` | External abort signal (acts like `dispose()` when aborted) |
+
+**Controller methods:**
+
+| Method           | Description                                  |
+| ---------------- | -------------------------------------------- |
+| `execute(query)` | Debounced predictive search for autocomplete |
+| `dispose()`      | Cleanup abort controller and timers          |
+
+### `sdk.search()` - Search Products
+
+Creates a search controller for full text search with prepare/execute flow.
+
+```typescript
+const search = sdk.search()
+
+// Subscribe to state
+effect(() => {
+  const { data, isFetching, error } = search.state.value
+  if (isFetching) console.log('Searching...')
+  if (data) renderResults(data.products)
+})
+
+// Prepare search (optional, caches searchId for reuse)
+await search.prepare({ query: 'ring' })
+
+// Execute search with pagination and filters
+form.addEventListener('submit', async (e) => {
+  e.preventDefault()
+  const result = await search.execute({
+    query: inputValue,
+    limit: 20,
+    filters: { color: 'Blue' },
+  })
+  if (result.data) console.log('Results:', result.data.products)
+})
+
+// Cleanup
+search.dispose()
+```
+
+**Controller methods:**
+
+| Method           | Description                                        |
+| ---------------- | -------------------------------------------------- |
+| `prepare(query)` | Prepare search and cache searchId for reuse        |
+| `execute(query)` | Execute search (uses cached searchId if available) |
+| `dispose()`      | Cleanup abort controller                           |
+
+**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           |
+
+### `sdk.uploadImage()` - Upload Image for Search
+
+Returns a reactive signal that uploads an image and resolves to an image ID for use with `imageSearch()`. Subscribe with `effect()` like other signal-based methods.
+
+```typescript
+const fileInput = document.querySelector('input[type="file"]')
+const file = fileInput.files[0]
+
+const state = sdk.uploadImage({ image: file, signal })
+
+effect(() => {
+  const { data, error, isFetching } = state.value
+  if (isFetching) console.log('Uploading...')
+  if (error) console.error('Upload failed:', error.message)
+  if (data) console.log('Image ID:', data.imageId)
+})
+```
+
+### `sdk.imageSearch()` - Search by Image
+
+Returns a reactive signal that searches products using a previously uploaded image. Same signal-based pattern as `uploadImage()` and `storefront()`.
+
+```typescript
+const state = sdk.imageSearch({
+  imageId: 'uploaded-image-id',
+  limit: 20,
+  filters: { vendor: 'Nike' },
+})
+
+effect(() => {
+  const { data, error, isFetching } = state.value
+  if (data) console.log('Similar products:', data.products)
+})
+```
+
+**Parameters:**
+
+| Parameter | Type           | Required | Description                     |
+| --------- | -------------- | -------- | ------------------------------- |
+| `imageId` | `string`       | Yes      | Image ID from `uploadImage()`   |
+| `page`    | `number`       | No       | Page number (default: 1)        |
+| `limit`   | `number`       | No       | Products per page (default: 24) |
+| `filters` | `unknown`      | No       | Filter criteria                 |
+| `tuning`  | `LayersTuning` | No       | Search tuning parameters        |
+| `signal`  | `AbortSignal`  | No       | External abort signal           |
+
+### `sdk.storefront()` - Fetch Products and Metadata
+
+Returns a reactive signal for fetching products by their Shopify GIDs, with optional collection/page metadata.
+
+```typescript
+const state = sdk.storefront({
+  ids: ['gid://shopify/Product/123', 'gid://shopify/Product/456'],
+  meta: {
+    collection: 'shirts', // optional: fetch collection metadata
+    page: 'about', // optional: fetch page metadata
+    includeFilters: true, // optional: include available filters
+  },
+})
+
+effect(() => {
+  const { data, error, isFetching } = state.value
+  if (data) {
+    console.log('Products:', data.products)
+    console.log('Collection:', data.collection)
+    console.log('Page:', data.page)
+  }
+})
+```
+
+**Parameters:**
+
+| Parameter             | Type          | Required | Description                              |
+| --------------------- | ------------- | -------- | ---------------------------------------- |
+| `ids`                 | `string[]`    | Yes      | Shopify Product GIDs                     |
+| `meta.collection`     | `string`      | No       | Collection handle to fetch metadata      |
+| `meta.page`           | `string`      | No       | Page handle to fetch metadata            |
+| `meta.includeFilters` | `boolean`     | No       | Include available filters for collection |
+| `signal`              | `AbortSignal` | No       | External abort signal                    |
+
+## Abort Signals
+
+All SDK methods accept an optional `signal` for external cancellation. This works alongside the SDK's internal abort logic (e.g., a new search call automatically cancels the previous one).
+
+```typescript
+const controller = new AbortController()
+
+// Cancel from outside
+await search.execute({ query: 'ring', signal: controller.signal })
+controller.abort() // cancels the request
+
+// With autocomplete — signal acts like dispose()
+const autocomplete = sdk.autocomplete({ signal: controller.signal })
+controller.abort() // cancels debounce + pending request
+
+// With collection
+await collection.execute({ page: 2, signal: controller.signal })
+```
+
+For controllers (autocomplete, search, collection), calling a new query still auto-cancels the previous request. The external signal adds an additional cancellation path — useful for component unmount or navigation.
+
+## Response Types
+
+```typescript
+// All controllers use QueryState<T> for reactive state
+interface QueryState<T> {
+  data: T | null
+  error: SdkError | null
+  isFetching: boolean
+}
+
+interface CollectionResult {
+  products: Product[]
+  totalResults: number
+  totalPages: number
+  page: number
+  facets: Record<string, Record<string, number>>
+  collection?: ShopifyCollection
+}
+
+interface SearchResult {
+  products: Product[]
+  totalResults: number
+  totalPages: number
+  page: number
+  facets: Record<string, Record<string, number>>
+}
+
+interface BlocksResult {
+  products: Product[]
+  totalResults: number
+  totalPages: number
+  page: number
+  facets: Record<string, Record<string, number>>
+  block?: BlocksInfo // { id, title, anchor_type, strategy_type, strategy_key }
+}
+
+interface StorefrontResult {
+  products: Product[]
+  collection?: ShopifyCollection
+  page?: ShopifyPage
+}
+```
+
+## Error Handling
+
+All methods return `Result<T, E>` instead of throwing. Errors are discriminated by `_tag`:
+
+```typescript
+const result = await collection.execute()
+
+if (result.error) {
+  switch (result.error._tag) {
+    case 'NetworkError':
+      // Connection issues, timeouts, aborted requests
+      console.log(result.error.code) // 'TIMEOUT' | 'CONNECTION_FAILED' | 'ABORTED' | ...
+      break
+    case 'ApiError':
+      // Server errors, rate limits
+      console.log(result.error.source) // 'layers' | 'shopify'
+      console.log(result.error.status) // HTTP status code
+      break
+    case 'ValidationError':
+      // Invalid parameters
+      console.log(result.error.operation) // which method failed
+      console.log(result.error.fields) // [{ field, code, message }]
+      break
+    case 'ConfigError':
+      // SDK configuration issues
+      console.log(result.error.field) // which config field
+      break
+  }
+} else {
+  const data = result.data
+}
+```
+
+### Error Types
+
+**`NetworkError`** — connection failures, timeouts, aborted requests
+
+| Field          | Type               | Description                                                                     |
+| -------------- | ------------------ | ------------------------------------------------------------------------------- |
+| `code`         | `NetworkErrorCode` | `TIMEOUT`, `CONNECTION_FAILED`, `DNS_FAILED`, `SSL_ERROR`, `ABORTED`, `OFFLINE` |
+| `message`      | `string`           | Human-readable description                                                      |
+| `retryable`    | `boolean`          | Whether the request can be retried                                              |
+| `retryAfterMs` | `number?`          | Suggested retry delay in milliseconds                                           |
+
+**`ApiError`** — server errors, rate limits, GraphQL errors
+
+| Field          | Type           | Description                                        |
+| -------------- | -------------- | -------------------------------------------------- |
+| `code`         | `ApiErrorCode` | `NOT_FOUND`, `RATE_LIMITED`, `GRAPHQL_ERROR`, etc. |
+| `source`       | `ApiSource`    | `'layers'` or `'shopify'`                          |
+| `status`       | `number?`      | HTTP status code                                   |
+| `retryable`    | `boolean`      | Whether the request can be retried                 |
+| `retryAfterMs` | `number?`      | Suggested retry delay                              |
+
+**`ValidationError`** — invalid parameters passed to SDK methods
+
+| Field       | Type                     | Description                           |
+| ----------- | ------------------------ | ------------------------------------- |
+| `operation` | `string`                 | Which method failed (e.g. `'search'`) |
+| `fields`    | `ValidationFieldError[]` | `[{ field, code, message }]`          |
+
+**`ConfigError`** — SDK configuration issues at init time
+
+| Field      | Type      | Description                 |
+| ---------- | --------- | --------------------------- |
+| `field`    | `string`  | Which config field is wrong |
+| `expected` | `string?` | What was expected           |
+
+### Error Helpers
+
+```typescript
+import { isRetryable, getRetryDelay } from '@commerce-blocks/sdk'
+
+if (result.error && isRetryable(result.error)) {
+  const delay = getRetryDelay(result.error) ?? 1000
+  setTimeout(() => collection.execute(), delay)
+}
+```
+
+## Filtering
+
+Build filters using the DSL helpers:
+
+```typescript
+import { filter, and, or, eq, inValues, gte, lte } from '@commerce-blocks/sdk'
+
+// Single filter
+const colorFilter = filter(eq('options.color', 'Red'))
+
+// Multiple conditions (AND)
+const multiFilter = filter(and(eq('options.color', 'Red'), eq('options.size', 'Medium')))
+
+// Multiple values (OR)
+const multiValue = filter(or(eq('vendor', 'Nike'), eq('vendor', 'Adidas')))
+
+// Price range
+const priceFilter = filter(and(gte('price', 50), lte('price', 200)))
+
+// Use in query
+await collection.execute({
+  filters: multiFilter.filter_group,
+})
+```
+
+### Filter Operators
+
+| Function                       | Description             |
+| ------------------------------ | ----------------------- |
+| `eq(property, value)`          | Equals                  |
+| `notEq(property, value)`       | Not equals              |
+| `inValues(property, values[])` | In list                 |
+| `notIn(property, values[])`    | Not in list             |
+| `gt(property, number)`         | Greater than            |
+| `gte(property, number)`        | Greater than or equal   |
+| `lt(property, number)`         | Less than               |
+| `lte(property, number)`        | Less than or equal      |
+| `exists(property)`             | Property exists         |
+| `notExists(property)`          | Property does not exist |
+
+### Filter Mapping
+
+Use `filterMap` for URL-friendly filter keys:
+
+```typescript
+const sdk = createSdk({
+  // ... other config
+  filterMap: {
+    color: 'options.color',
+    size: 'options.size',
+    brand: { property: 'vendor', values: { nike: 'Nike', adidas: 'Adidas' } },
+  },
+})
+
+// Now you can use simple keys
+await collection.execute({
+  filters: { color: 'Red', brand: 'nike' },
+})
+```
+
+## Hooks
+
+### `useProductCard()` - Product Card Helper
+
+Utility for building product cards with variant selection and availability logic.
+
+```typescript
+import { useProductCard } from '@commerce-blocks/sdk'
+
+const card = useProductCard({
+  product,
+  selectedOptions: [{ name: 'Size', value: 'M' }],
+  breakAwayOptions: [{ name: 'Color', value: 'Red' }],
+})
+
+// Access computed data
+card.variants // Variants filtered by breakAwayOptions
+card.selectedVariant // Currently selected variant
+card.options // Available options (excludes breakaway option names)
+card.images // Variant image or product images
+card.carouselIndex // Image index for carousel
+
+// Helper methods
+card.getOptionValues('Size') // ['S', 'M', 'L']
+card.getSwatches('Color') // Swatch definitions
+card.isOptionAvailable('Size', 'L') // Check if selecting 'L' results in available variant
+card.getVariantByOptions([{ name: 'Size', value: 'L' }])
+```
+
+**Parameters:**
+
+| Parameter          | Type              | Required | Description                                                   |
+| ------------------ | ----------------- | -------- | ------------------------------------------------------------- |
+| `product`          | `Product`         | Yes      | Product to display                                            |
+| `selectedOptions`  | `ProductOption[]` | No       | Currently selected options                                    |
+| `breakAwayOptions` | `ProductOption[]` | No       | Options to filter visible variants (e.g., pre-selected color) |
+
+**Returns:**
+
+| Property          | Type                     | Description                             |
+| ----------------- | ------------------------ | --------------------------------------- |
+| `product`         | `Product`                | Original product                        |
+| `variants`        | `ProductVariant[]`       | Variants matching breakAwayOptions      |
+| `selectedVariant` | `ProductVariant \| null` | Variant matching all selected options   |
+| `selectedOptions` | `ProductOption[]`        | Combined breakaway + selected options   |
+| `options`         | `RichProductOption[]`    | Available options from visible variants |
+| `optionNames`     | `string[]`               | Option names (excludes breakaway)       |
+| `images`          | `Image[]`                | Variant image or product images         |
+| `carouselIndex`   | `number`                 | Index of selected variant's image       |
+
+**Helper Methods:**
+
+| Method                           | Returns                  | Description                                            |
+| -------------------------------- | ------------------------ | ------------------------------------------------------ |
+| `getOptionValues(name)`          | `string[]`               | All values for an option from visible variants         |
+| `getSwatches(name)`              | `Swatch[]`               | Swatch definitions for an option                       |
+| `getVariantByOptions(opts)`      | `ProductVariant \| null` | Find variant by options                                |
+| `isOptionAvailable(name, value)` | `boolean`                | Check if selecting option results in available variant |
+| `isVariantAvailable(variant)`    | `boolean`                | Check if variant is available for sale                 |
+
+## Singleton Access
+
+After initialization, access the SDK anywhere:
+
+```typescript
+import { getSdk, isInitialized } from '@commerce-blocks/sdk'
+
+if (isInitialized()) {
+  const result = getSdk()
+  if (result.data) {
+    const sdk = result.data
+    // Use sdk
+  }
+}
+```
+
+## Store API
+
+The SDK exposes a reactive store for caching:
+
+```typescript
+const { store } = sdk
+
+// Product cache
+const product = store.products.get('gid://shopify/Product/123')
+const { cached, missing } = store.products.getMany(gids)
+store.products.set(products)
+
+// Query cache (reactive)
+const querySignal = store.queries.get('cache-key')
+store.queries.invalidate('browse:*') // invalidate by pattern
+
+// Collection metadata
+const meta = store.collections.get('shirts')
+
+// Persistence
+store.persist() // save to localStorage
+store.restore() // restore from localStorage
+store.clear() // clear all caches
+
+// Stats
+console.log(store.stats) // { products, queries, collections }
+```
+
+## Standalone Utilities
+
+### `search()` - Direct Layers Search
+
+For advanced use cases bypassing SDK caching. Combines `prepareSearch` + `search` into a single call.
+
+```typescript
+import { layersClient, search } from '@commerce-blocks/sdk'
+
+const clientResult = layersClient({
+  layersPublicToken: 'your-token',
+  sorts: [{ label: 'Featured', code: 'featured' }],
+})
+
+if (clientResult.data) {
+  const result = await search(clientResult.data, 'red dress', {
+    pagination: { page: 1, limit: 20 },
+  })
+
+  if (result.data) {
+    console.log('Raw Layers results:', result.data.results)
+  }
+}
+```
+
+### Cache Key Generators
+
+Build cache keys for manual store operations:
+
+```typescript
+import { browseKey, searchKey, similarKey, blocksKey, productsKey } from '@commerce-blocks/sdk'
+
+browseKey('shirts', { page: 1, limit: 24 }) // '/browse/shirts?limit=24&page=1'
+searchKey('red dress', { page: 2 }) // '/search/red%20dress?page=2'
+similarKey(123, { limit: 10 }) // '/similar/123?limit=10'
+blocksKey('block-abc', { anchorHandle: 'gold-necklace', page: 1 })
+productsKey(['gid://shopify/Product/1', 'gid://shopify/Product/2'])
+```
+
+## Testing
+
+Tests use Playwright running in a real browser context. The SDK is loaded via a test harness page and accessed through `window.SDK`.
+
+```bash
+npm run test                                    # run all tests
+npm run test:ui                                 # interactive UI
+npx playwright test tests/client.spec.ts        # single file
+npx playwright test tests/layers.spec.ts -g "search" # single test
+```
+
+### Test helpers
+
+- `setupSdk(page)` — navigates to the test harness and waits for `window.SDK_READY`
+- `inBrowser(page, fn)` — runs a function inside the browser via `page.evaluate()`
+
+### Writing tests
+
+Tests run SDK code inside the browser and return serializable results for assertions:
+
+```typescript
+import { test, expect } from '@playwright/test'
+import { setupSdk, inBrowser } from './helpers'
+
+test.describe('SDK: feature()', () => {
+  test.beforeEach(async ({ page }) => {
+    await setupSdk(page)
+  })
+
+  test('does something', async ({ page }) => {
+    const result = await inBrowser(page, async () => {
+      const { createSdk, devConfig } = (window as any).SDK
+      const { data: sdk } = createSdk(devConfig)
+      if (!sdk) return { error: 'init failed' }
+
+      const controller = sdk.collection({ handle: 'shirts' })
+      const { data, error } = await controller.execute({ limit: 3 })
+      controller.dispose()
+
+      if (error) return { error: error._tag }
+      return { count: data.products.length }
+    })
+
+    expect(result.error).toBeUndefined()
+    expect(result.count).toBeGreaterThan(0)
+  })
+})
+```
+
+Key patterns:
+
+- All SDK calls happen inside `inBrowser()` — you can't access SDK objects directly in Node
+- Return plain objects from `inBrowser()`, not class instances or signals
+- Always `dispose()` controllers to prevent leaks between tests
+- Use `devConfig` from the test harness for real API credentials
+
+## Technical Details
+
+- **Runtime**: Browser (ESM)
+- **TypeScript**: Full type definitions included
+- **Dependencies**: `@preact/signals-core`
+- **Bundle**: Tree-shakeable ES modules
+- **Caching**: Built-in LRU cache with configurable TTL