@uipath/data-fabric-tool 0.9.0

package/src/commands/records.ts

@@ -0,0 +1,875 @@
+import {
+    type CommandExample,
+    catchError,
+    extractErrorMessage,
+    OutputFormatter,
+    processContext,
+    RESULTS,
+} from "@uipath/common";
+import { getFileSystem } from "@uipath/filesystem";
+import type { EntityRecord } from "@uipath/uipath-typescript";
+import type { Command } from "commander";
+import { readFileBinary, readJsonInput } from "../utils/input";
+import { createDataFabricClient } from "../utils/sdk-client";
+
+interface ListOptions {
+    tenant?: string;
+    limit: string;
+    cursor?: string;
+}
+
+interface GetOptions {
+    tenant?: string;
+}
+
+interface InsertOptions {
+    tenant?: string;
+    file?: string;
+    body?: string;
+}
+
+interface UpdateOptions {
+    tenant?: string;
+    file?: string;
+    body?: string;
+}
+
+interface DeleteOptions {
+    tenant?: string;
+}
+
+interface QueryOptions {
+    tenant?: string;
+    file?: string;
+    body?: string;
+    limit: string;
+    cursor?: string;
+}
+
+interface ImportOptions {
+    tenant?: string;
+    file?: string;
+}
+
+interface BatchResult {
+    successRecords?: unknown[];
+    failureRecords?: unknown[];
+}
+
+const RECORDS_LIST_EXAMPLES: CommandExample[] = [
+    {
+        Description: "List records in an entity",
+        Command:
+            "uip df records list a1b2c3d4-0000-0000-0000-000000000001 --limit 2",
+        Output: {
+            Code: "RecordList",
+            Data: {
+                TotalCount: 2,
+                Records: [
+                    {
+                        Id: "b2c3d4e5-0000-0000-0000-000000000001",
+                        amount: 1500,
+                    },
+                    {
+                        Id: "b2c3d4e5-0000-0000-0000-000000000002",
+                        amount: 2750,
+                    },
+                ],
+                HasNextPage: false,
+            },
+        },
+    },
+];
+
+const RECORDS_GET_EXAMPLES: CommandExample[] = [
+    {
+        Description: "Get a record by ID",
+        Command:
+            "uip df records get a1b2c3d4-0000-0000-0000-000000000001 b2c3d4e5-0000-0000-0000-000000000001",
+        Output: {
+            Code: "RecordDetails",
+            Data: {
+                Id: "b2c3d4e5-0000-0000-0000-000000000001",
+                amount: 1500,
+                status: "Paid",
+            },
+        },
+    },
+];
+
+const RECORDS_INSERT_EXAMPLES: CommandExample[] = [
+    {
+        Description: "Insert a record",
+        Command:
+            'uip df records insert a1b2c3d4-0000-0000-0000-000000000001 --body \'{"amount":1500,"status":"New"}\'',
+        Output: {
+            Code: "RecordInserted",
+            Data: {
+                Id: "b2c3d4e5-0000-0000-0000-000000000010",
+                amount: 1500,
+                status: "New",
+            },
+        },
+    },
+];
+
+const RECORDS_UPDATE_EXAMPLES: CommandExample[] = [
+    {
+        Description: "Update a record",
+        Command:
+            'uip df records update a1b2c3d4-0000-0000-0000-000000000001 --body \'{"Id":"b2c3d4e5-0000-0000-0000-000000000001","status":"Paid"}\'',
+        Output: {
+            Code: "RecordUpdated",
+            Data: {
+                Id: "b2c3d4e5-0000-0000-0000-000000000001",
+                status: "Paid",
+            },
+        },
+    },
+];
+
+const RECORDS_DELETE_EXAMPLES: CommandExample[] = [
+    {
+        Description: "Delete records by ID",
+        Command:
+            "uip df records delete a1b2c3d4-0000-0000-0000-000000000001 b2c3d4e5-0000-0000-0000-000000000001",
+        Output: {
+            Code: "RecordsDeleted",
+            Data: {
+                SuccessCount: 1,
+                FailureCount: 0,
+                SuccessRecords: [
+                    { Id: "b2c3d4e5-0000-0000-0000-000000000001" },
+                ],
+                FailureRecords: [],
+            },
+        },
+    },
+];
+
+export const registerRecordsCommand = (program: Command) => {
+    const records = program
+        .command("records")
+        .description("Manage Data Fabric entity records");
+
+    records
+        .command("list")
+        .description("List records in a Data Fabric entity")
+        .argument("<id>", "Entity ID")
+        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .option(
+            "-l, --limit <number>",
+            "Number of records to return per page",
+            "50",
+        )
+        .option(
+            "--cursor <cursor>",
+            "Pagination cursor from a previous response to fetch the next page",
+        )
+        .examples(RECORDS_LIST_EXAMPLES)
+        .trackedAction(
+            processContext,
+            async (entityId: string, options: ListOptions) => {
+                const pageSize = parseInt(options.limit, 10);
+                if (Number.isNaN(pageSize) || pageSize < 1) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Invalid --limit value",
+                        Instructions: "Provide a positive integer for --limit.",
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                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 [listError, result] = await catchError(
+                    sdk.entities.getAllRecords(entityId, {
+                        pageSize,
+                        ...(options.cursor !== undefined && {
+                            cursor: { value: options.cursor },
+                        }),
+                    }),
+                );
+
+                if (listError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Error listing records",
+                        Instructions: await extractErrorMessage(listError),
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                const r = result as {
+                    items: unknown[];
+                    totalCount?: number;
+                    hasNextPage?: boolean;
+                    nextCursor?: unknown;
+                    currentPage?: number;
+                    totalPages?: number;
+                };
+                const nextCursor = extractCursorValue(r.nextCursor);
+
+                OutputFormatter.success({
+                    Result: RESULTS.Success,
+                    Code: "RecordList",
+                    Data: {
+                        TotalCount: r.totalCount ?? r.items.length,
+                        Records: r.items,
+                        HasNextPage: r.hasNextPage ?? false,
+                        ...(nextCursor !== undefined && {
+                            NextCursor: nextCursor,
+                        }),
+                        ...(r.currentPage !== undefined && {
+                            CurrentPage: r.currentPage,
+                        }),
+                        ...(r.totalPages !== undefined && {
+                            TotalPages: r.totalPages,
+                        }),
+                    },
+                });
+            },
+        );
+
+    records
+        .command("get")
+        .description("Get a single record by ID")
+        .argument("<id>", "Entity ID")
+        .argument("<key>", "Record ID")
+        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .examples(RECORDS_GET_EXAMPLES)
+        .trackedAction(
+            processContext,
+            async (entityId: string, recordId: string, options: GetOptions) => {
+                const [clientError, sdk] = await catchError(
+                    createDataFabricClient(options.tenant),
+                );
+
+                if (clientError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Error connecting to Data Fabric",
+                        Instructions: await extractErrorMessage(clientError),
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                const [getError, record] = await catchError(
+                    sdk.entities.getRecordById(entityId, recordId),
+                );
+
+                if (getError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: `Error getting record '${recordId}'`,
+                        Instructions: await extractErrorMessage(getError),
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                if (!record) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: `Record '${recordId}' not found in entity '${entityId}'`,
+                        Instructions:
+                            "Verify the record ID exists. Use 'df records list' to see available records.",
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                OutputFormatter.success({
+                    Result: RESULTS.Success,
+                    Code: "RecordDetails",
+                    Data: record as Record<string, unknown>,
+                });
+            },
+        );
+
+    records
+        .command("insert")
+        .description("Insert records into a Data Fabric entity")
+        .argument("<id>", "Entity ID")
+        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .option(
+            "-f, --file <path>",
+            "Path to JSON file with record data (object or array of objects)",
+        )
+        .option(
+            "--body <json>",
+            "Inline JSON record data (object or array of objects)",
+        )
+        .examples(RECORDS_INSERT_EXAMPLES)
+        .trackedAction(
+            processContext,
+            async (entityId: string, options: InsertOptions) => {
+                const [parseError, rawData] = await catchError(
+                    resolveJsonInput(options.file, options.body),
+                );
+
+                if (parseError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Error parsing input data",
+                        Instructions: parseError.message,
+                    });
+                    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 data = rawData as
+                    | Record<string, unknown>
+                    | Record<string, unknown>[];
+                const recordsList = Array.isArray(data) ? data : [data];
+
+                if (recordsList.length === 1) {
+                    const [insertError, result] = await catchError(
+                        sdk.entities.insertRecordById(entityId, recordsList[0]),
+                    );
+
+                    if (insertError) {
+                        OutputFormatter.error({
+                            Result: RESULTS.Failure,
+                            Message: "Error inserting record",
+                            Instructions:
+                                await extractErrorMessage(insertError),
+                        });
+                        processContext.exit(1);
+                        return;
+                    }
+
+                    OutputFormatter.success({
+                        Result: RESULTS.Success,
+                        Code: "RecordInserted",
+                        Data: result as Record<string, unknown>,
+                    });
+                } else {
+                    const [insertError, result] = await catchError(
+                        sdk.entities.insertRecordsById(entityId, recordsList),
+                    );
+
+                    if (insertError) {
+                        OutputFormatter.error({
+                            Result: RESULTS.Failure,
+                            Message: "Error inserting records",
+                            Instructions:
+                                await extractErrorMessage(insertError),
+                        });
+                        processContext.exit(1);
+                        return;
+                    }
+
+                    const r = result as BatchResult;
+                    const failureCount = r.failureRecords?.length ?? 0;
+                    OutputFormatter.success({
+                        Result: RESULTS.Success,
+                        Code: "RecordsBatchInserted",
+                        Data: {
+                            SuccessCount: r.successRecords?.length ?? 0,
+                            FailureCount: failureCount,
+                            SuccessRecords: r.successRecords ?? [],
+                            FailureRecords: r.failureRecords ?? [],
+                        },
+                    });
+                    if (failureCount > 0) {
+                        processContext.exit(1);
+                    }
+                }
+            },
+        );
+
+    records
+        .command("update")
+        .description("Update records in a Data Fabric entity")
+        .argument("<id>", "Entity ID")
+        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .option(
+            "-f, --file <path>",
+            "Path to JSON file with record data (must include Id field)",
+        )
+        .option(
+            "--body <json>",
+            "Inline JSON record data (must include Id field)",
+        )
+        .examples(RECORDS_UPDATE_EXAMPLES)
+        .trackedAction(
+            processContext,
+            async (entityId: string, options: UpdateOptions) => {
+                const [parseError, rawData] = await catchError(
+                    resolveJsonInput(options.file, options.body),
+                );
+
+                if (parseError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Error parsing input data",
+                        Instructions: parseError.message,
+                    });
+                    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 data = rawData as
+                    | Record<string, unknown>
+                    | Record<string, unknown>[];
+                const recordsList = Array.isArray(data) ? data : [data];
+
+                if (recordsList.length === 1) {
+                    const record = recordsList[0];
+                    const recordId =
+                        record.Id !== undefined ? record.Id : record.id;
+                    if (recordId === undefined || recordId === null) {
+                        OutputFormatter.error({
+                            Result: RESULTS.Failure,
+                            Message: "Record must include an 'Id' field",
+                            Instructions:
+                                "Provide the record ID in the JSON data.",
+                        });
+                        processContext.exit(1);
+                        return;
+                    }
+
+                    const [updateError, result] = await catchError(
+                        sdk.entities.updateRecordById(
+                            entityId,
+                            String(recordId),
+                            record,
+                        ),
+                    );
+
+                    if (updateError) {
+                        OutputFormatter.error({
+                            Result: RESULTS.Failure,
+                            Message: "Error updating record",
+                            Instructions:
+                                await extractErrorMessage(updateError),
+                        });
+                        processContext.exit(1);
+                        return;
+                    }
+
+                    OutputFormatter.success({
+                        Result: RESULTS.Success,
+                        Code: "RecordUpdated",
+                        Data: result as Record<string, unknown>,
+                    });
+                } else {
+                    const missingId = recordsList.find(
+                        (r) => r.Id == null && r.id == null,
+                    );
+                    if (missingId) {
+                        OutputFormatter.error({
+                            Result: RESULTS.Failure,
+                            Message: "All records must include an 'Id' field",
+                            Instructions:
+                                "Provide the record ID in each JSON object.",
+                        });
+                        processContext.exit(1);
+                        return;
+                    }
+
+                    const [updateError, result] = await catchError(
+                        sdk.entities.updateRecordsById(
+                            entityId,
+                            recordsList as EntityRecord[],
+                        ),
+                    );
+
+                    if (updateError) {
+                        OutputFormatter.error({
+                            Result: RESULTS.Failure,
+                            Message: "Error updating records",
+                            Instructions:
+                                await extractErrorMessage(updateError),
+                        });
+                        processContext.exit(1);
+                        return;
+                    }
+
+                    const r = result as BatchResult;
+                    const failureCount = r.failureRecords?.length ?? 0;
+                    OutputFormatter.success({
+                        Result: RESULTS.Success,
+                        Code: "RecordsBatchUpdated",
+                        Data: {
+                            SuccessCount: r.successRecords?.length ?? 0,
+                            FailureCount: failureCount,
+                            SuccessRecords: r.successRecords ?? [],
+                            FailureRecords: r.failureRecords ?? [],
+                        },
+                    });
+                    if (failureCount > 0) {
+                        processContext.exit(1);
+                    }
+                }
+            },
+        );
+
+    records
+        .command("query")
+        .description(
+            "Query records in a Data Fabric entity with filters and sorting. " +
+                "Provide a JSON object via --body or --file with optional keys: " +
+                "filterGroup, sortOptions (use isDescending: true/false), selectedFields.",
+        )
+        .argument("<id>", "Entity ID")
+        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .option(
+            "-f, --file <path>",
+            "Path to JSON file with query options (filterGroup, selectedFields, sortOptions)",
+        )
+        .option(
+            "--body <json>",
+            "Inline JSON query options (filterGroup, selectedFields, sortOptions)",
+        )
+        .option(
+            "-l, --limit <number>",
+            "Number of records to return per page",
+            "50",
+        )
+        .option(
+            "--cursor <cursor>",
+            "Pagination cursor from a previous response to fetch the next page",
+        )
+        .trackedAction(
+            processContext,
+            async (entityId: string, options: QueryOptions) => {
+                const pageSize = parseInt(options.limit, 10);
+                if (Number.isNaN(pageSize) || pageSize < 1) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Invalid --limit value",
+                        Instructions: "Provide a positive integer for --limit.",
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                let queryBody: Record<string, unknown> | null = null;
+                if (options.file !== undefined || options.body !== undefined) {
+                    const [parseError, parsed] = await catchError(
+                        readJsonInput(
+                            options.file,
+                            options.body,
+                            "Provide a JSON object with query options via --file or --body.",
+                        ),
+                    );
+                    if (parseError) {
+                        OutputFormatter.error({
+                            Result: RESULTS.Failure,
+                            Message: "Error parsing query options",
+                            Instructions: parseError.message,
+                        });
+                        processContext.exit(1);
+                        return;
+                    }
+                    if (
+                        typeof parsed !== "object" ||
+                        parsed === null ||
+                        Array.isArray(parsed)
+                    ) {
+                        OutputFormatter.error({
+                            Result: RESULTS.Failure,
+                            Message: "Query options must be a JSON object",
+                            Instructions:
+                                "Provide a JSON object (not an array) with filterGroup, selectedFields, or sortOptions.",
+                        });
+                        processContext.exit(1);
+                        return;
+                    }
+                    queryBody = parsed as Record<string, unknown>;
+                }
+
+                const [clientError, sdk] = await catchError(
+                    createDataFabricClient(options.tenant),
+                );
+
+                if (clientError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Error connecting to Data Fabric",
+                        Instructions: await extractErrorMessage(clientError),
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                const [queryError, result] = await catchError(
+                    sdk.entities.queryRecordsById(entityId, {
+                        ...(queryBody !== null && queryBody),
+                        pageSize,
+                        ...(options.cursor !== undefined && {
+                            cursor: { value: options.cursor },
+                        }),
+                    }),
+                );
+
+                if (queryError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Error querying records",
+                        Instructions: await extractErrorMessage(queryError),
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                const r = result as {
+                    items: unknown[];
+                    totalCount?: number;
+                    hasNextPage?: boolean;
+                    nextCursor?: unknown;
+                    currentPage?: number;
+                    totalPages?: number;
+                };
+                const nextCursor = extractCursorValue(r.nextCursor);
+
+                OutputFormatter.success({
+                    Result: RESULTS.Success,
+                    Code: "RecordQuery",
+                    Data: {
+                        TotalCount: r.totalCount ?? r.items.length,
+                        Records: r.items,
+                        HasNextPage: r.hasNextPage ?? false,
+                        ...(nextCursor !== undefined && {
+                            NextCursor: nextCursor,
+                        }),
+                        ...(r.currentPage !== undefined && {
+                            CurrentPage: r.currentPage,
+                        }),
+                        ...(r.totalPages !== undefined && {
+                            TotalPages: r.totalPages,
+                        }),
+                    },
+                });
+            },
+        );
+
+    records
+        .command("import")
+        .description("Import records from a CSV file into a Data Fabric entity")
+        .argument("<id>", "Entity ID")
+        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .option("-f, --file <path>", "Path to the CSV file to import")
+        .trackedAction(
+            processContext,
+            async (entityId: string, options: ImportOptions) => {
+                if (options.file === undefined) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "A CSV file path is required",
+                        Instructions: "Provide a CSV file path via --file.",
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                const [readError, fileContent] = await catchError(
+                    readFileBinary(options.file),
+                );
+
+                if (readError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Error reading CSV file",
+                        Instructions: readError.message,
+                    });
+                    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 fs = getFileSystem();
+                const fileName = fs.path.basename(options.file) || "import.csv";
+                const csvFile = new File(
+                    [fileContent as Uint8Array<ArrayBuffer>],
+                    fileName,
+                    { type: "text/csv" },
+                );
+                const [importError, result] = await catchError(
+                    sdk.entities.importRecordsById(entityId, csvFile),
+                );
+
+                if (importError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Error importing records",
+                        Instructions: await extractErrorMessage(importError),
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                const r = result as {
+                    insertedRecords?: number;
+                    totalRecords?: number;
+                    errorFileLink?: string;
+                };
+
+                OutputFormatter.success({
+                    Result: RESULTS.Success,
+                    Code: "RecordsImported",
+                    Data: {
+                        InsertedRecords: r.insertedRecords ?? 0,
+                        TotalRecords: r.totalRecords ?? 0,
+                        ...(r.errorFileLink !== undefined && {
+                            ErrorFileLink: r.errorFileLink,
+                        }),
+                    },
+                });
+            },
+        );
+
+    records
+        .command("delete")
+        .description("Delete records from a Data Fabric entity")
+        .argument("<id>", "Entity ID")
+        .argument("<key...>", "Record IDs to delete")
+        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .examples(RECORDS_DELETE_EXAMPLES)
+        .trackedAction(
+            processContext,
+            async (
+                entityId: string,
+                recordIds: 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, result] = await catchError(
+                    sdk.entities.deleteRecordsById(entityId, recordIds),
+                );
+
+                if (deleteError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Error deleting records",
+                        Instructions: await extractErrorMessage(deleteError),
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                const r = result as BatchResult;
+                const failureCount = r.failureRecords?.length ?? 0;
+                OutputFormatter.success({
+                    Result: RESULTS.Success,
+                    Code: "RecordsDeleted",
+                    Data: {
+                        SuccessCount: r.successRecords?.length ?? 0,
+                        FailureCount: failureCount,
+                        SuccessRecords: r.successRecords ?? [],
+                        FailureRecords: r.failureRecords ?? [],
+                    },
+                });
+                if (failureCount > 0) {
+                    processContext.exit(1);
+                }
+            },
+        );
+};
+
+/** Normalises the SDK cursor to a plain string for CLI output.
+ *  The SDK returns `PaginationCursor = { value: string }` but we want
+ *  to expose just the string so the user can pass it directly to --cursor. */
+function extractCursorValue(cursor: unknown): string | undefined {
+    if (cursor === undefined || cursor === null) return undefined;
+    if (typeof cursor === "string") return cursor;
+    const c = cursor as Record<string, unknown>;
+    if (typeof c.value === "string") return c.value;
+    return undefined;
+}
+
+const isRecordObject = (value: unknown): value is Record<string, unknown> =>
+    typeof value === "object" && value !== null && !Array.isArray(value);
+
+async function resolveJsonInput(
+    filePath?: string,
+    inlineBody?: string,
+): Promise<Record<string, unknown> | Record<string, unknown>[]> {
+    const parsed = await readJsonInput(
+        filePath,
+        inlineBody,
+        "Provide either --file <path> or --body <json> with record data.",
+    );
+    if (
+        (!Array.isArray(parsed) && !isRecordObject(parsed)) ||
+        (Array.isArray(parsed) &&
+            parsed.some((item: unknown) => !isRecordObject(item)))
+    ) {
+        throw new Error(
+            "Input must be a JSON object or an array of JSON objects.",
+        );
+    }
+
+    return parsed as Record<string, unknown> | Record<string, unknown>[];
+}