@metamask-previews/analytics-controller 1.0.1-preview-8e8c4f6f5 → 1.1.0-preview-e43dfcb

package/dist/AnalyticsPlatformAdapter.types.d.cts

@@ -7,6 +7,29 @@ export type AnalyticsEventProperties = Record<string, Json>;
  * User traits/properties for analytics identification
  */
 export type AnalyticsUserTraits = Record<string, Json>;
+/**
+ * Callback invoked by the platform adapter after an analytics payload is
+ * delivered or fails.
+ */
+export type AnalyticsInvocationCallback = (error?: unknown) => void;
+/**
+ * Internal delivery metadata used by AnalyticsController when event queue
+ * persistence is enabled.
+ */
+export type AnalyticsDeliveryOptions = {
+    /**
+     * Stable identifier for the analytics payload.
+     */
+    messageId?: string;
+    /**
+     * Original timestamp for the analytics payload.
+     */
+    timestamp?: Date;
+    /**
+     * Callback for delivery acknowledgement.
+     */
+    callback?: AnalyticsInvocationCallback;
+};
 /**
  * Event properties structure with two distinct properties lists for regular and sensitive data.
  * Similar to ITrackingEvent from legacy analytics but decoupled for platform agnosticism.
@@ -47,16 +70,18 @@ export type AnalyticsPlatformAdapter = {
      * @param properties - Event properties. If not provided, the event has no properties.
      * The privacy plugin should check for `isSensitive === true` to determine if an event contains sensitive data.
      * @param context - Optional platform-specific context attached to the invocation.
+     * @param options - Optional delivery metadata for platform adapters.
      */
-    track(eventName: string, properties?: AnalyticsEventProperties, context?: AnalyticsContext): void;
+    track(eventName: string, properties?: AnalyticsEventProperties, context?: AnalyticsContext, options?: AnalyticsDeliveryOptions): void;
     /**
      * Identify a user with traits.
      *
      * @param userId - The user identifier (e.g., metametrics ID)
      * @param traits - User traits/properties
      * @param context - Optional platform-specific context attached to the invocation.
+     * @param options - Optional delivery metadata for platform adapters.
      */
-    identify(userId: string, traits?: AnalyticsUserTraits, context?: AnalyticsContext): void;
+    identify(userId: string, traits?: AnalyticsUserTraits, context?: AnalyticsContext, options?: AnalyticsDeliveryOptions): void;
     /**
      * Track a UI unit (page or screen) view depending on the platform
      *
@@ -67,8 +92,9 @@ export type AnalyticsPlatformAdapter = {
      * @param name - The identifier/name of the page or screen being viewed (e.g., "home", "settings", "wallet")
      * @param properties - Optional properties associated with the view
      * @param context - Optional platform-specific context attached to the invocation.
+     * @param options - Optional delivery metadata for platform adapters.
      */
-    view(name: string, properties?: AnalyticsEventProperties, context?: AnalyticsContext): void;
+    view(name: string, properties?: AnalyticsEventProperties, context?: AnalyticsContext, options?: AnalyticsDeliveryOptions): void;
     /**
      * Lifecycle hook called after the AnalyticsController is fully initialized.
      *

package/dist/AnalyticsPlatformAdapter.types.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"AnalyticsPlatformAdapter.types.d.cts","sourceRoot":"","sources":["../src/AnalyticsPlatformAdapter.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAE5C;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAE5D;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAEvD;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,wBAAwB,CAAC;IACrC,mBAAmB,EAAE,wBAAwB,CAAC;IAC9C;;;;OAIG;IACH,iBAAiB,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;;;;;;OASG;IACH,KAAK,CACH,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,wBAAwB,EACrC,OAAO,CAAC,EAAE,gBAAgB,GACzB,IAAI,CAAC;IAER;;;;;;OAMG;IACH,QAAQ,CACN,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,gBAAgB,GACzB,IAAI,CAAC;IAER;;;;;;;;;;OAUG;IACH,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,wBAAwB,EACrC,OAAO,CAAC,EAAE,gBAAgB,GACzB,IAAI,CAAC;IAER;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7C,CAAC"}
+{"version":3,"file":"AnalyticsPlatformAdapter.types.d.cts","sourceRoot":"","sources":["../src/AnalyticsPlatformAdapter.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAE5C;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAE5D;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAEvD;;;GAGG;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AAEpE;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,SAAS,CAAC,EAAE,IAAI,CAAC;IAEjB;;OAEG;IACH,QAAQ,CAAC,EAAE,2BAA2B,CAAC;CACxC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,wBAAwB,CAAC;IACrC,mBAAmB,EAAE,wBAAwB,CAAC;IAC9C;;;;OAIG;IACH,iBAAiB,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;;;;;;;OAUG;IACH,KAAK,CACH,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,wBAAwB,EACrC,OAAO,CAAC,EAAE,gBAAgB,EAC1B,OAAO,CAAC,EAAE,wBAAwB,GACjC,IAAI,CAAC;IAER;;;;;;;OAOG;IACH,QAAQ,CACN,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,gBAAgB,EAC1B,OAAO,CAAC,EAAE,wBAAwB,GACjC,IAAI,CAAC;IAER;;;;;;;;;;;OAWG;IACH,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,wBAAwB,EACrC,OAAO,CAAC,EAAE,gBAAgB,EAC1B,OAAO,CAAC,EAAE,wBAAwB,GACjC,IAAI,CAAC;IAER;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7C,CAAC"}

package/dist/AnalyticsPlatformAdapter.types.d.mts

@@ -7,6 +7,29 @@ export type AnalyticsEventProperties = Record<string, Json>;
  * User traits/properties for analytics identification
  */
 export type AnalyticsUserTraits = Record<string, Json>;
