@aifabrix/builder 2.52.0 → 2.53.0

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

@@ -0,0 +1,433 @@
+/**
+ * Bind BID capability keys to OpenAPI method/path (vendor-agnostic heuristics).
+ * @fileoverview BID apply OpenAPI enrichment
+ */
+
+'use strict';
+
+const path = require('path');
+const fsReal = require('../internal/fs-real-sync');
+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;
+  }
+  // Product resolve root is workspace openapi/ (517.2) via explicit baseDir.
+  // No ship-local vendor enrichment packs under lib/.
+  const candidates = [
+    baseDir ? path.resolve(baseDir, trimmed) : null,
+    baseDir ? path.resolve(baseDir, path.basename(trimmed)) : null,
+    path.resolve(process.cwd(), trimmed)
+  ].filter(Boolean);
+  for (const candidate of candidates) {
+    if (fsReal.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  throw new Error(
+    `OpenAPI enrichment document not found for ref "${trimmed}". Tried: ${candidates.join(', ')}`
+  );
+}
+
+/**
+ * @param {string} ref
+ * @param {string} [baseDir]
+ * @returns {Record<string, unknown>}
+ */
+function loadOpenApiDocument(ref, baseDir) {
+  const abs = resolveOpenApiRefPath(ref, baseDir);
+  const raw = fsReal.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
+};