@uipath/uipath-typescript 1.0.0-beta.18 → 1.1.0

package/dist/core/index.d.ts

@@ -0,0 +1,398 @@
+interface BaseConfig {
+    baseUrl: string;
+    orgName: string;
+    tenantName: string;
+}
+interface OAuthFields {
+    clientId: string;
+    redirectUri: string;
+    scope: string;
+}
+type UiPathSDKConfig = BaseConfig & ({
+    secret: string;
+    clientId?: never;
+    redirectUri?: never;
+    scope?: never;
+} | ({
+    secret?: never;
+} & OAuthFields));
+
+/**
+ * IUiPath - Interface for UiPath SDK instance
+ *
+ * This interface defines the public contract for the UiPath SDK.
+ * Services depend on this interface rather than the concrete UiPath class,
+ * enabling proper type sharing across modular imports without #private field issues.
+ *
+ * @internal This interface is for internal SDK use only
+ */
+
+interface IUiPath {
+    /** Read-only configuration for the SDK instance */
+    readonly config: Readonly<BaseConfig>;
+    /**
+     * Initialize the SDK based on the provided configuration.
+     * For secret-based auth, this returns immediately.
+     * For OAuth, this handles the authentication flow.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Check if the SDK has been initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Check if we're in an OAuth callback state
+     */
+    isInOAuthCallback(): boolean;
+    /**
+     * Complete OAuth authentication flow
+     */
+    completeOAuth(): Promise<boolean>;
+    /**
+     * Check if the user is authenticated (has valid token)
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Get the current authentication token
+     */
+    getToken(): string | undefined;
+}
+
+/**
+ * UiPath - Core SDK class for authentication and configuration management.
+ *
+ * Handles authentication, configuration, and provides access to SDK internals
+ * for service instantiation in the modular pattern.
+ *
+ * @example
+ * ```typescript
+ * // Modular pattern
+ * import { UiPath } from '@uipath/uipath-typescript/core';
+ * import { Entities } from '@uipath/uipath-typescript/entities';
+ *
+ * const sdk = new UiPath({
+ *   baseUrl: 'https://cloud.uipath.com',
+ *   orgName: 'myorg',
+ *   tenantName: 'mytenant',
+ *   clientId: 'xxx',
+ *   redirectUri: 'http://localhost:3000/callback',
+ *   scope: 'OR.Users OR.Robots'
+ * });
+ *
+ * await sdk.initialize();
+ *
+ * const entitiesService = new Entities(sdk);
+ * const allEntities = await entitiesService.getAll();
+ * ```
+ */
+declare class UiPath implements IUiPath {
+    #private;
+    /** Read-only config for user convenience */
+    readonly config: Readonly<BaseConfig>;
+    constructor(config: UiPathSDKConfig);
+    /**
+     * Initialize the SDK based on the provided configuration.
+     * This method handles both OAuth flow initiation and completion automatically.
+     * For secret-based authentication, initialization is automatic and this returns immediately.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Check if the SDK has been initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Check if we're in an OAuth callback state
+     */
+    isInOAuthCallback(): boolean;
+    /**
+     * Complete OAuth authentication flow (only call if isInOAuthCallback() is true)
+     */
+    completeOAuth(): Promise<boolean>;
+    /**
+     * Check if the user is authenticated (has valid token)
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Get the current authentication token
+     */
+    getToken(): string | undefined;
+}
+
+/**
+ * Error thrown when authorization fails (403 errors)
+ * Common scenarios:
+ * - Insufficient permissions
+ * - Access denied to resource
+ * - Invalid scope
+ */
+declare class AuthorizationError extends UiPathError {
+    constructor(params?: Partial<ErrorParams>);
+}
+
+/**
+ * Error thrown when validation fails (400 errors or client-side validation)
+ * Common scenarios:
+ * - Invalid input parameters
+ * - Missing required fields
+ * - Invalid data format
+ */
+declare class ValidationError extends UiPathError {
+    constructor(params?: Partial<ErrorParams>);
+}
+
+/**
+ * Error thrown when a resource is not found (404 errors)
+ * Common scenarios:
+ * - Resource doesn't exist
+ * - Invalid ID provided
+ * - Resource deleted
+ */
+declare class NotFoundError extends UiPathError {
+    constructor(params?: Partial<ErrorParams>);
+}
+
+/**
+ * Error thrown when rate limit is exceeded (429 errors)
+ * Common scenarios:
+ * - Too many requests in a time window
+ * - API throttling
+ */
+declare class RateLimitError extends UiPathError {
+    constructor(params?: Partial<ErrorParams>);
+}
+
+/**
+ * Error thrown when server encounters an error (5xx errors)
+ * Common scenarios:
+ * - Internal server error
+ * - Service unavailable
+ * - Gateway timeout
+ */
+declare class ServerError extends UiPathError {
+    constructor(params?: Partial<ErrorParams>);
+    /**
+     * Checks if this is a temporary error that might succeed on retry
+     */
+    get isRetryable(): boolean;
+}
+
+/**
+ * Base error creation parameters - only what's needed
+ */
+interface ErrorParams {
+    message: string;
+    statusCode?: number;
+    requestId?: string;
+}
+
+/**
+ * Base error class for all UiPath SDK errors
+ * Extends Error for standard error handling compatibility
+ */
+declare abstract class UiPathError extends Error {
+    /**
+     * Error type identifier (e.g., "AuthenticationError", "ValidationError")
+     */
+    readonly type: string;
+    /**
+     * HTTP status code (400, 401, 403, 404, 500, etc.)
+     */
+    readonly statusCode?: number;
+    /**
+     * Request ID for tracking with UiPath support
+     */
+    readonly requestId?: string;
+    /**
+     * Timestamp when the error occurred
+     */
+    readonly timestamp: Date;
+    protected constructor(type: string, params: ErrorParams);
+    /**
+     * Returns a clean JSON representation of the error
+     */
+    private toJSON;
+    /**
+     * Returns detailed debug information including stack trace
+     */
+    getDebugInfo(): Record<string, unknown>;
+}
+
+/**
+ * Error thrown when authentication fails (401 errors)
+ * Common scenarios:
+ * - Invalid credentials
+ * - Expired token
+ * - Missing authentication
+ */
+declare class AuthenticationError extends UiPathError {
+    constructor(params?: Partial<ErrorParams>);
+}
+
+/**
+ * Error thrown when network/connection issues occur
+ * Common scenarios:
+ * - Connection timeout
+ * - DNS resolution failure
+ * - Network unreachable
+ * - Request aborted
+ */
+declare class NetworkError extends UiPathError {
+    constructor(params?: Partial<ErrorParams>);
+}
+
+/**
+ * Type guard to check if an error is a UiPathError
+ */
+declare function isUiPathError(error: unknown): error is UiPathError;
+/**
+ * Type guard to check if an error is an AuthenticationError
+ */
+declare function isAuthenticationError(error: unknown): error is AuthenticationError;
+/**
+ * Type guard to check if an error is an AuthorizationError
+ */
+declare function isAuthorizationError(error: unknown): error is AuthorizationError;
+/**
+ * Type guard to check if an error is a ValidationError
+ */
+declare function isValidationError(error: unknown): error is ValidationError;
+/**
+ * Type guard to check if an error is a NotFoundError
+ */
+declare function isNotFoundError(error: unknown): error is NotFoundError;
+/**
+ * Type guard to check if an error is a RateLimitError
+ */
+declare function isRateLimitError(error: unknown): error is RateLimitError;
+/**
+ * Type guard to check if an error is a ServerError
+ */
+declare function isServerError(error: unknown): error is ServerError;
+/**
+ * Type guard to check if an error is a NetworkError
+ */
+declare function isNetworkError(error: unknown): error is NetworkError;
+/**
+ * Helper to get error details in a safe way
+ */
+declare function getErrorDetails(error: unknown): {
+    message: string;
+    statusCode?: number;
+};
+
+/**
+ * HTTP status code constants for error handling
+ */
+declare const HttpStatus: {
+    readonly BAD_REQUEST: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly FORBIDDEN: 403;
+    readonly NOT_FOUND: 404;
+    readonly TOO_MANY_REQUESTS: 429;
+    readonly INTERNAL_SERVER_ERROR: 500;
+    readonly NOT_IMPLEMENTED: 501;
+    readonly BAD_GATEWAY: 502;
+    readonly SERVICE_UNAVAILABLE: 503;
+    readonly GATEWAY_TIMEOUT: 504;
+};
+/**
+ * Error type constants for consistent error identification
+ */
+declare const ErrorType: {
+    readonly AUTHENTICATION: "AuthenticationError";
+    readonly AUTHORIZATION: "AuthorizationError";
+    readonly VALIDATION: "ValidationError";
+    readonly NOT_FOUND: "NotFoundError";
+    readonly RATE_LIMIT: "RateLimitError";
+    readonly SERVER: "ServerError";
+    readonly NETWORK: "NetworkError";
+};
+
+/**
+ * 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;
+});
+
+/**
+ * Constants used throughout the pagination system
+ */
+/** Maximum number of items that can be requested in a single page */
+declare const MAX_PAGE_SIZE = 1000;
+/** Default page size when jumpToPage is used without specifying pageSize */
+declare const DEFAULT_PAGE_SIZE = 50;
+/** Default field name for items in a paginated response */
+declare const DEFAULT_ITEMS_FIELD = "value";
+/** Default field name for total count in a paginated response */
+declare const DEFAULT_TOTAL_COUNT_FIELD = "@odata.count";
+/**
+ * Limits the page size to the maximum allowed value
+ * @param pageSize - Requested page size
+ * @returns Limited page size value
+ */
+declare function getLimitedPageSize(pageSize?: number): number;
+
+export { AuthenticationError, AuthorizationError, DEFAULT_ITEMS_FIELD, DEFAULT_PAGE_SIZE, DEFAULT_TOTAL_COUNT_FIELD, ErrorType, HttpStatus, MAX_PAGE_SIZE, NetworkError, NotFoundError, RateLimitError, ServerError, UiPath, UiPathError, ValidationError, getErrorDetails, getLimitedPageSize, isAuthenticationError, isAuthorizationError, isNetworkError, isNotFoundError, isRateLimitError, isServerError, isUiPathError, isValidationError };
+export type { HasPaginationOptions, NonPaginatedResponse, PaginatedResponse, PaginationCursor, PaginationMethodUnion, PaginationOptions, UiPathSDKConfig };