@uipath/skills 1.199.0 → 1.200.0

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

@@ -1,44 +1,65 @@
-# SDK Module Imports
-
-Read this when writing TypeScript code that imports classes, types, or options from `@uipath/uipath-typescript`. The SDK uses subpath exports — service classes are **not** importable from the package root.
-
-## Subpath → Exports
-
-| Subpath | Classes |
-|---------|---------|
-| `@uipath/uipath-typescript/core` | `UiPath`, `UiPathError`, `UiPathSDKConfig`, `PaginationCursor`, `PaginationOptions`, `PaginatedResponse`, `NonPaginatedResponse` |
-| `@uipath/uipath-typescript/entities` | `Entities`, `ChoiceSets` |
-| `@uipath/uipath-typescript/tasks` | `Tasks` |
-| `@uipath/uipath-typescript/maestro-processes` | `MaestroProcesses`, `ProcessInstances`, `ProcessIncidents` |
-| `@uipath/uipath-typescript/cases` | `Cases`, `CaseInstances` |
-| `@uipath/uipath-typescript/assets` | `Assets` |
-| `@uipath/uipath-typescript/queues` | `Queues` |
-| `@uipath/uipath-typescript/buckets` | `Buckets` |
-| `@uipath/uipath-typescript/processes` | `Processes` |
-| `@uipath/uipath-typescript/jobs` | `Jobs` |
-| `@uipath/uipath-typescript/attachments` | `Attachments` |
-| `@uipath/uipath-typescript/agents` | `Agents`, `AgentListSortColumn`, `AgentErrorSortColumn` (Insights RTM — SDK ≥ 1.4.1) |
-| `@uipath/uipath-typescript/traces` | `AgentTraces`, `AgentTraceExecutionType`, `Traces` (generic spans — `Traces.getById(traceId)`) (Insights RTM — SDK ≥ 1.4.1) |
-| `@uipath/uipath-typescript/agent-memory` | `AgentMemory`, `AgentMemoryExecutionType` (SDK ≥ 1.4.1) |
-| `@uipath/uipath-typescript/governance` | `Governance`, `PolicyEvaluationResult` (SDK ≥ 1.4.1) |
-| `@uipath/uipath-typescript/conversational-agent` | `ConversationalAgent`, `Exchanges`, `Messages` |
-| `@uipath/uipath-typescript/feedback` | `Feedback` |
-
-## Type Imports
-
-Types, enums, and option interfaces are exported from the **same subpath** as their service class. Use `import type` for type-only imports:
+# SDK Reference Protocol
 
