@moonbase.sh/storefront 3.10.0 → 3.11.0

package/README.md

@@ -496,10 +496,43 @@ Available events include:
 - `downloaded-product`
 - `activated-product`
 - `added-to-cart`
+- `coupon-rejected`
 - `checkout-initiated`
+- `checkout-billing-details-added`
+- `checkout-coupon-applied`
+- `checkout-coupon-removed`
+- `checkout-payment-started`
+- `checkout-payment-failed`
 - `checkout-closed`
 - `checkout-completed`
 
+The checkout's own progress, from billing details to payment, is reported only by the checkout
+that opens on your page:
+
+- `checkout-billing-details-added` fires each time the buyer saves their billing details.
+- `checkout-payment-started` fires for each attempt to pay, and is followed by
+  `checkout-payment-failed` or `checkout-completed`.
+- `checkout-payment-failed` carries `error`, with `reason` and `paymentMethod` (such as `card`).
+  The reason is one of `Declined` (by the card issuer or fraud screening: try another card),
+  `AuthenticationFailed` (3-D Secure not passed), `CardDetails` (a wrong number, security code or
+  postcode, or an expired card), `ProcessingError` (trying again may work) or `Other`. The card
+  issuer's own decline code is never passed on. The checkout stays open for the buyer to try again.
+- `checkout-coupon-applied` and `checkout-coupon-removed` carry the `code`. A code the checkout
+  refuses fires `coupon-rejected`, with the `message` the buyer saw.
+- `checkout-closed` carries `completed`, and `checkoutOrder`, the order the checkout was open for.
+  Its `order` is the cart, which for a direct purchase is a different order.
+
+During a full-page redirect to the hosted checkout (`checkout.redirect`, and on phones by default)
+your page is not loaded, so only `checkout-completed` reaches it, once the buyer is back. To follow
+every checkout, hosted included, subscribe a webhook to `OrderCheckoutInitiated` (billing details
+saved) and `OrderPaymentFailed`.
+
+```ts
+Moonbase.on(MoonbaseEvent.CheckoutPaymentFailed, ({ order, error }) => {
+  console.log(`Payment for ${order.id} failed: ${error.reason}`)
+})
+```
+
 `signed-in` and `signed-up` fire on the page where the customer signs in, including through a link in an email. `signed-out` also fires when the session ends without anyone signing out on the page: in another tab, or elsewhere (for example a password change on another device), which the widget finds out when it next renews the token.
 
 ## Calling your own API

package/dist/moonbase.d.ts

@@ -1,5 +1,6 @@
 import { ActivationRequestFulfillmentType } from '@moonbase.sh/vue';
 import { CartItem } from '@moonbase.sh/vue';
+import { CheckoutPaymentFailure } from '@moonbase.sh/vue';
 import { CheckoutRedirectMode } from '@moonbase.sh/vue';
 import { CurrencyDisplay } from '@moonbase.sh/vue';
 import { Download } from '@moonbase.sh/vue';
@@ -28,10 +29,7 @@ export declare interface GoogleAnalyticsConfig {
 }
 
 export declare interface GoogleTagManagerConfig {
-    /**
-     * Informational/reserved. GTM containers read from `window.dataLayer`
-     * regardless of which container loaded them, so this is not used at runtime.
-     */
+    /** Not used: GTM reads `window.dataLayer` whichever container loaded it. */
     containerId?: string;
 }
 
@@ -88,6 +86,11 @@ export declare enum MoonbaseEvent {
     AddedToCart = "added-to-cart",
     CouponRejected = "coupon-rejected",
     CheckoutInitiated = "checkout-initiated",
+    CheckoutBillingDetailsAdded = "checkout-billing-details-added",
+    CheckoutCouponApplied = "checkout-coupon-applied",
+    CheckoutCouponRemoved = "checkout-coupon-removed",
+    CheckoutPaymentStarted = "checkout-payment-started",
+    CheckoutPaymentFailed = "checkout-payment-failed",
     CheckoutClosed = "checkout-closed",
     CheckoutCompleted = "checkout-completed"
 }
