@aifabrix/builder 2.52.1 → 2.53.1

package/lib/programmatic/help-content/connected-system-ui.md

@@ -0,0 +1,70 @@
+# Connected Systems UI navigation
+
+Use this topic after validate, test, test-integration, and upload succeed without resolved integration secrets in Builder API scope.
+
+## Post-upload authentication handoff
+
+Upload publishes the external system manifest. The user adds **live secrets only** in the dataplane Connected Systems Authentication tab — not by pasting tokens into Builder API or workspace files.
+
+Authentication is declared on the **external system** manifest (`authentications[]` with usage slots, or legacy `authentication` normalized by repair), not on individual datasource manifests. Datasources inherit linked system credentials at sync and CIP runtime.
+
+### Variables vs secrets (manifest split)
+
+| Manifest path | When to set | After upload |
+| --- | --- | --- |
+| `authentication.credential.variables` | During manifest editing (Builder API) | Published and **pre-filled** in Authentication UI — user does not re-enter |
+| `authentication.credential.security` | kv:// placeholders in manifest only | User adds **live secret values** in Authentication UI (for example token, apiKey, clientSecret) |
+
+**Enterprise-ready pattern:** put baseUrl, headerName, tokenUrl, prefix, testEndpoint, and similar non-secrets in `variables` before upload. After upload, the user opens Authentication and adds only the token or other required secret.
+
+Before prompting the user:
+
+1. Read `authentications[]` usage slots from the published system manifest (prefer over legacy `authentication`).
+2. For each slot, read `authType` and `credential.method` when applicable.
+3. Confirm `variables` are already complete in the manifest — do not ask the user to supply them again.
+4. Tell the user which **secret keys only** they must add in the UI (`requiredSecretKeys`).
+5. When webhook or syncBridge is enabled, also hand off to datasource **Sync** tab (`tab=sync`) for activation guide URLs.
+
+## Authentication modes (authType)
+
+| authType | Where in manifest | User action in UI |
+| --- | --- | --- |
+| `credential` | `authentication.credential` | Add secret values only; variables already pre-filled |
+| `apiProvider` | `authentication.apiProvider.apiProviderKey` | Link the Miso API Provider — no local vendor secrets |
+| `none` | `authentication.authType` only | No credential handoff unless live tests fail for other reasons |
+
+## Credential methods (when authType is credential)
+
+Methods come from `external-system.schema.json` (`authentication.credential.method`). User adds **secrets only** after upload:
+
+| method | User adds in UI (secrets only) | Already in manifest variables |
+| --- | --- | --- |
+| `oauth2` | clientSecret (clientId if empty) | baseUrl, tokenUrl, grantType, scope |
+| `aad` | clientSecret (clientId if empty) | baseUrl, tokenUrl, tenantId, grantType |
+| `apikey` | apiKey (token) | baseUrl, headerName, prefix, testEndpoint |
+| `bearerToken` | token | baseUrl, headerName, prefix, testEndpoint |
+| `basic` | username, password | baseUrl, testEndpoint |
+| `queryParam` | paramValue | baseUrl, paramName, testEndpoint |
+| `oidc` | any remaining OIDC secrets shown | openIdConfigUrl, clientId |
+| `hmac` | signingSecret | algorithm, signature headers |
+| `none` | none | — |
+
+Use optional query params `authType` and `credentialMethod` on this topic to get `manifestHandoff.promptHints` tailored to the manifest.
+
+## URL structure
+
+Combine `{dataplanePublicBase}` with a relative path:
+
+- System: `/connected-systems/{systemKey}?tab=authentication`
+- Datasource: `/connected-systems/{systemKey}/datasources/{datasourceKey}?tab={tab}`
+
+Omit `?tab=` for the default Overview tab on each level. Tab values are case-insensitive; aliases are listed in the structured `systemTabs` and `datasourceTabs` arrays on this topic.
+
+## Typical tabs after publish
+
+| Goal | System tab value |
+| --- | --- |
+| Add token / secrets | `authentication` |
+| Review datasources | `datasources` or `business-entities` |
+| Sync / webhook activation | Open datasource path with `tab=sync` |
+| Execution logs | Open datasource path with `tab=logs` |

package/lib/programmatic/help-content/dimensions-guide.md