-```typescript
-import type { AssetGetResponse } from '@uipath/uipath-typescript/assets';
-import type { ProcessInstanceGetResponse } from '@uipath/uipath-typescript/maestro-processes';
-import type { UiPathSDKConfig } from '@uipath/uipath-typescript/core';
-```
+The installed package is the authoritative reference for the `@uipath/uipath-typescript` SDK. This folder's files contain ONLY knowledge the package cannot carry; everything else is read from `node_modules`.
+
+## Where to look things up
+
+| Need | Source (inside `node_modules/@uipath/uipath-typescript/`) |
+|---|---|
+| Which subpaths exist | `ls dist/` — every directory is an import subpath: `@uipath/uipath-typescript/<dir>` |
+| Which subpath exports a class | `grep -l "class <Name>" dist/*/index.d.ts` |
+| Method signatures, params, return types, usage examples | `dist/<subpath>/index.d.ts` — full JSDoc, matches the installed version exactly (call only members NOT tagged `@internal` — see rule 5) |
+| Per-method OAuth scopes | `docs/oauth-scopes.md` (shipped with newer SDK versions; fallback: [../oauth-scopes.md](../oauth-scopes.md) § Per-method scope lookup) |
+| Types, enums, option interfaces | same `dist/<subpath>/index.d.ts` as their service class — use `import type` for type-only imports |
+| Version a capability was introduced in (when it is **absent** from the installed types) | `release-metadata.json` — see *When a capability is missing from the installed types* below |
+
+Rules:
+
+1. Before calling a service you have not used in this session, Read its `dist/<subpath>/index.d.ts`.
+2. If `node_modules` is absent, run the install step first (the app cannot build without it — see the scaffold workflow).
+3. NEVER guess or recall method names, signatures, or scopes from memory — SDK versions differ; the installed package is the contract.
+4. Task-level scope **bundles** and widget scopes: [../oauth-scopes.md](../oauth-scopes.md). Cross-service traps and server-side behavior the types cannot express: the per-domain files in this folder.
+5. **Call only methods that are NOT tagged `@internal`.** The shipped `.d.ts` includes members whose JSDoc carries an `@internal` tag — these are not a supported API and may change or disappear without notice. Ignore them when picking a method. This restricts *calling* `@internal` **methods**; referencing an `@internal` **type** that a public method's signature already exposes is unavoidable and fine.
+6. If a capability you expect is **absent** from the installed `.d.ts`, do not conclude it is impossible or invent it — resolve the required SDK version via *When a capability is missing from the installed types* below.
+
+## When a capability is missing from the installed types
+
+A subpath, service class, or method you need is not in the installed `.d.ts`. It may require a newer SDK. Resolve the version to upgrade to from **`release-metadata.json`** — a map the SDK ships of every public capability → the version each was introduced in:
+
+- Installed copy: `node_modules/@uipath/uipath-typescript/release-metadata.json` (matches the installed version).
+- Latest copy: `https://unpkg.com/@uipath/uipath-typescript@latest/release-metadata.json` (needed to see capabilities newer than what is installed).
+
+Find the service by `name` in the `services` array, then the method by `name` in that service's `methods`. **Every public service and method is listed**, so absence from the file means it does not exist — there is no inheritance to apply. Then:
+
+1. **Present in the installed `.d.ts`** → use it (you are not in this flow).
+2. **In the file with a `since` version `V`** (and no `deleted`), absent locally → tell the user: *"`<capability>` requires `@uipath/uipath-typescript` ≥ `V`; installed is `<version>` — upgrade to use it."*
+3. **`since: null`** → baseline (shipped before tracking; present in every tracked version); absence locally means the install is older than tracking or corrupt — advise reinstall / upgrade to latest.
+4. **Entry has `deleted` = `D`** → the capability was removed in `D`. Tell the user it is gone as of `D` and to use `replacedBy` if present; do not try to call it. (No entry sets `deleted` today.)
+5. **Absent from the latest file entirely** → the capability does not exist in the SDK. Do not fabricate it; route to the correct skill or tell the user it is unavailable.
+6. **Cannot fetch the latest copy (offline / no network)** → read the installed `release-metadata.json`; if it also lacks the capability, tell the user it is not in their installed SDK and may need a newer version — point them to the changelog or `npm view @uipath/uipath-typescript`.
+
+Name the exact `since` when the file has it; never silently build a lesser version or guess a number.
+
+## Version history (frozen)
+
+<!-- FROZEN: historical "requires SDK >= x.y.z" minimums, snapshot at the release-metadata.json cutover. Do NOT add NEW version gates here — from now on a capability's introduction version lives ONLY in the SDK's release-metadata.json (resolved via the fallback above). This table is a frozen convenience for pre-cutover minimums; release-metadata.json is authoritative. -->
+
+Pre-cutover minimums (authoritative source: `release-metadata.json`):
+
+| Capability | Min SDK |
+|---|---|
+| `agents`, `agent-memory`, `traces`, `governance` subpaths (Insights RTM) | 1.4.1 |
+| Agents Insights aggregates — `getSummary`, `getTopErrorCount`, `getTopConsumption`, `getIncidentDistribution`, `getUnitConsumptionSummary` | 1.5.0 |
+| AgentTraces governance — `getGovernanceDecisions`, `getGovernanceSummary` | 1.5.1 |
+| `EntityFieldDataType.MULTILINE_MAX` | 1.5.2 |
+| Maestro analytics on `MaestroProcesses` / `Cases` — `getTop*`, `getInstanceStatusTimeline`, `getElementStats`, `getInstanceStats`, `getIncidentsTimeline` | 1.3.9 to 1.5.1 by method — see `release-metadata.json` |
+| `Notifications` service | 1.5.1 |
 
 ## Anti-patterns
 
 ### Never import service classes from the package root
 
-Service classes are only available via subpath imports. Root-level imports will fail at build time.
+Service classes are only available via subpath imports. Root-level imports fail at build time.
 
 ```typescript
 // ❌ Wrong — service classes are not exported from the root
@@ -60,3 +81,24 @@ const items = await sdk.entities.getAll();
 const entities = new Entities(sdk);
 const items = await entities.getAll();
 ```
+
+### Never call methods tagged `@internal`
+
+The SDK does not strip `@internal` from its published types, so `@internal` methods are visible in `dist/<subpath>/index.d.ts` right alongside the public ones. They are internal plumbing — unsupported, undocumented, and subject to change without a version bump. A method being *readable* in the `.d.ts` does not make it callable API.
+
+```typescript
+// A method whose JSDoc carries an @internal tag:
+/**
+ * ...
+ * @internal
+ */
+someInternalMethod(...)
+
+// ❌ Wrong — it is in the types, but @internal means "not for you"
+await service.someInternalMethod(...);
+
+// ✓ Correct — use the public method that does the job
+await service.getAll(...);
+```
+
+Referencing an `@internal` **type** in a signature you cannot avoid (e.g. a public method returns one) is fine — the rule is about not **calling** `@internal` **methods**.

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

@@ -1,437 +1,60 @@
-# Maestro Reference
+# Maestro — Traps & Server Behavior
 
