@metamask-previews/analytics-controller 3.0.0-preview-f67925e6c → 3.0.0-preview-3e86f66f7

package/dist/AnalyticsController.js

@@ -21,6 +21,20 @@ export const controllerName = 'AnalyticsController';
  * `properties` or `sensitiveProperties` in storage indefinitely.
  */
 export const EVENT_FRAGMENT_MAX_AGE = 24 * 60 * 60 * 1000;
+/**
+ * Purposes for which an analytics payload can be used.
+ */
+export const AnalyticsPurpose = {
+    Product: 'product',
+    Marketing: 'marketing',
+};
+/**
+ * Persisted queues on {@link AnalyticsControllerState}.
+ */
+const AnalyticsQueue = {
+    EventQueue: 'eventQueue',
+    PreConsentEventQueue: 'preConsentEventQueue',
+};
 /**
  * Returns default values for AnalyticsController state.
  *
@@ -33,6 +47,8 @@ export function getDefaultAnalyticsControllerState() {
     return {
         optedIn: false,
         consentDecisionMade: false,
+        optedInToMarketing: false,
+        marketingConsentDecisionMade: false,
     };
 }
 /**
@@ -48,6 +64,24 @@ const analyticsControllerMetadata = {
         includeInDebugSnapshot: true,
         usedInUi: true,
     },
+    optedInToMarketing: {
+        includeInStateLogs: true,
+        persist: true,
+        includeInDebugSnapshot: true,
+        usedInUi: true,
+    },
+    marketingConsentDecisionMade: {
+        includeInStateLogs: true,
+        persist: true,
+        includeInDebugSnapshot: true,
+        usedInUi: true,
+    },
+    eventsConfig: {
+        includeInStateLogs: true,
+        persist: true,
+        includeInDebugSnapshot: true,
+        usedInUi: false,
+    },
     analyticsId: {
         includeInStateLogs: true,
         persist: true,
@@ -87,6 +121,9 @@ const MESSENGER_EXPOSED_METHODS = [
     'optIn',
     'optOut',
     'resetConsentDecision',
+    'optInToMarketing',
+    'optOutOfMarketing',
+    'resetMarketingConsentDecision',
     'createEventFragment',
     'upsertEventFragment',
     'updateEventFragment',
@@ -103,6 +140,22 @@ const MESSENGER_EXPOSED_METHODS = [
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
+function isAnalyticsPurpose(value) {
+    return (value === AnalyticsPurpose.Product || value === AnalyticsPurpose.Marketing);
+}
+function isEventPurposesRecord(value) {
+    return (isRecord(value) &&
+        Object.values(value).every((purposes) => Array.isArray(purposes) &&
+            purposes.length > 0 &&
+            purposes.every(isAnalyticsPurpose)));
+}
+function isAnalyticsEventsConfig(value) {
+    return (isRecord(value) &&
+        typeof value.schemaVersion === 'string' &&
+        typeof value.version === 'string' &&
+        typeof value.timestamp === 'number' &&
+        isEventPurposesRecord(value.events));
+}
 /**
  * Returns whether a JSON value is a non-array object.
  *
@@ -144,7 +197,12 @@ function isAnalyticsQueuedEvent(value) {
         return false;
     }
     if (typeof value.messageId !== 'string' ||
-        typeof value.timestamp !== 'string') {
+        typeof value.timestamp !== 'string' ||
+        (value.eventPurposes !== undefined &&
+            (!Array.isArray(value.eventPurposes) ||
+                !value.eventPurposes.every(isAnalyticsPurpose))) ||
+        (value.eventsConfigVersion !== undefined &&
+            typeof value.eventsConfigVersion !== 'string')) {
         return false;
     }
     if (value.type === 'track') {
@@ -185,6 +243,10 @@ function isAnalyticsEventFragment(value) {
             typeof value.successEvent === 'string') &&
         (value.failureEvent === undefined ||
             typeof value.failureEvent === 'string') &&
+        (value.eventPurposes === undefined ||
+            isEventPurposesRecord(value.eventPurposes)) &&
+        (value.eventsConfigVersion === undefined ||
+            typeof value.eventsConfigVersion === 'string') &&
         (value.context === undefined || isRecord(value.context)) &&
         (value.persist === undefined || typeof value.persist === 'boolean'));
 }
@@ -214,18 +276,17 @@ function mergeEventFragment(fragment, payload) {
     };
 }
 /**
- * Merges two optional analytics contexts, preserving `undefined` when neither
- * side has one so an empty context is never sent.
+ * Merges two optional analytics contexts.
  *
  * @param base - The context to merge into.
- * @param override - The context whose fields win.
+ * @param override - The context whose fields win. When omitted, `base` is kept.
  * @returns The merged context, or `undefined` when both sides are unset.
  */
 function mergeEventFragmentContext(base, override) {
-    if (base === undefined && override === undefined) {
-        return undefined;
+    if (override === undefined) {
+        return base;
     }
-    return { ...(base ?? {}), ...(override ?? {}) };
+    return { ...(base ?? {}), ...override };
 }
 /**
  * The AnalyticsController manages analytics tracking across platforms (Mobile/Extension).
@@ -247,6 +308,11 @@ export class AnalyticsController extends BaseController {
     #isPreConsentQueueEnabled;
     #isGeolocationEnabled;
     #isEventFragmentsEnabled;
+    /**
+     * In-memory event-purpose lookup from persisted state.
+     */
+    #eventPurposes;
+    #eventsConfigVersion;
     /**
      * The in-flight (or settled) initialization promise. Set on the first
      * {@link init} call and returned by subsequent calls so overlapping callers
@@ -280,6 +346,15 @@ export class AnalyticsController extends BaseController {
             ...getDefaultAnalyticsControllerState(),
             ...state,
         };
+        const eventsConfig = isAnalyticsEventsConfig(initialState.eventsConfig)
+            ? initialState.eventsConfig
+            : undefined;
+        if (eventsConfig === undefined) {
+            delete initialState.eventsConfig;
+        }
+        else {
+            initialState.eventsConfig = eventsConfig;
+        }
         validateAnalyticsControllerState(initialState, platformAdapter.skipUUIDv4Check === true);
         super({
             name: controllerName,
@@ -295,10 +370,14 @@ export class AnalyticsController extends BaseController {
         this.#platformAdapter = platformAdapter;
         this.#initPromise = undefined;
         this.#locationResolvePromise = undefined;
+        this.#eventPurposes = new Map(Object.entries(eventsConfig?.events ?? {}));
+        this.#eventsConfigVersion = eventsConfig?.version;
         this.messenger.registerMethodActionHandlers(this, MESSENGER_EXPOSED_METHODS);
         log('AnalyticsController initialized and ready', {
             enabled: analyticsControllerSelectors.selectEnabled(this.state),
             optedIn: this.state.optedIn,
+            optedInToMarketing: this.state.optedInToMarketing === true,
+            marketingConsentDecisionMade: this.state.marketingConsentDecisionMade === true,
             consentDecisionMade: this.state.consentDecisionMade,
             analyticsId: this.state.analyticsId,
             eventQueuePersistenceEnabled: this.#isEventQueuePersistenceEnabled,
@@ -313,10 +392,11 @@ export class AnalyticsController extends BaseController {
      * method must be called after construction to complete the setup process.
      *
      * When geolocation enrichment is enabled (`isGeolocationEnabled`), geolocation
-     * is resolved only for a user who is already opted in; for undecided or
-     * opted-out users it is deferred until they opt in (see {@link optIn}), so a
-     * user's location is never requested before they consent to analytics. In
-     * either case the `GeolocationController` and its
+     * is resolved only for a user who is already opted in to product or marketing
+     * analytics. For users undecided or opted out of both purposes, it is
+     * deferred until they opt in to either one (see {@link optIn} and
+     * {@link optInToMarketing}), so a user's location is never requested before
+     * they consent to analytics. In either case the `GeolocationController` and its
      * `GeolocationController:getGeolocationData` action must be registered before
      * resolution occurs, or enrichment is skipped for the session (a message is
      * logged, see {@link #resolveLocationContext}).
@@ -350,9 +430,11 @@ export class AnalyticsController extends BaseController {
                 initEventFragmentSnapshot.set(id, fragment.createdAt);
             }
         }
-        // Resolve geolocation only when the user is already opted in; for undecided
-        // or opted-out users it is deferred to {@link optIn}. Awaited so that an
-        // already-opted-in session has location available before events replay.
+        await this.#fetchEventsConfig();
+        // Resolve geolocation only when the user is already opted in to product or
+        // marketing analytics. For undecided or opted-out users it is deferred to
+        // {@link optIn} / {@link optInToMarketing}. Awaited so that an already-opted-in
+        // session has location available before events replay.
         await this.#maybeResolveLocation();
         // Call onSetupCompleted lifecycle hook after initialization
         // State is already validated, so analyticsId is guaranteed to be a valid UUIDv4
@@ -364,20 +446,20 @@ export class AnalyticsController extends BaseController {
             log('Error calling platformAdapter.onSetupCompleted', error);
         }
         this.#replayQueuedEvents();
-        this.#reconcilePreConsentEvents();
+        this.#replayPreConsentEvents();
         this.#reconcileEventFragments(initEventFragmentSnapshot);
     }
     /**
      * Start resolving the geolocation context if warranted, and return the
      * in-flight (or settled) resolution so callers can await it. No-op unless
-     * enrichment is enabled, the user is opted in, and a resolution has not
-     * already been started. Deferring resolution until opt-in ensures a user's
-     * location is never requested before they consent to analytics (for example,
-     * during onboarding).
+     * enrichment is enabled, the user is opted in to product or marketing
+     * analytics, and a resolution has not already been started. Deferring
+     * resolution until consent ensures a user's location is never requested before
+     * they consent to analytics (for example, during onboarding).
      *
      * Resolution runs at most once per controller session: the settled promise
-     * is retained, so the outcome — including a failure (see
-     * {@link #resolveLocationContext}) — is not retried, and events are delivered
+     * is retained, so the outcome, including a failure (see
+     * {@link #resolveLocationContext}) is not retried, and events are delivered
      * without location for the rest of the session.
      *
      * @returns The geolocation resolution promise, or `undefined` when no
@@ -386,7 +468,7 @@ export class AnalyticsController extends BaseController {
     #maybeResolveLocation() {
         if (this.#isGeolocationEnabled &&
             this.#locationResolvePromise === undefined &&
-            analyticsControllerSelectors.selectEnabled(this.state)) {
+            (this.state.optedIn || this.state.optedInToMarketing === true)) {
             this.#locationResolvePromise = this.#resolveLocationContext();
         }
         return this.#locationResolvePromise;
@@ -427,18 +509,131 @@ export class AnalyticsController extends BaseController {
             },
         };
     }
+    /**
+     * Stamp the purposes currently allowed for a payload using Segment's consent
+     * context shape.
+     *
+     * @param purposes - Purposes for which the payload is eligible.
+     * @param context - Optional caller-provided context.
+     * @param version - Config version captured with the payload.
+     * @returns Context with allowed purpose preferences.
+     */
+    #withConsentContext(purposes, context, version) {
+        const preferences = this.#allowedPurposePreferences(purposes);
+        const { consent: existingConsent, eventsConfigVersion: _ignoredVersion, ...unmanagedContext } = context ?? {};
+        const consent = isJsonRecord(existingConsent)
+            ? existingConsent
+            : {};
+        const existingCategoryPreferences = isJsonRecord(consent.categoryPreferences)
+            ? consent.categoryPreferences
+            : {};
+        return {
+            ...unmanagedContext,
+            consent: {
+                ...consent,
+                categoryPreferences: {
+                    ...existingCategoryPreferences,
+                    ...preferences,
+                },
+            },
+            ...(version === undefined ? {} : { eventsConfigVersion: version }),
+        };
+    }
+    /**
+     * Load event-purpose configuration.
+     *
+     * Phase 1 stub. Persisted configuration remains authoritative until a remote
+     * source is wired up.
+     */
+    async #fetchEventsConfig() {
+        // Intentionally empty until an events-config source is wired up.
+    }
+    #purposesFromName(name) {
+        return [...(this.#eventPurposes.get(name) ?? [AnalyticsPurpose.Product])];
+    }
+    #purposesFromQueuedEvent(queuedEvent) {
+        if (queuedEvent.type === 'identify') {
+            return [AnalyticsPurpose.Product];
+        }
+        if (queuedEvent.eventPurposes !== undefined) {
+            return [...queuedEvent.eventPurposes];
+        }
+        return this.#purposesFromName(queuedEvent.type === 'view' ? queuedEvent.name : queuedEvent.eventName);
+    }
+    #eventNamesFromFragment(fragment) {
+        return [
+            fragment.initialEvent,
+            fragment.successEvent,
+            fragment.failureEvent,
+        ].filter((name) => typeof name === 'string');
+    }
+    #purposesFromFragmentEvent(fragment, name) {
+        return [
+            ...(fragment.eventPurposes?.[name] ?? this.#purposesFromName(name)),
+        ];
+    }
+    #purposesFromFragment(fragment) {
+        const names = this.#eventNamesFromFragment(fragment);
+        if (names.length === 0) {
+            // Nameless property bags have no event to classify. Treat them as
+            // eligible for any purpose so they can accumulate when either consent
+            // allows capture.
+            return Object.values(AnalyticsPurpose);
+        }
+        return [
+            ...new Set(names.flatMap((name) => this.#purposesFromFragmentEvent(fragment, name))),
+        ];
+    }
+    #consent(purpose) {
+        return purpose === AnalyticsPurpose.Marketing
+            ? {
+                optedIn: this.state.optedInToMarketing === true,
+                decisionMade: this.state.marketingConsentDecisionMade === true,
+            }
+            : {
+                optedIn: this.state.optedIn,
+                decisionMade: this.state.consentDecisionMade === true,
+            };
+    }
+    #allowedPurposePreferences(purposes) {
+        return {
+            product: purposes.includes(AnalyticsPurpose.Product) &&
+                this.#consent(AnalyticsPurpose.Product).optedIn,
+            marketing: purposes.includes(AnalyticsPurpose.Marketing) &&
+                this.#consent(AnalyticsPurpose.Marketing).optedIn,
+        };
+    }
+    #hasAllowedPurpose(purposes) {
+        const { product, marketing } = this.#allowedPurposePreferences(purposes);
+        return product || marketing;
+    }
+    #hasUndecidedPurpose(purposes) {
+        return purposes.some((purpose) => !this.#consent(purpose).decisionMade);
+    }
+    #isCaptureAllowed(purposes) {
+        return (this.#hasAllowedPurpose(purposes) ||
+            (this.#isPreConsentQueueEnabled && this.#hasUndecidedPurpose(purposes)));
+    }
+    #replaceQueue(field, nextQueue) {
+        this.update((state) => {
+            state[field] = nextQueue;
+        });
+    }
     /**
      * Send final track payload through the platform adapter or queue it if persistence is enabled.
      *
      * @param eventName - The name of the event.
      * @param properties - Optional event properties.
      * @param context - Optional platform-specific context.
+     * @param purposes - Capture-time purposes for the event.
+     * @param version - Capture-time events config version.
      */
