@shopify/shop-minis-platform 0.21.0 → 0.23.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.23.0",
   "description": "Shared type definitions for Shop Minis Platform",
   "main": "src/index.ts",
   "exports": {

package/src/actions/intent-definitions.ts

@@ -91,8 +91,20 @@ export interface SelectProductVariantParams {
    * inventory (or unbounded when stock is not tracked).
    */
   maxQuantity?: number
-  /** Whether to show the quantity stepper. Defaults to `true`. */
+  /**
+   * Whether to show the quantity stepper. Defaults to `false` for the
+   * `select` intent (selection is informational; quantity is rarely
+   * relevant). Pass `true` to opt into the stepper.
+   */
   showQuantity?: boolean
+  /**
+   * When `true`, the sheet's confirm CTA stays enabled even for a sold-out
+   * variant — the host hands the selection back to the mini without
+   * touching the cart. Defaults to `true` for the `select` intent so flows
+   * like “notify me when back in stock” can pick a sold-out variant. Pass
+   * `false` to restore the cart-style sold-out guard.
+   */
+  allowOutOfStockSelection?: boolean
   /**
    * When `true`, always render the sheet — even for products with a single
    * variant. The single-variant short-circuit (resolving instantly without
@@ -248,6 +260,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 +372,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 +397,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']