@moonbase.sh/storefront 2.8.0 → 2.9.0

package/README.md

@@ -132,8 +132,76 @@ locale — this only chooses between the four forms.
 Both `pricing` options cover the widget's UI and your `data-moonbase-render` price
 elements. The checkout itself is rendered by Moonbase and formats its own prices.
 
+`cart.offers.cartWide` covers offers keyed off the cart as a whole, such as "10% off orders
+over $50", rather than off a single product. These apply themselves the moment the
+cart qualifies, so there is nothing for the buyer to press. While the cart is short
+of the threshold the widget shows a meter and how much further to go; once it
+qualifies, the saving appears as its own row above the total.
+
+```ts
+Moonbase.configure({
+  cart: {
+    offers: {
+      cartWide: {
+        showProgress: true,
+        savingLabel: 'You save',
+      },
+    },
+  },
+})
+```
+
+Set `showProgress` to `false` to let such an offer apply silently: the saving still
+shows in the totals, the nudge does not. With no cart-wide offer configured on your
+storefront, the meter never renders either way. `savingLabel` names the saving row
+in the cart totals.
+
 You can also control where the widget mounts by providing `target`.
 
+## Promotions
+
+When you run a sale across your catalogue, the widget surfaces it on its own — as a
+banner, a popup, or both, depending on what you asked for when you set the promotion
+up in Moonbase. Nothing to wire in: the sale appears while it is live and to the
+shoppers it applies to, and disappears when it ends.
+
+Once a shopper dismisses a promotion it stays dismissed in that browser, for as long
+as the promotion runs. Editing the campaign doesn't bring it back — a shopper who has
+turned a sale away isn't asked again. Start a new promotion to reach them again.
+
+The two surfaces are tracked separately, so closing the popup leaves the banner up as
+a reminder that the sale is still on. A popup also gets a single interaction: clicking
+through to the campaign retires it for good, the same as closing it would, since it
+interrupted the shopper to ask. A banner interrupted nobody, so clicking through leaves
+it standing — only an explicit dismissal takes it down.
+
+By default the banner pins itself to the top of the viewport. Give the widget a
+container and it renders inline in your own layout instead — anywhere on the page:
+
+```html
+<div data-moonbase-promotion></div>
+```
+
+```ts
+Moonbase.configure({
+  promotions: {
+    // Set to false to render sales yourself.
+    enabled: true,
+    // 'top' | 'bottom' — only used when the page offers no container.
+    location: 'top',
+    dismissLabel: 'Dismiss',
+  },
+})
+```
+
+Where a sale leads, and the wording on the link, both come from the promotion itself —
+only the merchant running the campaign knows what it is offering. A sale with no
+destination set shows the dismiss action as its only button.
+
+To render sales entirely yourself, turn the built-in surfaces off and listen for
+`promotion-shown`, or read them from the `usePromotions()` composable in
+`@moonbase.sh/vue`.
+
 ## Events
 
 Subscribe to widget lifecycle events with `Moonbase.on(...)`.
@@ -144,6 +212,9 @@ Available events include:
 - `signed-up`
 - `signed-out`
 - `storefront-updated`
+- `promotion-shown`
+- `promotion-clicked`
+- `promotion-dismissed`
 - `redeemed-voucher`
 - `downloaded-product`
 - `activated-product`

package/dist/moonbase.d.ts

@@ -9,6 +9,7 @@ import { Order } from '@moonbase.sh/vue';
 import { OwnedProduct } from '@moonbase.sh/vue';
 import { Storefront } from '@moonbase.sh/vue';
 import { StorefrontProduct } from '@moonbase.sh/vue';
+import { StorefrontPromotion } from '@moonbase.sh/vue';
 import { User } from '@moonbase.sh/vue';
 import { Voucher } from '@moonbase.sh/vue';
 
@@ -66,6 +67,9 @@ export declare enum MoonbaseEvent {
     SignedOut = "signed-out",
     RedeemedVoucher = "redeemed-voucher",
     StorefrontUpdated = "storefront-updated",
+    PromotionShown = "promotion-shown",
+    PromotionClicked = "promotion-clicked",
+    PromotionDismissed = "promotion-dismissed",
     DownloadedProduct = "downloaded-product",
     ActivatedProduct = "activated-product",
     AddedToCart = "added-to-cart",
@@ -93,6 +97,23 @@ export declare interface MoonbaseEventArgs {
         storefront: Storefront;
         user?: User | null;
     };
+    [MoonbaseEvent.PromotionShown]: {
+        promotion: StorefrontPromotion;
+        surface: PromotionSurface;
+        user?: User | null;
+    };
+    [MoonbaseEvent.PromotionClicked]: {
+        promotion: StorefrontPromotion;
+        surface: PromotionSurface;
+        /** Where the shopper is being sent — the promotion's own call-to-action URL. */
+        url: string;
+        user?: User | null;
+    };
+    [MoonbaseEvent.PromotionDismissed]: {
+        promotion: StorefrontPromotion;
+        surface: PromotionSurface;
+        user?: User | null;
+    };
     [MoonbaseEvent.DownloadedProduct]: {
         product: OwnedProduct;
         download: Download;
@@ -335,6 +356,27 @@ export declare interface MoonbaseOptions {
         };
         offers: {
             label: string;
+            /**
+             * Offers keyed off the cart as a whole, such as "10% off orders over $50", rather than off a single
+             * product. They apply themselves the moment the cart qualifies; there is nothing for the buyer
+             * to press.
+             */
+            cartWide: {
+                /**
+                 * Show the eligibility meter in the cart: how close the cart is to the offer's threshold
+                 * while it is short, and the discount confirmed once it is not.
+                 *
+                 * Set to `false` to let the offer apply silently: the saving still shows in the totals, the
+                 * nudge does not. With no such offer configured the meter never renders either way.
+                 */
+                showProgress: boolean;
+                /**
+                 * Label for the saving row in the cart totals, above `Total`. Kept in the widget's own voice
+                 * rather than taking the offer's name, so the totals column can't be pushed around by
+                 * merchant-length copy.
+                 */
+                savingLabel: string;
+            };
         };
         leadMagnets: {
             quantity: 'selectable' | 'single';
@@ -348,6 +390,26 @@ export declare interface MoonbaseOptions {
             label: string;
         };
     };
+    promotions: {
+        /**
+         * Whether to render the sales a merchant is running. When a promotion is live, the widget
+         * surfaces it as a banner and/or a popup depending on what the merchant asked for. Turn this
+         * off to render the campaign yourself from `Moonbase.on('promotion-shown', …)` or the
+         * `usePromotions()` composable in `@moonbase.sh/vue`.
+         */
+        enabled: boolean;
+        /**
+         * Where the banner sits when the host page has no `[data-moonbase-promotion]` container for
+         * it. Ignored when one exists — then the banner renders inline, wherever you put it.
+         */
+        location: 'top' | 'bottom';
+        /**
+         * The label on the dismiss action, and the primary action when a sale has no destination. The
+         * wording for a sale that *does* lead somewhere comes from the promotion itself, since only
+         * the merchant knows what the campaign is offering.
+         */
+        dismissLabel: string;
+    };
     theme: {
         dark: boolean;
         colors: {
@@ -405,6 +467,9 @@ export declare interface MoonbaseOptions {
     integrations: IntegrationsConfig;
 }
 
+/** Which surface a promotion was rendered on. */
+export declare type PromotionSurface = 'banner' | 'popup';
+
 export declare interface TikTokPixelConfig {
     pixelId: string;
 }