@uipath/tasks-tool 1.201.0-preview.115 → 1.201.0-preview.122

package/src/commands/tasks.ts

@@ -9,11 +9,17 @@ import {
     RESULTS,
 } from "@uipath/common";
 import type { TaskCompletionOptions } from "@uipath/uipath-typescript";
-import type { Command } from "commander";
+import { type Command, Option } from "commander";
 
-import { createTasksClient } from "../utils/sdk-client";
-
-const DEFAULT_PAGE_SIZE = 100;
+import { connectTasksClient } from "./_shared/connect";
+import { DEFAULT_PAGE_SIZE } from "./_shared/constants";
+import {
+    addFolderScopeOptions,
+    type FolderScopeOptions,
+    resolveFolderId,
+    resolveFolderScope,
+} from "./_shared/folder-picker";
+import { parseIntArg } from "./_shared/parse";
 
 const VALID_TASK_TYPES = [
     "FormTask",
@@ -26,17 +32,13 @@ const VALID_TASK_TYPES = [
 ] as const;
 type ValidTaskType = (typeof VALID_TASK_TYPES)[number];
 
-interface ListOptions {
-    tenant?: string;
-    folderId?: string;
+interface ListOptions extends FolderScopeOptions {
     asAdmin?: boolean;
     limit?: string;
 }
 
-interface GetOptions {
-    tenant?: string;
+interface GetOptions extends FolderScopeOptions {
     taskType?: string;
-    folderId?: string;
 }
 
 interface AssignOptions {
@@ -45,15 +47,13 @@ interface AssignOptions {
     user?: string;
 }
 
-interface CompleteOptions {
-    tenant?: string;
+interface CompleteOptions extends FolderScopeOptions {
     type: string;
     data?: string;
     action?: string;
 }
 
-interface UsersOptions {
-    tenant?: string;
+interface UsersOptions extends FolderScopeOptions {
     limit?: string;
 }
 
@@ -100,58 +100,56 @@ const TASKS_USERS_EXAMPLES: CommandExample[] = [
             ],
         },
     },
+    {
+        Description:
+            "List users by folder path instead of the numeric folder ID",
+        Command: 'uip tasks users --folder-path "Shared/Finance"',
+        Output: {
+            Code: "TaskUserList",
+            Data: [
+                {
+                    id: 1,
+                    name: "Alice",
+                    surname: "Smith",
+                    userName: "alice",
+                    emailAddress: "alice@company.com",
+                    displayName: "Alice Smith",
+                },
+            ],
+        },
+    },
 ];
 
 export const registerTasksCommand = (program: Command) => {
-    program
-        .command("list")
-        .description("List tasks across folders")
-        .addOption(
-            createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
-        )
-        .option("--folder-id <id>", "Filter by folder ID")
+    addFolderScopeOptions(
+        program
+            .command("list")
+            .description("List tasks across folders")
+            .addOption(
+                createHiddenDeprecatedTenantOption(
+                    "-t, --tenant <tenant-name>",
+                ),
+            ),
+        "Filter by folder ID",
+    )
         .option("--as-admin", "List tasks as admin")
         .option(
             "-l, --limit <number>",
             "Maximum number of items to return (fetches all if omitted)",
         )
         .trackedAction(processContext, async (options: ListOptions) => {
-            const [clientError, sdk] = await catchError(
-                createTasksClient(options.tenant),
-            );
-
-            if (clientError) {
-                OutputFormatter.error({
-                    Result: RESULTS.Failure,
-                    Message: "Error connecting to Action Center",
-                    Instructions: await extractErrorMessage(clientError),
-                });
-                processContext.exit(1);
-                return;
-            }
+            const sdk = await connectTasksClient(options.tenant);
+            if (!sdk) return;
 
             let limit: number | undefined;
             if (options.limit) {
-                const parsed = parsePositiveInt(options.limit, "--limit");
-                if (!parsed.valid) {
-                    reportInvalidInt(parsed);
-                    return;
-                }
-                limit = parsed.value;
+                const parsed = parseIntArg(options.limit, "--limit");
+                if (parsed === null) return;
+                limit = parsed;
             }
 
-            let folderId: number | undefined;
-            if (options.folderId) {
-                const parsed = parsePositiveInt(
-                    options.folderId,
-                    "--folder-id",
-                );
-                if (!parsed.valid) {
-                    reportInvalidInt(parsed);
-                    return;
-                }
-                folderId = parsed.value;
-            }
+            const folderId = await resolveFolderScope(options);
+            if (folderId === null) return;
 
             const allItems: unknown[] = [];
             let cursor: { value: string } | undefined;
@@ -211,96 +209,72 @@ export const registerTasksCommand = (program: Command) => {
             });
         });
 
-    program
-        .command("get")
-        .description(
-            "Get details of a task by ID. Use 'tasks list' to find task IDs.",
-        )
-        .argument("<id>", "Task ID")
-        .addOption(
-            createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
-        )
-        .option(
-            "--task-type <type>",
-            "Task type (FormTask, ExternalTask, AppTask, DocumentValidationTask, DocumentClassificationTask, DataLabelingTask, QuickFormTask)",
-        )
-        .option(
-            "--folder-id <id>",
-            "Folder ID (required when task-type is specified)",
-        )
-        .trackedAction(
-            processContext,
-            async (id: string, options: GetOptions) => {
-                const [clientError, sdk] = await catchError(
-                    createTasksClient(options.tenant),
-                );
-
-                if (clientError) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: "Error connecting to Action Center",
-                        Instructions: await extractErrorMessage(clientError),
-                    });
-                    processContext.exit(1);
-                    return;
-                }
-
-                const parsedId = parsePositiveInt(id, "<id>");
-                if (!parsedId.valid) {
-                    reportInvalidInt(parsedId);
-                    return;
-                }
-
-                if (options.taskType && !options.folderId) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message:
-                            "--folder-id is required when --task-type is specified",
-                        Instructions:
-                            "Provide a folder ID with --folder-id <id>.",
-                    });
-                    processContext.exit(1);
-                    return;
-                }
+    addFolderScopeOptions(
+        program
+            .command("get")
+            .description(
+                "Get details of a task by ID. Use 'tasks list' to find task IDs.",
+            )
+            .argument("<id>", "Task ID")
+            .addOption(
+                createHiddenDeprecatedTenantOption(
+                    "-t, --tenant <tenant-name>",
+                ),
+            )
+            .option(
+                "--task-type <type>",
+                "Task type (FormTask, ExternalTask, AppTask, DocumentValidationTask, DocumentClassificationTask, DataLabelingTask, QuickFormTask)",
+            ),
+        "Folder ID (a folder is required when task-type is specified)",
+    ).trackedAction(processContext, async (id: string, options: GetOptions) => {
+        const sdk = await connectTasksClient(options.tenant);
+        if (!sdk) return;
+
+        const parsedId = parseIntArg(id, "<id>");
+        if (parsedId === null) return;
+
+        const hasFolderScope =
+            options.folderId !== undefined ||
+            options.folderPath !== undefined ||
+            options.folderKey !== undefined;
+        if (options.taskType && !hasFolderScope) {
+            OutputFormatter.error({
+                Result: RESULTS.Failure,
+                Message: "A folder is required when --task-type is specified",
+                Instructions:
+                    "Pass --folder-id <id>, --folder-path <path>, or --folder-key <key>.",
+            });
+            processContext.exit(1);
+            return;
+        }
 
-                const getOptions: Record<string, unknown> = {};
-                if (options.taskType) {
-                    getOptions.taskType = options.taskType;
-                }
-                let folderId: number | undefined;
-                if (options.folderId) {
-                    const parsed = parsePositiveInt(
-                        options.folderId,
-                        "--folder-id",
-                    );
-                    if (!parsed.valid) {
-                        reportInvalidInt(parsed);
-                        return;
-                    }
-                    folderId = parsed.value;
-                }
+        const getOptions: Record<string, unknown> = {};
+        if (options.taskType) {
+            getOptions.taskType = options.taskType;
+        }
+        const folderId = await resolveFolderScope(options);
+        if (folderId === null) return;
 
-                const [getError, task] = await catchError(
-                    sdk.tasks.getById(parsedId.value, getOptions, folderId),
-                );
+        const [getError, task] = await catchError(
+            sdk.tasks.getById(parsedId, getOptions, folderId),
+        );
 
-                if (getError) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: `Error getting task '${id}'`,
-                        Instructions: await extractErrorMessage(getError),
-                    });
-                    processContext.exit(1);
-                    return;
-                }
+        if (getError) {
+            OutputFormatter.error({
+                Result: RESULTS.Failure,
+                Message: `Error getting task '${id}'`,
+                Instructions: await extractErrorMessage(getError),
+            });
+            processContext.exit(1);
+            return;
+        }
 
