@alagoni97/cli 0.72.1

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+export { run } from '@oclif/core';
+export { AsyncAPIDocumentInterface } from '@asyncapi/parser';
+export { defaultTypeScriptChannelsGenerator, defaultTypeScriptParametersOptions, defaultTypeScriptPayloadGenerator, defaultTypeScriptClientGenerator, defaultCustomGenerator, TypeScriptClientGenerator, TypeScriptChannelsGenerator, TypeScriptPayloadGenerator, TypescriptParametersGenerator, generateTypeScriptChannels, generateTypescriptParameters, generateTypescriptPayload, RunGeneratorContext, SupportedLanguages, PresetTypes, TheCodegenConfiguration, TheCodegenConfigurationInternal, zodAsyncAPICodegenConfiguration, zodAsyncAPIGenerators, zodAsyncAPITypeScriptGenerators, zodTheCodegenConfiguration, Generators, GenericCodegenContext, LoadArgument, ParameterRenderType, PayloadRenderType, SingleFunctionRenderType, runGenerators, loadAsyncapi, loadJsonSchema, getDefaultConfiguration, renderGenerator, realizeConfiguration, loadAndRealizeConfigFile, loadConfigFile, realizeGeneratorContext, ChannelFunctionTypes } from './codegen';
+export declare const modelina: {
+    TS_COMMON_PRESET: Partial<{
+        class: import("@asyncapi/modelina/lib/types/generators/typescript/TypeScriptPreset").ClassPresetType<import("@asyncapi/modelina").TypeScriptCommonPresetOptions>;
+        interface: import("@asyncapi/modelina/lib/types/generators/typescript/TypeScriptPreset").InterfacePresetType<import("@asyncapi/modelina").TypeScriptCommonPresetOptions>;
+        enum: import("@asyncapi/modelina/lib/types/generators/typescript/TypeScriptPreset").EnumPresetType<import("@asyncapi/modelina").TypeScriptCommonPresetOptions>;
+        type: import("@asyncapi/modelina/lib/types/generators/typescript/TypeScriptPreset").TypePresetType<import("@asyncapi/modelina").TypeScriptCommonPresetOptions>;
+    }>;
+    TS_DESCRIPTION_PRESET: Partial<{
+        class: import("@asyncapi/modelina/lib/types/generators/typescript/TypeScriptPreset").ClassPresetType<any>;
+        interface: import("@asyncapi/modelina/lib/types/generators/typescript/TypeScriptPreset").InterfacePresetType<any>;
+        enum: import("@asyncapi/modelina/lib/types/generators/typescript/TypeScriptPreset").EnumPresetType<any>;
+        type: import("@asyncapi/modelina/lib/types/generators/typescript/TypeScriptPreset").TypePresetType<any>;
+    }>;
+    TS_DEFAULT_PRESET: Partial<{
+        class: import("@asyncapi/modelina/lib/types/generators/typescript/TypeScriptPreset").ClassPresetType<import("@asyncapi/modelina").TypeScriptOptions>;
+        interface: import("@asyncapi/modelina/lib/types/generators/typescript/TypeScriptPreset").InterfacePresetType<import("@asyncapi/modelina").TypeScriptOptions>;
+        enum: import("@asyncapi/modelina/lib/types/generators/typescript/TypeScriptPreset").EnumPresetType<import("@asyncapi/modelina").TypeScriptOptions>;
+        type: import("@asyncapi/modelina/lib/types/generators/typescript/TypeScriptPreset").TypePresetType<import("@asyncapi/modelina").TypeScriptOptions>;
+    }>;
+    TS_JSONBINPACK_PRESET: Partial<{
+        class: import("@asyncapi/modelina/lib/types/generators/typescript/TypeScriptPreset").ClassPresetType<any>;
+        interface: import("@asyncapi/modelina/lib/types/generators/typescript/TypeScriptPreset").InterfacePresetType<any>;
+        enum: import("@asyncapi/modelina/lib/types/generators/typescript/TypeScriptPreset").EnumPresetType<any>;
+        type: import("@asyncapi/modelina/lib/types/generators/typescript/TypeScriptPreset").TypePresetType<any>;
+    }>;
+};