@@ -0,0 +1,23 @@
+# Dimensions and ABAC grounding
+
+Dimensions are governance attributes on datasource manifests. They map normalized metadata paths to ABAC policies, protection rules, and subscription filters.
+
+## When dimensions apply
+
+Use dimensions on recordStorage, documentStorage, and serviceContract datasources. entityType none orchestration datasources must not declare fieldMappings.dimensions.
+
+## Authoring rules
+
+Declare dimensions at fieldMappings.dimensions with values pointing to metadata paths, such as metadata.country or metadata.owner. Match metadataSchema properties so protection and sync can evaluate grants.
+
+Ask the user for business context before patching datasource.dimensions. Common dimensions include country, region, department, owner, sensitivity, siteId, and lifecycleStage.
+
+## Challenge patterns
+
+If a datasource uses resourceType customer but has no country or region dimension, ask whether geographic protection is required. If document libraries lack owner or sensitivity, ask before enabling protection.
+
+When foreignKeys link a child datasource to a parent, confirm whether dimensions should inherit from the parent record metadata.
+
+## Related sections
+
+datasource.dimensions, datasource.metadata, datasource.foreignKeys, datasource.governance, system.subscriptions

package/lib/programmatic/help-content/enterprise-sync-fabrix.md

@@ -0,0 +1,123 @@
+# Enterprise Synchronization Fabrix
+
+Webhook change signals and syncBridge propagation connect vendor events to governed CIP sync without a separate webhook engine.
+
+## Overview
+
+| Concept | Role |
+| --- | --- |
+| **webhook** | Inbound vendor POST trigger only — records WebhookDelivery and may create SyncIntent |
+| **syncBridge** | Resource-type propagation mode (`disabled`, `master`, `bidirectional`) across datasources |
+| **CIP get** | Business data always loaded via existing get operations and fieldMappings |
+
+Webhook does not carry full record payloads for sync. The coordinator runs CIP get after a valid trigger.
+
+## authentications[] usage slots
+
+Declare multiple authentication slots on the **external system** manifest (`authentications[]`), not on datasource files:
+
+| usage | Purpose |
+| --- | --- |
+| `api` | Outbound vendor API calls (default slot) |
+| `webhookInbound` | Validates inbound vendor webhook signatures or API keys |
+| `syncExecution` | Credentials for syncBridge propagation CIP calls |
+
+Example structure (YAML):
+
+```yaml
+authentications:
+  - key: default
+    usage: api
+    authType: credential
+    credential:
+      method: apikey
+      security:
+        apiKey: kv://my-app/apiKey
+  - key: webhookInbound
+    usage: webhookInbound
+    authType: credential
+    credential:
+      method: hmac
+      security:
+        signingSecret: kv://my-app/webhookSigningSecret
+  - key: syncExecution
+    usage: syncExecution
+    authType: credential
+    credential:
+      method: apikey
+      security:
+        apiKey: kv://my-app/syncApiKey
+```
+
+Repair helpers:
+
+- `aifabrix repair <systemKey>` — normalize legacy `authentication` to `authentications[]`
+- `aifabrix repair <systemKey> --auth apikey` — repair the default **api** slot only
+- `aifabrix repair <systemKey> --auth-webhook` — add webhookInbound slot from template
+- `aifabrix repair <systemKey> --auth-sync` — add syncExecution slot from template
+
+## Datasource webhook block
+
+Minimal enabled configuration on a datasource manifest:
+
+```yaml
+webhook:
+  enabled: true
+  endpointMode: datasource
+  events:
+    - company.updated
+  idPath: $.objectId
+  vendorDeliveryIdPath: $.deliveryId
+```
+
+| Field | Notes |
+| --- | --- |
+| `endpointMode` | `system`, `datasource`, or `event` — controls generated POST path |
+| `events` | Vendor event names that create SyncIntent |
+| `idPath` | JSONPath to vendor object id in payload |
+| `eventTypePath` | Required when multiple `events` and mode is not `event` |
+| `vendorDeliveryIdPath` | Payload JSONPath for idempotent dedupe |
+
+Generated receiver paths (first-party dataplane API):
+
+- System: `POST /api/v1/webhooks/{systemKey}`
+- Datasource: `POST /api/v1/webhooks/{systemKey}/{datasourceKey}`
+- Event: `POST /api/v1/webhooks/{systemKey}/{datasourceKey}/{eventKey}`
+
+Signature and API-key **headers** belong on the webhookInbound credential only — not on the datasource webhook block.
+
+## syncBridge modes
+
+| Mode | Behavior |
+| --- | --- |
+| `disabled` | Default — no propagation |
+| `master` | Authoritative source for a resourceType; receives webhook triggers |
+| `bidirectional` | Participates in propagation; exactly one master per resourceType |
+
+When syncBridge is not `disabled`, ensure `metadataSchema.properties.externalId` exists for routing.
+
+## Activation workflow
+
+1. Edit system + datasource manifests (authentications[], webhook, syncBridge).
+2. Run `aifabrix validate <app>` and `aifabrix repair <systemKey>` as needed.
+3. Run `aifabrix upload <app>` to publish.
+4. Open Connected Systems **Authentication** — add live secrets for each usage slot.
+5. Open datasource **Sync** tab — use **How to activate webhook** for operator copy/paste URLs.
+6. Run certification / test-e2e after credentials are live.
+
+UI displays webhook and syncBridge config as **read-only**; manifest and API remain SSOT.
+
+## Validate and certification
+
+- `aifabrix validate <app>` — schema + cross-field rules for webhook and syncBridge
+- Dataplane certification readiness — webhookInbound auth, idPath, syncBridge master uniqueness
+
+## Logs and troubleshooting
+
+After webhook POST, inspect datasource **Logs** tab for CIP execution traces. SyncIntent and coordinator outcomes appear in execution audit — no separate webhook log API.
+
+## Related help topics
+
+- `connectedSystemUi` — post-upload Authentication and Sync tab URLs
+- `workflow` — validate → upload → handoff ladder
+- `schemaCatalog` — manifest property reference

