@uipath/common 1.205.0-preview.277 → 1.206.0-preview.279

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/dist/attachment-binding.d.ts +2 -2
  2. package/dist/catch-error.d.ts +1 -0
  3. package/dist/catch-error.js +146 -15
  4. package/dist/classified-failure.d.ts +15 -17
  5. package/dist/command-examples.d.ts +5 -1
  6. package/dist/concurrency.d.ts +7 -0
  7. package/dist/entity-field-rules.js +1 -17
  8. package/dist/entity-name-rules.js +1 -17
  9. package/dist/error-codes.d.ts +41 -0
  10. package/dist/error-handler.d.ts +18 -1
  11. package/dist/error-handler.js +283 -58
  12. package/dist/error-instructions.d.ts +2 -1
  13. package/dist/exit-code.d.ts +30 -3
  14. package/dist/formatter.d.ts +18 -44
  15. package/dist/guid.js +1 -17
  16. package/dist/http-status.d.ts +18 -0
  17. package/dist/index.browser.d.ts +6 -0
  18. package/dist/index.browser.js +4010 -3568
  19. package/dist/index.d.ts +6 -0
  20. package/dist/index.js +7931 -7202
  21. package/dist/named-second.d.ts +27 -0
  22. package/dist/pass-through-tail.d.ts +54 -0
  23. package/dist/polling/poll-failure-mapping.d.ts +10 -7
  24. package/dist/polling/types.d.ts +8 -2
  25. package/dist/project-telemetry.d.ts +84 -0
  26. package/dist/report-failure.d.ts +31 -0
  27. package/dist/result-types.d.ts +12 -0
  28. package/dist/sdk-user-agent.js +19 -2
  29. package/dist/telemetry/index.d.ts +2 -0
  30. package/dist/telemetry/index.js +1816 -1734
  31. package/dist/telemetry/project-identity.d.ts +35 -0
  32. package/dist/telemetry/ship-succeeded.d.ts +7 -1
  33. package/dist/telemetry/telemetry-config.d.ts +2 -0
  34. package/dist/telemetry/telemetry-dimensions.d.ts +19 -1
  35. package/dist/telemetry/telemetry-events.d.ts +1 -0
  36. package/dist/telemetry/telemetry-init.d.ts +9 -3
  37. package/dist/testing.d.ts +57 -0
  38. package/dist/testing.js +3623 -0
  39. package/dist/timings.d.ts +4 -3
  40. package/dist/zip.js +139 -115
  41. package/package.json +6 -2
