@uipath/data-fabric-tool 1.1.0 → 1.196.0

package/src/commands/records.ts

@@ -9,10 +9,10 @@ import {
 } from "@uipath/common";
 import { getFileSystem } from "@uipath/filesystem";
 import type { EntityRecord } from "@uipath/uipath-typescript";
-import type { Command } from "commander";
+import { type Command, Option } from "commander";
 import { readFileBinary, readJsonInput } from "../utils/input";
-import { extractCursorValue } from "../utils/pagination";
-import { createDataFabricClient } from "../utils/sdk-client";
+import { fail, requireDestructiveConfirmation } from "../utils/output";
+import { connectOrFail } from "../utils/sdk-client";
 
 interface ListOptions {
     tenant?: string;
@@ -39,6 +39,9 @@ interface UpdateOptions {
 
 interface DeleteOptions {
     tenant?: string;
+    yes?: boolean;
+    confirm?: boolean;
+    reason?: string;
 }
 
 interface QueryOptions {
@@ -62,14 +65,13 @@ interface BatchResult {
 
 const RECORDS_LIST_EXAMPLES: CommandExample[] = [
     {
-        Description: "List records in an entity",
+        Description: "List records in an entity.",
         Command:
             "uip df records list a1b2c3d4-0000-0000-0000-000000000001 --limit 2",
         Output: {
             Code: "RecordList",
             Data: {
-                TotalCount: 2,
-                Records: [
+                items: [
                     {
                         Id: "b2c3d4e5-0000-0000-0000-000000000001",
                         amount: 1500,
@@ -79,7 +81,8 @@ const RECORDS_LIST_EXAMPLES: CommandExample[] = [
                         amount: 2750,
                     },
                 ],
-                HasNextPage: false,
+                totalCount: 2,
+                hasNextPage: false,
             },
         },
     },
@@ -118,9 +121,9 @@ const RECORDS_INSERT_EXAMPLES: CommandExample[] = [
     {
         Description:
             "Insert a record into an entity that has choice-set and relationship fields. " +
-            "CHOICE_SET_SINGLE → pass the choice value's 'NumberId' (integer, NOT the Name string — look it up via 'df choice-sets get <id>'). " +
-            "CHOICE_SET_MULTIPLE → pass an array of NumberId integers. " +
-            "RELATIONSHIP → always pass the target record's Id (UUID), even if the field was declared with a 'referenceFieldName' other than 'Id' (the referenceFieldName configures the join, not the stored value).",
+            "CHOICE_SET_SINGLE → pass the choice value's 'numberId' (integer, NOT the name string — look it up via 'df choice-sets list-values <id>'). " +
+            "CHOICE_SET_MULTIPLE → pass an array of numberId integers. " +
+            "RELATIONSHIP → always pass the target record's Id (UUID), regardless of which 'referenceFieldId' the schema uses for the join (the referenceFieldId configures the join, not the stored value).",
         Command:
             'uip df records insert a1b2c3d4-0000-0000-0000-000000000004 --body \'{"category":0,"tags":[1,3],"submitter":"e1f2a3b4-0000-0000-0000-000000000001","amount":250}\'',
         Output: {
@@ -201,58 +204,36 @@ export const registerRecordsCommand = (program: Command) => {
             async (entityId: string, options: ListOptions) => {
                 const pageSize = Number(options.limit);
                 if (Number.isNaN(pageSize) || pageSize < 1) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: "Invalid --limit value",
-                        Instructions: "Provide a positive integer for --limit.",
-                    });
-                    processContext.exit(1);
-                    return;
+                    return fail(
+                        "Invalid --limit value",
+                        "Provide a positive integer for --limit.",
+                    );
                 }
 
                 if (
                     options.cursor !== undefined &&
                     options.offset !== undefined
                 ) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: "--offset and --cursor are mutually exclusive",
-                        Instructions:
-                            "Use --offset to jump to a position by record count, or --cursor to continue from a previous response.",
-                    });
-                    processContext.exit(1);
-                    return;
+                    return fail(
+                        "--offset and --cursor are mutually exclusive",
+                        "Use --offset to jump to a position by record count, or --cursor to continue from a previous response.",
+                    );
                 }
 
                 let jumpToPage: number | undefined;
                 if (options.offset !== undefined) {
                     const offsetValue = Number(options.offset);
                     if (Number.isNaN(offsetValue) || offsetValue < 0) {
-                        OutputFormatter.error({
-                            Result: RESULTS.Failure,
-                            Message: "Invalid --offset value",
-                            Instructions:
-                                "Provide a non-negative integer for --offset.",
-                        });
-                        processContext.exit(1);
-                        return;
+                        return fail(
+                            "Invalid --offset value",
+                            "Provide a non-negative integer for --offset.",
+                        );
                     }
                     jumpToPage = Math.floor(offsetValue / pageSize) + 1;
                 }
 
-                const [clientError, sdk] = await catchError(
-                    createDataFabricClient(options.tenant),
-                );
-
-                if (clientError) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: "Error connecting to Data Fabric",
-                        Instructions: await extractErrorMessage(clientError),
-                    });
-                    processContext.exit(1);
-                    return;
-                }
+                const sdk = await connectOrFail(options.tenant);
+                if (!sdk) return;
 
                 const [listError, result] = await catchError(
                     sdk.entities.getAllRecords(entityId, {
@@ -265,42 +246,16 @@ export const registerRecordsCommand = (program: Command) => {
                 );
 
                 if (listError) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: "Error listing records",
-                        Instructions: await extractErrorMessage(listError),
-                    });
-                    processContext.exit(1);
-                    return;
+                    return fail(
+                        "Error listing records",
+                        await extractErrorMessage(listError),
+                    );
                 }
 
-                const r = result as {
-                    items: unknown[];
-                    totalCount?: number;
-                    hasNextPage?: boolean;
-                    nextCursor?: unknown;
-                    currentPage?: number;
-                    totalPages?: number;
-                };
-                const nextCursor = extractCursorValue(r.nextCursor);
-
                 OutputFormatter.success({
                     Result: RESULTS.Success,
                     Code: "RecordList",
-                    Data: {
-                        TotalCount: r.totalCount ?? r.items.length,
-                        Records: r.items,
-                        HasNextPage: r.hasNextPage ?? false,
-                        ...(nextCursor !== undefined && {
-                            NextCursor: nextCursor,
-                        }),
-                        ...(r.currentPage !== undefined && {
-                            CurrentPage: r.currentPage,
-                        }),
-                        ...(r.totalPages !== undefined && {
-                            TotalPages: r.totalPages,
-                        }),
-                    },
+                    Data: result,
                 });
             },
         );
@@ -317,43 +272,25 @@ export const registerRecordsCommand = (program: Command) => {
         .trackedAction(
             processContext,
             async (entityId: string, recordId: string, options: GetOptions) => {
-                const [clientError, sdk] = await catchError(
-                    createDataFabricClient(options.tenant),
-                );
-
-                if (clientError) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: "Error connecting to Data Fabric",
-                        Instructions: await extractErrorMessage(clientError),
-                    });
-                    processContext.exit(1);
-                    return;
-                }
+                const sdk = await connectOrFail(options.tenant);
+                if (!sdk) return;
 
                 const [getError, record] = await catchError(
                     sdk.entities.getRecordById(entityId, recordId),
                 );
 
                 if (getError) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: `Error getting record '${recordId}'`,
-                        Instructions: await extractErrorMessage(getError),
-                    });
-                    processContext.exit(1);
-                    return;
+                    return fail(
+                        `Error getting record '${recordId}'`,
+                        await extractErrorMessage(getError),
+                    );
                 }
 
                 if (!record) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: `Record '${recordId}' not found in entity '${entityId}'`,
