@shopify/hydrogen-react 2026.4.0 → 2026.4.2

package/dist/node-prod/useShopifyCookies.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"useShopifyCookies.mjs","sources":["../../src/useShopifyCookies.tsx"],"sourcesContent":["import {useEffect, useRef, useState} from 'react';\n// @ts-ignore - worktop/cookie types not properly exported\nimport {stringify} from 'worktop/cookie';\nimport {SHOPIFY_Y, SHOPIFY_S} from './cart-constants.js';\nimport {buildUUID} from './cookies-utils.js';\nimport {\n  getTrackingValues,\n  SHOPIFY_UNIQUE_TOKEN_HEADER,\n  SHOPIFY_VISIT_TOKEN_HEADER,\n} from './tracking-utils.js';\n\nconst longTermLength = 60 * 60 * 24 * 360 * 1; // ~1 year expiry\nconst shortTermLength = 60 * 30; // 30 mins\n\ntype UseShopifyCookiesOptions = CoreShopifyCookiesOptions & {\n  /**\n   * If set to `false`, Shopify cookies will be removed.\n   * If set to `true`, Shopify unique user token cookie will have cookie expiry of 1 year.\n   * Defaults to false.\n   **/\n  hasUserConsent?: boolean;\n  /**\n   * The domain scope of the cookie. Defaults to empty string.\n   **/\n  domain?: string;\n  /**\n   * The checkout domain of the shop. Defaults to empty string. If set, the cookie domain will check if it can be set with the checkout domain.\n   */\n  checkoutDomain?: string;\n  /**\n   * If set to `true`, it skips modifying the deprecated shopify_y and shopify_s cookies.\n   */\n  ignoreDeprecatedCookies?: boolean;\n};\n\n/**\n * Sets the `shopify_y` and `shopify_s` cookies in the browser based on user consent\n * for backward compatibility support.\n *\n * If `fetchTrackingValues` is true, it makes a request to Storefront API\n * to fetch or refresh Shopiy analytics and marketing cookies and tracking values.\n * Generally speaking, this should only be needed if you're not using Hydrogen's\n * built-in analytics components and hooks that already handle this automatically.\n * For example, set it to `true` if you are using `hydrogen-react` only with\n * a different framework and still need to make a same-domain request to\n * Storefront API to set cookies.\n *\n * If `ignoreDeprecatedCookies` is true, it skips setting the deprecated cookies entirely.\n * Useful when you only want to use the newer tracking values and not rely on the deprecated ones.\n *\n * @returns `true` when cookies are set and ready.\n */\nexport function useShopifyCookies(options?: UseShopifyCookiesOptions): boolean {\n  const {\n    hasUserConsent,\n    domain = '',\n    checkoutDomain = '',\n    storefrontAccessToken,\n    fetchTrackingValues,\n    ignoreDeprecatedCookies = false,\n  } = options || {};\n\n  const coreCookiesReady = useCoreShopifyCookies({\n    storefrontAccessToken,\n    fetchTrackingValues,\n    checkoutDomain,\n  });\n\n  useEffect(() => {\n    // Skip setting JS cookies until http-only cookies and server-timing\n    // are ready so that we have values synced in JS and http-only cookies.\n    if (ignoreDeprecatedCookies || !coreCookiesReady) return;\n\n    /**\n     * Setting cookie with domain\n     *\n     * If no domain is provided, the cookie will be set for the current host.\n     * For Shopify, we need to ensure this domain is set with a leading dot.\n     */\n\n    // Use override domain or current host\n    let currentDomain = domain || window.location.host;\n\n    if (checkoutDomain) {\n      const checkoutDomainParts = checkoutDomain.split('.').reverse();\n      const currentDomainParts = currentDomain.split('.').reverse();\n      const sameDomainParts: Array<string> = [];\n      checkoutDomainParts.forEach((part, index) => {\n        if (part === currentDomainParts[index]) {\n          sameDomainParts.push(part);\n        }\n      });\n\n      currentDomain = sameDomainParts.reverse().join('.');\n    }\n\n    // Reset domain if localhost\n    if (/^localhost/.test(currentDomain)) currentDomain = '';\n\n    // Shopify checkout only consumes cookies set with leading dot domain\n    const domainWithLeadingDot = currentDomain\n      ? /^\\./.test(currentDomain)\n        ? currentDomain\n        : `.${currentDomain}`\n      : '';\n\n    /**\n     * Set user and session cookies and refresh the expiry time\n     */\n    if (hasUserConsent) {\n      const trackingValues = getTrackingValues();\n      if (\n        (\n          trackingValues.uniqueToken ||\n          trackingValues.visitToken ||\n          ''\n        ).startsWith('00000000-')\n      ) {\n        // Skip writing cookies when tracking values signal we don't have consent yet\n        return;\n      }\n\n      setCookie(\n        SHOPIFY_Y,\n        trackingValues.uniqueToken || buildUUID(),\n        longTermLength,\n        domainWithLeadingDot,\n      );\n      setCookie(\n        SHOPIFY_S,\n        trackingValues.visitToken || buildUUID(),\n        shortTermLength,\n        domainWithLeadingDot,\n      );\n    } else {\n      setCookie(SHOPIFY_Y, '', 0, domainWithLeadingDot);\n      setCookie(SHOPIFY_S, '', 0, domainWithLeadingDot);\n    }\n  }, [\n    coreCookiesReady,\n    hasUserConsent,\n    domain,\n    checkoutDomain,\n    ignoreDeprecatedCookies,\n  ]);\n\n  return coreCookiesReady;\n}\n\nfunction setCookie(\n  name: string,\n  value: string,\n  maxage: number,\n  domain: string,\n): void {\n  document.cookie = stringify(name, value, {\n    maxage,\n    domain,\n    samesite: 'Lax',\n    path: '/',\n  });\n}\n\nasync function fetchTrackingValuesFromBrowser(\n  storefrontAccessToken?: string,\n  storefrontApiDomain = '',\n): Promise<void> {\n  // These values might come from server-timing or old cookies.\n  // If consent cannot be initially assumed, these tokens\n  // will be dropped in SFAPI and it will return a mock token\n  // starting with '00000000-'.\n  // However, if consent can be assumed initially, these tokens\n  // will be used to create proper cookies and continue our flow.\n  const {uniqueToken, visitToken} = getTrackingValues();\n\n  const response = await fetch(\n    // TODO: update this endpoint when it becomes stable\n    `${storefrontApiDomain.replace(/\\/+$/, '')}/api/unstable/graphql.json`,\n    {\n      method: 'POST',\n      headers: {\n        'Content-Type': 'application/json',\n        ...(storefrontAccessToken && {\n          'X-Shopify-Storefront-Access-Token': storefrontAccessToken,\n        }),\n        ...(visitToken || uniqueToken\n          ? {\n              [SHOPIFY_VISIT_TOKEN_HEADER]: visitToken,\n              [SHOPIFY_UNIQUE_TOKEN_HEADER]: uniqueToken,\n            }\n          : undefined),\n      },\n      body: JSON.stringify({\n        query:\n          // This query ensures we get _cmp (consent) server-timing header, which is not available in other queries.\n          // This value can be passed later to consent-tracking-api and privacy-banner scripts to avoid extra requests.\n          'query ensureCookies { consentManagement { cookies(visitorConsent:{}) { cookieDomain } } }',\n      }),\n    },\n  );\n\n  if (!response.ok) {\n    throw new Error(\n      `Failed to fetch consent from browser: ${response.status} ${response.statusText}`,\n    );\n  }\n\n  // Consume the body to complete the request and\n  // ensure server-timing is available in performance API\n  await response.json();\n\n  // Ensure we cache the latest tracking values from resources timing\n  getTrackingValues();\n}\n\ntype CoreShopifyCookiesOptions = {\n  storefrontAccessToken?: string;\n  fetchTrackingValues?: boolean;\n  checkoutDomain?: string;\n};\n\n/**\n * Gets http-only cookies from Storefront API via same-origin fetch request.\n * Falls back to checkout domain if provided to at least obtain the tracking\n * values via server-timing headers.\n */\nfunction useCoreShopifyCookies({\n  checkoutDomain,\n  storefrontAccessToken,\n  fetchTrackingValues = false,\n}: CoreShopifyCookiesOptions) {\n  const [cookiesReady, setCookiesReady] = useState(!fetchTrackingValues);\n  const hasFetchedTrackingValues = useRef(false);\n\n  useEffect(() => {\n    if (!fetchTrackingValues) {\n      // Backend did the work, or proxy is disabled.\n      setCookiesReady(true);\n      return;\n    }\n\n    // React runs effects twice in dev mode, avoid double fetching\n    if (hasFetchedTrackingValues.current) return;\n    hasFetchedTrackingValues.current = true;\n\n    // Fetch consent from browser via proxy\n    fetchTrackingValuesFromBrowser(storefrontAccessToken)\n      .catch((error) =>\n        checkoutDomain\n          ? // Retry with checkout domain if available to at least\n            // get the server-timing values for tracking.\n            fetchTrackingValuesFromBrowser(\n              storefrontAccessToken,\n              checkoutDomain,\n            )\n          : Promise.reject(error),\n      )\n      .catch((error) => {\n        console.warn(\n          '[h2:warn:useShopifyCookies] Failed to fetch tracking values from browser: ' +\n            (error instanceof Error ? error.message : String(error)),\n        );\n      })\n      .finally(() => {\n        // Proceed even on errors, degraded tracking is better than no app\n        setCookiesReady(true);\n      });\n  }, [checkoutDomain, fetchTrackingValues, storefrontAccessToken]);\n\n  return cookiesReady;\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"useShopifyCookies.mjs","names":[],"sources":["../../src/useShopifyCookies.tsx"],"sourcesContent":["import {useEffect, useRef, useState} from 'react';\n// @ts-ignore - worktop/cookie types not properly exported\nimport {stringify} from 'worktop/cookie';\nimport {SHOPIFY_Y, SHOPIFY_S} from './cart-constants.js';\nimport {buildUUID} from './cookies-utils.js';\nimport {\n  getTrackingValues,\n  SHOPIFY_UNIQUE_TOKEN_HEADER,\n  SHOPIFY_VISIT_TOKEN_HEADER,\n} from './tracking-utils.js';\n\nconst longTermLength = 60 * 60 * 24 * 360 * 1; // ~1 year expiry\nconst shortTermLength = 60 * 30; // 30 mins\n\ntype UseShopifyCookiesOptions = CoreShopifyCookiesOptions & {\n  /**\n   * If set to `false`, Shopify cookies will be removed.\n   * If set to `true`, Shopify unique user token cookie will have cookie expiry of 1 year.\n   * Defaults to false.\n   **/\n  hasUserConsent?: boolean;\n  /**\n   * The domain scope of the cookie. Defaults to empty string.\n   **/\n  domain?: string;\n  /**\n   * The checkout domain of the shop. Defaults to empty string. If set, the cookie domain will check if it can be set with the checkout domain.\n   */\n  checkoutDomain?: string;\n  /**\n   * If set to `true`, it skips modifying the deprecated shopify_y and shopify_s cookies.\n   */\n  ignoreDeprecatedCookies?: boolean;\n};\n\n/**\n * Sets the `shopify_y` and `shopify_s` cookies in the browser based on user consent\n * for backward compatibility support.\n *\n * If `fetchTrackingValues` is true, it makes a request to Storefront API\n * to fetch or refresh Shopiy analytics and marketing cookies and tracking values.\n * Generally speaking, this should only be needed if you're not using Hydrogen's\n * built-in analytics components and hooks that already handle this automatically.\n * For example, set it to `true` if you are using `hydrogen-react` only with\n * a different framework and still need to make a same-domain request to\n * Storefront API to set cookies.\n *\n * If `ignoreDeprecatedCookies` is true, it skips setting the deprecated cookies entirely.\n * Useful when you only want to use the newer tracking values and not rely on the deprecated ones.\n *\n * @returns `true` when cookies are set and ready.\n * @publicDocs\n */\nexport function useShopifyCookies(options?: UseShopifyCookiesOptions): boolean {\n  const {\n    hasUserConsent,\n    domain = '',\n    checkoutDomain = '',\n    storefrontAccessToken,\n    fetchTrackingValues,\n    ignoreDeprecatedCookies = false,\n  } = options || {};\n\n  const coreCookiesReady = useCoreShopifyCookies({\n    storefrontAccessToken,\n    fetchTrackingValues,\n    checkoutDomain,\n  });\n\n  useEffect(() => {\n    // Skip setting JS cookies until http-only cookies and server-timing\n    // are ready so that we have values synced in JS and http-only cookies.\n    if (ignoreDeprecatedCookies || !coreCookiesReady) return;\n\n    /**\n     * Setting cookie with domain\n     *\n     * If no domain is provided, the cookie will be set for the current host.\n     * For Shopify, we need to ensure this domain is set with a leading dot.\n     */\n\n    // Use override domain or current host\n    let currentDomain = domain || window.location.host;\n\n    if (checkoutDomain) {\n      const checkoutDomainParts = checkoutDomain.split('.').reverse();\n      const currentDomainParts = currentDomain.split('.').reverse();\n      const sameDomainParts: Array<string> = [];\n      checkoutDomainParts.forEach((part, index) => {\n        if (part === currentDomainParts[index]) {\n          sameDomainParts.push(part);\n        }\n      });\n\n      currentDomain = sameDomainParts.reverse().join('.');\n    }\n\n    // Reset domain if localhost\n    if (/^localhost/.test(currentDomain)) currentDomain = '';\n\n    // Shopify checkout only consumes cookies set with leading dot domain\n    const domainWithLeadingDot = currentDomain\n      ? /^\\./.test(currentDomain)\n        ? currentDomain\n        : `.${currentDomain}`\n      : '';\n\n    /**\n     * Set user and session cookies and refresh the expiry time\n     */\n    if (hasUserConsent) {\n      const trackingValues = getTrackingValues();\n      if (\n        (\n          trackingValues.uniqueToken ||\n          trackingValues.visitToken ||\n          ''\n        ).startsWith('00000000-')\n      ) {\n        // Skip writing cookies when tracking values signal we don't have consent yet\n        return;\n      }\n\n      setCookie(\n        SHOPIFY_Y,\n        trackingValues.uniqueToken || buildUUID(),\n        longTermLength,\n        domainWithLeadingDot,\n      );\n      setCookie(\n        SHOPIFY_S,\n        trackingValues.visitToken || buildUUID(),\n        shortTermLength,\n        domainWithLeadingDot,\n      );\n    } else {\n      setCookie(SHOPIFY_Y, '', 0, domainWithLeadingDot);\n      setCookie(SHOPIFY_S, '', 0, domainWithLeadingDot);\n    }\n  }, [\n    coreCookiesReady,\n    hasUserConsent,\n    domain,\n    checkoutDomain,\n    ignoreDeprecatedCookies,\n  ]);\n\n  return coreCookiesReady;\n}\n\nfunction setCookie(\n  name: string,\n  value: string,\n  maxage: number,\n  domain: string,\n): void {\n  document.cookie = stringify(name, value, {\n    maxage,\n    domain,\n    samesite: 'Lax',\n    path: '/',\n  });\n}\n\nasync function fetchTrackingValuesFromBrowser(\n  storefrontAccessToken?: string,\n  storefrontApiDomain = '',\n): Promise<void> {\n  // These values might come from server-timing or old cookies.\n  // If consent cannot be initially assumed, these tokens\n  // will be dropped in SFAPI and it will return a mock token\n  // starting with '00000000-'.\n  // However, if consent can be assumed initially, these tokens\n  // will be used to create proper cookies and continue our flow.\n  const {uniqueToken, visitToken} = getTrackingValues();\n\n  const response = await fetch(\n    // TODO: update this endpoint when it becomes stable\n    `${storefrontApiDomain.replace(/\\/+$/, '')}/api/unstable/graphql.json`,\n    {\n      method: 'POST',\n      headers: {\n        'Content-Type': 'application/json',\n        ...(storefrontAccessToken && {\n          'X-Shopify-Storefront-Access-Token': storefrontAccessToken,\n        }),\n        ...(visitToken || uniqueToken\n          ? {\n              [SHOPIFY_VISIT_TOKEN_HEADER]: visitToken,\n              [SHOPIFY_UNIQUE_TOKEN_HEADER]: uniqueToken,\n            }\n          : undefined),\n      },\n      body: JSON.stringify({\n        query:\n          // This query ensures we get _cmp (consent) server-timing header, which is not available in other queries.\n          // This value can be passed later to consent-tracking-api and privacy-banner scripts to avoid extra requests.\n          'query ensureCookies { consentManagement { cookies(visitorConsent:{}) { cookieDomain } } }',\n      }),\n    },\n  );\n\n  if (!response.ok) {\n    throw new Error(\n      `Failed to fetch consent from browser: ${response.status} ${response.statusText}`,\n    );\n  }\n\n  // Consume the body to complete the request and\n  // ensure server-timing is available in performance API\n  await response.json();\n\n  // Ensure we cache the latest tracking values from resources timing\n  getTrackingValues();\n}\n\ntype CoreShopifyCookiesOptions = {\n  storefrontAccessToken?: string;\n  fetchTrackingValues?: boolean;\n  checkoutDomain?: string;\n};\n\n/**\n * Gets http-only cookies from Storefront API via same-origin fetch request.\n * Falls back to checkout domain if provided to at least obtain the tracking\n * values via server-timing headers.\n */\nfunction useCoreShopifyCookies({\n  checkoutDomain,\n  storefrontAccessToken,\n  fetchTrackingValues = false,\n}: CoreShopifyCookiesOptions) {\n  const [cookiesReady, setCookiesReady] = useState(!fetchTrackingValues);\n  const hasFetchedTrackingValues = useRef(false);\n\n  useEffect(() => {\n    if (!fetchTrackingValues) {\n      // Backend did the work, or proxy is disabled.\n      setCookiesReady(true);\n      return;\n    }\n\n    // React runs effects twice in dev mode, avoid double fetching\n    if (hasFetchedTrackingValues.current) return;\n    hasFetchedTrackingValues.current = true;\n\n    // Fetch consent from browser via proxy\n    fetchTrackingValuesFromBrowser(storefrontAccessToken)\n      .catch((error) =>\n        checkoutDomain\n          ? // Retry with checkout domain if available to at least\n            // get the server-timing values for tracking.\n            fetchTrackingValuesFromBrowser(\n              storefrontAccessToken,\n              checkoutDomain,\n            )\n          : Promise.reject(error),\n      )\n      .catch((error) => {\n        console.warn(\n          '[h2:warn:useShopifyCookies] Failed to fetch tracking values from browser: ' +\n            (error instanceof Error ? error.message : String(error)),\n        );\n      })\n      .finally(() => {\n        // Proceed even on errors, degraded tracking is better than no app\n        setCookiesReady(true);\n      });\n  }, [checkoutDomain, fetchTrackingValues, storefrontAccessToken]);\n\n  return cookiesReady;\n}\n"],"mappings":";;;;;;AAWA,IAAM,iBAAiB,OAAU,KAAK,MAAM;AAC5C,IAAM,kBAAkB;;;;;;;;;;;;;;;;;;;AAyCxB,SAAgB,kBAAkB,SAA6C;CAC7E,MAAM,EACJ,gBACA,SAAS,IACT,iBAAiB,IACjB,uBACA,qBACA,0BAA0B,UACxB,WAAW,EAAE;CAEjB,MAAM,mBAAmB,sBAAsB;EAC7C;EACA;EACA;EACD,CAAC;AAEF,iBAAgB;AAGd,MAAI,2BAA2B,CAAC,iBAAkB;;;;;;;EAUlD,IAAI,gBAAgB,UAAU,OAAO,SAAS;AAE9C,MAAI,gBAAgB;GAClB,MAAM,sBAAsB,eAAe,MAAM,IAAI,CAAC,SAAS;GAC/D,MAAM,qBAAqB,cAAc,MAAM,IAAI,CAAC,SAAS;GAC7D,MAAM,kBAAiC,EAAE;AACzC,uBAAoB,SAAS,MAAM,UAAU;AAC3C,QAAI,SAAS,mBAAmB,OAC9B,iBAAgB,KAAK,KAAK;KAE5B;AAEF,mBAAgB,gBAAgB,SAAS,CAAC,KAAK,IAAI;;AAIrD,MAAI,aAAa,KAAK,cAAc,CAAE,iBAAgB;EAGtD,MAAM,uBAAuB,gBACzB,MAAM,KAAK,cAAc,GACvB,gBACA,IAAI,kBACN;;;;AAKJ,MAAI,gBAAgB;GAClB,MAAM,iBAAiB,mBAAmB;AAC1C,QAEI,eAAe,eACf,eAAe,cACf,IACA,WAAW,YAAY,CAGzB;AAGF,aACE,WACA,eAAe,eAAe,WAAW,EACzC,gBACA,qBACD;AACD,aACE,WACA,eAAe,cAAc,WAAW,EACxC,iBACA,qBACD;SACI;AACL,aAAU,WAAW,IAAI,GAAG,qBAAqB;AACjD,aAAU,WAAW,IAAI,GAAG,qBAAqB;;IAElD;EACD;EACA;EACA;EACA;EACA;EACD,CAAC;AAEF,QAAO;;AAGT,SAAS,UACP,MACA,OACA,QACA,QACM;AACN,UAAS,SAAS,UAAU,MAAM,OAAO;EACvC;EACA;EACA,UAAU;EACV,MAAM;EACP,CAAC;;AAGJ,eAAe,+BACb,uBACA,sBAAsB,IACP;CAOf,MAAM,EAAC,aAAa,eAAc,mBAAmB;CAErD,MAAM,WAAW,MAAM,MAErB,GAAG,oBAAoB,QAAQ,QAAQ,GAAG,CAAC,6BAC3C;EACE,QAAQ;EACR,SAAS;GACP,gBAAgB;GAChB,GAAI,yBAAyB,EAC3B,qCAAqC,uBACtC;GACD,GAAI,cAAc,cACd;KACG,6BAA6B;KAC7B,8BAA8B;IAChC,GACD,KAAA;GACL;EACD,MAAM,KAAK,UAAU,EACnB,OAGE,6FACH,CAAC;EACH,CACF;AAED,KAAI,CAAC,SAAS,GACZ,OAAM,IAAI,MACR,yCAAyC,SAAS,OAAO,GAAG,SAAS,aACtE;AAKH,OAAM,SAAS,MAAM;AAGrB,oBAAmB;;;;;;;AAcrB,SAAS,sBAAsB,EAC7B,gBACA,uBACA,sBAAsB,SACM;CAC5B,MAAM,CAAC,cAAc,mBAAmB,SAAS,CAAC,oBAAoB;CACtE,MAAM,2BAA2B,OAAO,MAAM;AAE9C,iBAAgB;AACd,MAAI,CAAC,qBAAqB;AAExB,mBAAgB,KAAK;AACrB;;AAIF,MAAI,yBAAyB,QAAS;AACtC,2BAAyB,UAAU;AAGnC,iCAA+B,sBAAsB,CAClD,OAAO,UACN,iBAGI,+BACE,uBACA,eACD,GACD,QAAQ,OAAO,MAAM,CAC1B,CACA,OAAO,UAAU;AAChB,WAAQ,KACN,gFACG,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM,EAC1D;IACD,CACD,cAAc;AAEb,mBAAgB,KAAK;IACrB;IACH;EAAC;EAAgB;EAAqB;EAAsB,CAAC;AAEhE,QAAO"}

package/dist/types/AddToCartButton.d.ts

@@ -22,7 +22,9 @@ export type AddToCartButtonProps<AsType extends React.ElementType = 'button'> =
 /**
  * The `AddToCartButton` component renders a button that adds an item to the cart when pressed.
  * It must be a descendent of the `CartProvider` component.
+ * @publicDocs
  */
 export declare function AddToCartButton<AsType extends React.ElementType = 'button'>(props: AddToCartButtonProps<AsType>): JSX.Element;
+/** @publicDocs */
 export interface AddToCartButtonPropsForDocs<AsType extends React.ElementType = 'button'> extends AddToCartButtonPropsBase, CustomBaseButtonProps<AsType> {
 }

package/dist/types/BuyNowButton.d.ts

@@ -16,8 +16,10 @@ type BuyNowButtonProps<AsType extends React.ElementType = 'button'> = BuyNowButt
 /**
  * The `BuyNowButton` component renders a button that adds an item to the cart and redirects the customer to checkout.
  * Must be a child of a `CartProvider` component.
+ * @publicDocs
  */
 export declare function BuyNowButton<AsType extends React.ElementType = 'button'>(props: BuyNowButtonProps<AsType>): JSX.Element;
+/** @publicDocs */
 export interface BuyNowButtonPropsForDocs<AsType extends React.ElementType = 'button'> extends BuyNowButtonPropsBase, CustomBaseButtonProps<AsType> {
 }
 export {};

package/dist/types/CartCheckoutButton.d.ts

@@ -8,8 +8,10 @@ type CartCheckoutButtonProps = Omit<BaseButtonProps<'button'>, 'onClick'> & Chil
 /**
  * The `CartCheckoutButton` component renders a button that redirects to the checkout URL for the cart.
  * It must be a descendent of a `CartProvider` component.
+ * @publicDocs
  */
 export declare function CartCheckoutButton(props: CartCheckoutButtonProps): JSX.Element;
+/** @publicDocs */
 export interface CartCheckoutButtonPropsForDocs<AsType extends React.ElementType = 'button'> extends Omit<CustomBaseButtonProps<AsType>, 'onClick'> {
 }
 export {};

package/dist/types/CartCost.d.ts

@@ -10,8 +10,10 @@ type CartCostProps = Omit<React.ComponentProps<typeof Money>, 'data'> & CartCost
  * The `CartCost` component renders a `Money` component with the cost associated with the `amountType` prop.
  * If no `amountType` prop is specified, then it defaults to `totalAmount`.
  * Depends on `useCart()` and must be a child of `<CartProvider/>`
+ * @publicDocs
  */
 export declare function CartCost(props: CartCostProps): JSX.Element | null;
+/** @publicDocs */
 export interface CartCostPropsForDocs<AsType extends React.ElementType = 'div'> extends Omit<MoneyPropsBase<AsType>, 'data'>, CartCostPropsBase {
 }
 export {};

package/dist/types/CartLineProvider.d.ts

@@ -7,6 +7,7 @@ type CartLinePartialDeep = PartialDeep<CartLine | ComponentizableCartLine, {
 export declare const CartLineContext: import("react").Context<CartLinePartialDeep | null>;
 /**
  * The `useCartLine` hook provides access to the [CartLine object](https://shopify.dev/api/storefront/2026-04/objects/cartline) from the Storefront API. It must be a descendent of a `CartProvider` component.
+ * @publicDocs
  */
 export declare function useCartLine(): CartLinePartialDeep;
 type CartLineProviderProps = {
@@ -17,6 +18,7 @@ type CartLineProviderProps = {
 };
 /**
  * The `CartLineProvider` component creates a context for using a cart line.
+ * @publicDocs
  */
 export declare function CartLineProvider({ children, line, }: CartLineProviderProps): JSX.Element;
 export {};

package/dist/types/CartLineQuantity.d.ts

@@ -1,4 +1,5 @@
 import type { ComponentPropsWithoutRef, ElementType } from 'react';
+/** @publicDocs */
 interface CartLineQuantityBaseProps<ComponentGeneric extends ElementType = 'span'> {
     /** An HTML tag or React Component to be rendered as the base element wrapper. The default is `span`. */
     as?: ComponentGeneric;
@@ -8,6 +9,7 @@ export type CartLineQuantityProps<ComponentGeneric extends ElementType> = CartLi
  * The `<CartLineQuantity/>` component renders a `span` (or another element / component that can be customized by the `as` prop) with the cart line's quantity.
  *
  * It must be a descendent of a `<CartLineProvider/>` component, and uses the `useCartLine()` hook internally.
+ * @publicDocs
  */
 export declare function CartLineQuantity<ComponentGeneric extends ElementType = 'span'>(props: CartLineQuantityProps<ComponentGeneric>): JSX.Element;
 export {};

package/dist/types/CartLineQuantityAdjustButton.d.ts

@@ -8,6 +8,7 @@ type CartLineQuantityAdjustButtonProps<AsType extends React.ElementType = 'butto
  * The `<CartLineQuantityAdjustButton />` component renders a button that adjusts the cart line's quantity when pressed.
  *
  * It must be a descendent of `<CartLineProvider/>` and `<CartProvider/>`.
+ * @publicDocs
  */
 export declare function CartLineQuantityAdjustButton<AsType extends React.ElementType = 'button'>(props: CartLineQuantityAdjustButtonProps<AsType>): JSX.Element;
 export {};

package/dist/types/CartProvider.d.ts

@@ -1,9 +1,14 @@
 import { CartBuyerIdentityInput, CountryCode, LanguageCode, Cart as CartType } from './storefront-api-types.js';
-import { CartWithActions } from './cart-types.js';
+import { CartWithActions, CartWithActionsDocs } from './cart-types.js';
 import { PartialDeep } from 'type-fest';
 export declare const CartContext: import("react").Context<CartWithActions | null>;
+/**
+ * `useCart` hook must be a descendent of a `CartProvider` component.
+ * @publicDocs */
+export type UseCartDocs = () => CartWithActionsDocs;
 /**
  * The `useCart` hook provides access to the cart object. It must be a descendent of a `CartProvider` component.
+ * @publicDocs
  */
 export declare function useCart(): CartWithActions;
 type CartProviderProps = {
@@ -65,6 +70,7 @@ type CartProviderProps = {
  * There are also props that trigger when a call to the Storefront API is completed, such as `onLineAddComplete={}` when the fetch request for adding a line to the cart completes.
  *
  * The `CartProvider` component must be a descendant of the `ShopifyProvider` component.
+ * @publicDocs
  */
 export declare function CartProvider({ children, numCartLines, onCreate, onLineAdd, onLineRemove, onLineUpdate, onNoteUpdate, onBuyerIdentityUpdate, onAttributesUpdate, onDiscountCodesUpdate, onCreateComplete, onLineAddComplete, onLineRemoveComplete, onLineUpdateComplete, onNoteUpdateComplete, onBuyerIdentityUpdateComplete, onAttributesUpdateComplete, onDiscountCodesUpdateComplete, data: cart, cartFragment, customerAccessToken, countryCode, languageCode, }: CartProviderProps): JSX.Element;
 /**

package/dist/types/ExternalVideo.d.ts

@@ -1,6 +1,9 @@
 import type { ExternalVideo as ExternalVideoType } from './storefront-api-types.js';
 import type { PartialDeep } from 'type-fest';
 import { IframeHTMLAttributes } from 'react';
+/**
+ * Takes in the same props as a native `<iframe>` element, except for `src`.
+ * @publicDocs */
 export interface ExternalVideoBaseProps {
     /**
      * An object with fields that correspond to the Storefront API's [ExternalVideo object](https://shopify.dev/api/storefront/reference/products/externalvideo).
@@ -18,6 +21,7 @@ export type ExternalVideoProps = Omit<IframeHTMLAttributes<HTMLIFrameElement>, '
 /**
  * The `ExternalVideo` component renders an embedded video for the Storefront
  * API's [ExternalVideo object](https://shopify.dev/api/storefront/reference/products/externalvideo).
+ * @publicDocs
  */
 export declare const ExternalVideo: import("react").ForwardRefExoticComponent<Omit<IframeHTMLAttributes<HTMLIFrameElement>, "src"> & ExternalVideoBaseProps & import("react").RefAttributes<HTMLIFrameElement>>;
 interface YouTube {

package/dist/types/Image.d.ts

@@ -23,6 +23,7 @@ export type LoaderParams = {
 };
 export type Loader = (params: LoaderParams) => string;
 type Crop = 'center' | 'top' | 'bottom' | 'left' | 'right';
+/** @publicDocs */
 export type HydrogenImageProps = React.ComponentPropsWithRef<'img'> & HydrogenImageBaseProps;
 type HydrogenImageBaseProps = {
     /** The aspect ratio of the image, in the format of `width/height`.
@@ -117,6 +118,7 @@ export declare const IMAGE_FRAGMENT = "#graphql\n  fragment Image on Image {\n
  * ```
  *
  * {@link https://shopify.dev/docs/api/hydrogen-react/components/image}
+ * @publicDocs
  */
 export declare const Image: React.ForwardRefExoticComponent<Omit<HydrogenImageProps, "ref"> & React.RefAttributes<HTMLImageElement>>;
 export declare function shopifyLoader({ src, width, height, crop }: LoaderParams): string;

package/dist/types/MediaFile.d.ts

@@ -6,6 +6,9 @@ import type { MediaEdge as MediaEdgeType } from './storefront-api-types.js';
 import type { PartialDeep } from 'type-fest';
 import type { ModelViewerElement } from '@google/model-viewer/lib/model-viewer.js';
 type BaseProps = React.HTMLAttributes<HTMLImageElement | HTMLVideoElement | HTMLIFrameElement | ModelViewerElement>;
+/**
+ * MediaFile renders an `Image`, `Video`, `ExternalVideo`, or `ModelViewer` component. Use the `mediaOptions` prop to customize the props sent to each of these components.
+ * @publicDocs */
 export interface MediaFileProps extends BaseProps {
     /** An object with fields that correspond to the Storefront API's [Media object](https://shopify.dev/api/storefront/reference/products/media). */
     data: PartialDeep<MediaEdgeType['node'], {
@@ -28,6 +31,7 @@ type MediaOptions = {
  * The `MediaFile` component renders the media for the Storefront API's
  * [Media object](https://shopify.dev/api/storefront/reference/products/media). It renders an `Image`, a
  * `Video`, an `ExternalVideo`, or a `ModelViewer` depending on the `__typename` of the `data` prop.
+ * @publicDocs
  */
 export declare function MediaFile({ data, mediaOptions, ...passthroughProps }: MediaFileProps): JSX.Element | null;
 export {};

package/dist/types/ModelViewer.d.ts

@@ -52,6 +52,7 @@ type ModelViewerBaseProps = {
  * The `model-viewer` custom element is lazily downloaded through a dynamically-injected `<script type="module">` tag when the `<ModelViewer />` component is rendered
  *
  * ModelViewer is using version `1.21.1` of the `@google/model-viewer` library.
+ * @publicDocs
  */
 export declare function ModelViewer(props: ModelViewerProps): JSX.Element | null;
 export {};

package/dist/types/Money.d.ts

@@ -59,6 +59,7 @@ export type MoneyProps<ComponentGeneric extends React.ElementType> = MoneyPropsB
  *   measurementSeparator=" per "
  * />
  * ```
+ * @publicDocs
  */
 export declare function Money<ComponentGeneric extends React.ElementType = 'div'>({ data, as, withoutCurrency, withoutTrailingZeros, measurement, measurementSeparator, ...passthroughProps }: MoneyProps<ComponentGeneric>): JSX.Element;
 export {};

package/dist/types/ProductPrice.d.ts

@@ -16,7 +16,9 @@ export interface ProductPriceProps {
 /**
  * The `ProductPrice` component renders a `Money` component with the product
  * [`priceRange`](https://shopify.dev/api/storefront/reference/products/productpricerange)'s `maxVariantPrice` or `minVariantPrice`, for either the regular price or compare at price range.
+ * @publicDocs
  */
 export declare function ProductPrice<ComponentGeneric extends React.ElementType = 'div'>(props: ProductPriceProps & Omit<MoneyProps<ComponentGeneric>, 'data' | 'measurement'>): JSX.Element | null;
+/** @publicDocs */
 export interface ProductPricePropsForDocs<AsType extends React.ElementType = 'div'> extends Omit<MoneyPropsBase<AsType>, 'data' | 'measurement'>, ProductPriceProps {
 }

package/dist/types/ProductProvider.d.ts

@@ -22,10 +22,12 @@ interface ProductProviderProps {
  * `<ProductProvider />` is a context provider that enables use of the `useProduct()` hook.
  *
  * It helps manage selected options and variants for a product.
+ * @publicDocs
  */
 export declare function ProductProvider({ children, data: product, initialVariantId: explicitVariantId, }: ProductProviderProps): JSX.Element;
 /**
  * Provides access to the context value provided by `<ProductProvider />`. Must be a descendent of `<ProductProvider />`.
+ * @publicDocs
  */
 export declare function useProduct(): ProductHookValue;
 export interface OptionWithValues {

package/dist/types/RichText.d.ts

@@ -9,6 +9,8 @@ export interface RichTextPropsBase<ComponentGeneric extends React.ElementType> {
     /** Remove rich text formatting and render plain text */
     plain?: boolean;
 }
+/** @publicDocs */
 export declare function RichText<ComponentGeneric extends React.ElementType = 'div'>({ as, data, plain, components, ...passthroughProps }: RichTextProps<ComponentGeneric>): JSX.Element;
 export type RichTextProps<ComponentGeneric extends React.ElementType> = RichTextPropsBase<ComponentGeneric> & Omit<React.ComponentPropsWithoutRef<ComponentGeneric>, keyof RichTextPropsBase<ComponentGeneric>>;
+/** @publicDocs */
 export type RichTextPropsForDocs<AsType extends React.ElementType = 'div'> = RichTextPropsBase<AsType>;

package/dist/types/ShopPayButton.d.ts

@@ -43,6 +43,7 @@ declare global {
  * The `ShopPayButton` component renders a button that redirects to the Shop Pay checkout.
  * It renders a [`<shop-pay-button>`](https://shopify.dev/custom-storefronts/tools/web-components) custom element, for which it will lazy-load the source code automatically.
  * It relies on the `<ShopProvider>` context provider.
+ * @publicDocs
  */
 export declare function ShopPayButton({ channel, variantIds, className, variantIdsAndQuantities, width, storeDomain: _storeDomain, }: ShopPayButtonProps): JSX.Element;
 export declare const MissingStoreDomainErrorMessage = "You must pass a \"storeDomain\" prop to the \"ShopPayButton\" component, or wrap it in a \"ShopifyProvider\" component.";

package/dist/types/ShopifyProvider.d.ts

@@ -3,10 +3,12 @@ import type { LanguageCode, CountryCode } from './storefront-api-types.js';
 export declare const defaultShopifyContext: ShopifyContextValue;
 /**
  * The `<ShopifyProvider/>` component enables use of the `useShop()` hook. The component should wrap your app.
+ * @publicDocs
  */
 export declare function ShopifyProvider({ children, ...shopifyConfig }: ShopifyProviderProps): JSX.Element;
 /**
  * Provides access to the `shopifyConfig` prop of `<ShopifyProvider/>`. Must be a descendent of `<ShopifyProvider/>`.
+ * @publicDocs
  */
 export declare function useShop(): ShopifyContextValue;
 export interface ShopifyProviderBase {

package/dist/types/Video.d.ts

@@ -2,6 +2,7 @@ import { type HTMLAttributes } from 'react';
 import { shopifyLoader } from './Image.js';
 import type { Video as VideoType } from './storefront-api-types.js';
 import type { PartialDeep } from 'type-fest';
+/** @publicDocs */
 export interface VideoProps {
     /** An object with fields that correspond to the Storefront API's [Video object](https://shopify.dev/api/storefront/2026-04/objects/video). */
     data: PartialDeep<VideoType, {
@@ -16,5 +17,6 @@ export interface VideoProps {
 }
 /**
  * The `Video` component renders a `video` for the Storefront API's [Video object](https://shopify.dev/api/storefront/reference/products/video).
+ * @publicDocs
  */
 export declare const Video: import("react").ForwardRefExoticComponent<Omit<import("react").ClassAttributes<HTMLVideoElement> & import("react").VideoHTMLAttributes<HTMLVideoElement> & VideoProps, "ref"> & import("react").RefAttributes<HTMLVideoElement>>;

package/dist/types/analytics-constants.d.ts

@@ -16,12 +16,18 @@ export declare const ShopifyAppId: {
  * These duplicated interface declaration is so that we can generate proper documentation
  * for these public facing constants
  */
+/**
+ * Analytics event names accepted by Shopify analytics.
+ * @publicDocs */
 export interface AnalyticsEventName {
     /** Page view */
     PAGE_VIEW: 'PAGE_VIEW';
     /** Add to cart */
     ADD_TO_CART: 'ADD_TO_CART';
 }
+/**
+ * Analytics page type values accepted by Shopify analytics.
+ * @publicDocs */
 export interface AnalyticsPageType {
     article: 'article';
     blog: 'blog';
@@ -46,6 +52,9 @@ export interface AnalyticsPageType {
     policy: 'policy';
     search: 'search';
 }
+/**
+ * Analytics sales channel values accepted by Shopify analytics.
+ * @publicDocs */
 export interface ShopifySalesChannel {
     /** Shopify Hydrogen sales channel */
     hydrogen: 'hydrogen';

package/dist/types/analytics-types.d.ts

@@ -180,6 +180,7 @@ export type ShopifyAnalyticsPayload = ShopifyPageViewPayload | ShopifyAddToCartP
  */
 export type ShopifyAnalyticsPayloadWithPrivacyFields = ShopifyPageViewPayloadWithPrivacyFields | ShopifyAddToCartPayloadWithPrivacyFields;
 export type ShopifyAnalytics = ShopifyPageView | ShopifyAddToCart;
+/** Shopify cookies names */
 export type ShopifyCookies = {
     /** Shopify unique user token: Value of `_shopify_y` cookie. */
     [SHOPIFY_Y]: string;

package/dist/types/analytics-utils.d.ts

@@ -19,6 +19,7 @@ export declare function schemaWrapper(schemaId: string, payload: ShopifyMonorail
  *  * const {id, resource} = parseGid('gid://shopify/Cart/abc123')
  * // => id = "abc123", resource = 'Cart'
  * ```
+ * @publicDocs
  **/
 export declare function parseGid(gid: string | undefined): ShopifyGid;
 /**

package/dist/types/analytics.d.ts

@@ -1,9 +1,14 @@
 import type { ClientBrowserParameters, ShopifyAnalytics } from './analytics-types.js';
 /**
- * Set user and session cookies and refresh the expiry time
+ * Set user and session cookies and refresh the expiry time. If `event.payload.hasUserConsent` is false, no analytics event will happen.
  * @param event - The analytics event.
  * @param shopDomain - The Online Store domain to sent Shopify analytics under the same
  *   top level domain.
+ * @publicDocs
  */
 export declare function sendShopifyAnalytics(event: ShopifyAnalytics, shopDomain?: string): Promise<void>;
+/**
+ * If executed on server, this method will return empty string for each field.
+ * @publicDocs
+ */
 export declare function getClientBrowserParameters(): ClientBrowserParameters;

package/dist/types/cart-queries.d.ts

@@ -1,10 +1,14 @@
-export declare const CartLineAdd: (cartFragment: string) => string;
-export declare const CartCreate: (cartFragment: string) => string;
-export declare const CartLineRemove: (cartFragment: string) => string;
-export declare const CartLineUpdate: (cartFragment: string) => string;
-export declare const CartNoteUpdate: (cartFragment: string) => string;
-export declare const CartBuyerIdentityUpdate: (cartFragment: string) => string;
-export declare const CartAttributesUpdate: (cartFragment: string) => string;
-export declare const CartDiscountCodesUpdate: (cartFragment: string) => string;
-export declare const CartQuery: (cartFragment: string) => string;
+type CartQueryOptions = {
+    includeVisitorConsent?: boolean;
+};
+export declare const CartLineAdd: (cartFragment: string, options?: CartQueryOptions) => string;
+export declare const CartCreate: (cartFragment: string, options?: CartQueryOptions) => string;
+export declare const CartLineRemove: (cartFragment: string, options?: CartQueryOptions) => string;
+export declare const CartLineUpdate: (cartFragment: string, options?: CartQueryOptions) => string;
+export declare const CartNoteUpdate: (cartFragment: string, options?: CartQueryOptions) => string;
+export declare const CartBuyerIdentityUpdate: (cartFragment: string, options?: CartQueryOptions) => string;
+export declare const CartAttributesUpdate: (cartFragment: string, options?: CartQueryOptions) => string;
+export declare const CartDiscountCodesUpdate: (cartFragment: string, options?: CartQueryOptions) => string;
+export declare const CartQuery: (cartFragment: string, options?: CartQueryOptions) => string;
 export declare const defaultCartFragment = "\n  fragment CartFragment on Cart {\n    id\n    checkoutUrl\n    totalQuantity\n    buyerIdentity {\n      countryCode\n      customer {\n        id\n        email\n        firstName\n        lastName\n        displayName\n      }\n      email\n      phone\n    }\n    lines(first: $numCartLines) {\n      edges {\n        node {\n          id\n          quantity\n          attributes {\n            key\n            value\n          }\n          cost {\n            totalAmount {\n              amount\n              currencyCode\n            }\n            compareAtAmountPerQuantity {\n              amount\n              currencyCode\n            }\n          }\n          merchandise {\n            ... on ProductVariant {\n              id\n              availableForSale\n              compareAtPrice {\n                ...MoneyFragment\n              }\n              price {\n                ...MoneyFragment\n              }\n              requiresShipping\n              title\n              image {\n                ...ImageFragment\n              }\n              product {\n                handle\n                title\n                id\n              }\n              selectedOptions {\n                name\n                value\n              }\n            }\n          }\n        }\n      }\n    }\n    cost {\n      subtotalAmount {\n        ...MoneyFragment\n      }\n      totalAmount {\n        ...MoneyFragment\n      }\n      totalDutyAmount {\n        ...MoneyFragment\n      }\n      totalTaxAmount {\n        ...MoneyFragment\n      }\n    }\n    note\n    attributes {\n      key\n      value\n    }\n    discountCodes {\n      code\n      applicable\n    }\n  }\n\n  fragment MoneyFragment on MoneyV2 {\n    currencyCode\n    amount\n  }\n  fragment ImageFragment on Image {\n    id\n    url\n    altText\n    width\n    height\n  }\n";
+export {};

package/dist/types/codegen.helpers.d.ts

@@ -2,6 +2,7 @@
  * Meant to be used with GraphQL CodeGen to type the Storefront API's custom scalars correctly.
  * Reference for the GraphQL types: https://shopify.dev/docs/api/storefront/2026-04/scalars/HTML
  * Note: JSON is generated as 'unknown' by default.
+ * @publicDocs
  */
 export declare const storefrontApiCustomScalars: {
     DateTime: string;
@@ -15,6 +16,7 @@ export declare const storefrontApiCustomScalars: {
  * Meant to be used with GraphQL CodeGen to type the Storefront API's custom scalars correctly.
  * Reference for the GraphQL types: https://shopify.dev/docs/api/customer/2026-04/scalars/HTML
  * Note: JSON is generated as 'unknown' by default.
+ * @publicDocs
  */
 export declare const customerAccountApiCustomScalars: {
     DateTime: string;

package/dist/types/cookies-utils.d.ts

@@ -2,7 +2,8 @@ import { ShopifyCookies } from './analytics-types.js';
 export declare function buildUUID(): string;
 export declare function hexTime(): string;
 /**
- * Gets the values of _shopify_y and _shopify_s cookies from the provided cookie string.
+ * Gets the values of _shopify_y and _shopify_s cookies from the provided cookie string. If the Shopify cookies doesn't exist, this method will return an empty string for each missing cookie.
  * @deprecated Use getTrackingValues instead.
+ * @publicDocs
  */
 export declare function getShopifyCookies(cookies: string): ShopifyCookies;

package/dist/types/flatten-connection.d.ts

@@ -4,6 +4,7 @@ import type { PartialDeep } from 'type-fest';
  * The utility works with either `nodes` or `edges.node`.
  *
  * If `connection` is null or undefined, will return an empty array instead in production. In development, an error will be thrown.
+ * @publicDocs
  */
 export declare function flattenConnection<ConnectionGeneric extends PartialDeep<ConnectionEdges, {
     recurseIntoArrays: true;
@@ -36,8 +37,10 @@ type ConnectionEdges = {
 type ConnectionNodes = {
     nodes: Array<unknown>;
 };
+/** @publicDocs */
 export interface ConnectionGenericForDoc {
     connection?: ConnectionEdges | ConnectionNodes;
 }
+/** @publicDocs */
 export type FlattenConnectionReturnForDoc = unknown[];
 export {};

package/dist/types/getProductOptions.d.ts

@@ -30,6 +30,7 @@ type MappedProductOptionValue = ProductOptionValue & ProductOptionValueState;
  *    Color: 'Red',
  *    Size: 'Medium',
  *  \}
+ * @publicDocs
  */
 export declare function mapSelectedProductOptionToObject(options: Pick<SelectedOption, 'name' | 'value'>[]): Record<string, string>;
 export type MappedProductOptions = Omit<ProductOption, 'optionValues'> & {
@@ -39,11 +40,13 @@ export declare function checkProductParam(product: RecursivePartial<Product>, ch
 /**
  * Finds all the variants provided by adjacentVariants, options.optionValues.firstAvailableVariant,
  * and selectedOrFirstAvailableVariant and return them in a single array
+ * @publicDocs
  */
 export declare function getAdjacentAndFirstAvailableVariants(product: RecursivePartial<Product>): ProductVariant[];
 /**
  * Returns a product options array with its relevant information
  * about the variant
+ * @publicDocs
  */
 export declare function getProductOptions(product: RecursivePartial<Product>): MappedProductOptions[];
 export {};

package/dist/types/load-script.d.ts

@@ -4,9 +4,11 @@ type LoadScriptOptions = {
     attributes?: Record<string, string>;
 };
 export declare function loadScript(src: string, options?: LoadScriptOptions): Promise<boolean>;
-type LoadScriptParams = Parameters<typeof loadScript>;
+/** @publicDocs */
+export type LoadScriptParams = Parameters<typeof loadScript>;
 /**
  * The `useLoadScript` hook loads an external script tag in the browser. It allows React components to lazy-load large third-party dependencies.
+ * @publicDocs
  */
 export declare function useLoadScript(url: LoadScriptParams[0], options?: LoadScriptParams[1]): ScriptState;
 type ScriptState = 'loading' | 'done' | 'error';

package/dist/types/optionValueDecoder.d.ts

@@ -9,6 +9,7 @@
  *  - `-` indicates a continuous range of option values. ex: `0 1-3 4`. Ranges are only present encoded in the final option value position, so for example the trie for the set [[0,0,0],[0,0,1], ..., [0,2,2]] will be structured as `0:0:0-2,1:0-2,2:0-2`, not `0:0-2:0-2`.
  */
 import { Product } from './storefront-api-types.js';
+/** @publicDocs */
 export type IsOptionValueCombinationInEncodedVariant = (targetOptionValueCombination: number[], encodedVariantField: string) => boolean;
 /**
  * Determine whether an option value combination is present in an encoded option value string. Function is memoized by encodedVariantField.
@@ -16,6 +17,7 @@ export type IsOptionValueCombinationInEncodedVariant = (targetOptionValueCombina
  * @param targetOptionValueCombination - Indices of option values to look up in the encoded option value string. A partial set of indices may be passed to determine whether a node or any children is present. For example, if a product has 3 options, passing [0] will return true if any option value combination for the first option's option value is present in the encoded string.
  * @param encodedVariantField - Encoded option value string from the Storefront API, e.g. [product.encodedVariantExistence](/docs/api/storefront/2026-04/objects/Product#field-encodedvariantexistence) or [product.encodedVariantAvailability](/docs/api/storefront/2026-04/objects/Product#field-encodedvariantavailability)
  * @returns - True if a full or partial targetOptionValueIndices is present in the encoded option value string, false otherwise.
+ * @publicDocs
  */
 export declare const isOptionValueCombinationInEncodedVariant: IsOptionValueCombinationInEncodedVariant;
 type EncodedVariantField = Product['encodedVariantAvailability'] | Product['encodedVariantExistence'];
@@ -24,6 +26,7 @@ type DecodedOptionValues = number[][];
  * For an encoded option value string, decode into option value combinations. Entries represent a valid combination formatted as an array of option value positions.
  * @param encodedVariantField - Encoded option value string from the Storefront API, e.g. [product.encodedVariantExistence](/docs/api/storefront/2026-04/objects/Product#field-encodedvariantexistence) or [product.encodedVariantAvailability](/docs/api/storefront/2026-04/objects/Product#field-encodedvariantavailability)
  * @returns Decoded option value combinations
+ * @publicDocs
  */
 export declare function decodeEncodedVariant(encodedVariantField: EncodedVariantField): DecodedOptionValues;
 export {};

package/dist/types/parse-metafield.d.ts

@@ -9,6 +9,7 @@ import { RootASTNode as RichTextRootASTNode } from './RichText.types.js';
  * ```
  * parseMetafield<ParsedMetafields['boolean']>({type: 'boolean', value: 'false'}
  * ```
+ * @publicDocs
  */
 export declare function parseMetafield<ReturnGeneric>(metafield: PartialDeep<MetafieldBaseType, {
     recurseIntoArrays: true;

package/dist/types/storefront-client.d.ts

@@ -18,6 +18,7 @@ export type StorefrontClientProps = {
  * The `createStorefrontClient()` function creates helpers that enable you to quickly query the Shopify Storefront API.
  *
  * When used on the server, it is recommended to use the `privateStorefrontToken` prop. When used on the client, it is recommended to use the `publicStorefrontToken` prop.
+ * @publicDocs
  */
 export declare function createStorefrontClient({ storeDomain, privateStorefrontToken, publicStorefrontToken, storefrontApiVersion, contentType, }: StorefrontClientProps): StorefrontClientReturn;
 export declare function getPublicTokenHeadersRaw(contentType: 'graphql' | 'json', storefrontApiVersion: string, accessToken: string): {

package/dist/types/tracking-utils.d.ts

@@ -14,8 +14,8 @@ export declare const cachedTrackingValues: {
     current: null | TrackingValues;
 };
 /**
- * Retrieves user session tracking values for analytics
- * and marketing from the browser environment.
+ * Retrieves user session tracking values for analytics and marketing from the browser environment.
+ * @publicDocs
  */
 export declare function getTrackingValues(): TrackingValues;
 export {};

package/dist/types/useMoney.d.ts

@@ -109,6 +109,7 @@ export type UseMoneyValue = {
  * ```ts
  * money.withoutTrailingZerosAndCurrency
  * ```
+ * @publicDocs
  */
 export declare function useMoney(money: MoneyV2): UseMoneyValue;
 export {};

package/dist/types/useSelectedOptionInUrlParam.d.ts

@@ -1,2 +1,3 @@
 import { SelectedOption } from './storefront-api-types.js';
+/** @publicDocs */
 export declare function useSelectedOptionInUrlParam(selectedOptions: Pick<SelectedOption, 'name' | 'value'>[]): null;

package/dist/types/useShopifyCookies.d.ts

@@ -34,6 +34,7 @@ type UseShopifyCookiesOptions = CoreShopifyCookiesOptions & {
  * Useful when you only want to use the newer tracking values and not rely on the deprecated ones.
  *
  * @returns `true` when cookies are set and ready.
+ * @publicDocs
  */
 export declare function useShopifyCookies(options?: UseShopifyCookiesOptions): boolean;
 type CoreShopifyCookiesOptions = {