@uipath/skills 1.199.0 → 1.200.0

package/skills/uipath-coded-apps/references/sdk/data-fabric.md

@@ -1,246 +1,29 @@
-# Data Fabric Reference
+# Data Fabric — Traps & Server Behavior
 
-## Imports
+Signatures/params/examples: `dist/entities/index.d.ts` (trigger-event behavior differs per method — the JSDoc on each insert/update/delete method documents it). Per-method scopes: shipped `docs/oauth-scopes.md`. This file covers only what neither can express.
 
-```typescript
-import { Entities, ChoiceSets } from '@uipath/uipath-typescript/entities';
-```
+> **Scope pairing warning:** schema introspection (`entities.getAll()` / `getById()`) and record I/O sit in different scope pairs — `DataFabric.Schema.Read` vs `DataFabric.Data.Read` / `DataFabric.Data.Write`. This file mandates schema introspection before writes and filters, so an app with only Data scopes 403s on the introspection step. Check the shipped table per method.
 
 ## Anti-shapes & gotchas (read first)
 
-Data Fabric does NOT behave like a typical RDBMS. These differences trip up agents that pattern-match on familiar SQL/ORM shapes. Before writing analytics, filters, or update logic, call `entities.getById(id)` and inspect `fields[].name` + `fieldDataType`. Pick your data strategy from what's actually there — do NOT assume.
+Data Fabric does NOT behave like a typical RDBMS. These server behaviors are invisible to both the types and the JSDoc. Before writing analytics, filters, or update logic, call `entities.getById(id)` and inspect `fields[].name` + `fieldDataType.name`. Pick your data strategy from what's actually there — do NOT assume.
 
