@fluentcommerce/fluent-mcp-extn 0.1.0

package/dist/config.js

@@ -0,0 +1,195 @@
+/**
+ * Runtime configuration loading and validation.
+ *
+ * FLUENT_PROFILE integration now delegates to the SDK's profile loader
+ * (`loadFluentProfile`) so this package does not need to duplicate profile
+ * parsing semantics.
+ */
+import { loadFluentProfile, } from "@fluentcommerce/fc-connect-sdk";
+const PLACEHOLDER_VALUES = new Set([
+    "https://your_account.sandbox.api.fluentretail.com",
+    "your_retailer",
+    "your_retailer_id",
+    "your_client_id",
+    "your_client_secret",
+    "your_username",
+    "your_password",
+    "your_bearer_token",
+    "your_profile",
+    "your-client-id",
+    "your-client-secret",
+    "your-username",
+    "your-password",
+].map((value) => value.toLowerCase()));
+function pick(name) {
+    const raw = process.env[name];
+    if (!raw)
+        return null;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return null;
+    if (PLACEHOLDER_VALUES.has(trimmed.toLowerCase()))
+        return null;
+    return trimmed;
+}
+function pickNumber(name, fallback, min) {
+    const value = pick(name);
+    if (!value)
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed < min)
+        return fallback;
+    return parsed;
+}
+function pickWithFallback(envName, fallbackValue) {
+    return pick(envName) ?? fallbackValue;
+}
+function toNullableString(value) {
+    if (typeof value === "string" && value.trim().length > 0)
+        return value.trim();
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    return null;
+}
+function asRecord(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    return value;
+}
+/**
+ * Returns true when required OAuth credential pair exists.
+ */
+export function hasOAuthConfig(config) {
+    return Boolean(config.clientId && config.clientSecret);
+}
+/**
+ * Determines which auth path will be selected at runtime.
+ */
+export function detectAuthStrategy(config) {
+    if (config.useProfileClientFactory)
+        return "profile";
+    if (hasOAuthConfig(config))
+        return "oauth";
+    if (config.tokenCommand)
+        return "tokenCommand";
+    if (config.envAccessToken)
+        return "staticToken";
+    return "none";
+}
+/**
+ * Reads env vars, optionally loads a Fluent CLI profile via SDK, and merges
+ * values. Explicit env vars always override profile-derived values.
+ */
+export async function loadConfig() {
+    const profileName = pick("FLUENT_PROFILE");
+    const profileRetailer = pick("FLUENT_PROFILE_RETAILER");
+    const explicitBaseUrl = Boolean(pick("FLUENT_BASE_URL"));
+    const explicitOAuthEnv = Boolean(pick("FLUENT_CLIENT_ID") ||
+        pick("FLUENT_CLIENT_SECRET") ||
+        pick("FLUENT_USERNAME") ||
+        pick("FLUENT_PASSWORD"));
+    let profileConfig = null;
+    let profileLoadError = null;
+    if (profileName) {
+        try {
+            profileConfig = loadFluentProfile(profileName, {
+                retailer: profileRetailer ?? undefined,
+            });
+        }
+        catch (error) {
+            profileLoadError = error instanceof Error ? error.message : String(error);
+        }
+    }
+    const profileRecord = asRecord(profileConfig);
+    const profileBaseUrl = toNullableString(profileRecord?.baseUrl);
+    const profileRetailerId = toNullableString(profileRecord?.retailerId);
+    const profileClientId = toNullableString(profileRecord?.clientId);
+    const profileClientSecret = toNullableString(profileRecord?.clientSecret);
+    const profileUsername = toNullableString(profileRecord?.username);
+    const profilePassword = toNullableString(profileRecord?.password);
+    return {
+        profileName,
+        profileRetailer,
+        profileLoaded: Boolean(profileConfig),
+        profileLoadError,
+        useProfileClientFactory: Boolean(profileName && profileConfig && !explicitBaseUrl && !explicitOAuthEnv),
+        baseUrl: pickWithFallback("FLUENT_BASE_URL", profileBaseUrl),
+        retailerId: pickWithFallback("FLUENT_RETAILER_ID", profileRetailerId),
+        accountId: pick("FLUENT_ACCOUNT_ID"),
+        // SDK OAuth — env vars override profile values.
+        clientId: pickWithFallback("FLUENT_CLIENT_ID", profileClientId),
+        clientSecret: pickWithFallback("FLUENT_CLIENT_SECRET", profileClientSecret),
+        username: pickWithFallback("FLUENT_USERNAME", profileUsername),
+        password: pickWithFallback("FLUENT_PASSWORD", profilePassword),
+        // Credential fallback (env-only).
+        tokenCommand: pick("TOKEN_COMMAND"),
+        envAccessToken: pick("FLUENT_ACCESS_TOKEN"),
+        // Resilience (FLUENT_RETRY_ATTEMPTS=0 disables retries)
+        tokenCommandTimeoutMs: pickNumber("TOKEN_COMMAND_TIMEOUT_MS", 10000, 1000),
+        requestTimeoutMs: pickNumber("FLUENT_REQUEST_TIMEOUT_MS", 30000, 1000),
+        retryAttempts: pickNumber("FLUENT_RETRY_ATTEMPTS", 3, 0),
+        retryInitialDelayMs: pickNumber("FLUENT_RETRY_INITIAL_DELAY_MS", 300, 50),
+        retryMaxDelayMs: pickNumber("FLUENT_RETRY_MAX_DELAY_MS", 5000, 100),
+        retryFactor: pickNumber("FLUENT_RETRY_FACTOR", 2, 1),
+    };
+}
+/**
+ * Validates readiness for API-backed tools and returns actionable messages.
+ */
+export function validateConfig(config) {
+    const errors = [];
+    const warnings = [];
+    const authStrategy = detectAuthStrategy(config);
+    if (!config.baseUrl) {
+        errors.push("FLUENT_BASE_URL is required for GraphQL, batch, and event APIs.");
+    }
+    if (config.profileName && config.profileLoadError) {
+        errors.push(`FLUENT_PROFILE="${config.profileName}" could not be loaded: ${config.profileLoadError}`);
+    }
+    if (authStrategy === "none") {
+        errors.push("Authentication is not configured. Set FLUENT_PROFILE, OAuth env vars, TOKEN_COMMAND, or FLUENT_ACCESS_TOKEN.");
+    }
+    if (authStrategy === "profile" && !config.retailerId) {
+        warnings.push("Profile auth is active without retailer scope. Set FLUENT_PROFILE_RETAILER or FLUENT_RETAILER_ID for event and batch APIs.");
+    }
+    if (hasOAuthConfig(config) && !config.username && !config.password) {
+        warnings.push("OAuth credentials are configured without username/password. This is fine for client-credentials flow.");
+    }
+    if (config.tokenCommand && config.envAccessToken) {
+        warnings.push("Both TOKEN_COMMAND and FLUENT_ACCESS_TOKEN are set; TOKEN_COMMAND takes precedence.");
+    }
+    return {
+        isReadyForApiCalls: errors.length === 0,
+        authStrategy,
+        errors,
+        warnings,
+    };
+}
+/**
+ * Returns a redacted summary suitable for logs and MCP responses.
+ */
+export function toSafeConfigSummary(config) {
+    return {
+        profileName: config.profileName,
+        profileRetailer: config.profileRetailer,
+        profileLoaded: config.profileLoaded,
+        hasProfileLoadError: Boolean(config.profileLoadError),
+        useProfileClientFactory: config.useProfileClientFactory,
+        baseUrl: config.baseUrl,
+        retailerId: config.retailerId,
+        accountId: config.accountId,
+        authStrategy: detectAuthStrategy(config),
+        hasClientId: Boolean(config.clientId),
+        hasClientSecret: Boolean(config.clientSecret),
+        hasUsername: Boolean(config.username),
+        hasPassword: Boolean(config.password),
+        hasTokenCommand: Boolean(config.tokenCommand),
+        hasEnvAccessToken: Boolean(config.envAccessToken),
+        tokenCommandTimeoutMs: config.tokenCommandTimeoutMs,
+        requestTimeoutMs: config.requestTimeoutMs,
+        retryAttempts: config.retryAttempts,
+        retryInitialDelayMs: config.retryInitialDelayMs,
+        retryMaxDelayMs: config.retryMaxDelayMs,
+        retryFactor: config.retryFactor,
+    };
+}