-                OutputFormatter.success({
-                    Result: RESULTS.Success,
-                    Code: "TaskDetails",
-                    Data: task,
-                });
-            },
-        );
+        OutputFormatter.success({
+            Result: RESULTS.Success,
+            Code: "TaskDetails",
+            Data: task,
+        });
+    });
 
     program
         .command("assign")
@@ -350,28 +324,14 @@ export const registerTasksCommand = (program: Command) => {
         .trackedAction(
             processContext,
             async (taskId: string, options: { tenant?: string }) => {
-                const [clientError, sdk] = await catchError(
-                    createTasksClient(options.tenant),
-                );
+                const sdk = await connectTasksClient(options.tenant);
+                if (!sdk) return;
 
-                if (clientError) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: "Error connecting to Action Center",
-                        Instructions: await extractErrorMessage(clientError),
-                    });
-                    processContext.exit(1);
-                    return;
-                }
-
-                const parsedId = parsePositiveInt(taskId, "<task-id>");
-                if (!parsedId.valid) {
-                    reportInvalidInt(parsedId);
-                    return;
-                }
+                const parsedId = parseIntArg(taskId, "<task-id>");
+                if (parsedId === null) return;
 
                 const [unassignError, result] = await catchError(
-                    sdk.tasks.unassign(parsedId.value),
+                    sdk.tasks.unassign(parsedId),
                 );
 
                 if (unassignError) {
@@ -392,18 +352,21 @@ export const registerTasksCommand = (program: Command) => {
             },
         );
 
