@aifabrix/builder 2.51.1 → 2.52.1

package/lib/integration-definition/enrich-crm-field-mappings.js

@@ -0,0 +1,240 @@
+/**
+ * CRM-style fieldMappings + properties query for OpenAPI object APIs.
+ * @fileoverview Keep BID propertyKeys durable across force-apply
+ */
+
+'use strict';
+
+const RESERVED_ATTR = new Set(['id', 'externalId', 'associations']);
+
+/**
+ * Seed metadataSchema + fieldMappings.attributes from BID propertyKeys.
+ * Does not write dimensions[] (repair / enrich owns dimensions alignment).
+ * @param {Record<string, unknown>} body
+ * @param {unknown} propertyKeys
+ * @returns {void}
+ */
+function seedPropertyKeysOnDatasource(body, propertyKeys) {
+  const keys = Array.isArray(propertyKeys)
+    ? propertyKeys.map((row) => String(row || '').trim()).filter(Boolean)
+    : [];
+  if (keys.length === 0) {
+    return;
+  }
+  if (!body.metadataSchema || typeof body.metadataSchema !== 'object') {
+    body.metadataSchema = { type: 'object', properties: {} };
+  }
+  const schema = /** @type {any} */ (body.metadataSchema);
+  if (!schema.properties || typeof schema.properties !== 'object') {
+    schema.properties = {};
+  }
+  if (!body.fieldMappings || typeof body.fieldMappings !== 'object') {
+    body.fieldMappings = { attributes: {} };
+  }
+  const mappings = /** @type {any} */ (body.fieldMappings);
+  if (!mappings.attributes || typeof mappings.attributes !== 'object') {
+    mappings.attributes = {};
+  }
+  for (const key of keys) {
+    if (!schema.properties[key]) {
+      schema.properties[key] = {
+        type: 'string',
+        index: true,
+        filter: true,
+        description: `Synced property ${key}`
+      };
+    }
+    if (!mappings.attributes[key]) {
+      mappings.attributes[key] = {
+        expression: `{{raw.${key}}}`,
+        description: `Synced property ${key}`
+      };
+    }
+  }
+}
+
+function mappingAttributes(body) {
+  const mappings = /** @type {any} */ (body.fieldMappings);
+  if (mappings && mappings.attributes && typeof mappings.attributes === 'object') {
+    return mappings.attributes;
+  }
+  return {};
+}
+
+function propertyNameFromAttr(key, row) {
+  const expr =
+    row && typeof row === 'object' ? String(/** @type {any} */ (row).expression || '') : '';
+  const match = expr.match(/\{\{\s*raw\.properties\.([a-zA-Z0-9_]+)\s*\}\}/);
+  if (match) {
+    return match[1];
+  }
+  if (expr === `{{raw.${key}}}` || expr.includes(`raw.properties.${key}`)) {
+    return key;
+  }
+  return null;
+}
+
+/**
+ * Collect vendor property names from CRM-style attribute expressions + labelKey.
+ * @param {Record<string, unknown>} body
+ * @returns {string[]}
+ */
+function collectCrmPropertyNames(body) {
+  const names = new Set();
+  const labelKeys = Array.isArray(body.labelKey) ? body.labelKey : [];
+  for (const label of labelKeys) {
+    const key = String(label || '').trim();
+    if (key) {
+      names.add(key);
+    }
+  }
+  for (const [key, row] of Object.entries(mappingAttributes(body))) {
+    if (RESERVED_ATTR.has(key)) {
+      continue;
+    }
+    const name = propertyNameFromAttr(key, row);
+    if (name) {
+      names.add(name);
+    }
+  }
+  return [...names].sort();
+}
+
+function ensureCrmPropertiesBag(schema) {
+  if (!schema || !schema.properties || typeof schema.properties !== 'object') {
+    return;
+  }
+  schema.properties.properties = {
+    type: 'object',
+    additionalProperties: true,
+    description: 'Vendor nested properties bag (CRM object APIs)'
+  };
+  schema.properties.associations = {
+    type: 'object',
+    additionalProperties: true,
+    description: 'Associated records bag from vendor list/get'
+  };
+}
+
+function rewriteCrmLabelExpressions(mappings, labelKeys) {
+  for (const label of labelKeys) {
+    if (mappings.attributes[label]) {
+      mappings.attributes[label].expression = `{{raw.properties.${label}}}`;
+      mappings.attributes[label].description =
+        'Display label from vendor properties object';
+    }
+  }
+}
+
+function rewriteCrmAttributeExpressions(mappings, labelKeys) {
+  for (const [key, row] of Object.entries(mappings.attributes)) {
+    if (RESERVED_ATTR.has(key) || labelKeys.includes(key) || !row || typeof row !== 'object') {
+      continue;
+    }
+    const expr = String(/** @type {any} */ (row).expression || '');
+    if (expr === `{{raw.${key}}}` || !expr.includes('raw.properties.')) {
+      /** @type {any} */ (row).expression = `{{raw.properties.${key}}}`;
+      if (!/** @type {any} */ (row).description) {
+        /** @type {any} */ (row).description = `Synced property ${key}`;
+      }
+    }
+  }
+}
+
+function ensureCrmIdentityMappings(mappings) {
+  if (mappings.attributes.id) {
+    mappings.attributes.id.expression = '{{raw.id}}';
+  }
+  if (mappings.attributes.externalId) {
+    mappings.attributes.externalId.expression = '{{raw.id}}';
+  }
+  if (!mappings.attributes.associations) {
+    mappings.attributes.associations = {
+      expression: '{{raw.associations}}',
+      description: 'Associated records returned when OpenAPI associations query is set'
+    };
+  }
+}
+
+/**
+ * When collection paths look like CRM object APIs, prefer nested properties for labels
+ * and request those properties on list/get CIP queries.
+ * @param {Record<string, unknown>} body
+ * @param {string} samplePath
+ * @returns {void}
+ */
+function maybeEnrichCrmStyleFieldMappings(body, samplePath) {
+  if (!/\/objects\//i.test(samplePath)) {
+    return;
+  }
+  const mappings = /** @type {any} */ (body.fieldMappings);
+  if (!mappings || !mappings.attributes || typeof mappings.attributes !== 'object') {
+    return;
+  }
+  const labelKeys = Array.isArray(body.labelKey) ? body.labelKey : ['name'];
+  ensureCrmPropertiesBag(/** @type {any} */ (body.metadataSchema));
+  rewriteCrmLabelExpressions(mappings, labelKeys);
+  rewriteCrmAttributeExpressions(mappings, labelKeys);
+  ensureCrmIdentityMappings(mappings);
+  applyCrmPropertiesQuery(body);
+}
+
+function resolveCipOperations(body) {
+  if (
+    body.execution &&
+    typeof body.execution === 'object' &&
+    /** @type {any} */ (body.execution).cip &&
+    typeof /** @type {any} */ (body.execution).cip === 'object'
+  ) {
+    return /** @type {any} */ (body.execution).cip.operations;
+  }
+  return null;
+}
+
+function applyPropertiesToFetchSteps(op, joined) {
+  if (!op || typeof op !== 'object' || !Array.isArray(/** @type {any} */ (op).steps)) {
+    return;
+  }
+  for (const step of /** @type {any} */ (op).steps) {
+    if (!step || !step.fetch || typeof step.fetch !== 'object') {
+      continue;
+    }
+    if (!step.fetch.query || typeof step.fetch.query !== 'object') {
+      step.fetch.query = {};
+    }
+    step.fetch.query.properties = joined;
+  }
+}
+
+/**
+ * Set CIP list/get query.properties from mapped CRM property names.
+ * @param {Record<string, unknown>} body
+ * @returns {void}
+ */
+function applyCrmPropertiesQuery(body) {
+  const propertyNames = collectCrmPropertyNames(body);
+  if (propertyNames.length === 0) {
+    return;
+  }
+  const cipOps = resolveCipOperations(body);
+  if (!cipOps || typeof cipOps !== 'object') {
+    return;
+  }
+  const joined = propertyNames.join(',');
+  for (const [capKey, op] of Object.entries(cipOps)) {
+    const leaf = String(capKey || '')
+      .split('.')
+      .pop()
+      .toLowerCase();
+    if (leaf === 'list' || leaf === 'get') {
+      applyPropertiesToFetchSteps(op, joined);
+    }
+  }
+}
+
+module.exports = {
+  seedPropertyKeysOnDatasource,
+  collectCrmPropertyNames,
+  maybeEnrichCrmStyleFieldMappings,
+  applyCrmPropertiesQuery
+};

