@atlaskit/rovo-agent-analytics 0.19.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @atlaskit/rovo-agent-analytics
 
+## 1.0.0
+
+### Major Changes
+
+- [`e4034958fc116`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/e4034958fc116) -
+  Adjust event tracking for agent analytics to use new trackAgentEvent() method. Remove deprecated
+  trackAgentAction() export and exported action const enums
+
+## 0.20.0
+
+### Minor Changes
+
+- [`30edbd0d978ea`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/30edbd0d978ea) -
+  Deprecate trackAgentAction() and enums exports, introduce trackAgentEvent()
+
 ## 0.19.0
 
 ### Minor Changes

package/README.md

@@ -1,166 +1,175 @@
 # RovoAgentAnalytics
 
-Rovo Agents analytics
+Rovo Agents analytics library for composing and sending typed analytics events.
 
 ## Usage
 
-`import RovoAgentAnalytics from '@atlaskit/rovo-agent-analytics';`
+```typescript
+import { useRovoAgentActionAnalytics } from '@atlaskit/rovo-agent-analytics/actions';
+
+const { trackAgentEvent } = useRovoAgentActionAnalytics({});
+
+// Full control over event properties — all fields are type-checked
+trackAgentEvent({
+  action: 'view',
+  actionSubject: 'rovoAgent',
+  attributes: { 
+    agentId: 'agent-123',
+    touchPoint: 'browse-agent-list',
+  },
+});
+```
 
 Detailed docs and example usage can be found
 [here](https://atlaskit.atlassian.com/packages/ai-mate/rovo-agent-analytics).
 
 ## Examples
 
-### Basic usage with common attributes
+### Basic Event Tracking
+
+For fully-typed events with explicit `action`, `actionSubject`, and `attributes`:
 
 ```typescript
-import { useRovoAgentActionAnalytics, AgentCommonActions } from '@atlaskit/rovo-agent-analytics';
+import { useRovoAgentActionAnalytics } from '@atlaskit/rovo-agent-analytics/actions';
 
-const { trackAgentAction } = useRovoAgentActionAnalytics({
-	agentId,
-	touchPoint: 'browse-agent-list',
+const { trackAgentEvent } = useRovoAgentActionAnalytics({
+  agentId,
+  touchPoint: 'browse-agent-list',
 });
 
-// No additional attributes needed - agentId and touchPoint already provided
-trackAgentAction(AgentCommonActions.DUPLICATE, {});
+// Track a user interaction
+trackAgentEvent({
+  action: 'duplicate',
+  actionSubject: 'rovoAgent',
+  attributes: {},
+});
 ```
 
-### Usage with debug actions (no attributes required)
+### Event Tracking with Custom Attributes
 
 ```typescript
-import { useRovoAgentActionAnalytics, AgentDebugActions } from '@atlaskit/rovo-agent-analytics';
-
-const { trackAgentAction } = useRovoAgentActionAnalytics({});
-
-// Debug actions don't require any attributes
-trackAgentAction(AgentDebugActions.VIEW, {});
-trackAgentAction(AgentDebugActions.COPY, {});
+import { useRovoAgentActionAnalytics } from '@atlaskit/rovo-agent-analytics/actions';
+
+const { trackAgentEvent } = useRovoAgentActionAnalytics({});
+
+// Full control over event properties — all fields are type-checked
+trackAgentEvent({
+  action: 'created',
+  actionSubject: 'batchEvaluationDataset',
+  attributes: { 
+    totalQuestions: 5 
+  },
+  objectType: 'batchEvaluationDataset',
+  objectId: 'dataset-123',
+});
 ```
 
-## Action Groups
-
-Actions are organized into **groups** — self-contained files that define their actions, attribute
-types, and a group name that gets automatically sent as `attributes.actionGroup` in every fired event.
+## Payload Types
 
-All groups live in **one place**: `src/actions/groups/`.
+Each group file in `src/actions/groups/` exports a **discriminated union payload type** that defines all valid event shapes for that group.
 
-| Group | File | Hook | Description |
-| --- | --- | --- | --- |
-| `agentInteractions` | `agent-interactions.ts` | actions | User-initiated interactions from overflow menu / profile (view, edit, delete, duplicate, star, chat, verify…) |
-| `editing` | `editing.ts` | actions | Agent save/mutation events (updated) |
-| `debug` | `debug.ts` | actions | Debug modal actions (view, copy, toggle skill info) |
-| `tools` | `tools.ts` | actions | Tool execution actions (confirm, stream stop, result viewed, error) |
-| `createFlow` | `create-flow.ts` | create | Create agent funnel steps (start, skip NL, review, activate, restart, error, land, discard) |
-| `addToolsPrompt` | `add-tools-prompt.ts` | create | Add tools prompt modal shown when activating an agent with no tools (shown, browse, dismiss) |
+| File | Payload Type | Description |
+| --- | --- | --- |
+| `agent-interactions.ts` | `AgentInteractionsEventPayload` | User-initiated interactions (view, edit, delete, duplicate, star, chat, verify…) |
+| `editing.ts` | `EditingEventPayload` | Agent save/mutation events (updated) |
+| `debug.ts` | `DebugEventPayload` | Debug modal actions (view, copy, toggle skill info) |
+| `tools.ts` | `ToolsEventPayload` | Tool execution actions (confirm, stream stop, result viewed, error) |
+| `evaluation.ts` | `EvaluationEventPayload` | Batch evaluation events (dataset CRUD, job lifecycle, results viewed) |
+| `create-flow.ts` | `CreateFlowEventPayload` | Create agent funnel steps |
+| `add-tools-prompt.ts` | `AddToolsPromptEventPayload` | Add tools prompt modal events |
 
-The `actionGroup` value is visible in Databricks via `attributes.actionGroup`.
+The combined `EventPayload` type (exported from `types.ts`) is a union of all these payload types.
 
 ## Adding a New Action
 
-### To an existing group
-
-1. Open the group file (e.g. `src/actions/groups/agent-interactions.ts` or `src/actions/groups/create-flow.ts`)
-2. Add the action to the enum with a data-portal registry link:
-
-```typescript
-export enum AgentInteractionActions {
-	// ... existing actions
-	/* My new action - https://data-portal.internal.atlassian.com/analytics/registry/XXXXX */
-	MY_NEW_ACTION = 'myNewAction',
-}
-```
+### To an existing payload type
 
-3. Add the attribute type in the same file:
+1. Open the group file (e.g. `src/actions/groups/agent-interactions.ts`)
+2. Add a new variant to the payload union type with a data-portal registry link:
 
 ```typescript
-export type AgentInteractionAttributes = {
-	// ... existing actions
-	[AgentInteractionActions.MY_NEW_ACTION]: BaseAgentAnalyticsAttributes;
-};
+export type AgentInteractionsEventPayload =
+  | {
+      // https://data-portal.internal.atlassian.com/analytics/registry/XXXXX
+      actionSubject: 'rovoAgent';
+      action: 'myNewAction';
+      attributes: BaseAgentAnalyticsAttributes & {
+        myCustomField: string;
+      };
+    }
+  | // ... existing variants
 ```
 
-That's it — the action is automatically registered and will fire with `actionGroup: 'agentInteractions'`.
+That's it — TypeScript will enforce the correct shape when calling `trackAgentEvent()`.
 
 ### To a new group
 
 If your action doesn't fit any existing group, create a new one:
 
-1. Create a new file in `src/actions/groups/`. Use any existing group file as a template — each one
-   has a header comment explaining the structure.
-
-2. Register the group in `src/actions/registry.ts`:
+1. Create a new file in `src/actions/groups/` following the existing template
+2. Export a discriminated union payload type (e.g. `MyFeatureEventPayload`)
+3. Add the new type to the `EventPayload` union in `src/common/types.ts`:
 
 ```typescript
-// 1. Import the group
-import {
-	MyFeatureActions,
-	type MyFeatureActionAttributes,
-	ACTION_GROUP as MY_FEATURE_GROUP,
-} from './groups/my-feature';
-
-// 2. Add to the combined type
-export type ActionAttributes = AgentInteractionAttributes &
-	EditingActionAttributes &
-	DebugActionAttributes &
-	ToolsActionAttributes &
-	MyFeatureActionAttributes;
-
-// 3. Add to the runtime group map
-export const ACTION_TO_GROUP: Record<string, string> = {
-	...mapActionsToGroup(AgentInteractionActions, AGENT_INTERACTIONS_GROUP),
-	...mapActionsToGroup(AgentEditingActions, EDITING_GROUP),
-	...mapActionsToGroup(AgentDebugActions, DEBUG_GROUP),
-	...mapActionsToGroup(AgentToolActions, TOOLS_GROUP),
-	...mapActionsToGroup(MyFeatureActions, MY_FEATURE_GROUP),
-};
+import type { MyFeatureEventPayload } from '../actions/groups/my-feature';
+
+export type EventPayload =
+  | EditingEventPayload
+  | AgentInteractionsEventPayload
+  // ... existing types
+  | MyFeatureEventPayload;
 ```
 
-## Defining Custom Attributes Per Action
+## Defining Custom Attributes
 
-Each action can have its own specific attributes. The `trackAgentAction` function is generic and
-will enforce the correct attributes based on the action you pass.
+Each action variant in a payload type can have its own specific attributes:
 
 ### Using BaseAgentAnalyticsAttributes
 
-For actions that only need `touchPoint` and `agentId`:
+For actions that need `touchPoint` and `agentId`:
 
 ```typescript
-export type AgentInteractionAttributes = {
-	[AgentInteractionActions.VIEW]: BaseAgentAnalyticsAttributes;
-};
+{
+  actionSubject: 'rovoAgent';
+  action: 'view';
+  attributes: BaseAgentAnalyticsAttributes;
+}
 ```
 
 ### Using Custom Attributes
 
-For actions that need additional attributes beyond the base ones:
-
-```typescript
-export type EditingActionAttributes = {
-	[AgentEditingActions.UPDATED]: BaseAgentAnalyticsAttributes & { agentType: string; field: string };
-};
-```
-
-When calling `trackAgentAction`, TypeScript will enforce the custom attributes:
+For actions that need additional attributes:
 
 ```typescript
-trackAgentAction(AgentEditingActions.UPDATED, { agentType: 'custom', field: 'name' });
+{
+  actionSubject: 'rovoAgent';
+  action: 'updated';
+  attributes: BaseAgentAnalyticsAttributes & { 
+    agentType: string; 
+    field: string; 
+  };
+}
 ```
 
-### How Type Inference Works
+## Entry Points
 
-The `trackAgentAction` function uses generics to infer required attributes:
+| Entry Point | Description |
+| --- | --- |
+| `@atlaskit/rovo-agent-analytics/actions` | Main entry point — exports `useRovoAgentActionAnalytics` hook |
+| `@atlaskit/rovo-agent-analytics/create` | Create agent flow analytics — exports `useRovoAgentCreateAnalytics` hook and `AgentCreateAction` type |
 
-1. When you call `trackAgentAction(action, attributes)`, TypeScript infers the action type
-2. It looks up `ActionAttributes[action]` to get the required attributes for that action
-3. It subtracts any attributes already provided in `commonAttributes` (via `RemainingRequired`)
-4. The remaining attributes must be provided in the `attributes` parameter
+### Create Flow Analytics
 
-Example:
+The `useRovoAgentCreateAnalytics` hook is used for tracking the agent creation funnel:
 
 ```typescript
-// If commonAttributes already includes agentId
-const { trackAgentAction } = useRovoAgentActionAnalytics({ agentId: '123' });
+import { useRovoAgentCreateAnalytics } from '@atlaskit/rovo-agent-analytics/create';
+
+const [csid, { trackCreateSession, trackCreateSessionStart }] = useRovoAgentCreateAnalytics({
+  touchPoint: 'agent-studio',
+});
 
-// Only touchPoint is required since agentId was already provided
-trackAgentAction(AgentCommonActions.VIEW, { touchPoint: 'my-touchpoint' });
+// Track funnel steps using string literal actions
+trackCreateSession('createFlowStart');
+trackCreateSession('createFlowActivate', { agentType: 'custom' });
 ```

package/dist/cjs/actions/groups/agent-interactions.js

@@ -2,43 +2,4 @@
 
 Object.defineProperty(exports, "__esModule", {
   value: true
-});
-exports.AgentInteractionActions = exports.ACTION_GROUP = void 0;
-/**
- * Action Group: agentInteractions
- *
- * User-initiated interactions with an agent — typically from the overflow menu ("...")
- * or agent profile surfaces (viewing, editing, deleting, duplicating, starring, sharing, verifying).
- *
- * NOTE: This is about UI interactions, not backend "actions" (which are being replaced by "tools").
- *
- * ## Adding a new action
- * 1. Add the action to the `AgentInteractionActions` enum below with a data-portal link
- * 2. Add the corresponding attribute type in `AgentInteractionAttributes`
- * 3. If this action doesn't fit user interactions, create a new group file instead
- *    (see other files in this directory for the template)
- */
-
-/** The group name sent as `attributes.actionGroup` in analytics events */
-var ACTION_GROUP = exports.ACTION_GROUP = 'agentInteractions';
-var AgentInteractionActions = exports.AgentInteractionActions = /*#__PURE__*/function (AgentInteractionActions) {
-  /* View agent clicked - https://data-portal.internal.atlassian.com/analytics/registry/97125 */
-  AgentInteractionActions["VIEW"] = "view";
-  /* Edit agent clicked - https://data-portal.internal.atlassian.com/analytics/registry/97126 */
-  AgentInteractionActions["EDIT"] = "edit";
-  /* Copy link clicked - https://data-portal.internal.atlassian.com/analytics/registry/97128 */
-  AgentInteractionActions["COPY_LINK"] = "copyLink";
-  /* Delete agent clicked - https://data-portal.internal.atlassian.com/analytics/registry/97129 */
-  AgentInteractionActions["DELETE"] = "delete";
-  /* Duplicate agent clicked - https://data-portal.internal.atlassian.com/analytics/registry/97130 */
-  AgentInteractionActions["DUPLICATE"] = "duplicate";
-  /* Star agent clicked - https://data-portal.internal.atlassian.com/analytics/registry/97133 */
-  AgentInteractionActions["STAR"] = "star";
-  /* Chat with agent clicked - https://data-portal.internal.atlassian.com/analytics/registry/97095 */
-  AgentInteractionActions["CHAT"] = "chat";
-  /* Verify agent clicked - https://data-portal.internal.atlassian.com/analytics/registry/97134 */
-  AgentInteractionActions["VERIFY"] = "verify";
-  /* Unverify agent clicked - https://data-portal.internal.atlassian.com/analytics/registry/97135 */
-  AgentInteractionActions["UNVERIFY"] = "unverify";
-  return AgentInteractionActions;
-}({});
+});

