@uipath/data-fabric-tool 0.9.0

package/src/commands/records.spec.ts

@@ -0,0 +1,2106 @@
+import { Command } from "commander";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../utils/sdk-client", () => ({
+    createDataFabricClient: vi.fn(),
+}));
+
+vi.mock("@uipath/common", async (importOriginal) => {
+    const actual = await importOriginal<typeof import("@uipath/common")>();
+    return {
+        ...actual,
+        OutputFormatter: {
+            success: vi.fn(),
+            error: vi.fn(),
+        },
+    };
+});
+
+vi.mock("@uipath/filesystem", () => ({
+    getFileSystem: vi.fn(() => ({
+        readFile: vi.fn().mockResolvedValue(null),
+    })),
+}));
+
+import { OutputFormatter } from "@uipath/common";
+import { createDataFabricClient } from "../utils/sdk-client";
+import { registerRecordsCommand } from "./records";
+
+function buildProgram(): Command {
+    const program = new Command();
+    program.name("test").exitOverride();
+    registerRecordsCommand(program);
+    return program;
+}
+
+function mockSdk(overrides: Record<string, unknown> = {}) {
+    const sdk = {
+        entities: {
+            getAllRecords: vi.fn().mockResolvedValue({
+                items: [],
+                totalCount: 0,
+            }),
+            getRecordById: vi.fn().mockResolvedValue({ Id: "rec-1" }),
+            insertRecordById: vi.fn().mockResolvedValue({ Id: "rec-2" }),
+            insertRecordsById: vi.fn().mockResolvedValue({
+                successRecords: [],
+                failureRecords: [],
+            }),
+            updateRecordById: vi.fn().mockResolvedValue({ Id: "rec-1" }),
+            updateRecordsById: vi.fn().mockResolvedValue({
+                successRecords: [],
+                failureRecords: [],
+            }),
+            deleteRecordsById: vi.fn().mockResolvedValue({
+                successRecords: ["rec-1"],
+                failureRecords: [],
+            }),
+            queryRecordsById: vi.fn().mockResolvedValue({
+                items: [],
+                totalCount: 0,
+            }),
+            importRecordsById: vi.fn().mockResolvedValue({
+                insertedRecords: 0,
+                totalRecords: 0,
+            }),
+            ...overrides,
+        },
+    };
+    vi.mocked(createDataFabricClient).mockResolvedValue(sdk as never);
+    return sdk;
+}
+
+describe("records list", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should register the records command", () => {
+        const program = buildProgram();
+        const cmd = program.commands.find((c) => c.name() === "records");
+        expect(cmd).toBeDefined();
+        expect(cmd?.commands.map((c) => c.name())).toContain("list");
+    });
+
+    it("should list records successfully", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.getAllRecords).mockResolvedValue({
+            items: [{ Id: "rec-1", name: "test" }],
+            totalCount: 1,
+            hasNextPage: false,
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "list",
+            "entity-id",
+        ]);
+
+        expect(sdk.entities.getAllRecords).toHaveBeenCalledWith("entity-id", {
+            pageSize: 50,
+        });
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "RecordList",
+                Data: expect.objectContaining({
+                    TotalCount: 1,
+                    HasNextPage: false,
+                }),
+            }),
+        );
+    });
+
+    it("should pass cursor to SDK and include NextCursor in output", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.getAllRecords).mockResolvedValue({
+            items: [{ Id: "rec-2" }],
+            totalCount: 100,
+            hasNextPage: true,
+            nextCursor: "cursor-abc",
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "list",
+            "entity-id",
+            "--cursor",
+            "cursor-xyz",
+        ]);
+
+        expect(sdk.entities.getAllRecords).toHaveBeenCalledWith("entity-id", {
+            pageSize: 50,
+            cursor: { value: "cursor-xyz" },
+        });
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Data: expect.objectContaining({
+                    HasNextPage: true,
+                    NextCursor: "cursor-abc",
+                }),
+            }),
+        );
+    });
+
+    it("should return empty list when no records exist", async () => {
+        mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "list",
+            "entity-id",
+        ]);
+
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "RecordList",
+                Data: expect.objectContaining({ TotalCount: 0, Records: [] }),
+            }),
+        );
+        expect(process.exitCode).not.toBe(1);
+    });
+
+    it("should output error when list fails", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.getAllRecords).mockRejectedValue(
+            new Error("timeout"),
+        );
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "list",
+            "entity-id",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({ Result: "Failure" }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should error when --limit is not a number", async () => {
+        mockSdk();
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "list",
+            "entity-id",
+            "--limit",
+            "abc",
+        ]);
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Invalid --limit value",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should error when --limit is zero", async () => {
+        mockSdk();
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "list",
+            "entity-id",
+            "--limit",
+            "0",
+        ]);
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Invalid --limit value",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+});
+
+describe("records list client error", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should error when SDK connection fails on list", async () => {
+        vi.mocked(createDataFabricClient).mockRejectedValue(
+            new Error("Not logged in"),
+        );
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "list",
+            "entity-id",
+        ]);
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error connecting to Data Fabric",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should handle list result without items/totalCount (uses defaults)", async () => {
+        const sdk = mockSdk({
+            getAllRecords: vi
+                .fn()
+                .mockResolvedValue({ items: [], hasNextPage: false }),
+        });
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "list",
+            "entity-id",
+        ]);
+        expect(sdk.entities.getAllRecords).toHaveBeenCalled();
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Data: expect.objectContaining({
+                    TotalCount: 0,
+                    Records: [],
+                    HasNextPage: false,
+                }),
+            }),
+        );
+    });
+});
+
+describe("records get", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should get record successfully", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.getRecordById).mockResolvedValue({
+            Id: "rec-1",
+            amount: 100,
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "get",
+            "entity-id",
+            "rec-1",
+        ]);
+
+        expect(sdk.entities.getRecordById).toHaveBeenCalledWith(
+            "entity-id",
+            "rec-1",
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "RecordDetails",
+            }),
+        );
+    });
+
+    it("should output error when record not found (SDK throws)", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.getRecordById).mockRejectedValue(
+            new Error("Not found"),
+        );
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "get",
+            "entity-id",
+            "bad-id",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({ Result: "Failure" }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should output error when record returns null (not found)", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.getRecordById).mockResolvedValue(null as never);
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "get",
+            "entity-id",
+            "missing-id",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Record 'missing-id' not found in entity 'entity-id'",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+});
+
+describe("records get client error", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should error when SDK connection fails on get", async () => {
+        vi.mocked(createDataFabricClient).mockRejectedValue(
+            new Error("Not logged in"),
+        );
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "get",
+            "entity-id",
+            "rec-1",
+        ]);
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error connecting to Data Fabric",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+});
+
+describe("records insert", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should insert single record via --body", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.insertRecordById).mockResolvedValue({
+            Id: "new-rec",
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "insert",
+            "entity-id",
+            "--body",
+            '{"amount":100}',
+        ]);
+
+        expect(sdk.entities.insertRecordById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.objectContaining({ amount: 100 }),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "RecordInserted",
+            }),
+        );
+    });
+
+    it("should output error when no data provided", async () => {
+        mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "insert",
+            "entity-id",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({ Result: "Failure" }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should insert multiple records via --body array", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.insertRecordsById).mockResolvedValue({
+            successRecords: [{ Id: "rec-1" }, { Id: "rec-2" }],
+            failureRecords: [],
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "insert",
+            "entity-id",
+            "--body",
+            '[{"amount":100},{"amount":200}]',
+        ]);
+
+        expect(sdk.entities.insertRecordsById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.arrayContaining([
+                expect.objectContaining({ amount: 100 }),
+                expect.objectContaining({ amount: 200 }),
+            ]),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "RecordsBatchInserted",
+                Data: expect.objectContaining({ SuccessCount: 2 }),
+            }),
+        );
+    });
+
+    it("should error when single insert API fails", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.insertRecordById).mockRejectedValue(
+            new Error("insert failed"),
+        );
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "insert",
+            "entity-id",
+            "--body",
+            '{"amount":100}',
+        ]);
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error inserting record",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should error when SDK connection fails on insert", async () => {
+        vi.mocked(createDataFabricClient).mockRejectedValue(
+            new Error("Not logged in"),
+        );
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "insert",
+            "entity-id",
+            "--body",
+            '{"amount":100}',
+        ]);
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error connecting to Data Fabric",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should handle batch insert result without successRecords/failureRecords", async () => {
+        const sdk = mockSdk({
+            insertRecordsById: vi.fn().mockResolvedValue({}),
+        });
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "insert",
+            "entity-id",
+            "--body",
+            '[{"amount":100},{"amount":200}]',
+        ]);
+        expect(sdk.entities.insertRecordsById).toHaveBeenCalled();
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Data: expect.objectContaining({
+                    SuccessCount: 0,
+                    FailureCount: 0,
+                }),
+            }),
+        );
+    });
+
+    it("should error when batch insert fails", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.insertRecordsById).mockRejectedValue(
+            new Error("batch failed"),
+        );
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "insert",
+            "entity-id",
+            "--body",
+            '[{"amount":100},{"amount":200}]',
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({ Result: "Failure" }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should error on partial batch insert failure (FailureCount > 0)", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.insertRecordsById).mockResolvedValue({
+            successRecords: [{ Id: "rec-1" }],
+            failureRecords: [{ error: "duplicate" }],
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "insert",
+            "entity-id",
+            "--body",
+            '[{"amount":100},{"amount":200}]',
+        ]);
+
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "RecordsBatchInserted",
+                Data: expect.objectContaining({
+                    FailureCount: 1,
+                    FailureRecords: [{ error: "duplicate" }],
+                }),
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+});
+
+describe("records update", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should update a single record via --body", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.updateRecordById).mockResolvedValue({
+            Id: "rec-1",
+            amount: 200,
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "update",
+            "entity-id",
+            "--body",
+            '{"Id":"rec-1","amount":200}',
+        ]);
+
+        expect(sdk.entities.updateRecordById).toHaveBeenCalledWith(
+            "entity-id",
+            "rec-1",
+            expect.objectContaining({ Id: "rec-1", amount: 200 }),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "RecordUpdated",
+            }),
+        );
+    });
+
+    it("should error when single record is missing Id", async () => {
+        mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "update",
+            "entity-id",
+            "--body",
+            '{"amount":200}',
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Record must include an 'Id' field",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should update batch records via --body", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.updateRecordsById).mockResolvedValue({
+            successRecords: [{ Id: "rec-1" }, { Id: "rec-2" }],
+            failureRecords: [],
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "update",
+            "entity-id",
+            "--body",
+            '[{"Id":"rec-1","amount":200},{"Id":"rec-2","amount":300}]',
+        ]);
+
+        expect(sdk.entities.updateRecordsById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.arrayContaining([
+                expect.objectContaining({ Id: "rec-1" }),
+                expect.objectContaining({ Id: "rec-2" }),
+            ]),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "RecordsBatchUpdated",
+                Data: expect.objectContaining({ SuccessCount: 2 }),
+            }),
+        );
+    });
+
+    it("should error when batch record is missing Id", async () => {
+        mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "update",
+            "entity-id",
+            "--body",
+            '[{"Id":"rec-1"},{"amount":300}]',
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "All records must include an 'Id' field",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should output error when update API fails", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.updateRecordById).mockRejectedValue(
+            new Error("update failed"),
+        );
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "update",
+            "entity-id",
+            "--body",
+            '{"Id":"rec-1","amount":200}',
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({ Result: "Failure" }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+});
+
+describe("records update parse error", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should error when --body is invalid JSON on update", async () => {
+        mockSdk();
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "update",
+            "entity-id",
+            "--body",
+            "not-valid-json",
+        ]);
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error parsing input data",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+});
+
+describe("records update client/batch errors", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should error when SDK connection fails on update", async () => {
+        vi.mocked(createDataFabricClient).mockRejectedValue(
+            new Error("Not logged in"),
+        );
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "update",
+            "entity-id",
+            "--body",
+            '{"Id":"rec-1"}',
+        ]);
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error connecting to Data Fabric",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should handle batch update result without successRecords/failureRecords", async () => {
+        const sdk = mockSdk({
+            updateRecordsById: vi.fn().mockResolvedValue({}),
+        });
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "update",
+            "entity-id",
+            "--body",
+            '[{"Id":"rec-1"},{"Id":"rec-2"}]',
+        ]);
+        expect(sdk.entities.updateRecordsById).toHaveBeenCalled();
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Data: expect.objectContaining({
+                    SuccessCount: 0,
+                    FailureCount: 0,
+                }),
+            }),
+        );
+    });
+
+    it("should error when batch update API fails", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.updateRecordsById).mockRejectedValue(
+            new Error("batch update failed"),
+        );
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "update",
+            "entity-id",
+            "--body",
+            '[{"Id":"rec-1"},{"Id":"rec-2"}]',
+        ]);
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error updating records",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should error on partial batch update failure (FailureCount > 0)", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.updateRecordsById).mockResolvedValue({
+            successRecords: [{ Id: "rec-1" }],
+            failureRecords: [{ error: "conflict" }],
+        });
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "update",
+            "entity-id",
+            "--body",
+            '[{"Id":"rec-1"},{"Id":"rec-2"}]',
+        ]);
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "RecordsBatchUpdated",
+                Data: expect.objectContaining({
+                    FailureCount: 1,
+                    FailureRecords: [{ error: "conflict" }],
+                }),
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+});
+
+describe("records delete", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should delete records successfully", async () => {
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "delete",
+            "entity-id",
+            "rec-1",
+            "rec-2",
+        ]);
+
+        expect(sdk.entities.deleteRecordsById).toHaveBeenCalledWith(
+            "entity-id",
+            ["rec-1", "rec-2"],
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "RecordsDeleted",
+            }),
+        );
+    });
+
+    it("should handle delete result without successRecords/failureRecords", async () => {
+        const sdk = mockSdk({
+            deleteRecordsById: vi.fn().mockResolvedValue({}),
+        });
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "delete",
+            "entity-id",
+            "rec-1",
+        ]);
+        expect(sdk.entities.deleteRecordsById).toHaveBeenCalled();
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Data: expect.objectContaining({
+                    SuccessCount: 0,
+                    FailureCount: 0,
+                }),
+            }),
+        );
+    });
+
+    it("should output error when delete fails", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.deleteRecordsById).mockRejectedValue(
+            new Error("forbidden"),
+        );
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "delete",
+            "entity-id",
+            "rec-1",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({ Result: "Failure" }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should error on partial batch delete failure (FailureCount > 0)", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.deleteRecordsById).mockResolvedValue({
+            successRecords: [{ id: "rec-1" }],
+            failureRecords: [{ error: "not found" }],
+        });
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "delete",
+            "entity-id",
+            "rec-1",
+            "rec-2",
+        ]);
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "RecordsDeleted",
+                Data: expect.objectContaining({
+                    FailureCount: 1,
+                    FailureRecords: [{ error: "not found" }],
+                }),
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+});
+
+describe("records delete client error", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should error when SDK connection fails on delete", async () => {
+        vi.mocked(createDataFabricClient).mockRejectedValue(
+            new Error("Not logged in"),
+        );
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "delete",
+            "entity-id",
+            "rec-1",
+        ]);
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error connecting to Data Fabric",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+});
+
+describe("records insert via --file", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should insert record from JSON file", async () => {
+        const sdk = mockSdk();
+        const { getFileSystem } = await import("@uipath/filesystem");
+        vi.mocked(getFileSystem).mockReturnValue({
+            readFile: vi.fn().mockResolvedValue('{"amount":100}'),
+            path: { basename: vi.fn().mockReturnValue("rec.json") },
+        } as never);
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "insert",
+            "entity-id",
+            "--file",
+            "rec.json",
+        ]);
+
+        expect(sdk.entities.insertRecordById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.objectContaining({ amount: 100 }),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "RecordInserted",
+            }),
+        );
+    });
+
+    it("should error when file cannot be read", async () => {
+        mockSdk();
+        const { getFileSystem } = await import("@uipath/filesystem");
+        vi.mocked(getFileSystem).mockReturnValue({
+            readFile: vi.fn().mockResolvedValue(null),
+            path: { basename: vi.fn().mockReturnValue("rec.json") },
+        } as never);
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "insert",
+            "entity-id",
+            "--file",
+            "missing.json",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({ Result: "Failure" }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should error when JSON body is not an object", async () => {
+        mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "insert",
+            "entity-id",
+            "--body",
+            '"just a string"',
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({ Result: "Failure" }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+});
+
+describe("records query", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should query records without filters (no --body)", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.queryRecordsById).mockResolvedValue({
+            items: [{ Id: "rec-1", title: "test" }],
+            totalCount: 1,
+            hasNextPage: false,
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "entity-id",
+        ]);
+
+        expect(sdk.entities.queryRecordsById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.objectContaining({ pageSize: 50 }),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "RecordQuery",
+                Data: expect.objectContaining({
+                    TotalCount: 1,
+                    HasNextPage: false,
+                }),
+            }),
+        );
+    });
+
+    it("should query records with filterGroup via --body", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.queryRecordsById).mockResolvedValue({
+            items: [{ Id: "rec-1", amount: 200 }],
+            totalCount: 1,
+            hasNextPage: false,
+        });
+
+        const filterBody = JSON.stringify({
+            filterGroup: {
+                logicalOperator: "And",
+                queryFilters: [
+                    {
+                        fieldName: "amount",
+                        operator: "GreaterThan",
+                        value: 100,
+                    },
+                ],
+            },
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "entity-id",
+            "--body",
+            filterBody,
+        ]);
+
+        expect(sdk.entities.queryRecordsById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.objectContaining({
+                filterGroup: expect.objectContaining({
+                    logicalOperator: "And",
+                }),
+                pageSize: 50,
+            }),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "RecordQuery",
+            }),
+        );
+    });
+
+    it("should query records with sortOptions via --body", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.queryRecordsById).mockResolvedValue({
+            items: [{ Id: "rec-2" }, { Id: "rec-1" }],
+            totalCount: 2,
+            hasNextPage: false,
+        });
+
+        const sortBody = JSON.stringify({
+            sortOptions: [{ fieldName: "amount", isAscending: false }],
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "entity-id",
+            "--body",
+            sortBody,
+        ]);
+
+        expect(sdk.entities.queryRecordsById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.objectContaining({
+                sortOptions: [{ fieldName: "amount", isAscending: false }],
+                pageSize: 50,
+            }),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "RecordQuery",
+                Data: expect.objectContaining({ TotalCount: 2 }),
+            }),
+        );
+    });
+
+    it("should query records with filterGroup and sortOptions combined", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.queryRecordsById).mockResolvedValue({
+            items: [{ Id: "rec-1" }],
+            totalCount: 1,
+            hasNextPage: false,
+        });
+
+        const combinedBody = JSON.stringify({
+            filterGroup: {
+                logicalOperator: "And",
+                queryFilters: [
+                    {
+                        fieldName: "status",
+                        operator: "Equals",
+                        value: "Active",
+                    },
+                ],
+            },
+            sortOptions: [{ fieldName: "createdAt", isAscending: true }],
+            selectedFields: ["Id", "status", "createdAt"],
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "entity-id",
+            "--body",
+            combinedBody,
+        ]);
+
+        expect(sdk.entities.queryRecordsById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.objectContaining({
+                filterGroup: expect.any(Object),
+                sortOptions: expect.any(Array),
+                selectedFields: ["Id", "status", "createdAt"],
+                pageSize: 50,
+            }),
+        );
+    });
+
+    it("should pass custom --limit and --cursor to queryRecordsById", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.queryRecordsById).mockResolvedValue({
+            items: [{ Id: "rec-3" }],
+            totalCount: 100,
+            hasNextPage: true,
+            nextCursor: "next-cursor-xyz",
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "entity-id",
+            "--limit",
+            "10",
+            "--cursor",
+            "prev-cursor",
+        ]);
+
+        expect(sdk.entities.queryRecordsById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.objectContaining({
+                pageSize: 10,
+                cursor: { value: "prev-cursor" },
+            }),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Data: expect.objectContaining({
+                    HasNextPage: true,
+                    NextCursor: "next-cursor-xyz",
+                }),
+            }),
+        );
+    });
+
+    it("should error when --limit is invalid on query", async () => {
+        mockSdk();
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "entity-id",
+            "--limit",
+            "bad",
+        ]);
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Invalid --limit value",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should error when --body is invalid JSON on query", async () => {
+        mockSdk();
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "entity-id",
+            "--body",
+            "not-json",
+        ]);
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error parsing query options",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should error when query body is an array instead of object", async () => {
+        mockSdk();
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "entity-id",
+            "--body",
+            '[{"filterGroup":{}}]',
+        ]);
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Query options must be a JSON object",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should error when SDK connection fails on query", async () => {
+        vi.mocked(createDataFabricClient).mockRejectedValue(
+            new Error("Not logged in"),
+        );
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "entity-id",
+        ]);
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error connecting to Data Fabric",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should error when query API fails", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.queryRecordsById).mockRejectedValue(
+            new Error("query failed"),
+        );
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "entity-id",
+        ]);
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error querying records",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+});
+
+describe("records import", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should error when no --file is provided", async () => {
+        mockSdk();
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "import",
+            "entity-id",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "A CSV file path is required",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should import records from CSV successfully", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.importRecordsById).mockResolvedValue({
+            insertedRecords: 2,
+            totalRecords: 2,
+        });
+
+        const { getFileSystem } = await import("@uipath/filesystem");
+        const csvBytes = new TextEncoder().encode(
+            "title,amount\ntest,100\nfoo,200",
+        );
+        vi.mocked(getFileSystem).mockReturnValue({
+            readFile: vi.fn().mockResolvedValue(csvBytes),
+            path: { basename: vi.fn().mockReturnValue("data.csv") },
+        } as never);
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "import",
+            "entity-id",
+            "--file",
+            "data.csv",
+        ]);
+
+        expect(sdk.entities.importRecordsById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.any(File),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "RecordsImported",
+                Data: expect.objectContaining({
+                    InsertedRecords: 2,
+                    TotalRecords: 2,
+                }),
+            }),
+        );
+    });
+
+    it("should include ErrorFileLink in output when import has partial errors", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.importRecordsById).mockResolvedValue({
+            insertedRecords: 1,
+            totalRecords: 2,
+            errorFileLink: "https://example.com/errors.csv",
+        });
+
+        const { getFileSystem } = await import("@uipath/filesystem");
+        vi.mocked(getFileSystem).mockReturnValue({
+            readFile: vi
+                .fn()
+                .mockResolvedValue(
+                    new TextEncoder().encode("title\nvalid\ninvalid"),
+                ),
+            path: { basename: vi.fn().mockReturnValue("data.csv") },
+        } as never);
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "import",
+            "entity-id",
+            "--file",
+            "data.csv",
+        ]);
+
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "RecordsImported",
+                Data: expect.objectContaining({
+                    InsertedRecords: 1,
+                    TotalRecords: 2,
+                    ErrorFileLink: "https://example.com/errors.csv",
+                }),
+            }),
+        );
+    });
+
+    it("should not include ErrorFileLink when import is fully successful", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.importRecordsById).mockResolvedValue({
+            insertedRecords: 3,
+            totalRecords: 3,
+        });
+
+        const { getFileSystem } = await import("@uipath/filesystem");
+        vi.mocked(getFileSystem).mockReturnValue({
+            readFile: vi
+                .fn()
+                .mockResolvedValue(new TextEncoder().encode("title\na\nb\nc")),
+            path: { basename: vi.fn().mockReturnValue("data.csv") },
+        } as never);
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "import",
+            "entity-id",
+            "--file",
+            "data.csv",
+        ]);
+
+        const call = vi.mocked(OutputFormatter.success).mock.calls[0][0] as {
+            Data: Record<string, unknown>;
+        };
+        expect(call.Data).not.toHaveProperty("ErrorFileLink");
+        expect(process.exitCode).not.toBe(1);
+    });
+
+    it("should error when CSV file cannot be read", async () => {
+        mockSdk();
+
+        const { getFileSystem } = await import("@uipath/filesystem");
+        vi.mocked(getFileSystem).mockReturnValue({
+            readFile: vi.fn().mockResolvedValue(null),
+        } as never);
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "import",
+            "entity-id",
+            "--file",
+            "missing.csv",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error reading CSV file",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should error when import API fails", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.importRecordsById).mockRejectedValue(
+            new Error("Import failed"),
+        );
+
+        const { getFileSystem } = await import("@uipath/filesystem");
+        vi.mocked(getFileSystem).mockReturnValue({
+            readFile: vi
+                .fn()
+                .mockResolvedValue(new TextEncoder().encode("title\ntest")),
+            path: { basename: vi.fn().mockReturnValue("data.csv") },
+        } as never);
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "import",
+            "entity-id",
+            "--file",
+            "data.csv",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error importing records",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should error when SDK connection fails on import", async () => {
+        vi.mocked(createDataFabricClient).mockRejectedValue(
+            new Error("Not logged in"),
+        );
+
+        const { getFileSystem } = await import("@uipath/filesystem");
+        vi.mocked(getFileSystem).mockReturnValue({
+            readFile: vi
+                .fn()
+                .mockResolvedValue(new TextEncoder().encode("title\ntest")),
+        } as never);
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "import",
+            "entity-id",
+            "--file",
+            "data.csv",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error connecting to Data Fabric",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+});
+
+describe("records query — pagination", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should return all records without pagination when no limit/cursor given", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.queryRecordsById).mockResolvedValue({
+            items: [{ Id: "r1" }, { Id: "r2" }, { Id: "r3" }],
+            totalCount: 3,
+            hasNextPage: false,
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "entity-id",
+        ]);
+
+        expect(sdk.entities.queryRecordsById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.objectContaining({ pageSize: 50 }),
+        );
+        const call = vi.mocked(OutputFormatter.success).mock
+            .calls[0][0] as unknown as {
+            Data: {
+                TotalCount: number;
+                Records: unknown[];
+                HasNextPage: boolean;
+            };
+        };
+        expect(call.Data.TotalCount).toBe(3);
+        expect(call.Data.Records).toHaveLength(3);
+        expect(call.Data.HasNextPage).toBe(false);
+    });
+
+    it("should return first page with cursor when paginated", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.queryRecordsById).mockResolvedValue({
+            items: [{ Id: "r1" }, { Id: "r2" }],
+            totalCount: 5,
+            hasNextPage: true,
+            nextCursor: "cursor-page2",
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "entity-id",
+            "--limit",
+            "2",
+        ]);
+
+        expect(sdk.entities.queryRecordsById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.objectContaining({ pageSize: 2 }),
+        );
+        const call = vi.mocked(OutputFormatter.success).mock
+            .calls[0][0] as unknown as {
+            Data: {
+                TotalCount: number;
+                Records: unknown[];
+                HasNextPage: boolean;
+                NextCursor: string;
+            };
+        };
+        expect(call.Data.TotalCount).toBe(5);
+        expect(call.Data.Records).toHaveLength(2);
+        expect(call.Data.HasNextPage).toBe(true);
+        expect(call.Data.NextCursor).toBe("cursor-page2");
+    });
+
+    it("should pass cursor to second page request", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.queryRecordsById).mockResolvedValue({
+            items: [{ Id: "r3" }, { Id: "r4" }],
+            totalCount: 5,
+            hasNextPage: true,
+            nextCursor: "cursor-page3",
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "entity-id",
+            "--limit",
+            "2",
+            "--cursor",
+            "cursor-page2",
+        ]);
+
+        expect(sdk.entities.queryRecordsById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.objectContaining({
+                pageSize: 2,
+                cursor: { value: "cursor-page2" },
+            }),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Data: expect.objectContaining({
+                    HasNextPage: true,
+                    NextCursor: "cursor-page3",
+                }),
+            }),
+        );
+    });
+
+    it("should apply filter AND sort together with pagination", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.queryRecordsById).mockResolvedValue({
+            items: [{ Id: "r1", status: "active" }],
+            totalCount: 10,
+            hasNextPage: true,
+            nextCursor: "cur-next",
+        });
+
+        const body = JSON.stringify({
+            filterGroup: {
+                queryFilters: [
+                    { fieldName: "status", operator: "=", value: "active" },
+                ],
+            },
+            sortOptions: [{ fieldName: "createTime", isDescending: true }],
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "entity-id",
+            "--body",
+            body,
+            "--limit",
+            "1",
+        ]);
+
+        expect(sdk.entities.queryRecordsById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.objectContaining({
+                filterGroup: expect.objectContaining({
+                    queryFilters: [
+                        { fieldName: "status", operator: "=", value: "active" },
+                    ],
+                }),
+                sortOptions: [{ fieldName: "createTime", isDescending: true }],
+                pageSize: 1,
+            }),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Data: expect.objectContaining({
+                    TotalCount: 10,
+                    HasNextPage: true,
+                    NextCursor: "cur-next",
+                }),
+            }),
+        );
+    });
+
+    it("should omit NextCursor when hasNextPage is false", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.queryRecordsById).mockResolvedValue({
+            items: [{ Id: "r1" }],
+            totalCount: 1,
+            hasNextPage: false,
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "entity-id",
+        ]);
+
+        const call = vi.mocked(OutputFormatter.success).mock.calls[0][0] as {
+            Data: Record<string, unknown>;
+        };
+        expect(call.Data).not.toHaveProperty("NextCursor");
+    });
+
+    it("should normalise cursor object {value} returned by SDK to a plain string", async () => {
+        const sdk = mockSdk();
+        // SDK may return PaginationCursor = { value: string } instead of a raw string
+        vi.mocked(sdk.entities.queryRecordsById).mockResolvedValue({
+            items: [{ Id: "r1" }, { Id: "r2" }],
+            totalCount: 4,
+            hasNextPage: true,
+            nextCursor: { value: "cursor-as-object" } as unknown as string,
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "entity-id",
+            "--limit",
+            "2",
+        ]);
+
+        const call = vi.mocked(OutputFormatter.success).mock
+            .calls[0][0] as unknown as {
+            Data: { NextCursor: unknown };
+        };
+        // Must be a plain string, not the object
+        expect(typeof call.Data.NextCursor).toBe("string");
+        expect(call.Data.NextCursor).toBe("cursor-as-object");
+    });
+
+    it("should use default limit 50 when --cursor is given without --limit", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.queryRecordsById).mockResolvedValue({
+            items: [{ Id: "r51" }],
+            totalCount: 51,
+            hasNextPage: false,
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "entity-id",
+            "--cursor",
+            "existing-cursor",
+        ]);
+
+        expect(sdk.entities.queryRecordsById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.objectContaining({
+                pageSize: 50,
+                cursor: { value: "existing-cursor" },
+            }),
+        );
+    });
+
+    it("should handle last page correctly — no NextCursor even if SDK emits undefined", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.queryRecordsById).mockResolvedValue({
+            items: [{ Id: "r5" }],
+            totalCount: 5,
+            hasNextPage: false,
+            nextCursor: undefined,
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "entity-id",
+            "--limit",
+            "4",
+            "--cursor",
+            "cursor-page2",
+        ]);
+
+        expect(sdk.entities.queryRecordsById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.objectContaining({
+                pageSize: 4,
+                cursor: { value: "cursor-page2" },
+            }),
+        );
+        const call = vi.mocked(OutputFormatter.success).mock.calls[0][0] as {
+            Data: Record<string, unknown>;
+        };
+        expect(call.Data.HasNextPage).toBe(false);
+        expect(call.Data).not.toHaveProperty("NextCursor");
+    });
+});
+
+describe("records — negative scenarios", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        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(
+            new Error("Entity not found"),
+        );
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "nonexistent-entity-id",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error querying records",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("records insert — entity not found returns error", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.insertRecordById).mockRejectedValue(
+            new Error("Entity not found"),
+        );
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "insert",
+            "nonexistent-entity-id",
+            "--body",
+            '{"field":"value"}',
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error inserting record",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("records delete — record not found returns error", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.deleteRecordsById).mockRejectedValue(
+            new Error("Record not found"),
+        );
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "delete",
+            "entity-id",
+            "nonexistent-record-id",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error deleting records",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("records get — record not found returns error", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.getRecordById).mockRejectedValue(
+            new Error("404 Not Found"),
+        );
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "get",
+            "entity-id",
+            "nonexistent-record",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({ Result: "Failure" }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("records import — entity not found returns error", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.importRecordsById).mockRejectedValue(
+            new Error("Entity not found"),
+        );
+
+        const { getFileSystem } = await import("@uipath/filesystem");
+        vi.mocked(getFileSystem).mockReturnValue({
+            readFile: vi
+                .fn()
+                .mockResolvedValue(new TextEncoder().encode("title\ntest")),
+            path: { basename: vi.fn().mockReturnValue("data.csv") },
+        } as never);
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "import",
+            "nonexistent-entity-id",
+            "--file",
+            "data.csv",
+        ]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error importing records",
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+});