+/**
+ * Callback invoked by the platform adapter after an analytics payload is
+ * delivered or fails.
+ */
+export type AnalyticsInvocationCallback = (error?: unknown) => void;
+/**
+ * Internal delivery metadata used by AnalyticsController when event queue
+ * persistence is enabled.
+ */
+export type AnalyticsDeliveryOptions = {
+    /**
+     * Stable identifier for the analytics payload.
+     */
+    messageId?: string;
+    /**
+     * Original timestamp for the analytics payload.
+     */
+    timestamp?: Date;
+    /**
+     * Callback for delivery acknowledgement.
+     */
+    callback?: AnalyticsInvocationCallback;
+};
 /**
  * Event properties structure with two distinct properties lists for regular and sensitive data.
  * Similar to ITrackingEvent from legacy analytics but decoupled for platform agnosticism.
@@ -47,16 +70,18 @@ export type AnalyticsPlatformAdapter = {
      * @param properties - Event properties. If not provided, the event has no properties.
      * The privacy plugin should check for `isSensitive === true` to determine if an event contains sensitive data.
      * @param context - Optional platform-specific context attached to the invocation.
+     * @param options - Optional delivery metadata for platform adapters.
      */
-    track(eventName: string, properties?: AnalyticsEventProperties, context?: AnalyticsContext): void;
+    track(eventName: string, properties?: AnalyticsEventProperties, context?: AnalyticsContext, options?: AnalyticsDeliveryOptions): void;
     /**
      * Identify a user with traits.
      *
      * @param userId - The user identifier (e.g., metametrics ID)
      * @param traits - User traits/properties
      * @param context - Optional platform-specific context attached to the invocation.
+     * @param options - Optional delivery metadata for platform adapters.
      */
-    identify(userId: string, traits?: AnalyticsUserTraits, context?: AnalyticsContext): void;
+    identify(userId: string, traits?: AnalyticsUserTraits, context?: AnalyticsContext, options?: AnalyticsDeliveryOptions): void;
     /**
      * Track a UI unit (page or screen) view depending on the platform
      *
@@ -67,8 +92,9 @@ export type AnalyticsPlatformAdapter = {
      * @param name - The identifier/name of the page or screen being viewed (e.g., "home", "settings", "wallet")
      * @param properties - Optional properties associated with the view
      * @param context - Optional platform-specific context attached to the invocation.
+     * @param options - Optional delivery metadata for platform adapters.
      */
