@atlaskit/rovo-agent-analytics 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @atlaskit/rovo-agent-analytics
 
+## 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,17 +1,21 @@
 # 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';
+```
 
 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 usage with `trackAgentAction()` (deprecated)
+
+For simple actions with default `actionSubject: 'rovoAgent'`:
 
 ```typescript
 import { useRovoAgentActionAnalytics, AgentCommonActions } from '@atlaskit/rovo-agent-analytics';
@@ -25,142 +29,132 @@ const { trackAgentAction } = useRovoAgentActionAnalytics({
 trackAgentAction(AgentCommonActions.DUPLICATE, {});
 ```
 
-### Usage with debug actions (no attributes required)
+> **Note:** `trackAgentAction()` is deprecated. Prefer `trackAgentEvent()` for new code.
 
-```typescript
-import { useRovoAgentActionAnalytics, AgentDebugActions } from '@atlaskit/rovo-agent-analytics';
+### Full Event Tracking with `trackAgentEvent()` (recommended)
 
-const { trackAgentAction } = useRovoAgentActionAnalytics({});
+For fully-typed events with explicit `action`, `actionSubject`, and `attributes`:
 
-// Debug actions don't require any attributes
-trackAgentAction(AgentDebugActions.VIEW, {});
-trackAgentAction(AgentDebugActions.COPY, {});
+```typescript
+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
+### When to use `trackAgentEvent()` vs `trackAgentAction()`
 
-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.
+| Use Case | Function |
+| --- | --- |
+| New code (recommended) | `trackAgentEvent()` |
+| Events with custom `actionSubject` | `trackAgentEvent()` |
+| Events with `source`, `objectType`, `objectId`, etc. | `trackAgentEvent()` |
+| Legacy code with default `actionSubject: 'rovoAgent'` | `trackAgentAction()` (deprecated) |
 
-All groups live in **one place**: `src/actions/groups/`.
+## Payload Types
 
-| 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) |
+Each group file in `src/actions/groups/` exports a **discriminated union payload type** that defines all valid event shapes for that group.
 
-The `actionGroup` value is visible in Databricks via `attributes.actionGroup`.
+| 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 |
 
-## Adding a New Action
-
-### To an existing group
+The combined `EventPayload` type (exported from `types.ts`) is a union of all these payload types.
 
-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:
+## Adding a New Action
 
-```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
-
-The `trackAgentAction` function uses generics to infer required attributes:
+## Backwards Compatibility
 
-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
+The following exports are **deprecated** but still available for existing consumers:
 
-Example:
+- `trackAgentAction()` — use `trackAgentEvent()` instead
+- `trackAgentActionError()` — use `trackAgentEvent()` instead  
+- Enum exports (e.g. `AgentEditingActions`, `AgentEvalActions`) — use string literals instead
+- `ActionAttributes` type — use `EventPayload` instead
 
-```typescript
-// If commonAttributes already includes agentId
-const { trackAgentAction } = useRovoAgentActionAnalytics({ agentId: '123' });
-
-// Only touchPoint is required since agentId was already provided
-trackAgentAction(AgentCommonActions.VIEW, { touchPoint: 'my-touchpoint' });
-```
+These will be removed in a future major version.

package/actions/evaluation/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@atlaskit/rovo-agent-analytics/actions/evaluation",
+  "main": "../../dist/cjs/actions/groups/evaluation.js",
+  "module": "../../dist/esm/actions/groups/evaluation.js",
+  "module:es2019": "../../dist/es2019/actions/groups/evaluation.js",
+  "sideEffects": [
+    "*.compiled.css"
+  ],
+  "types": "../../dist/types/actions/groups/evaluation.d.ts",
+  "typesVersions": {
+    ">=4.5 <5.9": {
+      "*": [
+        "../../dist/types-ts4.5/actions/groups/evaluation.d.ts"
+      ]
+    }
+  }
+}

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

@@ -14,13 +14,24 @@ exports.AddToolsPromptActions = exports.ACTION_GROUP = void 0;
  * regardless of whether the prompt fires from the create flow or a future publish flow.
  *
  * ## Adding a new action
- * 1. Add the action to the `AddToolsPromptActions` enum below with a data-portal link
- * 2. Register this group in ../registry.ts (if this is a new group file)
- *
+ * 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
+ *    (see other files in this directory for the template)
+ */
+
+/**
+ * Discriminated union payload type for add tools prompt events.
+ * Use with `trackAgentEvent()`.
  */
 
-/** The group name sent as `attributes.actionGroup` in analytics events */
+// ============================================================================
+// BACKWARDS COMPAT (deprecated): Keep enum and attributes for trackAgentAction() consumers
+// ============================================================================
+
+/** @deprecated Use AddToolsPromptEventPayload with trackAgentEvent() instead */
 var ACTION_GROUP = exports.ACTION_GROUP = 'addToolsPrompt';
+
+/** @deprecated Use AddToolsPromptEventPayload with trackAgentEvent() instead */
 var AddToolsPromptActions = exports.AddToolsPromptActions = /*#__PURE__*/function (AddToolsPromptActions) {
   /* Add tools prompt shown (agent has no tools) - https://data-portal.internal.atlassian.com/analytics/registry/98106 */
   AddToolsPromptActions["SHOWN"] = "addToolsPromptShown";

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

@@ -13,14 +13,24 @@ exports.AgentInteractionActions = exports.ACTION_GROUP = void 0;
  * 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
+ * 1. Add a new variant to the `AgentInteractionsEventPayload` union type below with a data-portal link
+ * 2. 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 */
+/**
+ * Discriminated union payload type for agent interaction events.
+ * Use with `trackAgentEvent()`.
+ */
+
+// ============================================================================
+// BACKWARDS COMPAT (deprecated): Keep enum and attributes for trackAgentAction() consumers
+// ============================================================================
+
+/** @deprecated Use AgentInteractionsEventPayload with trackAgentEvent() instead */
 var ACTION_GROUP = exports.ACTION_GROUP = 'agentInteractions';
+
+/** @deprecated Use AgentInteractionsEventPayload with trackAgentEvent() instead */
 var AgentInteractionActions = exports.AgentInteractionActions = /*#__PURE__*/function (AgentInteractionActions) {
   /* View agent clicked - https://data-portal.internal.atlassian.com/analytics/registry/97125 */
   AgentInteractionActions["VIEW"] = "view";
@@ -41,4 +51,5 @@ var AgentInteractionActions = exports.AgentInteractionActions = /*#__PURE__*/fun
   /* Unverify agent clicked - https://data-portal.internal.atlassian.com/analytics/registry/97135 */
   AgentInteractionActions["UNVERIFY"] = "unverify";
   return AgentInteractionActions;
-}({});
+}({});
+/** @deprecated Use AgentInteractionsEventPayload with trackAgentEvent() instead */

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

@@ -10,12 +10,24 @@ exports.CreateFlowActions = exports.ACTION_GROUP = void 0;
  * Create agent funnel steps — from clicking "Create agent" through to activation or discard,
  *
  * ## Adding a new action
- * 1. Add the action to the `CreateFlowActions` enum below with a data-portal link
- * 2. Register this group in ../registry.ts (if this is a new group file)
+ * 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)
  */
 
