@aifabrix/builder 2.51.1 → 2.52.1

package/lib/integration-definition/from-discovery.js

@@ -0,0 +1,339 @@
+/**
+ * Compile a BID from discovery answer bindings (suite / Intent payload).
+ * @fileoverview Deterministic discovery → aifabrix.builder.integrationDefinition
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+const { emitSuiteBid } = require('./emit-suite-bid');
+
+const DEFAULT_GATES = [
+  'GP',
+  'G1',
+  'G2',
+  'G3',
+  'G4',
+  'G5',
+  'G6',
+  'G7',
+  'G8',
+  'G9',
+  'G10',
+  'G11',
+  'G12'
+];
+
+/**
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+function unwrapBinding(value) {
+  if (value && typeof value === 'object' && !Array.isArray(value) && 'value' in value) {
+    return /** @type {{ value: unknown }} */ (value).value;
+  }
+  return value;
+}
+
+/**
+ * Flatten suite answers / Intent structuredPayload into discovery bindings.
+ * @param {unknown} answersOrPayload
+ * @returns {Record<string, unknown>}
+ */
+function discoveryBindingsFromAnswers(answersOrPayload) {
+  if (Array.isArray(answersOrPayload)) {
+    /** @type {Record<string, unknown>} */
+    const out = {};
+    for (const entry of answersOrPayload) {
+      if (!entry || typeof entry !== 'object') {
+        continue;
+      }
+      const when = /** @type {any} */ (entry).when;
+      const key = String((when && when.questionKey) || '').trim();
+      if (!key) {
+        continue;
+      }
+      const raw =
+        /** @type {any} */ (entry).value !== undefined
+          ? /** @type {any} */ (entry).value
+          : /** @type {any} */ (entry).answer;
+      out[key] = unwrapBinding(raw);
+    }
+    return out;
+  }
+  if (answersOrPayload && typeof answersOrPayload === 'object') {
+    /** @type {Record<string, unknown>} */
+    const out = {};
+    for (const [key, value] of Object.entries(answersOrPayload)) {
+      if (key.includes('.')) {
+        out[key] = unwrapBinding(value);
+      }
+    }
+    return out;
+  }
+  return {};
+}
+
+/**
+ * @param {Record<string, unknown>} bindings
+ * @returns {string[]}
+ */
+function resolveApiGroups(bindings) {
+  const raw = bindings['system.apiGroups'];
+  if (Array.isArray(raw)) {
+    return raw.map((row) => String(row || '').trim()).filter(Boolean);
+  }
+  if (typeof raw === 'string' && raw.trim()) {
+    return [raw.trim()];
+  }
+  return [];
+}
+
+/**
+ * @param {Record<string, unknown>} bindings
+ * @param {string[]} groups
+ * @param {Record<string, string>} openapiSourceRefs
+ * @returns {object[]}
+ */
+function buildDatasources(bindings, groups, openapiSourceRefs) {
+  const resourceTypes =
+    bindings['system.resourceTypes'] &&
+    typeof bindings['system.resourceTypes'] === 'object' &&
+    !Array.isArray(bindings['system.resourceTypes'])
+      ? /** @type {Record<string, unknown>} */ (bindings['system.resourceTypes'])
+      : {};
+  return groups.map((key) => {
+    const resourceType = String(resourceTypes[key] || key);
+    const openapiSourceRef =
+      (typeof openapiSourceRefs[key] === 'string' && openapiSourceRefs[key].trim()) ||
+      undefined;
+    const row = {
+      key,
+      displayName: key.charAt(0).toUpperCase() + key.slice(1),
+      entityType: 'recordStorage',
+      resourceType
+    };
+    if (openapiSourceRef) {
+      /** @type {any} */ (row).openapiSourceRef = openapiSourceRef;
+    }
+    const propertyKeys = bindings[`datasource.${key}.propertyKeys`];
+    if (Array.isArray(propertyKeys) && propertyKeys.length > 0) {
+      /** @type {any} */ (row).propertyKeys = propertyKeys
+        .map((item) => String(item || '').trim())
+        .filter(Boolean);
+    }
+    return row;
+  });
+}
+
+/**
+ * @param {Record<string, unknown>} bindings
+ * @returns {object[]}
+ */
+function buildRelationships(bindings) {
+  const raw = bindings['system.relationships'];
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  return raw
+    .filter((row) => row && typeof row === 'object')
+    .map((row) => ({
+      from: String(/** @type {any} */ (row).from || ''),
+      to: String(/** @type {any} */ (row).to || ''),
+      kind: String(/** @type {any} */ (row).kind || '')
+    }))
+    .filter((row) => row.from && row.to && row.kind);
+}
+
+/**
+ * @param {string[]} groups
+ * @param {Record<string, unknown>} bindings
+ * @returns {Record<string, string[]>}
+ */
+function buildCapabilities(groups, bindings) {
+  /** @type {Record<string, string[]>} */
+  const caps = {};
+  const named = String(bindings['system.namedWriteCapability'] || '').trim();
+  const [writeDs, writeCap] = named.includes('.')
+    ? named.split('.', 2)
+    : ['', ''];
+  for (const key of groups) {
+    const list = ['list', 'get'];
+    if (writeDs === key && writeCap) {
+      list.push(writeCap);
+      if (writeCap === 'createBasic') {
+        list.push('updateBasic', 'delete');
+      }
+    }
+    caps[key] = list;
+  }
+  return caps;
+}
+
+/**
+ * True when minimum discovery bindings exist for BID emission.
+ * @param {unknown} answersOrPayload
+ * @returns {boolean}
+ */
+function discoveryReadyForBid(answersOrPayload) {
+  const bindings = discoveryBindingsFromAnswers(answersOrPayload);
+  if (resolveApiGroups(bindings).length === 0) {
+    return false;
+  }
+  if (!bindings['system.syncMode']) {
+    return false;
+  }
+  const resourceTypes = bindings['system.resourceTypes'];
+  if (!resourceTypes || typeof resourceTypes !== 'object' || Array.isArray(resourceTypes)) {
+    return false;
+  }
+  return Object.keys(resourceTypes).length > 0;
+}
+
+/**
+ * @param {Record<string, unknown>} bindings
+ * @param {string} key
+ * @returns {Record<string, string>}
+ */
+function stringMapBinding(bindings, key) {
+  const raw = bindings[key];
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return {};
+  }
+  /** @type {Record<string, string>} */
+  const out = {};
+  for (const [mapKey, value] of Object.entries(raw)) {
+    const trimmedKey = String(mapKey || '').trim();
+    const trimmedValue = String(value || '').trim();
+    if (trimmedKey && trimmedValue) {
+      out[trimmedKey] = trimmedValue;
+    }
+  }
+  return out;
+}
+
+function mergeStringMapRefs(fromBindings, fromOptions, fallback) {
+  if (fromOptions && typeof fromOptions === 'object') {
+    return { ...fromBindings, ...fromOptions };
+  }
+  if (Object.keys(fromBindings).length > 0) {
+    return fromBindings;
+  }
+  return fallback;
+}
+
+/**
+ * Compile BID from discovery bindings + package options.
+ * Builder-owned SSOT (not dataplane Runtime).
+ * @param {Object} options
+ * @param {unknown} [options.answers]
+ * @param {Record<string, unknown>} [options.bindings]
+ * @param {string} options.systemKey
+ * @param {string} [options.displayName]
+ * @param {string} [options.packageVersion]
+ * @param {string} [options.systemKind]
+ * @param {Record<string, string>} [options.connectionRefs]
+ * @param {Record<string, string>} [options.openapiSourceRefs]
+ * @param {string} options.suiteRunId
+ * @param {string} [options.definitionId]
+ * @param {string} [options.btAssistantKey]
+ * @param {string[]} [options.knowledgePackRefs]
+ * @returns {Record<string, unknown>}
+ */
+function resolveBidInputs(options) {
+  const systemKey = String(options.systemKey || '').trim();
+  const suiteRunId = String(options.suiteRunId || '').trim();
+  if (!systemKey) {
+    throw new Error('bidFromDiscovery requires systemKey');
+  }
+  if (!suiteRunId) {
+    throw new Error('bidFromDiscovery requires suiteRunId');
+  }
+  const bindings = {
+    ...discoveryBindingsFromAnswers(options.answers),
+    ...(options.bindings && typeof options.bindings === 'object' ? options.bindings : {})
+  };
+  if (!discoveryReadyForBid(bindings)) {
+    throw new Error('bidFromDiscovery requires complete discovery bindings');
+  }
+  return {
+    systemKey,
+    suiteRunId,
+    bindings,
+    groups: resolveApiGroups(bindings),
+    syncMode: String(bindings['system.syncMode'] || 'incremental').trim() || 'incremental',
+    displayName: String(options.displayName || '').trim() || systemKey,
+    openapiSourceRefs: mergeStringMapRefs(
+      stringMapBinding(bindings, 'system.openapiSourceRefs'),
+      options.openapiSourceRefs,
+      {}
+    ),
+    connectionRefs: mergeStringMapRefs(
+      stringMapBinding(bindings, 'system.connectionRefs'),
+      options.connectionRefs,
+      { token: `kv://${systemKey}/token` }
+    )
+  };
+}
+
+function buildDiscoveryBidDraft(options, inputs) {
+  const {
+    systemKey,
+    groups,
+    bindings,
+    syncMode,
+    displayName,
+    openapiSourceRefs,
+    connectionRefs
+  } = inputs;
+  const draft = {
+    schemaName: 'aifabrix.builder.integrationDefinition',
+    schemaVersion: '1.0.0',
+    definitionId:
+      String(options.definitionId || '').trim() || crypto.randomUUID(),
+    meta: {
+      suiteRunId: 'pending',
+      producedAt: new Date().toISOString(),
+      btAssistantKey: options.btAssistantKey || 'ra-business-transformation',
+      knowledgePackRefs: Array.isArray(options.knowledgePackRefs)
+        ? options.knowledgePackRefs
+        : ['role-assistant/ra-business-transformation/knowledge/']
+    },
+    packageIdentity: {
+      systemKey,
+      packageVersion: String(options.packageVersion || '0.1.0'),
+      displayName
+    },
+    system: {
+      key: systemKey,
+      displayName,
+      systemKind: String(options.systemKind || 'crm'),
+      type: 'openapi',
+      connectionRefs
+    },
+    datasources: buildDatasources(bindings, groups, openapiSourceRefs),
+    relationships: buildRelationships(bindings),
+    sync: { mode: syncMode, datasources: groups },
+    capabilities: buildCapabilities(groups, bindings),
+    authority: { writeRequiresUserAuthority: true },
+    acceptance: { gates: DEFAULT_GATES }
+  };
+  return draft;
+}
+
+function bidFromDiscovery(options = {}) {
+  const inputs = resolveBidInputs(options);
+  const draft = buildDiscoveryBidDraft(options, inputs);
+  return emitSuiteBid(draft, {
+    suiteRunId: inputs.suiteRunId,
+    btAssistantKey: draft.meta.btAssistantKey,
+    answers: options.answers || inputs.bindings
+  });
+}
+
+module.exports = {
+  bidFromDiscovery,
+  discoveryBindingsFromAnswers,
+  discoveryReadyForBid,
+  unwrapBinding
+};