package/dist/cjs/actions/groups/debug.js

@@ -1,31 +1 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.AgentDebugActions = exports.ACTION_GROUP = void 0;
-/**
- * Action Group: debug
- *
- * Actions related to the agent debug modal (viewing, copying debug data, toggling skill info).
- *
- * ## Adding a new action
- * 1. Add the action to the `AgentDebugActions` enum below with a data-portal link
- * 2. Add the corresponding attribute type in `DebugActionAttributes`
- * 3. If this action doesn't fit this group, consider creating a new group file instead
- *    (see other files in this directory for the template)
- */
-
-/** The group name sent as `attributes.actionGroup` in analytics events */
-var ACTION_GROUP = exports.ACTION_GROUP = 'debug';
-var AgentDebugActions = exports.AgentDebugActions = /*#__PURE__*/function (AgentDebugActions) {
-  /* View debug modal - https://data-portal.internal.atlassian.com/analytics/registry/97183 */
-  AgentDebugActions["VIEW"] = "debugView";
-  /* Copy all debug data - https://data-portal.internal.atlassian.com/analytics/registry/97186 */
-  AgentDebugActions["COPY_ALL"] = "debugCopyAll";
-  /* Copy debug data - https://data-portal.internal.atlassian.com/analytics/registry/97184 */
-  AgentDebugActions["COPY"] = "debugCopy";
-  /* Toggle skill info - https://data-portal.internal.atlassian.com/analytics/registry/97185 */
-  AgentDebugActions["TOGGLE_SKILL_INFO"] = "debugToggleSkillInfo";
-  return AgentDebugActions;
-}({});
+"use strict";

