@uipath/uipath-typescript 1.4.0 → 1.4.2

package/dist/traces/index.cjs

@@ -919,6 +919,35 @@ const ODATA_PREFIX = '$';
 const HTTP_METHODS = {
     GET: 'GET',
     POST: 'POST'};
+/**
+ * Agents pagination constants — items and total count are nested under the response envelope
+ */
+const AGENTS_PAGINATION = {
+    /** Dotted path to the total count in the agents response envelope */
+    TOTAL_COUNT_FIELD: 'pagination.totalCount'
+};
+/**
+ * Agents OFFSET pagination parameter names (page-number style, 0-based, no skip conversion)
+ */
+const AGENTS_OFFSET_PARAMS = {
+    /** Page size parameter name */
+    PAGE_SIZE_PARAM: 'pageSize',
+    /** Page number parameter name (sent directly, 0-based) */
+    OFFSET_PARAM: 'pageNumber',
+    /** No count param needed */
+    COUNT_PARAM: undefined
+};
+/**
+ * Traceview spans pagination constants — items sit directly under `data`,
+ * total count under the same envelope location as the agents list. Request
+ * params reuse {@link AGENTS_OFFSET_PARAMS} (pageSize + 0-based pageNumber).
+ */
+const TRACEVIEW_SPANS_PAGINATION = {
+    /** Field name for the spans array in the response envelope */
+    ITEMS_FIELD: 'data',
+    /** Total count path — same envelope location as the agents list. */
+    TOTAL_COUNT_FIELD: AGENTS_PAGINATION.TOTAL_COUNT_FIELD
+};
 /**
  * OData OFFSET pagination parameter names (ODATA-style)
  */
