@uipath/data-fabric-tool 0.9.0

package/src/commands/files.spec.ts

@@ -0,0 +1,344 @@
+import { Command, CommanderError } 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(),
+        },
+    };
+});
+
+const mockFs = {
+    readFile: vi.fn(),
+    writeFile: vi.fn(),
+    path: { basename: vi.fn((p: string) => p.split("/").pop() ?? "") },
+};
+
+vi.mock("@uipath/filesystem", () => ({
+    getFileSystem: vi.fn(() => mockFs),
+}));
+
+import { OutputFormatter } from "@uipath/common";
+import { createDataFabricClient } from "../utils/sdk-client";
+import { registerFilesCommand } from "./files";
+
+function mockSdk(overrides: Record<string, unknown> = {}) {
+    const sdk = {
+        entities: {
+            uploadAttachment: vi.fn().mockResolvedValue({}),
+            downloadAttachment: vi.fn().mockResolvedValue(new Blob(["data"])),
+            deleteAttachment: vi.fn().mockResolvedValue({}),
+            ...overrides,
+        },
+    };
+    vi.mocked(createDataFabricClient).mockResolvedValue(sdk as never);
+    return sdk;
+}
+
+function buildProgram(): Command {
+    const program = new Command();
+    program.name("test").exitOverride();
+    registerFilesCommand(program);
+    return program;
+}
+
+async function runCommand(program: Command, args: string): Promise<void> {
+    try {
+        await program.parseAsync(args.split(" "), { from: "user" });
+    } catch (err) {
+        if (!(err instanceof CommanderError)) {
+            throw err;
+        }
+    }
+}
+
+describe("files upload", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        vi.mocked(OutputFormatter.success).mockReset();
+        vi.mocked(OutputFormatter.error).mockReset();
+    });
+
+    it("should error when --file is not provided", async () => {
+        mockSdk();
+        const program = buildProgram();
+        await runCommand(program, "files upload entity-1 record-1 attachment");
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "A file path is required",
+            }),
+        );
+    });
+
+    it("should error when file cannot be read", async () => {
+        mockSdk();
+        mockFs.readFile.mockResolvedValue(null);
+        const program = buildProgram();
+        await runCommand(
+            program,
+            "files upload entity-1 record-1 attachment --file /tmp/missing.pdf",
+        );
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error reading file",
+            }),
+        );
+    });
+
+    it("should upload and return FileUploaded on success", async () => {
+        const sdk = mockSdk();
+        mockFs.readFile.mockResolvedValue(new Uint8Array([1, 2, 3]));
+        const program = buildProgram();
+        await runCommand(
+            program,
+            "files upload entity-1 record-1 attachment --file /tmp/report.pdf",
+        );
+        expect(sdk.entities.uploadAttachment).toHaveBeenCalledWith(
+            "entity-1",
+            "record-1",
+            "attachment",
+            expect.any(File),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "FileUploaded",
+            }),
+        );
+    });
+
+    it("should use 'upload' as filename when basename returns empty string", async () => {
+        const sdk = mockSdk();
+        mockFs.readFile.mockResolvedValue(new Uint8Array([1, 2, 3]));
+        mockFs.path.basename.mockReturnValue("");
+        const program = buildProgram();
+        await runCommand(
+            program,
+            "files upload entity-1 record-1 attachment --file /tmp/report.pdf",
+        );
+        expect(sdk.entities.uploadAttachment).toHaveBeenCalledWith(
+            "entity-1",
+            "record-1",
+            "attachment",
+            expect.objectContaining({ name: "upload" }),
+        );
+    });
+
+    it("should error when SDK connection fails on upload", async () => {
+        vi.mocked(createDataFabricClient).mockRejectedValue(
+            new Error("Not logged in"),
+        );
+        mockFs.readFile.mockResolvedValue(new Uint8Array([1, 2, 3]));
+        const program = buildProgram();
+        await runCommand(
+            program,
+            "files upload entity-1 record-1 attachment --file /tmp/report.pdf",
+        );
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error connecting to Data Fabric",
+            }),
+        );
+    });
+
+    it("should error when upload API fails", async () => {
+        const sdk = mockSdk();
+        mockFs.readFile.mockResolvedValue(new Uint8Array([1, 2, 3]));
+        sdk.entities.uploadAttachment.mockRejectedValue(
+            new Error("Upload failed"),
+        );
+        const program = buildProgram();
+        await runCommand(
+            program,
+            "files upload entity-1 record-1 attachment --file /tmp/report.pdf",
+        );
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error uploading file to field 'attachment'",
+            }),
+        );
+    });
+});
+
+describe("files download", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        vi.mocked(OutputFormatter.success).mockReset();
+        vi.mocked(OutputFormatter.error).mockReset();
+    });
+
+    it("should download and write file to --destination path", async () => {
+        const blob = new Blob(["pdfdata"]);
+        mockSdk({ downloadAttachment: vi.fn().mockResolvedValue(blob) });
+        mockFs.writeFile.mockResolvedValue(undefined);
+        const program = buildProgram();
+        await runCommand(
+            program,
+            "files download entity-1 record-1 attachment --destination /tmp/out.pdf",
+        );
+        expect(mockFs.writeFile).toHaveBeenCalledWith(
+            "/tmp/out.pdf",
+            expect.any(Uint8Array),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "FileDownloaded",
+            }),
+        );
+    });
+
+    it("should error when download API fails", async () => {
+        const sdk = mockSdk();
+        sdk.entities.downloadAttachment.mockRejectedValue(
+            new Error("Server error"),
+        );
+        const program = buildProgram();
+        await runCommand(
+            program,
+            "files download entity-1 record-1 attachment",
+        );
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error downloading file from field 'attachment'",
+            }),
+        );
+    });
+
+    it("should error when SDK connection fails", async () => {
+        vi.mocked(createDataFabricClient).mockRejectedValue(
+            new Error("Not logged in"),
+        );
+        const program = buildProgram();
+        await runCommand(
+            program,
+            "files download entity-1 record-1 attachment",
+        );
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error connecting to Data Fabric",
+            }),
+        );
+    });
+});
+
+describe("files delete", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        vi.mocked(OutputFormatter.success).mockReset();
+        vi.mocked(OutputFormatter.error).mockReset();
+    });
+
+    it("should delete and return FileDeleted on success", async () => {
+        const sdk = mockSdk();
+        const program = buildProgram();
+        await runCommand(program, "files delete entity-1 record-1 attachment");
+        expect(sdk.entities.deleteAttachment).toHaveBeenCalledWith(
+            "entity-1",
+            "record-1",
+            "attachment",
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({ Result: "Success", Code: "FileDeleted" }),
+        );
+    });
+
+    it("should error when delete API fails", async () => {
+        const sdk = mockSdk();
+        sdk.entities.deleteAttachment.mockRejectedValue(new Error("Forbidden"));
+        const program = buildProgram();
+        await runCommand(program, "files delete entity-1 record-1 attachment");
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error deleting file from field 'attachment'",
+            }),
+        );
+    });
+
+    it("should error when SDK connection fails on delete", async () => {
+        vi.mocked(createDataFabricClient).mockRejectedValue(
+            new Error("Not logged in"),
+        );
+        const program = buildProgram();
+        await runCommand(program, "files delete entity-1 record-1 attachment");
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error connecting to Data Fabric",
+            }),
+        );
+    });
+});
+
+describe("files download edge cases", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        vi.mocked(OutputFormatter.success).mockReset();
+        vi.mocked(OutputFormatter.error).mockReset();
+    });
+
+    it("should error when writing downloaded file fails", async () => {
+        const blob = new Blob(["data"]);
+        mockSdk({ downloadAttachment: vi.fn().mockResolvedValue(blob) });
+        mockFs.writeFile.mockRejectedValue(new Error("Disk full"));
+        const program = buildProgram();
+        await runCommand(
+            program,
+            "files download entity-1 record-1 attachment --destination /tmp/out.bin",
+        );
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error writing downloaded file",
+            }),
+        );
+    });
+
+    it("should error when arrayBuffer() fails on blob", async () => {
+        const badBlob = {
+            arrayBuffer: () => Promise.reject(new Error("Stream error")),
+        };
+        mockSdk({ downloadAttachment: vi.fn().mockResolvedValue(badBlob) });
+        const program = buildProgram();
+        await runCommand(
+            program,
+            "files download entity-1 record-1 attachment --destination /tmp/out.bin",
+        );
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error reading downloaded file content",
+            }),
+        );
+    });
+
+    it("should use recordId_fieldName.bin as default destination", async () => {
+        const blob = new Blob(["data"]);
+        mockSdk({ downloadAttachment: vi.fn().mockResolvedValue(blob) });
+        mockFs.writeFile.mockResolvedValue(undefined);
+        const program = buildProgram();
+        await runCommand(
+            program,
+            "files download entity-1 record-1 attachment",
+        );
+        expect(mockFs.writeFile).toHaveBeenCalledWith(
+            "record-1_attachment.bin",
+            expect.any(Uint8Array),
+        );
+    });
+});