-                        Instructions:
-                            "Verify the record ID exists. Use 'df records list' to see available records.",
-                    });
-                    processContext.exit(1);
-                    return;
+                    return fail(
+                        `Record '${recordId}' not found in entity '${entityId}'`,
+                        "Verify the record ID exists. Use 'df records list' to see available records.",
+                    );
                 }
 
                 OutputFormatter.success({
@@ -377,7 +314,7 @@ export const registerRecordsCommand = (program: Command) => {
         )
         .option(
             "--body <json>",
-            "Inline JSON record data (object or array of objects)",
+            "Inline JSON record data (object or array of objects; use `-` to read from stdin)",
         )
         .examples(RECORDS_INSERT_EXAMPLES)
         .trackedAction(
@@ -388,28 +325,11 @@ export const registerRecordsCommand = (program: Command) => {
                 );
 
                 if (parseError) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: "Error parsing input data",
-                        Instructions: parseError.message,
-                    });
-                    processContext.exit(1);
-                    return;
+                    return fail("Error parsing input data", parseError.message);
                 }
 
-                const [clientError, sdk] = await catchError(
-                    createDataFabricClient(options.tenant),
-                );
-
-                if (clientError) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: "Error connecting to Data Fabric",
-                        Instructions: await extractErrorMessage(clientError),
-                    });
-                    processContext.exit(1);
-                    return;
-                }
+                const sdk = await connectOrFail(options.tenant);
+                if (!sdk) return;
 
                 const data = rawData as
                     | Record<string, unknown>