package/lib/programmatic/help-content/overview.md

@@ -0,0 +1,25 @@
+# Builder manifest editing overview
+
+The Builder API exposes governed manifest sections for external integrations. Agents read one section at a time, resolve missing inputs with the user, patch with explicit intent, repair derived sections, then validate and test the workspace draft.
+
+## Purpose
+
+Help agents and MCP tools bootstrap without guessing manifest structure. Structured topics describe section keys, dependency order, repair hooks, workflow rules, golden patterns, and evidence expectations.
+
+## Core concepts
+
+### Governed sections
+
+Manifests split into section keys for the external system and each datasource. Each section has schema fragments, mutability rules, and optional repair hooks.
+
+### Section quality
+
+Every section read returns a quality score, missing-input questions, blocking issues, and recommended next actions. Required missing inputs must be collected from the user before patching.
+
+### Dependency graph
+
+Some sections derive from others. After patching metadata or capabilities, run explicit repair hooks so field mappings, exposure, and RBAC stay aligned.
+
+## Getting started
+
+Call the help endpoint with topic overview, then workflow, then schemaCatalog or sections. Use topic section with a sectionKey when editing a specific area. Use subscriptionGuide and cipOverview for subscriptions and execution depth. Use enterpriseSyncFabrix for webhook change signals and syncBridge propagation. After upload, use connectedSystemUi for shareable dataplane UI paths and post-upload authentication handoff.

package/lib/programmatic/help-content/subscription-guide.md

@@ -0,0 +1,27 @@
+# Subscription and role-scoped generation guide
+
+Subscriptions on the external system manifest bootstrap platform tasks when records change or after publish. They connect certified datasources to role assistants without a separate workflow engine.
+
+## Where subscriptions live
+
+Edit the system.subscriptions section. Each entry has a unique key, optional filter conditions, a task type, and optional runOnPublish flag.
+
+Datasource manifests may declare subscriptionFilter to scope which role keys, system kinds, resource types, or datasource keys participate in generation.
+
+## Normalized record events
+
+Vendor sync and pipeline execution emit normalized events only: record insert, update, delete, and sync completed. Subscription conditions reference generic field paths such as after.status with operators equals, in, changed, exists, and missing.
+
+## Role and resource scoping
+
+Scope resourceTypes to business tokens on the datasource, such as company or deal, not generic placeholders. Match subscription filters to the same resourceType declared on each datasource.
+
+For document libraries linked to CRM records, declare foreignKeys on the library datasource and use a business resourceType on that datasource. Exclude generic document resource types from role assistant subscription filters when business libraries exist.
+
+## Editing workflow
+
+Read system.subscriptions with topic section before patch. Patch with intent describing the business trigger. Validate after edit; subscriptions do not auto-repair derived sections.
+
+## Related sections
+
+system.subscriptions, system.rolesPermissions, datasource.resourceType, datasource.foreignKeys, datasource.governance

