@uipath/common 1.195.0 → 1.197.0-preview.59

package/dist/interactivity-context.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Process-wide interactivity mode.
+ *
+ * The CLI prompts by default only when both stdout and stdin are attached to an
+ * interactive terminal. An automation agent or CI runner can never answer a
+ * `y/N` prompt, so piped input or redirected output stays non-interactive.
+ * Commands consult {@link canPrompt} before showing any optional/selection
+ * prompt; when it returns `false` they must fall back to a flag-driven path or
+ * fail fast with a structured error naming the flag to pass.
+ *
+ * Modes:
+ *   - "never"  — never prompt.
+ *   - "auto"   — prompt only when stdout and stdin are TTYs (the default).
+ *   - "always" — always prompt (assume a prompt-capable terminal).
+ *
+ * Stored via {@link singleton} so the value set once by the CLI host is visible
+ * from every tool bundle's own copy of `@uipath/common`.
+ *
+ * Note: destructive confirmation does NOT use this — it is flag-only and
+ * fail-closed (see `confirmation.ts`). Interactivity governs *optional* prompts.
+ */
+export type InteractivityMode = "never" | "auto" | "always";
+/** Set the process-wide interactivity mode. Called once at CLI startup. */
+export declare function setInteractivityMode(mode: InteractivityMode): void;
+/** Get the current interactivity mode, defaulting to "auto". */
+export declare function getInteractivityMode(): InteractivityMode;
+/**
+ * True when the CLI may show an interactive prompt right now.
+ *
+ * "always" always prompts; "never" never does; "auto" prompts only when the
+ * output sink reports an interactive (TTY) terminal and prompt-readable stdin.
+ */
+export declare function canPrompt(): boolean;

package/dist/output-sink.d.ts

