@commerce-blocks/sdk 2.0.0 → 2.0.2

package/README.md

@@ -58,10 +58,30 @@ collection.dispose()
 | `storage`       | `StorageAdapter`               | No       | Custom storage adapter               |
 | `initialData`   | `CacheData`                    | No       | Pre-populate cache at init           |
 | `restoreCache`  | `boolean`                      | No       | Restore from storage (default: true) |
+| `flags`         | `Flags`                        | No       | Feature flags (see below)            |
+
+### Flags
+
+Control which product data the SDK requests from the API.
+
+```typescript
+createClient({
+  // ...config
+  flags: { variants: true }, // opt-in for full variants array
+})
+```
+
+| Flag       | Default | Description                                                                   |
+| ---------- | ------- | ----------------------------------------------------------------------------- |
+| `variants` | `false` | Request full variants array per product. Enable for PDPs or option selectors. |
+
+By default, products are **shallow** — `variants` contains only the matched variant, and `price`/`compareAtPrice`/`featuredMedia`/`availableForSale` are sourced from `first_or_matched_variant`. This significantly reduces API payload size.
+
+When `flags.variants` is `true`, the full `variants` array is requested and `selectedVariant` is looked up from it. Use this for product detail pages or cards with variant/option selectors.
 
 ## Controllers
 
-All controllers (`collection`, `blocks`, `search`, `suggest`) follow the same pattern:
+All controllers (`collection`, `blocks`, `search`, `suggest`, `searchContent`) follow the same pattern:
 
 - **`state`** — a `ReadonlySignal<QueryState<T>>` with `{ data, error, isFetching }`
 - **`execute()`** — runs the query, returns `Result<T, ClientError>`
@@ -207,6 +227,56 @@ suggest.dispose()
 | `excludeQueries`    | `string[]`    | Custom strings to filter from suggestions   |
 | `signal`            | `AbortSignal` | Shared abort signal (acts like `dispose()`) |
 
+### Content Search
+
+Search articles and other content types.
+
+```typescript
+const content = client.searchContent({ query: 'styling tips' })
+
+const { data } = await content.execute()
+// data.articles, data.totalResults, data.page
+
+await content.execute({ query: 'new arrivals', contentType: 'blog' })
+await content.execute({ page: 2, temporary: true })
+
+content.dispose()
+```
+
+| Option             | Type             | Description                               |
+| ------------------ | ---------------- | ----------------------------------------- |
+| `query`            | `string`         | Search query                              |
+| `contentType`      | `string`         | Filter by content type                    |
+| `page`             | `number`         | Page number                               |
+| `limit`            | `number`         | Results per page                          |
+| `tuning`           | `SearchTuning`   | Matching weight configuration             |
+| `signal`           | `AbortSignal`    | Abort signal                              |
+| `transformRequest` | `(body) => body` | Custom request body transformation        |
+| `temporary`        | `boolean`        | Override without persisting for next call |
+
+Result shape:
+
+```typescript
+interface SearchContentResult {
+  articles: Article[]
+  query: string
+  contentType: string | null
+  totalResults: number
+  page: number
+  resultsPerPage: number
+}
+
+interface Article {
+  title: string
+  handle: string
+  summary: string
+  author: string
+  tags: string[]
+  image: { url: string; width: number; height: number } | null
+  publishedAt: string
+}
+```
+
 ### Image Search
 
 Upload an image, then search by it.

package/dist/index.d.ts

@@ -108,6 +108,7 @@ declare type CacheData = Record<string, CacheValue>;
 declare interface CacheEntry<T> {
     data: T;
     timestamp: number;
+    createdAt: number;
 }
 
 export declare interface CacheOptions {
@@ -512,8 +513,8 @@ export declare interface ProductBase {
     tags: string[];
     images: Image_2[];
     featuredMedia: FeaturedMedia | null;
-    priceRange: PriceRange;
-    compareAtPriceRange: PriceRange | null;
+    price: Price;
+    compareAtPrice: Price | null;
     options: RichProductOption[];
     selectedOptions: ProductOption[];
     variants: ProductVariant[];
@@ -615,16 +616,18 @@ declare interface ProductResult {
     featured_media: FeaturedMedia_2 | null;
     category: ProductCategory_2 | null;
     tags: string[];
-    images: ProductImage[];
+    images?: ProductImage[];
     collection_titles: string[];
     metafields: Record<string, Record<string, unknown>>;
     calculated: Record<string, unknown>;
-    price_range: {
+    options_v2: OptionV2[];
+    first_or_matched_variant: MatchedVariant;
+    price_range?: {
         from: number;
         to: number;
         compare_at_price: number;
     };
-    options_v2: OptionV2[];
+    variants?: LayersVariant[];
     body_html?: string | null;
     is_gift_card?: boolean | null;
     has_variants_that_require_components?: boolean | null;
@@ -633,8 +636,6 @@ declare interface ProductResult {
     created_at?: string;
     updated_at?: string;
     published_at?: string;
-    first_or_matched_variant?: MatchedVariant;
-    variants: LayersVariant[];
 }
 
 export declare interface ProductVariant {