package/lib/programmatic/help-content/workflow.md

@@ -0,0 +1,50 @@
+# Manifest development workflow
+
+Follow this loop when editing external integration manifests through the Builder API.
+
+## Normative loop
+
+Read a governed section, resolve required missing inputs with the user, patch with intent, repair derived sections, validate, then test.
+
+## Rules
+
+### Read before patch
+
+Prefer GET when you need quality scores or `missingInputs`. `sectionReadToken` on PATCH is **optional**: when omitted, the server re-reads the section immediately before write (same race window as CLI `patch-section` without `--token`). If you send a token and it is stale, PATCH returns **409** — GET again and retry.
+
+Do not invent primary keys, entity types, or similar values.
+
+### Ask when inputs are missing
+
+When quality reports required missingInputs, ask the user. Do not invent primary keys, entity types, or similar values.
+
+### Patch requires intent
+
+Every write records audit metadata describing why the change was made.
+
+### Repair is explicit
+
+Pass named repair hooks after patches that affect derived sections. The dependency graph defines downstream order.
+
+### No auto-upload
+
+Upload and certification are separate steps after validate and test succeed.
+
+### Post-upload authentication (enterprise handoff)
+
+Validate, test, test-integration, and upload must not depend on resolved integration secrets in Builder API scope. Upload publishes configuration including `authentication.credential.variables` (non-secrets). The user adds live secrets in the dataplane Connected Systems Authentication UI afterward.
+
+After upload succeeds:
+
+1. Read `authentication.authType` and `authentication.credential.method` from the published system manifest (`system.authentication`).
+2. Confirm non-secret `variables` (baseUrl, headerName, tokenUrl, and similar) were set in the manifest — they are pre-filled in the UI after upload.
+3. Fetch help topic `connectedSystemUi` with `systemKey`, optional `authType`, and optional `credentialMethod`.
+4. Ask the user for their dataplane public UI base (origin including `/data`).
+5. Provide the Authentication URL and tell the user to add **only the required secrets** (for example apiKey token for apikey method).
+6. User adds secrets in the UI, then re-runs E2E or live verification.
+
+Do not instruct the user to paste vendor tokens into Builder API or workspace env files when UI authentication is the intended path.
+
+## Typical sequence
+
+Start with datasource metadata for a new entity. Patch with intent describing the vendor payload mapping. Repair fieldMappings, expose, and rbac hooks. Patch openapiOperations when adding write capabilities. Repair again, validate, then test. Upload when ready, then hand off to Connected Systems Authentication per topic `connectedSystemUi`.

package/lib/programmatic/openapi-component-schemas.js

