@atlaskit/rovo-agent-analytics 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @atlaskit/rovo-agent-analytics
 
+## 1.1.0
+
+### Minor Changes
+
+- [`cffd9dae547c3`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/cffd9dae547c3) -
+  Update rovo agents analytics funnel
+
 ## 1.0.0
 
 ### Major Changes

package/dist/cjs/actions/groups/add-tools-prompt.js

@@ -0,0 +1 @@
+"use strict";

package/dist/cjs/actions/groups/create-flow.js

@@ -0,0 +1 @@
+"use strict";

package/dist/cjs/common/csid/index.js

@@ -12,46 +12,35 @@ var CACHED_CSID = null;
 var generateCSID = function generateCSID() {
   return crypto.randomUUID();
 };
-var retrieveCSID = function retrieveCSID() {
-  if (CACHED_CSID) {
-    return CACHED_CSID;
-  }
-  var queryParams = new URLSearchParams(window.location.search);
-  var querySessionId = queryParams.get(_constants.CSID_QUERY_PARAM);
-  return querySessionId !== null && querySessionId !== void 0 ? querySessionId : generateCSID();
-};
 
 /**
- * Hook to get Rovo Agent Create Session ID (CSID) from the query parameters or generate a new one if not found.
- * @returns Rovo Agent CSID as a string.
+ * Hook to manage CSID state for entry point components.
+ * The returned csid is used in href attributes and by trackCreateSessionStart.
+ * After trackCreateSessionStart fires, it calls refresh() to generate a new CSID
+ * for the next session — the component re-renders and the href updates.
  */
 var useRovoAgentCSID = exports.useRovoAgentCSID = function useRovoAgentCSID() {
-  var _useState = (0, _react.useState)(retrieveCSID()),
+  var _useState = (0, _react.useState)(CACHED_CSID || generateCSID()),
     _useState2 = (0, _slicedToArray2.default)(_useState, 2),
-    CSID = _useState2[0],
+    csid = _useState2[0],
     setCSID = _useState2[1];
+  var globalCSID = (0, _react.useMemo)(function () {
+    var queryParams = new URLSearchParams(window.location.search);
+    return queryParams.get(_constants.CSID_QUERY_PARAM);
+  }, []);
   var actions = (0, _react.useMemo)(function () {
     return {
       refresh: function refresh() {
         var newCSID = generateCSID();
         setCSID(newCSID);
+        CACHED_CSID = newCSID;
         return newCSID;
-      },
-      clear: function clear() {
-        // remove CSID query parameter
-        var url = new URL(window.location.href);
-        url.searchParams.delete(_constants.CSID_QUERY_PARAM);
-        window.history.replaceState({}, '', url.toString());
-
-        // reset state
-        setCSID(null);
-        return null;
       }
     };
   }, []);
-  (0, _react.useEffect)(function () {
-    // sync cache on state change
-    CACHED_CSID = CSID;
-  }, [CSID]);
-  return [CSID, actions];
+  return [{
+    csid: csid,
+    // generated CSID to be used in href and createFlowStart events
+    globalCSID: globalCSID // CSID from the URL query parameter
+  }, actions];
 };

package/dist/cjs/create/index.js