-    program
-        .command("complete")
-        .description("Complete a task with an action and optional data")
-        .argument("<task-id>", "Task ID")
-        .requiredOption(
-            "--type <type>",
-            "Task type (FormTask, ExternalTask, AppTask, DocumentValidationTask, DocumentClassificationTask, DataLabelingTask, QuickFormTask)",
-        )
-        .requiredOption("--folder-id <id>", "Folder ID (required)")
-        .addOption(
-            createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
-        )
+    addFolderScopeOptions(
+        program
+            .command("complete")
+            .description("Complete a task with an action and optional data")
+            .argument("<task-id>", "Task ID")
+            .requiredOption(
+                "--type <type>",
+                "Task type (FormTask, ExternalTask, AppTask, DocumentValidationTask, DocumentClassificationTask, DataLabelingTask, QuickFormTask)",
+            )
+            .addOption(
+                createHiddenDeprecatedTenantOption(
+                    "-t, --tenant <tenant-name>",
+                ),
+            ),
+    )
         .option("--data <json>", "Task data as JSON string")
         .option(
             "--action <action>",
@@ -411,38 +374,12 @@ export const registerTasksCommand = (program: Command) => {
         )
         .trackedAction(
             processContext,
-            async (
-                taskId: string,
-                options: CompleteOptions & { folderId: string },
-            ) => {
-                const [clientError, sdk] = await catchError(
-                    createTasksClient(options.tenant),
-                );
+            async (taskId: string, options: CompleteOptions) => {
+                const sdk = await connectTasksClient(options.tenant);
+                if (!sdk) return;
 
-                if (clientError) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: "Error connecting to Action Center",
-                        Instructions: await extractErrorMessage(clientError),
-                    });
-                    processContext.exit(1);
-                    return;
-                }
-
-                const parsedTaskId = parsePositiveInt(taskId, "<task-id>");
-                if (!parsedTaskId.valid) {
-                    reportInvalidInt(parsedTaskId);
-                    return;
-                }
-
-                const parsedFolderId = parsePositiveInt(
-                    options.folderId,
-                    "--folder-id",
-                );
-                if (!parsedFolderId.valid) {
-                    reportInvalidInt(parsedFolderId);
-                    return;
-                }
+                const parsedTaskId = parseIntArg(taskId, "<task-id>");
+                if (parsedTaskId === null) return;
 
                 if (!VALID_TASK_TYPES.includes(options.type as ValidTaskType)) {
                     OutputFormatter.error({
@@ -454,8 +391,11 @@ export const registerTasksCommand = (program: Command) => {
                     return;
                 }
 
+                const folderId = await resolveFolderId(options);
+                if (folderId === null) return;
+
                 const completionOptions: Record<string, unknown> = {
-                    taskId: parsedTaskId.value,
+                    taskId: parsedTaskId,
                     type: options.type,
                 };
 
@@ -485,7 +425,7 @@ export const registerTasksCommand = (program: Command) => {
                 const [completeError, result] = await catchError(
                     sdk.tasks.complete(
                         completionOptions as unknown as TaskCompletionOptions,
-                        parsedFolderId.value,
+                        folderId,
                     ),
                 );
 
@@ -512,10 +452,25 @@ export const registerTasksCommand = (program: Command) => {
         .description(
             "List users with task permissions in a folder. Use the user ID with 'tasks assign'.",
         )
-        .argument("<folder-id>", "Folder ID")
+        .argument(
+            "[folder-id]",
+            "Folder ID (alternatively pass --folder-path or --folder-key)",
+        )
         .addOption(
             createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
         )
+        .addOption(
+            new Option(
+                "--folder-path <path>",
+                "Folder path (alternative to the folder-id argument)",
+            ).conflicts("folderKey"),
+        )
+        .addOption(
+            new Option(
+                "--folder-key <key>",
+                "Folder key (alternative to the folder-id argument)",
+            ),
+        )
         .option(
             "-l, --limit <number>",
             "Maximum number of items to return (fetches all if omitted)",
@@ -523,38 +478,40 @@ export const registerTasksCommand = (program: Command) => {
         .examples(TASKS_USERS_EXAMPLES)
         .trackedAction(
             processContext,
-            async (folderId: string, options: UsersOptions) => {
-                const [clientError, sdk] = await catchError(
-                    createTasksClient(options.tenant),
-                );
-
-                if (clientError) {
+            async (folderId: string | undefined, options: UsersOptions) => {
+                const sdk = await connectTasksClient(options.tenant);
+                if (!sdk) return;
+
+                if (
+                    folderId !== undefined &&
+                    (options.folderPath !== undefined ||
+                        options.folderKey !== undefined)
+                ) {
                     OutputFormatter.error({
                         Result: RESULTS.Failure,
-                        Message: "Error connecting to Action Center",
-                        Instructions: await extractErrorMessage(clientError),
+                        Message:
+                            "The folder-id argument cannot be used with --folder-path or --folder-key",
+                        Instructions:
+                            "Pass the folder as a numeric argument, or as --folder-path/--folder-key, not both.",
                     });
                     processContext.exit(1);
                     return;
                 }
 
-                const parsedFolderId = parsePositiveInt(
-                    folderId,
-                    "<folder-id>",
-                );
-                if (!parsedFolderId.valid) {
-                    reportInvalidInt(parsedFolderId);
-                    return;
-                }
+                const parsedFolderId =
+                    folderId !== undefined
+                        ? parseIntArg(folderId, "<folder-id>")
+                        : await resolveFolderId(
+                              options,
+                              "Pass the folder-id argument, --folder-path <path>, or --folder-key <key> (run 'uip or folders list' to find one).",
+                          );
+                if (parsedFolderId === null) return;
 
                 let limit: number | undefined;
                 if (options.limit) {
-                    const parsed = parsePositiveInt(options.limit, "--limit");
-                    if (!parsed.valid) {
-                        reportInvalidInt(parsed);
-                        return;
-                    }
-                    limit = parsed.value;
+                    const parsed = parseIntArg(options.limit, "--limit");
+                    if (parsed === null) return;
+                    limit = parsed;
                 }
 
                 const allItems: unknown[] = [];
@@ -569,7 +526,7 @@ export const registerTasksCommand = (program: Command) => {
                     }
 
                     const [usersError, result] = await catchError(
-                        sdk.tasks.getUsers(parsedFolderId.value, getOptions),
+                        sdk.tasks.getUsers(parsedFolderId, getOptions),
                     );
 
                     if (usersError) {
@@ -629,36 +586,19 @@ async function assignOrReassign(
         return;
     }
 
-    const [clientError, sdk] = await catchError(
-        createTasksClient(options.tenant),
-    );
+    const sdk = await connectTasksClient(options.tenant);
+    if (!sdk) return;
 
-    if (clientError) {
-        OutputFormatter.error({
-            Result: RESULTS.Failure,
-            Message: "Error connecting to Action Center",
-            Instructions: await extractErrorMessage(clientError),
-        });
-        processContext.exit(1);
-        return;
-    }
-
-    const parsedTaskId = parsePositiveInt(taskId, "<task-id>");
-    if (!parsedTaskId.valid) {
-        reportInvalidInt(parsedTaskId);
-        return;
-    }
+    const parsedTaskId = parseIntArg(taskId, "<task-id>");
+    if (parsedTaskId === null) return;
 
     const assignment: Record<string, unknown> = {
-        taskId: parsedTaskId.value,
+        taskId: parsedTaskId,
     };
     if (options.userId) {
-        const parsedUserId = parsePositiveInt(options.userId, "--user-id");
-        if (!parsedUserId.valid) {
-            reportInvalidInt(parsedUserId);
-            return;
-        }
-        assignment.userId = parsedUserId.value;
+        const parsedUserId = parseIntArg(options.userId, "--user-id");
+        if (parsedUserId === null) return;
+        assignment.userId = parsedUserId;
     } else {
         assignment.userNameOrEmail = options.user;
     }
@@ -689,32 +629,3 @@ async function assignOrReassign(
         Data: result,
     });
 }
-
-function parsePositiveInt(
-    value: string,
-    label: string,
-):
-    | { valid: true; value: number }
-    | { valid: false; message: string; instructions: string } {
-    const parsed = Number(value);
-    if (!Number.isInteger(parsed) || parsed <= 0) {
-        return {
-            valid: false,
-            message: `Invalid ${label}: ${value}`,
-            instructions: "Must be a positive integer.",
-        };
-    }
-    return { valid: true, value: parsed };
-}
-
-function reportInvalidInt(error: {
-    message: string;
-    instructions: string;
-}): void {
-    OutputFormatter.error({
-        Result: RESULTS.Failure,
-        Message: error.message,
-        Instructions: error.instructions,
-    });
-    processContext.exit(1);
-}

package/src/tool.ts

@@ -1,5 +1,10 @@
 import type { Command } from "commander";
 import pkg from "../package.json" with { type: "json" };
+import { registerCatalogsCommand } from "./commands/catalogs";
+import { registerCommentsCommand } from "./commands/comments";
+import { registerDataCommand } from "./commands/data";
+import { registerLabelsCommand } from "./commands/labels";
+import { registerMetadataCommand } from "./commands/metadata";
 import { registerTasksCommand } from "./commands/tasks";
 
 export const metadata = {
@@ -11,4 +16,9 @@ export const metadata = {
 
 export const registerCommands = async (program: Command): Promise<void> => {
     registerTasksCommand(program);
+    registerCatalogsCommand(program);
+    registerCommentsCommand(program);
+    registerLabelsCommand(program);
+    registerMetadataCommand(program);
+    registerDataCommand(program);
 };

package/src/utils/sdk-client.ts

@@ -1,5 +1,6 @@
 import { getLoginStatusAsync } from "@uipath/auth";
 import { UiPath } from "@uipath/uipath-typescript";
+import { TaskCatalogs } from "@uipath/uipath-typescript/tasks";
 
 export const createTasksClient = async (
     tenantOverride?: string,
@@ -23,3 +24,7 @@ export const createTasksClient = async (
         tenantName: tenantOverride ?? status.tenantName,
     });
 };
+
+// Task catalogs live on their own service in the SDK, not on `sdk.tasks`.
+export const createTaskCatalogsClient = (sdk: UiPath): TaskCatalogs =>
+    new TaskCatalogs(sdk);