-## Imports
+Signatures/params/examples: `dist/maestro-processes/index.d.ts`, `dist/cases/index.d.ts`. Per-method scopes: shipped `docs/oauth-scopes.md`. This file covers only what neither can express.
 
-```typescript
-import { MaestroProcesses, ProcessInstances, ProcessIncidents } from '@uipath/uipath-typescript/maestro-processes';
-import { Cases, CaseInstances } from '@uipath/uipath-typescript/cases';
-```
-
-## Scopes
-
-- All Maestro operations: `PIMS`
-- ProcessInstances.getBpmn: also requires `OR.Execution.Read`
-- CaseInstances.getActionTasks: also requires `OR.Tasks` or `OR.Tasks.Read`
-
-## Types to Import
-
-```typescript
-// Maestro Processes
-import type {
-  MaestroProcessGetAllResponse,
-  RawMaestroProcessGetAllResponse,
-  ProcessMethods,
-} from '@uipath/uipath-typescript/maestro-processes';
-
-// Process Instances
-import type {
-  ProcessInstanceGetResponse,
-  RawProcessInstanceGetResponse,
-  ProcessInstanceMethods,
-  ProcessInstanceGetAllWithPaginationOptions,
-  ProcessInstanceGetAllOptions,
-  ProcessInstanceOperationOptions,
-  ProcessInstanceOperationResponse,
-  ProcessInstanceExecutionHistoryResponse,
-  BpmnXmlString,
-  ProcessInstanceGetVariablesResponse,
-  ProcessInstanceGetVariablesOptions,
-  ProcessInstanceRun,
-} from '@uipath/uipath-typescript/maestro-processes';
-
-// Process Incidents
-import type {
-  ProcessIncidentGetResponse,
-  ProcessIncidentGetAllResponse,
-} from '@uipath/uipath-typescript/maestro-processes';
-
-// Analytics / Insights (MaestroProcesses + Cases)
-import type {
-  TimelineOptions,
-  TopQueryOptions,
-  InstanceStatusTimelineResponse,
-  ProcessGetTopRunCountResponse,
-  ProcessGetTopFaultedCountResponse,
-  ProcessGetTopDurationResponse,
-} from '@uipath/uipath-typescript/maestro-processes';
-
-// Cases
-import type {
-  CaseGetAllResponse,
-  CaseGetTopRunCountResponse,
-  CaseGetTopFaultedCountResponse,
-  CaseGetTopDurationResponse,
-} from '@uipath/uipath-typescript/cases';
-
-// Case Instances
-import type {
-  CaseInstanceGetResponse,
-  RawCaseInstanceGetResponse,
-  CaseInstanceMethods,
-  CaseInstanceGetAllWithPaginationOptions,
-  CaseInstanceGetAllOptions,
-  CaseInstanceOperationOptions,
-  CaseInstanceOperationResponse,
-  CaseInstanceReopenOptions,
-  CaseGetStageResponse,
-  CaseInstanceExecutionHistoryResponse,
-  StageTask,
-  SlaSummaryResponse,
-  CaseInstanceStageSLAOptions,
-  CaseInstanceStageSLAResponse,
-} from '@uipath/uipath-typescript/cases';
-```
-
-## Enums
-
-```typescript
-import {
-  ProcessIncidentStatus,    // Open, Closed
-  ProcessIncidentType,      // System, User, Deployment
-  ProcessIncidentSeverity,  // Error, Warning
-  DebugMode,                // None, Default, StepByStep, SingleStep
-  TimeInterval,             // Hour = 'HOUR', Day = 'DAY', Week = 'WEEK' (analytics time-axis grouping)
-  InstanceFinalStatus,      // status value in getInstanceStatusTimeline() entries
-} from '@uipath/uipath-typescript/maestro-processes';
+> **Scope fork warning:** this service family splits across TWO scope bundles — instance/process operations use `PIMS`, while the analytics/SLA methods use the Insights bundle (`Insights Insights.RealTimeData OR.Folders.Read`; SLA also needs `PIMS`). Do not assume service-uniform scopes; check the shipped table per method. A 403 on analytics means the External App lacks the Insights bundle — surface it as a permissions message.
 
-import {
-  StageTaskType,               // external-agent, rpa, process, agent, action, api-workflow
-  EscalationRecipientScope,    // user, usergroup
-  EscalationActionType,        // notification
-  EscalationTriggerType,       // sla-breached, at-risk
-  SLADurationUnit,             // h, d, w, m
-} from '@uipath/uipath-typescript/cases';
-```
-
-## MaestroProcesses Service
+## Traps
 
-### getAll()
+### `folderKey` is a GUID, not a `folderId`
 
