@commercebuild/extension 0.0.13 → 0.0.14

package/config/vite.config.mjs

@@ -5,8 +5,31 @@ import tailwindcss from "@tailwindcss/vite";
 // import dts from "vite-plugin-dts";
 // import { fileURLToPath } from "url";
 import path from "path";
-import { existsSync } from "fs";
+import { existsSync, readFileSync } from "fs";
 import chalk from "chalk";
+
+// The host contract version this extension targets, declared in the manifest.
+// Injected into the bundle so the storefront host can check compatibility
+// before mounting the extension. See cb-store's docs/extension-host-api.
+function readCbApiVersion() {
+  try {
+    const manifestPath = path.resolve(process.cwd(), "commercebuild.json");
+    if (existsSync(manifestPath)) {
+      const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+      return manifest.cbApiVersion;
+    }
+  } catch {
+    // fall through — an extension with no declared version loads as legacy
+  }
+  return undefined;
+}
+
+const cbApiVersion = readCbApiVersion();
+const cbMetaBanner = cbApiVersion
+  ? `;(function(){try{if(typeof window!=="undefined"){window.__CBExtensionMeta=Object.assign(window.__CBExtensionMeta||{},{cbApiVersion:${JSON.stringify(
+      cbApiVersion,
+    )}});}}catch(e){}})();`
+  : "";
 // const __filename = fileURLToPath(import.meta.url);
 // const __dirname = dirname(__filename);
 