package/lib/integration-definition/enrich-openapi-operations.js

@@ -0,0 +1,434 @@
+/**
+ * Bind BID capability keys to OpenAPI method/path (vendor-agnostic heuristics).
+ * @fileoverview BID apply OpenAPI enrichment
+ */
+
+'use strict';
+
+const fs = require('../internal/fs-real-sync');
+const path = require('path');
+const {
+  maybeEnrichCrmStyleFieldMappings
+} = require('./enrich-crm-field-mappings');
+
+const PATH_PARAM_RE = /\{(\w+)\}/g;
+
+/**
+ * @param {string} ref
+ * @param {string} [baseDir]
+ * @returns {string}
+ */
+function resolveOpenApiRefPath(ref, baseDir) {
+  const trimmed = String(ref || '').trim();
+  if (!trimmed) {
+    throw new Error('openapiSourceRef is empty');
+  }
+  if (path.isAbsolute(trimmed)) {
+    return trimmed;
+  }
+  const moduleEnrichmentDir = path.join(__dirname, 'openapi-enrichment');
+  // Prefer caller baseDir, then bundled openapi-enrichment, then cwd.
+  // Cwd last avoids false misses when Jest mocks fs.existsSync but readFileSync
+  // remains real (fallback would otherwise point at <cwd>/<ref>).
+  const candidates = [
+    baseDir ? path.resolve(baseDir, trimmed) : null,
+    path.join(moduleEnrichmentDir, trimmed),
+    path.join(moduleEnrichmentDir, path.basename(trimmed)),
+    path.resolve(process.cwd(), trimmed)
+  ].filter(Boolean);
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return candidates[0];
+}
+
+/**
+ * @param {string} ref
+ * @param {string} [baseDir]
+ * @returns {Record<string, unknown>}
+ */
+function loadOpenApiDocument(ref, baseDir) {
+  const abs = resolveOpenApiRefPath(ref, baseDir);
+  const raw = fs.readFileSync(abs, 'utf8');
+  const doc = JSON.parse(raw);
+  if (!doc || typeof doc !== 'object' || !doc.paths || typeof doc.paths !== 'object') {
+    throw new Error(`OpenAPI document missing paths: ${abs}`);
+  }
+  return doc;
+}
+
+/**
+ * Object-collection segment from paths like `/crm/v3/objects/companies`.
+ * @param {string} opPath
+ * @returns {string | null}
+ */
+function objectTypeFromOpenApiPath(opPath) {
+  const match = String(opPath || '').match(/\/objects\/([^/{?]+)/i);
+  const value = match && match[1] ? String(match[1]).trim() : '';
+  if (!value) {
+    return null;
+  }
+  // Skip opaque numeric type ids (e.g. HubSpot `0-3`); associations query
+  // expects named collection segments when available.
+  if (/^\d/.test(value)) {
+    return null;
+  }
+  return value;
+}
+
+/**
+ * @param {Record<string, unknown>} doc
+ * @param {string} method
+ * @param {string} opPath
+ * @returns {boolean}
+ */
+/**
+ * @param {Record<string, unknown>} doc
+ * @param {string} method
+ * @param {string} opPath
+ * @returns {any | null}
+ */
+function operationFromDoc(doc, method, opPath) {
+  const pathItem = /** @type {any} */ (doc && doc.paths ? doc.paths[opPath] : null);
+  if (!pathItem || typeof pathItem !== 'object') {
+    return null;
+  }
+  return (
+    pathItem[String(method || '').toLowerCase()] ||
+    pathItem[String(method || '').toUpperCase()] ||
+    null
+  );
+}
+
+/**
+ * @param {Record<string, unknown>} doc
+ * @param {string} method
+ * @param {string} opPath
+ * @returns {any[]}
+ */
+function operationParameters(doc, method, opPath) {
+  const pathItem = /** @type {any} */ (doc && doc.paths ? doc.paths[opPath] : null);
+  const op = operationFromDoc(doc, method, opPath);
+  return [
+    ...(pathItem && Array.isArray(pathItem.parameters) ? pathItem.parameters : []),
+    ...(op && Array.isArray(op.parameters) ? op.parameters : [])
+  ];
+}
+
+function operationDeclaresAssociationsQuery(doc, method, opPath) {
+  return operationParameters(doc, method, opPath).some(
+    (row) =>
+      row &&
+      typeof row === 'object' &&
+      row.in === 'query' &&
+      String(row.name || '').toLowerCase() === 'associations'
+  );
+}
+
+/**
+ * Detect cursor list pagination from OpenAPI query params + response schema/docs.
+ * Vendor-agnostic: only emits when both cursor and page-size query params exist and
+ * response/docs mention a paging.next.after style cursor field.
+ * @param {Record<string, unknown>} doc
+ * @param {string} method
+ * @param {string} opPath
+ * @returns {{ cursorParam: string, pageSizeParam: string, cursorField: string } | null}
+ */
+function operationCursorPagination(doc, method, opPath) {
+  const params = operationParameters(doc, method, opPath).filter(
+    (row) => row && typeof row === 'object' && row.in === 'query'
+  );
+  const names = new Set(
+    params.map((row) => String(row.name || '').toLowerCase()).filter(Boolean)
+  );
+  if (!names.has('after') || !names.has('limit')) {
+    return null;
+  }
+  const blob = JSON.stringify({
+    params,
+    op: operationFromDoc(doc, method, opPath)
+  });
+  if (!/paging\.next\.after/i.test(blob)) {
+    return null;
+  }
+  return {
+    cursorParam: 'after',
+    pageSizeParam: 'limit',
+    cursorField: '$.paging.next.after'
+  };
+}
+
+/**
+ * @param {string} method
+ * @param {string} opPath
+ * @param {Record<string, unknown>} op
+ * @returns {{ method: string, path: string, operationId: string, pathParamCount: number }}
+ */
+function normalizeOp(method, opPath, op) {
+  const params = [...String(opPath).matchAll(PATH_PARAM_RE)].map((m) => m[1]);
+  return {
+    method: String(method || '').toUpperCase(),
+    path: String(opPath),
+    operationId: typeof op.operationId === 'string' ? op.operationId : '',
+    pathParamCount: params.length
+  };
+}
+
+/**
+ * @param {Record<string, unknown>} doc
+ * @returns {Array<{ method: string, path: string, operationId: string, pathParamCount: number }>}
+ */
+function indexOpenApiOperations(doc) {
+  const out = [];
+  for (const [opPath, methods] of Object.entries(doc.paths || {})) {
+    if (!methods || typeof methods !== 'object') {
+      continue;
+    }
+    for (const [method, op] of Object.entries(methods)) {
+      if (!op || typeof op !== 'object' || method.startsWith('x-')) {
+        continue;
+      }
+      if (!['get', 'post', 'put', 'patch', 'delete'].includes(method.toLowerCase())) {
+        continue;
+      }
+      out.push(normalizeOp(method, opPath, /** @type {Record<string, unknown>} */ (op)));
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {string} text
+ * @returns {boolean}
+ */
+function isBatchOrSearch(text) {
+  // Keep DELETE archive ops; exclude batch/search helpers only.
+  return /\/batch\/|\bbatch\b|\/search|merge|upsert/i.test(text);
+}
+
+/**
+ * @param {string} capabilityKey
+ * @param {Array<{ method: string, path: string, operationId: string, pathParamCount: number }>} ops
+ * @returns {{ method: string, path: string, operationId: string } | null}
+ */
+function pickFirstMatchingOp(candidates, predicate, idPattern) {
+  const hits = candidates.filter(predicate);
+  return hits.find((op) => idPattern.test(op.operationId)) || hits[0] || null;
+}
+
+function pickOperationForCapability(capabilityKey, ops) {
+  const key = String(capabilityKey || '').toLowerCase();
+  const candidates = ops.filter((op) => !isBatchOrSearch(`${op.path} ${op.operationId}`));
+  const rules = {
+    list: {
+      predicate: (op) => op.method === 'GET' && op.pathParamCount === 0,
+      idPattern: /getpage|list|getall/i
+    },
+    get: {
+      predicate: (op) => op.method === 'GET' && op.pathParamCount >= 1,
+      idPattern: /getbyid|get.*id|read/i
+    },
+    create: {
+      predicate: (op) => op.method === 'POST' && op.pathParamCount === 0,
+      idPattern: /create$|_create$/i
+    },
+    createbasic: {
+      predicate: (op) => op.method === 'POST' && op.pathParamCount === 0,
+      idPattern: /create$|_create$/i
+    },
+    update: {
+      predicate: (op) =>
+        (op.method === 'PATCH' || op.method === 'PUT') && op.pathParamCount >= 1,
+      idPattern: /update$|_update$/i
+    },
+    updatebasic: {
+      predicate: (op) =>
+        (op.method === 'PATCH' || op.method === 'PUT') && op.pathParamCount >= 1,
+      idPattern: /update$|_update$/i
+    },
+    delete: {
+      predicate: (op) => op.method === 'DELETE' && op.pathParamCount >= 1,
+      idPattern: /archive|delete/i
+    }
+  };
+  const rule = rules[key];
+  if (!rule) {
+    return null;
+  }
+  return pickFirstMatchingOp(candidates, rule.predicate, rule.idPattern);
+}
+
+/**
+ * @param {Record<string, unknown>} body
+ * @param {{ method: string, path: string, operationId: string }} binding
+ * @param {string} capabilityKey
+ * @param {{
+ *   hasAssociationsQuery?: boolean,
+ *   associationTargets?: string[],
+ *   cursorPagination?: { cursorParam: string, pageSizeParam: string, cursorField: string } | null
+ * }} [bindOptions]
+ * @returns {void}
+ */
+function bindOpenApiOperation(body, binding, capabilityKey) {
+  if (!body.openapi || typeof body.openapi !== 'object') {
+    body.openapi = {};
+  }
+  const openapi = /** @type {Record<string, unknown>} */ (body.openapi);
+  openapi.enabled = true;
+  if (!openapi.operations || typeof openapi.operations !== 'object') {
+    openapi.operations = {};
+  }
+  const ops = /** @type {Record<string, unknown>} */ (openapi.operations);
+  const prev = ops[capabilityKey] && typeof ops[capabilityKey] === 'object'
+    ? /** @type {Record<string, unknown>} */ (ops[capabilityKey])
+    : {};
+  ops[capabilityKey] = {
+    ...prev,
+    operationId: binding.operationId || prev.operationId || capabilityKey,
+    method: binding.method,
+    path: binding.path
+  };
+}
+
+function createCipQuery(capabilityKey, bindOptions) {
+  const cap = String(capabilityKey || '').toLowerCase();
+  const query = {};
+  const targets = Array.isArray(bindOptions.associationTargets)
+    ? bindOptions.associationTargets.map((row) => String(row || '').trim()).filter(Boolean)
+    : [];
+  if (targets.length > 0 && bindOptions.hasAssociationsQuery && (cap === 'list' || cap === 'get')) {
+    query.associations = targets.join(',');
+  }
+  const cursorPagination =
+    bindOptions.cursorPagination && typeof bindOptions.cursorPagination === 'object'
+      ? bindOptions.cursorPagination
+      : null;
+  if (cap === 'list' && cursorPagination) {
+    query[cursorPagination.pageSizeParam] = `{{${cursorPagination.pageSizeParam}}}`;
+    query[cursorPagination.cursorParam] = `{{${cursorPagination.cursorParam}}}`;
+  }
+  return { cap, query, cursorPagination };
+}
+
+function createCipSteps(capabilityKey, binding, cipQuery) {
+  const { cap, query, cursorPagination } = cipQuery;
+  const steps = [{ fetch: { source: 'openapi', openapiRef: capabilityKey, query } }];
+  if (cap === 'list' && /\/objects\//i.test(binding.path)) {
+    if (cursorPagination) {
+      steps.push({
+        paginate: {
+          strategy: 'cursor',
+          cursorField: cursorPagination.cursorField,
+          cursorParam: cursorPagination.cursorParam,
+          pageSizeParam: cursorPagination.pageSizeParam,
+          pageSize: 100,
+          maxPages: 100
+        }
+      });
+    }
+    steps.push({ map: { useFieldMappings: true, inputPath: '$.results[*]' } });
+  } else if (cap === 'get' || /^create/.test(cap) || /^update/.test(cap) || cap === 'delete' || cap === 'archive') {
+    steps.push({ map: { useFieldMappings: true, inputPath: '$' } });
+  }
+  steps.push({ output: { mode: 'records' } });
+  return steps;
+}
+
+function bindCipOperation(body, binding, capabilityKey, bindOptions) {
+  if (!body.execution || typeof body.execution !== 'object') {
+    body.execution = { engine: 'cip' };
+  }
+  const execution = /** @type {Record<string, unknown>} */ (body.execution);
+  if (!execution.cip || typeof execution.cip !== 'object') {
+    execution.cip = { version: '1.0', operations: {} };
+  }
+  const cip = /** @type {Record<string, unknown>} */ (execution.cip);
+  if (!cip.operations || typeof cip.operations !== 'object') {
+    cip.operations = {};
+  }
+  const cipOps = /** @type {Record<string, unknown>} */ (cip.operations);
+  const existing = cipOps[capabilityKey];
+  const steps = createCipSteps(capabilityKey, binding, createCipQuery(capabilityKey, bindOptions));
+  cipOps[capabilityKey] = {
+    ...(existing && typeof existing === 'object' ? existing : {}),
+    enabled: true,
+    description:
+      (existing &&
+        typeof existing === 'object' &&
+      /** @type {any} */ (existing).description) ||
+      `Execute ${capabilityKey} via OpenAPI`,
+    steps
+  };
+}
+
+function applyBindingToDatasource(body, binding, capabilityKey, bindOptions = {}) {
+  bindOpenApiOperation(body, binding, capabilityKey);
+  bindCipOperation(body, binding, capabilityKey, bindOptions);
+}
+
+/**
+ * Enrich datasource openapi.operations + CIP steps from an OpenAPI document.
+ * @param {Record<string, unknown>} body - datasource body (mutated)
+ * @param {string} openapiSourceRef
+ * @param {{ baseDir?: string, associationTargets?: string[] }} [options]
+ * @returns {string[]} capability keys that received method/path bindings
+ */
+function enrichDatasourceFromOpenApi(body, openapiSourceRef, options = {}) {
+  const doc = loadOpenApiDocument(openapiSourceRef, options.baseDir);
+  const indexed = indexOpenApiOperations(doc);
+  const caps = Array.isArray(body.capabilities)
+    ? body.capabilities
+      .map((row) => (row && typeof row === 'object' ? row.key : row))
+      .filter((k) => typeof k === 'string' && k.trim())
+    : [];
+  const selfTypeCandidates = indexed
+    .map((op) => objectTypeFromOpenApiPath(op.path))
+    .filter(Boolean);
+  // Opaque OpenAPI paths (e.g. /objects/0-3) yield no segment — fall back to BID ds key.
+  const selfType =
+    selfTypeCandidates[0] ||
+    (typeof body.key === 'string' && body.key.trim() ? body.key.trim() : null);
+  const associationTargets = (
+    Array.isArray(options.associationTargets) ? options.associationTargets : []
+  )
+    .map((row) => String(row || '').trim())
+    .filter((row) => row && row !== selfType);
+  const bound = [];
+  let samplePath = '';
+  for (const capabilityKey of caps) {
+    const picked = pickOperationForCapability(capabilityKey, indexed);
+    if (!picked) {
+      continue;
+    }
+    applyBindingToDatasource(body, picked, capabilityKey, {
+      hasAssociationsQuery: operationDeclaresAssociationsQuery(
+        doc,
+        picked.method,
+        picked.path
+      ),
+      associationTargets,
+      cursorPagination: operationCursorPagination(doc, picked.method, picked.path)
+    });
+    bound.push(capabilityKey);
+    if (!samplePath) {
+      samplePath = picked.path;
+    }
+  }
+  if (samplePath) {
+    maybeEnrichCrmStyleFieldMappings(body, samplePath);
+  }
+  return bound;
+}
+
+module.exports = {
+  resolveOpenApiRefPath,
+  loadOpenApiDocument,
+  indexOpenApiOperations,
+  pickOperationForCapability,
+  enrichDatasourceFromOpenApi,
+  objectTypeFromOpenApiPath,
+  operationDeclaresAssociationsQuery,
+  operationCursorPagination
+};