package/src/commands/files.ts

@@ -0,0 +1,339 @@
+import {
+    type CommandExample,
+    catchError,
+    extractErrorMessage,
+    OutputFormatter,
+    processContext,
+    RESULTS,
+} from "@uipath/common";
+import { getFileSystem } from "@uipath/filesystem";
+import type { Command } from "commander";
+import { readFileBinary } from "../utils/input";
+import { createDataFabricClient } from "../utils/sdk-client";
+
+interface UploadOptions {
+    tenant?: string;
+    file?: string;
+}
+
+interface DownloadOptions {
+    tenant?: string;
+    destination?: string;
+}
+
+interface DeleteOptions {
+    tenant?: string;
+}
+
+const FILES_UPLOAD_EXAMPLES: CommandExample[] = [
+    {
+        Description: "Upload a file attachment to a record field",
+        Command:
+            "uip df files upload a1b2c3d4-0000-0000-0000-000000000001 b2c3d4e5-0000-0000-0000-000000000001 invoice --file ./invoice.pdf",
+        Output: {
+            Code: "FileUploaded",
+            Data: {
+                EntityId: "a1b2c3d4-0000-0000-0000-000000000001",
+                RecordId: "b2c3d4e5-0000-0000-0000-000000000001",
+                FieldName: "invoice",
+                FileName: "invoice.pdf",
+            },
+        },
+    },
+];
+
+const FILES_DOWNLOAD_EXAMPLES: CommandExample[] = [
+    {
+        Description: "Download a file attachment from a record field",
+        Command:
+            "uip df files download a1b2c3d4-0000-0000-0000-000000000001 b2c3d4e5-0000-0000-0000-000000000001 invoice --destination ./invoice.pdf",
+        Output: {
+            Code: "FileDownloaded",
+            Data: {
+                EntityId: "a1b2c3d4-0000-0000-0000-000000000001",
+                RecordId: "b2c3d4e5-0000-0000-0000-000000000001",
+                FieldName: "invoice",
+                OutputPath: "./invoice.pdf",
+            },
+        },
+    },
+];
+
+const FILES_DELETE_EXAMPLES: CommandExample[] = [
+    {
+        Description: "Delete a file attachment from a record field",
+        Command:
+            "uip df files delete a1b2c3d4-0000-0000-0000-000000000001 b2c3d4e5-0000-0000-0000-000000000001 invoice",
+        Output: {
+            Code: "FileDeleted",
+            Data: {
+                EntityId: "a1b2c3d4-0000-0000-0000-000000000001",
+                RecordId: "b2c3d4e5-0000-0000-0000-000000000001",
+                FieldName: "invoice",
+            },
+        },
+    },
+];
+
+export const registerFilesCommand = (program: Command) => {
+    const files = program
+        .command("files")
+        .description("Manage file attachments on Data Fabric entity records");
+
+    files
+        .command("upload")
+        .description("Upload a file to a field on an entity record")
+        .argument("<entity-id>", "Entity ID")
+        .argument("<record-id>", "Record ID")
+        .argument("<field-name>", "Name of the file field (case-sensitive)")
+        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .option("-f, --file <path>", "Path to the file to upload")
+        .examples(FILES_UPLOAD_EXAMPLES)
+        .trackedAction(
+            processContext,
+            async (
+                entityId: string,
+                recordId: string,
+                fieldName: string,
+                options: UploadOptions,
+            ) => {
+                if (!options.file) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "A file path is required",
+                        Instructions: "Provide a file path via --file.",
+                    });
+                    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 [readError, fileContent] = await catchError(
+                    readFileBinary(options.file),
+                );
+
+                if (readError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Error reading file",
+                        Instructions: readError.message,
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                const fsInst = getFileSystem();
+                const fileName = fsInst.path.basename(options.file) || "upload";
+
+                const [uploadError] = await catchError(
+                    sdk.entities.uploadAttachment(
+                        entityId,
+                        recordId,
+                        fieldName,
+                        new File(
+                            [fileContent as Uint8Array<ArrayBuffer>],
+                            fileName,
+                        ),
+                    ),
+                );
+
+                if (uploadError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: `Error uploading file to field '${fieldName}'`,
+                        Instructions: await extractErrorMessage(uploadError),
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                OutputFormatter.success({
+                    Result: RESULTS.Success,
+                    Code: "FileUploaded",
+                    Data: {
+                        EntityId: entityId,
+                        RecordId: recordId,
+                        FieldName: fieldName,
+                        FileName: fileName,
+                    },
+                });
+            },
+        );
+
+    files
+        .command("download")
+        .description("Download a file from a field on an entity record")
+        .argument("<entity-id>", "Entity ID")
+        .argument("<record-id>", "Record ID")
+        .argument("<field-name>", "Name of the file field (case-sensitive)")
+        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .option(
+            "--destination <path>",
+            "Output file path (defaults to <record-id>_<field-name>.bin)",
+        )
+        .examples(FILES_DOWNLOAD_EXAMPLES)
+        .trackedAction(
+            processContext,
+            async (
+                entityId: string,
+                recordId: string,
+                fieldName: string,
+                options: DownloadOptions,
+            ) => {
+                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 [downloadError, blob] = await catchError(
+                    sdk.entities.downloadAttachment(
+                        entityId,
+                        recordId,
+                        fieldName,
+                    ),
+                );
+
+                if (downloadError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: `Error downloading file from field '${fieldName}'`,
+                        Instructions: await extractErrorMessage(downloadError),
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                const outputPath =
+                    options.destination ?? `${recordId}_${fieldName}.bin`;
+
+                const [bufferError, arrayBuffer] = await catchError(
+                    (blob as Blob).arrayBuffer(),
+                );
+
+                if (bufferError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Error reading downloaded file content",
+                        Instructions: bufferError.message,
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                const [writeError] = await catchError(
+                    writeFileBinary(outputPath, new Uint8Array(arrayBuffer)),
+                );
+
+                if (writeError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Error writing downloaded file",
+                        Instructions: writeError.message,
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                OutputFormatter.success({
+                    Result: RESULTS.Success,
+                    Code: "FileDownloaded",
+                    Data: {
+                        EntityId: entityId,
+                        RecordId: recordId,
+                        FieldName: fieldName,
+                        OutputPath: outputPath,
+                    },
+                });
+            },
+        );
+
+    files
+        .command("delete")
+        .description("Delete a file from a field on an entity record")
+        .argument("<entity-id>", "Entity ID")
+        .argument("<record-id>", "Record ID")
+        .argument("<field-name>", "Name of the file field (case-sensitive)")
+        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .examples(FILES_DELETE_EXAMPLES)
+        .trackedAction(
+            processContext,
+            async (
+                entityId: string,
+                recordId: string,
+                fieldName: string,
+                options: DeleteOptions,
+            ) => {
+                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 [deleteError] = await catchError(
+                    sdk.entities.deleteAttachment(
+                        entityId,
+                        recordId,
+                        fieldName,
+                    ),
+                );
+
+                if (deleteError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: `Error deleting file from field '${fieldName}'`,
+                        Instructions: await extractErrorMessage(deleteError),
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                OutputFormatter.success({
+                    Result: RESULTS.Success,
+                    Code: "FileDeleted",
+                    Data: {
+                        EntityId: entityId,
+                        RecordId: recordId,
+                        FieldName: fieldName,
+                    },
+                });
+            },
+        );
+};
+
+async function writeFileBinary(
+    filePath: string,
+    data: Uint8Array,
+): Promise<void> {
+    const fs = getFileSystem();
+    await fs.writeFile(filePath, data);
+}