@moonbase.sh/storefront 3.2.0 → 3.3.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:
@@ -312,6 +353,7 @@ Available events include:
 - `promotion-clicked`
 - `promotion-dismissed`
 - `redeemed-voucher`
+- `joined-group`
 - `downloaded-product`
 - `activated-product`
 - `added-to-cart`
@@ -381,7 +423,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

@@ -83,6 +83,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 +111,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 +202,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 +245,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 +264,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 +291,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 +314,9 @@ export declare interface MoonbaseIntentArgs {
     [MoonbaseIntent.ConnectAccount]: {
         provider_id: string;
     };
+    [MoonbaseIntent.JoinGroup]: {
+        group_id: string;
+    };
     [MoonbaseIntent.ViewProduct]: {
         product_id: string;
         version?: string;
@@ -368,6 +389,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.