-1. **Choice values come back as `numberId` integers on every read path.** Including ungrouped `getRecordById` and `queryRecordsById` items, not just `groupBy` results. Code like `record.Priority.toLowerCase()` will throw or produce `"5"`. Build `numberId → name` maps via `choiceSets.getById(<csId>)` and translate every read.
-2. **DF auto-creates audit fields that look like domain fields but aren't.** Every entity has `CreateTime`, `UpdateTime`, `CreatedBy`, `UpdatedBy`, `Id`, `RecordOwner` — these are **row metadata** (when DF inserted/wrote the row), not the business event the row represents. When you need a domain-level "created at" / "updated at" / "owner", look for a custom field with a domain-specific name; if none exists, flag it back to the user rather than silently using the audit column. When writing your own historical timestamp field, name it something distinct from `CreateTime` / `UpdateTime` to avoid the conflict at write time.
-3. **Unknown keys on insert are silently dropped.** A typo in a field name in `insertRecordsById` does NOT raise an error — the value is just discarded. Always introspect the schema and validate keys before bulk operations.
-4. **No `IsNull` filter operator.** `queryRecordsById` filters can't ask "where field is null". Filter client-side after fetching, or design queries with explicit non-null sentinels.
-5. **Field name casing is preserved verbatim on writes.** If the entity field is `Subject` (PascalCase), record payloads must use `Subject`, not `subject`. The SDK does NOT pascalize keys for you — DF rejects mismatched casing as missing required field.
-6. **Filter `value` for choice fields must be the `numberId` as a string.** `{ fieldName: 'Status', operator: Equals, value: 'Resolved' }` matches nothing — use `value: String(numberIdForResolved)`.
-7. **Aggregates require server-side `aggregates` + `groupBy`.** Don't fetch raw rows and `.length` / `.reduce` client-side — every list call returns one page (see [pagination.md](pagination.md)) and you'll silently truncate. Use `{ aggregates: [{ function: EntityAggregateFunction.Count, field: 'Id' }] }` (string literal `'COUNT'` works equivalently).
-8. **`field.fieldDataType` is an OBJECT, not a string.** It's `{ name: 'DECIMAL', lengthLimit?: ..., maxValue?: ..., ... }`. Code like `String(field.fieldDataType).toUpperCase()` produces `"[object Object]"` and silently rejects every field. Always read `field.fieldDataType?.name`. Same applies to `field.fieldDisplayType` — but that one IS a plain string enum (`'ChoiceSetSingle'`, `'File'`, etc.).
-9. **File-type fields (`fieldDisplayType === 'File'`) aren't strings.** The record carries only metadata (`{ id, name, size, contentType }`); stringifying gives `"[object Object]"`. To display, call `entities.downloadAttachment(entityId, recordId, fieldName)` → `Blob` → `URL.createObjectURL` for an `<img src>`. **Neither `contentType` nor filename extension is reliable for detecting kind** — DF often returns `application/octet-stream`, and the stored `name` is frequently a bare UUID with no extension. To decide whether to render inline or fall back to a download link, either (a) sniff the blob's magic bytes after download (PNG starts `89 50 4E 47`, JPEG `FF D8 FF`, GIF `47 49 46 38`, PDF `25 50 44 46`, etc.), or (b) optimistically attempt `<img src={objectUrl}>` and swap to a download link in `onError`. Writes: `uploadAttachment(entityId, recordId, fieldName, file)`, not `insertRecordById` / `updateRecordById`.
-10. **`MULTILINE_MAX` fields return a size marker on list/query reads.** `getAllRecords` / `queryRecordsById` return a string starting `HasValue=true Length=N` (live form: `"HasValue=true Length=20000 — call Get Entity Record By Id activity to retrieve content"`), never the content — only `getRecordById` returns the full value (SDK 1.5.2+, v2 read endpoint). Never render or persist the marker as data, and never echo it back through `updateRecordById` / `updateRecordsById` — the server accepts it as a normal value and silently destroys the real content; omit the key instead. The type accepts no filters or `sortOptions` (server 400: *"Field '<name>' is of type MULTILINE_MAX and cannot be used in filters."*). `lengthLimit` is a UTF-16 **byte** budget (max 131072 ≈ 65,536 chars).
+1. **Choice values come back as `numberId` integers on every read path.** Including ungrouped `getRecordById` / `queryRecordsById` items AND `groupBy` result keys. The SDK does NOT convert to string names. Code like `record.Priority.toLowerCase()` throws or produces `"5"`; `if (record.Status === "Resolved")` is always false because `record.Status` is `5`. Build `numberId → name` maps via `choiceSets.getById(<choiceSetId>)` (get `<choiceSetId>` from `entities.getById(id).fields[].choiceSetId`) and translate every read.
+2. **Choice-set writes and filters take the integer `numberId`, not the value name.** Writes: sending `status: "Open"` fails with `Single choiceset value Open is not integer`. Filters: `{ fieldName: 'Status', operator: Equals, value: 'Resolved' }` matches nothing — use `value: String(numberIdForResolved)` (applies to **every** operator touching a choice field, including `NotEquals`, `In`, `NotIn`). Failure is silent: 0 rows or all rows depending on operator.
+3. **Record keys must match the schema's exact casing.** The SDK does NOT pascalize keys. If the entity field is `Subject` (PascalCase, the DF UI default), sending `{ subject: … }` fails with `Required field "Subject" is not provided` — DF's required-field check is case-sensitive. Use `field.name` verbatim as the record key.
+4. **Unknown keys on insert/update are silently dropped.** A typo'd field name in `insertRecordsById` does NOT error — the value is discarded without warning. Introspect the schema and validate keys before bulk operations.
+5. **DF auto-creates audit fields that look like domain fields but aren't.** Every entity has `CreateTime`, `UpdateTime`, `CreatedBy`, `UpdatedBy`, `Id`, `RecordOwner` — **row metadata** (when DF wrote the row), not the business event the row represents. They appear in the schema but are not writable. Need a domain-level "created at" / "owner"? Look for a custom field with a domain-specific name; if none exists, flag it to the user rather than silently using the audit column. Seeding historical timestamps: add a custom `DATETIME_WITH_TZ` field (e.g., `OriginalCreatedTime`) — do NOT name it `CreateTime` / `CreatedTime`, the audit name conflict causes silent drops or schema rejection.
+6. **No `IsNull` filter operator.** The server can't ask "where field is null" (`QueryFilterOperator` has no such member). Filter client-side after fetching, or design with explicit non-null sentinels.
+7. **Aggregates require server-side `aggregates` + `groupBy`.** Don't fetch raw rows and `.length` / `.reduce` client-side — every list call returns one page (see [pagination.md](pagination.md)), so `result.items.length` after `queryRecordsById({ filter })` returns at most one page's worth, no matter how many rows match. Use `totalCount` for cardinality, `aggregates: [{ function: 'COUNT', field: 'Id' }]` (with `groupBy` for per-bucket counts) for chart data.
+8. **File-type fields (`fieldDisplayType === 'File'`) aren't strings.** The record carries only metadata (`{ id, name, size, contentType }`); stringifying gives `"[object Object]"`. To display, call `entities.downloadAttachment(entityId, recordId, fieldName)` → `Blob` → `URL.createObjectURL` for an `<img src>`. **Neither `contentType` nor filename extension is reliable for detecting kind** — DF often returns `application/octet-stream`, and the stored `name` is frequently a bare UUID with no extension. To decide inline render vs download link, either (a) sniff the blob's magic bytes after download (PNG starts `89 50 4E 47`, JPEG `FF D8 FF`, GIF `47 49 46 38`, PDF `25 50 44 46`), or (b) optimistically attempt `<img src={objectUrl}>` and swap to a download link in `onError`. Writes go through `uploadAttachment(...)`, not `insertRecordById` / `updateRecordById`.
+9. **`MULTILINE_MAX` fields return a size marker on list/query reads.** `getAllRecords` / `queryRecordsById` return a string starting `HasValue=true Length=N` (live form: `"HasValue=true Length=20000 — call Get Entity Record By Id activity to retrieve content"`), never the content — only `getRecordById` returns the full value (SDK 1.5.2+, v2 read endpoint). Never render or persist the marker as data, and never echo it back through `updateRecordById` / `updateRecordsById` — the server accepts it as a normal value and silently destroys the real content; omit the key instead. The type accepts no filters or `sortOptions` (server 400: *"Field '<name>' is of type MULTILINE_MAX and cannot be used in filters."*). `lengthLimit` is a UTF-16 **byte** budget (max 131072 ≈ 65,536 chars).
 
-## Scopes
+## Three paths require choice-value translation — don't miss any
 
-- Schema reads: `DataFabric.Schema.Read`
-- Data reads: `DataFabric.Data.Read`
-- Data writes: `DataFabric.Data.Write`
+| Path | Direction | What to do |
+|---|---|---|
+| Writes (`insertRecordsById`, `updateRecordById`, `updateRecordsById`) | name → `numberId` | translate before sending |
+| Filter values (any `queryRecordsById` filter on a choice field) | name → `numberId` (as a string) | translate before sending |
+| Read results (`groupBy` keys AND ungrouped record items) | `numberId` → name | translate after receiving |
 
