@shopify/shop-minis-platform 0.19.0 → 0.20.0

package/package.json

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

package/src/actions/intent-definitions.ts

@@ -1,3 +1,5 @@
+import type {ProductVariant} from '../types/product'
+
 // ---------------------------------------------------------------------------
 // User Image Intent — create:shop/UserImage
 // ---------------------------------------------------------------------------
@@ -50,6 +52,102 @@ export interface TryOnProductParams {
 
 export type TryOnProductResponse = ImageUrlResponse
 
+// ---------------------------------------------------------------------------
+// Product Variant Selector Intent — select:shopify/ProductVariant
+// ---------------------------------------------------------------------------
+
+/**
+ * Data payload for the `select:shopify/ProductVariant` intent.
+ *
+ * Prompts the user to pick a variant (and quantity) for the product whose
+ * GID is passed as `data.productId`. The host renders a native bottom sheet
+ * over the mini WebView using the same option pickers as the Shop PDP.
+ *
+ * Single-variant products short-circuit without showing UI.
+ *
+ * @publicDocs
+ */
+export interface SelectProductVariantParams {
+  /**
+   * The GID of the product whose variants should be selectable.
+   * E.g. `gid://shopify/Product/123`.
+   */
+  productId: string
+  /**
+   * If present, the GID of the variant that should be initially highlighted.
+   * Defaults to the product's default variant.
+   */
+  initialVariantId?: string
+  /**
+   * Optional allow-list of variant GIDs. When set, only these variants are
+   * presented to the user. Other variants are filtered out before the option
+   * tree is built.
+   */
+  includedProductVariantGIDs?: string[]
+  /** Initial quantity displayed in the stepper. Defaults to `1`. */
+  initialQuantity?: number
+  /**
+   * Maximum quantity selectable in the stepper. Defaults to the variant's available
+   * inventory (or unbounded when stock is not tracked).
+   */
+  maxQuantity?: number
+  /** Whether to show the quantity stepper. Defaults to `true`. */
+  showQuantity?: boolean
+  /**
+   * When `true`, always render the sheet — even for products with a single
+   * variant. The single-variant short-circuit (resolving instantly without
+   * showing UI) is bypassed. Useful for flows that want a consistent
+   * confirmation step regardless of variant count. Defaults to `false`.
+   */
+  forceShow?: boolean
+}
+
+/**
+ * Shared shape describing the variant + quantity a user (or the host)
+ * picked via the native variant selector sheet. Used as the base for the
+ * success payload of every variant-picker intent
+ * (`select`, `add_to_cart`, `buy_now`).
+ *
+ * @publicDocs
+ */
+export interface ProductVariantSelection {
+  /** The GID of the variant the user picked. */
+  productVariantId: string
+  /** The full variant the user picked. */
+  variant: ProductVariant
+  /** The quantity the user chose in the stepper. `1` when the stepper is hidden. */
+  quantity: number
+  /**
+   * Indicates whether the user actively picked a variant in the sheet
+   * (`'user'`) or whether the host resolved the selection automatically
+   * without showing UI (`'auto'`).
+   *
+   * `'auto'` is returned when the product has a single selectable variant
+   * and `forceShow` is `false` (the default). `'user'` is returned in every
+   * other success case — i.e. the sheet was rendered and the user tapped
+   * the CTA.
+   */
+  source: 'auto' | 'user'
+}
+
+/**
+ * Successful payload returned from `select:shopify/ProductVariant`. The
+ * intent result is `{code: 'ok', data: SelectProductVariantResult}` on
+ * success; `{code: 'closed'}` when the user dismisses the sheet.
+ *
+ * The `outcome` discriminator is single-valued today and is preserved for
+ * forward-compatibility — the variant-picker intents (`add_to_cart`,
+ * `buy_now`) use the same field to discriminate between multiple success
+ * outcomes (e.g. cart added vs. navigated to PDP), and minis can use a
+ * single switch over `data.outcome` to handle every intent.
+ *
+ * @publicDocs
+ */
+export interface SelectProductVariantResult extends ProductVariantSelection {
+  /** Discriminator. Currently always `'selected'`. */
+  outcome: 'selected'
+}
+
 // ---------------------------------------------------------------------------
 // Intent Registry
 // ---------------------------------------------------------------------------
@@ -67,6 +165,12 @@ export interface IntentDefinitions {
     data: TryOnProductParams
     result: TryOnProductResponse
   }
+  selectProductVariant: {
+    action: 'select'
+    type: 'shopify/ProductVariant'
+    data: SelectProductVariantParams
+    result: SelectProductVariantResult
+  }
 }
 
 export type IntentKey = keyof IntentDefinitions
@@ -81,6 +185,7 @@ export type IntentKey = keyof IntentDefinitions
 export const INTENT_REGISTRY = {
   createUserImage: {action: 'create', type: 'shop/UserImage'},
   tryOnProduct: {action: 'try_on', type: 'shopify/Product'},
+  selectProductVariant: {action: 'select', type: 'shopify/ProductVariant'},
 } as const satisfies {
   [K in IntentKey]: {
     action: IntentDefinitions[K]['action']

package/src/types/product.ts

@@ -13,6 +13,17 @@ export interface ProductImage {
   thumbhash?: string | null
 }
 
+/**
+ * A single (name, value) pair that identifies which value of a product option
+ * a variant corresponds to. E.g. `{name: 'Color', value: 'Green'}`.
+ *
+ * @publicDocs
+ */
+export interface ProductSelectedOption {
+  name: string
+  value: string
+}
+
 export interface ProductVariant {
   id: string
   title: string
@@ -24,6 +35,13 @@ export interface ProductVariant {
    * expose stock state.
    */
   availableForSale: boolean
+  /**
+   * The (name, value) pairs of product options this variant corresponds to.
+   * E.g. `[{name: 'Color', value: 'Green'}, {name: 'Size', value: 'M'}]`.
+   * Optional for backwards compatibility with variants returned by older
+   * Shop app hosts; treat as `[]` when undefined.
+   */
+  selectedOptions?: ProductSelectedOption[]
   image?: ProductImage | null
   price: Money
   compareAtPrice?: Money | null
@@ -84,6 +102,21 @@ export type ProductMedia =
       alt: string | null
     }
 
+/**
+ * A configurable product option (e.g. Color, Size) and the set of values it
+ * accepts across all variants.
+ *
+ * @publicDocs
+ */
+export interface ProductOption {
+  /** Globally-unique identifier for the option. */
+  id?: string
+  /** The display name of the option. E.g. `Color`. */
+  name: string
+  /** All possible values for the option across variants. E.g. `['Red', 'Blue']`. */
+  values: string[]
+}
+
 export interface Product {
   id: string
   title: string
@@ -96,6 +129,12 @@ export interface Product {
   defaultVariantId: string
   isFavorited: boolean
   variants?: ProductVariant[]
+  /**
+   * The product's configurable options (e.g. Color, Size). Optional for
+   * backwards compatibility with products returned by older Shop app hosts;
+   * treat as `[]` when undefined.
+   */
+  options?: ProductOption[]
   featuredImage?: ProductImage | null
   price: Money
   compareAtPrice?: Money | null