@@ -422,14 +342,10 @@ export const registerRecordsCommand = (program: Command) => {
                     );
 
                     if (insertError) {
-                        OutputFormatter.error({
-                            Result: RESULTS.Failure,
-                            Message: "Error inserting record",
-                            Instructions:
-                                await extractErrorMessage(insertError),
-                        });
-                        processContext.exit(1);
-                        return;
+                        return fail(
+                            "Error inserting record",
+                            await extractErrorMessage(insertError),
+                        );
                     }
 
                     OutputFormatter.success({
@@ -443,14 +359,10 @@ export const registerRecordsCommand = (program: Command) => {
                     );
 
                     if (insertError) {
-                        OutputFormatter.error({
-                            Result: RESULTS.Failure,
-                            Message: "Error inserting records",
-                            Instructions:
-                                await extractErrorMessage(insertError),
-                        });
-                        processContext.exit(1);
-                        return;
+                        return fail(
+                            "Error inserting records",
+                            await extractErrorMessage(insertError),
+                        );
                     }
 
                     const r = result as BatchResult;
@@ -485,7 +397,7 @@ export const registerRecordsCommand = (program: Command) => {
         )
         .option(
             "--body <json>",
-            "Inline JSON record data (must include Id field)",
+            "Inline JSON record data (must include Id field; use `-` to read from stdin)",
         )
         .examples(RECORDS_UPDATE_EXAMPLES)
         .trackedAction(
@@ -496,28 +408,11 @@ export const registerRecordsCommand = (program: Command) => {
                 );
 
                 if (parseError) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: "Error parsing input data",
-                        Instructions: parseError.message,
-                    });
-                    processContext.exit(1);
-                    return;
+                    return fail("Error parsing input data", parseError.message);
                 }
 
-                const [clientError, sdk] = await catchError(
-                    createDataFabricClient(options.tenant),
-                );
-
-                if (clientError) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: "Error connecting to Data Fabric",
-                        Instructions: await extractErrorMessage(clientError),
-                    });
-                    processContext.exit(1);
-                    return;
-                }
+                const sdk = await connectOrFail(options.tenant);
+                if (!sdk) return;
 
                 const data = rawData as
                     | Record<string, unknown>