-## Types to Import
-
-```typescript
-import type {
-  EntityGetResponse,
-  RawEntityGetResponse,
-  EntityMethods,
-  EntityRecord,
-  EntityFileType,
-  EntityGetAllRecordsOptions,
-  EntityGetRecordByIdOptions,
-  EntityInsertRecordOptions,
-  EntityInsertResponse,
-  EntityInsertRecordsOptions,
-  EntityBatchInsertResponse,
-  EntityUpdateRecordOptions,
-  EntityUpdateRecordResponse,
-  EntityUpdateRecordsOptions,
-  EntityUpdateResponse,
-  EntityDeleteRecordsOptions,
-  EntityDeleteResponse,
-  EntityUploadAttachmentOptions,
-  EntityUploadAttachmentResponse,
-  EntityDeleteAttachmentResponse,
-  EntityOperationResponse,
-  EntityQueryRecordsOptions,
-  EntityQueryRecordsResponse,
-  EntityQueryFilter,
-  EntityQueryFilterGroup,
-  EntityQuerySortOption,
-  EntityAggregate,
-  FailureRecord,
-  ChoiceSetGetAllResponse,
-  ChoiceSetGetResponse,
-  ChoiceSetGetByIdOptions,
-} from '@uipath/uipath-typescript/entities';
-```
-
-## Enums
-
-```typescript
-import {
-  EntityFieldDataType,     // UUID, STRING, INTEGER, DATETIME, DATETIME_WITH_TZ, DECIMAL, FLOAT, DOUBLE, DATE, BOOLEAN, BIG_INTEGER, MULTILINE_TEXT, MULTILINE_MAX (SDK 1.5.2+)
-  EntityType,              // Entity, ChoiceSet, InternalEntity, SystemEntity
-  FieldDisplayType,        // Basic, Relationship, File, ChoiceSetSingle, ChoiceSetMultiple, AutoNumber
-  LogicalOperator,         // And, Or
-  QueryFilterOperator,     // Equals, NotEquals, GreaterThan, LessThan, ... (used in queryRecordsById filters)
-  EntityAggregateFunction, // Count, Sum, Avg, Min, Max — string-valued enum ('COUNT', 'SUM', ...)
-} from '@uipath/uipath-typescript/entities';
-```
-
-## Entities Service
-
-### getAll()
-
-Returns `Promise<EntityGetResponse[]>`. Each entity has attached methods.
-
-### getById(id: string)
-
-Returns `Promise<EntityGetResponse>` with attached methods.
-
-### getAllRecords(entityId: string, options?: EntityGetAllRecordsOptions)
-
-Returns `NonPaginatedResponse<EntityRecord>` or `PaginatedResponse<EntityRecord>` when pagination options are passed. Options: `expansionLevel?: number`, plus `pageSize`, `cursor`, `jumpToPage`.
-
-### getRecordById(entityId: string, recordId: string, options?: EntityGetRecordByIdOptions)
-
-Returns `Promise<EntityRecord>`. Options: `expansionLevel?: number`.
-
-### insertRecordById(id: string, data: Record<string, any>, options?: EntityInsertRecordOptions)
-
-Returns `Promise<EntityInsertResponse>` (which is `EntityRecord` — the inserted record with generated ID). Triggers Data Fabric trigger events.
-
-### insertRecordsById(id: string, data: Record<string, any>[], options?: EntityInsertRecordsOptions)
-
-Returns `Promise<EntityBatchInsertResponse>` with `{ successRecords, failureRecords }`. Does NOT trigger events. Options: `expansionLevel`, `failOnFirst`.
-
-> **Choice-set fields take the integer `numberId`, not the value name.** Sending `status: "Open"` fails with `Single choiceset value Open is not integer`. Build a `name → numberId` map from `choiceSets.getById(<choiceSetId>)`; get the `<choiceSetId>` from `entities.getById(id).fields[].referenceChoiceSet?.id` (or `.choiceSetId`).
-
-> **Record keys must match the schema's exact casing.** The SDK does NOT pascalize record keys. If your entity's fields are `Subject`, `Status`, `CustomerEmail` (PascalCase, the DF UI default), you must send `{ Subject: …, Status: 1, CustomerEmail: … }` — sending `{ subject, status, customerEmail }` produces `Required field "Subject" is not provided` because DF's required-field check is case-sensitive. Read the schema via `entities.getById(id)` and use `field.name` verbatim as the record key.
-
-> **Unknown keys are silently dropped.** If your record contains a key that isn't in the entity schema (typo, removed field, audit-column name conflict), `insertRecordsById` does NOT error — the field is just ignored. Always introspect the schema with `entities.getById(id)` before seeding bulk data; keys that don't show up in `entity.fields` will be discarded without warning.
-
-> **DF auto-manages `CreateTime` / `UpdateTime` / `CreatedBy` / `UpdatedBy` / `Id` audit columns.** They appear in the entity schema but you cannot write to them — DF sets `CreateTime` to the moment of insert and `UpdateTime` to the moment of last write. If you need to seed historical timestamps (e.g., for an analytics demo where tickets must look 1–21 days old), add a **custom** `DATETIME_WITH_TZ` field (e.g., `OriginalCreatedTime`) and write to that. Do NOT name your custom field `CreateTime` or `CreatedTime` — the audit name conflict will cause silent drops or schema rejection.
-
-### updateRecordById(entityId: string, recordId: string, data: Record<string, any>, options?: EntityUpdateRecordOptions)
-
-Returns `Promise<EntityUpdateRecordResponse>` — the updated single record. **Triggers Data Fabric trigger events** (unlike the bulk `updateRecordsById`). Use this when you need trigger events to fire for the updated record. Options: `expansionLevel`.
-
-### updateRecordsById(id: string, data: EntityRecord[], options?: EntityUpdateRecordsOptions)
-
-Returns `Promise<EntityUpdateResponse>` with `{ successRecords, failureRecords }`. Each record in `data` MUST include an `Id` field. Options: `expansionLevel`, `failOnFirst`. **Does NOT trigger events** — use `updateRecordById` if you need trigger events.
-
-### deleteRecordsById(id: string, recordIds: string[], options?: EntityDeleteRecordsOptions)
-
-Returns `Promise<EntityDeleteResponse>` with `{ successRecords, failureRecords }`. Options: `failOnFirst`. **Does NOT trigger events** — use `deleteRecordById` if you need trigger events.
-
-### deleteRecordById(entityId: string, recordId: string)
-
-Returns `Promise<void>`. **Triggers Data Fabric trigger events.** Use this for single deletes when triggers must fire (the bulk `deleteRecordsById` does not fire triggers).
-
-### queryRecordsById(id: string, options?: EntityQueryRecordsOptions)
-
-Returns `NonPaginatedResponse<EntityRecord>` or `PaginatedResponse<EntityRecord>` when pagination options are passed. Supports server-side filters, sort, field selection, aggregates, and group-by.
-
-> **For counts and chart data, use server-side `aggregates` + `groupBy`.** Don't fetch raw rows and aggregate in JS — every list call returns one page (see [pagination.md](pagination.md)), so `result.items.length` after `queryRecordsById({ filter })` returns at most one page's worth, no matter how many rows match. Use `aggregates: [{ function: 'COUNT', field: 'Id' }]` (with `groupBy` for per-bucket counts).
-
-> **Choice-set values come back as `numberId` integers in read responses — translate them yourself.** This applies to `groupBy` results AND ungrouped `queryRecordsById`/`getRecordById` items. Build a `numberId → name` map per choice field from `choiceSets.getById(<choiceSetId>)` once on app load and translate every time you read a choice field for display, comparison, or filter logic. Do NOT assume the SDK has already converted to a string name — it has not. A common silent failure: code that does `if (record.Status === "Resolved")` always evaluates false because `record.Status` is `5` (the numberId). Same for any logic doing `record.Priority.toLowerCase()` — it'll read `(5).toLowerCase`, throw, or coerce to `"5"` and miss every lookup keyed on names.
-
-> **Filter `value` for a choice field must be the `numberId`** (as a string, per the operator type). `{ fieldName: 'Status', operator: Equals, value: 'Resolved' }` matches nothing — use `value: String(numberIdForResolved)`. This rule applies to **every** filter touching a choice-set field, including `NotEquals`, `In`, `NotIn`. Failing to translate filter values is silent: the API returns 0 rows or all rows depending on operator, so a "0 records" or "all records" symptom that ignores your filter usually means a missing translation.
-
-> **Three paths require choice-value translation. Don't miss any.**
-> | Path | Direction | What to do |
-> |---|---|---|
-> | Writes (`insertRecordsById`, `updateRecordById`, `updateRecordsById`) | name → `numberId` | translate before sending |
-> | Filter values (any `queryRecordsById` filter on a choice field) | name → `numberId` (as a string) | translate before sending |
-> | `groupBy` result keys | `numberId` → name | translate after receiving for display |
->
-> Best practice: on app load, fetch each choice set once and build **both** maps (`byName` and `byNumberId`). Reuse across all paths.
-
-`EntityQueryRecordsOptions`:
-- `filterGroup?: EntityQueryFilterGroup` — `{ logicalOperator?: LogicalOperator.And | Or, queryFilters?: EntityQueryFilter[], filterGroups?: EntityQueryFilterGroup[] }` (nested groups allowed). Each filter: `{ fieldName, operator: QueryFilterOperator, value?: string, valueList?: string[] }`.
-- `selectedFields?: string[]` — fields to return (omit for all)
-- `sortOptions?: EntityQuerySortOption[]` — `[{ fieldName, isDescending }]`
-- `aggregates?: EntityAggregate[]` — `[{ function: EntityAggregateFunction.Count | Sum | Avg | Min | Max, field, alias }]` (string literals `'COUNT'` / `'SUM'` / etc. also work — the enum is string-valued). For `Count`, any non-null field works — typically `'Id'`.
-- `groupBy?: string[]` — group aggregate results
-- `expansionLevel?: number` — default 0
-- Pagination (`pageSize`, `cursor`, `jumpToPage`) — when supplied, returns `PaginatedResponse`
-
-`QueryFilterOperator` values: `Equals` `'='`, `NotEquals` `'!='`, `GreaterThan` `'>'`, `LessThan` `'<'`, `GreaterThanOrEqual` `'>='`, `LessThanOrEqual` `'<='`, `Contains` `'contains'`, `NotContains` `'not contains'`, `StartsWith` `'startswith'`, `EndsWith` `'endswith'`, `In` `'in'`, `NotIn` `'not in'`.
-
-> **`value` is always a string.** For numeric, boolean, or date fields, pass the string form (e.g., `"42"`, `"true"`, `"2026-05-01T00:00:00Z"`). For `In`/`NotIn`, use `valueList: string[]` instead of `value`.
-
-```typescript
-import { LogicalOperator, QueryFilterOperator, EntityAggregateFunction } from '@uipath/uipath-typescript/entities';
-
-// Filter + sort
-const result = await entities.queryRecordsById(entityId, {
-  filterGroup: {
-    logicalOperator: LogicalOperator.And,
-    queryFilters: [{ fieldName: 'status', operator: QueryFilterOperator.Equals, value: 'active' }],
-  },
-  sortOptions: [{ fieldName: 'createdTime', isDescending: true }],
-});
-
-// Aggregate: count per status
-await entities.queryRecordsById(entityId, {
-  selectedFields: ['status'],
-  groupBy: ['status'],
-  aggregates: [{ function: EntityAggregateFunction.Count, field: 'Id', alias: 'total' }],
-});
-```
-
-### downloadAttachment(entityId: string, recordId: string, fieldName: string)
-
-Returns `Promise<Blob>`. **Positional arguments, not an options object.** `entityId` is the UUID of the entity (not the entity name).
-
-### uploadAttachment(entityId: string, recordId: string, fieldName: string, file: EntityFileType, options?: EntityUploadAttachmentOptions)
-
-Returns `Promise<EntityUploadAttachmentResponse>`. `file` accepts `Blob | File | Uint8Array`. Options: `expansionLevel`.
-
-### deleteAttachment(entityId: string, recordId: string, fieldName: string)
-
-Returns `Promise<EntityDeleteAttachmentResponse>`. Positional arguments.
-
-## Entity-Attached Methods (EntityMethods)
-
-Returned by `getAll()` and `getById()` on each `EntityGetResponse`:
-
-- `entity.insertRecord(data, options?)` -> `Promise<EntityInsertResponse>` (fires trigger events)
-- `entity.insertRecords(data[], options?)` -> `Promise<EntityBatchInsertResponse>` (no trigger events)
-- `entity.updateRecord(recordId, data, options?)` -> `Promise<EntityUpdateRecordResponse>` (fires trigger events)
-- `entity.updateRecords(data: EntityRecord[], options?)` -> `Promise<EntityUpdateResponse>` (no trigger events)
-- `entity.deleteRecords(recordIds: string[], options?)` -> `Promise<EntityDeleteResponse>` (no trigger events)
-- `entity.deleteRecord(recordId)` -> `Promise<void>` (fires trigger events)
-- `entity.getAllRecords(options?)` -> `NonPaginatedResponse<EntityRecord>` or `PaginatedResponse<EntityRecord>`
-- `entity.getRecord(recordId, options?)` -> `Promise<EntityRecord>`
-- `entity.queryRecords(options?)` -> `NonPaginatedResponse<EntityRecord>` or `PaginatedResponse<EntityRecord>` (filters, sort, aggregates — see `queryRecordsById` above)
-- `entity.uploadAttachment(recordId, fieldName, file, options?)` -> `Promise<EntityUploadAttachmentResponse>`
-- `entity.downloadAttachment(recordId, fieldName)` -> `Promise<Blob>`
-- `entity.deleteAttachment(recordId, fieldName)` -> `Promise<EntityDeleteAttachmentResponse>`
-
-## ChoiceSets Service
-
-### getAll()
-
-Returns `Promise<ChoiceSetGetAllResponse[]>`. Each item has: `name`, `displayName`, `description`, `folderId`, `createdBy`, `updatedBy`, `createdTime`, `updatedTime`.
-
-### getById(choiceSetId: string, options?: ChoiceSetGetByIdOptions)
-
-Returns `NonPaginatedResponse<ChoiceSetGetResponse>` or `PaginatedResponse<ChoiceSetGetResponse>`. Each value has: `id`, `name`, `displayName`, `numberId`, `createdTime`, `updatedTime`.
-
-## Usage Example
-
-```typescript
-import { useMemo, useEffect, useState } from 'react';
-import { useAuth } from '../hooks/useAuth';
-import { Entities } from '@uipath/uipath-typescript/entities';
-import type { EntityGetResponse, EntityRecord } from '@uipath/uipath-typescript/entities';
-
-function EntityRecords({ entityId }: { entityId: string }) {
-  const { sdk } = useAuth();
-  const entities = useMemo(() => new Entities(sdk), [sdk]);
-  const [records, setRecords] = useState<EntityRecord[]>([]);
-
-  useEffect(() => {
-    const load = async () => {
-      const entity = await entities.getById(entityId);
-      const result = await entity.getAllRecords({ pageSize: 50 });
-      setRecords(result.items);
-    };
-    load();
-  }, [entities, entityId]);
-
-  return <div>{records.map(r => <div key={r.id}>{JSON.stringify(r)}</div>)}</div>;
-}
-```
+Best practice: on app load, fetch each choice set once (`choiceSets.getById` returns values carrying `name` + `numberId`) and build **both** maps (`byName` and `byNumberId`). Reuse across all paths.

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

