@moonbase.sh/storefront 3.2.0 → 3.4.0

package/README.md

@@ -83,7 +83,7 @@ Moonbase.checkout()
 Moonbase.view_products()
 ```
 
-All intents are snake_case methods on the `Moonbase` instance (for example `view_product`, `manage_subscription`, `redeem_voucher`).
+All intents are snake_case methods on the `Moonbase` instance (for example `view_product`, `manage_subscription`, `redeem_voucher`, `join_group`).
 
 ## Configure behavior and theme
 
@@ -140,6 +140,47 @@ A redirected buyer is always brought back to your page once they've paid, so
 The hosted checkout stays anonymous for the trip — it prefills from the order rather
 than signing the buyer into a Moonbase account, matching the overlay's behavior.
 
+### Customer groups
+
+If you keep customer lists in Moonbase and have opened one to public sign-ups,
+name it by ID and the widget enrolls people who use the matching form:
+
+```ts
+Moonbase.configure({
+  groups: {
+    signUp: ['newsletter-2026'],
+    subscribe: ['newsletter-2026'],
+    checkout: ['buyers-2026'],
+  },
+})
+```
+
+Enrollment is silent. There is no checkbox and no label, because the API
+deliberately tells a storefront nothing about a group: an ID naming a list the
+merchant has not opened to public sign-ups is skipped without a word, so a stale
+ID here can never fail somebody's registration or somebody's purchase. At most
+five groups per request are applied, and IDs are matched lowercase.
+
+`signUp` and `subscribe` can be added to per link with `mb_groups`:
+
+```html
+<a href="?mb_intent=sign_up&mb_groups=beta,vip">Join the beta</a>
+```
+
+The two are unioned rather than overridden: `configure` names the lists everyone
+signing up through your site joins, the link adds whichever the campaign is for.
+`checkout` is configuration-only, because the cart outlives any one link.
+
+For somebody who already has an account, `join_group` does it as a request of its
+own, and unlike the three above it reports whether it worked:
+
+```html
+<a href="?mb_intent=join_group&mb_group_id=beta">Join the beta list</a>
+```
+
+It signs the visitor in first if they aren't, and emits `joined-group` on
+success. Joining a list twice is not an error.
+
 ### Fonts
 
 `theme.fonts.heading` and `theme.fonts.body` each take one of:
@@ -195,8 +236,10 @@ code (`USD 10`), and `'name'` spells it out in the visitor's language
 (`10 US dollars`). The symbol and its placement still follow the visitor's own
 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.
+Both `pricing` options cover the widget's UI, your `data-moonbase-render` price
+elements, and the checkout itself: the widget passes them to Moonbase's own
+checkout page, so the prices a buyer pays are written the same way as the ones
+that got them there.
 
 `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
@@ -312,6 +355,7 @@ Available events include:
 - `promotion-clicked`
 - `promotion-dismissed`
 - `redeemed-voucher`
+- `joined-group`
 - `downloaded-product`
 - `activated-product`
 - `added-to-cart`
@@ -381,7 +425,7 @@ Moonbase.configure({ integrations: { metaPixel: undefined } })
 
 ### Data conventions
 
-Forwarded order `value` is the amount the customer pays — `total.due`, post-discount and **tax-inclusive** (no separate tax field is sent). Per-item prices are the net (post-discount) unit price. `checkout-completed` events carry the order id as a dedup key (Meta `eventID`, TikTok `event_id`, GA4/GTM `transaction_id`) so a completion isn't double-counted.
+Forwarded order `value` is the amount the customer pays — `total.due`, post-discount and **tax-inclusive** (no separate tax field is sent). Per-item prices are the net (post-discount) unit price. `checkout-initiated` is the one exception: an order has no settled total until billing details are entered, so its `value` is the cart's own post-discount total and excludes tax. `checkout-completed` events carry the order id as a dedup key (Meta `eventID`, TikTok `event_id`, GA4/GTM `transaction_id`) so a completion isn't double-counted.
 
 ### Event mapping
 

package/dist/moonbase.d.ts

@@ -1,6 +1,7 @@
 import { ActivationRequestFulfillmentType } from '@moonbase.sh/vue';
 import { CartItem } from '@moonbase.sh/vue';
 import { CheckoutRedirectMode } from '@moonbase.sh/vue';
+import { CurrencyDisplay } from '@moonbase.sh/vue';
 import { Download } from '@moonbase.sh/vue';
 import { InjectionKey } from 'vue';
 import { MarketingConsentType } from '@moonbase.sh/vue';