@@ -14,8 +14,10 @@ export interface OutputSink {
     readonly capabilities: SinkCapabilities;
 }
 export interface SinkCapabilities {
-    /** True when a human is reading (TTY). False for piped, MCP, browser. */
+    /** True when stdout is a TTY. False for piped output, MCP, browser. */
     isInteractive: boolean;
+    /** True when stdin can be read interactively (TTY). False for piped input. */
+    canReadInput: boolean;
     /** True when ANSI escape codes are supported. */
     supportsColor: boolean;
     /** Terminal width, or a sensible default (80/120). */

package/dist/package-metadata-options.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared package-traceability metadata options for `pack` commands.
+ *
+ */
+import type { Command } from "commander";
+/**
+ * Raw camelCased values commander produces for the shared metadata options.
+ * Commands extend their own option interface with this.
+ */
+export interface PackageMetadataCliOptions {
+    author?: string;
+    description?: string;
+    repositoryUrl?: string;
+    repositoryCommit?: string;
+    repositoryBranch?: string;
+    repositoryType?: string;
+    releaseNotes?: string;
+    projectUrl?: string;
+}
+/**
+ * Subset of `NugetPackageInfo` fields produced from the metadata options.
+ * Only defined fields are present so spreading this into a package literal
+ * never clobbers existing defaults with `undefined`.
+ */
+export type PackageMetadataFields = PackageMetadataCliOptions;
+/**
+ * Register the shared package-metadata options on a commander command.
+ * Returns the command for chaining.
+ */
+export declare function registerPackageMetadataOptions(command: Command): Command;
+/**
+ * Map parsed metadata options to the `NugetPackageInfo` fields the packager
+ * understands. Returns only fields the user actually supplied, and defaults
+ * `repositoryType` to `"git"` when a `repositoryUrl` is given but no type —
+ * the nuspec generator only emits the `<repository>` element when both type
+ * and url are present.
+ */
+export declare function mapPackageMetadataOptions(opts: PackageMetadataCliOptions): PackageMetadataFields;

package/dist/package-metadata-options.js

@@ -0,0 +1,33 @@
+// src/package-metadata-options.ts
+function registerPackageMetadataOptions(command) {
+  return command.option("--author <author>", "Package author").option("--description <text>", "Package description").option("--repository-url <url>", "Source repository URL (recorded in the package for traceability)").option("--repository-commit <sha>", "Source repository commit hash (recorded in the package for traceability)").option("--repository-branch <branch>", "Source repository branch").option("--repository-type <type>", "Source repository type (defaults to 'git' when --repository-url is set)").option("--release-notes <text>", "Release notes for the package").option("--project-url <url>", "Automation Hub idea URL");
+}
+function mapPackageMetadataOptions(opts) {
+  const fields = {};
+  if (opts.author !== undefined)
+    fields.author = opts.author;
+  if (opts.description !== undefined)
+    fields.description = opts.description;
+  if (opts.releaseNotes !== undefined)
+    fields.releaseNotes = opts.releaseNotes;
+  if (opts.projectUrl !== undefined)
+    fields.projectUrl = opts.projectUrl;
+  if (opts.repositoryUrl !== undefined)
+    fields.repositoryUrl = opts.repositoryUrl;
+  if (opts.repositoryCommit !== undefined)
+    fields.repositoryCommit = opts.repositoryCommit;
+  if (opts.repositoryBranch !== undefined)
+    fields.repositoryBranch = opts.repositoryBranch;
+  if (opts.repositoryType !== undefined)
+    fields.repositoryType = opts.repositoryType;
+  if (fields.repositoryUrl !== undefined && fields.repositoryType === undefined) {
+    fields.repositoryType = "git";
+  }
+  return fields;
+}
+export {
+  registerPackageMetadataOptions,
+  mapPackageMetadataOptions
+};
+
+//# debugId=D76F2616EBFEF0E864756E2164756E21

package/dist/preview.d.ts

@@ -0,0 +1,53 @@
+import { type CommandOptions } from "commander";
+/**
+ * Publish whether the running CLI is a preview build. Called once by the CLI
+ * host during startup, before any command (root or tool) is registered.
+ *
+ * "Preview" means the CLI binary's own version (`pkg.version`) carries any
+ * prerelease tag — `alpha`, `beta`, or `preview`. The host computes that from
+ * its version alone; this module stays free of any version-parsing logic so
+ * it can ship in every tool bundle.
+ */
+export declare function setPreviewBuild(isPreview: boolean): void;
+/**
+ * True when the running CLI is a preview (prerelease) build.
+ *
+ * Defaults to `false` when the host never called {@link setPreviewBuild} —
+ * e.g. a tool's unit tests that don't boot the CLI host — so preview-only
+ * commands stay unregistered unless a preview build explicitly opted in.
+ */
+export declare function isPreviewBuild(): boolean;
+/**
+ * Register a command (or run any setup) only on preview builds.
+ *
+ * Ergonomic guard for `registerCommands`: on a stable build `register` is
+ * never called, so the command is not added to Commander at all — invoking it
+ * yields the standard "unknown command" error. On a preview build it
+ * registers normally.
+ *
+ *   export const registerCommands = async (program: Command) => {
+ *       registerStableCommand(program);
+ *       previewOnly(() => registerExperimentalCommand(program));
+ *   };
+ */
+export declare function previewOnly(register: () => void): void;
+declare module "commander" {
+    interface Command {
+        /**
+         * Drop-in for `.command(nameAndArgs, opts)` that attaches the
+         * subcommand only on preview (prerelease) builds.
+         *
+         * On a preview build it behaves exactly like `.command(...)`. On a
+         * stable build it returns a *detached* Command: the chained
+         * `.description()` / `.option()` / `.trackedAction()` calls still
+         * type-check and run, but the command is never added to this program,
+         * so invoking it yields the standard "unknown command" error.
+         *
+         *   entities
+         *       .previewCommand("bulk-import <file>")
+         *       .description("experimental bulk import")
+         *       .trackedAction(processContext, async () => { ... });
+         */
+        previewCommand(nameAndArgs: string, opts?: CommandOptions): Command;
+    }
+}

package/dist/sdk-user-agent.d.ts

@@ -5,8 +5,21 @@ export interface SdkUserAgentPackageInfo {
 export type SdkHttpHeaders = Record<string, string>;
 export declare function getSdkUserAgentToken(pkg: SdkUserAgentPackageInfo): string;
 export declare function setSdkUserAgentHostToken(token: string | undefined): void;
+/**
+ * Forwards the SDK `User-Agent` token, prefixed with the host token (e.g.
+ * `uip/1.1.0`) when one is configured. Appends to any existing value without
+ * duplicating tokens and preserves the caller's header casing.
+ */
 export declare function addSdkUserAgentHeader(headers: SdkHttpHeaders | undefined, userAgent: string): SdkHttpHeaders;
-export declare function withSdkUserAgentHeader(headers: unknown, userAgent: string): unknown;
+/**
+ * Forwards the telemetry `agent` via `x-coding-agent-info` as a JSON envelope —
+ * `{"CodingAgent":"<agent>"}`; preserves the caller's header casing.
+ * Leaves the header absent when no agent is available.
+ */
+export declare function addSdkCodingAgentHeader(headers: SdkHttpHeaders | undefined, agent?: string | undefined): SdkHttpHeaders;
 export declare function installSdkUserAgentHeader(BaseApiClass: {
     prototype: unknown;
 }, userAgent: string): void;
+export declare function installSdkCodingAgentHeader(BaseApiClass: {
+    prototype: unknown;
+}): void;

package/dist/sdk-user-agent.js

@@ -28,12 +28,30 @@ function singleton(ctorOrName) {
   };
 }
 
+// src/telemetry/global-telemetry-properties.ts
+var telemetryPropsSlot = singleton("TelemetryDefaultProps");
+function getGlobalTelemetryProperties() {
+  return telemetryPropsSlot.get();
+}
+
+// src/telemetry/telemetry-config.ts
+function isTelemetryDisabled() {
+  const value = process.env.UIPATH_TELEMETRY_DISABLED;
+  return value === "1" || value === "true";
+}
+
 // src/sdk-user-agent.ts
 var USER_AGENT_HEADER = "User-Agent";
+var CODING_AGENT_HEADER = "x-coding-agent-info";
+var AGENT_PROPERTY = "agent";
+var CODING_AGENT_PROPERTY = "CodingAgent";
 var sdkUserAgentHostToken = singleton("SdkUserAgentHostToken");
 function userAgentPatchKey(userAgent) {
   return Symbol.for(`@uipath/common/sdk-user-agent/${userAgent}`);
 }
+function codingAgentPatchKey() {
+  return Symbol.for("@uipath/common/sdk-coding-agent");
+}
 function splitUserAgentTokens(value) {
   return value?.trim().split(/\s+/).filter(Boolean) ?? [];
 }
@@ -51,8 +69,15 @@ function appendUserAgentToken(value, userAgent) {
 function getEffectiveUserAgent(userAgent) {
   return appendUserAgentToken(sdkUserAgentHostToken.get(), userAgent);
 }
-function isHeadersLike(headers) {
-  return typeof headers === "object" && headers !== null && "get" in headers && typeof headers.get === "function" && "set" in headers && typeof headers.set === "function";
+function getHeaderName(headers, headerName) {
+  return Object.keys(headers).find((key) => key.toLowerCase() === headerName.toLowerCase());
+}
+function getSdkAgentInfo() {
+  if (isTelemetryDisabled()) {
+    return;
+  }
+  const agent = getGlobalTelemetryProperties()?.[AGENT_PROPERTY];
+  return agent === undefined ? undefined : String(agent);
 }
 function getSdkUserAgentToken(pkg) {
   const packageName = pkg.name.replace(/^@uipath\//, "");
@@ -67,59 +92,42 @@ function setSdkUserAgentHostToken(token) {
 }
 function addSdkUserAgentHeader(headers, userAgent) {
   const result = { ...headers ?? {} };
-  const effectiveUserAgent = getEffectiveUserAgent(userAgent);
-  const headerName = Object.keys(result).find((key) => key.toLowerCase() === USER_AGENT_HEADER.toLowerCase());
-  if (headerName) {
-    result[headerName] = appendUserAgentToken(result[headerName], effectiveUserAgent);
-  } else {
-    result[USER_AGENT_HEADER] = effectiveUserAgent;
-  }
+  const headerName = getHeaderName(result, USER_AGENT_HEADER);
+  result[headerName ?? USER_AGENT_HEADER] = appendUserAgentToken(headerName ? result[headerName] : undefined, getEffectiveUserAgent(userAgent));
   return result;
 }
-function withSdkUserAgentHeader(headers, userAgent) {
-  const effectiveUserAgent = getEffectiveUserAgent(userAgent);
-  if (isHeadersLike(headers)) {
-    headers.set(USER_AGENT_HEADER, appendUserAgentToken(headers.get(USER_AGENT_HEADER), effectiveUserAgent));
-    return headers;
-  }
-  if (Array.isArray(headers)) {
-    const result = headers.map((entry) => {
-      const [key, value] = entry;
-      return [key, value];
-    });
-    const headerIndex = result.findIndex(([key]) => key.toLowerCase() === USER_AGENT_HEADER.toLowerCase());
-    if (headerIndex >= 0) {
-      const [key, value] = result[headerIndex];
-      result[headerIndex] = [
-        key,
-        appendUserAgentToken(value, effectiveUserAgent)
-      ];
-    } else {
-      result.push([USER_AGENT_HEADER, effectiveUserAgent]);
-    }
+function addSdkCodingAgentHeader(headers, agent = getSdkAgentInfo()) {
+  const result = { ...headers ?? {} };
+  if (agent === undefined) {
     return result;
   }
-  return addSdkUserAgentHeader(typeof headers === "object" && headers !== null ? { ...headers } : {}, effectiveUserAgent);
+  const headerName = getHeaderName(result, CODING_AGENT_HEADER);
+  result[headerName ?? CODING_AGENT_HEADER] = JSON.stringify({
+    [CODING_AGENT_PROPERTY]: agent
+  });
+  return result;
+}
+function asHeaderRecord(headers) {
+  return typeof headers === "object" && headers !== null ? { ...headers } : {};
 }
-function withUserAgentInitOverride(initOverrides, userAgent) {
+function withForwardedHeadersInitOverride(initOverrides, forward) {
   return async (requestContext) => {
-    const initWithUserAgent = {
+    const initWithHeaders = {
       ...requestContext.init,
-      headers: withSdkUserAgentHeader(requestContext.init.headers, userAgent)
+      headers: forward(asHeaderRecord(requestContext.init.headers))
     };
     const override = typeof initOverrides === "function" ? await initOverrides({
       ...requestContext,
-      init: initWithUserAgent
+      init: initWithHeaders
     }) : initOverrides;
     return {
       ...override ?? {},
-      headers: withSdkUserAgentHeader(override?.headers ?? initWithUserAgent.headers, userAgent)
+      headers: forward(asHeaderRecord(override?.headers ?? initWithHeaders.headers))
     };
   };
 }
-function installSdkUserAgentHeader(BaseApiClass, userAgent) {
+function installRequestHeaderForwarding(BaseApiClass, patchKey, forward) {
   const prototype = BaseApiClass.prototype;
-  const patchKey = userAgentPatchKey(userAgent);
   if (prototype[patchKey]) {
     return;
   }
@@ -127,17 +135,26 @@ function installSdkUserAgentHeader(BaseApiClass, userAgent) {
     throw new Error("Generated BaseAPI request function not found.");
   }
   const originalRequest = prototype.request;
-  prototype.request = function requestWithUserAgent(context, initOverrides) {
-    return originalRequest.call(this, context, withUserAgentInitOverride(initOverrides, userAgent));
+  prototype.request = function requestWithForwardedHeaders(context, initOverrides) {
+    return originalRequest.call(this, context, withForwardedHeadersInitOverride(initOverrides, forward));
   };
   Object.defineProperty(prototype, patchKey, {
     value: true
   });
 }
+function installSdkUserAgentHeader(BaseApiClass, userAgent) {
+  installRequestHeaderForwarding(BaseApiClass, userAgentPatchKey(userAgent), (headers) => addSdkUserAgentHeader(headers, userAgent));
+}
+function installSdkCodingAgentHeader(BaseApiClass) {
+  installRequestHeaderForwarding(BaseApiClass, codingAgentPatchKey(), (headers) => addSdkCodingAgentHeader(headers));
+}
 export {
-  withSdkUserAgentHeader,
   setSdkUserAgentHostToken,
   installSdkUserAgentHeader,
+  installSdkCodingAgentHeader,
   getSdkUserAgentToken,
-  addSdkUserAgentHeader
+  addSdkUserAgentHeader,
+  addSdkCodingAgentHeader
 };
+
+//# debugId=9DC7523199926B8364756E2164756E21

package/dist/stdin.d.ts

@@ -0,0 +1 @@
+export declare function readStdin(): Promise<string | null>;

package/dist/telemetry/global-telemetry-properties.d.ts

@@ -0,0 +1,8 @@
+import type { TelemetryProperties } from "./telemetry-service.js";
+/**
+ * Merge `properties` into the shared global base properties.
+ * Existing keys are preserved unless overwritten by `properties`, so callers
+ * can contribute base props incrementally (e.g. agent first, then auth context).
+ */
+export declare function setGlobalTelemetryProperties(properties: TelemetryProperties): void;
+export declare function getGlobalTelemetryProperties(): TelemetryProperties | undefined;

package/dist/telemetry/index.js

@@ -159,6 +159,42 @@ function redactProperties(properties) {
   }
   return out;
 }
+// src/singleton.ts
+var PREFIX = "@uipath/common/";
+var _g = globalThis;
+function singleton(ctorOrName) {
+  const name = typeof ctorOrName === "string" ? ctorOrName : ctorOrName.name;
+  const key = Symbol.for(PREFIX + name);
+  return {
+    get(fallback) {
+      return _g[key] ?? fallback;
+    },
+    set(value) {
+      _g[key] = value;
+    },
+    clear() {
+      delete _g[key];
+    },
+    getOrInit(factory, guard) {
+      const existing = _g[key];
+      if (existing != null && typeof existing === "object") {
+        if (!guard || guard(existing)) {
+          return existing;
+        }
+      }
+      const instance = factory();
+      _g[key] = instance;
+      return instance;
+    }
+  };
+}
+
+// src/telemetry/global-telemetry-properties.ts
+var telemetryPropsSlot = singleton("TelemetryDefaultProps");
+function getGlobalTelemetryProperties() {
+  return telemetryPropsSlot.get();
+}
+
 // src/telemetry/telemetry-service.ts
 class TelemetryService {
   telemetryProvider;
@@ -176,7 +212,7 @@ class TelemetryService {
     this.telemetryProvider = provider;
   }
   setDefaultProperties(properties) {
-    this.defaultProperties = properties;
+    this.defaultProperties = properties === undefined ? undefined : { ...this.defaultProperties, ...properties };
   }
   trackEvent(name, properties) {
     const context = this.getCurrentContext();
@@ -238,6 +274,7 @@ class TelemetryService {
   }
   enrichPropertiesWithContext(properties, context) {
     return {
+      ...getGlobalTelemetryProperties(),
       ...this.defaultProperties,
       ...properties,
       ...context
@@ -254,3 +291,5 @@ export {
   ConsoleTelemetryProvider,
   BrowserContextStorage
 };
+
+//# debugId=71EE5BABB86B607F64756E2164756E21

package/dist/telemetry/node-appinsights-telemetry-provider.d.ts

@@ -1,7 +1,6 @@
 import type { ITelemetryProvider } from "./telemetry-provider.js";
 import type { TelemetryProperties } from "./telemetry-service.js";
-export declare function setGlobalTelemetryProperties(properties: TelemetryProperties): void;
-export declare function getGlobalTelemetryProperties(): TelemetryProperties | undefined;
+export { getGlobalTelemetryProperties, setGlobalTelemetryProperties, } from "./global-telemetry-properties.js";
 /**
  * Node.js Application Insights telemetry provider.
  * Uses the `applicationinsights` Node SDK (not the browser SDK).

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

@@ -0,0 +1,5 @@
+/**
+ * Check whether telemetry is disabled via environment variable.
+ * Set UIPATH_TELEMETRY_DISABLED=1 or UIPATH_TELEMETRY_DISABLED=true to opt out.
+ */
+export declare function isTelemetryDisabled(): boolean;

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

@@ -6,11 +6,7 @@ import { type NodeAppInsightsTelemetryProvider } from "./node-appinsights-teleme
  * Returns undefined if the applicationinsights package is not installed.
  */
 export declare function createAppInsightsProvider(): Promise<NodeAppInsightsTelemetryProvider | undefined>;
-/**
- * Check whether telemetry is disabled via environment variable.
- * Set UIPATH_TELEMETRY_DISABLED=1 or UIPATH_TELEMETRY_DISABLED=true to opt out.
- */
-export declare function isTelemetryDisabled(): boolean;
+export { isTelemetryDisabled } from "./telemetry-config.js";
 interface TelemetryProviderResult {
     provider: ITelemetryProvider;
     name: string;
@@ -50,4 +46,3 @@ export declare function telemetryInit(options?: TelemetryInitOptions): Promise<v
  * Capped at FLUSH_SHUTDOWN_TIMEOUT_MS to avoid hanging on slow/unreachable endpoints.
  */
 export declare function telemetryFlushAndShutdown(): Promise<void>;
-export {};

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

@@ -147,7 +147,15 @@ export declare class TelemetryService implements ITelemetryService {
      */
     private getCurrentContext;
     /**
-     * Enriches properties with context information (operationId, parentId, id)
+     * Enriches properties with the shared base properties, this service's
+     * default properties, and context information (operationId, parentId, id).
+     *
+     * The global base properties (app version, detected agent, authenticated
+     * user/tenant/org) are merged here — at the service level — rather than
+     * inside a specific provider, so EVERY event carries them regardless of
+     * which provider is active (AppInsights, logger fallback, or a tool
+     * bundle's early local instance). Precedence, lowest to highest: global
+     * base props → per-service defaults → per-call props → correlation context.
      */
     private enrichPropertiesWithContext;
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@uipath/common",
   "license": "MIT",
-  "version": "1.195.0",
+  "version": "1.197.0-preview.59",
   "description": "Common infrastructure needed by uip tools.",
   "repository": {
     "type": "git",
@@ -24,13 +24,39 @@
         "default": "./dist/index.js"
       }
     },
+    "./catch-error": {
+      "types": "./dist/catch-error.d.ts",
+      "default": "./dist/catch-error.js"
+    },
     "./sdk-user-agent": {
-      "types": "./dist/sdk-user-agent.d.ts",
-      "default": "./dist/sdk-user-agent.js"
+      "browser": {
+        "types": "./dist/sdk-user-agent.d.ts",
+        "default": "./dist/sdk-user-agent.js"
+      },
+      "default": {
+        "types": "./dist/sdk-user-agent.d.ts",
+        "default": "./dist/sdk-user-agent.js"
+      }
+    },
+    "./package-metadata-options": {
+      "browser": {
+        "types": "./dist/package-metadata-options.d.ts",
+        "default": "./dist/package-metadata-options.js"
+      },
+      "default": {
+        "types": "./dist/package-metadata-options.d.ts",
+        "default": "./dist/package-metadata-options.js"
+      }
     },
     "./telemetry": {
-      "types": "./dist/telemetry/index.d.ts",
-      "default": "./dist/telemetry/index.js"
+      "browser": {
+        "types": "./dist/telemetry/index.d.ts",
+        "default": "./dist/telemetry/index.js"
+      },
+      "default": {
+        "types": "./dist/telemetry/index.d.ts",
+        "default": "./dist/telemetry/index.js"
+      }
     }
   },
   "files": [
@@ -41,5 +67,5 @@
     "mihaigirleanu",
     "vlad-uipath"
   ],
-  "gitHead": "65fabb84552758b2710d8ca68470e70a9b1d19bc"
+  "gitHead": "df0e2b8140cced13f463b487214927c82bc0f85b"
 }

package/dist/jsonpath.d.ts

@@ -1,11 +0,0 @@
-/**
- * Evaluate a JSONPath expression against arbitrary data.
- *
- * Returns a newline-separated string of matched values.
- * Objects/arrays are serialized to compact JSON.
- * Returns an empty string when nothing matches or the expression is unrecognised.
- */
-export declare function evaluateJsonPath(data: unknown, expression: string): string;
-export declare class JsonPathError extends Error {
-    constructor(message: string);
-}