@@ -0,0 +1,27 @@
1
+ /**
2
+ * The second value of a command that used to take two positionals and now
3
+ * names it (TOOL_SPEC Rule 13, UiPath/cli#4523). The old two-positional form
4
+ * still works for a deprecation window, with a `[WARN]` on stderr, so a script
5
+ * gets a warning rather than a break.
6
+ *
7
+ * Passing both, or neither, is a usage error ({@link usageError}).
8
+ */
9
+ export declare function namedOrLegacy(spec: {
10
+ /** The value of the named option, when given. */
11
+ named: string | undefined;
12
+ /** The old second positional, when given. */
13
+ legacy: string | undefined;
14
+ /** The named option, e.g. `--original`. */
15
+ flag: string;
16
+ /** The new form, for messages: `<verb> <object> --original <file>`. */
17
+ usage: string;
18
+ }): string;
19
+ /** The deprecated second positional, if given. A third is refused. */
20
+ export declare function legacySecondArg(args: string[], usage: string): string | undefined;
21
+ /**
22
+ * Refuse the command line as a usage error: `ValidationError` /
23
+ * `invalid_argument` / `RetryWillNotFix`, the same envelope Commander's own
24
+ * parse errors get. Thrown, because `trackedAction` turns a thrown error's
25
+ * `result`, `errorCode`, `retry` and `instructions` into the envelope.
26
+ */
27
+ export declare function usageError(message: string, usage: string): never;
@@ -0,0 +1,54 @@
1
+ import type { Command, Option } from "commander";
2
+ /**
3
+ * One token of a pass-through tail, classified by the rules Commander's own
4
+ * `parseOptions` applies (Commander 14), so every caller agrees with the
5
+ * parser the delegate runs.
6
+ *
7
+ * - `option`: a declared option, with the value Commander would give it.
8
+ * A required option takes the next token whatever it looks like
9
+ * (`--output-file --`, `--output-file -oSecret.flow`); an optional one
10
+ * takes it unless it looks like an option. `--name=value` and a joined
11
+ * short (`-ovalue`) carry the value inline.
12
+ * - `unknown`: a flag the command does not declare. Its arity is unknown, so
13
+ * the tokenizer never gives it the next token.
14
+ * - `operand`: a bare token, or anything after the sentinel (`literal`).
15
+ * - `sentinel`: a `--` that no option took as its value.
16
+ */
17
+ export type TailToken = {
18
+ kind: "sentinel";
19
+ index: number;
20
+ } | {
21
+ kind: "operand";
22
+ index: number;
23
+ text: string;
24
+ literal: boolean;
25
+ } | {
26
+ kind: "option";
27
+ index: number;
28
+ text: string;
29
+ option: Option;
30
+ value?: string;
31
+ } | {
32
+ kind: "unknown";
33
+ index: number;
34
+ text: string;
35
+ flag: string;
36
+ inlineValue?: string;
37
+ };
38
+ export interface TailTokens {
39
+ tokens: TailToken[];
40
+ /** Index in the tail of the first undeclared flag, or -1. */
41
+ firstUnknown: number;
42
+ /** Index in the tail of the sentinel `--`, or -1. */
43
+ sentinel: number;
44
+ }
45
+ /**
46
+ * Split a tail the way Commander would parse it against `cmd`'s declared
47
+ * options. Example, with `-o, --output-file <file>` declared:
48
+ *
49
+ * ```
50
+ * ["-o", "--", "--future", "x", "--", "y"]
51
+ * option(-o, value "--"), unknown(--future), operand(x), sentinel, operand(y, literal)
52
+ * ```
53
+ */
54
+ export declare function tokenizeTail(cmd: Command, tail: readonly string[]): TailTokens;
@@ -9,13 +9,16 @@ export interface PollFailureMapped {
9
9
  /** `2` for Timeout, `1` otherwise. */
10
10
  exitCode: number;
11
11
  /**
12
- * Classification for `OutputFormatter.error`, set only where the outcome
13
- * settles it. A timeout is `timeout` / `RetryLater`: the operation was
14
- * still running when we stopped watching, so the instructions say to check
15
- * again — and the hint has to agree, or an agent reads
16
- * `RetryWillNotFix` next to "may still be in progress". The other outcomes
17
- * carry an underlying error the formatter can classify better than we can
18
- * from the outcome alone, so they are left unset.
12
+ * Classification for `OutputFormatter.error`, set where the outcome or
13
+ * its error settles it. A timeout is `timeout` / `RetryLater`: the
14
+ * operation was still running when we stopped watching, so the
15
+ * instructions say to check again — and the hint has to agree, or an
16
+ * agent reads `RetryWillNotFix` next to "may still be in progress". A
17
+ * failed poll takes the class of the error it gave up on: only the
18
+ * message reaches the envelope, and a transport failure's message ("The
19
+ * request failed and the interceptors did not return an alternative
20
+ * response") says nothing the formatter can classify. The other outcomes
21
+ * are left unset.
19
22
  */
20
23
  errorCode?: CliErrorCode;
21
24
  /** See {@link PollFailureMapped.errorCode}. */
@@ -75,7 +75,12 @@ export interface PollUntilOptions<T> {
75
75
  intervalMs?: number | ((ctx: PollContext<T>) => number);
76
76
  /**
77
77
  * Max time to poll in ms. `0` means no limit — poll indefinitely until
78
- * a terminal state, abort, or interrupt.
78
+ * a terminal state, abort, or interrupt. A negative value counts as `0`.
79
+ *
80
+ * Every numeric setting (this one, a static `intervalMs`,
81
+ * `maxConsecutiveErrors`, `logIntervalMs` and the `backoff` fields) must
82
+ * be finite: `pollUntil` rejects with a `RangeError` naming the field
83
+ * for NaN or Infinity, before the first poll.
79
84
  *
80
85
  * (default: 1_800_000 — 30 minutes)
81
86
  */
@@ -108,7 +113,8 @@ export interface PollUntilOptions<T> {
108
113
  * - `0` — never auto-abort on errors. Only timeout, `onError` returning
109
114
  * `"abort"`, or signal interruption stops polling. Used by consumers
110
115
  * that expect transient errors (e.g., integration-service OAuth,
111
- * trace streaming with 404s during startup).
116
+ * trace streaming with 404s during startup). A negative value counts
117
+ * as `0`.
112
118
  *
113
119
  * (default: 3)
114
120
  */
@@ -0,0 +1,84 @@
1
+ import type { Command } from "commander";
2
+ import { type ProjectIdentityInput } from "./telemetry/project-identity.js";
3
+ import type { TelemetryProperties } from "./telemetry/telemetry-service.js";
4
+ export { PROJECT_IDENTITY_LOOKUP_BUDGET_MS, withinProjectIdentityBudget, } from "./telemetry/project-identity.js";
5
+ export { isProjectTelemetryDisabled } from "./telemetry/telemetry-config.js";
6
+ export interface ProjectTelemetryInput {
7
+ command: Command;
8
+ args: readonly unknown[];
9
+ phase: "before" | "after";
10
+ /** Actual path selected by a creating/importing handler, when available. */
11
+ target?: string;
12
+ success?: boolean;
13
+ }
14
+ export type ProjectTelemetryResolver = (input: ProjectTelemetryInput) => Promise<TelemetryProperties | undefined>;
15
+ export type ProjectContextTelemetryResolver = (projectDirectory: string) => Promise<TelemetryProperties | undefined>;
16
+ export declare function logSkipped(what: string, error: unknown): void;
17
+ /** Host-owned context discovery. No invocation data is stored on the command. */
18
+ export declare function configureProjectContextTelemetry(command: Command, resolver: ProjectContextTelemetryResolver): void;
19
+ /**
20
+ * Metadata only: the host retains ownership of trackedAction and child
21
+ * creation. The resolver nearest to a command wins. Handlers never receive an
22
+ * extra argument; one that wants to report an identity it resolved itself
23
+ * calls {@link getProjectTelemetryCapture} with the command Commander passes.
24
+ */
25
+ export declare function configureProjectTelemetry(command: Command, resolver: ProjectTelemetryResolver): void;
26
+ export declare function getProjectTelemetryResolver(command: Command): ProjectTelemetryResolver | undefined;
27
+ /**
28
+ * The running action's capture, or `undefined` when project telemetry is off,
29
+ * the command has no resolver, or the host predates the capture. Each CLI
30
+ * invocation (an MCP call included) builds its own command tree, so the slot
31
+ * belongs to exactly one action.
32
+ */
33
+ export declare function getProjectTelemetryCapture(command: Command | undefined): ProjectTelemetryCapture | undefined;
34
+ /** Host only: expose a session to its handler for the duration of the action. */
35
+ export declare function attachProjectTelemetryCapture(command: Command, capture: ProjectTelemetryCapture | undefined): void;
36
+ export interface ProjectTargetRule {
37
+ arguments?: readonly string[];
38
+ options?: readonly string[];
39
+ defaultTarget?: string;
40
+ create?: boolean;
41
+ }
42
+ /** Owners list eligible command groups and the parameters that select source. */
43
+ export declare function createProjectCommandResolver(root: Command, rules: Readonly<Record<string, ProjectTargetRule>>, read: (target: string) => Promise<ProjectIdentityInput>): ProjectTelemetryResolver;
44
+ /**
45
+ * Shared target selection; the owner supplies the identity dimensions, or
46
+ * `undefined` when it chooses not to read this target.
47
+ */
48
+ export declare function createIdentityCommandResolver(root: Command, rules: Readonly<Record<string, ProjectTargetRule>>, read: (target: string, command: Command) => Promise<TelemetryProperties | undefined>): ProjectTelemetryResolver;
49
+ /** Read by opted-in handlers through {@link getProjectTelemetryCapture}. */
50
+ export interface ProjectTelemetryCapture {
51
+ setTarget(path: string): Promise<void>;
52
+ /** Await before temporary source is removed, so context is captured too. */
53
+ setIdentity(identity: ProjectIdentityInput): Promise<void>;
54
+ /** Snapshot owner-defined identity fields before temporary inputs disappear. */
55
+ setProperties(properties: TelemetryProperties): void;
56
+ properties(): TelemetryProperties;
57
+ }
58
+ /**
59
+ * One object per action, explicitly retained through request finalization.
60
+ * Its fields go on the command's request row; nested records do not inherit
61
+ * them. A ship event carries them only when the handler passes this capture
62
+ * to `trackShipSucceeded` explicitly.
63
+ */
64
+ export declare class ProjectTelemetrySession implements ProjectTelemetryCapture {
65
+ private readonly resolver;
66
+ private readonly command?;
67
+ private target?;
68
+ private props;
69
+ private explicit;
70
+ private input?;
71
+ constructor(resolver: ProjectTelemetryResolver, command?: Command | undefined);
72
+ setTarget(path: string): Promise<void>;
73
+ setIdentity(identity: ProjectIdentityInput): Promise<void>;
74
+ setProperties(properties: TelemetryProperties): void;
75
+ properties(): TelemetryProperties;
76
+ resolve(input: Omit<ProjectTelemetryInput, "target">): Promise<void>;
77
+ }
78
+ /**
79
+ * Rules name commands and parameters as strings, and a rule whose name stops
80
+ * matching resolves nothing without any error. Call this after the tree is
81
+ * registered (a tool's coverage spec does) to list every rule that names a
82
+ * command, argument or option the tree does not have.
83
+ */
84
+ export declare function findStaleProjectTargetRules(root: Command): string[];
@@ -0,0 +1,31 @@
1
+ import { type FailureOutput } from "./formatter";
2
+ /** How a caller adjusts the envelope {@link reportFailure} prints. */
3
+ export interface ReportFailureOptions {
4
+ /**
5
+ * Rewrite the classified `Instructions`: a command's own guidance around
6
+ * the detail, or a tool's note for an `ErrorCode` it knows more about
7
+ * (orchestrator leads a 403 with what an external application lacks).
8
+ * Gets the envelope as classified, so it can branch on `ErrorCode`.
9
+ */
10
+ instructions?: (instructions: string, failure: FailureOutput) => string;
11
+ }
12
+ /**
13
+ * Report a caught error as the command's failure, then let the caller return.
14
+ *
15
+ * Classifies `error` into the standard envelope ({@link classifiedFailure}:
16
+ * `Message` is what the command was doing, `Instructions` the classified
17
+ * detail, plus the `ErrorCode`, `Retry` and `Context` agents branch on), and
18
+ * prints it. `OutputFormatter.error()` records the exit code the envelope's
19
+ * `Result` maps to, so there is no `context.exit(1)` to pair with it:
20
+ *
21
+ * ```ts
22
+ * if (apiError) {
23
+ * await reportFailure("Error creating folder", apiError);
24
+ * return;
25
+ * }
26
+ * ```
27
+ *
28
+ * The `return` stays at the call site: stopping the handler is the caller's
29
+ * business and has to stay visible.
30
+ */
31
+ export declare function reportFailure(message: string, error: unknown, options?: ReportFailureOptions): Promise<void>;
@@ -0,0 +1,12 @@
1
+ export type ResultType = "Success" | "Failure" | "ConfigError" | "AuthenticationError" | "ValidationError" | "TimeoutError";
2
+ export type FailureResultType = Exclude<ResultType, "Success">;
3
+ /** Canonical string constants for {@link ResultType} values. */
4
+ export declare const RESULTS: {
5
+ readonly Success: "Success";
6
+ readonly Failure: "Failure";
7
+ readonly ConfigError: "ConfigError";
8
+ readonly AuthenticationError: "AuthenticationError";
9
+ readonly ValidationError: "ValidationError";
10
+ /** A wait the caller bounded with --timeout ran out (e.g. `tm testsets clone`); exit 4. */
11
+ readonly TimeoutError: "TimeoutError";
12
+ };
@@ -75,6 +75,21 @@ var CommandDimensions = {
75
75
  ProductArea: "ProductArea",
76
76
  Mode: "Mode"
77
77
  };
78
+ var ProjectDimensions = {
79
+ ProjectKey: "ProjectKey",
80
+ ProjectType: "ProjectType",
81
+ ProjectIdentityStatus: "ProjectIdentityStatus",
82
+ SolutionKey: "SolutionKey",
83
+ SolutionProjectKey: "SolutionProjectKey",
84
+ SolutionIdentityStatus: "SolutionIdentityStatus",
85
+ PreviousSolutionKey: "PreviousSolutionKey"
86
+ };
87
+ var GUID_KEY_DIMENSIONS = new Set([
88
+ ProjectDimensions.ProjectKey,
89
+ ProjectDimensions.SolutionKey,
90
+ ProjectDimensions.SolutionProjectKey,
91
+ ProjectDimensions.PreviousSolutionKey
92
+ ]);
78
93
  var ShipDimensions = {
79
94
  ShipKind: "ShipKind",
80
95
  Target: "Target",
@@ -142,6 +157,7 @@ var RESERVED_DIMENSION_NAMES = new Set([
142
157
  ...Object.values(BaseDimensions),
143
158
  ...Object.values(CommandDimensions),
144
159
  ...Object.values(ShipDimensions),
160
+ ...Object.values(ProjectDimensions),
145
161
  ...Object.values(ErrorDimensions),
146
162
  ...Object.values(AuthDimensions),
147
163
  ...Object.values(SkillsDimensions),
@@ -167,7 +183,8 @@ var CURATED_DIMENSIONS = new Set([
167
183
  BaseDimensions.SessionIdSource,
168
184
  BaseDimensions.SessionId,
169
185
  ...Object.values(CommandDimensions),
170
- ...Object.values(ShipDimensions)
186
+ ...Object.values(ShipDimensions),
187
+ ...Object.values(ProjectDimensions)
171
188
  ]);
172
189
 
173
190
  // src/sdk-user-agent.ts
@@ -287,4 +304,4 @@ export {
287
304
  setSdkUserAgentHostToken
288
305
  };
289
306
 
290
- //# debugId=3EAF36DA2A24ACC564756E2164756E21
307
+ //# debugId=E1368F19FF99619464756E2164756E21
@@ -5,7 +5,9 @@ export type { IContextStorage } from "./context-storage.js";
5
5
  export { buildEnvironmentProperties, type NormalizedEnvironment, normalizeBaseUrl, normalizeEnvironment, } from "./environment-info.js";
6
6
  export { type CiProvider, detectExecutionContext, EXECUTION_CONTEXT_VALUES, type ExecutionContext, type ExecutionContextDetection, type ExecutionContextDetectionOptions, getExecutionContextTelemetryProperties, setExecutionContextAuthSignal, } from "./execution-context.js";
7
7
  export { redactError, redactProperties, redactProperty, } from "./pii-redactor.js";
8
+ export * from "./project-identity.js";
8
9
  export { getConfiguredTelemetrySessionId, getTelemetrySessionId, getTelemetrySessionSource, TELEMETRY_SESSION_ID_ENV, TELEMETRY_SESSION_SOURCE_PROPERTY, } from "./session-id.js";
10
+ export { isProjectTelemetryDisabled } from "./telemetry-config.js";
9
11
  export * from "./telemetry-dimensions.js";
10
12
  export type { ITelemetryProvider, TelemetryCorrelation, TrackedDependencySpan, TrackedEvent, TrackedException, TrackedSpan, } from "./telemetry-provider.js";
11
13
  export type { ITelemetryService, TelemetryContext, TelemetryProperties, } from "./telemetry-service.js";