@commerce-blocks/sdk 2.0.0-alpha.3 → 2.0.2

package/README.md

@@ -40,31 +40,48 @@ collection.dispose()
 
 ## Configuration
 
-| Option              | Type                           | Required | Description                          |
-| ------------------- | ------------------------------ | -------- | ------------------------------------ |
-| `token`             | `string`                       | Yes      | Layers API public token              |
-| `sorts`             | `Sort[]`                       | Yes      | Sort options `{ name, code }`        |
-| `facets`            | `Facet[]`                      | Yes      | Facet fields `{ name, code }`        |
-| `attributes`        | `string[]`                     | No       | Product attributes to fetch          |
-| `baseUrl`           | `string`                       | No       | Custom API URL                       |
-| `fetch`             | `CustomFetch`                  | No       | Custom fetch (SSR, testing)          |
-| `currency`          | `string`                       | No       | Currency for price formatting        |
-| `formatPrice`       | `(amount, currency) => string` | No       | Custom price formatter               |
-| `swatches`          | `Swatch[]`                     | No       | Color swatch definitions             |
-| `options`           | `string[]`                     | No       | Product options to expose            |
-| `productMetafields` | `{ namespace, key }[]`         | No       | Product metafields to fetch          |
-| `variantMetafields` | `{ namespace, key }[]`         | No       | Variant metafields to fetch          |
-| `transforms`        | `Transforms`                   | No       | Post-process results (see below)     |
-| `filterAliases`     | `FilterAliases`                | No       | URL-friendly filter key mapping      |
-| `cacheLimit`        | `number`                       | No       | Max entries in cache                 |
-| `cacheLifetime`     | `number`                       | No       | TTL in milliseconds                  |
-| `storage`           | `StorageAdapter`               | No       | Custom storage adapter               |
-| `initialData`       | `CacheData`                    | No       | Pre-populate cache at init           |
-| `restoreCache`      | `boolean`                      | No       | Restore from storage (default: true) |
+| Option          | Type                           | Required | Description                          |
+| --------------- | ------------------------------ | -------- | ------------------------------------ |
+| `token`         | `string`                       | Yes      | Layers API public token              |
+| `sorts`         | `Sort[]`                       | Yes      | Sort options `{ name, code }`        |
+| `facets`        | `Facet[]`                      | Yes      | Facet fields `{ name, code }`        |
+| `attributes`    | `string[]`                     | No       | Product attributes to fetch          |
+| `baseUrl`       | `string`                       | No       | Custom API URL                       |
+| `fetch`         | `CustomFetch`                  | No       | Custom fetch (SSR, testing)          |
+| `currency`      | `string`                       | No       | Currency for price formatting        |
+| `formatPrice`   | `(amount, currency) => string` | No       | Custom price formatter               |
+| `swatches`      | `Swatch[]`                     | No       | Color swatch definitions             |
+| `transforms`    | `Transforms`                   | No       | Post-process results (see below)     |
+| `filterAliases` | `FilterAliases`                | No       | URL-friendly filter key mapping      |
+| `cacheLimit`    | `number`                       | No       | Max entries in cache                 |
+| `cacheLifetime` | `number`                       | No       | TTL in milliseconds                  |
+| `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>`
@@ -210,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.
@@ -398,7 +465,7 @@ if (result.error) {
 }
 ```
 
-Retryable errors (`TIMEOUT`, `CONNECTION_FAILED`, `RATE_LIMITED`, `SERVICE_UNAVAILABLE`) expose `retryable` and `retryAfterMs`:
+`isRetryable` classifies errors by tag, code, and status — use it standalone or as a `shouldRetry` predicate:
 
 ```typescript
 import { isRetryable } from '@commerce-blocks/sdk'
@@ -417,7 +484,7 @@ The client exposes a reactive cache:
 const { cache } = client
 
 cache.get('cache-key') // CacheEntry<QueryResult> | null
-cache.invalidate('browse:*') // invalidate by pattern
+cache.invalidate('browse') // invalidate keys containing 'browse'
 cache.persist() // save to storage
 cache.restore() // restore from storage
 cache.clear() // clear all

package/dist/index.d.ts

