@uipath/common 1.201.0 → 1.202.0-preview.136

package/dist/telemetry/invocation-request.d.ts

@@ -0,0 +1,38 @@
+import type { TelemetryContext, TelemetryProperties } from "./telemetry-service.js";
+/**
+ * Open this invocation's request scope and run `fn` inside it.
+ *
+ * Call once, as early in the run as there is a run — inside the timing scope,
+ * since the span's start and duration are read from the invocation's baseline.
+ */
+export declare function runWithInvocationRequest<T>(fn: () => Promise<T>): Promise<T>;
+/**
+ * Run `fn` inside the invocation's request scope, opening one only if nothing
+ * has.
+ *
+ * For a caller that cannot assume the entry point ran: the standalone tool bins
+ * (`packages/*​/src/index.ts`) go straight to Commander, so without this their
+ * commands would have no scope and their outbound calls would go untracked.
+ */
+export declare function ensureInvocationRequestScope<T>(fn: () => Promise<T>): Promise<T>;
+/**
+ * This invocation's request context — the span every dependency and leaf in the
+ * run hangs under. `undefined` before the scope is opened.
+ *
+ * The active context wins over the slot, because it is the per-invocation one:
+ * in a host running two commands at once (the MCP bridge) the slot holds
+ * whichever opened last, so reading it alone made one command's request
+ * envelope ship under the other's span id.
+ */
+export declare function getInvocationRequestContext(): TelemetryContext | undefined;
+/**
+ * Emit this invocation's request span. One call per run.
+ *
+ * Duration is read here rather than passed in, so it covers everything from the
+ * invocation's start to this moment. The only part of the run left out is the
+ * telemetry flush, which is what sends this envelope — a span cannot contain
+ * its own delivery.
+ */
+export declare function emitInvocationRequest(name: string, success: boolean, properties?: TelemetryProperties): void;
+/** Drop the scope, so the next invocation in this process opens its own. */
+export declare function resetInvocationRequest(): void;

package/dist/telemetry/logger-telemetry-provider.d.ts