-/** The group name sent as `attributes.actionGroup` in analytics events */
+/**
+ * Discriminated union payload type for create flow events.
+ * Use with `trackAgentEvent()`.
+ */
+
+// ============================================================================
+// BACKWARDS COMPAT (deprecated): Keep enum and attributes for trackAgentAction() consumers
+// ============================================================================
+
+/** @deprecated Use CreateFlowEventPayload with trackAgentEvent() instead */
 var ACTION_GROUP = exports.ACTION_GROUP = 'createFlow';
+
+/** @deprecated Use CreateFlowEventPayload with trackAgentEvent() instead */
 var CreateFlowActions = exports.CreateFlowActions = /*#__PURE__*/function (CreateFlowActions) {
   /* Start create flow when user clicks on "Create agent" button - https://data-portal.internal.atlassian.com/analytics/registry/97089 */
   CreateFlowActions["START"] = "createFlowStart";

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

@@ -10,14 +10,24 @@ exports.AgentDebugActions = exports.ACTION_GROUP = void 0;
  * 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
+ * 1. Add a new variant to the `DebugEventPayload` 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)
  */
 
-/** The group name sent as `attributes.actionGroup` in analytics events */
+/**
+ * Discriminated union payload type for debug events.
+ * Use with `trackAgentEvent()`.
+ */
+
+// ============================================================================
+// BACKWARDS COMPAT (deprecated): Keep enum and attributes for trackAgentAction() consumers
+// ============================================================================
+
+/** @deprecated Use DebugEventPayload with trackAgentEvent() instead */
 var ACTION_GROUP = exports.ACTION_GROUP = 'debug';
