@salesforce/b2c-tooling-sdk 0.2.1 → 0.4.0

package/dist/cjs/auth/types.d.ts

@@ -1,13 +1,27 @@
+/**
+ * Extended RequestInit that supports undici dispatcher for TLS/mTLS.
+ * Uses `unknown` for dispatcher to avoid type conflicts between undici package
+ * and @types/node/undici-types.
+ */
+export type FetchInit = Omit<RequestInit, 'dispatcher'> & {
+    /** undici dispatcher for custom TLS options (mTLS, self-signed certs) */
+    dispatcher?: unknown;
+};
 export interface AuthStrategy {
     /**
      * Performs a fetch request with authentication.
      * Implementations MUST handle header injection and 401 retries (token refresh) internally.
      */
-    fetch(url: string, init?: RequestInit): Promise<Response>;
+    fetch(url: string, init?: FetchInit): Promise<Response>;
     /**
      * Optional: Helper for legacy clients (like a strict WebDAV lib) that need the raw header.
      */
     getAuthorizationHeader?(): Promise<string>;
+    /**
+     * Optional: Invalidates the cached token, forcing re-authentication on next request.
+     * Used by middleware to retry requests after receiving a 401 response.
+     */
+    invalidateToken?(): void;
 }
 /**
  * Configuration for Basic authentication (username/access-key).

package/dist/cjs/auth/types.js

@@ -1,3 +1,8 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
 /** All available auth methods in default priority order */
 export const ALL_AUTH_METHODS = ['client-credentials', 'implicit', 'basic', 'api-key'];
 //# sourceMappingURL=types.js.map

package/dist/cjs/auth/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/auth/types.ts"],"names":[],"mappings":"AA8FA,2DAA2D;AAC3D,MAAM,CAAC,MAAM,gBAAgB,GAAiB,CAAC,oBAAoB,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/auth/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA2GH,2DAA2D;AAC3D,MAAM,CAAC,MAAM,gBAAgB,GAAiB,CAAC,oBAAoB,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC"}

package/dist/cjs/cli/am-command.d.ts

@@ -0,0 +1,74 @@
+import { Command } from '@oclif/core';
+import { OAuthCommand } from './oauth-command.js';
+import type { AccountManagerClient } from '../clients/am-api.js';
+/**
+ * Base command for Account Manager operations.
+ *
+ * Extends OAuthCommand with Account Manager client setup for users, roles, and organizations.
+ * Provides enhanced error messages with role-specific guidance when authentication fails.
+ *
+ * @example
+ * export default class UserList extends AmCommand<typeof UserList> {
+ *   async run(): Promise<void> {
+ *     const users = await this.accountManagerClient.listUsers({});
+ *     // ...
+ *   }
+ * }
+ *
+ * @example
+ * export default class OrgList extends AmCommand<typeof OrgList> {
+ *   async run(): Promise<void> {
+ *     const orgs = await this.accountManagerClient.listOrgs();
+ *     // ...
+ *   }
+ * }
+ */
+export declare abstract class AmCommand<T extends typeof Command> extends OAuthCommand<T> {
+    protected getDefaultClientId(): string;
+    private _accountManagerClient?;
+    private _authStrategy?;
+    /**
+     * Gets the auth method type that was used, based on the stored strategy.
+     */
+    protected get authMethodUsed(): 'implicit' | 'client-credentials' | undefined;
+    /**
+     * Gets the unified Account Manager client, creating it if necessary.
+     * This provides direct access to all Account Manager API methods (users, roles, orgs).
+     *
+     * @example
+     * const client = this.accountManagerClient;
+     * const users = await client.listUsers({});
+     * const roles = await client.listRoles({});
+     * const orgs = await client.listOrgs();
+     * const user = await client.getUser('user-id');
+     * const role = await client.getRole('bm-admin');
+     * const org = await client.getOrg('org-id');
+     */
+    protected get accountManagerClient(): AccountManagerClient;
+    /**
+     * Override catch() to detect auth errors and append contextual AM role guidance.
+     */
+    protected catch(err: Error & {
+        exitCode?: number;
+    }): Promise<never>;
+    /**
+     * Builds a contextual suggestion message based on the auth method and AM subtopic.
+     */
+    private getAuthErrorSuggestion;
+    /**
+     * Gets the AM subtopic from the command ID (e.g., 'am:users:list' → 'users').
+     */
+    private getAmSubtopic;
+    /**
+     * Attempts to extract roles from the cached JWT token synchronously.
+     */
+    private getJwtRolesInfo;
+    /**
+     * Suggestion for client-credentials auth failures.
+     */
+    private getClientCredentialsSuggestion;
+    /**
+     * Suggestion for implicit auth failures.
+     */
+    private getImplicitSuggestion;
+}