@@ -1,5 +1,4 @@
-import type { ITelemetryProvider } from "./telemetry-provider.js";
-import type { TelemetryProperties } from "./telemetry-service.js";
+import type { ITelemetryProvider, TrackedDependencySpan, TrackedEvent, TrackedException, TrackedSpan } from "./telemetry-provider.js";
 /**
  * Telemetry provider that enriches all events with analyticsUniqueId
  * from the Windows registry and forwards them to the shared logger.
@@ -8,8 +7,8 @@ export declare class LoggerTelemetryProvider implements ITelemetryProvider {
     private readonly analyticsUniqueId;
     constructor();
     private enrich;
-    trackEvent(eventName: string, properties?: TelemetryProperties): Promise<void>;
-    trackException(error: Error, properties?: TelemetryProperties): Promise<void>;
-    trackRequest(name: string, duration: number, success: boolean, properties?: TelemetryProperties): Promise<void>;
-    trackDependency(name: string, type: string, duration: number, success: boolean, properties?: TelemetryProperties): Promise<void>;
+    trackEvent({ name, properties }: TrackedEvent): Promise<void>;
+    trackException({ error, properties, }: TrackedException): Promise<void>;
+    trackRequest({ name, durationMs, success, properties, }: TrackedSpan): Promise<void>;
+    trackDependency({ name, type, durationMs, success, properties, }: TrackedDependencySpan): Promise<void>;
 }

package/dist/telemetry/node-appinsights-telemetry-provider.d.ts

@@ -1,5 +1,4 @@
-import type { ITelemetryProvider } from "./telemetry-provider.js";
-import { type TelemetryProperties } from "./telemetry-service.js";
+import type { ITelemetryProvider, TrackedDependencySpan, TrackedEvent, TrackedException, TrackedSpan } from "./telemetry-provider.js";
 export { getGlobalTelemetryProperties, setGlobalTelemetryProperties, } from "./global-telemetry-properties.js";
 /**
  * Envelopes still buffered in the SDK channel at exit, plus the ingestion
@@ -43,40 +42,29 @@ export declare class NodeAppInsightsTelemetryProvider implements ITelemetryProvi
      */
     private mergeProperties;
     /**
-     * Read the trace context off the internal `uip.trace.*` routing keys and
-     * strip them, so nothing correlation-related ever ships as a custom
-     * dimension. `merged` is a fresh per-call object, so mutating it in place is
-     * safe; the same reference is what the client call emits as `properties`.
+     * Native correlation tags for any tracked item.
      *
-     * `operationId` falls back to the per-invocation id when no context is set
-     * (events outside a `trackRequest` scope), so every item in one run still
-     * groups under the same `operation_Id`. `parentId`/`spanId` are only present
-     * inside a scope.
-     */
-    private consumeCorrelation;
-    /**
-     * Native correlation tags for a LEAF item (event/exception). It has no item
-     * id of its own, so it nests under the current operation: `operation_Id` is
-     * the trace id, and `operation_ParentId` is the enclosing request/
-     * dependency's id (the context's `spanId`), present only inside a scope.
+     * `operation_Id` is the trace; `operation_ParentId` is whatever the item
+     * hangs under — for a span its parent span, for a leaf (event/exception)
+     * the span it was emitted inside. Both arrive as fields on the item, so
+     * one mapping serves requests, dependencies, events and exceptions alike,
+     * and nothing correlation-related has to be read out of — or stripped
+     * from — the custom dimensions.
+     *
+     * `operationId` falls back to the per-invocation id for an item emitted
+     * outside any scope, so every item in one run still groups under the same
+     * `operation_Id`.
      *
      * Cross-service join: `makeTrackedFetch` stamps a W3C `traceparent`
      * (`00-<operation_Id>-<span>-01`) on every outbound call made inside a
      * request scope, so the API side can line its telemetry up with this trace.
      * These native tags are the CLI-side half of that join.
      */
