@atlaskit/rovo-agent-analytics 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @atlaskit/rovo-agent-analytics
 
+## 1.4.0
+
+### Minor Changes
+
+- [`04fe400264167`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/04fe400264167) -
+  RAGE-3507: Add versioned-agent analytics foundation
+
+  ### `@atlaskit/rovo-agent-analytics`
+  - Added `VersionedAgentAttributes` type (`agentIsPublished`, `agentVersionNumber`)
+  - Added new `createFlow` event payloads:
+    - `createAgentRecord` — fires when BE `agentStudio_createAgent` mutation succeeds
+      (post-versioning, replaces `createFlowActivate`); minimal payload (registry/101157)
+    - `published` — fires on every agent version publish; carries rich agent attrs + versioning
+      envelope (registry/101158)
+    - `createLandInAgentLandingWithSA` — fires when user lands on agents landing with SA modal
+      auto-opened; v2/SA only (registry/99780)
+  - Extended `editing.ts` `updated` event to carry `agentIsPublished` from mutation response
+  - Updated `createFlow` JSDoc funnel table to v1 / v1+versioning / v2 / v2+versioning columns
+
+  ### `@atlassian/agent-studio`
+  - Three dedicated analytics helpers in `services/create-agent/utils.tsx`:
+    - `getAgentLegacyCreateActivateAnalytics` — rich write-input shape for legacy
+      `createFlowActivate` (deletion path RAGE-3459)
+    - `getAgentCreateAnalytics` — minimal payload for `createAgentRecord` (`agentId`, `source`,
+      `agentType`, `agentIsPublished`)
+    - `getAgentPublishAnalytics` — fragment-read shape for `published`; computes `agentToolCount`,
+      `agentMcpServerCount`, `agentToolsList` from agent-level tools and per-scenario `toolCount`,
+      `toolsList`, `mcpServerCount`, `mcpToolCount`
+  - `useCreateAgent`: new required `hasVersionCapability` param gates either-or between
+    `createAgentRecord` and `createFlowActivate`
+  - Publish-button: fires `published` event with rich attrs; fragment extended with `definitionId` +
+    `definitionSource` on all tool fields
+  - `update-agent-details` mutation: fires `updated` event with `agentIsPublished` from response
+    (gated on `rovo_agent_versioning_enabled` FG via `@include`)
+  - Landing: fires `createLandInAgentLandingWithSA` when SA modal auto-opens
+
+  ### `@atlassian/studio-solution-architect-ui-components`
+  - SA Manual Create Agent button: fires `createAgentRecord` analytics on successful create (gated
+    on `rovo-agents-universal-analytics` FG)
+
 ## 1.3.0
 
 ### Minor Changes

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

@@ -1 +1,5 @@
-"use strict";
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});

package/dist/cjs/common/types.js

@@ -4,6 +4,23 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.LIBRARY_ATTRIBUTE = void 0;
+/**
+ * Common attributes for events scoped to a single versioned agent.
+ *
+ * Extends `BaseAgentAnalyticsAttributes` with versioning state so DS can
+ * distinguish first-publish vs republish, edits-on-draft vs edits-after-publish,
+ * etc. without needing a separate event per state.
+ *
+ * - `agentIsPublished` — sourced from the BE `AgentStudioAssistant.isPublished`
+ *   field. Whether the agent has at least one published version.
+ * - `agentVersionNumber` — the version number the event relates to (e.g. the
+ *   version being edited or published). Sourced from the BE
+ *   `AgentStudioAssistant.version.versionNumber` field.
+ *
+ * Apply to every event scoped to a single agent (CRUD, publish, AND usage events).
+ * Pre-mutation create-flow events stay attribute-free — no `agentId` exists yet.
+ */
+
 /** Common library attribute injected into all events */
 var LIBRARY_ATTRIBUTE = exports.LIBRARY_ATTRIBUTE = 'agents-analytics';
 

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

@@ -0,0 +1 @@
+export {};

package/dist/es2019/common/types.js