package/dist/cjs/cli/am-command.js

@@ -0,0 +1,189 @@
+import { OAuthCommand } from './oauth-command.js';
+import { createAccountManagerClient } from '../clients/am-api.js';
+import { ImplicitOAuthStrategy } from '../auth/oauth-implicit.js';
+import { DEFAULT_PUBLIC_CLIENT_ID } from '../defaults.js';
+/** Account Manager role: User Administrator */
+const AM_USER_ADMIN = 'User Administrator';
+/** Account Manager role: Account Administrator */
+const AM_ACCOUNT_ADMIN = 'Account Administrator';
+/** Account Manager role: API Administrator */
+const AM_API_ADMIN = 'API Administrator';
+/** Patterns that indicate an authentication/authorization error */
+const AUTH_ERROR_PATTERNS = [
+    'authentication invalid',
+    'operation forbidden',
+    '401',
+    '403',
+    'failed to get access token',
+    'unauthorized',
+];
+/**
+ * Base command for Account Manager operations.
+ *
+ * Extends OAuthCommand with Account Manager client setup for users, roles, and organizations.
+ * Provides enhanced error messages with role-specific guidance when authentication fails.
+ *
+ * @example
+ * export default class UserList extends AmCommand<typeof UserList> {
+ *   async run(): Promise<void> {
+ *     const users = await this.accountManagerClient.listUsers({});
+ *     // ...
+ *   }
+ * }
+ *
+ * @example
+ * export default class OrgList extends AmCommand<typeof OrgList> {
+ *   async run(): Promise<void> {
+ *     const orgs = await this.accountManagerClient.listOrgs();
+ *     // ...
+ *   }
+ * }
+ */
+export class AmCommand extends OAuthCommand {
+    getDefaultClientId() {
+        return DEFAULT_PUBLIC_CLIENT_ID;
+    }
+    _accountManagerClient;
+    _authStrategy;
+    /**
+     * Gets the auth method type that was used, based on the stored strategy.
+     */
+    get authMethodUsed() {
+        if (!this._authStrategy)
+            return undefined;
+        return this._authStrategy instanceof ImplicitOAuthStrategy ? 'implicit' : 'client-credentials';
+    }
+    /**
+     * Gets the unified Account Manager client, creating it if necessary.
+     * This provides direct access to all Account Manager API methods (users, roles, orgs).
+     *
+     * @example
+     * const client = this.accountManagerClient;
+     * const users = await client.listUsers({});
+     * const roles = await client.listRoles({});
+     * const orgs = await client.listOrgs();
+     * const user = await client.getUser('user-id');
+     * const role = await client.getRole('bm-admin');
+     * const org = await client.getOrg('org-id');
+     */
+    get accountManagerClient() {
+        if (!this._accountManagerClient) {
+            this.requireOAuthCredentials();
+            const authStrategy = this.getOAuthStrategy();
+            this._authStrategy = authStrategy;
+            this._accountManagerClient = createAccountManagerClient({
+                hostname: this.accountManagerHost,
+            }, authStrategy);
+        }
+        return this._accountManagerClient;
+    }
+    /**
+     * Override catch() to detect auth errors and append contextual AM role guidance.
+     */
+    async catch(err) {
+        const message = err.message?.toLowerCase() ?? '';
+        const isAuthError = AUTH_ERROR_PATTERNS.some((pattern) => message.includes(pattern));
+        if (isAuthError) {
+            const suggestion = this.getAuthErrorSuggestion();
+            if (suggestion) {
+                err.message = `${err.message}\n\n${suggestion}`;
+            }
+        }
+        return super.catch(err);
+    }
+    /**
+     * Builds a contextual suggestion message based on the auth method and AM subtopic.
+     */
+    getAuthErrorSuggestion() {
+        const subtopic = this.getAmSubtopic();
+        const authMethod = this.authMethodUsed;
+        if (!subtopic)
+            return undefined;
+        // Try to get current JWT roles for client-credentials (avoid triggering browser login for implicit)
+        let rolesInfo = '';
+        if (authMethod === 'client-credentials' && this._authStrategy) {
+            try {
+                // getJWT() is async but we only want cached token info — use synchronous check
+                // The token should already be cached if we got far enough to receive an auth error
+                rolesInfo = this.getJwtRolesInfo();
+            }
+            catch {
+                // Token may be expired or unavailable, skip roles info
+            }
+        }
+        if (authMethod === 'client-credentials') {
+            return this.getClientCredentialsSuggestion(subtopic, rolesInfo);
+        }
+        if (authMethod === 'implicit') {
+            return this.getImplicitSuggestion(subtopic);
+        }
+        return undefined;
+    }
+    /**
+     * Gets the AM subtopic from the command ID (e.g., 'am:users:list' → 'users').
+     */
+    getAmSubtopic() {
+        if (!this.id)
+            return undefined;
+        const parts = this.id.split(':');
+        // Command IDs are like 'am:users:list', 'am:roles:get', 'am:orgs:list', 'am:clients:list'
+        const amIndex = parts.indexOf('am');
+        if (amIndex >= 0 && amIndex + 1 < parts.length) {
+            return parts[amIndex + 1];
+        }
+        return undefined;
+    }
+    /**
+     * Attempts to extract roles from the cached JWT token synchronously.
+     */
+    getJwtRolesInfo() {
+        // Access the strategy's internal token cache via getJWT()
+        // This is best-effort — if no token is cached, we skip
+        if (!this._authStrategy)
+            return '';
+        // We can't call async getJWT() here, but we can check if OAuthStrategy has a cached token
+        // by looking at the strategy type. For now, we'll return empty and let the suggestion
+        // work without role details.
+        return '';
+    }
+    /**
+     * Suggestion for client-credentials auth failures.
+     */
+    getClientCredentialsSuggestion(subtopic, rolesInfo) {
+        const suffix = rolesInfo ? `\n${rolesInfo}` : '';
+        switch (subtopic) {
+            case 'users':
+            case 'roles':
+                return (`Suggestion: Add the "${AM_USER_ADMIN}" role to your API client, ` +
+                    `or use --user-auth to authenticate as a user with the appropriate role.${suffix}`);
+            case 'orgs':
+                return (`Suggestion: Use --user-auth to authenticate as a user with the "${AM_ACCOUNT_ADMIN}" role. ` +
+                    `Organization management requires user authentication.${suffix}`);
+            case 'clients':
+                return (`Suggestion: Use --user-auth to authenticate as a user with the ` +
+                    `"${AM_ACCOUNT_ADMIN}" or "${AM_API_ADMIN}" role. ` +
+                    `API client management requires user authentication.${suffix}`);
+            default:
+                return `Suggestion: Try using --user-auth for browser-based authentication.${suffix}`;
+        }
+    }
+    /**
+     * Suggestion for implicit auth failures.
+     */
+    getImplicitSuggestion(subtopic) {
+        switch (subtopic) {
+            case 'users':
+            case 'roles':
+                return (`Suggestion: Your user account needs the "${AM_ACCOUNT_ADMIN}" or "${AM_USER_ADMIN}" role ` +
+                    `to manage users and roles.`);
+            case 'clients':
+                return (`Suggestion: Your user account needs the "${AM_ACCOUNT_ADMIN}" or "${AM_API_ADMIN}" role ` +
+                    `to manage API clients.`);
+            case 'orgs':
+                return `Suggestion: Your user account needs the "${AM_ACCOUNT_ADMIN}" role to manage organizations.`;
+            default:
+                return `Suggestion: Verify your user account has the appropriate Account Manager role.`;
+        }
+    }
+}
+//# sourceMappingURL=am-command.js.map

