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;
}

interface BaseOptions {
    expand?: string;
    select?: string;
}
/**
 * Common request options interface used across services for querying data
 */
interface RequestOptions extends BaseOptions {
    filter?: string;
    orderby?: string;
}
/**
 * Options that scope a name-based lookup (e.g. `getByName`) to a folder.
 * Provide one of `folderId`, `folderKey`, or `folderPath`. When more than
 * one is supplied, all are forwarded; the server applies precedence
 * `folderPath` > `folderKey` > `folderId`.
 */
interface FolderScopedOptions extends BaseOptions {
    /** Numeric folder ID. */
    folderId?: number;
    /** Folder key (GUID-formatted string). */
    folderKey?: string;
    /** Slash-delimited folder path, e.g. `'Shared/Finance'`. */
    folderPath?: string;
}

/**
 * Type for field mapping configuration
 * Maps source field names to target field names
 */
type FieldMapping = {
    [sourceField: string]: string;
};

/**
 * Base service for services that need folder-specific functionality.
 *
 * Extends BaseService with additional methods for working with folder-scoped resources
 * in UiPath Orchestrator. Services that work with folders (Assets, Queues) extend this class.
 *
 * @remarks
 * This class provides helper methods for making folder-scoped API calls, handling folder IDs
 * in request headers, and managing cross-folder queries.
 */
declare class FolderScopedService extends BaseService {
    /**
     * Gets resources in a folder with optional query parameters
     *
     * @param endpoint - API endpoint to call
     * @param folderId - required folder ID
     * @param options - Query options
     * @param transformFn - Optional function to transform the response data
     * @returns Promise resolving to an array of resources
     */
    protected _getByFolder<T, R = T>(endpoint: string, folderId: number, options?: Record<string, any>, transformFn?: (item: T) => R): Promise<R[]>;
    /**
     * Look up a single resource by name on a folder-scoped OData collection.
     *
     * Shared by `getByName` implementations across services (Assets, Processes, etc).
     * Handles:
     * - Name validation via `validateName`
     * - Folder header resolution via `resolveFolderHeaders` (folderId → ID/key
     *   header by type, folderPath → encoded path header, falls back to
     *   init-time `config.folderKey` from the `uipath:folder-key` meta tag)
     * - OData `$filter=Name eq '…'` with single-quote escaping + `$top=1`
     * - Empty-result → `NotFoundError` with folder context in the message
     *
     * The transform step is caller-provided because each resource has its own
     * PascalCase → camelCase field mapping.
     *
     * @param resourceType - Resource label used in validation + error messages (e.g. 'Asset', 'Process')
     * @param endpoint - Folder-scoped OData collection endpoint
     * @param name - Resource name to search for
     * @param options - Folder scoping (`folderId` / `folderKey` / `folderPath`) + OData query options (`expand`, `select`)
     * @param transform - Maps a raw OData item to the typed response (e.g. PascalCase → camelCase via field map)
     * @param responseFieldMap - Optional response field map (API → SDK), reversed internally by
     *   `transformOptions` to rewrite SDK field names back to API names in user-supplied
     *   `expand` / `select` (symmetric counterpart to `transform`)
     * @throws ValidationError when inputs are malformed; NotFoundError when no match
     */
    protected getByNameLookup<TRaw extends object, T>(resourceType: string, endpoint: string, name: string, options: FolderScopedOptions, transform: (raw: TRaw) => T, responseFieldMap?: FieldMapping): Promise<T>;
}

declare enum BucketOptions {
    None = "None",
    ReadOnly = "ReadOnly",
    AuditReadAccess = "AuditReadAccess",
    AccessDataThroughOrchestrator = "AccessDataThroughOrchestrator"
}
interface BucketGetResponse {
    id: number;
    name: string;
    description: string | null;
    identifier: string;
    storageProvider: string | null;
    storageParameters: string | null;
    storageContainer: string | null;
    options: BucketOptions;
    credentialStoreId: number | null;
    externalName: string | null;
    password: string | null;
    foldersCount: number;
}
type BucketGetAllOptions = RequestOptions & PaginationOptions & {
    folderId?: number;
};
interface BucketGetByIdOptions extends BaseOptions {
}
/**
 * Options for getting a single bucket by name
 */
