feat(governance): add Governance getPolicyTraces service

docs/oauth-scopes.md

@@ -194,6 +194,12 @@ The `ConversationalAgents` scope is required for real-time WebSocket sessions (`
 | `getById()` | `Traces.Api` |
 | `getSpansByIds()` | `Traces.Api` |
 
+## Governance
+
+| Method | OAuth Scope |
+|--------|-------------|
+| `getPolicyTraces()` | `Insights.RealTimeData Insights OR.Folders.Read` |
+
 ## Processes
 
 | Method | OAuth Scope |

docs/pagination.md

@@ -136,3 +136,4 @@ console.log(`Total count: ${allAssets.totalCount}`);
 | Feedback | `getCategories()` | ✅ Yes |
 | Traces | `getById()` | ❌ No |
 | Traces | `getSpansByIds()` | ❌ No |
+| Governance | `getPolicyTraces()` | ✅ Yes |

mkdocs.yml

@@ -195,6 +195,7 @@ nav:
           - Entities:
             - api/interfaces/entity/index.md
             - Choice Sets: api/interfaces/ChoiceSetServiceModel.md
+          - Governance: api/interfaces/GovernanceServiceModel.md
           - Maestro:
             - Processes: api/interfaces/MaestroProcessesServiceModel.md
             - Process Instances: api/interfaces/ProcessInstancesServiceModel.md

package.json

@@ -175,6 +175,16 @@
                 "types": "./dist/document-understanding/index.d.ts",
                 "default": "./dist/document-understanding/index.cjs"
             }
+        },
+        "./governance": {
+            "import": {
+                "types": "./dist/governance/index.d.ts",
+                "default": "./dist/governance/index.mjs"
+            },
+            "require": {
+                "types": "./dist/governance/index.d.ts",
+                "default": "./dist/governance/index.cjs"
+            }
         }
     },
     "files": [

rollup.config.js

@@ -208,6 +208,11 @@ const serviceEntries = [
     name: 'document-understanding',
     input: 'src/models/document-understanding/index.ts',
     output: 'document-understanding/index'
+  },
+  {
+    name: 'governance',
+    input: 'src/services/governance/index.ts',
+    output: 'governance/index'
   }
 ];
 

src/index.ts

@@ -18,6 +18,7 @@ export * from './models/action-center';
 export * from './models/conversational-agent';
 export * from './models/agents';
 export * from './models/document-understanding';
+export * from './models/governance';
 
 // Export error handling functionality (public API only)
 export * from './core/errors';

src/models/governance/governance.internal-types.ts

@@ -0,0 +1,23 @@
+/**
+ * Raw policy evaluation trace item as returned by API before transformation.
+ */
+export interface RawGovernancePolicyTraceItem {
+  tenantId?: string;
+  startTime: string;
+  finalEnforcement?: string;
+  policyId?: string;
+  policyEnforcement?: string;
+  policyEvaluationResult?: string;
+  policyName?: string;
+  policyStatus?: string;
+  policyEvaluationDetails?: string;
+  actorProcessId?: string;
+  actorProcessType?: string;
+  actorIdentityId?: string;
+  resourceId?: string;
+  resourceType?: string;
+  folderKey?: string;
+  traceId?: string;
+  processKey?: string;
+  jobKey?: string;
+}

src/models/governance/governance.models.ts

@@ -0,0 +1,81 @@
+import type {
+  GovernancePolicyTrace,
+  GovernancePolicyTraceGetAllOptions,
+} from './governance.types';
+import type {
+  PaginatedResponse,
+  NonPaginatedResponse,
+  HasPaginationOptions,
+} from '../../utils/pagination';
+
+/**
+ * Service for inspecting governance policy enforcement on the UiPath platform.
+ *
+ * See [Define governance policies](https://docs.uipath.com/automation-ops/automation-cloud/latest/user-guide/define-governance-policies)
+ * for how governance policies are configured in Automation Ops.
+ *
+ * All methods require the caller to be an organization administrator.
+ *
+ * ### Usage
+ *
+ * Prerequisites: Initialize the SDK first - see [Getting Started](/uipath-typescript/getting-started/#import-initialize)
+ *
+ * ```typescript
+ * import { Governance } from '@uipath/uipath-typescript/governance';
+ *
+ * const governance = new Governance(sdk);
+ * const traces = await governance.getPolicyTraces(new Date('2024-01-01'));
+ * ```
+ */
+export interface GovernanceServiceModel {
+  /**
+   * Gets per-policy enforcement decisions across the requested time range.
+   *
+   * Each result row represents one policy's verdict within a single governance enforcement event.
+   * A single user action can produce multiple rows when multiple policies were consulted.
+   * Results are ordered by event start time, descending.
+   *
+   * @param startTime - Inclusive lower bound on the trace start time.
+   * @param options - Optional filters and pagination options
+   * @returns Promise resolving to {@link NonPaginatedResponse} of {@link GovernancePolicyTrace}
+   *          without pagination options, or {@link PaginatedResponse} of
+   *          {@link GovernancePolicyTrace} when pagination options are used.
+   *
+   * @example
+   * ```typescript
+   * import { Governance, PolicyEvaluationResult } from '@uipath/uipath-typescript/governance';
+   *
+   * const governance = new Governance(sdk);
+   *
+   * // Get all policy traces from the specified start time
+   * const recent = await governance.getPolicyTraces(new Date('2024-01-01'));
+   * console.log(recent.items.length);
+   *
+   * // Get all denied decisions across the whole organization
+   * const page1 = await governance.getPolicyTraces(
+   *   new Date('2024-01-01'),
+   *   {
+   *     endTime: new Date(),
+   *     evaluationResult: [PolicyEvaluationResult.Deny, PolicyEvaluationResult.SimulatedDeny],
+   *     fullOrganization: true,
+   *     pageSize: 25,
+   *   },
+   * );
+   *
+   * if (page1.hasNextPage) {
+   *   const page2 = await governance.getPolicyTraces(
+   *     new Date('2024-01-01'),
+   *     { cursor: page1.nextCursor },
+   *   );
+   * }
+   * ```
+   */
+  getPolicyTraces<T extends GovernancePolicyTraceGetAllOptions = GovernancePolicyTraceGetAllOptions>(
+    startTime: Date,
+    options?: T,
+  ): Promise<
+    T extends HasPaginationOptions<T>
+      ? PaginatedResponse<GovernancePolicyTrace>
+      : NonPaginatedResponse<GovernancePolicyTrace>
+  >;
+}

src/models/governance/governance.types.ts

@@ -0,0 +1,113 @@
+/**
+ * Governance Service Types
+ *
+ * Public types exposed via `@uipath/uipath-typescript/governance`.
+ */
+
+import { PaginationOptions } from '../../utils/pagination/types';
+
+export enum PolicyEvaluationResult {
+  /** Active policy permitted the action. */
+  Allow = 'Allow',
+  /** Active policy blocked the action. */
+  Deny = 'Deny',
+  /** Simulated (NoOp) policy would have permitted the action. */
+  SimulatedAllow = 'SimulatedAllow',
+  /** Simulated (NoOp) policy would have blocked the action. */
+  SimulatedDeny = 'SimulatedDeny',
+}
+
+/**
+ * Each trace row represents one policy's verdict within a governance
+ * enforcement event. One enforcement event can produce multiple trace rows
+ * when multiple policies contributed to the final verdict.
+ */
+export interface GovernancePolicyTrace {
+  /** Tenant the trace was recorded in. Present even when `fullOrganization` is `true`. */
+  tenantId?: string;
+  /** The start time of governance enforcement event. */
+  startTime: string;
+  /** Final enforcement verdict for the parent governance event. */
+  finalEnforcement?: string;
+  /** ID of the policy this trace row evaluates. */
+  policyId?: string;
+  /** This individual policy's enforcement contribution to the parent verdict. */
+  policyEnforcement?: string;
+  /** The outcome of one policy evaluation — whether it allowed or denied the action, and whether that decision was actively enforced or just simulated (NoOp). */
+  policyEvaluationResult?: string;
+  /** Display name of the policy. */
+  policyName?: string;
+  /** Enforcement mode of the policy at the time of evaluation. */
+  policyStatus?: string;
+  /** Opaque details payload describing the evaluation result. */
+  policyEvaluationDetails?: string;
+  /** Process or executable that triggered the evaluation. */
+  actorProcessId?: string;
+  /** Type of the actor process (e.g. coded agent, RPA process). */
+  actorProcessType?: string;
+  /** Identity (user/principal) that triggered the evaluation. */
+  actorIdentityId?: string;
+  /** Resource being acted on. */
+  resourceId?: string;
+  /** Type of the resource being acted on. */
+  resourceType?: string;
+  /** Orchestrator folder key associated with the evaluation, if any. */
+  folderKey?: string;
+  /** Distributed-tracing ID covering the governance enforcement event. */
+  traceId?: string;
+  /** Process key associated with the evaluation, if any. */
+  processKey?: string;
+  /** Job key associated with the evaluation, if any. */
+  jobKey?: string;
+}
+
+/**
+ * Common filter options shared across Governance APIs.
+ *
+ * Holds filters that are not specific to any single governance resource, so
+ * other governance endpoints can reuse them.
+ */
+export interface GovernanceFilterOptions {
+  /**
+   * Inclusive upper bound on trace start time. When omitted, the upper bound
+   * is open. 
+   */
+  endTime?: Date;
+  /**
+   * Whether to query the whole organization instead of just the current tenant.
+   *
+   * Defaults to tenant-scoped:
+   * - omitted → tenant-scoped (default)
+   * - `false` → tenant-scoped (explicit, same result)
+   * - `true` → org-wide across all tenants; requires an organization admin,
+   *   otherwise the request returns 403
+   *
+   * @default false
+   */
+  fullOrganization?: boolean;
+}
+
+/**
+ * Filter and pagination options for fetching policy traces.
+ *
+ * All filters combine with AND semantics. Array filters match any value in
+ * the array (OR within a single filter).
+ */
+export type GovernancePolicyTraceGetAllOptions = PaginationOptions & GovernanceFilterOptions & {
+  /** Filter by one or more policy evaluation results. */
+  evaluationResult?: PolicyEvaluationResult[];
+  /** Filter by one or more policy IDs. */
+  policyId?: string[];
+  /** Filter by one or more actor process IDs. */
+  actorProcessId?: string[];
+  /** Filter by one or more actor process types (e.g. coded agent, RPA process). */
+  actorProcessType?: string[];
+  /** Filter by one or more actor identity IDs. */
+  actorIdentityId?: string[];
+  /** Filter by one or more resource IDs. */
+  resourceId?: string[];
+  /** Filter by one or more resource types. */
+  resourceType?: string[];
+  /** Filter by one or more distributed-trace IDs. */
+  traceId?: string[];
+};

src/models/governance/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Governance Types
+ *
+ * Public type surface for the Governance service.
+ */
+
+export * from './governance.types';
+export * from './governance.models';

src/services/base.ts

@@ -218,7 +218,7 @@
   /**
    * Prepares request parameters for pagination based on pagination type
    */
   private preparePaginationRequestParams(
     paginationType: PaginationType,
     params: InternalPaginationOptions,
     paginationConfig?: RequestWithPaginationOptions['pagination']
@@ -237,14 +237,17 @@
         // When true (default), converts pageNumber to a skip/offset value (e.g., page 3 with pageSize 10 → skip 20).
         // When false, passes pageNumber directly as the offset param — used by APIs that accept a page number instead of a record offset.
         const convertToSkip = paginationParams?.convertToSkip ?? true;
+        // When true, sends pageNumber - 1 (for 0-based APIs). Default false (1-based).
+        const zeroBased = paginationParams?.zeroBased ?? false;
 
         requestParams[pageSizeParam] = limitedPageSize;
         if (convertToSkip) {
           if (params.pageNumber && params.pageNumber > 1) {
             requestParams[offsetParam] = (params.pageNumber - 1) * limitedPageSize;
           }
         } else {
-          requestParams[offsetParam] = params.pageNumber || 1;
+          const sdkPageNumber = params.pageNumber || 1;
+          requestParams[offsetParam] = zeroBased ? sdkPageNumber - 1 : sdkPageNumber;
         }
         if (countParam) {
           requestParams[countParam] = true;