-    private leafTagOverrides;
-    /**
-     * Native correlation for an OPERATION item (request/dependency). It carries
-     * its own item `id` (the context's `spanId`) so child items can point their
-     * `operation_ParentId` at it, and its own `operation_ParentId` is the
-     * context's `parentId` (absent for a top-level request → a trace root).
-     */
-    private operationCorrelation;
-    trackEvent(eventName: string, properties?: TelemetryProperties): Promise<void>;
-    trackException(error: Error, properties?: TelemetryProperties): Promise<void>;
-    trackRequest(name: string, duration: number, success: boolean, properties?: TelemetryProperties): Promise<void>;
-    trackDependency(name: string, type: string, duration: number, success: boolean, properties?: TelemetryProperties, resultCode?: string): Promise<void>;
+    private correlationTags;
+    trackEvent(event: TrackedEvent): Promise<void>;
+    trackException(exception: TrackedException): Promise<void>;
+    trackRequest(span: TrackedSpan): Promise<void>;
+    trackDependency(span: TrackedDependencySpan): Promise<void>;
     flush(): Promise<void>;
     /**
      * Take the envelopes still buffered in the SDK channel (nothing has sent

package/dist/telemetry/node.d.ts

@@ -5,8 +5,8 @@ export { buildEnvironmentProperties, type NormalizedEnvironment, normalizeBaseUr
 export { type CiProvider, detectExecutionContext, EXECUTION_CONTEXT_VALUES, type ExecutionContext, type ExecutionContextDetection, type ExecutionContextDetectionOptions, getExecutionContextTelemetryProperties, setExecutionContextAuthSignal, } from "./execution-context.js";
 export { NodeContextStorage } from "./node-context-storage.js";
 export { getConfiguredTelemetrySessionId, getTelemetrySessionId, getTelemetrySessionSource, TELEMETRY_SESSION_ID_ENV, TELEMETRY_SESSION_SOURCE_PROPERTY, } from "./session-id.js";
-export type { ITelemetryProvider } from "./telemetry-provider.js";
+export type { ITelemetryProvider, TelemetryCorrelation, TrackedDependencySpan, TrackedEvent, TrackedException, TrackedSpan, } from "./telemetry-provider.js";
 export type { ITelemetryService, TelemetryContext, TelemetryProperties, } from "./telemetry-service.js";
-export { TELEMETRY_OPERATION_ID_PROPERTY, TELEMETRY_PARENT_ID_PROPERTY, TELEMETRY_SPAN_ID_PROPERTY, TelemetryService, } from "./telemetry-service.js";
+export { TelemetryService } from "./telemetry-service.js";
 export { getInboundTraceContext, type InboundTraceContext, parseInboundTraceparent, TELEMETRY_TRACEPARENT_ENV, } from "./trace-context.js";
 export { makeTrackedFetch } from "./tracked-fetch.js";

package/dist/telemetry/packaged-name.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Split a pack service's `<name>@<version>` display string.
+ *
+ * `flow-pack-service` and `maestro-pack-service` both return the packed
+ * artifact as one display string — `invoice-process@2.0.0` — and both hand it
+ * straight to telemetry's `package_name`. That breaks the dimension it feeds:
+ * the pseudonym is computed over the whole string, so the same package gets a
+ * different `package_name` for every version, and a publish event can no longer
+ * be joined to the deploy event for the same package. Splitting first is what
+ * makes the pseudonym stable across versions.
+ *
+ * The separator is unambiguous. Both services validate the name against
+ * `VALID_PACKAGE_NAME_REGEX` — letters, numbers, dots, underscores, hyphens —
+ * so a name can never contain `@`, and the last `@` is always the one the
+ * service added. A string with no `@` is returned as a name with no version,
+ * which is the right answer for a caller that already passes a bare name.
+ */
+export interface PackagedName {
+    name: string;
+    version?: string;
+}
+export declare function splitPackagedName(packaged: string): PackagedName;

package/dist/telemetry/pii-redactor.d.ts

@@ -9,29 +9,126 @@
  *      by a sensitive prefix (apiKey, accessKey, signingKey, …) so benign
  *      names like sortKey, cacheKey, keyword pass through.
  *   2. Value detectors — JWTs, UUIDs, emails, URLs, user-home paths are
- *      rewritten to a non-reversible form (hash or structural redaction).
- *      Long strings are truncated.
+ *      rewritten to a pseudonym or structurally redacted. Long strings are
+ *      truncated.
  *
  * The goal is defense in depth: even if a new sensitive option slips through
  * without being added to the denylist, value detectors catch common shapes.
+ *
+ * A pseudonym is NOT anonymous — see `pseudonymize.ts`. It keeps plaintext off
+ * the wire and out of the store, and it joins across events; it does not stop
+ * someone holding a candidate list from confirming a guess. Emitted `email#…` /
+ * `uuid#…` values carry the same handling obligations as the values they stand
+ * in for.
  */
 /**
- * Run the value detectors over a free-form string (no name-based check). Use for
- * strings that aren't property values but can still carry PII — a telemetry
- * event/dependency name (`GET /odata/Users/alice@corp.com`) or an exception
- * message. Emails/UUIDs are hashed, URLs reduced to origin, tokens/JWTs and
- * user-home paths redacted, over-long strings truncated.
+ * Cap on an emitted property value.
+ *
+ * Sized against what redaction ADDS, not just what the caller wrote. Each
+ * detector hit swaps its match for a `kind#<32 hex>` pseudonym, which is 24
+ * characters wider than the 8-hex digest this replaced — so a message carrying
+ * two or three ids or addresses would grow past a 200-character cap and lose its
+ * tail to truncation, taking the HTTP status and the failure shape with it.
+ * 280 restores the headroom the old cap gave before the digests widened, and is
+ * far below the App Insights 8192-character property limit, so nothing
+ * downstream reshapes it.
  */
