@uipath/maestro-sdk 0.2.0 → 0.9.1

package/dist/src/registry/node-sync-service.d.ts

@@ -0,0 +1,84 @@
+import type { NodeManifest } from "@uipath/flow-core";
+import type { ParsedFilters } from "./types";
+interface PullNodesOptions {
+    force?: boolean;
+}
+interface PullNodesResult {
+    syncedCount: number;
+    fromCache: boolean;
+    ageMinutes?: number;
+    source?: "ootb" | "authenticated";
+    cacheWritten?: boolean;
+    info?: string;
+}
+interface PullRemoteNodesResult {
+    nodes: NodeManifest[];
+    source: "ootb" | "authenticated";
+    cacheable: boolean;
+    info?: string;
+}
+/**
+ * Pull and sync all node sources with smart caching
+ *
+ * Simple caching strategy:
+ * - FRESH (< 30 min): Use cache immediately
+ * - EXPIRED (> 30 min): Must refresh before returning
+ *
+ * @param options - Pull options
+ * @param options.force - Force refresh, ignore cache (default: false)
+ * @returns Result with sync count and cache status
+ */
+export declare function pullNodes(options?: PullNodesOptions): Promise<PullNodesResult>;
+/**
+ * Pull remote nodes from the manifest API
+ * Only pulls if user is logged in
+ * Fetches all nodes (OOTB + remote) from the manifest
+ *
+ * @returns Array of all nodes from manifest
+ */
+export declare function pullRemoteNodes(): Promise<PullRemoteNodesResult>;
+/**
+ * List cached nodes, falling back to live OOTB nodes if no cache exists.
+ * With `--local`, returns only in-solution sibling project nodes and throws
+ * when no .uipx solution is found.
+ */
+export declare function listNodes(options?: {
+    local?: boolean;
+}): Promise<NodeManifest[]>;
+/**
+ * Search for nodes by keyword
+ * Searches across nodeType, category, tags, and display.label
+ * Returns all matching nodes
+ */
+export declare function searchNodes(keyword: string, options?: {
+    local?: boolean;
+}): Promise<NodeManifest[]>;
+/**
+ * Pure cache/OOTB node configuration fetch, no extra external call.
+ * @param nodeType
+ * @returns
+ */
+export declare function getNode(nodeType: string, options?: {
+    local?: boolean;
+}): Promise<NodeManifest | null>;
+/**
+ * Get a specific node by nodeType (case-insensitive).
+ * When connectionId is provided, enriches connector nodes with
+ * connection-specific metadata (custom fields, accurate references).
+ */
+export declare function getNodeEnriched(nodeType: string, connectionId?: string, options?: {
+    local?: boolean;
+}): Promise<NodeManifest | null>;
+/**
+ * Search nodes with advanced filtering
+ * Supports both keyword search and structured filters
+ * Uses the aggregated index (all sources)
+ *
+ * @param keyword - Optional keyword to search across all fields
+ * @param filters - Optional structured filter conditions
+ * @returns Array of matching nodes
+ */
+export declare function searchNodesWithFilters(keyword?: string, filters?: ParsedFilters, options?: {
+    local?: boolean;
+}): Promise<NodeManifest[]>;
+export {};