interface BucketGetByNameOptions extends FolderScopedOptions {
}
/**
 * Maps header names to their values
 *
 * @example
 * ```typescript
 * {
 *   "x-ms-blob-type": "BlockBlob"
 * }
 * ```
 */
type ResponseDictionary = Record<string, string>;
/**
 * Response from the GetReadUri API
 */
interface BucketGetUriResponse {
    /**
     * The URI for accessing the blob file
     */
    uri: string;
    /**
     * HTTP method to use with the URI
     */
    httpMethod: string;
    /**
     * Whether authentication is required to access the URI
     */
    requiresAuth: boolean;
    /**
     * Headers to be included in the request
     */
    headers: ResponseDictionary;
}
interface BucketGetUriOptions extends BaseOptions {
    /**
     * The ID of the bucket
     */
    bucketId: number;
    /**
     * The full path to the BlobFile
     */
    path: string;
    /**
     * URL expiration time in minutes (0 for default)
     */
    expiryInMinutes?: number;
}
/**
 * Optional parameters for the preferred `getReadUri(bucketId, path, options?)` form.
 * Contains folder scoping (`folderId` / `folderKey` / `folderPath`),
 * `expiryInMinutes`, and standard query options (`expand`, `select`).
 */
interface BucketGetReadUriRequestOptions extends BaseOptions, FolderScopedOptions {
    /**
     * URL expiration time in minutes (0 for default)
     */
    expiryInMinutes?: number;
}
/**
 * @deprecated Use the positional form: `getReadUri(bucketId, path, options?)`.
 * See {@link BucketGetReadUriRequestOptions} for the supported options.
 *
 * Request options for getting a read URI for a file in a bucket.
 */
interface BucketGetReadUriOptions extends BucketGetUriOptions, FolderScopedOptions {
}
/**
 * Request options for getting files in a bucket
 */
interface BucketGetFileMetaDataOptions {
    /**
     * The path prefix to filter files by
     */
    prefix?: string;
}
/**
 * Request options for getting files in a bucket with pagination support
 */
type BucketGetFileMetaDataWithPaginationOptions = BucketGetFileMetaDataOptions & PaginationOptions & FolderScopedOptions;
/**
 * Response from the GetFiles API
 */
interface BucketGetFileMetaDataResponse {
    /**
     * Array of blob items in the bucket
     */
    blobItems: BlobItem[];
    /**
     * Token for retrieving the next set of results
     */
    continuationToken: string | null;
}
/**
 * Represents a file or blob in a bucket
 */
interface BlobItem {
    /**
     * Full path to the blob
     */
    path: string;
    /**
     * Content type of the blob
     */
    contentType: string;
    /**
     * Size of the blob in bytes
     */
    size: number;
    /**
     * Last modified timestamp
     */
    lastModified: string | null;
}
/**
 * Represents a file or directory entry in a bucket
 */
interface BucketFile {
    /**
     * Full path to the file or directory
     */
    path: string;
    /**
     * Content type of the file (empty for directories)
     */
    contentType: string;
    /**
     * Size of the file in bytes
     */
    size: number;
    /**
     * Whether the entry is a directory
     */
    isDirectory: boolean;
    /**
     * Identifier of the file, when available
     */
    id: string | null;
}
/**
 * Options for listing files in a bucket directory
 */
type BucketGetFilesOptions = RequestOptions & PaginationOptions & FolderScopedOptions & {
    /**
     * Regex pattern to filter file names (e.g., '.*\\.pdf$')
     */
    fileNameRegex?: string;
};
/**
 * Options for deleting a file from a bucket
 */
interface BucketDeleteFileOptions extends FolderScopedOptions {
}
/**
 * Optional parameters for the preferred
 * `uploadFile(bucketId, path, content, options?)` form. Contains folder
 * scoping (`folderId` / `folderKey` / `folderPath`).
 */
interface BucketUploadFileRequestOptions extends FolderScopedOptions {
}
/**
 * @deprecated Use the positional form: `uploadFile(bucketId, path, content, options?)`.
 * See {@link BucketUploadFileRequestOptions} for the supported options.
 *
 * Options for uploading files to a bucket.
 */