@@ -529,14 +424,10 @@ export const registerRecordsCommand = (program: Command) => {
                     const recordId =
                         record.Id !== undefined ? record.Id : record.id;
                     if (recordId === undefined || recordId === null) {
-                        OutputFormatter.error({
-                            Result: RESULTS.Failure,
-                            Message: "Record must include an 'Id' field",
-                            Instructions:
-                                "Provide the record ID in the JSON data.",
-                        });
-                        processContext.exit(1);
-                        return;
+                        return fail(
+                            "Record must include an 'Id' field",
+                            "Provide the record ID in the JSON data.",
+                        );
                     }
 
                     const [updateError, result] = await catchError(
@@ -548,14 +439,10 @@ export const registerRecordsCommand = (program: Command) => {
                     );
 
                     if (updateError) {
-                        OutputFormatter.error({
-                            Result: RESULTS.Failure,
-                            Message: "Error updating record",
-                            Instructions:
-                                await extractErrorMessage(updateError),
-                        });
-                        processContext.exit(1);
-                        return;
+                        return fail(
+                            "Error updating record",
+                            await extractErrorMessage(updateError),
+                        );
                     }
 
                     OutputFormatter.success({
@@ -568,14 +455,10 @@ export const registerRecordsCommand = (program: Command) => {
                         (r) => r.Id == null && r.id == null,
                     );
                     if (missingId) {
-                        OutputFormatter.error({
-                            Result: RESULTS.Failure,
-                            Message: "All records must include an 'Id' field",
-                            Instructions:
-                                "Provide the record ID in each JSON object.",
-                        });
-                        processContext.exit(1);
-                        return;
+                        return fail(
+                            "All records must include an 'Id' field",
+                            "Provide the record ID in each JSON object.",
+                        );
                     }
 
                     const [updateError, result] = await catchError(
@@ -586,14 +469,10 @@ export const registerRecordsCommand = (program: Command) => {
                     );
 
                     if (updateError) {
-                        OutputFormatter.error({
-                            Result: RESULTS.Failure,
-                            Message: "Error updating records",
-                            Instructions:
-                                await extractErrorMessage(updateError),
-                        });
-                        processContext.exit(1);
-                        return;
+                        return fail(
+                            "Error updating records",
+                            await extractErrorMessage(updateError),
+                        );
                     }
 
                     const r = result as BatchResult;
@@ -633,7 +512,7 @@ export const registerRecordsCommand = (program: Command) => {
         )
         .option(
             "--body <json>",
-            "Inline JSON query options (filterGroup, selectedFields, sortOptions, aggregates, groupBy)",
+            "Inline JSON query options (filterGroup, selectedFields, sortOptions, aggregates, groupBy; use `-` to read from stdin)",
         )
         .option(
             "-l, --limit <number>",
@@ -653,41 +532,30 @@ export const registerRecordsCommand = (program: Command) => {
             async (entityId: string, options: QueryOptions) => {
                 const pageSize = Number(options.limit);
                 if (Number.isNaN(pageSize) || pageSize < 1) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: "Invalid --limit value",
-                        Instructions: "Provide a positive integer for --limit.",
-                    });
-                    processContext.exit(1);
-                    return;
+                    return fail(
+                        "Invalid --limit value",
+                        "Provide a positive integer for --limit.",
+                    );
                 }
 
                 if (
                     options.cursor !== undefined &&
                     options.offset !== undefined
                 ) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: "--offset and --cursor are mutually exclusive",
-                        Instructions:
-                            "Use --offset to jump to a position by record count, or --cursor to continue from a previous response.",
-                    });
-                    processContext.exit(1);
-                    return;
+                    return fail(
+                        "--offset and --cursor are mutually exclusive",
+                        "Use --offset to jump to a position by record count, or --cursor to continue from a previous response.",
+                    );
                 }
 
                 let jumpToPage: number | undefined;
                 if (options.offset !== undefined) {
                     const offsetValue = Number(options.offset);
                     if (Number.isNaN(offsetValue) || offsetValue < 0) {
-                        OutputFormatter.error({
-                            Result: RESULTS.Failure,
-                            Message: "Invalid --offset value",
-                            Instructions:
-                                "Provide a non-negative integer for --offset.",
-                        });
-                        processContext.exit(1);
-                        return;
+                        return fail(
+                            "Invalid --offset value",
+                            "Provide a non-negative integer for --offset.",
+                        );
                     }
                     jumpToPage = Math.floor(offsetValue / pageSize) + 1;
                 }
@@ -702,44 +570,26 @@ export const registerRecordsCommand = (program: Command) => {
                         ),
                     );
                     if (parseError) {
-                        OutputFormatter.error({
-                            Result: RESULTS.Failure,
-                            Message: "Error parsing query options",
-                            Instructions: parseError.message,
-                        });
-                        processContext.exit(1);
-                        return;
+                        return fail(
+                            "Error parsing query options",
+                            parseError.message,
+                        );
                     }
                     if (
                         typeof parsed !== "object" ||
                         parsed === null ||
                         Array.isArray(parsed)
                     ) {
-                        OutputFormatter.error({
-                            Result: RESULTS.Failure,
-                            Message: "Query options must be a JSON object",
-                            Instructions:
-                                "Provide a JSON object (not an array) with filterGroup, selectedFields, sortOptions, aggregates, or groupBy.",
-                        });
-                        processContext.exit(1);
-                        return;
+                        return fail(
+                            "Query options must be a JSON object",
+                            "Provide a JSON object (not an array) with filterGroup, selectedFields, sortOptions, aggregates, or groupBy.",
+                        );
                     }
                     queryBody = parsed as Record<string, unknown>;
                 }
 
-                const [clientError, sdk] = await catchError(
-                    createDataFabricClient(options.tenant),
-                );
-
-                if (clientError) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: "Error connecting to Data Fabric",
-                        Instructions: await extractErrorMessage(clientError),
-                    });
-                    processContext.exit(1);
-                    return;
-                }
+                const sdk = await connectOrFail(options.tenant);
+                if (!sdk) return;
 
                 const [queryError, result] = await catchError(
                     sdk.entities.queryRecordsById(entityId, {
@@ -753,42 +603,16 @@ export const registerRecordsCommand = (program: Command) => {
                 );
 
                 if (queryError) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: "Error querying records",
-                        Instructions: await extractErrorMessage(queryError),
-                    });
-                    processContext.exit(1);
-                    return;
+                    return fail(
+                        "Error querying records",
+                        await extractErrorMessage(queryError),
+                    );
                 }
 