package/dist/index.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.modelina = exports.ChannelFunctionTypes = exports.realizeGeneratorContext = exports.loadConfigFile = exports.loadAndRealizeConfigFile = exports.realizeConfiguration = exports.renderGenerator = exports.getDefaultConfiguration = exports.loadJsonSchema = exports.loadAsyncapi = exports.runGenerators = exports.zodTheCodegenConfiguration = exports.zodAsyncAPITypeScriptGenerators = exports.zodAsyncAPIGenerators = exports.zodAsyncAPICodegenConfiguration = exports.generateTypescriptPayload = exports.generateTypescriptParameters = exports.generateTypeScriptChannels = exports.defaultCustomGenerator = exports.defaultTypeScriptClientGenerator = exports.defaultTypeScriptPayloadGenerator = exports.defaultTypeScriptParametersOptions = exports.defaultTypeScriptChannelsGenerator = exports.run = void 0;
+var core_1 = require("@oclif/core");
+Object.defineProperty(exports, "run", { enumerable: true, get: function () { return core_1.run; } });
+var codegen_1 = require("./codegen");
+Object.defineProperty(exports, "defaultTypeScriptChannelsGenerator", { enumerable: true, get: function () { return codegen_1.defaultTypeScriptChannelsGenerator; } });
+Object.defineProperty(exports, "defaultTypeScriptParametersOptions", { enumerable: true, get: function () { return codegen_1.defaultTypeScriptParametersOptions; } });
+Object.defineProperty(exports, "defaultTypeScriptPayloadGenerator", { enumerable: true, get: function () { return codegen_1.defaultTypeScriptPayloadGenerator; } });
+Object.defineProperty(exports, "defaultTypeScriptClientGenerator", { enumerable: true, get: function () { return codegen_1.defaultTypeScriptClientGenerator; } });
+Object.defineProperty(exports, "defaultCustomGenerator", { enumerable: true, get: function () { return codegen_1.defaultCustomGenerator; } });
+Object.defineProperty(exports, "generateTypeScriptChannels", { enumerable: true, get: function () { return codegen_1.generateTypeScriptChannels; } });
+Object.defineProperty(exports, "generateTypescriptParameters", { enumerable: true, get: function () { return codegen_1.generateTypescriptParameters; } });
+Object.defineProperty(exports, "generateTypescriptPayload", { enumerable: true, get: function () { return codegen_1.generateTypescriptPayload; } });
+Object.defineProperty(exports, "zodAsyncAPICodegenConfiguration", { enumerable: true, get: function () { return codegen_1.zodAsyncAPICodegenConfiguration; } });
+Object.defineProperty(exports, "zodAsyncAPIGenerators", { enumerable: true, get: function () { return codegen_1.zodAsyncAPIGenerators; } });
+Object.defineProperty(exports, "zodAsyncAPITypeScriptGenerators", { enumerable: true, get: function () { return codegen_1.zodAsyncAPITypeScriptGenerators; } });
+Object.defineProperty(exports, "zodTheCodegenConfiguration", { enumerable: true, get: function () { return codegen_1.zodTheCodegenConfiguration; } });
+Object.defineProperty(exports, "runGenerators", { enumerable: true, get: function () { return codegen_1.runGenerators; } });
+Object.defineProperty(exports, "loadAsyncapi", { enumerable: true, get: function () { return codegen_1.loadAsyncapi; } });
+Object.defineProperty(exports, "loadJsonSchema", { enumerable: true, get: function () { return codegen_1.loadJsonSchema; } });
+Object.defineProperty(exports, "getDefaultConfiguration", { enumerable: true, get: function () { return codegen_1.getDefaultConfiguration; } });
+Object.defineProperty(exports, "renderGenerator", { enumerable: true, get: function () { return codegen_1.renderGenerator; } });
+Object.defineProperty(exports, "realizeConfiguration", { enumerable: true, get: function () { return codegen_1.realizeConfiguration; } });
+Object.defineProperty(exports, "loadAndRealizeConfigFile", { enumerable: true, get: function () { return codegen_1.loadAndRealizeConfigFile; } });
+Object.defineProperty(exports, "loadConfigFile", { enumerable: true, get: function () { return codegen_1.loadConfigFile; } });
+Object.defineProperty(exports, "realizeGeneratorContext", { enumerable: true, get: function () { return codegen_1.realizeGeneratorContext; } });
+Object.defineProperty(exports, "ChannelFunctionTypes", { enumerable: true, get: function () { return codegen_1.ChannelFunctionTypes; } });
+const modelina_1 = require("@asyncapi/modelina");
+exports.modelina = {
+    TS_COMMON_PRESET: modelina_1.TS_COMMON_PRESET,
+    TS_DESCRIPTION_PRESET: modelina_1.TS_DESCRIPTION_PRESET,
+    TS_DEFAULT_PRESET: modelina_1.TS_DEFAULT_PRESET,
+    TS_JSONBINPACK_PRESET: modelina_1.TS_JSONBINPACK_PRESET
+};

