@uipath/uipath-typescript 1.4.2 → 1.5.1

package/dist/tasks/index.mjs

@@ -713,7 +713,16 @@ var PaginationType;
  * Returns the original value if parsing fails.
  */
 /**
- * Transforms data by mapping fields according to the provided field mapping
+ * Transforms data by renaming each key in `data` exactly once, using the
+ * mapping (`sourceField → targetField`). Keys not present in the mapping
+ * pass through unchanged. The original (pre-rename) key is dropped — the
+ * result contains only the renamed key.
+ *
+ * Each rename is independent. If the mapping happens to contain chained
+ * entries (`a → b` and `b → c`), they do NOT compose: a field named `a`
+ * in `data` becomes `b` (not `c`), because the renames are applied based
+ * on the original data's keys, not the running result.
+ *
  * @param data The source data to transform
  * @param fieldMapping Object mapping source field names to target field names
  * @returns Transformed data with mapped field names
@@ -736,21 +745,28 @@ var PaginationType;
  * //   { userId: '123', name: 'john' },
  * //   { userId: '456', name: 'jane' }
  * // ]
+ *
+ * // No chaining — `a → b` does not become `a → c` even if the map has `b → c`.
+ * transformData({ a: 1 }, { a: 'b', b: 'c' });
+ * // result = { b: 1 }
  * ```
  */
 function transformData(data, fieldMapping) {
+    // Pass null/undefined through unchanged — callers (e.g. AttachmentService.getById)
+    // may invoke this on optional fields that an OData `select` excluded.
+    if (data == null) {
+        return data;
+    }
     // Handle array of objects
     if (Array.isArray(data)) {
         return data.map(item => transformData(item, fieldMapping));
     }
-    // Handle single object
-    const result = { ...data };
-    for (const [sourceField, targetField] of Object.entries(fieldMapping)) {
-        if (sourceField in result) {
-            const value = result[sourceField];
-            delete result[sourceField];
-            result[targetField] = value;
-        }
+    // Walk the ORIGINAL data's keys, look up each in the mapping. One rename
+    // per data key — no mutation of an in-progress result, so chains can't form.
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+        const renamedKey = fieldMapping[key] ?? key;
+        result[renamedKey] = value;
     }
     return result;
 }
@@ -965,6 +981,97 @@ function addPrefixToKeys(obj, prefix, keys) {
     }
     return result;
 }