package/dist/cjs/actions/groups/editing.js

@@ -2,25 +2,4 @@
 
 Object.defineProperty(exports, "__esModule", {
   value: true
-});
-exports.AgentEditingActions = exports.ACTION_GROUP = void 0;
-/**
- * Action Group: editing
- *
- * Agent editing/mutation events — fired when an agent's configuration is saved or modified.
- * Unlike agentInteractions (user clicks), these track actual data changes.
- *
- * ## Adding a new action
- * 1. Add the action to the `AgentEditingActions` enum below with a data-portal link
- * 2. Add the corresponding attribute type in `EditingActionAttributes`
- * 3. If this action doesn't fit editing/mutation events, create a new group file instead
- *    (see other files in this directory for the template)
- */
-
-/** The group name sent as `attributes.actionGroup` in analytics events */
-var ACTION_GROUP = exports.ACTION_GROUP = 'editing';
-var AgentEditingActions = exports.AgentEditingActions = /*#__PURE__*/function (AgentEditingActions) {
-  /* Agent updated - https://data-portal.internal.atlassian.com/analytics/registry/97122 */
-  AgentEditingActions["UPDATED"] = "updated";
-  return AgentEditingActions;
-}({});
+});

package/dist/cjs/actions/groups/evaluation.js

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

package/dist/cjs/actions/groups/tools.js