-Returns `Promise<MaestroProcessGetAllResponse[]>`. Each process has: `processKey`, `packageId`, `name`, `folderKey`, `folderName`, `packageVersions`, `versionCount`, plus instance count fields (`runningCount`, `faultedCount`, `completedCount`, `pausedCount`, `cancelledCount`, `pendingCount`, `retryingCount`, `resumingCount`, `pausingCount`, `cancelingCount`). Each process has an attached `getIncidents()` method.
+Maestro responses include `folderKey` (GUID string) but NOT `folderId` (number). If you need an Orchestrator method that requires `folderId` (e.g., `Processes.start()`), bridge via `Processes.getAll()` — see "Bridging folderKey ↔ folderId" in [orchestrator.md](orchestrator.md). **NEVER use `parseInt(folderKey)`** — it returns `NaN`.
 
-**NOTE:** Maestro responses include `folderKey` (GUID string) but NOT `folderId` (number). If you need to call an Orchestrator method that requires `folderId` (e.g., `Processes.start()`), you must bridge using `Processes.getAll()` — see "Bridging folderKey ↔ folderId" in [orchestrator.md](orchestrator.md). **NEVER use `parseInt(folderKey)`** — it returns `NaN`.
+### `name` is NOT `processKey`
 
-**CRITICAL — `name` is NOT `processKey`:** The human-readable process name (e.g., `"Loan.Origination.and.Review"`) is the `name` field. The `processKey` is a separate internal identifier (e.g., `"a1b2c3d4-..."`). When the user provides a process name, you MUST first call `MaestroProcesses.getAll()`, find the process where `name` matches, then extract its `processKey` and `folderKey` to use in subsequent calls like `ProcessInstances.getAll({ processKey })`. **NEVER use the process name as the processKey.**
+The human-readable process name (e.g., `"Loan.Origination.and.Review"`) is the `name` field. The `processKey` is a separate internal identifier. When the user provides a process name, first call `MaestroProcesses.getAll()`, find the process where `name` matches, then use its `processKey` and `folderKey`:
 
 ```typescript
-const maestroProcesses = new MaestroProcesses(sdk);
-const allProcesses = await maestroProcesses.getAll();
+const allProcesses = await new MaestroProcesses(sdk).getAll();
 const target = allProcesses.find(p => p.name === 'Loan.Origination.and.Review');
 if (!target) throw new Error('Process not found');
-// Now use target.processKey and target.folderKey for instance queries
 const instances = await processInstances.getAll({ processKey: target.processKey, pageSize: 20 });
 ```
 
-### getIncidents(processKey: string, folderKey: string)
-
-Returns `Promise<ProcessIncidentGetResponse[]>`. Each incident has: `instanceId`, `elementId`, `folderKey`, `processKey`, `incidentId`, `incidentStatus`, `incidentType`, `errorCode`, `errorMessage`, `errorTime`, `errorDetails`, `debugMode`, `incidentSeverity`, `incidentElementActivityType`, `incidentElementActivityName`.
-
-### Analytics / Insights methods
-
-Tenant-wide, time-ranged aggregates for dashboards. **All require `Insights.RealTimeData Insights OR.Folders.Read` scope** (not `PIMS`) — a separate scope bundle from the rest of Maestro. `startTime`/`endTime` are `Date` objects. Use these instead of fetching raw instances and aggregating client-side (which only sees one page — see [pagination.md](pagination.md)).
-
-#### getInstanceStatusTimeline(startTime: Date, endTime: Date, options?: TimelineOptions)
-
-Returns `Promise<InstanceStatusTimelineResponse[]>` — instance counts bucketed across the time axis. `TimelineOptions` supports `groupBy` and a `TimeInterval` (`Hour` / `Day` / `Week`) controlling bucket size. Use for "instances over time" charts. Each entry: `startTime: string` (bucket start, local tz, e.g. `"5/8/2026 12:00:00 AM"`), `status: InstanceFinalStatus`, `count: number`.
-
-#### getTopRunCount(startTime: Date, endTime: Date, options?: TopQueryOptions)
+**NEVER use the process name as the processKey.**
 
-Returns `Promise<ProcessGetTopRunCountResponse[]>` — processes ranked by run count. `TopQueryOptions` supports optional filters `packageId`, `processKey`, `version`. Each entry: `name: string`, `packageId: string`, `processKey: string`, `runCount: number`.
+### `reopen()` — where the required `stageId` comes from
 
-#### getTopFaultedCount(startTime: Date, endTime: Date, options?: TopQueryOptions)
-
-Returns `Promise<ProcessGetTopFaultedCountResponse[]>` — processes ranked by faulted-instance count. Each entry: `name`, `packageId`, `processKey`, `faultedCount: number`.
-
-#### getTopExecutionDuration(startTime: Date, endTime: Date, options?: TopQueryOptions)
-
-Returns `Promise<ProcessGetTopDurationResponse[]>` — processes ranked by execution duration. Each entry: `name`, `packageId`, `processKey`, `duration: number`.
-
-```typescript
-import { MaestroProcesses, TimeInterval } from '@uipath/uipath-typescript/maestro-processes';
-
-const maestro = new MaestroProcesses(sdk);
-const end = new Date();
-const start = new Date(end.getTime() - 7 * 24 * 60 * 60 * 1000); // last 7 days
-
-const timeline = await maestro.getInstanceStatusTimeline(start, end, { groupBy: TimeInterval.Day });
-const busiest = await maestro.getTopRunCount(start, end);
-const flakiest = await maestro.getTopFaultedCount(start, end);
-const slowest = await maestro.getTopExecutionDuration(start, end);
-```
+Get it from `getStages()` on the case instance.
 
