@uipath/common 1.196.0 → 1.197.0-preview.59

package/dist/interactivity-context.d.ts

@@ -1,15 +1,16 @@
 /**
  * Process-wide interactivity mode.
  *
- * The CLI is non-interactive by default: an automation agent or CI runner can
- * never answer a `y/N` prompt, so a hidden prompt hangs the caller forever.
+ * 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 (the default; the safe machine-first contract).
- *   - "auto"   — prompt only when stdout is a TTY (opt-in via config for humans).
+ *   - "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
@@ -21,13 +22,12 @@
 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 "never". */
+/** 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 — the canonical signal also
- * used by `login` and `completion`.
+ * 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

@@ -8,6 +8,8 @@ import type { Command } from "commander";
  * Commands extend their own option interface with this.
  */
 export interface PackageMetadataCliOptions {
+    author?: string;
+    description?: string;
     repositoryUrl?: string;
     repositoryCommit?: string;
     repositoryBranch?: string;

package/dist/package-metadata-options.js

@@ -1,9 +1,13 @@
 // src/package-metadata-options.ts
 function registerPackageMetadataOptions(command) {
-  return command.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");
+  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)
@@ -25,3 +29,5 @@ 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/telemetry/index.js

@@ -291,3 +291,5 @@ export {
   ConsoleTelemetryProvider,
   BrowserContextStorage
 };
+
+//# debugId=71EE5BABB86B607F64756E2164756E21

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@uipath/common",
   "license": "MIT",
-  "version": "1.196.0",
+  "version": "1.197.0-preview.59",
   "description": "Common infrastructure needed by uip tools.",
   "repository": {
     "type": "git",
@@ -24,17 +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": {
-      "types": "./dist/package-metadata-options.d.ts",
-      "default": "./dist/package-metadata-options.js"
+      "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": [
@@ -45,5 +67,5 @@
     "mihaigirleanu",
     "vlad-uipath"
   ],
-  "gitHead": "94d71f9c52214980a1f0ae62b3f5372095788553"
+  "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);
-}