@aifabrix/builder 2.52.0 → 2.53.0

package/lib/integration-definition/canonical-json.js

@@ -0,0 +1,51 @@
+/**
+ * Canonical JSON helpers for Builder Integration Definition hashing.
+ * @fileoverview Stable stringify for BID definitionHash
+ */
+
+'use strict';
+
+/**
+ * Recursively sort object keys for canonical JSON.
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+function sortValue(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortValue);
+  }
+  if (value && typeof value === 'object' && !(value instanceof Date)) {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      out[key] = sortValue(value[key]);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Canonical JSON string (sorted keys, no whitespace variance).
+ * @param {unknown} value
+ * @returns {string}
+ */
+function canonicalJsonString(value) {
+  return JSON.stringify(sortValue(value));
+}
+
+/**
+ * Clone BID without definitionHash for hashing.
+ * @param {Record<string, unknown>} bid
+ * @returns {Record<string, unknown>}
+ */
+function bidBodyWithoutHash(bid) {
+  const clone = { ...bid };
+  delete clone.definitionHash;
+  return clone;
+}
+
+module.exports = {
+  sortValue,
+  canonicalJsonString,
+  bidBodyWithoutHash
+};

package/lib/integration-definition/emit-suite-bid.js

@@ -0,0 +1,94 @@
+/**
+ * Stamp suite provenance onto a BID template for hard GP acceptance.
+ * @fileoverview Suite-emitted BID: suiteRunId + answerFingerprint + definitionHash
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+const { withDefinitionHash } = require('./hash');
+const { canonicalJsonString } = require('./canonical-json');
+
+/**
+ * Fingerprint discovery / case answers for BID meta.answerFingerprint.
+ * @param {unknown} answers
+ * @returns {string}
+ */
+function fingerprintAnswers(answers) {
+  const digest = crypto
+    .createHash('sha256')
+    .update(canonicalJsonString(answers === null || answers === undefined ? null : answers), 'utf8')
+    .digest('hex');
+  return `sha256:${digest}`;
+}
+
+function resolvePriorMeta(baseBid) {
+  return baseBid.meta && typeof baseBid.meta === 'object' && !Array.isArray(baseBid.meta)
+    ? baseBid.meta
+    : {};
+}
+
+function resolveAnswerFingerprint(options) {
+  if (typeof options.answerFingerprint === 'string' && options.answerFingerprint.trim()) {
+    return options.answerFingerprint.trim();
+  }
+  return fingerprintAnswers(options.answers);
+}
+
+function resolveProducedAt(options) {
+  if (typeof options.producedAt === 'string' && options.producedAt.trim()) {
+    return options.producedAt.trim();
+  }
+  return new Date().toISOString();
+}
+
+function resolveBtAssistantKey(options, priorMeta) {
+  if (typeof options.btAssistantKey === 'string' && options.btAssistantKey.trim()) {
+    return options.btAssistantKey.trim();
+  }
+  if (typeof priorMeta.btAssistantKey === 'string' && priorMeta.btAssistantKey.trim()) {
+    return priorMeta.btAssistantKey.trim();
+  }
+  return 'ra-business-transformation';
+}
+
+/**
+ * Clone a BID template and stamp suite provenance (hard GP).
+ * Does not invent datasources/capabilities — only meta + hash refresh.
+ *
+ * @param {Record<string, unknown>} baseBid - Valid BID template (e.g. example-bid.json)
+ * @param {Object} options
+ * @param {string} options.suiteRunId - Suite / processExecution id (required for hard GP)
+ * @param {string} [options.producedAt] - ISO timestamp
+ * @param {string} [options.btAssistantKey]
+ * @param {unknown} [options.answers] - Case answers for answerFingerprint
+ * @param {string} [options.answerFingerprint] - Explicit fingerprint override
+ * @returns {Record<string, unknown>}
+ */
+function emitSuiteBid(baseBid, options = {}) {
+  if (!baseBid || typeof baseBid !== 'object' || Array.isArray(baseBid)) {
+    throw new Error('emitSuiteBid requires a BID object');
+  }
+  const suiteRunId = String(options.suiteRunId || '').trim();
+  if (!suiteRunId) {
+    throw new Error('emitSuiteBid requires options.suiteRunId');
+  }
+  const priorMeta = resolvePriorMeta(baseBid);
+  const next = {
+    ...baseBid,
+    meta: {
+      ...priorMeta,
+      suiteRunId,
+      producedAt: resolveProducedAt(options),
+      btAssistantKey: resolveBtAssistantKey(options, priorMeta),
+      answerFingerprint: resolveAnswerFingerprint(options)
+    }
+  };
+  delete next.definitionHash;
+  return withDefinitionHash(next);
+}
+
+module.exports = {
+  emitSuiteBid,
+  fingerprintAnswers
+};

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
+};