@molecule/app-analytics 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/auto-tracking.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Automatic analytics tracking for auth, routing, HTTP, and mobile events.
+ *
+ * Uses minimal interfaces so there's no hard dependency on
+ * `@molecule/app-auth`, `@molecule/app-routing`, `@molecule/app-http`,
+ * `@molecule/app-lifecycle`, or `@molecule/app-push`.
+ *
+ * @module
+ */
+/**
+ * Minimal auth event shape (mirrors `@molecule/app-auth` AuthEvent).
+ */
+interface AuthEvent {
+    type: 'login' | 'logout' | 'register' | 'refresh' | 'error';
+    user?: {
+        id: string;
+        email?: string;
+        name?: string;
+    };
+    error?: string;
+}
+/**
+ * Minimal auth client interface for auto-tracking.
+ */
+interface AuthClientLike {
+    addEventListener(listener: (event: AuthEvent) => void): () => void;
+}
+/**
+ * Minimal route location shape (mirrors `@molecule/app-routing` RouteLocation).
+ */
+interface RouteLocationLike {
+    pathname: string;
+    search: string;
+    hash: string;
+}
+/**
+ * Minimal router interface for auto-tracking.
+ */
+interface RouterLike {
+    subscribe(listener: (location: RouteLocationLike, action: string) => void): () => void;
+}
+/**
+ * Minimal HTTP error shape.
+ */
+interface HttpErrorLike {
+    message: string;
+    status: number;
+    config?: {
+        method?: string;
+        url?: string;
+    };
+}
+/**
+ * Minimal HTTP client interface for auto-tracking.
+ */
+interface HttpClientLike {
+    addErrorInterceptor(interceptor: (error: HttpErrorLike) => HttpErrorLike): () => void;
+}
+/**
+ * Minimal app state change shape (mirrors `@molecule/app-lifecycle` AppStateChange).
+ */
+interface AppStateChangeLike {
+    current: string;
+    previous: string;
+}
+/**
+ * Minimal lifecycle client interface for auto-tracking app foreground/background
+ * transitions and deep link opens.
+ */
+interface LifecycleClientLike {
+    onAppStateChange(listener: (change: AppStateChangeLike) => void): () => void;
+    onUrlOpen(listener: (url: string) => void): () => void;
+}
+/**
+ * Minimal push notification shape for auto-tracking.
+ */
+interface PushNotificationLike {
+    id: string;
+    title: string;
+}
+/**
+ * Minimal notification received event shape (mirrors `@molecule/app-push` NotificationReceivedEvent).
+ */
+interface NotificationReceivedEventLike {
+    notification: PushNotificationLike;
+    foreground: boolean;
+}
+/**
+ * Minimal notification action event shape (mirrors `@molecule/app-push` NotificationActionEvent).
+ */
+interface NotificationActionEventLike {
+    notification: PushNotificationLike;
+    actionId?: string;
+}
+/**
+ * Minimal push client interface for auto-tracking notification events.
+ */
+interface PushClientLike {
+    onNotificationReceived(listener: (event: NotificationReceivedEventLike) => void): () => void;
+    onNotificationAction(listener: (event: NotificationActionEventLike) => void): () => void;
+}
+/**
+ * Auto-tracking options. Pass any combination of sources — only provided
+ * sources are tracked. Works for both web and mobile apps.
+ */
+export interface AutoTrackingOptions {
+    /** Auth client for login/logout/register/error events. */
+    authClient?: AuthClientLike;
+    /** Router for page view tracking. */
+    router?: RouterLike;
+    /** HTTP client for error tracking. */
+    httpClient?: HttpClientLike;
+    /** Lifecycle client for app foreground/background and deep link tracking. */
+    lifecycleClient?: LifecycleClientLike;
+    /** Push client for notification received/tapped tracking. */
+    pushClient?: PushClientLike;
+}
+/**
+ * Sets up automatic analytics tracking for auth events, route changes,
+ * HTTP errors, app lifecycle transitions, push notifications, and deep links.
+ * Returns a cleanup function that removes all subscriptions.
+ *
+ * Pass any combination of sources — only provided sources are tracked.
+ *
+ * The analytics provider is resolved at EVENT time, not at setup time — so
+ * `setupAutoTracking()` may safely run before the analytics bond is set
+ * (events fired before bonding no-op; events fired after are tracked).
+ *
+ * @example
+ * ```typescript
+ * // Web app
+ * const cleanup = setupAutoTracking({
+ *   authClient: getClient(),
+ *   router: getRouter(),
+ *   httpClient: getHttp(),
+ * })
+ *
+ * // Mobile app (React Native) — add lifecycle and push
+ * const cleanup = setupAutoTracking({
+ *   authClient: getClient(),
+ *   router: getRouter(),
+ *   httpClient: getHttp(),
+ *   lifecycleClient: getLifecycleProvider(),
+ *   pushClient: getPushProvider(),
+ * })
+ *
+ * // Later, to remove all listeners:
+ * cleanup()
+ * ```
+ *
+ * @param options - Sources to auto-track.
+ * @returns A cleanup function that removes all event subscriptions.
+ */
+export declare const setupAutoTracking: (options: AutoTrackingOptions) => (() => void);
+export {};
+//# sourceMappingURL=auto-tracking.d.ts.map

