@uipath/uipath-typescript 1.4.0 → 1.4.2

package/dist/traces/index.d.ts

@@ -49,6 +49,24 @@ interface PaginatedResponse<T> {
     /** Whether this pagination type supports jumping to arbitrary pages */
     supportsPageJump: boolean;
 }
+/**
+ * Response for non-paginated calls that includes both data and total count
+ */
+interface NonPaginatedResponse<T> {
+    items: T[];
+    totalCount?: number;
+}
+/**
+ * Helper type for defining paginated method overloads
+ * Creates a union type of all ways pagination can be triggered
+ */
+type HasPaginationOptions<T> = (T & {
+    pageSize: number;
+}) | (T & {
+    cursor: PaginationCursor;
+}) | (T & {
+    jumpToPage: number;
+});
 
 /**
  * Pagination types supported by the SDK
@@ -562,5 +580,467 @@ declare class TracesService extends BaseService implements TracesServiceModel {
     getSpansByIds(traceId: string, spanIds: string[]): Promise<SpanGetResponse[]>;
 }
 
-export { SpanAttachmentDirection, SpanAttachmentProvider, SpanExecutionType, SpanPermissionStatus, SpanSource, SpanStatus, SpanVerbosityLevel, TracesService as Traces };
-export type { SpanAttachment, SpanContext, SpanGetResponse, SpanReferenceHierarchyEntry, TracesGetByIdOptions, TracesServiceModel };
+/**
+ * Filter fields shared by the trace-level agent endpoints
+ */
+interface AgentTraceFilterOptions {
+    /** Inclusive lower bound for the query window. Omit to use the server default (1 year ago). */
+    startTime?: Date;
+    /** Exclusive upper bound for the query window. Omit to use the server default (now). */
+    endTime?: Date;
+    /** Folder keys to scope the query. Intersected with the user's accessible folders. */
+    folderKeys?: string[];
+    /** Filter to a single agent by ID. */
+    agentId?: string;
+    /** Filter to a specific agent version. */
+    agentVersion?: string;
+    /** Filter to a specific execution type. */
+    executionType?: SpanExecutionType;
+}
+/**
+ * One point on the trace-level errors timeline — error count for a single
+ * (error name, time bucket).
+ */
+interface AgentTraceGetErrorsTimelineResponse {
+    /** Error name / category for this time-slice. */
+    name: string;
+    /** Count of errors in this time bucket for this name. */
+    value: number;
+    /** Bucket timestamp. */
+    date: string;
+}
+/**
+ * Options for the trace-level errors timeline.
+ */
+interface AgentTraceGetErrorsTimelineOptions extends AgentTraceFilterOptions {
+}
+/**
+ * One point on the trace-level latency timeline — a latency value for a single
+ * (series, time bucket).
+ */
+interface AgentTraceGetLatencyTimelineResponse {
+    /** Series/grouping name for this latency point. */
+    name: string;
+    /** Latency value in decimal seconds for this series and time bucket. */
+    value: number;
+    /** Bucket timestamp. */
+    date: string;
+}
+/**
+ * Options for the trace-level latency timeline.
+ */
+interface AgentTraceGetLatencyTimelineOptions extends AgentTraceFilterOptions {
+}
+/**
+ * Per-agent unit consumption totals over the requested window (trace-level) —
+ * a flat per-(agent, version, folder) breakdown of AGU and PLTU consumed.
+ */
+interface AgentTraceGetUnitConsumptionResponse {
+    /** Agent ID these totals belong to. */
+    agentId: string;
+    /** Folder key (GUID) the consumption was recorded in. */
+    folderKey: string;
+    /** Agent version these totals belong to. */
+    agentVersion: string;
+    /** Agent units consumed over the window. */
+    agentUnitsConsumed: number;
+    /** Platform units consumed over the window. */
+    platformUnitsConsumed: number;
+}
+/**
+ * Options for the trace-level per-agent unit consumption.
+ */
+interface AgentTraceGetUnitConsumptionOptions extends AgentTraceFilterOptions {
+}
+/**
+ * A single span record from the trace store.
+ */
+interface AgentSpanGetResponse {
+    /** Span ID. */
+    id: string;
+    /** ID of the trace this span belongs to. */
+    traceId: string;
+    /** Parent span ID. `null` for a root span. */
+    parentId: string | null;
+    /** Span name. */
+    name: string;
+    /** Span start time. */
+    startTime: string;
+    /** Span end time. `null` while the span is in progress. */
+    endTime: string | null;
+    /** Raw span attributes as a JSON string. */
+    attributes: string;
+    /** Span status. */
+    status: string;
+    /** Organization ID (GUID). */
+    organizationId: string;
+    /** Tenant ID (GUID). May be `null`. */
+    tenantId: string | null;
+    /** Span retention expiry time. May be `null`. */
+    expiredTime: string | null;
+    /** Folder key (GUID) the span was recorded in. May be `null`. */
+    folderKey: string | null;
+    /** Span source. May be `null`. */
+    source: string | null;
+    /** Span type. May be `null`. */
+    spanType: string | null;
+    /** Process key (GUID). May be `null`. */
+    processKey: string | null;
+    /** Job key (GUID). May be `null`. */
+    jobKey: string | null;
+    /** Reference ID (GUID). May be `null`. */
+    referenceId: string | null;
+    /** Verbosity level. May be `null`. */
+    verbosityLevel: string | null;
+    /** Record last-updated time. */
+    updatedAt: string;
+    /** Whether the span payload is stored as a large payload. */
+    isLargePayload: boolean;
+    /** Payload compression type. May be `null`. */
+    compressionType: string | null;
+    /** Agent version that produced the span. May be `null`. */
+    agentVersion: string | null;
+    /** Raw span context as a JSON string. May be `null`. */
+    context: string | null;
+}
+/**
+ * Options for the spans-by-reference query.
+ *
+ * Composes the optional hierarchy/time filters with pagination options.
+ */
+type AgentTraceGetSpansByReferenceOptions = PaginationOptions & {
+    /** Optional trace scope — narrows the scan to a single trace. */
+    traceId?: string;
+    /** Restrict matches to hierarchy entries with this service type. */
+    serviceType?: string;
+    /** Restrict matches to hierarchy entries with this version. */
+    version?: string;
+    /** Inclusive lower bound on span start time. */
+    startTime?: Date;
+    /** Exclusive upper bound on span end time. */
+    endTime?: Date;
+    /** Execution type filter */
+    executionType?: SpanExecutionType;
+};
+
+/**
+ * Service for retrieving UiPath Agent trace metrics.
+ */
+interface AgentTracesServiceModel {
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    getErrorsTimeline(options?: AgentTraceGetErrorsTimelineOptions): Promise<AgentTraceGetErrorsTimelineResponse[]>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    getLatencyTimeline(options?: AgentTraceGetLatencyTimelineOptions): Promise<AgentTraceGetLatencyTimelineResponse[]>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    getUnitConsumption(options?: AgentTraceGetUnitConsumptionOptions): Promise<AgentTraceGetUnitConsumptionResponse[]>;
+    /**
+     * 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'})`);
+     * });
+     * ```
+     */
+    getSpansByTraceId(traceId: string): Promise<AgentSpanGetResponse[]>;
+    /**
+     * 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 });
+     * }
+     * ```
+     */
+    getSpansByReference<T extends AgentTraceGetSpansByReferenceOptions = AgentTraceGetSpansByReferenceOptions>(referenceId: string, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<AgentSpanGetResponse> : NonPaginatedResponse<AgentSpanGetResponse>>;
+}
+
+/**
+ * Service for retrieving UiPath Agent trace metrics.
+ */
+declare class AgentTracesService extends BaseService implements AgentTracesServiceModel {
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    getErrorsTimeline(options?: AgentTraceGetErrorsTimelineOptions): Promise<AgentTraceGetErrorsTimelineResponse[]>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    getLatencyTimeline(options?: AgentTraceGetLatencyTimelineOptions): Promise<AgentTraceGetLatencyTimelineResponse[]>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    getUnitConsumption(options?: AgentTraceGetUnitConsumptionOptions): Promise<AgentTraceGetUnitConsumptionResponse[]>;
+    /**
+     * 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'})`);
+     * });
+     * ```
+     */
+    getSpansByTraceId(traceId: string): Promise<AgentSpanGetResponse[]>;
+    /**
+     * 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 });
+     * }
+     * ```
+     */
+    getSpansByReference<T extends AgentTraceGetSpansByReferenceOptions = AgentTraceGetSpansByReferenceOptions>(referenceId: string, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<AgentSpanGetResponse> : NonPaginatedResponse<AgentSpanGetResponse>>;
+    private buildTraceFilterBody;
+}
+
+export { SpanExecutionType as AgentTraceExecutionType, AgentTracesService as AgentTraces, SpanAttachmentDirection, SpanAttachmentProvider, SpanExecutionType, SpanPermissionStatus, SpanSource, SpanStatus, SpanVerbosityLevel, TracesService as Traces };
+export type { AgentSpanGetResponse, AgentTraceFilterOptions, AgentTraceGetErrorsTimelineOptions, AgentTraceGetErrorsTimelineResponse, AgentTraceGetLatencyTimelineOptions, AgentTraceGetLatencyTimelineResponse, AgentTraceGetSpansByReferenceOptions, AgentTraceGetUnitConsumptionOptions, AgentTraceGetUnitConsumptionResponse, AgentTracesServiceModel, SpanAttachment, SpanContext, SpanGetResponse, SpanReferenceHierarchyEntry, TracesGetByIdOptions, TracesServiceModel };