@atlaskit/editor-common 110.29.0 → 110.29.2

package/dist/es2019/experiences/consts.js

@@ -19,13 +19,27 @@ export const EXPERIENCE_FAILURE_REASON = {
   DOM_MUTATION_CHECK_ERROR: 'dom-mutation-check-error'
 };
 
+/**
+ * Built-in abort reasons for experiences.
+ *
+ * These may be used by various ExperienceCheck implementations to
+ * provide consistent, well-known abort reasons for analytics and debugging.
+ */
+export const EXPERIENCE_ABORT_REASON = {
+  /**
+   * Experience was aborted because it was restarted while already in progress
+   */
+  RESTARTED: 'restarted'
+};
+
 /**
  * Default sample rate for experienceSampled events.
  * Set to 1 in 1000 (0.001) to balance data collection with event volume.
  *
  * Newly defined experiences should use this default unless they have data
- * to justify a different rate. The expectation is that measurements will be
- * gathered after initial instrumentation, then the sample rate can be tuned
- * up to a safe threshold.
+ * to justify a different rate.
+ *
+ * The expectation is that measurements will be gathered after initial
+ * instrumentation, then the sample rate can be tuned up to a safe threshold.
  */
 export const DEFAULT_EXPERIENCE_SAMPLE_RATE = 0.001;

package/dist/es2019/experiences/experience-state.js

@@ -1,7 +1,3 @@
-/**
- * Represents the state of an experience throughout its lifecycle.
- */
-
 /**
  * State transition map defining valid state transitions.
  */

package/dist/es2019/experiences/index.js

@@ -2,7 +2,7 @@
 /* eslint-disable @atlaskit/editor/no-re-export */
 
 export { Experience } from './Experience';
-export { EXPERIENCE_FAILURE_REASON } from './consts';
+export { EXPERIENCE_ABORT_REASON, EXPERIENCE_FAILURE_REASON } from './consts';
 export { ExperienceCheckComposite } from './ExperienceCheckComposite';
 export { ExperienceCheckDomMutation } from './ExperienceCheckDomMutation';
 export { ExperienceCheckTimeout } from './ExperienceCheckTimeout';

package/dist/es2019/monitoring/error.js

@@ -1,7 +1,7 @@
 import { isFedRamp } from './environment';
 const SENTRY_DSN = 'https://0b10c8e02fb44d8796c047b102c9bee8@o55978.ingest.sentry.io/4505129224110080';
 const packageName = 'editor-common'; // Sentry doesn't accept '/' in its releases https://docs.sentry.io/platforms/javascript/configuration/releases/