@@ -1,3 +1,20 @@
+/**
+ * Common attributes for events scoped to a single versioned agent.
+ *
+ * Extends `BaseAgentAnalyticsAttributes` with versioning state so DS can
+ * distinguish first-publish vs republish, edits-on-draft vs edits-after-publish,
+ * etc. without needing a separate event per state.
+ *
+ * - `agentIsPublished` — sourced from the BE `AgentStudioAssistant.isPublished`
+ *   field. Whether the agent has at least one published version.
+ * - `agentVersionNumber` — the version number the event relates to (e.g. the
+ *   version being edited or published). Sourced from the BE
+ *   `AgentStudioAssistant.version.versionNumber` field.
+ *
+ * Apply to every event scoped to a single agent (CRUD, publish, AND usage events).
+ * Pre-mutation create-flow events stay attribute-free — no `agentId` exists yet.
+ */
+
 /** Common library attribute injected into all events */
 export const LIBRARY_ATTRIBUTE = 'agents-analytics';
 

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

@@ -0,0 +1 @@
+export {};

package/dist/esm/common/types.js

@@ -1,3 +1,20 @@
+/**
+ * Common attributes for events scoped to a single versioned agent.
+ *
+ * Extends `BaseAgentAnalyticsAttributes` with versioning state so DS can
+ * distinguish first-publish vs republish, edits-on-draft vs edits-after-publish,
+ * etc. without needing a separate event per state.
+ *
+ * - `agentIsPublished` — sourced from the BE `AgentStudioAssistant.isPublished`
+ *   field. Whether the agent has at least one published version.
+ * - `agentVersionNumber` — the version number the event relates to (e.g. the
+ *   version being edited or published). Sourced from the BE
+ *   `AgentStudioAssistant.version.versionNumber` field.
+ *
+ * Apply to every event scoped to a single agent (CRUD, publish, AND usage events).
+ * Pre-mutation create-flow events stay attribute-free — no `agentId` exists yet.
+ */
+
 /** Common library attribute injected into all events */
 export var LIBRARY_ATTRIBUTE = 'agents-analytics';
 

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

@@ -1,17 +1,33 @@
 /**
  * Action Group: createFlow
  *
- * Create agent funnel steps — from clicking "Create agent" through to activation or discard.
+ * Create agent funnel steps — from clicking "Create agent" through to activation /
+ * publish.
+ *
+ * See LDR for the full reasoning behind the post-versioning funnel:
+ * https://hello.atlassian.net/wiki/spaces/778dcad2d8a34a91b8ebe71c18678e0c/pages/6851055849
  *
  * ## 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               |
+ * | Step                                | v1 / NL (today)         | v1 / NL + versioning            | v2 / SA (today)         | v2 / SA + versioning            |
+ * |-------------------------------------|-------------------------|---------------------------------|-------------------------|---------------------------------|
+ * | Intent to create                    | createFlowStart         | createFlowStart                 | saDraft                 | saDraft                         |
+ * | Land in NL page                     | createLandInStudio      | createLandInStudio              | —                       | —                               |
+ * | NL interaction                      | createFlowReviewNL /    | createFlowReviewNL /            | —                       | —                               |
+ * |                                     | createFlowSkipNL        | createFlowSkipNL                |                         |                                 |
+ * | Land on landing w/ SA modal         | —                       | —                               | createLandIn-           | createLandIn-                   |
+ * |                                     |                         |                                 | AgentLandingWithSA      | AgentLandingWithSA              |
+ * | Land in configure screen            | createLandInConfigure   | dropped (no FE draft anymore;   | createLandInConfigure   | createLandInConfigure           |
+ * |                                     |                         | createAgentRecord replaces it)  |                         |                                 |
+ * | Discard                             | createDiscard           | dropped (no FE draft)           | —                       | —                               |
+ * | Agent record created (BE mutation)  | createFlowActivate      | createAgentRecord (NEW) +       | createFlowActivate      | createFlowActivate              |
+ * |                                     |                         | createFlowActivate (kept until  |                         | (SA still on FE drafts pre-     |
+ * |                                     |                         | rollout — RAGE-3459)            |                         | migration)                      |
+ * | Published                           | —                       | published (NEW)                 | —                       | ❓ owned by SA team              |
+ * | Generic error                       | createFlowError         | createFlowError                 | createFlowError         | createFlowError                 |
+ *
+ * Funnel completion (first publish) is derived from `published` events with
+ * `agentIsPublished === false` in the attributes (i.e. the pre-mutation state).
  *
  * ## CSID (Create Session ID)
  *
@@ -19,11 +35,17 @@
  * - `trackCreateSessionStart()` fires `createFlowStart` with the current CSID
  * - `trackCreateSession()` uses the existing CSID (for all other steps including `saDraft`)
  *
+ * With versioning the user can leave and come back days later to keep editing,
+ * so the in-memory linear "session" assumption breaks. Post-mutation events
+ * carry `agentId` (via `VersionedAgentAttributes`) which can be used as the
+ * stable correlation key across sessions. See LDR for the full discussion.
+ *
  * ## 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)
  */