package/lib/integration-definition/hash.js

@@ -0,0 +1,37 @@
+/**
+ * BID definitionHash helpers.
+ * @fileoverview SHA-256 hash for aifabrix.builder.integrationDefinition
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+const { canonicalJsonString, bidBodyWithoutHash } = require('./canonical-json');
+
+/**
+ * Compute definitionHash for a BID object (excludes definitionHash field).
+ * @param {Record<string, unknown>} bid
+ * @returns {string} sha256:<hex>
+ */
+function computeDefinitionHash(bid) {
+  const body = bidBodyWithoutHash(bid);
+  const digest = crypto.createHash('sha256').update(canonicalJsonString(body), 'utf8').digest('hex');
+  return `sha256:${digest}`;
+}
+
+/**
+ * Attach or refresh definitionHash on a BID object (mutates and returns).
+ * @param {Record<string, unknown>} bid
+ * @returns {Record<string, unknown>}
+ */
+function withDefinitionHash(bid) {
+  const next = { ...bid };
+  delete next.definitionHash;
+  next.definitionHash = computeDefinitionHash(next);
+  return next;
+}
+
+module.exports = {
+  computeDefinitionHash,
+  withDefinitionHash
+};

package/lib/integration-definition/index.js

@@ -0,0 +1,37 @@
+/**
+ * Builder Integration Definition (BID) public API.
+ * @fileoverview aifabrix.builder.integrationDefinition v1.0.0
+ */
+
+'use strict';
+
+const { applyIntegrationDefinition, STAMP_FILE } = require('./apply');
+const { computeDefinitionHash, withDefinitionHash } = require('./hash');
+const { emitSuiteBid, fingerprintAnswers } = require('./emit-suite-bid');
+const {
+  bidFromDiscovery,
+  discoveryBindingsFromAnswers,
+  discoveryReadyForBid
+} = require('./from-discovery');
+const {
+  validateIntegrationDefinition,
+  resetIntegrationDefinitionValidator,
+  INTEGRATION_DEFINITION_SCHEMA_NAME,
+  INTEGRATION_DEFINITION_SCHEMA_VERSION
+} = require('./validate');
+
+module.exports = {
+  applyIntegrationDefinition,
+  computeDefinitionHash,
+  withDefinitionHash,
+  emitSuiteBid,
+  fingerprintAnswers,
+  bidFromDiscovery,
+  discoveryBindingsFromAnswers,
+  discoveryReadyForBid,
+  validateIntegrationDefinition,
+  resetIntegrationDefinitionValidator,
+  INTEGRATION_DEFINITION_SCHEMA_NAME,
+  INTEGRATION_DEFINITION_SCHEMA_VERSION,
+  STAMP_FILE
+};