-export declare function redactValue(value: string): string;
+export declare const MAX_VALUE_LENGTH = 280;
 /**
- * Return a sanitized copy of an Error whose `message` and `stack` have been run
- * through the value detectors, so telemetry never ships a raw exception string
- * (they routinely embed the offending token, URL, path, or id). The original
- * frames are preserved — only their sensitive substrings are rewritten — and
- * the `name` is kept so App Insights still groups by exception type.
+ * Cap on a redacted stack trace.
+ *
+ * A stack is not a dimension and the value cap makes no sense for it: at 280
+ * characters a stack is two or three frames, which is the part every stack has in
+ * common and none of the part that says where the bug is. App Insights allows
+ * 8192 characters per property, so this leaves headroom under it while keeping
+ * enough frames to be worth shipping.
+ */
+export declare const MAX_STACK_LENGTH = 4096;
+/**
+ * Redact a free-form message — an error string built from whatever a server or
+ * an OS sent back.
+ *
+ * The value detectors alone are not enough here. `HTTP 409: Queue
+ * 'BigBank_AG_Inv_2024' is locked by user Jane D.` matches none of them: those
+ * are names, not tokens, URLs or ids. What the message is worth keeping for is
+ * its *shape* — which call failed and how — so the three places customer data
+ * actually sits are removed and the rest is kept:
+ *
+ *   - an embedded JSON body, which is an API response folded into the message;
+ *   - quoted literals, where a server names the offending resource or person;
+ *   - anything this run was *given* as an argument, quoted or not, because the
+ *     CLI's own messages interpolate a value bare (`Unknown agent: bogusagent`
+ *     echoes back exactly the string `trackedAction` had just withheld from the
+ *     `uip.cmd.arg.*` dimensions). See `supplied-values.ts`.
+ *
+ * `HTTP 409: Queue '<redacted>' is locked by user Jane D.` still tells an
+ * operator what happened.
+ *
+ * Order matters: structure first, then the supplied-value scrub. The scrub
+ * emits `[REDACTED]`, and running it before the body pass would let that
+ * placeholder be read as an embedded array. Anything inside a body or a quoted
+ * span is already gone by the time the scrub runs, so nothing is missed by
+ * going in this order.
+ */
+/**
+ * Scrub a span or event NAME.
+ *
+ * A name is not a message, and the difference is the supplied-value scrub. That
+ * scrub is a substring replace over the whole string, and a command path is
+ * made of the same words a user types as arguments: with the full message
+ * treatment, `uip tools install tools` shipped
+ * `requests.name = uip.[REDACTED].install` — the column every command count,
+ * failure rate and duration percentile groups by, destroyed by the run's own
+ * argument. So a name gets the quoted-literal rule, which is what an OData key
+ * predicate needs (`GET /odata/QueueDefinitions('BigBank_AG_Inv_2024')`), plus
+ * the detectors, and nothing that can rewrite a word the CLI itself chose.
+ *
+ * The one name that IS untrusted end to end is the fetch wrapper's
+ * `METHOD /path` — see {@link redactHttpDependencyName}, which
+ * {@link ITelemetryService.trackDependencyResult} calls before this.
+ */
+export declare function redactSpanName(name: string): string;
+/**
+ * Scrub the fetch wrapper's `METHOD /path`, the one name that is untrusted end
+ * to end: a path segment can be an email or an id (`/odata/Users/a@b.com`), a
+ * resource the server quoted, or the exact string the user typed as an argument.
+ * So the PATH gets the full message treatment, supplied-value scrub included —
+ * a command path can never arrive here, which is why the scrub that would wreck
+ * one is safe on this name and on no other.
+ *
+ * The METHOD does not. It is a word the CLI chose, from a set of eight, and the
+ * scrub is a plain substring replace: a run whose own argument was `POST` (or
+ * `HEAD`, `PATCH`, `DELETE`) turned every one of its outbound calls into
+ * `[REDACTED] /path` and took the verb out of the column that separates a read
+ * from a write. Split first, scrub the half that is data.
+ */
+export declare function redactHttpDependencyName(name: string): string;
+export declare function redactMessage(value: string): string;
+/**
+ * Return a sanitized copy of an Error whose `message` and `stack` have been
+ * scrubbed, so telemetry never ships a raw exception string (they routinely
+ * embed the offending token, URL, path, or id). The original frames are
+ * preserved — only their sensitive substrings are rewritten — and the `name` is
+ * kept so App Insights still groups by exception type.
+ *
+ * The message gets {@link redactMessage}, not the detectors alone. An exception
+ * message IS a message: it is where a server names the thing that went wrong
+ * (`Queue 'BigBank_AG_Inv_2024' is locked`), where a response body ends up
+ * inlined, and where the CLI interpolates what the user typed. Running only the
+ * detectors here shipped all three verbatim in `exceptions.message` while the
+ * identical text was scrubbed out of the request row's `errorMessage` — the same
+ * string, two answers, and the looser one on the surface that also carries a
+ * stack.
  */
 export declare function redactError(error: Error): Error;
 type TelemetryValue = string | number | boolean;
