@shopify/shop-minis-platform 0.17.0 → 0.19.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.19.0",
   "description": "Shared type definitions for Shop Minis Platform",
   "main": "src/index.ts",
   "exports": {
@@ -21,13 +21,13 @@
   ],
   "scripts": {
     "test": "TZ=UTC jest",
-    "type-check": "tsc --noEmit",
+    "type-check": "tsgo --noEmit",
     "typecheck": "pnpm run type-check"
   },
   "dependencies": {},
   "peerDependencies": {},
   "devDependencies": {
-    "typescript": "^5.8.3"
+    "typescript": "^6.0.3"
   },
   "author": "Shopify",
   "repository": {

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,
@@ -67,6 +71,8 @@ import {
   GetRecentProductsResponse,
   GetProductSearchParams,
   GetProductSearchResponse,
+  GetSimilarProductsParams,
+  GetSimilarProductsResponse,
   GetProductsParams,
   GetProductsResponse,
   GetProductParams,
@@ -214,6 +220,10 @@ export interface ShopActionEvents {
     GetProductSearchParams,
     GetProductSearchResponse
   >
+  GET_SIMILAR_PRODUCTS: ShopAction<
+    GetSimilarProductsParams,
+    GetSimilarProductsResponse
+  >
   GET_PRODUCTS: ShopAction<GetProductsParams, GetProductsResponse>
   GET_PRODUCT: ShopAction<GetProductParams, GetProductResponse>
   GET_PRODUCT_VARIANTS: ShopAction<
@@ -250,4 +260,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/actions/params.ts

@@ -695,6 +695,62 @@ export interface GetProductSearchResponse extends PaginatedResponse<
   Product[]
 > {}
 
+/**
+ * Image media used as the source for similar product search.
+ * The hook handles base64 encoding from a File — partners pass a File directly,
+ * not the encoded payload.
+ */
+export interface GetSimilarProductsMediaInput {
+  /**
+   * The image MIME type. Currently only `image/jpeg` is supported.
+   */
+  contentType: string
+  /**
+   * The base64-encoded image content (without `data:` prefix). Must be <= 4 MiB.
+   */
+  base64: string
+}
+
+/**
+ * The source for similar product search. Exactly one of `productId`,
+ * `productVariantId`, or `media` must be provided.
+ */
+export interface GetSimilarProductsSourceInput {
+  /**
+   * Shopify Product GID, e.g. `gid://shopify/Product/123`.
+   */
+  productId?: string
+  /**
+   * Shopify ProductVariant GID, e.g. `gid://shopify/ProductVariant/456`.
+   */
+  productVariantId?: string
+  /**
+   * JPEG image media to find similar products for.
+   */
+  media?: GetSimilarProductsMediaInput
+}
+
+export interface GetSimilarProductsParams {
+  /**
+   * Source for similar product search. Exactly one of `productId`,
+   * `productVariantId`, or `media` must be set.
+   */
+  similarTo: GetSimilarProductsSourceInput
+  /**
+   * Number of products to return. Must be 1..10.
+   */
+  first?: number
+  /**
+   * Cursor for pagination. Currently the backend returns only a first page,
+   * so this is effectively unused.
+   */
+  after?: string
+  fetchPolicy?: DataHookFetchPolicy
+}
+
+export interface GetSimilarProductsResponse
+  extends PaginatedResponse<Product[]> {}
+
 export interface GetProductVariantsParams {
   id: string
   first?: number

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 {