@@ -166,6 +169,11 @@ export declare interface MoonbaseEventArgs {
     };
     [MoonbaseEvent.CouponRejected]: {
         code: string;
+        /**
+         * Why, as the buyer was told, when the checkout refused a code typed into
+         * it. Absent for a code passed to the `purchase` intent.
+         */
+        message?: string;
         user?: User | null;
     };
     [MoonbaseEvent.CheckoutInitiated]: {
@@ -173,8 +181,61 @@ export declare interface MoonbaseEventArgs {
         total: Money;
         user?: User | null;
     };
+    /**
+     * The buyer saved their billing details in the checkout. Sent again each time
+     * they change them. Only from the checkout that opens on the page, not the
+     * hosted one a redirect goes to.
+     */
+    [MoonbaseEvent.CheckoutBillingDetailsAdded]: {
+        order: OpenOrder;
+        user?: User | null;
+    };
+    /** The buyer applied a coupon code in the checkout. On-page checkout only. */
+    [MoonbaseEvent.CheckoutCouponApplied]: {
+        order: OpenOrder;
+        code: string;
+        user?: User | null;
+    };
+    /** The buyer took a coupon off the order in the checkout. On-page checkout only. */
+    [MoonbaseEvent.CheckoutCouponRemoved]: {
+        order: OpenOrder;
+        code: string;
+        user?: User | null;
+    };
+    /**
+     * The buyer submitted payment in the checkout. Each attempt is followed by
+     * `checkout-payment-failed` or `checkout-completed`. On-page checkout only.
+     */
+    [MoonbaseEvent.CheckoutPaymentStarted]: {
+        order: OpenOrder;
+        user?: User | null;
+    };
+    /**
+     * An attempt to pay failed: a declined card, or a 3-D Secure check the buyer
+     * did not pass. The checkout stays open for them to try again. `error.reason`
+     * says what kind of failure it was; the card issuer's own decline code is
+     * never passed on. On-page checkout only: for every checkout, hosted
+     * included, subscribe a webhook to `OrderPaymentFailed`.
+     */
+    [MoonbaseEvent.CheckoutPaymentFailed]: {
+        order: OpenOrder;
+        error: CheckoutPaymentFailure;
+        user?: User | null;
+    };
     [MoonbaseEvent.CheckoutClosed]: {
+        /**
+         * The cart. For a direct purchase (the `purchase` intent, a buy button)
+         * this is not the order the checkout was for: read `checkoutOrder`.
+         */
         order: Order;
+        /** The order the checkout was open for. Absent if it closed before it loaded. */
+        checkoutOrder?: Order;
+        /**
+         * Whether the checkout completed the order before it closed, the same
+         * moment `checkout-completed` fires. An order that was paid but could not
+         * be fulfilled is not completed, and fires neither.
+         */
+        completed: boolean;
         user?: User | null;
     };
     [MoonbaseEvent.CheckoutCompleted]: {
@@ -222,6 +283,7 @@ declare class MoonbaseImpl implements MoonbaseInstance {
     redeem_voucher(parameters?: MoonbaseIntentArgs['redeem_voucher']): void;
     view_product(parameters?: MoonbaseIntentArgs['view_product']): void;
     download_product(parameters?: MoonbaseIntentArgs['download_product']): void;
+    view_release_history(parameters?: MoonbaseIntentArgs['view_release_history']): void;
     activate_product(parameters?: MoonbaseIntentArgs['activate_product']): void;
     manage_subscription(parameters?: MoonbaseIntentArgs['manage_subscription']): void;
     view_cart(): void;
@@ -269,6 +331,7 @@ export declare enum MoonbaseIntent {
     JoinGroup = "join_group",
     ViewProduct = "view_product",
     DownloadProduct = "download_product",
+    ViewReleaseHistory = "view_release_history",
     ActivateProduct = "activate_product",
     ManageSubscription = "manage_subscription",
     ViewCart = "view_cart",
@@ -349,6 +412,9 @@ export declare interface MoonbaseIntentArgs {
         version?: string;
         key?: string;
     };
+    [MoonbaseIntent.ViewReleaseHistory]: {
+        product_id: string;
+    };
     [MoonbaseIntent.ActivateProduct]: {
         token?: string;
     };
@@ -413,23 +479,10 @@ export declare interface MoonbaseOptions {
         };
     };
     /**
-     * Merchant-owned customer groups a visitor joins when they use one of these
-     * forms. Named by ID, because the API deliberately tells a storefront nothing
-     * about a group: an ID that names a group the merchant has not opened to
-     * public sign-ups is skipped in silence, so a stale one here can never fail a
-     * registration or a sale. Enrollment is therefore silent too, and there is
-     * nothing to label.
-     *
-     * `signUp` and `subscribe` can be added to per link with `mb_groups`, e.g.
-     * `?mb_intent=sign_up&mb_groups=beta,vip`. The two are unioned: the options
-     * say which lists everyone signing up through this site joins, the link adds
-     * whichever the campaign is for. A host-page `data-moonbase-form="subscribe"`
-     * form adds to `subscribe` the same way, with a field named `groups`.
-     *
-     * `checkout` is options-only. The cart outlives any one intent, and a buyer
-     * pressing the drawer's own checkout button never went through a link, so a
-     * URL-scoped group there would apply or not depending on which button they
-     * happened to press.
+     * IDs of the customer groups a visitor joins through each form. A group not open to public
+     * sign-ups is skipped silently. A link adds to `signUp` and `subscribe` with `mb_groups`
+     * (`?mb_intent=sign_up&mb_groups=beta,vip`), and a `data-moonbase-form="subscribe"` form with a
+     * `groups` field. `checkout` is set here only.
      */
     groups: {
         signUp: string[];
@@ -438,68 +491,36 @@ export declare interface MoonbaseOptions {
     };
     checkout: {
         /**
-         * Where checkout happens.
-         *
-         * - `'auto'` (default) — overlay on desktop, full-page redirect on mobile.
-         *   The redirect is what makes Apple Pay and Google Pay available: those
-         *   wallets require the *top-level* domain to be a registered payment-method
-         *   domain, which it never is when checkout runs in an iframe on the host's
-         *   own site.
-         * - `'always'` / `true` — always redirect to the hosted checkout.
-         * - `'never'` / `false` — always use the overlay, wallets included in the cost.
+         * Where checkout happens:
+         * - `'auto'` (default): an overlay on desktop, the hosted checkout on mobile.
+         * - `'always'` / `true`: always the hosted checkout.
+         * - `'never'` / `false`: always the overlay, which can't offer Apple Pay or Google Pay.
          */
         redirect: boolean | CheckoutRedirectMode;
     };
     cart: {
         quantity: 'selectable' | 'single';
         bundles: {
+            /**
+             * `'replace'` (default) takes a bundle's products out of the cart when it is added, if they are
+             * sold the same way (subscription or one-off) as the bundle. `'append'` leaves them in.
+             */
             onAdd: 'append' | 'replace';
             showProducts: boolean;
         };
         offers: {
             label: string;
             /**
-             * Apply an eligible offer to the cart line it targets without waiting for the buyer to press
-             * its upsell card. Applies to offers keyed off a single product; offers keyed off the cart as a
-             * whole have always applied themselves; see `cartWide` below.
-             *
-             * Off by default: an offer is a merchant's to give, and applying one unasked discounts a cart
-             * the buyer never asked to have discounted. Turn it on to close the one case the upsell cannot
-             * reach. The card is hidden once the offer's targets are in the cart, so a cart assembled in
-             * that order (target first, then the item that satisfies the offer's condition) leaves a real
-             * discount with no way of being claimed.
-             *
-             * Never adds anything to the cart, and never takes an offer the cart is still selling: an offer
-             * that names a product the buyer has not added keeps showing as a card and still takes a press,
-             * since an offer is good for one line only and spending it early would remove that card. Nor
-             * does it replace an offer a line already carries.
-             *
-             * That last part governs when an offer is taken, not where it stays. Remove one of the products
-             * that qualified an offer and it stays on the line it landed on, exactly as an offer claimed
-             * from the card would. A buyer can put a multi-target offer on one product and never add the
-             * other, so this is a cart they could have built by hand. Losing the discount because of an
-             * unrelated removal would be the surprising behaviour, not keeping it.
+             * Put an eligible single-product offer on the line it targets without the buyer pressing its
+             * card, which hides once the target is in the cart. Off by default. Never adds to the cart or
+             * replaces an offer a line already has.
              */
             autoApply: boolean;
-            /**
-             * 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.
-             */
+            /** Offers on the whole cart, such as "10% off orders over $50". They apply once the cart qualifies. */
             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.
-                 */
+                /** Show how far the cart is from the offer's threshold. `false` applies it without the meter. */
                 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.
-                 */
+                /** Label for the saving row in the cart totals. */
                 savingLabel: string;
             };
         };
@@ -507,19 +528,10 @@ export declare interface MoonbaseOptions {
             quantity: 'selectable' | 'single';
         };
         /**
-         * The smallest order the cart will check out, keyed by currency code in major units, e.g.
-         * `{ USD: 25, EUR: 25 }`. Below it the checkout button gives way to a meter showing how much
-         * further the buyer has to go, and the `checkout` intent opens the cart instead of checking out.
-         *
-         * Per currency because the API picks each visitor's currency and the widget never converts one
-         * into another. A currency with no entry has no minimum, so a buyer priced in one you did not
-         * list checks out as before.
-         *
-         * Measured on the cart's own Total: after product discounts and offers, before coupons and tax.
-         * A cart of nothing but free items is exempt, since there is no purchase to hold back.
-         *
-         * The widget enforces this, not the API: `purchase()` and checkouts built outside the widget are
-         * not held to it. A value you pass replaces the previous one outright; pass `{}` to remove it.
+         * The smallest order the cart checks out, per currency in major units, e.g. `{ USD: 25, EUR: 25 }`.
+         * Measured after discounts and offers, before coupons and tax. A currency left out has no
+         * minimum, and a cart of only free items is exempt. `purchase()` is not held to it. Pass `{}` to
+         * remove it.
          */
         minimumTotal: Record<string, number>;
     };
@@ -533,22 +545,13 @@ export declare interface MoonbaseOptions {
     };
     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`.
+         * Show running promotions as a banner or popup. Turn off to render them yourself from the
+         * `promotion-shown` event or `usePromotions()` 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.
-         */
+        /** Where the banner goes when the page has no `[data-moonbase-promotion]` container. */
         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.
-         */
+        /** Label for dismissing a promotion, and its only action when it has no link. */
         dismissLabel: string;
     };
     theme: {
@@ -559,19 +562,11 @@ export declare interface MoonbaseOptions {
         };
         fonts: {
             /**
-             * Font for headings and display text. Either a built-in family, which the widget loads from
-             * Moonbase's own asset host, or one of:
-             *
-             * - `'inherit'` — render in whatever font the host page uses at that spot. Loads nothing.
-             * - `'system'` — the widget's own system stack. Loads nothing.
-             * - `{ family }` — name any family the page already loads.
-             * - `{ family, stylesheet }` — name any family and the URL to load the face from.
-             *
-             * The distinction that catches people out: `'Inter'` means "load Inter for me",
-             * `{ family: 'Inter' }` means "the family is Inter, I already load it".
+             * A built-in family the widget loads (`'Inter'`), `'inherit'` for the page's font, `'system'`,
+             * `{ family }` for one the page already loads, or `{ family, stylesheet }` to load one.
              */
             heading: MoonbaseFont;
-            /** As `heading`, for body copy. Either slot accepts any of the built-in families. */
+            /** As `heading`, for body text. */
             body: MoonbaseFont;
         };
         corners: 'sharp' | 'soft' | 'round';
@@ -579,44 +574,17 @@ export declare interface MoonbaseOptions {
         cards: 'outlined' | 'shadow' | 'white';
     };
     pricing: {
-        /**
-         * How to render a price that lands on a whole number.
-         * - `'auto'` (default) drops the fraction entirely, so `10` renders `$10`.
-         * - `'always'` keeps the currency's own fraction digits, so `10` renders
-         *   `$10.00` — and still `¥1000` for zero-decimal currencies like JPY.
-         *
-         * Prices that aren't whole are unaffected; they always show their decimals.
-         */
+        /** Whole prices: `'auto'` (default) shows `$10`, `'always'` shows `$10.00`. */
         trailingZeros: TrailingZeros;
-        /**
-         * Which marker identifies the currency. Taking `10` USD read in a British
-         * locale:
-         * - `'narrowSymbol'` (default) renders the shortest symbol, `$10`.
-         * - `'symbol'` renders the locale's usual symbol, `US$10`.
-         * - `'code'` renders the ISO 4217 code, `USD 10`.
-         * - `'name'` spells it out in the visitor's language, `10 US dollars`.
-         *
-         * The symbol and its placement always follow the visitor's own locale;
-         * this only picks which of the four forms to use.
-         */
+        /** `'narrowSymbol'` (default) `$10`, `'symbol'` `US$10`, `'code'` `USD 10`, `'name'` `10 US dollars`. */
         currencyDisplay: CurrencyDisplay;
     };
     target: HTMLElement | undefined;
-    /**
-     * When the host page declares a fixed-width mobile viewport (e.g. Wix's
-     * legacy `<meta name="viewport" content="width=320, ...">`), the browser
-     * upscales every CSS pixel to fit the device. Set this to `true` to opt out
-     * of the widget's automatic counter-scaling and match the host's density.
-     */
+    /** Turn off the widget's scaling on pages with a fixed-width mobile viewport, such as Wix's `width=320`. */
     disableViewportCompensation: boolean;
     /**
-     * Opt in to built-in forwarding of storefront events to common
-     * marketing/analytics SDKs. Each provider is enabled by supplying its
-     * config object. The widget never loads SDK scripts — it only forwards
-     * to globals the host page has already initialised (e.g. `window.fbq`,
-     * `window.gtag`, `window.dataLayer`, `window.klaviyo`, `window.ttq`).
-     * If a provider's global is missing at the time of an event, the
-     * forwarding is a silent no-op.
+     * Forward storefront events to analytics SDKs the page already loads (`fbq`, `gtag`,
+     * `dataLayer`, `klaviyo`, `ttq`). Pass a provider's config to turn it on.
      */
     integrations: IntegrationsConfig;
 }