interface BucketUploadFileOptions extends FolderScopedOptions {
    /**
     * The ID of the bucket to upload to
     */
    bucketId: number;
    /**
     * Path where the file should be stored in the bucket
     */
    path: string;
    /**
     * File content to upload
     */
    content: Blob | Uint8Array<ArrayBuffer> | File;
}
/**
 * Response from file upload operations
 */
interface BucketUploadResponse {
    /**
     * Whether the upload was successful
     */
    success: boolean;
    /**
     * HTTP status code from the upload operation
     */
    statusCode: number;
}

/**
 * Service for managing UiPath storage Buckets.
 *
 * Buckets are cloud storage containers that can be used to store and manage files used by automation processes. [UiPath Buckets Guide](https://docs.uipath.com/orchestrator/automation-cloud/latest/user-guide/about-storage-buckets)
 *
 * ### Usage
 *
 * Prerequisites: Initialize the SDK first - see [Getting Started](/uipath-typescript/getting-started/#import-initialize)
 *
 * ```typescript
 * import { Buckets } from '@uipath/uipath-typescript/buckets';
 *
 * const buckets = new Buckets(sdk);
 * const allBuckets = await buckets.getAll();
 * ```
 */
interface BucketServiceModel {
    /**
     * Gets all buckets across folders with optional filtering
     *
     * The method returns either:
     * - A NonPaginatedResponse with data and totalCount (when no pagination parameters are provided)
     * - A paginated result with navigation cursors (when any pagination parameter is provided)
     *
     * @param options - Query options including optional folderId and pagination options
     * @returns Promise resolving to either an array of buckets NonPaginatedResponse<BucketGetResponse> or a PaginatedResponse<BucketGetResponse> when pagination options are used.
     * {@link BucketGetResponse}
     * @example
     * ```typescript
     * // Get all buckets across folders
     * const allBuckets = await buckets.getAll();
     *
     * // Get buckets within a specific folder
     * const folderBuckets = await buckets.getAll({
     *   folderId: <folderId>
     * });
     *
     * // Get buckets with filtering
     * const filteredBuckets = await buckets.getAll({
     *   filter: "name eq 'MyBucket'"
     * });
     *
     * // First page with pagination
     * const page1 = await buckets.getAll({ pageSize: 10 });
     *
     * // Navigate using cursor
     * if (page1.hasNextPage) {
     *   const page2 = await buckets.getAll({ cursor: page1.nextCursor });
     * }
     *
     * // Jump to specific page
     * const page5 = await buckets.getAll({
     *   jumpToPage: 5,
     *   pageSize: 10
     * });
     * ```
     */
    getAll<T extends BucketGetAllOptions = BucketGetAllOptions>(options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BucketGetResponse> : NonPaginatedResponse<BucketGetResponse>>;
    /**
     * Gets a single bucket by ID
     *
     * @param bucketId - Bucket ID
     * @param folderId - Required folder ID
     * @param options - Optional query parameters
     * @returns Promise resolving to a bucket definition
     * {@link BucketGetResponse}
     * @example
     * ```typescript
     * // Get bucket by ID
     * const bucket = await buckets.getById(<bucketId>, <folderId>);
     * ```
     */
    getById(bucketId: number, folderId: number, options?: BucketGetByIdOptions): Promise<BucketGetResponse>;
    /**
     * Retrieves a single orchestrator storage bucket by name.
     *
     * @param name - Bucket name to search for
     * @param options - Folder scoping (`folderId` / `folderKey` / `folderPath`) and optional query parameters (`expand`, `select`)
     * @returns Promise resolving to a single bucket
     * {@link BucketGetResponse}
     * @example
     * ```typescript
     * // By folder ID
     * await buckets.getByName('MyBucket', { folderId: <folderId> });
     *
     * // By folder key (GUID)
     * await buckets.getByName('MyBucket', { folderKey: '<folderKey>' });
     *
     * // By folder path
     * await buckets.getByName('MyBucket', { folderPath: '<folderPath>' });
     * ```
     */
    getByName(name: string, options?: BucketGetByNameOptions): Promise<BucketGetResponse>;
    /**
     * Gets metadata for files in a bucket with optional filtering and pagination.
     *
     * Folder context can be supplied as `folderId`, `folderKey`, or `folderPath`
     * inside the options.
     *
     * The method returns either:
     * - A NonPaginatedResponse with items array (when no pagination parameters are provided)
     * - A PaginatedResponse with navigation cursors (when any pagination parameter is provided)
     *
     * @param bucketId - The ID of the bucket to get file metadata from
     * @param options - Folder scoping (`folderId` / `folderKey` / `folderPath`) and optional parameters for filtering and pagination
     * @returns Promise resolving to either an array of files metadata NonPaginatedResponse<BlobItem> or a PaginatedResponse<BlobItem> when pagination options are used.
     * {@link BlobItem}
     * @example
     * ```typescript
     * // By folder ID
     * const fileMetadata = await buckets.getFileMetaData(<bucketId>, { folderId: <folderId> });
     *
     * // By folder key (GUID)
     * await buckets.getFileMetaData(<bucketId>, { folderKey: '5f6dadf1-3677-49dc-8aca-c2999dd4b3ba' });
     *
     * // By folder path
     * await buckets.getFileMetaData(<bucketId>, { folderPath: 'Shared/Finance' });
     *
     * // Filter by prefix
     * await buckets.getFileMetaData(<bucketId>, { folderId: <folderId>, prefix: '/folder1' });
     *
     * // First page with pagination
     * const page1 = await buckets.getFileMetaData(<bucketId>, { folderId: <folderId>, pageSize: 10 });
     *
     * // Navigate using cursor
     * if (page1.hasNextPage) {
     *   const page2 = await buckets.getFileMetaData(<bucketId>, { folderId: <folderId>, cursor: page1.nextCursor });
     * }
     * ```
     */
    getFileMetaData<T extends BucketGetFileMetaDataWithPaginationOptions = BucketGetFileMetaDataWithPaginationOptions>(bucketId: number, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BlobItem> : NonPaginatedResponse<BlobItem>>;
    /**
     * Gets metadata for files in a bucket — positional `folderId` form.
     *
     * @deprecated Use the options-object form: `getFileMetaData(bucketId, { folderId })`. See {@link BucketGetFileMetaDataWithPaginationOptions} for the supported options.
     *
     * @param bucketId - The ID of the bucket to get file metadata from
     * @param folderId - Required folder ID (numeric)
     * @param options - Optional parameters for filtering and pagination
     * @returns Promise resolving to either an array of files metadata NonPaginatedResponse<BlobItem> or a PaginatedResponse<BlobItem> when pagination options are used.
     * {@link BlobItem}
     */
    getFileMetaData<T extends BucketGetFileMetaDataWithPaginationOptions = BucketGetFileMetaDataWithPaginationOptions>(bucketId: number, folderId: number, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BlobItem> : NonPaginatedResponse<BlobItem>>;
    /**
     * Gets a direct download URL for a file in the bucket.
     *
     * Folder context can be supplied as `folderId`, `folderKey`, or `folderPath`
     * in the options.
     *
     * @param bucketId - The ID of the bucket
     * @param path - The full path to the file
     * @param options - Folder scoping (`folderId` / `folderKey` / `folderPath`) and optional `expiryInMinutes`
     * @returns Promise resolving to blob file access information
     * {@link BucketGetUriResponse}
     * @example
     * ```typescript
     * // By folder ID
     * await buckets.getReadUri(<bucketId>, '/folder/file.pdf', { folderId: <folderId> });
     *
     * // By folder key (GUID)
     * await buckets.getReadUri(<bucketId>, '/folder/file.pdf', { folderKey: '5f6dadf1-3677-49dc-8aca-c2999dd4b3ba' });
     *
     * // By folder path
     * await buckets.getReadUri(<bucketId>, '/folder/file.pdf', { folderPath: 'Shared/Finance' });
     * ```
     */
    getReadUri(bucketId: number, path: string, options?: BucketGetReadUriRequestOptions): Promise<BucketGetUriResponse>;
    /**
     * Gets a direct download URL for a file in the bucket — options-only form.
     *
     * @deprecated Use the positional form: `getReadUri(bucketId, path, options?)`. See {@link BucketGetReadUriRequestOptions} for the supported options.
     *
     * @param options - Contains bucketId, folder scoping (`folderId` / `folderKey` / `folderPath`), file path and optional expiry time
     * @returns Promise resolving to blob file access information
     * {@link BucketGetUriResponse}
     */
    getReadUri(options: BucketGetReadUriOptions): Promise<BucketGetUriResponse>;
    /**
     * Uploads a file to a bucket.
     *
     * Folder context can be supplied as `folderId`, `folderKey`, or `folderPath`
     * in the options.
     *
     * @param bucketId - The ID of the bucket to upload to
     * @param path - Path where the file should be stored in the bucket
     * @param content - File content to upload
     * @param options - Folder scoping (`folderId` / `folderKey` / `folderPath`)
     * @returns Promise resolving bucket upload response
     * {@link BucketUploadResponse}
     * @example
     * ```typescript
     * // By folder ID
     * const file = new File(['file content'], 'example.txt');
     * await buckets.uploadFile(<bucketId>, '/folder/example.txt', file, { folderId: <folderId> });
     *
     * // By folder key (GUID)
     * await buckets.uploadFile(<bucketId>, '/folder/example.txt', file, { folderKey: '5f6dadf1-3677-49dc-8aca-c2999dd4b3ba' });
     *
     * // By folder path
     * await buckets.uploadFile(<bucketId>, '/folder/example.txt', file, { folderPath: 'Shared/Finance' });
     *
     * // In Node env with Uint8Array or Buffer
     * const content = new TextEncoder().encode('file content');
     * await buckets.uploadFile(<bucketId>, '/folder/example.txt', content, { folderId: <folderId> });
     * ```
     */
    uploadFile(bucketId: number, path: string, content: Blob | Uint8Array<ArrayBuffer> | File, options?: BucketUploadFileRequestOptions): Promise<BucketUploadResponse>;
    /**
     * Uploads a file to a bucket — options-only form.
     *
     * @deprecated Use the positional form: `uploadFile(bucketId, path, content, options?)`. See {@link BucketUploadFileRequestOptions} for the supported options.
     *
     * @param options - Options for file upload including bucket ID, folder scoping (`folderId` / `folderKey` / `folderPath`), path, and content
     * @returns Promise resolving bucket upload response
     * {@link BucketUploadResponse}
     */
    uploadFile(options: BucketUploadFileOptions): Promise<BucketUploadResponse>;
    /**
     * Deletes a file from a bucket
     *
     * @param bucketId - The ID of the bucket
     * @param path - The full path to the file to delete
     * @param options - Folder scoping (`folderId` / `folderKey` / `folderPath`)
     * @returns Promise resolving when the file is deleted
     * @example
     * ```typescript
     * // Delete a file from a bucket
     * await buckets.deleteFile(<bucketId>, '/folder/file.pdf', { folderId: <folderId> });
     * ```
     */
    deleteFile(bucketId: number, path: string, options?: BucketDeleteFileOptions): Promise<void>;
    /**
     * Lists all files in a bucket.
     *
     * Returns a flat, recursive listing of all files in the bucket. Supports regex filtering
     * and filter / orderby / select / expand. {@link BucketFile} entries include
     * `isDirectory` so callers can distinguish folders from files.
     *
     * The method returns either:
     * - A NonPaginatedResponse with items array (when no pagination parameters are provided)
     * - A PaginatedResponse with navigation cursors (when any pagination parameter is provided)
     *
     * @param bucketId - The ID of the bucket
     * @param options - Folder scoping (`folderId` / `folderKey` / `folderPath`) and optional parameters for regex filtering, query options, and pagination
     * {@link BucketGetFilesOptions}
     * @returns Promise resolving to either an array of files NonPaginatedResponse<BucketFile> or a PaginatedResponse<BucketFile> when pagination options are used.
     * {@link BucketFile}
     * @example
     * ```typescript
     * // List all files in the bucket
     * const files = await buckets.getFiles(<bucketId>, { folderId: <folderId> });
     *
     * // Filter by regex pattern
     * const pdfs = await buckets.getFiles(<bucketId>, {
     *   folderId: <folderId>,
     *   fileNameRegex: '.*\\.pdf$'
     * });
     *
     * // First page with pagination
     * const page1 = await buckets.getFiles(<bucketId>, { folderId: <folderId>, pageSize: 10 });
     *
     * // Navigate using cursor
     * if (page1.hasNextPage) {
     *   const page2 = await buckets.getFiles(<bucketId>, { folderId: <folderId>, cursor: page1.nextCursor });
     * }
     *
     * // Jump to specific page
     * const page5 = await buckets.getFiles(<bucketId>, {
     *   folderId: <folderId>,
     *   jumpToPage: 5,
     *   pageSize: 10
     * });
     * ```
     */
    getFiles<T extends BucketGetFilesOptions = BucketGetFilesOptions>(bucketId: number, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BucketFile> : NonPaginatedResponse<BucketFile>>;
}

declare class BucketService extends FolderScopedService implements BucketServiceModel {
    getById(id: number, folderId: number, options?: BucketGetByIdOptions): Promise<BucketGetResponse>;
    getByName(name: string, options?: BucketGetByNameOptions): Promise<BucketGetResponse>;
    getAll<T extends BucketGetAllOptions = BucketGetAllOptions>(options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BucketGetResponse> : NonPaginatedResponse<BucketGetResponse>>;
    getFileMetaData<T extends BucketGetFileMetaDataWithPaginationOptions = BucketGetFileMetaDataWithPaginationOptions>(bucketId: number, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BlobItem> : NonPaginatedResponse<BlobItem>>;
    getFileMetaData<T extends BucketGetFileMetaDataWithPaginationOptions = BucketGetFileMetaDataWithPaginationOptions>(bucketId: number, folderId: number, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BlobItem> : NonPaginatedResponse<BlobItem>>;
    uploadFile(bucketId: number, path: string, content: Blob | Uint8Array<ArrayBuffer> | File, options?: BucketUploadFileRequestOptions): Promise<BucketUploadResponse>;
    uploadFile(options: BucketUploadFileOptions): Promise<BucketUploadResponse>;
    getReadUri(bucketId: number, path: string, options?: BucketGetReadUriRequestOptions): Promise<BucketGetUriResponse>;
    getReadUri(options: BucketGetReadUriOptions): Promise<BucketGetUriResponse>;
    /**
     * Uploads content to the provided URI
     * @param uriResponse - Response from getWriteUri containing URL and headers
     * @param content - The content to upload
     * @returns The response from the upload request with status info
     */
    private _uploadToUri;
    /**
     * Private method to handle common URI request logic
     * @param endpoint - The API endpoint to call
     * @param bucketId - The bucket ID
     * @param path - The file path
     * @param headers - Pre-built folder-context headers (built via `resolveFolderHeaders`)
     * @param queryOptions - Additional query parameters
     * @returns Promise resolving to blob file access information
     */
    private _getUri;
    getFiles<T extends BucketGetFilesOptions = BucketGetFilesOptions>(bucketId: number, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<BucketFile> : NonPaginatedResponse<BucketFile>>;
    deleteFile(bucketId: number, path: string, options?: BucketDeleteFileOptions): Promise<void>;
    /**
     * Gets a direct upload URL for a file in the bucket
     *
     * @param options - Contains bucketId, file path, optional expiry time, and pre-built folder-context headers
     * @returns Promise resolving to blob file access information
     */
    private _getWriteUri;
}

export { BucketOptions, BucketService, BucketService as Buckets };
export type { BlobItem, BucketDeleteFileOptions, BucketFile, BucketGetAllOptions, BucketGetByIdOptions, BucketGetByNameOptions, BucketGetFileMetaDataOptions, BucketGetFileMetaDataResponse, BucketGetFileMetaDataWithPaginationOptions, BucketGetFilesOptions, BucketGetReadUriOptions, BucketGetReadUriRequestOptions, BucketGetResponse, BucketGetUriOptions, BucketGetUriResponse, BucketServiceModel, BucketUploadFileOptions, BucketUploadFileRequestOptions, BucketUploadResponse, ResponseDictionary };