@uipath/data-fabric-tool 0.9.1 → 1.0.1

package/src/commands/entities.ts

@@ -37,6 +37,14 @@ interface UpdateEntityOptions {
     tenant?: string;
     file?: string;
     body?: string;
+    confirm?: boolean;
+    reason?: string;
+}
+
+interface DeleteOptions {
+    tenant?: string;
+    confirm?: boolean;
+    reason?: string;
 }
 
 const ENTITIES_LIST_EXAMPLES: CommandExample[] = [
@@ -106,6 +114,22 @@ const ENTITIES_GET_EXAMPLES: CommandExample[] = [
     },
 ];
 
+const ENTITIES_DELETE_EXAMPLES: CommandExample[] = [
+    {
+        Description:
+            "Delete an entity (irreversible — requires --confirm and --reason)",
+        Command:
+            'uip df entities delete a1b2c3d4-0000-0000-0000-000000000001 --confirm --reason "test entity cleanup"',
+        Output: {
+            Code: "EntityDeleted",
+            Data: {
+                ID: "a1b2c3d4-0000-0000-0000-000000000001",
+                Reason: "test entity cleanup",
+            },
+        },
+    },
+];
+
 const VALID_FIELD_TYPES = new Set(Object.values(EntityFieldDataType));
 const VALID_FIELD_TYPES_LIST = [...VALID_FIELD_TYPES].join(", ");
 
@@ -119,6 +143,25 @@ function hasInvalidFieldType(fields: unknown[]): boolean {
     });
 }
 
