@moonbase.sh/storefront 2.4.2 → 2.5.0

package/README.md

@@ -45,14 +45,14 @@ When you load the widget via the CDN script tag:
 
 When you import from npm (`import Moonbase from '@moonbase.sh/storefront'`), `setup` still needs the DOM to be available before it runs, since there is no loader in that path.
 
-## Testing pre-release builds with `?mb_version=`
+## Testing pre-release builds with `?mb_storefront_version=`
 
-The CDN loader recognises an `?mb_version=` query parameter for opting into a non-default storefront build on a per-page-load basis. This is intended for testing pre-release changes on a live merchant site without changing the embed code.
+The CDN loader recognises an `?mb_storefront_version=` query parameter for opting into a non-default storefront build on a per-page-load basis. This is intended for testing pre-release changes on a live merchant site without changing the embed code.
 
-- `?mb_version=next` — loads the latest `@next` snapshot from `/storefront/next/moonbase.js`
-- `?mb_version=pr-<N>` — loads the snapshot from a labeled PR `<N>` from `/storefront/pr-<N>/moonbase.js` (only present while the PR carries the `release-snapshot` label)
-- `?mb_version=2.1.0` — pins to a specific published version from `/storefront/<version>/moonbase.js`
-- `?mb_version=latest` or omitted — loads the current stable release (default)
+- `?mb_storefront_version=next` — loads the latest `@next` snapshot from `/storefront/next/moonbase.js`
+- `?mb_storefront_version=pr-<N>` — loads the snapshot from a labeled PR `<N>` from `/storefront/pr-<N>/moonbase.js` (only present while the PR carries the `release-snapshot` label)
+- `?mb_storefront_version=2.1.0` — pins to a specific published version from `/storefront/<version>/moonbase.js`
+- `?mb_storefront_version=latest` or omitted — loads the current stable release (default)
 
 Don't use this to pin a production embed to a specific version — pin the `<script src>` URL instead.
 
@@ -131,3 +131,80 @@ Available events include:
 - `checkout-initiated`
 - `checkout-closed`
 - `checkout-completed`
