@aifabrix/builder 2.60.0 → 2.62.0

package/docs/builder-help/resource-type-catalog.json

@@ -0,0 +1,402 @@
+{
+  "schemaVersion": "1.0.0",
+  "source": "baseline-resourcetypes.json",
+  "lastSynced": "2026-08-22",
+  "minimumSystemKeys": [
+    "customer",
+    "contact",
+    "employee",
+    "project",
+    "task",
+    "meeting",
+    "document",
+    "approval",
+    "contract",
+    "invoice",
+    "deal",
+    "ticket",
+    "message",
+    "channel",
+    "workspace",
+    "knowledge",
+    "event"
+  ],
+  "resourceTypes": [
+    {
+      "key": "approval",
+      "displayName": "Approval",
+      "description": "Approval request, decision, review process, or authorization workflow item.",
+      "category": "governance",
+      "defaultRiskLevel": "high",
+      "status": "active"
+    },
+    {
+      "key": "asset",
+      "displayName": "Asset",
+      "description": "Managed physical, digital, financial, or operational business asset.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "attachment",
+      "displayName": "Attachment",
+      "description": "File attachment, uploaded content, supporting artifact, or binary business asset.",
+      "category": "content",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "balance",
+      "displayName": "Balance",
+      "description": "Leave, absence, or accrued time-off balance for a person.",
+      "category": "people",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "budget",
+      "displayName": "Budget",
+      "description": "Budget allocation, financial plan, spending target, or funding record.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "case",
+      "displayName": "Case",
+      "description": "Support request, incident, issue, service ticket, or customer problem record.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "channel",
+      "displayName": "Channel",
+      "description": "Collaboration channel, team space, or communication group.",
+      "category": "collaboration",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "contact",
+      "displayName": "Contact",
+      "description": "Individual person associated with a customer, supplier, partner, or other business entity.",
+      "category": "people",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "contract",
+      "displayName": "Contract",
+      "description": "Formal agreement, legal commitment, or business contract between parties.",
+      "category": "governance",
+      "defaultRiskLevel": "high",
+      "status": "active"
+    },
+    {
+      "key": "customer",
+      "displayName": "Customer",
+      "description": "Organization, account, client, or business entity that purchases, receives, or is associated with products or services.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "deal",
+      "displayName": "Deal",
+      "description": "Commercial deal, sales opportunity, or revenue pursuit in the sales pipeline.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "decision",
+      "displayName": "Decision",
+      "description": "Business decision, resolution, approved action, or governance outcome.",
+      "category": "governance",
+      "defaultRiskLevel": "high",
+      "status": "active"
+    },
+    {
+      "key": "department",
+      "displayName": "Department",
+      "description": "Organizational unit, business function, or department.",
+      "category": "people",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "document",
+      "displayName": "Document",
+      "description": "Business document, file, presentation, contract, or knowledge artifact.",
+      "category": "content",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "folder",
+      "displayName": "Folder",
+      "description": "Container or directory for documents and files.",
+      "category": "content",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "hr-report",
+      "displayName": "HR Report",
+      "description": "People and HR report, workforce analytics rollup, or period summary. Distinct from Document.",
+      "category": "people",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "email",
+      "displayName": "Email",
+      "description": "Email message, conversation, or business communication record.",
+      "category": "communication",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "employee",
+      "displayName": "Employee",
+      "description": "Internal worker, staff member, contractor, or workforce resource.",
+      "category": "people",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "event",
+      "displayName": "Event",
+      "description": "Business event, calendar event, milestone, or scheduled activity.",
+      "category": "communication",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "expense",
+      "displayName": "Expense",
+      "description": "Expense claim, cost record, reimbursement, or financial expenditure.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "finance-report",
+      "displayName": "Finance Report",
+      "description": "Financial report, analytics rollup, or period summary over finance records. Distinct from Document.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "invoice",
+      "displayName": "Invoice",
+      "description": "Billing document, payment request, or financial charge record.",
+      "category": "business",
+      "defaultRiskLevel": "high",
+      "status": "active"
+    },
+    {
+      "key": "knowledge",
+      "displayName": "Knowledge",
+      "description": "Knowledge article, FAQ, guidance, procedure, or reference content.",
+      "category": "content",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "llm",
+      "displayName": "LLM",
+      "description": "Large language model provider capability surface for chat completion and embedding operations.",
+      "category": "content",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "meeting",
+      "displayName": "Meeting",
+      "description": "Scheduled interaction, discussion, workshop, or business event involving participants.",
+      "category": "collaboration",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "message",
+      "displayName": "Message",
+      "description": "Chat, Teams message, discussion, or conversational communication record.",
+      "category": "communication",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "note",
+      "displayName": "Note",
+      "description": "Business note, comment, activity note, CRM note, or user-generated contextual information.",
+      "category": "content",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "objective",
+      "displayName": "Objective",
+      "description": "Strategic goal, business objective, target outcome, or organizational priority.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "opportunity",
+      "displayName": "Opportunity",
+      "description": "Potential sales, revenue, business development, or commercial opportunity.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "operations-report",
+      "displayName": "Operations Report",
+      "description": "Operations report, operational analytics rollup, or period summary. Distinct from Document.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "order",
+      "displayName": "Order",
+      "description": "Customer order, purchase request, sales order, or transaction record.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "organization",
+      "displayName": "Organization",
+      "description": "Internal organizational entity, subsidiary, legal entity, or business unit.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "owner",
+      "displayName": "Owner",
+      "description": "Individual user or account responsible for ownership, stewardship, or accountability of a record or business object.",
+      "category": "people",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "partner",
+      "displayName": "Partner",
+      "description": "External organization participating in business collaboration, delivery, sales, or strategic activities.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "payment",
+      "displayName": "Payment",
+      "description": "Payment transaction, settlement, receipt, or financial payment record.",
+      "category": "business",
+      "defaultRiskLevel": "high",
+      "status": "active"
+    },
+    {
+      "key": "policy",
+      "displayName": "Policy",
+      "description": "Policy, guideline, compliance rule, or governance document.",
+      "category": "governance",
+      "defaultRiskLevel": "high",
+      "status": "active"
+    },
+    {
+      "key": "position",
+      "displayName": "Position",
+      "description": "Job role, position, title, or workforce assignment.",
+      "category": "people",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "product",
+      "displayName": "Product",
+      "description": "Product, service offering, subscription, or item available for sale or delivery.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "project",
+      "displayName": "Project",
+      "description": "Temporary initiative or work effort with defined objectives, timelines, resources, and deliverables.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "repository",
+      "displayName": "Repository",
+      "description": "Version-controlled source repository for integration manifests, CIP pipelines, and workspace sync.",
+      "category": "content",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "risk",
+      "displayName": "Risk",
+      "description": "Potential business, operational, compliance, security, or financial risk.",
+      "category": "governance",
+      "defaultRiskLevel": "high",
+      "status": "active"
+    },
+    {
+      "key": "sales-report",
+      "displayName": "Sales Report",
+      "description": "Sales report, pipeline analytics rollup, or commercial period summary. Distinct from Document.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "supplier",
+      "displayName": "Supplier",
+      "description": "Organization providing products, services, materials, or external resources.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "task",
+      "displayName": "Task",
+      "description": "Work item, action, assignment, or activity that can be completed by an individual or team.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "template",
+      "displayName": "Template",
+      "description": "Integration workspace template used to materialize local Builder workspaces.",
+      "category": "content",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "ticket",
+      "displayName": "Ticket",
+      "description": "Support ticket, service request, incident, or customer issue record.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "workspace",
+      "displayName": "Workspace",
+      "description": "Shared workspace, site, or collaboration area for teams and content.",
+      "category": "collaboration",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    }
+  ]
+}

