@metamask-previews/analytics-controller 2.0.0-preview-fe4b3be11 → 2.1.0-preview-2f57247

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.1.0]
+
+### Added
+
+- Add optional event fragments to `AnalyticsController` (disabled by default via `isEventFragmentsEnabled`), letting clients accumulate analytics properties across a user journey and optionally emit an initial, success, or failure event for it ([#10055](https://github.com/MetaMask/core/pull/10055))
+
+### Changed
+
+- Bump `@metamask/utils` from `^11.11.0` to `^11.12.0` ([#10076](https://github.com/MetaMask/core/pull/10076))
+
 ## [2.0.0]
 
 ### Changed
@@ -68,7 +78,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Initial release of @metamask/analytics-controller. ([#7017](https://github.com/MetaMask/core/pull/7017), [#7202](https://github.com/MetaMask/core/pull/7202))
 
-[Unreleased]: https://github.com/MetaMask/core/compare/@metamask/analytics-controller@2.0.0...HEAD
+[Unreleased]: https://github.com/MetaMask/core/compare/@metamask/analytics-controller@2.1.0...HEAD
+[2.1.0]: https://github.com/MetaMask/core/compare/@metamask/analytics-controller@2.0.0...@metamask/analytics-controller@2.1.0
 [2.0.0]: https://github.com/MetaMask/core/compare/@metamask/analytics-controller@1.2.1...@metamask/analytics-controller@2.0.0
 [1.2.1]: https://github.com/MetaMask/core/compare/@metamask/analytics-controller@1.2.0...@metamask/analytics-controller@1.2.1
 [1.2.0]: https://github.com/MetaMask/core/compare/@metamask/analytics-controller@1.1.1...@metamask/analytics-controller@1.2.0

package/README.md

@@ -16,11 +16,12 @@ The AnalyticsController provides a unified interface for tracking analytics even
 
 ## State
 
-| Field         | Type      | Description                                   | Persisted |
-| ------------- | --------- | --------------------------------------------- | --------- |
-| `analyticsId` | `string`  | UUIDv4 identifier (client platform-generated) | Yes       |
-| `optedIn`     | `boolean` | User opt-in status                            | Yes       |
-| `eventQueue`  | `object`  | Optional persisted delivery queue             | Yes       |
+| Field            | Type      | Description                                   | Persisted |
+| ---------------- | --------- | --------------------------------------------- | --------- |
+| `analyticsId`    | `string`  | UUIDv4 identifier (client platform-generated) | Yes       |
+| `optedIn`        | `boolean` | User opt-in status                            | Yes       |
+| `eventQueue`     | `object`  | Optional persisted delivery queue             | Yes       |
+| `eventFragments` | `object`  | Optional in-progress event fragments          | Yes       |
 
 ### Client Platform Responsibilities
 
@@ -46,6 +47,46 @@ This feature is disabled by default. Client platforms that already rely on SDK-l
 
 Platforms without SDK-level persistence, such as MetaMask Extension, can enable it to replay queued payloads after restart. The queue stores the final adapter calls, so anonymous event splitting persists the identified and anonymous payloads separately.
 
+## Event Fragments
+
+When `isEventFragmentsEnabled` is enabled in the constructor, clients can accumulate analytics properties across a user journey instead of re-deriving them for every event in that journey.
+
+A fragment is a persisted bag of `properties` and `sensitiveProperties` that any part of the client can contribute to while the journey is in progress. It supports two shapes, and the difference is only which event names it declares:
+
+- **Funnel.** Declare `initialEvent`, `successEvent` and `failureEvent`. The initial event is emitted as soon as the fragment is created, and `finalizeEventFragment` emits the success event, or the failure event when called with `{ abandoned: true }`. A signature request is the canonical example: the request, approval and rejection events all carry the properties that the confirmation UI attached while the user was deciding.
+- **Property bag.** Declare no event names. Nothing is ever emitted. The client reads the fragment back with `getEventFragmentById` at the moment it emits its own event and merges the accumulated properties in. A transaction confirmation is the canonical example.
+
+```ts
+controller.createEventFragment({
+  id: `signature-${requestId}`,
+  initialEvent: 'Signature Requested',
+  successEvent: 'Signature Approved',
+  failureEvent: 'Signature Rejected',
+  properties: { signature_type: 'personal_sign' },
+  context: { referrer: { url: origin } },
+  persist: true,
+});
+
+// Any number of contributors, at any later point.
+controller.updateEventFragment(`signature-${requestId}`, {
+  properties: { alert_triggered_count: 1 },
+});
+
+// Emits 'Signature Approved' with every accumulated property, then discards
+// the fragment. Pass `{ abandoned: true }` to emit 'Signature Rejected'.
+controller.finalizeEventFragment(`signature-${requestId}`);
+```
+
+Use `upsertEventFragment` when a contributor cannot know whether the journey has been started yet. It merges into an existing fragment, or creates a property bag when none exists.
+
+Emission goes through `trackEvent`, so consent gating, anonymous event splitting, the pre-consent queue and geolocation enrichment all apply to a fragment's events exactly as they do to a direct call.
+
+The consent gate also applies to accumulation, not just to emission, so a fragment never stores data for an event that could not be delivered. A fragment only holds data while the user is opted in, or while they are still undecided and `isPreConsentQueueEnabled` is holding their events until they decide. In any other consent state, and in particular after an explicit opt-out, every fragment method is a logged no-op.
+
+Fragments are removed when they are finalized, deleted, or when the user opts out. `resetConsentDecision` keeps them only while the now-undecided user can still accumulate them. On `init`, any fragment that did not set `persist: true` is discarded, since the journey it belonged to cannot be resumed. Persistent fragments that have not been written to for longer than `EVENT_FRAGMENT_MAX_AGE` (24 hours, measured from `lastUpdated`) are also discarded, so abandoned journeys cannot keep `properties` or `sensitiveProperties` in storage indefinitely. All fragments are discarded when the consent state no longer allows accumulation. Nothing is emitted for a discarded fragment: a journey that never reached its own finalization is unfinished, not failed.
+
+This feature is disabled by default. When disabled, every fragment method is a logged no-op and no fragment is written to state.
+
 ## Lifecycle Hooks
 
 ### `onSetupCompleted`

package/dist/AnalyticsController-method-action-types.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"AnalyticsController-method-action-types.cjs","sourceRoot":"","sources":["../src/AnalyticsController-method-action-types.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated.\n * Do not edit manually.\n */\n\nimport type { AnalyticsController } from './AnalyticsController.js';\n\n/**\n * Track an analytics event.\n *\n * Events are only tracked if analytics is enabled.\n *\n * @param event - Analytics event with properties and sensitive properties\n * @param context - Optional platform-specific context forwarded to the platform adapter.\n */\nexport type AnalyticsControllerTrackEventAction = {\n  type: `AnalyticsController:trackEvent`;\n  handler: AnalyticsController['trackEvent'];\n};\n\n/**\n * Identify a user for analytics.\n *\n * @param traits - User traits/properties\n * @param context - Optional platform-specific context forwarded to the platform adapter.\n */\nexport type AnalyticsControllerIdentifyAction = {\n  type: `AnalyticsController:identify`;\n  handler: AnalyticsController['identify'];\n};\n\n/**\n * Track a page or screen view.\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 forwarded to the platform adapter.\n */\nexport type AnalyticsControllerTrackViewAction = {\n  type: `AnalyticsController:trackView`;\n  handler: AnalyticsController['trackView'];\n};\n\n/**\n * Opt in to analytics.\n *\n * Records that a consent decision has been made and replays any events that\n * were queued while the user was undecided.\n *\n * When geolocation enrichment is enabled, geolocation is resolved here (once\n * the user has consented) and awaited before the queued events are replayed,\n * so those events are enriched with the resolved location as they are sent.\n *\n * @returns A promise that resolves once opt-in processing has completed.\n */\nexport type AnalyticsControllerOptInAction = {\n  type: `AnalyticsController:optIn`;\n  handler: AnalyticsController['optIn'];\n};\n\n/**\n * Opt out of analytics.\n *\n * Records that a consent decision has been made and discards any persisted\n * events so nothing captured before the decision is ever delivered.\n */\nexport type AnalyticsControllerOptOutAction = {\n  type: `AnalyticsController:optOut`;\n  handler: AnalyticsController['optOut'];\n};\n\n/**\n * Reset the consent decision back to undecided.\n *\n * Intended for client flows that restart onboarding. Clears the opt-in\n * preference and discards the delivery queue, but preserves any pre-consent\n * events so they can still be replayed if the user opts in again. The user is\n * treated as undecided again.\n */\nexport type AnalyticsControllerResetConsentDecisionAction = {\n  type: `AnalyticsController:resetConsentDecision`;\n  handler: AnalyticsController['resetConsentDecision'];\n};\n\n/**\n * Union of all AnalyticsController action types.\n */\nexport type AnalyticsControllerMethodActions =\n  | AnalyticsControllerTrackEventAction\n  | AnalyticsControllerIdentifyAction\n  | AnalyticsControllerTrackViewAction\n  | AnalyticsControllerOptInAction\n  | AnalyticsControllerOptOutAction\n  | AnalyticsControllerResetConsentDecisionAction;\n"]}
+{"version":3,"file":"AnalyticsController-method-action-types.cjs","sourceRoot":"","sources":["../src/AnalyticsController-method-action-types.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated.\n * Do not edit manually.\n */\n\nimport type { AnalyticsController } from './AnalyticsController.js';\n\n/**\n * Track an analytics event.\n *\n * Events are only tracked if analytics is enabled.\n *\n * @param event - Analytics event with properties and sensitive properties\n * @param context - Optional platform-specific context forwarded to the platform adapter.\n */\nexport type AnalyticsControllerTrackEventAction = {\n  type: `AnalyticsController:trackEvent`;\n  handler: AnalyticsController['trackEvent'];\n};\n\n/**\n * Identify a user for analytics.\n *\n * @param traits - User traits/properties\n * @param context - Optional platform-specific context forwarded to the platform adapter.\n */\nexport type AnalyticsControllerIdentifyAction = {\n  type: `AnalyticsController:identify`;\n  handler: AnalyticsController['identify'];\n};\n\n/**\n * Track a page or screen view.\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 forwarded to the platform adapter.\n */\nexport type AnalyticsControllerTrackViewAction = {\n  type: `AnalyticsController:trackView`;\n  handler: AnalyticsController['trackView'];\n};\n\n/**\n * Create an event fragment.\n *\n * A fragment accumulates properties across a user journey so that several\n * parts of a client can contribute to the same set of events without\n * re-deriving them. Declaring `successEvent` and `failureEvent` turns the\n * fragment into a funnel that {@link finalizeEventFragment} closes. Declaring\n * none of the event names makes it a pure property bag that the client reads\n * back with {@link getEventFragmentById} when it emits its own events.\n *\n * Any existing fragment with the same ID is replaced, so a new journey never\n * inherits properties from a stale one.\n *\n * Nothing is created unless the user is opted in, or undecided with the\n * pre-consent queue enabled, so an opted-out user accumulates no fragment\n * data.\n *\n * @param options - The fragment definition. An ID is generated when one is\n * not supplied.\n * @returns A read-only copy of the created fragment, or `undefined` when the\n * event fragments feature is disabled or the consent state does not allow\n * capture. Mutating the returned object does not change controller state.\n * Use {@link updateEventFragment} or {@link upsertEventFragment} to write.\n */\nexport type AnalyticsControllerCreateEventFragmentAction = {\n  type: `AnalyticsController:createEventFragment`;\n  handler: AnalyticsController['createEventFragment'];\n};\n\n/**\n * Write to an event fragment, creating a property bag if none exists.\n *\n * This is the ergonomic entry point for contributors that do not know\n * whether the journey has been started yet, and it avoids the read then\n * write race a caller would otherwise have to implement itself.\n *\n * @param id - The fragment ID.\n * @param payload - The properties and context to merge in.\n */\nexport type AnalyticsControllerUpsertEventFragmentAction = {\n  type: `AnalyticsController:upsertEventFragment`;\n  handler: AnalyticsController['upsertEventFragment'];\n};\n\n/**\n * Write to an existing event fragment.\n *\n * @param id - The fragment ID.\n * @param payload - The properties and context to merge in.\n * @throws Error if no fragment has that ID when the call is not ignored.\n * Use {@link upsertEventFragment} when the fragment may not exist yet.\n * When the event fragments feature is disabled or the consent state does not\n * allow capture, the call is a logged no-op and does not throw.\n */\nexport type AnalyticsControllerUpdateEventFragmentAction = {\n  type: `AnalyticsController:updateEventFragment`;\n  handler: AnalyticsController['updateEventFragment'];\n};\n\n/**\n * Read an event fragment.\n *\n * @param id - The fragment ID.\n * @returns A read-only copy of the fragment, or `undefined` when no fragment\n * has that ID, the event fragments feature is disabled, or the consent state\n * does not allow capture. Mutating the returned object does not change\n * controller state. Use {@link updateEventFragment} or\n * {@link upsertEventFragment} to write.\n */\nexport type AnalyticsControllerGetEventFragmentByIdAction = {\n  type: `AnalyticsController:getEventFragmentById`;\n  handler: AnalyticsController['getEventFragmentById'];\n};\n\n/**\n * Discard an event fragment without emitting anything.\n *\n * @param id - The fragment ID.\n */\nexport type AnalyticsControllerDeleteEventFragmentAction = {\n  type: `AnalyticsController:deleteEventFragment`;\n  handler: AnalyticsController['deleteEventFragment'];\n};\n\n/**\n * Close an event fragment, emitting its closing event and discarding it.\n *\n * The event emitted is `failureEvent` when the journey was abandoned and\n * `successEvent` otherwise. A fragment that does not declare the relevant\n * event name is discarded silently, which is what makes a pure property bag\n * possible.\n *\n * @param id - The fragment ID.\n * @param options - Finalization options.\n * @param options.abandoned - Whether the journey was abandoned.\n * @param options.context - Context merged over the fragment's own context.\n * @throws Error if no fragment has that ID when the call is not ignored.\n * When the event fragments feature is disabled or the consent state does not\n * allow capture, the call is a logged no-op and does not throw.\n */\nexport type AnalyticsControllerFinalizeEventFragmentAction = {\n  type: `AnalyticsController:finalizeEventFragment`;\n  handler: AnalyticsController['finalizeEventFragment'];\n};\n\n/**\n * Opt in to analytics.\n *\n * Records that a consent decision has been made and replays any events that\n * were queued while the user was undecided.\n *\n * When geolocation enrichment is enabled, geolocation is resolved here (once\n * the user has consented) and awaited before the queued events are replayed,\n * so those events are enriched with the resolved location as they are sent.\n *\n * @returns A promise that resolves once opt-in processing has completed.\n */\nexport type AnalyticsControllerOptInAction = {\n  type: `AnalyticsController:optIn`;\n  handler: AnalyticsController['optIn'];\n};\n\n/**\n * Opt out of analytics.\n *\n * Records that a consent decision has been made and discards any persisted\n * events and in-progress event fragments so nothing captured before the\n * decision is ever delivered.\n */\nexport type AnalyticsControllerOptOutAction = {\n  type: `AnalyticsController:optOut`;\n  handler: AnalyticsController['optOut'];\n};\n\n/**\n * Reset the consent decision back to undecided.\n *\n * Intended for client flows that restart onboarding. Clears the opt-in\n * preference and discards the delivery queue, but preserves any pre-consent\n * events so they can still be replayed if the user opts in again. The user is\n * treated as undecided again.\n *\n * In-progress event fragments are kept only while the undecided user can\n * still accumulate them, and discarded otherwise, so no fragment outlives the\n * consent state that allowed it.\n */\nexport type AnalyticsControllerResetConsentDecisionAction = {\n  type: `AnalyticsController:resetConsentDecision`;\n  handler: AnalyticsController['resetConsentDecision'];\n};\n\n/**\n * Union of all AnalyticsController action types.\n */\nexport type AnalyticsControllerMethodActions =\n  | AnalyticsControllerTrackEventAction\n  | AnalyticsControllerIdentifyAction\n  | AnalyticsControllerTrackViewAction\n  | AnalyticsControllerCreateEventFragmentAction\n  | AnalyticsControllerUpsertEventFragmentAction\n  | AnalyticsControllerUpdateEventFragmentAction\n  | AnalyticsControllerGetEventFragmentByIdAction\n  | AnalyticsControllerDeleteEventFragmentAction\n  | AnalyticsControllerFinalizeEventFragmentAction\n  | AnalyticsControllerOptInAction\n  | AnalyticsControllerOptOutAction\n  | AnalyticsControllerResetConsentDecisionAction;\n"]}

package/dist/AnalyticsController-method-action-types.d.cts

@@ -36,6 +36,105 @@ export type AnalyticsControllerTrackViewAction = {
     type: `AnalyticsController:trackView`;
     handler: AnalyticsController['trackView'];
 };
+/**
+ * Create an event fragment.
+ *
+ * A fragment accumulates properties across a user journey so that several
+ * parts of a client can contribute to the same set of events without
+ * re-deriving them. Declaring `successEvent` and `failureEvent` turns the
+ * fragment into a funnel that {@link finalizeEventFragment} closes. Declaring
+ * none of the event names makes it a pure property bag that the client reads
+ * back with {@link getEventFragmentById} when it emits its own events.
+ *
+ * Any existing fragment with the same ID is replaced, so a new journey never
+ * inherits properties from a stale one.
+ *
+ * Nothing is created unless the user is opted in, or undecided with the
+ * pre-consent queue enabled, so an opted-out user accumulates no fragment
+ * data.
+ *
+ * @param options - The fragment definition. An ID is generated when one is
+ * not supplied.
+ * @returns A read-only copy of the created fragment, or `undefined` when the
+ * event fragments feature is disabled or the consent state does not allow
+ * capture. Mutating the returned object does not change controller state.
+ * Use {@link updateEventFragment} or {@link upsertEventFragment} to write.
+ */
+export type AnalyticsControllerCreateEventFragmentAction = {
+    type: `AnalyticsController:createEventFragment`;
+    handler: AnalyticsController['createEventFragment'];
+};
+/**
+ * Write to an event fragment, creating a property bag if none exists.
+ *
+ * This is the ergonomic entry point for contributors that do not know
+ * whether the journey has been started yet, and it avoids the read then
+ * write race a caller would otherwise have to implement itself.
+ *
+ * @param id - The fragment ID.
+ * @param payload - The properties and context to merge in.
+ */
+export type AnalyticsControllerUpsertEventFragmentAction = {
+    type: `AnalyticsController:upsertEventFragment`;
+    handler: AnalyticsController['upsertEventFragment'];
+};
+/**
+ * Write to an existing event fragment.
+ *
+ * @param id - The fragment ID.
+ * @param payload - The properties and context to merge in.
+ * @throws Error if no fragment has that ID when the call is not ignored.
+ * Use {@link upsertEventFragment} when the fragment may not exist yet.
+ * When the event fragments feature is disabled or the consent state does not
+ * allow capture, the call is a logged no-op and does not throw.
+ */
+export type AnalyticsControllerUpdateEventFragmentAction = {
+    type: `AnalyticsController:updateEventFragment`;
+    handler: AnalyticsController['updateEventFragment'];
+};
+/**
+ * Read an event fragment.
+ *
+ * @param id - The fragment ID.
+ * @returns A read-only copy of the fragment, or `undefined` when no fragment
+ * has that ID, the event fragments feature is disabled, or the consent state
+ * does not allow capture. Mutating the returned object does not change
+ * controller state. Use {@link updateEventFragment} or
+ * {@link upsertEventFragment} to write.
+ */
+export type AnalyticsControllerGetEventFragmentByIdAction = {
+    type: `AnalyticsController:getEventFragmentById`;
+    handler: AnalyticsController['getEventFragmentById'];
+};
+/**
+ * Discard an event fragment without emitting anything.
+ *
+ * @param id - The fragment ID.
+ */
+export type AnalyticsControllerDeleteEventFragmentAction = {
+    type: `AnalyticsController:deleteEventFragment`;
+    handler: AnalyticsController['deleteEventFragment'];
+};
+/**
+ * Close an event fragment, emitting its closing event and discarding it.
+ *
+ * The event emitted is `failureEvent` when the journey was abandoned and
+ * `successEvent` otherwise. A fragment that does not declare the relevant
+ * event name is discarded silently, which is what makes a pure property bag
+ * possible.
+ *
+ * @param id - The fragment ID.
+ * @param options - Finalization options.
+ * @param options.abandoned - Whether the journey was abandoned.
+ * @param options.context - Context merged over the fragment's own context.
+ * @throws Error if no fragment has that ID when the call is not ignored.
+ * When the event fragments feature is disabled or the consent state does not
+ * allow capture, the call is a logged no-op and does not throw.
+ */
+export type AnalyticsControllerFinalizeEventFragmentAction = {
+    type: `AnalyticsController:finalizeEventFragment`;
+    handler: AnalyticsController['finalizeEventFragment'];
+};
 /**
  * Opt in to analytics.
  *
@@ -56,7 +155,8 @@ export type AnalyticsControllerOptInAction = {
  * Opt out of analytics.
  *
  * Records that a consent decision has been made and discards any persisted
- * events so nothing captured before the decision is ever delivered.
+ * events and in-progress event fragments so nothing captured before the
+ * decision is ever delivered.
  */
 export type AnalyticsControllerOptOutAction = {
     type: `AnalyticsController:optOut`;
@@ -69,6 +169,10 @@ export type AnalyticsControllerOptOutAction = {
  * preference and discards the delivery queue, but preserves any pre-consent
  * events so they can still be replayed if the user opts in again. The user is
  * treated as undecided again.
+ *
+ * In-progress event fragments are kept only while the undecided user can
+ * still accumulate them, and discarded otherwise, so no fragment outlives the
+ * consent state that allowed it.
  */
 export type AnalyticsControllerResetConsentDecisionAction = {
     type: `AnalyticsController:resetConsentDecision`;
@@ -77,5 +181,5 @@ export type AnalyticsControllerResetConsentDecisionAction = {
 /**
  * Union of all AnalyticsController action types.
  */
-export type AnalyticsControllerMethodActions = AnalyticsControllerTrackEventAction | AnalyticsControllerIdentifyAction | AnalyticsControllerTrackViewAction | AnalyticsControllerOptInAction | AnalyticsControllerOptOutAction | AnalyticsControllerResetConsentDecisionAction;
+export type AnalyticsControllerMethodActions = AnalyticsControllerTrackEventAction | AnalyticsControllerIdentifyAction | AnalyticsControllerTrackViewAction | AnalyticsControllerCreateEventFragmentAction | AnalyticsControllerUpsertEventFragmentAction | AnalyticsControllerUpdateEventFragmentAction | AnalyticsControllerGetEventFragmentByIdAction | AnalyticsControllerDeleteEventFragmentAction | AnalyticsControllerFinalizeEventFragmentAction | AnalyticsControllerOptInAction | AnalyticsControllerOptOutAction | AnalyticsControllerResetConsentDecisionAction;
 //# sourceMappingURL=AnalyticsController-method-action-types.d.cts.map

package/dist/AnalyticsController-method-action-types.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"AnalyticsController-method-action-types.d.cts","sourceRoot":"","sources":["../src/AnalyticsController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,kCAAiC;AAEpE;;;;;;;GAOG;AACH,MAAM,MAAM,mCAAmC,GAAG;IAChD,IAAI,EAAE,gCAAgC,CAAC;IACvC,OAAO,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAC;CAC5C,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,iCAAiC,GAAG;IAC9C,IAAI,EAAE,8BAA8B,CAAC;IACrC,OAAO,EAAE,mBAAmB,CAAC,UAAU,CAAC,CAAC;CAC1C,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,kCAAkC,GAAG;IAC/C,IAAI,EAAE,+BAA+B,CAAC;IACtC,OAAO,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;CAC3C,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAC3C,IAAI,EAAE,2BAA2B,CAAC;IAClC,OAAO,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;CACvC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,+BAA+B,GAAG;IAC5C,IAAI,EAAE,4BAA4B,CAAC;IACnC,OAAO,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC;CACxC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,6CAA6C,GAAG;IAC1D,IAAI,EAAE,0CAA0C,CAAC;IACjD,OAAO,EAAE,mBAAmB,CAAC,sBAAsB,CAAC,CAAC;CACtD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gCAAgC,GACxC,mCAAmC,GACnC,iCAAiC,GACjC,kCAAkC,GAClC,8BAA8B,GAC9B,+BAA+B,GAC/B,6CAA6C,CAAC"}
+{"version":3,"file":"AnalyticsController-method-action-types.d.cts","sourceRoot":"","sources":["../src/AnalyticsController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,kCAAiC;AAEpE;;;;;;;GAOG;AACH,MAAM,MAAM,mCAAmC,GAAG;IAChD,IAAI,EAAE,gCAAgC,CAAC;IACvC,OAAO,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAC;CAC5C,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,iCAAiC,GAAG;IAC9C,IAAI,EAAE,8BAA8B,CAAC;IACrC,OAAO,EAAE,mBAAmB,CAAC,UAAU,CAAC,CAAC;CAC1C,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,kCAAkC,GAAG;IAC/C,IAAI,EAAE,+BAA+B,CAAC;IACtC,OAAO,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;CAC3C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,4CAA4C,GAAG;IACzD,IAAI,EAAE,yCAAyC,CAAC;IAChD,OAAO,EAAE,mBAAmB,CAAC,qBAAqB,CAAC,CAAC;CACrD,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,4CAA4C,GAAG;IACzD,IAAI,EAAE,yCAAyC,CAAC;IAChD,OAAO,EAAE,mBAAmB,CAAC,qBAAqB,CAAC,CAAC;CACrD,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,4CAA4C,GAAG;IACzD,IAAI,EAAE,yCAAyC,CAAC;IAChD,OAAO,EAAE,mBAAmB,CAAC,qBAAqB,CAAC,CAAC;CACrD,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,6CAA6C,GAAG;IAC1D,IAAI,EAAE,0CAA0C,CAAC;IACjD,OAAO,EAAE,mBAAmB,CAAC,sBAAsB,CAAC,CAAC;CACtD,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,4CAA4C,GAAG;IACzD,IAAI,EAAE,yCAAyC,CAAC;IAChD,OAAO,EAAE,mBAAmB,CAAC,qBAAqB,CAAC,CAAC;CACrD,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,8CAA8C,GAAG;IAC3D,IAAI,EAAE,2CAA2C,CAAC;IAClD,OAAO,EAAE,mBAAmB,CAAC,uBAAuB,CAAC,CAAC;CACvD,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAC3C,IAAI,EAAE,2BAA2B,CAAC;IAClC,OAAO,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;CACvC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,+BAA+B,GAAG;IAC5C,IAAI,EAAE,4BAA4B,CAAC;IACnC,OAAO,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC;CACxC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,6CAA6C,GAAG;IAC1D,IAAI,EAAE,0CAA0C,CAAC;IACjD,OAAO,EAAE,mBAAmB,CAAC,sBAAsB,CAAC,CAAC;CACtD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gCAAgC,GACxC,mCAAmC,GACnC,iCAAiC,GACjC,kCAAkC,GAClC,4CAA4C,GAC5C,4CAA4C,GAC5C,4CAA4C,GAC5C,6CAA6C,GAC7C,4CAA4C,GAC5C,8CAA8C,GAC9C,8BAA8B,GAC9B,+BAA+B,GAC/B,6CAA6C,CAAC"}

package/dist/AnalyticsController-method-action-types.d.mts

@@ -36,6 +36,105 @@ export type AnalyticsControllerTrackViewAction = {
     type: `AnalyticsController:trackView`;
     handler: AnalyticsController['trackView'];
 };
+/**
+ * Create an event fragment.
+ *
+ * A fragment accumulates properties across a user journey so that several
+ * parts of a client can contribute to the same set of events without
+ * re-deriving them. Declaring `successEvent` and `failureEvent` turns the
+ * fragment into a funnel that {@link finalizeEventFragment} closes. Declaring
+ * none of the event names makes it a pure property bag that the client reads
+ * back with {@link getEventFragmentById} when it emits its own events.
+ *
+ * Any existing fragment with the same ID is replaced, so a new journey never
+ * inherits properties from a stale one.
+ *
+ * Nothing is created unless the user is opted in, or undecided with the
+ * pre-consent queue enabled, so an opted-out user accumulates no fragment
+ * data.
+ *
+ * @param options - The fragment definition. An ID is generated when one is
+ * not supplied.
+ * @returns A read-only copy of the created fragment, or `undefined` when the
+ * event fragments feature is disabled or the consent state does not allow
+ * capture. Mutating the returned object does not change controller state.
+ * Use {@link updateEventFragment} or {@link upsertEventFragment} to write.
+ */
+export type AnalyticsControllerCreateEventFragmentAction = {
+    type: `AnalyticsController:createEventFragment`;
+    handler: AnalyticsController['createEventFragment'];
+};
+/**
+ * Write to an event fragment, creating a property bag if none exists.
+ *
+ * This is the ergonomic entry point for contributors that do not know
+ * whether the journey has been started yet, and it avoids the read then
+ * write race a caller would otherwise have to implement itself.
+ *
+ * @param id - The fragment ID.
+ * @param payload - The properties and context to merge in.
+ */
+export type AnalyticsControllerUpsertEventFragmentAction = {
+    type: `AnalyticsController:upsertEventFragment`;
+    handler: AnalyticsController['upsertEventFragment'];
+};
+/**
+ * Write to an existing event fragment.
+ *
+ * @param id - The fragment ID.
+ * @param payload - The properties and context to merge in.
+ * @throws Error if no fragment has that ID when the call is not ignored.
+ * Use {@link upsertEventFragment} when the fragment may not exist yet.
+ * When the event fragments feature is disabled or the consent state does not
+ * allow capture, the call is a logged no-op and does not throw.
+ */
+export type AnalyticsControllerUpdateEventFragmentAction = {
+    type: `AnalyticsController:updateEventFragment`;
+    handler: AnalyticsController['updateEventFragment'];
+};
+/**
+ * Read an event fragment.
+ *
+ * @param id - The fragment ID.
+ * @returns A read-only copy of the fragment, or `undefined` when no fragment
+ * has that ID, the event fragments feature is disabled, or the consent state
+ * does not allow capture. Mutating the returned object does not change
+ * controller state. Use {@link updateEventFragment} or
+ * {@link upsertEventFragment} to write.
+ */
+export type AnalyticsControllerGetEventFragmentByIdAction = {
+    type: `AnalyticsController:getEventFragmentById`;
+    handler: AnalyticsController['getEventFragmentById'];
+};
+/**
+ * Discard an event fragment without emitting anything.
+ *
+ * @param id - The fragment ID.
+ */
+export type AnalyticsControllerDeleteEventFragmentAction = {
+    type: `AnalyticsController:deleteEventFragment`;
+    handler: AnalyticsController['deleteEventFragment'];
+};
+/**
+ * Close an event fragment, emitting its closing event and discarding it.
+ *
+ * The event emitted is `failureEvent` when the journey was abandoned and
+ * `successEvent` otherwise. A fragment that does not declare the relevant
+ * event name is discarded silently, which is what makes a pure property bag
+ * possible.
+ *
+ * @param id - The fragment ID.
+ * @param options - Finalization options.
+ * @param options.abandoned - Whether the journey was abandoned.
+ * @param options.context - Context merged over the fragment's own context.
+ * @throws Error if no fragment has that ID when the call is not ignored.
+ * When the event fragments feature is disabled or the consent state does not
+ * allow capture, the call is a logged no-op and does not throw.
+ */
+export type AnalyticsControllerFinalizeEventFragmentAction = {
+    type: `AnalyticsController:finalizeEventFragment`;
+    handler: AnalyticsController['finalizeEventFragment'];
+};
 /**
  * Opt in to analytics.
  *
@@ -56,7 +155,8 @@ export type AnalyticsControllerOptInAction = {
  * Opt out of analytics.
  *
  * Records that a consent decision has been made and discards any persisted
- * events so nothing captured before the decision is ever delivered.
+ * events and in-progress event fragments so nothing captured before the
+ * decision is ever delivered.
  */
 export type AnalyticsControllerOptOutAction = {
     type: `AnalyticsController:optOut`;
@@ -69,6 +169,10 @@ export type AnalyticsControllerOptOutAction = {
  * preference and discards the delivery queue, but preserves any pre-consent
  * events so they can still be replayed if the user opts in again. The user is
  * treated as undecided again.
+ *
+ * In-progress event fragments are kept only while the undecided user can
+ * still accumulate them, and discarded otherwise, so no fragment outlives the
+ * consent state that allowed it.
  */
 export type AnalyticsControllerResetConsentDecisionAction = {
     type: `AnalyticsController:resetConsentDecision`;
@@ -77,5 +181,5 @@ export type AnalyticsControllerResetConsentDecisionAction = {
 /**
  * Union of all AnalyticsController action types.
  */
-export type AnalyticsControllerMethodActions = AnalyticsControllerTrackEventAction | AnalyticsControllerIdentifyAction | AnalyticsControllerTrackViewAction | AnalyticsControllerOptInAction | AnalyticsControllerOptOutAction | AnalyticsControllerResetConsentDecisionAction;
+export type AnalyticsControllerMethodActions = AnalyticsControllerTrackEventAction | AnalyticsControllerIdentifyAction | AnalyticsControllerTrackViewAction | AnalyticsControllerCreateEventFragmentAction | AnalyticsControllerUpsertEventFragmentAction | AnalyticsControllerUpdateEventFragmentAction | AnalyticsControllerGetEventFragmentByIdAction | AnalyticsControllerDeleteEventFragmentAction | AnalyticsControllerFinalizeEventFragmentAction | AnalyticsControllerOptInAction | AnalyticsControllerOptOutAction | AnalyticsControllerResetConsentDecisionAction;
 //# sourceMappingURL=AnalyticsController-method-action-types.d.mts.map

package/dist/AnalyticsController-method-action-types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"AnalyticsController-method-action-types.d.mts","sourceRoot":"","sources":["../src/AnalyticsController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,kCAAiC;AAEpE;;;;;;;GAOG;AACH,MAAM,MAAM,mCAAmC,GAAG;IAChD,IAAI,EAAE,gCAAgC,CAAC;IACvC,OAAO,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAC;CAC5C,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,iCAAiC,GAAG;IAC9C,IAAI,EAAE,8BAA8B,CAAC;IACrC,OAAO,EAAE,mBAAmB,CAAC,UAAU,CAAC,CAAC;CAC1C,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,kCAAkC,GAAG;IAC/C,IAAI,EAAE,+BAA+B,CAAC;IACtC,OAAO,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;CAC3C,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAC3C,IAAI,EAAE,2BAA2B,CAAC;IAClC,OAAO,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;CACvC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,+BAA+B,GAAG;IAC5C,IAAI,EAAE,4BAA4B,CAAC;IACnC,OAAO,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC;CACxC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,6CAA6C,GAAG;IAC1D,IAAI,EAAE,0CAA0C,CAAC;IACjD,OAAO,EAAE,mBAAmB,CAAC,sBAAsB,CAAC,CAAC;CACtD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gCAAgC,GACxC,mCAAmC,GACnC,iCAAiC,GACjC,kCAAkC,GAClC,8BAA8B,GAC9B,+BAA+B,GAC/B,6CAA6C,CAAC"}
+{"version":3,"file":"AnalyticsController-method-action-types.d.mts","sourceRoot":"","sources":["../src/AnalyticsController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,kCAAiC;AAEpE;;;;;;;GAOG;AACH,MAAM,MAAM,mCAAmC,GAAG;IAChD,IAAI,EAAE,gCAAgC,CAAC;IACvC,OAAO,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAC;CAC5C,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,iCAAiC,GAAG;IAC9C,IAAI,EAAE,8BAA8B,CAAC;IACrC,OAAO,EAAE,mBAAmB,CAAC,UAAU,CAAC,CAAC;CAC1C,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,kCAAkC,GAAG;IAC/C,IAAI,EAAE,+BAA+B,CAAC;IACtC,OAAO,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;CAC3C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,4CAA4C,GAAG;IACzD,IAAI,EAAE,yCAAyC,CAAC;IAChD,OAAO,EAAE,mBAAmB,CAAC,qBAAqB,CAAC,CAAC;CACrD,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,4CAA4C,GAAG;IACzD,IAAI,EAAE,yCAAyC,CAAC;IAChD,OAAO,EAAE,mBAAmB,CAAC,qBAAqB,CAAC,CAAC;CACrD,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,4CAA4C,GAAG;IACzD,IAAI,EAAE,yCAAyC,CAAC;IAChD,OAAO,EAAE,mBAAmB,CAAC,qBAAqB,CAAC,CAAC;CACrD,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,6CAA6C,GAAG;IAC1D,IAAI,EAAE,0CAA0C,CAAC;IACjD,OAAO,EAAE,mBAAmB,CAAC,sBAAsB,CAAC,CAAC;CACtD,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,4CAA4C,GAAG;IACzD,IAAI,EAAE,yCAAyC,CAAC;IAChD,OAAO,EAAE,mBAAmB,CAAC,qBAAqB,CAAC,CAAC;CACrD,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,8CAA8C,GAAG;IAC3D,IAAI,EAAE,2CAA2C,CAAC;IAClD,OAAO,EAAE,mBAAmB,CAAC,uBAAuB,CAAC,CAAC;CACvD,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAC3C,IAAI,EAAE,2BAA2B,CAAC;IAClC,OAAO,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;CACvC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,+BAA+B,GAAG;IAC5C,IAAI,EAAE,4BAA4B,CAAC;IACnC,OAAO,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC;CACxC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,6CAA6C,GAAG;IAC1D,IAAI,EAAE,0CAA0C,CAAC;IACjD,OAAO,EAAE,mBAAmB,CAAC,sBAAsB,CAAC,CAAC;CACtD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gCAAgC,GACxC,mCAAmC,GACnC,iCAAiC,GACjC,kCAAkC,GAClC,4CAA4C,GAC5C,4CAA4C,GAC5C,4CAA4C,GAC5C,6CAA6C,GAC7C,4CAA4C,GAC5C,8CAA8C,GAC9C,8BAA8B,GAC9B,+BAA+B,GAC/B,6CAA6C,CAAC"}

package/dist/AnalyticsController-method-action-types.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"AnalyticsController-method-action-types.mjs","sourceRoot":"","sources":["../src/AnalyticsController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated.\n * Do not edit manually.\n */\n\nimport type { AnalyticsController } from './AnalyticsController.js';\n\n/**\n * Track an analytics event.\n *\n * Events are only tracked if analytics is enabled.\n *\n * @param event - Analytics event with properties and sensitive properties\n * @param context - Optional platform-specific context forwarded to the platform adapter.\n */\nexport type AnalyticsControllerTrackEventAction = {\n  type: `AnalyticsController:trackEvent`;\n  handler: AnalyticsController['trackEvent'];\n};\n\n/**\n * Identify a user for analytics.\n *\n * @param traits - User traits/properties\n * @param context - Optional platform-specific context forwarded to the platform adapter.\n */\nexport type AnalyticsControllerIdentifyAction = {\n  type: `AnalyticsController:identify`;\n  handler: AnalyticsController['identify'];\n};\n\n/**\n * Track a page or screen view.\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 forwarded to the platform adapter.\n */\nexport type AnalyticsControllerTrackViewAction = {\n  type: `AnalyticsController:trackView`;\n  handler: AnalyticsController['trackView'];\n};\n\n/**\n * Opt in to analytics.\n *\n * Records that a consent decision has been made and replays any events that\n * were queued while the user was undecided.\n *\n * When geolocation enrichment is enabled, geolocation is resolved here (once\n * the user has consented) and awaited before the queued events are replayed,\n * so those events are enriched with the resolved location as they are sent.\n *\n * @returns A promise that resolves once opt-in processing has completed.\n */\nexport type AnalyticsControllerOptInAction = {\n  type: `AnalyticsController:optIn`;\n  handler: AnalyticsController['optIn'];\n};\n\n/**\n * Opt out of analytics.\n *\n * Records that a consent decision has been made and discards any persisted\n * events so nothing captured before the decision is ever delivered.\n */\nexport type AnalyticsControllerOptOutAction = {\n  type: `AnalyticsController:optOut`;\n  handler: AnalyticsController['optOut'];\n};\n\n/**\n * Reset the consent decision back to undecided.\n *\n * Intended for client flows that restart onboarding. Clears the opt-in\n * preference and discards the delivery queue, but preserves any pre-consent\n * events so they can still be replayed if the user opts in again. The user is\n * treated as undecided again.\n */\nexport type AnalyticsControllerResetConsentDecisionAction = {\n  type: `AnalyticsController:resetConsentDecision`;\n  handler: AnalyticsController['resetConsentDecision'];\n};\n\n/**\n * Union of all AnalyticsController action types.\n */\nexport type AnalyticsControllerMethodActions =\n  | AnalyticsControllerTrackEventAction\n  | AnalyticsControllerIdentifyAction\n  | AnalyticsControllerTrackViewAction\n  | AnalyticsControllerOptInAction\n  | AnalyticsControllerOptOutAction\n  | AnalyticsControllerResetConsentDecisionAction;\n"]}
+{"version":3,"file":"AnalyticsController-method-action-types.mjs","sourceRoot":"","sources":["../src/AnalyticsController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated.\n * Do not edit manually.\n */\n\nimport type { AnalyticsController } from './AnalyticsController.js';\n\n/**\n * Track an analytics event.\n *\n * Events are only tracked if analytics is enabled.\n *\n * @param event - Analytics event with properties and sensitive properties\n * @param context - Optional platform-specific context forwarded to the platform adapter.\n */\nexport type AnalyticsControllerTrackEventAction = {\n  type: `AnalyticsController:trackEvent`;\n  handler: AnalyticsController['trackEvent'];\n};\n\n/**\n * Identify a user for analytics.\n *\n * @param traits - User traits/properties\n * @param context - Optional platform-specific context forwarded to the platform adapter.\n */\nexport type AnalyticsControllerIdentifyAction = {\n  type: `AnalyticsController:identify`;\n  handler: AnalyticsController['identify'];\n};\n\n/**\n * Track a page or screen view.\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 forwarded to the platform adapter.\n */\nexport type AnalyticsControllerTrackViewAction = {\n  type: `AnalyticsController:trackView`;\n  handler: AnalyticsController['trackView'];\n};\n\n/**\n * Create an event fragment.\n *\n * A fragment accumulates properties across a user journey so that several\n * parts of a client can contribute to the same set of events without\n * re-deriving them. Declaring `successEvent` and `failureEvent` turns the\n * fragment into a funnel that {@link finalizeEventFragment} closes. Declaring\n * none of the event names makes it a pure property bag that the client reads\n * back with {@link getEventFragmentById} when it emits its own events.\n *\n * Any existing fragment with the same ID is replaced, so a new journey never\n * inherits properties from a stale one.\n *\n * Nothing is created unless the user is opted in, or undecided with the\n * pre-consent queue enabled, so an opted-out user accumulates no fragment\n * data.\n *\n * @param options - The fragment definition. An ID is generated when one is\n * not supplied.\n * @returns A read-only copy of the created fragment, or `undefined` when the\n * event fragments feature is disabled or the consent state does not allow\n * capture. Mutating the returned object does not change controller state.\n * Use {@link updateEventFragment} or {@link upsertEventFragment} to write.\n */\nexport type AnalyticsControllerCreateEventFragmentAction = {\n  type: `AnalyticsController:createEventFragment`;\n  handler: AnalyticsController['createEventFragment'];\n};\n\n/**\n * Write to an event fragment, creating a property bag if none exists.\n *\n * This is the ergonomic entry point for contributors that do not know\n * whether the journey has been started yet, and it avoids the read then\n * write race a caller would otherwise have to implement itself.\n *\n * @param id - The fragment ID.\n * @param payload - The properties and context to merge in.\n */\nexport type AnalyticsControllerUpsertEventFragmentAction = {\n  type: `AnalyticsController:upsertEventFragment`;\n  handler: AnalyticsController['upsertEventFragment'];\n};\n\n/**\n * Write to an existing event fragment.\n *\n * @param id - The fragment ID.\n * @param payload - The properties and context to merge in.\n * @throws Error if no fragment has that ID when the call is not ignored.\n * Use {@link upsertEventFragment} when the fragment may not exist yet.\n * When the event fragments feature is disabled or the consent state does not\n * allow capture, the call is a logged no-op and does not throw.\n */\nexport type AnalyticsControllerUpdateEventFragmentAction = {\n  type: `AnalyticsController:updateEventFragment`;\n  handler: AnalyticsController['updateEventFragment'];\n};\n\n/**\n * Read an event fragment.\n *\n * @param id - The fragment ID.\n * @returns A read-only copy of the fragment, or `undefined` when no fragment\n * has that ID, the event fragments feature is disabled, or the consent state\n * does not allow capture. Mutating the returned object does not change\n * controller state. Use {@link updateEventFragment} or\n * {@link upsertEventFragment} to write.\n */\nexport type AnalyticsControllerGetEventFragmentByIdAction = {\n  type: `AnalyticsController:getEventFragmentById`;\n  handler: AnalyticsController['getEventFragmentById'];\n};\n\n/**\n * Discard an event fragment without emitting anything.\n *\n * @param id - The fragment ID.\n */\nexport type AnalyticsControllerDeleteEventFragmentAction = {\n  type: `AnalyticsController:deleteEventFragment`;\n  handler: AnalyticsController['deleteEventFragment'];\n};\n\n/**\n * Close an event fragment, emitting its closing event and discarding it.\n *\n * The event emitted is `failureEvent` when the journey was abandoned and\n * `successEvent` otherwise. A fragment that does not declare the relevant\n * event name is discarded silently, which is what makes a pure property bag\n * possible.\n *\n * @param id - The fragment ID.\n * @param options - Finalization options.\n * @param options.abandoned - Whether the journey was abandoned.\n * @param options.context - Context merged over the fragment's own context.\n * @throws Error if no fragment has that ID when the call is not ignored.\n * When the event fragments feature is disabled or the consent state does not\n * allow capture, the call is a logged no-op and does not throw.\n */\nexport type AnalyticsControllerFinalizeEventFragmentAction = {\n  type: `AnalyticsController:finalizeEventFragment`;\n  handler: AnalyticsController['finalizeEventFragment'];\n};\n\n/**\n * Opt in to analytics.\n *\n * Records that a consent decision has been made and replays any events that\n * were queued while the user was undecided.\n *\n * When geolocation enrichment is enabled, geolocation is resolved here (once\n * the user has consented) and awaited before the queued events are replayed,\n * so those events are enriched with the resolved location as they are sent.\n *\n * @returns A promise that resolves once opt-in processing has completed.\n */\nexport type AnalyticsControllerOptInAction = {\n  type: `AnalyticsController:optIn`;\n  handler: AnalyticsController['optIn'];\n};\n\n/**\n * Opt out of analytics.\n *\n * Records that a consent decision has been made and discards any persisted\n * events and in-progress event fragments so nothing captured before the\n * decision is ever delivered.\n */\nexport type AnalyticsControllerOptOutAction = {\n  type: `AnalyticsController:optOut`;\n  handler: AnalyticsController['optOut'];\n};\n\n/**\n * Reset the consent decision back to undecided.\n *\n * Intended for client flows that restart onboarding. Clears the opt-in\n * preference and discards the delivery queue, but preserves any pre-consent\n * events so they can still be replayed if the user opts in again. The user is\n * treated as undecided again.\n *\n * In-progress event fragments are kept only while the undecided user can\n * still accumulate them, and discarded otherwise, so no fragment outlives the\n * consent state that allowed it.\n */\nexport type AnalyticsControllerResetConsentDecisionAction = {\n  type: `AnalyticsController:resetConsentDecision`;\n  handler: AnalyticsController['resetConsentDecision'];\n};\n\n/**\n * Union of all AnalyticsController action types.\n */\nexport type AnalyticsControllerMethodActions =\n  | AnalyticsControllerTrackEventAction\n  | AnalyticsControllerIdentifyAction\n  | AnalyticsControllerTrackViewAction\n  | AnalyticsControllerCreateEventFragmentAction\n  | AnalyticsControllerUpsertEventFragmentAction\n  | AnalyticsControllerUpdateEventFragmentAction\n  | AnalyticsControllerGetEventFragmentByIdAction\n  | AnalyticsControllerDeleteEventFragmentAction\n  | AnalyticsControllerFinalizeEventFragmentAction\n  | AnalyticsControllerOptInAction\n  | AnalyticsControllerOptOutAction\n  | AnalyticsControllerResetConsentDecisionAction;\n"]}