@uipath/uipath-typescript 1.3.10 → 1.4.0

package/dist/traces/index.d.ts

@@ -0,0 +1,566 @@
+import { IUiPath } from '../core/index';
+
+/**
+ * Simplified universal pagination cursor
+ * Used to fetch next/previous pages
+ */
+interface PaginationCursor {
+    /** Opaque string containing all information needed to fetch next page */
+    value: string;
+}
+/**
+ * Discriminated union for pagination methods - ensures cursor and jumpToPage are mutually exclusive
+ */
+type PaginationMethodUnion = {
+    cursor?: PaginationCursor;
+    jumpToPage?: never;
+} | {
+    cursor?: never;
+    jumpToPage?: number;
+} | {
+    cursor?: never;
+    jumpToPage?: never;
+};
+/**
+ * Pagination options. Users cannot specify both cursor and jumpToPage.
+ */
+type PaginationOptions = {
+    /** Size of the page to fetch (items per page) */
+    pageSize?: number;
+} & PaginationMethodUnion;
+/**
+ * Paginated response containing items and navigation information
+ */
+interface PaginatedResponse<T> {
+    /** The items in the current page */
+    items: T[];
+    /** Total count of items across all pages (if available) */
+    totalCount?: number;
+    /** Whether more pages are available */
+    hasNextPage: boolean;
+    /** Cursor to fetch the next page (if available) */
+    nextCursor?: PaginationCursor;
+    /** Cursor to fetch the previous page (if available) */
+    previousCursor?: PaginationCursor;
+    /** Current page number (1-based, if available) */
+    currentPage?: number;
+    /** Total number of pages (if available) */
+    totalPages?: number;
+    /** Whether this pagination type supports jumping to arbitrary pages */
+    supportsPageJump: boolean;
+}
+
+/**
+ * Pagination types supported by the SDK
+ */
+declare enum PaginationType {
+    OFFSET = "offset",
+    TOKEN = "token"
+}
+/**
+ * Interface for service access methods needed by pagination helpers
+ */
+interface PaginationServiceAccess {
+    get<T>(path: string, options?: any): Promise<{
+        data: T;
+    }>;
+    post<T>(path: string, body?: any, options?: any): Promise<{
+        data: T;
+    }>;
+    requestWithPagination<T>(method: string, path: string, paginationOptions: PaginationOptions, options: RequestWithPaginationOptions): Promise<PaginatedResponse<T>>;
+}
+/**
+ * Field names for extracting data from paginated responses.
+ */
+interface PaginationFieldNames {
+    itemsField?: string;
+    totalCountField?: string;
+    continuationTokenField?: string;
+}
+/**
+ * Options for the requestWithPagination method in BaseService.
+ */
+interface RequestWithPaginationOptions extends RequestSpec {
+    pagination: PaginationFieldNames & {
+        paginationType: PaginationType;
+        paginationParams?: {
+            pageSizeParam?: string;
+            offsetParam?: string;
+            tokenParam?: string;
+            countParam?: string;
+            convertToSkip?: boolean;
+            zeroBased?: boolean;
+        };
+    };
+}
+
+/**
+ * HTTP methods supported by the API client
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/**
+ * Supported response types for API requests
+ */
+type ResponseType = 'json' | 'text' | 'blob' | 'arraybuffer' | 'stream';
+/**
+ * Query parameters type with support for arrays and nested objects
+ */
+type QueryParams = Record<string, string | number | boolean | Array<string | number | boolean> | null | undefined>;
+/**
+ * Standard HTTP headers type
+ */
+type Headers = Record<string, string>;
+/**
+ * Options for request retries
+ */
+interface RetryOptions {
+    /** Maximum number of retry attempts */
+    maxRetries?: number;
+    /** Base delay between retries in milliseconds */
+    retryDelay?: number;
+    /** Whether to use exponential backoff */
+    useExponentialBackoff?: boolean;
+    /** Status codes that should trigger a retry */
+    retryableStatusCodes?: number[];
+}
+/**
+ * Options for request timeouts
+ */
+interface TimeoutOptions {
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Whether to abort the request on timeout */
+    abortOnTimeout?: boolean;
+}
+/**
+ * Options for request body transformation
+ */
+interface BodyOptions {
+    /** Whether to stringify the body */
+    stringify?: boolean;
+    /** Content type override */
+    contentType?: string;
+}
+/**
+ * Pagination metadata for API requests
+ */
+interface PaginationMetadata {
+    /** Type of pagination used by the API endpoint */
+    paginationType: PaginationType;
+    /** Response field containing items array (defaults to 'value') */
+    itemsField?: string;
+    /** Response field containing total count (defaults to '@odata.count') */
+    totalCountField?: string;
+    /** Response field containing continuation token (defaults to 'continuationToken') */
+    continuationTokenField?: string;
+}
+/**
+ * Base interface for all API requests
+ */
+interface RequestSpec {
+    /** HTTP method for the request */
+    method?: HttpMethod;
+    /** URL endpoint for the request */
+    url?: string;
+    /** Query parameters to be appended to the URL */
+    params?: QueryParams;
+    /** HTTP headers to include with the request */
+    headers?: Headers;
+    /** Raw body content (takes precedence over data) */
+    body?: unknown;
+    /** Expected response type */
+    responseType?: ResponseType;
+    /** Request timeout options */
+    timeoutOptions?: TimeoutOptions;
+    /** Retry behavior options */
+    retryOptions?: RetryOptions;
+    /** Body transformation options */
+    bodyOptions?: BodyOptions;
+    /** AbortSignal for cancelling the request */
+    signal?: AbortSignal;
+    /** Pagination metadata for the request */
+    pagination?: PaginationMetadata;
+}
+
+interface ApiResponse<T> {
+    data: T;
+}
+/**
+ * Base class for all UiPath SDK services.
+ *
+ * Provides common functionality for authentication, configuration, and API communication.
+ * All service classes extend this base to inherit dependency injection and HTTP client access.
+ *
+ * This class implements the dependency injection pattern where services receive a configured
+ * UiPath instance. The ApiClient is created internally and handles all HTTP operations
+ * including authentication token management.
+ *
+ * @remarks
+ * Service classes should extend this base and call `super(uiPath)` in their constructor.
+ * Protected HTTP methods (get, post, put, patch, delete) are available to all subclasses.
+ *
+ */
+declare class BaseService {
+    #private;
+    /**
+     * SDK configuration (read-only). Available to subclasses so they can
+     * fall back to init-time defaults like `folderKey`.
+     */
+    protected readonly config: {
+        folderKey?: string;
+    };
+    /**
+     * Creates a base service instance with dependency injection.
+     *
+     * Extracts configuration, execution context, and token manager from the UiPath instance
+     * to initialize an authenticated API client. The ApiClient handles all HTTP operations
+     * and token management internally.
+     *
+     * @param instance - UiPath SDK instance providing authentication and configuration.
+     *                    Services receive this via dependency injection in the modular pattern.
+     * @param headers - Optional default headers to include in every request (e.g. `x-uipath-external-user-id` for
+     *                  CAS external-app auth)
+     *
+     * @example
+     * ```typescript
+     * // Services automatically call this via super()
+     * export class EntityService extends BaseService {
+     *   constructor(instance: IUiPath) {
+     *     super(instance); // Initializes the internal ApiClient
+     *   }
+     * }
+     *
+     * // Usage in modular pattern
+     * import { UiPath } from '@uipath/uipath-typescript/core';
+     * import { Entities } from '@uipath/uipath-typescript/entities';
+     *
+     * const sdk = new UiPath(config);
+     * await sdk.initialize();
+     * const entities = new Entities(sdk);
+     * ```
+     */
+    constructor(instance: IUiPath, headers?: Record<string, string>);
+    /**
+     * Gets a valid authentication token, refreshing if necessary.
+     * Use this when you need to manually add Authorization headers (e.g., direct uploads).
+     *
+     * @returns Promise resolving to a valid access token string
+     * @throws AuthenticationError if no token is available or refresh fails
+     */
+    protected getValidAuthToken(): Promise<string>;
+    /**
+     * Creates a service accessor for pagination helpers
+     * This allows pagination helpers to access protected methods without making them public
+     */
+    protected createPaginationServiceAccess(): PaginationServiceAccess;
+    protected request<T>(method: string, path: string, options?: RequestSpec): Promise<ApiResponse<T>>;
+    protected requestWithSpec<T>(spec: RequestSpec): Promise<ApiResponse<T>>;
+    protected get<T>(path: string, options?: RequestSpec): Promise<ApiResponse<T>>;
+    protected post<T>(path: string, data?: unknown, options?: RequestSpec): Promise<ApiResponse<T>>;
+    protected put<T>(path: string, data?: unknown, options?: RequestSpec): Promise<ApiResponse<T>>;
+    protected patch<T>(path: string, data?: unknown, options?: RequestSpec): Promise<ApiResponse<T>>;
+    protected delete<T>(path: string, options?: RequestSpec): Promise<ApiResponse<T>>;
+    /**
+     * Execute a request with cursor-based pagination
+     */
+    protected requestWithPagination<T>(method: string, path: string, paginationOptions: PaginationOptions, options: RequestWithPaginationOptions): Promise<PaginatedResponse<T>>;
+    /**
+     * Validates and prepares pagination parameters from options
+     */
+    private validateAndPreparePaginationParams;
+    /**
+     * Prepares request parameters for pagination based on pagination type
+     */
+    private preparePaginationRequestParams;
+    /**
+     * Creates a paginated response from API response
+     */
+    private createPaginatedResponseFromResponse;
+    /**
+     * Determines if there are more pages based on pagination type and metadata
+     */
+    private determineHasMorePages;
+}
+
+/** Status of a span: whether it completed successfully, with an error, or was not set. */
+declare enum SpanStatus {
+    Unset = "Unset",
+    Ok = "Ok",
+    Error = "Error",
+    /** Span is still in progress. */
+    Running = "Running",
+    /** Span data is hidden from the caller due to tenant/folder permission rules. */
+    Restricted = "Restricted",
+    /** Span was cancelled before completion. */
+    Cancelled = "Cancelled"
+}
+/** Platform source that produced the span. */
+declare enum SpanSource {
+    Testing = "Testing",
+    Agents = "Agents",
+    ProcessOrchestration = "ProcessOrchestration",
+    ApiWorkflows = "ApiWorkflows",
+    Robots = "Robots",
+    ConversationalAgentsService = "ConversationalAgentsService",
+    IntegrationServiceTrigger = "IntegrationServiceTrigger",
+    Playground = "Playground",
+    Governance = "Governance",
+    /** Intelligent Experience Platform — unstructured and complex document processing source. */
+    IXPUnstructuredAndComplexDocuments = "IXPUnstructuredAndComplexDocuments",
+    /** Agents authored in code (as opposed to visual/no-code designers). */
+    CodedAgents = "CodedAgents",
+    /** Intelligent Experience Platform — communications mining source. */
+    IXPCommunicationsMining = "IXPCommunicationsMining",
+    /** UiPath Context Grounding — span produced by the Enterprise Context Service for RAG/knowledge-base operations. */
+    EnterpriseContextService = "EnterpriseContextService",
+    /** Model Context Protocol — span produced by an MCP server integration. */
+    MCP = "MCP",
+    /** Agent-to-Agent — span produced by an A2A protocol call between agents. */
+    A2A = "A2A",
+    /** Serverless — span produced by a serverless function execution. */
+    Serverless = "Serverless"
+}
+/** Minimum severity level of events captured in the span. */
+declare enum SpanVerbosityLevel {
+    Verbose = "Verbose",
+    Trace = "Trace",
+    Information = "Information",
+    Warning = "Warning",
+    Error = "Error",
+    Critical = "Critical",
+    Off = "Off"
+}
+/** Whether the span was produced during a debug or production runtime. */
+declare enum SpanExecutionType {
+    Debug = "Debug",
+    Runtime = "Runtime"
+}
+/** Whether the caller has permission to read this span's data. */
+declare enum SpanPermissionStatus {
+    Allow = "Allow",
+    /** Some span fields are redacted due to permission constraints (e.g. attributes visible but payload hidden). */
+    PartialBlock = "PartialBlock",
+    Block = "Block"
+}
+/** Storage provider that created or manages the attachment. */
+declare enum SpanAttachmentProvider {
+    Orchestrator = "Orchestrator",
+    /** Span attachment stored by the observability platform. */
+    LLMOps = "LLMOps"
+}
+/** Whether the attachment is an input, output, or neither. */
+declare enum SpanAttachmentDirection {
+    None = "None",
+    In = "In",
+    Out = "Out"
+}
+/** One level in the reference hierarchy that produced this span. */
+interface SpanReferenceHierarchyEntry {
+    serviceType: string;
+    referenceId: string;
+    version: string | null;
+}
+/** Contextual lineage attached to the span (reference hierarchy). */
+interface SpanContext {
+    referenceHierarchy: SpanReferenceHierarchyEntry[];
+}
+/** File or payload attachment linked to the span. */
+interface SpanAttachment {
+    provider: SpanAttachmentProvider;
+    id: string;
+    fileName: string;
+    mimeType: string;
+    direction: SpanAttachmentDirection;
+}
+/** A single execution span returned by the Traces API. */
+interface SpanGetResponse {
+    /** Unique identifier of this span (GUID). */
+    id: string;
+    /** Trace this span belongs to (GUID). */
+    traceId: string;
+    /** Parent span ID, or null for root spans. */
+    parentId: string | null;
+    /** Human-readable name of the operation, or null if the span has no name. */
+    name: string | null;
+    /** ISO-8601 UTC timestamp when the span started. */
+    startTime: string;
+    /** ISO-8601 UTC timestamp when the span ended, or null if still running. */
+    endTime: string | null;
+    /**
+     * Span attributes (user-defined schema — do not transform keys).
+     * Values depend on the span type and the agent that produced them.
+     */
+    attributes: Record<string, unknown>;
+    /** Completion status of the span. */
+    status: SpanStatus;
+    /** Platform source that produced the span. */
+    source: SpanSource | null;
+    /** Span type tag (e.g. `"agentRun"`, `"llmCall"`). */
+    spanType: string | null;
+    /** Minimum verbosity level captured in this span. */
+    verbosityLevel: SpanVerbosityLevel | null;
+    /** Whether this span was from a debug or runtime execution. */
+    executionType: SpanExecutionType | null;
+    /** Folder key (GUID) scoping this span. */
+    folderKey: string | null;
+    /** Identifier of the entity (agent, process, etc.) that produced the span. */
+    referenceId: string | null;
+    /** Version of the entity that produced the span. */
+    referenceVersion: string | null;
+    /** Version of the agent runtime. */
+    agentVersion: string | null;
+    /** Organization (account) GUID. */
+    organizationId: string;
+    /** Tenant GUID. */
+    tenantId: string | null;
+    /** Key of the process associated with this span. */
+    processKey: string | null;
+    /** Key of the job associated with this span. */
+    jobKey: string | null;
+    /** ISO-8601 UTC timestamp of last update. */
+    updatedAt: string;
+    /** Expiry timestamp, or null if the span does not expire. */
+    expiredTime: string | null;
+    /** Reference hierarchy context for this span. */
+    context: SpanContext | null;
+    /** File or payload attachments linked to this span. */
+    attachments: SpanAttachment[] | null;
+    /** Whether the caller can read this span's data. */
+    permissionStatus: SpanPermissionStatus | null;
+}
+/** Options for retrieving all spans belonging to a trace. */
+interface TracesGetByIdOptions {
+    /** Maximum number of spans to return. */
+    pageSize?: number;
+    /** Filter spans to those produced by a specific agent ID. */
+    agentId?: string;
+    /** When true, include expired spans that are outside the default retention window. */
+    includeExpiredSpans?: boolean;
+}
+
+/**
+ * Service for querying UiPath execution traces (spans).
+ *
+ * Traces are OpenTelemetry-compatible execution records generated by agents, robots,
+ * Maestro processes, conversational agents, and other UiPath execution sources.
+ * The `source` field on each {@link SpanGetResponse} identifies the originating platform.
+ *
+ * @example
+ * ```typescript
+ * import { UiPath } from '@uipath/uipath-typescript/core';
+ * import { Traces } from '@uipath/uipath-typescript/traces';
+ *
+ * const sdk = new UiPath(config);
+ * await sdk.initialize();
+ *
+ * const traces = new Traces(sdk);
+ * const spans = await traces.getById('<traceId>');
+ * ```
+ */
+interface TracesServiceModel {
+    /**
+     * Gets all spans for a specific trace ID.
+     *
+     * Returns up to `pageSize` spans (default 1000) in a single fetch.
+     * Accepts both GUID format and OTEL 32-char hex format — the API normalizes both.
+     *
+     * @param traceId - Trace identifier
+     * @param options - Optional filters {@link TracesGetByIdOptions}
+     * @returns Promise resolving to an array of {@link SpanGetResponse}, each containing span identity, timing, status, source platform, attributes, verbosity, execution type, lineage context, and any file attachments.
+     * @example
+     * ```typescript
+     * import { Traces } from '@uipath/uipath-typescript/traces';
+     *
+     * const traces = new Traces(sdk);
+     * const spans = await traces.getById('<traceId>');
+     * console.log(spans.length, spans[0].spanType, spans[0].status);
+     * ```
+     * @example
+     * ```typescript
+     * // Filter to a specific agent's spans
+     * const agentSpans = await traces.getById('<traceId>', {
+     *   agentId: '<agentId>',
+     *   pageSize: 500,
+     * });
+     * ```
+     */
+    getById(traceId: string, options?: TracesGetByIdOptions): Promise<SpanGetResponse[]>;
+    /**
+     * Gets specific spans by trace ID and span IDs.
+     *
+     * Accepts OTEL 16-char hex or GUID format for span IDs.
+     *
+     * @param traceId - Trace identifier
+     * @param spanIds - List of span IDs to retrieve
+     * @returns Promise resolving to an array of matching {@link SpanGetResponse}, each containing span identity, timing, status, source platform, attributes, verbosity, execution type, lineage context, and any file attachments.
+     * @example
+     * ```typescript
+     * import { Traces } from '@uipath/uipath-typescript/traces';
+     *
+     * const traces = new Traces(sdk);
+     *
+     * // First retrieve all spans to find the IDs you want
+     * const allSpans = await traces.getById('<traceId>');
+     * const spanIds = allSpans.slice(0, 3).map(s => s.id);
+     *
+     * const subset = await traces.getSpansByIds('<traceId>', spanIds);
+     * ```
+     */
+    getSpansByIds(traceId: string, spanIds: string[]): Promise<SpanGetResponse[]>;
+}
+
+declare class TracesService extends BaseService implements TracesServiceModel {
+    private transformOtelSpan;
+    /**
+     * Gets all spans for a specific trace ID.
+     *
+     * Returns up to `pageSize` spans (default 1000) in a single fetch.
+     * Accepts both GUID format and OTEL 32-char hex format — the API normalizes both.
+     *
+     * @param traceId - Trace identifier
+     * @param options - Optional filters {@link TracesGetByIdOptions}
+     * @returns Promise resolving to an array of {@link SpanGetResponse}, each containing span identity, timing, status, source platform, attributes, verbosity, execution type, lineage context, and any file attachments.
+     * @example
+     * ```typescript
+     * import { Traces } from '@uipath/uipath-typescript/traces';
+     *
+     * const traces = new Traces(sdk);
+     * const spans = await traces.getById('<traceId>');
+     * console.log(spans.length, spans[0].spanType, spans[0].status);
+     * ```
+     * @example
+     * ```typescript
+     * // Filter to a specific agent's spans
+     * const agentSpans = await traces.getById('<traceId>', {
+     *   agentId: '<agentId>',
+     *   pageSize: 500,
+     * });
+     * ```
+     */
+    getById(traceId: string, options?: TracesGetByIdOptions): Promise<SpanGetResponse[]>;
+    /**
+     * Gets specific spans by trace ID and span IDs.
+     *
+     * Accepts OTEL 16-char hex or GUID format for span IDs.
+     *
+     * @param traceId - Trace identifier
+     * @param spanIds - List of span IDs to retrieve
+     * @returns Promise resolving to an array of matching {@link SpanGetResponse}
+     * @example
+     * ```typescript
+     * import { Traces } from '@uipath/uipath-typescript/traces';
+     *
+     * const traces = new Traces(sdk);
+     *
+     * // First retrieve all spans to find the IDs you want
+     * const allSpans = await traces.getById('<traceId>');
+     * const spanIds = allSpans.slice(0, 3).map(s => s.id);
+     *
+     * const subset = await traces.getSpansByIds('<traceId>', spanIds);
+     * ```
+     */
+    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 };