@shopify/shop-minis-platform 0.19.0 → 0.21.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.21.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,202 @@ 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'
+}
+
+// ---------------------------------------------------------------------------
+// Add to Cart Intent — add_to_cart:shopify/ProductVariant
+// ---------------------------------------------------------------------------
+
+/**
+ * Data payload for the `add_to_cart:shopify/ProductVariant` intent.
+ *
+ * Adds a variant to the user's cart. If `productVariantId` is omitted (or
+ * `forceShow` is `true`), the host opens the same native variant selector
+ * sheet as `select:shopify/ProductVariant` first — the user picks a variant
+ * and quantity, and the host then performs the add-to-cart on confirm.
+ *
+ * For products outside Shop's catalog (referral products), the host
+ * navigates the user to the product's PDP instead of adding to cart.
+ *
+ * @publicDocs
+ */
+export interface AddToCartProductVariantParams {
+  /**
+   * The GID of the product. E.g. `gid://shopify/Product/123`.
+   */
+  productId: string
+  /**
+   * The GID of the variant to add. When provided, the host adds it
+   * directly without showing the sheet. Omit to let the user pick.
+   */
+  productVariantId?: string
+  /** Quantity to add. Defaults to `1`. */
+  quantity?: number
+  /**
+   * Discount codes to apply to the cart when adding.
+   */
+  discountCodes?: 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. Ignored when `productVariantId` is supplied.
+   */
+  includedProductVariantGIDs?: string[]
+  /**
+   * If present, the GID of the variant that should be initially highlighted
+   * in the sheet. Defaults to the product's default variant. Ignored when
+   * `productVariantId` is supplied.
+   */
+  initialVariantId?: string
+  /** Initial quantity displayed in the stepper. Defaults to `quantity ?? 1`. */
+  initialQuantity?: number
+  /**
+   * Maximum quantity selectable in the stepper. Defaults to the variant's
+   * `quantityAvailable` (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 or when `productVariantId` is supplied. Bypasses the
+   * single-variant short-circuit so the mini gets a consistent confirmation
+   * step. Defaults to `false`.
+   */
+  forceShow?: boolean
+}
+
+/**
+ * Variant added to the cart by `add_to_cart:shopify/ProductVariant`.
+ */
+export interface AddToCartAddedResult extends ProductVariantSelection {
+  /** Discriminator. The host added a concrete variant to the cart. */
+  outcome: 'added_to_cart'
+}
+
+/**
+ * Returned when the product cannot be added to the cart from the mini
+ * (e.g. referral products outside Shop's catalog) and the host instead
+ * sent the user to the product's PDP. The mini should treat this as a
+ * successful hand-off — the shopper is now on the PDP.
+ */
+export interface AddToCartNavigatedToProductResult {
+  /** Discriminator. The host navigated the user to the PDP instead. */
+  outcome: 'navigated_to_product'
+  /** GID of the product the host navigated to. */
+  productId: string
+}
+
+/**
+ * Successful payload returned from `add_to_cart:shopify/ProductVariant`.
+ *
+ * Discriminate via `data.outcome`:
+ * - `'added_to_cart'` — a concrete variant was added; selection fields
+ *   (`productVariantId`, `quantity`, `source`) are present.
+ * - `'navigated_to_product'` — the host could not add this product (e.g.
+ *   referral product on another merchant's storefront) and instead sent
+ *   the user to the PDP. Only `productId` is present.
+ *
+ * @publicDocs
+ */
+export type AddToCartProductVariantResult =
+  | AddToCartAddedResult
+  | AddToCartNavigatedToProductResult
+
 // ---------------------------------------------------------------------------
 // Intent Registry
 // ---------------------------------------------------------------------------
@@ -67,6 +265,18 @@ export interface IntentDefinitions {
     data: TryOnProductParams
     result: TryOnProductResponse
   }
+  selectProductVariant: {
+    action: 'select'
+    type: 'shopify/ProductVariant'
+    data: SelectProductVariantParams
+    result: SelectProductVariantResult
+  }
+  addToCartProductVariant: {
+    action: 'add_to_cart'
+    type: 'shopify/ProductVariant'
+    data: AddToCartProductVariantParams
+    result: AddToCartProductVariantResult
+  }
 }
 
 export type IntentKey = keyof IntentDefinitions
@@ -81,6 +291,11 @@ 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'},
+  addToCartProductVariant: {
+    action: 'add_to_cart',
+    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