import { PostHog } from 'posthog-node'; export declare const CreateTinaAppStartedEvent: string; export declare const CreateTinaAppFinishedEvent: string; /** * Step names for tracking progress through the create-tina-app process */ export declare const TRACKING_STEPS: { readonly INIT: "initializing"; readonly PRE_RUN_CHECKS: "pre_run_checks"; readonly TELEMETRY_SETUP: "telemetry_setup"; readonly PKG_MANAGER_SELECT: "package_manager_selection"; readonly PROJECT_NAME_INPUT: "project_name_input"; readonly TEMPLATE_SELECT: "template_selection"; readonly THEME_SELECT: "theme_selection"; readonly DIRECTORY_SETUP: "directory_setup"; readonly DOWNLOADING_TEMPLATE: "downloading_template"; readonly UPDATING_METADATA: "updating_metadata"; readonly INSTALLING_PACKAGES: "installing_packages"; readonly GIT_INIT: "git_initialization"; readonly COMPLETE: "complete"; }; /** * Generate a unique session ID for this run */ export declare function generateSessionId(): string; /** * Get a hashed user ID based on system UUID * Returns a consistent anonymous identifier for the machine */ export declare function getAnonymousUserId(): Promise; /** * Structured error codes for categorizing failures */ export declare const ERROR_CODES: { readonly ERR_VAL_INVALID_TEMPLATE: "ERR_VAL_INVALID_TEMPLATE"; readonly ERR_VAL_INVALID_PKG_MANAGER: "ERR_VAL_INVALID_PKG_MANAGER"; readonly ERR_VAL_INVALID_PROJECT_NAME: "ERR_VAL_INVALID_PROJECT_NAME"; readonly ERR_VAL_INVALID_THEME: "ERR_VAL_INVALID_THEME"; readonly ERR_VAL_UNSUPPORTED_NODE: "ERR_VAL_UNSUPPORTED_NODE"; readonly ERR_VAL_NO_PKG_MANAGERS: "ERR_VAL_NO_PKG_MANAGERS"; readonly ERR_FS_NOT_WRITABLE: "ERR_FS_NOT_WRITABLE"; readonly ERR_FS_HAS_CONFLICTS: "ERR_FS_HAS_CONFLICTS"; readonly ERR_FS_MKDIR_FAILED: "ERR_FS_MKDIR_FAILED"; readonly ERR_FS_CHDIR_FAILED: "ERR_FS_CHDIR_FAILED"; readonly ERR_FS_READ_PACKAGE_JSON: "ERR_FS_READ_PACKAGE_JSON"; readonly ERR_FS_WRITE_PACKAGE_JSON: "ERR_FS_WRITE_PACKAGE_JSON"; readonly ERR_FS_UPDATE_THEME_FAILED: "ERR_FS_UPDATE_THEME_FAILED"; readonly ERR_FS_COPY_TEMPLATE_FAILED: "ERR_FS_COPY_TEMPLATE_FAILED"; readonly ERR_NET_POSTHOG_CONFIG_FETCH: "ERR_NET_POSTHOG_CONFIG_FETCH"; readonly ERR_NET_TARBALL_DOWNLOAD: "ERR_NET_TARBALL_DOWNLOAD"; readonly ERR_NET_GITHUB_API_FAILED: "ERR_NET_GITHUB_API_FAILED"; readonly ERR_NET_REPO_INFO_NOT_FOUND: "ERR_NET_REPO_INFO_NOT_FOUND"; readonly ERR_NET_REPO_INVALID_URL: "ERR_NET_REPO_INVALID_URL"; readonly ERR_NET_TARBALL_EXTRACT: "ERR_NET_TARBALL_EXTRACT"; readonly ERR_INSTALL_PKG_MANAGER_FAILED: "ERR_INSTALL_PKG_MANAGER_FAILED"; readonly ERR_INSTALL_PKG_MANAGER_NOT_FOUND: "ERR_INSTALL_PKG_MANAGER_NOT_FOUND"; readonly ERR_INSTALL_SPAWN_ERROR: "ERR_INSTALL_SPAWN_ERROR"; readonly ERR_INSTALL_TIMEOUT: "ERR_INSTALL_TIMEOUT"; readonly ERR_GIT_NOT_INSTALLED: "ERR_GIT_NOT_INSTALLED"; readonly ERR_GIT_INIT_FAILED: "ERR_GIT_INIT_FAILED"; readonly ERR_GIT_ADD_FAILED: "ERR_GIT_ADD_FAILED"; readonly ERR_GIT_COMMIT_FAILED: "ERR_GIT_COMMIT_FAILED"; readonly ERR_GIT_CHECKOUT_FAILED: "ERR_GIT_CHECKOUT_FAILED"; readonly ERR_GIT_ALREADY_INITIALIZED: "ERR_GIT_ALREADY_INITIALIZED"; readonly ERR_CANCEL_PKG_MANAGER_PROMPT: "ERR_CANCEL_PKG_MANAGER_PROMPT"; readonly ERR_CANCEL_PROJECT_NAME_PROMPT: "ERR_CANCEL_PROJECT_NAME_PROMPT"; readonly ERR_CANCEL_TEMPLATE_PROMPT: "ERR_CANCEL_TEMPLATE_PROMPT"; readonly ERR_CANCEL_THEME_PROMPT: "ERR_CANCEL_THEME_PROMPT"; readonly ERR_CANCEL_SIGINT: "ERR_CANCEL_SIGINT"; readonly ERR_CFG_POSTHOG_INIT_FAILED: "ERR_CFG_POSTHOG_INIT_FAILED"; readonly ERR_CFG_OSINFO_FETCH_FAILED: "ERR_CFG_OSINFO_FETCH_FAILED"; readonly ERR_CFG_TELEMETRY_SETUP_FAILED: "ERR_CFG_TELEMETRY_SETUP_FAILED"; readonly ERR_TPL_DOWNLOAD_FAILED: "ERR_TPL_DOWNLOAD_FAILED"; readonly ERR_TPL_EXTRACT_FAILED: "ERR_TPL_EXTRACT_FAILED"; readonly ERR_TPL_METADATA_UPDATE_FAILED: "ERR_TPL_METADATA_UPDATE_FAILED"; readonly ERR_TPL_INTERNAL_COPY_FAILED: "ERR_TPL_INTERNAL_COPY_FAILED"; readonly ERR_TPL_THEME_UPDATE_FAILED: "ERR_TPL_THEME_UPDATE_FAILED"; readonly ERR_UNCAUGHT: "ERR_UNCAUGHT"; }; /** * Sends an event to PostHog for analytics tracking. * * @param client - The PostHog client instance used to send the event * @param distinctId - A unique identifier for the user (hashed system UUID) * @param sessionId - A unique identifier for this run/session * @param event - The name of the event to track (e.g., 'create-tina-app-started') * @param properties - Additional properties to include with the event * * @remarks * - Returns early if the PostHog client is not provided * - Skips sending data when `TINA_DEV` environment variable is set to 'true' * - Automatically adds a 'system' property with value 'tinacms/create-tina-app' * - Includes sessionId in properties to track individual runs * - Uses hashed system UUID as distinctId to track unique users anonymously * - Logs errors to console if event capture fails * * @example * ```typescript * const client = new PostHog('api-key'); * const userId = await getAnonymousUserId(); * const sessionId = generateSessionId(); * postHogCapture(client, userId, sessionId, 'create-tina-app-started', { * template: 'basic', * typescript: true * }); * ``` */ export declare function postHogCapture(client: PostHog, distinctId: string, sessionId: string, event: string, properties: Record): void; /** * Capture an error event in PostHog with categorized tracking and sanitized stack traces * * @param client - The PostHog client instance * @param distinctId - A unique identifier for the user (hashed system UUID) * @param sessionId - A unique identifier for this run/session * @param error - The error object that was thrown * @param context - Context about the error including code, category, step, and additional properties * * @remarks * - Sanitizes stack traces to remove local file paths * - Maps error categories to three event types: * - 'create-tina-app-error' for technical failures (filesystem, network, installation, git, etc.) * - 'create-tina-app-validation-error' for user input validation issues * - 'create-tina-app-user-cancelled' for user cancellations (Ctrl+C) * - Includes error code, sanitized stack, step name, and telemetry data in properties * - Non-fatal errors are tracked but allow the process to continue * * @example * ```typescript * try { * await downloadTemplate(); * } catch (err) { * postHogCaptureError(client, userId, sessionId, err as Error, { * errorCode: ERROR_CODES.ERR_TPL_DOWNLOAD_FAILED, * errorCategory: 'template', * step: TRACKING_STEPS.DOWNLOADING_TEMPLATE, * fatal: true, * additionalProperties: { template: 'basic' } * }); * } * ``` */ export declare function postHogCaptureError(client: PostHog | null, distinctId: string, sessionId: string, error: Error, context: { errorCode: string; errorCategory: string; step: string; fatal?: boolean; additionalProperties?: Record; }): void;