@uipath/uipath-typescript 1.5.0 → 1.5.1

package/dist/traces/index.d.ts

@@ -674,33 +674,33 @@ interface AgentSpanGetResponse {
     status: string;
     /** Organization ID (GUID). */
     organizationId: string;
-    /** Tenant ID (GUID). May be `null`. */
+    /** Tenant ID (GUID). */
     tenantId: string | null;
-    /** Span retention expiry time. May be `null`. */
+    /** Span retention expiry time. */
     expiredTime: string | null;
-    /** Folder key (GUID) the span was recorded in. May be `null`. */
+    /** Folder key (GUID) the span was recorded in. */
     folderKey: string | null;
-    /** Span source. May be `null`. */
+    /** Span source. */
     source: string | null;
-    /** Span type. May be `null`. */
+    /** Span type. */
     spanType: string | null;
-    /** Process key (GUID). May be `null`. */
+    /** Process key (GUID). */
     processKey: string | null;
-    /** Job key (GUID). May be `null`. */
+    /** Job key (GUID). */
     jobKey: string | null;
-    /** Reference ID (GUID). May be `null`. */
+    /** Reference ID (GUID). */
     referenceId: string | null;
-    /** Verbosity level. May be `null`. */
+    /** Verbosity level. */
     verbosityLevel: string | null;
     /** Record last-updated time. */
     updatedAt: string;
     /** Whether the span payload is stored as a large payload. */
     isLargePayload: boolean;
-    /** Payload compression type. May be `null`. */
+    /** Payload compression type. */
     compressionType: string | null;
-    /** Agent version that produced the span. May be `null`. */
+    /** Agent version that produced the span. */
     agentVersion: string | null;
-    /** Raw span context as a JSON string. May be `null`. */
+    /** Raw span context as a JSON string. */
     context: string | null;
 }
 /**
@@ -722,6 +722,153 @@ type AgentTraceGetSpansByReferenceOptions = PaginationOptions & {
     /** Execution type filter */
     executionType?: SpanExecutionType;
 };