@@ -26,6 +26,7 @@ const { OPENAPI_HELP_RESULT_SCHEMAS } = require('./openapi-help-schemas');
 const RESPONSE_ENVELOPES = [
   ['ListSystemsResponse', 'ListSystemsData'],
   ['CreateSystemResponse', 'CreateSystemData'],
+  ['PersistSuppliedOpenApiResponse', 'PersistSuppliedOpenApiData'],
   ['SystemManifestResponse', 'SystemManifestData'],
   ['DeleteSystemResponse', 'DeleteSystemData'],
   ['WizardRunResponse', 'WizardRunData'],

package/lib/programmatic/openapi-descriptions.js

@@ -22,6 +22,12 @@ const OPERATION_DESCRIPTIONS = Object.freeze({
       'Create an empty integration workspace for a systemKey. Mutating; requires Idempotency-Key on retries.',
     tags: ['workspace']
   },
+  persistSuppliedOpenApi: {
+    summary: 'Persist supplied OpenAPI documents to workspace',
+    description:
+      'Validate Runtime-authorized OpenAPI documents and write them under integration/<systemKey>/openapi/. Does not run wizard or BID apply. Mutating.',
+    tags: ['workspace']
+  },
   getSystemManifest: {
     summary: 'Read workspace manifest summary',
     description: 'Return local workspace metadata and file manifest for one systemKey. Read-only.',

package/lib/programmatic/openapi-envelope-examples.js

@@ -78,6 +78,17 @@ const OPENAPI_ENVELOPE_DATA_EXAMPLES = {
   EmptyResultData: {},
   ListSystemsData: { systems: [{ systemKey: SAMPLE_SYSTEM_KEY, meta: SAMPLE_META }] },
   CreateSystemData: { systemKey: SAMPLE_SYSTEM_KEY, meta: SAMPLE_META },
+  PersistSuppliedOpenApiData: {
+    accepted: [
+      {
+        filename: 'companies.json',
+        path: `integration/${SAMPLE_SYSTEM_KEY}/openapi/companies.json`,
+        digest: 'sha256:demo'
+      }
+    ],
+    rejected: [],
+    workspaceRoot: '/workspace/integration'
+  },
   SystemManifestData: SAMPLE_SYSTEM_MANIFEST,
   DeleteSystemData: { systemKey: SAMPLE_SYSTEM_KEY, deleted: true },
   WizardRunData: { systemKey: SAMPLE_SYSTEM_KEY, status: 'completed' },

package/lib/programmatic/openapi-operation-bindings.js

@@ -81,6 +81,11 @@ const OPERATION_BINDINGS = Object.freeze({
     requestBody: jsonRequestBody('CreateSystemRequest', true),
     successResponse: 'CreateSystemResponse'
   },
+  persistSuppliedOpenApi: {
+    parameters: [SYSTEM_KEY_PARAM],
+    requestBody: jsonRequestBody('PersistSuppliedOpenApiRequest', true),
+    successResponse: 'PersistSuppliedOpenApiResponse'
+  },
   getSystemManifest: {
     parameters: [SYSTEM_KEY_PARAM],
     successResponse: 'SystemManifestResponse'

package/lib/programmatic/openapi-request-schemas.js

@@ -53,6 +53,29 @@ const OPENAPI_REQUEST_SCHEMAS = {
     sync: { type: 'boolean' }
   }),
   CreateSystemRequest: frozenObject({ systemKey: schemaRef('SystemKey') }, ['systemKey']),
+  PersistSuppliedOpenApiDocument: frozenObject(
+    {
+      filename: { type: 'string' },
+      name: { type: 'string' },
+      mediaType: { type: 'string' },
+      digest: { type: 'string' },
+      body: {
+        description: 'Authorized OpenAPI document object or JSON string (Runtime-resolved).',
+        oneOf: [{ type: 'object', additionalProperties: true }, { type: 'string' }]
+      }
+    },
+    ['body']
+  ),
+  PersistSuppliedOpenApiRequest: frozenObject(
+    {
+      documents: {
+        type: 'array',
+        minItems: 1,
+        items: schemaRef('PersistSuppliedOpenApiDocument')
+      }
+    },
+    ['documents']
+  ),
   WizardConfigRequest: frozenObject(
     {
       appName: { type: 'string' },
@@ -66,20 +89,23 @@ const OPENAPI_REQUEST_SCHEMAS = {
     },
     ['appName', 'source']
   ),
-  IntegrationDefinitionApplyRequest: frozenObject({
-    integrationDefinition: {
-      type: 'object',
-      additionalProperties: true,
-      description: 'Builder Integration Definition (aifabrix.builder.integrationDefinition).'
-    },
-    bid: {
-      type: 'object',
-      additionalProperties: true,
-      description: 'Alias for integrationDefinition.'
+  IntegrationDefinitionApplyRequest: frozenObject(
+    {
+      integrationDefinition: {
+        type: 'object',
+        additionalProperties: true,
+        description: 'Builder Integration Definition (aifabrix.builder.integrationDefinition).'
+      },
+      bid: {
+        type: 'object',
+        additionalProperties: true,
+        description: 'Alias for integrationDefinition.'
+      },
+      force: { type: 'boolean' },
+      dryRun: { type: 'boolean' }
     },
-    force: { type: 'boolean' },
-    dryRun: { type: 'boolean' }
-  }),
+    ['integrationDefinition']
+  ),
   RepairRequest: frozenObject({
     dryRun: { type: 'boolean' },
     auth: { type: 'string' },

package/lib/programmatic/openapi-result-schemas.js

@@ -129,6 +129,36 @@ const OPENAPI_RESULT_SCHEMAS = {
     },
     ['systemKey', 'meta']
   ),
+  PersistSuppliedOpenApiAcceptedFile: frozenObject(
+    {
+      filename: { type: 'string' },
+      path: { type: 'string' },
+      digest: { type: 'string' }
+    },
+    ['filename', 'path', 'digest']
+  ),
+  PersistSuppliedOpenApiRejectedFile: frozenObject(
+    {
+      filename: { type: 'string' },
+      reason: { type: 'string' },
+      detail: { type: 'string' }
+    },
+    ['filename', 'reason']
+  ),
+  PersistSuppliedOpenApiData: frozenObject(
+    {
+      accepted: {
+        type: 'array',
+        items: schemaRef('PersistSuppliedOpenApiAcceptedFile')
+      },
+      rejected: {
+        type: 'array',
+        items: schemaRef('PersistSuppliedOpenApiRejectedFile')
+      },
+      workspaceRoot: { type: 'string' }
+    },
+    ['accepted', 'rejected', 'workspaceRoot']
+  ),
   SystemManifestData: frozenObject(
     {
       systemKey: schemaRef('SystemKey'),

package/lib/programmatic/openapi-schema-descriptions-core.js

@@ -78,6 +78,24 @@ const CORE_SCHEMA_DESCRIPTIONS = {
     _schema: 'Payload for listSystems: integration keys under the authenticated user.',
     systems: 'Workspace summaries ordered by systemKey.'
   },
+  PersistSuppliedOpenApiData: {
+    _schema: 'Findings for persistSuppliedOpenApi (accepted and rejected files).',
+    accepted: 'Successfully validated and written OpenAPI files.',
+    rejected: 'Documents that failed validation (no success claim).',
+    workspaceRoot: 'Absolute workspace integration root for this user.'
+  },
+  PersistSuppliedOpenApiAcceptedFile: {
+    _schema: 'One accepted OpenAPI file written under the workspace.',
+    filename: 'Basename written under openapi/.',
+    path: 'Workspace-relative path including integration/<systemKey>/openapi/.',
+    digest: 'sha256 digest of the serialized JSON body.'
+  },
+  PersistSuppliedOpenApiRejectedFile: {
+    _schema: 'One rejected OpenAPI document (not written).',
+    filename: 'Requested basename when available.',
+    reason: 'Stable rejection reason code (openapi.invalid, …).',
+    detail: 'Human-readable validation detail.'
+  },
   CreateSystemData: {
     _schema: 'Payload after createSystem: new workspace folder and metadata.',
     systemKey: 'Created integration system key.',

package/lib/programmatic/openapi-schema-descriptions-operations.js

@@ -35,6 +35,25 @@ const OPERATIONS_SCHEMA_DESCRIPTIONS = {
     _schema: 'Request body to create an empty integration workspace folder.',
     systemKey: 'Unique integration system key for the new workspace.'
   },
+  PersistSuppliedOpenApiDocument: {
+    _schema: 'One Runtime-authorized OpenAPI document to persist.',
+    filename: 'Target basename under openapi/ (no path segments).',
+    name: 'Optional alias for filename.',
+    mediaType: 'Optional media type (application/json).',
+    digest: 'Optional sha256 digest of the serialized body for integrity check.',
+    body: 'OpenAPI document object or JSON string resolved by Runtime before CIP.'
+  },
+  PersistSuppliedOpenApiRequest: {
+    _schema: 'Request body for persistSuppliedOpenApi.',
+    documents: 'One or more authorized OpenAPI documents to validate and write.'
+  },
+  PersistSuppliedOpenApiResponse: {
+    _schema: '200 response envelope for persistSuppliedOpenApi.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see PersistSuppliedOpenApiData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
   WizardConfigRequest: {
     _schema: 'Headless wizard configuration to generate system and datasource JSON.',
     appName: 'Integration app folder name under the user workspace.',