@shopify/shop-minis-react 0.15.1 → 0.16.1

package/src/hooks/product/useProductListActions.ts

@@ -11,7 +11,7 @@ import {useHandleAction} from '../../internal/useHandleAction'
 import {useShopActions} from '../../internal/useShopActions'
 import {ProductList} from '../../types'
 
-interface UseProductListActionsReturns {
+export interface UseProductListActionsReturns {
   /**
    * Add a product list
    */
@@ -59,3 +59,18 @@ export const useProductListActions = (): UseProductListActionsReturns => {
     removeProductListItem: useHandleAction(removeProductListItem),
   }
 }
+
+/**
+ * The `useProductListActions` hook provides mutation functions for managing product collections. Available actions: `addProductList()` creates a new collection, `removeProductList()` deletes a collection, `renameProductList()` updates a collection name, `addProductListItem()` saves a product to a collection, and `removeProductListItem()` removes a product from a collection. All actions automatically handle Shop app integration.
+ * <!-- SCOPE_REQUIREMENTS_START -->
+ *
+ * > Caution: This hook requires adding the following scopes to the manifest file:
+ * >
+ * > `product_list:write` `product_list_item:write`
+ * >
+ * > For more details, see [manifest.json](/docs/api/shop-minis/manifest-file).
+ * <!-- SCOPE_REQUIREMENTS_END -->
+ * @publicDocs
+ */
+export type UseProductListActionsGeneratedType =
+  () => UseProductListActionsReturns

package/src/hooks/product/useProductLists.ts

@@ -6,14 +6,14 @@ import {
   ProductList,
 } from '../../types'
 
-interface UseProductListsParams extends PaginatedDataHookOptionsBase {
+export interface UseProductListsParams extends PaginatedDataHookOptionsBase {
   /**
    * The number of products to fetch per product list.
    */
   itemsFirst?: number
 }
 
-interface UseProductListsResult extends PaginatedDataHookReturnsBase {
+export interface UseProductListsResult extends PaginatedDataHookReturnsBase {
   productLists: ProductList[] | null
 }
 
@@ -35,3 +35,11 @@ export const useProductLists = (
     productLists: data,
   }
 }
+
+/**
+ * The `useProductLists` hook fetches all product collections that the user has created. Use this for displaying a user's collections overview or collection picker. For fetching a specific collection's full contents, use `useProductList()` instead which provides better pagination for individual lists.
+ * @publicDocs
+ */
+export type UseProductListsGeneratedType = (
+  params?: UseProductListsParams
+) => UseProductListsResult

package/src/hooks/product/useProductMedia.ts

@@ -13,7 +13,7 @@ export interface UseProductMediaParams extends PaginatedDataHookOptionsBase {
   id: string
 }
 
-interface UseProductMediaReturns extends PaginatedDataHookReturnsBase {
+export interface UseProductMediaReturns extends PaginatedDataHookReturnsBase {
   /**
    * The product media returned from the query.
    */
@@ -38,3 +38,11 @@ export const useProductMedia = (
     media: data,
   }
 }
+
+/**
+ * The `useProductMedia` hook fetches media items (images, videos, etc.) for a specific product.
+ * @publicDocs
+ */
+export type UseProductMediaGeneratedType = (
+  params: UseProductMediaParams
+) => UseProductMediaReturns

package/src/hooks/product/useProductSearch.ts

@@ -31,7 +31,7 @@ export interface UseProductSearchParams extends PaginatedDataHookOptionsBase {
   includeSensitive?: boolean
 }
 
-interface UseProductSearchReturns extends PaginatedDataHookReturnsBase {
+export interface UseProductSearchReturns extends PaginatedDataHookReturnsBase {
   /**
    * The products returned from the query.
    */
@@ -106,3 +106,13 @@ export const useProductSearch = (
     isTyping: debouncedQuery !== query,
   }
 }
+
+/**
+ * The `useProductSearch` hook fetches products based on a search query.
+ *
+ * > Note: In order to filter products by category, you can check [Shopify's Product Taxonomy](https://shopify.github.io/product-taxonomy/releases/latest/). Then use the GID of the category. For example, to filter products in the Electronics category, you would use: ["gid://shopify/TaxonomyCategory/el"]
+ * @publicDocs
+ */
+export type UseProductSearchGeneratedType = (
+  params: UseProductSearchParams
+) => UseProductSearchReturns

package/src/hooks/product/useProductVariants.ts

@@ -13,7 +13,7 @@ export interface UseProductVariantsParams extends PaginatedDataHookOptionsBase {
   id: string
 }
 
-interface UseProductVariantsReturns extends PaginatedDataHookReturnsBase {
+export interface UseProductVariantsReturns extends PaginatedDataHookReturnsBase {
   /**
    * The product variants returned from the query.
    */
@@ -38,3 +38,11 @@ export const useProductVariants = (
     variants: data,
   }
 }
+
+/**
+ * The `useProductVariants` hook fetches product variants for a specific product.
+ * @publicDocs
+ */
+export type UseProductVariantsGeneratedType = (
+  params: UseProductVariantsParams
+) => UseProductVariantsReturns

package/src/hooks/product/useProducts.ts

@@ -9,7 +9,7 @@ export interface UseProductsParams extends DataHookOptionsBase {
   ids: string[]
 }
 
-interface UseProductsReturns extends DataHookReturnsBase {
+export interface UseProductsReturns extends DataHookReturnsBase {
   /**
    * The products returned from the query.
    */
@@ -32,3 +32,11 @@ export const useProducts = (params: UseProductsParams): UseProductsReturns => {
     products: data,
   }
 }
+
+/**
+ * The `useProducts` hook efficiently fetches multiple products in a single batched request. Takes an array of product IDs and returns complete product data. Ideal for product grids, carousels, or any UI displaying multiple products. All products share a single query cache entry, making this more efficient than multiple `useProduct()` calls. The entire query refetches if any ID in the array changes.
+ * @publicDocs
+ */
+export type UseProductsGeneratedType = (
+  params: UseProductsParams
+) => UseProductsReturns

package/src/hooks/product/useRecommendedProducts.ts

@@ -6,9 +6,9 @@ import {
   PaginatedDataHookReturnsBase,
 } from '../../types'
 
-interface UseRecommendedProductsParams extends PaginatedDataHookOptionsBase {}
+export interface UseRecommendedProductsParams extends PaginatedDataHookOptionsBase {}
 
-interface UseRecommendedProductsReturns extends PaginatedDataHookReturnsBase {
+export interface UseRecommendedProductsReturns extends PaginatedDataHookReturnsBase {
   products: Product[] | null
 }
 
@@ -33,3 +33,11 @@ export const useRecommendedProducts = (
     products: data,
   }
 }
+
+/**
+ * The `useRecommendedProducts` hook fetches personalized product recommendations based on the user's shopping behavior, purchase history, and preferences in the Shop app. Recommendations may be empty for new users without sufficient activity. You can use this for personalized discovery sections, "You might like" carousels, or filling empty states with relevant products. Unlike `useRecentProducts` which shows browsing history, this hook provides algorithmic suggestions.
+ * @publicDocs
+ */
+export type UseRecommendedProductsGeneratedType = (
+  params?: UseRecommendedProductsParams
+) => UseRecommendedProductsReturns

package/src/hooks/shop/useRecommendedShops.ts

@@ -8,9 +8,9 @@ import {
   PaginatedDataHookReturnsBase,
 } from '../../types'
 
-interface UseRecommendedShopsParams extends PaginatedDataHookOptionsBase {}
+export interface UseRecommendedShopsParams extends PaginatedDataHookOptionsBase {}
 
-interface UseRecommendedShopsReturns extends PaginatedDataHookReturnsBase {
+export interface UseRecommendedShopsReturns extends PaginatedDataHookReturnsBase {
   shops: Shop[] | null
 }
 
@@ -39,3 +39,11 @@ export const useRecommendedShops = (
     shops,
   }
 }
+
+/**
+ * The `useRecommendedShops` hook fetches personalized shop recommendations based on the user's purchase patterns, followed shops, and product interests in the Shop app. You can use this for shop discovery sections, "Brands you might like" features, or diversifying merchant exposure. Unlike `useRecentShops` which shows interaction history, this hook provides algorithmic suggestions for new merchant discovery.
+ * @publicDocs
+ */
+export type UseRecommendedShopsGeneratedType = (
+  params?: UseRecommendedShopsParams
+) => UseRecommendedShopsReturns

package/src/hooks/shop/useShop.ts

@@ -9,7 +9,7 @@ export interface UseShopParams extends DataHookOptionsBase {
   id: string
 }
 
-interface UseShopReturns extends DataHookReturnsBase {
+export interface UseShopReturns extends DataHookReturnsBase {
   /**
    * The shop returned from the query.
    */
@@ -32,3 +32,9 @@ export const useShop = (params: UseShopParams): UseShopReturns => {
     shop: data,
   }
 }
+
+/**
+ * The `useShop` hook enables fetching a shop by its ID.
+ * @publicDocs
+ */
+export type UseShopGeneratedType = (params: UseShopParams) => UseShopReturns

package/src/hooks/storage/useAsyncStorage.ts

@@ -7,7 +7,7 @@ import {
 import {useHandleAction} from '../../internal/useHandleAction'
 import {useShopActions} from '../../internal/useShopActions'
 
-interface UseAsyncStorageReturns {
+export interface UseAsyncStorageReturns {
   /**
    * Get an item from the async storage.
    */
@@ -47,3 +47,13 @@ export function useAsyncStorage(): UseAsyncStorageReturns {
     clear: useHandleAction(clearPersistedItems),
   }
 }
+
+/**
+ * The `useAsyncStorage` hook provides functions to interact with persistent storage for non-sensitive data. Use this for user preferences, UI state, cached content, or any data where performance matters and encryption is not required. Data is stored in plaintext and persists between app sessions.
+ *
+ * > Note: Use `useAsyncStorage` for non-sensitive data like themes, preferences, cached content, or application state. It supports multiple key-value pairs. Use `useSecureStorage` for sensitive data like authentication tokens. It provides hardware-backed encryption but only stores one secret per Mini and has slower performance.
+ *
+ * > Caution: Do not store images, base64-encoded images, blobs, or any other binary data in async storage. This is against Shop Minis guidelines and will cause your Mini to be rejected during review. Async storage is designed for small, serializable key-value pairs only. For image handling, use the `useImageUpload` or `useCreateImageContent` hooks instead.
+ * @publicDocs
+ */
+export type UseAsyncStorageGeneratedType = () => UseAsyncStorageReturns

package/src/hooks/storage/useImageUpload.ts

@@ -42,7 +42,7 @@ export interface UploadedImage {
   resourceUrl?: string
 }
 
-interface UseImageUploadReturns {
+export interface UseImageUploadReturns {
   /**
    * Upload an image which will be attached to the current user.
    */
@@ -165,3 +165,9 @@ export const useImageUpload = (): UseImageUploadReturns => {
     uploadImage,
   }
 }
+
+/**
+ * The `useImageUpload` hook provides image upload functionality, handling the complete upload pipeline. It returns basic image metadata (ID, URL, resource URL) with uploads automatically attached to the current user. This hook is the foundation for direct image storage scenarios like profile pictures, attachments, or cases where you manage image relationships and metadata yourself. For user-generated content requiring visibility controls, sharing capabilities, or content discovery features, `useCreateImageContent` builds on this hook to provide those higher-level abstractions.
+ * @publicDocs
+ */
+export type UseImageUploadGeneratedType = () => UseImageUploadReturns

package/src/hooks/storage/useSecureStorage.ts

@@ -3,7 +3,7 @@ import {SetSecretParams} from '@shopify/shop-minis-platform/actions'
 import {useHandleAction} from '../../internal/useHandleAction'
 import {useShopActions} from '../../internal/useShopActions'
 
-interface UseSecureStorageReturns {
+export interface UseSecureStorageReturns {
   /**
    * Get the secret from the secure storage.
    */
@@ -27,3 +27,13 @@ export function useSecureStorage(): UseSecureStorageReturns {
     removeSecret: useHandleAction(removeSecret),
   }
 }
+
+/**
+ * The `useSecureStorage` hook provides functions to interact with secure storage for sensitive data. You can use this for authentication tokens or any sensitive data that requires hardware-backed encryption.
+ *
+ * > Caution: You can only store one secret per Mini.
+ *
+ * > Note: Use `useSecureStorage` for sensitive data like auth tokens, API keys, or PII. It provides hardware-backed encryption on both iOS and Android, ensuring data is protected even if the device is compromised. The tradeoff is slower performance and a limit of one secret per Mini. Use `useAsyncStorage` for non-sensitive data like preferences or cached content. It supports multiple key-value pairs and is ~3x faster, but stores data in plaintext.
+ * @publicDocs
+ */
+export type UseSecureStorageGeneratedType = () => UseSecureStorageReturns

package/src/hooks/user/useBuyerAttributes.ts

@@ -30,3 +30,19 @@ export const useBuyerAttributes = (
     buyerAttributes: data,
   }
 }
+
+/**
+ * The `useBuyerAttributes` hook fetches shopping preference signals for personalization. Returns `genderAffinity` (MALE, FEMALE, or NEUTRAL) and `categoryAffinities` (list of product taxonomy categories the user engages with). Use this data to customize product recommendations, filter content, or tailor messaging. This is privacy-sensitive data derived from the user's Shop activity, always handle respectfully and transparently in your UI.
+ * <!-- SCOPE_REQUIREMENTS_START -->
+ *
+ * > Caution: This hook requires adding the following scopes to the manifest file:
+ * >
+ * > `profile`
+ * >
+ * > For more details, see [manifest.json](/docs/api/shop-minis/manifest-file).
+ * <!-- SCOPE_REQUIREMENTS_END -->
+ * @publicDocs
+ */
+export type UseBuyerAttributesGeneratedType = (
+  params?: UseBuyerAttributesParams
+) => UseBuyerAttributesReturns

package/src/hooks/user/useCurrentUser.ts

@@ -36,3 +36,19 @@ export const useCurrentUser = (
     currentUser: data,
   }
 }
+
+/**
+ * The `useCurrentUser` hook fetches the Shop app user's profile information including display name and avatar image URL. Use this for personalizing the UI, displaying user info in headers/profiles, or conditionally showing features based on authentication status.
+ * <!-- SCOPE_REQUIREMENTS_START -->
+ *
+ * > Caution: This hook requires adding the following scopes to the manifest file:
+ * >
+ * > `user_settings:read`
+ * >
+ * > For more details, see [manifest.json](/docs/api/shop-minis/manifest-file).
+ * <!-- SCOPE_REQUIREMENTS_END -->
+ * @publicDocs
+ */
+export type UseCurrentUserGeneratedType = (
+  params?: UseCurrentUserParams
+) => UseCurrentUserReturns

package/src/hooks/user/useFollowedShops.ts

@@ -8,7 +8,7 @@ import {
 
 export interface UseFollowedShopsParams extends PaginatedDataHookOptionsBase {}
 
-interface UseFollowedShopsReturns extends PaginatedDataHookReturnsBase {
+export interface UseFollowedShopsReturns extends PaginatedDataHookReturnsBase {
   /**
    * The followed shops returned from the query.
    */
@@ -33,3 +33,11 @@ export const useFollowedShops = (
     shops: data,
   }
 }
+
+/**
+ * The `useFollowedShops` hook fetches the collection of shops the user follows in the Shop app. Use this to display followed brands, create quick-access shop lists, show follow status in UI, or build social commerce features. Pair with `useFollowedShopsActions()` to manage follow/unfollow operations.
+ * @publicDocs
+ */
+export type UseFollowedShopsGeneratedType = (
+  params?: UseFollowedShopsParams
+) => UseFollowedShopsReturns

package/src/hooks/user/useFollowedShopsActions.ts

@@ -6,7 +6,7 @@ import {
 import {useHandleAction} from '../../internal/useHandleAction'
 import {useShopActions} from '../../internal/useShopActions'
 
-interface UseFollowedShopsActionsReturns {
+export interface UseFollowedShopsActionsReturns {
   /**
    * Follows a shop.
    */
@@ -25,3 +25,18 @@ export const useFollowedShopsActions = (): UseFollowedShopsActionsReturns => {
     unfollowShop: useHandleAction(unfollowShop),
   }
 }
+
+/**
+ * The `useFollowedShopsActions` hook provides mutation functions to follow and unfollow shops. Returns `followShop()` and `unfollowShop()` functions that accept a shop GID. Following a shop adds it to the user's followed shops collection in the Shop app, enabling personalized recommendations. `useFollowedShops()` hook can be used to display current follow status.
+ * <!-- SCOPE_REQUIREMENTS_START -->
+ *
+ * > Caution: This hook requires adding the following scopes to the manifest file:
+ * >
+ * > `shops:follows:write`
+ * >
+ * > For more details, see [manifest.json](/docs/api/shop-minis/manifest-file).
+ * <!-- SCOPE_REQUIREMENTS_END -->
+ * @publicDocs
+ */
+export type UseFollowedShopsActionsGeneratedType =
+  () => UseFollowedShopsActionsReturns

package/src/hooks/user/useGenerateUserToken.ts

@@ -8,7 +8,7 @@ import {
 import {useHandleAction} from '../../internal/useHandleAction'
 import {useShopActions} from '../../internal/useShopActions'
 
-interface UseGenerateUserTokenReturns {
+export interface UseGenerateUserTokenReturns {
   /**
    * Generates a temporary token for the user.
    * Tokens are cached in memory and reused if still valid (with a 5-minute expiry buffer).
@@ -93,3 +93,18 @@ export function useGenerateUserToken(): UseGenerateUserTokenReturns {
     generateUserToken,
   }
 }
+
+/**
+ * The `useGenerateUserToken` hook generates a temporary token for authenticating the current user with your backend. This token can be verified using the [`userTokenVerify`](/docs/api/shop-minis/minis-admin-api/mutations/usertokenverify) mutation to obtain a permanent user identifier. See [Verifying requests](/docs/api/shop-minis/network-requests#verifying-requests) for implementation details.
+ *
+ * > Note: Some common use cases are: authenticating API requests to your backend, identifying users for personalized experiences, securely linking Shop users to your application's user database.
+ * <!-- SCOPE_REQUIREMENTS_START -->
+ *
+ * > Note: This hook optionally uses the following scope(s) when declared in the manifest: `openid`
+ * >
+ * > For more details, see [manifest.json](/docs/api/shop-minis/manifest-file).
+ * <!-- SCOPE_REQUIREMENTS_END -->
+ * @publicDocs
+ */
+export type UseGenerateUserTokenGeneratedType =
+  () => UseGenerateUserTokenReturns

package/src/hooks/user/useOrders.ts

@@ -28,3 +28,19 @@ export const useOrders = (params?: UseOrdersParams): UseOrdersReturns => {
     orders: data,
   }
 }
+
+/**
+ * The `useOrders` hook fetches the user's recent order history from all Shop stores, sorted by most recent first. Use this for order history pages, reorder functionality, tracking shipments, or customer support features. Orders are aggregated across all merchants the user has purchased from through Shop.
+ * <!-- SCOPE_REQUIREMENTS_START -->
+ *
+ * > Caution: This hook requires adding the following scopes to the manifest file:
+ * >
+ * > `orders`
+ * >
+ * > For more details, see [manifest.json](/docs/api/shop-minis/manifest-file).
+ * <!-- SCOPE_REQUIREMENTS_END -->
+ * @publicDocs
+ */
+export type UseOrdersGeneratedType = (
+  params?: UseOrdersParams
+) => UseOrdersReturns

package/src/hooks/user/useRecentProducts.ts

@@ -42,3 +42,11 @@ export const useRecentProducts = (
     products,
   }
 }
+
+/**
+ * The `useRecentProducts` hook fetches products the user recently viewed in the Shop app, ordered by recency. You can use this to create 'Continue Shopping' sections or personalized product recommendations based on browsing history.
+ * @publicDocs
+ */
+export type UseRecentProductsGeneratedType = (
+  params?: UseRecentProductsParams
+) => UseRecentProductsReturns

package/src/hooks/user/useRecentShops.ts

@@ -8,7 +8,7 @@ import {
 
 export interface UseRecentShopsParams extends PaginatedDataHookOptionsBase {}
 
-interface UseRecentShopsReturns extends PaginatedDataHookReturnsBase {
+export interface UseRecentShopsReturns extends PaginatedDataHookReturnsBase {
   /**
    * The recent shops returned from the query.
    */
@@ -33,3 +33,11 @@ export const useRecentShops = (
     shops: data,
   }
 }
+
+/**
+ * The `useRecentShops` hook fetches shops the user recently interacted with in the Shop app, ordered by recency. You can use this to create quick access to favorite stores or personalized shop recommendations.
+ * @publicDocs
+ */
+export type UseRecentShopsGeneratedType = (
+  params?: UseRecentShopsParams
+) => UseRecentShopsReturns

package/src/hooks/user/useSavedProducts.ts

@@ -36,3 +36,11 @@ export const useSavedProducts = (
     products: data,
   }
 }
+
+/**
+ * The `useSavedProducts` hook fetches the current user's saved products.
+ * @publicDocs
+ */
+export type UseSavedProductsGeneratedType = (
+  params?: UseSavedProductsParams
+) => UseSavedProductsReturns

package/src/hooks/user/useSavedProductsActions.ts

@@ -6,7 +6,7 @@ import {
 import {useHandleAction} from '../../internal/useHandleAction'
 import {useShopActions} from '../../internal/useShopActions'
 
-interface UseSavedProductsActionsReturns {
+export interface UseSavedProductsActionsReturns {
   /**
    * Save a product.
    */
@@ -25,3 +25,18 @@ export const useSavedProductsActions = (): UseSavedProductsActionsReturns => {
     unsaveProduct: useHandleAction(unfavorite),
   }
 }
+
+/**
+ * The `useSavedProductsActions` hook provides mutation functions to save and unsave products (favorites). Returns `saveProduct()` and `unsaveProduct()` functions that accept product IDs and variant information. Saving a product adds it to the user's products collection in the Shop app. Use with `useSavedProducts()` to display current saved status and implement optimistic UI updates.
+ * <!-- SCOPE_REQUIREMENTS_START -->
+ *
+ * > Caution: This hook requires adding the following scopes to the manifest file:
+ * >
+ * > `product_list:write`
+ * >
+ * > For more details, see [manifest.json](/docs/api/shop-minis/manifest-file).
+ * <!-- SCOPE_REQUIREMENTS_END -->
+ * @publicDocs
+ */
+export type UseSavedProductsActionsGeneratedType =
+  () => UseSavedProductsActionsReturns

package/src/hooks/util/useCheckPermissions.ts

@@ -0,0 +1,40 @@
+import {
+  CheckPermissionParams,
+  CheckPermissionResponse,
+} from '@shopify/shop-minis-platform/actions'
+
+import {useHandleAction} from '../../internal/useHandleAction'
+import {useShopActions} from '../../internal/useShopActions'
+
+export interface UseCheckPermissionsReturns {
+  /**
+   * Check the current status of a native device permission without prompting the user.
+   *
+   * Returns a {@link PermissionStatus} describing the combined state of the Mini's in-app
+   * consent decision and the OS-level permission. Safe to call at any time — never triggers
+   * the permission dialog or OS prompt.
+   */
+  checkPermission: (
+    params: CheckPermissionParams
+  ) => Promise<CheckPermissionResponse>
+}
+
+export const useCheckPermissions = (): UseCheckPermissionsReturns => {
+  const {checkPermission} = useShopActions()
+
+  return {
+    checkPermission: useHandleAction(checkPermission),
+  }
+}
+
+/**
+ * The `useCheckPermissions` hook provides a function to read the current status of a native device permission for the Mini **without prompting the user**.
+ *
+ * Use it to branch UI on permission state — for example, showing a welcome/onboarding screen only when the user has never seen the consent dialog (`undetermined`), sending the user to system Settings when the permission is `blocked`, or skipping straight to the main flow when the permission is already `granted`.
+ *
+ * Returns one of: `'granted' | 'denied' | 'blocked' | 'undetermined' | 'unavailable'`.
+ *
+ * > Note: Before using this hook, add the required permissions to your Mini's manifest file: `"permissions": ["CAMERA"]`.
+ * @publicDocs
+ */
+export type UseCheckPermissionsGeneratedType = () => UseCheckPermissionsReturns

package/src/hooks/util/useErrorScreen.ts

@@ -2,7 +2,7 @@ import {ShopActions} from '@shopify/shop-minis-platform/actions'
 
 import {useShopActions} from '../../internal/useShopActions'
 
-interface UseErrorScreenReturns {
+export interface UseErrorScreenReturns {
   /**
    * Show an error screen with the given error message.
    */
@@ -14,3 +14,11 @@ export const useErrorScreen = (): UseErrorScreenReturns => {
 
   return {showErrorScreen}
 }
+
+/**
+ * The `useErrorScreen` hook displays a full-screen blocking error UI. Use this for critical, unrecoverable errors that prevent users from continuing, such as missing required data or fatal API errors. The error screen takes over the entire Mini interface and typically requires user action to dismiss or retry.
+ *
+ * > Note: Use `useErrorScreen` for critical failures that block the user workflow (e.g., authentication failures, data corruption, network timeouts that prevent the app from functioning). This provides a full-screen error UI that the user must acknowledge. Use `useErrorToast` for recoverable errors or informational warnings (e.g., failed to save preference, temporary network issues). This shows a non-blocking notification that auto-dismisses and allows users to continue their current task.
+ * @publicDocs
+ */
+export type UseErrorScreenGeneratedType = () => UseErrorScreenReturns

package/src/hooks/util/useErrorToast.ts

@@ -2,7 +2,7 @@ import {ShopActions} from '@shopify/shop-minis-platform/actions'
 
 import {useShopActions} from '../../internal/useShopActions'
 
-interface UseErrorToastReturns {
+export interface UseErrorToastReturns {
   /**
    * Show an error toast with the given error message.
    */
@@ -14,3 +14,11 @@ export const useErrorToast = (): UseErrorToastReturns => {
 
   return {showErrorToast}
 }
+
+/**
+ * The `useErrorToast` hook displays a non-blocking error notification. Use this for recoverable errors, warnings, or informational messages that don't prevent users from continuing their workflow. The toast appears temporarily at the top or bottom of the screen, auto-dismisses, and allows users to keep interacting with the Mini.
+ *
+ * > Note: Use `useErrorToast` for recoverable errors or warnings (e.g., failed to save preference, item out of stock, temporary network issues, validation errors). This shows a non-blocking notification that auto-dismisses and doesn't interrupt the user's current task. Use `useErrorScreen` for critical failures that block the user workflow (e.g., authentication failures, data corruption, network timeouts that prevent the app from functioning). This provides a full-screen error UI that the user must acknowledge before continuing.
+ * @publicDocs
+ */
+export type UseErrorToastGeneratedType = () => UseErrorToastReturns

package/src/hooks/util/useImagePicker.ts

@@ -6,7 +6,7 @@ import {
   OpenGalleryParams,
 } from '../../providers/ImagePickerProvider'
 
-interface UseImagePickerReturns {
+export interface UseImagePickerReturns {
   /**
    * Opens the camera to take a photo.
    */
@@ -41,3 +41,9 @@ export function useImagePicker(): UseImagePickerReturns {
     openGallery: openGalleryWithQuality,
   }
 }
+
+/**
+ * The `useImagePicker` hook provides access to camera and gallery functionality for selecting images.
+ * @publicDocs
+ */
+export type UseImagePickerGeneratedType = () => UseImagePickerReturns

package/src/hooks/util/useRequestPermissions.ts

@@ -6,7 +6,7 @@ import {
 import {useHandleAction} from '../../internal/useHandleAction'
 import {useShopActions} from '../../internal/useShopActions'
 
-interface UseRequestPermissionsReturns {
+export interface UseRequestPermissionsReturns {
   /**
    * Request native permissions from the user
    */
@@ -22,3 +22,13 @@ export const useRequestPermissions = (): UseRequestPermissionsReturns => {
     requestPermission: useHandleAction(requestPermission),
   }
 }
+
+/**
+ * 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.
+ *
+ *
+ * > Note: Before using this hook, add the required permissions to your Mini's manifest file: `"permissions": ["CAMERA"]`.
+ * @publicDocs
+ */
+export type UseRequestPermissionsGeneratedType =
+  () => UseRequestPermissionsReturns

package/src/hooks/util/useSafeArea.ts

@@ -1,6 +1,13 @@
 import type {SafeAreaInsets} from '@shopify/shop-minis-platform'
 
-/** @docs Return type for the useSafeArea hook */
+/**
+ * Returns the safe area insets for the current device in pixels. These values represent the areas of the screen obscured by system UI such as the home indicator on iOS or the navigation bar on Android. Use these values to ensure your content is not hidden behind system chrome.
+ *
+ * The insets are injected by the Shop app and work reliably on both iOS and Android. The equivalent CSS custom properties (`--safe-area-inset-top`, `--safe-area-inset-right`, `--safe-area-inset-bottom`, `--safe-area-inset-left`) are also available for use in stylesheets.
+ *
+ * Your Mini should handle all four edges to ensure correct rendering across devices and future layout changes.
+ * @publicDocs
+ */
 export type UseSafeAreaGeneratedType = SafeAreaInsets
 
 const DEFAULT_INSETS: SafeAreaInsets = {top: 0, right: 0, bottom: 0, left: 0}
@@ -21,6 +28,7 @@ const DEFAULT_INSETS: SafeAreaInsets = {top: 0, right: 0, bottom: 0, left: 0}
  * const {bottom} = useSafeArea()
  * return <div style={{paddingBottom: bottom}}>Content</div>
  * ```
+ * @publicDocs
  */
 export function useSafeArea(): SafeAreaInsets {
   return window.minisParams?.safeAreaInsets ?? DEFAULT_INSETS