-## Process-Attached Methods (ProcessMethods)
+### Rendering `getVariables()` output — MANDATORY
 
-Returned by `getAll()` on each `MaestroProcessGetAllResponse`:
+See [../patterns.md](../patterns.md) section "Rendering Process Instance Data". **NEVER dump raw JSON** — parse `globalVariables` / `elements` and render structured UI.
 
-- `process.getIncidents()` -> `Promise<ProcessIncidentGetResponse[]>`
-
-## ProcessIncidents Service
-
-Standalone service exported from `@uipath/uipath-typescript/maestro-processes` (same subpath as `MaestroProcesses` and `ProcessInstances`). Use it when you need incidents across **all folders** without first resolving a specific `processKey` or `instanceId`.
-
-### getAll()
-
-Returns `Promise<ProcessIncidentGetAllResponse[]>`. Each summary has aggregated fields like `processKey`, `errorMessage`, `count`, `firstOccuranceTime`.
-
-```typescript
-import { ProcessIncidents } from '@uipath/uipath-typescript/maestro-processes';
-
-const processIncidents = new ProcessIncidents(sdk);
-const incidents = await processIncidents.getAll();
-for (const incident of incidents) {
-  console.log(`${incident.processKey}: ${incident.errorMessage} (count: ${incident.count})`);
-}
-```
-
-### When to use which incident accessor
+## Which incident accessor when
 
 | Scope | Use |
 |---|---|
 | All incidents across all folders (summary rollup) | `new ProcessIncidents(sdk).getAll()` — returns `ProcessIncidentGetAllResponse[]` |
