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 { /** 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 { 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 & { 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(path: string, options?: any): Promise<{ data: T; }>; post(path: string, body?: any, options?: any): Promise<{ data: T; }>; requestWithPagination(method: string, path: string, paginationOptions: PaginationOptions, options: RequestWithPaginationOptions): Promise>; } /** * 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 | null | undefined>; /** * Standard HTTP headers type */ type Headers = Record; /** * 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 { 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); /** * 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; /** * Creates a service accessor for pagination helpers * This allows pagination helpers to access protected methods without making them public */ protected createPaginationServiceAccess(): PaginationServiceAccess; protected request(method: string, path: string, options?: RequestSpec): Promise>; protected requestWithSpec(spec: RequestSpec): Promise>; protected get(path: string, options?: RequestSpec): Promise>; protected post(path: string, data?: unknown, options?: RequestSpec): Promise>; protected put(path: string, data?: unknown, options?: RequestSpec): Promise>; protected patch(path: string, data?: unknown, options?: RequestSpec): Promise>; protected delete(path: string, options?: RequestSpec): Promise>; /** * Execute a request with cursor-based pagination */ protected requestWithPagination(method: string, path: string, paginationOptions: PaginationOptions, options: RequestWithPaginationOptions): Promise>; /** * 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; } /** * Represents a category that can be associated with feedback. * Default categories (Output, Agent Error, Agent Plan Execution) are auto-created per tenant. * Used as nested objects inside {@link FeedbackResponse}. */ interface FeedbackCategory { /** Unique identifier of the feedback category */ id: string; /** Category name (max 256 characters, unique per tenant) */ category: string; /** Timestamp when the category was created */ createdAt: string; /** Whether this is a system default category (e.g., Output, Agent Error, Agent Plan Execution) */ isDefault: boolean; /** Whether this category applies to positive feedback */ isPositive: boolean; /** Whether this category applies to negative feedback */ isNegative: boolean; } /** * A feedback category returned by {@link FeedbackServiceModel.getCategories}, {@link FeedbackServiceModel.createCategory}. * Fields are transformed to camelCase SDK conventions (createdAt → createdTime). */ interface FeedbackCategoryResponse { /** Unique identifier of the feedback category */ id: string; /** Category name (max 256 characters, unique per tenant) */ category: string; /** Timestamp when the category was created */ createdTime: string; /** Whether this is a system default category (e.g., Output, Agent Error, Agent Plan Execution) */ isDefault: boolean; /** Whether this category applies to positive feedback */ isPositive: boolean; /** Whether this category applies to negative feedback */ isNegative: boolean; } /** * Status of a feedback entry in the review workflow */ declare enum FeedbackStatus { /** Feedback is awaiting review */ Pending = 0, /** Feedback has been approved and confirmed */ Approved = 1, /** Feedback has been dismissed */ Dismissed = 2 } /** * Complete feedback object returned from the API */ interface FeedbackResponse { /** Unique identifier of the feedback entry */ id: string; /** Trace identifier linking feedback to a specific agent execution */ traceId: string; /** Span identifier representing a specific operation within the trace */ spanId: string; /** Identifier of the agent that generated the response being reviewed */ agentId: string | null; /** Version of the agent at the time the feedback was given (max 100 characters) */ agentVersion?: string; /** Optional text comment provided by the user (max 4000 characters) */ comment?: string; /** Optional metadata string associated with the feedback (max 4000 characters) */ metadata?: string; /** Whether the feedback is positive (thumbs up) or negative (thumbs down) */ isPositive: boolean; /** Categories associated with this feedback entry */ feedbackCategories: FeedbackCategory[]; /** Folder key (GUID) of the folder the feedback belongs to */ folderKey?: string; /** Email address of the user who submitted the feedback */ userEmail?: string; /** Current status of the feedback in the review workflow */ status: FeedbackStatus; /** Timestamp when the feedback was created */ createdTime: string; /** Timestamp when the feedback was last updated */ updatedTime: string; } /** * Feedback object returned by getAll and getById. * Extends {@link FeedbackResponse} — use this type for getAll/getById return values. */ interface FeedbackGetResponse extends FeedbackResponse { } /** * Options shared across feedback operations */ interface FeedbackOptions { /** Folder key for authorization */ folderKey: string; } /** * A category reference used when creating or updating feedback */ interface FeedbackCategoryInput { /** Unique identifier of the category */ id: string; /** Category name (e.g., 'Output', 'Agent Error', 'Agent Plan Execution') */ category: string; } /** * Options for submitting a new feedback entry */ interface FeedbackSubmitOptions extends FeedbackOptions { /** Span identifier representing a specific operation within the trace */ spanId?: string; /** Identifier of the agent that generated the response being reviewed */ agentId?: string; /** Version of the agent at the time the feedback was given (max 100 characters) */ agentVersion?: string; /** Span type (e.g., 'agentRun', 'llm', 'tool', 'retriever') (max 100 characters) */ spanType?: string; /** Optional text comment provided by the user (max 4000 characters) */ comment?: string; /** Optional metadata string associated with the feedback (max 4000 characters) */ metadata?: string; /** Categories to associate with this feedback entry */ categories?: FeedbackCategoryInput[]; } /** * Options for updating an existing feedback entry */ interface FeedbackUpdateOptions extends FeedbackOptions { /** Optional text comment provided by the user (max 4000 characters) */ comment?: string; /** Optional metadata string associated with the feedback (max 4000 characters) */ metadata?: string; /** Categories to associate with this feedback entry */ categories?: FeedbackCategoryInput[]; } /** * Options for retrieving multiple feedback entries */ type FeedbackGetAllOptions = PaginationOptions & { /** Filter by agent identifier */ agentId?: string; /** Filter by agent version */ agentVersion?: string; /** Filter by feedback status */ status?: FeedbackStatus; /** Filter by OpenTelemetry trace identifier */ traceId?: string; /** Filter by OpenTelemetry span identifier */ spanId?: string; }; /** * Options for creating a new feedback category */ interface FeedbackCreateCategoryOptions { /** Whether the category applies to positive feedback (defaults to true) */ isPositive?: boolean; /** Whether the category applies to negative feedback (defaults to true) */ isNegative?: boolean; } /** * Options for deleting a feedback category. * Note: system default categories (Output, Agent Error, Agent Plan Execution) cannot be deleted — attempting to do so returns a 409 Conflict. */ interface FeedbackDeleteCategoryOptions { /** When true, deletes the category even if it has associated feedback entries */ forceDelete?: boolean; } /** * Options for retrieving feedback categories */ type FeedbackGetCategoriesOptions = PaginationOptions & { /** Filter by whether the category applies to positive feedback */ isPositive?: boolean; /** Filter by whether the category applies to negative feedback */ isNegative?: boolean; }; /** * Service for managing UiPath Agent Feedback. * * Feedback allows you to collect and manage user feedback on AI agent responses, * including positive/negative ratings, comments, and categorized feedback. * This is useful for monitoring agent quality, identifying areas for improvement, * and building datasets for fine-tuning. [Feedback on agent runs](https://docs.uipath.com/agents/automation-cloud/latest/user-guide/agent-traces#feedback-on-agent-runs) * * ### Usage * * Prerequisites: Initialize the SDK first - see [Getting Started](/uipath-typescript/getting-started/#import-initialize) * * ```typescript * import { Feedback } from '@uipath/uipath-typescript/feedback'; * * const feedback = new Feedback(sdk); * const allFeedback = await feedback.getAll(); * ``` */ interface FeedbackServiceModel { /** * Gets all feedback across all agents in the tenant, with optional filters. * * Retrieves a list of feedback entries, optionally filtered by agent, trace, span, status, or agent version. * When no pagination options are provided, the SDK returns up to 100 items. When pagination options are provided without a pageSize, the SDK defaults to 50 items per page. * * @param options - Optional query parameters for filtering and pagination * @returns Promise resolving to {@link NonPaginatedResponse} of {@link FeedbackResponse} without pagination options, or {@link PaginatedResponse} of {@link FeedbackResponse} when pagination options are used. * @example * ```typescript * import { Feedback, FeedbackStatus } from '@uipath/uipath-typescript/feedback'; * * // Get all feedback (returns API default page size) * const allFeedback = await feedback.getAll(); * * // Get the agentId from a feedback entry * const agentId = allFeedback.items[0].agentId; * * // Get feedback for a specific agent * const agentFeedback = await feedback.getAll({ * agentId, * }); * * // First page with pagination * const page1 = await feedback.getAll({ pageSize: 10 }); * * // Navigate using cursor * if (page1.hasNextPage) { * const page2 = await feedback.getAll({ cursor: page1.nextCursor }); * } * * // Filter by status * const activeFeedback = await feedback.getAll({ * status: FeedbackStatus.Pending, * }); * ``` */ getAll(options?: T): Promise ? PaginatedResponse : NonPaginatedResponse>; /** * Gets a single feedback entry by its feedback ID. * * @param id - Feedback ID (GUID) of the feedback entry * @param options - Required options including folderKey for folder-level authorization {@link FeedbackOptions} * @returns Promise resolving to {@link FeedbackResponse} * @example * ```typescript * import { Feedback } from '@uipath/uipath-typescript/feedback'; * * const feedback = new Feedback(sdk); * * // First, get feedback entries to obtain the ID and folder key * const allFeedback = await feedback.getAll({ pageSize: 10 }); * const feedbackId = allFeedback.items[0].id; * const folderKey = allFeedback.items[0].folderKey; * * const item = await feedback.getById(feedbackId, { folderKey }); * console.log(item.isPositive, item.comment, item.status); * ``` */ getById(id: string, options: FeedbackOptions): Promise; /** * Submits a feedback entry. * * @param traceId - Trace identifier linking feedback to a specific agent execution * @param isPositive - Whether the feedback is positive (thumbs up) or negative (thumbs down) * @param options - Additional feedback data and folderKey for authorization {@link FeedbackSubmitOptions} * @returns Promise resolving to the submitted {@link FeedbackResponse} * @example * ```typescript * import { Feedback } from '@uipath/uipath-typescript/feedback'; * * const feedback = new Feedback(sdk); * * // Obtain traceId and folderKey from an existing feedback entry * const allFeedback = await feedback.getAll({ pageSize: 1 }); * const traceId = allFeedback.items[0].traceId; * const folderKey = allFeedback.items[0].folderKey!; * * const item = await feedback.submit(traceId, true, { folderKey }); * console.log(item.id, item.status); * ``` */ submit(traceId: string, isPositive: boolean, options: FeedbackSubmitOptions): Promise; /** * Updates already submitted feedback. * * @param id - Feedback ID (GUID) of the entry to update * @param isPositive - Whether the feedback is positive (thumbs up) or negative (thumbs down) * @param options - Updated feedback data and folderKey for authorization {@link FeedbackUpdateOptions} * @returns Promise resolving to the updated {@link FeedbackResponse} * @example * ```typescript * import { Feedback } from '@uipath/uipath-typescript/feedback'; * * const feedback = new Feedback(sdk); * * const allFeedback = await feedback.getAll({ pageSize: 1 }); * const feedbackId = allFeedback.items[0].id; * const folderKey = allFeedback.items[0].folderKey!; * * const updated = await feedback.updateById(feedbackId, false, { * comment: 'On reflection, not great.', * folderKey, * }); * console.log(updated.isPositive, updated.comment); * ``` */ updateById(id: string, isPositive: boolean, options: FeedbackUpdateOptions): Promise; /** * Deletes a feedback entry by its ID. * * @param id - Feedback ID (GUID) of the entry to delete * @param options - Required options including folderKey for folder-level authorization {@link FeedbackOptions} * @returns Promise resolving to void on success * @example * ```typescript * import { Feedback } from '@uipath/uipath-typescript/feedback'; * * const feedback = new Feedback(sdk); * * const allFeedback = await feedback.getAll({ pageSize: 1 }); * const feedbackId = allFeedback.items[0].id; * const folderKey = allFeedback.items[0].folderKey!; * * await feedback.deleteById(feedbackId, { folderKey }); * ``` */ deleteById(id: string, options: FeedbackOptions): Promise; /** * Creates a new feedback category. * * Custom categories can be used to label feedback entries beyond the default system categories. * Once created, reference the category by its `id` when submitting or updating feedback. * If `isPositive` and `isNegative` are omitted, the backend defaults both to `true`. * * @param category - Name of the category to create (max 256 characters, unique per tenant) * @param options - Optional flags controlling whether the category applies to positive and/or negative feedback {@link FeedbackCreateCategoryOptions} * @returns Promise resolving to the created {@link FeedbackCategoryResponse} * @example * ```typescript * import { Feedback } from '@uipath/uipath-typescript/feedback'; * * const feedback = new Feedback(sdk); * * // Minimum — applies to both positive and negative feedback by default * const category = await feedback.createCategory('Hallucination'); * console.log(category.id, category.category); * * // With explicit flags * const negativeOnly = await feedback.createCategory('Off-topic', { * isPositive: false, * isNegative: true, * }); * ``` */ createCategory(category: string, options?: FeedbackCreateCategoryOptions): Promise; /** * Gets all feedback categories for the tenant. * * Returns both system default categories (Output, Agent Error, Agent Plan Execution) * and any custom categories created for this tenant. * When no pagination options are provided, the SDK returns up to 100 items. When pagination options are provided without a pageSize, the SDK defaults to 50 items per page. * * @param options - Optional filters and pagination options {@link FeedbackGetCategoriesOptions} * @returns Promise resolving to {@link NonPaginatedResponse} of {@link FeedbackCategoryResponse} without pagination options, or {@link PaginatedResponse} of {@link FeedbackCategoryResponse} when pagination options are used. * @example * ```typescript * import { Feedback } from '@uipath/uipath-typescript/feedback'; * * const feedback = new Feedback(sdk); * * // Get all categories * const categories = await feedback.getCategories(); * console.log(categories.items.map(c => c.category)); * * // Get only categories applicable to negative feedback * const negativeCategories = await feedback.getCategories({ isNegative: true }); * * // Paginated * const page1 = await feedback.getCategories({ pageSize: 10 }); * ``` */ getCategories(options?: T): Promise ? PaginatedResponse : NonPaginatedResponse>; /** * Deletes a feedback category by its ID. * * System default categories (Output, Agent Error, Agent Plan Execution) cannot be deleted — * attempting to do so throws a `409 Conflict` error. * Use `forceDelete` to delete a custom category that already has feedback entries associated with it. * * @param id - Category ID (GUID) of the category to delete * @param options - Optional deletion options {@link FeedbackDeleteCategoryOptions} * @returns Promise resolving to void on success * @example * ```typescript * import { Feedback } from '@uipath/uipath-typescript/feedback'; * * const feedback = new Feedback(sdk); * * // Only custom categories (isDefault: false) can be deleted * const categories = await feedback.getCategories(); * const customCategory = categories.items.find(c => !c.isDefault); * if (customCategory) { * await feedback.deleteCategory(customCategory.id); * } * ``` * @example * ```typescript * // Force-delete a custom category that has associated feedback entries * const categories = await feedback.getCategories(); * const customCategory = categories.items.find(c => !c.isDefault); * if (customCategory) { * await feedback.deleteCategory(customCategory.id, { forceDelete: true }); * } * ``` */ deleteCategory(id: string, options?: FeedbackDeleteCategoryOptions): Promise; } /** * Service for interacting with UiPath Agent Feedback API */ declare class FeedbackService extends BaseService implements FeedbackServiceModel { getAll(options?: T): Promise ? PaginatedResponse : NonPaginatedResponse>; getById(id: string, options: FeedbackOptions): Promise; submit(traceId: string, isPositive: boolean, options: FeedbackSubmitOptions): Promise; updateById(id: string, isPositive: boolean, options: FeedbackUpdateOptions): Promise; deleteById(id: string, options: FeedbackOptions): Promise; createCategory(category: string, options?: FeedbackCreateCategoryOptions): Promise; getCategories(options?: T): Promise ? PaginatedResponse : NonPaginatedResponse>; deleteCategory(id: string, options?: FeedbackDeleteCategoryOptions): Promise; } export { FeedbackService as Feedback, FeedbackStatus }; export type { FeedbackCategory, FeedbackCategoryInput, FeedbackCategoryResponse, FeedbackCreateCategoryOptions, FeedbackDeleteCategoryOptions, FeedbackGetAllOptions, FeedbackGetCategoriesOptions, FeedbackGetResponse, FeedbackOptions, FeedbackResponse, FeedbackServiceModel, FeedbackSubmitOptions, FeedbackUpdateOptions };