@@ -27,9 +50,10 @@ const baseBuildConfig = {
   rollupOptions: {
     external: ["react", "react-dom"],
     output: {
+      banner: cbMetaBanner,
       globals: {
-        react: "cb.React",
-        "react-dom": "cb.ReactDom",
+        react: "cb.lib.React",
+        "react-dom": "cb.lib.ReactDom",
       },
       assetFileNames: (assetInfo) => {
         if (assetInfo.name.endsWith(".css")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercebuild/extension",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "types": "./types/index.d.ts",
   "exports": {
     ".": {
@@ -11,7 +11,7 @@
   },
   "dependencies": {
     "@commercebuild/platform-api": "^0.*",
-    "@commercebuild/ui": "^0.0.5",
+    "@commercebuild/ui": "^0.*",
     "@headlessui/react": "^2.2.4",
     "@tailwindcss/postcss": "^4.1.10",
     "@tailwindcss/vite": "^4.1.11",
@@ -34,4 +34,4 @@
   "bin": {
     "commercebuild-extension": "./scripts/cli.js"
   }
-}
+}

package/types/global.d.ts

@@ -1,15 +1,359 @@
+// AUTO-GENERATED — DO NOT EDIT.
+// Generated by scripts/generate-extension-host-types.mjs from
+// apps/storefront/src/lib/extension/cb-host-api.types.ts (the CbHostApi
+// contract). Regenerate with `yarn generate-extension-host-types`.
+
+import * as React from "react";
+import React__default, { CSSProperties } from "react";
+import * as ReactDOM from "react-dom";
+import { cart_v2, catalog_v1, Platform } from "@commercebuild/platform-api";
+import * as icons from "lucide-react";
+import * as uis from "@commercebuild/ui";
 import {
   Disclosure,
   DisclosureButton,
   DisclosurePanel,
 } from "@headlessui/react";
-import * as uis from "@commercebuild/ui";
-import * as icons from "lucide-react";
-import * as React from "react";
-import { Platform } from "@commercebuild/platform-api";
-import type { UrlObject } from "url";
+import { UrlObject } from "url";
+import { ProductTypeInterface } from "@commercebuild/platform-api/type/v1";
+
+declare function useLanagueTranslater(): {
+  _t: (k: string, obj?: any) => string | undefined;
+  t: (k: string) => string;
+  tt: (k: string, obj?: any) => (kk: string) => string;
+  tmsg: (k: string) => any;
+  tlink: (uri: string) => string;
+  talink: (uri: string) => string;
+  trlink: (uri: string) => string;
+  lang: "en-US" | "fr-FR" | "zh";
+  locale: "en-US" | "fr-FR" | "zh";
+};
+
+declare const useTranslater: typeof useLanagueTranslater;
+
+type Category = catalog_v1.VerifiedCategoryMapper;
+type CartRequestItem = Omit<
+  cart_v2.CartUserCartItemInterface,
+  "configuratorCode" | "groupCode"
+> & {
+  imageUrl?: string;
+  description?: string;
+  unitPrice?: number;
+  detailPageUrl?: string;
+};
+type PostItemsSearchItem = catalog_v1.PostItemsSearchItem;
+type PostItemsSearchResponse = catalog_v1.PostItemsSearchResponse;
+type GetItemDetailResponse = catalog_v1.GetItemDetailResponse;
+
+interface AddToCartProps {
+  items: CartRequestItem[];
+  disabled?: boolean;
+  onSuccessCallback?: () => void;
+  className?: string;
+  /** Inline style forwarded to the button (e.g. Product Card button-scheme vars). */
+  style?: CSSProperties;
+  /**
+   * Width control (opt-in). Omit for the default responsive width; `true` = full
+   * width at all breakpoints; `false` = content width (auto).
+   */
+  fullWidth?: boolean;
+}
+declare function AddToCart({
+  items,
+  disabled,
+  onSuccessCallback,
+  className,
+  style,
+  fullWidth,
+}: AddToCartProps): React.JSX.Element;
+
+declare function CategoryProduct({
+  product,
+  imagePriority,
+}: {
+  product: PostItemsSearchItem;
+  imagePriority?: boolean;
+}): React.JSX.Element;
+
+declare function CategoryBreadcrumb({
+  category,
+}: {
+  category: Category;
+}): React.JSX.Element;
+
+declare function CategoryTitle({
+  category,
+}: {
+  category: Category;
+}): React.JSX.Element;
+
+declare function CategorySidebar({
+  category,
+  url,
+  aggregation,
+  currentFilters,
+  isDrawer,
+}: {
+  category: Category;
+  url: string;
+  aggregation?: PostItemsSearchResponse["aggregation"];
+  currentFilters: Record<string, string[]>;
+  isDrawer?: boolean;
+}): React.JSX.Element | null;
+
+declare function CategorySort({
+  url,
+  options,
+  sort,
+}: {
+  url: string;
+  options: {
+    name: string;
+  }[];
+  sort: number;
+}): React.JSX.Element;
+
+declare function CategoryProducts({
+  hasSiderbar,
+  items,
+}: {
+  hasSiderbar?: boolean;
+  items: PostItemsSearchItem[];
+}): React.JSX.Element;
+
+declare function CategoryProductsPageSize({
+  url,
+  options,
+  size,
+}: {
+  url: string;
+  options: {
+    name: string;
+    value: number;
+  }[];
+  size: number;
+}): React.JSX.Element;
+
+declare function ProductTitle({
+  product,
+}: {
+  product: GetItemDetailResponse;
+}): React.JSX.Element;
+
+type ThumbnailPosition = "top" | "right" | "bottom" | "left";
+declare const ProductImages: ({
+  product,
+  thumbnailPosition,
+}: {
+  product: GetItemDetailResponse;
+  thumbnailPosition?: ThumbnailPosition;
+}) => React.JSX.Element;
+
+declare function ProductPrice({
+  product,
+  items,
+}: {
+  product: GetItemDetailResponse | PostItemsSearchItem;
+  items?: {
+    price?: number;
+  }[];
+}): React.JSX.Element | null;
+
+declare const ProductStockStatus: ({
+  product,
+  displayStatusTitle,
+}: {
+  product: GetItemDetailResponse | PostItemsSearchItem;
+  displayStatusTitle?: boolean;
+}) => React.JSX.Element | null;
+
+declare const ProductStockQuantity: ({
+  product,
+}: {
+  product: GetItemDetailResponse;
+}) => React.JSX.Element | null;
+
+declare function ProductRating({
+  product,
+}: {
+  product: GetItemDetailResponse;
+}): React.JSX.Element;
+
+declare function ProductDescription({
+  product,
+}: {
+  product: GetItemDetailResponse;
+}): React.JSX.Element;
+
+interface ProductQuantityInputProps {
+  qty: number;
+  setQty: (qty: number) => void;
+  min?: number;
+  max?: number;
+  disabled?: boolean;
+}
+declare const ProductQuantityInput: React__default.FC<ProductQuantityInputProps>;
 
-// === Link and Image from nextjs =============================================
+declare function StandardProductAddToCart({
+  product,
+  quantityRequested,
+}: {
+  product: GetItemDetailResponse;
+  quantityRequested: number;
+}): React.JSX.Element;
+
+declare function ProductAddToFavorite({
+  product,
+}: {
+  product: GetItemDetailResponse;
+}): React.JSX.Element;
+
+declare function ProductMakeOffer({
+  product,
+  qty,
+}: {
+  product: GetItemDetailResponse;
+  qty: number;
+}): React.JSX.Element | null;
+
+declare function ProductRelatedProducts({
+  relatedProducts,
+}: {
+  relatedProducts: PostItemsSearchItem[];
+}): React.JSX.Element | null;
+
+declare function VariantProductAddToCart({
+  items,
+}: {
+  items: CartRequestItem[];
+}): React.JSX.Element;
+
+declare function ProductBreadcrumb({
+  product,
+}: {
+  product: GetItemDetailResponse;
+}): React.JSX.Element;
+
+/**
+ * @deprecated Use convertProductToCartRequestItem instead
+ */
+
+type ProductProps = {
+  type: ProductTypeInterface;
+  itemCode: string;
+  variantCode?: string;
+  defaultUnitOfMeasure: {
+    unitCode: string;
+    conversion: number;
+    default: boolean;
+  } | null;
+  description?: string;
+  detailPageUrl?: string;
+  images: {
+    main: {
+      thumbnailSmall: string;
+    } | null;
+  } | null;
+  quantityRequested?: number;
+};
+declare const convertProductItemToCartRequestItem: (
+  product: ProductProps,
+) => CartRequestItem;
+
+interface Options extends Intl.NumberFormatOptions {
+  locale?: string;
+  forceDecimals?: number;
+}
+declare const displayMoney: (
+  amount: string | number,
+  options?: Options,
+) => string;
+
+declare function revalidateTag(
+  tag: string,
+  profile:
+    | string
+    | {
+        expire?: number;
+      },
+): Promise<void>;
+declare function revalidatePath(
+  path: string,
+  type?: "layout" | "page",
+): Promise<void>;
+declare function revalidate(): Promise<void>;
+
+/**
+ * The extension host API contract (`window.cb`).
+ *
+ * This file is the SINGLE SOURCE OF TRUTH for the `cb` surface. The runtime
+ * factory `buildCbHostApi()` (./cb-host-api.ts) is typed to return `CbHostApi`,
+ * so `tsc` fails if the runtime values and this contract ever diverge.
+ *
+ * The author-facing type declaration (`global.d.ts`) is GENERATED from this
+ * file by `scripts/generate-extension-host-types.mjs` (`yarn
+ * generate-extension-host-types`). Never hand-edit the generated file.
+ *
+ * Boundary typing is hybrid: most members derive their type straight from the
+ * runtime symbol (`typeof ProductTitle`, `typeof displayMoney`); a member is
+ * only curated by hand when deriving would emit an import an extension author's
+ * project cannot resolve (e.g. `next/link`) or would leak internals.
+ */
+
+type TranslationHelpers = ReturnType<typeof useTranslater>;
+/**
+ * The Next.js App Router surface exposed to extensions. Curated (not derived
+ * from `next`) so the generated declaration does not import a `next/*` path an
+ * extension author's project cannot resolve.
+ */
+interface CbRouter {
+  push(
+    href: string,
+    options?: {
+      scroll?: boolean;
+    },
+  ): void;
+  replace(
+    href: string,
+    options?: {
+      scroll?: boolean;
+    },
+  ): void;
+  back(): void;
+  forward(): void;
+  refresh(): void;
+  prefetch(href: string): void;
+}
+/**
+ * Dynamic values the host supplies to the API at build time (per-request React
+ * context values that cannot be static imports).
+ */
+interface CbHostDeps {
+  platformApi: Platform;
+  router: CbRouter;
+  tmsg: TranslationHelpers["tmsg"];
+  tlink: TranslationHelpers["tlink"];
+}
+type CbClassValue =
+  | string
+  | number
+  | bigint
+  | boolean
+  | null
+  | undefined
+  | Record<string, unknown>
+  | CbClassValue[];
+type CbClassNameFn = (...inputs: CbClassValue[]) => string;
+type CbContainerProps = React.PropsWithChildren<
+  React.HTMLAttributes<HTMLDivElement> & {
+    maxWidth?: "sm" | "md" | "lg" | "xl" | "2xl" | "full";
+    padding?: "default";
+    additionalMaxWidth?: "default";
+  }
+>;
+type CbContainer = React.ForwardRefExoticComponent<
+  CbContainerProps & React.RefAttributes<HTMLDivElement>
+>;
 type Url = string | UrlObject;
 type OnNavigateEventHandler = (event: { preventDefault: () => void }) => void;
 type InternalLinkProps = {
@@ -28,15 +372,13 @@ type InternalLinkProps = {
   children?: React.ReactNode | undefined;
   onNavigate?: OnNavigateEventHandler;
 } & React.RefAttributes<HTMLAnchorElement>;
-
-declare const NextLink: React.ForwardRefExoticComponent<
+type CbLink = React.ForwardRefExoticComponent<
   Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, keyof InternalLinkProps> &
     InternalLinkProps & {
       children?: React.ReactNode | undefined;
     } & React.RefAttributes<HTMLAnchorElement>
 >;
-
-export interface StaticImageData {
+interface StaticImageData {
   src: string;
   height: number;
   width: number;
@@ -44,19 +386,19 @@ export interface StaticImageData {
   blurWidth?: number;
   blurHeight?: number;
 }
-export interface StaticRequire {
+interface StaticRequire {
   default: StaticImageData;
 }
-export type StaticImport = StaticRequire | StaticImageData;
-export type ImageLoaderProps = {
+type StaticImport = StaticRequire | StaticImageData;
+type ImageLoaderProps = {
   src: string;
   width: number;
   quality?: number;
 };
-export type ImageLoader = (p: ImageLoaderProps) => string;
-export type PlaceholderValue = "blur" | "empty" | `data:image/${string}`;
-export type OnLoadingComplete = (img: HTMLImageElement) => void;
-declare const NextImage: React.ForwardRefExoticComponent<
+type ImageLoader = (p: ImageLoaderProps) => string;
+type PlaceholderValue = "blur" | "empty" | `data:image/${string}`;
+type OnLoadingComplete = (img: HTMLImageElement) => void;
+type CbImage = React.ForwardRefExoticComponent<
   Omit<
     React.DetailedHTMLProps<
       React.ImgHTMLAttributes<HTMLImageElement>,
@@ -85,71 +427,98 @@ declare const NextImage: React.ForwardRefExoticComponent<
     lazyRoot?: string;
   } & React.RefAttributes<HTMLImageElement | null>
 >;
-
-// ============================================================================
-
-declare global {
-  const cb: {
-    version: string;
+interface CbHostApi {
+  /** Host-contract semver — see docs/extension-host-api/versioning.md. */
+  version: string;
+  /**
+   * Shared libraries the host provides as build-time externals, so an extension
+   * shares the host's single instance instead of bundling its own (critical for
+   * React — two instances break hooks). The extension build maps
+   * `import ... from "react"` → `cb.lib.React` and `"react-dom"` →
+   * `cb.lib.ReactDom`.
+   */
+  lib: {
     React: typeof React;
-    platformApi: Platform;
-    utils: {
-      convertProductItemToCartRequestItem;
-      tlink;
-      tmsg;
-      router;
-      displayMoney;
-      cn;
-      revalidate;
-      revalidateTag;
-      revalidatePath;
+    ReactDom: typeof ReactDOM;
+  };
+  /** The platform (commerce backend) API SDK client. */
+  platform: Platform;
+  /**
+   * Feature-detect a member by dotted path, e.g.
+   * `cb.has("com.Product.ProductMakeOffer")`. Lets an extension degrade
+   * gracefully across host versions instead of hard-crashing.
+   */
+  has: (path: string) => boolean;
+  utils: {
+    convertProductItemToCartRequestItem: typeof convertProductItemToCartRequestItem;
+    tlink: TranslationHelpers["tlink"];
+    tmsg: TranslationHelpers["tmsg"];
+    router: CbRouter;
+    displayMoney: typeof displayMoney;
+    cn: CbClassNameFn;
+    revalidate: typeof revalidate;
+    revalidateTag: typeof revalidateTag;
+    revalidatePath: typeof revalidatePath;
+  };
+  com: {
+    Cart: {
+      AddToCart: typeof AddToCart;
     };
-    com: {
-      Cart: {
-        AddToCart;
-      };
-      Category: {
-        CategoryProducts;
-        CategoryProduct;
-        CategoryBreadcrumb;
-        CategoryTitle;
-        CategorySidebar;
-        CategorySort;
-        CategoryProductsPageSize;
-      };
-      Product: {
-        ProductTitle;
-        ProductImages;
-        ProductPrice;
-        ProductStockStatus;
-        ProductStockQuantity;
-        ProductRating;
-        ProductDescription;
-        ProductTabs;
-        ProductQuantityInput;
-        StandardProductAddToCart;
-        VariantProductAddToCart;
-        ProductAddToFavorite;
-        ProductMakeOffer;
-        ProductRelatedProducts;
-      };
+    Category: {
+      CategoryProducts: typeof CategoryProducts;
+      CategoryProduct: typeof CategoryProduct;
+      CategoryBreadcrumb: typeof CategoryBreadcrumb;
+      CategoryTitle: typeof CategoryTitle;
+      CategorySidebar: typeof CategorySidebar;
+      CategorySort: typeof CategorySort;
+      CategoryProductsPageSize: typeof CategoryProductsPageSize;
+    };
+    Product: {
+      ProductTitle: typeof ProductTitle;
+      ProductImages: typeof ProductImages;
+      ProductPrice: typeof ProductPrice;
+      ProductStockStatus: typeof ProductStockStatus;
+      ProductStockQuantity: typeof ProductStockQuantity;
+      ProductRating: typeof ProductRating;
+      ProductDescription: typeof ProductDescription;
+      ProductQuantityInput: typeof ProductQuantityInput;
+      StandardProductAddToCart: typeof StandardProductAddToCart;
+      VariantProductAddToCart: typeof VariantProductAddToCart;
+      ProductAddToFavorite: typeof ProductAddToFavorite;
+      ProductMakeOffer: typeof ProductMakeOffer;
+      ProductRelatedProducts: typeof ProductRelatedProducts;
+      ProductBreadcrumb: typeof ProductBreadcrumb;
     };
-    ui: {
-      icons: { [K in keyof typeof icons]: (typeof icons)[K] };
-      Link: typeof NextLink;
-      Image: typeof NextImage;
-      Container: React.FC<
-        React.PropsWithChildren<React.HTMLAttributes<HTMLDivElement>>
-      >;
-      Disclosure: typeof Disclosure;
-      DisclosureButton: typeof DisclosureButton;
-      DisclosurePanel: typeof DisclosurePanel;
-    } & { [K in keyof typeof uis]: (typeof uis)[K] };
   };
-
+  ui: {
+    icons: typeof icons;
+    Link: CbLink;
+    Image: CbImage;
+    Container: CbContainer;
+    Disclosure: typeof Disclosure;
+    DisclosureButton: typeof DisclosureButton;
+    DisclosurePanel: typeof DisclosurePanel;
+  } & typeof uis;
+}
+declare global {
+  const cb: CbHostApi;
   interface Window {
-    cb: typeof cb;
+    cb: CbHostApi;
+  }
+  /**
+   * Storefront domain types made ambient for extension authors, so
+   * component/page code (and editor scaffolds) can reference them bare
+   * without importing from the SDK.
+   */
+  type Category = catalog_v1.VerifiedCategoryMapper;
+  interface Product extends catalog_v1.CatalogProductSearchProduct {
+    image: Required<
+      Pick<catalog_v1.CatalogProductSearchProduct["details"]["images"], "main">
+    >["main"];
+    originalPrice?: catalog_v1.CatalogPriceItemDto;
+    formattedPrice: string;
+    href: string;
   }
 }
 
-export {};
+export type { CbHostApi, CbHostDeps, CbRouter };