+/**
+ * True when a property name looks like it holds credentials. Exported so
+ * `describeThrownValue` can drop the same names when it serializes a thrown
+ * object into a user-facing message — a rejected HTTP client payload often
+ * carries the request's own `Authorization` header.
+ */
+export declare function isSensitiveName(name: string): boolean;
 /**
  * Redact a single telemetry property.
  * Preserves the original value's type (number/boolean pass through unchanged);

package/dist/telemetry/pseudonymize.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The one-way transform every identifying value in telemetry goes through.
+ *
+ * ## What this is, and what it is not
+ *
+ * This produces a **pseudonym**, not an anonymous token. Hashing cannot make a
+ * low-entropy value unrecoverable: anyone holding the telemetry AND a candidate
+ * list (a company's employee directory, a customer's domain list) can hash the
+ * candidates and match. That is true of any unkeyed digest, and the salt below
+ * ships in this source file, so it does not change the analysis. Treat every
+ * `email#…` / `uuid#…` / `origin#…` value as *pseudonymous personal data* under
+ * the same retention and access rules as the raw value would be.
+ *
+ * What the digest DOES buy:
+ *
+ *   - it removes the plaintext from the wire and the store, so nobody reading a
+ *     dashboard, an export, or a spool file sees a customer's address;
+ *   - it is stable, so the same value joins across events and runs;
+ *   - at 128 bits it does not collide, which the previous 32-bit FNV-1a did:
+ *     that space hit a 50% collision chance at ~77k distinct values, so at real
+ *     telemetry volume distinct tenants, projects and people silently merged
+ *     into one bucket — breaking the joins the hash exists for.
+ *
+ * This is the ONLY digest in the telemetry pipeline. `pii-redactor.ts` calls it
+ * directly for every `email#…`, `uuid#…` and `url#…` it writes, rather than
+ * through the FNV-1a wrapper it used to keep. Two strengths for one job would have
+ * left an email on the very payload whose `package_name` is pseudonymized here
+ * carrying the collision risk this file exists to remove. Anything new that
+ * needs to hash an identifying value calls this, and nothing rolls its own.
+ *
+ * ## Two implementations, one digest
+ *
+ * The redactor runs inside `String.prototype.replace` callbacks, so the digest
+ * has to be synchronous — which rules out `crypto.subtle.digest`, the async
+ * one. It does NOT rule out `node:crypto`: `createHash().digest()` is fully
+ * synchronous, and about 36x faster than the pure implementation below (0.28us
+ * against 10.2us on a short string). So Node takes `node:crypto` and the pure
+ * version is the browser fallback, where `node:crypto` does not resolve. Both
+ * produce the same bytes, so a pseudonym computed on either path joins with the
+ * other — and `resolveSha256Hex` checks that rather than assuming it.
+ *
+ * @see hashContent in `../content-hash.ts` for the async SHA-256 used for
+ * content addressing — a different job with no sync constraint.
+ */
+/**
+ * FIPS 180-4 SHA-256 over the UTF-8 bytes of `input`, as 64 lowercase hex.
+ *
+ * The portable reference implementation: the browser fallback, and the value
+ * `resolveSha256Hex` checks `node:crypto` against before adopting it.
+ */
+export declare function sha256Hex(input: string): string;
+/**
+ * The stable pseudonym for an identifying value: 32 lowercase hex characters.
+ *
+ * Read the module comment before treating the output as anonymous — it is not.
+ */
+export declare function pseudonymize(input: string): string;

