@commerce-blocks/sdk 2.0.0-alpha.1 → 2.0.0-alpha.2

package/README.md

@@ -138,29 +138,38 @@ await collection.execute({ filters: { color: 'Red' } }) // filterMap applied
 
 ### `sdk.collection()` - Browse Collections
 
-Creates a collection controller for browsing products in a collection. Controllers expose two ways to consume results:
+Creates a collection controller for browsing products in a collection. Controllers expose three ways to consume results:
 
-- **Reactive**: Subscribe to `controller.state` (a `ReadonlySignal<QueryState<T>>`) via `effect()` — state updates automatically on each execute
+- **Reactive (signals)**: Access `controller.state` (a `ReadonlySignal<QueryState<T>>`) directly with `effect()` from `@preact/signals-core`
+- **Reactive (callback)**: Use `controller.subscribe(callback)` — receives state updates without needing signals
 - **Imperative**: `await controller.execute()` returns `Result<T, SdkError>` directly
 
-This pattern applies to all controllers (`collection`, `search`, `blocks`).
+This pattern applies to all controllers (`collection`, `search`, `blocks`, `autocomplete`).
 
 ```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
+// Option 1: Controller subscribe() — no signal import needed
+const unsubscribe = collection.subscribe(({ data, error, isFetching }) => {
   if (isFetching) console.log('Loading...')
   if (error) console.error('Error:', error.message)
   if (data) console.log('Products:', data.products)
 })
 
+// Option 2: Standalone subscribe() — works with any signal
+const unsubscribe = subscribe(collection.state, ({ data, error, isFetching }) => {
+  // same as above
+})
+
+// Option 3: Direct signal access (for custom reactivity)
+effect(() => {
+  const { data, error, isFetching } = collection.state.value
+  // same as above
+})
+
 // Execute queries — returns Result<CollectionResult, SdkError>
 const result = await collection.execute() // initial load
 if (result.error) console.error(result.error.message)
@@ -170,16 +179,20 @@ 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()
+// Unsubscribe
+unsubscribe() // remove single subscription
+collection.dispose() // cleanup all subscriptions + abort pending requests
 ```
 
+The `subscribe()` method is an effect abstraction — it wraps `@preact/signals-core`'s `effect()` so you can react to state changes without importing signals directly. The callback receives the full `QueryState<T>` object (not a signal), making it easy to use in any framework.
+
 **Options:**
 
-| Parameter     | Type     | Required | Description                                    |
-| ------------- | -------- | -------- | ---------------------------------------------- |
-| `handle`      | `string` | Yes      | Collection URL handle                          |
-| `defaultSort` | `string` | No       | Default sort code (uses first configured sort) |
+| Parameter     | Type          | Required | Description                                    |
+| ------------- | ------------- | -------- | ---------------------------------------------- |
+| `handle`      | `string`      | Yes      | Collection URL handle                          |
+| `defaultSort` | `string`      | No       | Default sort code (uses first configured sort) |
+| `signal`      | `AbortSignal` | No       | Shared abort signal                            |
 
 **Execute parameters:**
 
@@ -189,7 +202,7 @@ collection.dispose()
 | `limit`          | `number`                  | Products per page (default: 24)       |
 | `sortOrderCode`  | `string`                  | Sort option code                      |
 | `filters`        | `unknown`                 | Filter criteria                       |
-| `signal`         | `AbortSignal`             | External abort signal                 |
+| `signal`         | `AbortSignal`             | Per-call abort signal                 |
 | `includeMeta`    | `boolean`                 | Fetch collection metadata             |
 | `includeFilters` | `boolean`                 | Include filter counts in response     |
 | `dynamicLinking` | `Record<string, unknown>` | Custom dynamic linking parameters     |