package/dist/telemetry/anonymize.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Re-export the canonical helper from `src/utils/inputSource.ts`. The
+ * telemetry surface is unchanged; the helper now lives next to the rest
+ * of the URL-detection code so it can be shared with the input loaders.
+ */
+export { getInputSourceType } from '../utils/inputSource';
+/**
+ * Detect if running in a CI environment.
+ * Checks common CI environment variables.
+ */
+export declare function isCIEnvironment(): boolean;
+/**
+ * Categorize an error for telemetry purposes.
+ * Only returns the error category, not the actual error message or details.
+ *
+ * @param error - The error to categorize
+ * @returns Error category string
+ */
+export declare function categorizeError(error: unknown): string;

package/dist/telemetry/anonymize.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.categorizeError = exports.isCIEnvironment = exports.getInputSourceType = void 0;
+/* eslint-disable no-undef */
+/**
+ * Re-export the canonical helper from `src/utils/inputSource.ts`. The
+ * telemetry surface is unchanged; the helper now lives next to the rest
+ * of the URL-detection code so it can be shared with the input loaders.
+ */
+var inputSource_1 = require("../utils/inputSource");
+Object.defineProperty(exports, "getInputSourceType", { enumerable: true, get: function () { return inputSource_1.getInputSourceType; } });
+/**
+ * Detect if running in a CI environment.
+ * Checks common CI environment variables.
+ */
+function isCIEnvironment() {
+    return Boolean(process.env.CI || // Generic CI indicator
+        process.env.GITHUB_ACTIONS ||
+        process.env.GITLAB_CI ||
+        process.env.CIRCLECI ||
+        process.env.TRAVIS ||
+        process.env.JENKINS_URL ||
+        process.env.BITBUCKET_PIPELINE_UUID ||
+        process.env.CODEBUILD_BUILD_ID ||
+        process.env.TEAMCITY_VERSION ||
+        process.env.BUILDKITE);
+}
+exports.isCIEnvironment = isCIEnvironment;
+/**
+ * Categorize an error for telemetry purposes.
+ * Only returns the error category, not the actual error message or details.
+ *
+ * @param error - The error to categorize
+ * @returns Error category string
+ */
+function categorizeError(error) {
+    if (!error) {
+        return 'unknown_error';
+    }
+    const errorMessage = error instanceof Error
+        ? error.message.toLowerCase()
+        : String(error).toLowerCase();
+    // Configuration errors
+    if (errorMessage.includes('config') ||
+        errorMessage.includes('configuration')) {
+        return 'configuration_error';
+    }
+    // File system errors
+    if (errorMessage.includes('enoent') ||
+        errorMessage.includes('file not found')) {
+        return 'file_not_found';
+    }
+    // Network errors
+    if (errorMessage.includes('network') ||
+        errorMessage.includes('fetch') ||
+        errorMessage.includes('http')) {
+        return 'network_error';
+    }
+    // Parse errors
+    if (errorMessage.includes('parse') || errorMessage.includes('syntax')) {
+        return 'parse_error';
+    }
+    // Validation errors
+    if (errorMessage.includes('validation') || errorMessage.includes('invalid')) {
+        return 'validation_error';
+    }
+    // Permission errors
+    if (errorMessage.includes('permission') || errorMessage.includes('eacces')) {
+        return 'permission_error';
+    }
+    return 'unknown_error';
+}
+exports.categorizeError = categorizeError;

