@moonbase.sh/storefront 3.9.0 → 3.11.0

package/README.md

@@ -496,10 +496,82 @@ 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
+
+`Moonbase.getAccessToken()` resolves to the signed-in customer's access token, or `null` when nobody is signed in. Send it to your own API to act on the customer's behalf. It's renewed first when it's about to run out, so call it for each request rather than keeping a copy.
+
+```ts
+const token = await Moonbase.getAccessToken()
+const response = await fetch('https://api.example.com/presets', {
+  headers: token ? { Authorization: `Bearer ${token}` } : {},
+})
+```
+
+The token is a JWT signed with your account's key. Verify it on your server against the JWK Set at `https://<account-id>.moonbase.sh/api/key/jwks`, and check all of:
+
+- the `typ` header is `at+jwt` and the algorithm is `RS256`
+- the issuer (`iss`) is your Account ID
+- the audience (`aud`) is `https://moonbase.sh`
+- the expiry (`exp`) is present and hasn't passed
+
+License tokens are signed with the same key and issuer, so a check that skips the audience or the expiry accepts a license file as a sign-in. The customer's ID is the `sub` claim. With [jose](https://github.com/panva/jose):
+
+```ts
+import { createRemoteJWKSet, jwtVerify } from 'jose'
+
+const jwks = createRemoteJWKSet(new URL('https://acme.moonbase.sh/api/key/jwks'))
+
+const { payload } = await jwtVerify(token, jwks, {
+  typ: 'at+jwt',
+  algorithms: ['RS256'],
+  issuer: 'acme',
+  audience: 'https://moonbase.sh',
+  requiredClaims: ['exp'],
+})
+// payload.sub is the customer's ID
+```
+
+Don't read the widget's `localStorage` entry yourself: it holds the refresh token as well, which must never leave the browser.
+
 ## Integrations
 
 The widget can forward its commerce and auth events to common marketing/analytics SDKs without any extra glue code. Enable a provider by passing its config in `integrations`:

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]: {
@@ -202,6 +263,7 @@ declare class MoonbaseImpl implements MoonbaseInstance {
     setup(url: string, options?: DeepPartial<MoonbaseOptions>): Promise<void>;
     configure(options: DeepPartial<MoonbaseOptions>): void;
     on<TEvent extends MoonbaseEvent>(eventType: TEvent, callback: (event: MoonbaseEventArgs[TEvent]) => void): void;
+    getAccessToken(): Promise<string | null>;
     private handleLocationIntent;
     sign_in(parameters?: MoonbaseIntentArgs['sign_in']): void;
     sign_up(parameters?: MoonbaseIntentArgs['sign_up']): void;
@@ -221,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;
@@ -236,6 +299,13 @@ export declare type MoonbaseInstance = MoonbaseInstanceIntents & {
     setup: (url: string, options: DeepPartial<MoonbaseOptions>) => Promise<void>;
     configure: (options: DeepPartial<MoonbaseOptions>) => void;
     on: <TEvent extends MoonbaseEvent>(eventType: TEvent, callback: (event: MoonbaseEventArgs[TEvent]) => void) => void;
+    /**
+     * The signed-in customer's access token, for calling your own API on their behalf, or
+     * null when nobody is signed in. Renewed first when it is about to run out, so it is
+     * always good for at least the next half minute. Verify it on your server with your
+     * account's public key, at `/api/key/jwks` on your Moonbase address.
+     */
+    getAccessToken: () => Promise<string | null>;
 };
 
 declare type MoonbaseInstanceIntents = {
@@ -261,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",
@@ -341,6 +412,9 @@ export declare interface MoonbaseIntentArgs {
         version?: string;
         key?: string;
     };
+    [MoonbaseIntent.ViewReleaseHistory]: {
+        product_id: string;
+    };
     [MoonbaseIntent.ActivateProduct]: {
         token?: string;
     };
@@ -405,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[];
@@ -430,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;
             };
         };
@@ -499,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>;
     };
@@ -525,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: {
@@ -551,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';
@@ -571,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;
 }