@@ -203,18 +216,28 @@ Creates a blocks controller for product recommendations powered by Layers blocks
 ```typescript
 const blocks = sdk.blocks({
   blockId: 'block-abc123',
-  anchorHandle: 'gold-necklace', // anchor by product handle
+  anchorId: 'gold-necklace', // anchor by product ID or handle
 })
 
-// Subscribe to state changes
-effect(() => {
-  const { data, error, isFetching } = blocks.state.value
+// Option 1: Controller subscribe() — no signal import needed
+const unsubscribe = blocks.subscribe(({ data, error, isFetching }) => {
   if (data) {
     console.log('Recommendations:', data.products)
     console.log('Block info:', data.block) // { title, anchor_type, strategy_type, ... }
   }
 })
 
+// Option 2: Standalone subscribe() — works with any signal
+const unsubscribe = subscribe(blocks.state, ({ data, error, isFetching }) => {
+  // same as above
+})
+
+// Option 3: Direct signal access (for custom reactivity)
+effect(() => {
+  const { data, error, isFetching } = blocks.state.value
+  // same as above
+})
+
 // Execute queries
 await blocks.execute()
 await blocks.execute({ page: 2, limit: 12 })
@@ -232,17 +255,18 @@ await blocks.execute({
   discountEntitlements: [{ id: 'discount-123' }],
 })
 
-// Cleanup
-blocks.dispose()
+// Unsubscribe
+unsubscribe() // remove single subscription
+blocks.dispose() // cleanup all subscriptions + abort pending requests
 ```
 
 **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 |
+| Parameter  | Type          | Required | Description                            |
+| ---------- | ------------- | -------- | -------------------------------------- |
+| `blockId`  | `string`      | Yes      | Layers block ID                        |
+| `anchorId` | `string`      | No       | Anchor product/collection ID or handle |
+| `signal`   | `AbortSignal` | No       | Shared abort signal                    |
 
 **Execute parameters:**
 
@@ -290,89 +314,116 @@ Creates a standalone autocomplete controller with debounced search and local cac
 ```typescript
 const autocomplete = sdk.autocomplete({ debounceMs: 300 })
 
-// Subscribe to state
-effect(() => {
-  const { data, isFetching, error } = autocomplete.state.value
+// Option 1: Controller subscribe() — no signal import needed
+const unsubscribe = autocomplete.subscribe(({ data, isFetching, error }) => {
   if (isFetching) console.log('Loading suggestions...')
   if (data) renderSuggestions(data.matchedQueries)
 })
 
+// Option 2: Standalone subscribe() — works with any signal
+const unsubscribe = subscribe(autocomplete.state, ({ data, isFetching, error }) => {
+  // same as above
+})
+
+// Option 3: Direct signal access (for custom reactivity)
+effect(() => {
+  const { data, isFetching, error } = autocomplete.state.value
+  // same as above
+})
+
 // Wire to input (debounced automatically)
 input.addEventListener('input', (e) => {
   autocomplete.execute(e.target.value)
 })
 
-// Cleanup
-autocomplete.dispose()
+// Unsubscribe
+unsubscribe() // remove single subscription
+autocomplete.dispose() // cleanup all subscriptions, abort controller, and timers
 ```
 
 **Options:**
 
-| Parameter    | Type          | Description                                                |
-| ------------ | ------------- | ---------------------------------------------------------- |
-| `debounceMs` | `number`      | Debounce delay (default: 300)                              |
-| `signal`     | `AbortSignal` | External abort signal (acts like `dispose()` when aborted) |
+| Parameter    | Type          | Description                                              |
+| ------------ | ------------- | -------------------------------------------------------- |
+| `debounceMs` | `number`      | Debounce delay (default: 300)                            |
+| `signal`     | `AbortSignal` | Shared abort signal (acts like `dispose()` when aborted) |
 
 **Controller methods:**
 
-| Method           | Description                                  |
-| ---------------- | -------------------------------------------- |
-| `execute(query)` | Debounced predictive search for autocomplete |
-| `dispose()`      | Cleanup abort controller and timers          |
+| Method           | Description                                              |
+| ---------------- | -------------------------------------------------------- |
+| `execute(query)` | Debounced predictive search for autocomplete             |
+| `subscribe(cb)`  | Subscribe to state changes, returns unsubscribe function |
+| `dispose()`      | Cleanup all subscriptions, abort controller and timers   |
 
 ### `sdk.search()` - Search Products
 