@@ -17,29 +17,18 @@ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t =
 var DefaultActionSubject = 'rovoAgent';
 
 /**
- * Union type of all valid create agent flow actions.
- * Includes both CreateFlow and AddToolsPrompt actions.
- *
- * Data portal registry links:
- * - createFlowStart: https://data-portal.internal.atlassian.com/analytics/registry/97089
- * - createFlowSkipNL: https://data-portal.internal.atlassian.com/analytics/registry/97127
- * - createFlowReviewNL: https://data-portal.internal.atlassian.com/analytics/registry/97124
- * - createFlowActivate: https://data-portal.internal.atlassian.com/analytics/registry/97123
- * - createFlowRestart: https://data-portal.internal.atlassian.com/analytics/registry/97131
- * - createFlowError: https://data-portal.internal.atlassian.com/analytics/registry/97132
- * - createLandInStudio: https://data-portal.internal.atlassian.com/analytics/registry/97136
- * - createDiscard: https://data-portal.internal.atlassian.com/analytics/registry/97137
- * - saDraft: https://data-portal.internal.atlassian.com/analytics/registry/97924
- * - addToolsPromptShown: https://data-portal.internal.atlassian.com/analytics/registry/98106
- * - addToolsPromptBrowse: https://data-portal.internal.atlassian.com/analytics/registry/98107
- * - addToolsPromptDismiss: https://data-portal.internal.atlassian.com/analytics/registry/98108
+ * Union of all valid actions for the create agent analytics hook.
+ * Derived from the event payload types in the action group files.
+ * To add a new action, update the payload type in the relevant group file.
  */
 
 var globalEventConfig = (0, _utils.getDefaultTrackEventConfig)();
 var useRovoAgentCreateAnalytics = exports.useRovoAgentCreateAnalytics = function useRovoAgentCreateAnalytics(commonAttributes) {
   var _useRovoAgentCSID = (0, _csid.useRovoAgentCSID)(),
     _useRovoAgentCSID2 = (0, _slicedToArray2.default)(_useRovoAgentCSID, 2),
-    csid = _useRovoAgentCSID2[0],
+    _useRovoAgentCSID2$ = _useRovoAgentCSID2[0],
+    csid = _useRovoAgentCSID2$.csid,
+    globalCSID = _useRovoAgentCSID2$.globalCSID,
     refreshCSID = _useRovoAgentCSID2[1].refresh;
   var analyticsContext = (0, _react.useContext)(_analyticsNext.AnalyticsReactContext);
   var _useAnalyticsEvents = (0, _analyticsNext.useAnalyticsEvents)(),
@@ -49,38 +38,43 @@ var useRovoAgentCreateAnalytics = exports.useRovoAgentCreateAnalytics = function
     var referrer = typeof window !== 'undefined' ? window.document.referrer : 'unknown';
     var attributes = _objectSpread(_objectSpread(_objectSpread(_objectSpread({}, (0, _utils.getAttributesFromContexts)(analyticsContext.getAtlaskitAnalyticsContext())), commonAttributesRef.current), event.attributes), {}, {
       actionGroup: 'createFlow',
-      csid: csid,
       referrer: referrer
     });
     createAnalyticsEvent(_objectSpread(_objectSpread(_objectSpread({}, globalEventConfig), event), {}, {
       attributes: attributes
     })).fire(_constants.ANALYTICS_CHANNEL);
-  }, [createAnalyticsEvent, csid, analyticsContext] // keep number of dependencies minimal to prevent re-rendering
+  }, [createAnalyticsEvent, analyticsContext] // keep number of dependencies minimal to prevent re-rendering
   );
 
   /**
-   * This will fire analytics event for intermediate steps in the create agent flow funnel
-   * To start the create agent flow, use trackCreateSessionStart
+   * Fires an analytics event for a step in the create agent flow funnel.
+   * Uses the CSID from the URL query parameter.
    */
   var trackCreateSession = (0, _react.useCallback)(function (action, attributes) {
     fireAnalyticsEvent({
       actionSubject: DefaultActionSubject,
       action: action,
-      attributes: attributes
+      attributes: _objectSpread({
+        csid: globalCSID
+      }, attributes)
     });
-  }, [fireAnalyticsEvent]);
+  }, [fireAnalyticsEvent, globalCSID]);
 
   /**
-   * This should be used ONLY in the beginning of the funnel of create agent flow, it will create a new CSID (CSID = create session ID)
+   * Fires `createFlowStart` with the current CSID (matching the href),
+   * then refreshes the CSID for the next session.
+   * The component re-renders with the new CSID, updating any href attributes.
    */
   var trackCreateSessionStart = (0, _react.useCallback)(function (attributes) {
     fireAnalyticsEvent({
       actionSubject: DefaultActionSubject,
       action: 'createFlowStart',
-      attributes: attributes
+      attributes: _objectSpread({
+        csid: csid
+      }, attributes)
     });
     refreshCSID();
-  }, [fireAnalyticsEvent, refreshCSID]);
+  }, [fireAnalyticsEvent, refreshCSID, csid]);
   var trackCreateSessionError = (0, _react.useCallback)(function (error, attributes) {
     fireAnalyticsEvent({
       actionSubject: DefaultActionSubject,
@@ -88,10 +82,11 @@ var useRovoAgentCreateAnalytics = exports.useRovoAgentCreateAnalytics = function
       attributes: _objectSpread({
         error: {
           message: error.message
-        }
+        },
+        csid: globalCSID
       }, attributes)
     });
-  }, [fireAnalyticsEvent]);
+  }, [fireAnalyticsEvent, globalCSID]);
   return [csid, {
     trackCreateSession: trackCreateSession,
     trackCreateSessionStart: trackCreateSessionStart,

package/dist/es2019/common/csid/index.js

@@ -1,46 +1,35 @@
-import { useEffect, useMemo, useState } from 'react';
+import { useMemo, useState } from 'react';
 import { CSID_QUERY_PARAM } from '../constants';
 let CACHED_CSID = null;
 const generateCSID = () => {
   return crypto.randomUUID();
 };
-const retrieveCSID = () => {
-  if (CACHED_CSID) {
-    return CACHED_CSID;
-  }
-  const queryParams = new URLSearchParams(window.location.search);
-  const querySessionId = queryParams.get(CSID_QUERY_PARAM);
-  return querySessionId !== null && querySessionId !== void 0 ? querySessionId : generateCSID();
-};
 
 /**
- * Hook to get Rovo Agent Create Session ID (CSID) from the query parameters or generate a new one if not found.
- * @returns Rovo Agent CSID as a string.
+ * Hook to manage CSID state for entry point components.
+ * The returned csid is used in href attributes and by trackCreateSessionStart.
+ * After trackCreateSessionStart fires, it calls refresh() to generate a new CSID
+ * for the next session — the component re-renders and the href updates.
  */
 export const useRovoAgentCSID = () => {
-  const [CSID, setCSID] = useState(retrieveCSID());
+  const [csid, setCSID] = useState(CACHED_CSID || generateCSID());
+  const globalCSID = useMemo(() => {
+    const queryParams = new URLSearchParams(window.location.search);
+    return queryParams.get(CSID_QUERY_PARAM);
+  }, []);
   const actions = useMemo(() => {
     return {
       refresh: () => {
         const newCSID = generateCSID();
         setCSID(newCSID);
+        CACHED_CSID = newCSID;
         return newCSID;
-      },
-      clear: () => {
-        // remove CSID query parameter
-        const url = new URL(window.location.href);
-        url.searchParams.delete(CSID_QUERY_PARAM);
-        window.history.replaceState({}, '', url.toString());
-
-        // reset state
-        setCSID(null);
-        return null;
       }
     };
   }, []);
-  useEffect(() => {
-    // sync cache on state change
-    CACHED_CSID = CSID;
-  }, [CSID]);
-  return [CSID, actions];
+  return [{
+    csid,
+    // generated CSID to be used in href and createFlowStart events
+    globalCSID // CSID from the URL query parameter
+  }, actions];
 };

package/dist/es2019/create/index.js

@@ -6,27 +6,17 @@ import { getAttributesFromContexts, getDefaultTrackEventConfig } from '../common
 const DefaultActionSubject = 'rovoAgent';
 
 /**
- * Union type of all valid create agent flow actions.
- * Includes both CreateFlow and AddToolsPrompt actions.
- *
- * Data portal registry links:
- * - createFlowStart: https://data-portal.internal.atlassian.com/analytics/registry/97089
- * - createFlowSkipNL: https://data-portal.internal.atlassian.com/analytics/registry/97127
- * - createFlowReviewNL: https://data-portal.internal.atlassian.com/analytics/registry/97124
- * - createFlowActivate: https://data-portal.internal.atlassian.com/analytics/registry/97123
- * - createFlowRestart: https://data-portal.internal.atlassian.com/analytics/registry/97131
- * - createFlowError: https://data-portal.internal.atlassian.com/analytics/registry/97132
- * - createLandInStudio: https://data-portal.internal.atlassian.com/analytics/registry/97136
- * - createDiscard: https://data-portal.internal.atlassian.com/analytics/registry/97137
- * - saDraft: https://data-portal.internal.atlassian.com/analytics/registry/97924
- * - addToolsPromptShown: https://data-portal.internal.atlassian.com/analytics/registry/98106
- * - addToolsPromptBrowse: https://data-portal.internal.atlassian.com/analytics/registry/98107
- * - addToolsPromptDismiss: https://data-portal.internal.atlassian.com/analytics/registry/98108
+ * Union of all valid actions for the create agent analytics hook.
+ * Derived from the event payload types in the action group files.
+ * To add a new action, update the payload type in the relevant group file.
  */
 
 const globalEventConfig = getDefaultTrackEventConfig();
 export const useRovoAgentCreateAnalytics = commonAttributes => {
-  const [csid, {
+  const [{
+    csid,
+    globalCSID
+  }, {
     refresh: refreshCSID
   }] = useRovoAgentCSID();
   const analyticsContext = useContext(AnalyticsReactContext);
@@ -41,7 +31,6 @@ export const useRovoAgentCreateAnalytics = commonAttributes => {
       ...commonAttributesRef.current,
       ...event.attributes,
       actionGroup: 'createFlow',
-      csid,
       referrer
     };
     createAnalyticsEvent({
@@ -49,32 +38,40 @@ export const useRovoAgentCreateAnalytics = commonAttributes => {
       ...event,
       attributes
     }).fire(ANALYTICS_CHANNEL);
-  }, [createAnalyticsEvent, csid, analyticsContext] // keep number of dependencies minimal to prevent re-rendering
+  }, [createAnalyticsEvent, analyticsContext] // keep number of dependencies minimal to prevent re-rendering
   );
 
   /**
-   * This will fire analytics event for intermediate steps in the create agent flow funnel
-   * To start the create agent flow, use trackCreateSessionStart
+   * Fires an analytics event for a step in the create agent flow funnel.
+   * Uses the CSID from the URL query parameter.
    */
   const trackCreateSession = useCallback((action, attributes) => {
     fireAnalyticsEvent({
       actionSubject: DefaultActionSubject,
       action,
-      attributes
+      attributes: {
+        csid: globalCSID,
+        ...attributes
+      }
     });
-  }, [fireAnalyticsEvent]);
+  }, [fireAnalyticsEvent, globalCSID]);
 
   /**
-   * This should be used ONLY in the beginning of the funnel of create agent flow, it will create a new CSID (CSID = create session ID)
+   * Fires `createFlowStart` with the current CSID (matching the href),
+   * then refreshes the CSID for the next session.
+   * The component re-renders with the new CSID, updating any href attributes.
    */
   const trackCreateSessionStart = useCallback(attributes => {
     fireAnalyticsEvent({
       actionSubject: DefaultActionSubject,
       action: 'createFlowStart',
-      attributes
+      attributes: {
+        csid,
+        ...attributes
+      }
     });
     refreshCSID();
-  }, [fireAnalyticsEvent, refreshCSID]);
+  }, [fireAnalyticsEvent, refreshCSID, csid]);
   const trackCreateSessionError = useCallback((error, attributes) => {
     fireAnalyticsEvent({
       actionSubject: DefaultActionSubject,
@@ -83,10 +80,11 @@ export const useRovoAgentCreateAnalytics = commonAttributes => {
         error: {
           message: error.message
         },
+        csid: globalCSID,
         ...attributes
       }
     });
-  }, [fireAnalyticsEvent]);
+  }, [fireAnalyticsEvent, globalCSID]);
   return [csid, {
     trackCreateSession,
     trackCreateSessionStart,

package/dist/esm/common/csid/index.js

@@ -1,50 +1,39 @@
 import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
-import { useEffect, useMemo, useState } from 'react';
+import { useMemo, useState } from 'react';
 import { CSID_QUERY_PARAM } from '../constants';
 var CACHED_CSID = null;
 var generateCSID = function generateCSID() {
   return crypto.randomUUID();
 };
-var retrieveCSID = function retrieveCSID() {
-  if (CACHED_CSID) {
-    return CACHED_CSID;
-  }
-  var queryParams = new URLSearchParams(window.location.search);
-  var querySessionId = queryParams.get(CSID_QUERY_PARAM);
-  return querySessionId !== null && querySessionId !== void 0 ? querySessionId : generateCSID();
-};
 
 /**
- * Hook to get Rovo Agent Create Session ID (CSID) from the query parameters or generate a new one if not found.
- * @returns Rovo Agent CSID as a string.
+ * Hook to manage CSID state for entry point components.
+ * The returned csid is used in href attributes and by trackCreateSessionStart.
+ * After trackCreateSessionStart fires, it calls refresh() to generate a new CSID
+ * for the next session — the component re-renders and the href updates.
  */
 export var useRovoAgentCSID = function useRovoAgentCSID() {
-  var _useState = useState(retrieveCSID()),
+  var _useState = useState(CACHED_CSID || generateCSID()),
     _useState2 = _slicedToArray(_useState, 2),
-    CSID = _useState2[0],
+    csid = _useState2[0],
     setCSID = _useState2[1];
+  var globalCSID = useMemo(function () {
+    var queryParams = new URLSearchParams(window.location.search);
+    return queryParams.get(CSID_QUERY_PARAM);
+  }, []);
   var actions = useMemo(function () {
     return {
       refresh: function refresh() {
         var newCSID = generateCSID();
         setCSID(newCSID);
+        CACHED_CSID = newCSID;
         return newCSID;
-      },
-      clear: function clear() {
-        // remove CSID query parameter
-        var url = new URL(window.location.href);
-        url.searchParams.delete(CSID_QUERY_PARAM);
-        window.history.replaceState({}, '', url.toString());
-
-        // reset state
-        setCSID(null);
-        return null;
       }
     };
   }, []);
-  useEffect(function () {
-    // sync cache on state change
-    CACHED_CSID = CSID;
-  }, [CSID]);
-  return [CSID, actions];
+  return [{
+    csid: csid,
+    // generated CSID to be used in href and createFlowStart events
+    globalCSID: globalCSID // CSID from the URL query parameter
+  }, actions];
 };

package/dist/esm/create/index.js

@@ -10,29 +10,18 @@ import { getAttributesFromContexts, getDefaultTrackEventConfig } from '../common
 var DefaultActionSubject = 'rovoAgent';
 
 /**
- * Union type of all valid create agent flow actions.
- * Includes both CreateFlow and AddToolsPrompt actions.
- *
- * Data portal registry links:
- * - createFlowStart: https://data-portal.internal.atlassian.com/analytics/registry/97089
- * - createFlowSkipNL: https://data-portal.internal.atlassian.com/analytics/registry/97127
- * - createFlowReviewNL: https://data-portal.internal.atlassian.com/analytics/registry/97124
- * - createFlowActivate: https://data-portal.internal.atlassian.com/analytics/registry/97123
- * - createFlowRestart: https://data-portal.internal.atlassian.com/analytics/registry/97131
- * - createFlowError: https://data-portal.internal.atlassian.com/analytics/registry/97132
- * - createLandInStudio: https://data-portal.internal.atlassian.com/analytics/registry/97136
- * - createDiscard: https://data-portal.internal.atlassian.com/analytics/registry/97137
- * - saDraft: https://data-portal.internal.atlassian.com/analytics/registry/97924
- * - addToolsPromptShown: https://data-portal.internal.atlassian.com/analytics/registry/98106
- * - addToolsPromptBrowse: https://data-portal.internal.atlassian.com/analytics/registry/98107
- * - addToolsPromptDismiss: https://data-portal.internal.atlassian.com/analytics/registry/98108
+ * Union of all valid actions for the create agent analytics hook.
+ * Derived from the event payload types in the action group files.
+ * To add a new action, update the payload type in the relevant group file.
  */
 
 var globalEventConfig = getDefaultTrackEventConfig();
 export var useRovoAgentCreateAnalytics = function useRovoAgentCreateAnalytics(commonAttributes) {
   var _useRovoAgentCSID = useRovoAgentCSID(),
     _useRovoAgentCSID2 = _slicedToArray(_useRovoAgentCSID, 2),
-    csid = _useRovoAgentCSID2[0],
+    _useRovoAgentCSID2$ = _useRovoAgentCSID2[0],
+    csid = _useRovoAgentCSID2$.csid,
+    globalCSID = _useRovoAgentCSID2$.globalCSID,
     refreshCSID = _useRovoAgentCSID2[1].refresh;
   var analyticsContext = useContext(AnalyticsReactContext);
   var _useAnalyticsEvents = useAnalyticsEvents(),
@@ -42,38 +31,43 @@ export var useRovoAgentCreateAnalytics = function useRovoAgentCreateAnalytics(co
     var referrer = typeof window !== 'undefined' ? window.document.referrer : 'unknown';
     var attributes = _objectSpread(_objectSpread(_objectSpread(_objectSpread({}, getAttributesFromContexts(analyticsContext.getAtlaskitAnalyticsContext())), commonAttributesRef.current), event.attributes), {}, {
       actionGroup: 'createFlow',
-      csid: csid,
       referrer: referrer
     });
     createAnalyticsEvent(_objectSpread(_objectSpread(_objectSpread({}, globalEventConfig), event), {}, {
       attributes: attributes
     })).fire(ANALYTICS_CHANNEL);
-  }, [createAnalyticsEvent, csid, analyticsContext] // keep number of dependencies minimal to prevent re-rendering
+  }, [createAnalyticsEvent, analyticsContext] // keep number of dependencies minimal to prevent re-rendering
   );
 
   /**
-   * This will fire analytics event for intermediate steps in the create agent flow funnel
-   * To start the create agent flow, use trackCreateSessionStart
+   * Fires an analytics event for a step in the create agent flow funnel.
+   * Uses the CSID from the URL query parameter.
    */
   var trackCreateSession = useCallback(function (action, attributes) {
     fireAnalyticsEvent({
       actionSubject: DefaultActionSubject,
       action: action,
-      attributes: attributes
+      attributes: _objectSpread({
+        csid: globalCSID
+      }, attributes)
     });
-  }, [fireAnalyticsEvent]);
+  }, [fireAnalyticsEvent, globalCSID]);
 
   /**
-   * This should be used ONLY in the beginning of the funnel of create agent flow, it will create a new CSID (CSID = create session ID)
+   * Fires `createFlowStart` with the current CSID (matching the href),
+   * then refreshes the CSID for the next session.
+   * The component re-renders with the new CSID, updating any href attributes.
    */
   var trackCreateSessionStart = useCallback(function (attributes) {
     fireAnalyticsEvent({
       actionSubject: DefaultActionSubject,
       action: 'createFlowStart',
-      attributes: attributes
+      attributes: _objectSpread({
+        csid: csid
+      }, attributes)
     });
     refreshCSID();
-  }, [fireAnalyticsEvent, refreshCSID]);
+  }, [fireAnalyticsEvent, refreshCSID, csid]);
   var trackCreateSessionError = useCallback(function (error, attributes) {
     fireAnalyticsEvent({
       actionSubject: DefaultActionSubject,
@@ -81,10 +75,11 @@ export var useRovoAgentCreateAnalytics = function useRovoAgentCreateAnalytics(co
       attributes: _objectSpread({
         error: {
           message: error.message
-        }
+        },
+        csid: globalCSID
       }, attributes)
     });
-  }, [fireAnalyticsEvent]);
+  }, [fireAnalyticsEvent, globalCSID]);
   return [csid, {
     trackCreateSession: trackCreateSession,
     trackCreateSessionStart: trackCreateSessionStart,

package/dist/types/actions/groups/add-tools-prompt.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Action Group: addToolsPrompt
+ *
+ * Events related to the "Add Tools" prompt shown during agent creation.
+ *
+ * ## Adding a new action
+ * 1. Add a new variant to the `AddToolsPromptEventPayload` union type below with a data-portal link
+ * 2. If this action doesn't fit this group, consider creating a new group file instead
+ */
+/**
+ * Discriminated union payload type for add tools prompt events.
+ * Use with `trackAgentEvent()`.
+ */
+export type AddToolsPromptEventPayload = {
+    actionSubject: 'rovoAgent';
+    action: 'addToolsPromptShown';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'addToolsPromptBrowse';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'addToolsPromptDismiss';
+    attributes: {};
+};

package/dist/types/actions/groups/create-flow.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Action Group: createFlow
+ *
+ * Create agent funnel steps — from clicking "Create agent" through to activation or discard.
+ *
+ * ## Funnel overview
+ *
+ * | Step                  | v1 (NL flow) event     | v2 (SA flow) event     | CSID behavior                    |
+ * |-----------------------|------------------------|------------------------|----------------------------------|
+ * | Intent to create      | createFlowStart        | saDraft                | Uses existing CSID                                        |
+ * | Land in NL page       | createLandInStudio     | (skipped)              | Uses existing CSID               |
+ * | NL interaction        | REVIEW_NL / SKIP_NL    | (skipped)              | Uses existing CSID               |
+ * | Land in configure     | createLandInConfigure  | createLandInConfigure  | Uses existing CSID               |
+ * | Activate agent        | createFlowActivate     | createFlowActivate     | Uses existing CSID               |
+ *
+ * ## CSID (Create Session ID)
+ *
+ * CSID links all events in a single agent creation session.
+ * - `trackCreateSessionStart()` fires `createFlowStart` with the current CSID
+ * - `trackCreateSession()` uses the existing CSID (for all other steps including `saDraft`)
+ *
+ * ## Adding a new action
+ * 1. Add a new variant to the `CreateFlowEventPayload` union type below with a data-portal link
+ * 2. If this action doesn't fit this group, consider creating a new group file instead
+ *    (see other files in this directory for the template)
+ */
+/**
+ * Discriminated union payload type for create flow events.
+ * Use with `trackAgentEvent()`.
+ */
+export type CreateFlowEventPayload = {
+    actionSubject: 'rovoAgent';
+    action: 'createFlowStart';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'createFlowSkipNL';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'createFlowReviewNL';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'createFlowActivate';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'createFlowRestart';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'createFlowError';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'createLandInStudio';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'createDiscard';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'saDraft';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'createLandInConfigure';
+    attributes: {};
+};

package/dist/types/common/constants.d.ts

@@ -1,3 +1,3 @@
 import { FabricChannel } from '@atlaskit/analytics-listeners';
-export declare const ANALYTICS_CHANNEL = FabricChannel.aiMate;
+export declare const ANALYTICS_CHANNEL: FabricChannel.aiMate;
 export declare const CSID_QUERY_PARAM = "csid";

package/dist/types/common/csid/index.d.ts

@@ -1,8 +1,12 @@
 /**
- * Hook to get Rovo Agent Create Session ID (CSID) from the query parameters or generate a new one if not found.
- * @returns Rovo Agent CSID as a string.
+ * Hook to manage CSID state for entry point components.
+ * The returned csid is used in href attributes and by trackCreateSessionStart.
+ * After trackCreateSessionStart fires, it calls refresh() to generate a new CSID
+ * for the next session — the component re-renders and the href updates.
  */
-export declare const useRovoAgentCSID: () => readonly [string | null, {
+export declare const useRovoAgentCSID: () => readonly [{
+    readonly csid: string | null;
+    readonly globalCSID: string | null;
+}, {
     refresh: () => `${string}-${string}-${string}-${string}-${string}`;
-    clear: () => null;
 }];

package/dist/types/create/index.d.ts

@@ -1,22 +1,11 @@
+import type { AddToolsPromptEventPayload } from '../actions/groups/add-tools-prompt';
+import type { CreateFlowEventPayload } from '../actions/groups/create-flow';
 /**
- * Union type of all valid create agent flow actions.
- * Includes both CreateFlow and AddToolsPrompt actions.
- *
- * Data portal registry links:
- * - createFlowStart: https://data-portal.internal.atlassian.com/analytics/registry/97089
- * - createFlowSkipNL: https://data-portal.internal.atlassian.com/analytics/registry/97127
- * - createFlowReviewNL: https://data-portal.internal.atlassian.com/analytics/registry/97124
- * - createFlowActivate: https://data-portal.internal.atlassian.com/analytics/registry/97123
- * - createFlowRestart: https://data-portal.internal.atlassian.com/analytics/registry/97131
- * - createFlowError: https://data-portal.internal.atlassian.com/analytics/registry/97132
- * - createLandInStudio: https://data-portal.internal.atlassian.com/analytics/registry/97136
- * - createDiscard: https://data-portal.internal.atlassian.com/analytics/registry/97137
- * - saDraft: https://data-portal.internal.atlassian.com/analytics/registry/97924
- * - addToolsPromptShown: https://data-portal.internal.atlassian.com/analytics/registry/98106
- * - addToolsPromptBrowse: https://data-portal.internal.atlassian.com/analytics/registry/98107
- * - addToolsPromptDismiss: https://data-portal.internal.atlassian.com/analytics/registry/98108
+ * Union of all valid actions for the create agent analytics hook.
+ * Derived from the event payload types in the action group files.
+ * To add a new action, update the payload type in the relevant group file.
  */
-type AgentCreateAction = 'createFlowStart' | 'createFlowSkipNL' | 'createFlowReviewNL' | 'createFlowActivate' | 'createFlowRestart' | 'createFlowError' | 'createLandInStudio' | 'createDiscard' | 'saDraft' | 'addToolsPromptShown' | 'addToolsPromptBrowse' | 'addToolsPromptDismiss';
+type AgentCreateAction = CreateFlowEventPayload['action'] | AddToolsPromptEventPayload['action'];
 type CommonAnalyticsAttributes = {
     touchPoint?: string;
 } & Record<string, any>;
@@ -24,6 +13,6 @@ export declare const useRovoAgentCreateAnalytics: (commonAttributes: CommonAnaly
     readonly trackCreateSession: (action: AgentCreateAction, attributes?: CommonAnalyticsAttributes) => void;
     readonly trackCreateSessionStart: (attributes?: CommonAnalyticsAttributes) => void;
     readonly trackCreateSessionError: (error: Error, attributes?: CommonAnalyticsAttributes) => void;
-    readonly refreshCSID: () => `${string}-${string}-${string}-${string}-${string}`;
+    readonly refreshCSID: () => string;
 }];
 export {};

package/dist/types-ts4.5/actions/groups/add-tools-prompt.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Action Group: addToolsPrompt
+ *
+ * Events related to the "Add Tools" prompt shown during agent creation.
+ *
+ * ## Adding a new action
+ * 1. Add a new variant to the `AddToolsPromptEventPayload` union type below with a data-portal link
+ * 2. If this action doesn't fit this group, consider creating a new group file instead
+ */
+/**
+ * Discriminated union payload type for add tools prompt events.
+ * Use with `trackAgentEvent()`.
+ */
+export type AddToolsPromptEventPayload = {
+    actionSubject: 'rovoAgent';
+    action: 'addToolsPromptShown';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'addToolsPromptBrowse';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'addToolsPromptDismiss';
+    attributes: {};
+};

package/dist/types-ts4.5/actions/groups/create-flow.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Action Group: createFlow
+ *
+ * Create agent funnel steps — from clicking "Create agent" through to activation or discard.
+ *
+ * ## Funnel overview
+ *
+ * | Step                  | v1 (NL flow) event     | v2 (SA flow) event     | CSID behavior                    |
+ * |-----------------------|------------------------|------------------------|----------------------------------|
+ * | Intent to create      | createFlowStart        | saDraft                | Uses existing CSID                                        |
+ * | Land in NL page       | createLandInStudio     | (skipped)              | Uses existing CSID               |
+ * | NL interaction        | REVIEW_NL / SKIP_NL    | (skipped)              | Uses existing CSID               |
+ * | Land in configure     | createLandInConfigure  | createLandInConfigure  | Uses existing CSID               |
+ * | Activate agent        | createFlowActivate     | createFlowActivate     | Uses existing CSID               |
+ *
+ * ## CSID (Create Session ID)
+ *
+ * CSID links all events in a single agent creation session.
+ * - `trackCreateSessionStart()` fires `createFlowStart` with the current CSID
+ * - `trackCreateSession()` uses the existing CSID (for all other steps including `saDraft`)
+ *
+ * ## Adding a new action
+ * 1. Add a new variant to the `CreateFlowEventPayload` union type below with a data-portal link
+ * 2. If this action doesn't fit this group, consider creating a new group file instead
+ *    (see other files in this directory for the template)
+ */
+/**
+ * Discriminated union payload type for create flow events.
+ * Use with `trackAgentEvent()`.
+ */
+export type CreateFlowEventPayload = {
+    actionSubject: 'rovoAgent';
+    action: 'createFlowStart';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'createFlowSkipNL';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'createFlowReviewNL';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'createFlowActivate';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'createFlowRestart';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'createFlowError';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'createLandInStudio';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'createDiscard';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'saDraft';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'createLandInConfigure';
+    attributes: {};
+};

package/dist/types-ts4.5/common/constants.d.ts

@@ -1,3 +1,3 @@
 import { FabricChannel } from '@atlaskit/analytics-listeners';
-export declare const ANALYTICS_CHANNEL = FabricChannel.aiMate;
+export declare const ANALYTICS_CHANNEL: FabricChannel.aiMate;
 export declare const CSID_QUERY_PARAM = "csid";

package/dist/types-ts4.5/common/csid/index.d.ts

@@ -1,11 +1,15 @@
 /**
- * Hook to get Rovo Agent Create Session ID (CSID) from the query parameters or generate a new one if not found.
- * @returns Rovo Agent CSID as a string.
+ * Hook to manage CSID state for entry point components.
+ * The returned csid is used in href attributes and by trackCreateSessionStart.
+ * After trackCreateSessionStart fires, it calls refresh() to generate a new CSID
+ * for the next session — the component re-renders and the href updates.
  */
 export declare const useRovoAgentCSID: () => readonly [
-    string | null,
+    {
+        readonly csid: string | null;
+        readonly globalCSID: string | null;
+    },
     {
         refresh: () => `${string}-${string}-${string}-${string}-${string}`;
-        clear: () => null;
     }
 ];

package/dist/types-ts4.5/create/index.d.ts

@@ -1,22 +1,11 @@
+import type { AddToolsPromptEventPayload } from '../actions/groups/add-tools-prompt';
+import type { CreateFlowEventPayload } from '../actions/groups/create-flow';
 /**
- * Union type of all valid create agent flow actions.
- * Includes both CreateFlow and AddToolsPrompt actions.
- *
- * Data portal registry links:
- * - createFlowStart: https://data-portal.internal.atlassian.com/analytics/registry/97089
- * - createFlowSkipNL: https://data-portal.internal.atlassian.com/analytics/registry/97127
- * - createFlowReviewNL: https://data-portal.internal.atlassian.com/analytics/registry/97124
- * - createFlowActivate: https://data-portal.internal.atlassian.com/analytics/registry/97123
- * - createFlowRestart: https://data-portal.internal.atlassian.com/analytics/registry/97131
- * - createFlowError: https://data-portal.internal.atlassian.com/analytics/registry/97132
- * - createLandInStudio: https://data-portal.internal.atlassian.com/analytics/registry/97136
- * - createDiscard: https://data-portal.internal.atlassian.com/analytics/registry/97137
- * - saDraft: https://data-portal.internal.atlassian.com/analytics/registry/97924
- * - addToolsPromptShown: https://data-portal.internal.atlassian.com/analytics/registry/98106
- * - addToolsPromptBrowse: https://data-portal.internal.atlassian.com/analytics/registry/98107
- * - addToolsPromptDismiss: https://data-portal.internal.atlassian.com/analytics/registry/98108
+ * Union of all valid actions for the create agent analytics hook.
+ * Derived from the event payload types in the action group files.
+ * To add a new action, update the payload type in the relevant group file.
  */
-type AgentCreateAction = 'createFlowStart' | 'createFlowSkipNL' | 'createFlowReviewNL' | 'createFlowActivate' | 'createFlowRestart' | 'createFlowError' | 'createLandInStudio' | 'createDiscard' | 'saDraft' | 'addToolsPromptShown' | 'addToolsPromptBrowse' | 'addToolsPromptDismiss';
+type AgentCreateAction = CreateFlowEventPayload['action'] | AddToolsPromptEventPayload['action'];
 type CommonAnalyticsAttributes = {
     touchPoint?: string;
 } & Record<string, any>;
@@ -26,7 +15,7 @@ export declare const useRovoAgentCreateAnalytics: (commonAttributes: CommonAnaly
         readonly trackCreateSession: (action: AgentCreateAction, attributes?: CommonAnalyticsAttributes) => void;
         readonly trackCreateSessionStart: (attributes?: CommonAnalyticsAttributes) => void;
         readonly trackCreateSessionError: (error: Error, attributes?: CommonAnalyticsAttributes) => void;
-        readonly refreshCSID: () => `${string}-${string}-${string}-${string}-${string}`;
+        readonly refreshCSID: () => string;
     }
 ];
 export {};

package/package.json

@@ -1,4 +1,8 @@
 {
+	"name": "@atlaskit/rovo-agent-analytics",
+	"version": "1.1.0",
+	"description": "Rovo Agents analytics",
+	"repository": "https://bitbucket.org/atlassian/atlassian-frontend-monorepo",
 	"atlassian": {
 		"team": "Rovo Agents",
 		"website": {
@@ -6,7 +10,11 @@
 			"category": "Layout and structure"
 		}
 	},
-	"repository": "https://bitbucket.org/atlassian/atlassian-frontend-monorepo",
+	"author": "Atlassian Pty Ltd",
+	"license": "Apache-2.0",
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org/"
+	},
 	"main": "dist/cjs/index.js",
 	"module": "dist/esm/index.js",
 	"module:es2019": "dist/es2019/index.js",
@@ -19,19 +27,16 @@
 			]
 		}
 	},
