@uipath/skills 1.195.0

package/skills/uipath-coded-apps/references/sdk/orchestrator.md

@@ -0,0 +1,358 @@
+# Orchestrator Reference
+
+## Imports
+
+```typescript
+import { Assets } from '@uipath/uipath-typescript/assets';
+import { Queues } from '@uipath/uipath-typescript/queues';
+import { Buckets } from '@uipath/uipath-typescript/buckets';
+import { Processes } from '@uipath/uipath-typescript/processes';
+import { Jobs } from '@uipath/uipath-typescript/jobs';
+import { Attachments } from '@uipath/uipath-typescript/attachments';
+```
+
+## Note: Folder-Scoped Services
+
+Assets, Queues, Buckets, and Processes are folder-scoped. Many methods require a `folderId` parameter.
+
+**Bound methods**: `Jobs.getById()` and `Jobs.getAll()` items return response objects with attached methods (`getOutput()`, `stop()`, `resume()`, `restart()`). Assets, Queues, Buckets, Processes, and Attachments responses do **not** have attached methods — use the service directly.
+
+## `getByName` folder identifiers
+
+`Assets.getByName` and `Processes.getByName` accept `FolderScopedOptions` — supply one of `folderId`, `folderKey`, or `folderPath` (e.g., `'Shared/Finance'`). If multiple are supplied, server precedence is `folderPath` > `folderKey` > `folderId`.
+
+## Types to Import
+
+```typescript
+// Assets
+import type {
+  AssetGetResponse,
+  AssetGetAllOptions,
+  AssetGetByIdOptions,
+  AssetGetByNameOptions,
+  CustomKeyValuePair,
+} from '@uipath/uipath-typescript/assets';
+
+// Queues
+import type {
+  QueueGetResponse,
+  QueueGetAllOptions,
+  QueueGetByIdOptions,
+} from '@uipath/uipath-typescript/queues';
+
+// Buckets
+import type {
+  BucketGetResponse,
+  BucketGetAllOptions,
+  BucketGetByIdOptions,
+  BucketGetByNameOptions,
+  BucketGetFilesOptions,
+  BucketFile,
+  BucketGetFileMetaDataWithPaginationOptions,
+  BucketGetFileMetaDataOptions,
+  BucketGetReadUriOptions,
+  BucketGetUriResponse,
+  BucketUploadFileOptions,
+  BucketUploadResponse,
+  BucketDeleteFileOptions,
+  BlobItem,
+} from '@uipath/uipath-typescript/buckets';
+
+// Processes
+import type {
+  ProcessGetResponse,
+  ProcessGetAllOptions,
+  ProcessGetByIdOptions,
+  ProcessGetByNameOptions,
+  ProcessStartRequest,
+  ProcessStartResponse,
+} from '@uipath/uipath-typescript/processes';
+
+// Jobs
+import type {
+  JobGetResponse,
+  JobGetAllOptions,
+  JobGetByIdOptions,
+  JobStopOptions,
+  JobResumeOptions,
+  JobMethods,
+} from '@uipath/uipath-typescript/jobs';
+
+// Attachments
+import type {
+  AttachmentResponse,
+  AttachmentGetByIdOptions,
+} from '@uipath/uipath-typescript/attachments';
+```
+
+## Enums
+
+```typescript
+// Assets
+import {
+  AssetValueScope,   // Global, PerRobot
+  AssetValueType,    // DBConnectionString, HttpConnectionString, Text, Bool, Integer, Credential, WindowsCredential, KeyValueList, Secret
+} from '@uipath/uipath-typescript/assets';
+
+// Buckets
+import {
+  BucketOptions,     // None, ReadOnly, AuditReadAccess, AccessDataThroughOrchestrator
+} from '@uipath/uipath-typescript/buckets';
+
+// Processes
+import {
+  PackageType,       // Undefined, Process, ProcessOrchestration, WebApp, Agent, TestAutomationProcess, Api, MCPServer, BusinessRules
+  JobPriority,       // Low, Normal, High
+  StartStrategy,     // All, Specific, RobotCount, JobsCount, ModernJobsCount
+  TargetFramework,   // Legacy, Windows, Portable
+  RobotSize,         // Small, Standard, Medium, Large
+  PackageSourceType, // Manual, Schedule, Queue, StudioWeb, ...
+  StopStrategy,      // SoftStop, Kill
+} from '@uipath/uipath-typescript/processes';
+```
+
+## Assets Service (Scopes: `OR.Assets` or `OR.Assets.Read`)
+
+### getAll(options?: AssetGetAllOptions)
+
+Returns `NonPaginatedResponse<AssetGetResponse>` or `PaginatedResponse<AssetGetResponse>`. Options extend `RequestOptions & PaginationOptions & { folderId?: number }`. Supports `filter`, `orderby`, `expand`, `select`.
+
+### getById(id: number, folderId: number, options?: AssetGetByIdOptions)
+
+Returns `Promise<AssetGetResponse>`. The `folderId` is required.
+
+### getByName(name: string, options: AssetGetByNameOptions)
+
+Returns `Promise<AssetGetResponse>`. Resolves an asset by display name within a folder. Supply one of `folderId` (number), `folderKey` (GUID string), or `folderPath` (e.g., `'Shared/Finance'`). Throws `NotFoundError` if no asset matches.
+
+```typescript
+await assets.getByName('ApiKey', { folderId: 123 });
+await assets.getByName('ApiKey', { folderKey: '5f6dadf1-3677-49dc-8aca-c2999dd4b3ba' });
+await assets.getByName('ApiKey', { folderPath: 'Shared/Finance', expand: 'keyValueList' });
+```
+
+`AssetGetResponse` fields: `key`, `name`, `id`, `canBeDeleted`, `valueScope`, `valueType`, `value`, `credentialStoreId`, `keyValueList`, `hasDefaultValue`, `description`, `foldersCount`, `lastModifiedTime`, `createdTime`, `creatorUserId`. **Note:** Additional fields may be available. Check the TypeScript types for the complete list.
+
+## Queues Service (Scopes: `OR.Queues` or `OR.Queues.Read`)
+
+### getAll(options?: QueueGetAllOptions)
+
+Returns `NonPaginatedResponse<QueueGetResponse>` or `PaginatedResponse<QueueGetResponse>`. Options extend `RequestOptions & PaginationOptions & { folderId?: number }`.
+
+### getById(id: number, folderId: number, options?: QueueGetByIdOptions)
+
+Returns `Promise<QueueGetResponse>`. The `folderId` is required.
+
+`QueueGetResponse` fields: `key`, `name`, `id`, `description`, `maxNumberOfRetries`, `acceptAutomaticallyRetry`, `retryAbandonedItems`, `enforceUniqueReference`, `encrypted`, `createdTime`, `slaInMinutes`, `riskSlaInMinutes`, `folderId`, `folderName`.
+
+## Buckets Service (Scopes: `OR.Buckets` or `OR.Buckets.Read`; `OR.Buckets.Write` for `deleteFile`)
+
+### getAll(options?: BucketGetAllOptions)
+
+Returns `NonPaginatedResponse<BucketGetResponse>` or `PaginatedResponse<BucketGetResponse>`. Options extend `RequestOptions & PaginationOptions & { folderId?: number }`.
+
+### getById(bucketId: number, folderId: number, options?: BucketGetByIdOptions)
+
+Returns `Promise<BucketGetResponse>`.
+
+`BucketGetResponse` fields: `id`, `name`, `description`, `identifier`, `storageProvider`, `storageContainer`, `options`, `foldersCount`.
+
+### getByName(name: string, options?: BucketGetByNameOptions)
+
+Returns `Promise<BucketGetResponse>`. Resolves a bucket by name within a folder. `BucketGetByNameOptions` is `FolderScopedOptions` — supply one of `folderId`, `folderKey`, or `folderPath` (same precedence as Assets/Processes) plus optional `expand` / `select`. Throws `NotFoundError` if no bucket matches.
+
+### getFiles(bucketId: number, options?: BucketGetFilesOptions)
+
+Returns `NonPaginatedResponse<BucketFile>` or `PaginatedResponse<BucketFile>`. Folder-scoped (`folderId` / `folderKey` / `folderPath`); supports regex filtering, query options, and pagination. Each `BucketFile` includes `isDirectory` so callers can distinguish folders from files. **Note:** Additional fields may be available — check the TypeScript types.
+
+> **`getFiles` vs `getFileMetaData`.** `getFiles` returns `BucketFile` items (folder-aware, supports regex filtering) and is folder-scoped via `FolderScopedOptions`. `getFileMetaData` returns flat `BlobItem` items by `prefix` and takes a positional `folderId`. Prefer `getFiles` for directory-style browsing.
+
+### getFileMetaData(bucketId: number, folderId: number, options?: BucketGetFileMetaDataWithPaginationOptions)
+
+Returns `NonPaginatedResponse<BlobItem>` or `PaginatedResponse<BlobItem>`. Options: `{ prefix?: string }` plus pagination. Each `BlobItem` has: `path`, `contentType`, `size`, `lastModified`.
+
+### uploadFile(options: BucketUploadFileOptions)
+
+Returns `Promise<BucketUploadResponse>` with `{ success, statusCode }`. Options: `{ bucketId, folderId, path, content: Blob | Uint8Array<ArrayBuffer> | File }`.
+
+### getReadUri(options: BucketGetReadUriOptions)
+
+Returns `Promise<BucketGetUriResponse>` with `{ uri, httpMethod, requiresAuth, headers }`. Options: `{ bucketId, folderId, path, expiryInMinutes? }`.
+
+### deleteFile(bucketId: number, path: string, options?: BucketDeleteFileOptions)
+
+Returns `Promise<void>`. Deletes a single file from the bucket by `path`. `BucketDeleteFileOptions` is folder-scoped (`folderId` / `folderKey` / `folderPath`). Requires `OR.Buckets` or `OR.Buckets.Write`.
+
+## Processes Service (Scopes: `OR.Execution` / `OR.Execution.Read`, `OR.Jobs` / `OR.Jobs.Write` for start)
+
+### getAll(options?: ProcessGetAllOptions)
+
+Returns `NonPaginatedResponse<ProcessGetResponse>` or `PaginatedResponse<ProcessGetResponse>`. Options extend `RequestOptions & PaginationOptions & { folderId?: number }`.
+
+### getById(id: number, folderId: number, options?: ProcessGetByIdOptions)
+
+Returns `Promise<ProcessGetResponse>`.
+
+### getByName(name: string, options: ProcessGetByNameOptions)
+
+Returns `Promise<ProcessGetResponse>`. Resolves a process release by name within a folder. Supply one of `folderId`, `folderKey`, or `folderPath`. Throws `NotFoundError` if no process matches.
+
+```typescript
+await processes.getByName('MyProcess', { folderPath: 'Shared/Finance', expand: 'entryPoints' });
+```
+
+`ProcessGetResponse` fields: `key`, `packageKey`, `packageVersion`, `isLatestVersion`, `description`, `name`, `packageType`, `targetFramework`, `robotSize`, `autoUpdate`, `id`, `folderId`, `folderName`, `folderKey`, `createdTime`, `lastModifiedTime`.
+
+### start(request: ProcessStartRequest, folderId: number, options?: RequestOptions)
+
+Returns `Promise<ProcessStartResponse[]>`. The `request` must include either `processKey` or `processName`. Optional fields: `strategy`, `robotIds`, `jobsCount`, `inputArguments`, `jobPriority`.
+
+`ProcessStartResponse` fields: `key`, `startTime`, `endTime`, `state`, `source`, `processName`, `type`, `id`, `folderId`.
+
+## Jobs Service (Scopes: `OR.Jobs` or `OR.Jobs.Read`)
+
+### getAll(options?: JobGetAllOptions)
+
+Returns `NonPaginatedResponse<JobGetResponse>` or `PaginatedResponse<JobGetResponse>`. Options extend `RequestOptions & PaginationOptions & { folderId?: number }`. Supports `filter`, `orderby`, `expand`, `select`.
+
+### getById(id: string, folderId: number, options?: JobGetByIdOptions)
+
+Returns `Promise<JobGetResponse>`. The `folderId` is required. **Note:** `id` is a `string` here (not a `number` like Assets/Queues/Processes).
+
+### getOutput(jobKey: string, folderId: number)
+
+Returns `Promise<Record<string, unknown> | null>` — the job's parsed output arguments, or `null` if unavailable. Use after a job has finished; output is not populated while the job is still running.
+
+### stop(jobKeys: string[], folderId: number, options?: JobStopOptions)
+
+Returns `Promise<void>`. Stops one or more jobs (pass an array even for a single job). Throws if any keys cannot be resolved. `JobStopOptions`: `{ strategy?: StopStrategy }` — `StopStrategy.SoftStop` (default, graceful) or `StopStrategy.Kill` (immediate).
+
+### resume(jobKey: string, folderId: number, options?: JobResumeOptions)
+
+Returns `Promise<void>`. Resumes a job currently in `Suspended` state. `JobResumeOptions`: `{ inputArguments?: Record<string, unknown> }`.
+
+### restart(jobKey: string, folderId: number)
+
+Returns `Promise<JobGetResponse>` — a **new** job with a new `key`, in `Pending` state. The original job must be in a final state (`Successful`, `Faulted`, or `Stopped`). Inputs are inherited from the original.
+
+`JobGetResponse` fields: `key`, `id`, `state`, `createdTime`, `startTime`, `endTime`, `lastModifiedTime`, `resumeTime`, `processName`, `entryPointPath`, `processVersionId`, `hostMachineName`, `inputArguments`, `outputArguments`, `environmentVariables`, `type`, `packageType`, `runtimeType`, `serverlessJobType`, `jobPriority`, `specificPriorityValue`, `stopStrategy`, `remoteControlAccess`, `batchExecutionKey`, `parentJobKey`, `traceId`, `parentSpanId`, `errorCode`, `jobError`, `subState`, `machine`, `robot`, `process`. The `machine`, `robot`, and `process` fields are populated only when requested via `expand`.
+
+## Job-Attached Methods (JobMethods)
+
+Returned by `getById()` and `getAll()` items on each `JobGetResponse`. These are bound to the job's `key` and `folderId`, so you don't need to pass them again:
+
+- `job.getOutput()` -> `Promise<Record<string, unknown> | null>`
+- `job.stop(options?)` -> `Promise<void>`
+- `job.resume(options?)` -> `Promise<void>`
+- `job.restart()` -> `Promise<JobGetResponse>` (new job)
+
+```typescript
+const all = await jobs.getAll({ folderId, pageSize: 20 });
+const running = all.items.find(j => j.state === 'Running');
+if (running) await running.stop();             // bound — no folderId needed
+const completed = all.items.find(j => j.state === 'Successful');
+if (completed) {
+  const output = await completed.getOutput();   // bound
+  const newJob = await completed.restart();     // bound
+}
+```
+
+## Attachments Service (Scopes: `OR.Folders` or `OR.Folders.Read`)
+
+Standalone service for retrieving Orchestrator attachment metadata and a signed URL for downloading the blob. `Jobs.getOutput()` uses this internally to resolve file-type output arguments — most app code will not need to call it directly, but if you call `Jobs.getOutput()` you must add `OR.Folders` (or `OR.Folders.Read`) to the app's scopes in addition to `OR.Jobs`.
+
+### getById(id: string, options?: AttachmentGetByIdOptions)
+
+Returns `Promise<AttachmentResponse>`. Options support OData `expand` / `select`.
+
+`AttachmentResponse` fields: `id`, `name`, `jobKey?`, `attachmentCategory?`, `lastModifiedTime?`, `lastModifierUserId?`, `createdTime?`, `creatorUserId?`, `blobFileAccess: BucketGetUriResponse` (the signed URL + headers — `{ uri, httpMethod, requiresAuth, headers }`).
+
+```typescript
+import { Attachments } from '@uipath/uipath-typescript/attachments';
+
+const attachments = new Attachments(sdk);
+const attachment = await attachments.getById('<attachmentId>');
+// Download the blob using the signed URI
+const blob = await fetch(attachment.blobFileAccess.uri).then(r => r.blob());
+```
+
+## Bridging folderKey ↔ folderId
+
+Maestro services return `folderKey` (GUID string), but Orchestrator services like `Processes.start()` require `folderId` (number). These are **completely different identifiers** — `parseInt(folderKey)` gives `NaN`.
+
+**NEVER do this:**
+```typescript
+// WRONG — folderKey is a GUID like "a1b2c3d4-e5f6-...", parseInt returns NaN
+const folderId = parseInt(process.folderKey, 10);
+await processes.start(request, folderId);
+```
+
+**Correct pattern — resolve folderId from Orchestrator:**
+
+```typescript
+import { Processes } from '@uipath/uipath-typescript/processes';
+import { MaestroProcesses } from '@uipath/uipath-typescript/maestro-processes';
+
+// 1. Get the Maestro process (has folderKey and processKey, but no folderId)
+const maestro = new MaestroProcesses(sdk);
+const maestroProcesses = await maestro.getAll();
+const target = maestroProcesses.find(p => p.name === 'My Process');
+// target.folderKey = "a1b2c3d4-e5f6-..." (GUID)
+// target.processKey = the Orchestrator release key (use for Processes.start())
+// target.packageId = the NuGet package identifier (NOT the processKey!)
+
+// 2. Get Orchestrator processes to find the matching folderId
+const processes = new Processes(sdk);
+const orchResult = await processes.getAll();
+// ProcessGetResponse has BOTH folderKey and folderId
+const orchProcess = orchResult.items.find(p => p.folderKey === target.folderKey);
+const folderId = orchProcess?.folderId;
+
+// 3. Now start the process with the correct fields:
+//    - processKey comes from MaestroProcess.processKey (NOT packageId!)
+//    - folderId comes from the Orchestrator bridge above
+if (folderId) {
+  await processes.start({ processKey: target.processKey }, folderId);
+}
+```
+
+**Cache the mapping:** If your app frequently bridges between Maestro and Orchestrator, resolve the `folderKey → folderId` mapping once on load and cache it in a `Map<string, number>` or React state. Don't re-query on every operation.
+
+```typescript
+// Build a folderKey → folderId lookup map (do once)
+const orchProcesses = await processes.getAll();
+const folderMap = new Map<string, number>();
+for (const p of orchProcesses.items) {
+  if (p.folderKey && p.folderId) {
+    folderMap.set(p.folderKey, p.folderId);
+  }
+}
+// Use: folderMap.get(maestroProcess.folderKey) → folderId
+```
+
+## Usage Example
+
+```typescript
+import { useMemo } from 'react';
+import { useAuth } from '../hooks/useAuth';
+import { Assets } from '@uipath/uipath-typescript/assets';
+import { Processes } from '@uipath/uipath-typescript/processes';
+import type { ProcessStartRequest } from '@uipath/uipath-typescript/processes';
+
+function OrchestratorActions({ folderId }: { folderId: number }) {
+  const { sdk } = useAuth();
+  const assets = useMemo(() => new Assets(sdk), [sdk]);
+  const processes = useMemo(() => new Processes(sdk), [sdk]);
+
+  const listAssets = async () => {
+    const result = await assets.getAll({ folderId, pageSize: 10 });
+    return result.items;
+  };
+
+  const startProcess = async (processKey: string) => {
+    const request: ProcessStartRequest = { processKey };
+    const jobs = await processes.start(request, folderId);
+    return jobs;
+  };
+}
+```

