@shopify/shop-minis-platform 0.23.0 → 0.25.0

package/package.json

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

package/src/actions/intent-definitions.ts

@@ -142,23 +142,49 @@ export interface ProductVariantSelection {
   source: 'auto' | 'user'
 }
 
+/**
+ * Variant chosen by the user from the sheet's option pickers.
+ */
+export interface SelectVariantSelectedResult extends ProductVariantSelection {
+  /** Discriminator. The user picked a variant and confirmed. */
+  outcome: 'selected'
+}
+
+/**
+ * Returned when the user taps the product header inside the sheet to go
+ * to the PDP instead of confirming a selection. The sheet is dismissed,
+ * the user has navigated to the PDP, and no selection is reported back.
+ */
+export interface SelectVariantNavigatedToProductResult {
+  /** Discriminator. The user navigated to the PDP from the sheet. */
+  outcome: 'navigated_to_product'
+  /** GID of the product the host navigated to. */
+  productId: string
+  /**
+   * GID of the variant that was highlighted when the user tapped to
+   * navigate. The PDP opens scoped to this variant.
+   */
+  productVariantId: string
+}
+
 /**
  * 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.
+ * Discriminate via `data.outcome`:
+ * - `'selected'` — the user picked a variant from the sheet; the full
+ *   selection (`productVariantId`, `quantity`, `variant`, `source`) is
+ *   present.
+ * - `'navigated_to_product'` — the user tapped the sheet's product
+ *   header and the host took them to the PDP. Only `productId` and
+ *   `productVariantId` (the highlighted variant) are present.
  *
  * @publicDocs
  */
-export interface SelectProductVariantResult extends ProductVariantSelection {
-  /** Discriminator. Currently always `'selected'`. */
-  outcome: 'selected'
-}
+export type SelectProductVariantResult =
+  | SelectVariantSelectedResult
+  | SelectVariantNavigatedToProductResult
 
 // ---------------------------------------------------------------------------
 // Add to Cart Intent — add_to_cart:shopify/ProductVariant
@@ -232,16 +258,34 @@ export interface AddToCartAddedResult extends ProductVariantSelection {
 }
 
 /**
- * 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.
+ * Returned when the user tapped the sheet's product header to view the
+ * PDP instead of adding to cart. The sheet is dismissed and the user is
+ * now on the PDP.
  */
 export interface AddToCartNavigatedToProductResult {
-  /** Discriminator. The host navigated the user to the PDP instead. */
+  /** Discriminator. The user navigated to the PDP from the sheet. */
   outcome: 'navigated_to_product'
   /** GID of the product the host navigated to. */
   productId: string
+  /**
+   * GID of the variant that was highlighted when the user tapped to
+   * navigate. The PDP opens scoped to this variant.
+   */
+  productVariantId: string
+}
+
+/**
+ * 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
+ * redirected the user to the product's PDP. The mini should treat this
+ * as a successful hand-off — the cart was not modified but the shopper
+ * is now on the PDP.
+ */
+export interface AddToCartRedirectedToProductResult {
+  /** Discriminator. The host redirected the user to the PDP instead. */
+  outcome: 'redirected_to_product'
+  /** GID of the product the host redirected to. */
+  productId: string
 }
 
 /**
@@ -250,15 +294,18 @@ export interface AddToCartNavigatedToProductResult {
  * 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.
+ * - `'navigated_to_product'` — the user tapped the sheet's product
+ *   header and the host took them to the PDP. The cart was not modified.
+ * - `'redirected_to_product'` — the host could not add this product
+ *   (e.g. referral product on another merchant's storefront) and
+ *   redirected the user to the PDP. Only `productId` is present.
  *
  * @publicDocs
  */
 export type AddToCartProductVariantResult =
   | AddToCartAddedResult
   | AddToCartNavigatedToProductResult
+  | AddToCartRedirectedToProductResult
 
 // ---------------------------------------------------------------------------
 // Buy Now Intent — buy_now:shopify/ProductVariant
@@ -316,15 +363,33 @@ export interface BuyNowCheckoutOpenedResult extends ProductVariantSelection {
 }
 
 /**
- * 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.
+ * Returned when the user tapped the sheet's product header to view the
+ * PDP instead of going to checkout. The sheet is dismissed and the user
+ * is now on the PDP.
  */
 export interface BuyNowNavigatedToProductResult {
-  /** Discriminator. The host navigated the user to the PDP instead. */
+  /** Discriminator. The user navigated to the PDP from the sheet. */
   outcome: 'navigated_to_product'
   /** GID of the product the host navigated to. */
   productId: string
+  /**
+   * GID of the variant that was highlighted when the user tapped to
+   * navigate. The PDP opens scoped to this variant.
+   */
+  productVariantId: string
+}
+
+/**
+ * Returned when the product cannot be bought from the mini (e.g. referral
+ * products outside Shop's catalog) and the host instead redirected the
+ * user to the product's PDP. The mini should treat this as a successful
+ * hand-off — no checkout was created but the shopper is now on the PDP.
+ */
+export interface BuyNowRedirectedToProductResult {
+  /** Discriminator. The host redirected the user to the PDP instead. */
+  outcome: 'redirected_to_product'
+  /** GID of the product the host redirected to. */
+  productId: string
 }
 
 /**
@@ -333,15 +398,18 @@ export interface BuyNowNavigatedToProductResult {
  * 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.
+ * - `'navigated_to_product'` — the user tapped the sheet's product
+ *   header and the host took them to the PDP. No checkout was created.
+ * - `'redirected_to_product'` — the host could not buy this product
+ *   (e.g. referral product on another merchant's storefront) and
+ *   redirected the user to the PDP. Only `productId` is present.
  *
  * @publicDocs
  */
 export type BuyNowProductVariantResult =
   | BuyNowCheckoutOpenedResult
   | BuyNowNavigatedToProductResult
+  | BuyNowRedirectedToProductResult
 
 // ---------------------------------------------------------------------------
 // Intent Registry