-    #sendOrQueueTrackEvent(eventName, properties, context) {
+    #sendOrQueueTrackEvent(eventName, properties, context, purposes, version) {
+        const isAllowed = this.#hasAllowedPurpose(purposes);
+        const contextWithConsent = this.#withConsentContext(purposes, context, version);
         // Direct delivery: enabled and not persisting.
-        if (analyticsControllerSelectors.selectEnabled(this.state) &&
-            !this.#isEventQueuePersistenceEnabled) {
-            this.#platformAdapter.track(eventName, properties, context);
+        if (isAllowed && !this.#isEventQueuePersistenceEnabled) {
+            this.#platformAdapter.track(eventName, properties, contextWithConsent);
             return;
         }
         const queuedEvent = {
@@ -447,11 +642,11 @@ export class AnalyticsController extends BaseController {
             messageId: uuid(),
             timestamp: new Date().toISOString(),
             ...(properties === undefined ? {} : { properties }),
-            ...(context === undefined ? {} : { context }),
+            context: contextWithConsent,
+            eventPurposes: purposes,
+            ...(version === undefined ? {} : { eventsConfigVersion: version }),
         };
-        // Not yet enabled (reached only while undecided with the pre-consent queue
-        // enabled): hold the event until the user opts in.
-        if (!analyticsControllerSelectors.selectEnabled(this.state)) {
+        if (!isAllowed) {
             this.#enqueuePreConsentEvent(queuedEvent);
             return;
         }
@@ -465,8 +660,10 @@ export class AnalyticsController extends BaseController {
      * @param context - Optional platform-specific context.
      */
     #sendOrQueueIdentifyEvent(userId, traits, context) {
+        const purposes = [AnalyticsPurpose.Product];
+        const contextWithConsent = this.#withConsentContext(purposes, context);
         if (!this.#isEventQueuePersistenceEnabled) {
-            this.#platformAdapter.identify(userId, traits, context);
+            this.#platformAdapter.identify(userId, traits, contextWithConsent);
             return;
         }
         const queuedEvent = {
@@ -475,7 +672,8 @@ export class AnalyticsController extends BaseController {
             messageId: uuid(),
             timestamp: new Date().toISOString(),
             ...(traits === undefined ? {} : { traits }),
-            ...(context === undefined ? {} : { context }),
+            context: contextWithConsent,
+            eventPurposes: purposes,
         };
         this.#enqueueEvent(queuedEvent);
     }
@@ -485,10 +683,14 @@ export class AnalyticsController extends BaseController {
      * @param name - The view name.
      * @param properties - Optional view properties.
      * @param context - Optional platform-specific context.
+     * @param purposes - Capture-time purposes for the view.
+     * @param version - Capture-time events config version.
      */
-    #sendOrQueueViewEvent(name, properties, context) {
-        if (!this.#isEventQueuePersistenceEnabled) {
-            this.#platformAdapter.view(name, properties, context);
+    #sendOrQueueViewEvent(name, properties, context, purposes, version) {
+        const isAllowed = this.#hasAllowedPurpose(purposes);
+        const contextWithConsent = this.#withConsentContext(purposes, context, version);
+        if (isAllowed && !this.#isEventQueuePersistenceEnabled) {
+            this.#platformAdapter.view(name, properties, contextWithConsent);
             return;
         }
         const queuedEvent = {
@@ -497,8 +699,14 @@ export class AnalyticsController extends BaseController {
             messageId: uuid(),
             timestamp: new Date().toISOString(),
             ...(properties === undefined ? {} : { properties }),
-            ...(context === undefined ? {} : { context }),
+            context: contextWithConsent,
+            eventPurposes: purposes,
+            ...(version === undefined ? {} : { eventsConfigVersion: version }),
         };
+        if (!isAllowed) {
+            this.#enqueuePreConsentEvent(queuedEvent);
+            return;
+        }
         this.#enqueueEvent(queuedEvent);
     }
     /**
@@ -568,17 +776,23 @@ export class AnalyticsController extends BaseController {
         if (!this.#isEventQueuePersistenceEnabled || !this.state.eventQueue) {
             return;
         }
-        if (!analyticsControllerSelectors.selectEnabled(this.state)) {
-            this.#clearQueuedEvents();
-            return;
-        }
+        const remainingQueue = {};
+        const eventsToSend = [];
         for (const [messageId, queuedEvent] of Object.entries(this.state.eventQueue)) {
             if (!isAnalyticsQueuedEvent(queuedEvent) ||
                 queuedEvent.messageId !== messageId) {
                 log('Dropping invalid queued analytics event', { messageId });
-                this.#removeQueuedEvent(messageId);
                 continue;
             }
+            const purposes = this.#purposesFromQueuedEvent(queuedEvent);
+            if (this.#hasAllowedPurpose(purposes)) {
+                const refreshedEvent = this.#refreshQueuedEventConsent(queuedEvent);
+                remainingQueue[messageId] = refreshedEvent;
+                eventsToSend.push(refreshedEvent);
+            }
+        }
+        this.#replaceQueue(AnalyticsQueue.EventQueue, remainingQueue);
+        for (const queuedEvent of eventsToSend) {
             this.#sendQueuedEvent(queuedEvent);
         }
     }
@@ -598,17 +812,59 @@ export class AnalyticsController extends BaseController {
             state.eventQueue = eventQueue;
         });
     }
+    #refreshQueuedEventConsent(queuedEvent) {
+        // Refresh only the consent stamp. Capture-time `eventPurposes` and
+        // `eventsConfigVersion` stay as a pair and are never rewritten here.
+        const purposes = this.#purposesFromQueuedEvent(queuedEvent);
+        const preferences = this.#allowedPurposePreferences(purposes);
+        const existingPreferences = isJsonRecord(queuedEvent.context?.consent)
+            ? queuedEvent.context.consent.categoryPreferences
+            : undefined;
+        if (isJsonRecord(existingPreferences) &&
+            existingPreferences.product === preferences.product &&
+            existingPreferences.marketing === preferences.marketing) {
+            return queuedEvent;
+        }
+        return {
+            ...queuedEvent,
+            context: this.#withConsentContext(purposes, queuedEvent.context, queuedEvent.eventsConfigVersion),
+        };
+    }
     /**
-     * Clear all queued analytics events.
+     * Prune a queue after a consent change.
+     *
+     * For {@link AnalyticsQueue.EventQueue}, entries are kept only while at least
+     * one capture-time purpose is opted in, and their consent stamp is refreshed.
+     * For {@link AnalyticsQueue.PreConsentEventQueue}, entries are kept while at
+     * least one purpose is still allowed or undecided.
+     *
+     * @param field - The queue to prune.
      */
-    #clearQueuedEvents() {
-        if (!this.state.eventQueue ||
-            Object.keys(this.state.eventQueue).length === 0) {
+    #pruneQueueForConsent(field) {
+        const queue = this.state[field];
+        if (!queue) {
             return;
         }
-        this.update((state) => {
-            state.eventQueue = {};
-        });
+        const nextQueue = {};
+        for (const [messageId, queuedEvent] of Object.entries(queue)) {
+            if (!isAnalyticsQueuedEvent(queuedEvent) ||
+                queuedEvent.messageId !== messageId) {
+                continue;
+            }
+            const purposes = this.#purposesFromQueuedEvent(queuedEvent);
+            const isAllowed = this.#hasAllowedPurpose(purposes);
+            if (field === AnalyticsQueue.EventQueue) {
+                if (isAllowed) {
+                    nextQueue[messageId] = this.#refreshQueuedEventConsent(queuedEvent);
+                }
+            }
+            if (field === AnalyticsQueue.PreConsentEventQueue) {
+                if (isAllowed || this.#hasUndecidedPurpose(purposes)) {
+                    nextQueue[messageId] = queuedEvent;
+                }
+            }
+        }
+        this.#replaceQueue(field, nextQueue);
     }
     /**
      * Add an event to the pre-consent queue without delivering it.
@@ -624,34 +880,6 @@ export class AnalyticsController extends BaseController {
             state.preConsentEventQueue = preConsentEventQueue;
         });
     }
-    /**
-     * Replay queued pre-consent events through the delivery path.
-     *
-     * Only called by {@link #reconcilePreConsentEvents}, which guarantees the
-     * pre-consent queue is enabled and that the user is opted in. The queue is
-     * cleared before replaying so events cannot be re-queued or replayed twice.
-     *
-     * @param queue - The pre-consent event queue to replay.
-     */
-    #replayPreConsentEvents(queue) {
-        this.#clearPreConsentEvents();
-        for (const [messageId, queuedEvent] of Object.entries(queue)) {
-            if (!isAnalyticsQueuedEvent(queuedEvent) ||
-                queuedEvent.messageId !== messageId) {
-                log('Dropping invalid queued pre-consent analytics event', {
-                    messageId,
-                });
-                continue;
-            }
-            const eventToReplay = this.#enrichPreConsentEvent(queuedEvent);
-            if (this.#isEventQueuePersistenceEnabled) {
-                this.#enqueueEvent(eventToReplay);
-            }
-            else {
-                this.#sendQueuedEvent(eventToReplay);
-            }
-        }
-    }
     /**
      * Enrich a pre-consent event with the geolocation resolved on opt-in.
      *
@@ -675,42 +903,52 @@ export class AnalyticsController extends BaseController {
         };
     }
     /**
-     * Clear all queued pre-consent events.
-     */
-    #clearPreConsentEvents() {
-        if (!this.state.preConsentEventQueue) {
-            return;
-        }
-        this.update((state) => {
-            state.preConsentEventQueue = {};
-        });
-    }
-    /**
-     * Reconcile the pre-consent queue on initialization.
+     * Replay eligible pre-consent events against current consent.
      *
-     * The queue should normally be empty unless the user is still undecided. This
-     * handles the rare cases where a consent decision was persisted but the queue
-     * was not flushed/cleared (e.g. an interrupted shutdown): replay it if the
-     * user is opted in, or clear it if they opted out.
+     * Allowed entries are replayed, undecided entries are kept for later, and
+     * entries with no remaining allowed or undecided purpose are dropped. The
+     * keep set is written before replay so events cannot be re-queued or
+     * replayed twice.
      *
      * If the pre-consent queue is disabled, any stale persisted entries (e.g. from
      * a previous session where it was enabled) are dropped so they can never be
      * replayed.
      */
-    #reconcilePreConsentEvents() {
+    #replayPreConsentEvents() {
         const queue = this.state.preConsentEventQueue;
         if (!queue) {
             return;
         }
         if (!this.#isPreConsentQueueEnabled) {
-            this.#clearPreConsentEvents();
+            this.update((state) => {
+                state.preConsentEventQueue = {};
+            });
             return;
         }
-        if (this.state.optedIn) {
-            this.#replayPreConsentEvents(queue);
+        const keep = {};
+        const replay = [];
+        for (const [messageId, queuedEvent] of Object.entries(queue)) {
+            if (!isAnalyticsQueuedEvent(queuedEvent) ||
+                queuedEvent.messageId !== messageId) {
+                continue;
+            }
+            const purposes = this.#purposesFromQueuedEvent(queuedEvent);
+            if (this.#hasAllowedPurpose(purposes)) {
+                replay.push(queuedEvent);
+            }
+            else if (this.#hasUndecidedPurpose(purposes)) {
+                keep[messageId] = queuedEvent;
+            }
         }
-        else if (this.state.consentDecisionMade) {
-            this.#clearPreConsentEvents();
+        this.#replaceQueue(AnalyticsQueue.PreConsentEventQueue, keep);
+        for (const queuedEvent of replay) {
+            const eventToReplay = this.#refreshQueuedEventConsent(this.#enrichPreConsentEvent(queuedEvent));
+            if (this.#isEventQueuePersistenceEnabled) {
+                this.#enqueueEvent(eventToReplay);
+            }
+            else {
+                this.#sendQueuedEvent(eventToReplay);
+            }
         }
     }
     /**
@@ -723,9 +961,8 @@ export class AnalyticsController extends BaseController {
      * finalization is not a failure, just an unfinished one.
      *
      * If the feature is disabled (e.g. a previous session had it enabled), or the
-     * consent state no longer allows capture (e.g. the fragments were written
-     * before the user opted out), every persisted fragment is dropped so none of
-     * them can linger.
+     * consent state no longer allows capture for any of a fragment's purposes,
+     * those fragments are dropped so none of them can linger.
      *
      * Non-persistent fragments are dropped only when their ID and `createdAt`
      * match a fragment present at the start of {@link init}. Fragments created
@@ -740,28 +977,13 @@ export class AnalyticsController extends BaseController {
         if (!fragments) {
             return;
         }
-        if (!this.#isEventFragmentsEnabled || !this.#isAnalyticsCaptureAllowed()) {
+        if (!this.#isEventFragmentsEnabled) {
             this.#clearEventFragments();
             return;
         }
-        this.#purgeStaleEventFragments(fragments, initEventFragmentSnapshot);
-    }
-    /**
-     * Drop every persisted fragment that is invalid, expired, did not opt into
-     * `persist`, or was already present with the same `createdAt` when
-     * {@link init} began.
-     *
-     * Only called by {@link #reconcileEventFragments}, which guarantees the
-     * fragments exist and that the event fragments feature is enabled.
-     *
-     * @param currentEventFragments - The persisted fragments to filter.
-     * @param initEventFragmentSnapshot - Fragment IDs and `createdAt` values
-     * present when {@link init} began.
-     */
-    #purgeStaleEventFragments(currentEventFragments, initEventFragmentSnapshot) {
         const eventFragments = {};
         const now = Date.now();
-        for (const [id, fragment] of Object.entries(currentEventFragments)) {
+        for (const [id, fragment] of Object.entries(fragments)) {
             if (!isAnalyticsEventFragment(fragment) || fragment.id !== id) {
                 log('Dropping invalid persisted event fragment', { id });
                 continue;
@@ -770,6 +992,9 @@ export class AnalyticsController extends BaseController {
                 log('Dropping expired persisted event fragment', { id });
                 continue;
             }
+            if (!this.#isCaptureAllowed(this.#purposesFromFragment(fragment))) {
+                continue;
+            }
             const snapshotCreatedAt = initEventFragmentSnapshot.get(id);
             if (fragment.persist === true ||
                 snapshotCreatedAt === undefined ||
@@ -777,8 +1002,11 @@ export class AnalyticsController extends BaseController {
                 eventFragments[id] = fragment;
             }
         }
-        if (Object.keys(eventFragments).length ===
-            Object.keys(currentEventFragments).length) {
+        if (Object.keys(eventFragments).length === 0) {
+            this.#clearEventFragments();
+            return;
+        }
+        if (Object.keys(eventFragments).length === Object.keys(fragments).length) {
             return;
         }
         this.update((state) => {
@@ -798,15 +1026,31 @@ export class AnalyticsController extends BaseController {
      * Write an event fragment to state, replacing any fragment with the same ID.
      *
      * @param fragment - The fragment to store.
+     * @returns The stored fragment with capture-time purpose metadata.
      */
     #setEventFragment(fragment) {
+        // Snapshot classification only. Consent is stamped at emit time by
+        // {@link #trackEvent}, so fragment.context stays caller metadata.
+        let fragmentWithPurposeSnapshot = fragment;
+        if (fragment.eventPurposes === undefined) {
+            const names = this.#eventNamesFromFragment(fragment);
+            const eventPurposes = Object.fromEntries(names.map((name) => [name, this.#purposesFromName(name)]));
+            fragmentWithPurposeSnapshot = {
+                ...fragment,
+                ...(names.length === 0 ? {} : { eventPurposes }),
+                ...(this.#eventsConfigVersion === undefined
+                    ? {}
+                    : { eventsConfigVersion: this.#eventsConfigVersion }),
+            };
+        }
         const eventFragments = {
             ...this.state.eventFragments,
-            [fragment.id]: fragment,
+            [fragmentWithPurposeSnapshot.id]: fragmentWithPurposeSnapshot,
         };
         this.update((state) => {
             state.eventFragments = eventFragments;
         });
+        return fragmentWithPurposeSnapshot;
     }
     /**
      * Remove an event fragment from state.
@@ -824,6 +1068,35 @@ export class AnalyticsController extends BaseController {
             state.eventFragments = eventFragments;
         });
     }
+    /**
+     * Drop event fragments that the current consent state no longer allows to
+     * accumulate.
+     */
+    #pruneEventFragmentsForConsent() {
+        const fragments = this.state.eventFragments;
+        if (!fragments || Object.keys(fragments).length === 0) {
+            return;
+        }
+        const eventFragments = {};
+        for (const [id, fragment] of Object.entries(fragments)) {
+            if (isAnalyticsEventFragment(fragment) &&
+                this.#isCaptureAllowed(this.#purposesFromFragment(fragment))) {
+                eventFragments[id] = fragment;
+            }
+        }
+        this.update((state) => {
+            state.eventFragments = eventFragments;
+        });
+    }
+    /**
+     * Drop queued events and fragments that the current consent state no longer
+     * allows to keep.
+     */
+    #pruneAllForConsent() {
+        this.#pruneQueueForConsent(AnalyticsQueue.EventQueue);
+        this.#pruneQueueForConsent(AnalyticsQueue.PreConsentEventQueue);
+        this.#pruneEventFragmentsForConsent();
+    }
     /**
      * Clear all event fragments.
      */
@@ -846,14 +1119,18 @@ export class AnalyticsController extends BaseController {
      * fragment never accumulates data for an event that could not be delivered.
      *
      * @param method - The name of the method that was called.
+     * @param fragment - The fragment being read or written, when one is known.
      * @returns True when the call should be ignored.
      */
-    #shouldIgnoreEventFragmentCall(method) {
+    #shouldIgnoreEventFragmentCall(method, fragment) {
         if (!this.#isEventFragmentsEnabled) {
             log('Ignoring event fragment call because the event fragments feature is disabled', { method });
             return true;
         }
-        if (!this.#isAnalyticsCaptureAllowed()) {
+        const captureAllowed = fragment
+            ? this.#isCaptureAllowed(this.#purposesFromFragment(fragment))
+            : this.#isCaptureAllowed(Object.values(AnalyticsPurpose));
+        if (!captureAllowed) {
             log('Ignoring event fragment call because the consent state does not allow capturing analytics', { method });
             return true;
         }
@@ -873,32 +1150,14 @@ export class AnalyticsController extends BaseController {
     #emitEventFragment(fragment, name, context) {
         const properties = { ...fragment.properties };
         const sensitiveProperties = { ...fragment.sensitiveProperties };
-        this.trackEvent({
+        this.#trackEvent({
             name,
             properties,
             sensitiveProperties,
             saveDataRecording: false,
             hasProperties: Object.keys(properties).length > 0 ||
                 Object.keys(sensitiveProperties).length > 0,
-        }, context);
-    }
-    /**
-     * Returns whether the current consent state allows analytics data to be
-     * captured, either for immediate delivery or to be held until the user
-     * decides.
-     *
-     * Capture is allowed once the user has opted in, and also while they are
-     * undecided if the pre-consent queue is enabled: what is captured then is
-     * replayed when they opt in (see {@link optIn}) and discarded if they opt out
-     * (see {@link optOut}). An explicit opt-out never allows capture.
-     *
-     * @returns True when analytics data may be captured.
-     */
-    #isAnalyticsCaptureAllowed() {
-        if (analyticsControllerSelectors.selectEnabled(this.state)) {
-            return true;
-        }
-        return this.#isPreConsentQueueEnabled && !this.state.consentDecisionMade;
+        }, context, this.#purposesFromFragmentEvent(fragment, name), fragment.eventsConfigVersion);
     }
     /**
      * Track an analytics event.
@@ -909,16 +1168,19 @@ export class AnalyticsController extends BaseController {
      * @param context - Optional platform-specific context forwarded to the platform adapter.
      */
     trackEvent(event, context) {
+        this.#trackEvent(event, context, this.#purposesFromName(event.name), this.#eventsConfigVersion);
+    }
+    #trackEvent(event, context, purposes, version) {
         // An event captured while the user is still undecided is held in the
         // pre-consent queue (see #sendOrQueueTrackEvent) instead of being
         // delivered, and replayed if they later opt in.
-        if (!this.#isAnalyticsCaptureAllowed()) {
+        if (!this.#isCaptureAllowed(purposes)) {
             return;
         }
         // if event does not have properties, send event without properties
         // and return to prevent any additional processing
         if (!event.hasProperties) {
-            this.#sendOrQueueTrackEvent(event.name, undefined, this.#withLocationContext(context));
+            this.#sendOrQueueTrackEvent(event.name, undefined, this.#withLocationContext(context), purposes, version);
             return;
         }
         // Track regular properties first if anonymous events feature is enabled
@@ -927,7 +1189,7 @@ export class AnalyticsController extends BaseController {
             // an event with user ID is tracked.
             this.#sendOrQueueTrackEvent(event.name, {
                 ...event.properties,
-            }, this.#withLocationContext(context));
+            }, this.#withLocationContext(context), purposes, version);
         }
         const hasSensitiveProperties = Object.keys(event.sensitiveProperties).length > 0;
         if (!this.#isAnonymousEventsFeatureEnabled || hasSensitiveProperties) {
@@ -941,7 +1203,7 @@ export class AnalyticsController extends BaseController {
             // disabled, this is the single identified payload, so it is enriched.
             this.#isAnonymousEventsFeatureEnabled
                 ? context
-                : this.#withLocationContext(context));
+                : this.#withLocationContext(context), purposes, version);
         }
     }
     /**
@@ -954,7 +1216,6 @@ export class AnalyticsController extends BaseController {
         if (!analyticsControllerSelectors.selectEnabled(this.state)) {
             return;
         }
-        // Delegate to platform adapter using the current analytics ID
         this.#sendOrQueueIdentifyEvent(this.state.analyticsId, traits, this.#withLocationContext(context));
     }
     /**
@@ -965,11 +1226,13 @@ export class AnalyticsController extends BaseController {
      * @param context - Optional platform-specific context forwarded to the platform adapter.
      */
     trackView(name, properties, context) {
-        if (!analyticsControllerSelectors.selectEnabled(this.state)) {
+        const purposes = this.#purposesFromName(name);
+        const version = this.#eventsConfigVersion;
+        if (!this.#isCaptureAllowed(purposes)) {
             return;
         }
         // Delegate to platform adapter
-        this.#sendOrQueueViewEvent(name, properties, this.#withLocationContext(context));
+        this.#sendOrQueueViewEvent(name, properties, this.#withLocationContext(context), purposes, version);
     }
     /**
      * Create an event fragment.
@@ -996,11 +1259,17 @@ export class AnalyticsController extends BaseController {
      * Use {@link updateEventFragment} or {@link upsertEventFragment} to write.
      */
     createEventFragment(options = {}) {
-        if (this.#shouldIgnoreEventFragmentCall('createEventFragment')) {
+        // Classify create from event names only. Caller consent context must not
+        // affect the event-purpose snapshot.
+        if (this.#shouldIgnoreEventFragmentCall('createEventFragment', {
+            initialEvent: options.initialEvent,
+            successEvent: options.successEvent,
+            failureEvent: options.failureEvent,
+        })) {
             return undefined;
         }
         const now = Date.now();
-        const fragment = {
+        const fragment = this.#setEventFragment({
             id: options.id ?? uuid(),
             properties: { ...(options.properties ?? {}) },
             sensitiveProperties: { ...(options.sensitiveProperties ?? {}) },
@@ -1019,8 +1288,7 @@ export class AnalyticsController extends BaseController {
                 ? {}
                 : { context: { ...options.context } }),
             ...(options.persist === undefined ? {} : { persist: options.persist }),
-        };
-        this.#setEventFragment(fragment);
+        });
         if (fragment.initialEvent) {
             this.#emitEventFragment(fragment, fragment.initialEvent, fragment.context);
         }
@@ -1037,10 +1305,10 @@ export class AnalyticsController extends BaseController {
      * @param payload - The properties and context to merge in.
      */
     upsertEventFragment(id, payload = {}) {
-        if (this.#shouldIgnoreEventFragmentCall('upsertEventFragment')) {
+        const fragment = this.#getEventFragment(id);
+        if (this.#shouldIgnoreEventFragmentCall('upsertEventFragment', fragment ?? {})) {
             return;
         }
-        const fragment = this.#getEventFragment(id);
         if (!fragment) {
             this.createEventFragment({ id, ...payload });
             return;
@@ -1058,10 +1326,10 @@ export class AnalyticsController extends BaseController {
      * allow capture, the call is a logged no-op and does not throw.
      */
     updateEventFragment(id, payload = {}) {
-        if (this.#shouldIgnoreEventFragmentCall('updateEventFragment')) {
+        const fragment = this.#getEventFragment(id);
+        if (this.#shouldIgnoreEventFragmentCall('updateEventFragment', fragment)) {
             return;
         }
-        const fragment = this.#getEventFragment(id);
         if (!fragment) {
             throw new Error(`Event fragment with id ${id} does not exist.`);
         }
@@ -1078,10 +1346,10 @@ export class AnalyticsController extends BaseController {
      * {@link upsertEventFragment} to write.
      */
     getEventFragmentById(id) {
-        if (this.#shouldIgnoreEventFragmentCall('getEventFragmentById')) {
+        const fragment = this.#getEventFragment(id);
+        if (this.#shouldIgnoreEventFragmentCall('getEventFragmentById', fragment)) {
             return undefined;
         }
-        const fragment = this.#getEventFragment(id);
         return fragment === undefined ? undefined : cloneDeep(fragment);
     }
     /**
@@ -1090,7 +1358,8 @@ export class AnalyticsController extends BaseController {
      * @param id - The fragment ID.
      */
     deleteEventFragment(id) {
-        if (this.#shouldIgnoreEventFragmentCall('deleteEventFragment')) {
+        const fragment = this.#getEventFragment(id);
+        if (this.#shouldIgnoreEventFragmentCall('deleteEventFragment', fragment)) {
             return;
         }
         this.#removeEventFragment(id);
@@ -1112,10 +1381,10 @@ export class AnalyticsController extends BaseController {
      * allow capture, the call is a logged no-op and does not throw.
      */
     finalizeEventFragment(id, { abandoned = false, context } = {}) {
-        if (this.#shouldIgnoreEventFragmentCall('finalizeEventFragment')) {
+        const fragment = this.#getEventFragment(id);
+        if (this.#shouldIgnoreEventFragmentCall('finalizeEventFragment', fragment)) {
             return;
         }
-        const fragment = this.#getEventFragment(id);
         if (!fragment) {
             throw new Error(`Event fragment with id ${id} does not exist.`);
         }
@@ -1149,7 +1418,7 @@ export class AnalyticsController extends BaseController {
         // consent decision may have changed while geolocation was resolving (e.g.
         // resetConsentDecision ran during the await), and preserved pre-consent
         // events must not be delivered once the user is no longer opted in.
-        this.#reconcilePreConsentEvents();
+        this.#replayPreConsentEvents();
     }
     /**
      * Opt out of analytics.
@@ -1163,9 +1432,7 @@ export class AnalyticsController extends BaseController {
             state.optedIn = false;
             state.consentDecisionMade = true;
         });
-        this.#clearQueuedEvents();
-        this.#clearPreConsentEvents();
-        this.#clearEventFragments();
+        this.#pruneAllForConsent();
     }
     /**
      * Reset the consent decision back to undecided.
@@ -1184,10 +1451,47 @@ export class AnalyticsController extends BaseController {
             state.optedIn = false;
             state.consentDecisionMade = false;
         });
-        this.#clearQueuedEvents();
-        if (!this.#isAnalyticsCaptureAllowed()) {
-            this.#clearEventFragments();
-        }
+        this.#pruneAllForConsent();
+    }
+    /**
+     * Opt in to marketing analytics.
+     *
+     * Independent of {@link optIn}. Replays queued marketing events.
+     *
+     * @returns A promise that resolves once opt-in processing has completed.
+     */
+    async optInToMarketing() {
+        this.update((state) => {
+            state.optedInToMarketing = true;
+            state.marketingConsentDecisionMade = true;
+        });
+        await this.#maybeResolveLocation();
+        this.#replayPreConsentEvents();
+    }
+    /**
+     * Opt out of marketing analytics.
+     *
+     * Independent of {@link optOut}. Discards queued marketing events and
+     * marketing event fragments.
+     */
+    optOutOfMarketing() {
+        this.update((state) => {
+            state.optedInToMarketing = false;
+            state.marketingConsentDecisionMade = true;
+        });
+        this.#pruneAllForConsent();
+    }
+    /**
+     * Reset the marketing consent decision back to undecided.
+     *
+     * Independent of {@link resetConsentDecision}.
+     */
+    resetMarketingConsentDecision() {
+        this.update((state) => {
+            state.optedInToMarketing = false;
+            state.marketingConsentDecisionMade = false;
+        });
+        this.#pruneAllForConsent();
     }
 }
 //# sourceMappingURL=AnalyticsController.js.map