package/dist/src/registry/registry-service.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Maestro Registry Service
+ *
+ * Combines a static BPMN spec (OOTB extension types) with dynamically
+ * discovered resources from Integration Service (connectors, connections,
+ * activities, triggers) and Orchestrator (processes, agents, API workflows).
+ *
+ * Discovery is best-effort: when a particular API call fails the service
+ * logs a warning and continues so the caller always gets at least the
+ * static registry.
+ */
+import type { BpmnExtensionType, DiscoveredConnector, DiscoveredProcess, MaestroRegistry } from "../manifest/types.js";
+export interface PullRegistryOptions {
+    force?: boolean;
+}
+export interface PullRegistryResult {
+    extensionTypeCount: number;
+    connectorCount: number;
+    processCount: number;
+    fromCache: boolean;
+    ageMinutes?: number;
+    cacheWritten: boolean;
+    info?: string;
+}
+/**
+ * Pull (or return cached) the full Maestro registry.
+ *
+ * Cache strategy mirrors the flow-tool:
+ * - FRESH (< 30 min): return cache immediately
+ * - EXPIRED or missing: fetch fresh, write to cache, return
+ * - force=true: always fetch fresh
+ */
+export declare function pullRegistry(options?: PullRegistryOptions): Promise<PullRegistryResult>;
+/**
+ * List the cached registry. Auto-pulls if no cache exists.
+ */
+export declare function getRegistry(): Promise<MaestroRegistry>;
+/**
+ * Search the registry by keyword across extension types and discovered resources.
+ */
+export declare function searchRegistry(keyword: string): Promise<{
+    extensionTypes: BpmnExtensionType[];
+    connectors: DiscoveredConnector[];
+    processes: DiscoveredProcess[];
+}>;
+/**
+ * Get a single extension type by key (case-insensitive).
+ */
+export declare function getExtensionType(extensionType: string): Promise<BpmnExtensionType | null>;
+/**
+ * IS-enriched metadata for a connector activity.
+ *
+ * Calls the IS elements API to get full field metadata for a specific
+ * connector + object + connection combination.
+ */
+export declare function getEnrichedActivityMetadata(objectName: string, connectionId: string): Promise<Record<string, unknown> | null>;

package/dist/src/registry/solution-discovery.d.ts

@@ -0,0 +1,31 @@
+import type { NodeManifest } from "@uipath/flow-core";
+import { type ProjectEntryPointIO } from "@uipath/flow-core/manifest";
+interface UipxProject {
+    Type: string;
+    ProjectRelativePath: string;
+    Id: string;
+}
+export interface SolutionContext {
+    solutionId: string;
+    solutionDir: string;
+    projects: UipxProject[];
+    /** ID of the project that CWD is inside — excluded from results to prevent self-reference */
+    currentProjectId?: string;
+}
+/**
+ * Walk CWD then its parent and grandparent (3 levels) looking for a .uipx file.
+ * Returns null if not inside a solution.
+ */
+export declare function findSolutionFromCwd(): Promise<SolutionContext | null>;
+/**
+ * Read entry-points.json from a project directory.
+ * Tries flat layout first, then content/ subdirectory.
+ */
+export declare function readProjectEntryPointIO(projectDir: string): Promise<ProjectEntryPointIO>;
+/**
+ * Build NodeManifest[] for all invokable sibling projects in the solution.
+ * Non-invokable types (Library, Tests, Connector, etc.) are silently skipped.
+ * The current project (ctx.currentProjectId) is excluded to prevent self-reference.
+ */
+export declare function buildInSolutionNodeManifests(ctx: SolutionContext): Promise<NodeManifest[]>;
+export {};

package/dist/src/registry/storage.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Local file-system cache for the Maestro registry.
+ *
+ * Mirrors the flow-tool's nodeStorage pattern:
+ *   ~/.uipath/maestro/registry.json      — full registry
+ *   ~/.uipath/maestro/registry.meta.json  — lightweight metadata (lastSync, hash, counts)
+ *
+ * 30-minute cache expiration is enforced by the caller (registry service).
+ */
+import type { MaestroRegistry, RegistryMetadata } from "../manifest/types.js";
+/** Cache is considered fresh for 30 minutes. */
+export declare const CACHE_EXPIRATION_MS: number;
+/**
+ * Generate a SHA-256 hex hash of the given string content.
+ */
+export declare function hashContent(content: string): Promise<string>;
+/**
+ * Save the full registry to disk and update the companion metadata file.
+ */
+export declare function saveRegistry(registry: MaestroRegistry): Promise<void>;
+/**
+ * Load the full registry from disk. Returns null if cache does not exist.
+ */
+export declare function loadRegistry(): Promise<MaestroRegistry | null>;
+/**
+ * Load only the lightweight metadata. Returns null if missing.
+ */
+export declare function loadRegistryMetadata(): Promise<RegistryMetadata | null>;