-Creates a search controller for full text search with prepare/execute flow.
+Creates a search controller for full text search. Options persist across calls — subsequent `execute()` and `prepare()` calls merge with these defaults.
 
 ```typescript
-const search = sdk.search()
+// Initialize with base options
+const search = sdk.search({ query: 'ring', limit: 20 })
 
-// Subscribe to state
-effect(() => {
-  const { data, isFetching, error } = search.state.value
+// Option 1: Controller subscribe() — no signal import needed
+const unsubscribe = search.subscribe(({ data, isFetching, error }) => {
   if (isFetching) console.log('Searching...')
   if (data) renderResults(data.products)
 })
 
-// Prepare search (optional, caches searchId for reuse)
-await search.prepare({ query: 'ring' })
+// Option 2: Standalone subscribe() — works with any signal
+const unsubscribe = subscribe(search.state, ({ data, isFetching, error }) => {
+  // same as above
+})
 
-// 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)
+// Option 3: Direct signal access (for custom reactivity)
+effect(() => {
+  const { data, isFetching, error } = search.state.value
+  // same as above
 })
 
-// Cleanup
+// Execute with initial options
+await search.execute()
+
+// Override and persist new options
+await search.execute({ page: 2 }) // page=2 persists
+await search.execute({ filters: { vendor: 'Adidas' } }) // filters updated
+
+// Temporary override without persisting
+await search.execute({ query: 'shoes', transient: true }) // query stays 'ring' for next call
+
+// Prepare search (optional, caches searchId for faster execute)
+await search.prepare()
+await search.execute() // uses cached searchId
+
+// Unsubscribe
+unsubscribe()
 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                           |
+**SearchQuery parameters** (used for init, execute, and prepare):
+
+| Parameter        | Type                      | Description                                   |
+| ---------------- | ------------------------- | --------------------------------------------- |
+| `query`          | `string`                  | Search query (required for first execute)     |
+| `searchId`       | `string`                  | Use specific searchId (skips prepare)         |
+| `page`           | `number`                  | Page number (default: 1)                      |
+| `limit`          | `number`                  | Products per page (default: 24)               |
+| `filters`        | `unknown`                 | Filter criteria                               |
+| `tuning`         | `LayersTuning`            | Search tuning parameters                      |
+| `signal`         | `AbortSignal`             | Abort signal (shared at init, per-call later) |
+| `dynamicLinking` | `Record<string, unknown>` | Custom dynamic linking parameters             |
+| `params`         | `Record<string, unknown>` | Additional request parameters                 |
+| `transformBody`  | `(body) => body`          | Custom request body mutation function         |
+| `transient`      | `boolean`                 | If true, overrides don't persist              |
 
-**Search parameters:**
+**Controller methods:**
 
-| 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 |
+| Method            | Description                                              |
+| ----------------- | -------------------------------------------------------- |
+| `prepare(query?)` | Prepare search and cache searchId for reuse              |
+| `execute(query?)` | Execute search (uses cached searchId if available)       |
+| `subscribe(cb)`   | Subscribe to state changes, returns unsubscribe function |
+| `dispose()`       | Cleanup all subscriptions and abort pending requests     |
 
 **`LayersTuning`:**
 
@@ -393,12 +444,18 @@ const file = fileInput.files[0]
 
 const state = sdk.uploadImage({ image: file, signal })
 
-effect(() => {
-  const { data, error, isFetching } = state.value
+// Option 1: Standalone subscribe() — works with any signal
+const unsubscribe = subscribe(state, ({ data, error, isFetching }) => {
   if (isFetching) console.log('Uploading...')
   if (error) console.error('Upload failed:', error.message)
   if (data) console.log('Image ID:', data.imageId)
 })
+
+// Option 2: Direct signal access (for custom reactivity)
+effect(() => {
+  const { data, error, isFetching } = state.value
+  // same as above
+})
 ```
 
 ### `sdk.imageSearch()` - Search by Image
