@uipath/common 0.2.0 → 0.9.1

package/dist/telemetry/telemetry-service.d.ts

@@ -0,0 +1,157 @@
+import type { IContextStorage } from "./context-storage.js";
+import type { ITelemetryProvider } from "./telemetry-provider.js";
+/**
+ * Properties that can be attached to telemetry events
+ */
+export interface TelemetryProperties {
+    [key: string]: string | number | boolean | undefined;
+}
+/**
+ * Telemetry correlation context for tracking parent-child relationships
+ */
+export interface TelemetryContext {
+    /**
+     * Operation ID - unique identifier for the entire operation tree
+     */
+    operationId: string;
+    /**
+     * Parent ID - identifier of the parent operation (for correlation)
+     */
+    parentId?: string;
+    /**
+     * Current operation ID - identifier for this specific operation
+     */
+    id: string;
+}
+/**
+ * Interface for tracking telemetry events.
+ *
+ * @remarks
+ * Telemetry context (operationId, parentId) is managed automatically using IContextStorage.
+ * You don't need to pass context around - it's stored and retrieved automatically.
+ *
+ * Once a `trackRequest` is called, all subsequent telemetry operations (trackEvent,
+ * trackException, trackDependencyOperation) within the same async execution context
+ * will automatically include the operationId for correlation. This enables full
+ * distributed tracing and operation correlation across the entire request tree.
+ */
+export interface ITelemetryService {
+    /**
+     * Sets the operation ID for telemetry correlation.
+     * @param operationId - The operation ID to set, or undefined to clear it
+     *
+     * @remarks
+     * This method allows setting a custom operation ID that will be used by trackRequest
+     * if provided. If not set, trackRequest will generate a new operation ID automatically.
+     */
+    setOperationId(operationId: string | undefined): void;
+    /**
+     * Replaces the telemetry provider at runtime.
+     * @param provider - The new telemetry provider to use
+     *
+     * @remarks
+     * Useful for switching between providers (e.g. AppInsights vs Console) without
+     * recreating the service. Default properties and operation context are preserved.
+     */
+    setProvider(provider: ITelemetryProvider): void;
+    /**
+     * Sets default properties that will be included in all telemetry entries.
+     * @param properties - The default properties to set. Pass undefined to clear.
+     *
+     * @remarks
+     * These properties are merged into every telemetry call (trackEvent, trackException,
+     * trackRequest, trackDependencyOperation). Per-call properties take precedence
+     * over default properties when there are key conflicts.
+     */
+    setDefaultProperties(properties?: TelemetryProperties): void;
+    /**
+     * Track a telemetry event
+     * @param name - The name of the event
+     * @param properties - Optional properties to attach to the event
+     *
+     * @remarks
+     * If called within a trackRequest block, automatically includes operationId for correlation.
+     */
+    trackEvent(name: string, properties?: TelemetryProperties): void;
+    /**
+     * Track an exception
+     * @param error - The error to track
+     * @param properties - Optional properties to attach to the exception
+     *
+     * @remarks
+     * If called within a trackRequest block, automatically includes operationId for correlation.
+     */
+    trackException(error: Error, properties?: TelemetryProperties): void;
+    /**
+     * Track a request operation (top-level operation in the dependency tree).
+     * Use this for main entry point.
+     *
+     * @template T The return type of the function
+     * @param name The request name (e.g., 'PackSolution')
+     * @param fn The async function to execute and track
+     * @param properties Base properties to include in telemetry
+     * @returns A promise that resolves to the function result
+     *
+     * @remarks
+     * Creates a new operation ID and tracks this as a request in Application Insights.
+     * All nested trackDependencyOperation calls will be automatically correlated to this request.
+     */
+    trackRequest<T>(name: string, fn: () => Promise<T>, properties?: TelemetryProperties): Promise<T>;
+    /**
+     * Track a dependency operation (child operation in the dependency tree).
+     * Use this for operations that are part of a larger request.
+     *
+     * @template T The return type of the function
+     * @param name The dependency name
+     * @param type The dependency type
+     * @param fn The async function to execute and track
+     * @param properties Base properties to include in telemetry
+     * @returns A promise that resolves to the function result
+     *
+     * @remarks
+     * Tracks this operation as a dependency in Application Insights, automatically correlated
+     * to the parent request using the context from IContextStorage.
+     */
+    trackDependencyOperation<T>(name: string, type: string, fn: () => Promise<T>, properties?: TelemetryProperties): Promise<T>;
+}
+/**
+ * TelemetryService implementation that manages context storage and orchestrates telemetry operations.
+ * This service handles all common logic:
+ * - Context creation and correlation (operationId, id, parentId)
+ * - Duration measurement
+ * - Error handling and success/failure tracking
+ * - Context propagation via storage
+ *
+ * ITelemetryProvider implementations are simple adapters that receive pre-measured data.
+ */
+export declare class TelemetryService implements ITelemetryService {
+    private telemetryProvider;
+    private readonly contextStorage;
+    private operationId?;
+    private defaultProperties?;
+    constructor(telemetryProvider: ITelemetryProvider, contextStorage: IContextStorage<TelemetryContext>);
+    /**
+     * Sets the operation ID for telemetry correlation.
+     * @param operationId - The operation ID to set, or undefined to clear it
+     */
+    setOperationId(operationId: string | undefined): void;
+    setProvider(provider: ITelemetryProvider): void;
+    setDefaultProperties(properties?: TelemetryProperties): void;
+    trackEvent(name: string, properties?: TelemetryProperties): void;
+    trackException(error: Error, properties?: TelemetryProperties): void;
+    trackRequest<T>(name: string, fn: () => Promise<T>, properties?: TelemetryProperties): Promise<T>;
+    trackDependencyOperation<T>(name: string, type: string, fn: () => Promise<T>, properties?: TelemetryProperties): Promise<T>;
+    /**
+     * Gets the current telemetry context from the context storage.
+     * Returns undefined if no context is available (not within a trackRequest block).
+     */
+    private getCurrentContext;
+    /**
+     * Enriches properties with context information (operationId, parentId, id)
+     */
+    private enrichPropertiesWithContext;
+    /**
+     * Generate a unique ID for telemetry correlation
+     */
+    private generateId;
+}

