@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,35 @@
1
+ import type { TelemetryProperties } from "./telemetry-service.js";
2
+ /** Plain data supplied by a project owner. This module knows no file formats. */
3
+ export interface ProjectIdentityInput {
4
+ id?: string;
5
+ /** Local lookup input only. Never included in emitted telemetry. */
6
+ projectDirectory?: string;
7
+ projectType: string;
8
+ status: string;
9
+ }
10
+ /** A containing solution has its own identity; it is not another project. */
11
+ export interface SolutionIdentityInput {
12
+ id?: string;
13
+ status: string;
14
+ }
15
+ export declare function solutionIdentityProperties(identity: SolutionIdentityInput): TelemetryProperties;
16
+ /** Full native GUID in lowercase compact form; never hash or invent an ID. */
17
+ export declare function projectKey(id: unknown): string | undefined;
18
+ export declare function projectIdentityProperties(identity: ProjectIdentityInput): TelemetryProperties;
19
+ /**
20
+ * Identity lookups run on the command's path, before and after its action, and
21
+ * can walk parent folders (a slow network share, an automounter). A lookup
22
+ * slower than this is skipped so telemetry never delays the command. It also
23
+ * covers the resolver's first `import()` of its reader, so it is generous for
24
+ * a cold start on a slow CI runner; a local `.uipx` read takes milliseconds.
25
+ */
26
+ export declare const PROJECT_IDENTITY_LOOKUP_BUDGET_MS = 1000;
27
+ /**
28
+ * Wait for optional telemetry work for at most
29
+ * {@link PROJECT_IDENTITY_LOOKUP_BUDGET_MS}. Resolves `undefined` when it runs
30
+ * out; a later answer is dropped. Every wait for identity on a command's path
31
+ * goes through this, so none of them can hold up the operation.
32
+ */
33
+ export declare function withinProjectIdentityBudget<T>(work: Promise<T>,
34
+ /** Called when the budget runs out; this leaf has no logger (browser entry). */
35
+ onTimeout?: () => void): Promise<T | undefined>;
@@ -1,3 +1,4 @@
1
+ import { type ProjectTelemetryCapture } from "../project-telemetry.js";
1
2
  export interface ShipSucceededTelemetryPayload {
2
3
  ShipKind: string;
3
4
  Target: string;
@@ -13,4 +14,9 @@ export interface ShipSucceededTelemetryPayload {
13
14
  FeedId?: string;
14
15
  ProjectTypes?: string;
15
16
  }
16
- export declare function trackShipSucceeded(payload: ShipSucceededTelemetryPayload): boolean;
17
+ /**
18
+ * @param capture the shipping command's capture, from
19
+ * `getProjectTelemetryCapture(command)`: the GUID identity keys it holds at
20
+ * this moment go on the event. Omit it for a command without one.
21
+ */
22
+ export declare function trackShipSucceeded(payload: ShipSucceededTelemetryPayload, capture?: ProjectTelemetryCapture): boolean;
@@ -3,3 +3,5 @@
3
3
  * Set UIPATH_TELEMETRY_DISABLED=1 or UIPATH_TELEMETRY_DISABLED=true to opt out.
4
4
  */
5
5
  export declare function isTelemetryDisabled(): boolean;
6
+ /** Independent opt-out for optional project and solution identity discovery. */
7
+ export declare function isProjectTelemetryDisabled(): boolean;
@@ -88,7 +88,23 @@ export declare const CommandDimensions: {
88
88
  /** `build` | `operate` | `troubleshoot`. */
89
89
  readonly Mode: "Mode";
90
90
  };
91
- /** Dimensions on `Cli.ShipSucceeded`. */
91
+ /** Stable source identity, separate from runtime and deployment IDs. */
92
+ export declare const ProjectDimensions: {
93
+ readonly ProjectKey: "ProjectKey";
94
+ readonly ProjectType: "ProjectType";
95
+ readonly ProjectIdentityStatus: "ProjectIdentityStatus";
96
+ readonly SolutionKey: "SolutionKey";
97
+ readonly SolutionProjectKey: "SolutionProjectKey";
98
+ readonly SolutionIdentityStatus: "SolutionIdentityStatus";
99
+ readonly PreviousSolutionKey: "PreviousSolutionKey";
100
+ };
101
+ /** Full native GUIDs, normalized to lowercase compact form before delivery. */
102
+ export declare const GUID_KEY_DIMENSIONS: ReadonlySet<string>;
103
+ /**
104
+ * Dimensions on `Cli.ShipSucceeded`. The event also carries the GUID identity
105
+ * keys of `ProjectDimensions` when the shipping handler passes its capture to
106
+ * `trackShipSucceeded` (ship-succeeded.ts).
107
+ */
92
108
  export declare const ShipDimensions: {
93
109
  readonly ShipKind: "ShipKind";
94
110
  readonly Target: "Target";
@@ -171,6 +187,8 @@ export declare const ScopeDimensions: {
171
187
  * verbatim so a host that exports `UIPATH_SESSION_ID=AbC` can find its own
172
188
  * sessions by that literal string — and it has to keep agreeing with the
173
189
  * native `ai.session.id` tag, which nothing lowercases.
190
+ * Project and solution correlation keys are also excluded: see
191
+ * GUID_KEY_DIMENSIONS. Their full GUID in lowercase compact form is the join key.
174
192
  */
175
193
  export declare const ID_DIMENSIONS: ReadonlySet<string>;
176
194
  /**
@@ -22,5 +22,6 @@ export declare const CommonTelemetryEvents: {
22
22
  /** A ship (publish/deploy/upload) completed. The command that shipped is
23
23
  * carried by the `CommandName` dimension; `ShipKind`/`Target` describe
24
24
  * what was shipped where. */
25
+ readonly ProjectActivity: "Cli.ProjectActivity";
25
26
  readonly ShipSucceeded: "Cli.ShipSucceeded";
26
27
  };
@@ -41,19 +41,25 @@ interface TelemetryProviderResult {
41
41
  /**
42
42
  * Create the default telemetry provider (async).
43
43
  * Uses Application Insights (Node SDK) by default, falls back to
44
- * LoggerTelemetryProvider if telemetry is disabled, initialization
45
- * fails, or the applicationinsights package is not installed.
44
+ * LoggerTelemetryProvider if telemetry is disabled, the host has no
45
+ * Application Insights (`appInsights: false`), initialization fails, or
46
+ * the applicationinsights package is not installed.
46
47
  *
47
48
  * Returns both the provider and its name so callers can log which
48
49
  * provider was selected without relying on module-level mutable state.
49
50
  */
50
- export declare function createTelemetryProvider(): Promise<TelemetryProviderResult>;
51
+ export declare function createTelemetryProvider(options?: Pick<TelemetryInitOptions, "appInsights">): Promise<TelemetryProviderResult>;
51
52
  export declare const telemetry: ITelemetryService;
52
53
  export interface TelemetryInitOptions {
53
54
  /** Application version — sets the standard `ai.application.ver` context tag. */
54
55
  version?: string;
55
56
  /** Custom dimensions added to every telemetry event. */
56
57
  defaultProperties?: Record<string, string>;
58
+ /**
59
+ * `false` where the Node Application Insights SDK cannot load (the browser
60
+ * bundle externalizes it): use the logger provider without trying it.
61
+ */
62
+ appInsights?: boolean;
57
63
  }
58
64
  /**
59
65
  * Initialize telemetry with default properties.
@@ -0,0 +1,57 @@
1
+ import { type FailureOutput } from "./formatter";
2
+ /** The spies a spec asserts on in place of the real formatter. */
3
+ interface FormatterFakes {
4
+ success: (...args: never[]) => unknown;
5
+ error: (data: FailureOutput) => unknown;
6
+ }
7
+ /**
8
+ * Point the real `OutputFormatter` at a spec's fakes, and hand the fakes back
9
+ * for the `@uipath/common` mock to expose.
10
+ *
11
+ * A mock that only swaps `OutputFormatter` on the mocked module misses every
12
+ * envelope printed from inside `@uipath/common` (`reportFailure`,
13
+ * `requireConfirmation`), because those print through the real namespace
14
+ * object. Forwarding the real object's `success` / `error` to the same fakes
15
+ * lets a spec keep asserting on them whichever side printed.
16
+ *
17
+ * The forwarded `error` also records the exit code the envelope's `Result`
18
+ * maps to, as the real formatter does, so a spec can still read
19
+ * `process.exitCode` after a reported failure. That covers envelopes printed
20
+ * from inside `@uipath/common` only: a command that calls the mocked
21
+ * `OutputFormatter.error` directly reaches the bare fake, so give that fake
22
+ * {@link recordFailureExit} as its implementation when the spec reads the
23
+ * exit code.
24
+ *
25
+ * The patch stays for the rest of the spec file. Vitest gives each spec file
26
+ * its own module registry, so it ends with the file.
27
+ *
28
+ * Resolve `@uipath/common/testing` through the workspace source aliases, as
29
+ * every spec here does. The built `dist/testing.js` carries its own copy of
30
+ * the formatter, so patching it would not reach the copy a tool bundle uses.
31
+ *
32
+ * Test support only. Call it inside a `vi.mock` factory through a dynamic
33
+ * import, which keeps the factory hoisting-safe:
34
+ *
35
+ * ```ts
36
+ * vi.mock("@uipath/common", async (importOriginal) => {
37
+ * const actual = await importOriginal<typeof import("@uipath/common")>();
38
+ * const { installFormatterFakes } = await import("@uipath/common/testing");
39
+ * return {
40
+ * ...actual,
41
+ * OutputFormatter: installFormatterFakes({ success: vi.fn(), error: vi.fn() }),
42
+ * };
43
+ * });
44
+ * ```
45
+ */
46
+ export declare function installFormatterFakes<T extends FormatterFakes>(fakes: T): T;
47
+ /**
48
+ * Record the exit code `data.Result` maps to, as the real
49
+ * `OutputFormatter.error()` does. For a fake formatter's `error`, so a spec
50
+ * that stubs the printing still sees the exit code a failure leaves:
51
+ *
52
+ * ```ts
53
+ * vi.spyOn(OutputFormatter, "error").mockImplementation(recordFailureExit);
54
+ * ```
55
+ */
56
+ export declare function recordFailureExit(data: FailureOutput): void;
57
+ export {};