+/**
+ * Creates a new map with the keys and values reversed
+ * @param map The original map to reverse
+ * @returns A new map with keys and values swapped
+ *
+ * @example
+ * ```typescript
+ * const original = { key1: 'value1', key2: 'value2' };
+ * const reversed = reverseMap(original);
+ * // reversed = { value1: 'key1', value2: 'key2' }
+ * ```
+ */
+function reverseMap(map) {
+    return Object.entries(map).reduce((acc, [key, value]) => {
+        acc[value] = key;
+        return acc;
+    }, {});
+}
+/**
+ * OData query-string keys whose values may contain field identifiers that
+ * need rewriting from SDK names → API names.
+ */
+const ODATA_FIELD_PARAM_KEYS = ['filter', 'orderby', 'select', 'expand'];
+/**
+ * Matches one token at a time in an OData expression:
+ *   1. A single-quoted string literal, allowing the `''` escape sequence —
+ *      consumed atomically so identifiers inside the literal can't match.
+ *   2. An OData identifier (`[A-Za-z_][A-Za-z0-9_]*`).
+ * Anything else (whitespace, operators, parens, commas) is left alone by
+ * `String.prototype.replace`, which only substitutes matched substrings.
+ */
+const ODATA_TOKEN_RE = /'(?:[^']|'')*'|[A-Za-z_][A-Za-z0-9_]*/g;
+/**
+ * Rewrites SDK field identifiers to API field identifiers inside an OData
+ * expression string (`$filter`, `$orderby`, `$select`, `$expand`).
+ *
+ * Field maps (e.g. `JobMap`) rename API fields → SDK fields on responses, so
+ * SDK consumers see the renamed names. Without this rewrite, the same name
+ * in a `filter` string would be forwarded verbatim and the API (which still
+ * uses the original name) would reject it.
+ *
+ * Quoted string literals (with the OData `''` escape) are preserved exactly:
+ * the token regex consumes them whole, so identifiers inside literals never
+ * match. Identifier tokens are looked up in the reversed field map.
+ *
+ * @example
+ * ```typescript
+ * const requestMap = { processName: 'releaseName' };
+ * rewriteODataIdentifiers("processName eq 'processName'", requestMap);
+ * // "releaseName eq 'processName'"  — identifier rewritten, literal preserved
+ * ```
+ */
+function rewriteODataIdentifiers(expression, requestMap) {
+    if (!expression)
+        return expression;
+    return expression.replace(ODATA_TOKEN_RE, (match) => match.startsWith("'") ? match : (requestMap[match] ?? match));
+}
+/**
+ * Symmetric counterpart of {@link transformRequest} for OData query options:
+ * rewrites SDK field identifiers inside the recognized OData string params
+ * (`filter`, `orderby`, `select`, `expand`) to their API names using the
+ * reversed form of a response field map. Returns a shallow copy with the
+ * relevant values rewritten; other keys pass through unchanged.
+ *
+ * Use at the OData edge so SDK consumers can refer to renamed fields by
+ * their SDK name throughout — for reading the response and for filtering /
+ * sorting / projecting / expanding.
+ *
+ * @param options The OData query options as authored with SDK field names
+ * @param responseMap The response field map (API → SDK); reversed internally
+ *
+ * @example
+ * ```typescript
+ * // JobMap renames releaseName → processName on responses.
+ * transformOptions({ filter: "processName eq 'X'" }, JobMap);
+ * // { filter: "releaseName eq 'X'" }
+ * ```
+ */
+function transformOptions(options, responseMap) {
+    const requestMap = reverseMap(responseMap);
+    if (Object.keys(requestMap).length === 0)
+        return options;
+    const result = { ...options };
+    for (const key of ODATA_FIELD_PARAM_KEYS) {
+        const value = result[key];
+        if (typeof value === 'string') {
+            result[key] = rewriteODataIdentifiers(value, requestMap);
+        }
+    }
+    return result;
+}
 
 /**
  * Constants used throughout the pagination system
@@ -2258,6 +2365,10 @@ class TaskService extends BaseService {
             const transformedTask = transformData(pascalToCamelCaseKeys(task), TaskMap);
             return createTaskWithMethods(applyDataTransforms(transformedTask, { field: 'status', valueMap: TaskStatusMap }), this);
         };
+        // Rewrite renamed SDK field names → API names inside OData strings
+        // before delegating, mirroring the transformRequest pattern used for
+        // request bodies.
+        const apiOptions = options ? transformOptions(options, TaskMap) : options;
         return PaginationHelpers.getAll({
             serviceAccess: this.createPaginationServiceAccess(),
             getEndpoint: () => endpoint,
@@ -2274,7 +2385,7 @@ class TaskService extends BaseService {
                     countParam: ODATA_OFFSET_PARAMS.COUNT_PARAM // OData OFFSET parameter
                 }
             }
-        }, options);
+        }, apiOptions);
     }
     /**
      * Gets a task by ID
@@ -2310,9 +2421,10 @@ class TaskService extends BaseService {
         const headers = createHeaders({ [FOLDER_ID]: folderId });
         // Add default expand parameters
         const modifiedOptions = this.addDefaultExpand(restOptions);
-        // prefix all keys in options
-        const keysToPrefix = Object.keys(modifiedOptions);
-        const apiOptions = addPrefixToKeys(modifiedOptions, ODATA_PREFIX, keysToPrefix);
+        // Rewrite renamed SDK field names → API names inside OData strings,
+        // then prefix all keys for OData.
+        const apiFieldOptions = transformOptions(modifiedOptions, TaskMap);
+        const apiOptions = addPrefixToKeys(apiFieldOptions, ODATA_PREFIX, Object.keys(apiFieldOptions));
         const response = await this.get(TASK_ENDPOINTS.GET_BY_ID(id), {
             params: apiOptions,
             headers

package/dist/traces/index.cjs

@@ -948,6 +948,17 @@ const TRACEVIEW_SPANS_PAGINATION = {
     /** Total count path — same envelope location as the agents list. */
     TOTAL_COUNT_FIELD: AGENTS_PAGINATION.TOTAL_COUNT_FIELD
 };
