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

package/dist/index.d.ts

@@ -26,14 +26,15 @@ export declare interface ApiError {
     };
 }
 
-declare type ApiErrorCode = 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'RATE_LIMITED' | 'SERVICE_UNAVAILABLE' | 'GRAPHQL_ERROR' | 'PARSE_ERROR' | 'UNKNOWN';
+declare type ApiErrorCode = 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'NOT_READY' | 'RATE_LIMITED' | 'SERVICE_UNAVAILABLE' | 'GRAPHQL_ERROR' | 'PARSE_ERROR' | 'UNKNOWN';
 
 declare type ApiSource = 'layers' | 'storefront';
 
 export declare interface AutocompleteController {
-    execute: (query: string) => void;
-    state: ReadonlySignal<QueryState<PredictiveSearchResponse>>;
-    dispose: () => void;
+    readonly state: ReadonlySignal<QueryState<PredictiveSearchResponse>>;
+    execute(query: string): void;
+    subscribe(callback: (state: QueryState<PredictiveSearchResponse>) => void): Unsubscribe;
+    dispose(): void;
 }
 
 export declare interface AutocompleteOptions {
@@ -41,49 +42,6 @@ export declare interface AutocompleteOptions {
     signal?: AbortSignal;
 }
 
-declare interface BaseProduct {
-    id: ID;
-    gid: ProductGID;
-    numericId: number;
-    title: string;
-    handle: string;
-    type: string;
-    vendor: string;
-    description: string;
-    availableForSale: boolean;
-    images: Image_2[];
-    priceRange: {
-        min: Price;
-        max: Price;
-    };
-    compareAtPriceRange?: {
-        min: Price;
-        max: Price;
-    };
-    options: RichProductOption[];
-    tags: string[];
-    variants: ProductVariant[];
-    selectedOptions: ProductOption[];
-    metafields: Record<string, Record<string, unknown>> | unknown[];
-    calculated?: Record<string, unknown>;
-    isGiftCard: boolean;
-    category: ProductCategory | null;
-    createdAt: string | null;
-    publishedAt: string | null;
-    updatedAt: string | null;
-    featuredMedia: FeaturedMedia | null;
-    namedTags?: NamedTag[];
-    combinedListingParentProductId: number | null;
-    combinedListingRole: string | null;
-    hasVariantsThatRequireComponents: boolean;
-    originalOptions: Record<string, string[]>;
-    selectedVariant: ProductVariant | null;
-    breakoutOptions?: ProductOption[];
-    breakoutVariantId?: number;
-}
-
-declare type BaseResult<P extends Product = Product> = QueryResult<P>;
-
 export { batch }
 
 declare interface BlocksContext {
@@ -101,22 +59,10 @@ declare interface BlocksContext {
 }
 
 export declare interface BlocksController<P extends Product = Product> {
-    state: ReadonlySignal<QueryState<BlocksResult<P>>>;
-    execute: (query?: BlocksExecuteQuery) => Promise<Result<BlocksResult<P>, SdkError>>;
-    dispose: () => void;
-}
-
-export declare interface BlocksExecuteQuery {
-    page?: number;
-    limit?: number;
-    filters?: unknown;
-    signal?: AbortSignal;
-    discountEntitlements?: DiscountEntitlement[];
-    context?: BlocksContext;
-    dynamicLinking?: Record<string, string | number | (string | number)[]>;
-    params?: Record<string, unknown>;
-    paramDefinitions?: ParamDefinitions;
-    transformBody?: BodyTransformer;
+    readonly state: ReadonlySignal<QueryState<BlocksResult<P>>>;
+    execute(query?: BlocksQuery): Promise<Result<BlocksResult<P>, SdkError>>;
+    subscribe(callback: (state: QueryState<BlocksResult<P>>) => void): Unsubscribe;
+    dispose(): void;
 }
 
 export declare type BlocksExtender<P extends Product = Product> = (result: BlocksResult<P>, raw: LayersResponse & {
@@ -135,37 +81,29 @@ declare interface BlocksInfo {
 export declare interface BlocksOptions {
     blockId: string;
     anchorId?: string;
-    anchorHandle?: string;
 }
 
-export declare interface BlocksResult<P extends Product = Product> extends BaseResult<P> {
+export declare interface BlocksQuery extends QueryParams {
+    discountEntitlements?: DiscountEntitlement[];
+    context?: BlocksContext;
+}
+
+export declare interface BlocksResult<P extends Product = Product> extends QueryResult<P> {
     block?: BlocksInfo;
 }
 
 export declare type BodyTransformer = (body: Record<string, unknown>) => Record<string, unknown>;
 
-export declare interface CollectionController<P extends Product = Product> {
-    state: ReadonlySignal<QueryState<CollectionResult<P>>>;
-    execute: (query?: CollectionExecuteQuery) => Promise<Result<CollectionResult<P>, SdkError>>;
-    dispose: () => void;
+declare interface CacheEntry<T> {
+    data: T;
+    timestamp: number;
 }
 
-export declare interface CollectionExecuteQuery {
-    page?: number;
-    limit?: number;
-    filters?: unknown;
-    sortOrderCode?: string;
-    signal?: AbortSignal;
-    includeMeta?: boolean;
-    collectionMetafields?: {
-        namespace: string;
-        key: string;
-    }[];
-    includeFilters?: boolean;
-    dynamicLinking?: Record<string, string | number | (string | number)[]>;
-    params?: Record<string, unknown>;
-    paramDefinitions?: ParamDefinitions;
-    transformBody?: BodyTransformer;
+export declare interface CollectionController<P extends Product = Product> {
+    readonly state: ReadonlySignal<QueryState<CollectionResult<P>>>;
+    execute(query?: CollectionQuery): Promise<Result<CollectionResult<P>, SdkError>>;
+    subscribe(callback: (state: QueryState<CollectionResult<P>>) => void): Unsubscribe;
+    dispose(): void;
 }
 
 export declare type CollectionExtender<P extends Product = Product> = (result: CollectionResult<P>, raw: LayersResponse) => CollectionResult<P>;
@@ -181,7 +119,7 @@ declare interface CollectionMeta {
         width?: number;
         height?: number;
     };
-    metafields?: (MetafieldResult_2 | null)[];
+    metafields?: (Metafield | null)[];
     totalProducts: number;
     totalPages: number;
     lastPageFetched: number;
@@ -194,7 +132,17 @@ export declare interface CollectionOptions {
     defaultSort?: string;
 }
 
-export declare interface CollectionResult<P extends Product = Product> extends BaseResult<P> {
+export declare interface CollectionQuery extends QueryParams {
+    sortOrderCode?: string;
+    includeMeta?: boolean;
+    collectionMetafields?: {
+        namespace: string;
+        key: string;
+    }[];
+    includeFilters?: boolean;
+}
+
+export declare interface CollectionResult<P extends Product = Product> extends QueryResult<P> {
     collection?: StorefrontCollection;
 }
 
@@ -218,6 +166,13 @@ export declare interface ConfigError {
 
 declare type ConfigErrorCode = 'MISSING_CONFIG' | 'INVALID_CONFIG';
 
+export declare interface Controller<TData, TQuery = void> {
+    readonly state: ReadonlySignal<QueryState<TData>>;
+    execute(query: TQuery): Promise<Result<TData, SdkError>>;
+    subscribe(callback: (state: QueryState<TData>) => void): Unsubscribe;
+    dispose(): void;
+}
+
 export declare function createProductCard({ product, selectedOptions: initialSelectedOptions, breakoutOptions: initialBreakoutOptions, }: CreateProductCardParams): ProductCardController;
 
 export declare interface CreateProductCardParams {
@@ -245,17 +200,12 @@ declare interface DiscountEntitlement {
 
 export { effect }
 
-declare interface Entry<T> {
-    data: T;
-    timestamp: number;
-}
-
 export declare function eq(property: string, value: FilterValue): FilterExpression;
 
 export declare function exists(property: string): FilterExpression;
 
-declare interface ExtendedProduct extends BaseProduct {
-    _base: BaseProduct;
+declare interface ExtendedProduct extends Product {
+    _base: Product;
 }
 
 declare interface Facet {
@@ -342,6 +292,13 @@ declare interface FilterValueResult {
     input: string;
 }
 
+export declare interface FireAndForgetController<TData, TQuery = void> {
+    readonly state: ReadonlySignal<QueryState<TData>>;
+    execute(query: TQuery): void;
+    subscribe(callback: (state: QueryState<TData>) => void): Unsubscribe;
+    dispose(): void;
+}
+
 export declare function getSdk(): Result<Sdk, ConfigError>;
 
 declare interface GraphQLErrorDetail {
@@ -369,8 +326,6 @@ export declare function gte(property: string, value: number): FilterExpression;
  */
 declare type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
 
-declare type ID = CommerceBlocksID;
-
 declare interface Image_2 {
     url: string;
     alt: string;
@@ -388,17 +343,9 @@ declare interface ImageResult {
     height: number;
 }
 
-export declare interface ImageSearchOptions {
+export declare interface ImageSearchQuery extends QueryParams {
     imageId: string;
-    page?: number;
-    limit?: number;
-    filters?: unknown;
     tuning?: LayersTuning;
-    signal?: AbortSignal;
-    dynamicLinking?: Record<string, string | number | (string | number)[]>;
-    params?: Record<string, unknown>;
-    paramDefinitions?: ParamDefinitions;
-    transformBody?: BodyTransformer;
 }
 
 export declare function inValues(property: string, values: FilterValue[]): FilterExpression;
@@ -443,6 +390,16 @@ declare interface LayersMeta {
     variantBreakouts?: {
         optionCode: string;
     }[];
+    redirect?: {
+        url: string;
+    };
+    timings?: {
+        embedding?: number;
+        query_expansion?: number;
+        intent_modifiers?: number;
+        prepare_total?: number;
+        query?: number;
+    };
 }
 
 declare interface LayersPagination {
@@ -466,6 +423,8 @@ declare interface LayersTuning {
     visualWeight?: number;
     multipleFactor?: number;
     minimumMatch?: number;
+    missingEmbeddingScore?: number;
+    highSignalWeight?: number;
 }
 
 declare interface LayersVariant {
@@ -524,13 +483,6 @@ declare interface MetafieldResult {
     type: string;
 }
 
-declare interface MetafieldResult_2 {
-    namespace: string;
-    key: string;
-    value: string;
-    type: string;
-}
-
 declare interface MoneyResult {
     amount: string;
     currencyCode: string;
@@ -609,15 +561,8 @@ declare interface PredictiveSearchResponse {
     normalizedQuery: string;
 }
 
-export declare interface PrepareSearchQuery {
-    query: string;
-    filters?: unknown;
-    tuning?: LayersTuning;
-    signal?: AbortSignal;
-    dynamicLinking?: Record<string, string | number | (string | number)[]>;
-    params?: Record<string, unknown>;
-    paramDefinitions?: ParamDefinitions;
-    transformBody?: BodyTransformer;
+export declare interface PreparableController<TData, TQuery, TPrepareResult> extends Controller<TData, TQuery> {
+    prepare(query: TQuery): Promise<Result<TPrepareResult, SdkError>>;
 }
 
 export declare interface PrepareSearchResult {
@@ -630,12 +575,50 @@ export declare interface Price {
     formatted: string;
 }
 
+export declare interface PriceRange {
+    min: Price;
+    max: Price;
+}
+
 declare interface PriceRangeResult {
     minVariantPrice: MoneyResult;
     maxVariantPrice: MoneyResult;
 }
 
-export declare type Product = BaseProduct;
+export declare interface Product {
+    id: CommerceBlocksID;
+    gid: ProductGID;
+    numericId: number;
+    title: string;
+    handle: string;
+    type: string;
+    vendor: string;
+    description: string;
+    availableForSale: boolean;
+    images: Image_2[];
+    priceRange: PriceRange;
+    compareAtPriceRange?: PriceRange;
+    options: RichProductOption[];
+    tags: string[];
+    variants: ProductVariant[];
+    selectedOptions: ProductOption[];
+    metafields: Record<string, Record<string, unknown>> | unknown[];
+    calculated?: Record<string, unknown>;
+    isGiftCard: boolean;
+    category: ProductCategory | null;
+    createdAt: string | null;
+    publishedAt: string | null;
+    updatedAt: string | null;
+    featuredMedia: FeaturedMedia | null;
+    namedTags?: NamedTag[];
+    combinedListingParentProductId: number | null;
+    combinedListingRole: string | null;
+    hasVariantsThatRequireComponents: boolean;
+    originalOptions: Record<string, string[]>;
+    selectedVariant: ProductVariant | null;
+    breakoutOptions?: ProductOption[];
+    breakoutVariantId?: number;
+}
 
 export declare interface ProductCardController {
     product: Product;
@@ -744,7 +727,7 @@ declare interface ProductResult {
 }
 
 export declare interface ProductVariant {
-    id: ID;
+    id: CommerceBlocksID;
     gid: VariantGID;
     numericId: number;
     title: string;
@@ -766,20 +749,21 @@ export declare interface ProductVariant {
 
 declare type Queries<P extends Product = Product> = Record<string, QueryResult<P>>;
 
-declare interface QueryResult<P extends Product = Product> {
+export declare interface QueryParams {
+    page?: number;
+    limit?: number;
+    filters?: unknown;
+    signal?: AbortSignal;
+    dynamicLinking?: Record<string, string | number | (string | number)[]>;
+    params?: Record<string, unknown>;
+    paramDefinitions?: ParamDefinitions;
+    transformBody?: BodyTransformer;
+}
+
+declare interface QueryResult<P extends Product = Product> extends Omit<LayersResponse, 'results' | 'facets'> {
     products: P[];
-    totalResults: number;
-    totalPages: number;
-    page: number;
-    resultsPerPage?: number;
     facets: Record<string, Record<string, number>>;
-    facetRanges?: Record<string, {
-        min: number;
-        max: number;
-    }>;
-    attributionToken?: string;
-    _meta?: LayersMeta;
-    _workflow?: unknown;
+    priceRange?: PriceRange;
 }
 
 export declare interface QueryState<T> {
@@ -819,10 +803,10 @@ export declare interface Sdk<P extends Product = Product> {
     collection: (options: CollectionOptions) => CollectionController<P>;
     blocks: (options: BlocksOptions) => BlocksController<P>;
     autocomplete: (options?: AutocompleteOptions) => AutocompleteController;
-    search: () => SearchController<P>;
+    search: (options?: SearchQuery) => SearchController<P>;
     storefront: (query: StorefrontQuery) => ReadonlySignal<QueryState<StorefrontResult<P>>>;
     uploadImage: (options: UploadImageOptions) => ReadonlySignal<QueryState<UploadImageResult>>;
-    imageSearch: (options: ImageSearchOptions) => ReadonlySignal<QueryState<SearchResult<P>>>;
+    imageSearch: (options: ImageSearchQuery) => ReadonlySignal<QueryState<SearchResult<P>>>;
     config: SdkConfig<P>;
     store: Store<P>;
 }
@@ -872,32 +856,26 @@ export declare interface SdkConfig<P extends Product = Product> extends LayersCl
     restoreFromStorage?: boolean;
 }
 
-export declare type SdkError = NetworkError | ApiError | ValidationError | ConfigError;
+export declare type SdkError = ServiceError | ConfigError;
 
 export declare interface SearchController<P extends Product = Product> {
-    state: ReadonlySignal<QueryState<SearchResult<P>>>;
-    prepare: (query: PrepareSearchQuery) => Promise<Result<PrepareSearchResult, SdkError>>;
-    execute: (query: SearchQuery) => Promise<Result<SearchResult<P>, SdkError>>;
-    dispose: () => void;
+    readonly state: ReadonlySignal<QueryState<SearchResult<P>>>;
+    prepare(query?: SearchQuery): Promise<Result<PrepareSearchResult, SdkError>>;
+    execute(query?: SearchQuery): Promise<Result<SearchResult<P>, SdkError>>;
+    subscribe(callback: (state: QueryState<SearchResult<P>>) => void): Unsubscribe;
+    dispose(): void;
 }
 
 export declare type SearchExtender<P extends Product = Product> = (result: SearchResult<P>, raw: LayersResponse) => SearchResult<P>;
 
-export declare interface SearchQuery {
-    query: string;
+export declare interface SearchQuery extends QueryParams {
+    query?: string;
     searchId?: string;
-    page?: number;
-    limit?: number;
-    filters?: unknown;
     tuning?: LayersTuning;
-    signal?: AbortSignal;
-    dynamicLinking?: Record<string, string | number | (string | number)[]>;
-    params?: Record<string, unknown>;
-    paramDefinitions?: ParamDefinitions;
-    transformBody?: BodyTransformer;
+    transient?: boolean;
 }
 
-export declare type SearchResult<P extends Product = Product> = BaseResult<P>;
+export declare type SearchResult<P extends Product = Product> = QueryResult<P>;
 
 declare interface SelectedOptionResult {
     name: string;
@@ -909,6 +887,8 @@ declare interface SeoResult {
     description: string | null;
 }
 
+declare type ServiceError = NetworkError | ApiError | ValidationError;
+
 declare type ShopifyGID<T extends ShopifyType> = `gid://shopify/${T}/${number}`;
 
 declare type ShopifyType = 'Product' | 'ProductVariant' | 'Collection';
@@ -943,7 +923,7 @@ declare interface Store<P extends Product = Product> {
         has(gid: ProductGID): boolean;
     };
     queries: {
-        get(key: string): ReadonlySignal<Entry<QueryResult<P>> | null>;
+        get(key: string): ReadonlySignal<CacheEntry<QueryResult<P>> | null>;
         set(key: string, result: QueryResult<P>): void;
         isExpired(key: string): boolean;
         invalidate(pattern: string): void;
@@ -1070,6 +1050,11 @@ export declare interface StoreOptions {
     storageAdapter?: StorageAdapter;
 }
 
+/**
+ * Subscribe to state changes. Callback fires immediately, then on every change.
+ */
+export declare function subscribe<T>(state: ReadonlySignal<QueryState<T>>, callback: (state: QueryState<T>) => void): Unsubscribe;
+
 export declare interface Swatch {
     name: string | null;
     value: string;
@@ -1086,6 +1071,8 @@ declare interface SwatchResult {
     } | null;
 }
 
+export declare type Unsubscribe = () => void;
+
 export declare interface UploadImageOptions {
     image: File | Blob;
     signal?: AbortSignal;