@@ -412,9 +469,15 @@ const state = sdk.imageSearch({
   filters: { vendor: 'Nike' },
 })
 
+// Option 1: Standalone subscribe() — works with any signal
+const unsubscribe = subscribe(state, ({ data, error, isFetching }) => {
+  if (data) console.log('Similar products:', data.products)
+})
+
+// Option 2: Direct signal access (for custom reactivity)
 effect(() => {
   const { data, error, isFetching } = state.value
-  if (data) console.log('Similar products:', data.products)
+  // same as above
 })
 ```
 
@@ -443,14 +506,20 @@ const state = sdk.storefront({
   },
 })
 
-effect(() => {
-  const { data, error, isFetching } = state.value
+// Option 1: Standalone subscribe() — works with any signal
+const unsubscribe = subscribe(state, ({ data, error, isFetching }) => {
   if (data) {
     console.log('Products:', data.products)
     console.log('Collection:', data.collection)
     console.log('Page:', data.page)
   }
 })
+
+// Option 2: Direct signal access (for custom reactivity)
+effect(() => {
+  const { data, error, isFetching } = state.value
+  // same as above
+})
 ```
 
 **Parameters:**
@@ -465,24 +534,47 @@ effect(() => {
 
 ## 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).
+Controllers support two levels of abort signals:
+
+1. **Shared signal** — passed at initialization, affects all operations
+2. **Per-call signal** — passed to `execute()` or `prepare()`, affects only that call
+
+Both signals are linked internally using `linkedAbort()` — when either signal aborts, the request cancels. This allows component-level cancellation (shared) alongside request-level cancellation (per-call).
 
 ```typescript
-const controller = new AbortController()
+// Shared signal at init — cancels everything when component unmounts
+const componentController = new AbortController()
+
+const search = sdk.search({
+  query: 'ring',
+  signal: componentController.signal, // shared: affects all operations
+})
 
-// Cancel from outside
-await search.execute({ query: 'ring', signal: controller.signal })
-controller.abort() // cancels the request
+const autocomplete = sdk.autocomplete({
+  signal: componentController.signal, // shared: acts like dispose() when aborted
+})
 
-// With autocomplete — signal acts like dispose()
-const autocomplete = sdk.autocomplete({ signal: controller.signal })
-controller.abort() // cancels debounce + pending request
+// Per-call signal — cancels only this specific request
+const requestController = new AbortController()
+await search.execute({ page: 2, signal: requestController.signal })
+requestController.abort() // cancels only this request
 
-// With collection
-await collection.execute({ page: 2, signal: controller.signal })
+// Shared signal abort cancels everything
+componentController.abort() // cancels all pending requests + acts like dispose()
 ```
 
-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.
+**How signals compose:**
+
+| Scenario             | Behavior                                  |
+| -------------------- | ----------------------------------------- |
+| Only shared signal   | All requests use shared signal            |
+| Only per-call signal | That request uses per-call signal         |
+| Both signals         | Request cancels if either aborts          |
+| Neither signal       | Controller manages its own internal abort |
+
+**Auto-cancellation:**
+
+Controllers that don't support concurrent requests (collection, blocks) automatically abort the previous request when a new one starts. The abort signals add external cancellation paths on top of this built-in behavior.
 
 ## Response Types
 
@@ -730,7 +822,7 @@ card.getSwatches('Color') // Swatch definitions
 card.isOptionAvailable('Size', 'L') // Check if selecting 'L' results in available variant
 card.getVariantByOptions([{ name: 'Size', value: 'L' }])
 
-// Cleanup
+// Unsubscribe
 card.dispose()
 ```
 
@@ -894,7 +986,7 @@ import { browseKey, searchKey, similarKey, blocksKey, productsKey } from '@comme
 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 })
+blocksKey('block-abc', { anchorId: 'gold-necklace', page: 1 })
 productsKey(['gid://shopify/Product/1', 'gid://shopify/Product/2'])
 ```