package/dist/entity-registry.js

@@ -0,0 +1,418 @@
+/**
+ * Entity metadata registry for type-safe entity operations.
+ *
+ * Encodes Fluent Commerce entity-specific knowledge:
+ * - Required fields per create mutation
+ * - Compound key structures
+ * - Known gotchas (e.g., Location needs openingSchedule)
+ * - GraphQL mutation/query names
+ * - Default field selections for queries
+ */
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+const ENTITY_REGISTRY = {
+    ORDER: {
+        createMutation: "createOrder",
+        createInputType: "CreateOrderInput",
+        updateMutation: "updateOrder",
+        updateInputType: "UpdateOrderInput",
+        queryRoot: "orders",
+        queryById: "orderById",
+        requiredCreateFields: ["ref", "type", "retailer", "customer", "items"],
+        defaultFields: [
+            "id",
+            "ref",
+            "status",
+            "type",
+            "createdOn",
+            "updatedOn",
+        ],
+        edges: [
+            "fulfilmentChoice",
+            "fulfilments",
+            "items",
+            "customer",
+            "attributes",
+        ],
+        gotchas: [
+            'retailer must be { id: N } not { ref: "..." }',
+            "customer must be { id: N } (CustomerId only accepts id, NOT username)",
+            "items is required: [{ ref, productRef, quantity, ... }]",
+            "status is auto-set to CREATED; do not pass status in create",
+            "type is the order type (e.g., HD, CC)",
+        ],
+        hasRef: true,
+        retailerScoped: true,
+    },
+    FULFILMENT: {
+        createMutation: "createFulfilment",
+        createInputType: "CreateFulfilmentInput",
+        updateMutation: "updateFulfilment",
+        updateInputType: "UpdateFulfilmentInput",
+        queryRoot: "fulfilments",
+        queryById: "fulfilmentById",
+        requiredCreateFields: ["ref", "type", "order"],
+        defaultFields: [
+            "id",
+            "ref",
+            "status",
+            "type",
+            "createdOn",
+            "updatedOn",
+        ],
+        edges: ["order", "items", "articles", "fromLocation", "attributes"],
+        gotchas: [
+            'order must be { id: N } or { ref: "..." } (OrderId!)',
+            "no retailer field — inherited from the order",
+            "status auto-set to CREATED",
+        ],
+        hasRef: true,
+        retailerScoped: true,
+    },
+    LOCATION: {
+        createMutation: "createLocation",
+        createInputType: "CreateLocationInput",
+        updateMutation: "updateLocation",
+        updateInputType: "UpdateLocationInput",
+        queryRoot: "locations",
+        queryById: "locationById",
+        requiredCreateFields: ["ref", "type", "name", "openingSchedule"],
+        defaultFields: [
+            "id",
+            "ref",
+            "status",
+            "type",
+            "name",
+            "createdOn",
+            "updatedOn",
+        ],
+        edges: ["networks", "storageAreas", "attributes"],
+        gotchas: [
+            "openingSchedule is ALWAYS required (even for 24/7 warehouses, use allHours: true)",
+            'retailer must be { id: N }',
+            "status auto-set to CREATED",
+        ],
+        hasRef: true,
+        retailerScoped: true,
+    },
+    NETWORK: {
+        createMutation: "createNetwork",
+        createInputType: "CreateNetworkInput",
+        updateMutation: "updateNetwork",
+        updateInputType: "UpdateNetworkInput",
+        queryRoot: "networks",
+        queryById: "networkById",
+        requiredCreateFields: ["name", "type", "retailers"],
+        defaultFields: ["id", "ref", "status", "type", "name", "createdOn"],
+        edges: ["locations", "retailers"],
+        gotchas: [
+            "Uses 'name' not 'ref' in create; name becomes the ref",
+            "retailers is a plural ARRAY, not a single retailer",
+        ],
+        hasRef: true,
+        retailerScoped: false,
+    },
+    CUSTOMER: {
+        createMutation: "createCustomer",
+        createInputType: "CreateCustomerInput",
+        updateMutation: "updateCustomer",
+        updateInputType: "UpdateCustomerInput",
+        queryRoot: "customers",
+        queryById: "customerById",
+        requiredCreateFields: [
+            "username",
+            "firstName",
+            "lastName",
+            "retailer",
+            "promotionOptIn",
+        ],
+        defaultFields: [
+            "id",
+            "username",
+            "status",
+            "firstName",
+            "lastName",
+            "primaryEmail",
+            "createdOn",
+        ],
+        edges: ["retailer", "attributes"],
+        gotchas: [
+            "NO ref field; username is the identifier",
+            "promotionOptIn (Boolean!) is REQUIRED",
+            'retailer must be { id: N }',
+        ],
+        hasRef: false,
+        retailerScoped: true,
+    },
+    PRODUCT: {
+        createMutation: "createProduct",
+        createInputType: "CreateProductInput",
+        updateMutation: "updateProduct",
+        updateInputType: "UpdateProductInput",
+        queryRoot: "products",
+        queryById: "productById",
+        requiredCreateFields: ["ref", "type", "name", "catalogue"],
+        defaultFields: [
+            "id",
+            "ref",
+            "status",
+            "type",
+            "name",
+            "gtin",
+            "createdOn",
+        ],
+        edges: ["categories", "attributes", "catalogue"],
+        gotchas: [
+            'catalogue must be { ref: "PC:MASTER:N" } (ProductCatalogueKey)',
+            "gtin has 20-char max; do not use long refs as gtin",
+            "status auto-set to CREATED",
+            'For variant→parent link, use product: { ref, catalogue: { ref } } (ProductKey requires BOTH)',
+        ],
+        hasRef: true,
+        retailerScoped: false,
+    },
+    INVENTORY_POSITION: {
+        createMutation: "createInventoryPosition",
+        createInputType: "CreateInventoryPositionInput",
+        updateMutation: "updateInventoryPosition",
+        updateInputType: "UpdateInventoryPositionInput",
+        queryRoot: "inventoryPositions",
+        queryById: "inventoryPositionById",
+        requiredCreateFields: ["ref", "type", "catalogue", "locationRef", "productRef"],
+        defaultFields: [
+            "id",
+            "ref",
+            "status",
+            "type",
+            "onHand",
+            "createdOn",
+            "updatedOn",
+        ],
+        edges: ["location", "product", "catalogue", "attributes"],
+        gotchas: [
+            'catalogue must be { ref: "DEFAULT:N" } (InventoryCatalogueKey)',
+            "locationRef and productRef are String fields, not object keys",
+            "status auto-set to CREATED",
+        ],
+        hasRef: true,
+        retailerScoped: false,
+    },
+    VIRTUAL_CATALOGUE: {
+        createMutation: "createVirtualCatalogue",
+        createInputType: "CreateVirtualCatalogueInput",
+        updateMutation: "updateVirtualCatalogue",
+        updateInputType: "UpdateVirtualCatalogueInput",
+        queryRoot: "virtualCatalogues",
+        queryById: "virtualCatalogueById",
+        requiredCreateFields: [
+            "ref",
+            "type",
+            "inventoryCatalogueRef",
+            "productCatalogueRef",
+        ],
+        defaultFields: ["id", "ref", "status", "type", "createdOn"],
+        edges: ["virtualPositions"],
+        gotchas: [
+            "inventoryCatalogueRef and productCatalogueRef are both String! (not object keys)",
+        ],
+        hasRef: true,
+        retailerScoped: false,
+    },
+    VIRTUAL_POSITION: {
+        createMutation: "createVirtualPosition",
+        createInputType: "CreateVirtualPositionInput",
+        updateMutation: "updateVirtualPosition",
+        updateInputType: "UpdateVirtualPositionInput",
+        queryRoot: "virtualPositions",
+        queryById: "virtualPositionById",
+        requiredCreateFields: ["ref", "type", "catalogue", "productRef", "quantity"],
+        defaultFields: ["id", "ref", "status", "type", "quantity", "createdOn"],
+        edges: ["catalogue", "product"],
+        gotchas: ["quantity (Int!) is REQUIRED"],
+        hasRef: true,
+        retailerScoped: false,
+    },
+    CATEGORY: {
+        createMutation: "createCategory",
+        createInputType: "CreateCategoryInput",
+        updateMutation: "updateCategory",
+        updateInputType: "UpdateCategoryInput",
+        queryRoot: "categories",
+        queryById: "categoryById",
+        requiredCreateFields: ["ref", "type", "name", "catalogue"],
+        defaultFields: ["id", "ref", "status", "type", "name", "createdOn"],
+        edges: ["products", "childCategories", "parentCategory", "attributes"],
+        gotchas: ['catalogue must be { ref: "..." } (ProductCatalogueKey)'],
+        hasRef: true,
+        retailerScoped: false,
+    },
+    CARRIER: {
+        createMutation: "createCarrier",
+        createInputType: "CreateCarrierInput",
+        updateMutation: "updateCarrier",
+        updateInputType: "UpdateCarrierInput",
+        queryRoot: "carriers",
+        queryById: "carrierById",
+        requiredCreateFields: ["name", "type", "retailer"],
+        defaultFields: ["id", "ref", "status", "type", "name", "createdOn"],
+        edges: ["retailer", "consignmentArticles", "attributes"],
+        gotchas: [
+            "name is required in create",
+            'retailer must be { id: N }',
+        ],
+        hasRef: true,
+        retailerScoped: true,
+    },
+    SETTING: {
+        createMutation: "createSetting",
+        createInputType: "CreateSettingInput",
+        updateMutation: "updateSetting",
+        updateInputType: "UpdateSettingInput",
+        queryRoot: "settings",
+        queryById: "settingById",
+        requiredCreateFields: ["name", "value", "context", "contextId"],
+        defaultFields: [
+            "id",
+            "name",
+            "value",
+            "valueType",
+            "context",
+            "contextId",
+            "lobValue",
+        ],
+        edges: [],
+        gotchas: [
+            'context is a plain String ("RETAILER"), NOT { contextType: "RETAILER" }',
+            "contextId is a separate Int field, not combined with context",
+            "For large JSON values, use lobValue instead of value (lobType: LOB)",
+        ],
+        hasRef: false,
+        retailerScoped: false,
+    },
+};
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** All supported entity types */
+export const SUPPORTED_ENTITY_TYPES = Object.keys(ENTITY_REGISTRY);
+/**
+ * Look up entity metadata. Returns null for unsupported types.
+ * Accepts case-insensitive input and normalizes underscores.
+ */
+export function getEntityMeta(entityType) {
+    const normalized = entityType.toUpperCase().replace(/-/g, "_");
+    return ENTITY_REGISTRY[normalized] ?? null;
+}
+/**
+ * Build a GraphQL create mutation string for an entity type.
+ * Returns the mutation string and the input type for variable binding.
+ */
+export function buildCreateMutation(entityType, returnFields) {
+    const meta = getEntityMeta(entityType);
+    if (!meta)
+        return null;
+    const fields = returnFields ?? meta.defaultFields;
+    const fieldSelection = fields.join(" ");
+    return {
+        mutation: `mutation Create($input: ${meta.createInputType}!) {
+  ${meta.createMutation}(input: $input) {
+    ${fieldSelection}
+  }
+}`,
+        inputType: meta.createInputType,
+    };
+}
+/**
+ * Build a GraphQL update mutation string for an entity type.
+ */
+export function buildUpdateMutation(entityType, returnFields) {
+    const meta = getEntityMeta(entityType);
+    if (!meta)
+        return null;
+    const fields = returnFields ?? meta.defaultFields;
+    const fieldSelection = fields.join(" ");
+    return {
+        mutation: `mutation Update($input: ${meta.updateInputType}!) {
+  ${meta.updateMutation}(input: $input) {
+    ${fieldSelection}
+  }
+}`,
+        inputType: meta.updateInputType,
+    };
+}
+/**
+ * Build a GraphQL query to look up an entity by ID.
+ */
+export function buildGetByIdQuery(entityType, includeEdges) {
+    const meta = getEntityMeta(entityType);
+    if (!meta)
+        return null;
+    const fields = [...meta.defaultFields];
+    if (includeEdges) {
+        for (const edge of includeEdges) {
+            if (meta.edges.includes(edge)) {
+                // For connection edges, include basic node fields
+                fields.push(`${edge} { edges { node { id ref status } } }`);
+            }
+        }
+    }
+    const fieldSelection = fields.join("\n    ");
+    return {
+        query: `query GetById($id: ID!) {
+  ${meta.queryById}(id: $id) {
+    ${fieldSelection}
+  }
+}`,
+        queryRoot: meta.queryById,
+    };
+}
+/**
+ * Build a GraphQL query to search entities by ref.
+ */
+export function buildSearchByRefQuery(entityType, includeEdges) {
+    const meta = getEntityMeta(entityType);
+    if (!meta)
+        return null;
+    if (!meta.hasRef) {
+        // Entities without ref (like CUSTOMER) need different lookup
+        return null;
+    }
+    const fields = [...meta.defaultFields];
+    if (includeEdges) {
+        for (const edge of includeEdges) {
+            if (meta.edges.includes(edge)) {
+                fields.push(`${edge} { edges { node { id ref status } } }`);
+            }
+        }
+    }
+    const fieldSelection = fields.join("\n      ");
+    return {
+        query: `query SearchByRef($ref: [String]) {
+  ${meta.queryRoot}(ref: $ref, first: 1) {
+    edges {
+      node {
+        ${fieldSelection}
+      }
+    }
+  }
+}`,
+        queryRoot: meta.queryRoot,
+    };
+}
+/**
+ * Validate that required create fields are present in the input data.
+ * Returns an array of missing field names.
+ */
+export function validateCreateInput(entityType, data) {
+    const meta = getEntityMeta(entityType);
+    if (!meta)
+        return [];
+    const missing = [];
+    for (const field of meta.requiredCreateFields) {
+        if (data[field] === undefined || data[field] === null) {
+            missing.push(field);
+        }
+    }
+    return missing;
+}