+/**
+ * Evaluation mode of a governance decision.
+ */
+declare enum AgentGovernanceMode {
+    /** Policy evaluated and logged, but not enforced. */
+    Audit = "AUDIT",
+    /** Policy evaluated and enforced. */
+    Enforce = "ENFORCE",
+    /** Unrecognized or missing mode. */
+    Unknown = "Unknown"
+}
+/**
+ * Verdict of a governance decision (`Deny` = violation).
+ */
+declare enum AgentGovernanceVerdict {
+    /** Allowed — not a violation. */
+    Allow = "ALLOW",
+    /** Denied — counts as a violation. */
+    Deny = "DENY",
+    /** Unrecognized or missing verdict. */
+    Unknown = "Unknown"
+}
+/**
+ * A single governance decision — one policy's allow/deny result for an agent run.
+ */
+interface AgentGovernanceDecisionGetResponse {
+    /** Tenant ID (GUID). */
+    tenantId: string | null;
+    /** Decision window start time — ISO 8601, UTC. */
+    startTime: string;
+    /** Decision window end time — ISO 8601, UTC. */
+    endTime: string | null;
+    /** Trace ID (GUID). */
+    traceId: string | null;
+    /** Job key (GUID). */
+    jobKey: string | null;
+    /** Folder key (GUID). */
+    folderKey: string | null;
+    /** Runtime the evaluator ran in (context, not a filter). */
+    source: string | null;
+    /** Policy ID. */
+    policyId: string | null;
+    /** Policy display name. */
+    policyName: string | null;
+    /** Governance pack name. */
+    packName: string | null;
+    /** Governance hook (e.g. `BEFORE_MODEL`). */
+    hook: string | null;
+    /** Evaluation mode, normalized to {@link AgentGovernanceMode} ({@link AgentGovernanceMode.Unknown} when missing/unrecognized). */
+    mode: AgentGovernanceMode;
+    /** Enforcement action applied. `null` in audit mode (no action enforced). */
+    actionApplied: string | null;
+    /** Verdict, normalized to {@link AgentGovernanceVerdict} (`Deny` = violation). */
+    evaluatorResult: AgentGovernanceVerdict;
+    /** Human-readable reason. */
+    reason: string | null;
+    /** Resolved agent ID (GUID). */
+    agentId: string | null;
+    /** Agent display name. */
+    agentName: string | null;
+}
+/**
+ * Options for the governance decisions query — optional filters plus pagination.
+ */
+type AgentGovernanceDecisionsOptions = PaginationOptions & {
+    /** Inclusive upper bound for the query window. Defaults to now when omitted. */
+    endTime?: Date;
+    /** Filter on the governance hook. */
+    hook?: string;
+    /** Filter on the verdict. */
+    evaluatorResult?: AgentGovernanceVerdict;
+    /** Filter on a single policy ID. */
+    policyId?: string;
+    /** Filter on a single agent by its project key. */
+    agentId?: string;
+    /** When `true`, restrict to violations (deny verdicts). */
+    violationsOnly?: boolean;
+};
+/**
+ * One breakdown entry in the governance summary — counts for a single key.
+ */
+interface AgentGovernanceCountItem {
+    /** The value this row groups by — the distinct hook, agent id, policy id, or pack name for this breakdown. */
+    key: string | null;
+    /** Display name (populated for the policy and agent breakdowns). */
+    name: string | null;
+    /** Number of decisions for this key. */
+    count: number;
+    /** Number of violations (deny verdicts) for this key. */
+    violationCount: number;
+}
+/**
+ * Sections the governance summary can compute. `action` and `mode` are opt-in.
+ */
+declare enum AgentGovernanceSection {
+    /** Scalar totals (`total`, `violations`). */
+    Totals = "totals",
+    /** Breakdown by governance hook. */
+    Hook = "hook",
+    /** Breakdown by agent. */
+    Agent = "agent",
+    /** Breakdown by policy. */
+    Policy = "policy",
+    /** Breakdown by governance pack. */
+    Pack = "pack",
+    /** Breakdown by enforcement action (opt-in). */
+    Action = "action",
+    /** Breakdown by evaluation mode (opt-in). */
+    Mode = "mode"
+}
+/**
+ * Aggregated governance posture over the requested window.
+ */
+interface AgentGovernanceGetSummaryResponse {
+    /** Total decisions in the window. */
+    total: number;
+    /** Total violations (deny verdicts). */
+    violations: number;
+    /** Breakdown by governance hook. */
+    byHook: AgentGovernanceCountItem[];
+    /** Breakdown by agent. */
+    byAgent: AgentGovernanceCountItem[];
+    /** Breakdown by policy. */
+    byPolicy: AgentGovernanceCountItem[];
+    /** Breakdown by governance pack. */
+    byPack: AgentGovernanceCountItem[];
+    /** Breakdown by enforcement action. Empty unless `action` is requested in `sections`. */
+    byAction: AgentGovernanceCountItem[];
+    /** Breakdown by evaluation mode. Empty unless `mode` is requested in `sections`. */
+    byMode: AgentGovernanceCountItem[];
+}
+/**
+ * Options for the governance summary.
+ */
+interface AgentGovernanceSummaryOptions {
+    /** Inclusive upper bound for the query window. Defaults to now when omitted. */
+    endTime?: Date;
+    /** Top-N size for each breakdown. */
+    topN?: number;
+    /** Restrict totals and breakdowns to a single governance pack. */
+    packName?: string;
+    /**
+     * Which sections to compute. Omit for the default set
+     * (`totals`, `hook`, `agent`, `policy`, `pack`); `action` and `mode` are opt-in.
+     */
+    sections?: AgentGovernanceSection[];
+}
 
 /**
  * Service for retrieving UiPath Agent trace metrics.
@@ -844,10 +991,6 @@ interface AgentTracesServiceModel {
     /**
      * Retrieves spans whose reference hierarchy contains the given reference id.
      *
-     * Returns a {@link PaginatedResponse} when pagination options (`pageSize`,
-     * `cursor`, or `jumpToPage`) are provided, otherwise a
-     * {@link NonPaginatedResponse}.
-     *
      * @param referenceId - Reference id matched against each span's reference hierarchy
      * @param options - Optional pagination and hierarchy/time filters
      * @returns Promise resolving to a paginated or non-paginated list of {@link AgentSpanGetResponse}
@@ -880,6 +1023,104 @@ interface AgentTracesServiceModel {
      * ```
      */
     getSpansByReference<T extends AgentTraceGetSpansByReferenceOptions = AgentTraceGetSpansByReferenceOptions>(referenceId: string, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<AgentSpanGetResponse> : NonPaginatedResponse<AgentSpanGetResponse>>;
+    /**
+     * Lists individual governance decisions from agent execution traces — each
+     * policy check's allow/deny outcome with its agent, policy, pack, hook, and
+     * mode, plus the trace it belongs to — over the requested window. Filterable
+     * and paginated.
+     *
+     * @remarks Requires the caller to be an organization admin. Non-admin callers get a `403` and the SDK throws an {@link AuthorizationError}.
+     *
+     * @param startTime - Inclusive lower bound for the query window
+     * @param options - Optional window end, filters, and pagination
+     * @returns Promise resolving to a paginated or non-paginated list of {@link AgentGovernanceDecisionGetResponse}
+     * @example
+     * ```typescript
+     * import { AgentTraces } from '@uipath/uipath-typescript/traces';
+     *
+     * const trace = new AgentTraces(sdk);
+     *
+     * // Decision rows since a start time
+     * const result = await trace.getGovernanceDecisions(new Date('2025-05-01T00:00:00Z'));
+     * result.items.forEach((row) => {
+     *   console.log(`${row.hook} ${row.policyId}: ${row.evaluatorResult}`);
+     * });
+     * ```
+     * @example
+     * ```typescript
+     * // Violations only, for one agent, paginated
+     * const page = await trace.getGovernanceDecisions(new Date('2025-05-01T00:00:00Z'), {
+     *   endTime: new Date('2025-06-01T00:00:00Z'),
+     *   violationsOnly: true,
+     *   agentId: '<agentProjectKey>',
+     *   pageSize: 25,
+     * });
+     * if (page.hasNextPage && page.nextCursor) {
+     *   const next = await trace.getGovernanceDecisions(new Date('2025-05-01T00:00:00Z'), { cursor: page.nextCursor });
+     * }
+     * ```
+     * @example
+     * ```typescript
+     * import { isAuthorizationError } from '@uipath/uipath-typescript/core';
+     *
+     * // Non-admin callers get a 403
+     * try {
+     *   await trace.getGovernanceDecisions(new Date('2025-05-01T00:00:00Z'));
+     * } catch (error) {
+     *   if (isAuthorizationError(error)) {
+     *     console.error('Governance data requires an organization admin.');
+     *   }
+     * }
+     * ```
+     */
+    getGovernanceDecisions<T extends AgentGovernanceDecisionsOptions = AgentGovernanceDecisionsOptions>(startTime: Date, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<AgentGovernanceDecisionGetResponse> : NonPaginatedResponse<AgentGovernanceDecisionGetResponse>>;
+    /**
+     * Summarizes governance decisions across agent execution traces — total
+     * decisions and violations, plus top breakdowns by hook, agent, policy, and
+     * pack — over the requested window. Filterable.
+     *
+     * @remarks Requires the caller to be an organization admin. Non-admin callers get a `403` and the SDK throws an {@link AuthorizationError}.
+     *
+     * @param startTime - Inclusive lower bound for the query window
+     * @param options - Optional window end, top-N, pack scope, and sections
+     * @returns Promise resolving to {@link AgentGovernanceGetSummaryResponse}
+     * @example
+     * ```typescript
+     * import { AgentTraces } from '@uipath/uipath-typescript/traces';
+     *
+     * const trace = new AgentTraces(sdk);
+     *
+     * // Default posture since a start time
+     * const summary = await trace.getGovernanceSummary(new Date('2025-05-01T00:00:00Z'));
+     * console.log(`${summary.violations} / ${summary.total} violations`);
+     * summary.byPolicy.forEach((p) => console.log(`${p.key}: ${p.violationCount}`));
+     * ```
+     * @example
+     * ```typescript
+     * import { AgentGovernanceSection } from '@uipath/uipath-typescript/traces';
+     *
+     * // Top 5 per breakdown, scoped to a pack, including the opt-in action/mode sections
+     * const summary = await trace.getGovernanceSummary(new Date('2025-05-01T00:00:00Z'), {
+     *   topN: 5,
+     *   packName: 'ISO/IEC 42001:2023 Runtime',
+     *   sections: [AgentGovernanceSection.Action, AgentGovernanceSection.Mode],
+     * });
+     * ```
+     * @example
+     * ```typescript
+     * import { isAuthorizationError } from '@uipath/uipath-typescript/core';
+     *
+     * // Non-admin callers get a 403
+     * try {
+     *   await trace.getGovernanceSummary(new Date('2025-05-01T00:00:00Z'));
+     * } catch (error) {
+     *   if (isAuthorizationError(error)) {
+     *     console.error('Governance data requires an organization admin.');
+     *   }
+     * }
+     * ```
+     */
+    getGovernanceSummary(startTime: Date, options?: AgentGovernanceSummaryOptions): Promise<AgentGovernanceGetSummaryResponse>;
 }
 
 /**
@@ -1003,10 +1244,6 @@ declare class AgentTracesService extends BaseService implements AgentTracesServi
     /**
      * Retrieves spans whose reference hierarchy contains the given reference id.
      *
-     * Returns a {@link PaginatedResponse} when pagination options (`pageSize`,
-     * `cursor`, or `jumpToPage`) are provided, otherwise a
-     * {@link NonPaginatedResponse}.
-     *
      * @param referenceId - Reference id matched against each span's reference hierarchy
      * @param options - Optional pagination and hierarchy/time filters
      * @returns Promise resolving to a paginated or non-paginated list of {@link AgentSpanGetResponse}
@@ -1039,8 +1276,106 @@ declare class AgentTracesService extends BaseService implements AgentTracesServi
      * ```
      */
     getSpansByReference<T extends AgentTraceGetSpansByReferenceOptions = AgentTraceGetSpansByReferenceOptions>(referenceId: string, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<AgentSpanGetResponse> : NonPaginatedResponse<AgentSpanGetResponse>>;
+    /**
+     * Lists individual governance decisions from agent execution traces — each
+     * policy check's allow/deny outcome with its agent, policy, pack, hook, and
+     * mode, plus the trace it belongs to — over the requested window. Filterable
+     * and paginated.
+     *
+     * @remarks Requires the caller to be an organization admin. Non-admin callers get a `403` and the SDK throws an {@link AuthorizationError}.
+     *
+     * @param startTime - Inclusive lower bound for the query window
+     * @param options - Optional window end, filters, and pagination
+     * @returns Promise resolving to a paginated or non-paginated list of {@link AgentGovernanceDecisionGetResponse}
+     * @example
+     * ```typescript
+     * import { AgentTraces } from '@uipath/uipath-typescript/traces';
+     *
+     * const trace = new AgentTraces(sdk);
+     *
+     * // Decision rows since a start time
+     * const result = await trace.getGovernanceDecisions(new Date('2025-05-01T00:00:00Z'));
+     * result.items.forEach((row) => {
+     *   console.log(`${row.hook} ${row.policyId}: ${row.evaluatorResult}`);
+     * });
+     * ```
+     * @example
+     * ```typescript
+     * // Violations only, for one agent, paginated
+     * const page = await trace.getGovernanceDecisions(new Date('2025-05-01T00:00:00Z'), {
+     *   endTime: new Date('2025-06-01T00:00:00Z'),
+     *   violationsOnly: true,
+     *   agentId: '<agentProjectKey>',
+     *   pageSize: 25,
+     * });
+     * if (page.hasNextPage && page.nextCursor) {
+     *   const next = await trace.getGovernanceDecisions(new Date('2025-05-01T00:00:00Z'), { cursor: page.nextCursor });
+     * }
+     * ```
+     * @example
+     * ```typescript
+     * import { isAuthorizationError } from '@uipath/uipath-typescript/core';
+     *
+     * // Non-admin callers get a 403
+     * try {
+     *   await trace.getGovernanceDecisions(new Date('2025-05-01T00:00:00Z'));
+     * } catch (error) {
+     *   if (isAuthorizationError(error)) {
+     *     console.error('Governance data requires an organization admin.');
+     *   }
+     * }
+     * ```
+     */
+    getGovernanceDecisions<T extends AgentGovernanceDecisionsOptions = AgentGovernanceDecisionsOptions>(startTime: Date, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<AgentGovernanceDecisionGetResponse> : NonPaginatedResponse<AgentGovernanceDecisionGetResponse>>;
+    /**
+     * Summarizes governance decisions across agent execution traces — total
+     * decisions and violations, plus top breakdowns by hook, agent, policy, and
+     * pack — over the requested window. Filterable.
+     *
+     * @remarks Requires the caller to be an organization admin. Non-admin callers get a `403` and the SDK throws an {@link AuthorizationError}.
+     *
+     * @param startTime - Inclusive lower bound for the query window
+     * @param options - Optional window end, top-N, pack scope, and sections
+     * @returns Promise resolving to {@link AgentGovernanceGetSummaryResponse}
+     * @example
+     * ```typescript
+     * import { AgentTraces } from '@uipath/uipath-typescript/traces';
+     *
+     * const trace = new AgentTraces(sdk);
+     *
+     * // Default posture since a start time
+     * const summary = await trace.getGovernanceSummary(new Date('2025-05-01T00:00:00Z'));
+     * console.log(`${summary.violations} / ${summary.total} violations`);
+     * summary.byPolicy.forEach((p) => console.log(`${p.key}: ${p.violationCount}`));
+     * ```
+     * @example
+     * ```typescript
+     * import { AgentGovernanceSection } from '@uipath/uipath-typescript/traces';
+     *
+     * // Top 5 per breakdown, scoped to a pack, including the opt-in action/mode sections
+     * const summary = await trace.getGovernanceSummary(new Date('2025-05-01T00:00:00Z'), {
+     *   topN: 5,
+     *   packName: 'ISO/IEC 42001:2023 Runtime',
+     *   sections: [AgentGovernanceSection.Action, AgentGovernanceSection.Mode],
+     * });
+     * ```
+     * @example
+     * ```typescript
+     * import { isAuthorizationError } from '@uipath/uipath-typescript/core';
+     *
+     * // Non-admin callers get a 403
+     * try {
+     *   await trace.getGovernanceSummary(new Date('2025-05-01T00:00:00Z'));
+     * } catch (error) {
+     *   if (isAuthorizationError(error)) {
+     *     console.error('Governance data requires an organization admin.');
+     *   }
+     * }
+     * ```
+     */
+    getGovernanceSummary(startTime: Date, options?: AgentGovernanceSummaryOptions): Promise<AgentGovernanceGetSummaryResponse>;
     private buildTraceFilterBody;
 }
 
-export { SpanExecutionType as AgentTraceExecutionType, AgentTracesService as AgentTraces, SpanAttachmentDirection, SpanAttachmentProvider, SpanExecutionType, SpanPermissionStatus, SpanSource, SpanStatus, SpanVerbosityLevel, TracesService as Traces };
-export type { AgentSpanGetResponse, AgentTraceFilterOptions, AgentTraceGetErrorsTimelineOptions, AgentTraceGetErrorsTimelineResponse, AgentTraceGetLatencyTimelineOptions, AgentTraceGetLatencyTimelineResponse, AgentTraceGetSpansByReferenceOptions, AgentTraceGetUnitConsumptionOptions, AgentTraceGetUnitConsumptionResponse, AgentTracesServiceModel, SpanAttachment, SpanContext, SpanGetResponse, SpanReferenceHierarchyEntry, TracesGetByIdOptions, TracesServiceModel };
+export { AgentGovernanceMode, AgentGovernanceSection, AgentGovernanceVerdict, SpanExecutionType as AgentTraceExecutionType, AgentTracesService as AgentTraces, SpanAttachmentDirection, SpanAttachmentProvider, SpanExecutionType, SpanPermissionStatus, SpanSource, SpanStatus, SpanVerbosityLevel, TracesService as Traces };
+export type { AgentGovernanceCountItem, AgentGovernanceDecisionGetResponse, AgentGovernanceDecisionsOptions, AgentGovernanceGetSummaryResponse, AgentGovernanceSummaryOptions, AgentSpanGetResponse, AgentTraceFilterOptions, AgentTraceGetErrorsTimelineOptions, AgentTraceGetErrorsTimelineResponse, AgentTraceGetLatencyTimelineOptions, AgentTraceGetLatencyTimelineResponse, AgentTraceGetSpansByReferenceOptions, AgentTraceGetUnitConsumptionOptions, AgentTraceGetUnitConsumptionResponse, AgentTracesServiceModel, SpanAttachment, SpanContext, SpanGetResponse, SpanReferenceHierarchyEntry, TracesGetByIdOptions, TracesServiceModel };