@@ -1,142 +1,7 @@
-# Agent Feedback Reference
+# Agent Feedback — Traps
 
-Feedback allows you to collect and manage user feedback on AI agent responses, including positive/negative ratings, comments, and categorized feedback. This is useful for monitoring agent quality, identifying areas for improvement, and building datasets for fine-tuning.
+Signatures/params/examples: `dist/feedback/index.d.ts` (JSDoc documents the required `folderKey` option, default categories, and `createCategory` flag defaults). Per-method scopes: shipped `docs/oauth-scopes.md`. This file covers only what neither can express.
 
-## Import
+> **Scope warning:** every Feedback method — reads, writes, category management — uses the Traces bundle (`Traces.Api`), not an OR.* or Agents scope. A 403 here means the External App lacks the Traces bundle; check the shipped table.
 
-```typescript
-import { Feedback } from '@uipath/uipath-typescript/feedback';
-```
-
-## Scopes
-
-`Traces.Api` — for **every** method (reads, writes, and category management).
-
-## Types to Import
-
-```typescript
-import type {
-  FeedbackGetResponse,
-  FeedbackResponse,
-  FeedbackGetAllOptions,
-  FeedbackOptions,
-  FeedbackSubmitOptions,
-  FeedbackUpdateOptions,
-  FeedbackGetCategoriesOptions,
-  FeedbackCreateCategoryOptions,
-  FeedbackDeleteCategoryOptions,
-  FeedbackCategory,
-  FeedbackCategoryInput,
-  FeedbackCategoryResponse,
-} from '@uipath/uipath-typescript/feedback';
-```
-
-## Enums
-
-```typescript
-import { FeedbackStatus } from '@uipath/uipath-typescript/feedback';
-// FeedbackStatus.Pending = 0, Approved = 1, Dismissed = 2
-```
-
-## Feedback Service
-
-### getAll(options?: FeedbackGetAllOptions)
-
-Returns `NonPaginatedResponse<FeedbackGetResponse>` or `PaginatedResponse<FeedbackGetResponse>`. As with every list method, this returns one page — see [pagination.md](pagination.md) for cursor-loop retrieval if the source has more rows than the server's default cap.
-
-`FeedbackGetAllOptions` filters: `agentId?`, `agentVersion?`, `status?: FeedbackStatus`, `traceId?`, `spanId?`. Plus `PaginationOptions` (`pageSize`, `cursor`, `jumpToPage`).
-
-### getById(id: string, options: FeedbackOptions)
-
-Returns `Promise<FeedbackGetResponse>`. **`options.folderKey` is required** — get it from a `getAll()` item or wherever the feedback originated.
-
-`FeedbackGetResponse` fields: `id`, `traceId`, `spanId`, `agentId`, `agentVersion?`, `comment?`, `metadata?`, `isPositive`, `feedbackCategories: FeedbackCategory[]`, `folderKey?`, `userEmail?`, `status: FeedbackStatus`, `createdTime`, `updatedTime`.
-
-`FeedbackCategory` fields: `id`, `category`, `createdAt`, `isDefault`, `isPositive`, `isNegative`. Default categories (Output, Agent Error, Agent Plan Execution) are auto-created per tenant.
-
-### submit(traceId: string, isPositive: boolean, options: FeedbackSubmitOptions)
-
-Returns `Promise<FeedbackResponse>`. Creates a new feedback entry against an agent trace. `isPositive` is the thumbs-up/down. **`options.folderKey` is required.** Other `FeedbackSubmitOptions` fields (all optional): `agentId`, `agentVersion`, `comment`, `metadata` (string), `spanId`, `spanType`, `categories: FeedbackCategoryInput[]`.
-
-### updateById(id: string, isPositive: boolean, options: FeedbackUpdateOptions)
-
-Returns `Promise<FeedbackResponse>`. Updates an existing feedback entry. **`options.folderKey` is required.** Optional fields: `comment`, `metadata`, `categories: FeedbackCategoryInput[]`.
-
-### deleteById(id: string, options: FeedbackOptions)
-
-Returns `Promise<void>`. **`options.folderKey` is required.**
-
-### getCategories(options?: FeedbackGetCategoriesOptions)
-
-Returns `NonPaginatedResponse<FeedbackCategoryResponse>` or `PaginatedResponse<FeedbackCategoryResponse>`. Lists feedback categories (default + custom). `FeedbackCategoryResponse` fields: `id`, `category`, `createdTime`, `isDefault`, `isPositive`, `isNegative`.
-
-### createCategory(category: string, options?: FeedbackCreateCategoryOptions)
-
-Returns `Promise<FeedbackCategoryResponse>`. Creates a custom category. `FeedbackCreateCategoryOptions`: `isPositive?` (defaults `true`), `isNegative?` (defaults `true`) — set the flags to scope the category to one rating direction.
-
-### deleteCategory(id: string, options?: FeedbackDeleteCategoryOptions)
-
-Returns `Promise<void>`. Deletes a custom category. Default tenant categories cannot be removed.
-
-## Usage Example — Feedback Inbox
-
-```typescript
-import { useMemo, useEffect, useState } from 'react';
-import { useAuth } from '../hooks/useAuth';
-import { Feedback, FeedbackStatus } from '@uipath/uipath-typescript/feedback';
-import type { FeedbackGetResponse } from '@uipath/uipath-typescript/feedback';
-
-function FeedbackInbox({ agentId }: { agentId: string }) {
-  const { sdk } = useAuth();
-  const feedback = useMemo(() => new Feedback(sdk), [sdk]);
-  const [items, setItems] = useState<FeedbackGetResponse[]>([]);
-
-  useEffect(() => {
-    const load = async () => {
-      const result = await feedback.getAll({
-        agentId,
-        status: FeedbackStatus.Pending,
-        pageSize: 25,
-      });
-      setItems(result.items);
-    };
-    load();
-  }, [feedback, agentId]);
-
-  const openDetail = async (item: FeedbackGetResponse) => {
-    if (!item.folderKey) return;
-    const detail = await feedback.getById(item.id, { folderKey: item.folderKey });
-    console.log(detail.comment, detail.feedbackCategories);
-  };
-}
-```
-
-## Usage Example — Submitting & Managing Feedback
-
-```typescript
-import { Feedback } from '@uipath/uipath-typescript/feedback';
-
-const feedback = new Feedback(sdk);
-
-// Submit thumbs-up on an agent trace
-const created = await feedback.submit(traceId, true, {
-  folderKey,                      // required
-  agentId,
-  comment: 'Accurate and well-structured answer',
-  categories: [{ category: 'Output', isPositive: true }],
-});
-
-// Flip it to thumbs-down and edit the comment
-await feedback.updateById(created.id, false, {
-  folderKey,
-  comment: 'On second read, the figures were wrong',
-});
-
-// Manage categories
-const categories = await feedback.getCategories({ pageSize: 50 });
-const custom = await feedback.createCategory('Tone', { isNegative: true, isPositive: false });
-await feedback.deleteCategory(custom.id);
-
-// Remove the entry
-await feedback.deleteById(created.id, { folderKey });
-```
+`getAll()` returns one page — cursor-loop per [pagination.md](pagination.md) when the source may exceed the server's default cap.

