@energio/holded-mcp 1.3.0 → 1.5.0

package/dist/utils/custom-fields.js

@@ -0,0 +1,133 @@
+/**
+ * Custom-fields map serialization and repair.
+ *
+ * Holded's `POST /documents/{docType}` and `POST|PUT /contacts[{id}]` endpoints
+ * decompose each `customFields` entry via their own `Object.entries` — every
+ * own-prop becomes a separate `{field: <key>, value: <val>}` row. The single
+ * reliable workaround is to send one own-prop per entry: `[{"src":"val"}]` →
+ * Holded unpacks to `[{field:"src", value:"val"}]`.
+ *
+ * Other endpoints behave normally and accept the documented `[{field, value}]`
+ * shape, or (for funnel PUT) store the array byte-for-byte.
+ *
+ * See `docs/superpowers/specs/2026-04-16-customfields-map-interface-design.md`
+ * and DRIFT entries DRIFT-INV-14 / DRIFT-INV-15.
+ *
+ * Per-resource variant lookup:
+ *
+ *   | Resource | POST           | PUT            |
+ *   |----------|----------------|----------------|
+ *   | Document | map-per-entry  | documented     |
+ *   | Contact  | map-per-entry  | map-per-entry  |
+ *   | Lead     | documented     | documented     |
+ *   | Funnel   | (n/a)          | map-per-entry  |
+ */
+/**
+ * Convert a caller-facing customFields map to the wire shape expected by a
+ * specific Holded endpoint variant. Returns `undefined` when the input is
+ * undefined or empty so callers can spread the result straight into a body
+ * without introducing a `customFields: []` noise field.
+ */
+export function serialize(map, variant) {
+    if (!map)
+        return undefined;
+    const keys = Object.keys(map);
+    if (keys.length === 0)
+        return undefined;
+    if (variant === "documented") {
+        return keys.map((k) => ({ field: k, value: map[k] }));
+    }
+    // map-per-entry
+    return keys.map((k) => ({ [k]: map[k] }));
+}
+/**
+ * Parse any observed wire shape back into a caller-facing map. Idempotent
+ * on arrays of known shapes; returns `{}` for any non-array input (including
+ * an already-parsed map — callers must not re-parse).
+ *
+ * Priority order:
+ *   1. null/undefined/non-array  → {}
+ *   2. empty array               → {}
+ *   3. whole-array mangled pairs → collapse each pair into {K: V}
+ *   4. entry-by-entry:
+ *        {field, value} exact    → {K: V}
+ *        single own-prop {K: V}  → {K: V}
+ *        otherwise               → skip
+ *
+ * Rule 3 runs before rule 4: a legitimate pair
+ *   [{field:"field", value:X}, {field:"value", value:Y}]
+ * is indistinguishable from the mangled output of `[{field:X, value:Y}]`;
+ * the mangled interpretation wins. Custom fields literally named "field"
+ * or "value" are accepted as an unavoidable heuristic cost.
+ */
+export function parse(raw) {
+    if (!Array.isArray(raw))
+        return {};
+    if (raw.length === 0)
+        return {};
+    // Rule 3: whole-array mangled pairs
+    if (raw.length % 2 === 0 && raw.every(isRowObject) && allMangledPairs(raw)) {
+        const out = {};
+        for (let i = 0; i < raw.length; i += 2) {
+            const key = String(raw[i].value);
+            const val = String(raw[i + 1].value);
+            out[key] = val;
+        }
+        return out;
+    }
+    // Rule 4: entry-by-entry
+    const out = {};
+    for (const entry of raw) {
+        if (!isRowObject(entry))
+            continue;
+        const keys = Object.keys(entry);
+        if (keys.length === 2 && "field" in entry && "value" in entry) {
+            out[String(entry.field)] = String(entry.value);
+        }
+        else if (keys.length === 1) {
+            const [k] = keys;
+            const v = entry[k];
+            if (typeof v === "string") {
+                out[k] = v;
+            }
+        }
+        // else: skip silently
+    }
+    return out;
+}
+/**
+ * Mutate-in-place: if `item` is an object with a `customFields` property,
+ * overwrite it with `parse(item.customFields)`. No-op otherwise. Returns
+ * `item` for chaining.
+ *
+ * Call sites:
+ *   - Direct handlers (documents): after `makeApiRequest`, call on each
+ *     returned document.
+ *   - Factory `responseTransform`: return `repairCustomFieldsInPlace(item)`.
+ */
+export function repairCustomFieldsInPlace(item) {
+    if (item && typeof item === "object" && "customFields" in item) {
+        const target = item;
+        target.customFields = parse(target.customFields);
+    }
+    return item;
+}
+function isRowObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function allMangledPairs(rows) {
+    for (let i = 0; i < rows.length; i += 2) {
+        const a = rows[i];
+        const b = rows[i + 1];
+        if (Object.keys(a).length !== 2 ||
+            a.field !== "field" ||
+            typeof a.value !== "string")
+            return false;
+        if (Object.keys(b).length !== 2 ||
+            b.field !== "value" ||
+            typeof b.value !== "string")
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=custom-fields.js.map

package/dist/utils/custom-fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-fields.js","sourceRoot":"","sources":["../../src/utils/custom-fields.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@energio/holded-mcp",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "MCP server for Holded — invoicing, accounting, CRM, projects, and team",
   "type": "module",
   "main": "dist/index.js",