-| All incidents for one process | `MaestroProcesses.getIncidents(processKey, folderKey)` or `process.getIncidents()` — returns `ProcessIncidentGetResponse[]` |
-| Incidents on a single instance | `ProcessInstances.getIncidents(instanceId, folderKey)` or `instance.getIncidents()` — returns `ProcessIncidentGetResponse[]` |
-
-Note that `ProcessIncidentGetAllResponse` (summary) and `ProcessIncidentGetResponse` (per-incident detail) are different shapes.
-
-## ProcessInstanceGetResponse Fields
-
-`instanceId: string`, `packageKey: string`, `packageId: string`, `packageVersion: string`, `latestRunId: string`, `latestRunStatus: string`, `processKey: string`, `folderKey: string`, `userId: number`, `instanceDisplayName: string`, `startedByUser: string`, `source: string`, `creatorUserKey: string`, `startedTime: string`, `completedTime: string | null`, `instanceRuns: ProcessInstanceRun[]`. Plus all `ProcessInstanceMethods`.
-
-## ProcessInstances Service
-
-### getAll(options?: ProcessInstanceGetAllWithPaginationOptions)
-
-Returns `NonPaginatedResponse<ProcessInstanceGetResponse>` or `PaginatedResponse<ProcessInstanceGetResponse>`. Token-based pagination. Filter options: `processKey`, `packageId`, `packageVersion`, `errorCode`.
-
-### getById(id: string, folderKey: string)
-
-Returns `Promise<ProcessInstanceGetResponse>` with attached methods.
-
-### cancel(instanceId: string, folderKey: string, options?: ProcessInstanceOperationOptions)
-
-Returns `Promise<OperationResponse<ProcessInstanceOperationResponse>>`. Options: `{ comment?: string }`.
-
-### pause(instanceId: string, folderKey: string, options?: ProcessInstanceOperationOptions)
-
-Same signature and return type as cancel.
-
-### resume(instanceId: string, folderKey: string, options?: ProcessInstanceOperationOptions)
-
-Same signature and return type as cancel.
-
-### getExecutionHistory(instanceId: string)
-
-Returns `Promise<ProcessInstanceExecutionHistoryResponse[]>`. Each span has: `id`, `traceId`, `parentId`, `name`, `startedTime`, `endTime`, `attributes`, `createdTime`, `updatedTime?`, `expiredTime`.
-
-### getBpmn(instanceId: string, folderKey: string)
-
-Returns `Promise<BpmnXmlString>` (a string of BPMN XML).
-
-### getVariables(instanceId: string, folderKey: string, options?: ProcessInstanceGetVariablesOptions)
-
-Returns `Promise<ProcessInstanceGetVariablesResponse>` with `{ elements, globalVariables, instanceId, parentElementId }`. Options: `{ parentElementId?: string }`.
-
-**Response structure:**
-
-- `globalVariables: GlobalVariableMetaData[]` — Named variables with types. Each has:
-  - `id: string` — unique identifier
-  - `name: string` — human-readable variable name (e.g., `"loanAmount"`, `"applicantName"`)
-  - `type: string` — value type (`"integer"`, `"string"`, `"boolean"`, or custom types)
-  - `value: any` — the current value (can be primitive, object, or array)
-  - `source: string` — name of the BPMN element that set/owns this variable
-  - `elementId: string` — BPMN element ID
-- `elements: ElementMetaData[]` — Per-element execution data (activity steps). Each has:
-  - `elementId: string` — BPMN element ID (e.g., `"Activity_XYRXSH"`)
-  - `elementRunId: string` — unique run identifier
-  - `isMarker: boolean` — whether this is a marker element
-  - `inputs: Record<string, any>` — input arguments passed to the element (can be deeply nested objects)
-  - `inputDefinitions: Record<string, any>` — schema/definitions for inputs
-  - `outputs: Record<string, any>` — output values produced by the element (can be deeply nested objects)
-
-**UI rendering — MANDATORY:** See [../patterns.md](../patterns.md) section "Rendering Process Instance Data" for how to display variables and element data properly. **NEVER dump raw JSON** — always parse and render structured UI.
-
-### getIncidents(instanceId: string, folderKey: string)
-
-Returns `Promise<ProcessIncidentGetResponse[]>`.
-
-## ProcessInstance-Attached Methods (ProcessInstanceMethods)
-
-Returned by `getAll()` and `getById()` on each `ProcessInstanceGetResponse`:
-
-- `instance.cancel(options?)` -> `Promise<OperationResponse<ProcessInstanceOperationResponse>>`
-- `instance.pause(options?)` -> `Promise<OperationResponse<ProcessInstanceOperationResponse>>`
-- `instance.resume(options?)` -> `Promise<OperationResponse<ProcessInstanceOperationResponse>>`
-- `instance.getIncidents()` -> `Promise<ProcessIncidentGetResponse[]>`
-- `instance.getExecutionHistory()` -> `Promise<ProcessInstanceExecutionHistoryResponse[]>`
-- `instance.getBpmn()` -> `Promise<BpmnXmlString>`
-- `instance.getVariables(options?)` -> `Promise<ProcessInstanceGetVariablesResponse>`
-
-## Cases Service
-
-### getAll()
-
-Returns `Promise<CaseGetAllResponse[]>`. Each case has: `processKey`, `packageId`, `name`, `folderKey`, `folderName`, `packageVersions`, `versionCount`, plus instance count fields (same as MaestroProcesses).
-
-**Example response** — a **bare top-level array** (no `.items` wrapper):
-
-```json
-[
-  {
-    "name": "Loan Processing", "processKey": "case-proc-uuid",
-    "folderKey": "f-1001", "folderName": "Lending", "versionCount": 2,
-    "pendingCount": 5, "runningCount": 3, "completedCount": 125,
-    "faultedCount": 1, "pausedCount": 0, "cancelledCount": 2
-  }
-]
-```
-
-> **Semantics:** same shape as `MaestroProcesses.getAll` — bare array, counts pre-aggregated per case process. Chart `runningCount` / `completedCount` / `faultedCount` directly.
-
-### Analytics / Insights methods
-
-Same signatures and scope as the MaestroProcesses analytics methods above (`Insights.RealTimeData Insights OR.Folders.Read`), but scoped to cases:
-
-- `getInstanceStatusTimeline(startTime: Date, endTime: Date, options?: TimelineOptions)` → `Promise<InstanceStatusTimelineResponse[]>`
-- `getTopRunCount(startTime: Date, endTime: Date, options?: TopQueryOptions)` → `Promise<CaseGetTopRunCountResponse[]>`
-- `getTopFaultedCount(startTime: Date, endTime: Date, options?: TopQueryOptions)` → `Promise<CaseGetTopFaultedCountResponse[]>`
-- `getTopExecutionDuration(startTime: Date, endTime: Date, options?: TopQueryOptions)` → `Promise<CaseGetTopDurationResponse[]>`
-
-## CaseInstanceGetResponse Fields
-
-`instanceId: string`, `packageKey: string`, `packageId: string`, `packageVersion: string`, `latestRunId: string`, `latestRunStatus: string`, `processKey: string`, `folderKey: string`, `userId: number`, `instanceDisplayName: string`, `startedByUser: string`, `source: string`, `creatorUserKey: string`, `startedTime: string`, `completedTime: string`, `instanceRuns: CaseInstanceRun[]`, `caseAppConfig?: CaseAppConfig`, `caseType?: string`, `caseTitle?: string`. Plus all `CaseInstanceMethods`.
-
-## CaseInstanceExecutionHistoryResponse Fields
-
-`creationUserKey: string | null`, `folderKey: string`, `instanceDisplayName: string`, `instanceId: string`, `packageId: string`, `packageKey: string`, `packageVersion: string`, `processKey: string`, `source: string`, `status: string`, `startedTime: string`, `completedTime: string | null`, `elementExecutions: ElementExecutionMetadata[]`.
-
-## CaseGetStageResponse Fields
-
-`id: string`, `name: string`, `sla?: StageSLA`, `status: string`, `tasks: StageTask[][]`.
-
-## StageTask Fields
-
-`id: string`, `name: string`, `completedTime: string`, `startedTime: string`, `status: string`, `type: StageTaskType`.
-
-## CaseInstances Service
-
-### getAll(options?: CaseInstanceGetAllWithPaginationOptions)
-
-Returns `NonPaginatedResponse<CaseInstanceGetResponse>` or `PaginatedResponse<CaseInstanceGetResponse>`. Filter options: `processKey`, `packageId`, `packageVersion`, `errorCode`.
-
-### getById(instanceId: string, folderKey: string)
-
-Returns `Promise<CaseInstanceGetResponse>` with attached methods.
-
-### close(instanceId: string, folderKey: string, options?: CaseInstanceOperationOptions)
-
-Returns `Promise<OperationResponse<CaseInstanceOperationResponse>>`. Options: `{ comment?: string }`.
-
-### pause / resume
-
-Same signature pattern as close.
-
-### reopen(instanceId: string, folderKey: string, options: CaseInstanceReopenOptions)
-
-Options: `{ stageId: string, comment?: string }`. The `stageId` is required - get it from `getStages()`.
-
-### getStages(caseInstanceId: string, folderKey: string)
-
-Returns `Promise<CaseGetStageResponse[]>`. Each stage has: `id`, `name`, `sla`, `status`, `tasks: StageTask[][]`.
-
-### getExecutionHistory(instanceId: string, folderKey: string)
-
-Returns `Promise<CaseInstanceExecutionHistoryResponse>` with `{ elementExecutions, instanceId, status, startedTime, completedTime, ... }`.
-
-### getActionTasks(caseInstanceId: string, options?: TaskGetAllOptions)
-
-Returns `NonPaginatedResponse<TaskGetResponse>` or `PaginatedResponse<TaskGetResponse>`. Requires `OR.Tasks` scope.
-
-### getSlaSummary(options?)
-
-Returns `NonPaginatedResponse<SlaSummaryResponse>` or `PaginatedResponse<SlaSummaryResponse>` (pass pagination options to get the paginated shape). Tenant-wide SLA rollup across case instances. **Requires `Insights.RealTimeData Insights OR.Folders.Read PIMS` scope.**
-
-### getStagesSlaSummary(options?: CaseInstanceStageSLAOptions)
-
-Returns `Promise<CaseInstanceStageSLAResponse[]>` — per-stage SLA breakdown. Same scope as `getSlaSummary`. **Note:** Exact response fields are not fully published; check the TypeScript types.
-
-## CaseInstance-Attached Methods (CaseInstanceMethods)
-
-- `instance.close(options?)` -> `Promise<OperationResponse<CaseInstanceOperationResponse>>`
-- `instance.pause(options?)` -> `Promise<OperationResponse<CaseInstanceOperationResponse>>`
-- `instance.resume(options?)` -> `Promise<OperationResponse<CaseInstanceOperationResponse>>`
-- `instance.reopen(options)` -> `Promise<OperationResponse<CaseInstanceOperationResponse>>`
-- `instance.getExecutionHistory()` -> `Promise<CaseInstanceExecutionHistoryResponse>`
-- `instance.getStages()` -> `Promise<CaseGetStageResponse[]>`
-- `instance.getActionTasks(options?)` -> pagination-aware, returns tasks
-
-## Usage Example
-
-```typescript
-import { useMemo, useEffect, useState } from 'react';
-import { useAuth } from '../hooks/useAuth';
-import { ProcessInstances } from '@uipath/uipath-typescript/maestro-processes';
-import type { ProcessInstanceGetResponse } from '@uipath/uipath-typescript/maestro-processes';
-
-function InstanceDashboard() {
-  const { sdk } = useAuth();
-  const processInstances = useMemo(() => new ProcessInstances(sdk), [sdk]);
-  const [instances, setInstances] = useState<ProcessInstanceGetResponse[]>([]);
-
-  useEffect(() => {
-    const load = async () => {
-      const result = await processInstances.getAll({ pageSize: 20 });
-      setInstances(result.items);
-    };
-    load();
-  }, [processInstances]);
-
-  const handleCancel = async (instance: ProcessInstanceGetResponse) => {
-    const result = await instance.cancel({ comment: 'Cancelled from dashboard' });
-    if (result.success) {
-      // Refresh list
-    }
-  };
-
-  return (
-    <div>
-      {instances.map(inst => (
-        <div key={inst.instanceId}>
-          <span>{inst.instanceDisplayName} - {inst.latestRunStatus}</span>
-          <button onClick={() => handleCancel(inst)}>Cancel</button>
-        </div>
-      ))}
-    </div>
-  );
-}
-```
-
-## Maestro Insights — RTM (SDK ≥ 1.4.x)
-
-> Scopes: Top/timeline/element methods need `Insights Insights.RealTimeData OR.Folders.Read`; the SLA methods additionally need **`PIMS`**. These use the Insights RTM host (NOT PIMS) — contrast with `Cases.getAll`/`CaseInstances.getAll`. Surface a 403 as a permissions message (the External App may lack the scopes in this environment).
-
-`Cases` (`@uipath/uipath-typescript/cases`) and `MaestroProcesses` (`@uipath/uipath-typescript/maestro-processes`) expose the **same six methods** with identical signatures. `CaseInstances` (`@uipath/uipath-typescript/cases`) adds the two SLA methods.
-
-**Positional `Date` args** (`start, end`) for the six analytics methods; `getSlaSummary` takes an **options object**. All return a **bare array** except `getSlaSummary` (rows on `.items`).
+| All incidents for one process | `MaestroProcesses.getIncidents(processKey, folderKey)` or `process.getIncidents()` |
+| Incidents on a single instance | `ProcessInstances.getIncidents(instanceId, folderKey)` or `instance.getIncidents()` |
 
