@atlaskit/rovo-agent-analytics 0.19.0 → 0.20.0

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

@@ -5,14 +5,19 @@
  * (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 */
 export var ACTION_GROUP = 'tools';
+
+/** @deprecated Use ToolsEventPayload with trackAgentEvent() instead */
 export var 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";
@@ -23,4 +28,10 @@ export var AgentToolActions = /*#__PURE__*/function (AgentToolActions) {
   /* 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/esm/actions/index.js

@@ -1,14 +1,17 @@
+import _objectWithoutProperties from "@babel/runtime/helpers/objectWithoutProperties";
 import _defineProperty from "@babel/runtime/helpers/defineProperty";
+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) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
 import { useCallback, useContext, useRef } from 'react';
 import { AnalyticsReactContext, useAnalyticsEvents } from '@atlaskit/analytics-next';
 import { ANALYTICS_CHANNEL } from '../common/constants';
+import { LIBRARY_ATTRIBUTE } from '../common/types';
 import { getAttributesFromContexts, getDefaultTrackEventConfig } from '../common/utils';
 import { AgentInteractionActions } from './groups/agent-interactions';
 import { AgentDebugActions as AgentDebugActionsEnum } from './groups/debug';
 import { AgentEditingActions } from './groups/editing';
-import { ACTION_TO_GROUP } from './registry';
+import { DefaultActionSubject } from './registry';
 
 // Backward-compatible aliases
 // TODO: migrate consumers to use group-specific imports, then remove
@@ -23,27 +26,54 @@ export var useRovoAgentActionAnalytics = function useRovoAgentActionAnalytics(co
     createAnalyticsEvent = _useAnalyticsEvents.createAnalyticsEvent;
   var commonAttributesRef = useRef(commonAttributes);
   var fireAnalyticsEvent = useCallback(function (event) {
-    var attributes = _objectSpread(_objectSpread(_objectSpread({}, getAttributesFromContexts(analyticsContext.getAtlaskitAnalyticsContext())), commonAttributesRef.current), event.attributes);
+    var attributes = _objectSpread(_objectSpread(_objectSpread({}, getAttributesFromContexts(analyticsContext.getAtlaskitAnalyticsContext())), commonAttributesRef.current), {}, {
+      library: LIBRARY_ATTRIBUTE
+    }, event.attributes);
     createAnalyticsEvent(_objectSpread(_objectSpread(_objectSpread({}, globalEventConfig), event), {}, {
       attributes: attributes
     })).fire(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 = useCallback(function (action, attributes) {
     fireAnalyticsEvent({
-      actionSubject: 'rovoAgent',
+      actionSubject: DefaultActionSubject,
       action: action,
-      attributes: _objectSpread(_objectSpread({}, attributes), {}, {
-        actionGroup: 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 = useCallback(function (payload) {
+    var action = payload.action,
+      actionSubject = payload.actionSubject,
+      attributes = payload.attributes,
+      eventProps = _objectWithoutProperties(payload, _excluded);
+    fireAnalyticsEvent(_objectSpread(_objectSpread({
+      actionSubject: actionSubject,
+      action: action
+    }, eventProps), {}, {
+      attributes: attributes
+    }));
+  }, [fireAnalyticsEvent]);
+
+  /**
+   * @deprecated Use trackAgentEvent() with typed payloads instead
+   */
   var trackAgentActionError = useCallback(function (action, error, attributes) {
     fireAnalyticsEvent({
       actionSubject: 'rovoAgentError',
       action: action,
       attributes: _objectSpread(_objectSpread({}, attributes), {}, {
-        actionGroup: ACTION_TO_GROUP[action],
         error: {
           message: error.message
         }
@@ -52,6 +82,7 @@ export var useRovoAgentActionAnalytics = function useRovoAgentActionAnalytics(co
   }, [fireAnalyticsEvent]);
   return {
     trackAgentAction: trackAgentAction,
+    trackAgentEvent: trackAgentEvent,
     trackAgentActionError: trackAgentActionError
   };
 };

package/dist/esm/actions/registry.js

@@ -1,48 +1,20 @@
-import _defineProperty from "@babel/runtime/helpers/defineProperty";
-function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
-function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
 /**
- * Action Registry
+ * 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`
+ * @deprecated The registry pattern is deprecated. Use EventPayload from types.ts instead.
  */
-import { AddToolsPromptActions, ACTION_GROUP as ADD_TOOLS_PROMPT_GROUP } from './groups/add-tools-prompt';
-import { AgentInteractionActions, ACTION_GROUP as AGENT_INTERACTIONS_GROUP } from './groups/agent-interactions';
-import { CreateFlowActions, ACTION_GROUP as CREATE_FLOW_GROUP } from './groups/create-flow';
-import { AgentDebugActions, ACTION_GROUP as DEBUG_GROUP } from './groups/debug';
-import { AgentEditingActions, ACTION_GROUP as EDITING_GROUP } from './groups/editing';
-import { AgentToolActions, ACTION_GROUP as TOOLS_GROUP } from './groups/tools';
 
-/**
- * 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.
- */
-
-/**
- * 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];
-  }));
-};
+export var 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.
- */
-export var ACTION_TO_GROUP = _objectSpread(_objectSpread(_objectSpread(_objectSpread(_objectSpread(_objectSpread({}, mapActionsToGroup(AgentInteractionActions, AGENT_INTERACTIONS_GROUP)), mapActionsToGroup(AgentEditingActions, EDITING_GROUP)), mapActionsToGroup(AgentDebugActions, DEBUG_GROUP)), mapActionsToGroup(AgentToolActions, TOOLS_GROUP)), mapActionsToGroup(CreateFlowActions, CREATE_FLOW_GROUP)), mapActionsToGroup(AddToolsPromptActions, ADD_TOOLS_PROMPT_GROUP));
+ * @deprecated Use EventPayload with trackAgentEvent() instead
+ */

package/dist/esm/common/types.js

@@ -0,0 +1,7 @@
+/** Common library attribute injected into all events */
+export var LIBRARY_ATTRIBUTE = 'agents-analytics';
+
+/**
+ * Union of all event payload types.
+ * Use with `trackAgentEvent()` for typed event tracking.
+ */

package/dist/esm/create/index.js

@@ -6,7 +6,7 @@ import { useCallback, useContext, useRef } from 'react';
 import { AnalyticsReactContext, useAnalyticsEvents } from '@atlaskit/analytics-next';
 import { AddToolsPromptActions } from '../actions/groups/add-tools-prompt';
 import { CreateFlowActions } from '../actions/groups/create-flow';
-import { ACTION_TO_GROUP } from '../actions/registry';
+import { DefaultActionSubject } from '../actions/registry';
 import { ANALYTICS_CHANNEL } from '../common/constants';
 import { useRovoAgentCSID } from '../common/csid';
 import { getAttributesFromContexts, getDefaultTrackEventConfig } from '../common/utils';
@@ -26,9 +26,7 @@ export var useRovoAgentCreateAnalytics = function useRovoAgentCreateAnalytics(co
   var commonAttributesRef = useRef(commonAttributes);
   var fireAnalyticsEvent = useCallback(function (event) {
     var referrer = typeof window !== 'undefined' ? window.document.referrer : 'unknown';
-    var action = event.action;
     var attributes = _objectSpread(_objectSpread(_objectSpread(_objectSpread({}, getAttributesFromContexts(analyticsContext.getAtlaskitAnalyticsContext())), commonAttributesRef.current), event.attributes), {}, {
-      actionGroup: ACTION_TO_GROUP[action],
       csid: csid,
       referrer: referrer
     });
@@ -44,7 +42,7 @@ export var useRovoAgentCreateAnalytics = function useRovoAgentCreateAnalytics(co
    */
   var trackCreateSession = useCallback(function (action, attributes) {
     fireAnalyticsEvent({
-      actionSubject: 'rovoAgent',
+      actionSubject: DefaultActionSubject,
       action: action,
       attributes: attributes
     });
@@ -55,7 +53,7 @@ export var useRovoAgentCreateAnalytics = function useRovoAgentCreateAnalytics(co
    */
   var trackCreateSessionStart = useCallback(function (attributes) {
     fireAnalyticsEvent({
-      actionSubject: 'rovoAgent',
+      actionSubject: DefaultActionSubject,
       action: CreateFlowActions.START,
       attributes: attributes
     });
@@ -63,7 +61,7 @@ export var useRovoAgentCreateAnalytics = function useRovoAgentCreateAnalytics(co
   }, [fireAnalyticsEvent, refreshCSID]);
   var trackCreateSessionError = useCallback(function (error, attributes) {
     fireAnalyticsEvent({
-      actionSubject: 'rovoAgent',
+      actionSubject: DefaultActionSubject,
       action: CreateFlowActions.ERROR,
       attributes: _objectSpread({
         error: {

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

@@ -8,12 +8,30 @@
  * 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 */
+export type AddToolsPromptEventPayload = {
+    actionSubject: 'rovoAgent';
+    action: 'addToolsPromptShown';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'addToolsPromptBrowse';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'addToolsPromptDismiss';
+    attributes: {};
+};
+/** @deprecated Use AddToolsPromptEventPayload with trackAgentEvent() instead */
 export declare const ACTION_GROUP: "addToolsPrompt";
+/** @deprecated Use AddToolsPromptEventPayload with trackAgentEvent() instead */
 export declare enum AddToolsPromptActions {
     SHOWN = "addToolsPromptShown",
     BROWSE = "addToolsPromptBrowse",

package/dist/types/actions/groups/agent-interactions.d.ts

@@ -7,14 +7,55 @@
  * 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)
  */
 import type { BaseAgentAnalyticsAttributes } from '../../common/types';
-/** The group name sent as `attributes.actionGroup` in analytics events */
+/**
+ * Discriminated union payload type for agent interaction events.
+ * Use with `trackAgentEvent()`.
+ */
+export type AgentInteractionsEventPayload = {
+    actionSubject: 'rovoAgent';
+    action: 'view';
+    attributes: BaseAgentAnalyticsAttributes;
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'edit';
+    attributes: BaseAgentAnalyticsAttributes;
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'copyLink';
+    attributes: BaseAgentAnalyticsAttributes;
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'delete';
+    attributes: BaseAgentAnalyticsAttributes;
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'duplicate';
+    attributes: BaseAgentAnalyticsAttributes;
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'star';
+    attributes: BaseAgentAnalyticsAttributes;
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'chat';
+    attributes: BaseAgentAnalyticsAttributes;
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'verify';
+    attributes: BaseAgentAnalyticsAttributes;
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'unverify';
+    attributes: BaseAgentAnalyticsAttributes;
+};
+/** @deprecated Use AgentInteractionsEventPayload with trackAgentEvent() instead */
 export declare const ACTION_GROUP: "agentInteractions";
+/** @deprecated Use AgentInteractionsEventPayload with trackAgentEvent() instead */
 export declare enum AgentInteractionActions {
     VIEW = "view",
     EDIT = "edit",
@@ -26,6 +67,7 @@ export declare enum AgentInteractionActions {
     VERIFY = "verify",
     UNVERIFY = "unverify"
 }
+/** @deprecated Use AgentInteractionsEventPayload with trackAgentEvent() instead */
 export type AgentInteractionAttributes = {
     [AgentInteractionActions.VIEW]: BaseAgentAnalyticsAttributes;
     [AgentInteractionActions.EDIT]: BaseAgentAnalyticsAttributes;

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

@@ -4,11 +4,54 @@
  * 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()`.
+ */
+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: {};
+};
+/** @deprecated Use CreateFlowEventPayload with trackAgentEvent() instead */
 export declare const ACTION_GROUP: "createFlow";
+/** @deprecated Use CreateFlowEventPayload with trackAgentEvent() instead */
 export declare enum CreateFlowActions {
     START = "createFlowStart",
     SKIP_NL = "createFlowSkipNL",

package/dist/types/actions/groups/debug.d.ts

@@ -4,13 +4,37 @@
  * 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()`.
+ */
+export type DebugEventPayload = {
+    actionSubject: 'rovoAgent';
+    action: 'debugView';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'debugCopyAll';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'debugCopy';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'debugToggleSkillInfo';
+    attributes: {
+        toolId: string;
+        isExpanded: boolean;
+    };
+};
+/** @deprecated Use DebugEventPayload with trackAgentEvent() instead */
 export declare const ACTION_GROUP: "debug";
+/** @deprecated Use DebugEventPayload with trackAgentEvent() instead */
 export declare enum AgentDebugActions {
     VIEW = "debugView",
     COPY_ALL = "debugCopyAll",
@@ -18,6 +42,7 @@ export declare enum AgentDebugActions {
     TOGGLE_SKILL_INFO = "debugToggleSkillInfo"
 }
 type EmptyAttributes = {};
+/** @deprecated Use DebugEventPayload with trackAgentEvent() instead */
 export type DebugActionAttributes = {
     [AgentDebugActions.COPY_ALL]: EmptyAttributes;
     [AgentDebugActions.COPY]: EmptyAttributes;

package/dist/types/actions/groups/editing.d.ts

@@ -5,17 +5,26 @@
  * 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)
  */
 import type { BaseAgentAnalyticsAttributes } from '../../common/types';
-/** The group name sent as `attributes.actionGroup` in analytics events */
+export type EditingEventPayload = {
+    actionSubject: 'rovoAgent';
+    action: 'updated';
+    attributes: BaseAgentAnalyticsAttributes & {
+        agentType: string;
+        field: string;
+    };
+};
+/** @deprecated Use EditingEventPayload with trackAgentEvent() instead */
 export declare const ACTION_GROUP: "editing";
+/** @deprecated Use EditingEventPayload with trackAgentEvent() instead */
 export declare enum AgentEditingActions {
     UPDATED = "updated"
 }
+/** @deprecated Use EditingEventPayload with trackAgentEvent() instead */
 export type EditingActionAttributes = {
     [AgentEditingActions.UPDATED]: BaseAgentAnalyticsAttributes & {
         agentType: string;

package/dist/types/actions/groups/evaluation.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Action Group: evaluation
+ *
+ * Batch evaluation events — dataset CRUD, job lifecycle, and validation UI events
+ * fired from the shared `agent-evaluation` package.
+ *
+ * ## Adding a new action
+ * 1. Add a new variant to the `EvaluationEventPayload` 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)
+ */
+type EvalAttributesBase = {
+    objectType?: string;
+    objectId?: string;
+    containerType?: string;
+    containerId?: string;
+    actionSubjectId?: string;
+};
+export type EvaluationEventPayload = ({
+    actionSubject: 'batchEvaluationDataset';
+    action: 'created';
+    attributes: {
+        totalQuestions: number;
+    };
+} & EvalAttributesBase) | ({
+    actionSubject: 'batchEvaluationJob';
+    action: 'created';
+    attributes: {
+        datasetSize: number;
+        isDraftAgent: boolean;
+        judgeMode: string | undefined;
+    };
+} & EvalAttributesBase) | ({
+    actionSubject: 'batchEvaluationDataset';
+    action: 'deleted';
+    attributes: {};
+} & EvalAttributesBase) | ({
+    actionSubject: 'batchEvaluationDatasetQuestion';
+    action: 'deleted';
+    attributes: {};
+} & EvalAttributesBase) | ({
+    actionSubject: 'evalResultsModal';
+    action: 'viewed';
+    attributes: {
+        trigger: 'row_action' | 'flag_action';
+    };
+} & EvalAttributesBase) | ({
+    actionSubject: 'batchEvaluationJob';
+    action: 'completed';
+    attributes: {
+        status: string | null;
+        durationMs: number | null;
+        datasetSize: number | null | undefined;
+    };
+} & EvalAttributesBase);
+export {};

package/dist/types/actions/groups/tools.d.ts

@@ -5,20 +5,48 @@
  * (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)
  */
 import type { BaseAgentAnalyticsAttributes } from '../../common/types';
-/** The group name sent as `attributes.actionGroup` in analytics events */
+type ToolsExecutionAttributesBase = BaseAgentAnalyticsAttributes & {
+    tools: {
+        toolId: string;
+        toolSource: string;
+        resolutionType: string;
+    }[];
+    singleInstrumentationId: string | undefined;
+};
+export type ToolsEventPayload = {
+    actionSubject: 'rovoAgent';
+    action: 'toolsExecutionConfirmed';
+    attributes: ToolsExecutionAttributesBase;
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'toolsExecutionStreamStopped';
+    attributes: ToolsExecutionAttributesBase;
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'toolsExecutionResultViewed';
+    attributes: ToolsExecutionAttributesBase & {
+        scenarioId: string | null | undefined;
+    };
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'toolsExecutionResultError';
+    attributes: ToolsExecutionAttributesBase;
+};
+/** @deprecated Use ToolsEventPayload with trackAgentEvent() instead */
 export declare const ACTION_GROUP: "tools";
+/** @deprecated Use ToolsEventPayload with trackAgentEvent() instead */
 export declare enum AgentToolActions {
     TOOLS_EXECUTION_CONFIRMED = "toolsExecutionConfirmed",
     TOOLS_EXECUTION_STREAM_STOPPED = "toolsExecutionStreamStopped",
     TOOLS_EXECUTION_RESULT_VIEWED = "toolsExecutionResultViewed",
     TOOLS_EXECUTION_RESULT_ERROR = "toolsExecutionResultError"
 }
+/** @deprecated Use ToolsEventPayload with trackAgentEvent() instead */
 export type ToolsExecutionAttributes = BaseAgentAnalyticsAttributes & {
     tools: {
         toolId: string;
@@ -27,12 +55,15 @@ export type ToolsExecutionAttributes = BaseAgentAnalyticsAttributes & {
     }[];
     singleInstrumentationId: string | undefined;
 };
+/** @deprecated Use ToolsEventPayload with trackAgentEvent() instead */
 export type ToolsExecutionResultAttributes = ToolsExecutionAttributes & {
     scenarioId: string | null | undefined;
 };
+/** @deprecated Use ToolsEventPayload with trackAgentEvent() instead */
 export type ToolsActionAttributes = {
     [AgentToolActions.TOOLS_EXECUTION_CONFIRMED]: ToolsExecutionAttributes;
     [AgentToolActions.TOOLS_EXECUTION_STREAM_STOPPED]: ToolsExecutionAttributes;
     [AgentToolActions.TOOLS_EXECUTION_RESULT_VIEWED]: ToolsExecutionResultAttributes;
     [AgentToolActions.TOOLS_EXECUTION_RESULT_ERROR]: ToolsExecutionAttributes;
 };
+export {};

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

@@ -1,4 +1,4 @@
-import type { RemainingRequired } from '../common/types';
+import { type EventPayload, type RemainingRequired } from '../common/types';
 import { AgentInteractionActions } from './groups/agent-interactions';
 import { AgentDebugActions as AgentDebugActionsEnum } from './groups/debug';
 import { AgentEditingActions } from './groups/editing';
@@ -18,5 +18,6 @@ export declare const AgentCommonActions: {
 export declare const AgentDebugActions: typeof AgentDebugActionsEnum;
 export declare const useRovoAgentActionAnalytics: <T extends {}>(commonAttributes: T) => {
     trackAgentAction: <A extends keyof ActionAttributes>(action: A, attributes: RemainingRequired<ActionAttributes[A], T>) => void;
+    trackAgentEvent: (payload: EventPayload) => void;
     trackAgentActionError: <A extends keyof ActionAttributes>(action: A, error: Error, attributes?: RemainingRequired<ActionAttributes[A], T>) => void;
 };

package/dist/types/actions/registry.d.ts

@@ -1,16 +1,23 @@
+/**
+ * Action Registry (Backwards Compatibility)
+ *
+ * This file contains deprecated exports for backwards compatibility
+ * with consumers using `trackAgentAction()`.
+ *
+ * For new code, use the payload types from each group file directly
+ * with `trackAgentEvent()`.
+ *
+ * @deprecated The registry pattern is deprecated. Use EventPayload from types.ts instead.
+ */
 import { type AgentInteractionAttributes } from './groups/agent-interactions';
 import { type DebugActionAttributes } from './groups/debug';
 import { type EditingActionAttributes } from './groups/editing';
 import { type ToolsActionAttributes } from './groups/tools';
+export declare const DefaultActionSubject = "rovoAgent";
 /**
- * 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.
- */
-export type ActionAttributes = AgentInteractionAttributes & EditingActionAttributes & DebugActionAttributes & ToolsActionAttributes;
-/**
- * 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.
+ * @deprecated Use EventPayload with trackAgentEvent() instead
  */
-export declare const ACTION_TO_GROUP: Record<string, string>;
+export type ActionAttributes = AgentInteractionAttributes & EditingActionAttributes & DebugActionAttributes & ToolsActionAttributes;