@fluentcommerce/fluent-mcp-extn 0.1.0

package/dist/entity-tools.js

@@ -0,0 +1,414 @@
+/**
+ * Entity lifecycle tools: entity.create, entity.update, entity.get
+ *
+ * Type-safe entity CRUD with built-in validation, gotcha knowledge,
+ * and audit trail for agentic workflows.
+ */
+import { z } from "zod";
+import { ToolError } from "./errors.js";
+import { getEntityMeta, buildCreateMutation, buildUpdateMutation, buildGetByIdQuery, buildSearchByRefQuery, validateCreateInput, SUPPORTED_ENTITY_TYPES, } from "./entity-registry.js";
+// ---------------------------------------------------------------------------
+// Input schemas
+// ---------------------------------------------------------------------------
+export const EntityCreateInputSchema = z.object({
+    entityType: z.string().min(1).describe(`Entity type. Supported: ${SUPPORTED_ENTITY_TYPES.join(", ")}`),
+    data: z
+        .record(z.string(), z.unknown())
+        .describe("Entity creation input fields (matches GraphQL create input type)"),
+    returnFields: z
+        .array(z.string())
+        .optional()
+        .describe("Fields to return after creation. Defaults to entity type defaults."),
+    dryRun: z
+        .boolean()
+        .default(false)
+        .describe("If true, build mutation without executing. Returns the GraphQL query."),
+});
+export const EntityUpdateInputSchema = z.object({
+    entityType: z.string().min(1),
+    id: z.string().min(1).describe("Entity ID (required for updates)"),
+    fields: z
+        .record(z.string(), z.unknown())
+        .describe("Fields to update (matches GraphQL update input type)"),
+    returnFields: z
+        .array(z.string())
+        .optional()
+        .describe("Fields to return after update."),
+    validateTransition: z
+        .boolean()
+        .default(false)
+        .describe("If true and status is being changed, validates the transition is allowed before executing."),
+});
+export const EntityGetInputSchema = z.object({
+    entityType: z.string().min(1),
+    id: z.string().optional().describe("Entity ID (preferred lookup method)"),
+    ref: z.string().optional().describe("Entity ref (fallback when ID unavailable)"),
+    fields: z
+        .array(z.string())
+        .optional()
+        .describe("Fields to return. Defaults to entity type defaults."),
+    includeEdges: z
+        .array(z.string())
+        .optional()
+        .describe("Related entity edges to include (e.g., fulfilments, items)"),
+});
+// ---------------------------------------------------------------------------
+// Tool definitions (JSON Schema for MCP)
+// ---------------------------------------------------------------------------
+export const ENTITY_TOOL_DEFINITIONS = [
+    {
+        name: "entity.create",
+        description: [
+            "Type-safe entity creation with built-in validation and gotcha knowledge.",
+            "",
+            `Supported entity types: ${SUPPORTED_ENTITY_TYPES.join(", ")}`,
+            "",
+            "KEY FEATURES:",
+            "- Validates required fields BEFORE sending (e.g., Location needs openingSchedule)",
+            "- Encodes compound key rules (ProductKey needs ref + catalogue.ref)",
+            "- Auto-resolves retailerId from config",
+            "- dryRun mode returns the mutation without executing",
+            "- Returns the executed mutation string for audit trail",
+            "",
+            "GOTCHAS encoded:",
+            "- No create inputs have status field (auto-set to CREATED)",
+            "- Customer has NO ref field, username is identifier",
+            "- Network uses name not ref in create, retailers is plural array",
+            "- Location requires openingSchedule (even for 24/7, use allHours: true)",
+            "- Product gtin has 20-char max",
+            "- Settings context is plain String, contextId is separate Int",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                entityType: {
+                    type: "string",
+                    description: `Entity type. Supported: ${SUPPORTED_ENTITY_TYPES.join(", ")}`,
+                },
+                data: {
+                    type: "object",
+                    additionalProperties: true,
+                    description: "Entity creation input fields. The structure depends on the entity type.",
+                },
+                returnFields: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Fields to return after creation.",
+                },
+                dryRun: {
+                    type: "boolean",
+                    description: "If true, build and validate mutation without executing.",
+                },
+            },
+            required: ["entityType", "data"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "entity.update",
+        description: [
+            "Status-aware entity updates with optional transition validation.",
+            "",
+            "KEY FEATURES:",
+            "- Auto-detects mutation name from entity type",
+            "- Optional validateTransition: checks workflow.transitions before status change",
+            "- Returns previous status for audit trail",
+            "- Supports all entity types in the registry",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                entityType: {
+                    type: "string",
+                    description: "Entity type (ORDER, FULFILMENT, LOCATION, etc.)",
+                },
+                id: {
+                    type: "string",
+                    description: "Entity ID (required for updates)",
+                },
+                fields: {
+                    type: "object",
+                    additionalProperties: true,
+                    description: "Fields to update",
+                },
+                returnFields: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Fields to return after update.",
+                },
+                validateTransition: {
+                    type: "boolean",
+                    description: "If true and status is being changed, validates the transition is allowed.",
+                },
+            },
+            required: ["entityType", "id", "fields"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "entity.get",
+        description: [
+            "Unified entity lookup by ID or ref with optional edge inclusion.",
+            "",
+            "Supports all entity types. Resolves by id (preferred) or ref.",
+            "includeEdges fetches related entities (e.g., order.fulfilments).",
+            "Default field set per entity type (id, ref, status, type, createdOn, etc.).",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                entityType: {
+                    type: "string",
+                    description: "Entity type (ORDER, FULFILMENT, LOCATION, etc.)",
+                },
+                id: {
+                    type: "string",
+                    description: "Entity ID (preferred lookup method)",
+                },
+                ref: {
+                    type: "string",
+                    description: "Entity ref (fallback when ID unavailable; not available for CUSTOMER)",
+                },
+                fields: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Fields to return.",
+                },
+                includeEdges: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Related entity edges to include (e.g., fulfilments, items, attributes)",
+                },
+            },
+            required: ["entityType"],
+            additionalProperties: false,
+        },
+    },
+];
+function requireEntityClient(ctx) {
+    if (!ctx.client) {
+        throw new ToolError("CONFIG_ERROR", "SDK client is not available. Run config.validate and fix auth/base URL.");
+    }
+    return ctx.client;
+}
+/**
+ * Handle entity.create tool call.
+ */
+export async function handleEntityCreate(args, ctx) {
+    const parsed = EntityCreateInputSchema.parse(args);
+    const meta = getEntityMeta(parsed.entityType);
+    if (!meta) {
+        throw new ToolError("VALIDATION_ERROR", `Unsupported entity type: "${parsed.entityType}". Supported: ${SUPPORTED_ENTITY_TYPES.join(", ")}`);
+    }
+    // Auto-inject retailerId for retailer-scoped entities before validation
+    const data = parsed.data;
+    if (meta.retailerScoped &&
+        !data.retailer &&
+        ctx.config.retailerId) {
+        data.retailer = { id: Number(ctx.config.retailerId) };
+    }
+    // Validate required fields (after auto-injection)
+    const stillMissing = validateCreateInput(parsed.entityType, data);
+    const built = buildCreateMutation(parsed.entityType, parsed.returnFields);
+    if (!built) {
+        throw new ToolError("VALIDATION_ERROR", `Cannot build create mutation for entity type: "${parsed.entityType}"`);
+    }
+    if (stillMissing.length > 0) {
+        throw new ToolError("VALIDATION_ERROR", `Missing required fields for ${parsed.entityType}: ${stillMissing.join(", ")}`, {
+            details: {
+                missingFields: stillMissing,
+                requiredFields: meta.requiredCreateFields,
+                gotchas: meta.gotchas,
+            },
+        });
+    }
+    if (parsed.dryRun) {
+        return {
+            ok: true,
+            dryRun: true,
+            entityType: parsed.entityType,
+            mutation: built.mutation,
+            inputType: built.inputType,
+            variables: { input: data },
+            requiredFields: meta.requiredCreateFields,
+            gotchas: meta.gotchas,
+            note: "No API call made. Set dryRun=false to execute.",
+        };
+    }
+    const client = requireEntityClient(ctx);
+    const payload = {
+        query: built.mutation,
+        variables: { input: data },
+    };
+    // Use executeOnce semantics (no retry for mutations)
+    const response = await client.graphql(payload, { retry: false });
+    // Extract the created entity from the response
+    const gqlData = response?.data;
+    const entity = gqlData?.[meta.createMutation];
+    if (!entity) {
+        const errors = response?.errors;
+        throw new ToolError("SDK_ERROR", "Create mutation returned no data", {
+            details: { graphqlErrors: errors },
+        });
+    }
+    return {
+        ok: true,
+        entityType: parsed.entityType,
+        entity,
+        mutation: built.mutation,
+    };
+}
+/**
+ * Handle entity.update tool call.
+ */
+export async function handleEntityUpdate(args, ctx) {
+    const parsed = EntityUpdateInputSchema.parse(args);
+    const meta = getEntityMeta(parsed.entityType);
+    if (!meta) {
+        throw new ToolError("VALIDATION_ERROR", `Unsupported entity type: "${parsed.entityType}". Supported: ${SUPPORTED_ENTITY_TYPES.join(", ")}`);
+    }
+    const client = requireEntityClient(ctx);
+    const fields = parsed.fields;
+    // If validateTransition is requested and status is changing, check transitions first
+    let transitionWarning;
+    if (parsed.validateTransition && fields.status) {
+        try {
+            // Get current entity state to know current status
+            const currentQuery = `query($id: ID!) { ${meta.queryById}(id: $id) { id status type } }`;
+            const currentResponse = await client.graphql({
+                query: currentQuery,
+                variables: { id: parsed.id },
+            });
+            const currentData = currentResponse?.data?.[meta.queryById];
+            if (currentData) {
+                const trigger = {
+                    type: parsed.entityType,
+                    status: currentData.status,
+                    retailerId: ctx.config.retailerId ?? undefined,
+                };
+                if (currentData.type) {
+                    trigger.flexType = `${parsed.entityType}::${currentData.type}`;
+                }
+                const transitions = await client.getTransitions({
+                    triggers: [trigger],
+                });
+                const transArr = Array.isArray(transitions)
+                    ? transitions
+                    : [transitions];
+                const availableEvents = transArr.flatMap((t) => {
+                    const rec = t;
+                    const actions = rec?.userActions ?? rec?.transitions ?? [];
+                    return Array.isArray(actions) ? actions : [];
+                });
+                if (availableEvents.length === 0) {
+                    transitionWarning = `No workflow transitions available from status "${currentData.status}" for ${parsed.entityType}. The status update may succeed as a direct mutation but will not trigger workflow orchestration.`;
+                }
+            }
+            else {
+                transitionWarning = `Could not fetch current entity state for transition validation (entity ID: ${parsed.id}).`;
+            }
+        }
+        catch {
+            // Transition API failure is non-blocking — proceed with update
+            transitionWarning = "Transition validation skipped — transitions API unavailable.";
+        }
+    }
+    const built = buildUpdateMutation(parsed.entityType, parsed.returnFields);
+    if (!built) {
+        throw new ToolError("VALIDATION_ERROR", `Cannot build update mutation for entity type: "${parsed.entityType}"`);
+    }
+    const input = { id: parsed.id, ...fields };
+    const payload = {
+        query: built.mutation,
+        variables: { input },
+    };
+    const response = await client.graphql(payload, { retry: false });
+    const gqlData = response?.data;
+    const entity = gqlData?.[meta.updateMutation];
+    if (!entity) {
+        const errors = response?.errors;
+        throw new ToolError("SDK_ERROR", "Update mutation returned no data", {
+            details: { graphqlErrors: errors },
+        });
+    }
+    return {
+        ok: true,
+        entityType: parsed.entityType,
+        entity,
+        mutation: built.mutation,
+        ...(transitionWarning ? { transitionWarning } : {}),
+    };
+}
+/**
+ * Handle entity.get tool call.
+ */
+export async function handleEntityGet(args, ctx) {
+    const parsed = EntityGetInputSchema.parse(args);
+    const meta = getEntityMeta(parsed.entityType);
+    if (!meta) {
+        throw new ToolError("VALIDATION_ERROR", `Unsupported entity type: "${parsed.entityType}". Supported: ${SUPPORTED_ENTITY_TYPES.join(", ")}`);
+    }
+    if (!parsed.id && !parsed.ref) {
+        throw new ToolError("VALIDATION_ERROR", "Either id or ref must be provided for entity lookup.");
+    }
+    const client = requireEntityClient(ctx);
+    // Prefer ID lookup
+    if (parsed.id) {
+        const built = buildGetByIdQuery(parsed.entityType, parsed.includeEdges);
+        if (!built) {
+            throw new ToolError("VALIDATION_ERROR", `Cannot build ID query for entity type: "${parsed.entityType}"`);
+        }
+        const response = await client.graphql({
+            query: built.query,
+            variables: { id: parsed.id },
+        });
+        const gqlData = response?.data;
+        const entity = gqlData?.[built.queryRoot];
+        if (!entity) {
+            return {
+                ok: true,
+                found: false,
+                entityType: parsed.entityType,
+                lookupBy: "id",
+                lookupValue: parsed.id,
+            };
+        }
+        return {
+            ok: true,
+            found: true,
+            entityType: parsed.entityType,
+            entity,
+        };
+    }
+    // Ref-based lookup
+    if (!meta.hasRef) {
+        throw new ToolError("VALIDATION_ERROR", `Entity type ${parsed.entityType} does not support ref-based lookup. Use id instead.`);
+    }
+    const built = buildSearchByRefQuery(parsed.entityType, parsed.includeEdges);
+    if (!built) {
+        throw new ToolError("VALIDATION_ERROR", `Cannot build ref query for entity type: "${parsed.entityType}"`);
+    }
+    const response = await client.graphql({
+        query: built.query,
+        variables: { ref: [parsed.ref] },
+    });
+    const gqlData = response?.data;
+    const connection = gqlData?.[built.queryRoot];
+    const edges = connection?.edges;
+    const entity = edges?.[0]?.node;
+    if (!entity) {
+        return {
+            ok: true,
+            found: false,
+            entityType: parsed.entityType,
+            lookupBy: "ref",
+            lookupValue: parsed.ref,
+        };
+    }
+    return {
+        ok: true,
+        found: true,
+        entityType: parsed.entityType,
+        entity,
+    };
+}