package/dist/src/registry/types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Supported filter fields for node search
+ */
+export type FilterField = "category" | "type" | "tags" | "displayname" | "nodetype" | "description";
+/**
+ * Filter operator types
+ */
+export type FilterOperator = "equals" | "contains" | "in" | "startsWith" | "endsWith";
+/**
+ * Individual filter condition
+ */
+export interface FilterCondition {
+    field: FilterField;
+    operator: FilterOperator;
+    value: string | string[];
+}
+/**
+ * Parse result from filter string
+ */
+export interface ParsedFilters {
+    filters: FilterCondition[];
+    logic: "AND" | "OR";
+}

package/dist/src/shared-commands/incidents.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from "commander";
+export interface IncidentCommandsConfig {
+    /** Label used in command descriptions, e.g. "Flow", "Maestro", "Case" */
+    toolLabel: string;
+}
+export declare const registerSharedIncidentCommands: (program: Command, config: IncidentCommandsConfig) => void;

package/dist/src/shared-commands/instances.d.ts

@@ -0,0 +1,14 @@
+import type { Command } from "commander";
+export interface InstanceCommandsConfig {
+    /** Label used in command descriptions, e.g. "Flow", "Maestro", "Case" */
+    toolLabel: string;
+    /** Asset type query parameter, e.g. "flow", "bpmn", "case" */
+    assetType: string;
+    /** Process type filter for the list command. Omit to not filter by type. */
+    processType?: string;
+    /** Whether to register the element-executions subcommand (default: true) */
+    includeElementExecutions?: boolean;
+    /** Whether --folder-key is required (default: true) */
+    folderKeyRequired?: boolean;
+}
+export declare const registerSharedInstanceCommands: (program: Command, config: InstanceCommandsConfig) => void;

package/dist/src/shared-commands/processes.d.ts

@@ -0,0 +1,8 @@
+import type { Command } from "commander";
+export interface ProcessesCommandsConfig {
+    /** Label used in command descriptions, e.g. "Flow", "Maestro", "Case" */
+    toolLabel: string;
+    /** Process type filter for the list endpoint. Omit to not filter by type. */
+    processType?: string;
+}
+export declare const registerSharedProcessesCommands: (program: Command, config: ProcessesCommandsConfig) => void;

package/dist/src/shared-utils.d.ts

@@ -0,0 +1,11 @@
+export declare const VALID_PROJECT_NAME_REGEX: RegExp;
+export declare const VALID_PACKAGE_NAME_REGEX: RegExp;
+export declare function readStdin(): Promise<string | null>;
+export interface TraceEvent {
+    timestamp: string;
+    status: string;
+    name: string;
+    duration?: number;
+}
+export declare function formatTraceStatus(status: string): string;
+export declare function formatTraceLine(trace: TraceEvent): string;

package/dist/src/types.d.ts