package/dist/telemetry/span-clock.d.ts

@@ -0,0 +1,27 @@
+/**
+ * One clock reading, serving both halves of a span.
+ *
+ * A span carries two numbers that have to agree: the wall-clock moment it
+ * began, which is where App Insights draws the bar, and its duration, which is
+ * how far the bar extends. Reading `new Date()` for the first and a separate
+ * `performance.now()` baseline for the second samples two clocks at two
+ * moments, and those clocks drift independently — the wall clock can be stepped
+ * by NTP or a suspend/resume mid-span, the monotonic one cannot.
+ *
+ * {@link startSpanClock} reads `performance.now()` once. The start is that
+ * reading projected onto the wall clock through `performance.timeOrigin`, and
+ * the duration is measured back against the same reading, so the bar's position
+ * and its length are two views of a single instant.
+ *
+ * `timings.ts` applies the same projection to the whole invocation
+ * (`invocationStartedAt` / `invocationElapsedMs`); this is that pattern for a
+ * span that opens and closes inside one.
+ */
+export interface SpanClock {
+    /** Wall-clock moment the span opened. */
+    readonly startedAt: Date;
+    /** Milliseconds since it opened, off the monotonic clock. */
+    elapsedMs(): number;
+}
+/** Open a clock for a span that is starting now. */
+export declare function startSpanClock(): SpanClock;

package/dist/telemetry/supplied-values.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The literal strings this run's user typed as argument and option values.
+ *
+ * Held in memory and **never emitted** — the point is the opposite.
+ * `trackedAction` withholds an argument's value from the `uip.cmd.arg.*`
+ * dimensions unless the value cannot carry a payload, but that only covers those
+ * dimensions. Nothing stopped the same string coming back out through a
+ * *message*: a command that says `Unknown agent: bogusagent`, or a server that
+ * says `Queue 'BigBank_AG_Inv_2024' not found`, hands it to
+ * `OutputFormatter.error`, which ships `Message` to telemetry.
+ *
+ * Quoting rules cannot close that, because the CLI's own messages interpolate
+ * the value bare. What closes it is knowing what the user typed and refusing to
+ * echo it — see `redactMessage`.
+ *
+ * Process-wide, like every other telemetry slot on this path, and held as one
+ * ENTRY PER RUN rather than a single list. A long-lived host runs commands
+ * concurrently (the MCP bridge), and a single list made both directions wrong:
+ * the second command to start replaced the first one's values, so the first
+ * stopped scrubbing its own arguments, and the first to finish emptied the list
+ * and stopped scrubbing the second's. With an entry per run, an overlap scrubs
+ * the union — over-scrub, the safe direction — and a run that ends takes only
+ * its own values with it.
+ */
+export interface SuppliedValueEntry {
+    readonly values: readonly string[];
+}
+/**
+ * Record the values this run was given, and return the handle that releases
+ * them again.
+ *
+ * The handle is the entry object itself, so it works across bundles: a number
+ * or a name would have to be unique in a process where several copies of this
+ * module are live, and object identity already is.
+ *
+ * Hand the handle back to {@link releaseSuppliedArgumentValues} when the run
+ * ends — never to {@link clearSuppliedArgumentValues}, which drops every
+ * concurrent run's entries too. The pair is exported together from the package
+ * barrel for that reason: a caller that can record and cannot release leaks its
+ * values into every later run in the process.
+ */
+export declare function recordSuppliedArgumentValues(values: unknown): SuppliedValueEntry;
+/** Drop one run's values, leaving any other run's in place. */
+export declare function releaseSuppliedArgumentValues(entry: SuppliedValueEntry): void;
+/**
+ * Every value a run in flight was given, longest first.
+ *
+ * Longest first so a value that contains another is replaced whole rather than
+ * leaving the tail of it behind.
+ */
+export declare function getSuppliedArgumentValues(): readonly string[];
+/**
+ * Drop every run's values.
+ *
+ * For tests, and for a host that knows nothing is in flight.
+ * `trackedAction` releases its own entry instead — see
+ * {@link releaseSuppliedArgumentValues}.
+ */
+export declare function clearSuppliedArgumentValues(): void;

