@fluentcommerce/fluent-mcp-extn 0.1.0

package/dist/response-shaper.js

@@ -0,0 +1,361 @@
+// ---------------------------------------------------------------------------
+// Response shaping: local analysis before LLM
+// ---------------------------------------------------------------------------
+/** Protected keys that are never stripped, even when empty/null. */
+const PROTECTED_KEYS = new Set([
+    "ok",
+    "error",
+    "code",
+    "message",
+    "retryable",
+    "id",
+    "ref",
+    "status",
+]);
+/**
+ * Default budget: 50 000 chars (~12.5k tokens).
+ * Set FLUENT_RESPONSE_BUDGET_CHARS=0 to disable (unlimited).
+ */
+const DEFAULT_BUDGET_CHARS = 50_000;
+export function loadResponseBudget() {
+    const raw = process.env.FLUENT_RESPONSE_BUDGET_CHARS?.trim();
+    // Explicit "0" disables budget; absence uses sensible default
+    const maxChars = raw !== undefined
+        ? envNumber("FLUENT_RESPONSE_BUDGET_CHARS", DEFAULT_BUDGET_CHARS, 0)
+        : DEFAULT_BUDGET_CHARS;
+    const maxArrayElements = envNumber("FLUENT_RESPONSE_MAX_ARRAY", 50, 1);
+    const sampleSize = envNumber("FLUENT_RESPONSE_SAMPLE_SIZE", 3, 1);
+    return {
+        maxChars,
+        maxArrayElements: maxChars > 0 ? maxArrayElements : Infinity,
+        sampleSize,
+        stripEmpty: maxChars > 0,
+    };
+}
+function envNumber(name, fallback, min) {
+    const raw = process.env[name]?.trim();
+    if (!raw)
+        return fallback;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < min)
+        return fallback;
+    return n;
+}
+/**
+ * Shape a payload to fit within a character budget.
+ *
+ * Strategy (in order):
+ * 1. Strip null/undefined/empty-string values (keeps protected keys).
+ * 2. Auto-summarize arrays that exceed maxArrayElements: instead of truncating
+ *    (which gives the LLM incomplete data), produce a COMPLETE summary with
+ *    record count, field inventory, value distribution, and sample records.
+ * 3. Auto-summarize objects with more keys than maxArrayElements (same approach).
+ * 4. If still over budget after pass 1, progressively tighten thresholds
+ *    (halve maxArrayElements and sampleSize) and re-shape up to 3 times.
+ * 5. Returns payload unchanged if no budget is set or it already fits.
+ *
+ * The budget is enforced as a HARD cap. After all passes, if the response
+ * still exceeds the budget, a final truncation with _budgetExceeded marker
+ * ensures the response never blows out the LLM context window.
+ */
+export function shapeResponse(payload, budget) {
+    const original = JSON.stringify(payload);
+    const originalChars = original.length;
+    if (budget.maxChars <= 0 || originalChars <= budget.maxChars) {
+        return {
+            shaped: payload,
+            meta: {
+                originalChars,
+                shapedChars: originalChars,
+                reductionPercent: 0,
+                summarizedArrays: 0,
+                strippedFields: 0,
+            },
+        };
+    }
+    // Iterative shaping: progressively tighten thresholds until within budget
+    const totalStats = { summarizedArrays: 0, strippedFields: 0 };
+    let currentBudget = { ...budget };
+    let shaped = payload;
+    let shapedStr;
+    const MAX_PASSES = 3;
+    for (let pass = 0; pass < MAX_PASSES; pass++) {
+        const stats = { summarizedArrays: 0, strippedFields: 0 };
+        shaped = deepShape(shaped, currentBudget, stats);
+        shapedStr = JSON.stringify(shaped);
+        totalStats.summarizedArrays += stats.summarizedArrays;
+        totalStats.strippedFields += stats.strippedFields;
+        if (shapedStr.length <= budget.maxChars)
+            break;
+        // Tighten for next pass: halve thresholds (min 5 elements, 1 sample)
+        currentBudget = {
+            ...currentBudget,
+            maxArrayElements: Math.max(5, Math.floor(currentBudget.maxArrayElements / 2)),
+            sampleSize: Math.max(1, Math.floor(currentBudget.sampleSize / 2)),
+        };
+    }
+    shapedStr = JSON.stringify(shaped);
+    // Final safety net: if still over budget, truncate with marker
+    if (shapedStr.length > budget.maxChars) {
+        const marker = `,"_budgetExceeded":true,"_originalChars":${originalChars},"_budgetChars":${budget.maxChars}}`;
+        // Reserve space for the marker at the end
+        const truncateAt = budget.maxChars - marker.length;
+        if (truncateAt > 100) {
+            shapedStr = shapedStr.slice(0, truncateAt) + marker;
+            try {
+                shaped = JSON.parse(shapedStr);
+            }
+            catch {
+                // If truncated JSON is invalid, wrap in an envelope
+                shaped = {
+                    _budgetExceeded: true,
+                    _originalChars: originalChars,
+                    _budgetChars: budget.maxChars,
+                    _note: "Response exceeded budget after all shaping passes. Use targeted queries (compact mode, filters, specific IDs) to get smaller responses.",
+                };
+                shapedStr = JSON.stringify(shaped);
+            }
+        }
+    }
+    const shapedChars = shapedStr.length;
+    return {
+        shaped,
+        meta: {
+            originalChars,
+            shapedChars,
+            reductionPercent: Math.round(((originalChars - shapedChars) / originalChars) * 100),
+            summarizedArrays: totalStats.summarizedArrays,
+            strippedFields: totalStats.strippedFields,
+        },
+    };
+}
+function deepShape(value, budget, stats) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value !== "object")
+        return value;
+    if (Array.isArray(value)) {
+        if (value.length > budget.maxArrayElements) {
+            return summarizeArray(value, budget.sampleSize, stats);
+        }
+        return value.map((item) => deepShape(item, budget, stats));
+    }
+    // Object
+    const obj = value;
+    const keys = Object.keys(obj);
+    // Summarize large objects (e.g., plugin.list with 597 rule keys)
+    if (keys.length > budget.maxArrayElements && !hasProtectedStructure(obj)) {
+        return summarizeObject(obj, keys, budget.sampleSize, stats);
+    }
+    const out = {};
+    for (const [key, val] of Object.entries(obj)) {
+        const shapedVal = deepShape(val, budget, stats);
+        if (budget.stripEmpty && !PROTECTED_KEYS.has(key)) {
+            if (shapedVal === null || shapedVal === undefined || shapedVal === "") {
+                stats.strippedFields++;
+                continue;
+            }
+        }
+        out[key] = shapedVal;
+    }
+    return out;
+}
+/**
+ * Check if an object is a top-level response envelope that should NOT be summarized.
+ * Envelopes have 'ok' key or very few keys — they wrap the real data.
+ */
+function hasProtectedStructure(obj) {
+    if ("ok" in obj)
+        return true;
+    if ("error" in obj)
+        return true;
+    if ("data" in obj)
+        return true; // GraphQL response wrapper
+    // Small objects (≤10 keys) are likely structured responses, not large data maps
+    if (Object.keys(obj).length <= 10)
+        return true;
+    return false;
+}
+/**
+ * Summarize a large object (many keys) like we summarize arrays.
+ *
+ * Produces:
+ * - _summarized: true
+ * - totalKeys: number of keys
+ * - keysSample: first N key names
+ * - sample: first N key-value pairs (as object)
+ * - valueShape: field names found in value objects (if values are objects)
+ */
+function summarizeObject(obj, keys, sampleSize, stats) {
+    stats.summarizedArrays++;
+    const summary = {
+        _summarized: true,
+        totalKeys: keys.length,
+        keysSample: keys.slice(0, Math.min(20, keys.length)),
+    };
+    // Check if values are objects — extract their field structure
+    const firstVal = obj[keys[0]];
+    if (firstVal && typeof firstVal === "object" && !Array.isArray(firstVal)) {
+        const fieldSet = new Set();
+        // Sample first 50 values for field discovery
+        const sampleKeys = keys.slice(0, 50);
+        for (const k of sampleKeys) {
+            const v = obj[k];
+            if (v && typeof v === "object" && !Array.isArray(v)) {
+                for (const field of Object.keys(v)) {
+                    fieldSet.add(field);
+                }
+            }
+        }
+        summary.valueFields = Array.from(fieldSet).sort();
+    }
+    // Include first N full entries as sample
+    const sampleObj = {};
+    for (let i = 0; i < sampleSize && i < keys.length; i++) {
+        sampleObj[keys[i]] = obj[keys[i]];
+    }
+    summary.sample = sampleObj;
+    return summary;
+}
+/**
+ * Auto-summarize an array instead of truncating it.
+ *
+ * Produces a COMPLETE analytical summary:
+ * - totalCount: exact record count
+ * - fields: all field names across records (if objects)
+ * - sample: first N records for LLM to see actual data shape
+ * - distribution: value counts for key categorical fields (status, type, name, entityType)
+ *
+ * The LLM gets a full, accurate picture without incomplete raw data.
+ */
+function summarizeArray(arr, sampleSize, stats) {
+    stats.summarizedArrays++;
+    const summary = {
+        _summarized: true,
+        totalCount: arr.length,
+    };
+    // If array contains objects, extract field names and distributions
+    const firstObj = arr.find((item) => item !== null && typeof item === "object" && !Array.isArray(item));
+    if (firstObj) {
+        // Collect all field names across all records
+        const fieldSet = new Set();
+        for (const item of arr) {
+            if (item && typeof item === "object" && !Array.isArray(item)) {
+                for (const key of Object.keys(item)) {
+                    fieldSet.add(key);
+                }
+            }
+        }
+        summary.fields = Array.from(fieldSet).sort();
+        // Build value distributions for categorical fields
+        const categoricalKeys = ["status", "type", "name", "entityType",
+            "eventStatus", "category", "subtype", "eventType"];
+        const distributions = {};
+        for (const key of categoricalKeys) {
+            if (!fieldSet.has(key))
+                continue;
+            const counts = {};
+            for (const item of arr) {
+                if (item && typeof item === "object" && !Array.isArray(item)) {
+                    const val = item[key];
+                    if (val !== null && val !== undefined) {
+                        const strVal = String(val);
+                        counts[strVal] = (counts[strVal] ?? 0) + 1;
+                    }
+                }
+            }
+            if (Object.keys(counts).length > 0) {
+                distributions[key] = counts;
+            }
+        }
+        if (Object.keys(distributions).length > 0) {
+            summary.distributions = distributions;
+        }
+        // Sample records (first N)
+        summary.sample = arr.slice(0, sampleSize);
+    }
+    else {
+        // Array of primitives or mixed — just show sample
+        summary.sample = arr.slice(0, sampleSize);
+    }
+    return summary;
+}
+/**
+ * Detect Relay connection pattern in a GraphQL response and return a summary.
+ * Returns null if no connection pattern is detected.
+ */
+export function summarizeConnection(response, sampleSize = 3) {
+    if (!response || typeof response !== "object")
+        return null;
+    const data = response.data;
+    if (!data || typeof data !== "object")
+        return null;
+    // Find the first key in data that has an edges array with node objects
+    for (const [key, val] of Object.entries(data)) {
+        if (!val || typeof val !== "object")
+            continue;
+        const connection = val;
+        const edges = connection.edges;
+        if (!Array.isArray(edges))
+            continue;
+        // Verify at least one edge has a node
+        const nodes = edges
+            .map((edge) => {
+            if (!edge || typeof edge !== "object")
+                return null;
+            return edge.node;
+        })
+            .filter((node) => node !== null && node !== undefined && typeof node === "object");
+        if (nodes.length === 0 && edges.length > 0)
+            continue;
+        const pageInfo = connection.pageInfo;
+        const hasMore = pageInfo?.hasNextPage === true;
+        const fields = nodes.length > 0 ? Object.keys(nodes[0]) : [];
+        const sample = nodes.slice(0, sampleSize);
+        return {
+            connectionKey: key,
+            recordCount: nodes.length,
+            fields,
+            sample,
+            hasMore,
+        };
+    }
+    return null;
+}
+/**
+ * Aggregate raw events into a compact analysis.
+ */
+export function analyzeEvents(results, hasMore) {
+    const groups = new Map();
+    let minTime = null;
+    let maxTime = null;
+    const statusCounts = {};
+    for (const evt of results) {
+        const name = String(evt.name ?? "unknown");
+        const ctx = evt.context;
+        const entityType = String(ctx?.entityType ?? "unknown");
+        const eventStatus = String(evt.eventStatus ?? "unknown");
+        const time = typeof evt.generatedOn === "string" ? evt.generatedOn : null;
+        const key = `${name}|${entityType}|${eventStatus}`;
+        const existing = groups.get(key);
+        if (existing)
+            existing.count++;
+        else
+            groups.set(key, { name, entityType, eventStatus, count: 1 });
+        statusCounts[eventStatus] = (statusCounts[eventStatus] ?? 0) + 1;
+        if (time) {
+            if (!minTime || time < minTime)
+                minTime = time;
+            if (!maxTime || time > maxTime)
+                maxTime = time;
+        }
+    }
+    const sorted = Array.from(groups.values()).sort((a, b) => b.count - a.count);
+    return {
+        totalCount: results.length,
+        hasMore,
+        timeRange: { from: minTime, to: maxTime },
+        statusBreakdown: statusCounts,
+        groups: sorted,
+    };
+}