-| Method | Returns (bare array of) | Notes |
-|--------|------------------------|-------|
-| `getTopRunCount(start, end, options?)` | `{ packageId, processKey, runCount, name }` | ≤5, ranked. `options`: `{ packageId?, processKey?, version? }` |
-| `getTopFaultedCount(start, end, options?)` | `{ packageId, processKey, faultedCount, name }` | ≤10, ranked |
-| `getTopExecutionDuration(start, end, options?)` | `{ packageId, processKey, duration, name }` | ≤5, `duration` in ms |
-| `getTopElementFailedCount(start, end, options?)` | `{ elementName, elementType, processKey, failedCount }` | ≤10, BPMN elements |
-| `getInstanceStatusTimeline(start, end, options?)` | `{ startTime, status, count }` | `status` ∈ `Completed`/`Faulted`/`Cancelled`; `startTime` is a LOCALE string; `options`: `{ groupBy?: TimeInterval }` (HOUR/DAY/WEEK, default DAY) |
-| `getElementStats(processKey, packageId, start, end, packageVersion)` | `{ elementId, successCount, failCount, terminatedCount, pausedCount, inProgressCount, minDurationMs, maxDurationMs, avgDurationMs, p50DurationMs, p95DurationMs, p99DurationMs }` | all positional args |
+`ProcessIncidentGetAllResponse` (summary) and `ProcessIncidentGetResponse` (per-incident detail) are different shapes.
 
