@shopify/shop-minis-platform 0.21.0 → 0.22.0

package/package.json

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

package/src/actions/intent-definitions.ts

@@ -248,6 +248,89 @@ 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
 // ---------------------------------------------------------------------------
@@ -277,6 +360,12 @@ export interface IntentDefinitions {
     data: AddToCartProductVariantParams
     result: AddToCartProductVariantResult
   }
+  buyNowProductVariant: {
+    action: 'buy_now'
+    type: 'shopify/ProductVariant'
+    data: BuyNowProductVariantParams
+    result: BuyNowProductVariantResult
+  }
 }
 
 export type IntentKey = keyof IntentDefinitions
@@ -296,6 +385,10 @@ export const INTENT_REGISTRY = {
     action: 'add_to_cart',
     type: 'shopify/ProductVariant',
   },
+  buyNowProductVariant: {
+    action: 'buy_now',
+    type: 'shopify/ProductVariant',
+  },
 } as const satisfies {
   [K in IntentKey]: {
     action: IntentDefinitions[K]['action']