@shopify/shop-minis-platform 0.20.0 → 0.22.0

package/package.json

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

package/src/actions/intent-definitions.ts

@@ -148,6 +148,189 @@ export interface SelectProductVariantResult extends ProductVariantSelection {
   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
+
+// ---------------------------------------------------------------------------
+// Buy Now Intent — buy_now:shopify/ProductVariant
+// ---------------------------------------------------------------------------
+
+/**
+ * Data payload for the `buy_now:shopify/ProductVariant` intent.
+ *
+ * Sends the user to express checkout for a variant, bypassing the cart. If
+ * `productVariantId` is omitted (or `forceShow` is `true`), the host opens
+ * the same native variant selector sheet as the other variant intents — the
+ * user picks a variant and quantity, and the host then creates the checkout
+ * on confirm.
+ *
+ * For products outside Shop's catalog (referral products), the host
+ * navigates the user to the product's PDP instead.
+ *
+ * @publicDocs
+ */
+export interface BuyNowProductVariantParams {
+  /** The GID of the product. E.g. `gid://shopify/Product/123`. */
+  productId: string
+  /**
+   * The GID of the variant to buy. When provided, the host creates the
+   * checkout directly without showing the sheet. Omit to let the user pick.
+   */
+  productVariantId?: string
+  /** Quantity to buy. Defaults to `1`. */
+  quantity?: number
+  /** Discount code to apply to the checkout. */
+  discountCode?: string
+  /** Allow-list of variant GIDs surfaced in the sheet. */
+  includedProductVariantGIDs?: string[]
+  /** Variant initially highlighted in the picker. */
+  initialVariantId?: string
+  /** Initial quantity in the stepper. Defaults to `quantity ?? 1`. */
+  initialQuantity?: number
+  /** Max quantity selectable in the stepper. */
+  maxQuantity?: number
+  /** Whether to show the quantity stepper. Defaults to `true`. */
+  showQuantity?: boolean
+  /**
+   * When `true`, always render the sheet — even for single-variant products
+   * or when `productVariantId` is supplied. Defaults to `false`.
+   */
+  forceShow?: boolean
+}
+
+/**
+ * Checkout opened for a concrete variant by `buy_now:shopify/ProductVariant`.
+ */
+export interface BuyNowCheckoutOpenedResult extends ProductVariantSelection {
+  /** Discriminator. The host opened express checkout for a variant. */
+  outcome: 'checkout_opened'
+}
+
+/**
+ * Returned when the product cannot be bought 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.
+ */
+export interface BuyNowNavigatedToProductResult {
+  /** 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 `buy_now:shopify/ProductVariant`.
+ *
+ * Discriminate via `data.outcome`:
+ * - `'checkout_opened'` — express checkout opened for a concrete variant;
+ *   selection fields (`productVariantId`, `quantity`, `source`) are present.
+ * - `'navigated_to_product'` — the host could not buy 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 BuyNowProductVariantResult =
+  | BuyNowCheckoutOpenedResult
+  | BuyNowNavigatedToProductResult
+
 // ---------------------------------------------------------------------------
 // Intent Registry
 // ---------------------------------------------------------------------------
@@ -171,6 +354,18 @@ export interface IntentDefinitions {
     data: SelectProductVariantParams
     result: SelectProductVariantResult
   }
+  addToCartProductVariant: {
+    action: 'add_to_cart'
+    type: 'shopify/ProductVariant'
+    data: AddToCartProductVariantParams
+    result: AddToCartProductVariantResult
+  }
+  buyNowProductVariant: {
+    action: 'buy_now'
+    type: 'shopify/ProductVariant'
+    data: BuyNowProductVariantParams
+    result: BuyNowProductVariantResult
+  }
 }
 
 export type IntentKey = keyof IntentDefinitions
@@ -186,6 +381,14 @@ 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',
+  },
+  buyNowProductVariant: {
+    action: 'buy_now',
+    type: 'shopify/ProductVariant',
+  },
 } as const satisfies {
   [K in IntentKey]: {
     action: IntentDefinitions[K]['action']