@tiendanube/nube-sdk-helper 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,1167 @@
+import { NubeBrowserAPIs, NubeComponent, NubeSDKState, UISlot, NubeSDKListenableEvent, EventListenerMap, Nullable, Address, BillingAddress, ShippingAddress, Cart, CartItem, CartValidation, CartValidationFail, CartValidationPending, CartValidationSuccess, ProductDetails, Customer, Payment, Shipping, ShippingOption, Store, Page, AllProductsPage, CategoryPage, CheckoutPage, HomePage, ProductPage, SearchPage, NubeSDK, Checkout, Category, Home } from '@tiendanube/nube-sdk-types';
+
+/**
+ * @fileoverview Browser APIs access functions for NubeSDK
+ *
+ * This module provides utility functions to easily access
+ * browser APIs through the NubeSDK instance.
+ */
+
+/**
+ * Browser APIs available through NubeSDK.
+ *
+ * Provides access to browser storage, navigation, and other APIs
+ * in a convenient and type-safe way.
+ *
+ * @example
+ * ```typescript
+ * // Use async localStorage
+ * await browser.asyncLocalStorage.setItem('key', 'value');
+ * const value = await browser.asyncLocalStorage.getItem('key');
+ *
+ * // Use async sessionStorage
+ * await browser.asyncSessionStorage.setItem('session', 'data');
+ *
+ * // Navigate to a route
+ * browser.navigate('/products/123');
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare const browser: Readonly<NubeBrowserAPIs>;
+/**
+ * Navigates to a specific route within the Nube application.
+ *
+ * @param route - The route to navigate to, must start with '/'
+ *
+ * @example
+ * ```typescript
+ * // Navigate to a product page
+ * navigate('/products/123');
+ *
+ * // Navigate to home
+ * navigate('/');
+ *
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function navigate(route: `/${string}`): void;
+/**
+ * Clears the browser APIs cache.
+ *
+ * This function is useful for testing or when you need to force
+ * a fresh instance of the browser APIs to be created.
+ *
+ * @example
+ * ```typescript
+ * // Clear cache before testing
+ * clearBrowserCache();
+ *
+ * // Next access to browser properties will create a new instance
+ * await browser.asyncLocalStorage.setItem('key', 'value');
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function clearBrowserCache(): void;
+
+/**
+ * Visual variants supported by {@link UIHelper.showToast}.
+ *
+ * @since 0.1.0
+ */
+type ToastVariant = "success" | "error" | "warning" | "info";
+/**
+ * A component, list of components, or a render function that derives them from
+ * the current state.
+ *
+ * @since 0.1.0
+ */
+type RenderableComponent = NubeComponent | NubeComponent[] | ((state: Readonly<NubeSDKState>) => NubeComponent | NubeComponent[]);
+type UIHelper = {
+    showToast: (message: string, variant?: ToastVariant) => void;
+    clear: (slot: UISlot) => void;
+    render: (slot: UISlot, component: RenderableComponent) => void;
+    renderAll: (slots: UISlot[], component: RenderableComponent) => void;
+};
+/**
+ * View helpers for NubeSDK.
+ *
+ * Provides methods to show toasts, clear slots, and render components.
+ */
+declare const ui: Readonly<UIHelper>;
+
+/**
+ * @fileoverview Event subscription helpers for NubeSDK
+ *
+ * Thin, ergonomic wrappers around `nube.on` that return an unsubscribe
+ * function, plus sugar for the very common "show a toast when an event fires"
+ * pattern seen across apps.
+ */
+
+/**
+ * Subscribes a listener to a NubeSDK event and returns an unsubscribe function.
+ *
+ * Equivalent to calling `nube.on(event, listener)`, but the returned function
+ * detaches the listener via `nube.off`, so you don't need to hold a reference
+ * to both the instance and the listener to clean it up.
+ *
+ * @param event - The event to listen for
+ * @param listener - The listener to register
+ * @returns An unsubscribe function
+ *
+ * @example
+ * ```typescript
+ * const unsubscribe = onEvent("cart:update", (state) => {
+ *   console.log("Cart now has", state.cart.items.length, "items");
+ * });
+ *
+ * // Later:
+ * unsubscribe();
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function onEvent<T extends NubeSDKListenableEvent>(event: T, listener: EventListenerMap[T]): () => void;
+/**
+ * Shows a toast whenever the given event fires.
+ *
+ * Replaces the repetitive `nube.on("...:success", () => ui.showToast(...))`
+ * pattern. The message can be a static string or a function deriving it from
+ * the current state.
+ *
+ * @param event - The event to listen for
+ * @param message - The toast message, or a function returning it from state
+ * @param variant - Optional toast variant (defaults to the {@link ui.showToast} default)
+ * @returns An unsubscribe function
+ *
+ * @example
+ * ```typescript
+ * toastOn("cart:add:success", "Product added to cart", "success");
+ *
+ * toastOn(
+ *   "cart:update",
+ *   (state) => `Cart updated: ${state.cart.items.length} items`,
+ * );
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function toastOn<T extends NubeSDKListenableEvent>(event: T, message: string | ((state: Readonly<NubeSDKState>) => string), variant?: ToastVariant): () => void;
+
+/**
+ * @fileoverview Access functions for NubeSDK instance data
+ *
+ * This module provides utility functions to easily access
+ * the SDK instance, current state and application data.
+ */
+
+/**
+ * Gets the current NubeSDK state.
+ *
+ * @returns The current readonly SDK state
+ *
+ * @example
+ * ```typescript
+ * const state = getCurrentState();
+ * console.log('Current page:', state.location.page.type);
+ * console.log('Page data:', state.location.page.data);
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function getCurrentState(): Readonly<NubeSDKState>;
+/**
+ * Gets the current application data.
+ *
+ * @returns Readonly object containing application ID and script
+ *
+ * @example
+ * ```typescript
+ * const appData = getAppData();
+ * console.log('Application ID:', appData.id);
+ * console.log('Application script:', appData.script);
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function getAppData(): Readonly<{
+    id: string;
+    script: string;
+}>;
+/**
+ * Gets the parsed URL of the application script.
+ *
+ * @returns The readonly URL instance of the application script
+ *
+ * @example
+ * ```typescript
+ * const url = getScriptURL();
+ * console.log('Script origin:', url.origin);
+ * console.log('Script pathname:', url.pathname);
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function getScriptURL(): Readonly<URL>;
+/**
+ * Gets the search parameters of the application script URL.
+ *
+ * @returns The readonly URLSearchParams instance from the script URL
+ *
+ * @example
+ * ```typescript
+ * const params = getScriptSearchParams();
+ * for (const [key, value] of params) {
+ *   console.log(`${key}: ${value}`);
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function getScriptSearchParams(): Readonly<URLSearchParams>;
+/**
+ * Gets a specific search parameter from the application script URL.
+ *
+ * @param key - The name of the search parameter to retrieve
+ * @returns The value of the search parameter, or null if not present
+ *
+ * @example
+ * ```typescript
+ * const version = getScriptParam('version');
+ * if (version) {
+ *   console.log('Script version:', version);
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function getScriptParam(key: string): Nullable<string>;
+
+/**
+ * @fileoverview Address type guards for NubeSDK (address, shipping & billing).
+ */
+
+/**
+ * Type guard to check if a value is a valid address object
+ *
+ * @param value - The value to check
+ * @returns True if the value is an Address
+ *
+ * @example
+ * ```typescript
+ * if (isAddress(data)) {
+ *   // data is now typed as Address
+ *   console.log(data.zipcode);
+ *   console.log(data.city);
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function isAddress(value: unknown): value is Address;
+/**
+ * Type guard to check if a value is a valid shipping address
+ *
+ * @param value - The value to check
+ * @returns True if the value is a ShippingAddress
+ *
+ * @example
+ * ```typescript
+ * if (isShippingAddress(data)) {
+ *   // data is now typed as ShippingAddress
+ *   console.log(data.zipcode);
+ *   console.log(data.between_street);
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function isShippingAddress(value: unknown): value is ShippingAddress;
+/**
+ * Type guard to check if a value is a valid billing address
+ *
+ * @param value - The value to check
+ * @returns True if the value is a BillingAddress
+ *
+ * @example
+ * ```typescript
+ * if (isBillingAddress(data)) {
+ *   // data is now typed as BillingAddress
+ *   console.log(data.zipcode);
+ *   console.log(data.business_name);
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function isBillingAddress(value: unknown): value is BillingAddress;
+
+/**
+ * @fileoverview Cart type guards for NubeSDK.
+ */
+
+/**
+ * Type guard to check if a value is a valid cart object
+ *
+ * @param value - The value to check
+ * @returns True if the value is a Cart
+ *
+ * @example
+ * ```typescript
+ * if (isCart(data)) {
+ *   // data is now typed as Cart
+ *   console.log(data.id);
+ *   console.log(data.items.length);
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function isCart(value: unknown): value is Cart;
+/**
+ * Type guard to check if a value is a valid cart item
+ *
+ * @param value - The value to check
+ * @returns True if the value is a CartItem
+ *
+ * @example
+ * ```typescript
+ * if (isCartItem(item)) {
+ *   // item is now typed as CartItem
+ *   console.log(item.name);
+ *   console.log(item.price);
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function isCartItem(value: unknown): value is CartItem;
+/**
+ * Type guard to check if a cart validation is successful
+ *
+ * @param validation - The validation to check
+ * @returns True if the validation is successful
+ *
+ * @example
+ * ```typescript
+ * if (isCartValidationSuccess(cart.validation)) {
+ *   // cart.validation is now typed as CartValidationSuccess
+ *   console.log('Cart is valid');
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function isCartValidationSuccess(validation: CartValidation): validation is CartValidationSuccess;
+/**
+ * Type guard to check if a cart validation is pending
+ *
+ * @param validation - The validation to check
+ * @returns True if the validation is pending
+ *
+ * @example
+ * ```typescript
+ * if (isCartValidationPending(cart.validation)) {
+ *   // cart.validation is now typed as CartValidationPending
+ *   console.log('Cart validation in progress...');
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function isCartValidationPending(validation: CartValidation): validation is CartValidationPending;
+/**
+ * Type guard to check if a cart validation failed
+ *
+ * @param validation - The validation to check
+ * @returns True if the validation failed
+ *
+ * @example
+ * ```typescript
+ * if (isCartValidationFail(cart.validation)) {
+ *   // cart.validation is now typed as CartValidationFail
+ *   console.log('Cart validation failed:', cart.validation.reason);
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function isCartValidationFail(validation: CartValidation): validation is CartValidationFail;
+
+/**
+ * @fileoverview Component & page-data structure guards for NubeSDK.
+ */
+
+/**
+ * Type guard to check if a value is a valid Nube component
+ *
+ * @param value - The value to check
+ * @returns True if the value is a NubeComponent
+ *
+ * @example
+ * ```typescript
+ * if (isNubeComponent(component)) {
+ *   // component is now typed as NubeComponent
+ *   console.log(component.type);
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function isNubeComponent(value: unknown): value is NubeComponent;
+/**
+ * Type guard that checks if an object contains a list of products.
+ *
+ * This function verifies that the provided data is an object with a `products`
+ * property that is an array of ProductDetails. Useful for validating page data
+ * structures that may contain product lists.
+ *
+ * @param data - The unknown value to check
+ * @returns True if data is an object with a `products` array property, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const pageData = { products: [product1, product2] };
+ * if (hasProductList(pageData)) {
+ *   // TypeScript now knows pageData.products exists and is ProductDetails[]
+ *   pageData.products.forEach(product => console.log(product.id));
+ * }
+ * ```
+ */
+declare function hasProductList(data: unknown): data is {
+    products: ProductDetails[];
+};
+/**
+ * Type guard that checks if an object contains a list of sections.
+ *
+ * This function verifies that the provided data is an object with a `sections`
+ * property that is an array. Useful for validating page data structures that
+ * may contain section-based content.
+ *
+ * @param data - The unknown value to check
+ * @returns True if data is an object with a `sections` array property, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const pageData = { sections: [{ type: "featured_products", products: [] }] };
+ * if (hasSections(pageData)) {
+ *   // TypeScript now knows pageData.sections exists and is an array
+ *   pageData.sections.forEach(section => processSection(section));
+ * }
+ * ```
+ */
+declare function hasSections(data: unknown): data is {
+    sections: unknown[];
+};
+/**
+ * Type guard that checks if a section item contains products.
+ *
+ * This function verifies that the provided item is an object with a `products`
+ * property that is an array of ProductDetails. Useful for iterating through
+ * sections and filtering those that contain product lists.
+ *
+ * @param item - The unknown value to check (typically a section object)
+ * @returns True if item is an object with a `products` array property, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const sections = [{ type: "featured_products", products: [product1] }];
+ * sections.forEach(section => {
+ *   if (isSectionWithProducts(section)) {
+ *     // TypeScript now knows section.products exists and is ProductDetails[]
+ *     section.products.forEach(product => renderProduct(product));
+ *   }
+ * });
+ * ```
+ */
+declare function isSectionWithProducts(item: unknown): item is {
+    products: ProductDetails[];
+};
+/**
+ * Type guard that checks if an object contains a single product (Product Detail Page).
+ *
+ * This function verifies that the provided data is an object with a `product`
+ * property that is a valid ProductDetails object. It performs a minimal integrity
+ * check by verifying the product has an `id` property. Useful for validating
+ * product detail page data structures.
+ *
+ * @param data - The unknown value to check
+ * @returns True if data is an object with a `product` property containing a valid ProductDetails, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const pageData = { product: { id: 1, name: {...}, ... } };
+ * if (hasSingleProduct(pageData)) {
+ *   // TypeScript now knows pageData.product exists and is ProductDetails
+ *   console.log(pageData.product.id);
+ * }
+ * ```
+ */
+declare function hasSingleProduct(data: unknown): data is {
+    product: ProductDetails;
+};
+
+/**
+ * @fileoverview Domain type guards for NubeSDK (store, customer, payment, shipping).
+ */
+
+/**
+ * Type guard to check if a value is a valid store object
+ *
+ * @param value - The value to check
+ * @returns True if the value is a Store
+ *
+ * @example
+ * ```typescript
+ * if (isStore(data)) {
+ *   // data is now typed as Store
+ *   console.log(data.name);
+ *   console.log(data.currency);
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function isStore(value: unknown): value is Store;
+/**
+ * Type guard to check if a value is a valid customer object
+ *
+ * @param value - The value to check
+ * @returns True if the value is a Customer
+ *
+ * @example
+ * ```typescript
+ * if (isCustomer(data)) {
+ *   // data is now typed as Customer
+ *   console.log(data.contact.email);
+ *   console.log(data.shipping_address.city);
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function isCustomer(value: unknown): value is Customer;
+/**
+ * Type guard to check if a value is a valid payment object
+ *
+ * @param value - The value to check
+ * @returns True if the value is a Payment
+ *
+ * @example
+ * ```typescript
+ * if (isPayment(data)) {
+ *   // data is now typed as Payment
+ *   console.log(data.status);
+ *   console.log(data.selected?.method_name);
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function isPayment(value: unknown): value is Payment;
+/**
+ * Type guard to check if a value is a valid shipping object
+ *
+ * @param value - The value to check
+ * @returns True if the value is a Shipping
+ *
+ * @example
+ * ```typescript
+ * if (isShipping(data)) {
+ *   // data is now typed as Shipping
+ *   console.log(data.selected);
+ *   console.log(data.options?.length);
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function isShipping(value: unknown): value is Shipping;
+/**
+ * Type guard to check if a value is a valid shipping option
+ *
+ * @param value - The value to check
+ * @returns True if the value is a ShippingOption
+ *
+ * @example
+ * ```typescript
+ * if (isShippingOption(option)) {
+ *   // option is now typed as ShippingOption
+ *   console.log(option.name);
+ *   console.log(option.price);
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function isShippingOption(value: unknown): value is ShippingOption;
+
+/**
+ * @fileoverview Page type guards for NubeSDK.
+ *
+ * Runtime checks that narrow a `Page` to its specific page type.
+ */
+
+/**
+ * Type guard to check if a page is a product page
+ *
+ * @param page - The page to check
+ * @returns True if the page is a ProductPage
+ *
+ * @example
+ * ```typescript
+ * if (isProductPage(page)) {
+ *   // page is now typed as ProductPage
+ *   console.log(page.data.name);
+ *   console.log(page.data.variants);
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function isProductPage(page: Page): page is ProductPage;
+/**
+ * Type guard to check if a page is a category page
+ *
+ * @param page - The page to check
+ * @returns True if the page is a CategoryPage
+ *
+ * @example
+ * ```typescript
+ * if (isCategoryPage(page)) {
+ *   // page is now typed as CategoryPage
+ *   console.log(page.data.name);
+ *   console.log(page.data.id);
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function isCategoryPage(page: Page): page is CategoryPage;
+/**
+ * Type guard to check if a page is a checkout page
+ *
+ * @param page - The page to check
+ * @returns True if the page is a CheckoutPage
+ *
+ * @example
+ * ```typescript
+ * if (isCheckoutPage(page)) {
+ *   // page is now typed as CheckoutPage
+ *   console.log(page.data.step);
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function isCheckoutPage(page: Page): page is CheckoutPage;
+/**
+ * Type guard to check if a page is an all products page
+ *
+ * @param page - The page to check
+ * @returns True if the page is an AllProductsPage
+ *
+ * @example
+ * ```typescript
+ * if (isAllProductsPage(page)) {
+ *   // page is now typed as AllProductsPage
+ *   console.log(page.data.id); // 0
+ *   console.log(page.data.products);
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function isAllProductsPage(page: Page): page is AllProductsPage;
+/**
+ * Type guard to check if a page is a search page
+ *
+ * @param page - The page to check
+ * @returns True if the page is a SearchPage
+ *
+ * @example
+ * ```typescript
+ * if (isSearchPage(page)) {
+ *   // page is now typed as SearchPage
+ *   console.log(page.data.q);
+ *   console.log(page.data.products);
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function isSearchPage(page: Page): page is SearchPage;
+/**
+ * Type guard to check if a page is a home page
+ *
+ * @param page - The page to check
+ * @returns True if the page is a HomePage
+ *
+ * @example
+ * ```typescript
+ * if (isHomePage(page)) {
+ *   // page is now typed as HomePage
+ *   console.log(page.data?.sections);
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function isHomePage(page: Page): page is HomePage;
+
+/**
+ * @fileoverview NubeSDK instance management
+ *
+ * The NubeSDK runtime passes the SDK instance only as the argument of the
+ * app entry point (`App(nube)`); it does not expose it on a global. This module
+ * lets an app register that instance once, so every other helper
+ * (`getCurrentState`, `ui`, `browser`, `onPage`, selectors, ...) can access it
+ * without threading `nube` through every function and component.
+ */
+
+/**
+ * Registers the NubeSDK instance for the current app.
+ *
+ * Call this once at the very start of your app entry point so the rest of the
+ * helper API can access the instance without it being passed around.
+ *
+ * @param nube - The NubeSDK instance received by your `App(nube)` entry point
+ *
+ * @example
+ * ```typescript
+ * import { setNubeInstance, getCurrentState, ui } from "@tiendanube/nube-sdk-helper";
+ *
+ * export function App(nube: NubeSDK) {
+ *   setNubeInstance(nube);
+ *
+ *   // No need to pass `nube` around anymore:
+ *   const state = getCurrentState();
+ *   ui.showToast("App ready!");
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function setNubeInstance(nube: Readonly<NubeSDK>): void;
+/**
+ * Gets the NubeSDK instance for the current app.
+ *
+ * Returns the instance registered via {@link setNubeInstance}. If none was
+ * registered, it falls back to `self.__SDK_INSTANCE__` (for forward
+ * compatibility) and throws a descriptive error if neither is available.
+ *
+ * @returns The readonly NubeSDK instance
+ * @throws If no instance was registered and no global instance exists
+ *
+ * @example
+ * ```typescript
+ * const nube = getNubeInstance();
+ * nube.on("location:updated", (state) => {
+ *   console.log("Page updated:", state.location.page);
+ * });
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function getNubeInstance(): Readonly<NubeSDK>;
+/**
+ * Clears the registered NubeSDK instance.
+ *
+ * Mainly useful for testing or for tearing down between app reloads.
+ *
+ * @since 0.1.0
+ */
+declare function clearNubeInstance(): void;
+
+/**
+ * @fileoverview Page matching system for NubeSDK
+ *
+ * This module provides a type-safe system for handling different page types
+ * (product, category, checkout) and their respective data.
+ * Includes functions for page matching and event handlers.
+ */
+
+/**
+ * Maps each page type to its specific data payload.
+ *
+ * @example
+ * ```typescript
+ * // Product page data
+ * const productData: PageDataMap['product'] = {
+ *   id: '123',
+ *   name: 'Example Product',
+ *   price: 29.99
+ * };
+ *
+ * // Category page data
+ * const categoryData: PageDataMap['category'] = {
+ *   id: 'cat-1',
+ *   name: 'Example Category',
+ *   products: []
+ * };
+ * ```
+ *
+ * @since 0.1.0
+ */
+type PageDataMap = {
+    product: ProductDetails;
+    category: Category;
+    checkout: Checkout;
+    home: Home;
+};
+/**
+ * Typed handler for a given page type.
+ *
+ * @template T - The page type (product, category, checkout)
+ * @param state - Current NubeSDK state
+ * @param data - Page-specific data for the given page type
+ *
+ * @example
+ * ```typescript
+ * const productHandler: PageHandlerFunction<'product'> = (state, data) => {
+ *   console.log('Product viewed:', data.name);
+ *   trackProductView(data.id);
+ * };
+ *
+ * const checkoutHandler: PageHandlerFunction<'checkout'> = (state, data) => {
+ *   if (data.step === 'success') {
+ *     trackPurchase(data.orderId);
+ *   }
+ * };
+ * ```
+ *
+ * @since 0.1.0
+ */
+type PageHandlerFunction<T extends keyof PageDataMap> = (state: NubeSDKState, data: PageDataMap[T]) => void;
+/**
+ * Partial set of handlers where only relevant page types need to be implemented.
+ *
+ * @example
+ * ```typescript
+ * const handlers: PageHandlers = {
+ *   product: (state, data) => trackProductView(data.id),
+ *   checkout: (state, data) => {
+ *     if (data.step === 'success') trackPurchase();
+ *   }
+ *   // category handler is optional
+ * };
+ * ```
+ *
+ * @since 0.1.0
+ */
+type PageHandlers = {
+    [K in keyof PageDataMap]?: PageHandlerFunction<K>;
+};
+/**
+ * Dispatches to the appropriate handler based on the current page type.
+ * Type inference guarantees that each handler receives the correct payload.
+ *
+ * @param state - Current NubeSDK state
+ * @param handlers - Handlers mapped by page type
+ *
+ * @example
+ * ```typescript
+ * const state = getCurrentState();
+ *
+ * pageMatch(state, {
+ *   product: (state, data) => {
+ *     console.log('Product:', data.name, 'Price:', data.price);
+ *   },
+ *   category: (state, data) => {
+ *     console.log('Category:', data.name, 'Products:', data.products.length);
+ *   },
+ *   checkout: (state, data) => {
+ *     console.log('Checkout step:', data.step);
+ *   }
+ * });
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function pageMatch(state: NubeSDKState, handlers: PageHandlers): void;
+/**
+ * Subscribes to navigation changes and invokes handlers that match the current page.
+ *
+ * Functional pattern that detects the current page type and calls the
+ * corresponding handler whenever navigation updates occur.
+ *
+ * @param handlers - Handlers mapped by page type
+ * @returns An unsubscribe function that stops listening for navigation changes
+ *
+ * @example
+ * ```typescript
+ * const unsubscribe = onPage({
+ *   product: (state, data) => trackProductView(data.id),
+ *   checkout: (state, data) => {
+ *     if (data.step === 'success') trackPurchase();
+ *   }
+ * });
+ *
+ * // Later, to stop listening:
+ * unsubscribe();
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function onPage(handlers: PageHandlers): () => void;
+/**
+ * Union of all possible checkout steps.
+ *
+ * @since 0.1.0
+ */
+type CheckoutStep = Checkout["step"];
+/**
+ * Handlers per checkout step (e.g., 'cart', 'payment', 'success').
+ * Only the steps you care about need to be provided.
+ *
+ * @example
+ * ```typescript
+ * const checkoutHandlers: CheckoutStepHandlers = {
+ *   cart: (state) => console.log('Cart step'),
+ *   payment: (state) => console.log('Payment step'),
+ *   success: (state) => console.log('Success step')
+ * };
+ * ```
+ *
+ * @since 0.1.0
+ */
+type CheckoutStepHandlers = Partial<Record<CheckoutStep, (state: NubeSDKState) => void>>;
+/**
+ * Runs a handler when the checkout is ready and the current step matches.
+ *
+ * Listens to `checkout:ready` and, if the current page is a checkout,
+ * invokes the handler registered for the current `Checkout.step`.
+ *
+ * @param handlers - Handlers keyed by checkout step
+ * @returns An unsubscribe function that stops listening for checkout steps
+ *
+ * @example
+ * ```typescript
+ * const unsubscribe = onCheckoutStep({
+ *   cart: (state) => {
+ *     console.log('User is in cart step');
+ *     trackCartView();
+ *   },
+ *   success: (state) => {
+ *     console.log('Purchase completed');
+ *     trackPurchase();
+ *   }
+ * });
+ *
+ * // Later, to stop listening:
+ * unsubscribe();
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function onCheckoutStep(handlers: CheckoutStepHandlers): () => void;
+
+/**
+ * @fileoverview Render helpers for NubeSDK
+ *
+ * This module provides utilities to extract products from state and
+ * iterate over them for rendering (e.g., in grid slots).
+ */
+
+/**
+ * Extracts all products from the NubeSDK state, regardless of the page type.
+ * Strategy: "Greedy" (Aggressive Collection).
+ *
+ * This function collects products from multiple sources within the state:
+ * - Direct product lists in category, products, and search pages
+ * - Products within sections for home, product, category, and products pages
+ * - The main product in product detail pages
+ *
+ * @param state - The current NubeSDK state containing location and page information
+ * @returns An array of ProductDetails. Returns an empty array if no products are found
+ *          or if the page structure doesn't contain products.
+ *
+ * @example
+ * ```typescript
+ * const state = nube.getState();
+ * const products = getProductsFromState(state);
+ * products.forEach(product => console.log(product.id));
+ * ```
+ */
+declare function getProductsFromState(state: NubeSDKState): ProductDetails[];
+/**
+ * Creates a higher-order function that iterates over products in grid slots.
+ *
+ * This helper abstracts page type checking, product iteration, and automatic key generation.
+ * It extracts products from the state, maps them through a render factory function,
+ * filters out null/undefined results, and automatically injects unique keys for each component.
+ *
+ * @param renderFactory - A function that receives a ProductDetails and returns a NubeComponent,
+ *                        null, or undefined. Components returning null/undefined are filtered out.
+ * @returns A function that accepts NubeSDKState and returns an array of NubeComponent instances
+ *          with automatically generated keys using the product ID.
+ *
+ * @example
+ * ```typescript
+ * nube.render(
+ *   "product_grid_item_image_bottom_right",
+ *   forEachProduct((product) => <MyBadge product={product} />)
+ * );
+ * ```
+ */
+declare function forEachProduct(renderFactory: (product: ProductDetails) => NubeComponent | null | undefined): (state: NubeSDKState) => NubeComponent[];
+
+/**
+ * @fileoverview State selectors for NubeSDK
+ *
+ * Small, focused accessors for the most frequently read slices of the SDK
+ * state. Each selector accepts an optional `state`; when omitted it reads the
+ * current state from the registered instance, so apps don't need to repeat
+ * `const state = nube.getState()` everywhere.
+ */
+
+/**
+ * Gets the current cart.
+ *
+ * @param state - Optional state; defaults to the current SDK state
+ * @returns The cart
+ *
+ * @example
+ * ```typescript
+ * const cart = getCart();
+ * console.log("Items:", cart.items.length);
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function getCart(state?: NubeSDKState): Cart;
+/**
+ * Gets the items currently in the cart.
+ *
+ * @param state - Optional state; defaults to the current SDK state
+ * @returns The list of cart items
+ *
+ * @example
+ * ```typescript
+ * for (const item of getCartItems()) {
+ *   console.log(item.name, item.quantity);
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function getCartItems(state?: NubeSDKState): CartItem[];
+/**
+ * Gets the type of the current page (e.g. `"home"`, `"product"`, `"checkout"`).
+ *
+ * @param state - Optional state; defaults to the current SDK state
+ * @returns The current page type
+ *
+ * @example
+ * ```typescript
+ * if (getPageType() === "checkout") {
+ *   // checkout-specific logic
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function getPageType(state?: NubeSDKState): Page["type"];
+/**
+ * Gets the current customer, or `null` when not available on the current page.
+ *
+ * @param state - Optional state; defaults to the current SDK state
+ * @returns The customer or `null`
+ *
+ * @example
+ * ```typescript
+ * const customer = getCustomer();
+ * if (customer) console.log(customer.contact?.email);
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function getCustomer(state?: NubeSDKState): Nullable<Customer>;
+
+/**
+ * @fileoverview General utility functions for NubeSDK
+ *
+ * This module provides general-purpose utility functions including
+ * deep cloning, debouncing, and throttling capabilities.
+ */
+/**
+ * Deep clones a value.
+ *
+ * Uses the structured clone algorithm when available (it is, in the NubeSDK
+ * Web Worker runtime), which correctly handles `Date`, `Map`, `Set`, typed
+ * arrays and circular references. Falls back to JSON serialization in
+ * environments without `structuredClone` (with the usual JSON limitations:
+ * functions, symbols and `undefined` are dropped).
+ *
+ * @template T - The type of the value to clone
+ * @param obj - The value to deep clone
+ * @returns A deep clone of the input value
+ *
+ * @example
+ * ```typescript
+ * const original = { name: 'John', age: 30, hobbies: ['reading', 'coding'] };
+ * const cloned = deepClone(original);
+ *
+ * cloned.name = 'Jane';
+ * cloned.hobbies.push('gaming');
+ *
+ * console.log(original.name); // 'John' (unchanged)
+ * console.log(original.hobbies); // ['reading', 'coding'] (unchanged)
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function deepClone<T>(obj: T): T;
+/**
+ * Debounces a function call, ensuring it only executes after a specified
+ * delay has passed since the last invocation.
+ *
+ * @template T - The function type
+ * @param func - The function to debounce
+ * @param wait - The number of milliseconds to delay
+ * @returns A debounced version of the function
+ *
+ * @example
+ * ```typescript
+ * const debouncedSearch = debounce((query: string) => {
+ *   console.log('Searching for:', query);
+ *   // Perform search operation
+ * }, 300);
+ *
+ * // Multiple rapid calls will only execute the last one after 300ms
+ * debouncedSearch('a');
+ * debouncedSearch('ab');
+ * debouncedSearch('abc'); // Only this will execute
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function debounce<T extends (...args: never[]) => unknown>(func: T, wait: number): (...args: Parameters<T>) => void;
+/**
+ * Creates a throttled version of a function that will only execute
+ * at most once per specified time limit.
+ *
+ * @template T - The function type
+ * @param func - The function to throttle
+ * @param limit - The time limit in milliseconds
+ * @returns A throttled version of the function
+ *
+ * @example
+ * ```typescript
+ * const throttledScroll = throttle((event: Event) => {
+ *   console.log('Scroll event:', event);
+ *   // Handle scroll event
+ * }, 100);
+ *
+ * // Even with rapid scroll events, the function will only execute
+ * // once every 100ms
+ * window.addEventListener('scroll', throttledScroll);
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare function throttle<T extends (...args: never[]) => unknown>(func: T, limit: number): (...args: Parameters<T>) => void;
+
+export { type CheckoutStepHandlers, type PageDataMap, type PageHandlerFunction, type PageHandlers, type RenderableComponent, type ToastVariant, type UIHelper, browser, clearBrowserCache, clearNubeInstance, debounce, deepClone, forEachProduct, getAppData, getCart, getCartItems, getCurrentState, getCustomer, getNubeInstance, getPageType, getProductsFromState, getScriptParam, getScriptSearchParams, getScriptURL, hasProductList, hasSections, hasSingleProduct, isAddress, isAllProductsPage, isBillingAddress, isCart, isCartItem, isCartValidationFail, isCartValidationPending, isCartValidationSuccess, isCategoryPage, isCheckoutPage, isCustomer, isHomePage, isNubeComponent, isPayment, isProductPage, isSearchPage, isSectionWithProducts, isShipping, isShippingAddress, isShippingOption, isStore, navigate, onCheckoutStep, onEvent, onPage, pageMatch, setNubeInstance, throttle, toastOn, ui };