@shopify/shop-minis-react 0.14.0 → 0.15.1

package/dist/hooks/intents/useIntent.js

@@ -0,0 +1,45 @@
+import { useMemo as f } from "react";
+import { useDeeplink as p } from "../navigation/useDeeplink.js";
+function q() {
+  const { queryParams: o } = p();
+  return f(() => {
+    const u = o?.intentQuery;
+    if (!u) return { query: null, data: null };
+    let e;
+    try {
+      e = decodeURIComponent(u);
+    } catch {
+      e = u;
+    }
+    const c = e.indexOf(":");
+    if (c === -1) return { query: null, data: null };
+    const s = e.slice(0, c);
+    if (!s) return { query: null, data: null };
+    const l = e.slice(c + 1), r = l.indexOf(",");
+    let a = r === -1 ? l : l.slice(0, r), d = r === -1 ? null : l.slice(r + 1) || null;
+    const n = a.match(/^gid:\/\/shopify\/(\w+)(?:\/(.+))?$/);
+    if (n && (a = `shopify/${n[1]}`, d = n[2] ? `gid://shopify/${n[1]}/${n[2]}` : null), !a) return { query: null, data: null };
+    let y = null;
+    const i = o?.intentData;
+    if (i) {
+      let t;
+      try {
+        t = JSON.parse(i);
+      } catch {
+        try {
+          t = JSON.parse(decodeURIComponent(i));
+        } catch {
+        }
+      }
+      t !== null && typeof t == "object" && !Array.isArray(t) && (y = t);
+    }
+    return {
+      query: { action: s, type: a, value: d },
+      data: y
+    };
+  }, [o]);
+}
+export {
+  q as useIntent
+};
+//# sourceMappingURL=useIntent.js.map