+/**
+ * Governance decisions pagination constants — decision rows sit directly
+ * under `items`. This endpoint returns no total-count field, so no
+ * `TOTAL_COUNT_FIELD` is defined; `hasNextPage` falls back to page-fullness
+ * (a full page implies there may be more). Request params reuse
+ * {@link AGENTS_OFFSET_PARAMS} (pageSize + 0-based pageNumber).
+ */
+const GOVERNANCE_DECISIONS_PAGINATION = {
+    /** Field name for the decision-rows array in the response. */
+    ITEMS_FIELD: 'items',
+};
 /**
  * OData OFFSET pagination parameter names (ODATA-style)
  */
@@ -1839,12 +1850,16 @@ const AGENT_TRACES_ENDPOINTS = {
     GET_ERRORS_TIMELINE: `${INSIGHTS_RTM_BASE}/Traceview/errorsTimeline`,
     /** Trace-level time-series of latency (decimal seconds per series). */
     GET_LATENCY_TIMELINE: `${INSIGHTS_RTM_BASE}/Traceview/latencyTimeline`,
-    /** Trace-level per-agent AGU/PLTU consumption totals. */
+    /** Trace-level per-agent Agent Units and Platform Units consumption totals. */
     GET_UNIT_CONSUMPTION: `${INSIGHTS_RTM_BASE}/Traceview/unitConsumption`,
     /** All spans for a single trace (flat array, not paginated). */
     GET_SPANS_BY_TRACE_ID: (traceId) => `${INSIGHTS_RTM_BASE}/Traceview/spans/${traceId}`,
     /** Paginated spans whose reference hierarchy contains the given reference id. */
     GET_SPANS_BY_REFERENCE: (referenceId) => `${INSIGHTS_RTM_BASE}/Traceview/spans/reference/${referenceId}`,
+    /** Paginated raw governance decision rows. */
+    GET_GOVERNANCE_DECISIONS: `${INSIGHTS_RTM_BASE}/Governance/agentic/traces`,
+    /** Aggregated governance posture (totals + top-N breakdowns). */
+    GET_GOVERNANCE_SUMMARY: `${INSIGHTS_RTM_BASE}/Governance/agentic/summary`,
 };
 
 /**
@@ -1983,6 +1998,52 @@ __decorate([
     track('Traces.GetSpansByIds')
 ], TracesService.prototype, "getSpansByIds", null);
 
+// ─── Governance ─────────────────────────────────────────────────────
+/**
+ * Evaluation mode of a governance decision.
+ */
+exports.AgentGovernanceMode = void 0;
+(function (AgentGovernanceMode) {
+    /** Policy evaluated and logged, but not enforced. */
+    AgentGovernanceMode["Audit"] = "AUDIT";
+    /** Policy evaluated and enforced. */
+    AgentGovernanceMode["Enforce"] = "ENFORCE";
+    /** Unrecognized or missing mode. */
+    AgentGovernanceMode["Unknown"] = "Unknown";
+})(exports.AgentGovernanceMode || (exports.AgentGovernanceMode = {}));
+/**
+ * Verdict of a governance decision (`Deny` = violation).
+ */
+exports.AgentGovernanceVerdict = void 0;
+(function (AgentGovernanceVerdict) {
+    /** Allowed — not a violation. */
+    AgentGovernanceVerdict["Allow"] = "ALLOW";
+    /** Denied — counts as a violation. */
+    AgentGovernanceVerdict["Deny"] = "DENY";
+    /** Unrecognized or missing verdict. */
+    AgentGovernanceVerdict["Unknown"] = "Unknown";
+})(exports.AgentGovernanceVerdict || (exports.AgentGovernanceVerdict = {}));
+/**
+ * Sections the governance summary can compute. `action` and `mode` are opt-in.
+ */
+exports.AgentGovernanceSection = void 0;
+(function (AgentGovernanceSection) {
+    /** Scalar totals (`total`, `violations`). */
+    AgentGovernanceSection["Totals"] = "totals";
+    /** Breakdown by governance hook. */
+    AgentGovernanceSection["Hook"] = "hook";
+    /** Breakdown by agent. */
+    AgentGovernanceSection["Agent"] = "agent";
+    /** Breakdown by policy. */
+    AgentGovernanceSection["Policy"] = "policy";
+    /** Breakdown by governance pack. */
+    AgentGovernanceSection["Pack"] = "pack";
+    /** Breakdown by enforcement action (opt-in). */
+    AgentGovernanceSection["Action"] = "action";
+    /** Breakdown by evaluation mode (opt-in). */
+    AgentGovernanceSection["Mode"] = "mode";
+})(exports.AgentGovernanceSection || (exports.AgentGovernanceSection = {}));
+
 /**
  * Maps a raw span record to a {@link AgentSpanGetResponse}
  */