package/dist/telemetry/collector.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Get CLI version from package.json
+ */
+export declare function getCliVersion(): string;
+/**
+ * Get Node.js version
+ */
+export declare function getNodeVersion(): string;
+/**
+ * Get operating system platform
+ */
+export declare function getOSPlatform(): string;
+/**
+ * Check if running in CI environment
+ */
+export declare function isCI(): boolean;
+/**
+ * Collect common system information for telemetry events.
+ * This data is added to all telemetry events.
+ */
+export declare function collectSystemInfo(): {
+    cli_version: string;
+    node_version: string;
+    os: string;
+    ci: boolean;
+};

package/dist/telemetry/collector.js

@@ -0,0 +1,57 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectSystemInfo = exports.isCI = exports.getOSPlatform = exports.getNodeVersion = exports.getCliVersion = void 0;
+/* eslint-disable no-undef */
+const os_1 = __importDefault(require("os"));
+const anonymize_1 = require("./anonymize");
+/**
+ * Get CLI version from package.json
+ */
+function getCliVersion() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const packageJson = require('../../package.json');
+        return packageJson.version || 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+exports.getCliVersion = getCliVersion;
+/**
+ * Get Node.js version
+ */
+function getNodeVersion() {
+    return process.version;
+}
+exports.getNodeVersion = getNodeVersion;
+/**
+ * Get operating system platform
+ */
+function getOSPlatform() {
+    return os_1.default.platform();
+}
+exports.getOSPlatform = getOSPlatform;
+/**
+ * Check if running in CI environment
+ */
+function isCI() {
+    return (0, anonymize_1.isCIEnvironment)();
+}
+exports.isCI = isCI;
+/**
+ * Collect common system information for telemetry events.
+ * This data is added to all telemetry events.
+ */
+function collectSystemInfo() {
+    return {
+        cli_version: getCliVersion(),
+        node_version: getNodeVersion(),
+        os: getOSPlatform(),
+        ci: isCI()
+    };
+}
+exports.collectSystemInfo = collectSystemInfo;

package/dist/telemetry/config.d.ts

@@ -0,0 +1,32 @@
+import { TelemetryConfig } from '../PersistedConfig';
+import { ProjectTelemetryConfig } from '../codegen/types';
+/**
+ * Get telemetry configuration with proper priority order.
+ * This function never throws - returns disabled config on any error.
+ *
+ * Priority order (highest to lowest):
+ * 1. Environment variable overrides (highest priority):
+ *    - CODEGEN_TELEMETRY_DISABLED / DO_NOT_TRACK: disable telemetry
+ *    - CODEGEN_TELEMETRY_ENDPOINT: custom analytics endpoint
+ *    - CODEGEN_TELEMETRY_ID: custom tracking ID
+ *    - CODEGEN_TELEMETRY_API_SECRET: custom API secret
+ * 2. Project-level config (from codegen.config.js)
+ * 3. Global config file (~/.the-codegen-project/config.json)
+ *
+ * @param projectConfig - Optional project-level telemetry config from codegen.config.js
+ * @returns Promise resolving to telemetry configuration
+ */
+export declare function getTelemetryConfig(projectConfig?: ProjectTelemetryConfig): Promise<TelemetryConfig>;
+/**
+ * Enable telemetry.
+ * Updates the global config file to enable telemetry.
+ * This function never throws - fails silently on errors.
+ */
+export declare function setTelemetryEnabled(enabled: boolean): Promise<void>;
+/**
+ * Check if telemetry is enabled.
+ * Checks environment variables and global config.
+ *
+ * @returns Promise resolving to true if telemetry is enabled, false otherwise
+ */
+export declare function isTelemetryEnabled(): Promise<boolean>;