@@ -11,18 +12,10 @@ 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 { TrailingZeros } from '@moonbase.sh/vue';
 import { User } from '@moonbase.sh/vue';
 import { Voucher } from '@moonbase.sh/vue';
 
-/**
- * Which marker identifies the currency, for `10` USD read in a British locale:
- * - `'narrowSymbol'` (default) — the shortest symbol: `$10`.
- * - `'symbol'` — the locale's usual symbol, disambiguated where it needs to be: `US$10`.
- * - `'code'` — the ISO 4217 code: `USD 10`.
- * - `'name'` — the currency spelled out in the visitor's language: `10 US dollars`.
- */
-declare type CurrencyDisplay = 'narrowSymbol' | 'symbol' | 'code' | 'name';
-
 declare type DeepPartial<T> = T extends object ? {
     [P in keyof T]?: T[P] extends HTMLElement | undefined ? T[P] : DeepPartial<T[P]>;
 } : T;
@@ -83,6 +76,7 @@ export declare enum MoonbaseEvent {
     SignedUp = "signed-up",
     SignedOut = "signed-out",
     RedeemedVoucher = "redeemed-voucher",
+    JoinedGroup = "joined-group",
     StorefrontUpdated = "storefront-updated",
     PromotionShown = "promotion-shown",
     PromotionClicked = "promotion-clicked",
@@ -110,6 +104,11 @@ export declare interface MoonbaseEventArgs {
         voucher: Voucher;
         user: User;
     };
+    [MoonbaseEvent.JoinedGroup]: {
+        /** The group's ID. The API never tells a storefront a group's name. */
+        groupId: string;
+        user: User;
+    };
     [MoonbaseEvent.StorefrontUpdated]: {
         storefront: Storefront;
         user?: User | null;
@@ -196,6 +195,7 @@ declare class MoonbaseImpl implements MoonbaseInstance {
     confirm_communication_preferences(parameters?: MoonbaseIntentArgs['confirm_communication_preferences']): void;
     manage_communication_preferences(parameters?: MoonbaseIntentArgs['manage_communication_preferences']): void;
     connect_account(parameters?: MoonbaseIntentArgs['connect_account']): void;
+    join_group(parameters?: MoonbaseIntentArgs['join_group']): void;
     view_account(): void;
     view_products(): void;
     view_subscriptions(): void;
@@ -238,6 +238,7 @@ export declare enum MoonbaseIntent {
     ViewSubscriptions = "view_subscriptions",
     RedeemVoucher = "redeem_voucher",
     ConnectAccount = "connect_account",
+    JoinGroup = "join_group",
     ViewProduct = "view_product",
     DownloadProduct = "download_product",
     ActivateProduct = "activate_product",
@@ -256,6 +257,11 @@ export declare interface MoonbaseIntentArgs {
     };
     [MoonbaseIntent.SignUp]: {
         email?: string;
+        /**
+         * Comma-separated merchant-owned group IDs to join on sign-up, added to
+         * whatever `options.groups.signUp` already names.
+         */
+        groups?: string;
     };
     [MoonbaseIntent.ForgotPassword]: {
         email?: string;
@@ -278,6 +284,11 @@ export declare interface MoonbaseIntentArgs {
     };
     [MoonbaseIntent.Subscribe]: {
         email?: string;
+        /**
+         * Comma-separated merchant-owned group IDs to join on subscribe, added to
+         * whatever `options.groups.subscribe` already names.
+         */
+        groups?: string;
     };
     [MoonbaseIntent.ConfirmCommunicationPreferences]: {
         email: string;
@@ -296,6 +307,9 @@ export declare interface MoonbaseIntentArgs {
     [MoonbaseIntent.ConnectAccount]: {
         provider_id: string;
     };
+    [MoonbaseIntent.JoinGroup]: {
+        group_id: string;
+    };
     [MoonbaseIntent.ViewProduct]: {
         product_id: string;
         version?: string;
@@ -368,6 +382,29 @@ export declare interface MoonbaseOptions {
             productUpdates: boolean;
         };
     };
+    /**
+     * 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.
+     *
+     * `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.
+     */
+    groups: {
+        signUp: string[];
+        subscribe: string[];
+        checkout: string[];
+    };
     checkout: {
         /**
          * Where checkout happens.
@@ -544,12 +581,6 @@ export declare interface TikTokPixelConfig {
     pixelId: string;
 }
 
-/**
- * How a whole-number price renders: `'auto'` drops the fraction (`$10`),
- * `'always'` keeps the currency's own fraction digits (`$10.00`, `¥1000`).
- */
-declare type TrailingZeros = 'auto' | 'always';
-
 export declare const urlKey: InjectionKey<string>;
 
 export { }