@aifabrix/builder 2.49.1 → 2.50.0

package/templates/channels/slack/install.template.md.hbs

@@ -1,12 +1,27 @@
-# {{appName}} — assistant channel install
+# {{appName}} — Slack communication channel install
 
 {{appDescription}}
 
-Environment: **{{environment}}** · Credential key: `{{credentialKey}}`
+Environment: **{{environment}}** · Credential key: `{{credentialKey}}` · Command prefix: `{{commandPrefix}}`
+
+One Slack app delivers **Role Assistant** chat, **Work hub** shortcuts, and **document approval**.
+
+**Chat with your assistant:** DM this app (no slash command for Q&A).
+
+## Create the Slack app (workspace admin)
+
+1. Open [Slack API — Your Apps](https://api.slack.com/apps) and sign in as a workspace admin.
+2. Click **Create New App** → **From an app manifest**.
+3. Select your workspace, then paste or upload the generated manifest JSON from `dist/channels/slack/channel-slack.json` (same folder as this file).
+4. Review callback URLs and OAuth scopes — they must match the values in **Platform callback URLs** below.
+5. Confirm **App Home → Messages tab** is **ON** in the manifest (required for bot DMs and proactive notifications; slash commands work without it).
+6. Click **Create**, then open **Install App** → **Install to Workspace** and approve.
+7. Copy **Bot User OAuth Token** and **Signing Secret** from the Slack app settings.
+8. Save **Bot User OAuth Token** and **Signing Secret** in AI Fabrix: [Authentication settings]({{credentialPortalUrl}})
 
 ## Platform callback URLs
 
-Configure these in your Slack app, Teams bot registration, or platform admin console. Do not embed secrets in generated files — use AI Fabrix credential storage only.
+Configure these in your Slack app if you edit settings manually. Do not embed secrets in generated files — use AI Fabrix credential storage only.
 
 {{#if eventsUrl}}
 - **Events:** {{eventsUrl}}
@@ -17,18 +32,27 @@ Configure these in your Slack app, Teams bot registration, or platform admin con
 {{#if commandUrl}}
 - **Slash commands:** {{commandUrl}}
 {{/if}}
-{{#if oauthCallbackUrl}}
-- **OAuth redirect:** {{oauthCallbackUrl}}
-{{/if}}
-{{#if messagesUrl}}
-- **Bot messages:** {{messagesUrl}}
-{{/if}}
-{{#if notificationsUrl}}
-- **Notifications:** {{notificationsUrl}}
-{{/if}}
-{{#if botConfigUrl}}
-- **Bot config:** {{botConfigUrl}}
-{{/if}}
+
+Register these **V1** slash commands in the manifest (all use the same request URL):
+
+| Command | Purpose |
+| --- | --- |
+| `/{{commandPrefix}}-help` | Command help and portal links |
+| `/{{commandPrefix}}-assistants` | See your Role Assistants and chat in DM |
+| `/{{commandPrefix}}-tasks` | Tasks waiting for you — View opens the Work hub |
+| `/{{commandPrefix}}-documents [status] [count]` | Documents waiting for review — Open in portal |
+
+Single-task and single-document detail, plus approve-in-Slack, are **not** registered in the manifest — use list **View** buttons or the portal for full review.
+
+Document review **block actions** use the **Interactivity** URL above.
+
+## Validate after manifest import
+
+1. `/{{commandPrefix}}-help` — returns Block Kit help (proves command is registered and dataplane responds).
+2. `/{{commandPrefix}}-assistants` — Role Assistant status cards or activation offer.
+3. `/{{commandPrefix}}-tasks` — waiting-for-me work items (when Work hub is enabled).
+4. `/{{commandPrefix}}-documents` — document list with **Review in portal** links.
+5. DM the bot — assistant chat.
 
 ## Assistant catalog
 
@@ -36,14 +60,20 @@ Runtime lists **assistants** available to each user from:
 
 {{assistantCatalogUrl}}
 
-## After admin approval
+## After Slack install
 
 ```bash
-aifabrix app add-channel {{channelTarget}} --name "{{baseName}}"
+aifabrix channel add {{channelTarget}} --name "{{baseName}}"
 ```
 
 Optional validation:
 
 ```bash
-aifabrix app add-channel {{channelTarget}} --name "{{baseName}}" --probe
+aifabrix channel add {{channelTarget}} --name "{{baseName}}" --probe
+```
+
+To use a different slash prefix (default `af`):
+
+```bash
+aifabrix channel add {{channelTarget}} --name "{{baseName}}" --command-prefix <key>
 ```

package/templates/channels/slack/integration/README.md

@@ -0,0 +1,38 @@
+# Slack communication channel
+
+Communication external system for **Role Assistants** (workforce transport) **and document approval** — one Slack app, dual surface (plan 455.2).
+
+## What this integration is
+
+- Slack app manifest install (`channel-slack.json` via `aifabrix channel add slack`)
+- **Workforce:** slash commands (`/assistants`, `/tasks`, `/task`), Events API (DM chat), interactive components
+- **Document approval:** slash commands (`/documents`, `/document`, `/approve`, `/help`), review card block actions, proactive notifications
+- **Command SSOT:** `templates/slack/command_catalog.yaml` + Block Kit JSON under `templates/slack/`; optional install prefix (default `af`) registers `/af-*` aliases
+- Outbound CIP: `slack-messages`, `slack-conversations` (workforce replies, DMs, and approval notifications)
+
+## What this integration is not
+
+- **Not** channel listing / user directory sync (`slack-channels`, `slack-users` are out of scope for this scaffold).
+
+## Endpoints
+
+Registered at `/api/v1/external/systems/slack/`:
+
+| Path | Purpose |
+| --- | --- |
+| `/commands` | Slash commands (workforce + document approval) |
+| `/events` | Events API |
+| `/interactive` | Block actions (approve, reject, metadata) |
+| `/notifications` | Proactive messages |
+| `/documents` | Document review Block Kit payload |
+| `/bot-config` | Bot configuration |
+
+## Workflow
+
+```bash
+aifabrix channel scaffold slack   # or use this folder as SSOT
+aifabrix upload slack --force
+aifabrix channel add slack --name "Your Assistant"
+```
+
+Publish template changes: `make sync-json` in dataplane → `aifabrix-builder/templates/channels/slack/integration/`.

package/templates/channels/slack/integration/application.json

@@ -0,0 +1,18 @@
+{
+  "app": {
+    "key": "slack",
+    "displayName": "slack assistant channel",
+    "description": "Assistant communication channel — upload then channel add",
+    "type": "external"
+  },
+  "externalIntegration": {
+    "schemaBasePath": "./",
+    "systems": ["slack-system.json"],
+    "dataSources": [
+      "slack-datasource-messages.json",
+      "slack-datasource-conversations.json"
+    ],
+    "autopublish": true,
+    "version": "1.0.0"
+  }
+}

package/templates/channels/slack/integration/env.template

@@ -0,0 +1,29 @@
+# Slack assistant channel (communication) — lab fixture secrets
+# Copy to integration/slack/.env (or use aifabrix secret set --shared) before deploy/upload.
+#
+# Manifest: integration/slack/slack-system.json
+# Credential key: slack-app (method hmac)
+#
+# Resolution order at deploy: dataplane secret store (POST /api/v1/credential/secret)
+# then KV_* env fallback in the dataplane container.
+#
+# In .env set plain values (not kv:// literals), e.g.:
+#   KV_SLACK_SIGNINGSECRET=<Signing Secret from Slack app Basic Information>
+#   KV_SLACK_BOTTOKEN=xoxb-<Bot User OAuth Token from OAuth & Permissions>
+#   (NOT xapp- app-level tokens — bot tokens always start with xoxb-)
+# Optional OAuth client secret (not required for webhook + bot outbound smoke):
+#   KV_SLACK_CLIENTSECRET=<Client Secret>
+#
+# Shared secrets (Builder CLI, keys without kv:// prefix):
+#   aifabrix secret set slack/signingSecret "<value>" --shared
+#   aifabrix secret set slack/botToken "xoxb-..." --shared
+#   aifabrix secret set slack/clientSecret "<value>" --shared
+
+# Required — webhook signature verification (438.3 inbound)
+KV_SLACK_SIGNINGSECRET=kv://slack/signingSecret
+
+# Required — outbound Slack Web API (post message, etc.)
+KV_SLACK_BOTTOKEN=kv://slack/botToken
+
+# Optional — OAuth app client secret
+KV_SLACK_CLIENTSECRET=kv://slack/clientSecret

package/templates/channels/slack/integration/slack-datasource-conversations.json

@@ -0,0 +1,226 @@
+{
+  "key": "slack-conversations",
+  "displayName": "Slack Conversations",
+  "description": "Slack conversations datasource for managing DM and channel conversations",
+  "enabled": true,
+  "systemKey": "slack",
+  "resourceType": "conversation",
+  "entityType": "messageService",
+  "version": "1.0.0",
+  "metadataSchema": {
+    "type": "object",
+    "properties": {
+      "id": {
+        "type": "string",
+        "description": "Conversation ID"
+      },
+      "name": {
+        "type": "string",
+        "description": "Conversation name"
+      },
+      "isPrivate": {
+        "type": "boolean",
+        "description": "Whether conversation is private"
+      },
+      "isIm": {
+        "type": "boolean",
+        "description": "Whether conversation is a direct message"
+      },
+      "user": {
+        "type": "string",
+        "description": "User ID (for DM conversations)"
+      },
+      "key": {
+        "type": "string",
+        "index": true
+      }
+    }
+  },
+  "fieldMappings": {
+    "attributes": {
+      "externalId": {
+        "expression": "{{raw.id}}"
+      },
+      "key": {
+        "expression": "{{raw.id}}"
+      },
+      "id": {
+        "expression": "{{raw.id}}"
+      },
+      "name": {
+        "expression": "{{raw.name}}"
+      },
+      "isPrivate": {
+        "expression": "{{raw.isPrivate}}"
+      },
+      "isIm": {
+        "expression": "{{raw.isIm}}"
+      },
+      "user": {
+        "expression": "{{raw.user}}"
+      }
+    }
+  },
+  "primaryKey": [
+    "key"
+  ],
+  "labelKey": [
+    "key"
+  ],
+  "exposed": {
+    "schema": {
+      "externalId": "metadata.externalId",
+      "key": "metadata.key",
+      "id": "metadata.id",
+      "name": "metadata.name",
+      "isPrivate": "metadata.isPrivate",
+      "isIm": "metadata.isIm",
+      "user": "metadata.user"
+    },
+    "profiles": {
+      "default": [
+        "externalId",
+        "key",
+        "id",
+        "name",
+        "isPrivate",
+        "isIm",
+        "user"
+      ]
+    }
+  },
+  "quality": {
+    "rejectIf": []
+  },
+  "execution": {
+    "engine": "cip",
+    "cip": {
+      "version": "1.0",
+      "inputType": "void",
+      "outputType": "records",
+      "operations": {
+        "create": {
+          "description": "Open a direct message conversation",
+          "enabled": true,
+          "steps": [
+            {
+              "fetch": {
+                "source": "http",
+                "method": "POST",
+                "path": "/api/conversations.open",
+                "headers": {
+                  "Authorization": "Bearer {{credential.botToken}}",
+                  "Content-Type": "application/json"
+                },
+                "bodyTemplate": {
+                  "users": "{{parameters.users}}"
+                }
+              }
+            },
+            {
+              "map": {
+                "useFieldMappings": true,
+                "inputPath": "$.channel"
+              }
+            },
+            {
+              "output": {
+                "mode": "records"
+              }
+            }
+          ]
+        },
+        "list": {
+          "description": "List conversations",
+          "enabled": true,
+          "steps": [
+            {
+              "fetch": {
+                "source": "openapi",
+                "openapiRef": "list",
+                "query": {
+                  "types": "{{parameters.types | default('public_channel,private_channel,im,mpim')}}",
+                  "limit": "{{parameters.limit | default(100)}}"
+                }
+              }
+            },
+            {
+              "map": {
+                "useFieldMappings": true,
+                "inputPath": "$.channels[*]"
+              }
+            },
+            {
+              "output": {
+                "mode": "records"
+              }
+            }
+          ]
+        },
+        "get": {
+          "description": "Get conversation info",
+          "enabled": true,
+          "steps": [
+            {
+              "fetch": {
+                "source": "openapi",
+                "openapiRef": "get",
+                "query": {
+                  "channel": "{{parameters.channel}}"
+                }
+              }
+            },
+            {
+              "map": {
+                "useFieldMappings": true,
+                "inputPath": "$.channel"
+              }
+            },
+            {
+              "output": {
+                "mode": "records"
+              }
+            }
+          ]
+        }
+      }
+    }
+  },
+  "capabilities": [
+    {
+      "key": "list",
+      "description": "List conversations",
+      "riskLevel": "low",
+      "approvalRequired": false
+    },
+    {
+      "key": "get",
+      "description": "Get conversation info",
+      "riskLevel": "low",
+      "approvalRequired": false
+    },
+    {
+      "key": "create",
+      "description": "Open a direct message conversation",
+      "riskLevel": "medium",
+      "approvalRequired": false
+    }
+  ],
+  "openapi": {
+    "operations": {
+      "list": {
+        "operationId": "get-api-conversations-list",
+        "method": "GET",
+        "path": "/api/conversations.list"
+      },
+      "get": {
+        "operationId": "get-api-conversations-info",
+        "method": "GET",
+        "path": "/api/conversations.info"
+      }
+    },
+    "enabled": true,
+    "documentKey": "slack-conversations",
+    "autoRbac": true
+  }
+}

package/templates/channels/slack/integration/slack-datasource-messages.json

@@ -0,0 +1,269 @@
+{
+  "key": "slack-messages",
+  "displayName": "Slack Messages",
+  "description": "Slack messages datasource for sending and managing messages via Slack Web API",
+  "enabled": true,
+  "systemKey": "slack",
+  "resourceType": "message",
+  "entityType": "messageService",
+  "version": "1.0.0",
+  "metadataSchema": {
+    "type": "object",
+    "properties": {
+      "channel": {
+        "type": "string",
+        "description": "Channel ID where message is sent"
+      },
+      "text": {
+        "type": "string",
+        "description": "Message text"
+      },
+      "blocks": {
+        "type": "array",
+        "description": "Message blocks (Slack Block Kit)",
+        "items": {
+          "type": "string"
+        }
+      },
+      "ts": {
+        "type": "string",
+        "description": "Message timestamp (used as message ID)"
+      },
+      "user": {
+        "type": "string",
+        "description": "User ID who sent the message"
+      },
+      "key": {
+        "type": "string",
+        "index": true
+      }
+    },
+    "required": [
+      "channel"
+    ]
+  },
+  "fieldMappings": {
+    "attributes": {
+      "externalId": {
+        "expression": "{{raw.ts}}"
+      },
+      "key": {
+        "expression": "{{raw.ts}}"
+      },
+      "channel": {
+        "expression": "{{raw.channel}}"
+      },
+      "text": {
+        "expression": "{{raw.text}}"
+      },
+      "blocks": {
+        "expression": "{{raw.blocks}}"
+      },
+      "ts": {
+        "expression": "{{raw.ts}}"
+      },
+      "user": {
+        "expression": "{{raw.user}}"
+      }
+    }
+  },
+  "primaryKey": [
+    "key"
+  ],
+  "labelKey": [
+    "key"
+  ],
+  "exposed": {
+    "schema": {
+      "externalId": "metadata.externalId",
+      "key": "metadata.key",
+      "channel": "metadata.channel",
+      "text": "metadata.text",
+      "blocks": "metadata.blocks",
+      "ts": "metadata.ts",
+      "user": "metadata.user"
+    },
+    "profiles": {
+      "default": [
+        "externalId",
+        "key",
+        "channel",
+        "text",
+        "blocks",
+        "ts",
+        "user"
+      ]
+    }
+  },
+  "quality": {
+    "rejectIf": []
+  },
+  "execution": {
+    "engine": "cip",
+    "cip": {
+      "version": "1.0",
+      "inputType": "void",
+      "outputType": "records",
+      "operations": {
+        "create": {
+          "description": "Send a message to Slack channel",
+          "enabled": true,
+          "steps": [
+            {
+              "fetch": {
+                "source": "http",
+                "method": "POST",
+                "path": "/api/chat.postMessage",
+                "headers": {
+                  "Authorization": "Bearer {{credential.botToken}}",
+                  "Content-Type": "application/json"
+                },
+                "bodyTemplate": {
+                  "channel": "{{parameters.channel}}",
+                  "text": "{{parameters.text}}",
+                  "blocks": "{{parameters.blocks}}"
+                }
+              }
+            },
+            {
+              "map": {
+                "useFieldMappings": true,
+                "inputPath": "$"
+              }
+            },
+            {
+              "output": {
+                "mode": "records"
+              }
+            }
+          ]
+        },
+        "update": {
+          "description": "Update an existing Slack message",
+          "enabled": true,
+          "steps": [
+            {
+              "fetch": {
+                "source": "http",
+                "method": "POST",
+                "path": "/api/chat.update",
+                "headers": {
+                  "Authorization": "Bearer {{credential.botToken}}",
+                  "Content-Type": "application/json"
+                },
+                "bodyTemplate": {
+                  "channel": "{{parameters.channel}}",
+                  "ts": "{{parameters.ts}}",
+                  "text": "{{parameters.text}}",
+                  "blocks": "{{parameters.blocks}}"
+                }
+              }
+            },
+            {
+              "map": {
+                "useFieldMappings": true,
+                "inputPath": "$"
+              }
+            },
+            {
+              "output": {
+                "mode": "records"
+              }
+            }
+          ]
+        },
+        "delete": {
+          "description": "Delete a Slack message",
+          "enabled": true,
+          "steps": [
+            {
+              "fetch": {
+                "source": "http",
+                "method": "POST",
+                "path": "/api/chat.delete",
+                "headers": {
+                  "Authorization": "Bearer {{credential.botToken}}",
+                  "Content-Type": "application/json"
+                },
+                "bodyTemplate": {
+                  "channel": "{{parameters.channel}}",
+                  "ts": "{{parameters.ts}}"
+                }
+              }
+            },
+            {
+              "output": {
+                "mode": "records"
+              }
+            }
+          ]
+        },
+        "list": {
+          "description": "Get message history from Slack channel",
+          "enabled": true,
+          "steps": [
+            {
+              "fetch": {
+                "source": "openapi",
+                "openapiRef": "list",
+                "query": {
+                  "channel": "{{parameters.channel}}",
+                  "limit": "{{parameters.limit | default(100)}}"
+                }
+              }
+            },
+            {
+              "map": {
+                "useFieldMappings": true,
+                "inputPath": "$.messages[*]"
+              }
+            },
+            {
+              "output": {
+                "mode": "records"
+              }
+            }
+          ]
+        }
+      }
+    }
+  },
+  "capabilities": [
+    {
+      "key": "list",
+      "description": "Get message history from Slack channel",
+      "riskLevel": "low",
+      "approvalRequired": false
+    },
+    {
+      "key": "create",
+      "description": "Send a message to Slack channel",
+      "riskLevel": "medium",
+      "approvalRequired": false
+    },
+    {
+      "key": "update",
+      "description": "Update an existing Slack message",
+      "riskLevel": "medium",
+      "approvalRequired": false
+    },
+    {
+      "key": "delete",
+      "description": "Delete a Slack message",
+      "riskLevel": "high",
+      "approvalRequired": false
+    }
+  ],
+  "openapi": {
+    "operations": {
+      "list": {
+        "operationId": "get-api-conversations-history",
+        "method": "GET",
+        "path": "/api/conversations.history"
+      }
+    },
+    "enabled": true,
+    "documentKey": "slack-messages",
+    "autoRbac": true
+  }
+}