@uipath/uipath-typescript 1.3.10 → 1.4.0

package/dist/governance/index.d.ts

@@ -0,0 +1,598 @@
+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;
+}
+/**
+ * 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
+ */
+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;
+}
+
+/**
+ * Governance Service Types
+ *
+ * Public types exposed via `@uipath/uipath-typescript/governance`.
+ */
+
+declare enum PolicyEvaluationResult {
+    /** Active policy permitted the action. */
+    Allow = "Allow",
+    /** Active policy blocked the action. */
+    Deny = "Deny",
+    /** Simulated (NoOp) policy would have permitted the action. */
+    SimulatedAllow = "SimulatedAllow",
+    /** Simulated (NoOp) policy would have blocked the action. */
+    SimulatedDeny = "SimulatedDeny"
+}
+/**
+ * Each trace row represents one policy's verdict within a governance
+ * enforcement event. One enforcement event can produce multiple trace rows
+ * when multiple policies contributed to the final verdict.
+ */
+interface GovernancePolicyTrace {
+    /** Tenant the trace was recorded in. Present even when `fullOrganization` is `true`. */
+    tenantId?: string;
+    /** The start time of governance enforcement event. */
+    startTime: string;
+    /** Final enforcement verdict for the parent governance event. */
+    finalEnforcement?: string;
+    /** ID of the policy this trace row evaluates. */
+    policyId?: string;
+    /** This individual policy's enforcement contribution to the parent verdict. */
+    policyEnforcement?: string;
+    /** The outcome of one policy evaluation — whether it allowed or denied the action, and whether that decision was actively enforced or just simulated (NoOp). */
+    policyEvaluationResult?: string;
+    /** Display name of the policy. */
+    policyName?: string;
+    /** Enforcement mode of the policy at the time of evaluation. */
+    policyStatus?: string;
+    /** Opaque details payload describing the evaluation result. */
+    policyEvaluationDetails?: string;
+    /** Process or executable that triggered the evaluation. */
+    actorProcessId?: string;
+    /** Type of the actor process (e.g. coded agent, RPA process). */
+    actorProcessType?: string;
+    /** Identity (user/principal) that triggered the evaluation. */
+    actorIdentityId?: string;
+    /** Resource being acted on. */
+    resourceId?: string;
+    /** Type of the resource being acted on. */
+    resourceType?: string;
+    /** Orchestrator folder key associated with the evaluation, if any. */
+    folderKey?: string;
+    /** Distributed-tracing ID covering the governance enforcement event. */
+    traceId?: string;
+    /** Process key associated with the evaluation, if any. */
+    processKey?: string;
+    /** Job key associated with the evaluation, if any. */
+    jobKey?: string;
+}
+/**
+ * Common filter options shared across Governance APIs.
+ *
+ * Holds filters that are not specific to any single governance resource, so
+ * other governance endpoints can reuse them.
+ */
+interface GovernanceFilterOptions {
+    /**
+     * Inclusive upper bound on trace start time. When omitted, the upper bound
+     * is open.
+     */
+    endTime?: Date;
+    /**
+     * Whether to query the whole organization instead of just the current tenant.
+     *
+     * Defaults to tenant-scoped:
+     * - omitted → tenant-scoped (default)
+     * - `false` → tenant-scoped (explicit, same result)
+     * - `true` → org-wide across all tenants; requires an organization admin,
+     *   otherwise the request returns 403
+     *
+     * @default false
+     */
+    fullOrganization?: boolean;
+}
+/**
+ * Filter and pagination options for fetching policy traces.
+ *
+ * All filters combine with AND semantics. Array filters match any value in
+ * the array (OR within a single filter).
+ */
+type GovernancePolicyTraceGetAllOptions = PaginationOptions & GovernanceFilterOptions & {
+    /** Filter by one or more policy evaluation results. */
+    evaluationResult?: PolicyEvaluationResult[];
+    /** Filter by one or more policy IDs. */
+    policyId?: string[];
+    /** Filter by one or more actor process IDs. */
+    actorProcessId?: string[];
+    /** Filter by one or more actor process types (e.g. coded agent, RPA process). */
+    actorProcessType?: string[];
+    /** Filter by one or more actor identity IDs. */
+    actorIdentityId?: string[];
+    /** Filter by one or more resource IDs. */
+    resourceId?: string[];
+    /** Filter by one or more resource types. */
+    resourceType?: string[];
+    /** Filter by one or more distributed-trace IDs. */
+    traceId?: string[];
+};
+/**
+ * Aggregate governance enforcement counts returned by
+ * {@link GovernanceServiceModel.getOperationSummary}, covering the requested
+ * time range.
+ */
+interface GovernanceOperationSummary {
+    /** Total number of governance enforcement evaluations in range. */
+    totalEvaluations: number;
+    /** Number of evaluations that resolved to `Allow`. */
+    allowedCount: number;
+    /** Number of evaluations that resolved to `Deny`. */
+    deniedCount: number;
+    /** Number of evaluations that resolved to `NoOp` (simulated). */
+    noOpCount: number;
+}
+
+/**
+ * Service for inspecting governance policy enforcement on the UiPath platform.
+ *
+ * See [Define governance policies](https://docs.uipath.com/automation-ops/automation-cloud/latest/user-guide/define-governance-policies)
+ * for how governance policies are configured in Automation Ops.
+ *
+ * All methods require the caller to be an organization administrator.
+ *
+ * ### Usage
+ *
+ * Prerequisites: Initialize the SDK first - see [Getting Started](/uipath-typescript/getting-started/#import-initialize)
+ *
+ * ```typescript
+ * import { Governance } from '@uipath/uipath-typescript/governance';
+ *
+ * const governance = new Governance(sdk);
+ * const traces = await governance.getPolicyTraces(new Date('2024-01-01'));
+ * ```
+ */
+interface GovernanceServiceModel {
+    /**
+     * Gets per-policy enforcement decisions across the requested time range.
+     *
+     * Each result row represents one policy's verdict within a single governance enforcement event.
+     * A single user action can produce multiple rows when multiple policies were consulted.
+     * Results are ordered by event start time, descending.
+     *
+     * @param startTime - Inclusive lower bound on the trace start time.
+     * @param options - Optional filters and pagination options
+     * @returns Promise resolving to {@link NonPaginatedResponse} of {@link GovernancePolicyTrace}
+     *          without pagination options, or {@link PaginatedResponse} of
+     *          {@link GovernancePolicyTrace} when pagination options are used.
+     *
+     * @example
+     * ```typescript
+     * import { Governance, PolicyEvaluationResult } from '@uipath/uipath-typescript/governance';
+     *
+     * const governance = new Governance(sdk);
+     *
+     * // Get all policy traces from the specified start time
+     * const recent = await governance.getPolicyTraces(new Date('2024-01-01'));
+     * console.log(recent.items.length);
+     *
+     * // Get all denied decisions across the whole organization
+     * const page1 = await governance.getPolicyTraces(
+     *   new Date('2024-01-01'),
+     *   {
+     *     endTime: new Date(),
+     *     evaluationResult: [PolicyEvaluationResult.Deny, PolicyEvaluationResult.SimulatedDeny],
+     *     fullOrganization: true,
+     *     pageSize: 25,
+     *   },
+     * );
+     *
+     * if (page1.hasNextPage) {
+     *   const page2 = await governance.getPolicyTraces(
+     *     new Date('2024-01-01'),
+     *     { cursor: page1.nextCursor },
+     *   );
+     * }
+     * ```
+     */
+    getPolicyTraces<T extends GovernancePolicyTraceGetAllOptions = GovernancePolicyTraceGetAllOptions>(startTime: Date, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<GovernancePolicyTrace> : NonPaginatedResponse<GovernancePolicyTrace>>;
+    /**
+     * Gets aggregate governance enforcement counts across the requested time range.
+     *
+     * Returns the total number of evaluations along with how many resolved to
+     * `Allow`, `Deny`, or `NoOp`.
+     *
+     * @param startTime - Inclusive lower bound on the evaluation time.
+     * @param options - Optional `endTime` upper bound and `fullOrganization` flag
+     * @returns Promise resolving to {@link GovernanceOperationSummary}
+     *
+     * @example
+     * ```typescript
+     * import { Governance } from '@uipath/uipath-typescript/governance';
+     *
+     * const governance = new Governance(sdk);
+     *
+     * // Get operation summary from the specified start time to right now
+     * const summary = await governance.getOperationSummary(new Date('2024-01-01'));
+     * console.log(summary.totalEvaluations, summary.allowedCount, summary.deniedCount, summary.noOpCount);
+     *
+     * // Bounded range across the whole organization
+     * const ranged = await governance.getOperationSummary(
+     *   new Date('2024-01-01'),
+     *   { endTime: new Date(), fullOrganization: true },
+     * );
+     * ```
+     */
+    getOperationSummary(startTime: Date, options?: GovernanceFilterOptions): Promise<GovernanceOperationSummary>;
+}
+
+/**
+ * Service for inspecting governance policy enforcement on the UiPath platform.
+ */
+declare class GovernanceService extends BaseService implements GovernanceServiceModel {
+    /**
+     * Gets per-policy enforcement decisions across the requested time range.
+     *
+     * Each result row represents one policy's verdict within a single governance enforcement event.
+     * A single user action can produce multiple rows when multiple policies were consulted.
+     * Results are ordered by event start time, descending.
+     *
+     * @param startTime - Inclusive lower bound on the trace start time.
+     * @param options - Optional filters and pagination options
+     * @returns Promise resolving to {@link NonPaginatedResponse} of {@link GovernancePolicyTrace}
+     *          without pagination options, or {@link PaginatedResponse} of
+     *          {@link GovernancePolicyTrace} when pagination options are used.
+     *
+     * @example
+     * ```typescript
+     * import { Governance, PolicyEvaluationResult } from '@uipath/uipath-typescript/governance';
+     *
+     * const governance = new Governance(sdk);
+     *
+     * // Get all policy traces from the specified start time
+     * const recent = await governance.getPolicyTraces(new Date('2024-01-01'));
+     * console.log(recent.items.length);
+     *
+     * // Get all denied decisions across the whole organization
+     * const page1 = await governance.getPolicyTraces(
+     *   new Date('2024-01-01'),
+     *   {
+     *     endTime: new Date(),
+     *     evaluationResult: [PolicyEvaluationResult.Deny, PolicyEvaluationResult.SimulatedDeny],
+     *     fullOrganization: true,
+     *     pageSize: 25,
+     *   },
+     * );
+     *
+     * if (page1.hasNextPage) {
+     *   const page2 = await governance.getPolicyTraces(
+     *     new Date('2024-01-01'),
+     *     { cursor: page1.nextCursor },
+     *   );
+     * }
+     * ```
+     */
+    getPolicyTraces<T extends GovernancePolicyTraceGetAllOptions = GovernancePolicyTraceGetAllOptions>(startTime: Date, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<GovernancePolicyTrace> : NonPaginatedResponse<GovernancePolicyTrace>>;
+    /**
+     * Gets aggregate governance enforcement counts across the requested time range.
+     *
+     * Returns the total number of evaluations along with how many resolved to
+     * `Allow`, `Deny`, or `NoOp`.
+     *
+     * @param startTime - Inclusive lower bound on the evaluation time.
+     * @param options - Optional `endTime` upper bound and `fullOrganization` flag
+     * @returns Promise resolving to {@link GovernanceOperationSummary}
+     *
+     * @example
+     * ```typescript
+     * import { Governance } from '@uipath/uipath-typescript/governance';
+     *
+     * const governance = new Governance(sdk);
+     *
+     * // Get operation summary from the specified start time to right now
+     * const summary = await governance.getOperationSummary(new Date('2024-01-01'));
+     * console.log(summary.totalEvaluations, summary.allowedCount, summary.deniedCount, summary.noOpCount);
+     *
+     * // Bounded range across the whole organization
+     * const ranged = await governance.getOperationSummary(
+     *   new Date('2024-01-01'),
+     *   { endTime: new Date(), fullOrganization: true },
+     * );
+     * ```
+     */
+    getOperationSummary(startTime: Date, options?: GovernanceFilterOptions): Promise<GovernanceOperationSummary>;
+}
+
+export { GovernanceService as Governance, PolicyEvaluationResult };
+export type { GovernanceFilterOptions, GovernanceOperationSummary, GovernancePolicyTrace, GovernancePolicyTraceGetAllOptions, GovernanceServiceModel };