@uipath/data-fabric-tool 0.9.0

package/src/commands/entities.ts

@@ -0,0 +1,564 @@
+import {
+    type CommandExample,
+    catchError,
+    extractErrorMessage,
+    OutputFormatter,
+    processContext,
+    RESULTS,
+} from "@uipath/common";
+import type {
+    EntityCreateFieldOptions,
+    EntityServiceModel,
+    EntityUpdateByIdOptions,
+    ExternalSourceFields,
+    RawEntityGetResponse,
+} from "@uipath/uipath-typescript";
+import { EntityFieldDataType } from "@uipath/uipath-typescript";
+import type { Command } from "commander";
+import { readJsonInput } from "../utils/input";
+import { createDataFabricClient } from "../utils/sdk-client";
+
+interface ListOptions {
+    tenant?: string;
+    nativeOnly?: boolean;
+}
+
+interface GetOptions {
+    tenant?: string;
+}
+
+interface CreateOptions {
+    tenant?: string;
+    file?: string;
+    body?: string;
+}
+
+interface UpdateEntityOptions {
+    tenant?: string;
+    file?: string;
+    body?: string;
+}
+
+const ENTITIES_LIST_EXAMPLES: CommandExample[] = [
+    {
+        Description: "List Data Fabric entities",
+        Command: "uip df entities list --native-only",
+        Output: {
+            Code: "EntityList",
+            Data: [
+                {
+                    Name: "Invoice",
+                    DisplayName: "Invoice",
+                    ID: "a1b2c3d4-0000-0000-0000-000000000001",
+                    Type: "Standard",
+                    Source: "Native",
+                    Description: "Invoice records",
+                    FieldCount: 8,
+                },
+                {
+                    Name: "Customer",
+                    DisplayName: "Customer",
+                    ID: "a1b2c3d4-0000-0000-0000-000000000002",
+                    Type: "Standard",
+                    Source: "Native",
+                    Description: "Customer records",
+                    FieldCount: 6,
+                },
+            ],
+        },
+    },
+];
+
+const ENTITIES_GET_EXAMPLES: CommandExample[] = [
+    {
+        Description: "Get entity schema by ID",
+        Command: "uip df entities get a1b2c3d4-0000-0000-0000-000000000001",
+        Output: {
+            Code: "EntitySchema",
+            Data: {
+                Name: "Invoice",
+                DisplayName: "Invoice",
+                ID: "a1b2c3d4-0000-0000-0000-000000000001",
+                Type: "Standard",
+                Description: "Invoice records",
+                Fields: [
+                    {
+                        ID: "f1000000-0000-0000-0000-000000000001",
+                        Name: "id",
+                        DisplayName: "ID",
+                        Type: "Guid",
+                        Required: true,
+                        PrimaryKey: true,
+                        System: true,
+                    },
+                    {
+                        ID: "f1000000-0000-0000-0000-000000000002",
+                        Name: "amount",
+                        DisplayName: "Amount",
+                        Type: "Decimal",
+                        Required: true,
+                        PrimaryKey: false,
+                        System: false,
+                    },
+                ],
+            },
+        },
+    },
+];
+
+const VALID_FIELD_TYPES = new Set(Object.values(EntityFieldDataType));
+const VALID_FIELD_TYPES_LIST = [...VALID_FIELD_TYPES].join(", ");
+
+function hasInvalidFieldType(fields: unknown[]): boolean {
+    return fields.some((f) => {
+        const field = f as Record<string, unknown>;
+        return (
+            field.type !== undefined &&
+            !VALID_FIELD_TYPES.has(field.type as EntityFieldDataType)
+        );
+    });
+}
+
+export const registerEntitiesCommand = (program: Command) => {
+    const entities = program
+        .command("entities")
+        .description("Browse Data Fabric entity schemas");
+
+    entities
+        .command("list")
+        .description("List all Data Fabric entities")
+        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .option(
+            "--native-only",
+            "Show only native entities (exclude federated entities with external connections)",
+        )
+        .examples(ENTITIES_LIST_EXAMPLES)
+        .trackedAction(processContext, async (options: ListOptions) => {
+            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.getAll());
+
+            if (listError) {
+                OutputFormatter.error({
+                    Result: RESULTS.Failure,
+                    Message: "Error listing entities",
+                    Instructions: await extractErrorMessage(listError),
+                });
+                processContext.exit(1);
+                return;
+            }
+
+            const entityList = (result ?? [])
+                .map((e) => {
+                    const entity = e as unknown as RawEntityGetResponse;
+                    const externalFields: ExternalSourceFields[] =
+                        entity.externalFields ?? [];
+                    const isNative = externalFields.length === 0;
+                    const connectorName =
+                        externalFields[0]?.externalConnectionDetail
+                            ?.connectorName;
+                    return {
+                        Name: entity.name,
+                        DisplayName: entity.displayName || entity.name,
+                        ID: entity.id,
+                        Type: entity.entityType,
+                        Source: isNative
+                            ? "Native"
+                            : `Federated${connectorName ? ` (${connectorName})` : ""}`,
+                        Description: entity.description || "",
+                        FieldCount: entity.fields.length,
+                    };
+                })
+                .filter((e) => !options.nativeOnly || e.Source === "Native");
+
+            OutputFormatter.success({
+                Result: RESULTS.Success,
+                Code: "EntityList",
+                Data: entityList,
+            });
+        });
+
+    entities
+        .command("get")
+        .description("Get schema details of a Data Fabric entity")
+        .argument("<id>", "Entity ID")
+        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .examples(ENTITIES_GET_EXAMPLES)
+        .trackedAction(
+            processContext,
+            async (id: 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, entity] = await catchError(
+                    sdk.entities.getById(id),
+                );
+
+                if (getError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: `Error getting entity schema '${id}'`,
+                        Instructions: await extractErrorMessage(getError),
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                const e = entity as unknown as RawEntityGetResponse;
+
+                if (!e?.fields) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: `Entity '${id}' not found`,
+                        Instructions:
+                            "Verify the entity ID exists. Use 'df entities list' to see available entities.",
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                const fields = e.fields.map((field) => ({
+                    ID: field.id,
+                    Name: field.name,
+                    DisplayName: field.displayName,
+                    Type: field.fieldDataType?.name,
+                    Required: field.isRequired,
+                    PrimaryKey: field.isPrimaryKey,
+                    System: field.isSystemField,
+                }));
+
+                OutputFormatter.success({
+                    Result: RESULTS.Success,
+                    Code: "EntitySchema",
+                    Data: {
+                        Name: e.name,
+                        DisplayName: e.displayName || e.name,
+                        ID: e.id,
+                        Type: e.entityType,
+                        Description: e.description || "",
+                        Fields: fields,
+                    },
+                });
+            },
+        );
+
+    entities
+        .command("create")
+        .description("Create a new Data Fabric entity")
+        .argument(
+            "<name>",
+            "Entity name (must start with a letter; letters, numbers, and underscores only)",
+        )
+        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .option(
+            "-f, --file <path>",
+            "Path to JSON file with entity definition (fields array required; displayName, description, isRbacEnabled optional)",
+        )
+        .option("--body <json>", "Inline JSON entity definition")
+        .trackedAction(
+            processContext,
+            async (name: string, options: CreateOptions) => {
+                const [parseError, parsed] = await catchError(
+                    readJsonInput(
+                        options.file,
+                        options.body,
+                        "Provide entity definition via --file or --body.",
+                    ),
+                );
+
+                if (parseError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Error parsing entity definition",
+                        Instructions: parseError.message,
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                if (
+                    typeof parsed !== "object" ||
+                    parsed === null ||
+                    Array.isArray(parsed)
+                ) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Entity definition must be a JSON object",
+                        Instructions:
+                            "Provide a JSON object with a 'fields' array and optional displayName, description, isRbacEnabled.",
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                const definition = parsed as Record<string, unknown>;
+                if (!Array.isArray(definition.fields)) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message:
+                            "Entity definition must include a 'fields' array",
+                        Instructions:
+                            "Provide a JSON object with a 'fields' array containing field definitions.",
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                const hasInvalidField = (definition.fields as unknown[]).some(
+                    (f) =>
+                        typeof f !== "object" ||
+                        f === null ||
+                        typeof (f as Record<string, unknown>).fieldName !==
+                            "string",
+                );
+                if (hasInvalidField) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Each field must include a 'fieldName' string",
+                        Instructions:
+                            'Example: {"fieldName":"title","type":"STRING"}',
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                if (hasInvalidFieldType(definition.fields as unknown[])) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Invalid field type in fields",
+                        Instructions: `Valid types: ${VALID_FIELD_TYPES_LIST}`,
+                    });
+                    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 createOpts = {
+                    ...(definition.displayName !== undefined && {
+                        displayName: definition.displayName as string,
+                    }),
+                    ...(definition.description !== undefined && {
+                        description: definition.description as string,
+                    }),
+                    ...(definition.isRbacEnabled !== undefined && {
+                        isRbacEnabled: definition.isRbacEnabled as boolean,
+                    }),
+                };
+
+                const entityService: EntityServiceModel = sdk.entities;
+                const [createError, entityId] = await catchError(
+                    entityService.create(
+                        name,
+                        definition.fields as EntityCreateFieldOptions[],
+                        Object.keys(createOpts).length > 0
+                            ? createOpts
+                            : undefined,
+                    ),
+                );
+
+                if (createError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Error creating entity",
+                        Instructions: await extractErrorMessage(createError),
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                OutputFormatter.success({
+                    Result: RESULTS.Success,
+                    Code: "EntityCreated",
+                    Data: { ID: entityId },
+                });
+            },
+        );
+
+    entities
+        .command("update")
+        .description("Update schema or metadata of a Data Fabric entity")
+        .argument("<id>", "Entity ID")
+        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .option(
+            "-f, --file <path>",
+            "Path to JSON file with update options (addFields, updateFields, displayName, description, isRbacEnabled)",
+        )
+        .option("--body <json>", "Inline JSON update options")
+        .trackedAction(
+            processContext,
+            async (id: string, options: UpdateEntityOptions) => {
+                const [parseError, parsed] = await catchError(
+                    readJsonInput(
+                        options.file,
+                        options.body,
+                        "Provide update options via --file or --body.",
+                    ),
+                );
+
+                if (parseError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Error parsing update options",
+                        Instructions: parseError.message,
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                if (
+                    typeof parsed !== "object" ||
+                    parsed === null ||
+                    Array.isArray(parsed)
+                ) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Update options must be a JSON object",
+                        Instructions:
+                            "Provide a JSON object with addFields, updateFields, displayName, description, or isRbacEnabled.",
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                const input = parsed as Record<string, unknown>;
+                if (input.removeFields !== undefined) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "removeFields is not supported",
+                        Instructions:
+                            "Removing fields is not supported at this time. Use addFields or updateFields instead.",
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                if (Array.isArray(input.addFields)) {
+                    const hasInvalidField = (input.addFields as unknown[]).some(
+                        (f) =>
+                            typeof f !== "object" ||
+                            f === null ||
+                            typeof (f as Record<string, unknown>).fieldName !==
+                                "string",
+                    );
+                    if (hasInvalidField) {
+                        OutputFormatter.error({
+                            Result: RESULTS.Failure,
+                            Message:
+                                "Each field in addFields must include a 'fieldName' string",
+                            Instructions:
+                                'Example: {"fieldName":"title","type":"STRING"}',
+                        });
+                        processContext.exit(1);
+                        return;
+                    }
+
+                    if (hasInvalidFieldType(input.addFields as unknown[])) {
+                        OutputFormatter.error({
+                            Result: RESULTS.Failure,
+                            Message: "Invalid field type in addFields",
+                            Instructions: `Valid types: ${VALID_FIELD_TYPES_LIST}`,
+                        });
+                        processContext.exit(1);
+                        return;
+                    }
+                }
+
+                if (Array.isArray(input.updateFields)) {
+                    const hasInvalidField = (
+                        input.updateFields as unknown[]
+                    ).some(
+                        (f) =>
+                            typeof f !== "object" ||
+                            f === null ||
+                            typeof (f as Record<string, unknown>).id !==
+                                "string",
+                    );
+                    if (hasInvalidField) {
+                        OutputFormatter.error({
+                            Result: RESULTS.Failure,
+                            Message:
+                                "Each field in updateFields must include an 'id' string",
+                            Instructions:
+                                'Use \'df entities get <entityId>\' to find field IDs. Example: {"id":"<fieldId>","displayName":"Total Amount","isRequired":true}',
+                        });
+                        processContext.exit(1);
+                        return;
+                    }
+                }
+
+                const [clientError, sdk] = await catchError(
+                    createDataFabricClient(options.tenant),
+                );
+
+                if (clientError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Error connecting to Data Fabric",
+                        Instructions: await extractErrorMessage(clientError),
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                const entityService: EntityServiceModel = sdk.entities;
+                const [updateError] = await catchError(
+                    entityService.updateById(
+                        id,
+                        input as EntityUpdateByIdOptions,
+                    ),
+                );
+
+                if (updateError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Error updating entity",
+                        Instructions: await extractErrorMessage(updateError),
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                OutputFormatter.success({
+                    Result: RESULTS.Success,
+                    Code: "EntityUpdated",
+                    Data: { ID: id },
+                });
+            },
+        );
+};