@@ -1990,6 +2051,22 @@ const transformSpan = (span) => {
     const { expiryTimeUtc, ...rest } = span;
     return { ...rest, expiredTime: expiryTimeUtc };
 };
+// Case-insensitive lookups from a raw API value → enum member (keys upper-cased).
+const GOVERNANCE_MODE_BY_VALUE = new Map(Object.values(exports.AgentGovernanceMode).map((mode) => [mode.toUpperCase(), mode]));
+const GOVERNANCE_VERDICT_BY_VALUE = new Map(Object.values(exports.AgentGovernanceVerdict).map((verdict) => [verdict.toUpperCase(), verdict]));
+/** Maps a raw mode string to {@link AgentGovernanceMode}, case-insensitively; missing/unrecognized → `Unknown`. */
+const toGovernanceMode = (raw) => (raw != null ? GOVERNANCE_MODE_BY_VALUE.get(raw.toUpperCase()) : undefined) ?? exports.AgentGovernanceMode.Unknown;
+/** Maps a raw verdict string to {@link AgentGovernanceVerdict}, case-insensitively; missing/unrecognized → `Unknown`. */
+const toGovernanceVerdict = (raw) => (raw != null ? GOVERNANCE_VERDICT_BY_VALUE.get(raw.toUpperCase()) : undefined) ?? exports.AgentGovernanceVerdict.Unknown;
+/**
+ * Normalizes a raw governance row, mapping the mode and verdict strings to
+ * their enums while leaving the other fields untouched.
+ */
+const transformGovernanceDecision = (row) => ({
+    ...row,
+    mode: toGovernanceMode(row.mode),
+    evaluatorResult: toGovernanceVerdict(row.evaluatorResult),
+});
 /**
  * Service for retrieving UiPath Agent trace metrics.
  */