@@ -2,31 +2,4 @@
 
 Object.defineProperty(exports, "__esModule", {
   value: true
-});
-exports.AgentToolActions = exports.ACTION_GROUP = void 0;
-/**
- * Action Group: tools
- *
- * Actions related to agent tool execution during chat
- * (confirming, streaming, viewing results, errors).
- *
- * ## Adding a new action
- * 1. Add the action to the `AgentToolActions` enum below with a data-portal link
- * 2. Add the corresponding attribute type in `ToolsActionAttributes`
- * 3. If this action doesn't fit this group, consider creating a new group file instead
- *    (see other files in this directory for the template)
- */
-
-/** The group name sent as `attributes.actionGroup` in analytics events */
-var ACTION_GROUP = exports.ACTION_GROUP = 'tools';
-var AgentToolActions = exports.AgentToolActions = /*#__PURE__*/function (AgentToolActions) {
-  /* When chatting with an agent, and tools confirmation being shown, then user click proceed with the possible actions (e.g. confirm, dismiss etc) https://data-portal.internal.atlassian.com/analytics/registry/97675 */
-  AgentToolActions["TOOLS_EXECUTION_CONFIRMED"] = "toolsExecutionConfirmed";
-  /* When tools execution result is being streamed and user stops the stream e.g. by clicking stop button https://data-portal.internal.atlassian.com/analytics/registry/97750 */
-  AgentToolActions["TOOLS_EXECUTION_STREAM_STOPPED"] = "toolsExecutionStreamStopped";
-  /* When tools execution result is done streaming and user sees the result https://data-portal.internal.atlassian.com/analytics/registry/97751*/
-  AgentToolActions["TOOLS_EXECUTION_RESULT_VIEWED"] = "toolsExecutionResultViewed";
-  /* When tools execution result streaming fails https://data-portal.internal.atlassian.com/analytics/registry/97752 */
-  AgentToolActions["TOOLS_EXECUTION_RESULT_ERROR"] = "toolsExecutionResultError";
-  return AgentToolActions;
-}({});
+});