package/skills/uipath-coded-apps/references/sdk/pagination.md

@@ -0,0 +1,84 @@
+# Pagination Reference
+
+> **Foot-gun: every "list" call returns ONE page, even when you pass no pagination options.** `getAll`, `getAllRecords`, `queryRecordsById`, `getFileMetaData`, etc. all make exactly one HTTP call. Whether the response is typed as `PaginatedResponse` or `NonPaginatedResponse` is purely about whether you passed pagination options — it does NOT control how many rows you get back.
+>
+> - `getAll()` (no options) → `NonPaginatedResponse` → SDK sends no `pageSize` param; the **server** applies its own default cap and returns one page. You can't override it client-side without explicitly paginating. Despite the name, `NonPaginatedResponse` is NOT "all rows in one shot."
+> - `getAll({ pageSize: 200 })` → `PaginatedResponse` → API returns up to 200, plus `hasNextPage` / `nextCursor`.
+>
+> **There is no "give me everything" call.** To list every row from a source that may have more than the cap, you MUST loop the cursor:
+>
+> ```typescript
+> const all: T[] = [];
+> let cursor: PaginationCursor | undefined;
+> while (true) {
+>   const page = await service.getAll(cursor ? { pageSize: 100, cursor } : { pageSize: 100 });
+>   all.push(...page.items);
+>   if (!page.hasNextPage || !page.nextCursor) break;
+>   cursor = page.nextCursor;
+> }
+> ```
+>
+> Code that does `result.items.length` after a single call is almost always a bug — it returns at most the page size, not the total. Use `totalCount` for cardinality, the cursor loop for full retrieval. If the source has fewer rows than the default cap (e.g., 30 of a 100-cap), a single call works but you cannot rely on that as data grows.
+
+## Imports
+
+Import pagination types from `@uipath/uipath-typescript/core`:
+
+```typescript
+import type {
+  PaginationCursor,
+  PaginationOptions,
+  PaginatedResponse,
+  NonPaginatedResponse,
+} from '@uipath/uipath-typescript/core';
+```
+
+- `PaginationCursor`: `{ value: string }` — an opaque cursor object. Pass it to `cursor` in pagination options.
+- `PaginationOptions`: `{ pageSize?, cursor?, jumpToPage? }` (cursor and jumpToPage are mutually exclusive)
+- `PaginatedResponse<T>`: `{ items, hasNextPage, nextCursor?, previousCursor?, totalCount?, currentPage?, totalPages?, supportsPageJump }`
+- `NonPaginatedResponse<T>`: `{ items, totalCount? }`
+
+## Behavior
+
+- No pagination options passed → returns `NonPaginatedResponse<T>` (response wrapper has no pagination metadata; data is still capped at the **server's** default page limit, applied on the API side because the SDK sends no `pageSize`; see foot-gun above).
+- Any pagination option passed (pageSize, cursor, or jumpToPage) → returns `PaginatedResponse<T>` with `hasNextPage`/`nextCursor` for cursor-loop retrieval.
+
+## Cursor Navigation
+
+```typescript
+// First page
+const page1 = await service.getAll({ pageSize: 10 });
+
+// Next page using cursor
+if (page1.hasNextPage && page1.nextCursor) {
+  const page2 = await service.getAll({ cursor: page1.nextCursor });
+}
+
+// Jump to page (only for offset-based services: Assets, Queues, Tasks, Entities)
+const page5 = await service.getAll({ jumpToPage: 5, pageSize: 10 });
+```
+
+## Type Narrowing
+
+TypeScript narrows the return type at compile-time based on whether pagination options are passed. At runtime, use `'hasNextPage' in result` to discriminate — this field exists only on `PaginatedResponse`, never on `NonPaginatedResponse`.
+
+```typescript
+import type { PaginatedResponse } from '@uipath/uipath-typescript/core';
+
+// Pattern 1: When you always pass pagination options, assert the type
+const result = await tasks.getAll({ pageSize: 10 });
+// TypeScript already infers PaginatedResponse here, but if using dynamic options:
+const paginated = result as PaginatedResponse<TaskGetResponse>;
+
+// Pattern 2: When options are dynamic and you don't know the return type
+const result = await tasks.getAll(options);
+if ('hasNextPage' in result) {
+  // PaginatedResponse — safe to access nextCursor, supportsPageJump, etc.
+  if (result.hasNextPage && result.nextCursor) {
+    const nextPage = await tasks.getAll({ cursor: result.nextCursor });
+  }
+} else {
+  // NonPaginatedResponse — only has items and totalCount
+  console.log(`All ${result.items.length} items returned`);
+}
+```