package/dist/sdk-client.js

@@ -0,0 +1,237 @@
+import { exec as execCb } from "node:child_process";
+import { promisify } from "node:util";
+import { createClient, createClientFromProfile, } from "@fluentcommerce/fc-connect-sdk";
+import { hasOAuthConfig } from "./config.js";
+import { createFluentClientAdapter } from "./fluent-client.js";
+import { ToolError } from "./errors.js";
+/**
+ * SDK bootstrap and auth strategy resolution.
+ *
+ * Priority:
+ * 1) Fluent profile via createClientFromProfile (when enabled)
+ * 2) OAuth (SDK-native)
+ * 3) TOKEN_COMMAND (bridge)
+ * 4) Static token (bridge)
+ */
+const exec = promisify(execCb);
+/**
+ * Disable SDK-level retries and centralize retry policy in FluentClientAdapter.
+ * This lets us enforce "no retry" on non-idempotent operations.
+ *
+ * SDK v0.1.54+ validates delay ranges:
+ *   baseRetryDelayMs:    100–60000
+ *   maxRetryDelayMs:    1000–60000
+ *   maxAuthRetryDelayMs: 1000–60000
+ *
+ * With maxRetries=0 these values are never used, but must pass validation.
+ */
+const SDK_RETRY_ATTEMPTS = 0;
+const SDK_BASE_RETRY_DELAY_MS = 100;
+const SDK_MAX_RETRY_DELAY_MS = 1000;
+/** TTL for tokens obtained via command or OAuth refresh cycle. */
+const TOKEN_TTL_MS = 55 * 60 * 1000;
+const TOKEN_EXPIRY_BUFFER_SECONDS = 300;
+/**
+ * TTL for static tokens (FLUENT_ACCESS_TOKEN).
+ * Keep this intentionally long because there is no local refresh mechanism.
+ * The API will still reject expired tokens server-side with 401.
+ */
+const STATIC_TOKEN_TTL_MS = 365 * 24 * 60 * 60 * 1000;
+function asMutableTokenClient(client) {
+    if (!client || typeof client !== "object")
+        return null;
+    const rec = client;
+    // Verify at least one expected mutable property exists or can be set.
+    // accessToken and tokenExpiry may not exist yet (they get assigned),
+    // but getAccessToken should be present on a real SDK client.
+    if (typeof rec.getAccessToken !== "function" &&
+        typeof rec.accessToken !== "string" &&
+        !("accessToken" in rec)) {
+        return null;
+    }
+    return client;
+}
+/**
+ * Parse command output into a token string.
+ * Supports:
+ * - plain text token
+ * - JSON with access_token
+ * - JSON with token
+ */
+export function parseTokenFromCommandOutput(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed) {
+        throw new ToolError("AUTH_ERROR", "TOKEN_COMMAND returned empty output.");
+    }
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (typeof parsed.access_token === "string")
+            return parsed.access_token;
+        if (typeof parsed.token === "string")
+            return parsed.token;
+    }
+    catch {
+        // Not JSON: treat stdout as a raw token.
+    }
+    return trimmed;
+}
+async function resolveTokenFromCommand(command, timeoutMs) {
+    try {
+        const { stdout } = await exec(command, {
+            maxBuffer: 1024 * 1024,
+            timeout: timeoutMs,
+        });
+        return parseTokenFromCommandOutput(stdout);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new ToolError("AUTH_ERROR", `TOKEN_COMMAND failed: ${message}`, {
+            retryable: false,
+            cause: error,
+        });
+    }
+}
+function applyTokenBridge(client, token, ttlMs = TOKEN_TTL_MS) {
+    const mutable = asMutableTokenClient(client);
+    if (!mutable) {
+        throw new ToolError("SDK_ERROR", "Cannot inject access token into SDK client object.");
+    }
+    try {
+        mutable.accessToken = token;
+        mutable.tokenExpiry = new Date(Date.now() + ttlMs);
+    }
+    catch (error) {
+        throw new ToolError("SDK_ERROR", "Cannot assign token fields on SDK client.", {
+            cause: error,
+        });
+    }
+    // Runtime cast verification: ensure token assignment actually succeeded.
+    if (mutable.accessToken !== token) {
+        throw new ToolError("SDK_ERROR", "Cannot inject access token into SDK client object.");
+    }
+}
+/**
+ * Keeps TOKEN_COMMAND integrations working until the SDK exposes a first-class
+ * command/vault auth provider.
+ */
+function patchTokenRefreshBridge(client, command, timeoutMs) {
+    const mutable = asMutableTokenClient(client);
+    const original = mutable?.getAccessToken?.bind(mutable);
+    if (!mutable || !original)
+        return;
+    mutable.getAccessToken = async () => {
+        if (mutable.tokenExpiry && mutable.tokenExpiry > new Date() && mutable.accessToken) {
+            return mutable.accessToken;
+        }
+        const fresh = await resolveTokenFromCommand(command, timeoutMs);
+        mutable.accessToken = fresh;
+        mutable.tokenExpiry = new Date(Date.now() + TOKEN_TTL_MS);
+        return fresh;
+    };
+}
+function applyRetailerOverride(client, retailerId) {
+    if (!retailerId || !client || typeof client !== "object")
+        return;
+    const rec = client;
+    if (typeof rec.setRetailerId === "function") {
+        rec.setRetailerId(retailerId);
+    }
+}
+export async function initSDKClient(config) {
+    const baseUrl = config.baseUrl;
+    if (!baseUrl && !config.useProfileClientFactory) {
+        console.error("[sdk-client] FLUENT_BASE_URL is missing; SDK client disabled.");
+        return null;
+    }
+    try {
+        // Path 1: Fluent CLI profile via SDK profile client factory.
+        if (config.useProfileClientFactory && config.profileName) {
+            const client = await createClientFromProfile(config.profileName, {
+                retailer: config.profileRetailer ?? undefined,
+                timeout: config.requestTimeoutMs,
+                retryConfig: {
+                    maxRetries: SDK_RETRY_ATTEMPTS,
+                    maxAuthRetries: SDK_RETRY_ATTEMPTS,
+                    baseRetryDelayMs: SDK_BASE_RETRY_DELAY_MS,
+                    maxRetryDelayMs: SDK_MAX_RETRY_DELAY_MS,
+                    maxAuthRetryDelayMs: SDK_MAX_RETRY_DELAY_MS,
+                    tokenExpiryBufferSeconds: TOKEN_EXPIRY_BUFFER_SECONDS,
+                },
+            });
+            applyRetailerOverride(client, config.retailerId);
+            return createFluentClientAdapter(client, config);
+        }
+        if (!baseUrl) {
+            console.error("[sdk-client] FLUENT_BASE_URL is missing; SDK client disabled.");
+            return null;
+        }
+        // Path 2: OAuth credentials.
+        if (hasOAuthConfig(config)) {
+            const client = await createClient({
+                config: {
+                    baseUrl,
+                    clientId: config.clientId ?? undefined,
+                    clientSecret: config.clientSecret ?? undefined,
+                    username: config.username ?? undefined,
+                    password: config.password ?? undefined,
+                    retailerId: config.retailerId ?? undefined,
+                    timeout: config.requestTimeoutMs,
+                    retryAttempts: SDK_RETRY_ATTEMPTS,
+                    retryDelay: SDK_BASE_RETRY_DELAY_MS,
+                },
+            });
+            return createFluentClientAdapter(client, config);
+        }
+        // Path 3: command-based token retrieval (vault, secret manager, etc.).
+        if (config.tokenCommand) {
+            const token = await resolveTokenFromCommand(config.tokenCommand, config.tokenCommandTimeoutMs);
+            const client = await createClient({
+                config: {
+                    baseUrl,
+                    retailerId: config.retailerId ?? undefined,
+                    timeout: config.requestTimeoutMs,
+                    retryAttempts: SDK_RETRY_ATTEMPTS,
+                    retryDelay: SDK_BASE_RETRY_DELAY_MS,
+                },
+            });
+            applyTokenBridge(client, token);
+            patchTokenRefreshBridge(client, config.tokenCommand, config.tokenCommandTimeoutMs);
+            return createFluentClientAdapter(client, config);
+        }
+        // Path 4: static bearer token.
+        if (config.envAccessToken) {
+            console.warn("[sdk-client] Using static FLUENT_ACCESS_TOKEN. " +
+                "No automatic refresh is available — token will expire server-side " +
+                "according to its original grant TTL. Prefer OAuth credentials for " +
+                "long-running sessions.");
+            const client = await createClient({
+                config: {
+                    baseUrl,
+                    retailerId: config.retailerId ?? undefined,
+                    timeout: config.requestTimeoutMs,
+                    retryAttempts: SDK_RETRY_ATTEMPTS,
+                    retryDelay: SDK_BASE_RETRY_DELAY_MS,
+                },
+            });
+            applyTokenBridge(client, config.envAccessToken, STATIC_TOKEN_TTL_MS);
+            return createFluentClientAdapter(client, config);
+        }
+        // Path 5: no auth. Client can still be useful for read-only local checks,
+        // but API tools will fail until auth is configured.
+        const client = await createClient({
+            config: {
+                baseUrl,
+                retailerId: config.retailerId ?? undefined,
+                timeout: config.requestTimeoutMs,
+                retryAttempts: SDK_RETRY_ATTEMPTS,
+                retryDelay: SDK_BASE_RETRY_DELAY_MS,
+            },
+        });
+        return createFluentClientAdapter(client, config);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`[sdk-client] failed to initialize SDK client: ${message}`);
+        return null;
+    }
+}