@iheartjane/dm-sdk 2.24.1

package/dist/index.d.ts

@@ -0,0 +1,1181 @@
+import { P as Placement, A as AdMode, F as FilterContext, a as PageContextEnum, S as SearchSortEnum, C as Click, I as Impression, b as CustomImageData, c as SmartSortProductProps, d as SmartSortClickIntent, e as SmartSortProps, f as ConversionExternalProduct, g as SessionEvent, R as RequiredConfig, J as JaneDMPublicConfig, h as JaneDMInternalConfig, i as FetchCartTopperRowProps, j as FetchCustomImageRowProps, k as Facets, l as FetchMenuRowProps, m as FetchMenuTopRowProps, n as FetchProductReviewsProps, o as ProductReviewsResponse, p as FetchRecommendedPDPRowProps, q as FetchRecommendedRowProps, r as FetchRecommendedSortProps, V as VirtualBudtenderQuery, s as IterateProductReviewsProps, t as ProductReviewsIterable } from './smartSort-DJFM0D_n.js';
+export { u as AppMode, D as DEFAULT_PAGE_SIZE, v as FetchCartTopperRowByPosProductId, w as FetchCartTopperRowByProductProps, x as FetchRecommendedPDPRowByPosProductId, y as FetchRecommendedPDPRowByProductId, z as IntendedDisplay, B as JaneDMConfig, E as JaneDMIdentifiers, G as JaneDeviceIdSentinel, H as PaginationInfo, K as ProductKindEnum, L as ProductReview, M as ProductReviewsAggregate, N as ReviewSortEnum, O as SearchSort, Q as SmartSortNextPageProps, T as VirtualBudtenderSearchResponse, U as bestSellerRank, W as categoryAndNameAsc, X as defaultOrder, Y as priceAsc, Z as priceDesc, _ as priceEighthOunceAsc, $ as priceEighthOunceDesc, a0 as priceGramAsc, a1 as priceGramDesc, a2 as priceHalfGramAsc, a3 as priceHalfGramDesc, a4 as priceHalfOunceAsc, a5 as priceHalfOunceDesc, a6 as priceOunceAsc, a7 as priceOunceDesc, a8 as priceQuarterOunceAsc, a9 as priceQuarterOunceDesc, aa as priceTwoGramAsc, ab as priceTwoGramDesc, ac as rating, ad as recommendation, ae as searchSorts, af as thcPotencyAsc, ag as thcPotencyDesc } from './smartSort-DJFM0D_n.js';
+
+interface CustomBestSellingProps {
+    placement: Placement.BestSelling;
+    title?: string;
+}
+interface CustomBrandSpecialsProps {
+    placement: Placement.BrandSpecials;
+    title?: string;
+}
+interface CustomBuyAgainRowProps {
+    placement: Placement.BuyAgainRow;
+    title?: string;
+}
+interface CustomFeaturedRowProps {
+    placement: Placement.FeaturedRow;
+    rowId: number;
+}
+interface CustomImageRowProps {
+    placement: Placement.CustomImageRow;
+    searchFilter?: string;
+}
+interface CustomMenuDynamicRowProps {
+    adMode?: AdMode;
+    filterContext?: FilterContext[];
+    pageContext?: PageContextEnum;
+    placement: Placement.MenuDynamicRow;
+}
+interface CustomMenuInlineProps {
+    adMode?: AdMode;
+    metadata?: Record<string, unknown>;
+    placement: Placement.MenuInline;
+    searchFilter?: string;
+    searchQuery?: string;
+    searchSort?: SearchSortEnum;
+    title?: string;
+}
+interface CustomMenuInlineTableProps {
+    disableAds?: boolean;
+    maxProducts?: number;
+    metadata?: Record<string, unknown>;
+    pageSize?: number;
+    placement: Placement.MenuInlineTable;
+    searchFacets?: string[];
+    searchFilter?: string;
+    searchQuery?: string;
+    searchSort?: SearchSortEnum;
+    title?: string;
+}
+interface CustomMenuTopRowProps {
+    placement: Placement.MenuTopRow;
+    searchFilter?: string;
+}
+type CustomPlacementProps = CustomBestSellingProps | CustomBrandSpecialsProps | CustomBuyAgainRowProps | CustomFeaturedRowProps | CustomImageRowProps | CustomMenuDynamicRowProps | CustomMenuInlineProps | CustomMenuInlineTableProps | CustomMenuTopRowProps | CustomSaleProps | CustomSpecialsProps;
+interface CustomSaleProps {
+    placement: Placement.Sale;
+    title?: string;
+}
+interface CustomSpecialsProps {
+    placement: Placement.Specials;
+    title?: string;
+}
+interface FetchCustomPlacementsProps extends CommonProps {
+    /**
+     * The placements to fetch.
+     */
+    placements: CustomPlacementProps[];
+}
+interface FetchFeaturedPlacementProps extends CommonProps {
+    /**
+     * Whether to exclude the menu top row from the featured placements.
+     */
+    excludeMenuTopRow?: boolean;
+}
+interface CommonProps {
+    numColumns?: number;
+    /**
+     * The attributes to be returned in the response.
+     */
+    searchAttributes: string[];
+    /**
+     * The ID of the store to fetch the placements from.
+     */
+    storeId: number;
+}
+
+type FetchProductProps = {
+    searchAttributes: string[];
+    storeId: number;
+} & (ProductById | ProductByPosProductId);
+interface ProductById {
+    posProductId?: never;
+    productId: number;
+}
+interface ProductByPosProductId {
+    posProductId: string;
+    productId?: never;
+}
+
+/**
+ * The VirtualBudtenderClickIntent is used to determine if the click
+ * event should be treated as an "add to cart" event.
+ */
+interface VirtualBudtenderClickIntent {
+    /**
+     * When set to true, the click event will be treated as an "add to cart" event.
+     * @default false
+     */
+    isAddToCart?: boolean;
+}
+/**
+ * Properties to create a `VirtualBudtenderProduct` instance.
+ * @internal
+ */
+interface VirtualBudtenderProductProps<ProductAttributes extends object = Record<string, unknown>> {
+    /**
+     * The raw Virtual Budtender product data
+     */
+    attributes: ProductAttributes;
+    /**
+     * Click tracking payload
+     */
+    clickPayload: Click;
+    /**
+     * Click tracking URL
+     */
+    clickUrl: string;
+    /**
+     * Whether this product has been impressed yet
+     */
+    hasBeenImpressed?: boolean;
+    /**
+     * Impression tracking payload
+     */
+    impressPayload: Impression;
+    /**
+     * Impression tracking URL
+     */
+    impressUrl: string;
+    /**
+     * Boolean that indicates if a product is sponsored or not
+     */
+    isSponsored: boolean;
+    /**
+     * The primary identifier for this product
+     */
+    objectId: string;
+    /**
+     * The reasoning for the product
+     */
+    reasoning?: string;
+    /**
+     * The score of the product
+     */
+    score?: number;
+}
+/**
+ * Parameters for fetching virtual budtender query suggestions.
+ * @internal
+ */
+interface VirtualBudtenderQueriesParams {
+    /**
+     * The store ID to get queries for
+     */
+    storeId: number;
+}
+/**
+ * Parameters for virtual budtender search.
+ * @internal
+ */
+interface VirtualBudtenderSearchParams {
+    /**
+     * Natural language query for product search
+     */
+    query: string;
+    /**
+     * Optional search attributes to include in the results
+     */
+    searchAttributes?: string[];
+    /**
+     * Store ID to search products in
+     */
+    storeId: number;
+}
+
+/**
+ * Parameters for fetching facets.
+ */
+interface FetchFacetsParams {
+    /**
+     * A list of search facets to be returned in the search results, such as
+     * `['kind']`.
+     */
+    searchFacets?: string[];
+    /**
+     * A filter string to be applied to the search results, such as
+     * `'kind:flower'`.
+     */
+    searchFilter?: string;
+    /**
+     * A search query to filter results.
+     */
+    searchQuery?: string;
+    /**
+     * The store ID to fetch facets for.
+     */
+    storeId: number;
+}
+
+/**
+ * Represents a product, called menu product in the Jane ecosystem, for a
+ * smart sort placement.
+ */
+declare class SmartSortProduct<ProductShape extends object = Record<string, unknown>> {
+    /**
+     * The attributes of this product.
+     * The shape and data of this field will change depending on the requested
+     * attributes.
+     * @example
+     * ```jsx
+     * { product_id: '1234' }
+     * ```
+     */
+    attributes: ProductShape;
+    /**
+     * Boolean that indicates if a product is sponsored or not
+     */
+    isSponsored: boolean;
+    /**
+     * The primary identifier for this product.
+     */
+    objectId: string;
+    private clickPayload;
+    private clickUrl;
+    private hasBeenImpressed;
+    private impressPayload;
+    private impressPromise?;
+    private impressUrl;
+    /**
+     * Builds a new SmartSortProduct instance based on the provided properties.
+     * This method should be used in conjunction with `serialize()` to recreate the instance.
+     */
+    constructor(props: SmartSortProductProps<ProductShape>);
+    /**
+     * Converts the previously-serialized object back to an instance of this class.
+     * This method should be used in conjunction with `toJSON()` to recreate the instance.
+     */
+    static fromJSON<ProductShape extends object = Record<string, unknown>>(serialized: string): SmartSortProduct<ProductShape>;
+    /**
+     * Records attribution data for this product. This method
+     * should be called when the product is clicked by the user.
+     * If the click is associated with an add to cart action,
+     * that intent should be passed to the click method.
+     * @example
+     * ```jsx
+     * placement.products.map((product) => {
+     *   return (<ProductCard
+     *     product={product}
+     *     onClick={() => product.click()}
+     *     key={product.objectId}
+     *   >
+     *     <Button
+     *       title="Add to Cart"
+     *       onClick={() => product.click({isAddToCart: true})}
+     *      />
+     *   </ProductCard>);
+     * });
+     * ```
+     */
+    click(props?: SmartSortClickIntent): Promise<void>;
+    /**
+     * Records attribution data for this product. This method
+     * should be called when the product is visible by the user in
+     * the viewport, as a visible DOM element.
+     * See {@link https://www.npmjs.com/package/react-intersection-observer react-intersection-observer} for a React component that can be used to detect when an element is in the viewport.
+     * @example
+     * ```jsx
+     * import { InView } from "react-intersection-observer";
+     *
+     * const Component = () => (
+     *   <InView onChange={(inView) => {
+     *     if(inView) {
+     *       product.impress();
+     *     }
+     *   }}>
+     *     <ProductCard />
+     *   </InView>
+     * );
+     * ```
+     */
+    impress(): Promise<void>;
+    /**
+     * Converts the object in a JSON-serializable data structure that should be
+     * used **unmodified** in the constructor to create a new instance of this class.
+     * This method should be used in conjunction with `new SmartSortProduct()` to recreate the instance.
+     *
+     * This function is especially helpful in a server-side environment to
+     * keep track of the same instance across client side and server side
+     * rendered components.
+     * @example
+     * ```jsx
+     * let serializedObj = obj.serialize();
+     * let deserializedObj = new SmartSortProduct(serializedObj);
+     * ```
+     */
+    serialize(): SmartSortProductProps<ProductShape>;
+    /**
+     * Converts the object to a JSON string, using `serialize()` behind the
+     * scenes. The returned value should be used **unmodified** in the
+     * `SmartSortProduct.fromJSON()` static method.
+     * This method should be used in conjunction with `SmartSortProduct.fromJSON()` to recreate the instance.
+     */
+    toJSON(): string;
+}
+/**
+ * Represents a configurable placement that can be used in
+ * different type of pages.
+ *
+ * In a server side context, this instance can be recreated over to the
+ * client by using the **unmodified** properties provided by the `serialize()`
+ * method.
+ */
+declare class SmartSort<ProductShape extends object = Record<string, unknown>> {
+    /**
+     * The custom images for the current instance. Always an array; empty when
+     * the placement returns no custom images.
+     */
+    customImages: CustomImageData[];
+    /**
+     * The placement type of the current instance.
+     */
+    placement?: Placement;
+    /**
+     * A mix of organic and sponsored products for this placement.
+     * @example
+     * ```jsx
+     * placement.products.map((product) => {
+     *   return (<ProductCard
+     *     product={product}
+     *     onClick={() => product.click()}
+     *     key={product.objectId}
+     *   />);
+     * });
+     * ```
+     */
+    products: SmartSortProduct<ProductShape>[];
+    /**
+     * The row id of the placement.
+     */
+    rowId?: number;
+    /**
+     * A map of search facets for this placement.
+     * @example
+     * ```json
+     * {
+     *   "category": {
+     *     "sativa": 20,
+     *     "indica": 10,
+     *   },
+     *   "kind": {
+     *     "flower": 31,
+     *     "vape": 5,
+     *   },
+     * }
+     * ```
+     */
+    searchFacets?: Record<string, Record<string, number>>;
+    /**
+     * The title of the placement.
+     */
+    title: string | undefined;
+    /**
+     * The total number of products available for this placement.
+     */
+    totalProducts: number;
+    /**
+     * Creative ids associated with the current request.
+     *
+     * @internal
+     */
+    protected creativeIds: number[] | undefined;
+    private cachedProducts;
+    private config;
+    private loadPromise?;
+    private nextPageProps;
+    private nextPageUrl;
+    /**
+     * Builds a new SmartSort instance based on the provided properties.
+     *
+     * This method should be used in conjunction with `serialize()` to recreate the instance.
+     */
+    constructor(props: SmartSortProps<ProductShape>);
+    /**
+     * Converts the previously-serialized object back to an instance of this class.
+     * This method should be used in conjunction with `toJSON()` to recreate the instance.
+     */
+    static fromJSON<ProductShape extends object = Record<string, unknown>>(serialized: string): SmartSort<ProductShape>;
+    /**
+     * Boolean that indicates if more products are available for this placement.
+     */
+    hasNextPage(): boolean;
+    /**
+     * Retrieves the next page of mixed organic and sponsored products for
+     * this placement.
+     *
+     * The `products` property will have the new products appended.
+     * @example
+     * ```jsx
+     * function ProductsList({ placement }) {
+     *   let [hasMoreProducts, setHasMoreProducts] = useState(placement.hasNextPage());
+     *   let [products, setProducts] = useState(placement.products);
+     *
+     *   let loadMore = (async () => {
+     *     await placement.nextPage();
+     *     setHasMoreProducts(placement.hasNextPage());
+     *     setProducts([...placement.products]);
+     *   });
+     *
+     *   return (
+     *     <div>
+     *       <button onclick={() => {loadMore()}} disabled={!hasMoreProducts}>Load more</button>
+     *       <div>
+     *         {products.map((product) => {
+     *           return (<ProductCard
+     *             product={product}
+     *             onClick={() => product.click()}
+     *             key={product.objectId}
+     *           />);
+     *         }}
+     *       </div>
+     *     </div>
+     *   );
+     * }
+     * ```
+     */
+    nextPage(): Promise<void>;
+    /**
+     * Triggers fingerprint collection and session event for the placement.
+     *
+     * **Note:** This method is called automatically when the placement is created on the client side,
+     * so manual calls are not necessary. It's safe to call multiple times due to built-in idempotency.
+     *
+     * @internal This is called automatically by the constructor. Manual calls are only needed for advanced use cases.
+     */
+    onLoad(): Promise<void>;
+    /**
+     * Converts the object in a JSON-serializable data structure that should be
+     * used **unmodified** in the constructor to create a new instance of this class.
+     * This method should be used in conjunction with `new SmartSort()` to recreate the instance.
+     *
+     * This function is especially helpful in a server-side environment to
+     * keep track of the same instance across client side and server side
+     * rendered components.
+     * @example
+     * ```jsx
+     * let serializedObj = obj.serialize();
+     * let deserializedObj = new SmartSort(serializedObj);
+     * ```
+     */
+    serialize(): SmartSortProps<ProductShape>;
+    /**
+     * Converts the object to a JSON string, using `serialize()` behind the
+     * scenes. The returned value should be used **unmodified** in the
+     * `SmartSort.fromJSON()` static method.
+     * This method should be used in conjunction with `SmartSort.fromJSON()` to recreate the instance.
+     */
+    toJSON(): string;
+}
+
+type MultiPlacementResponse<ProductShape extends object = Record<string, unknown>> = BrandSpecials | SmartSort<ProductShape> | Specials;
+declare class BrandSpecials {
+    placement: Placement.BrandSpecials;
+    title: string | undefined;
+    constructor(title: string | undefined);
+}
+declare class Specials {
+    placement: Placement.Specials;
+    title: string | undefined;
+    constructor(title: string | undefined);
+}
+
+/**
+ * Parameters to record attribution data for a checkout event.
+ */
+interface PosCheckoutParams {
+    /**
+     * The unique identifier for the order in the POS system.
+     */
+    posOrderId: string;
+    /**
+     * The unique identifier for the authenticated user checking out in the
+     * POS system.
+     */
+    posUserId?: string;
+    /**
+     * The products that were purchased at checkout.
+     */
+    products: ConversionExternalProduct[];
+    /**
+     * The unique identifier for the store, according to the Jane ecosystem.
+     */
+    storeId: number;
+}
+
+/**
+ * Parameters that represent events by the user in a given session.
+ */
+interface SessionEventParams {
+    /**
+     * Either events when user clicked to add a product to the cart or
+     * filtered for a category.
+     */
+    events: SessionEvent[];
+}
+
+interface VirtualBudtenderSearchWithProductsResponse<ProductShape extends object = Record<string, unknown>> {
+    htmlResponse: string;
+    markdownResponse: string;
+    products: VirtualBudtenderProduct<ProductShape>[];
+    query: string;
+    totalResults: number;
+    unformattedResponse: string;
+}
+/**
+ * Represents a product returned from Virtual Budtender search.
+ * Provides tracking methods for click and impression events.
+ *
+ * @internal
+ */
+declare class VirtualBudtenderProduct<ProductShape extends object = Record<string, unknown>> {
+    /**
+     * The raw Virtual Budtender product data including search attributes and reasoning.
+     */
+    attributes: ProductShape;
+    /**
+     * Boolean that indicates if a product is sponsored or not
+     */
+    isSponsored: boolean;
+    /**
+     * The primary identifier for this product.
+     */
+    objectId: string;
+    /**
+     * The reasoning for the product
+     */
+    reasoning?: string;
+    /**
+     * The score of the product
+     */
+    score?: number;
+    private clickPayload;
+    private clickUrl;
+    private hasBeenImpressed;
+    private impressPayload;
+    private impressPromise?;
+    private impressUrl;
+    /**
+     * Builds a new VirtualBudtenderProduct instance based on the provided properties.
+     * This method should be used in conjunction with `serialize()` to recreate the instance.
+     */
+    constructor(props: VirtualBudtenderProductProps<ProductShape>);
+    /**
+     * Converts the previously-serialized object back to an instance of this class.
+     * This method should be used in conjunction with `toJSON()` to recreate the instance.
+     */
+    static fromJSON<ProductShape extends object = Record<string, unknown>>(serialized: string): VirtualBudtenderProduct<ProductShape>;
+    /**
+     * Records attribution data for this product. This method
+     * should be called when the product is clicked by the user.
+     * If the click is associated with an add to cart action,
+     * that intent should be passed to the click method.
+     * @example
+     * ```jsx
+     * results.products.map((product) => {
+     *   return (<ProductCard
+     *     product={product}
+     *     onClick={() => product.click()}
+     *     key={product.objectId}
+     *   >
+     *     <Button
+     *       title="Add to Cart"
+     *       onClick={() => product.click({isAddToCart: true})}
+     *      />
+     *   </ProductCard>);
+     * });
+     * ```
+     */
+    click(props?: VirtualBudtenderClickIntent): Promise<void>;
+    /**
+     * Records attribution data for this product. This method
+     * should be called when the product is visible by the user in
+     * the viewport, as a visible DOM element.
+     * See {@link https://www.npmjs.com/package/react-intersection-observer react-intersection-observer} for a React component that can be used to detect when an element is in the viewport.
+     * @example
+     * ```jsx
+     * import { InView } from "react-intersection-observer";
+     *
+     * const Component = () => (
+     *   <InView onChange={(inView) => {
+     *     if(inView) {
+     *       product.impress();
+     *     }
+     *   }}>
+     *     <ProductCard />
+     *   </InView>
+     * );
+     * ```
+     */
+    impress(): Promise<void>;
+    /**
+     * Serializes the instance to a plain object for storage or transport.
+     * This method should be used in conjunction with `fromJSON()` to recreate the instance.
+     */
+    serialize(): VirtualBudtenderProductProps<ProductShape>;
+    /**
+     * Converts the instance to a JSON string for storage or transport.
+     * This method should be used in conjunction with `fromJSON()` to recreate the instance.
+     */
+    toJSON(): string;
+}
+
+type Func<T> = () => Promise<T>;
+/**
+ * Generic Cell Rate Algorithm (GCRA) rate limiter implementation.
+ *
+ * Provides smooth rate limiting with burst capacity, allowing temporary spikes
+ * in traffic while maintaining an average rate limit over time. Unlike simple
+ * token bucket algorithms, GCRA provides more predictable and smoother rate limiting.
+ *
+ * @example
+ * ```typescript
+ * // Allow 10 requests per second with a burst of 3
+ * const limiter = new GcraRateLimiter(10, 3);
+ *
+ * // First 3 calls execute immediately (burst capacity)
+ * await limiter.schedule(() => apiCall1());
+ * await limiter.schedule(() => apiCall2());
+ * await limiter.schedule(() => apiCall3());
+ *
+ * // 4th call waits ~100ms to maintain 10 req/sec rate
+ * await limiter.schedule(() => apiCall4());
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Conservative rate limiting: 1 request per second, no burst
+ * const conservativeLimiter = new GcraRateLimiter(1, 1);
+ *
+ * await conservativeLimiter.schedule(() => slowApiCall1()); // immediate
+ * await conservativeLimiter.schedule(() => slowApiCall2()); // waits 1000ms
+ * ```
+ */
+declare class GcraRateLimiter {
+    /** Maximum number of requests that can be made in a burst */
+    private burst;
+    /** Time interval between requests in milliseconds */
+    private intervalMs;
+    /** Maximum requests per second */
+    private rate;
+    /** Theoretical arrival time in milliseconds - tracks when next request should ideally arrive */
+    private tat;
+    /** Burst window tolerance in milliseconds - how much early arrival is allowed */
+    private toleranceMs;
+    /**
+     * Creates a new GCRA rate limiter.
+     *
+     * @param rate - Maximum number of requests per second (must be > 0)
+     * @param burst - Maximum number of requests that can be made immediately without waiting (default: 1, must be >= 1)
+     *
+     * @throws {SdkError} When rate <= 0
+     * @throws {SdkError} When burst < 1
+     *
+     * @example
+     * ```typescript
+     * // 5 requests per second, burst of 2
+     * const limiter = new GcraRateLimiter(5, 2);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // 0.5 requests per second (one every 2 seconds), no burst
+     * const slowLimiter = new GcraRateLimiter(0.5, 1);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // 20 requests per second, burst of 20
+     * const limiter = new GcraRateLimiter(20, 20);
+     * ```
+     */
+    constructor(rate: number, burst?: number);
+    /**
+     * Schedules a function to be executed under rate limiting constraints.
+     *
+     * The function will either execute immediately (if within rate limits) or be
+     * delayed until the rate limit allows execution. The delay is calculated using
+     * the GCRA algorithm to maintain smooth, predictable rate limiting.
+     *
+     * @template T - The return type of the scheduled function
+     * @param fn - The function to execute. Must return a Promise.
+     * @returns Promise that resolves with the function's result after rate limiting
+     *
+     * @example
+     * ```typescript
+     * const limiter = new GcraRateLimiter(2, 1); // 2 req/sec, no burst
+     *
+     * // First call executes immediately
+     * const result1 = await limiter.schedule(async () => {
+     *   const response = await fetch('/api/data');
+     *   return response.json();
+     * });
+     *
+     * // Second call waits 500ms before executing
+     * const result2 = await limiter.schedule(async () => {
+     *   return await someAsyncOperation();
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // 20 requests per second, burst of 20
+     * const limiter = new GcraRateLimiter(20, 20);
+     *
+     *
+     * // First 20 calls execute immediately (burst capacity)
+     * await limiter.schedule(async () => {
+     *   return await someAsyncOperation();
+     * });
+     *
+     * // 21st call waits ~100ms to maintain 20 req/sec rate
+     * await limiter.schedule(async () => {
+     *   return await someAsyncOperation();
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Error handling
+     * try {
+     *   const result = await limiter.schedule(async () => {
+     *     throw new Error('API failed');
+     *   });
+     * } catch (error) {
+     *   console.error('Scheduled function failed:', error);
+     * }
+     * ```
+     */
+    schedule<T>(fn: Func<T>): Promise<T>;
+}
+
+/**
+ * JaneDM is the main class that is used to interact with the Jane DM API.
+ * An instance is required to fetch ads and send checkout events.
+ * This is the **entry point for the Jane DM SDK.**
+ * @example
+ * ```jsx
+ * // Create instance - initialization happens automatically on first fetch
+ * let client = new JaneDM({
+ *   apiKey: 'your-api-key',
+ *   endpoint: 'https://dmerch.iheartjane.com',
+ *   identifier: { jdid: 'your-jdid', userId: 'your-user-id' },
+ * });
+ *
+ * // Or manually initialize if needed
+ * await client.init();
+ *
+ * function MenuTopRowComponent({ placement }) {
+ *   // Fingerprint collection and session events happen automatically when
+ *   // the placement is created - no manual calls needed
+ *
+ *   return (<div>...</div>);
+ * }
+ *
+ * // init() is called automatically before the first fetch operation
+ * let placement = await client.fetchMenuTopRow({ storeId: 420 });
+ *
+ * <MenuTopRowComponent placement={placement} />
+ * ```
+ */
+declare class JaneDM {
+    protected readonly config: RequiredConfig;
+    /**
+     * 20 requests per second, burst of 20
+     *
+     * DM Server rate is 40 requests per second, burst of 40
+     */
+    protected readonly rateLimiter: GcraRateLimiter;
+    private initialized;
+    private readonly multiClient;
+    private readonly productClient;
+    private readonly smartSortClient;
+    private userProvidedJdid;
+    /**
+     * Creates an instance of the Jane DM SDK client.
+     *
+     * @param props - Public configuration options for the Jane DM SDK client.
+     * @param internalConfig - Internal configuration options for the Jane DM SDK client. **DO NOT MODIFY INTERNAL CONFIGURATION OPTIONS. Unexpected behavior will result.**
+     * Internal configuration options are experimental and may change in the future.
+     */
+    constructor(props: JaneDMPublicConfig, internalConfig?: JaneDMInternalConfig);
+    /**
+     * Function used to generate a valid jane device id. This function is
+     * intended to be used upon initial setup in a SSR environment & stored in a cookie
+     */
+    static generateJaneDeviceId(): string;
+    /**
+     * Fetches a cart topper row placement from the Jane DM API. This
+     * placement represents a row of sponsored and organic products to be
+     * displayed in the cart page.
+     * A placement can be serialized to and from JSON for the purpose of
+     * server-side rendering, the serialized object **should not be persisted**
+     * because it has a very short lifecycle.
+     * @example
+     * ```jsx
+     * let placement = await client.fetchCartTopperRow({
+     *   // Required
+     *   storeId: 420,
+     *   // Required
+     *   searchAttributes: ['product_id', 'name'],
+     *   // Required
+     *   cartProductIds: [123, 456],
+     * });
+     * ```
+     */
+    fetchCartTopperRow<ProductShape extends object = Record<string, unknown>>(props: FetchCartTopperRowProps): Promise<SmartSort<ProductShape>>;
+    /**
+     * Fetches a custom image row placement from the Jane DM API. This
+     * placement represents a row of custom images to be displayed alongside
+     * lists or grids of products. The returned placement exposes the custom
+     * images through {@link SmartSort.customImages}.
+     * A placement can be serialized to and from JSON for the purpose of
+     * server-side rendering, the serialized object **should not be persisted**
+     * because it has a very short lifecycle.
+     * @internal
+     * @example
+     * ```jsx
+     * let placement = await client.fetchCustomImageRow({
+     *   // Required
+     *   storeId: 420,
+     *   searchAttributes: ['product_id', 'name'],
+     *   searchFilter: 'kind:flower',
+     * });
+     * ```
+     */
+    fetchCustomImageRow<ProductShape extends object = Record<string, unknown>>(props: FetchCustomImageRowProps): Promise<SmartSort<ProductShape>>;
+    /**
+     * Fetches a custom set of placements for the featured page for any given store.
+     *
+     * @example
+     * ```jsx
+     * const placements = await client.fetchCustomPlacements({
+     *   storeId: 420,
+     *   searchAttributes: ['product_id', 'name'],
+     * });
+     * ```
+     */
+    fetchCustomPlacements<ProductShape extends object = Record<string, unknown>>(props: FetchCustomPlacementsProps): Promise<MultiPlacementResponse<ProductShape>[]>;
+    /**
+     * Fetches facets from the Jane DM API.
+     * This method gets facet information that can be used for filtering products.
+     * @example
+     * ```jsx
+     * const facets = await client.fetchFacets({
+     *   storeId: 420,
+     *   searchFilter: 'kind:flower',
+     *   searchFacets: ['kind', 'category'],
+     * });
+     *
+     * console.log(facets.search_facets);
+     * ```
+     */
+    fetchFacets(props: FetchFacetsParams): Promise<Facets>;
+    /**
+     * Fetches featured placements from the Jane DM API. This method returns
+     * a list of placements that should be displayed on the featured page of any given store's menu
+     *
+     * @example
+     * ```jsx
+     * const placements = await client.fetchFeaturedPlacements({
+     *   storeId: 420,
+     *   searchAttributes: ['product_id', 'name'],
+     * });
+     * ```
+     */
+    fetchFeaturedPlacements<ProductShape extends object = Record<string, unknown>>(props: FetchFeaturedPlacementProps): Promise<MultiPlacementResponse<ProductShape>[]>;
+    /**
+     * Fetches a menu row placement from the Jane DM API. This placement
+     * represents a row of products to be displayed on a page displaying lists of products.
+     * A placement can be serialized to and from JSON for the purpose of
+     * server-side rendering, the serialized object **should not be persisted**
+     * because it has a very short lifecycle.
+     * @internal
+     * @example
+     * ```jsx
+     * let placement = await client.fetchMenuRow({
+     *   // Required
+     *   storeId: 420,
+     *   searchAttributes: ['product_id', 'name'],
+     *   searchFilter: 'kind:flower',
+     * });
+     * ```
+     */
+    fetchMenuRow<ProductShape extends object = Record<string, unknown>>(props: FetchMenuRowProps): Promise<SmartSort<ProductShape>>;
+    /**
+     * Fetches a top of menu row placement from the Jane DM API. This
+     * placement represents a row of sponsored products to be displayed at
+     * the top of the page displaying lists or grids of products.
+     * A placement can be serialized to and from JSON for the purpose of
+     * server-side rendering, the serialized object **should not be persisted**
+     * because it has a very short lifecycle.
+     *
+     * @example
+     * ```jsx
+     * let placement = await client.fetchMenuTopRow({
+     *   // Required
+     *   storeId: 420,
+     *   searchAttributes: ['product_id', 'name'],
+     *   searchFilter: 'kind:flower',
+     * });
+     * ```
+     */
+    fetchMenuTopRow<ProductShape extends object = Record<string, unknown>, AdditionalTypes = object>(props: FetchMenuTopRowProps<AdditionalTypes>): Promise<SmartSort<ProductShape>>;
+    /**
+     * Fetches a product from the Jane DM API. This method returns a product object that can be used to display product details.
+     * @example
+     * ```jsx
+     * const product = await client.fetchProduct({
+     *   // Required
+     *   storeId: 420,
+     *   // Required
+     *   searchAttributes: ['product_id', 'name'],
+     *   // Required one of, but not both
+     *   productId: 1234,
+     *   posProductId: '1234',
+     * });
+     * ```
+     */
+    fetchProduct<ProductShape extends object = Record<string, unknown>>(props: FetchProductProps): Promise<SmartSortProduct<ProductShape>>;
+    /**
+     * Fetches one page of product reviews from the Jane DM API. Returns
+     * individual reviews, pagination metadata, and aggregate rating data.
+     * Supports filtering by activities, feelings, and ratings.
+     *
+     * Use this method for UIs that paginate with page numbers, next/prev
+     * buttons, or infinite scroll. For server-side scenarios that need to
+     * traverse every matching review, prefer {@link JaneDM.iterateProductReviews}.
+     *
+     * @see {@link ProductReviewsResponse} for the full response shape.
+     * @see [Pagination guide](https://dm-sdk-docs.iheartjane.com/app/pagination).
+     *
+     * @example Traditional pagination
+     * ```tsx
+     * const response = await client.fetchProductReviews({
+     *   productId: 123,
+     *   page: 1,
+     *   pageSize: 20,
+     *   ratings: [4, 5],
+     * });
+     *
+     * response.items;                    // ProductReview[]
+     * response.pagination.totalPages;    // number of pages available
+     * response.pagination.hasNextPage;   // boolean
+     * response.aggregate.averageRating;  // number
+     * ```
+     *
+     * @example Next/prev navigation
+     * ```tsx
+     * <button disabled={!response.pagination.hasPreviousPage}>Prev</button>
+     * <button disabled={!response.pagination.hasNextPage}>Next</button>
+     * ```
+     */
+    fetchProductReviews(props: FetchProductReviewsProps): Promise<ProductReviewsResponse>;
+    /**
+     * Fetches a recommended PDP row placement from the Jane DM API. This
+     * placement represents a row of sponsored products to be displayed in a
+     * product's details page.
+     * A placement can be serialized to and from JSON for the purpose of
+     * server-side rendering, the serialized object **should not be persisted**
+     * because it has a very short lifecycle.
+     * @example
+     * ```jsx
+     * let placement = await client.fetchRecommendedPDPRow({
+     *   // Required
+     *   storeId: 420,
+     *   // Required one of, but not both
+     *   productId: 420,
+     *   posProductId: '420',
+     *   searchAttributes: ['product_id', 'name'],
+     * });
+     * ```
+     */
+    fetchRecommendedPDPRow<ProductShape extends object = Record<string, unknown>>(props: FetchRecommendedPDPRowProps): Promise<SmartSort<ProductShape>>;
+    /**
+     * Fetches a recommended row placement from the Jane DM API. This
+     * placement represents a row of recommended organic and sponsored
+     * products to be displayed in any kind of page.
+     * A placement can be serialized to and from JSON for the purpose of
+     * server-side rendering, the serialized object **should not be persisted**
+     * because it has a very short lifecycle.
+     * @example
+     * ```jsx
+     * let placement = await client.fetchRecommendedRow({
+     *   // Required
+     *   storeId: 420,
+     *   searchAttributes: ['product_id', 'name'],
+     * });
+     * ```
+     */
+    fetchRecommendedRow<ProductShape extends object = Record<string, unknown>>(props: FetchRecommendedRowProps): Promise<SmartSort<ProductShape>>;
+    /**
+     * Fetches a recommended sort placement from the Jane DM API. This
+     * placement represents a list of mixed organic and sponsored products,
+     * sorted according to user's recommendations, to be used when sorting
+     * lists of products on your pages.
+     * A placement can be serialized to and from JSON for the purpose of
+     * server-side rendering, the serialized object **should not be persisted**
+     * because it has a very short lifecycle.
+     * @example
+     * ```jsx
+     * let placement = await client.fetchRecommendedSort({
+     *   // Required
+     *   storeId: 420,
+     *   // Required
+     *   searchSort: 'recommendation',
+     *   disableAds: false,
+     *   maxProducts: 10,
+     *   numColumns: 5,
+     *   pageSize: 10,
+     *   searchAttributes: ['product_id', 'name'],
+     *   searchFacets: ['kind'],
+     *   searchFilter: 'kind:flower',
+     *   searchQuery: '',
+     * });
+     * ```
+     */
+    fetchRecommendedSort<ProductShape extends object = Record<string, unknown>>(props: FetchRecommendedSortProps): Promise<SmartSort<ProductShape>>;
+    /**
+     * Fetches virtual budtender query suggestions from the Jane DM API.
+     * Returns curated queries optimized for natural language product search.
+     * @internal
+     * @example
+     * ```jsx
+     * const queries = await client.fetchVirtualBudtenderQueries({
+     *   storeId: 420,
+     * });
+     *
+     * console.log(queries); // [{ query: "help me sleep", displayText: "Help me sleep" }, ...]
+     * ```
+     */
+    fetchVirtualBudtenderQueries(props: VirtualBudtenderQueriesParams): Promise<VirtualBudtenderQuery[]>;
+    /**
+     * Performs natural language product search using Virtual Budtender AI.
+     * Returns personalized product recommendations with AI-generated explanations
+     * and integrates sponsored products when relevant to the query.
+     * @internal
+     * @example
+     * ```jsx
+     * const result = await client.fetchVirtualBudtenderSearch({
+     *   query: "help me sleep",
+     *   storeId: 420,
+     * });
+     *
+     * console.log(result.markdownResponse); // AI-generated response
+     * console.log(result.products); // Array of VirtualBudtenderProduct instances
+     *
+     * // Each product has click and impression tracking
+     * result.products.forEach(product => {
+     *   console.log(product.attributes.reasoning); // AI reasoning
+     *   console.log(product.isSponsored); // Sponsored status
+     * });
+     * ```
+     */
+    fetchVirtualBudtenderSearch<ProductShape extends object = Record<string, unknown>>(props: VirtualBudtenderSearchParams): Promise<VirtualBudtenderSearchWithProductsResponse<ProductShape>>;
+    /**
+     * Retrieves the configured JDID for the client.
+     */
+    getJaneDeviceId(): string;
+    /**
+     * Initializes the SDK with async operations.
+     * This method is automatically called before any fetch operations if not already initialized.
+     * You can also call it explicitly for immediate initialization.
+     * @example
+     * ```jsx
+     * const client = new JaneDM({ apiKey: 'your-api-key' });
+     * await client.init(); // Optional - will be called automatically on first fetch
+     * ```
+     */
+    init(): Promise<void>;
+    /**
+     * Returns an async iterable over every review matching the given
+     * filters. The iterator fetches pages lazily, one HTTP request per
+     * page. It yields individual reviews by default; use the `.pages`
+     * property to yield whole page envelopes instead (useful when you
+     * need access to `pagination` or `aggregate` during traversal).
+     *
+     * The underlying API is page-indexed; the iterator always starts at
+     * page 1 and advances until the server reports no more pages.
+     *
+     * For UIs that paginate, use {@link JaneDM.fetchProductReviews} instead.
+     *
+     * @see {@link ProductReviewsIterable} for the return shape.
+     * @see [Pagination guide](https://dm-sdk-docs.iheartjane.com/app/pagination).
+     *
+     * @example Collect every 5-star review for a product
+     * ```ts
+     * const reviews: ProductReview[] = [];
+     * for await (const review of client.iterateProductReviews({
+     *   productId: 123,
+     *   ratings: [5],
+     * })) {
+     *   reviews.push(review);
+     * }
+     * ```
+     *
+     * @example Iterate page-by-page
+     * ```ts
+     * for await (const page of client.iterateProductReviews({ productId: 123 }).pages) {
+     *   console.log(
+     *     `Page ${page.pagination.currentPage}/${page.pagination.totalPages}`,
+     *     `avg rating: ${page.aggregate.averageRating}`,
+     *   );
+     * }
+     * ```
+     */
+    iterateProductReviews(props: IterateProductReviewsProps): ProductReviewsIterable;
+    /**
+     * Signals the Jane DM API that a checkout event has happened.
+     * This method should be called when a user has completed a purchase to
+     * record attribution data for conversions.
+     * It is preferable to call this method from the server-side to avoid
+     * race conditions.
+     * @example
+     * ```jsx
+     * await client.sendPosCheckout({
+     *   storeId: 420,
+     *   posOrderId: 'some-pos-order-id',
+     *   posUserId: 'some-pos-user-id',
+     *   products: [
+     *     {
+     *       posProductId: 'some-pos-product-id',
+     *       price: 10.99,
+     *       quantity: 1,
+     *     },
+     *   ],
+     * });
+     * ```
+     */
+    sendPosCheckout(props: PosCheckoutParams): Promise<void>;
+    /**
+     * Signals the Jane DM API that session events happened.
+     * This method should be called when a user clicked to add a product
+     * to the cart or filtered a category.
+     * @example
+     * ```jsx
+     * await client.sendSessionEvent({
+     *   events: [
+     *     {
+     *        type: 'clickedAddToCart',
+     *        posProductId: 'some-pos-product-id',
+     *        storeId: 420,
+     *     },
+     *     {
+     *        type: 'clickedAddToCart',
+     *        productId: 1234,
+     *        storeId: 420,
+     *     },
+     *     {
+     *        type: 'filteredCategory',
+     *        category: SessionEventCategory.Extract,
+     *        storeId: 420,
+     *     },
+     *   ],
+     * });
+     * ```
+     */
+    sendSessionEvent(props: SessionEventParams): Promise<void>;
+    private initializeClientSideJdid;
+}
+
+export { AdMode, BrandSpecials, ConversionExternalProduct, CustomImageData, Facets, FetchCartTopperRowProps, FetchCustomImageRowProps, type FetchCustomPlacementsProps, type FetchFacetsParams, type FetchFeaturedPlacementProps, FetchMenuRowProps, FetchMenuTopRowProps, FetchProductReviewsProps, FetchRecommendedPDPRowProps, FetchRecommendedRowProps, FetchRecommendedSortProps, IterateProductReviewsProps, JaneDM, type MultiPlacementResponse, PageContextEnum, Placement, type PosCheckoutParams, ProductReviewsIterable, ProductReviewsResponse, SearchSortEnum, type SessionEventParams, SmartSort, SmartSortClickIntent, SmartSortProduct, SmartSortProductProps, SmartSortProps, Specials, type VirtualBudtenderClickIntent, VirtualBudtenderProduct, VirtualBudtenderQuery };