Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
feat(cli): stamp telemetry with journey_stage + cli_channel; tag installer origin
Kshitij Jhunjhunwala5254e9075192
diff --git a/install.sh b/install.shindex 6a2488de5..fbd6233ab 100755--- a/install.sh+++ b/install.sh@@ -310,7 +310,7 @@ success "Composio CLI was installed successfully to $Bold_Green$(tildify "$exe")echoinstall_err=$(mktemp)-if COMPOSIO_INSTALL_DIR="$COMPOSIO_INSTALL_DIR" "$exe" install 2>"$install_err"; then+if COMPOSIO_INSTALL_DIR="$COMPOSIO_INSTALL_DIR" COMPOSIO_CLI_INVOCATION_ORIGIN=installer "$exe" install 2>"$install_err"; thencat "$install_err" >&2 # Show CLI's TerminalUI output on successelseinfo "Setting up shell integration..."diff --git a/ts/packages/cli/CHANGELOG.md b/ts/packages/cli/CHANGELOG.mdindex e8a938bcf..06da0dc36 100644--- a/ts/packages/cli/CHANGELOG.md+++ b/ts/packages/cli/CHANGELOG.md@@ -11,6 +11,7 @@### Minor Changes- Telemetry now delivers directly to PostHog, so pre-login `install`/`setup` events are captured. Opt-outs are unchanged.+- Telemetry events now carry `journey_stage` (install/setup/login/connect/execute/other) and `cli_channel` (stable/beta) properties, and `install.sh` marks its `composio install` run with `invocation_origin: installer` so script installs are distinguishable from manual ones. npm and Homebrew installs do not run `install.sh`, so they emit no install-stage events.- a0bef5d: Bump `@composio/client` to `0.1.0-alpha.74`.- 025a657: Drop CommonJS entrypoints and publish the TypeScript SDK packages as ESM-only packages. This is a breaking change within the existing 0.x release line: consumers must use Node.js 22.22.3 or newer. CommonJS callers can only rely on Node's native `require(esm)` interop, and the SDK no longer ships custom CommonJS compatibility machinery or `.cjs` artifacts.diff --git a/ts/packages/cli/src/analytics/events.ts b/ts/packages/cli/src/analytics/events.tsindex 7bf73c077..df0807270 100644--- a/ts/packages/cli/src/analytics/events.ts+++ b/ts/packages/cli/src/analytics/events.ts@@ -1,4 +1,6 @@import type { CliCommandTelemetryContext, TrackEvent } from './types';+import { APP_VERSION } from 'src/constants';+import { inferSkillReleaseChannel } from 'src/effects/install-skill';import { ToolInputValidationError } from 'src/services/tool-input-validation';import { toolkitFromToolSlug } from 'src/utils/toolkit-from-tool-slug';@@ -44,6 +46,75 @@ export const CLI_ANALYTICS_EVENTS = {CLI_TOOL_INVOCATION_FAILED: 'CLI_TOOL_INVOCATION_FAILED',} as const;+type CliAnalyticsEventName = (typeof CLI_ANALYTICS_EVENTS)[keyof typeof CLI_ANALYTICS_EVENTS];++// Contract with the downstream metrics flow page: stage values group the+// adoption funnel, so renaming or removing one is a breaking change there.+export const CLI_JOURNEY_STAGES = [+ 'install',+ 'setup',+ 'login',+ 'connect',+ 'execute',+ 'other',+] as const;++export type CliJourneyStage = (typeof CLI_JOURNEY_STAGES)[number];++export const CLI_EVENT_JOURNEY_STAGES = {+ CLI_COMMAND_INVOKED: 'other',+ CLI_COMMAND_SUCCEEDED: 'other',+ CLI_COMMAND_FAILED: 'other',+ CLI_EXECUTE_INVOKED: 'execute',+ CLI_EXECUTE_SUCCEEDED: 'execute',+ CLI_EXECUTE_FAILED: 'execute',+ CLI_SEARCH_INVOKED: 'other',+ CLI_SEARCH_SUCCEEDED: 'other',+ CLI_SEARCH_FAILED: 'other',+ CLI_LINK_INVOKED: 'connect',+ CLI_LINK_SUCCEEDED: 'connect',+ CLI_LINK_FAILED: 'connect',+ CLI_LOGIN_INVOKED: 'login',+ CLI_LOGIN_SUCCEEDED: 'login',+ CLI_LOGIN_FAILED: 'login',+ CLI_LOGOUT_INVOKED: 'other',+ CLI_LOGOUT_SUCCEEDED: 'other',+ CLI_LOGOUT_FAILED: 'other',+ CLI_PROXY_INVOKED: 'other',+ CLI_PROXY_SUCCEEDED: 'other',+ CLI_PROXY_FAILED: 'other',+ CLI_RUN_INVOKED: 'other',+ CLI_RUN_SUCCEEDED: 'other',+ CLI_RUN_FAILED: 'other',+ CLI_INSTALL_INVOKED: 'install',+ CLI_INSTALL_SUCCEEDED: 'install',+ CLI_INSTALL_FAILED: 'install',+ CLI_SETUP_INVOKED: 'setup',+ CLI_SETUP_SUCCEEDED: 'setup',+ CLI_SETUP_FAILED: 'setup',+ CLI_SETUP_HOST_DETECTED: 'setup',+ CLI_SETUP_CANCELLED: 'setup',+ CLI_SETUP_SKIPPED: 'setup',+ CLI_PLUGIN_SETUP_SUCCEEDED: 'setup',+ CLI_PLUGIN_SETUP_FAILED: 'setup',+ CLI_PLUGIN_UNINSTALL_SUCCEEDED: 'setup',+ CLI_TOOL_INVOCATION_VALIDATION_FAILED: 'execute',+ CLI_TOOL_INVOCATION_TOOL_NOT_FOUND: 'execute',+ CLI_TOOL_INVOCATION_FAILED: 'execute',+} as const satisfies Record<CliAnalyticsEventName, CliJourneyStage>;++const buildEvent = (+ name: CliAnalyticsEventName,+ properties: Record<string, unknown>+): TrackEvent => ({+ name,+ properties: {+ ...properties,+ journey_stage: CLI_EVENT_JOURNEY_STAGES[name],+ cli_channel: inferSkillReleaseChannel(APP_VERSION),+ },+});+const KNOWN_COMMAND_TOKENS = new Set(['version','upgrade',@@ -400,9 +471,8 @@ export const createCliCommandTelemetryContext = (: undefined,});-const getCliCommandInvokedEvent = (context: CliCommandTelemetryContext): TrackEvent => ({- name: CLI_ANALYTICS_EVENTS.CLI_COMMAND_INVOKED,- properties: {+const getCliCommandInvokedEvent = (context: CliCommandTelemetryContext): TrackEvent =>+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_COMMAND_INVOKED, {source: 'cli',invocation_origin: getInvocationOrigin(),cli_version: context.cliVersion,@@ -411,27 +481,23 @@ const getCliCommandInvokedEvent = (context: CliCommandTelemetryContext): TrackEvarg_count: Math.max(0, context.argv.length - 2),stdout_is_tty: context.stdoutIsTTY,stderr_is_tty: context.stderrIsTTY,- },-});+ });-const getCliCommandSucceededEvent = (context: CliCommandTelemetryContext): TrackEvent => ({- name: CLI_ANALYTICS_EVENTS.CLI_COMMAND_SUCCEEDED,- properties: {+const getCliCommandSucceededEvent = (context: CliCommandTelemetryContext): TrackEvent =>+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_COMMAND_SUCCEEDED, {source: 'cli',invocation_origin: getInvocationOrigin(),cli_version: context.cliVersion,command_path: context.commandPath,duration_ms: Date.now() - context.startedAt,flag_names: context.flagNames,- },-});+ });const getCliCommandFailedEvent = (context: CliCommandTelemetryContext,error: unknown-): TrackEvent => ({- name: CLI_ANALYTICS_EVENTS.CLI_COMMAND_FAILED,- properties: {+): TrackEvent =>+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_COMMAND_FAILED, {source: 'cli',invocation_origin: getInvocationOrigin(),cli_version: context.cliVersion,@@ -440,14 +506,13 @@ const getCliCommandFailedEvent = (flag_names: context.flagNames,error_name: errorNameOf(error),error_message: errorMessageOf(error),- },-});+ });type SpecialLifecycleFamily = {readonly match: (commandPath: string) => boolean;- readonly invokedEventName: string;- readonly succeededEventName: string;- readonly failedEventName: string;+ readonly invokedEventName: CliAnalyticsEventName;+ readonly succeededEventName: CliAnalyticsEventName;+ readonly failedEventName: CliAnalyticsEventName;readonly getProperties: (context: CliCommandTelemetryContext) => Record<string, unknown>;};@@ -527,10 +592,7 @@ export const getPrimaryLifecycleInvokedEvent = (if (!family || isGenericOnlyCommand(context.commandPath)) {return getCliCommandInvokedEvent(context);}- return {- name: family.invokedEventName,- properties: family.getProperties(context),- };+ return buildEvent(family.invokedEventName, family.getProperties(context));};export const getPrimaryLifecycleSucceededEvent = (@@ -540,10 +602,7 @@ export const getPrimaryLifecycleSucceededEvent = (if (!family || isGenericOnlyCommand(context.commandPath)) {return getCliCommandSucceededEvent(context);}- return {- name: family.succeededEventName,- properties: family.getProperties(context),- };+ return buildEvent(family.succeededEventName, family.getProperties(context));};export const getPrimaryLifecycleFailedEvent = (@@ -554,14 +613,11 @@ export const getPrimaryLifecycleFailedEvent = (if (!family || isGenericOnlyCommand(context.commandPath)) {return getCliCommandFailedEvent(context, error);}- return {- name: family.failedEventName,- properties: {- ...family.getProperties(context),- error_name: errorNameOf(error),- error_message: errorMessageOf(error),- },- };+ return buildEvent(family.failedEventName, {+ ...family.getProperties(context),+ error_name: errorNameOf(error),+ error_message: errorMessageOf(error),+ });};export const getPluginLifecycleSucceededEvent = (params: {@@ -569,21 +625,21 @@ export const getPluginLifecycleSucceededEvent = (params: {readonly target: 'claude' | 'codex';readonly action: 'installed' | 'enabled' | 'configured' | 'uninstalled';readonly cliVersion: string;-}): TrackEvent => ({- name:+}): TrackEvent =>+ buildEvent(params.operation === 'uninstall'? CLI_ANALYTICS_EVENTS.CLI_PLUGIN_UNINSTALL_SUCCEEDED: CLI_ANALYTICS_EVENTS.CLI_PLUGIN_SETUP_SUCCEEDED,- properties: {- source: 'cli',- invocation_origin: getInvocationOrigin(),- cli_version: params.cliVersion,- command_path: 'setup',- operation: params.operation,- agent_host: params.target,- action: params.action,- },-});+ {+ source: 'cli',+ invocation_origin: getInvocationOrigin(),+ cli_version: params.cliVersion,+ command_path: 'setup',+ operation: params.operation,+ agent_host: params.target,+ action: params.action,+ }+ );export const getPluginLifecycleFailedEvent = (params: {readonly operation: 'setup' | 'uninstall';@@ -591,9 +647,8 @@ export const getPluginLifecycleFailedEvent = (params: {readonly phase: 'install' | 'uninstall';readonly error: unknown;readonly cliVersion: string;-}): TrackEvent => ({- name: CLI_ANALYTICS_EVENTS.CLI_PLUGIN_SETUP_FAILED,- properties: {+}): TrackEvent =>+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_PLUGIN_SETUP_FAILED, {source: 'cli',invocation_origin: getInvocationOrigin(),cli_version: params.cliVersion,@@ -603,8 +658,7 @@ export const getPluginLifecycleFailedEvent = (params: {phase: params.phase,error_name: errorNameOf(params.error),error_message: errorMessageOf(params.error),- },-});+ });export const getSetupHostDetectedEvent = (params: {readonly operation: 'setup' | 'uninstall';@@ -616,9 +670,8 @@ export const getSetupHostDetectedEvent = (params: {readonly unsupportedReasonCode?:'codex_too_old' | 'no_json_inspection' | 'host_command_failed' | 'unknown';readonly cliVersion: string;-}): TrackEvent => ({- name: CLI_ANALYTICS_EVENTS.CLI_SETUP_HOST_DETECTED,- properties: {+}): TrackEvent =>+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_SETUP_HOST_DETECTED, {source: 'cli',invocation_origin: getInvocationOrigin(),cli_version: params.cliVersion,@@ -630,16 +683,14 @@ export const getSetupHostDetectedEvent = (params: {supported: params.supported,host_version: params.hostVersion,unsupported_reason_code: params.unsupportedReasonCode,- },-});+ });export const getSetupCancelledEvent = (params: {readonly operation: 'setup' | 'uninstall';readonly requestedTarget: 'auto' | 'claude' | 'codex' | 'all';readonly cliVersion: string;-}): TrackEvent => ({- name: CLI_ANALYTICS_EVENTS.CLI_SETUP_CANCELLED,- properties: {+}): TrackEvent =>+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_SETUP_CANCELLED, {source: 'cli',invocation_origin: getInvocationOrigin(),cli_version: params.cliVersion,@@ -647,16 +698,14 @@ export const getSetupCancelledEvent = (params: {operation: params.operation,requested_target: params.requestedTarget,reason: 'user_declined',- },-});+ });export const getSetupSkippedEvent = (params: {readonly operation: 'setup' | 'uninstall';readonly requestedTarget: 'auto' | 'claude' | 'codex' | 'all';readonly cliVersion: string;-}): TrackEvent => ({- name: CLI_ANALYTICS_EVENTS.CLI_SETUP_SKIPPED,- properties: {+}): TrackEvent =>+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_SETUP_SKIPPED, {source: 'cli',invocation_origin: getInvocationOrigin(),cli_version: params.cliVersion,@@ -664,8 +713,7 @@ export const getSetupSkippedEvent = (params: {operation: params.operation,requested_target: params.requestedTarget,reason: 'no_host_detected',- },-});+ });export const getToolExecuteValidationFailedEvent = (params: {readonly toolSlug: string;@@ -676,9 +724,8 @@ export const getToolExecuteValidationFailedEvent = (params: {readonly stage: 'dry_run' | 'validation' | 'execution';readonly failureOrigin: 'fast_fail' | 'main_endpoint';readonly logId?: string;-}): TrackEvent => ({- name: CLI_ANALYTICS_EVENTS.CLI_TOOL_INVOCATION_VALIDATION_FAILED,- properties: {+}): TrackEvent =>+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_TOOL_INVOCATION_VALIDATION_FAILED, {source: 'cli',invocation_origin: getInvocationOrigin(),tool_slug: params.toolSlug,@@ -693,8 +740,7 @@ export const getToolExecuteValidationFailedEvent = (params: {unknown_keys: extractUnknownKeys(params.error.issues),schema_path: params.error.schemaPath,...argumentShape(params.args),- },-});+ });export const isMaybeToolNotFoundError = (params: {readonly message?: string;@@ -731,9 +777,8 @@ export const getToolExecuteToolNotFoundEvent = (params: {readonly status?: number;readonly apiCode?: number;readonly message?: string;-}): TrackEvent => ({- name: CLI_ANALYTICS_EVENTS.CLI_TOOL_INVOCATION_TOOL_NOT_FOUND,- properties: {+}): TrackEvent =>+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_TOOL_INVOCATION_TOOL_NOT_FOUND, {source: 'cli',invocation_origin: getInvocationOrigin(),tool_slug: params.toolSlug,@@ -748,8 +793,7 @@ export const getToolExecuteToolNotFoundEvent = (params: {api_error_code: params.apiCode,error_message: params.message?.slice(0, 500),...argumentShape(params.args),- },-});+ });export const getToolExecuteFailedEvent = (params: {readonly toolSlug: string;@@ -765,9 +809,8 @@ export const getToolExecuteFailedEvent = (params: {readonly message?: string;readonly errorName?: string;readonly isNoConnectionError?: boolean;-}): TrackEvent => ({- name: CLI_ANALYTICS_EVENTS.CLI_TOOL_INVOCATION_FAILED,- properties: {+}): TrackEvent =>+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_TOOL_INVOCATION_FAILED, {source: 'cli',invocation_origin: getInvocationOrigin(),tool_slug: params.toolSlug,@@ -784,5 +827,4 @@ export const getToolExecuteFailedEvent = (params: {error_message: params.message?.slice(0, 500),is_no_connection_error: Boolean(params.isNoConnectionError),...argumentShape(params.args),- },-});+ });diff --git a/ts/packages/cli/test/src/analytics.events.test.ts b/ts/packages/cli/test/src/analytics.events.test.tsindex 5586f7b34..57115b379 100644--- a/ts/packages/cli/test/src/analytics.events.test.ts+++ b/ts/packages/cli/test/src/analytics.events.test.ts@@ -1,7 +1,10 @@-import { describe, expect, it } from 'vitest';+import { readFileSync } from 'node:fs';+import { afterEach, describe, expect, it, vi } from 'vitest';import { createCliCodactFailureBody } from 'src/analytics/dispatch';import {CLI_ANALYTICS_EVENTS,+ CLI_EVENT_JOURNEY_STAGES,+ CLI_JOURNEY_STAGES,createCliCommandTelemetryContext,getPluginLifecycleFailedEvent,getPluginLifecycleSucceededEvent,@@ -18,6 +21,8 @@ import {isMaybeToolValidationError,} from 'src/analytics/events';import { APP_VERSION } from 'src/constants';+import { inferSkillReleaseChannel } from 'src/effects/install-skill';+import { CLI_RELEASE_CHANNELS } from 'src/experimental-features';import { ToolInputValidationError } from 'src/services/tool-input-validation';describe('CLI analytics execute failure events', () => {@@ -326,3 +331,100 @@ describe('CLI analytics setup runtime-context events', () => {});});});++describe('CLI analytics journey taxonomy', () => {+ afterEach(() => {+ vi.unstubAllEnvs();+ });++ const contextFor = (argv: ReadonlyArray<string>) =>+ createCliCommandTelemetryContext(['bun', 'composio', ...argv], APP_VERSION, {+ stdoutIsTTY: false,+ stderrIsTTY: false,+ });++ const lifecycleCases: ReadonlyArray<[ReadonlyArray<string>, string]> = [+ [['execute', 'GMAIL_SEND_EMAIL'], 'execute'],+ [['search', 'send email'], 'other'],+ [['link', 'github'], 'connect'],+ [['login'], 'login'],+ [['logout'], 'other'],+ [['proxy', '/api/v3/toolkits'], 'other'],+ [['run', 'echo hi'], 'other'],+ [['install'], 'install'],+ [['setup'], 'setup'],+ [['version'], 'other'],+ ];++ it.each(lifecycleCases)('stamps %j lifecycle events with journey_stage %s', (argv, stage) => {+ const context = contextFor(argv);++ expect(getPrimaryLifecycleInvokedEvent(context)?.properties?.journey_stage).toBe(stage);+ expect(getPrimaryLifecycleSucceededEvent(context)?.properties?.journey_stage).toBe(stage);+ expect(+ getPrimaryLifecycleFailedEvent(context, new Error('boom'))?.properties?.journey_stage+ ).toBe(stage);+ });++ it('maps every analytics event name to a declared journey stage', () => {+ for (const name of Object.values(CLI_ANALYTICS_EVENTS)) {+ expect(CLI_JOURNEY_STAGES).toContain(CLI_EVENT_JOURNEY_STAGES[name]);+ }+ });++ it('stamps standalone setup and tool-invocation events with their stages', () => {+ expect(+ getPluginLifecycleSucceededEvent({+ operation: 'setup',+ target: 'claude',+ action: 'installed',+ cliVersion: APP_VERSION,+ })?.properties?.journey_stage+ ).toBe('setup');++ expect(+ getSetupSkippedEvent({+ operation: 'setup',+ requestedTarget: 'auto',+ cliVersion: APP_VERSION,+ })?.properties?.journey_stage+ ).toBe('setup');++ expect(+ getToolExecuteFailedEvent({+ toolSlug: 'GMAIL_SEND_EMAIL',+ args: {},+ surface: 'root',+ projectMode: 'consumer',+ stage: 'execution',+ failureOrigin: 'main_endpoint',+ })?.properties?.journey_stage+ ).toBe('execute');+ });++ it('stamps events with the release channel of the running build', () => {+ const properties = getPrimaryLifecycleInvokedEvent(contextFor(['login']))?.properties;++ expect(properties?.cli_channel).toBe(inferSkillReleaseChannel(APP_VERSION));+ expect(CLI_RELEASE_CHANNELS).toContain(properties?.cli_channel);+ });++ it('propagates the installer invocation origin from the environment', () => {+ vi.stubEnv('COMPOSIO_CLI_INVOCATION_ORIGIN', 'installer');++ expect(getPrimaryLifecycleInvokedEvent(contextFor(['install']))?.properties).toMatchObject({+ invocation_origin: 'installer',+ journey_stage: 'install',+ });+ });++ it('marks the install.sh shell-integration run as installer-origin', () => {+ const installScript = readFileSync(+ new URL('../../../../../install.sh', import.meta.url),+ 'utf8'+ );+ const installLine = installScript.split('\n').find(line => line.includes('"$exe" install '));++ expect(installLine).toContain('COMPOSIO_CLI_INVOCATION_ORIGIN=installer');+ });+});