@@ -1205,12 +1234,18 @@ class PaginationHelpers {
      * @returns Promise resolving to a paginated result
      */
     static async getAllPaginated(params) {
-        const { serviceAccess, getEndpoint, folderId, headers: providedHeaders, paginationParams, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
+        const { serviceAccess, getEndpoint, folderId, headers: providedHeaders, paginationParams, additionalParams, queryParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
         const endpoint = getEndpoint(folderId);
         const headers = providedHeaders ?? (folderId ? createHeaders({ [FOLDER_ID]: folderId }) : {});
+        // On POST, the caller's options go in the body; queryParams stays in the URL.
+        // On GET, everything is URL — queryParams merges with additionalParams.
+        const isPost = method === HTTP_METHODS.POST;
+        const requestSpec = isPost
+            ? { body: additionalParams, params: queryParams }
+            : { params: { ...additionalParams, ...queryParams } };
         const paginatedResponse = await serviceAccess.requestWithPagination(method, endpoint, paginationParams, {
             headers,
-            params: additionalParams,
+            ...requestSpec,
             pagination: {
                 paginationType: options.paginationType || PaginationType.OFFSET,
                 itemsField: options.itemsField || DEFAULT_ITEMS_FIELD,
@@ -1235,7 +1270,7 @@ class PaginationHelpers {
      * @returns Promise resolving to an object with data and totalCount
      */
     static async getAllNonPaginated(params) {
-        const { serviceAccess, getAllEndpoint, getByFolderEndpoint, folderId, headers: providedHeaders, additionalParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
+        const { serviceAccess, getAllEndpoint, getByFolderEndpoint, folderId, headers: providedHeaders, additionalParams, queryParams, transformFn, method = HTTP_METHODS.GET, options = {} } = params;
         // Set default field names
         const itemsField = options.itemsField || DEFAULT_ITEMS_FIELD;
         const totalCountField = options.totalCountField || DEFAULT_TOTAL_COUNT_FIELD;
@@ -1245,11 +1280,11 @@ class PaginationHelpers {
         // Make the API call based on method
         let response;
         if (method === HTTP_METHODS.POST) {
-            response = await serviceAccess.post(endpoint, additionalParams, { headers });
+            response = await serviceAccess.post(endpoint, additionalParams, { headers, params: queryParams });
         }
         else {
             response = await serviceAccess.get(endpoint, {
-                params: additionalParams,
+                params: { ...additionalParams, ...queryParams },
                 headers
             });
         }
@@ -1304,6 +1339,7 @@ class PaginationHelpers {
                 headers: config.headers,
                 paginationParams: cursor ? { cursor, pageSize } : jumpToPage !== undefined ? { jumpToPage, pageSize } : { pageSize },
                 additionalParams: prefixedOptions,
+                queryParams: config.queryParams,
                 transformFn: config.transformFn,
                 method: config.method,
                 options: {
@@ -1321,6 +1357,7 @@ class PaginationHelpers {
             folderId,
             headers: config.headers,
             additionalParams: prefixedOptions,
+            queryParams: config.queryParams,
             transformFn: config.transformFn,
             method: config.method,
             options: {
@@ -1512,18 +1549,17 @@ class BaseService {
         const params = this.validateAndPreparePaginationParams(paginationType, paginationOptions);
         // Prepare request parameters based on pagination type
         const requestParams = this.preparePaginationRequestParams(paginationType, params, options.pagination);
-        // For POST requests, merge pagination params into body and set params to undefined; for GET, use query params
+        // Route pagination state to wherever the API expects it (body for POST, URL for GET).
+        // Caller-supplied options.body / options.params are respected as-is — the api-client
+        // already handles params (URL) and body (request body) independently for every method.
         if (method.toUpperCase() === 'POST') {
             const existingBody = (options.body && typeof options.body === 'object') ? options.body : {};
             options.body = {
                 ...existingBody,
-                ...options.params,
                 ...requestParams
             };
-            options.params = undefined;
         }
         else {
-            // Merge pagination parameters with existing parameters
             options.params = {
                 ...options.params,
                 ...requestParams
@@ -1793,6 +1829,23 @@ const SpanAttachmentDirectionMap = {
  * Base path constants for different services
  */
 const LLMOPS_BASE = 'llmopstenant_';
+const INSIGHTS_RTM_BASE = 'insightsrtm_';
+
+/**
+ * Agent Traces Service Endpoints
+ */
+const AGENT_TRACES_ENDPOINTS = {
+    /** Trace-level time-series of error counts grouped by error name. */
+    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. */
+    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}`,
+};
 
 /**
  * Traces Service Endpoints
@@ -1930,4 +1983,245 @@ __decorate([
     track('Traces.GetSpansByIds')
 ], TracesService.prototype, "getSpansByIds", null);
 
+/**
+ * Maps a raw span record to a {@link AgentSpanGetResponse}
+ */
+const transformSpan = (span) => {
+    const { expiryTimeUtc, ...rest } = span;
+    return { ...rest, expiredTime: expiryTimeUtc };
+};
+/**
+ * Service for retrieving UiPath Agent trace metrics.
+ */
+class AgentTracesService extends BaseService {
+    /**
+     * Retrieves a trace-level time-series of error counts grouped by error name.
+     *
+     * @param options - Optional window and filters
+     * @returns Promise resolving to an array of {@link AgentTraceGetErrorsTimelineResponse}
+     * @example
+     * ```typescript
+     * import { AgentTraces } from '@uipath/uipath-typescript/traces';
+     *
+     * const trace = new AgentTraces(sdk);
+     *
+     * // Get the errors timeline
+     * const result = await trace.getErrorsTimeline();
+     * result.forEach((point) => {
+     *   console.log(`${point.date} ${point.name}: ${point.value} errors`);
+     * });
+     * ```
+     * @example
+     * ```typescript
+     * import { AgentTraceExecutionType } from '@uipath/uipath-typescript/traces';
+     *
+     * // Get the errors timeline for an agent version within a time window
+     * const filtered = await trace.getErrorsTimeline({
+     *   startTime: new Date('2025-05-01T00:00:00Z'),
+     *   endTime: new Date('2025-06-01T00:00:00Z'),
+     *   agentId: '<agentId>',
+     *   agentVersion: '1.0.0',
+     *   executionType: AgentTraceExecutionType.Runtime,
+     * });
+     * ```
+     */
+    async getErrorsTimeline(options) {
+        const response = await this.post(AGENT_TRACES_ENDPOINTS.GET_ERRORS_TIMELINE, this.buildTraceFilterBody(options));
+        return response.data.data;
+    }
+    /**
+     * Retrieves a trace-level time-series of latency.
+     *
+     * @param options - Optional window and filters
+     * @returns Promise resolving to an array of {@link AgentTraceGetLatencyTimelineResponse}
+     * @example
+     * ```typescript
+     * import { AgentTraces } from '@uipath/uipath-typescript/traces';
+     *
+     * const trace = new AgentTraces(sdk);
+     *
+     * // Get the latency timeline
+     * const result = await trace.getLatencyTimeline();
+     * result.forEach((point) => {
+     *   console.log(`${point.date} ${point.name}: ${point.value}s`);
+     * });
+     * ```
+     * @example
+     * ```typescript
+     * import { AgentTraceExecutionType } from '@uipath/uipath-typescript/traces';
+     *
+     * // Get the latency timeline for an agent version within a time window
+     * const filtered = await trace.getLatencyTimeline({
+     *   startTime: new Date('2025-05-01T00:00:00Z'),
+     *   endTime: new Date('2025-06-01T00:00:00Z'),
+     *   agentId: '<agentId>',
+     *   agentVersion: '1.0.0',
+     *   executionType: AgentTraceExecutionType.Runtime,
+     * });
+     * ```
+     */
+    async getLatencyTimeline(options) {
+        const response = await this.post(AGENT_TRACES_ENDPOINTS.GET_LATENCY_TIMELINE, this.buildTraceFilterBody(options));
+        return response.data.data;
+    }
+    /**
+     * Retrieves trace-level per-agent unit consumption totals.
+     *
+     * @param options - Optional window and filters
+     * @returns Promise resolving to an array of {@link AgentTraceGetUnitConsumptionResponse}
+     * @example
+     * ```typescript
+     * import { AgentTraces } from '@uipath/uipath-typescript/traces';
+     *
+     * const trace = new AgentTraces(sdk);
+     *
+     * // Get per-agent unit consumption
+     * const result = await trace.getUnitConsumption();
+     * result.forEach((row) => {
+     *   console.log(`${row.agentId}: ${row.agentUnitsConsumed} AGU, ${row.platformUnitsConsumed} PLTU`);
+     * });
+     * ```
+     * @example
+     * ```typescript
+     * import { AgentTraceExecutionType } from '@uipath/uipath-typescript/traces';
+     *
+     * // Get per-agent unit consumption for an agent version within a time window
+     * const filtered = await trace.getUnitConsumption({
+     *   startTime: new Date('2025-05-01T00:00:00Z'),
+     *   endTime: new Date('2025-06-01T00:00:00Z'),
+     *   agentId: '<agentId>',
+     *   agentVersion: '1.0.0',
+     *   executionType: AgentTraceExecutionType.Runtime,
+     * });
+     * ```
+     */
+    async getUnitConsumption(options) {
+        const response = await this.post(AGENT_TRACES_ENDPOINTS.GET_UNIT_CONSUMPTION, this.buildTraceFilterBody(options));
+        return response.data.data;
+    }
+    /**
+     * Retrieves every span belonging to a single trace.
+     *
+     * @param traceId - Identifier of the trace whose spans should be returned
+     * @returns Promise resolving to an array of {@link AgentSpanGetResponse}
+     * @example
+     * ```typescript
+     * import { AgentTraces } from '@uipath/uipath-typescript/traces';
+     *
+     * const trace = new AgentTraces(sdk);
+     *
+     * const spans = await trace.getSpansByTraceId('<traceId>');
+     * spans.forEach((span) => {
+     *   console.log(`${span.name} (${span.startTime} → ${span.endTime ?? 'in progress'})`);
+     * });
+     * ```
+     */
+    async getSpansByTraceId(traceId) {
+        if (!traceId)
+            throw new ValidationError({ message: 'traceId is required for getSpansByTraceId' });
+        const response = await this.get(AGENT_TRACES_ENDPOINTS.GET_SPANS_BY_TRACE_ID(traceId));
+        return (response.data ?? []).map(transformSpan);
+    }
+    /**
+     * 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}
+     * @example
+     * ```typescript
+     * import { AgentTraces } from '@uipath/uipath-typescript/traces';
+     *
+     * const trace = new AgentTraces(sdk);
+     *
+     * // Get spans by referenceId
+     * const result = await trace.getSpansByReference('<referenceId>');
+     * result.items.forEach((span) => console.log(span.name));
+     * ```
+     * @example
+     * ```typescript
+     * import { AgentTraceExecutionType } from '@uipath/uipath-typescript/traces';
+     *
+     * // Get spans by referenceId within a trace and time window
+     * const page = await trace.getSpansByReference('<referenceId>', {
+     *   traceId: '<traceId>',
+     *   executionType: AgentTraceExecutionType.Runtime,
+     *   startTime: new Date('2025-05-01T00:00:00Z'),
+     *   endTime: new Date('2025-06-01T00:00:00Z'),
+     *   pageSize: 25,
+     * });
+     *
+     * if (page.hasNextPage && page.nextCursor) {
+     *   const next = await trace.getSpansByReference('<referenceId>', { cursor: page.nextCursor });
+     * }
+     * ```
+     */
+    async getSpansByReference(referenceId, options) {
+        if (!referenceId)
+            throw new ValidationError({ message: 'referenceId is required for getSpansByReference' });
+        const { startTime, endTime, ...rest } = options ?? {};
+        const apiOptions = {
+            ...rest,
+            ...(startTime !== undefined ? { startTime: startTime.toISOString() } : {}),
+            ...(endTime !== undefined ? { endTime: endTime.toISOString() } : {}),
+        };
+        return PaginationHelpers.getAll({
+            serviceAccess: this.createPaginationServiceAccess(),
+            getEndpoint: () => AGENT_TRACES_ENDPOINTS.GET_SPANS_BY_REFERENCE(referenceId),
+            method: HTTP_METHODS.GET,
+            transformFn: transformSpan,
+            excludeFromPrefix: Object.keys(apiOptions),
+            pagination: {
+                paginationType: PaginationType.OFFSET,
+                itemsField: TRACEVIEW_SPANS_PAGINATION.ITEMS_FIELD,
+                totalCountField: TRACEVIEW_SPANS_PAGINATION.TOTAL_COUNT_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);
+    }
+    buildTraceFilterBody(options) {
+        const body = {};
+        if (options?.startTime !== undefined)
+            body.startTime = options.startTime.toISOString();
+        if (options?.endTime !== undefined)
+            body.endTime = options.endTime.toISOString();
+        if (options?.folderKeys !== undefined)
+            body.folderKeys = options.folderKeys;
+        if (options?.agentId !== undefined)
+            body.agentId = options.agentId;
+        if (options?.agentVersion !== undefined)
+            body.agentVersion = options.agentVersion;
+        if (options?.executionType !== undefined)
+            body.executionType = options.executionType;
+        return body;
+    }
+}
+__decorate([
+    track('AgentTraces.GetErrorsTimeline')
+], AgentTracesService.prototype, "getErrorsTimeline", null);
+__decorate([
+    track('AgentTraces.GetLatencyTimeline')
+], AgentTracesService.prototype, "getLatencyTimeline", null);
+__decorate([
+    track('AgentTraces.GetUnitConsumption')
+], AgentTracesService.prototype, "getUnitConsumption", null);
+__decorate([
+    track('AgentTraces.GetSpansByTraceId')
+], AgentTracesService.prototype, "getSpansByTraceId", null);
+__decorate([
+    track('AgentTraces.GetSpansByReference')
+], AgentTracesService.prototype, "getSpansByReference", null);
+
+exports.AgentTraceExecutionType = exports.SpanExecutionType;
+exports.AgentTraces = AgentTracesService;
 exports.Traces = TracesService;