@shopify/shop-minis-platform 0.17.0 → 0.18.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shopify/shop-minis-platform",
   "license": "SEE LICENSE IN LICENSE.txt",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Shared type definitions for Shop Minis Platform",
   "main": "src/index.ts",
   "exports": {

package/src/actions/actions.ts

@@ -1,6 +1,10 @@
 import {ProductList} from '../types'
 
-import {InvokeIntentParams, InvokeIntentResponse} from './intents'
+import {
+  InvokeIntentParams,
+  InvokeIntentResponse,
+  ResolveIntentParams,
+} from './intents'
 import {
   FollowShopParams,
   UnfollowShopParams,
@@ -250,4 +254,5 @@ export interface ShopActionEvents {
   REPORT_ERROR: ShopAction<ReportErrorParams, void>
   REPORT_FETCH: ShopAction<ReportFetchParams, void>
   INVOKE_INTENT: ShopAction<InvokeIntentParams, InvokeIntentResponse>
+  RESOLVE_INTENT: ShopAction<ResolveIntentParams, void>
 }

package/src/actions/intent-definitions.ts

@@ -32,10 +32,24 @@ export interface CreateUserImageParams {
   maxSize?: number
 }
 
-export interface CreateUserImageResponse {
+export interface ImageUrlResponse {
+  /** URL of the generated image. */
   imageUrl: string
 }
 
+export type CreateUserImageResponse = ImageUrlResponse
+
+// ---------------------------------------------------------------------------
+// Try On Product Intent — try_on:shopify/Product
+// ---------------------------------------------------------------------------
+
+export interface TryOnProductParams {
+  /** Variant the user selected on the PDP that launched the Mini. */
+  variantId: string
+}
+
+export type TryOnProductResponse = ImageUrlResponse
+
 // ---------------------------------------------------------------------------
 // Intent Registry
 // ---------------------------------------------------------------------------
@@ -47,6 +61,46 @@ export interface IntentDefinitions {
     data: CreateUserImageParams
     result: CreateUserImageResponse
   }
+  tryOnProduct: {
+    action: 'try_on'
+    type: 'shopify/Product'
+    data: TryOnProductParams
+    result: TryOnProductResponse
+  }
 }
 
 export type IntentKey = keyof IntentDefinitions
+
+// ---------------------------------------------------------------------------
+// Runtime registry — pairs every IntentKey to the (action, type) literals it
+// declares. The type-level IntentDefinitions above is erased at runtime; this
+// constant is what code that needs to look up "which key matches this parsed
+// intent" reads from. Keep in sync with IntentDefinitions.
+// ---------------------------------------------------------------------------
+
+export const INTENT_REGISTRY = {
+  createUserImage: {action: 'create', type: 'shop/UserImage'},
+  tryOnProduct: {action: 'try_on', type: 'shopify/Product'},
+} as const satisfies {
+  [K in IntentKey]: {
+    action: IntentDefinitions[K]['action']
+    type: IntentDefinitions[K]['type']
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Intent label constants — derived from INTENT_REGISTRY so adding an entry
+// above automatically extends `Intents`. The trailing cast is safe because
+// `INTENT_REGISTRY` is `satisfies {[K in IntentKey]: ...}`, so its keys are
+// exactly `IntentKey`.
+// ---------------------------------------------------------------------------
+
+export const Intents = (() => {
+  const out: {[label: string]: IntentKey} = {}
+  for (const key of Object.keys(INTENT_REGISTRY) as IntentKey[]) {
+    out[key[0].toUpperCase() + key.slice(1)] = key
+  }
+  return out as {[K in IntentKey as Capitalize<K>]: K}
+})()
+
+export type Intents = (typeof Intents)[keyof typeof Intents]

package/src/actions/intents.ts

@@ -32,19 +32,22 @@ export interface IntentQuery<
   type: string
 }
 
-/**
- * Params for the INVOKE_INTENT shop action.
- */
+/** Params for the INVOKE_INTENT shop action. */
 export type InvokeIntentParams = IntentQuery<any>
 
 // ---------------------------------------------------------------------------
 // Intent result types
 // ---------------------------------------------------------------------------
 
-export interface IntentResultOk<T> {
-  code: 'ok'
-  data: T
-}
+/**
+ * Successful intent completion. `data` follows the declared response type:
+ * `void` → omitted, concrete shape → required, untyped (`unknown`) → optional.
+ */
+export type IntentResultOk<T> = unknown extends T
+  ? {code: 'ok'; data?: T}
+  : [T] extends [void]
+    ? {code: 'ok'}
+    : {code: 'ok'; data: T}
 
 export interface IntentResultError {
   code: 'error'
@@ -61,7 +64,7 @@ export interface IntentResultClosed {
  * - `'error'`  — workflow failed with a message
  * - `'closed'` — user dismissed without completing
  */
-export type IntentResult<T = {[key: string]: unknown}> =
+export type IntentResult<T = unknown> =
   | IntentResultOk<T>
   | IntentResultError
   | IntentResultClosed
@@ -86,6 +89,21 @@ export type IntentAction<TData, TResult> = (
 /** Untyped intent response used at the INVOKE_INTENT bridge boundary. */
 export type InvokeIntentResponse = IntentResult
 
+// ---------------------------------------------------------------------------
+// RESOLVE_INTENT — Mini reports intent completion back to the host
+// ---------------------------------------------------------------------------
+
+/**
+ * Params for the RESOLVE_INTENT shop action. `result` is loose at the bridge;
+ * the typed correlation between `intentKey` and `result.data` is enforced by
+ * the `useResolveIntent` hook, where K is concrete.
+ */
+export interface ResolveIntentParams {
+  /** Lets the host verify the Mini resolved the intent it was launched with. */
+  intentKey: IntentKey
+  result: IntentResult
+}
+
 // ---------------------------------------------------------------------------
 // Typed intent utilities — leverage IntentDefinitions for per-intent safety
 // ---------------------------------------------------------------------------

package/src/index.ts

@@ -4,6 +4,7 @@ import {MinisParams} from './types'
 
 export * from './types'
 export * from './constants'
+export * from './actions/intent-definitions'
 
 declare global {
   interface Window {