@@ -2078,7 +2155,7 @@ class AgentTracesService extends BaseService {
      * // Get per-agent unit consumption
      * const result = await trace.getUnitConsumption();
      * result.forEach((row) => {
-     *   console.log(`${row.agentId}: ${row.agentUnitsConsumed} AGU, ${row.platformUnitsConsumed} PLTU`);
+     *   console.log(`${row.agentId}: ${row.agentUnitsConsumed} Agent Units, ${row.platformUnitsConsumed} Platform Units`);
      * });
      * ```
      * @example
@@ -2125,10 +2202,6 @@ class AgentTracesService extends BaseService {
     /**
      * Retrieves spans whose reference hierarchy contains the given reference id.
      *
-     * Returns a {@link PaginatedResponse} when pagination options (`pageSize`,
-     * `cursor`, or `jumpToPage`) are provided, otherwise a
-     * {@link NonPaginatedResponse}.
-     *
      * @param referenceId - Reference id matched against each span's reference hierarchy
      * @param options - Optional pagination and hierarchy/time filters
      * @returns Promise resolving to a paginated or non-paginated list of {@link AgentSpanGetResponse}
@@ -2189,6 +2262,141 @@ class AgentTracesService extends BaseService {
             },
         }, apiOptions);
     }
+    /**
+     * Lists individual governance decisions from agent execution traces — each
+     * policy check's allow/deny outcome with its agent, policy, pack, hook, and
+     * mode, plus the trace it belongs to — over the requested window. Filterable
+     * and paginated.
+     *
+     * @remarks Requires the caller to be an organization admin. Non-admin callers get a `403` and the SDK throws an {@link AuthorizationError}.
+     *
+     * @param startTime - Inclusive lower bound for the query window
+     * @param options - Optional window end, filters, and pagination
+     * @returns Promise resolving to a paginated or non-paginated list of {@link AgentGovernanceDecisionGetResponse}
+     * @example
+     * ```typescript
+     * import { AgentTraces } from '@uipath/uipath-typescript/traces';
+     *
+     * const trace = new AgentTraces(sdk);
+     *
+     * // Decision rows since a start time
+     * const result = await trace.getGovernanceDecisions(new Date('2025-05-01T00:00:00Z'));
+     * result.items.forEach((row) => {
+     *   console.log(`${row.hook} ${row.policyId}: ${row.evaluatorResult}`);
+     * });
+     * ```
+     * @example
+     * ```typescript
+     * // Violations only, for one agent, paginated
+     * const page = await trace.getGovernanceDecisions(new Date('2025-05-01T00:00:00Z'), {
+     *   endTime: new Date('2025-06-01T00:00:00Z'),
+     *   violationsOnly: true,
+     *   agentId: '<agentProjectKey>',
+     *   pageSize: 25,
+     * });
+     * if (page.hasNextPage && page.nextCursor) {
+     *   const next = await trace.getGovernanceDecisions(new Date('2025-05-01T00:00:00Z'), { cursor: page.nextCursor });
+     * }
+     * ```
+     * @example
+     * ```typescript
+     * import { isAuthorizationError } from '@uipath/uipath-typescript/core';
+     *
+     * // Non-admin callers get a 403
+     * try {
+     *   await trace.getGovernanceDecisions(new Date('2025-05-01T00:00:00Z'));
+     * } catch (error) {
+     *   if (isAuthorizationError(error)) {
+     *     console.error('Governance data requires an organization admin.');
+     *   }
+     * }
+     * ```
+     */
+    async getGovernanceDecisions(startTime, options) {
+        const { endTime, ...rest } = options ?? {};
+        const apiOptions = {
+            ...rest,
+            startTime: startTime.toISOString(),
+            ...(endTime !== undefined ? { endTime: endTime.toISOString() } : {}),
+        };
+        return PaginationHelpers.getAll({
+            serviceAccess: this.createPaginationServiceAccess(),
+            getEndpoint: () => AGENT_TRACES_ENDPOINTS.GET_GOVERNANCE_DECISIONS,
+            method: HTTP_METHODS.POST,
+            transformFn: transformGovernanceDecision,
+            excludeFromPrefix: Object.keys(apiOptions),
+            pagination: {
+                paginationType: PaginationType.OFFSET,
+                itemsField: GOVERNANCE_DECISIONS_PAGINATION.ITEMS_FIELD,
+                paginationParams: {
+                    pageSizeParam: AGENTS_OFFSET_PARAMS.PAGE_SIZE_PARAM,
+                    offsetParam: AGENTS_OFFSET_PARAMS.OFFSET_PARAM,
+                    countParam: AGENTS_OFFSET_PARAMS.COUNT_PARAM,
+                    convertToSkip: false,
+                    zeroBased: true,
+                },
+            },
+        }, apiOptions);
+    }
+    /**
+     * Summarizes governance decisions across agent execution traces — total
+     * decisions and violations, plus top breakdowns by hook, agent, policy, and
+     * pack — over the requested window. Filterable.
+     *
+     * @remarks Requires the caller to be an organization admin. Non-admin callers get a `403` and the SDK throws an {@link AuthorizationError}.
+     *
+     * @param startTime - Inclusive lower bound for the query window
+     * @param options - Optional window end, top-N, pack scope, and sections
+     * @returns Promise resolving to {@link AgentGovernanceGetSummaryResponse}
+     * @example
+     * ```typescript
+     * import { AgentTraces } from '@uipath/uipath-typescript/traces';
+     *
+     * const trace = new AgentTraces(sdk);
+     *
+     * // Default posture since a start time
+     * const summary = await trace.getGovernanceSummary(new Date('2025-05-01T00:00:00Z'));
+     * console.log(`${summary.violations} / ${summary.total} violations`);
+     * summary.byPolicy.forEach((p) => console.log(`${p.key}: ${p.violationCount}`));
+     * ```
+     * @example
+     * ```typescript
+     * import { AgentGovernanceSection } from '@uipath/uipath-typescript/traces';
+     *
+     * // Top 5 per breakdown, scoped to a pack, including the opt-in action/mode sections
+     * const summary = await trace.getGovernanceSummary(new Date('2025-05-01T00:00:00Z'), {
+     *   topN: 5,
+     *   packName: 'ISO/IEC 42001:2023 Runtime',
+     *   sections: [AgentGovernanceSection.Action, AgentGovernanceSection.Mode],
+     * });
+     * ```
+     * @example
+     * ```typescript
+     * import { isAuthorizationError } from '@uipath/uipath-typescript/core';
+     *
+     * // Non-admin callers get a 403
+     * try {
+     *   await trace.getGovernanceSummary(new Date('2025-05-01T00:00:00Z'));
+     * } catch (error) {
+     *   if (isAuthorizationError(error)) {
+     *     console.error('Governance data requires an organization admin.');
+     *   }
+     * }
+     * ```
+     */
+    async getGovernanceSummary(startTime, options) {
+        const body = { startTime: startTime.toISOString() };
+        if (options?.endTime !== undefined)
+            body.endTime = options.endTime.toISOString();
+        if (options?.topN !== undefined)
+            body.topN = options.topN;
+        if (options?.packName !== undefined)
+            body.packName = options.packName;
+        if (options?.sections !== undefined)
+            body.sections = options.sections;
+        const response = await this.post(AGENT_TRACES_ENDPOINTS.GET_GOVERNANCE_SUMMARY, body);
+        return response.data;
+    }
     buildTraceFilterBody(options) {
         const body = {};
         if (options?.startTime !== undefined)
@@ -2221,6 +2429,12 @@ __decorate([
 __decorate([
     track('AgentTraces.GetSpansByReference')
 ], AgentTracesService.prototype, "getSpansByReference", null);
+__decorate([
+    track('AgentTraces.GetGovernanceDecisions')
+], AgentTracesService.prototype, "getGovernanceDecisions", null);
+__decorate([
+    track('AgentTraces.GetGovernanceSummary')
+], AgentTracesService.prototype, "getGovernanceSummary", null);
 
 exports.AgentTraceExecutionType = exports.SpanExecutionType;
 exports.AgentTraces = AgentTracesService;