+
+## 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`:
+
+```ts
+Moonbase.setup('https://demo.moonbase.sh', {
+  integrations: {
+    metaPixel:        { pixelId: '1234567890' },
+    googleAnalytics:  { measurementId: 'G-XXXXXXX' },
+    googleTagManager: { containerId: 'GTM-XXXXXXX' },
+    klaviyo:          { companyId: 'ABC123' },
+    tiktokPixel:      { pixelId: 'C12345...' },
+  },
+})
+```
+
+The widget never loads SDK scripts itself — it only forwards to globals the host page has already initialised (`window.fbq`, `window.gtag`, `window.dataLayer`, `window.klaviyo`, `window.ttq`). If a global is missing when an event fires, the forwarding is a silent no-op (with a one-time `console.warn` so a misconfiguration is discoverable).
+
+### You install the SDK; Moonbase forwards to it
+
+You load each SDK with its own official snippet, exactly as you would without Moonbase — Moonbase only needs the same id so it can forward. Load order doesn't matter: if the global appears after `setup()`, forwarding begins as soon as it's there. For example, Meta Pixel:
+
+```html
+<!-- Your existing Meta Pixel snippet -->
+<script>
+  !function(f,b,e,v,n,t,s){/* …standard fbq loader… */}(window,document,'script',
+  'https://connect.facebook.net/en_US/fbevents.js');
+  fbq('init', '1234567890');
+  fbq('track', 'PageView');
+</script>
+```
+
+```ts
+// Hand Moonbase the same id so it can forward commerce/auth events to fbq:
+Moonbase.setup('https://demo.moonbase.sh', {
+  integrations: { metaPixel: { pixelId: '1234567890' } },
+})
+```
+
+The same pattern applies to GA4 (`gtag`), GTM (`dataLayer`), Klaviyo (`klaviyo`), and TikTok (`ttq`): install the vendor snippet, then pass the matching id. For Klaviyo, both the modern onsite object (`klaviyo.identify()` / `klaviyo.track()`) and the legacy `klaviyo.push([...])` queue are supported automatically. The `googleTagManager.containerId` is informational/reserved — GTM reads from `window.dataLayer` regardless of which container loaded it, so it isn't used at runtime.
+
+### Consent
+
+Forwarding is unconditional: Moonbase forwards to whatever SDK global is present, and relies on **that SDK's own consent state** (e.g. Google Consent Mode v2, or your CMP gating `fbq`/`ttq`). To suppress forwarding entirely until consent is granted, omit the provider from `setup()` and add it once consent lands:
+
+```ts
+onConsentGranted(() => Moonbase.configure({ integrations: { metaPixel: { pixelId: '1234567890' } } }))
+```
+
+`configure({ integrations })` can add, change, or remove providers at any time. Merge semantics apply per provider: pass a provider to add or update it, pass it as `undefined` (or `null`) to remove it, and omit it to leave it unchanged — so granting one provider after consent never disturbs the others.
+
+```ts
+// Stop forwarding to Meta Pixel, leave every other provider running:
+Moonbase.configure({ integrations: { metaPixel: undefined } })
+```
+
+### Identity
+
+`signed-in` / `signed-up` forward an identify call when an email/id is available (Meta advanced match, GA4 `user_id`, Klaviyo identify, TikTok identify). On `signed-out`, Moonbase clears what each SDK supports (GA4 `user_id` is reset, GTM gets a `logout` push); Meta, TikTok, and Klaviyo expose no per-user logout, so their profiles persist for the session.
+
+### 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.
+
+### Event mapping
+
+| Moonbase event       | Meta Pixel              | GA4                  | GTM (`dataLayer`)    | Klaviyo                  | TikTok Pixel          |
+| -------------------- | ----------------------- | -------------------- | -------------------- | ------------------------ | --------------------- |
+| `added-to-cart`      | `AddToCart`             | `add_to_cart`        | `add_to_cart`        | `Added to Cart`          | `AddToCart`           |
+| `checkout-initiated` | `InitiateCheckout`      | `begin_checkout`     | `begin_checkout`     | `Started Checkout`       | `InitiateCheckout`    |
+| `checkout-completed` | `Purchase`              | `purchase`           | `purchase`           | `Placed Order`           | `CompletePayment`     |
+| `signed-in`          | advanced match          | `login` + `user_id`  | `login`              | `identify`               | `identify`            |
+| `signed-up`          | `CompleteRegistration`  | `sign_up` + `user_id`| `sign_up`            | `identify`               | `CompleteRegistration`|
+| `signed-out`         | —                       | clears `user_id`     | `logout`             | —                        | —                     |
+
+For any event not listed (or a provider that isn't built in), use `Moonbase.on(...)` and forward by hand.

package/dist/moonbase.d.ts

@@ -18,8 +18,36 @@ declare type DeepPartial<T> = T extends object ? {
 
 export declare const eventEmitterKey: InjectionKey<MoonbaseEventEmitter>;
 
+export declare interface GoogleAnalyticsConfig {
+    measurementId: string;
+}
+
+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.
+     */
+    containerId?: string;
+}
+
 export declare const instanceKey: InjectionKey<MoonbaseInstance>;
 
+export declare interface IntegrationsConfig {
+    metaPixel?: MetaPixelConfig;
+    googleAnalytics?: GoogleAnalyticsConfig;
+    googleTagManager?: GoogleTagManagerConfig;
+    klaviyo?: KlaviyoConfig;
+    tiktokPixel?: TikTokPixelConfig;
+}
+
+export declare interface KlaviyoConfig {
+    companyId: string;
+}
+
+export declare interface MetaPixelConfig {
+    pixelId: string;
+}
+
 declare const Moonbase_2: MoonbaseImpl;
 export default Moonbase_2;
 
@@ -97,6 +125,8 @@ declare class MoonbaseImpl implements MoonbaseInstance {
     private pinia;
     private storefront;
     private options;
+    private integrations;
+    private completedOrderIds;
     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;
@@ -256,7 +286,7 @@ export declare interface MoonbaseIntentArgs {
     [MoonbaseIntent.ViewAbout]: never;
 }
 
-declare interface MoonbaseOptions {
+export declare interface MoonbaseOptions {
     toolbar: {
         enabled: boolean;
         location: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
@@ -329,6 +359,20 @@ declare interface MoonbaseOptions {
      * of the widget's automatic counter-scaling and match the host's density.
      */
     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.
+     */
+    integrations: IntegrationsConfig;
+}
+
+export declare interface TikTokPixelConfig {
+    pixelId: string;
 }
 
 export declare const urlKey: InjectionKey<string>;