package/dist/hooks/intents/useIntent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useIntent.js","sources":["../../../src/hooks/intents/useIntent.ts"],"sourcesContent":["import {useMemo} from 'react'\n\nimport {useDeeplink} from '../navigation/useDeeplink'\n\n/**\n * Structured description of an intent, following the Shopify Intents API\n * URI format: `action:type,value`\n *\n * @see https://shopify.dev/docs/api/admin-extensions/latest/target-apis/utility-apis/intents-api\n */\nexport interface IntentQuery {\n  /** Verb describing the operation (e.g., 'try_on', 'create', 'edit') */\n  action: string\n  /** Resource type identifier (e.g., 'shopify/Product', 'shop/UserImage') */\n  type: string\n  /** Resource GID (e.g., 'gid://shopify/Product/123') if applicable */\n  value: string | null\n}\n\nexport interface UseIntentReturn {\n  /** Parsed intent query, or null if no intent was passed */\n  query: IntentQuery | null\n  /** Additional JSON data passed with the intent, or null */\n  data: {[key: string]: unknown} | null\n}\n\n/**\n * Parses an intent passed to this mini via deeplink.\n *\n * Follows the Shopify Intents API URI format (`action:type,value`) with\n * an optional JSON data payload passed separately.\n *\n * @see https://shopify.dev/docs/api/admin-extensions/latest/target-apis/utility-apis/intents-api\n *\n * Deeplink format:\n *   ?intentQuery=action:type,value&intentData={\"key\":\"value\"}\n *\n * Examples:\n *   ?intentQuery=try_on:shopify/Product,gid://shopify/Product/123\n *   ?intentQuery=create:shopify/Product\n *   ?intentQuery=edit:shopify/Product,gid://shopify/Product/123&intentData={\"variantId\":\"456\"}\n *\n * Shorthand GID syntax (type inferred from GID):\n *   ?intentQuery=edit:gid://shopify/Product/123\n *   ?intentQuery=create:gid://shopify/Product\n *\n * Use this hook to receive intents from the host app (Host → Mini direction).\n */\nexport function useIntent(): UseIntentReturn {\n  const {queryParams} = useDeeplink()\n\n  return useMemo(() => {\n    const raw = queryParams?.intentQuery\n\n    if (!raw) return {query: null, data: null}\n\n    let decoded: string\n    try {\n      decoded = decodeURIComponent(raw)\n    } catch {\n      decoded = raw\n    }\n\n    const colonIdx = decoded.indexOf(':')\n    if (colonIdx === -1) return {query: null, data: null}\n\n    const action = decoded.slice(0, colonIdx)\n    if (!action) return {query: null, data: null}\n\n    const rest = decoded.slice(colonIdx + 1)\n    const commaIdx = rest.indexOf(',')\n\n    let type = commaIdx === -1 ? rest : rest.slice(0, commaIdx)\n    let value = commaIdx === -1 ? null : rest.slice(commaIdx + 1) || null\n\n    // Shorthand GID syntax: edit:gid://shopify/Product/123\n    // Infer type from GID and use full GID as value\n    const gidMatch = type.match(/^gid:\\/\\/shopify\\/(\\w+)(?:\\/(.+))?$/)\n    if (gidMatch) {\n      type = `shopify/${gidMatch[1]}`\n      value = gidMatch[2] ? `gid://shopify/${gidMatch[1]}/${gidMatch[2]}` : null\n    }\n\n    if (!type) return {query: null, data: null}\n\n    let data: {[key: string]: unknown} | null = null\n    const rawData = queryParams?.intentData\n    if (rawData) {\n      let parsed: unknown\n      try {\n        parsed = JSON.parse(rawData)\n      } catch {\n        try {\n          parsed = JSON.parse(decodeURIComponent(rawData))\n        } catch {\n          // malformed JSON — ignore\n        }\n      }\n      if (\n        parsed !== null &&\n        typeof parsed === 'object' &&\n        !Array.isArray(parsed)\n      ) {\n        data = parsed as {[key: string]: unknown}\n      }\n    }\n\n    return {\n      query: {action, type, value},\n      data,\n    }\n  }, [queryParams])\n}\n"],"names":["useIntent","queryParams","useDeeplink","useMemo","raw","decoded","colonIdx","action","rest","commaIdx","type","value","gidMatch","data","rawData","parsed"],"mappings":";;AAgDO,SAASA,IAA6B;AACrC,QAAA,EAAC,aAAAC,EAAW,IAAIC,EAAY;AAElC,SAAOC,EAAQ,MAAM;AACnB,UAAMC,IAAMH,GAAa;AAEzB,QAAI,CAACG,EAAK,QAAO,EAAC,OAAO,MAAM,MAAM,KAAI;AAErC,QAAAC;AACA,QAAA;AACF,MAAAA,IAAU,mBAAmBD,CAAG;AAAA,IAAA,QAC1B;AACI,MAAAC,IAAAD;AAAA,IAAA;AAGN,UAAAE,IAAWD,EAAQ,QAAQ,GAAG;AACpC,QAAIC,MAAa,GAAI,QAAO,EAAC,OAAO,MAAM,MAAM,KAAI;AAEpD,UAAMC,IAASF,EAAQ,MAAM,GAAGC,CAAQ;AACxC,QAAI,CAACC,EAAQ,QAAO,EAAC,OAAO,MAAM,MAAM,KAAI;AAE5C,UAAMC,IAAOH,EAAQ,MAAMC,IAAW,CAAC,GACjCG,IAAWD,EAAK,QAAQ,GAAG;AAEjC,QAAIE,IAAOD,MAAa,KAAKD,IAAOA,EAAK,MAAM,GAAGC,CAAQ,GACtDE,IAAQF,MAAa,KAAK,OAAOD,EAAK,MAAMC,IAAW,CAAC,KAAK;AAI3D,UAAAG,IAAWF,EAAK,MAAM,qCAAqC;AAMjE,QALIE,MACKF,IAAA,WAAWE,EAAS,CAAC,CAAC,IACrBD,IAAAC,EAAS,CAAC,IAAI,iBAAiBA,EAAS,CAAC,CAAC,IAAIA,EAAS,CAAC,CAAC,KAAK,OAGpE,CAACF,EAAM,QAAO,EAAC,OAAO,MAAM,MAAM,KAAI;AAE1C,QAAIG,IAAwC;AAC5C,UAAMC,IAAUb,GAAa;AAC7B,QAAIa,GAAS;AACP,UAAAC;AACA,UAAA;AACO,QAAAA,IAAA,KAAK,MAAMD,CAAO;AAAA,MAAA,QACrB;AACF,YAAA;AACF,UAAAC,IAAS,KAAK,MAAM,mBAAmBD,CAAO,CAAC;AAAA,QAAA,QACzC;AAAA,QAAA;AAAA,MAER;AAGA,MAAAC,MAAW,QACX,OAAOA,KAAW,YAClB,CAAC,MAAM,QAAQA,CAAM,MAEdF,IAAAE;AAAA,IACT;AAGK,WAAA;AAAA,MACL,OAAO,EAAC,QAAAR,GAAQ,MAAAG,GAAM,OAAAC,EAAK;AAAA,MAC3B,MAAAE;AAAA,IACF;AAAA,EAAA,GACC,CAACZ,CAAW,CAAC;AAClB;"}

package/dist/index.js

@@ -87,21 +87,22 @@ import { useShare as Ht } from "./hooks/util/useShare.js";
 import { useImagePicker as zt } from "./hooks/util/useImagePicker.js";
 import { useKeyboardAvoidingView as Yt } from "./hooks/util/useKeyboardAvoidingView.js";
 import { useRequestPermissions as Kt } from "./hooks/util/useRequestPermissions.js";
-import { useOnMiniFocus as Zt } from "./hooks/events/useOnMiniFocus.js";
-import { useOnMiniBlur as Jt } from "./hooks/events/useOnMiniBlur.js";
-import { useOnMiniClose as $t } from "./hooks/events/useOnMiniClose.js";
-import { useOnAppStateChange as ea } from "./hooks/events/useOnAppStateChange.js";
-import { useOnNavigateBack as ta } from "./hooks/events/useOnNavigateBack.js";
-import { buildDeeplinkUrl as pa } from "./utils/buildDeeplinkUrl.js";
-import { MiniEntityNotFoundError as ma, MiniError as na, MiniNetworkError as sa, formatError as la } from "./utils/errors.js";
-import { extractBrandTheme as fa, formatReviewCount as xa, getFeaturedImages as ca, normalizeRating as da } from "./utils/merchant-card.js";
-import { parseUrl as ga } from "./utils/parseUrl.js";
-import { dataURLToBlob as Aa, fileToDataUri as Da, getResizedImageUrl as Pa, getThumbhashBlobURL as Ta, getThumbhashDataURL as ha } from "./utils/image.js";
-import { formatMoney as Ra } from "./utils/formatMoney.js";
-import { UserState as wa, UserTokenGenerateUserErrorCode as Ba } from "./shop-minis-platform/src/types/user.js";
-import { ContentCreateUserErrorCode as Ma, MinisContentStatus as Fa } from "./shop-minis-platform/src/types/content.js";
-import { Social as ba } from "./shop-minis-platform/src/types/share.js";
-import { DATA_FETCHING_DEFAULT_FETCH_POLICY as ka, DATA_FETCHING_DEFAULT_PAGE_SIZE as Na } from "./shop-minis-platform/src/constants.js";
+import { useIntent as Zt } from "./hooks/intents/useIntent.js";
+import { useOnMiniFocus as Jt } from "./hooks/events/useOnMiniFocus.js";
+import { useOnMiniBlur as $t } from "./hooks/events/useOnMiniBlur.js";
+import { useOnMiniClose as ea } from "./hooks/events/useOnMiniClose.js";
+import { useOnAppStateChange as ta } from "./hooks/events/useOnAppStateChange.js";
+import { useOnNavigateBack as pa } from "./hooks/events/useOnNavigateBack.js";
+import { buildDeeplinkUrl as ma } from "./utils/buildDeeplinkUrl.js";
+import { MiniEntityNotFoundError as sa, MiniError as la, MiniNetworkError as ua, formatError as fa } from "./utils/errors.js";
+import { extractBrandTheme as ca, formatReviewCount as da, getFeaturedImages as Ca, normalizeRating as ga } from "./utils/merchant-card.js";
+import { parseUrl as Aa } from "./utils/parseUrl.js";
+import { dataURLToBlob as Pa, fileToDataUri as Ta, getResizedImageUrl as ha, getThumbhashBlobURL as Ia, getThumbhashDataURL as Ra } from "./utils/image.js";
+import { formatMoney as wa } from "./utils/formatMoney.js";
+import { UserState as Ea, UserTokenGenerateUserErrorCode as Ma } from "./shop-minis-platform/src/types/user.js";
+import { ContentCreateUserErrorCode as Ua, MinisContentStatus as ba } from "./shop-minis-platform/src/types/content.js";
+import { Social as ka } from "./shop-minis-platform/src/types/share.js";
+import { DATA_FETCHING_DEFAULT_FETCH_POLICY as Oa, DATA_FETCHING_DEFAULT_PAGE_SIZE as _a } from "./shop-minis-platform/src/constants.js";
 export {
   Tr as Accordion,
   hr as AccordionContent,
@@ -142,10 +143,10 @@ export {
   me as CarouselNext,
   ne as CarouselPrevious,
   le as Checkbox,
-  Ma as ContentCreateUserErrorCode,
+  Ua as ContentCreateUserErrorCode,
   cr as ContentWrapper,
-  ka as DATA_FETCHING_DEFAULT_FETCH_POLICY,
-  Na as DATA_FETCHING_DEFAULT_PAGE_SIZE,
+  Oa as DATA_FETCHING_DEFAULT_FETCH_POLICY,
+  _a as DATA_FETCHING_DEFAULT_PAGE_SIZE,
   o as DATA_NAVIGATION_TYPE_ATTRIBUTE,
   fe as Dialog,
   xe as DialogClose,
@@ -182,11 +183,11 @@ export {
   B as MerchantCardName,
   E as MerchantCardRating,
   b as MerchantCardSkeleton,
-  ma as MiniEntityNotFoundError,
-  na as MiniError,
-  sa as MiniNetworkError,
+  sa as MiniEntityNotFoundError,
+  la as MiniError,
+  ua as MiniNetworkError,
   p as MinisContainer,
-  Fa as MinisContentStatus,
+  ba as MinisContentStatus,
   q as MinisRouter,
   t as NAVIGATION_TYPES,
   u as ProductCard,
@@ -236,29 +237,29 @@ export {
   Co as SheetTitle,
   go as SheetTrigger,
   ho as Skeleton,
-  ba as Social,
+  ka as Social,
   Dr as StaticArea,
   fr as TextInput,
   Ao as Toaster,
   or as Touchable,
   Q as TransitionLink,
-  wa as UserState,
-  Ba as UserTokenGenerateUserErrorCode,
+  Ea as UserState,
+  Ma as UserTokenGenerateUserErrorCode,
   lr as VideoPlayer,
   Qr as badgeVariants,
-  pa as buildDeeplinkUrl,
-  Aa as dataURLToBlob,
-  fa as extractBrandTheme,
-  Da as fileToDataUri,
-  la as formatError,
-  Ra as formatMoney,
-  xa as formatReviewCount,
-  ca as getFeaturedImages,
-  Pa as getResizedImageUrl,
-  Ta as getThumbhashBlobURL,
-  ha as getThumbhashDataURL,
-  da as normalizeRating,
-  ga as parseUrl,
+  ma as buildDeeplinkUrl,
+  Pa as dataURLToBlob,
+  ca as extractBrandTheme,
+  Ta as fileToDataUri,
+  fa as formatError,
+  wa as formatMoney,
+  da as formatReviewCount,
+  Ca as getFeaturedImages,
+  ha as getResizedImageUrl,
+  Ia as getThumbhashBlobURL,
+  Ra as getThumbhashDataURL,
+  ga as normalizeRating,
+  Aa as parseUrl,
   Po as toast,
   xt as useARPreview,
   dt as useAsyncStorage,
@@ -274,13 +275,14 @@ export {
   zo as useGenerateUserToken,
   zt as useImagePicker,
   At as useImageUpload,
+  Zt as useIntent,
   Yt as useKeyboardAvoidingView,
   wt as useNavigateWithTransition,
-  ea as useOnAppStateChange,
-  Jt as useOnMiniBlur,
-  $t as useOnMiniClose,
-  Zt as useOnMiniFocus,
-  ta as useOnNavigateBack,
+  ta as useOnAppStateChange,
+  $t as useOnMiniBlur,
+  ea as useOnMiniClose,
+  Jt as useOnMiniFocus,
+  pa as useOnNavigateBack,
   yo as useOrders,
   ut as usePopularProducts,
   Jo as useProduct,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shopify/shop-minis-react",
   "license": "SEE LICENSE IN LICENSE.txt",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "sideEffects": false,
   "type": "module",
   "engines": {
@@ -93,6 +93,7 @@
     "@types/react-dom": "^19.1.2",
     "@vitest/coverage-v8": "^2.1.8",
     "@vitest/ui": "^2.1.8",
+    "eslint-formatter-codeframe": "^7.32.1",
     "jsdom": "^25.0.1",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",

package/src/hooks/index.ts

@@ -51,6 +51,9 @@ export * from './util/useImagePicker'
 export * from './util/useKeyboardAvoidingView'
 export * from './util/useRequestPermissions'
 
+// - Intent Hooks
+export * from './intents/useIntent'
+
 // - Event Hooks
 export * from './events/useOnMiniFocus'
 export * from './events/useOnMiniBlur'

package/src/hooks/intents/useIntent.test.ts

@@ -0,0 +1,330 @@
+import {renderHook} from '@testing-library/react'
+import {describe, expect, it, vi, beforeEach} from 'vitest'
+
+import {useIntent} from './useIntent'
+
+vi.mock('../navigation/useDeeplink', () => ({
+  useDeeplink: vi.fn(),
+}))
+
+const {useDeeplink} = await import('../navigation/useDeeplink')
+
+describe('useIntent', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('without intent params', () => {
+    it('returns nulls when no query params', () => {
+      vi.mocked(useDeeplink).mockReturnValue({
+        path: '/',
+        queryParams: undefined,
+        hash: '',
+      })
+
+      const {result} = renderHook(() => useIntent())
+
+      expect(result.current).toEqual({query: null, data: null})
+    })
+
+    it('returns nulls when intentQuery is missing', () => {
+      vi.mocked(useDeeplink).mockReturnValue({
+        path: '/',
+        queryParams: {other: 'param'},
+        hash: '',
+      })
+
+      const {result} = renderHook(() => useIntent())
+
+      expect(result.current).toEqual({query: null, data: null})
+    })
+  })
+
+  describe('intent query parsing', () => {
+    it('parses action:type,value format', () => {
+      vi.mocked(useDeeplink).mockReturnValue({
+        path: '/',
+        queryParams: {
+          intentQuery: 'try_on:shopify/Product,gid://shopify/Product/123',
+        },
+        hash: '',
+      })
+
+      const {result} = renderHook(() => useIntent())
+
+      expect(result.current.query).toEqual({
+        action: 'try_on',
+        type: 'shopify/Product',
+        value: 'gid://shopify/Product/123',
+      })
+      expect(result.current.data).toBeNull()
+    })
+
+    it('parses action:type without value', () => {
+      vi.mocked(useDeeplink).mockReturnValue({
+        path: '/',
+        queryParams: {intentQuery: 'create:shopify/Product'},
+        hash: '',
+      })
+
+      const {result} = renderHook(() => useIntent())
+
+      expect(result.current.query).toEqual({
+        action: 'create',
+        type: 'shopify/Product',
+        value: null,
+      })
+    })
+
+    it('handles URL-encoded intentQuery', () => {
+      vi.mocked(useDeeplink).mockReturnValue({
+        path: '/',
+        queryParams: {
+          intentQuery:
+            'try_on%3Ashopify%2FProduct%2Cgid%3A%2F%2Fshopify%2FProduct%2F123',
+        },
+        hash: '',
+      })
+
+      const {result} = renderHook(() => useIntent())
+
+      expect(result.current.query).toEqual({
+        action: 'try_on',
+        type: 'shopify/Product',
+        value: 'gid://shopify/Product/123',
+      })
+    })
+
+    it('returns null query for invalid format without colon', () => {
+      vi.mocked(useDeeplink).mockReturnValue({
+        path: '/',
+        queryParams: {intentQuery: 'invalid-no-colon'},
+        hash: '',
+      })
+
+      const {result} = renderHook(() => useIntent())
+
+      expect(result.current).toEqual({query: null, data: null})
+    })
+
+    it('returns null query when action is empty', () => {
+      vi.mocked(useDeeplink).mockReturnValue({
+        path: '/',
+        queryParams: {
+          intentQuery: ':shopify/Product,gid://shopify/Product/123',
+        },
+        hash: '',
+      })
+
+      const {result} = renderHook(() => useIntent())
+
+      expect(result.current).toEqual({query: null, data: null})
+    })
+
+    it('returns null value for trailing comma', () => {
+      vi.mocked(useDeeplink).mockReturnValue({
+        path: '/',
+        queryParams: {intentQuery: 'create:shopify/Product,'},
+        hash: '',
+      })
+
+      const {result} = renderHook(() => useIntent())
+
+      expect(result.current.query).toEqual({
+        action: 'create',
+        type: 'shopify/Product',
+        value: null,
+      })
+    })
+
+    it('returns null query when type is empty', () => {
+      vi.mocked(useDeeplink).mockReturnValue({
+        path: '/',
+        queryParams: {intentQuery: 'try_on:'},
+        hash: '',
+      })
+
+      const {result} = renderHook(() => useIntent())
+
+      expect(result.current).toEqual({query: null, data: null})
+    })
+  })
+
+  describe('shorthand GID syntax', () => {
+    it('infers type and value from full GID', () => {
+      vi.mocked(useDeeplink).mockReturnValue({
+        path: '/',
+        queryParams: {
+          intentQuery: 'edit:gid://shopify/Product/123',
+        },
+        hash: '',
+      })
+
+      const {result} = renderHook(() => useIntent())
+
+      expect(result.current.query).toEqual({
+        action: 'edit',
+        type: 'shopify/Product',
+        value: 'gid://shopify/Product/123',
+      })
+    })
+
+    it('infers type with null value from GID without ID', () => {
+      vi.mocked(useDeeplink).mockReturnValue({
+        path: '/',
+        queryParams: {
+          intentQuery: 'create:gid://shopify/Product',
+        },
+        hash: '',
+      })
+
+      const {result} = renderHook(() => useIntent())
+
+      expect(result.current.query).toEqual({
+        action: 'create',
+        type: 'shopify/Product',
+        value: null,
+      })
+    })
+
+    it('parses intentData alongside shorthand GID', () => {
+      vi.mocked(useDeeplink).mockReturnValue({
+        path: '/',
+        queryParams: {
+          intentQuery: 'edit:gid://shopify/Product/123',
+          intentData: '{"title":"Updated"}',
+        },
+        hash: '',
+      })
+
+      const {result} = renderHook(() => useIntent())
+
+      expect(result.current.query).toEqual({
+        action: 'edit',
+        type: 'shopify/Product',
+        value: 'gid://shopify/Product/123',
+      })
+      expect(result.current.data).toEqual({title: 'Updated'})
+    })
+  })
+
+  describe('intent data parsing', () => {
+    it('parses JSON intentData', () => {
+      vi.mocked(useDeeplink).mockReturnValue({
+        path: '/',
+        queryParams: {
+          intentQuery: 'try_on:shopify/Product,gid://shopify/Product/123',
+          intentData: '{"variantId":"gid://shopify/ProductVariant/456"}',
+        },
+        hash: '',
+      })
+
+      const {result} = renderHook(() => useIntent())
+
+      expect(result.current.data).toEqual({
+        variantId: 'gid://shopify/ProductVariant/456',
+      })
+    })
+
+    it('parses URL-encoded intentData', () => {
+      vi.mocked(useDeeplink).mockReturnValue({
+        path: '/',
+        queryParams: {
+          intentQuery: 'try_on:shopify/Product,gid://shopify/Product/123',
+          intentData: '%7B%22variantId%22%3A%22456%22%7D',
+        },
+        hash: '',
+      })
+
+      const {result} = renderHook(() => useIntent())
+
+      expect(result.current.data).toEqual({variantId: '456'})
+    })
+
+    it('preserves percent-encoded values inside already-decoded JSON', () => {
+      vi.mocked(useDeeplink).mockReturnValue({
+        path: '/',
+        queryParams: {
+          intentQuery: 'edit:shopify/Product,gid://shopify/Product/123',
+          intentData: '{"redirect":"https%3A%2F%2Fexample.com"}',
+        },
+        hash: '',
+      })
+
+      const {result} = renderHook(() => useIntent())
+
+      expect(result.current.data).toEqual({
+        redirect: 'https%3A%2F%2Fexample.com',
+      })
+    })
+
+    it('returns null data when intentData is a JSON array', () => {
+      vi.mocked(useDeeplink).mockReturnValue({
+        path: '/',
+        queryParams: {
+          intentQuery: 'try_on:shopify/Product,gid://shopify/Product/123',
+          intentData: '[1,2,3]',
+        },
+        hash: '',
+      })
+
+      const {result} = renderHook(() => useIntent())
+
+      expect(result.current.query).not.toBeNull()
+      expect(result.current.data).toBeNull()
+    })
+
+    it('returns null data when intentData is a JSON primitive', () => {
+      vi.mocked(useDeeplink).mockReturnValue({
+        path: '/',
+        queryParams: {
+          intentQuery: 'try_on:shopify/Product,gid://shopify/Product/123',
+          intentData: '"just a string"',
+        },
+        hash: '',
+      })
+
+      const {result} = renderHook(() => useIntent())
+
+      expect(result.current.query).not.toBeNull()
+      expect(result.current.data).toBeNull()
+    })
+
+    it('returns null data for malformed JSON', () => {
+      vi.mocked(useDeeplink).mockReturnValue({
+        path: '/',
+        queryParams: {
+          intentQuery: 'try_on:shopify/Product,gid://shopify/Product/123',
+          intentData: 'not-valid-json',
+        },
+        hash: '',
+      })
+
+      const {result} = renderHook(() => useIntent())
+
+      expect(result.current.query).not.toBeNull()
+      expect(result.current.data).toBeNull()
+    })
+  })
+
+  describe('memoization', () => {
+    it('returns same reference when queryParams do not change', () => {
+      const queryParams = {
+        intentQuery: 'try_on:shopify/Product,gid://shopify/Product/123',
+      }
+
+      vi.mocked(useDeeplink).mockReturnValue({
+        path: '/',
+        queryParams,
+        hash: '',
+      })
+
+      const {result, rerender} = renderHook(() => useIntent())
+      const firstResult = result.current
+
+      rerender()
+
+      expect(result.current).toBe(firstResult)
+    })
+  })
+})

package/src/hooks/intents/useIntent.ts

@@ -0,0 +1,113 @@
+import {useMemo} from 'react'
+
+import {useDeeplink} from '../navigation/useDeeplink'
+
+/**
+ * Structured description of an intent, following the Shopify Intents API
+ * URI format: `action:type,value`
+ *
+ * @see https://shopify.dev/docs/api/admin-extensions/latest/target-apis/utility-apis/intents-api
+ */
+export interface IntentQuery {
+  /** Verb describing the operation (e.g., 'try_on', 'create', 'edit') */
+  action: string
+  /** Resource type identifier (e.g., 'shopify/Product', 'shop/UserImage') */
+  type: string
+  /** Resource GID (e.g., 'gid://shopify/Product/123') if applicable */
+  value: string | null
+}
+
+export interface UseIntentReturn {
+  /** Parsed intent query, or null if no intent was passed */
+  query: IntentQuery | null
+  /** Additional JSON data passed with the intent, or null */
+  data: {[key: string]: unknown} | null
+}
+
+/**
+ * Parses an intent passed to this mini via deeplink.
+ *
+ * Follows the Shopify Intents API URI format (`action:type,value`) with
+ * an optional JSON data payload passed separately.
+ *
+ * @see https://shopify.dev/docs/api/admin-extensions/latest/target-apis/utility-apis/intents-api
+ *
+ * Deeplink format:
+ *   ?intentQuery=action:type,value&intentData={"key":"value"}
+ *
+ * Examples:
+ *   ?intentQuery=try_on:shopify/Product,gid://shopify/Product/123
+ *   ?intentQuery=create:shopify/Product
+ *   ?intentQuery=edit:shopify/Product,gid://shopify/Product/123&intentData={"variantId":"456"}
+ *
+ * Shorthand GID syntax (type inferred from GID):
+ *   ?intentQuery=edit:gid://shopify/Product/123
+ *   ?intentQuery=create:gid://shopify/Product
+ *
+ * Use this hook to receive intents from the host app (Host → Mini direction).
+ */
+export function useIntent(): UseIntentReturn {
+  const {queryParams} = useDeeplink()
+
+  return useMemo(() => {
+    const raw = queryParams?.intentQuery
+
+    if (!raw) return {query: null, data: null}
+
+    let decoded: string
+    try {
+      decoded = decodeURIComponent(raw)
+    } catch {
+      decoded = raw
+    }
+
+    const colonIdx = decoded.indexOf(':')
+    if (colonIdx === -1) return {query: null, data: null}
+
+    const action = decoded.slice(0, colonIdx)
+    if (!action) return {query: null, data: null}
+
+    const rest = decoded.slice(colonIdx + 1)
+    const commaIdx = rest.indexOf(',')
+
+    let type = commaIdx === -1 ? rest : rest.slice(0, commaIdx)
+    let value = commaIdx === -1 ? null : rest.slice(commaIdx + 1) || null
+
+    // Shorthand GID syntax: edit:gid://shopify/Product/123
+    // Infer type from GID and use full GID as value
+    const gidMatch = type.match(/^gid:\/\/shopify\/(\w+)(?:\/(.+))?$/)
+    if (gidMatch) {
+      type = `shopify/${gidMatch[1]}`
+      value = gidMatch[2] ? `gid://shopify/${gidMatch[1]}/${gidMatch[2]}` : null
+    }
+
+    if (!type) return {query: null, data: null}
+
+    let data: {[key: string]: unknown} | null = null
+    const rawData = queryParams?.intentData
+    if (rawData) {
+      let parsed: unknown
+      try {
+        parsed = JSON.parse(rawData)
+      } catch {
+        try {
+          parsed = JSON.parse(decodeURIComponent(rawData))
+        } catch {
+          // malformed JSON — ignore
+        }
+      }
+      if (
+        parsed !== null &&
+        typeof parsed === 'object' &&
+        !Array.isArray(parsed)
+      ) {
+        data = parsed as {[key: string]: unknown}
+      }
+    }
+
+    return {
+      query: {action, type, value},
+      data,
+    }
+  }, [queryParams])
+}