-    view(name: string, properties?: AnalyticsEventProperties, context?: AnalyticsContext): void;
+    view(name: string, properties?: AnalyticsEventProperties, context?: AnalyticsContext, options?: AnalyticsDeliveryOptions): void;
     /**
      * Lifecycle hook called after the AnalyticsController is fully initialized.
      *

package/dist/AnalyticsPlatformAdapter.types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"AnalyticsPlatformAdapter.types.d.mts","sourceRoot":"","sources":["../src/AnalyticsPlatformAdapter.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAE5C;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAE5D;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAEvD;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,wBAAwB,CAAC;IACrC,mBAAmB,EAAE,wBAAwB,CAAC;IAC9C;;;;OAIG;IACH,iBAAiB,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;;;;;;OASG;IACH,KAAK,CACH,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,wBAAwB,EACrC,OAAO,CAAC,EAAE,gBAAgB,GACzB,IAAI,CAAC;IAER;;;;;;OAMG;IACH,QAAQ,CACN,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,gBAAgB,GACzB,IAAI,CAAC;IAER;;;;;;;;;;OAUG;IACH,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,wBAAwB,EACrC,OAAO,CAAC,EAAE,gBAAgB,GACzB,IAAI,CAAC;IAER;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7C,CAAC"}
+{"version":3,"file":"AnalyticsPlatformAdapter.types.d.mts","sourceRoot":"","sources":["../src/AnalyticsPlatformAdapter.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAE5C;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAE5D;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAEvD;;;GAGG;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AAEpE;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,SAAS,CAAC,EAAE,IAAI,CAAC;IAEjB;;OAEG;IACH,QAAQ,CAAC,EAAE,2BAA2B,CAAC;CACxC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,wBAAwB,CAAC;IACrC,mBAAmB,EAAE,wBAAwB,CAAC;IAC9C;;;;OAIG;IACH,iBAAiB,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;;;;;;;OAUG;IACH,KAAK,CACH,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,wBAAwB,EACrC,OAAO,CAAC,EAAE,gBAAgB,EAC1B,OAAO,CAAC,EAAE,wBAAwB,GACjC,IAAI,CAAC;IAER;;;;;;;OAOG;IACH,QAAQ,CACN,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,gBAAgB,EAC1B,OAAO,CAAC,EAAE,wBAAwB,GACjC,IAAI,CAAC;IAER;;;;;;;;;;;OAWG;IACH,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,wBAAwB,EACrC,OAAO,CAAC,EAAE,gBAAgB,EAC1B,OAAO,CAAC,EAAE,wBAAwB,GACjC,IAAI,CAAC;IAER;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7C,CAAC"}

package/dist/AnalyticsPlatformAdapter.types.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"AnalyticsPlatformAdapter.types.mjs","sourceRoot":"","sources":["../src/AnalyticsPlatformAdapter.types.ts"],"names":[],"mappings":"","sourcesContent":["import type { Json } from '@metamask/utils';\n\n/**\n * Analytics event properties\n */\nexport type AnalyticsEventProperties = Record<string, Json>;\n\n/**\n * User traits/properties for analytics identification\n */\nexport type AnalyticsUserTraits = Record<string, Json>;\n\n/**\n * Event properties structure with two distinct properties lists for regular and sensitive data.\n * Similar to ITrackingEvent from legacy analytics but decoupled for platform agnosticism.\n * Sensitivity is derived from the presence of sensitiveProperties (if sensitiveProperties has keys, the event is sensitive).\n */\nexport type AnalyticsTrackingEvent = {\n  readonly name: string;\n  properties: AnalyticsEventProperties;\n  sensitiveProperties: AnalyticsEventProperties;\n  /**\n   * Legacy property handled by the mobile app.\n   * This property is ignored by the analytics controller and will be removed from the type in the future.\n   * The mobile app will use the future analytics privacy controller to handle this functionality.\n   */\n  saveDataRecording: boolean;\n  readonly hasProperties: boolean;\n};\n\n/**\n * Optional analytics context payload (for example Segment-style context).\n */\nexport type AnalyticsContext = Record<string, Json>;\n\n/**\n * Platform adapter interface for analytics tracking\n * Implementations should handle platform-specific details (Segment SDK, etc.)\n */\nexport type AnalyticsPlatformAdapter = {\n  /**\n   * When `true`, the controller accepts any non-empty `analyticsId` string\n   * instead of requiring UUIDv4 format. Defaults to validation against UUIDv4 when omitted or `false`.\n   */\n  skipUUIDv4Check?: boolean;\n\n  /**\n   * Track an analytics event.\n   *\n   * This is the same as trackEvent in the old analytics system\n   *\n   * @param eventName - The name of the event\n   * @param properties - Event properties. If not provided, the event has no properties.\n   * The privacy plugin should check for `isSensitive === true` to determine if an event contains sensitive data.\n   * @param context - Optional platform-specific context attached to the invocation.\n   */\n  track(\n    eventName: string,\n    properties?: AnalyticsEventProperties,\n    context?: AnalyticsContext,\n  ): void;\n\n  /**\n   * Identify a user with traits.\n   *\n   * @param userId - The user identifier (e.g., metametrics ID)\n   * @param traits - User traits/properties\n   * @param context - Optional platform-specific context attached to the invocation.\n   */\n  identify(\n    userId: string,\n    traits?: AnalyticsUserTraits,\n    context?: AnalyticsContext,\n  ): void;\n\n  /**\n   * Track a UI unit (page or screen) view depending on the platform\n   *\n   * This method delegates to platform-specific Segment SDK methods:\n   * - Web adapters should call `analytics.page(name, properties)`\n   * - Mobile adapters should call `analytics.screen(name, properties)`\n   *\n   * @param name - The identifier/name of the page or screen being viewed (e.g., \"home\", \"settings\", \"wallet\")\n   * @param properties - Optional properties associated with the view\n   * @param context - Optional platform-specific context attached to the invocation.\n   */\n  view(\n    name: string,\n    properties?: AnalyticsEventProperties,\n    context?: AnalyticsContext,\n  ): void;\n\n  /**\n   * Lifecycle hook called after the AnalyticsController is fully initialized.\n   *\n   * This hook allows platform-specific adapters to perform setup that requires\n   * access to the controller's state (e.g., analyticsId).\n   *\n   * The controller calls this method once after initialization, passing the\n   * analyticsId from controller state. The analyticsId is guaranteed to be set\n   * when this method is called - this is the definition of \"completed\" setup.\n   *\n   * @param analyticsId - The analytics ID from controller state. Always set (never empty).\n   * @throws {AnalyticsPlatformAdapterSetupError} May throw errors during setup (e.g., configuration errors, network failures).\n   * Errors thrown by this method are caught and logged by the controller, but do not prevent\n   * controller initialization from completing successfully.\n   *\n   * @example\n   * ```typescript\n   * onSetupCompleted(analyticsId: string): void {\n   *   // Add platform-specific plugins that require analyticsId\n   *   client.add({\n   *     plugin: new PrivacyPlugin(analyticsId),\n   *   });\n   * }\n   * ```\n   */\n  onSetupCompleted(analyticsId: string): void;\n};\n"]}
+{"version":3,"file":"AnalyticsPlatformAdapter.types.mjs","sourceRoot":"","sources":["../src/AnalyticsPlatformAdapter.types.ts"],"names":[],"mappings":"","sourcesContent":["import type { Json } from '@metamask/utils';\n\n/**\n * Analytics event properties\n */\nexport type AnalyticsEventProperties = Record<string, Json>;\n\n/**\n * User traits/properties for analytics identification\n */\nexport type AnalyticsUserTraits = Record<string, Json>;\n\n/**\n * Callback invoked by the platform adapter after an analytics payload is\n * delivered or fails.\n */\nexport type AnalyticsInvocationCallback = (error?: unknown) => void;\n\n/**\n * Internal delivery metadata used by AnalyticsController when event queue\n * persistence is enabled.\n */\nexport type AnalyticsDeliveryOptions = {\n  /**\n   * Stable identifier for the analytics payload.\n   */\n  messageId?: string;\n\n  /**\n   * Original timestamp for the analytics payload.\n   */\n  timestamp?: Date;\n\n  /**\n   * Callback for delivery acknowledgement.\n   */\n  callback?: AnalyticsInvocationCallback;\n};\n\n/**\n * Event properties structure with two distinct properties lists for regular and sensitive data.\n * Similar to ITrackingEvent from legacy analytics but decoupled for platform agnosticism.\n * Sensitivity is derived from the presence of sensitiveProperties (if sensitiveProperties has keys, the event is sensitive).\n */\nexport type AnalyticsTrackingEvent = {\n  readonly name: string;\n  properties: AnalyticsEventProperties;\n  sensitiveProperties: AnalyticsEventProperties;\n  /**\n   * Legacy property handled by the mobile app.\n   * This property is ignored by the analytics controller and will be removed from the type in the future.\n   * The mobile app will use the future analytics privacy controller to handle this functionality.\n   */\n  saveDataRecording: boolean;\n  readonly hasProperties: boolean;\n};\n\n/**\n * Optional analytics context payload (for example Segment-style context).\n */\nexport type AnalyticsContext = Record<string, Json>;\n\n/**\n * Platform adapter interface for analytics tracking\n * Implementations should handle platform-specific details (Segment SDK, etc.)\n */\nexport type AnalyticsPlatformAdapter = {\n  /**\n   * When `true`, the controller accepts any non-empty `analyticsId` string\n   * instead of requiring UUIDv4 format. Defaults to validation against UUIDv4 when omitted or `false`.\n   */\n  skipUUIDv4Check?: boolean;\n\n  /**\n   * Track an analytics event.\n   *\n   * This is the same as trackEvent in the old analytics system\n   *\n   * @param eventName - The name of the event\n   * @param properties - Event properties. If not provided, the event has no properties.\n   * The privacy plugin should check for `isSensitive === true` to determine if an event contains sensitive data.\n   * @param context - Optional platform-specific context attached to the invocation.\n   * @param options - Optional delivery metadata for platform adapters.\n   */\n  track(\n    eventName: string,\n    properties?: AnalyticsEventProperties,\n    context?: AnalyticsContext,\n    options?: AnalyticsDeliveryOptions,\n  ): void;\n\n  /**\n   * Identify a user with traits.\n   *\n   * @param userId - The user identifier (e.g., metametrics ID)\n   * @param traits - User traits/properties\n   * @param context - Optional platform-specific context attached to the invocation.\n   * @param options - Optional delivery metadata for platform adapters.\n   */\n  identify(\n    userId: string,\n    traits?: AnalyticsUserTraits,\n    context?: AnalyticsContext,\n    options?: AnalyticsDeliveryOptions,\n  ): void;\n\n  /**\n   * Track a UI unit (page or screen) view depending on the platform\n   *\n   * This method delegates to platform-specific Segment SDK methods:\n   * - Web adapters should call `analytics.page(name, properties)`\n   * - Mobile adapters should call `analytics.screen(name, properties)`\n   *\n   * @param name - The identifier/name of the page or screen being viewed (e.g., \"home\", \"settings\", \"wallet\")\n   * @param properties - Optional properties associated with the view\n   * @param context - Optional platform-specific context attached to the invocation.\n   * @param options - Optional delivery metadata for platform adapters.\n   */\n  view(\n    name: string,\n    properties?: AnalyticsEventProperties,\n    context?: AnalyticsContext,\n    options?: AnalyticsDeliveryOptions,\n  ): void;\n\n  /**\n   * Lifecycle hook called after the AnalyticsController is fully initialized.\n   *\n   * This hook allows platform-specific adapters to perform setup that requires\n   * access to the controller's state (e.g., analyticsId).\n   *\n   * The controller calls this method once after initialization, passing the\n   * analyticsId from controller state. The analyticsId is guaranteed to be set\n   * when this method is called - this is the definition of \"completed\" setup.\n   *\n   * @param analyticsId - The analytics ID from controller state. Always set (never empty).\n   * @throws {AnalyticsPlatformAdapterSetupError} May throw errors during setup (e.g., configuration errors, network failures).\n   * Errors thrown by this method are caught and logged by the controller, but do not prevent\n   * controller initialization from completing successfully.\n   *\n   * @example\n   * ```typescript\n   * onSetupCompleted(analyticsId: string): void {\n   *   // Add platform-specific plugins that require analyticsId\n   *   client.add({\n   *     plugin: new PrivacyPlugin(analyticsId),\n   *   });\n   * }\n   * ```\n   */\n  onSetupCompleted(analyticsId: string): void;\n};\n"]}

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,8CAA8C;AAC9C,iEAG+B;AAF7B,0HAAA,mBAAmB,OAAA;AACnB,yIAAA,kCAAkC,OAAA;AAIpC,gBAAgB;AAChB,+FAA0F;AAAjF,wJAAA,kCAAkC,OAAA;AAc3C,mBAAmB;AACnB,6CAA2D;AAAlD,yHAAA,4BAA4B,OAAA","sourcesContent":["// Export controller class and state utilities\nexport {\n  AnalyticsController,\n  getDefaultAnalyticsControllerState,\n} from './AnalyticsController';\nexport type { AnalyticsControllerOptions } from './AnalyticsController';\n\n// Export errors\nexport { AnalyticsPlatformAdapterSetupError } from './AnalyticsPlatformAdapterSetupError';\n\n// Export types\nexport type {\n  AnalyticsContext,\n  AnalyticsEventProperties,\n  AnalyticsUserTraits,\n  AnalyticsPlatformAdapter,\n  AnalyticsTrackingEvent,\n} from './AnalyticsPlatformAdapter.types';\n\n// Export state types\nexport type { AnalyticsControllerState } from './AnalyticsController';\n\n// Export selectors\nexport { analyticsControllerSelectors } from './selectors';\n\n// Export messenger types\nexport type { AnalyticsControllerMessenger } from './AnalyticsController';\n\n// Export action and event types\nexport type {\n  AnalyticsControllerActions,\n  AnalyticsControllerEvents,\n  AnalyticsControllerGetStateAction,\n  AnalyticsControllerStateChangeEvent,\n} from './AnalyticsController';\nexport type {\n  AnalyticsControllerTrackEventAction,\n  AnalyticsControllerIdentifyAction,\n  AnalyticsControllerTrackViewAction,\n  AnalyticsControllerOptInAction,\n  AnalyticsControllerOptOutAction,\n  AnalyticsControllerMethodActions,\n} from './AnalyticsController-method-action-types';\n"]}
+{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,8CAA8C;AAC9C,iEAG+B;AAF7B,0HAAA,mBAAmB,OAAA;AACnB,yIAAA,kCAAkC,OAAA;AAIpC,gBAAgB;AAChB,+FAA0F;AAAjF,wJAAA,kCAAkC,OAAA;AAwB3C,mBAAmB;AACnB,6CAA2D;AAAlD,yHAAA,4BAA4B,OAAA","sourcesContent":["// Export controller class and state utilities\nexport {\n  AnalyticsController,\n  getDefaultAnalyticsControllerState,\n} from './AnalyticsController';\nexport type { AnalyticsControllerOptions } from './AnalyticsController';\n\n// Export errors\nexport { AnalyticsPlatformAdapterSetupError } from './AnalyticsPlatformAdapterSetupError';\n\n// Export types\nexport type {\n  AnalyticsContext,\n  AnalyticsEventProperties,\n  AnalyticsDeliveryOptions,\n  AnalyticsInvocationCallback,\n  AnalyticsUserTraits,\n  AnalyticsPlatformAdapter,\n  AnalyticsTrackingEvent,\n} from './AnalyticsPlatformAdapter.types';\n\n// Export state types\nexport type {\n  AnalyticsControllerState,\n  AnalyticsEventQueue,\n  AnalyticsQueuedEvent,\n  AnalyticsQueuedEventType,\n  AnalyticsQueuedTrackEvent,\n  AnalyticsQueuedIdentifyEvent,\n  AnalyticsQueuedViewEvent,\n} from './AnalyticsController';\n\n// Export selectors\nexport { analyticsControllerSelectors } from './selectors';\n\n// Export messenger types\nexport type { AnalyticsControllerMessenger } from './AnalyticsController';\n\n// Export action and event types\nexport type {\n  AnalyticsControllerActions,\n  AnalyticsControllerEvents,\n  AnalyticsControllerGetStateAction,\n  AnalyticsControllerStateChangeEvent,\n} from './AnalyticsController';\nexport type {\n  AnalyticsControllerTrackEventAction,\n  AnalyticsControllerIdentifyAction,\n  AnalyticsControllerTrackViewAction,\n  AnalyticsControllerOptInAction,\n  AnalyticsControllerOptOutAction,\n  AnalyticsControllerMethodActions,\n} from './AnalyticsController-method-action-types';\n"]}

package/dist/index.d.cts

@@ -1,8 +1,8 @@
 export { AnalyticsController, getDefaultAnalyticsControllerState, } from "./AnalyticsController.cjs";
 export type { AnalyticsControllerOptions } from "./AnalyticsController.cjs";
 export { AnalyticsPlatformAdapterSetupError } from "./AnalyticsPlatformAdapterSetupError.cjs";
-export type { AnalyticsContext, AnalyticsEventProperties, AnalyticsUserTraits, AnalyticsPlatformAdapter, AnalyticsTrackingEvent, } from "./AnalyticsPlatformAdapter.types.cjs";
-export type { AnalyticsControllerState } from "./AnalyticsController.cjs";
+export type { AnalyticsContext, AnalyticsEventProperties, AnalyticsDeliveryOptions, AnalyticsInvocationCallback, AnalyticsUserTraits, AnalyticsPlatformAdapter, AnalyticsTrackingEvent, } from "./AnalyticsPlatformAdapter.types.cjs";
+export type { AnalyticsControllerState, AnalyticsEventQueue, AnalyticsQueuedEvent, AnalyticsQueuedEventType, AnalyticsQueuedTrackEvent, AnalyticsQueuedIdentifyEvent, AnalyticsQueuedViewEvent, } from "./AnalyticsController.cjs";
 export { analyticsControllerSelectors } from "./selectors.cjs";
 export type { AnalyticsControllerMessenger } from "./AnalyticsController.cjs";
 export type { AnalyticsControllerActions, AnalyticsControllerEvents, AnalyticsControllerGetStateAction, AnalyticsControllerStateChangeEvent, } from "./AnalyticsController.cjs";

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,mBAAmB,EACnB,kCAAkC,GACnC,kCAA8B;AAC/B,YAAY,EAAE,0BAA0B,EAAE,kCAA8B;AAGxE,OAAO,EAAE,kCAAkC,EAAE,iDAA6C;AAG1F,YAAY,EACV,gBAAgB,EAChB,wBAAwB,EACxB,mBAAmB,EACnB,wBAAwB,EACxB,sBAAsB,GACvB,6CAAyC;AAG1C,YAAY,EAAE,wBAAwB,EAAE,kCAA8B;AAGtE,OAAO,EAAE,4BAA4B,EAAE,wBAAoB;AAG3D,YAAY,EAAE,4BAA4B,EAAE,kCAA8B;AAG1E,YAAY,EACV,0BAA0B,EAC1B,yBAAyB,EACzB,iCAAiC,EACjC,mCAAmC,GACpC,kCAA8B;AAC/B,YAAY,EACV,mCAAmC,EACnC,iCAAiC,EACjC,kCAAkC,EAClC,8BAA8B,EAC9B,+BAA+B,EAC/B,gCAAgC,GACjC,sDAAkD"}
+{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,mBAAmB,EACnB,kCAAkC,GACnC,kCAA8B;AAC/B,YAAY,EAAE,0BAA0B,EAAE,kCAA8B;AAGxE,OAAO,EAAE,kCAAkC,EAAE,iDAA6C;AAG1F,YAAY,EACV,gBAAgB,EAChB,wBAAwB,EACxB,wBAAwB,EACxB,2BAA2B,EAC3B,mBAAmB,EACnB,wBAAwB,EACxB,sBAAsB,GACvB,6CAAyC;AAG1C,YAAY,EACV,wBAAwB,EACxB,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,EACxB,yBAAyB,EACzB,4BAA4B,EAC5B,wBAAwB,GACzB,kCAA8B;AAG/B,OAAO,EAAE,4BAA4B,EAAE,wBAAoB;AAG3D,YAAY,EAAE,4BAA4B,EAAE,kCAA8B;AAG1E,YAAY,EACV,0BAA0B,EAC1B,yBAAyB,EACzB,iCAAiC,EACjC,mCAAmC,GACpC,kCAA8B;AAC/B,YAAY,EACV,mCAAmC,EACnC,iCAAiC,EACjC,kCAAkC,EAClC,8BAA8B,EAC9B,+BAA+B,EAC/B,gCAAgC,GACjC,sDAAkD"}

package/dist/index.d.mts

@@ -1,8 +1,8 @@
 export { AnalyticsController, getDefaultAnalyticsControllerState, } from "./AnalyticsController.mjs";
 export type { AnalyticsControllerOptions } from "./AnalyticsController.mjs";
 export { AnalyticsPlatformAdapterSetupError } from "./AnalyticsPlatformAdapterSetupError.mjs";
-export type { AnalyticsContext, AnalyticsEventProperties, AnalyticsUserTraits, AnalyticsPlatformAdapter, AnalyticsTrackingEvent, } from "./AnalyticsPlatformAdapter.types.mjs";
-export type { AnalyticsControllerState } from "./AnalyticsController.mjs";
+export type { AnalyticsContext, AnalyticsEventProperties, AnalyticsDeliveryOptions, AnalyticsInvocationCallback, AnalyticsUserTraits, AnalyticsPlatformAdapter, AnalyticsTrackingEvent, } from "./AnalyticsPlatformAdapter.types.mjs";
+export type { AnalyticsControllerState, AnalyticsEventQueue, AnalyticsQueuedEvent, AnalyticsQueuedEventType, AnalyticsQueuedTrackEvent, AnalyticsQueuedIdentifyEvent, AnalyticsQueuedViewEvent, } from "./AnalyticsController.mjs";
 export { analyticsControllerSelectors } from "./selectors.mjs";
 export type { AnalyticsControllerMessenger } from "./AnalyticsController.mjs";
 export type { AnalyticsControllerActions, AnalyticsControllerEvents, AnalyticsControllerGetStateAction, AnalyticsControllerStateChangeEvent, } from "./AnalyticsController.mjs";

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,mBAAmB,EACnB,kCAAkC,GACnC,kCAA8B;AAC/B,YAAY,EAAE,0BAA0B,EAAE,kCAA8B;AAGxE,OAAO,EAAE,kCAAkC,EAAE,iDAA6C;AAG1F,YAAY,EACV,gBAAgB,EAChB,wBAAwB,EACxB,mBAAmB,EACnB,wBAAwB,EACxB,sBAAsB,GACvB,6CAAyC;AAG1C,YAAY,EAAE,wBAAwB,EAAE,kCAA8B;AAGtE,OAAO,EAAE,4BAA4B,EAAE,wBAAoB;AAG3D,YAAY,EAAE,4BAA4B,EAAE,kCAA8B;AAG1E,YAAY,EACV,0BAA0B,EAC1B,yBAAyB,EACzB,iCAAiC,EACjC,mCAAmC,GACpC,kCAA8B;AAC/B,YAAY,EACV,mCAAmC,EACnC,iCAAiC,EACjC,kCAAkC,EAClC,8BAA8B,EAC9B,+BAA+B,EAC/B,gCAAgC,GACjC,sDAAkD"}
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,mBAAmB,EACnB,kCAAkC,GACnC,kCAA8B;AAC/B,YAAY,EAAE,0BAA0B,EAAE,kCAA8B;AAGxE,OAAO,EAAE,kCAAkC,EAAE,iDAA6C;AAG1F,YAAY,EACV,gBAAgB,EAChB,wBAAwB,EACxB,wBAAwB,EACxB,2BAA2B,EAC3B,mBAAmB,EACnB,wBAAwB,EACxB,sBAAsB,GACvB,6CAAyC;AAG1C,YAAY,EACV,wBAAwB,EACxB,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,EACxB,yBAAyB,EACzB,4BAA4B,EAC5B,wBAAwB,GACzB,kCAA8B;AAG/B,OAAO,EAAE,4BAA4B,EAAE,wBAAoB;AAG3D,YAAY,EAAE,4BAA4B,EAAE,kCAA8B;AAG1E,YAAY,EACV,0BAA0B,EAC1B,yBAAyB,EACzB,iCAAiC,EACjC,mCAAmC,GACpC,kCAA8B;AAC/B,YAAY,EACV,mCAAmC,EACnC,iCAAiC,EACjC,kCAAkC,EAClC,8BAA8B,EAC9B,+BAA+B,EAC/B,gCAAgC,GACjC,sDAAkD"}

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,OAAO,EACL,mBAAmB,EACnB,kCAAkC,EACnC,kCAA8B;AAG/B,gBAAgB;AAChB,OAAO,EAAE,kCAAkC,EAAE,iDAA6C;AAc1F,mBAAmB;AACnB,OAAO,EAAE,4BAA4B,EAAE,wBAAoB","sourcesContent":["// Export controller class and state utilities\nexport {\n  AnalyticsController,\n  getDefaultAnalyticsControllerState,\n} from './AnalyticsController';\nexport type { AnalyticsControllerOptions } from './AnalyticsController';\n\n// Export errors\nexport { AnalyticsPlatformAdapterSetupError } from './AnalyticsPlatformAdapterSetupError';\n\n// Export types\nexport type {\n  AnalyticsContext,\n  AnalyticsEventProperties,\n  AnalyticsUserTraits,\n  AnalyticsPlatformAdapter,\n  AnalyticsTrackingEvent,\n} from './AnalyticsPlatformAdapter.types';\n\n// Export state types\nexport type { AnalyticsControllerState } from './AnalyticsController';\n\n// Export selectors\nexport { analyticsControllerSelectors } from './selectors';\n\n// Export messenger types\nexport type { AnalyticsControllerMessenger } from './AnalyticsController';\n\n// Export action and event types\nexport type {\n  AnalyticsControllerActions,\n  AnalyticsControllerEvents,\n  AnalyticsControllerGetStateAction,\n  AnalyticsControllerStateChangeEvent,\n} from './AnalyticsController';\nexport type {\n  AnalyticsControllerTrackEventAction,\n  AnalyticsControllerIdentifyAction,\n  AnalyticsControllerTrackViewAction,\n  AnalyticsControllerOptInAction,\n  AnalyticsControllerOptOutAction,\n  AnalyticsControllerMethodActions,\n} from './AnalyticsController-method-action-types';\n"]}
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,OAAO,EACL,mBAAmB,EACnB,kCAAkC,EACnC,kCAA8B;AAG/B,gBAAgB;AAChB,OAAO,EAAE,kCAAkC,EAAE,iDAA6C;AAwB1F,mBAAmB;AACnB,OAAO,EAAE,4BAA4B,EAAE,wBAAoB","sourcesContent":["// Export controller class and state utilities\nexport {\n  AnalyticsController,\n  getDefaultAnalyticsControllerState,\n} from './AnalyticsController';\nexport type { AnalyticsControllerOptions } from './AnalyticsController';\n\n// Export errors\nexport { AnalyticsPlatformAdapterSetupError } from './AnalyticsPlatformAdapterSetupError';\n\n// Export types\nexport type {\n  AnalyticsContext,\n  AnalyticsEventProperties,\n  AnalyticsDeliveryOptions,\n  AnalyticsInvocationCallback,\n  AnalyticsUserTraits,\n  AnalyticsPlatformAdapter,\n  AnalyticsTrackingEvent,\n} from './AnalyticsPlatformAdapter.types';\n\n// Export state types\nexport type {\n  AnalyticsControllerState,\n  AnalyticsEventQueue,\n  AnalyticsQueuedEvent,\n  AnalyticsQueuedEventType,\n  AnalyticsQueuedTrackEvent,\n  AnalyticsQueuedIdentifyEvent,\n  AnalyticsQueuedViewEvent,\n} from './AnalyticsController';\n\n// Export selectors\nexport { analyticsControllerSelectors } from './selectors';\n\n// Export messenger types\nexport type { AnalyticsControllerMessenger } from './AnalyticsController';\n\n// Export action and event types\nexport type {\n  AnalyticsControllerActions,\n  AnalyticsControllerEvents,\n  AnalyticsControllerGetStateAction,\n  AnalyticsControllerStateChangeEvent,\n} from './AnalyticsController';\nexport type {\n  AnalyticsControllerTrackEventAction,\n  AnalyticsControllerIdentifyAction,\n  AnalyticsControllerTrackViewAction,\n  AnalyticsControllerOptInAction,\n  AnalyticsControllerOptOutAction,\n  AnalyticsControllerMethodActions,\n} from './AnalyticsController-method-action-types';\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamask-previews/analytics-controller",
-  "version": "1.0.1-preview-8e8c4f6f5",
+  "version": "1.1.0-preview-e43dfcb",
   "description": "Common Analytics controller for event tracking",
   "keywords": [
     "Ethereum",
@@ -55,12 +55,15 @@
   "dependencies": {
     "@metamask/base-controller": "^9.1.0",
     "@metamask/messenger": "^1.2.0",
-    "@metamask/utils": "^11.9.0"
+    "@metamask/utils": "^11.9.0",
+    "lodash": "^4.17.21",
+    "uuid": "^8.3.2"
   },
   "devDependencies": {
     "@metamask/auto-changelog": "^6.1.0",
     "@ts-bridge/cli": "^0.6.4",
     "@types/jest": "^29.5.14",
+    "@types/uuid": "^8.3.0",
     "deepmerge": "^4.2.2",
     "jest": "^29.7.0",
     "ts-jest": "^29.2.5",