+import type { VersionedAgentAttributes } from '../../common/types';
 /**
  * Discriminated union payload type for create flow events.
  * Use with `trackAgentEvent()`.
@@ -72,4 +94,16 @@ export type CreateFlowEventPayload = {
     actionSubject: 'rovoAgent';
     action: 'createSubpathRedirect';
     attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'createLandInAgentLandingWithSA';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'createAgentRecord';
+    attributes: VersionedAgentAttributes & Record<string, unknown>;
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'published';
+    attributes: VersionedAgentAttributes & Record<string, unknown>;
 };

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

@@ -9,11 +9,11 @@
  * 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';
+import type { VersionedAgentAttributes } from '../../common/types';
 export type EditingEventPayload = {
     actionSubject: 'rovoAgent';
     action: 'updated';
-    attributes: BaseAgentAnalyticsAttributes & {
+    attributes: VersionedAgentAttributes & {
         agentType: string;
         field: string;
     };

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

@@ -9,6 +9,26 @@ export type BaseAgentAnalyticsAttributes = {
     touchPoint?: string;
     agentId?: string;
 };
+/**
+ * Common attributes for events scoped to a single versioned agent.
+ *
+ * Extends `BaseAgentAnalyticsAttributes` with versioning state so DS can
+ * distinguish first-publish vs republish, edits-on-draft vs edits-after-publish,
+ * etc. without needing a separate event per state.
+ *
+ * - `agentIsPublished` — sourced from the BE `AgentStudioAssistant.isPublished`
+ *   field. Whether the agent has at least one published version.
+ * - `agentVersionNumber` — the version number the event relates to (e.g. the
+ *   version being edited or published). Sourced from the BE
+ *   `AgentStudioAssistant.version.versionNumber` field.
+ *
+ * Apply to every event scoped to a single agent (CRUD, publish, AND usage events).
+ * Pre-mutation create-flow events stay attribute-free — no `agentId` exists yet.
+ */
+export type VersionedAgentAttributes = BaseAgentAnalyticsAttributes & {
+    agentIsPublished?: boolean | null;
+    agentVersionNumber?: number | null;
+};
 /** Common library attribute injected into all events */
 export declare const LIBRARY_ATTRIBUTE: "agents-analytics";
 /**

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

@@ -1,17 +1,33 @@
 /**
  * Action Group: createFlow
  *
- * Create agent funnel steps — from clicking "Create agent" through to activation or discard.
+ * Create agent funnel steps — from clicking "Create agent" through to activation /
+ * publish.
+ *
+ * See LDR for the full reasoning behind the post-versioning funnel:
+ * https://hello.atlassian.net/wiki/spaces/778dcad2d8a34a91b8ebe71c18678e0c/pages/6851055849
  *
  * ## 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               |
+ * | Step                                | v1 / NL (today)         | v1 / NL + versioning            | v2 / SA (today)         | v2 / SA + versioning            |
+ * |-------------------------------------|-------------------------|---------------------------------|-------------------------|---------------------------------|
+ * | Intent to create                    | createFlowStart         | createFlowStart                 | saDraft                 | saDraft                         |
+ * | Land in NL page                     | createLandInStudio      | createLandInStudio              | —                       | —                               |
+ * | NL interaction                      | createFlowReviewNL /    | createFlowReviewNL /            | —                       | —                               |
+ * |                                     | createFlowSkipNL        | createFlowSkipNL                |                         |                                 |
+ * | Land on landing w/ SA modal         | —                       | —                               | createLandIn-           | createLandIn-                   |
+ * |                                     |                         |                                 | AgentLandingWithSA      | AgentLandingWithSA              |
+ * | Land in configure screen            | createLandInConfigure   | dropped (no FE draft anymore;   | createLandInConfigure   | createLandInConfigure           |
+ * |                                     |                         | createAgentRecord replaces it)  |                         |                                 |
+ * | Discard                             | createDiscard           | dropped (no FE draft)           | —                       | —                               |
+ * | Agent record created (BE mutation)  | createFlowActivate      | createAgentRecord (NEW) +       | createFlowActivate      | createFlowActivate              |
+ * |                                     |                         | createFlowActivate (kept until  |                         | (SA still on FE drafts pre-     |
+ * |                                     |                         | rollout — RAGE-3459)            |                         | migration)                      |
+ * | Published                           | —                       | published (NEW)                 | —                       | ❓ owned by SA team              |
+ * | Generic error                       | createFlowError         | createFlowError                 | createFlowError         | createFlowError                 |
+ *
+ * Funnel completion (first publish) is derived from `published` events with
+ * `agentIsPublished === false` in the attributes (i.e. the pre-mutation state).
  *
  * ## CSID (Create Session ID)
  *
@@ -19,11 +35,17 @@
  * - `trackCreateSessionStart()` fires `createFlowStart` with the current CSID
  * - `trackCreateSession()` uses the existing CSID (for all other steps including `saDraft`)
  *
+ * With versioning the user can leave and come back days later to keep editing,
+ * so the in-memory linear "session" assumption breaks. Post-mutation events
+ * carry `agentId` (via `VersionedAgentAttributes`) which can be used as the
+ * stable correlation key across sessions. See LDR for the full discussion.
+ *
  * ## 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)
  */