package/dist/telemetry/config.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTelemetryEnabled = exports.setTelemetryEnabled = exports.getTelemetryConfig = void 0;
+/* eslint-disable no-undef */
+/* eslint-disable no-console */
+const LoggingInterface_1 = require("../LoggingInterface");
+const PersistedConfig_1 = require("../PersistedConfig");
+/**
+ * Get telemetry configuration with proper priority order.
+ * This function never throws - returns disabled config on any error.
+ *
+ * Priority order (highest to lowest):
+ * 1. Environment variable overrides (highest priority):
+ *    - CODEGEN_TELEMETRY_DISABLED / DO_NOT_TRACK: disable telemetry
+ *    - CODEGEN_TELEMETRY_ENDPOINT: custom analytics endpoint
+ *    - CODEGEN_TELEMETRY_ID: custom tracking ID
+ *    - CODEGEN_TELEMETRY_API_SECRET: custom API secret
+ * 2. Project-level config (from codegen.config.js)
+ * 3. Global config file (~/.the-codegen-project/config.json)
+ *
+ * @param projectConfig - Optional project-level telemetry config from codegen.config.js
+ * @returns Promise resolving to telemetry configuration
+ */
+async function getTelemetryConfig(projectConfig) {
+    try {
+        const globalConfig = await (0, PersistedConfig_1.getGlobalConfig)();
+        const telemetryConfig = {
+            ...globalConfig.telemetry,
+            ...(projectConfig ?? {})
+        };
+        // Apply environment variable overrides (highest priority)
+        if (process.env.CODEGEN_TELEMETRY_DISABLED === '1' ||
+            process.env.DO_NOT_TRACK) {
+            telemetryConfig.enabled = false;
+        }
+        if (process.env.CODEGEN_TELEMETRY_ENDPOINT) {
+            telemetryConfig.endpoint = process.env.CODEGEN_TELEMETRY_ENDPOINT;
+        }
+        if (process.env.CODEGEN_TELEMETRY_ID) {
+            telemetryConfig.trackingId = process.env.CODEGEN_TELEMETRY_ID;
+        }
+        if (process.env.CODEGEN_TELEMETRY_API_SECRET) {
+            telemetryConfig.apiSecret = process.env.CODEGEN_TELEMETRY_API_SECRET;
+        }
+        return telemetryConfig;
+    }
+    catch (error) {
+        // On any error, return disabled config
+        if (process.env.CODEGEN_TELEMETRY_DEBUG === '1') {
+            LoggingInterface_1.Logger.error('Failed to get telemetry config:', error);
+        }
+        return createDisabledTelemetryConfig();
+    }
+}
+exports.getTelemetryConfig = getTelemetryConfig;
+/**
+ * Enable telemetry.
+ * Updates the global config file to enable telemetry.
+ * This function never throws - fails silently on errors.
+ */
+async function setTelemetryEnabled(enabled) {
+    try {
+        const globalConfig = await (0, PersistedConfig_1.getGlobalConfig)();
+        globalConfig.telemetry.enabled = enabled;
+        await (0, PersistedConfig_1.updateGlobalConfig)(globalConfig);
+    }
+    catch (error) {
+        if (process.env.CODEGEN_TELEMETRY_DEBUG === '1') {
+            LoggingInterface_1.Logger.error('Failed to set telemetry enabled state:', error);
+        }
+        // Fail silently
+    }
+}
+exports.setTelemetryEnabled = setTelemetryEnabled;
+/**
+ * Check if telemetry is enabled.
+ * Checks environment variables and global config.
+ *
+ * @returns Promise resolving to true if telemetry is enabled, false otherwise
+ */
+async function isTelemetryEnabled() {
+    const config = await getTelemetryConfig();
+    return config.enabled;
+}
+exports.isTelemetryEnabled = isTelemetryEnabled;
+/**
+ * Create a disabled telemetry configuration.
+ */
+function createDisabledTelemetryConfig() {
+    return {
+        enabled: false,
+        anonymousId: '',
+        endpoint: '',
+        trackingId: '',
+        apiSecret: ''
+    };
+}