package/lib/api/applications.api.js

@@ -202,6 +202,26 @@ async function getApplicationStatus(controllerUrl, envKey, appKey, authConfig) {
   );
 }
 
+/**
+ * Update the authenticated application's own runtime status and URLs.
+ * POST /api/v1/environments/{envKey}/applications/self/status
+ * @requiresPermission {Controller} Application client token
+ * @async
+ * @function updateApplicationSelfStatus
+ * @param {string} controllerUrl - Controller base URL
+ * @param {string} envKey - Environment key
+ * @param {Object} authConfig - Client-token authentication configuration
+ * @param {Object} statusData - Runtime status payload
+ * @returns {Promise<Object>} Updated application response
+ * @throws {Error} If request fails
+ */
+async function updateApplicationSelfStatus(controllerUrl, envKey, authConfig, statusData) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.post(`/api/v1/environments/${envKey}/applications/self/status`, {
+    body: statusData
+  });
+}
+
 module.exports = {
   listApplications,
   createApplication,
@@ -211,6 +231,6 @@ module.exports = {
   registerApplication,
   bootstrapApplication,
   rotateApplicationSecret,
-  getApplicationStatus
+  getApplicationStatus,
+  updateApplicationSelfStatus
 };
-

package/lib/api/bootstrap-snapshot.api.js

@@ -0,0 +1,115 @@
+/**
+ * `POST /api/v1/auth/bootstrap` — an application's resolved configuration (Miso 257.0).
+ *
+ * This is what removes the drift. Miso generates an environment's variables through the same
+ * catalog and reconciliation it uses for Azure, holds them in whichever store the deployment
+ * calls for — Key Vault, or encrypted in `Environment.configuration` for a local install —
+ * and hands back the resolved set. Builder stops generating values and stops deriving secret
+ * names, so there is one generator, one naming rule and one record.
+ *
+ * **The caller is the application, not the operator.** A client id and secret are provisioned
+ * with the application itself, so there is no chicken-and-egg: they exchange for a client
+ * token at `/api/v1/auth/token`, which needs no prior authentication. The token carries the
+ * application and environment, which means the snapshot is server-assigned — an application
+ * cannot ask for another application's configuration, because it cannot mint a token naming
+ * one. Builder passes credentials it already holds and is told what that application gets.
+ *
+ * **`success === true` is load-bearing.** Miso writes this envelope out explicitly rather than
+ * through the helper every neighbouring route uses, because that helper omits `success` and a
+ * consumer treats its absence as a protocol error. Checking it here keeps Builder honest with
+ * the same contract the SDK enforces.
+ *
+ * @fileoverview Fetch an application's bootstrap configuration snapshot from Miso
+ */
+
+'use strict';
+
+/** The only protocol version the endpoint accepts. */
+const BOOTSTRAP_PROTOCOL_VERSION = 1;
+
+/**
+ * @param {string} controllerUrl - Controller base URL
+ * @returns {string} Without a trailing slash
+ */
+function normalizeControllerUrl(controllerUrl) {
+  return String(controllerUrl || '').trim().replace(/\/+$/, '');
+}
+
+/**
+ * Exchange an application's client credentials for a client token.
+ *
+ * @async
+ * @param {string} controllerUrl - Controller base URL
+ * @param {{ clientId: string, clientSecret: string }} credentials - Application credentials
+ * @param {Function} [makeApiCall] - Injected transport
+ * @returns {Promise<string>} The client token
+ * @throws {Error} When the exchange fails or returns no token
+ */
+async function exchangeClientToken(controllerUrl, credentials, makeApiCall) {
+  const call = makeApiCall || require('../utils/api').makeApiCall;
+  const response = await call(`${normalizeControllerUrl(controllerUrl)}/api/v1/auth/token`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-client-id': credentials.clientId,
+      'x-client-secret': credentials.clientSecret
+    }
+  });
+  if (!response || response.success !== true) {
+    throw new Error(
+      `Could not authenticate as ${credentials.clientId}: ${(response && response.error) || 'request failed'}`
+    );
+  }
+  const data = response.data || {};
+  const token = data.token || data.data?.token || data.accessToken;
+  if (!token) {
+    // Names the client, never the secret, because this message reaches the terminal.
+    throw new Error(`Authentication for ${credentials.clientId} returned no token`);
+  }
+  return token;
+}
+
+/**
+ * Fetch an application's resolved configuration for its environment.
+ *
+ * @async
+ * @param {string} controllerUrl - Controller base URL
+ * @param {{ clientId: string, clientSecret: string }} credentials - Application credentials
+ * @param {Object} [deps] - Injected collaborators
+ * @returns {Promise<{ configuration: Object, context: Object, issuedAt: string }>} The snapshot
+ * @throws {Error} When authentication fails, or the snapshot is refused or malformed
+ */
+async function fetchBootstrapSnapshot(controllerUrl, credentials, deps = {}) {
+  if (!credentials || !credentials.clientId || !credentials.clientSecret) {
+    throw new Error('Client id and secret are required to fetch a bootstrap snapshot');
+  }
+  const call = deps.makeApiCall || require('../utils/api').makeApiCall;
+  const token = await exchangeClientToken(controllerUrl, credentials, call);
+  const response = await call(`${normalizeControllerUrl(controllerUrl)}/api/v1/auth/bootstrap`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${token}`
+    },
+    body: JSON.stringify({ protocolVersion: BOOTSTRAP_PROTOCOL_VERSION })
+  });
+  if (!response || response.success !== true) {
+    throw new Error(
+      `Miso refused a configuration snapshot for ${credentials.clientId}: ` +
+        `${(response && response.error) || 'request failed'}`
+    );
+  }
+  const snapshot = response.data && response.data.data ? response.data.data : response.data;
+  if (!snapshot || typeof snapshot.configuration !== 'object' || snapshot.configuration === null) {
+    throw new Error(
+      `Miso returned a snapshot with no configuration for ${credentials.clientId}`
+    );
+  }
+  return snapshot;
+}
+
+module.exports = {
+  BOOTSTRAP_PROTOCOL_VERSION,
+  exchangeClientToken,
+  fetchBootstrapSnapshot
+};

package/lib/api/configuration.api.js

@@ -0,0 +1,131 @@
+/**
+ * Parameter-backed installation configuration API.
+ *
+ * @fileoverview Read safe configuration metadata from Miso Controller
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { ApiClient } = require('./index');
+
+const PAGE_SIZE = 100;
+
+/**
+ * @param {string} envKey - Environment key
+ * @returns {string} Configuration collection endpoint
+ */
+function configurationEndpoint(envKey) {
+  return `/api/v1/environments/${encodeURIComponent(envKey)}/configuration`;
+}
+
+/**
+ * @param {Object} meta - Pagination metadata
+ * @param {number} requestedPage - Requested one-based page
+ * @param {boolean} hasRows - Whether the page contains rows
+ * @returns {number} Validated total page count
+ */
+function validatePageMeta(meta, requestedPage, hasRows) {
+  const currentPage = Number(meta && meta.currentPage);
+  const totalPages = Number(meta && meta.totalPages);
+  if (!Number.isInteger(currentPage) || currentPage !== requestedPage) {
+    throw new Error('Configuration list response has invalid pagination metadata');
+  }
+  if (!Number.isInteger(totalPages) || totalPages < 0 || (hasRows && totalPages === 0)) {
+    throw new Error('Configuration list response has invalid pagination metadata');
+  }
+  return totalPages;
+}
+
+/**
+ * @param {Object} response - API response
+ * @param {number} requestedPage - Requested one-based page
+ * @returns {{ rows: Object[], totalPages: number }} Validated page
+ */
+function readConfigurationPage(response, requestedPage) {
+  if (response && response.success === false) {
+    throw new Error(response.formattedError || response.error || 'Configuration list request failed');
+  }
+  const body = response && response.data !== undefined ? response.data : response;
+  if (!body || !Array.isArray(body.data) || !body.meta) {
+    throw new Error('Configuration list response is not a paginated result');
+  }
+  const totalPages = validatePageMeta(body.meta, requestedPage, body.data.length > 0);
+  return { rows: body.data, totalPages };
+}
+
+/**
+ * List configuration declarations, optionally for one exact owner.
+ *
+ * GET /api/v1/environments/{envKey}/configuration
+ * @requiresPermission {Controller} controller:monitor or admin:read
+ * @async
+ * @function listEnvironmentConfiguration
+ * @param {string} controllerUrl - Controller base URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {string} envKey - Environment key
+ * @param {string} [application] - Exact owning application key
+ * @param {Object} [options] - Optional safe search
+ * @param {string} [options.search] - Partial key/name search
+ * @returns {Promise<Object[]>} Safe configuration metadata rows
+ */
+async function listEnvironmentConfiguration(controllerUrl, authConfig, envKey, application, options = {}) {
+  if (!controllerUrl || typeof controllerUrl !== 'string') {
+    throw new Error('controllerUrl is required and must be a string');
+  }
+  const environment = typeof envKey === 'string' ? envKey.trim() : '';
+  const owner = typeof application === 'string' ? application.trim() : '';
+  if (!environment) {
+    throw new Error('envKey is required and must be a string');
+  }
+  const client = new ApiClient(controllerUrl, authConfig);
+  const common = {
+    pageSize: PAGE_SIZE,
+    sort: owner ? 'key' : 'application'
+  };
+  if (owner) common.application = owner;
+  if (options.search) common.search = String(options.search).trim();
+  const rows = [];
+  for (let page = 1;; page += 1) {
+    const response = await client.get(configurationEndpoint(environment), {
+      params: { ...common, page }
+    });
+    const result = readConfigurationPage(response, page);
+    rows.push(...result.rows);
+    if (page >= result.totalPages) return rows;
+  }
+}
+
+/**
+ * Update one authoritatively non-sensitive configuration declaration.
+ * @param {string} controllerUrl - Controller base URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {string} envKey - Environment key
+ * @param {string} application - Exact application owner
+ * @param {string} key - Configuration declaration key
+ * @param {Object} update - Value and concurrency revision
+ * @param {string} update.value - Non-sensitive value
+ * @param {string} update.revision - Opaque revision from the configuration list
+ * @returns {Promise<Object>} Safe updated metadata
+ */
+async function putEnvironmentConfiguration(
+  controllerUrl, authConfig, envKey, application, key, update
+) {
+  const value = update && update.value;
+  const revision = update && update.revision;
+  const required = { controllerUrl, envKey, application, key, revision };
+  for (const [name, input] of Object.entries(required)) {
+    if (!input || typeof input !== 'string') throw new Error(`${name} is required`);
+  }
+  if (typeof value !== 'string') throw new Error('value must be a string');
+  const client = new ApiClient(controllerUrl, authConfig);
+  const endpoint = `${configurationEndpoint(envKey)}/${encodeURIComponent(application)}/` +
+    encodeURIComponent(key);
+  return await client.put(endpoint, { body: { value }, headers: { 'If-Match': revision } });
+}
+
+module.exports = {
+  listEnvironmentConfiguration,
+  putEnvironmentConfiguration
+};