-For Cases, `name` is derived from `packageId` (CaseManagement prefix stripped); for MaestroProcesses, `name === packageId`. Both present on every row.
+## Analytics / Insights RTM — server behavior the types don't show
 
-`CaseInstances` SLA methods:
+`Cases` and `MaestroProcesses` expose the same six analytics methods; `CaseInstances` adds the two SLA methods.
 
-| Method | Returns | Row shape |
-|--------|---------|-----------|
-| `getSlaSummary(options?)` | `{ items: SlaSummaryResponse[] }` (default top 50) or paginated | `{ caseInstanceId, folderKey, name, externalId, caseSummary, processKey, slaDueTime (ISO UTC), slaStatus, escalationRuleIndex, escalationRuleType, instanceStatus, lastModifiedTime }`. `options`: `{ caseInstanceId?, startTimeUtc?: Date, endTimeUtc?: Date }` + pagination |
-| `getStagesSlaSummary(options?)` | **bare** `{ caseInstanceId, stages: Stage[] }[]` | `Stage = { elementId, name, latestStatus, slaDueTime, slaStatus, escalationRuleIndex, escalationRuleType }`. `options`: `{ caseInstanceId? }` |
+| Method | Server behavior |
+|--------|----------------|
+| `getTopRunCount` | ≤5 rows, ranked |
+| `getTopFaultedCount` | ≤10 rows, ranked |
+| `getTopExecutionDuration` | ≤5 rows, `duration` in **ms** |
+| `getTopElementFailedCount` | ≤10 rows, BPMN elements |
+| `getInstanceStatusTimeline` | `startTime` is a **LOCALE string**, not ISO |
 
-`slaStatus` string values: `'On Track'`, `'At Risk'`, `'Overdue'`, `'Completed'`, `'Unknown'`. **Compare as strings — do not import the enum** (avoids TS narrowing errors; values are stable).
+- For Cases, `name` is derived from `packageId` (CaseManagement prefix stripped); for MaestroProcesses, `name === packageId`.
+- `slaStatus`: **compare as strings** (`'At Risk'`, `'Overdue'`, …) — do not import the enum (avoids TS narrowing errors; values are stable).
 
 ### Module patterns