package/skills/uipath-coded-apps/references/sdk/governance-traces.md

@@ -1,7 +1,9 @@
 # Agent Governance Decisions (Insights RTM)
 
-> Requires `@uipath/uipath-typescript` **≥ 1.5.1**. Scopes: `Insights Insights.RealTimeData OR.Folders.Read` (all in `DASHBOARD_SCOPES`). Subpath: `@uipath/uipath-typescript/traces` (the `AgentTraces` service).
-> **Org-admin required.** Both methods 403 for non-admin callers (SDK throws `AuthorizationError`). On 403: tell the user their account lacks governance access, render the widget's EmptyState, build the rest of the dashboard. Do not retry.
+Signatures/params/examples: `dist/traces/index.d.ts` (the `AgentTraces` service). Per-method scopes: shipped `docs/oauth-scopes.md`. This file covers only what neither can express.
+
+> Subpath: `@uipath/uipath-typescript/traces`.
+> **Org-admin required** (both methods 403 otherwise — see the JSDoc `@remarks`). On 403: tell the user their account lacks governance access, render the widget's EmptyState, build the rest of the dashboard. Do not retry. Never fabricate data.
 
 First-class Insights endpoints for **agentic runtime governance** — every policy check an agent run went through (allow/deny per hook) plus an aggregated posture summary. These widgets honor the dashboard time range like any other metric.
 