+import type { VersionedAgentAttributes } from '../../common/types';
 /**
  * Discriminated union payload type for create flow events.
  * Use with `trackAgentEvent()`.
@@ -72,4 +94,16 @@ export type CreateFlowEventPayload = {
     actionSubject: 'rovoAgent';
     action: 'createSubpathRedirect';
     attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'createLandInAgentLandingWithSA';
+    attributes: {};
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'createAgentRecord';
+    attributes: VersionedAgentAttributes & Record<string, unknown>;
+} | {
+    actionSubject: 'rovoAgent';
+    action: 'published';
+    attributes: VersionedAgentAttributes & Record<string, unknown>;
 };

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

@@ -9,11 +9,11 @@
  * 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';
+import type { VersionedAgentAttributes } from '../../common/types';
 export type EditingEventPayload = {
     actionSubject: 'rovoAgent';
     action: 'updated';
-    attributes: BaseAgentAnalyticsAttributes & {
+    attributes: VersionedAgentAttributes & {
         agentType: string;
         field: string;
     };

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

@@ -9,6 +9,26 @@ export type BaseAgentAnalyticsAttributes = {
     touchPoint?: string;
     agentId?: string;
 };
+/**
+ * Common attributes for events scoped to a single versioned agent.
+ *
+ * Extends `BaseAgentAnalyticsAttributes` with versioning state so DS can
+ * distinguish first-publish vs republish, edits-on-draft vs edits-after-publish,
+ * etc. without needing a separate event per state.
+ *
+ * - `agentIsPublished` — sourced from the BE `AgentStudioAssistant.isPublished`
+ *   field. Whether the agent has at least one published version.
+ * - `agentVersionNumber` — the version number the event relates to (e.g. the
+ *   version being edited or published). Sourced from the BE
+ *   `AgentStudioAssistant.version.versionNumber` field.
+ *
+ * Apply to every event scoped to a single agent (CRUD, publish, AND usage events).
+ * Pre-mutation create-flow events stay attribute-free — no `agentId` exists yet.
+ */
+export type VersionedAgentAttributes = BaseAgentAnalyticsAttributes & {
+    agentIsPublished?: boolean | null;
+    agentVersionNumber?: number | null;
+};
 /** Common library attribute injected into all events */
 export declare const LIBRARY_ATTRIBUTE: "agents-analytics";
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/rovo-agent-analytics",
-	"version": "1.3.0",
+	"version": "1.4.0",
 	"description": "Rovo Agents analytics",
 	"repository": "https://bitbucket.org/atlassian/atlassian-frontend-monorepo",
 	"atlassian": {