@fluentcommerce/fluent-mcp-extn 0.1.0

package/dist/settings-tools.js

@@ -0,0 +1,348 @@
+/**
+ * Settings management tools: setting.upsert, setting.bulkUpsert
+ *
+ * Closes the configuration loop — agents can create and update
+ * settings that workflows depend on (webhook URLs, feature flags, thresholds).
+ */
+import { z } from "zod";
+import { ToolError } from "./errors.js";
+// ---------------------------------------------------------------------------
+// Input schemas
+// ---------------------------------------------------------------------------
+const SettingInputSchema = z.object({
+    name: z.string().min(1).describe("Setting key/name"),
+    value: z.string().describe("Setting value (for small values). Mutually exclusive with lobValue."),
+    lobValue: z
+        .string()
+        .optional()
+        .describe("Large object value (for JSON payloads > 4KB). Mutually exclusive with value."),
+    context: z
+        .string()
+        .min(1)
+        .describe('Setting scope context: "RETAILER", "ACCOUNT", "LOCATION", "NETWORK", "AGENT", "CUSTOMER"'),
+    contextId: z
+        .number()
+        .int()
+        .optional()
+        .describe("Context ID (e.g., retailer ID). Falls back to FLUENT_RETAILER_ID for RETAILER context."),
+});
+export const SettingUpsertInputSchema = SettingInputSchema;
+export const SettingBulkUpsertInputSchema = z.object({
+    settings: z
+        .array(SettingInputSchema)
+        .min(1)
+        .max(50)
+        .describe("Array of settings to create or update (max 50)"),
+});
+// ---------------------------------------------------------------------------
+// Tool definitions (JSON Schema for MCP)
+// ---------------------------------------------------------------------------
+export const SETTING_TOOL_DEFINITIONS = [
+    {
+        name: "setting.upsert",
+        description: [
+            "Create or update a Fluent Commerce setting.",
+            "",
+            "Upsert semantics: creates if missing, updates if exists.",
+            "Queries existing settings by name + context + contextId first.",
+            "",
+            "KEY GOTCHAS:",
+            '- context is a plain String ("RETAILER"), NOT an object',
+            "- contextId is a separate Int field",
+            "- For large JSON values (>4KB), use lobValue instead of value",
+            "- Returns created: true/false for audit trail",
+            "",
+            "CONTEXTS: RETAILER, ACCOUNT, LOCATION, NETWORK, AGENT, CUSTOMER",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Setting key/name",
+                },
+                value: {
+                    type: "string",
+                    description: "Setting value (for small values)",
+                },
+                lobValue: {
+                    type: "string",
+                    description: "Large object value (for JSON payloads > 4KB)",
+                },
+                context: {
+                    type: "string",
+                    description: 'Setting scope: RETAILER, ACCOUNT, LOCATION, NETWORK, AGENT, CUSTOMER',
+                },
+                contextId: {
+                    type: "integer",
+                    description: "Context ID (e.g., retailer ID). Defaults to FLUENT_RETAILER_ID for RETAILER context.",
+                },
+            },
+            required: ["name", "value", "context"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "setting.bulkUpsert",
+        description: [
+            "Batch create or update multiple settings in one call.",
+            "",
+            "Processes up to 50 settings sequentially with individual error handling.",
+            "Returns per-setting results with created/updated/failed counts.",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                settings: {
+                    type: "array",
+                    minItems: 1,
+                    maxItems: 50,
+                    items: {
+                        type: "object",
+                        properties: {
+                            name: { type: "string" },
+                            value: { type: "string" },
+                            lobValue: { type: "string" },
+                            context: { type: "string" },
+                            contextId: { type: "integer" },
+                        },
+                        required: ["name", "value", "context"],
+                    },
+                    description: "Array of settings to upsert",
+                },
+            },
+            required: ["settings"],
+            additionalProperties: false,
+        },
+    },
+];
+function requireSettingClient(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;
+}
+function resolveContextId(context, contextId, config) {
+    if (contextId !== undefined)
+        return contextId;
+    if (context === "RETAILER" && config.retailerId) {
+        return Number(config.retailerId);
+    }
+    throw new ToolError("VALIDATION_ERROR", `contextId is required for context "${context}". Set FLUENT_RETAILER_ID or pass contextId explicitly.`);
+}
+/**
+ * Query for an existing setting by name, context, and contextId.
+ */
+async function findExistingSetting(client, name, context, contextId) {
+    const query = `query FindSetting($name: [String!], $context: [String!], $contextId: [Int!]) {
+  settings(name: $name, context: $context, contextId: $contextId, first: 1) {
+    edges {
+      node {
+        id
+        name
+        value
+        lobValue
+        context
+        contextId
+      }
+    }
+  }
+}`;
+    const response = await client.graphql({
+        query,
+        variables: {
+            name: [name],
+            context: [context],
+            contextId: [contextId],
+        },
+    });
+    const data = response?.data;
+    const connection = data?.settings;
+    const edges = connection?.edges;
+    const node = edges?.[0]?.node;
+    if (!node)
+        return null;
+    return {
+        id: node.id,
+        value: node.value ?? null,
+        lobValue: node.lobValue ?? null,
+    };
+}
+/**
+ * Create a new setting.
+ */
+async function createSetting(client, input) {
+    const mutationInput = {
+        name: input.name,
+        context: input.context,
+        contextId: input.contextId,
+    };
+    if (input.lobValue) {
+        mutationInput.lobValue = input.lobValue;
+        mutationInput.valueType = "LOB";
+    }
+    else {
+        mutationInput.value = input.value;
+        mutationInput.valueType = "STRING";
+    }
+    const mutation = `mutation CreateSetting($input: CreateSettingInput!) {
+  createSetting(input: $input) {
+    id
+    name
+    value
+    lobValue
+    context
+    contextId
+  }
+}`;
+    const response = await client.graphql({
+        query: mutation,
+        variables: { input: mutationInput },
+    }, { retry: false });
+    const data = response?.data;
+    const setting = data?.createSetting;
+    if (!setting) {
+        const errors = response?.errors;
+        throw new ToolError("SDK_ERROR", "createSetting mutation returned no data", {
+            details: { graphqlErrors: errors },
+        });
+    }
+    return setting;
+}
+/**
+ * Update an existing setting.
+ */
+async function updateSetting(client, input) {
+    const mutationInput = {
+        id: input.id,
+        context: input.context,
+        contextId: input.contextId,
+    };
+    if (input.lobValue) {
+        mutationInput.lobValue = input.lobValue;
+        mutationInput.valueType = "LOB";
+    }
+    else {
+        mutationInput.value = input.value;
+        mutationInput.valueType = "STRING";
+    }
+    const mutation = `mutation UpdateSetting($input: UpdateSettingInput!) {
+  updateSetting(input: $input) {
+    id
+    name
+    value
+    lobValue
+    context
+    contextId
+  }
+}`;
+    const response = await client.graphql({
+        query: mutation,
+        variables: { input: mutationInput },
+    }, { retry: false });
+    const data = response?.data;
+    const setting = data?.updateSetting;
+    if (!setting) {
+        const errors = response?.errors;
+        throw new ToolError("SDK_ERROR", "updateSetting mutation returned no data", {
+            details: { graphqlErrors: errors },
+        });
+    }
+    return setting;
+}
+/**
+ * Handle setting.upsert tool call.
+ */
+export async function handleSettingUpsert(args, ctx) {
+    const parsed = SettingUpsertInputSchema.parse(args);
+    const client = requireSettingClient(ctx);
+    const contextId = resolveContextId(parsed.context, parsed.contextId, ctx.config);
+    // Check if setting already exists
+    const existing = await findExistingSetting(client, parsed.name, parsed.context, contextId);
+    if (existing) {
+        // Update
+        const setting = await updateSetting(client, {
+            id: existing.id,
+            value: parsed.value,
+            lobValue: parsed.lobValue,
+            context: parsed.context,
+            contextId,
+        });
+        return {
+            ok: true,
+            created: false,
+            updated: true,
+            setting,
+            previousValue: existing.value ?? existing.lobValue,
+        };
+    }
+    // Create
+    const setting = await createSetting(client, {
+        name: parsed.name,
+        value: parsed.value,
+        lobValue: parsed.lobValue,
+        context: parsed.context,
+        contextId,
+    });
+    return {
+        ok: true,
+        created: true,
+        updated: false,
+        setting,
+    };
+}
+/**
+ * Handle setting.bulkUpsert tool call.
+ */
+export async function handleSettingBulkUpsert(args, ctx) {
+    const parsed = SettingBulkUpsertInputSchema.parse(args);
+    const client = requireSettingClient(ctx);
+    let created = 0;
+    let updated = 0;
+    let failed = 0;
+    const results = [];
+    for (const setting of parsed.settings) {
+        try {
+            const contextId = resolveContextId(setting.context, setting.contextId, ctx.config);
+            const existing = await findExistingSetting(client, setting.name, setting.context, contextId);
+            if (existing) {
+                await updateSetting(client, {
+                    id: existing.id,
+                    value: setting.value,
+                    lobValue: setting.lobValue,
+                    context: setting.context,
+                    contextId,
+                });
+                updated++;
+                results.push({ name: setting.name, status: "updated" });
+            }
+            else {
+                await createSetting(client, {
+                    name: setting.name,
+                    value: setting.value,
+                    lobValue: setting.lobValue,
+                    context: setting.context,
+                    contextId,
+                });
+                created++;
+                results.push({ name: setting.name, status: "created" });
+            }
+        }
+        catch (error) {
+            failed++;
+            results.push({
+                name: setting.name,
+                status: "failed",
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return {
+        ok: true,
+        created,
+        updated,
+        failed,
+        total: parsed.settings.length,
+        results,
+    };
+}