@@ -13,60 +15,10 @@ First-class Insights endpoints for **agentic runtime governance** — every poli
 > a different domain (platform policy enforcement). When unsure which the user means, ASK. Never add these
 > widgets to a plain agent-health/ops dashboard.
 
-```typescript
-import { AgentTraces, AgentGovernanceVerdict, AgentGovernanceSection } from '@uipath/uipath-typescript/traces'
-const svc = new AgentTraces(sdk)
-```
-
-Both methods take a **required positional `startTime: Date`** first (same convention as `Governance.getPolicyTraces`); everything else lives in options.
-
-## getGovernanceSummary(startTime, options?) — breakdowns in ONE call
-
-Returns a **single object — not an array**. Options: `{ endTime?, topN?, packName?, sections? }`.
-
-**Example response** (grounded in SDK test fixtures):
-
-```json
-{
-  "total": 26, "violations": 3,
-  "byHook":   [{ "key": "BEFORE_MODEL", "name": null, "count": 12, "violationCount": 2 }],
-  "byAgent":  [{ "key": "af12…", "name": "customer-care-assistant-for-acmecare", "count": 20, "violationCount": 1 }],
-  "byPolicy": [{ "key": "ISO42001-guardrail-prompt-injection", "name": "AI system impact assessment", "count": 2, "violationCount": 0 }],
-  "byPack":   [{ "key": "ISO/IEC 42001:2023 Runtime", "name": null, "count": 26, "violationCount": 3 }],
-  "byAction": [], "byMode": []
-}
-```
-
-Semantics:
-- `violations` / `violationCount` = **Deny verdicts**; `count`/`total` = all checks. Violation widgets read `violationCount`; all-checks widgets read `count`.
-- **`byAction` and `byMode` are EMPTY unless opted in** via `sections: [AgentGovernanceSection.Action]` / `[…Mode]`. Forgetting `sections` is the compiles-green-renders-empty trap here.
-- `name` is populated for `byPolicy`/`byAgent`; render `name ?? key`.
-- `topN` caps each breakdown; `packName` scopes totals + breakdowns to one pack.
-
-## getGovernanceDecisions(startTime, options?) — the record grain
-
-One row per policy check. Paginated; rows on `.items`. Options: `{ endTime?, hook?, evaluatorResult?, policyId?, agentId?, violationsOnly?, pageSize?, cursor? }`.
-
-**Example response** (`.items` — grounded in SDK test fixtures):
-
-```json
-{
-  "items": [{
-    "startTime": "2026-06-28T14:03:22Z", "endTime": "2026-06-28T14:03:24Z",
-    "traceId": "3f9c…", "jobKey": "8a1d…", "folderKey": "f-1001", "source": "10",
-    "policyId": "ISO42001-guardrail-prompt-injection", "policyName": "AI system impact assessment",
-    "packName": "ISO/IEC 42001:2023 Runtime", "hook": "BEFORE_MODEL",
-    "mode": "ENFORCE", "actionApplied": "BLOCK", "evaluatorResult": "DENY",
-    "reason": "Prompt injection was detected with a probability of 0.97.",
-    "agentId": "af12…", "agentName": "customer-care-assistant-for-acmecare"
-  }]
-}
-```
+## Semantics the JSDoc lacks
 