package/dist/telemetry/telemetry-init.d.ts

@@ -1,5 +1,32 @@
 import type { ITelemetryProvider, ITelemetryService } from "./node.js";
 import { type NodeAppInsightsTelemetryProvider } from "./node-appinsights-telemetry-provider.js";
+/**
+ * The one origin this process is allowed to send telemetry to.
+ *
+ * The spool sender needs this because the URL it POSTs to arrives from a **file
+ * on disk**, and a spool file is not a trusted input — anything running as the
+ * user can drop one in, which on a shared CI agent is any other job on the same
+ * uid. Checking only the scheme (all the sender used to do) let such a file
+ * point the CLI's own sidecar at an arbitrary host and hand it whole envelopes.
+ * Comparing against this closes it: the file supplies the path, never the
+ * destination.
+ *
+ * Read from the connection string rather than hardcoded, so an operator's
+ * `UIPATH_AI_CONNECTION_STRING` (and the e2e suite's local ingestion server)
+ * keeps working — the destination is theirs to choose through configuration,
+ * which is exactly the channel a file on disk is not.
+ *
+ * This has to answer with whatever the SDK would have used, because the URL in
+ * the spool file is the SDK's `config.endpointUrl` and a mismatch means the
+ * file is dropped. `InstrumentationKey=…` with no `IngestionEndpoint` is legal
+ * and common, and the SDK then sends to {@link DEFAULT_INGESTION_ORIGIN} — so
+ * returning "no endpoint" there and failing closed silently discarded every
+ * spooled envelope for anyone using the short form. There is no case left where
+ * a spool file exists and no origin resolves: without a usable instrumentation
+ * key the SDK throws instead of constructing a client, so nothing is ever
+ * spooled.
+ */
+export declare function getTelemetryIngestionOrigin(): string;
 /**
  * Create or retrieve the shared Node.js Application Insights telemetry provider.
  * Uses globalThis to ensure all bundled copies share a single TelemetryClient.

package/dist/telemetry/telemetry-provider.d.ts

@@ -1,31 +1,99 @@
 import type { TelemetryProperties } from "./telemetry-service.js";
 /**
- * Interface for telemetry providers that can be injected into the solution packager.
- * Providers are simple adapters that send pre-measured telemetry data to their backends.
+ * Where an item sits in the trace.
+ *
+ * Every tracked item carries this, because every backend needs it and none of
+ * it belongs in custom dimensions. It used to travel as reserved `uip.trace.*`
+ * keys inside `properties`, which meant each provider had to know the contract,
+ * read the keys, and delete them before emitting — and a provider that forgot
+ * (the logger one, the browser one) shipped raw correlation ids as dimensions.
+ * An item that describes itself needs no such contract.
  */