+
+/** @deprecated Use DebugEventPayload with trackAgentEvent() instead */
 var AgentDebugActions = exports.AgentDebugActions = /*#__PURE__*/function (AgentDebugActions) {
   /* View debug modal - https://data-portal.internal.atlassian.com/analytics/registry/97183 */
   AgentDebugActions["VIEW"] = "debugView";
@@ -28,4 +38,5 @@ var AgentDebugActions = exports.AgentDebugActions = /*#__PURE__*/function (Agent
   /* Toggle skill info - https://data-portal.internal.atlassian.com/analytics/registry/97185 */
   AgentDebugActions["TOGGLE_SKILL_INFO"] = "debugToggleSkillInfo";
   return AgentDebugActions;
-}({});
+}({});
+/** @deprecated Use DebugEventPayload with trackAgentEvent() instead */

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

@@ -11,16 +11,22 @@ exports.AgentEditingActions = exports.ACTION_GROUP = void 0;
  * 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
+ * 1. Add a new variant to the `EditingEventPayload` union type below with a data-portal link
+ * 2. 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 */
+// ============================================================================
+// BACKWARDS COMPAT (deprecated): Keep enum and attributes for trackAgentAction() consumers
+// ============================================================================
+
+/** @deprecated Use EditingEventPayload with trackAgentEvent() instead */
 var ACTION_GROUP = exports.ACTION_GROUP = 'editing';
+
+/** @deprecated Use EditingEventPayload with trackAgentEvent() instead */
 var AgentEditingActions = exports.AgentEditingActions = /*#__PURE__*/function (AgentEditingActions) {
   /* Agent updated - https://data-portal.internal.atlassian.com/analytics/registry/97122 */
   AgentEditingActions["UPDATED"] = "updated";
   return AgentEditingActions;
-}({});
+}({});
+/** @deprecated Use EditingEventPayload with trackAgentEvent() instead */

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

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

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

@@ -11,14 +11,19 @@ exports.AgentToolActions = exports.ACTION_GROUP = void 0;
  * (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
+ * 1. Add a new variant to the `ToolsEventPayload` 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)
  */
 
-/** The group name sent as `attributes.actionGroup` in analytics events */
+// ============================================================================
+// BACKWARDS COMPAT (deprecated): Keep enum and attributes for trackAgentAction() consumers
+// ============================================================================
+
+/** @deprecated Use ToolsEventPayload with trackAgentEvent() instead */
 var ACTION_GROUP = exports.ACTION_GROUP = 'tools';
+
+/** @deprecated Use ToolsEventPayload with trackAgentEvent() instead */
 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";
@@ -29,4 +34,7 @@ var AgentToolActions = exports.AgentToolActions = /*#__PURE__*/function (AgentTo
   /* When tools execution result streaming fails https://data-portal.internal.atlassian.com/analytics/registry/97752 */
   AgentToolActions["TOOLS_EXECUTION_RESULT_ERROR"] = "toolsExecutionResultError";
   return AgentToolActions;
-}({});
+}({});
+/** @deprecated Use ToolsEventPayload with trackAgentEvent() instead */
+/** @deprecated Use ToolsEventPayload with trackAgentEvent() instead */
+/** @deprecated Use ToolsEventPayload with trackAgentEvent() instead */

package/dist/cjs/actions/index.js

@@ -5,15 +5,18 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.useRovoAgentActionAnalytics = exports.AgentDebugActions = exports.AgentCommonActions = 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
@@ -29,27 +32,54 @@ 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
   );
+
+  /**
+   * Simple tracking of just action + attributes only.
+   * Uses default actionSubject ('rovoAgent').
+   *
+   * @deprecated Use trackAgentEvent() with typed payloads instead
+   */
   var trackAgentAction = (0, _react.useCallback)(function (action, attributes) {
     fireAnalyticsEvent({
-      actionSubject: 'rovoAgent',
+      actionSubject: _registry.DefaultActionSubject,
       action: action,
-      attributes: _objectSpread(_objectSpread({}, attributes), {}, {
-        actionGroup: _registry.ACTION_TO_GROUP[action]
-      })
+      attributes: attributes
     });
   }, [fireAnalyticsEvent]);