-Semantics — the traps:
-- **`evaluatorResult === AgentGovernanceVerdict.Deny` IS the violation.** `mode` (`AUDIT`/`ENFORCE`) says whether it was enforced; `actionApplied` is the enforcement action string (`null` in audit mode). Compare enum fields with the imported enums — `d.evaluatorResult === 'DENY'` is a tsc error.
-- **No server-side `traceId` filter.** Per-run views fetch the window and filter client-side on the row's `traceId`. `agentId` (agent project key) IS a server-side filter.
-- `violationsOnly: true` → Deny rows only. Use for violation tables and violation drill-downs.
+- Widget routing: violation widgets read `violationCount` / `violations`; all-checks widgets read `count` / `total`.
+- **No server-side `traceId` filter** on `getGovernanceDecisions`. Per-run views fetch the window and filter client-side on the row's `traceId`.
 - One agent run = one `traceId` (with its `jobKey`); group rows by `traceId` for run-level rollups.
 - Rows are TS interfaces — project with `.map(x => ({ ...x }))`, never `as` casts.
 - User vocabulary maps onto the response fields: "rule" → **policy** (`policyId`/`policyName`), "standard" → **pack** (`packName`), "violation" → **Deny verdict**, "enforcement action" → **actionApplied**, "audit vs enforce" → **mode**.

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

