@uipath/tasks-tool 0.9.0

package/src/commands/tasks.ts

@@ -0,0 +1,552 @@
+import {
+    catchError,
+    extractErrorMessage,
+    extractErrorMessageSync,
+    OutputFormatter,
+    processContext,
+    RESULTS,
+} from "@uipath/common";
+import type { TaskCompletionOptions } from "@uipath/uipath-typescript";
+import type { Command } from "commander";
+
+import { createTasksClient } from "../utils/sdk-client";
+
+const DEFAULT_PAGE_SIZE = 100;
+
+const VALID_TASK_TYPES = [
+    "FormTask",
+    "ExternalTask",
+    "AppTask",
+    "DocumentValidationTask",
+    "DocumentClassificationTask",
+    "DataLabelingTask",
+] as const;
+type ValidTaskType = (typeof VALID_TASK_TYPES)[number];
+
+interface ListOptions {
+    tenant?: string;
+    folderId?: string;
+    asAdmin?: boolean;
+    limit?: string;
+}
+
+interface GetOptions {
+    tenant?: string;
+    taskType?: string;
+    folderId?: string;
+}
+
+interface AssignOptions {
+    tenant?: string;
+    userId?: string;
+    user?: string;
+}
+
+interface CompleteOptions {
+    tenant?: string;
+    type: string;
+    data?: string;
+    action?: string;
+}
+
+export const registerTasksCommand = (program: Command) => {
+    program
+        .command("list")
+        .description("List tasks across folders")
+        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .option("--folder-id <id>", "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;
+            }
+
+            let limit: number | undefined;
+            if (options.limit) {
+                const parsed = parsePositiveInt(options.limit, "--limit");
+                if (!parsed.valid) {
+                    reportInvalidInt(parsed);
+                    return;
+                }
+                limit = parsed.value;
+            }
+
+            let folderId: number | undefined;
+            if (options.folderId) {
+                const parsed = parsePositiveInt(
+                    options.folderId,
+                    "--folder-id",
+                );
+                if (!parsed.valid) {
+                    reportInvalidInt(parsed);
+                    return;
+                }
+                folderId = parsed.value;
+            }
+
+            const allItems: unknown[] = [];
+            let cursor: { value: string } | undefined;
+
+            do {
+                const getOptions: Record<string, unknown> = {
+                    pageSize: DEFAULT_PAGE_SIZE,
+                };
+                if (folderId !== undefined) {
+                    getOptions.folderId = folderId;
+                }
+                if (options.asAdmin) {
+                    getOptions.asTaskAdmin = true;
+                }
+                if (cursor) {
+                    getOptions.cursor = cursor;
+                }
+
+                const [listError, result] = await catchError(
+                    sdk.tasks.getAll(getOptions),
+                );
+
+                if (listError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Error listing tasks",
+                        Instructions: await extractErrorMessage(listError),
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                if (Array.isArray(result)) {
+                    allItems.push(...result);
+                    break;
+                }
+
+                const page = result as unknown as Record<string, unknown>;
+                const items = (page.items ?? []) as unknown[];
+                allItems.push(...items);
+
+                cursor = page.hasNextPage
+                    ? (page.nextCursor as { value: string })
+                    : undefined;
+
+                if (limit && allItems.length >= limit) {
+                    break;
+                }
+            } while (cursor);
+
+            const data = limit ? allItems.slice(0, limit) : allItems;
+
+            OutputFormatter.success({
+                Result: RESULTS.Success,
+                Code: "TaskList",
+                Data: data,
+            });
+        });
+
+    program
+        .command("get")
+        .description(
+            "Get details of a task by ID. Use 'tasks list' to find task IDs.",
+        )
+        .argument("<id>", "Task ID")
+        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .option(
+            "--task-type <type>",
+            "Task type (FormTask, ExternalTask, AppTask, DocumentValidationTask, DocumentClassificationTask, DataLabelingTask)",
+        )
+        .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;
+                }
+
+                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 [getError, task] = await catchError(
+                    sdk.tasks.getById(parsedId.value, getOptions, folderId),
+                );
+
+                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,
+                });
+            },
+        );
+
+    program
+        .command("assign")
+        .description("Assign a task to a user")
+        .argument("<task-id>", "Task ID")
+        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .option("--user-id <id>", "User ID")
+        .option(
+            "--user <email>",
+            "User name or email (alternative to --user-id)",
+        )
+        .trackedAction(
+            processContext,
+            async (taskId: string, options: AssignOptions) => {
+                await assignOrReassign(taskId, options, "assign");
+            },
+        );
+
+    program
+        .command("reassign")
+        .description("Reassign a task to a different user")
+        .argument("<task-id>", "Task ID")
+        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .option("--user-id <id>", "User ID")
+        .option(
+            "--user <email>",
+            "User name or email (alternative to --user-id)",
+        )
+        .trackedAction(
+            processContext,
+            async (taskId: string, options: AssignOptions) => {
+                await assignOrReassign(taskId, options, "reassign");
+            },
+        );
+
+    program
+        .command("unassign")
+        .description("Remove the assignee from a task")
+        .argument("<task-id>", "Task ID")
+        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .trackedAction(
+            processContext,
+            async (taskId: string, options: { tenant?: string }) => {
+                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(taskId, "<task-id>");
+                if (!parsedId.valid) {
+                    reportInvalidInt(parsedId);
+                    return;
+                }
+
+                const [unassignError, result] = await catchError(
+                    sdk.tasks.unassign(parsedId.value),
+                );
+
+                if (unassignError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: `Error unassigning task '${taskId}'`,
+                        Instructions: await extractErrorMessage(unassignError),
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                OutputFormatter.success({
+                    Result: RESULTS.Success,
+                    Code: "TaskUnassigned",
+                    Data: result,
+                });
+            },
+        );
+
+    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)",
+        )
+        .requiredOption("--folder-id <id>", "Folder ID (required)")
+        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .option("--data <json>", "Task data as JSON string")
+        .option(
+            "--action <action>",
+            "Action name (required for FormTask and AppTask)",
+        )
+        .trackedAction(
+            processContext,
+            async (
+                taskId: string,
+                options: CompleteOptions & { folderId: string },
+            ) => {
+                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 parsedTaskId = parsePositiveInt(taskId, "<task-id>");
+                if (!parsedTaskId.valid) {
+                    reportInvalidInt(parsedTaskId);
+                    return;
+                }
+
+                const parsedFolderId = parsePositiveInt(
+                    options.folderId,
+                    "--folder-id",
+                );
+                if (!parsedFolderId.valid) {
+                    reportInvalidInt(parsedFolderId);
+                    return;
+                }
+
+                if (!VALID_TASK_TYPES.includes(options.type as ValidTaskType)) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: `Invalid task type '${options.type}'`,
+                        Instructions: `Valid types: ${VALID_TASK_TYPES.join(", ")}`,
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                const completionOptions: Record<string, unknown> = {
+                    taskId: parsedTaskId.value,
+                    type: options.type,
+                };
+
+                if (options.action) {
+                    completionOptions.action = options.action;
+                }
+
+                if (options.data) {
+                    const [parseError, parsed] = await catchError(
+                        Promise.resolve().then(
+                            () => JSON.parse(options.data as string) as unknown,
+                        ),
+                    );
+                    if (parseError) {
+                        OutputFormatter.error({
+                            Result: RESULTS.Failure,
+                            Message: "Invalid JSON in --data",
+                            Instructions: extractErrorMessageSync(parseError),
+                        });
+                        processContext.exit(1);
+                        return;
+                    }
+                    completionOptions.data = parsed;
+                }
+
+                // CLI receives type as a raw string; SDK expects a TaskType enum discriminated union.
+                const [completeError, result] = await catchError(
+                    sdk.tasks.complete(
+                        completionOptions as unknown as TaskCompletionOptions,
+                        parsedFolderId.value,
+                    ),
+                );
+
+                if (completeError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: `Error completing task '${taskId}'`,
+                        Instructions: await extractErrorMessage(completeError),
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                OutputFormatter.success({
+                    Result: RESULTS.Success,
+                    Code: "TaskCompleted",
+                    Data: result,
+                });
+            },
+        );
+};
+
+async function assignOrReassign(
+    taskId: string,
+    options: AssignOptions,
+    action: "assign" | "reassign",
+): Promise<void> {
+    if (!options.userId && !options.user) {
+        OutputFormatter.error({
+            Result: RESULTS.Failure,
+            Message: "Missing assignee",
+            Instructions:
+                action === "assign"
+                    ? "Provide either --user-id or --user to specify the assignee."
+                    : "Provide either --user-id or --user to specify the new assignee.",
+        });
+        processContext.exit(1);
+        return;
+    }
+
+    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 parsedTaskId = parsePositiveInt(taskId, "<task-id>");
+    if (!parsedTaskId.valid) {
+        reportInvalidInt(parsedTaskId);
+        return;
+    }
+
+    const assignment: Record<string, unknown> = {
+        taskId: parsedTaskId.value,
+    };
+    if (options.userId) {
+        const parsedUserId = parsePositiveInt(options.userId, "--user-id");
+        if (!parsedUserId.valid) {
+            reportInvalidInt(parsedUserId);
+            return;
+        }
+        assignment.userId = parsedUserId.value;
+    } else {
+        assignment.userNameOrEmail = options.user;
+    }
+
+    type TaskAssignment =
+        | { taskId: number; userId: number }
+        | { taskId: number; userNameOrEmail: string };
+
+    const [error, result] = await catchError(
+        action === "assign"
+            ? sdk.tasks.assign(assignment as TaskAssignment)
+            : sdk.tasks.reassign(assignment as TaskAssignment),
+    );
+
+    if (error) {
+        OutputFormatter.error({
+            Result: RESULTS.Failure,
+            Message: `Error ${action === "assign" ? "assigning" : "reassigning"} task '${taskId}'`,
+            Instructions: await extractErrorMessage(error),
+        });
+        processContext.exit(1);
+        return;
+    }
+
+    OutputFormatter.success({
+        Result: RESULTS.Success,
+        Code: action === "assign" ? "TaskAssigned" : "TaskReassigned",
+        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/index.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env bun
+import { Command } from "commander";
+import pkg from "../package.json" with { type: "json" };
+import { registerTasksCommand } from "./commands/tasks";
+
+const program = new Command();
+program
+    .name("tasks-tool")
+    .description("UiPath Tasks Tool - Standalone CLI")
+    .version(pkg.version);
+
+registerTasksCommand(program);
+program.parse(process.argv);

package/src/tool.ts

@@ -0,0 +1,14 @@
+import type { Command } from "commander";
+import pkg from "../package.json" with { type: "json" };
+import { registerTasksCommand } from "./commands/tasks";
+
+export const metadata = {
+    name: "tasks-tool",
+    version: pkg.version,
+    description: "Manage Action Center tasks.",
+    commandPrefix: "tasks",
+};
+
+export const registerCommands = async (program: Command): Promise<void> => {
+    registerTasksCommand(program);
+};

package/src/utils/sdk-client.ts

@@ -0,0 +1,25 @@
+import { getLoginStatusAsync } from "@uipath/auth";
+import { UiPath } from "@uipath/uipath-typescript";
+
+export const createTasksClient = async (
+    tenantOverride?: string,
+): Promise<UiPath> => {
+    const status = await getLoginStatusAsync({
+        ensureTokenValidityMinutes: 10,
+    });
+
+    if (
+        status.loginStatus !== "Logged in" ||
+        !status.accessToken ||
+        !status.baseUrl
+    ) {
+        throw new Error(status.hint ?? "Not logged in. Run 'uip login' first.");
+    }
+
+    return new UiPath({
+        secret: status.accessToken,
+        baseUrl: status.baseUrl,
+        orgName: status.organizationName,
+        tenantName: tenantOverride ?? status.tenantName,
+    });
+};

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+    "extends": "../../tsconfig.base.json",
+    "compilerOptions": {
+        "outDir": "./dist",
+        "types": ["node"]
+    },
+    "include": ["src/**/*", "tests/**/*", "vitest*.ts"],
+    "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1 @@
+export { default } from "../../vitest.base.config";