+
+  /**
+   * 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]);
+
+  /**
+   * @deprecated Use trackAgentEvent() with typed payloads instead
+   */
   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
         }
@@ -58,6 +88,7 @@ var useRovoAgentActionAnalytics = exports.useRovoAgentActionAnalytics = function
   }, [fireAnalyticsEvent]);
   return {
     trackAgentAction: trackAgentAction,
+    trackAgentEvent: trackAgentEvent,
     trackAgentActionError: trackAgentActionError
   };
 };

package/dist/cjs/actions/registry.js

@@ -1,53 +1,26 @@
 "use strict";
 
-var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.ACTION_TO_GROUP = void 0;
-var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
-var _addToolsPrompt = require("./groups/add-tools-prompt");
-var _agentInteractions = require("./groups/agent-interactions");
-var _createFlow = require("./groups/create-flow");
-var _debug = require("./groups/debug");
-var _editing = require("./groups/editing");
-var _tools = require("./groups/tools");
-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; } /**
- * Action Registry
+exports.DefaultActionSubject = void 0;
+/**
+ * Action Registry (Backwards Compatibility)
  *
- * Single source of truth for ALL action groups across the library.
- * This file composes all groups into a type-safe registry and builds the
- * runtime mapping from action values to their group names, which gets
- * automatically attached as `attributes.actionGroup` in every fired event.
+ * This file contains deprecated exports for backwards compatibility
+ * with consumers using `trackAgentAction()`.
  *
- * Both `useRovoAgentActionAnalytics` and `useRovoAgentCreateAnalytics` hooks
- * use `ACTION_TO_GROUP` from this registry.
+ * For new code, use the payload types from each group file directly
+ * with `trackAgentEvent()`.
  *
- * ## Adding a new action group
- * 1. Create a new file in ./groups/ following the template of existing group files
- * 2. Import the group's ACTION_GROUP, action enum, and attribute type below
- * 3. If the group is used by the actions hook, add the attribute type to `ActionAttributes`
- * 4. Add the enum + group to `ACTION_TO_GROUP` using `mapActionsToGroup`
- */
-/**
- * Combined attribute map for action-hook groups (type-safe attributes).
- * Create-flow groups are excluded — they use a looser attribute type via the create hook.
+ * @deprecated The registry pattern is deprecated. Use EventPayload from types.ts instead.
  */
 
-/**
- * Helper to build a Record mapping each enum value to its group name.
- */
-var mapActionsToGroup = function mapActionsToGroup(actionEnum, group) {
-  return Object.fromEntries(Object.values(actionEnum).map(function (action) {
-    return [action, group];
-  }));
-};
+var DefaultActionSubject = exports.DefaultActionSubject = 'rovoAgent';
 
 /**
- * Runtime lookup: action value → group name.
- * Used by ALL analytics hooks to auto-inject `attributes.actionGroup`.
+ * Combined attribute map (union of all groups).
+ * Used by the backward-compatible `trackAgentAction` helper.
  *
- * When you add a new group, add it here too.
- */
-var ACTION_TO_GROUP = exports.ACTION_TO_GROUP = _objectSpread(_objectSpread(_objectSpread(_objectSpread(_objectSpread(_objectSpread({}, mapActionsToGroup(_agentInteractions.AgentInteractionActions, _agentInteractions.ACTION_GROUP)), mapActionsToGroup(_editing.AgentEditingActions, _editing.ACTION_GROUP)), mapActionsToGroup(_debug.AgentDebugActions, _debug.ACTION_GROUP)), mapActionsToGroup(_tools.AgentToolActions, _tools.ACTION_GROUP)), mapActionsToGroup(_createFlow.CreateFlowActions, _createFlow.ACTION_GROUP)), mapActionsToGroup(_addToolsPrompt.AddToolsPromptActions, _addToolsPrompt.ACTION_GROUP));
+ * @deprecated Use EventPayload with trackAgentEvent() instead
+ */