+	"atlaskit:src": "src/index.ts",
 	"sideEffects": [
 		"*.compiled.css"
 	],
-	"atlaskit:src": "src/index.ts",
 	"dependencies": {
 		"@atlaskit/analytics-listeners": "^10.0.0",
 		"@atlaskit/analytics-next": "^11.1.0",
 		"@babel/runtime": "^7.0.0",
 		"@compiled/react": "^0.20.0"
 	},
-	"peerDependencies": {
-		"react": "^18.2.0"
-	},
 	"devDependencies": {
 		"@af/integration-testing": "workspace:^",
 		"@af/visual-regression": "workspace:^",
@@ -39,6 +44,9 @@
 		"@testing-library/react": "^16.3.0",
 		"react-dom": "^18.2.0"
 	},
+	"peerDependencies": {
+		"react": "^18.2.0"
+	},
 	"techstack": {
 		"@atlassian/frontend": {
 			"import-structure": [
@@ -73,13 +81,5 @@
 				"import-no-extraneous-disable-for-examples-and-docs"
 			]
 		}
-	},
-	"name": "@atlaskit/rovo-agent-analytics",
-	"version": "1.0.0",
-	"description": "Rovo Agents analytics",
-	"author": "Atlassian Pty Ltd",
-	"license": "Apache-2.0",
-	"publishConfig": {
-		"registry": "https://registry.npmjs.org/"
 	}
 }