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

package/README.md

@@ -40,27 +40,24 @@ 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) |
 
 ## Controllers
 
@@ -398,7 +395,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 +414,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,7 +103,7 @@ declare interface Cache_2 {
     };
 }
 
-declare type CacheData = Record<string, QueryResult>;
+declare type CacheData = Record<string, CacheValue>;
 
 declare interface CacheEntry<T> {
     data: T;
@@ -103,6 +118,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 +127,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 +135,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 +182,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 +320,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 +426,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 +498,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;
@@ -480,7 +513,7 @@ export declare interface ProductBase {
     images: Image_2[];
     featuredMedia: FeaturedMedia | null;
     priceRange: PriceRange;
-    compareAtPriceRange: PriceRange | undefined;
+    compareAtPriceRange: PriceRange | null;
     options: RichProductOption[];
     selectedOptions: ProductOption[];
     variants: ProductVariant[];
@@ -508,7 +541,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;
 }
 
@@ -591,7 +624,6 @@ declare interface ProductResult {
         to: number;
         compare_at_price: number;
     };
-    options: Record<string, string[]>;
     options_v2: OptionV2[];
     body_html?: string | null;
     is_gift_card?: boolean | null;
@@ -658,6 +690,7 @@ declare type Result<T, E = Error> = {
 };
 
 export declare interface RichProductOption extends ProductOption {
+    code: string;
     swatch?: Swatch;
 }
 
@@ -672,6 +705,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 +843,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;