package/dist/telemetry/events.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Telemetry event type definitions
+ */
+/**
+ * Base telemetry event interface
+ */
+export interface TelemetryEvent {
+    event: string;
+    [key: string]: any;
+}
+/**
+ * Command execution event
+ */
+export interface CommandExecutedEvent extends TelemetryEvent {
+    event: 'command_executed';
+    command: string;
+    flags: string[];
+    input_source?: 'remote_url' | 'local_relative' | 'local_absolute';
+    input_type?: 'asyncapi' | 'openapi' | 'jsonschema';
+    generators?: string[];
+    generator_count?: number;
+    duration: number;
+    success: boolean;
+    error_type?: string;
+    cli_version: string;
+    node_version: string;
+    os: string;
+    ci: boolean;
+}
+/**
+ * Generator usage event
+ */
+export interface GeneratorUsedEvent extends TelemetryEvent {
+    event: 'generator_used';
+    generator_type: string;
+    input_type: 'asyncapi' | 'openapi' | 'jsonschema';
+    input_source?: 'remote_url' | 'local_relative' | 'local_absolute';
+    language: string;
+    options: Record<string, any>;
+    duration: number;
+    success: boolean;
+}
+/**
+ * Init command event
+ */
+export interface InitExecutedEvent extends TelemetryEvent {
+    event: 'init_executed';
+    config_type: 'esm' | 'json' | 'yaml' | 'ts';
+    input_type?: string;
+    generators: string[];
+    language?: string;
+    completed: boolean;
+}
+/**
+ * Error event
+ */
+export interface ErrorOccurredEvent extends TelemetryEvent {
+    event: 'error_occurred';
+    command: string;
+    error_type: string;
+    error_code?: string;
+    cli_version: string;
+    node_version: string;
+}
+/**
+ * Watch mode event
+ */
+export interface WatchModeEvent extends TelemetryEvent {
+    event: 'watch_mode_started';
+    command: string;
+    watch_duration?: number;
+}

package/dist/telemetry/events.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Telemetry event type definitions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/telemetry/index.d.ts

@@ -0,0 +1,46 @@
+import { TelemetryEvent } from './events';
+import { ProjectTelemetryConfig } from '../codegen/types';
+export * from './events';
+export * from './config';
+export * from './anonymize';
+export * from './collector';
+/**
+ * Track a telemetry event.
+ *
+ * **IMPORTANT**: This function is designed to NEVER throw or reject.
+ * It is safe to call without .catch() or try/catch.
+ * All errors are handled internally and logged only in debug mode.
+ *
+ * The function automatically:
+ * - Shows first-run notice if needed
+ * - Adds system information to the event
+ * - Applies project-level config overrides if provided
+ * - Sends the event to the configured endpoint
+ * - Handles all errors gracefully
+ *
+ * Priority order for configuration:
+ * 1. Environment variables (highest priority)
+ * 2. Project-level config (from codegen.config.js)
+ * 3. Global config (from ~/.the-codegen-project/config.json)
+ *
+ * @param event - The event data to track
+ * @param projectConfig - Optional project-level telemetry config from codegen.config.js
+ * @returns Promise that always resolves (never rejects)
+ *
+ * @example
+ * ```typescript
+ * // Fire and forget - safe to call without await or .catch()
+ * void trackEvent({
+ *   event: 'command_executed',
+ *   command: 'generate',
+ *   success: true
+ * });
+ *
+ * // With project config override
+ * void trackEvent({
+ *   event: 'generator_used',
+ *   generator_type: 'payloads'
+ * }, config.telemetry);
+ * ```
+ */
+export declare function trackEvent(event: TelemetryEvent, projectConfig?: ProjectTelemetryConfig): Promise<void>;

package/dist/telemetry/index.js