-                const r = result as {
-                    items: unknown[];
-                    totalCount?: number;
-                    hasNextPage?: boolean;
-                    nextCursor?: unknown;
-                    currentPage?: number;
-                    totalPages?: number;
-                };
-                const nextCursor = extractCursorValue(r.nextCursor);
-
                 OutputFormatter.success({
                     Result: RESULTS.Success,
                     Code: "RecordQuery",
-                    Data: {
-                        TotalCount: r.totalCount ?? r.items.length,
-                        Records: r.items,
-                        HasNextPage: r.hasNextPage ?? false,
-                        ...(nextCursor !== undefined && {
-                            NextCursor: nextCursor,
-                        }),
-                        ...(r.currentPage !== undefined && {
-                            CurrentPage: r.currentPage,
-                        }),
-                        ...(r.totalPages !== undefined && {
-                            TotalPages: r.totalPages,
-                        }),
-                    },
+                    Data: result,
                 });
             },
         );
@@ -805,13 +629,10 @@ export const registerRecordsCommand = (program: Command) => {
             processContext,
             async (entityId: string, options: ImportOptions) => {
                 if (options.file === undefined) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: "A CSV file path is required",
-                        Instructions: "Provide a CSV file path via --file.",
-                    });
-                    processContext.exit(1);
-                    return;
+                    return fail(
+                        "A CSV file path is required",
+                        "Provide a CSV file path via --file.",
+                    );
                 }
 
                 const [readError, fileContent] = await catchError(
@@ -819,28 +640,11 @@ export const registerRecordsCommand = (program: Command) => {
                 );
 
                 if (readError) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: "Error reading CSV file",
-                        Instructions: readError.message,
-                    });
-                    processContext.exit(1);
-                    return;
+                    return fail("Error reading CSV file", readError.message);
                 }
 
-                const [clientError, sdk] = await catchError(
-                    createDataFabricClient(options.tenant),
-                );
-
-                if (clientError) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: "Error connecting to Data Fabric",
-                        Instructions: await extractErrorMessage(clientError),
-                    });
-                    processContext.exit(1);
-                    return;
-                }
+                const sdk = await connectOrFail(options.tenant);
+                if (!sdk) return;
 
                 const fs = getFileSystem();
                 const fileName = fs.path.basename(options.file) || "import.csv";
@@ -854,13 +658,10 @@ export const registerRecordsCommand = (program: Command) => {
                 );
 
                 if (importError) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: "Error importing records",
-                        Instructions: await extractErrorMessage(importError),
-                    });
-                    processContext.exit(1);
-                    return;
+                    return fail(
+                        "Error importing records",
+                        await extractErrorMessage(importError),
+                    );
                 }
 
                 const r = result as {
@@ -891,6 +692,14 @@ export const registerRecordsCommand = (program: Command) => {
         .addOption(
             createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
         )
+        .option("-y, --yes", "Acknowledge this is an irreversible operation")
+        .addOption(
+            new Option("--confirm", "Deprecated alias for --yes").hideHelp(),
+        )
+        .option(
+            "--reason <reason>",
+            "Reason for the deletion — echoed back in the response so the caller can log it",
+        )
         .examples(RECORDS_DELETE_EXAMPLES)
         .trackedAction(
             processContext,
@@ -899,32 +708,25 @@ export const registerRecordsCommand = (program: Command) => {
                 recordIds: string[],
                 options: DeleteOptions,
             ) => {
-                const [clientError, sdk] = await catchError(
-                    createDataFabricClient(options.tenant),
+                const reason = requireDestructiveConfirmation(
+                    options,
+                    `delete ${recordIds.length} record(s) from entity '${entityId}'`,
+                    'Pass --reason "<text>" to record why the records are being deleted.',
                 );
+                if (reason === null) return;
 
-                if (clientError) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: "Error connecting to Data Fabric",
-                        Instructions: await extractErrorMessage(clientError),
-                    });
-                    processContext.exit(1);
-                    return;
-                }
+                const sdk = await connectOrFail(options.tenant);
+                if (!sdk) return;
 
                 const [deleteError, result] = await catchError(
                     sdk.entities.deleteRecordsById(entityId, recordIds),
                 );
 
                 if (deleteError) {
-                    OutputFormatter.error({
-                        Result: RESULTS.Failure,
-                        Message: "Error deleting records",
-                        Instructions: await extractErrorMessage(deleteError),
-                    });
-                    processContext.exit(1);
-                    return;
+                    return fail(
+                        "Error deleting records",
+                        await extractErrorMessage(deleteError),
+                    );
                 }
 
                 const r = result as BatchResult;
@@ -937,6 +739,7 @@ export const registerRecordsCommand = (program: Command) => {
                         FailureCount: failureCount,
                         SuccessRecords: r.successRecords ?? [],
                         FailureRecords: r.failureRecords ?? [],
+                        Reason: reason,
                     },
                 });
                 if (failureCount > 0) {