@commerce-blocks/sdk 1.3.0 → 2.0.0-alpha.0

package/README.md

@@ -1,6 +1,6 @@
 # @commerce-blocks/sdk
 
-ES module SDK for Shopify storefronts with Layers API integration.
+ES module SDK powered by Layers API with optional Shopify Storefront enrichment.
 
 ## Installation
 
@@ -22,7 +22,7 @@ const result = createSdk({
   ],
   facets: ['options.color', 'options.size', 'vendor'],
 
-  // Opt in to Shopify Storefront API for richer product data
+  // Opt in to Storefront API for additional product data
   // enableStorefront: true,
   // shop: 'your-store.myshopify.com',
   // storefrontPublicToken: 'your-storefront-token',
@@ -38,18 +38,6 @@ if (result.error) {
 
 ## 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                                          |
@@ -61,6 +49,18 @@ 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) |
 
+### Storefront (optional)
+
+Storefront API is opt-in. Enable it for collection/page metadata and Shopify-specific fields (metafields, variant detail).
+
+| 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 API supports identity tracking for personalization. Pass identity fields via request context:
 
 ```typescript
@@ -87,14 +87,14 @@ interface LayersIdentity {
 
 ### 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           |
-| `extendBlock`      | `(result, raw) => result`       | Transform blocks results           |
-| `transformFilters` | `(filters) => FilterGroup`      | Custom filter transformation       |
-| `filterMap`        | `FilterMap`                     | URL-friendly filter key mapping    |
+| Option             | Type                               | Description                        |
+| ------------------ | ---------------------------------- | ---------------------------------- |
+| `extendProduct`    | `({ base, raw, storefront }) => 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    |
 
 Once configured, extenders and transformers are applied automatically. You pass simple inputs and receive transformed outputs—no manual transformation needed on each call.
 
@@ -102,7 +102,7 @@ Once configured, extenders and transformers are applied automatically. You pass
 // Configure once at initialization
 const sdk = createSdk({
   // ... base config
-  extendProduct: ({ base, raw, shopify }) => ({
+  extendProduct: ({ base, raw, storefront }) => ({
     ...base,
     isNew: raw.tags?.includes('new') ?? false,
     rating: raw.calculated?.average_rating,
@@ -457,7 +457,7 @@ effect(() => {
 
 | Parameter             | Type          | Required | Description                              |
 | --------------------- | ------------- | -------- | ---------------------------------------- |
-| `ids`                 | `string[]`    | Yes      | Shopify Product GIDs                     |
+| `ids`                 | `string[]`    | Yes      | 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 |
@@ -503,7 +503,7 @@ interface CollectionResult {
   facets: Record<string, Record<string, number>>
   facetRanges?: Record<string, { min: number; max: number }>
   attributionToken: string
-  collection?: ShopifyCollection
+  collection?: StorefrontCollection
 }
 
 interface SearchResult {
@@ -531,8 +531,8 @@ interface BlocksResult {
 
 interface StorefrontResult {
   products: Product[]
-  collection?: ShopifyCollection
-  page?: ShopifyPage
+  collection?: StorefrontCollection
+  page?: StorefrontPage
 }
 ```
 
@@ -551,7 +551,7 @@ if (result.error) {
       break
     case 'ApiError':
       // Server errors, rate limits
-      console.log(result.error.source) // 'layers' | 'shopify'
+      console.log(result.error.source) // 'layers' | 'storefront'
       console.log(result.error.status) // HTTP status code
       break
     case 'ValidationError':
@@ -585,7 +585,7 @@ if (result.error) {
 | Field          | Type           | Description                                        |
 | -------------- | -------------- | -------------------------------------------------- |
 | `code`         | `ApiErrorCode` | `NOT_FOUND`, `RATE_LIMITED`, `GRAPHQL_ERROR`, etc. |
-| `source`       | `ApiSource`    | `'layers'` or `'shopify'`                          |
+| `source`       | `ApiSource`    | `'layers'` or `'storefront'`                       |
 | `status`       | `number?`      | HTTP status code                                   |
 | `retryable`    | `boolean`      | Whether the request can be retried                 |
 | `retryAfterMs` | `number?`      | Suggested retry delay                              |
@@ -606,6 +606,8 @@ if (result.error) {
 
 ### Error Helpers
 
+Always check `isRetryable()` before calling `getRetryDelay()`. `getRetryDelay()` returns `undefined` for non-retryable errors — it's not meant to be used standalone.
+
 ```typescript
 import { isRetryable, getRetryDelay } from '@commerce-blocks/sdk'
 
@@ -636,7 +638,7 @@ const priceFilter = filter(and(gte('price', 50), lte('price', 200)))
 
 // Use in query
 await collection.execute({
-  filters: multiFilter.filter_group,
+  filters: multiFilter,
 })
 ```
 
@@ -675,57 +677,80 @@ await collection.execute({
 })
 ```
 
-## Hooks
+## Product Card
 
-### `useProductCard()` - Product Card Helper
+### `createProductCard()` - Reactive Product Card Controller
 
-Utility for building product cards with variant selection and availability logic.
+Creates a reactive controller for product cards with variant selection and availability logic. All derived values are computed signals that auto-update when inputs change.
 
 ```typescript
-import { useProductCard } from '@commerce-blocks/sdk'
+import { createProductCard, effect } from '@commerce-blocks/sdk'
 
-const card = useProductCard({
+const card = createProductCard({
   product,
-  selectedOptions: [{ name: 'Size', value: 'M' }],
-  breakAwayOptions: [{ name: 'Color', value: 'Red' }],
+  selectedOptions: [{ name: 'Size', value: '7' }],
+  breakoutOptions: [{ name: 'Stone', value: 'Ruby' }],
 })
 
-// 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
+// Subscribe to reactive state
+effect(() => {
+  console.log('Selected variant:', card.selectedVariant.value)
+  console.log('Available options:', card.options.value)
+})
+
+// Access reactive signals
+card.variants.value // Variants filtered by breakoutOptions
+card.selectedVariant.value // Currently selected variant
+card.options.value // Available options (excludes breakout option names)
+card.images.value // Variant image or product images
+card.carouselIndex.value // Image index for carousel
 
-// Helper methods
+// Mutate state via actions
+card.selectOption('Size', 'L') // Select a single option
+card.setSelectedOptions([{ name: 'Size', value: 'L' }]) // Merge options by name
+card.setBreakoutOptions([{ name: 'Stone', value: 'Emerald' }]) // Change breakout filter
+
+// Query methods (pure)
 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' }])
+
+// Cleanup
+card.dispose()
 ```
 
 **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:**
+| Parameter         | Type              | Required | Description                                              |
+| ----------------- | ----------------- | -------- | -------------------------------------------------------- |
+| `product`         | `Product`         | Yes      | Product to display                                       |
+| `selectedOptions` | `ProductOption[]` | No       | Initially selected options                               |
+| `breakoutOptions` | `ProductOption[]` | No       | Options to filter variants (auto-set from variant tiles) |
+
+**Reactive State (ReadonlySignal):**
+
+| Property          | Type                                     | Description                             |
+| ----------------- | ---------------------------------------- | --------------------------------------- |
+| `product`         | `Product`                                | Original product (static)               |
+| `variants`        | `ReadonlySignal<ProductVariant[]>`       | Variants matching breakoutOptions       |
+| `selectedVariant` | `ReadonlySignal<ProductVariant \| null>` | Variant matching all selected options   |
+| `selectedOptions` | `ReadonlySignal<ProductOption[]>`        | Combined breakout + selected options    |
+| `options`         | `ReadonlySignal<RichProductOption[]>`    | Available options from visible variants |
+| `optionNames`     | `ReadonlySignal<string[]>`               | Option names (excludes breakout)        |
+| `images`          | `ReadonlySignal<Image[]>`                | Variant image or product images         |
+| `carouselIndex`   | `ReadonlySignal<number>`                 | Index of selected variant's image       |
+
+**Actions:**
+
+| Method                        | Description                     |
+| ----------------------------- | ------------------------------- |
+| `selectOption(name, value)`   | Select a single option by name  |
+| `setSelectedOptions(options)` | Merge options by name           |
+| `setBreakoutOptions(options)` | Replace breakout filter options |
+| `dispose()`                   | Cleanup controller              |
+
+**Query Methods:**
 
 | Method                           | Returns                  | Description                                            |
 | -------------------------------- | ------------------------ | ------------------------------------------------------ |