package/dist/auto-tracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-tracking.d.ts","sourceRoot":"","sources":["../src/auto-tracking.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH;;GAEG;AACH,UAAU,SAAS;IACjB,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,OAAO,CAAA;IAC3D,IAAI,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACpD,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;GAEG;AACH,UAAU,cAAc;IACtB,gBAAgB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;CACnE;AAED;;GAEG;AACH,UAAU,iBAAiB;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;GAEG;AACH,UAAU,UAAU;IAClB,SAAS,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;CACvF;AAED;;GAEG;AACH,UAAU,aAAa;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC3C;AAED;;GAEG;AACH,UAAU,cAAc;IACtB,mBAAmB,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,aAAa,GAAG,MAAM,IAAI,CAAA;CACtF;AAMD;;GAEG;AACH,UAAU,kBAAkB;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;GAGG;AACH,UAAU,mBAAmB;IAC3B,gBAAgB,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IAC5E,SAAS,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;CACvD;AAED;;GAEG;AACH,UAAU,oBAAoB;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;GAEG;AACH,UAAU,6BAA6B;IACrC,YAAY,EAAE,oBAAoB,CAAA;IAClC,UAAU,EAAE,OAAO,CAAA;CACpB;AAED;;GAEG;AACH,UAAU,2BAA2B;IACnC,YAAY,EAAE,oBAAoB,CAAA;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,UAAU,cAAc;IACtB,sBAAsB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,6BAA6B,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IAC5F,oBAAoB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,2BAA2B,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;CACzF;AAMD;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,0DAA0D;IAC1D,UAAU,CAAC,EAAE,cAAc,CAAA;IAC3B,qCAAqC;IACrC,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,sCAAsC;IACtC,UAAU,CAAC,EAAE,cAAc,CAAA;IAC3B,6EAA6E;IAC7E,eAAe,CAAC,EAAE,mBAAmB,CAAA;IACrC,6DAA6D;IAC7D,UAAU,CAAC,EAAE,cAAc,CAAA;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS,mBAAmB,KAAG,CAAC,MAAM,IAAI,CA2J3E,CAAA"}

package/dist/auto-tracking.js