@@ -0,0 +1,91 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trackEvent = void 0;
+/* eslint-disable no-undef */
+/* eslint-disable no-console */
+const sender_1 = require("./sender");
+const notice_1 = require("./notice");
+const collector_1 = require("./collector");
+const LoggingInterface_1 = require("../LoggingInterface");
+__exportStar(require("./events"), exports);
+__exportStar(require("./config"), exports);
+__exportStar(require("./anonymize"), exports);
+__exportStar(require("./collector"), exports);
+/**
+ * Track a telemetry event.
+ *
+ * **IMPORTANT**: This function is designed to NEVER throw or reject.
+ * It is safe to call without .catch() or try/catch.
+ * All errors are handled internally and logged only in debug mode.
+ *
+ * The function automatically:
+ * - Shows first-run notice if needed
+ * - Adds system information to the event
+ * - Applies project-level config overrides if provided
+ * - Sends the event to the configured endpoint
+ * - Handles all errors gracefully
+ *
+ * Priority order for configuration:
+ * 1. Environment variables (highest priority)
+ * 2. Project-level config (from codegen.config.js)
+ * 3. Global config (from ~/.the-codegen-project/config.json)
+ *
+ * @param event - The event data to track
+ * @param projectConfig - Optional project-level telemetry config from codegen.config.js
+ * @returns Promise that always resolves (never rejects)
+ *
+ * @example
+ * ```typescript
+ * // Fire and forget - safe to call without await or .catch()
+ * void trackEvent({
+ *   event: 'command_executed',
+ *   command: 'generate',
+ *   success: true
+ * });
+ *
+ * // With project config override
+ * void trackEvent({
+ *   event: 'generator_used',
+ *   generator_type: 'payloads'
+ * }, config.telemetry);
+ * ```
+ */
+async function trackEvent(event, projectConfig) {
+    try {
+        // Debug mode: log the event being tracked
+        if (process.env.CODEGEN_TELEMETRY_DEBUG === '1') {
+            LoggingInterface_1.Logger.info('[Telemetry Debug] Tracking event:', JSON.stringify(event, null, 2));
+        }
+        // Show notice on first run (also safe, never throws)
+        await (0, notice_1.showTelemetryNoticeIfNeeded)();
+        // Add system information to event
+        const enrichedEvent = {
+            ...event,
+            ...(0, collector_1.collectSystemInfo)()
+        };
+        // Send event with project config (also safe, never throws)
+        await (0, sender_1.sendEvent)(enrichedEvent, projectConfig);
+    }
+    catch (error) {
+        // This should never happen, but just in case
+        if (process.env.CODEGEN_TELEMETRY_DEBUG === '1') {
+            LoggingInterface_1.Logger.error('[Telemetry Debug] Unexpected error in trackEvent:', error);
+        }
+        // Always resolve
+    }
+}
+exports.trackEvent = trackEvent;

package/dist/telemetry/notice.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Show telemetry notice on first run.
+ * This function never throws - fails silently on errors.
+ *
+ * The notice informs users that telemetry is enabled and how to disable it.
+ * After showing the notice once, it sets a flag to prevent showing it again.
+ */
+export declare function showTelemetryNoticeIfNeeded(): Promise<void>;

package/dist/telemetry/notice.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.showTelemetryNoticeIfNeeded = void 0;
+/* eslint-disable no-undef */
+/* eslint-disable no-console */
+const PersistedConfig_1 = require("../PersistedConfig");
+const LoggingInterface_1 = require("../LoggingInterface");
+/**
+ * Show telemetry notice on first run.
+ * This function never throws - fails silently on errors.
+ *
+ * The notice informs users that telemetry is enabled and how to disable it.
+ * After showing the notice once, it sets a flag to prevent showing it again.
+ */
+async function showTelemetryNoticeIfNeeded() {
+    try {
+        const globalConfig = await (0, PersistedConfig_1.getGlobalConfig)();
+        // Skip if already shown or if telemetry is disabled
+        if (globalConfig.hasShownTelemetryNotice ||
+            !globalConfig.telemetry.enabled) {
+            return;
+        }
+        // Skip in CI environments (no need to show notice)
+        if (process.env.CI === 'true' || process.env.CI === '1') {
+            return;
+        }
+        // Show the notice
+        LoggingInterface_1.Logger.info(`
+┌─────────────────────────────────────────────────────────────┐
+│                                                             │
+│  The Codegen Project CLI collects anonymous usage data      │
+│  to help us improve the tool.                               │
+│                                                             │
+│  To disable: codegen telemetry disable                      │
+│  Learn more: https://the-codegen-project.org/docs/telemetry │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+`);
+        // Mark as shown
+        globalConfig.hasShownTelemetryNotice = true;
+        await (0, PersistedConfig_1.updateGlobalConfig)(globalConfig);
+    }
+    catch (error) {
+        // Fail silently - notice is not critical
+        if (process.env.CODEGEN_TELEMETRY_DEBUG === '1') {
+            LoggingInterface_1.Logger.error('[Telemetry Debug] Failed to show notice:', error);
+        }
+    }
+}
+exports.showTelemetryNoticeIfNeeded = showTelemetryNoticeIfNeeded;