@tiendanube/nube-sdk-helper 0.0.1

package/README.md

@@ -0,0 +1,174 @@
+# `@tiendanube/nube-sdk-helper`
+
+**Utility functions, type guards, and SDK instance management for building NubeSDK apps.**
+
+## About
+
+`@tiendanube/nube-sdk-helper` centralizes the repetitive patterns that NubeSDK
+apps need: registering and accessing the SDK instance, reading state with
+selectors, runtime type guards, page/checkout handling, rendering, and event
+subscriptions. The goal is less boilerplate and stronger type safety.
+
+Apps in NubeSDK run **inside isolated web workers**, without direct access to the
+DOM. All helpers are designed for that environment and interact with the
+platform exclusively through the SDK instance.
+
+## Installation
+
+```sh
+npm install @tiendanube/nube-sdk-helper @tiendanube/nube-sdk-types
+```
+
+> Note: `@tiendanube/nube-sdk-types` is a peer dependency and must be installed alongside this package.
+
+## Instance management
+
+The NubeSDK runtime passes the SDK instance only as the argument of your app
+entry point (`App(nube)`). Register it once with `setNubeInstance` and every
+other helper (`getCurrentState`, `ui`, `browser`, selectors, `onPage`, ...) can
+access it without you having to thread `nube` through every function and
+component.
+
+```typescript
+import {
+  setNubeInstance,
+  getCurrentState,
+  getNubeInstance,
+  ui,
+} from "@tiendanube/nube-sdk-helper";
+import type { NubeSDK } from "@tiendanube/nube-sdk-types";
+
+export function App(nube: NubeSDK) {
+  setNubeInstance(nube); // call this first
+
+  const state = getCurrentState();
+  ui.showToast(`You are on the ${state.location.page.type} page`);
+}
+```
+
+- `setNubeInstance(nube)` — registers the instance (call once at the top of `App`).
+- `getNubeInstance()` — returns the registered instance; throws a descriptive
+  error if you forgot to register it.
+- `clearNubeInstance()` — clears the registered instance (useful in tests).
+
+## State access
+
+```typescript
+import {
+  getCurrentState,
+  getCart,
+  getCartItems,
+  getPageType,
+  getCustomer,
+  getAppData,
+  getScriptParam,
+} from "@tiendanube/nube-sdk-helper";
+
+// Selectors read the current state by default; pass a state to keep them pure.
+const items = getCartItems();
+const pageType = getPageType();
+const customer = getCustomer();
+
+// App data injected by the runtime
+const { id } = getAppData();
+const variant = getScriptParam("variant"); // ?variant=... on the app script URL
+```
+
+## Pages and checkout
+
+```typescript
+import { pageMatch, onPage, onCheckoutStep } from "@tiendanube/nube-sdk-helper";
+
+// One-off dispatch on the current page:
+pageMatch(getCurrentState(), {
+  product: (state, product) => console.log(product.name),
+  checkout: (state, checkout) => console.log(checkout.step),
+});
+
+// Subscribe to navigation. Both return an unsubscribe function:
+const stop = onPage({
+  product: (state, product) => trackProductView(product.id),
+});
+// stop(); // when you no longer need it
+
+onCheckoutStep({
+  success: () => trackPurchase(),
+});
+```
+
+## Events
+
+```typescript
+import { onEvent, toastOn } from "@tiendanube/nube-sdk-helper";
+
+// Thin wrapper around nube.on that returns an unsubscribe:
+const off = onEvent("cart:update", (state) => {
+  console.log("items:", state.cart.items.length);
+});
+
+// Show a toast whenever an event fires:
+toastOn("cart:add:success", "Added to cart", "success");
+toastOn("cart:update", (state) => `Cart: ${state.cart.items.length} items`);
+```
+
+## Rendering
+
+```typescript
+import { ui, forEachProduct } from "@tiendanube/nube-sdk-helper";
+
+// Render the same component into many slots at once:
+ui.renderAll(["corner_top_left", "corner_top_right"], { type: "txt", children: "Hi" });
+
+// Render one component per product on the current page (keys are added automatically):
+getNubeInstance().render(
+  "product_grid_item_image_bottom_right",
+  forEachProduct((product) => ({ type: "txt", children: product.name })),
+);
+
+ui.showToast("Done!", "success");
+ui.clear("corner_top_right");
+```
+
+## Browser APIs
+
+```typescript
+import { browser, navigate } from "@tiendanube/nube-sdk-helper";
+
+await browser.asyncLocalStorage.setItem("key", "value");
+navigate("/products/123");
+```
+
+## Type guards
+
+Runtime checks that also narrow types for TypeScript:
+
+- Pages: `isProductPage`, `isCategoryPage`, `isCheckoutPage`, `isHomePage`,
+  `isAllProductsPage`, `isSearchPage`
+- Cart: `isCart`, `isCartItem`, `isCartValidationSuccess` / `Pending` / `Fail`
+- Domain: `isStore`, `isCustomer`, `isPayment`, `isShipping`, `isShippingOption`,
+  `isAddress`, `isShippingAddress`, `isBillingAddress`
+- Components / page data: `isNubeComponent`, `hasProductList`, `hasSections`,
+  `hasSingleProduct`, `isSectionWithProducts`
+
+```typescript
+import { isProductPage } from "@tiendanube/nube-sdk-helper";
+
+const { page } = getCurrentState().location;
+if (isProductPage(page)) {
+  console.log(page.data.product.name);
+}
+```
+
+## General utilities
+
+```typescript
+import { deepClone, debounce, throttle } from "@tiendanube/nube-sdk-helper";
+
+const copy = deepClone(state); // uses structuredClone when available
+const debounced = debounce((q: string) => search(q), 300);
+const throttled = throttle(() => onScroll(), 100);
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,449 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  browser: () => browser,
+  clearBrowserCache: () => clearBrowserCache,
+  clearNubeInstance: () => clearNubeInstance,
+  debounce: () => debounce,
+  deepClone: () => deepClone,
+  forEachProduct: () => forEachProduct,
+  getAppData: () => getAppData,
+  getCart: () => getCart,
+  getCartItems: () => getCartItems,
+  getCurrentState: () => getCurrentState,
+  getCustomer: () => getCustomer,
+  getNubeInstance: () => getNubeInstance,
+  getPageType: () => getPageType,
+  getProductsFromState: () => getProductsFromState,
+  getScriptParam: () => getScriptParam,
+  getScriptSearchParams: () => getScriptSearchParams,
+  getScriptURL: () => getScriptURL,
+  hasProductList: () => hasProductList,
+  hasSections: () => hasSections,
+  hasSingleProduct: () => hasSingleProduct,
+  isAddress: () => isAddress,
+  isAllProductsPage: () => isAllProductsPage,
+  isBillingAddress: () => isBillingAddress,
+  isCart: () => isCart,
+  isCartItem: () => isCartItem,
+  isCartValidationFail: () => isCartValidationFail,
+  isCartValidationPending: () => isCartValidationPending,
+  isCartValidationSuccess: () => isCartValidationSuccess,
+  isCategoryPage: () => isCategoryPage,
+  isCheckoutPage: () => isCheckoutPage,
+  isCustomer: () => isCustomer,
+  isHomePage: () => isHomePage,
+  isNubeComponent: () => isNubeComponent,
+  isPayment: () => isPayment,
+  isProductPage: () => isProductPage,
+  isSearchPage: () => isSearchPage,
+  isSectionWithProducts: () => isSectionWithProducts,
+  isShipping: () => isShipping,
+  isShippingAddress: () => isShippingAddress,
+  isShippingOption: () => isShippingOption,
+  isStore: () => isStore,
+  navigate: () => navigate,
+  onCheckoutStep: () => onCheckoutStep,
+  onEvent: () => onEvent,
+  onPage: () => onPage,
+  pageMatch: () => pageMatch,
+  setNubeInstance: () => setNubeInstance,
+  throttle: () => throttle,
+  toastOn: () => toastOn,
+  ui: () => ui
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/lib/instance.ts
+var registeredInstance;
+function readGlobalInstance() {
+  return typeof self !== "undefined" ? self.__SDK_INSTANCE__ : void 0;
+}
+function setNubeInstance(nube) {
+  registeredInstance = nube;
+}
+function getNubeInstance() {
+  const instance2 = registeredInstance ?? readGlobalInstance();
+  if (!instance2) {
+    throw new Error(
+      "NubeSDK instance not registered. Call setNubeInstance(nube) at the start of your App(nube) entry point."
+    );
+  }
+  return instance2;
+}
+function clearNubeInstance() {
+  registeredInstance = void 0;
+}
+
+// src/lib/browser.ts
+var instance = null;
+var browser = new Proxy({}, {
+  get(_, prop) {
+    if (instance === null) {
+      instance = getNubeInstance().getBrowserAPIs();
+    }
+    return instance[prop];
+  }
+});
+function navigate(route) {
+  browser.navigate(route);
+}
+function clearBrowserCache() {
+  instance = null;
+}
+
+// src/lib/ui.ts
+var ui = Object.freeze({
+  // Helpers for common components
+  showToast(message, variant = "info") {
+    const toast = {
+      type: "toastRoot",
+      variant,
+      children: [{ type: "toastTitle", children: message }]
+    };
+    getNubeInstance().render("corner_top_right", toast);
+  },
+  // Clear slot
+  clear(slot) {
+    getNubeInstance().clearSlot(slot);
+  },
+  render(slot, component) {
+    getNubeInstance().render(slot, component);
+  },
+  // Render the same component across multiple slots in a single call.
+  renderAll(slots, component) {
+    const nube = getNubeInstance();
+    for (const slot of slots) {
+      nube.render(slot, component);
+    }
+  }
+});
+
+// src/lib/events.ts
+function onEvent(event, listener) {
+  const nube = getNubeInstance();
+  nube.on(event, listener);
+  return () => nube.off(event, listener);
+}
+function toastOn(event, message, variant) {
+  const listener = ((state) => {
+    const text = typeof message === "function" ? message(state) : message;
+    ui.showToast(text, variant);
+  });
+  return onEvent(event, listener);
+}
+
+// src/lib/getters.ts
+function getCurrentState() {
+  return getNubeInstance().getState();
+}
+function getAppData() {
+  return self.__APP_DATA__;
+}
+var cachedScriptURL;
+function getScriptURL() {
+  if (!cachedScriptURL) {
+    cachedScriptURL = Object.freeze(new URL(self.__APP_DATA__.script));
+  }
+  return cachedScriptURL;
+}
+function getScriptSearchParams() {
+  return getScriptURL().searchParams;
+}
+function getScriptParam(key) {
+  return getScriptSearchParams().get(key);
+}
+
+// src/internal/primitives.ts
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function isPlainObject(value) {
+  return isObject(value) && !Array.isArray(value) && Object.prototype.toString.call(value) === "[object Object]";
+}
+
+// src/lib/guards/address.ts
+function isAddress(value) {
+  return isPlainObject(value) && typeof value.zipcode === "string" && (value.first_name === null || typeof value.first_name === "string") && (value.last_name === null || typeof value.last_name === "string") && (value.address === null || typeof value.address === "string") && (value.number === null || typeof value.number === "string") && (value.floor === null || typeof value.floor === "string") && (value.locality === null || typeof value.locality === "string") && (value.city === null || typeof value.city === "string") && (value.state === null || typeof value.state === "string") && (value.country === null || typeof value.country === "string") && (value.phone === null || typeof value.phone === "string");
+}
+function isShippingAddress(value) {
+  return isPlainObject(value) && typeof value.zipcode === "string" && (value.first_name === null || typeof value.first_name === "string") && (value.last_name === null || typeof value.last_name === "string") && (value.address === null || typeof value.address === "string") && (value.number === null || typeof value.number === "string") && (value.floor === null || typeof value.floor === "string") && (value.locality === null || typeof value.locality === "string") && (value.city === null || typeof value.city === "string") && (value.state === null || typeof value.state === "string") && (value.country === null || typeof value.country === "string") && (value.phone === null || typeof value.phone === "string") && (value.between_street === null || typeof value.between_street === "string") && (value.reference === null || typeof value.reference === "string");
+}
+function isBillingAddress(value) {
+  return isPlainObject(value) && typeof value.zipcode === "string" && (value.first_name === null || typeof value.first_name === "string") && (value.last_name === null || typeof value.last_name === "string") && (value.address === null || typeof value.address === "string") && (value.number === null || typeof value.number === "string") && (value.floor === null || typeof value.floor === "string") && (value.locality === null || typeof value.locality === "string") && (value.city === null || typeof value.city === "string") && (value.state === null || typeof value.state === "string") && (value.country === null || typeof value.country === "string") && (value.phone === null || typeof value.phone === "string") && (value.id_number === null || typeof value.id_number === "string") && (value.customer_type === null || typeof value.customer_type === "string") && (value.business_name === null || typeof value.business_name === "string") && (value.trade_name === null || typeof value.trade_name === "string") && (value.state_registration === null || typeof value.state_registration === "string") && (value.fiscal_regime === null || typeof value.fiscal_regime === "string") && (value.invoice_use === null || typeof value.invoice_use === "string") && (value.document_type === null || typeof value.document_type === "string") && (value.business_activity === null || typeof value.business_activity === "string");
+}
+
+// src/lib/guards/cart.ts
+function isCart(value) {
+  return isPlainObject(value) && typeof value.id === "string" && isPlainObject(value.validation) && typeof value.validation.status === "string" && Array.isArray(value.items) && isPlainObject(value.prices) && typeof value.prices.subtotal === "number" && typeof value.prices.total === "number" && isPlainObject(value.coupon);
+}
+function isCartItem(value) {
+  return isPlainObject(value) && typeof value.id === "number" && typeof value.name === "string" && typeof value.price === "string" && typeof value.quantity === "number" && typeof value.free_shipping === "boolean" && typeof value.product_id === "number" && typeof value.variant_id === "number" && typeof value.thumbnail === "string" && typeof value.variant_values === "string" && typeof value.url === "string" && typeof value.is_ahora_12_eligible === "boolean";
+}
+function isCartValidationSuccess(validation) {
+  return validation.status === "success";
+}
+function isCartValidationPending(validation) {
+  return validation.status === "pending";
+}
+function isCartValidationFail(validation) {
+  return validation.status === "fail";
+}
+
+// src/lib/guards/components.ts
+function isNubeComponent(value) {
+  return typeof value === "string" || isPlainObject(value) && typeof value.type === "string";
+}
+function hasProductList(data) {
+  return isObject(data) && "products" in data && Array.isArray(data.products);
+}
+function hasSections(data) {
+  return isObject(data) && "sections" in data && Array.isArray(data.sections);
+}
+function isSectionWithProducts(item) {
+  return isObject(item) && "products" in item && Array.isArray(item.products);
+}
+function hasSingleProduct(data) {
+  return isObject(data) && "product" in data && isObject(data.product) && "id" in data.product;
+}
+
+// src/lib/guards/domain.ts
+function isStore(value) {
+  return isPlainObject(value) && typeof value.id === "number" && typeof value.name === "string" && typeof value.domain === "string" && typeof value.currency === "string" && typeof value.language === "string";
+}
+function isCustomer(value) {
+  return isPlainObject(value) && (value.id === null || typeof value.id === "number") && isPlainObject(value.contact) && isPlainObject(value.shipping_address) && isPlainObject(value.billing_address);
+}
+function isPayment(value) {
+  return isPlainObject(value) && (value.status === null || typeof value.status === "string") && (value.selected === null || isPlainObject(value.selected));
+}
+function isShipping(value) {
+  return isPlainObject(value) && (value.selected === null || typeof value.selected === "string") && (value.options === void 0 || Array.isArray(value.options)) && (value.custom_labels === void 0 || isPlainObject(value.custom_labels));
+}
+function isShippingOption(value) {
+  return isPlainObject(value) && typeof value.id === "string" && typeof value.price === "number" && typeof value.currency === "string" && typeof value.phone_required === "boolean" && typeof value.id_required === "boolean" && typeof value.accepts_cod === "boolean" && typeof value.free_shipping_eligible === "boolean" && isPlainObject(value.extra) && typeof value.hidden === "boolean" && typeof value.shippable === "boolean";
+}
+
+// src/lib/guards/pages.ts
+function isProductPage(page) {
+  return page.type === "product";
+}
+function isCategoryPage(page) {
+  return page.type === "category";
+}
+function isCheckoutPage(page) {
+  return page.type === "checkout";
+}
+function isAllProductsPage(page) {
+  return page.type === "products";
+}
+function isSearchPage(page) {
+  return page.type === "search";
+}
+function isHomePage(page) {
+  return page.type === "home";
+}
+
+// src/lib/page-match.ts
+function pageMatch(state, handlers) {
+  const { page } = state.location;
+  if (isProductPage(page)) {
+    handlers.product?.(state, page.data.product);
+    return;
+  }
+  if (isCategoryPage(page)) {
+    handlers.category?.(state, page.data);
+    return;
+  }
+  if (isCheckoutPage(page)) {
+    handlers.checkout?.(state, page.data);
+    return;
+  }
+  if (isHomePage(page)) {
+    handlers.home?.(state, page.data);
+    return;
+  }
+}
+function onPage(handlers) {
+  const nube = getNubeInstance();
+  const currentState = nube.getState();
+  pageMatch(currentState, handlers);
+  const listener = (state) => pageMatch(state, handlers);
+  nube.on("location:updated", listener);
+  return () => nube.off("location:updated", listener);
+}
+function onCheckoutStep(handlers) {
+  const nube = getNubeInstance();
+  const currentState = nube.getState();
+  const currentPage = currentState.location.page;
+  if (currentPage.type === "checkout") {
+    handlers[currentPage?.data?.step]?.(currentState);
+  }
+  const listener = (state) => {
+    const { page } = state.location;
+    if (page.type !== "checkout") return;
+    const step = page.data.step;
+    handlers[step]?.(state);
+  };
+  nube.on("checkout:ready", listener);
+  return () => nube.off("checkout:ready", listener);
+}
+
+// src/lib/render.ts
+function getProductsFromState(state) {
+  const { page } = state.location;
+  if (!page || !("data" in page) || !page.data) {
+    return [];
+  }
+  const products = [];
+  if (hasProductList(page.data)) {
+    products.push(...page.data.products);
+  }
+  if (hasSections(page.data)) {
+    for (const section of page.data.sections) {
+      if (isSectionWithProducts(section)) {
+        products.push(...section.products);
+      }
+    }
+  }
+  if (hasSingleProduct(page.data)) {
+    products.push(page.data.product);
+  }
+  return products;
+}
+function forEachProduct(renderFactory) {
+  return (state) => {
+    const products = getProductsFromState(state);
+    if (!products.length) return [];
+    return products.reduce((acc, product) => {
+      const component = renderFactory(product);
+      if (component) {
+        acc.push(Object.assign({}, component, { key: product.id }));
+      }
+      return acc;
+    }, []);
+  };
+}
+
+// src/lib/selectors.ts
+function getCart(state = getCurrentState()) {
+  return state.cart;
+}
+function getCartItems(state = getCurrentState()) {
+  return state.cart.items;
+}
+function getPageType(state = getCurrentState()) {
+  return state.location.page.type;
+}
+function getCustomer(state = getCurrentState()) {
+  return state.customer;
+}
+
+// src/lib/utils.ts
+function deepClone(obj) {
+  if (obj === null || typeof obj !== "object") {
+    return obj;
+  }
+  if (typeof structuredClone === "function") {
+    return structuredClone(obj);
+  }
+  return JSON.parse(JSON.stringify(obj));
+}
+function debounce(func, wait) {
+  let timeout;
+  return (...args) => {
+    const later = () => {
+      timeout = void 0;
+      func(...args);
+    };
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+    timeout = setTimeout(later, wait);
+  };
+}
+function throttle(func, limit) {
+  let inThrottle;
+  return (...args) => {
+    if (!inThrottle) {
+      func(...args);
+      inThrottle = true;
+      setTimeout(() => {
+        inThrottle = false;
+      }, limit);
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  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
+});
+//# sourceMappingURL=index.cjs.map