@@ -19,7 +19,6 @@ export declare interface ApiError {
     readonly source: ApiSource;
     readonly message: string;
     readonly status?: number;
-    readonly retryable: boolean;
     readonly retryAfterMs?: number;
     readonly cause?: unknown;
 }
@@ -34,6 +33,22 @@ declare interface ApiFetchConfig {
 
 declare type ApiSource = 'layers';
 
+export declare interface Article {
+    title: string;
+    handle: string;
+    summary: string;
+    author: string;
+    tags: string[];
+    image: ArticleImage | null;
+    publishedAt: string;
+}
+
+declare interface ArticleImage {
+    url: string;
+    width: number;
+    height: number;
+}
+
 export { batch }
 
 declare interface BlocksContext {
@@ -76,8 +91,8 @@ export declare interface BlocksResult extends QueryResult {
 }
 
 declare interface Cache_2 {
-    get(key: string): CacheEntry<QueryResult> | null;
-    set(key: string, result: QueryResult): void;
+    get(key: string): CacheEntry<CacheValue> | null;
+    set(key: string, result: CacheValue): void;
     isExpired(key: string): boolean;
     invalidate(pattern: string): void;
     persist(): void;
@@ -88,11 +103,12 @@ declare interface Cache_2 {
     };
 }
 
-declare type CacheData = Record<string, QueryResult>;
+declare type CacheData = Record<string, CacheValue>;
 
 declare interface CacheEntry<T> {
     data: T;
     timestamp: number;
+    createdAt: number;
 }
 
 export declare interface CacheOptions {
@@ -103,6 +119,8 @@ export declare interface CacheOptions {
     storageAdapter?: StorageAdapter;
 }
 
+declare type CacheValue = QueryResult | ContentResult;
+
 export declare interface Client {
     collection: (options: CollectionOptions) => CollectionController;
     blocks: (options: BlocksOptions) => BlocksController;
@@ -110,6 +128,7 @@ export declare interface Client {
     search: (options?: SearchQuery) => SearchController;
     uploadImage: (options: UploadImageOptions) => UploadImageController;
     searchByImage: (options: SearchByImageQuery) => SearchByImageController;
+    searchContent: (options?: SearchContentQuery) => SearchContentController;
     config: ClientConfig;
     cache: Cache_2;
 }
@@ -117,17 +136,8 @@ export declare interface Client {
 export declare interface ClientConfig extends ApiClientConfig {
     includeMeta?: boolean;
     currency?: string;
-    formatPrice?: (amount: number, currencyCode: string) => string;
+    formatPrice?: FormatPriceFn;
     swatches?: Swatch[];
-    options?: string[];
-    productMetafields?: {
-        namespace: string;
-        key: string;
-    }[];
-    variantMetafields?: {
-        namespace: string;
-        key: string;
-    }[];
     cacheLimit?: number;
     cacheLifetime?: number;
     /** Custom storage adapter for cache persistence. Defaults to localStorage in browser. */
@@ -173,6 +183,39 @@ export declare interface ConfigError {
 
 declare type ConfigErrorCode = 'MISSING_CONFIG' | 'INVALID_CONFIG';
 
+declare interface ContentArticleRaw {
+    title: string;
+    handle: string;
+    summary_text: string;
+    author: string;
+    tags: string[];
+    image: {
+        url: string;
+        width: number;
+        height: number;
+    } | null;
+    published_at: string;
+}
+
+declare interface ContentResult {
+    articles: unknown[];
+    query: string;
+    contentType: string | null;
+    totalResults: number;
+    page: number;
+    resultsPerPage: number;
+}
+
+declare interface ContentSearchResponse {
+    results: ContentArticleRaw[];
+    query: string;
+    contentType: string | null;
+    totalResults: number;
+    totalPages: number;
+    page: number;
+    resultsPerPage: number;
+}
+
 export declare interface Controller<TData, TQuery = void> {
     readonly state: ReadonlySignal<QueryState<TData>>;
     execute(query?: TQuery): Promise<Result<TData, ClientError>>;
@@ -278,6 +321,8 @@ declare enum FilterOperator {
 
 declare type FilterValue = string | number | boolean;
 
+declare type FormatPriceFn = (amount: number, currencyCode: string) => string;
+
 export declare function getClient(): Result<Client, ConfigError>;
 
 export declare function gt(property: string, value: number): FilterExpression;
@@ -382,21 +427,10 @@ declare interface MatchedVariant extends LayersVariant {
     rn?: number;
 }
 
-export declare interface Metafield extends MetafieldIdentifier {
-    value: string;
-    type: string;
-}
-
-declare interface MetafieldIdentifier {
-    namespace: string;
-    key: string;
-}
-
 export declare interface NetworkError {
     readonly _tag: 'NetworkError';
     readonly code: NetworkErrorCode;
     readonly message: string;
-    readonly retryable: boolean;
     readonly retryAfterMs?: number;
     readonly cause?: unknown;
 }
@@ -465,7 +499,7 @@ export declare interface PriceRangeData {
     compareAtPriceRange: PriceRange | null;
 }
 
-export declare type Product<T extends Record<string, unknown> = Record<string, unknown>> = ProductBase & T;
+export declare type Product = ProductBase & Record<string, unknown>;
 
 export declare interface ProductBase {
     id: CommerceBlocksID;
@@ -479,8 +513,8 @@ export declare interface ProductBase {
     tags: string[];
     images: Image_2[];
     featuredMedia: FeaturedMedia | null;
-    priceRange: PriceRange;
-    compareAtPriceRange: PriceRange | undefined;
+    price: Price;
+    compareAtPrice: Price | null;
     options: RichProductOption[];
     selectedOptions: ProductOption[];
     variants: ProductVariant[];
@@ -508,7 +542,7 @@ export declare interface ProductCardController {
     setSelectedOptions(options: ProductOption[]): void;
     setSelectedVariant(variantId: number): void;
     setCarouselPosition(position: number): void;
-    subscribe(callback: (state: ProductCardState) => void): Unsubscribe_2;
+    subscribe(callback: (state: ProductCardState) => void): Unsubscribe;
     dispose(): void;
 }
 
@@ -582,17 +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: Record<string, string[]>;
-    options_v2: OptionV2[];
+    variants?: LayersVariant[];
     body_html?: string | null;
     is_gift_card?: boolean | null;
     has_variants_that_require_components?: boolean | null;
@@ -601,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 {
@@ -658,6 +691,7 @@ declare type Result<T, E = Error> = {
 };
 
 export declare interface RichProductOption extends ProductOption {
+    code: string;
     swatch?: Swatch;
 }
 
@@ -672,6 +706,33 @@ export declare interface SearchByImageQuery extends QueryParams {
     tuning?: SearchTuning;
 }
 
+export declare interface SearchContentController {
+    readonly state: ReadonlySignal<QueryState<SearchContentResult>>;
+    execute(query?: SearchContentQuery): Promise<Result<SearchContentResult, ClientError>>;
+    subscribe(callback: (state: QueryState<SearchContentResult>) => void): Unsubscribe;
+    dispose(): void;
+}
+
+export declare interface SearchContentQuery {
+    query?: string;
+    contentType?: string;
+    page?: number;
+    limit?: number;
+    tuning?: SearchTuning;
+    signal?: AbortSignal;
+    transformRequest?: RequestTransformer;
+    temporary?: boolean;
+}
+
+export declare interface SearchContentResult {
+    articles: Article[];
+    query: string;
+    contentType: string | null;
+    totalResults: number;
+    page: number;
+    resultsPerPage: number;
+}
+
 export declare interface SearchController {
     readonly state: ReadonlySignal<QueryState<SearchResult>>;
     prepare(query?: SearchQuery): Promise<Result<SearchPrepareResult, ClientError>>;
@@ -783,13 +844,12 @@ export declare interface Transforms {
     block?: (result: BlocksResult, raw: LayersResponse & {
         block?: BlocksInfo;
     }) => BlocksResult;
+    searchContent?: (result: SearchContentResult, raw: ContentSearchResponse) => SearchContentResult;
     filters?: (filters: unknown) => FilterGroup | undefined;
 }
 
 export declare type Unsubscribe = () => void;
 
-declare type Unsubscribe_2 = () => void;
-
 export declare interface UploadImageController {
     readonly state: ReadonlySignal<QueryState<UploadImageResult>>;
     subscribe(callback: (state: QueryState<UploadImageResult>) => void): Unsubscribe;