@uipath/common 1.0.4 → 1.195.0

package/dist/attachment-binding.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Commander collector for repeatable string options. Use with `.option(...,
+ * appendOption, [] as string[])` to accumulate values across multiple flag
+ * occurrences (e.g. `--attachment a=b --attachment c=d`).
+ */
+export declare function appendOption(value: string, previous: string[] | undefined): string[];
+/** A parsed `name=path` --attachment spec. */
+export interface ParsedAttachmentSpec {
+    name: string;
+    path: string;
+}
+/**
+ * Standard `Instructions` text for an OutputFormatter error when the user's
+ * `--attachment` spec is malformed.
+ */
+export declare const ATTACHMENT_INSTRUCTIONS = "Provide --attachment as 'name=path' where 'name' matches a file-typed workflow input variable and 'path' points at a readable local file. Repeat the flag to attach multiple files.";
+/**
+ * Standard `Instructions` text when `--attachment` upload fails (auth, network,
+ * permissions). Pair with the underlying error message in `Message`.
+ */
+export declare const ATTACHMENT_UPLOAD_INSTRUCTIONS = "Check that the active tenant has Orchestrator access and the file is readable, then retry.";
+/**
+ * Parse a `name=path` --attachment spec for Maestro-engine file-variable
+ * binding (used by `flow debug` and `flow process run`).
+ *
+ * `name=` is mandatory: the engine resolves `=js:($vars.<scope>.input.<name>)`
+ * expressions in connector multipart slots against the uploaded
+ * `JobAttachmentReference`, so it needs the explicit workflow-variable name
+ * as the binding key. A bare path has no binding target and is rejected.
+ *
+ * Distinct from `or jobs run --attachment` which auto-derives a name from
+ * the basename when '=' is absent (no binding key required there).
+ */
+export declare function parseAttachmentSpec(spec: string): ParsedAttachmentSpec;
+/**
+ * Read each spec's bytes (fail-fast on any error), then upload all via the
+ * caller-supplied `upload` function (e.g. `uploadJobAttachment` from
+ * `@uipath/orchestrator-sdk`) in parallel. Returns references in input order.
+ *
+ * Two-phase to avoid orphaned attachments when a local path is bad: phase 1
+ * reads + validates every file before any network write. A read failure
+ * short-circuits before any upload begins. A mid-upload failure on one spec
+ * can still leave a sibling's attachment orphaned — accepted trade-off;
+ * Orchestrator has no atomic-batch endpoint.
+ *
+ * The `fileName` passed to `upload` is the local basename (not the LHS of
+ * `name=path`) so users recognize their uploaded file in the Orchestrator
+ * UI. The spec's `name` is preserved on the returned record for callers to
+ * use as the binding key in their inputs payload.
+ */
+export declare function resolveAttachmentInputs<R>(specs: ParsedAttachmentSpec[], upload: (bytes: Uint8Array, fileName: string) => Promise<R>): Promise<{
+    name: string;
+    path: string;
+    reference: R;
+}[]>;

package/dist/error-handler.d.ts

@@ -11,6 +11,14 @@ export interface ErrorDetails {
     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

@@ -75,10 +75,19 @@ export interface ErrorContext {
 }
 export declare class FailureOutput {
     Result: FailureResultType;
+    Code?: string;
     Message: string;
     Instructions: string;
     Context?: ErrorContext;
     Log?: string;
+    /**
+     * 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);
 }
 export type StructuredOutput = SuccessOutput | FailureOutput;
@@ -96,11 +105,47 @@ 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 instructions: string;
+    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

@@ -0,0 +1,23 @@
+export * from "./catch-error";
+export * from "./command-examples";
+export * from "./command-help";
+export * from "./command-walker";
+export * from "./completer";
+export { installConsoleGuard, restoreConsole } from "./console-guard";
+export * from "./constants";
+export * from "./env-reference";
+export * from "./error-handler";
+export * from "./error-instructions";
+export * from "./guid";
+export * from "./jsonpath";
+export * from "./logger";
+export * from "./option-validators";
+export * from "./orchestrator-urls";
+export * from "./output-context";
+export * from "./output-format-context";
+export * from "./output-sink";
+export * from "./polling";
+export * from "./screen-logger";
+export * from "./singleton";
+export * from "./telemetry/telemetry-events.js";
+export * from "./tool-provider";