@@ -0,0 +1,126 @@
+export interface PimsApiConfig {
+    baseUrl: string;
+    organizationId: string;
+    tenantId: string;
+    authToken: string;
+}
+export interface PimsRequestOptions {
+    folderKey?: string;
+}
+export interface ProcessInstanceRun {
+    runId: string;
+    status: string;
+    startedTime: string;
+    completedTime: string | null;
+}
+export interface ProcessInstance {
+    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[];
+}
+export interface ProcessInstanceOperationResponse {
+    instanceId: string;
+    status: string;
+}
+export interface GlobalVariableMetaData {
+    id: string;
+    name: string;
+    type: string;
+    value: unknown;
+    elementId: string;
+    source: string;
+}
+export interface ElementMetaData {
+    elementId: string;
+    elementRunId: string;
+    inputDefinitions: Record<string, unknown>;
+    inputs: Record<string, unknown>;
+    outputs: Record<string, unknown>;
+    isMarker: boolean;
+}
+export interface ProcessInstanceGetVariablesResponse {
+    instanceId: string;
+    parentElementId: string | null;
+    globalVariables: GlobalVariableMetaData[];
+    elements: ElementMetaData[];
+}
+export interface ProcessIncidentGetResponse {
+    incidentId: string;
+    instanceId: string;
+    processKey: string;
+    folderKey: string;
+    incidentType: string | null;
+    incidentSeverity: string | null;
+    incidentStatus: string;
+    debugMode: string;
+    incidentElementActivityName: string;
+    incidentElementActivityType: string;
+    elementId: string;
+    errorCode: string;
+    errorMessage: string;
+    errorDetails: string;
+    errorTime: string;
+}
+export interface ProcessIncidentGetAllResponse {
+    count: number;
+    errorMessage: string;
+    errorCode: string;
+    firstTimeUtc: string;
+    processKey: string;
+}
+export interface MaestroProcessSummary {
+    processKey: string;
+    runningCount: number;
+    faultedCount: number;
+}
+export interface GoToTransition {
+    sourceElementId: string;
+    targetElementId: string;
+}
+export interface GoToCursorsResponse {
+    elementIds: string[];
+}
+export interface ElementExecutionApi {
+    completedTimeUtc: string | null;
+    elementId: string;
+    elementType: string;
+    elementExtensionType: string | null;
+    parentRunId: string | null;
+    parentElementId: string | null;
+    parentElementRunId: string | null;
+    runId: string;
+    startedTimeUtc: string | null;
+    status: string;
+    elementRuns: unknown[];
+}
+export interface GetInstanceElementExecutionsResponse {
+    creationUserKey: string | null;
+    folderKey: string;
+    instanceDisplayName: string;
+    instanceId: string;
+    organizationId: string;
+    packageId: string;
+    packageKey: string;
+    packageVersion: string;
+    processKey: string;
+    source: string;
+    tenantId: string;
+    status: string;
+    startedTimeUtc: string;
+    completedTimeUtc: string | null;
+    elementExecutions: ElementExecutionApi[];
+    traceId: string | null;
+}

package/dist/src/with-pims-call.d.ts

@@ -0,0 +1,2 @@
+import type { PimsApiConfig } from "./types";
+export declare function withPimsCall<T>(fn: (config: PimsApiConfig) => Promise<T>, errorMessage: string): Promise<T | undefined>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@uipath/maestro-sdk",
-    "version": "0.2.0",
+    "version": "0.9.1",
     "description": "SDK for the UiPath Maestro (PIMS) API — process instance management.",
     "repository": {
         "type": "git",
@@ -18,20 +18,32 @@
     ],
     "type": "module",
     "main": "./dist/index.js",
+    "types": "./dist/src/index.d.ts",
     "exports": {
-        ".": "./dist/index.js"
+        ".": {
+            "types": "./dist/src/index.d.ts",
+            "default": "./dist/index.js"
+        }
     },
     "files": [
         "dist"
     ],
     "scripts": {
-        "build": "bun build ./src/index.ts --outdir dist --format esm --target node",
+        "build": "bun build ./src/index.ts --outdir dist --format esm --target node && tsc -p tsconfig.build.json --noCheck",
+        "test": "vitest run",
+        "test:coverage": "vitest run --coverage",
         "lint": "biome check ."
     },
     "devDependencies": {
-        "@uipath/auth": "0.2.0",
-        "@uipath/common": "0.2.0",
+        "@uipath/auth": "0.9.1",
+        "@uipath/common": "0.9.1",
+        "@uipath/filesystem": "0.9.1",
+        "@uipath/flow-core": "^0.2.0",
+        "@uipath/integrationservice-sdk": "0.9.1",
+        "@uipath/orchestrator-sdk": "0.9.1",
         "@types/node": "^25.5.0",
+        "commander": "^14.0.3",
         "typescript": "^5"
-    }
+    },
+    "gitHead": "e8da2857e37a9495c4907cd39f47c9d6ed1a5566"
 }