@@ -1,52 +1,12 @@
 # Governance (Insights RTM) Reference
 
-> Requires `@uipath/uipath-typescript` **≥ 1.4.1**. Scopes: `Insights Insights.RealTimeData`. Governance endpoints expect an **elevated (org-admin) caller** — `fullOrganization: true` returns 403 without org-admin rights; if a tenant-scoped call 403s, tell the user their account lacks governance access.
+Signatures/params/examples: `dist/governance/index.d.ts`. Per-method scopes: shipped `docs/oauth-scopes.md`. This file covers only what neither can express.
 
-```typescript
-import { Governance, PolicyEvaluationResult } from '@uipath/uipath-typescript/governance';
-const svc = new Governance(sdk)
-```
-
-Both methods take a **required positional `startTime: Date`** first; everything else lives in the options object.
-
-## getPolicyTraces(startTime: Date, options?)
-
-Per-policy enforcement decisions, one row per policy verdict per event (one user action can yield multiple rows). Ordered by event start time desc. Returns `NonPaginatedResponse<GovernancePolicyTrace>` (or paginated). **Rows are on `.items`.**
-
-Options (`GovernancePolicyTraceGetAllOptions`): `endTime?: Date`, `fullOrganization?: boolean`, `evaluationResult?: PolicyEvaluationResult[]`, `policyId?: string[]`, `actorProcessId?: string[]`, `actorProcessType?: string[]`, `actorIdentityId?: string[]`, `resourceId?: string[]`, `resourceType?: string[]`, `traceId?: string[]` + pagination. Filters AND across fields, OR within an array.
-
-`PolicyEvaluationResult` enum: `Allow`, `Deny`, `SimulatedAllow`, `SimulatedDeny`.
+This service answers the **platform governance** question — policy enforcement verdicts (allow/deny) on user and agent actions across the platform. For **agentic runtime governance** (per-hook policy checks inside agent runs — standards packs, rule violations) → [`sdk/governance-traces.md`](governance-traces.md), a different domain.
 
-`GovernancePolicyTrace` fields: `tenantId`, `startTime`, `finalEnforcement`, `policyId`, `policyEnforcement`, `policyEvaluationResult`, `policyName`, `policyStatus`, `policyEvaluationDetails`, `actorProcessId`, `actorProcessType`, `actorIdentityId`, `resourceId`, `resourceType`, `folderKey`, `traceId`, `processKey`, `jobKey`. All optional except `startTime`.
-
-**Example response** (`.items` — shape from SDK test fixtures):
-
-```json
-{
-  "items": [
-    {
-      "tenantId": "t-2298", "startTime": "2026-06-10T14:03:22Z",
-      "finalEnforcement": "Deny", "policyId": "pol-7f3a", "policyEnforcement": "Deny",
-      "policyEvaluationResult": "Deny", "policyName": "Block external LLM calls",
-      "policyStatus": "Active", "actorProcessId": "InvoiceTriageAgent",
-      "actorProcessType": "CodedAgent", "actorIdentityId": "user-91",
-      "resourceId": "openai.com", "resourceType": "ExternalService",
-      "folderKey": "f-1001", "traceId": "tr-...", "processKey": "p-0088", "jobKey": "j-..."
-    }
-  ],
-  "count": 1
-}
-```
-
-## getOperationSummary(startTime: Date, options?)
-
-Aggregate enforcement counts for the window. Options: `{ endTime?: Date, fullOrganization?: boolean }`. Returns a **single object — not an array**:
-
-```json
-{ "totalEvaluations": 1240, "allowedCount": 1180, "deniedCount": 42, "noOpCount": 18 }
-```
+On a 403 (org-admin gating — see the `fullOrganization` JSDoc): tell the user their account lacks governance access; do not retry.
 
-> **Semantics:** the SDK maps raw `allow`/`deny`/`noOp` → `allowedCount`/`deniedCount`/`noOpCount`. For a kpi-card or donut, the `fnBody` must wrap/transform the object into a row array (see patterns). No policy UUID is required — this summarizes all policies.
+`getOperationSummary` returns a **single object — not an array**. For a kpi-card or donut, the `fnBody` must wrap/transform it into a row array (see patterns).
 
 ## fnBody patterns