-const packageVersion = "110.28.0";
+const packageVersion = "0.0.0-development";
 const sanitiseSentryEvents = (data, _hint) => {
   // Remove URL as it has UGC
   // Ignored via go/ees007

package/dist/es2019/ui/DropList/index.js

@@ -14,7 +14,7 @@ import withAnalyticsEvents from '@atlaskit/analytics-next/withAnalyticsEvents';
 import { fg } from '@atlaskit/platform-feature-flags';
 import Layer from '../Layer';
 const packageName = "@atlaskit/editor-common";
-const packageVersion = "110.28.0";
+const packageVersion = "0.0.0-development";
 const halfFocusRing = 1;
 const dropOffset = '0, 8';
 const fadeIn = keyframes({

package/dist/es2019/utils/annotation/index.js

@@ -214,9 +214,6 @@ export function getAnnotationInlineNodeTypes(state, annotationId) {
 	Used with the creation of the inline nodes: emoji, status, dates, mentions & inlineCards.
 */
 export function getAnnotationMarksForPos(pos) {
-  if (!fg('editor_inline_comments_paste_insert_nodes')) {
-    return undefined;
-  }
   const annotationMarks = pos.marks().filter(mark => mark.type === pos.doc.type.schema.marks.annotation);
   return annotationMarks;
 }

package/dist/esm/experiences/Experience.js

@@ -4,7 +4,7 @@ import _defineProperty from "@babel/runtime/helpers/defineProperty";
 function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
 function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
 import { ACTION, ACTION_SUBJECT, EVENT_TYPE } from '../analytics';
-import { DEFAULT_EXPERIENCE_SAMPLE_RATE } from './consts';
+import { DEFAULT_EXPERIENCE_SAMPLE_RATE, EXPERIENCE_ABORT_REASON } from './consts';
 import { canTransition } from './experience-state';
 import { ExperienceCheckComposite } from './ExperienceCheckComposite';
 export var Experience = /*#__PURE__*/function () {
@@ -16,14 +16,45 @@ export var Experience = /*#__PURE__*/function () {
    * Ensures that every tracked start has corresponding abort/fail/success tracked.
    */
 
+  /**
+   * Timestamp (in milliseconds) when the experience transitioned to 'started' state.
+   *
+   * Used to calculate experience duration. Set via Date.now() when experience starts.
+   */
+
+  /**
+   * Metadata provided at experience start time to merge into subsequent events.
+   *
+   * Used to retain experienceStartMethod and other start-specific metadata.
+   */
+
+  /**
+   * Creates a new Experience instance for tracking user experiences.
+   *
+   * @param id - Unique identifier for the experience
+   * @param options - Configuration options for the experience
+   * @param options.checks - Experience checks to monitor for completion
+   * @param options.dispatchAnalyticsEvent - Function to dispatch analytics events
+   * @param options.sampleRate - Sample rate for experienceSampled events
+   * @param options.metadata - Global metadata to attach to all events
+   * @param options.action - Optional sub identifier for the specific experience action
+   */
   function Experience(id, options) {
     var _options$sampleRate;
     _classCallCheck(this, Experience);
     _defineProperty(this, "currentState", 'pending');
+    /**
+     * Set of experience states that have been seen in the current session.
+     *
+     * Used to determine if experienceStatusFirstSeen flag should be set in events.
+     */
     _defineProperty(this, "statesSeen", new Set());
     this.id = id;
     this.dispatchAnalyticsEvent = options.dispatchAnalyticsEvent;
     this.sampleRate = (_options$sampleRate = options.sampleRate) !== null && _options$sampleRate !== void 0 ? _options$sampleRate : DEFAULT_EXPERIENCE_SAMPLE_RATE;
+    this.globalMetadata = _objectSpread(_objectSpread({}, options.metadata), {}, {
+      experienceAction: options.action
+    });
     this.check = new ExperienceCheckComposite(options.checks || []);
   }
   return _createClass(Experience, [{
@@ -33,17 +64,21 @@ export var Experience = /*#__PURE__*/function () {
       this.stopCheck();
       this.check.start(function (_ref) {
         var status = _ref.status,
+          reason = _ref.reason,
           metadata = _ref.metadata;
         if (status === 'success') {
           _this.success({
+            reason: reason,
             metadata: metadata
           });
         } else if (status === 'abort') {
           _this.abort({
+            reason: reason,
             metadata: metadata
           });
         } else if (status === 'failure') {
           _this.failure({
+            reason: reason,
             metadata: metadata
           });
         }
@@ -55,12 +90,13 @@ export var Experience = /*#__PURE__*/function () {
       this.check.stop();
     }
   }, {
-    key: "getEndStateConfig",
-    value: function getEndStateConfig(options) {
-      var _this$startOptions, _this$startOptions2;
-      return {
-        metadata: options !== null && options !== void 0 && options.metadata || (_this$startOptions = this.startOptions) !== null && _this$startOptions !== void 0 && _this$startOptions.metadata ? _objectSpread(_objectSpread({}, (_this$startOptions2 = this.startOptions) === null || _this$startOptions2 === void 0 ? void 0 : _this$startOptions2.metadata), options === null || options === void 0 ? void 0 : options.metadata) : undefined
-      };
+    key: "getEndStateMetadata",
+    value: function getEndStateMetadata(options) {
+      var metadata = _objectSpread({}, options === null || options === void 0 ? void 0 : options.metadata);
+      if (options !== null && options !== void 0 && options.reason) {
+        metadata.experienceEndReason = options.reason;
+      }
+      return metadata;
     }
 
     /**
@@ -80,12 +116,20 @@ export var Experience = /*#__PURE__*/function () {
       if (!canTransition(this.currentState, toState)) {
         return false;
       }
-      this.statesSeen.add(toState);
       this.currentState = toState;
       if (toState === 'started') {
         this.isSampledTrackingEnabled = Math.random() < this.sampleRate;
+        this.startTimeMs = Date.now();
+        this.startMetadata = metadata;
       }
       this.trackTransition(toState, metadata);
+      if (toState === 'started') {
+        this.startCheck();
+      } else {
+        this.stopCheck();
+        this.startMetadata = undefined;
+      }
+      this.statesSeen.add(toState);
       return true;
     }
 
@@ -100,11 +144,13 @@ export var Experience = /*#__PURE__*/function () {
   }, {
     key: "trackTransition",
     value: function trackTransition(toState, metadata) {
-      var attributes = _objectSpread({
+      var attributes = _objectSpread(_objectSpread(_objectSpread({
         experienceKey: this.id,
         experienceStatus: toState,
-        firstInSession: !this.statesSeen.has(toState)
-      }, metadata);
+        experienceStatusFirstSeen: !this.statesSeen.has(toState),
+        experienceStartTime: this.startTimeMs || 0,
+        experienceDuration: this.startTimeMs ? Date.now() - this.startTimeMs : 0
+      }, this.globalMetadata), this.startMetadata), metadata);
       var experienceMeasuredEvent = {
         action: ACTION.EXPERIENCE_MEASURED,
         actionSubject: ACTION_SUBJECT.EDITOR,
@@ -131,31 +177,36 @@ export var Experience = /*#__PURE__*/function () {
      * Metadata from options will be merged with metadata provided in subsequent events.
      *
      * @param options - Configuration for starting the experience
-     * @param options.metadata - Optional metadata attached to all subsequent events for this started experience
+     * @param options.metadata - Optional custom metadata attached to all subsequent events for this started experience
+     * @param options.forceRestart - If true and experience already in progress will abort and restart
+     * @param options.method - Optional method for experience start, e.g., how the experience was initiated
      */
   }, {
     key: "start",
     value: function start(options) {
-      this.startOptions = options;
-      if (this.transitionTo('started', options === null || options === void 0 ? void 0 : options.metadata)) {
-        this.startCheck();
+      if (options.forceRestart && this.currentState === 'started') {
+        this.abort({
+          reason: EXPERIENCE_ABORT_REASON.RESTARTED
+        });
       }
+      return this.transitionTo('started', _objectSpread({
+        experienceStartMethod: options.method
+      }, options.metadata));
     }
 
     /**
      * Marks the experience as successful and stops any ongoing checks.
      *
      * @param options - Configuration for the success event
-     * @param options.metadata - Optional metadata attached to the success event
+     * @param options.metadata - Optional custom metadata attached to the success event
+     * @param options.reason - Optional reason for success
+     * @returns false if transition to success state was not valid
      */
   }, {
     key: "success",
     value: function success(options) {
-      var mergedConfig = this.getEndStateConfig(options);
-      if (this.transitionTo('succeeded', mergedConfig.metadata)) {
-        this.stopCheck();
-        this.startOptions = undefined;
-      }
+      var metadata = this.getEndStateMetadata(options);
+      return this.transitionTo('succeeded', metadata);
     }
 
     /**
@@ -165,22 +216,22 @@ export var Experience = /*#__PURE__*/function () {
      * (e.g., component unmount, navigation). This is neither success nor failure.
      *
      * @param options - Configuration for the abort event
-     * @param options.metadata - Optional metadata attached to the abort event
+     * @param options.metadata - Optional custom metadata attached to the abort event
+     * @param options.reason - Optional reason for abort
      *
      * @example
      * // Abort on component unmount
      * useEffect(() => {
-     *   return () => experience.abort({ metadata: { reason: 'unmount' } });
+     *   return () => experience.abort({ reason: 'unmount', metadata: { someKey: 'someValue' } });
      * }, []);
+     *
+     * @returns false if transition to aborted state was not valid
      */
   }, {
     key: "abort",
     value: function abort(options) {
-      var mergedConfig = this.getEndStateConfig(options);
-      if (this.transitionTo('aborted', mergedConfig.metadata)) {
-        this.stopCheck();
-        this.startOptions = undefined;
-      }
+      var metadata = this.getEndStateMetadata(options);
+      return this.transitionTo('aborted', metadata);
     }
 
     /**
@@ -189,16 +240,15 @@ export var Experience = /*#__PURE__*/function () {
      * Use this for actual failures in the experience flow (e.g., timeout, error conditions).
      *
      * @param options - Configuration for the failure event
-     * @param options.metadata - Optional metadata attached to the failure event
+     * @param options.metadata - Optional custom metadata attached to the failure event
+     * @param options.reason - Optional reason for failure
+     * @returns false if transition to failed state was not valid
      */
   }, {
     key: "failure",
     value: function failure(options) {
-      var mergedConfig = this.getEndStateConfig(options);
-      if (this.transitionTo('failed', mergedConfig.metadata)) {
-        this.stopCheck();
-        this.startOptions = undefined;
-      }
+      var metadata = this.getEndStateMetadata(options);
+      return this.transitionTo('failed', metadata);
     }
   }]);
 }();

package/dist/esm/experiences/ExperienceCheckDomMutation.js

@@ -26,9 +26,7 @@ export var ExperienceCheckDomMutation = /*#__PURE__*/function () {
       if (!(config !== null && config !== void 0 && config.target)) {
         callback({
           status: 'failure',
-          metadata: {
-            reason: EXPERIENCE_FAILURE_REASON.DOM_MUTATION_TARGET_NOT_FOUND
-          }
+          reason: EXPERIENCE_FAILURE_REASON.DOM_MUTATION_TARGET_NOT_FOUND
         });
         return;
       }
@@ -43,9 +41,7 @@ export var ExperienceCheckDomMutation = /*#__PURE__*/function () {
         } catch (error) {
           callback({
             status: 'failure',
-            metadata: {
-              reason: EXPERIENCE_FAILURE_REASON.DOM_MUTATION_CHECK_ERROR
-            }
+            reason: EXPERIENCE_FAILURE_REASON.DOM_MUTATION_CHECK_ERROR
           });
         }
       });

package/dist/esm/experiences/ExperienceCheckTimeout.js

@@ -4,9 +4,7 @@ import _defineProperty from "@babel/runtime/helpers/defineProperty";
 import { EXPERIENCE_FAILURE_REASON } from './consts';
 var DEFAULT_FAILURE_RESULT = {
   status: 'failure',
-  metadata: {
-    reason: EXPERIENCE_FAILURE_REASON.TIMEOUT
-  }
+  reason: EXPERIENCE_FAILURE_REASON.TIMEOUT
 };
 
 /**

package/dist/esm/experiences/consts.js

@@ -19,13 +19,27 @@ export var EXPERIENCE_FAILURE_REASON = {
   DOM_MUTATION_CHECK_ERROR: 'dom-mutation-check-error'
 };
 
+/**
+ * Built-in abort reasons for experiences.
+ *
+ * These may be used by various ExperienceCheck implementations to
+ * provide consistent, well-known abort reasons for analytics and debugging.
+ */
+export var EXPERIENCE_ABORT_REASON = {
+  /**
+   * Experience was aborted because it was restarted while already in progress
+   */
+  RESTARTED: 'restarted'
+};
+
 /**
  * Default sample rate for experienceSampled events.
  * Set to 1 in 1000 (0.001) to balance data collection with event volume.
  *
  * Newly defined experiences should use this default unless they have data
- * to justify a different rate. The expectation is that measurements will be
- * gathered after initial instrumentation, then the sample rate can be tuned
- * up to a safe threshold.
+ * to justify a different rate.
+ *
+ * The expectation is that measurements will be gathered after initial
+ * instrumentation, then the sample rate can be tuned up to a safe threshold.
  */
 export var DEFAULT_EXPERIENCE_SAMPLE_RATE = 0.001;

package/dist/esm/experiences/experience-state.js

@@ -1,7 +1,3 @@
-/**
- * Represents the state of an experience throughout its lifecycle.
- */
-
 /**
  * State transition map defining valid state transitions.
  */

package/dist/esm/experiences/index.js

@@ -2,7 +2,7 @@
 /* eslint-disable @atlaskit/editor/no-re-export */
 
 export { Experience } from './Experience';
-export { EXPERIENCE_FAILURE_REASON } from './consts';
+export { EXPERIENCE_ABORT_REASON, EXPERIENCE_FAILURE_REASON } from './consts';
 export { ExperienceCheckComposite } from './ExperienceCheckComposite';
 export { ExperienceCheckDomMutation } from './ExperienceCheckDomMutation';
 export { ExperienceCheckTimeout } from './ExperienceCheckTimeout';

package/dist/esm/monitoring/error.js

@@ -7,7 +7,7 @@ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t =
 import { isFedRamp } from './environment';
 var SENTRY_DSN = 'https://0b10c8e02fb44d8796c047b102c9bee8@o55978.ingest.sentry.io/4505129224110080';
 var packageName = 'editor-common'; // Sentry doesn't accept '/' in its releases https://docs.sentry.io/platforms/javascript/configuration/releases/
-var packageVersion = "110.28.0";
+var packageVersion = "0.0.0-development";
 var sanitiseSentryEvents = function sanitiseSentryEvents(data, _hint) {
   // Remove URL as it has UGC
   // Ignored via go/ees007

package/dist/esm/ui/DropList/index.js

@@ -21,7 +21,7 @@ import withAnalyticsEvents from '@atlaskit/analytics-next/withAnalyticsEvents';
 import { fg } from '@atlaskit/platform-feature-flags';
 import Layer from '../Layer';
 var packageName = "@atlaskit/editor-common";
-var packageVersion = "110.28.0";
+var packageVersion = "0.0.0-development";
 var halfFocusRing = 1;
 var dropOffset = '0, 8';
 var fadeIn = keyframes({

package/dist/esm/utils/annotation/index.js

@@ -203,9 +203,6 @@ export function getAnnotationInlineNodeTypes(state, annotationId) {
 	Used with the creation of the inline nodes: emoji, status, dates, mentions & inlineCards.
 */
 export function getAnnotationMarksForPos(pos) {
-  if (!fg('editor_inline_comments_paste_insert_nodes')) {
-    return undefined;
-  }
   var annotationMarks = pos.marks().filter(function (mark) {
     return mark.type === pos.doc.type.schema.marks.annotation;
   });

package/dist/types/analytics/types/experience-events.d.ts

@@ -1,11 +1,10 @@
-import type { ExperienceState } from '../../experiences/experience-state';
+import type { CustomExperienceMetadata, ExperienceState } from '../../experiences/types';
 import type { ACTION, ACTION_SUBJECT } from './enums';
 import type { OperationalAEP } from './utils';
 /**
  * Experience event attributes for tracking experience state transitions.
  */
-type ExperienceEventAttributes = {
-    [key: string]: unknown;
+export type ExperienceEventAttributes = CustomExperienceMetadata & {
     /**
      * The unique key identifying the experience being tracked.
      */
@@ -18,7 +17,31 @@ type ExperienceEventAttributes = {
      * Whether this is the first transition to this status for this experience
      * in the current editor session.
      */
-    firstInSession: boolean;
+    experienceStatusFirstSeen: boolean;
+    /**
+     * Timestamp when the experience started.
+     *
+     * Milliseconds since epoch.
+     */
+    experienceStartTime: number;
+    /**
+     * Duration from experience start to current status transition.
+     *
+     * Measured in milliseconds.
+     */
+    experienceDuration: number;
+    /**
+     * Optional method for experience start, e.g., how the experience was initiated.
+     */
+    experienceStartMethod?: string;
+    /**
+     * Optional reason for experience end, e.g., abort or failure reason.
+     */
+    experienceEndReason?: string;
+    /**
+     * Optional action that triggered the experience, if applicable.
+     */
+    experienceAction?: string;
 };
 /**
  * Event fired on every successful experience state transition.

package/dist/types/analytics/types/mention-events.d.ts

@@ -16,6 +16,7 @@ type MentionTypeaheadInviteItemViewedPayload = UIAEP<ACTION.RENDERED, ACTION_SUB
     containerId: string;
     objectId: string;
     sessionId: string;
+    source: string;
     userRole?: string;
 }, undefined>;
 type MentionTypeaheadInviteItemClickedPayload = UIAEP<ACTION.CLICKED | ACTION.PRESSED, ACTION_SUBJECT.INVITE_ITEM, undefined, {

package/dist/types/experiences/Experience.d.ts

@@ -1,6 +1,6 @@
-import type { CustomData } from '@atlaskit/ufo';
 import type { DispatchAnalyticsEvent } from '../analytics';
 import type { ExperienceCheck } from './ExperienceCheck';
+import type { CustomExperienceMetadata } from './types';
 type ExperienceOptions = {
     /**
      * Checks used to control experience transition to various states.
@@ -25,20 +25,40 @@ type ExperienceOptions = {
      * instrumentation, then the sample rate can be tuned up to a safe threshold.
      */
     sampleRate?: number;
+    /**
+     * Optional global metadata to attach to all analytics events for this experience.
+     *
+     * Can be overridden by metadata provided in individual start/abort/fail/success calls.
+     */
+    metadata?: CustomExperienceMetadata;
+    /**
+     * An optional sub identifier to further classify the specific experience action taken
+     *
+     * e.g. 'bold' 'bullet' 'insert-table'
+     */
+    action?: string;
 };
 type ExperienceStartOptions = {
-    metadata?: CustomData;
+    metadata?: CustomExperienceMetadata;
+    method?: string;
+    forceRestart?: boolean;
 };
 type ExperienceEndOptions = {
-    metadata?: CustomData;
+    reason?: string;
+    metadata?: CustomExperienceMetadata;
 };
 export declare class Experience {
     private readonly id;
     private readonly dispatchAnalyticsEvent;
     private readonly sampleRate;
-    private check;
-    private startOptions;
+    private readonly globalMetadata;
+    private readonly check;
     private currentState;
+    /**
+     * Set of experience states that have been seen in the current session.
+     *
+     * Used to determine if experienceStatusFirstSeen flag should be set in events.
+     */
     private statesSeen;
     /**
      * Indicates whether sampled tracking is enabled for this current experience session.
@@ -48,10 +68,33 @@ export declare class Experience {
      * Ensures that every tracked start has corresponding abort/fail/success tracked.
      */
     private isSampledTrackingEnabled;
+    /**
+     * Timestamp (in milliseconds) when the experience transitioned to 'started' state.
+     *
+     * Used to calculate experience duration. Set via Date.now() when experience starts.
+     */
+    private startTimeMs;
+    /**
+     * Metadata provided at experience start time to merge into subsequent events.
+     *
+     * Used to retain experienceStartMethod and other start-specific metadata.
+     */
+    private startMetadata;
+    /**
+     * Creates a new Experience instance for tracking user experiences.
+     *
+     * @param id - Unique identifier for the experience
+     * @param options - Configuration options for the experience
+     * @param options.checks - Experience checks to monitor for completion
+     * @param options.dispatchAnalyticsEvent - Function to dispatch analytics events
+     * @param options.sampleRate - Sample rate for experienceSampled events
+     * @param options.metadata - Global metadata to attach to all events
+     * @param options.action - Optional sub identifier for the specific experience action
+     */
     constructor(id: string, options: ExperienceOptions);
     private startCheck;
     private stopCheck;
-    private getEndStateConfig;
+    private getEndStateMetadata;
     /**
      * Transitions to a new experience state and tracks analytics events.
      *
@@ -79,16 +122,20 @@ export declare class Experience {
      * Metadata from options will be merged with metadata provided in subsequent events.
      *
      * @param options - Configuration for starting the experience
-     * @param options.metadata - Optional metadata attached to all subsequent events for this started experience
+     * @param options.metadata - Optional custom metadata attached to all subsequent events for this started experience
+     * @param options.forceRestart - If true and experience already in progress will abort and restart
+     * @param options.method - Optional method for experience start, e.g., how the experience was initiated
      */
-    start(options?: ExperienceStartOptions): void;
+    start(options: ExperienceStartOptions): boolean;
     /**
      * Marks the experience as successful and stops any ongoing checks.
      *
      * @param options - Configuration for the success event
-     * @param options.metadata - Optional metadata attached to the success event
+     * @param options.metadata - Optional custom metadata attached to the success event
+     * @param options.reason - Optional reason for success
+     * @returns false if transition to success state was not valid
      */
-    success(options?: ExperienceEndOptions): void;
+    success(options?: ExperienceEndOptions): boolean;
     /**
      * Aborts the experience and stops any ongoing checks.
      *
@@ -96,23 +143,28 @@ export declare class Experience {
      * (e.g., component unmount, navigation). This is neither success nor failure.
      *
      * @param options - Configuration for the abort event
-     * @param options.metadata - Optional metadata attached to the abort event
+     * @param options.metadata - Optional custom metadata attached to the abort event
+     * @param options.reason - Optional reason for abort
      *
      * @example
      * // Abort on component unmount
      * useEffect(() => {
-     *   return () => experience.abort({ metadata: { reason: 'unmount' } });
+     *   return () => experience.abort({ reason: 'unmount', metadata: { someKey: 'someValue' } });
      * }, []);
+     *
+     * @returns false if transition to aborted state was not valid
      */
-    abort(options?: ExperienceEndOptions): void;
+    abort(options?: ExperienceEndOptions): boolean;
     /**
      * Manually marks the experience as failed and stops any ongoing checks.
      *
      * Use this for actual failures in the experience flow (e.g., timeout, error conditions).
      *
      * @param options - Configuration for the failure event
-     * @param options.metadata - Optional metadata attached to the failure event
+     * @param options.metadata - Optional custom metadata attached to the failure event
+     * @param options.reason - Optional reason for failure
+     * @returns false if transition to failed state was not valid
      */
-    failure(options?: ExperienceEndOptions): void;
+    failure(options?: ExperienceEndOptions): boolean;
 }
 export {};

package/dist/types/experiences/ExperienceCheck.d.ts

@@ -1,7 +1,8 @@
-import type { CustomData } from '@atlaskit/ufo';
+import type { CustomExperienceMetadata } from './types';
 type ExperienceCheckResultStatus = 'success' | 'failure' | 'abort';
 export type ExperienceCheckResult = {
-    metadata?: CustomData;
+    metadata?: CustomExperienceMetadata;
+    reason?: string;
     status: ExperienceCheckResultStatus;
 };
 export type ExperienceCheckCallback = (result: ExperienceCheckResult) => void;