@@ -0,0 +1,196 @@
+/**
+ * Automatic analytics tracking for auth, routing, HTTP, and mobile events.
+ *
+ * Uses minimal interfaces so there's no hard dependency on
+ * `@molecule/app-auth`, `@molecule/app-routing`, `@molecule/app-http`,
+ * `@molecule/app-lifecycle`, or `@molecule/app-push`.
+ *
+ * @module
+ */
+import { getProvider } from './provider.js';
+/**
+ * Sets up automatic analytics tracking for auth events, route changes,
+ * HTTP errors, app lifecycle transitions, push notifications, and deep links.
+ * Returns a cleanup function that removes all subscriptions.
+ *
+ * Pass any combination of sources — only provided sources are tracked.
+ *
+ * The analytics provider is resolved at EVENT time, not at setup time — so
+ * `setupAutoTracking()` may safely run before the analytics bond is set
+ * (events fired before bonding no-op; events fired after are tracked).
+ *
+ * @example
+ * ```typescript
+ * // Web app
+ * const cleanup = setupAutoTracking({
+ *   authClient: getClient(),
+ *   router: getRouter(),
+ *   httpClient: getHttp(),
+ * })
+ *
+ * // Mobile app (React Native) — add lifecycle and push
+ * const cleanup = setupAutoTracking({
+ *   authClient: getClient(),
+ *   router: getRouter(),
+ *   httpClient: getHttp(),
+ *   lifecycleClient: getLifecycleProvider(),
+ *   pushClient: getPushProvider(),
+ * })
+ *
+ * // Later, to remove all listeners:
+ * cleanup()
+ * ```
+ *
+ * @param options - Sources to auto-track.
+ * @returns A cleanup function that removes all event subscriptions.
+ */
+export const setupAutoTracking = (options) => {
+    const cleanups = [];
+    // Resolve the provider per event — capturing getProvider() once at setup
+    // permanently baked in the no-op provider whenever setupAutoTracking() ran
+    // before the analytics bond was set, silently dropping every event forever.
+    const analytics = () => getProvider();
+    // Auth events
+    if (options.authClient) {
+        const removeListener = options.authClient.addEventListener((event) => {
+            switch (event.type) {
+                case 'login':
+                    if (event.user) {
+                        analytics()
+                            .identify({
+                            userId: event.user.id,
+                            email: event.user.email,
+                            name: event.user.name,
+                        })
+                            .catch(() => { });
+                        analytics()
+                            .track({ name: 'auth.login', properties: { userId: event.user.id } })
+                            .catch(() => { });
+                    }
+                    break;
+                case 'register':
+                    if (event.user) {
+                        analytics()
+                            .identify({
+                            userId: event.user.id,
+                            email: event.user.email,
+                            name: event.user.name,
+                        })
+                            .catch(() => { });
+                        analytics()
+                            .track({ name: 'auth.register', properties: { userId: event.user.id } })
+                            .catch(() => { });
+                    }
+                    break;
+                case 'logout':
+                    analytics()
+                        .track({ name: 'auth.logout' })
+                        .catch(() => { });
+                    analytics()
+                        .reset?.()
+                        .catch(() => { });
+                    break;
+                case 'error':
+                    analytics()
+                        .track({ name: 'auth.error', properties: { error: event.error } })
+                        .catch(() => { });
+                    break;
+            }
+        });
+        cleanups.push(removeListener);
+    }
+    // Route changes
+    if (options.router) {
+        const removeListener = options.router.subscribe((location) => {
+            analytics()
+                .page({
+                path: location.pathname,
+                url: `${location.pathname}${location.search}${location.hash}`,
+            })
+                .catch(() => { });
+        });
+        cleanups.push(removeListener);
+    }
+    // HTTP errors
+    if (options.httpClient) {
+        const removeInterceptor = options.httpClient.addErrorInterceptor((error) => {
+            analytics()
+                .track({
+                name: 'http.error',
+                properties: {
+                    status: error.status,
+                    method: error.config?.method,
+                    url: error.config?.url,
+                    message: error.message,
+                },
+            })
+                .catch(() => { });
+            return error;
+        });
+        cleanups.push(removeInterceptor);
+    }
+    // App lifecycle (foreground/background transitions + deep links)
+    if (options.lifecycleClient) {
+        const removeStateListener = options.lifecycleClient.onAppStateChange((change) => {
+            if (change.current === 'active' && change.previous !== 'active') {
+                analytics()
+                    .track({
+                    name: 'app.foreground',
+                    properties: { previous: change.previous },
+                })
+                    .catch(() => { });
+            }
+            else if (change.current === 'background' && change.previous !== 'background') {
+                analytics()
+                    .track({
+                    name: 'app.background',
+                    properties: { previous: change.previous },
+                })
+                    .catch(() => { });
+            }
+        });
+        cleanups.push(removeStateListener);
+        const removeUrlListener = options.lifecycleClient.onUrlOpen((url) => {
+            analytics()
+                .track({
+                name: 'deeplink.open',
+                properties: { url },
+            })
+                .catch(() => { });
+        });
+        cleanups.push(removeUrlListener);
+    }
+    // Push notifications (received + tapped)
+    if (options.pushClient) {
+        const removeReceivedListener = options.pushClient.onNotificationReceived((event) => {
+            analytics()
+                .track({
+                name: 'push.received',
+                properties: {
+                    id: event.notification.id,
+                    title: event.notification.title,
+                    foreground: event.foreground,
+                },
+            })
+                .catch(() => { });
+        });
+        cleanups.push(removeReceivedListener);
+        const removeActionListener = options.pushClient.onNotificationAction((event) => {
+            analytics()
+                .track({
+                name: 'push.tapped',
+                properties: {
+                    id: event.notification.id,
+                    title: event.notification.title,
+                    actionId: event.actionId,
+                },
+            })
+                .catch(() => { });
+        });
+        cleanups.push(removeActionListener);
+    }
+    return () => {
+        cleanups.forEach((fn) => fn());
+    };
+};
+//# sourceMappingURL=auto-tracking.js.map