package/dist/tool-provider.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Cross-module bridge for packager factory resolution.
+ */
+export type PackagerFactoryProvider = (verb: string) => Promise<void>;
+export declare function setPackagerFactoryProvider(provider: PackagerFactoryProvider): void;
+export declare function ensurePackagerFactory(verb: string): Promise<void>;

package/dist/trackedAction.d.ts

@@ -0,0 +1,38 @@
+import { Command } from "commander";
+import type { TelemetryProperties } from "./telemetry/telemetry-service.js";
+export interface CommandContext {
+    exit: (code: number) => void;
+    /** AbortSignal wired to SIGINT/SIGTERM. Pass to `pollUntil({ signal })` for graceful cancellation. */
+    pollSignal?: AbortSignal;
+}
+/**
+ * Default CommandContext for tool packages that sets process.exitCode
+ * instead of calling process.exit().
+ *
+ * `pollSignal` is resolved from globalThis so it works across bundle
+ * boundaries — the CLI sets it once, all tool bundles see the same signal.
+ */
+export declare const processContext: CommandContext;
+/**
+ * Wire an AbortSignal into the process-wide shared slot so all bundles
+ * of `@uipath/common` see it via `processContext.pollSignal`.
+ *
+ * Call once at CLI startup after creating the poll abort controller.
+ */
+export declare function setProcessContextPollSignal(signal: AbortSignal): void;
+/**
+ * Derives a telemetry event name from the command hierarchy.
+ * Walks up the parent chain, collects command names, strips the root,
+ * and always prepends "uip" so all events share a uniform prefix.
+ * Names are lowercase dot-separated, mirroring the CLI invocation.
+ *
+ * Example: `uip maestro processes list` → `"uip.maestro.processes.list"`
+ * Example: `uip login`                 → `"uip.login"`
+ */
+declare function deriveCommandPath(cmd: Command): string;
+declare module "commander" {
+    interface Command {
+        trackedAction(context: CommandContext, fn: (...args: any[]) => Promise<void>, properties?: TelemetryProperties | ((...args: any[]) => TelemetryProperties)): this;
+    }
+}
+export { deriveCommandPath };

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@uipath/common",
-    "version": "0.2.0",
-    "description": "Common infrastructure needed by uipcli tools.",
+    "version": "0.9.1",
+    "description": "Common infrastructure needed by uip tools.",
     "repository": {
         "type": "git",
         "url": "https://github.com/UiPath/cli.git",
@@ -13,7 +13,14 @@
     "type": "module",
     "main": "./dist/index.js",
     "exports": {
-        ".": "./dist/index.js"
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./telemetry": {
+            "types": "./dist/telemetry/index.d.ts",
+            "default": "./dist/telemetry/index.js"
+        }
     },
     "files": [
         "dist"
@@ -24,7 +31,7 @@
         "vlad-uipath"
     ],
     "scripts": {
-        "build": "bun build ./src/index.ts --outdir dist --format esm --target node --external applicationinsights",
+        "build": "bun build ./src/index.ts --outdir dist --format esm --target node --external applicationinsights && bun build ./src/telemetry/index.ts --outfile dist/telemetry/index.js --format esm --target browser && tsc -p tsconfig.build.json --noCheck",
         "typecheck": "tsc --noEmit",
         "lint": "biome check .",
         "test": "vitest run",
@@ -34,10 +41,11 @@
         "@jmespath-community/jmespath": "^1.3.0",
         "@types/js-yaml": "^4.0.9",
         "@types/node": "^25.5.0",
-        "@uipath/telemetry": "0.0.6",
+        "@uipath/filesystem": "0.9.1",
         "commander": "^14.0.3",
         "js-yaml": "^4.1.0",
         "jsonpath-plus": "^10.4.0",
         "typescript": "^5"
-    }
+    },
+    "gitHead": "e8da2857e37a9495c4907cd39f47c9d6ed1a5566"
 }