+const KNOWN_UPDATE_KEYS = [
+    "addFields",
+    "removeFields",
+    "updateFields",
+    "displayName",
+    "description",
+    "isRbacEnabled",
+] as const;
+
+function pickKnownUpdateKeys(
+    input: Record<string, unknown>,
+): EntityUpdateByIdOptions {
+    const out: Record<string, unknown> = {};
+    for (const key of KNOWN_UPDATE_KEYS) {
+        if (input[key] !== undefined) out[key] = input[key];
+    }
+    return out as EntityUpdateByIdOptions;
+}
+
 export const registerEntitiesCommand = (program: Command) => {
     const entities = program
         .command("entities")
@@ -417,9 +460,17 @@ export const registerEntitiesCommand = (program: Command) => {
         .option("-t, --tenant <tenant-name>", "Tenant name")
         .option(
             "-f, --file <path>",
-            "Path to JSON file with update options (addFields, updateFields, displayName, description, isRbacEnabled)",
+            "Path to JSON file with update options (addFields, updateFields, removeFields, displayName, description, isRbacEnabled)",
         )
         .option("--body <json>", "Inline JSON update options")
+        .option(
+            "--confirm",
+            "Required when 'removeFields' is non-empty — acknowledges the field deletion is irreversible",
+        )
+        .option(
+            "--reason <reason>",
+            "Required when 'removeFields' is non-empty — echoed back in the response so the caller can log it",
+        )
         .trackedAction(
             processContext,
             async (id: string, options: UpdateEntityOptions) => {
@@ -450,37 +501,125 @@ export const registerEntitiesCommand = (program: Command) => {
                         Result: RESULTS.Failure,
                         Message: "Update options must be a JSON object",
                         Instructions:
-                            "Provide a JSON object with addFields, updateFields, displayName, description, or isRbacEnabled.",
+                            "Provide a JSON object with addFields, updateFields, removeFields, displayName, description, or isRbacEnabled.",
                     });
                     processContext.exit(1);
                     return;
                 }
 
                 const input = parsed as Record<string, unknown>;
-                if (input.removeFields !== undefined) {
+
+                if (
+                    input.addFields !== undefined &&
+                    !Array.isArray(input.addFields)
+                ) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "'addFields' must be an array",
+                        Instructions:
+                            'Example: {"addFields":[{"fieldName":"title","type":"STRING"}]}',
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                if (
+                    input.updateFields !== undefined &&
+                    !Array.isArray(input.updateFields)
+                ) {
                     OutputFormatter.error({
                         Result: RESULTS.Failure,
-                        Message: "removeFields is not supported",
+                        Message: "'updateFields' must be an array",
                         Instructions:
-                            "Removing fields is not supported at this time. Use addFields or updateFields instead.",
+                            'Example: {"updateFields":[{"id":"<fieldId>","displayName":"New Name"}]}',
                     });
                     processContext.exit(1);
                     return;
                 }
 
+                if (
+                    input.removeFields !== undefined &&
+                    !Array.isArray(input.removeFields)
+                ) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "'removeFields' must be an array",
+                        Instructions:
+                            'Example: {"removeFields":[{"fieldName":"old_field"}]}',
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                let trimmedReason: string | undefined;
+                let removedFieldNames: string[] = [];
+                const hasRemove =
+                    Array.isArray(input.removeFields) &&
+                    input.removeFields.length > 0;
+
+                if (hasRemove) {
+                    const removeFields = input.removeFields as unknown[];
+                    const hasInvalidRemove = removeFields.some((f) => {
+                        if (typeof f !== "object" || f === null) return true;
+                        const fn = (f as Record<string, unknown>).fieldName;
+                        return typeof fn !== "string" || fn.trim() === "";
+                    });
+                    if (hasInvalidRemove) {
+                        OutputFormatter.error({
+                            Result: RESULTS.Failure,
+                            Message:
+                                "Each field in removeFields must include a non-empty 'fieldName' string",
+                            Instructions:
+                                'Example: {"removeFields":[{"fieldName":"old_field"}]}',
+                        });
+                        processContext.exit(1);
+                        return;
+                    }
+
+                    if (options.confirm !== true) {
+                        OutputFormatter.error({
+                            Result: RESULTS.Failure,
+                            Message:
+                                "Confirmation required for destructive operation",
+                            Instructions:
+                                "Pass --confirm to acknowledge field deletion is irreversible.",
+                        });
+                        processContext.exit(1);
+                        return;
+                    }
+
+                    trimmedReason = options.reason?.trim();
+                    if (trimmedReason === undefined || trimmedReason === "") {
+                        OutputFormatter.error({
+                            Result: RESULTS.Failure,
+                            Message:
+                                "Reason required for destructive operation",
+                            Instructions:
+                                'Pass --reason "<text>" to record why fields are being removed.',
+                        });
+                        processContext.exit(1);
+                        return;
+                    }
+
+                    removedFieldNames = (
+                        removeFields as { fieldName: string }[]
+                    ).map((f) => f.fieldName);
+                }
+
                 if (Array.isArray(input.addFields)) {
                     const hasInvalidField = (input.addFields as unknown[]).some(
-                        (f) =>
-                            typeof f !== "object" ||
-                            f === null ||
-                            typeof (f as Record<string, unknown>).fieldName !==
-                                "string",
+                        (f) => {
+                            if (typeof f !== "object" || f === null)
+                                return true;
+                            const fn = (f as Record<string, unknown>).fieldName;
+                            return typeof fn !== "string" || fn.trim() === "";
+                        },
                     );
                     if (hasInvalidField) {
                         OutputFormatter.error({
                             Result: RESULTS.Failure,
                             Message:
-                                "Each field in addFields must include a 'fieldName' string",
+                                "Each field in addFields must include a non-empty 'fieldName' string",
                             Instructions:
                                 'Example: {"fieldName":"title","type":"STRING"}',
                         });
@@ -497,23 +636,54 @@ export const registerEntitiesCommand = (program: Command) => {
                         processContext.exit(1);
                         return;
                     }
+
+                    const addNames = (
+                        input.addFields as { fieldName: string }[]
+                    ).map((f) => f.fieldName);
+                    const duplicateAdd = addNames.find(
+                        (name, i) => addNames.indexOf(name) !== i,
+                    );
+                    if (duplicateAdd !== undefined) {
+                        OutputFormatter.error({
+                            Result: RESULTS.Failure,
+                            Message: `Duplicate fieldName '${duplicateAdd}' in addFields`,
+                            Instructions:
+                                "Each entry in addFields must have a unique fieldName.",
+                        });
+                        processContext.exit(1);
+                        return;
+                    }
+
+                    if (removedFieldNames.length > 0) {
+                        const conflict = addNames.find((name) =>
+                            removedFieldNames.includes(name),
+                        );
+                        if (conflict !== undefined) {
+                            OutputFormatter.error({
+                                Result: RESULTS.Failure,
+                                Message: `Field '${conflict}' appears in both addFields and removeFields`,
+                                Instructions:
+                                    "A single update cannot add and remove the same field. Split into two calls if you need to recreate it.",
+                            });
+                            processContext.exit(1);
+                            return;
+                        }
+                    }
                 }
 
                 if (Array.isArray(input.updateFields)) {
                     const hasInvalidField = (
                         input.updateFields as unknown[]
-                    ).some(
-                        (f) =>
-                            typeof f !== "object" ||
-                            f === null ||
-                            typeof (f as Record<string, unknown>).id !==
-                                "string",
-                    );
+                    ).some((f) => {
+                        if (typeof f !== "object" || f === null) return true;
+                        const fid = (f as Record<string, unknown>).id;
+                        return typeof fid !== "string" || fid.trim() === "";
+                    });
                     if (hasInvalidField) {
                         OutputFormatter.error({
                             Result: RESULTS.Failure,
                             Message:
-                                "Each field in updateFields must include an 'id' string",
+                                "Each field in updateFields must include a non-empty 'id' string",
                             Instructions:
                                 'Use \'df entities get <entityId>\' to find field IDs. Example: {"id":"<fieldId>","displayName":"Total Amount","isRequired":true}',
                         });
@@ -538,10 +708,7 @@ export const registerEntitiesCommand = (program: Command) => {
 
                 const entityService: EntityServiceModel = sdk.entities;
                 const [updateError] = await catchError(
-                    entityService.updateById(
-                        id,
-                        input as EntityUpdateByIdOptions,
-                    ),
+                    entityService.updateById(id, pickKnownUpdateKeys(input)),
                 );
 
                 if (updateError) {
@@ -557,7 +724,88 @@ export const registerEntitiesCommand = (program: Command) => {
                 OutputFormatter.success({
                     Result: RESULTS.Success,
                     Code: "EntityUpdated",
-                    Data: { ID: id },
+                    Data: {
+                        ID: id,
+                        ...(removedFieldNames.length > 0 && {
+                            RemovedFields: removedFieldNames,
+                            Reason: trimmedReason,
+                        }),
+                    },
+                });
+            },
+        );
+
+    entities
+        .command("delete")
+        .description("Delete a Data Fabric entity (irreversible)")
+        .argument("<id>", "Entity ID")
+        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .option("--confirm", "Acknowledge this is an irreversible operation")
+        .option(
+            "--reason <reason>",
+            "Reason for the deletion — echoed back in the response so the caller can log it",
+        )
+        .examples(ENTITIES_DELETE_EXAMPLES)
+        .trackedAction(
+            processContext,
+            async (id: string, options: DeleteOptions) => {
+                if (options.confirm !== true) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message:
+                            "Confirmation required for destructive operation",
+                        Instructions:
+                            "Pass --confirm to acknowledge this is irreversible.",
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                const reason = options.reason?.trim();
+                if (reason === undefined || reason === "") {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Reason required for destructive operation",
+                        Instructions:
+                            'Pass --reason "<text>" to record why the entity is being deleted.',
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                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 entityService: EntityServiceModel = sdk.entities;
+                const [deleteError] = await catchError(
+                    entityService.deleteById(id),
+                );
+
+                if (deleteError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: `Error deleting entity '${id}'`,
+                        Instructions: await extractErrorMessage(deleteError),
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                OutputFormatter.success({
+                    Result: RESULTS.Success,
+                    Code: "EntityDeleted",
+                    Data: { ID: id, Reason: reason },
                 });
             },
         );

package/src/commands/records.spec.ts

@@ -233,6 +233,126 @@ describe("records list", () => {
         );
         expect(process.exitCode).toBe(1);
     });
+
+    it("should pass jumpToPage to SDK when --offset is given", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.getAllRecords).mockResolvedValue({
+            items: [{ Id: "rec-51" }],
+            totalCount: 100,
+            hasNextPage: true,
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "list",
+            "entity-id",
+            "--offset",
+            "50",
+            "--limit",
+            "50",
+        ]);
+
+        expect(sdk.entities.getAllRecords).toHaveBeenCalledWith("entity-id", {
+            pageSize: 50,
+            jumpToPage: 2,
+        });
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({ Result: "Success", Code: "RecordList" }),
+        );
+    });
+
+    it("should use jumpToPage 1 when --offset is 0", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.getAllRecords).mockResolvedValue({
+            items: [{ Id: "rec-1" }],
+            totalCount: 10,
+            hasNextPage: false,
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "list",
+            "entity-id",
+            "--offset",
+            "0",
+        ]);
+
+        expect(sdk.entities.getAllRecords).toHaveBeenCalledWith("entity-id", {
+            pageSize: 50,
+            jumpToPage: 1,
+        });
+    });
+
+    it("should error when --offset and --cursor are both given on list", async () => {
+        mockSdk();
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "list",
+            "entity-id",
+            "--offset",
+            "50",
+            "--cursor",
+            "some-cursor",
+        ]);
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "--offset and --cursor are mutually exclusive",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should error when --offset is not a number on list", async () => {
+        mockSdk();
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "list",
+            "entity-id",
+            "--offset",
+            "abc",
+        ]);
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Invalid --offset value",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should error when --offset is negative on list", async () => {
+        mockSdk();
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "list",
+            "entity-id",
+            "--offset",
+            "-1",
+        ]);
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Invalid --offset value",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
 });
 
 describe("records list client error", () => {
@@ -1237,6 +1357,60 @@ describe("records query", () => {
         );
     });
 
+    it("should query records with aggregates and groupBy via --body", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.queryRecordsById).mockResolvedValue({
+            items: [
+                { status: "Open", total: 12 },
+                { status: "Closed", total: 5 },
+            ],
+            totalCount: 2,
+            hasNextPage: false,
+        });
+
+        const aggregateBody = JSON.stringify({
+            selectedFields: ["status"],
+            groupBy: ["status"],
+            aggregates: [{ function: "COUNT", field: "Id", alias: "total" }],
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "entity-id",
+            "--body",
+            aggregateBody,
+        ]);
+
+        expect(sdk.entities.queryRecordsById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.objectContaining({
+                selectedFields: ["status"],
+                groupBy: ["status"],
+                aggregates: [
+                    { function: "COUNT", field: "Id", alias: "total" },
+                ],
+                pageSize: 50,
+            }),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "RecordQuery",
+                Data: expect.objectContaining({
+                    TotalCount: 2,
+                    Records: [
+                        { status: "Open", total: 12 },
+                        { status: "Closed", total: 5 },
+                    ],
+                }),
+            }),
+        );
+    });
+
     it("should query records with filterGroup and sortOptions combined", async () => {
         const sdk = mockSdk();
         vi.mocked(sdk.entities.queryRecordsById).mockResolvedValue({
@@ -1920,6 +2094,83 @@ describe("records query — pagination", () => {
         );
     });
 
+    it("should pass jumpToPage to SDK when --offset is given on query", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.queryRecordsById).mockResolvedValue({
+            items: [{ Id: "r101" }],
+            totalCount: 200,
+            hasNextPage: true,
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "entity-id",
+            "--offset",
+            "100",
+            "--limit",
+            "50",
+        ]);
+
+        expect(sdk.entities.queryRecordsById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.objectContaining({
+                pageSize: 50,
+                jumpToPage: 3,
+            }),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({ Result: "Success", Code: "RecordQuery" }),
+        );
+    });
+
+    it("should error when --offset and --cursor are both given on query", async () => {
+        mockSdk();
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "entity-id",
+            "--offset",
+            "50",
+            "--cursor",
+            "some-cursor",
+        ]);
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "--offset and --cursor are mutually exclusive",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should error when --offset is invalid on query", async () => {
+        mockSdk();
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "entity-id",
+            "--offset",
+            "bad",
+        ]);
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Invalid --offset value",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
     it("should handle last page correctly — no NextCursor even if SDK emits undefined", async () => {
         const sdk = mockSdk();
         vi.mocked(sdk.entities.queryRecordsById).mockResolvedValue({
@@ -1963,16 +2214,6 @@ describe("records — negative scenarios", () => {
         process.exitCode = undefined;
     });
 
-    it("entities delete is not a registered command", async () => {
-        const { registerEntitiesCommand } = await import("./entities");
-        const { Command } = await import("commander");
-        const prog = new Command().exitOverride();
-        registerEntitiesCommand(prog);
-        const cmd = prog.commands.find((c) => c.name() === "entities");
-        const subNames = cmd?.commands.map((c) => c.name());
-        expect(subNames).not.toContain("delete");
-    });
-
     it("records query — entity not found returns error", async () => {
         const sdk = mockSdk();
         vi.mocked(sdk.entities.queryRecordsById).mockRejectedValue(