package/dist/auto-tracking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-tracking.js","sourceRoot":"","sources":["../src/auto-tracking.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Frontend analytics interface for molecule.dev.
+ *
+ * Provides a unified analytics API that can be backed by different
+ * implementations (PostHog, Mixpanel, etc.).
+ *
+ * @example
+ * ```typescript
+ * import { identify, reset, setProvider, track } from '@molecule/app-analytics'
+ * import { createProvider } from '@molecule/app-analytics-posthog'
+ *
+ * // At startup — the key comes from your build-time env (in Vite:
+ * // import.meta.env.VITE_POSTHOG_KEY); a missing key yields a warning +
+ * // no-op provider, never a crash.
+ * setProvider(createProvider({ apiKey: posthogApiKey }))
+ *
+ * identify({ userId: user.id, email: user.email })      // on login
+ * track({ name: 'order_placed', properties: { total } })
+ * reset()                                               // on logout
+ * ```
+ *
+ * @remarks
+ * - Every convenience function (`track`, `identify`, `page`, …) swallows
+ *   provider errors and no-ops when nothing is bonded — analytics can never
+ *   break the UI, so `hasProvider()` is the ONLY signal that separates
+ *   "analytics disabled/unbonded" from "events are being tracked". Check it
+ *   (and the bond's own console warning) before debugging tracking code.
+ * - Attribution is AMBIENT in the browser: call `identify(user)` on login and
+ *   `reset()` on logout; per-event `userId`/`anonymousId` fields are not
+ *   honored by browser bonds (they exist for parity with
+ *   `@molecule/api-analytics`).
+ * - `group(groupId)` normalizes the group TYPE to `'company'` in every bond
+ *   (Mixpanel group key, PostHog group type) — look under "company" in the
+ *   provider's UI.
+ *
+ * @module
+ */
+export * from './auto-tracking.js';
+export * from './provider.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,41 @@
+/**
+ * Frontend analytics interface for molecule.dev.
+ *
+ * Provides a unified analytics API that can be backed by different
+ * implementations (PostHog, Mixpanel, etc.).
+ *
+ * @example
+ * ```typescript
+ * import { identify, reset, setProvider, track } from '@molecule/app-analytics'
+ * import { createProvider } from '@molecule/app-analytics-posthog'
+ *
+ * // At startup — the key comes from your build-time env (in Vite:
+ * // import.meta.env.VITE_POSTHOG_KEY); a missing key yields a warning +
+ * // no-op provider, never a crash.
+ * setProvider(createProvider({ apiKey: posthogApiKey }))
+ *
+ * identify({ userId: user.id, email: user.email })      // on login
+ * track({ name: 'order_placed', properties: { total } })
+ * reset()                                               // on logout
+ * ```
+ *
+ * @remarks
+ * - Every convenience function (`track`, `identify`, `page`, …) swallows
+ *   provider errors and no-ops when nothing is bonded — analytics can never
+ *   break the UI, so `hasProvider()` is the ONLY signal that separates
+ *   "analytics disabled/unbonded" from "events are being tracked". Check it
+ *   (and the bond's own console warning) before debugging tracking code.
+ * - Attribution is AMBIENT in the browser: call `identify(user)` on login and
+ *   `reset()` on logout; per-event `userId`/`anonymousId` fields are not
+ *   honored by browser bonds (they exist for parity with
+ *   `@molecule/api-analytics`).
+ * - `group(groupId)` normalizes the group TYPE to `'company'` in every bond
+ *   (Mixpanel group key, PostHog group type) — look under "company" in the
+ *   provider's UI.
+ *
+ * @module
+ */
+export * from './auto-tracking.js';
+export * from './provider.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA"}

package/dist/provider.d.ts

@@ -0,0 +1,69 @@
+/**
+ * App-side analytics bond accessor and convenience functions.
+ *
+ * Bond packages call `setProvider()` during setup. All convenience
+ * functions silently swallow errors so analytics never breaks the UI.
+ * If no provider is bonded, a no-op provider is used.
+ *
+ * @module
+ */
+import type { AnalyticsEvent, AnalyticsPageView, AnalyticsProvider, AnalyticsUserProps } from './types.js';
+/**
+ * Registers an analytics provider as the active singleton.
+ *
+ * @param provider - The analytics provider implementation to bond.
+ */
+export declare const setProvider: (provider: AnalyticsProvider) => void;
+/**
+ * Retrieves the bonded analytics provider. Returns a no-op provider if
+ * none is bonded, so analytics calls never throw.
+ *
+ * @returns The bonded analytics provider, or a silent no-op fallback.
+ */
+export declare const getProvider: () => AnalyticsProvider;
+/**
+ * Checks whether an analytics provider is currently bonded.
+ *
+ * @returns `true` if an analytics provider is bonded.
+ */
+export declare const hasProvider: () => boolean;
+/**
+ * Identifies the current user for analytics tracking. Errors are silently ignored.
+ *
+ * @param user - The user properties (ID, email, name, traits).
+ * @returns A promise that resolves when identification completes or fails silently.
+ */
+export declare const identify: (user: AnalyticsUserProps) => Promise<void>;
+/**
+ * Tracks a named event with optional properties. Errors are silently ignored.
+ *
+ * @param event - The event to track (name and optional properties).
+ * @returns A promise that resolves when tracking completes or fails silently.
+ */
+export declare const track: (event: AnalyticsEvent) => Promise<void>;
+/**
+ * Tracks a page view event. Errors are silently ignored.
+ *
+ * @param pageView - The page view data (name, path, referrer, etc.).
+ * @returns A promise that resolves when page tracking completes or fails silently.
+ */
+export declare const page: (pageView: AnalyticsPageView) => Promise<void>;
+/**
+ * Associates the current user with a group/organization. Errors are silently ignored.
+ *
+ * @param groupId - The group identifier.
+ * @param traits - Optional traits describing the group.
+ * @returns A promise that resolves when group association completes or fails silently.
+ */
+export declare const group: (groupId: string, traits?: Record<string, unknown>) => Promise<void>;
+/**
+ * Resets the analytics state (e.g. on logout). Errors are silently ignored.
+ * @returns A promise that resolves when reset completes or fails silently.
+ */
+export declare const reset: () => Promise<void>;
+/**
+ * Flushes any queued analytics events to the backend. Errors are silently ignored.
+ * @returns A promise that resolves when flush completes or fails silently.
+ */
+export declare const flush: () => Promise<void>;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,YAAY,CAAA;AAYnB;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,iBAAiB,KAAG,IAEzD,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,QAAO,iBAK9B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,QAAO,OAE9B,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GAAI,MAAM,kBAAkB,KAAG,OAAO,CAAC,IAAI,CAG5C,CAAA;AAEpB;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAAI,OAAO,cAAc,KAAG,OAAO,CAAC,IAAI,CAGtC,CAAA;AAEpB;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAI,UAAU,iBAAiB,KAAG,OAAO,CAAC,IAAI,CAG3C,CAAA;AAEpB;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,GAAI,SAAS,MAAM,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,OAAO,CAAC,IAAI,CACP,CAAA;AAE/E;;;GAGG;AACH,eAAO,MAAM,KAAK,QAAO,OAAO,CAAC,IAAI,CAC2B,CAAA;AAEhE;;;GAGG;AACH,eAAO,MAAM,KAAK,QAAO,OAAO,CAAC,IAAI,CAC2B,CAAA"}

package/dist/provider.js

@@ -0,0 +1,92 @@
+/**
+ * App-side analytics bond accessor and convenience functions.
+ *
+ * Bond packages call `setProvider()` during setup. All convenience
+ * functions silently swallow errors so analytics never breaks the UI.
+ * If no provider is bonded, a no-op provider is used.
+ *
+ * @module
+ */
+import { bond, get as bondGet, isBonded } from '@molecule/app-bond';
+const BOND_TYPE = 'app-analytics';
+const noopProvider = {
+    identify: async () => { },
+    track: async () => { },
+    page: async () => { },
+    reset: async () => { },
+    flush: async () => { },
+};
+/**
+ * Registers an analytics provider as the active singleton.
+ *
+ * @param provider - The analytics provider implementation to bond.
+ */
+export const setProvider = (provider) => {
+    bond(BOND_TYPE, provider);
+};
+/**
+ * Retrieves the bonded analytics provider. Returns a no-op provider if
+ * none is bonded, so analytics calls never throw.
+ *
+ * @returns The bonded analytics provider, or a silent no-op fallback.
+ */
+export const getProvider = () => {
+    if (!isBonded(BOND_TYPE)) {
+        return noopProvider;
+    }
+    return bondGet(BOND_TYPE);
+};
+/**
+ * Checks whether an analytics provider is currently bonded.
+ *
+ * @returns `true` if an analytics provider is bonded.
+ */
+export const hasProvider = () => {
+    return isBonded(BOND_TYPE);
+};
+/**
+ * Identifies the current user for analytics tracking. Errors are silently ignored.
+ *
+ * @param user - The user properties (ID, email, name, traits).
+ * @returns A promise that resolves when identification completes or fails silently.
+ */
+export const identify = (user) => getProvider()
+    .identify(user)
+    .catch(() => { });
+/**
+ * Tracks a named event with optional properties. Errors are silently ignored.
+ *
+ * @param event - The event to track (name and optional properties).
+ * @returns A promise that resolves when tracking completes or fails silently.
+ */
+export const track = (event) => getProvider()
+    .track(event)
+    .catch(() => { });
+/**
+ * Tracks a page view event. Errors are silently ignored.
+ *
+ * @param pageView - The page view data (name, path, referrer, etc.).
+ * @returns A promise that resolves when page tracking completes or fails silently.
+ */
+export const page = (pageView) => getProvider()
+    .page(pageView)
+    .catch(() => { });
+/**
+ * Associates the current user with a group/organization. Errors are silently ignored.
+ *
+ * @param groupId - The group identifier.
+ * @param traits - Optional traits describing the group.
+ * @returns A promise that resolves when group association completes or fails silently.
+ */
+export const group = (groupId, traits) => (getProvider().group?.(groupId, traits) ?? Promise.resolve()).catch(() => { });
+/**
+ * Resets the analytics state (e.g. on logout). Errors are silently ignored.
+ * @returns A promise that resolves when reset completes or fails silently.
+ */
+export const reset = () => (getProvider().reset?.() ?? Promise.resolve()).catch(() => { });
+/**
+ * Flushes any queued analytics events to the backend. Errors are silently ignored.
+ * @returns A promise that resolves when flush completes or fails silently.
+ */
+export const flush = () => (getProvider().flush?.() ?? Promise.resolve()).catch(() => { });
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,EAAE,GAAG,IAAI,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AASnE,MAAM,SAAS,GAAG,eAAe,CAAA;AAEjC,MAAM,YAAY,GAAsB;IACtC,QAAQ,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC;IACxB,KAAK,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC;IACrB,IAAI,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC;IACpB,KAAK,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC;IACrB,KAAK,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC;CACtB,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAA2B,EAAQ,EAAE;IAC/D,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAA;AAC3B,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,GAAsB,EAAE;IACjD,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QACzB,OAAO,YAAY,CAAA;IACrB,CAAC;IACD,OAAO,OAAO,CAAoB,SAAS,CAAE,CAAA;AAC/C,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,GAAY,EAAE;IACvC,OAAO,QAAQ,CAAC,SAAS,CAAC,CAAA;AAC5B,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,IAAwB,EAAiB,EAAE,CAClE,WAAW,EAAE;KACV,QAAQ,CAAC,IAAI,CAAC;KACd,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;AAEpB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,KAAqB,EAAiB,EAAE,CAC5D,WAAW,EAAE;KACV,KAAK,CAAC,KAAK,CAAC;KACZ,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;AAEpB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,QAA2B,EAAiB,EAAE,CACjE,WAAW,EAAE;KACV,IAAI,CAAC,QAAQ,CAAC;KACd,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;AAEpB;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,OAAe,EAAE,MAAgC,EAAiB,EAAE,CACxF,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;AAE/E;;;GAGG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,GAAkB,EAAE,CACvC,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,EAAE,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;AAEhE;;;GAGG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,GAAkB,EAAE,CACvC,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,EAAE,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA"}

package/dist/types.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Type definitions for the app analytics module.
+ *
+ * @module
+ */
+/**
+ * User properties for analytics identification.
+ */
+export interface AnalyticsUserProps {
+    /** Unique user identifier. */
+    userId: string;
+    /** User email address. */
+    email?: string;
+    /** User display name. */
+    name?: string;
+    /** Arbitrary key-value traits to associate with the user. */
+    traits?: Record<string, unknown>;
+}
+/**
+ * Event properties for analytics tracking.
+ */
+export interface AnalyticsEvent {
+    /** Event name (e.g. `"button_clicked"`, `"purchase_completed"`). */
+    name: string;
+    /** Arbitrary key-value properties for this event. */
+    properties?: Record<string, unknown>;
+    /**
+     * Event timestamp (defaults to now). Only honored where the underlying
+     * browser SDK supports client-set timestamps (PostHog does); the Mixpanel
+     * browser SDK always stamps the time of capture. For reliable historical
+     * timestamps use the API-side `@molecule/api-analytics` bonds.
+     */
+    timestamp?: Date;
+    /**
+     * Identified user who triggered the event. Browser analytics SDKs attribute
+     * events to the AMBIENT identified session — call `identify()` first;
+     * current browser bonds do not honor a per-event userId override. (Exists
+     * for interface parity with `@molecule/api-analytics`, where there is no
+     * ambient session and per-event IDs are required.)
+     */
+    userId?: string;
+    /**
+     * Anonymous identifier for unauthenticated users. Like `userId`, browser
+     * bonds use the SDK's own ambient anonymous identity instead of this field.
+     */
+    anonymousId?: string;
+}
+/**
+ * Page view event.
+ */
+export interface AnalyticsPageView {
+    /** Page name (e.g. `"Home"`, `"Settings"`). */
+    name?: string;
+    /** Page category (e.g. `"Dashboard"`, `"Marketing"`). */
+    category?: string;
+    /** Full page URL. */
+    url?: string;
+    /** Page path (e.g. `"/settings/profile"`). */
+    path?: string;
+    /** Referrer URL. */
+    referrer?: string;
+    /** Arbitrary key-value properties for this page view. */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Analytics provider interface that all analytics bond packages must implement.
+ */
+export interface AnalyticsProvider {
+    /**
+     * Identifies a user and associates traits with them.
+     *
+     * @param user - User properties including userId and optional traits.
+     */
+    identify(user: AnalyticsUserProps): Promise<void>;
+    /**
+     * Tracks a named event with optional properties.
+     *
+     * @param event - The event name and properties to track.
+     */
+    track(event: AnalyticsEvent): Promise<void>;
+    /**
+     * Records a page view.
+     *
+     * @param pageView - Page view details (name, path, properties).
+     */
+    page(pageView: AnalyticsPageView): Promise<void>;
+    /**
+     * Associates a user with a group (e.g. company, team).
+     *
+     * @param groupId - The group identifier.
+     * @param traits - Arbitrary traits to associate with the group.
+     */
+    group?(groupId: string, traits?: Record<string, unknown>): Promise<void>;
+    /**
+     * Resets the current user identity and generates a new anonymous ID.
+     */
+    reset?(): Promise<void>;
+    /**
+     * Flushes any queued events to the analytics service immediately.
+     */
+    flush?(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,0BAA0B;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,yBAAyB;IACzB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAA;IACZ,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,IAAI,CAAA;IAChB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,qBAAqB;IACrB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,oBAAoB;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEjD;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE3C;;;;OAIG;IACH,IAAI,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEhD;;;;;OAKG;IACH,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAExE;;OAEG;IACH,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAEvB;;OAEG;IACH,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACxB"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Type definitions for the app analytics module.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@molecule/app-analytics",
+  "version": "1.0.0",
+  "description": "Frontend analytics interface for molecule.dev",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "analytics",
+    "tracking",
+    "posthog",
+    "mixpanel"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@molecule/app-bond": "^1.0.0"
+  },
+  "devDependencies": {
+    "@molecule/app-bond": "1.0.0",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/app/core/analytics"
+  },
+  "homepage": "https://github.com/molecule-dev/molecule/tree/main/packages/app/core/analytics",
+  "bugs": "https://github.com/molecule-dev/molecule/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}