package/dist/cjs/actions/index.js

@@ -4,24 +4,17 @@ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefau
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.useRovoAgentActionAnalytics = exports.AgentDebugActions = exports.AgentCommonActions = void 0;
+exports.useRovoAgentActionAnalytics = void 0;
+var _objectWithoutProperties2 = _interopRequireDefault(require("@babel/runtime/helpers/objectWithoutProperties"));
 var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
 var _react = require("react");
 var _analyticsNext = require("@atlaskit/analytics-next");
 var _constants = require("../common/constants");
+var _types = require("../common/types");
 var _utils = require("../common/utils");
-var _agentInteractions = require("./groups/agent-interactions");
-var _debug = require("./groups/debug");
-var _editing = require("./groups/editing");
-var _registry = require("./registry");
+var _excluded = ["action", "actionSubject", "attributes"];
 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) { (0, _defineProperty2.default)(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; }
-// Backward-compatible aliases
-// TODO: migrate consumers to use group-specific imports, then remove
-var AgentCommonActions = exports.AgentCommonActions = _objectSpread(_objectSpread({}, _agentInteractions.AgentInteractionActions), _editing.AgentEditingActions);
-
-// TODO: Remove the alias, will be breaking change, this is just for backward compatibility
-var AgentDebugActions = exports.AgentDebugActions = _debug.AgentDebugActions;
 var globalEventConfig = (0, _utils.getDefaultTrackEventConfig)();
 var useRovoAgentActionAnalytics = exports.useRovoAgentActionAnalytics = function useRovoAgentActionAnalytics(commonAttributes) {
   var analyticsContext = (0, _react.useContext)(_analyticsNext.AnalyticsReactContext);
@@ -29,35 +22,32 @@ var useRovoAgentActionAnalytics = exports.useRovoAgentActionAnalytics = function
     createAnalyticsEvent = _useAnalyticsEvents.createAnalyticsEvent;
   var commonAttributesRef = (0, _react.useRef)(commonAttributes);
   var fireAnalyticsEvent = (0, _react.useCallback)(function (event) {
-    var attributes = _objectSpread(_objectSpread(_objectSpread({}, (0, _utils.getAttributesFromContexts)(analyticsContext.getAtlaskitAnalyticsContext())), commonAttributesRef.current), event.attributes);
+    var attributes = _objectSpread(_objectSpread(_objectSpread({}, (0, _utils.getAttributesFromContexts)(analyticsContext.getAtlaskitAnalyticsContext())), commonAttributesRef.current), {}, {
+      library: _types.LIBRARY_ATTRIBUTE
+    }, event.attributes);
     createAnalyticsEvent(_objectSpread(_objectSpread(_objectSpread({}, globalEventConfig), event), {}, {
       attributes: attributes
     })).fire(_constants.ANALYTICS_CHANNEL);
   }, [createAnalyticsEvent, analyticsContext] // keep number of dependencies minimal to prevent re-rendering
   );
-  var trackAgentAction = (0, _react.useCallback)(function (action, attributes) {
-    fireAnalyticsEvent({
-      actionSubject: 'rovoAgent',
-      action: action,
-      attributes: _objectSpread(_objectSpread({}, attributes), {}, {
-        actionGroup: _registry.ACTION_TO_GROUP[action]
-      })
-    });
-  }, [fireAnalyticsEvent]);
-  var trackAgentActionError = (0, _react.useCallback)(function (action, error, attributes) {
-    fireAnalyticsEvent({
-      actionSubject: 'rovoAgentError',
-      action: action,
-      attributes: _objectSpread(_objectSpread({}, attributes), {}, {
-        actionGroup: _registry.ACTION_TO_GROUP[action],
-        error: {
-          message: error.message
-        }
-      })
-    });
+
+  /**
+   * Fully-typed event tracking using discriminated union payload types.
+   * The payload type enforces correct action, actionSubject, and attributes.
+   */
+  var trackAgentEvent = (0, _react.useCallback)(function (payload) {
+    var action = payload.action,
+      actionSubject = payload.actionSubject,
+      attributes = payload.attributes,
+      eventProps = (0, _objectWithoutProperties2.default)(payload, _excluded);
+    fireAnalyticsEvent(_objectSpread(_objectSpread({
+      actionSubject: actionSubject,
+      action: action
+    }, eventProps), {}, {
+      attributes: attributes
+    }));
   }, [fireAnalyticsEvent]);
   return {
-    trackAgentAction: trackAgentAction,
-    trackAgentActionError: trackAgentActionError
+    trackAgentEvent: trackAgentEvent
   };
 };

package/dist/cjs/common/types.js

@@ -1 +1,18 @@
-"use strict";
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.LIBRARY_ATTRIBUTE = void 0;
+/** Common library attribute injected into all events */
+var LIBRARY_ATTRIBUTE = exports.LIBRARY_ATTRIBUTE = 'agents-analytics';
+
+/**
+ * Generic error event payload type.
+ * Use with `trackAgentEvent()` to track error events.
+ */
+
+/**
+ * Union of all event payload types.
+ * Use with `trackAgentEvent()` for typed event tracking.
+ */

package/dist/cjs/create/index.js

@@ -4,22 +4,37 @@ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefau
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.useRovoAgentCreateAnalytics = exports.AgentCreateActions = void 0;
-var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
+exports.useRovoAgentCreateAnalytics = void 0;
 var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
 var _react = require("react");
 var _analyticsNext = require("@atlaskit/analytics-next");
-var _addToolsPrompt = require("../actions/groups/add-tools-prompt");
-var _createFlow = require("../actions/groups/create-flow");
-var _registry = require("../actions/registry");
 var _constants = require("../common/constants");
 var _csid = require("../common/csid");
 var _utils = require("../common/utils");
 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) { (0, _defineProperty2.default)(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; }
-// Backward-compatible alias
-// TODO: migrate consumers to use CreateFlowActions / AddToolsPromptActions directly, then remove
-var AgentCreateActions = exports.AgentCreateActions = _objectSpread(_objectSpread({}, _createFlow.CreateFlowActions), _addToolsPrompt.AddToolsPromptActions);
+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
+ */
+
 var globalEventConfig = (0, _utils.getDefaultTrackEventConfig)();
 var useRovoAgentCreateAnalytics = exports.useRovoAgentCreateAnalytics = function useRovoAgentCreateAnalytics(commonAttributes) {
   var _useRovoAgentCSID = (0, _csid.useRovoAgentCSID)(),
@@ -32,9 +47,8 @@ var useRovoAgentCreateAnalytics = exports.useRovoAgentCreateAnalytics = function
   var commonAttributesRef = (0, _react.useRef)(commonAttributes);
   var fireAnalyticsEvent = (0, _react.useCallback)(function (event) {
     var referrer = typeof window !== 'undefined' ? window.document.referrer : 'unknown';
-    var action = event.action;
     var attributes = _objectSpread(_objectSpread(_objectSpread(_objectSpread({}, (0, _utils.getAttributesFromContexts)(analyticsContext.getAtlaskitAnalyticsContext())), commonAttributesRef.current), event.attributes), {}, {
-      actionGroup: _registry.ACTION_TO_GROUP[action],
+      actionGroup: 'createFlow',
       csid: csid,
       referrer: referrer
     });
@@ -50,7 +64,7 @@ var useRovoAgentCreateAnalytics = exports.useRovoAgentCreateAnalytics = function
    */
   var trackCreateSession = (0, _react.useCallback)(function (action, attributes) {
     fireAnalyticsEvent({
-      actionSubject: 'rovoAgent',
+      actionSubject: DefaultActionSubject,
       action: action,
       attributes: attributes
     });
@@ -61,16 +75,16 @@ var useRovoAgentCreateAnalytics = exports.useRovoAgentCreateAnalytics = function
    */
   var trackCreateSessionStart = (0, _react.useCallback)(function (attributes) {
     fireAnalyticsEvent({
-      actionSubject: 'rovoAgent',
-      action: _createFlow.CreateFlowActions.START,
+      actionSubject: DefaultActionSubject,
+      action: 'createFlowStart',
       attributes: attributes
     });
     refreshCSID();
   }, [fireAnalyticsEvent, refreshCSID]);
   var trackCreateSessionError = (0, _react.useCallback)(function (error, attributes) {
     fireAnalyticsEvent({
-      actionSubject: 'rovoAgent',
-      action: _createFlow.CreateFlowActions.ERROR,
+      actionSubject: DefaultActionSubject,
+      action: 'createFlowError',
       attributes: _objectSpread({
         error: {
           message: error.message