+export interface TelemetryCorrelation {
+    /** The trace this item belongs to (`operation_Id`). */
+    operationId?: string;
+    /**
+     * The span this item hangs under (`operation_ParentId`). For a span, the
+     * span containing it — absent on a trace root. For a leaf, the span it was
+     * emitted inside — absent outside any span scope.
+     */
+    parentId?: string;
+}
+/**
+ * One finished span, as a provider receives it.
+ *
+ * Everything the backend needs about a request or dependency arrives as this
+ * one object: what it was, how long it took, whether it worked, when it began,
+ * and where it sits in the trace.
+ */
+export interface TrackedSpan extends TelemetryCorrelation {
+    /** Operation name — the command path, or `METHOD /path` for a call. */
+    name: string;
+    /** Measured wall-clock length, in milliseconds. */
+    durationMs: number;
+    success: boolean;
+    /**
+     * When the span began.
+     *
+     * App Insights reads this as the span START and draws the bar forward by
+     * `durationMs`. A provider whose backend timestamps on arrival must use it;
+     * without it, the only start available is the moment of emit, which charges
+     * the bar for everything that happened after the clock stopped.
+     */
+    startedAt?: Date;
+    /** This span's own id, which its children point their parent id at. */
+    id?: string;
+    /** Custom dimensions. Correlation is not among them — see above. */
+    properties?: TelemetryProperties;
+}
+/** A {@link TrackedSpan} for an outbound call. */
+export interface TrackedDependencySpan extends TrackedSpan {
+    /** Dependency kind, e.g. `HTTP`. */
+    type: string;
+    /**
+     * Backend-native status of the call (e.g. the HTTP status code). Omitted,
+     * a provider derives a coarse code from `success`; supplying the real one
+     * keeps `dependencies.resultCode` truthful instead of collapsing every
+     * outcome to 200/500.
+     */
+    resultCode?: string;
+}
+/**
+ * One event, as a provider receives it.
+ *
+ * A leaf: it marks an instant rather than an interval, so it has no duration
+ * and no id of its own. It nests under whichever span was open when it was
+ * emitted, via {@link TelemetryCorrelation.parentId}.
+ */
+export interface TrackedEvent extends TelemetryCorrelation {
+    name: string;
+    /** Custom dimensions. Correlation is not among them. */
+    properties?: TelemetryProperties;
+}
+/** A {@link TrackedEvent}-shaped leaf carrying an error instead of a name. */
+export interface TrackedException extends TelemetryCorrelation {
+    /** Already redacted by the service — providers emit it as-is. */
+    error: Error;
+    /** Custom dimensions. Correlation is not among them. */
+    properties?: TelemetryProperties;
+}
 export interface ITelemetryProvider {
     /**
-     * Track a custom event with optional properties.
+     * Track a custom event.
      */
-    trackEvent(eventName: string, properties?: TelemetryProperties): Promise<void>;
+    trackEvent(event: TrackedEvent): Promise<void>;
     /**
-     * Track an exception with optional properties.
+     * Track an exception.
      */
-    trackException(error: Error, properties?: TelemetryProperties): Promise<void>;
+    trackException(exception: TrackedException): Promise<void>;
     /**
-     * Track a completed request operation with measured duration.
+     * Track a completed request operation.
      */
-    trackRequest(name: string, duration: number, success: boolean, properties?: TelemetryProperties): Promise<void>;
+    trackRequest(span: TrackedSpan): Promise<void>;
     /**
-     * Track a completed dependency operation with measured duration.
-     *
-     * `resultCode` is the backend-native status of the call (e.g. the HTTP
-     * status code for an outbound request). When omitted the provider derives a
-     * coarse code from `success`. Passing the real code keeps the App Insights
-     * `dependencies.resultCode` column accurate instead of collapsing every
-     * outcome to 200/500.
+     * Track a completed dependency operation.
      */
-    trackDependency(name: string, type: string, duration: number, success: boolean, properties?: TelemetryProperties, resultCode?: string): Promise<void>;
+    trackDependency(span: TrackedDependencySpan): Promise<void>;
     /**
      * Get the current session ID, if available.
      */