@uipath/common 1.1.0 → 1.196.0

package/dist/confirmation.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Flags that affirm a destructive operation. `--yes` is the canonical flag for
+ * delete/remove commands; `--force` is the established alias used by overwrite
+ * commands (`init`, `pull`). Either one satisfies the guard.
+ *
+ * Add the flag to a command with
+ * `.option("-y, --yes", "Confirm this irreversible operation (required; the CLI never prompts)")`
+ * and gate the handler with {@link requireConfirmation}.
+ */
+export interface ConfirmationFlags {
+    yes?: boolean;
+    force?: boolean;
+}
+/**
+ * Guard a destructive operation. Returns `true` when the caller passed `--yes`
+ * (or `--force`). Otherwise emits a structured failure naming the flag to pass,
+ * sets a non-zero exit code via {@link processContext}, and returns `false` so
+ * the handler can bail in one line:
+ *
+ * ```ts
+ * if (!requireConfirmation(options, `delete folder '${id}'`)) return;
+ * ```
+ *
+ * @param flags - the parsed command options (must carry `yes`/`force`).
+ * @param operation - a short description of what will happen, e.g.
+ *   `"delete folder 'Finance'"`. Surfaced in the error message.
+ */
+export declare function requireConfirmation(flags: ConfirmationFlags, operation: string): boolean;

package/dist/content-hash.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Generate a SHA-256 hex hash of content for change detection.
+ * Prefers the Web Crypto API; falls back to node:crypto outside the browser.
+ *
+ * @param content - String content to hash
+ * @returns Hex string of the hash
+ */
+export declare function hashContent(content: string): Promise<string>;

package/dist/error-handler.d.ts

