@shopify/shop-minis-react 0.17.2 → 0.19.0

package/generated-hook-maps/hook-actions-map.json

@@ -15,6 +15,9 @@
   "useCheckPermissions": [
     "CHECK_PERMISSION"
   ],
+  "useCheckScopesConsent": [
+    "CHECK_SCOPES_CONSENT"
+  ],
   "useCloseMini": [
     "CLOSE_MINI"
   ],
@@ -104,6 +107,9 @@
   "useRequestPermissions": [
     "REQUEST_PERMISSION"
   ],
+  "useRequestScopesConsent": [
+    "REQUEST_SCOPES_CONSENT"
+  ],
   "useSavedProducts": [
     "GET_SAVED_PRODUCTS"
   ],

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shopify/shop-minis-react",
   "license": "SEE LICENSE IN LICENSE.txt",
-  "version": "0.17.2",
+  "version": "0.19.0",
   "sideEffects": false,
   "type": "module",
   "engines": {
@@ -63,7 +63,7 @@
     "typescript": ">=5.0.0"
   },
   "dependencies": {
-    "@shopify/shop-minis-platform": "0.15.1",
+    "@shopify/shop-minis-platform": "0.17.0",
     "@tailwindcss/vite": "4.1.8",
     "@tanstack/react-query": "5.86.0",
     "@types/lodash": "4.17.20",

package/src/components/commerce/add-to-cart.test.tsx

@@ -51,6 +51,7 @@ describe('AddToCartButton', () => {
         id: 'gid://shopify/ProductVariant/456',
         title: 'Default',
         isFavorited: false,
+        availableForSale: true,
         price: {
           amount: '10.00',
           currencyCode: 'USD',
@@ -231,6 +232,7 @@ describe('AddToCartButton', () => {
           id: 'gid://shopify/ProductVariant/999',
           title: 'Different',
           isFavorited: false,
+          availableForSale: true,
           price: {
             amount: '15.00',
             currencyCode: 'USD',
@@ -285,4 +287,112 @@ describe('AddToCartButton', () => {
       variantImageUrl: 'https://example.com/variant-image.jpg',
     })
   })
+
+  describe('sold-out state', () => {
+    const soldOutProduct: Product = {
+      ...mockProduct,
+      variants: [
+        {
+          id: 'gid://shopify/ProductVariant/456',
+          title: 'Default',
+          isFavorited: false,
+          availableForSale: false,
+          price: {
+            amount: '10.00',
+            currencyCode: 'USD',
+          },
+        },
+      ],
+    }
+
+    it('shows "Sold out" text when matching variant is not available for sale', () => {
+      render(
+        <AddToCartButton
+          product={soldOutProduct}
+          productVariantId="gid://shopify/ProductVariant/456"
+        />
+      )
+
+      expect(screen.getByText('Sold out')).toBeInTheDocument()
+      expect(screen.queryByText('Add to cart')).not.toBeInTheDocument()
+    })
+
+    it('disables the button when matching variant is sold out', () => {
+      render(
+        <AddToCartButton
+          product={soldOutProduct}
+          productVariantId="gid://shopify/ProductVariant/456"
+        />
+      )
+
+      expect(screen.getByRole('button')).toBeDisabled()
+    })
+
+    it('does not call addToCart when matching variant is sold out', async () => {
+      const user = userEvent.setup()
+
+      render(
+        <AddToCartButton
+          product={soldOutProduct}
+          productVariantId="gid://shopify/ProductVariant/456"
+        />
+      )
+
+      const button = screen.getByRole('button')
+      await user.click(button)
+
+      expect(mockMinisSDK.addToCart).not.toHaveBeenCalled()
+    })
+
+    it('referral products show "View product" and stay clickable even when sold out', async () => {
+      const user = userEvent.setup()
+      const referralSoldOutProduct: Product = {
+        ...soldOutProduct,
+        referral: true,
+      }
+
+      render(
+        <AddToCartButton
+          product={referralSoldOutProduct}
+          productVariantId="gid://shopify/ProductVariant/456"
+        />
+      )
+
+      expect(screen.getByText('View product')).toBeInTheDocument()
+      expect(screen.queryByText('Sold out')).not.toBeInTheDocument()
+
+      const button = screen.getByRole('button')
+      expect(button).toBeEnabled()
+
+      await user.click(button)
+      expect(mockMinisSDK.navigateToProduct).toHaveBeenCalledWith({
+        productId: referralSoldOutProduct.id,
+      })
+      expect(mockMinisSDK.addToCart).not.toHaveBeenCalled()
+    })
+
+    it('falls back to selectedVariant when variants array is missing', () => {
+      const productWithSelectedVariant: Product = {
+        ...mockProduct,
+        variants: undefined,
+        selectedVariant: {
+          id: 'gid://shopify/ProductVariant/456',
+          title: 'Default',
+          isFavorited: false,
+          availableForSale: false,
+          price: {amount: '10.00', currencyCode: 'USD'},
+        },
+      }
+
+      render(
+        <AddToCartButton
+          product={productWithSelectedVariant}
+          productVariantId="gid://shopify/ProductVariant/456"
+        />
+      )
+
+      expect(screen.getByText('Sold out')).toBeInTheDocument()
+      expect(screen.getByRole('button')).toBeDisabled()
+    })
+  })
 })

package/src/components/commerce/add-to-cart.tsx

@@ -41,16 +41,23 @@ export function AddToCartButton({
   const {navigateToProduct} = useShopNavigation()
   const [isAdded, setIsAdded] = useState(false)
   const timeoutRef = React.useRef<number | undefined>(undefined)
-  const {id, referral, variants} = product ?? {}
-
-  const variantImageUrl = variants?.find(
-    variant => variant.id === productVariantId
-  )?.image?.url
+  const {id, referral, variants, selectedVariant} = product ?? {}
+
+  // Look up the matching variant from `variants` first (productLists/savedProducts
+  // path); otherwise fall back to `selectedVariant` (useProduct/useProducts marketplace path).
+  const matchingVariant =
+    variants?.find(variant => variant.id === productVariantId) ??
+    (selectedVariant?.id === productVariantId ? selectedVariant : undefined)
+  const variantImageUrl = matchingVariant?.image?.url
+  const isSoldOut = matchingVariant?.availableForSale === false
+  // Referral products only navigate to the PDP — never gate them on stock so a
+  // sold-out selected variant doesn't strand the user without a way to switch.
+  const isDisabled = disabled || (!referral && isSoldOut)
 
   const {showErrorToast} = useErrorToast()
 
   const handleClick = useCallback(async () => {
-    if (disabled) return
+    if (isDisabled) return
 
     if (id && referral) {
       navigateToProduct({
@@ -95,7 +102,7 @@ export function AddToCartButton({
       console.error('Failed to add to cart:', error)
     }
   }, [
-    disabled,
+    isDisabled,
     id,
     referral,
     isAdded,
@@ -116,13 +123,18 @@ export function AddToCartButton({
     }
   }, [])
 
-  const addToCartText = isAdded ? 'Added to cart' : 'Add to cart'
-  const buttonText = referral ? 'View product' : addToCartText
+  const getButtonText = () => {
+    if (referral) return 'View product'
+    if (isSoldOut) return 'Sold out'
+    if (isAdded) return 'Added to cart'
+    return 'Add to cart'
+  }
+  const buttonText = getButtonText()
 
   return (
     <Button
       onClick={handleClick}
-      disabled={disabled}
+      disabled={isDisabled}
       className={cn(
         'relative overflow-hidden transition-all duration-300',
         className
@@ -131,7 +143,7 @@ export function AddToCartButton({
     >
       <div className="relative flex items-center justify-center">
         <AnimatePresence>
-          {isAdded && (
+          {isAdded && !isSoldOut && (
             <motion.div
               initial={{scale: 0, rotate: -180}}
               animate={{scale: 1, rotate: 0}}
@@ -147,7 +159,12 @@ export function AddToCartButton({
             </motion.div>
           )}
         </AnimatePresence>
-        <span className={cn(isAdded && 'pl-5', 'transition-all duration-300')}>
+        <span
+          className={cn(
+            isAdded && !isSoldOut && 'pl-5',
+            'transition-all duration-300'
+          )}
+        >
           {buttonText}
         </span>
       </div>

package/src/components/commerce/buy-now.test.tsx

@@ -269,4 +269,113 @@ describe('BuyNowButton', () => {
       discountCode: undefined,
     })
   })
+
+  describe('sold-out state', () => {
+    const soldOutProduct: Product = {
+      ...mockProduct,
+      variants: [
+        {
+          id: 'gid://shopify/ProductVariant/456',
+          title: 'Default',
+          isFavorited: false,
+          availableForSale: false,
+          price: {
+            amount: '10.00',
+            currencyCode: 'USD',
+          },
+        },
+      ],
+    }
+
+    it('shows "Sold out" text when matching variant is not available for sale', () => {
+      render(
+        <BuyNowButton
+          product={soldOutProduct}
+          productVariantId="gid://shopify/ProductVariant/456"
+        />
+      )
+
+      expect(screen.getByText('Sold out')).toBeInTheDocument()
+      expect(screen.queryByText('Buy now')).not.toBeInTheDocument()
+    })
+
+    it('referral products show "View product" and stay clickable even when sold out', async () => {
+      const user = userEvent.setup()
+      const referralSoldOutProduct: Product = {
+        ...soldOutProduct,
+        referral: true,
+      }
+
+      render(
+        <BuyNowButton
+          product={referralSoldOutProduct}
+          productVariantId="gid://shopify/ProductVariant/456"
+        />
+      )
+
+      expect(screen.getByText('View product')).toBeInTheDocument()
+      expect(screen.queryByText('Sold out')).not.toBeInTheDocument()
+
+      const button = screen.getByRole('button')
+      expect(button).toBeEnabled()
+
+      await user.click(button)
+      expect(mockMinisSDK.navigateToProduct).toHaveBeenCalledWith({
+        productId: referralSoldOutProduct.id,
+      })
+      expect(mockMinisSDK.buyProduct).not.toHaveBeenCalled()
+    })
+
+    it('falls back to selectedVariant when variants array is missing', () => {
+      const productWithSelectedVariant: Product = {
+        ...mockProduct,
+        variants: undefined,
+        selectedVariant: {
+          id: 'gid://shopify/ProductVariant/456',
+          title: 'Default',
+          isFavorited: false,
+          availableForSale: false,
+          price: {amount: '10.00', currencyCode: 'USD'},
+        },
+      }
+
+      render(
+        <BuyNowButton
+          product={productWithSelectedVariant}
+          productVariantId="gid://shopify/ProductVariant/456"
+        />
+      )
+
+      expect(screen.getByText('Sold out')).toBeInTheDocument()
+      expect(screen.getByRole('button')).toBeDisabled()
+    })
+
+    it('disables the button when matching variant is sold out', () => {
+      render(
+        <BuyNowButton
+          product={soldOutProduct}
+          productVariantId="gid://shopify/ProductVariant/456"
+        />
+      )
+
+      expect(screen.getByRole('button')).toBeDisabled()
+    })
+
+    it('does not call buyProduct when matching variant is sold out', async () => {
+      const user = userEvent.setup()
+
+      render(
+        <BuyNowButton
+          product={soldOutProduct}
+          productVariantId="gid://shopify/ProductVariant/456"
+        />
+      )
+
+      const button = screen.getByRole('button')
+      await user.click(button)
+
+      expect(mockMinisSDK.buyProduct).not.toHaveBeenCalled()
+      expect(mockMinisSDK.navigateToProduct).not.toHaveBeenCalled()
+    })
+  })
 })

package/src/components/commerce/buy-now.tsx

@@ -38,12 +38,22 @@ export function BuyNowButton({
   const {buyProduct} = useShopCartActions()
   const {navigateToProduct} = useShopNavigation()
   const [isPurchasing, setIsPurchasing] = useState(false)
-  const {id, referral} = product ?? {}
+  const {id, referral, variants, selectedVariant} = product ?? {}
+
+  // Look up the matching variant from `variants` first (productLists/savedProducts
+  // path); otherwise fall back to `selectedVariant` (useProduct/useProducts marketplace path).
+  const matchingVariant =
+    variants?.find(variant => variant.id === productVariantId) ??
+    (selectedVariant?.id === productVariantId ? selectedVariant : undefined)
+  const isSoldOut = matchingVariant?.availableForSale === false
+  // Referral products only navigate to the PDP — never gate them on stock so a
+  // sold-out selected variant doesn't strand the user without a way to switch.
+  const isDisabled = disabled || isPurchasing || (!referral && isSoldOut)
 
   const {showErrorToast} = useErrorToast()
 
   const handleClick = useCallback(async () => {
-    if (disabled) return
+    if (isDisabled) return
 
     if (id && referral) {
       navigateToProduct({
@@ -53,8 +63,6 @@ export function BuyNowButton({
       return
     }
 
-    if (isPurchasing) return
-
     try {
       if (id && productVariantId) {
         setIsPurchasing(true)
@@ -73,10 +81,9 @@ export function BuyNowButton({
       setIsPurchasing(false)
     }
   }, [
-    disabled,
+    isDisabled,
     id,
     referral,
-    isPurchasing,
     navigateToProduct,
     productVariantId,
     buyProduct,
@@ -84,10 +91,17 @@ export function BuyNowButton({
     showErrorToast,
   ])
 
+  const getButtonText = () => {
+    if (referral) return 'View product'
+    if (isSoldOut) return 'Sold out'
+    return 'Buy now'
+  }
+  const buttonText = getButtonText()
+
   return (
     <Button
       onClick={handleClick}
-      disabled={disabled || isPurchasing}
+      disabled={isDisabled}
       className={cn('relative overflow-hidden', className)}
       size={size}
       aria-live="polite"
@@ -101,7 +115,7 @@ export function BuyNowButton({
           exit={{opacity: 0, y: -10}}
           transition={{duration: 0.2}}
         >
-          {referral ? 'View product' : 'Buy now'}
+          {buttonText}
         </motion.span>
       </AnimatePresence>
     </Button>

package/src/components/commerce/product-link.test.tsx

@@ -297,6 +297,7 @@ describe('ProductLink', () => {
           id: 'selected-variant-id',
           title: 'Selected Variant',
           isFavorited: false,
+          availableForSale: true,
           price: {amount: '29.99', currencyCode: 'USD'},
           compareAtPrice: null,
           image: null,

package/src/hooks/index.ts

@@ -51,6 +51,8 @@ export * from './util/useImagePicker'
 export * from './util/useKeyboardAvoidingView'
 export * from './util/useRequestPermissions'
 export * from './util/useCheckPermissions'
+export * from './util/useCheckScopesConsent'
+export * from './util/useRequestScopesConsent'
 
 // - Intent Hooks
 export * from './intents/useIntent'

package/src/hooks/util/useCheckScopesConsent.ts

@@ -0,0 +1,61 @@
+import {CheckScopesConsentResponse} from '@shopify/shop-minis-platform/actions'
+
+import {useShopActionQuery} from '../../internal/reactQuery'
+import {useShopActions} from '../../internal/useShopActions'
+
+export interface UseCheckScopesConsentReturns {
+  /**
+   * Required scopes declared by the mini, fetched fresh from the API.
+   */
+  requiredScopes: string[] | undefined
+  /**
+   * Scopes already granted by the user.
+   */
+  grantedScopes: string[] | undefined
+  /**
+   * Consent status derived from comparing required vs granted scopes.
+   *
+   * - `'granted'` — all required scopes are granted, or none declared
+   * - `'partially_granted'` — at least one required scope is granted but not all
+   * - `'not_granted'` — no required scopes are granted
+   */
+  status: CheckScopesConsentResponse['status'] | undefined
+  loading: boolean
+  error: Error | null
+  /**
+   * Re-fetch scope consent status. Call this after `requestScopesConsent()` resolves
+   * to get the updated status.
+   */
+  refetch: () => Promise<void>
+}
+
+export const useCheckScopesConsent = (): UseCheckScopesConsentReturns => {
+  const {checkScopesConsent} = useShopActions()
+  const {data, loading, error, refetch} = useShopActionQuery(
+    ['scopesConsent'],
+    checkScopesConsent,
+    {}
+  )
+  return {
+    requiredScopes: data?.requiredScopes,
+    grantedScopes: data?.grantedScopes,
+    status: data?.status,
+    loading,
+    error,
+    refetch,
+  }
+}
+
+/**
+ * Returns the current scope consent status for this mini, fetched fresh from the API on mount.
+ *
+ * Use `status` to branch UI on whether the user has granted all required scopes:
+ * - `'granted'` — all required scopes are granted (or none declared)
+ * - `'partially_granted'` — at least one required scope is granted but not all
+ * - `'not_granted'` — no required scopes are granted
+ *
+ * Call `refetch()` after `requestScopesConsent()` resolves to get the updated status.
+ * @publicDocs
+ */
+export type UseCheckScopesConsentGeneratedType =
+  () => UseCheckScopesConsentReturns

package/src/hooks/util/useRequestPermissions.ts

@@ -26,6 +26,7 @@ export const useRequestPermissions = (): UseRequestPermissionsReturns => {
 /**
  * The `useRequestPermissions` hook provides a function to request native device permissions from the user. It handles both app-level and system-level permission requests, showing appropriate dialogs and managing permission state. Supported permissions include camera, microphone, and device motion access.
  *
+ * `errorMessage` is normally a string describing the failure. The value `'request_blocked'` is a reserved sentinel — it means the request couldn't be served because another consent or permission sheet is already showing, or the Mini's scope state hasn't finished loading yet. Don't surface this string to users.
  *
  * > Note: Before using this hook, add the required permissions to your Mini's manifest file: `"permissions": ["CAMERA"]`.
  * @publicDocs

package/src/hooks/util/useRequestScopesConsent.ts

@@ -0,0 +1,38 @@
+import {RequestScopesConsentResponse} from '@shopify/shop-minis-platform/actions'
+
+import {useHandleAction} from '../../internal/useHandleAction'
+import {useShopActions} from '../../internal/useShopActions'
+
+export interface UseRequestScopesConsentReturns {
+  /**
+   * Programmatically show the consent sheet for the Mini's required scopes.
+   *
+   * The sheet will show even if the user previously rejected it in the same
+   * session. Use this to build retry UX (e.g., a "Connect account" button).
+   *
+   * Resolves with `{granted: boolean}`. Rejects with `'request_blocked'`
+   * if the request can't be served right now — either another consent or
+   * permission sheet is already showing, or the Mini's scope state hasn't
+   * finished loading yet.
+   *
+   * Call `refetch()` on `useCheckScopesConsent` after resolution to get the
+   * updated scope status.
+   */
+  requestScopesConsent: () => Promise<RequestScopesConsentResponse>
+}
+
+export const useRequestScopesConsent = (): UseRequestScopesConsentReturns => {
+  const {requestScopesConsent} = useShopActions()
+  return {
+    requestScopesConsent: useHandleAction(requestScopesConsent),
+  }
+}
+
+/**
+ * Returns a function to programmatically show the consent sheet. Use this to
+ * build re-consent UX after the user has previously rejected, or when partial
+ * scope grants are detected via `useCheckScopesConsent`.
+ * @publicDocs
+ */
+export type UseRequestScopesConsentGeneratedType =
+  () => UseRequestScopesConsentReturns

package/src/mocks.ts

@@ -479,6 +479,7 @@ export function makeMockActions(): ShopActions {
           id: 'variant-1',
           title: 'Variant 1',
           isFavorited: false,
+          availableForSale: true,
           image: {url: 'https://example.com/variant-1.jpg'},
           price: {amount: '19.99', currencyCode: 'USD'},
           compareAtPrice: {amount: '29.99', currencyCode: 'USD'},
@@ -577,6 +578,14 @@ export function makeMockActions(): ShopActions {
     checkPermission: {
       status: 'granted',
     },
+    checkScopesConsent: {
+      data: {
+        requiredScopes: ['profile'],
+        grantedScopes: ['profile'],
+        status: 'granted',
+      },
+    },
+    requestScopesConsent: {granted: true},
     reportError: undefined,
     reportFetch: undefined,
     invokeIntent: {code: 'closed' as const},

package/src/test-utils.tsx

@@ -128,6 +128,7 @@ export const mockProductVariant = (
   id: 'variant-1',
   title: 'Default Variant',
   isFavorited: false,
+  availableForSale: true,
   price: mockMoney('29.99', 'USD'),
   compareAtPrice: mockMoney('39.99', 'USD'),
   image: mockProductImage(),