package/lib/integration-definition/openapi-enrichment/hubspot-crm-companies.json

@@ -0,0 +1,205 @@
+{
+  "openapi": "3.0.1",
+  "info": {
+    "title": "CRM Companies (enrichment fixture)",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/crm/v3/objects/companies": {
+      "get": {
+        "operationId": "get-/crm/v3/objects/companies",
+        "summary": "List companies",
+        "parameters": [
+          {
+            "name": "limit",
+            "in": "query",
+            "schema": { "type": "integer" }
+          },
+          {
+            "name": "after",
+            "in": "query",
+            "schema": { "type": "string" }
+          },
+          {
+            "name": "properties",
+            "in": "query",
+            "schema": { "type": "string" }
+          },
+          {
+            "name": "associations",
+            "in": "query",
+            "schema": { "type": "string" }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Results use paging.next.after as the cursor for the next page.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "results": {
+                      "type": "array",
+                      "items": { "$ref": "#/components/schemas/Company" }
+                    },
+                    "paging": {
+                      "type": "object",
+                      "properties": {
+                        "next": {
+                          "type": "object",
+                          "properties": {
+                            "after": { "type": "string" }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "operationId": "post-/crm/v3/objects/companies",
+        "summary": "Create company",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "properties": {
+                    "type": "object",
+                    "additionalProperties": { "type": "string" }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Created",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/Company" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/crm/v3/objects/companies/{companyId}": {
+      "get": {
+        "operationId": "get-/crm/v3/objects/companies/{companyId}",
+        "summary": "Get company",
+        "parameters": [
+          {
+            "name": "companyId",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string" }
+          },
+          {
+            "name": "properties",
+            "in": "query",
+            "schema": { "type": "string" }
+          },
+          {
+            "name": "associations",
+            "in": "query",
+            "schema": { "type": "string" }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/Company" }
+              }
+            }
+          }
+        }
+      },
+      "patch": {
+        "operationId": "patch-/crm/v3/objects/companies/{companyId}",
+        "summary": "Update company",
+        "parameters": [
+          {
+            "name": "companyId",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string" }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "properties": {
+                    "type": "object",
+                    "additionalProperties": { "type": "string" }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/Company" }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "operationId": "delete-/crm/v3/objects/companies/{companyId}",
+        "summary": "Delete company",
+        "parameters": [
+          {
+            "name": "companyId",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string" }
+          }
+        ],
+        "responses": {
+          "204": { "description": "No Content" }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Company": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string" },
+          "properties": {
+            "type": "object",
+            "properties": {
+              "name": { "type": "string" },
+              "country": { "type": "string" }
+            },
+            "additionalProperties": { "type": "string" }
+          },
+          "associations": {
+            "type": "object",
+            "additionalProperties": true
+          }
+        }
+      }
+    }
+  }
+}

package/lib/integration-definition/resource-type-catalog.js

@@ -0,0 +1,59 @@
+/**
+ * Offline resource-type catalog keys for BID product rules (same SSOT as help topic).
+ * @fileoverview Active keys from docs/builder-help/resource-type-catalog.json
+ */
+
+'use strict';
+
+const { loadResourceTypeCatalog } = require('../programmatic/builder-help-governance');
+
+/** @type {Set<string>|null} */
+let cachedActiveKeys = null;
+
+/**
+ * @returns {Set<string>}
+ */
+function getActiveResourceTypeKeys() {
+  if (cachedActiveKeys) {
+    return cachedActiveKeys;
+  }
+  const catalog = loadResourceTypeCatalog();
+  const keys = new Set();
+  for (const row of catalog.resourceTypes || []) {
+    if (!row || typeof row !== 'object') {
+      continue;
+    }
+    const key = String(row.key || '').trim();
+    const status = String(row.status || 'active').trim().toLowerCase();
+    if (key && status === 'active') {
+      keys.add(key);
+    }
+  }
+  cachedActiveKeys = keys;
+  return cachedActiveKeys;
+}
+
+/**
+ * Reset cache (tests).
+ */
+function resetResourceTypeCatalogCache() {
+  cachedActiveKeys = null;
+}
+
+/**
+ * @param {string} key
+ * @returns {boolean}
+ */
+function isActiveResourceTypeKey(key) {
+  const normalized = String(key || '').trim();
+  if (!normalized) {
+    return false;
+  }
+  return getActiveResourceTypeKeys().has(normalized);
+}
+
+module.exports = {
+  getActiveResourceTypeKeys,
+  isActiveResourceTypeKey,
+  resetResourceTypeCatalogCache
+};