package/dist/cjs/cli/am-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"am-command.js","sourceRoot":"","sources":["../../../src/cli/am-command.ts"],"names":[],"mappings":"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"}

package/dist/cjs/cli/base-command.d.ts

@@ -1,8 +1,10 @@
 import { Command, type Interfaces } from '@oclif/core';
+import type { LoadConfigOptions, PluginSources } from './config.js';
 import type { ResolvedB2CConfig } from '../config/index.js';
 import { type Logger } from '../logging/index.js';
 import { type ExtraParamsConfig } from '../clients/middleware.js';
 import type { ConfigSource } from '../config/types.js';
+import { Telemetry, type TelemetryAttributes } from '../telemetry/index.js';
 export type Flags<T extends typeof Command> = Interfaces.InferredFlags<(typeof BaseCommand)['baseFlags'] & T['flags']>;
 export type Args<T extends typeof Command> = Interfaces.InferredArgs<T['args']>;
 /**
@@ -13,6 +15,11 @@ export type Args<T extends typeof Command> = Interfaces.InferredArgs<T['args']>;
  * - SFCC_LOG_COLORIZE: Force colors on/off (default: auto-detect TTY)
  * - SFCC_REDACT_SECRETS: Set to 'false' to disable secret redaction
  * - NO_COLOR: Industry standard to disable colors
+ *
+ * Environment variables for telemetry:
+ * - SF_DISABLE_TELEMETRY: Set to 'true' to disable telemetry (sf CLI standard)
+ * - SFCC_DISABLE_TELEMETRY: Set to 'true' to disable telemetry
+ * - SFCC_APP_INSIGHTS_KEY: Override connection string from package.json
  */
 export declare abstract class BaseCommand<T extends typeof Command> extends Command {
     static baseFlags: {
@@ -31,11 +38,31 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
     protected args: Args<T>;
     protected resolvedConfig: ResolvedB2CConfig;
     protected logger: Logger;
+    /** Telemetry instance for tracking command events */
+    protected telemetry?: Telemetry;
     /** High-priority config sources from plugins (inserted before defaults) */
     protected pluginSourcesBefore: ConfigSource[];
     /** Low-priority config sources from plugins (inserted after defaults) */
     protected pluginSourcesAfter: ConfigSource[];
+    /** Start time for command duration tracking */
+    private commandStartTime?;
     init(): Promise<void>;
+    /**
+     * Auto-initialize telemetry from package.json oclif.telemetry config.
+     * Called during init() to enable automatic telemetry for all commands.
+     */
+    private initTelemetryFromConfig;
+    /**
+     * Manual telemetry initialization for non-pjson usage (e.g., MCP server with additional attributes).
+     * Use this when you need to pass custom initial attributes or use a different connection string.
+     *
+     * @param options - Telemetry options
+     * @returns The telemetry instance, or undefined if telemetry is disabled
+     */
+    protected initTelemetry(options: {
+        appInsightsKey?: string;
+        initialAttributes?: TelemetryAttributes;
+    }): Promise<Telemetry | undefined>;
     /**
      * Determine colorize setting based on env vars and TTY.
      * Priority: NO_COLOR > SFCC_LOG_COLORIZE > TTY detection
@@ -50,7 +77,35 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
      * Override oclif's warn() to use pino.
      */
     warn(input: string | Error): string | Error;
+    /**
+     * Gets base configuration options from common flags.
+     *
+     * Subclasses should spread these options when overriding loadConfiguration()
+     * to ensure common options like startDir are always included.
+     *
+     * @example
+     * ```typescript
+     * protected override loadConfiguration(): ResolvedB2CConfig {
+     *   const options: LoadConfigOptions = {
+     *     ...this.getBaseConfigOptions(),
+     *     // Add subclass-specific options here
+     *   };
+     *   return loadConfig(extractMyFlags(this.flags), options, this.getPluginSources());
+     * }
+     * ```
+     */
+    protected getBaseConfigOptions(): LoadConfigOptions;
+    /**
+     * Gets plugin sources for configuration resolution.
+     */
+    protected getPluginSources(): PluginSources;
     protected loadConfiguration(): ResolvedB2CConfig;
+    /**
+     * Enrich telemetry with realm/tenant context from the resolved configuration.
+     * Called after loadConfiguration() in init() so that COMMAND_SUCCESS and
+     * COMMAND_EXCEPTION events include organizational context.
+     */
+    protected addTelemetryContext(): void;
     /**
      * Collects config sources from plugins via the `b2c:config-sources` hook.
      *
@@ -93,10 +148,16 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
      *
      * Logs the error using the structured logger (including cause if available).
      * In JSON mode, outputs a JSON error object to stdout instead of oclif's default format.
+     * Sends exception to telemetry if initialized.
      */
     protected catch(err: Error & {
         exitCode?: number;
     }): Promise<never>;
+    /**
+     * Called after run() completes (whether successfully or via catch()).
+     * Tracks COMMAND_SUCCESS and stops telemetry.
+     */
+    protected finally(err: Error | undefined): Promise<void>;
     baseCommandTest(): void;
     /**
      * Parse extra params from --extra-query, --extra-body, and --extra-headers flags.

package/dist/cjs/cli/base-command.js

@@ -5,12 +5,14 @@
  */
 import { Command, Flags } from '@oclif/core';
 import { loadConfig } from './config.js';
+import { parseFriendlySandboxId } from '../operations/ods/sandbox-lookup.js';
 import { setLanguage } from '../i18n/index.js';
 import { configureLogger, getLogger } from '../logging/index.js';
 import { createExtraParamsMiddleware } from '../clients/middleware.js';
 import { globalMiddlewareRegistry } from '../clients/middleware-registry.js';
 import { globalAuthMiddlewareRegistry } from '../auth/middleware.js';
 import { setUserAgent } from '../clients/user-agent.js';
+import { createTelemetry, Telemetry } from '../telemetry/index.js';
 const LOG_LEVELS = ['trace', 'debug', 'info', 'warn', 'error', 'silent'];
 /**
  * Base command class for B2C CLI tools.
@@ -20,6 +22,11 @@ const LOG_LEVELS = ['trace', 'debug', 'info', 'warn', 'error', 'silent'];
  * - SFCC_LOG_COLORIZE: Force colors on/off (default: auto-detect TTY)
  * - SFCC_REDACT_SECRETS: Set to 'false' to disable secret redaction
  * - NO_COLOR: Industry standard to disable colors
+ *
+ * Environment variables for telemetry:
+ * - SF_DISABLE_TELEMETRY: Set to 'true' to disable telemetry (sf CLI standard)
+ * - SFCC_DISABLE_TELEMETRY: Set to 'true' to disable telemetry
+ * - SFCC_APP_INSIGHTS_KEY: Override connection string from package.json
  */
 export class BaseCommand extends Command {
     static baseFlags = {
@@ -85,10 +92,14 @@ export class BaseCommand extends Command {
     args;
     resolvedConfig;
     logger;
+    /** Telemetry instance for tracking command events */
+    telemetry;
     /** High-priority config sources from plugins (inserted before defaults) */
     pluginSourcesBefore = [];
     /** Low-priority config sources from plugins (inserted after defaults) */
     pluginSourcesAfter = [];
+    /** Start time for command duration tracking */
+    commandStartTime;
     async init() {
         await super.init();
         const { args, flags } = await this.parse({
@@ -115,7 +126,59 @@ export class BaseCommand extends Command {
         await this.collectPluginAuthMiddleware();
         // Collect config sources from plugins before loading configuration
         await this.collectPluginConfigSources();
+        // Auto-initialize telemetry from oclif pjson config
+        await this.initTelemetryFromConfig();
         this.resolvedConfig = this.loadConfiguration();
+        this.addTelemetryContext();
+    }
+    /**
+     * Auto-initialize telemetry from package.json oclif.telemetry config.
+     * Called during init() to enable automatic telemetry for all commands.
+     */
+    async initTelemetryFromConfig() {
+        const pjsonTelemetry = this.config.pjson.oclif?.telemetry;
+        const connectionString = Telemetry.getConnectionString(pjsonTelemetry?.connectionString);
+        if (!connectionString)
+            return;
+        this.telemetry = createTelemetry({
+            project: this.config.name,
+            appInsightsKey: connectionString,
+            version: this.config.version,
+            dataDir: this.config.dataDir,
+            initialAttributes: { command: this.id },
+        });
+        await this.telemetry.start();
+        // Track command start
+        this.commandStartTime = Date.now();
+        this.telemetry.sendEvent('COMMAND_START', { command: this.id });
+    }
+    /**
+     * Manual telemetry initialization for non-pjson usage (e.g., MCP server with additional attributes).
+     * Use this when you need to pass custom initial attributes or use a different connection string.
+     *
+     * @param options - Telemetry options
+     * @returns The telemetry instance, or undefined if telemetry is disabled
+     */
+    async initTelemetry(options) {
+        // If telemetry was already initialized by initTelemetryFromConfig, stop it first
+        if (this.telemetry) {
+            await this.telemetry.stop();
+        }
+        const connectionString = Telemetry.getConnectionString(options.appInsightsKey);
+        if (!connectionString)
+            return undefined;
+        this.telemetry = createTelemetry({
+            project: this.config.name,
+            appInsightsKey: connectionString,
+            version: this.config.version,
+            dataDir: this.config.dataDir,
+            initialAttributes: { command: this.id, ...options.initialAttributes },
+        });
+        await this.telemetry.start();
+        // Track command start
+        this.commandStartTime = Date.now();
+        this.telemetry.sendEvent('COMMAND_START', { command: this.id });
+        return this.telemetry;
     }
     /**
      * Determine colorize setting based on env vars and TTY.
@@ -166,16 +229,91 @@ export class BaseCommand extends Command {
         this.logger.warn(message);
         return input;
     }
-    loadConfiguration() {
-        const options = {
+    /**
+     * Gets base configuration options from common flags.
+     *
+     * Subclasses should spread these options when overriding loadConfiguration()
+     * to ensure common options like startDir are always included.
+     *
+     * @example
+     * ```typescript
+     * protected override loadConfiguration(): ResolvedB2CConfig {
+     *   const options: LoadConfigOptions = {
+     *     ...this.getBaseConfigOptions(),
+     *     // Add subclass-specific options here
+     *   };
+     *   return loadConfig(extractMyFlags(this.flags), options, this.getPluginSources());
+     * }
+     * ```
+     */
+    getBaseConfigOptions() {
+        return {
             instance: this.flags.instance,
             configPath: this.flags.config,
+            startDir: this.flags['working-directory'],
         };
-        const pluginSources = {
+    }
+    /**
+     * Gets plugin sources for configuration resolution.
+     */
+    getPluginSources() {
+        return {
             before: this.pluginSourcesBefore,
             after: this.pluginSourcesAfter,
         };
-        return loadConfig({}, options, pluginSources);
+    }
+    loadConfiguration() {
+        return loadConfig({}, this.getBaseConfigOptions(), this.getPluginSources());
+    }
+    /**
+     * Enrich telemetry with realm/tenant context from the resolved configuration.
+     * Called after loadConfiguration() in init() so that COMMAND_SUCCESS and
+     * COMMAND_EXCEPTION events include organizational context.
+     */
+    addTelemetryContext() {
+        if (!this.telemetry)
+            return;
+        try {
+            const attributes = {};
+            const { values, sources } = this.resolvedConfig;
+            // Extract realm from tenantId (e.g., "zzpq_019" or "f_ecom_zzpq_019")
+            if (values.tenantId) {
+                attributes.tenantId = values.tenantId;
+                const parsed = parseFriendlySandboxId(values.tenantId);
+                if (parsed) {
+                    attributes.realm = parsed.realm;
+                }
+            }
+            // Fallback: extract realm from hostname (e.g., "zzpq-019.dx.commercecloud.salesforce.com")
+            if (!attributes.realm && values.hostname) {
+                const parsed = parseFriendlySandboxId(values.hostname.split('.')[0]);
+                if (parsed) {
+                    attributes.realm = parsed.realm;
+                }
+            }
+            if (values.hostname) {
+                attributes.hostname = values.hostname;
+            }
+            if (values.clientId) {
+                attributes.clientId = values.clientId;
+            }
+            if (values.shortCode) {
+                attributes.shortCode = values.shortCode;
+            }
+            // Record which config sources contributed
+            if (sources.length > 0) {
+                attributes.configSources = sources.map((s) => s.name).join(', ');
+            }
+            if (Object.keys(attributes).length > 0) {
+                this.telemetry.addAttributes(attributes);
+                if (process.env.SFCC_TELEMETRY_LOG === 'true') {
+                    this.logger.debug({ attributes }, 'telemetry context enriched');
+                }
+            }
+        }
+        catch {
+            // Best-effort: telemetry context enrichment must never prevent command execution
+        }
     }
     /**
      * Collects config sources from plugins via the `b2c:config-sources` hook.
@@ -303,9 +441,25 @@ export class BaseCommand extends Command {
      *
      * Logs the error using the structured logger (including cause if available).
      * In JSON mode, outputs a JSON error object to stdout instead of oclif's default format.
+     * Sends exception to telemetry if initialized.
      */
     async catch(err) {
         const exitCode = err.exitCode ?? 1;
+        const duration = this.commandStartTime ? Date.now() - this.commandStartTime : undefined;
+        // Send exception and COMMAND_ERROR event so the error appears in custom events (same view as COMMAND_START)
+        // Flush explicitly before stop to ensure events are sent before process exits
+        if (this.telemetry) {
+            this.telemetry.sendException(err, { command: this.id, exitCode, duration });
+            this.telemetry.sendEvent('COMMAND_ERROR', {
+                command: this.id,
+                exitCode,
+                duration,
+                errorMessage: err.message,
+                ...(err.cause ? { errorCause: String(err.cause) } : {}),
+            });
+            await this.telemetry.flush();
+            await this.telemetry.stop();
+        }
         // Log if logger is available (may not be if error during init)
         if (this.logger) {
             this.logger.error({ cause: err?.cause }, err.message);
@@ -325,6 +479,19 @@ export class BaseCommand extends Command {
         // Use oclif's error() for proper exit code and display
         this.error(err.message, { exit: exitCode });
     }
+    /**
+     * Called after run() completes (whether successfully or via catch()).
+     * Tracks COMMAND_SUCCESS and stops telemetry.
+     */
+    async finally(err) {
+        // Only track success if no error occurred
+        if (!err && this.telemetry) {
+            const duration = this.commandStartTime ? Date.now() - this.commandStartTime : undefined;
+            this.telemetry.sendEvent('COMMAND_SUCCESS', { command: this.id, duration });
+            await this.telemetry.stop();
+        }
+        await super.finally(err);
+    }
     baseCommandTest() {
         this.logger.info('BaseCommand initialized');
     }