@@ -1,16 +1,28 @@
-import type { ErrorContext, FailureResultType } from "./formatter";
+import type { CliErrorCode, ErrorContext, FailureResultType, RetryHint } from "./formatter";
 /**
  * Structured error details returned by {@link extractErrorDetails}.
  */
 export interface ErrorDetails {
     /** Categorised failure type suitable for OutputFormatter.error() Result field */
     result: FailureResultType;
+    /** Stable CLI-owned error code suitable for agent control flow */
+    errorCode: CliErrorCode;
     /** Human-readable error message suitable for OutputFormatter.error() */
     message: string;
+    /** Stable retry guidance suitable for agent control flow */
+    retry: RetryHint;
     /** Raw details from the response body or error object for debugging */
     details: string;
     /** Machine-readable context for agents (HTTP status, request ID, retry-after, etc.) */
     context?: ErrorContext;
+    /**
+     * Per-field validation errors lifted from an ASP.NET ProblemDetails body
+     * (application/problem+json). Shape: `{ fieldName: ["msg", ...] }`.
+     * Surfaced as `Errors` on the OutputFormatter envelope so agents can
+     * react to the specific field that failed validation instead of parsing
+     * the free-text Message.
+     */
+    parsedErrors?: Record<string, string[]>;
 }
 /**
  * Options for customising error extraction behaviour.

package/dist/formatter.d.ts

@@ -1,6 +1,10 @@
 export type OutputFormat = "table" | "json" | "yaml" | "plain";
 export type ResultType = "Success" | "Failure" | "ConfigError" | "AuthenticationError" | "ValidationError" | "TimeoutError";
 export type FailureResultType = Exclude<ResultType, "Success">;
+export declare const CLI_ERROR_CODES: readonly ["invalid_argument", "authentication_required", "permission_denied", "not_found", "rate_limited", "network_error", "timeout", "server_error", "method_not_allowed", "configuration_error", "unknown_error"];
+export type CliErrorCode = (typeof CLI_ERROR_CODES)[number];
+export declare const RETRY_HINTS: readonly ["RetryWillNotFix", "RetryLater", "RetryAfter1Second", "RetryAfter10Seconds", "RetryAfter30Seconds", "RetryAfter60Seconds"];
+export type RetryHint = (typeof RETRY_HINTS)[number];
 /** Canonical string constants for {@link ResultType} values. */
 export declare const RESULTS: {
     readonly Success: "Success";
@@ -76,11 +80,21 @@ export interface ErrorContext {
 export declare class FailureOutput {
     Result: FailureResultType;
     Code?: string;
+    ErrorCode?: CliErrorCode;
     Message: string;
     Instructions: string;
+    Retry?: RetryHint;
     Context?: ErrorContext;
     Log?: string;
-    constructor(result: FailureResultType, message: string, instructions: string, context?: ErrorContext);
+    /**
+     * Optional structured payload for failure envelopes that need to carry
+     * actionable detail beyond the Message string (e.g. JobKey + JobState
+     * + SubState for the `jobs start --wait-for-completion` failure path).
+     * Mirrors SuccessOutput.Data so consumers can use a single accessor
+     * across success / failure paths.
+     */
+    Data?: DataRecord | DataRecord[];
+    constructor(result: FailureResultType, message: string, instructions: string, context?: ErrorContext, errorCode?: CliErrorCode, retry?: RetryHint);
 }
 export type StructuredOutput = SuccessOutput | FailureOutput;
 /**
@@ -97,11 +111,49 @@ export type StructuredOutput = SuccessOutput | FailureOutput;
  * closed-box guarantee must additionally wrap {@link applyFilter}.
  */
 export declare function validateOutputFilter(filter: string): Error | null;
+/**
+ * Thrown when a `--output-filter` expression parses successfully but fails at
+ * evaluation time (e.g. type-coercion errors when functions receive unexpected
+ * types). Carries `instructions` and `result` so {@link trackedAction} can
+ * surface filter-specific guidance through the failure envelope instead of the
+ * generic "unexpected error" fallback.
+ *
+ * Uses a duck-type `__brand` rather than relying on `instanceof`, because each
+ * tool bundles its own copy of `@uipath/common` and class identity differs
+ * across bundle boundaries.
+ */
+export declare class FilterEvaluationError extends Error {
+    readonly __brand: "FilterEvaluationError";
+    readonly filter: string;
+    readonly errorCode: CliErrorCode;
+    readonly instructions: string;
+    readonly retry: RetryHint;
+    readonly result: FailureResultType;
+    constructor(filter: string, cause: unknown);
+}
 /**
  * OutputFormatter namespace for formatting and displaying output.
  */
 export declare namespace OutputFormatter {
-    function success(data: SuccessOutput): void;
+    /**
+     * Emit a success envelope.
+     *
+     * By default every key in `data.Data` is normalized to PascalCase for
+     * cross-command output consistency (see {@link normalizeDataKeys}).
+     *
+     * Pass `{ preserveDataKeys: true }` when the `Data` payload is content that
+     * is copied verbatim back into a UiPath artifact and whose key casing is
+     * therefore load-bearing — most notably `registry get` node definitions,
+     * whose camelCase field names (`inputDefinition`, `inputString`, …) are
+     * pasted straight into `.flow` files. PascalCasing those names produces a
+     * flow that passes `flow validate` but faults at runtime (the agent/job
+     * receives `InputString` while its schema requires `inputString`). With
+     * this flag the `Data` payload keeps its original casing; the envelope
+     * keys (`Result`/`Code`/`Data`/`Log`/…) are still PascalCased.
+     */
+    function success(data: SuccessOutput, options?: {
+        preserveDataKeys?: boolean;
+    }): void;
     /**
      * Format and display an error, then set {@link process.exitCode} to the
      * value from {@link EXIT_CODES} for `data.Result` (falls back to 1).

package/dist/index.browser.d.ts

@@ -5,6 +5,7 @@ export * from "./command-walker";
 export * from "./completer";
 export { installConsoleGuard, restoreConsole } from "./console-guard";
 export * from "./constants";
+export * from "./content-hash";
 export * from "./env-reference";
 export * from "./error-handler";
 export * from "./error-instructions";
@@ -16,6 +17,7 @@ export * from "./orchestrator-urls";
 export * from "./output-context";
 export * from "./output-format-context";
 export * from "./output-sink";
+export * from "./package-metadata-options";
 export * from "./polling";
 export * from "./screen-logger";
 export * from "./singleton";