@mastra/slack 1.0.2 → 1.1.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# @mastra/slack
+
+## 1.1.0-alpha.0
+
+### Minor Changes
+
+- Added @mastra/slack channel integration for connecting AI agents to Slack workspaces. Provides automatic Slack app provisioning via OAuth, manifest management with drift detection, encrypted credential storage, slash command support, and threaded conversation handling. Usage: ([#15876](https://github.com/mastra-ai/mastra/pull/15876))
+
+  ```ts
+  import { SlackProvider } from '@mastra/slack';
+
+  const mastra = new Mastra({
+    channels: {
+      slack: new SlackProvider({
+        refreshToken: process.env.SLACK_APP_CONFIG_REFRESH_TOKEN!,
+      }),
+    },
+  });
+
+  // Connect an agent to Slack
+  const result = await mastra.channels.slack.connect('my-agent');
+  // result.type === 'oauth' → redirect user to result.authorizationUrl
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`b2deb29`](https://github.com/mastra-ai/mastra/commit/b2deb29412b300c868655b5840463614fbb7962d), [`66644be`](https://github.com/mastra-ai/mastra/commit/66644beac1aa560f0e417956ff007c89341dc382), [`310b953`](https://github.com/mastra-ai/mastra/commit/310b95345f302dcd5ba3ed862bdc96f059d44122), [`43f0e1d`](https://github.com/mastra-ai/mastra/commit/43f0e1d5d5a74ba6fc746f2ad89ebe0c64777a7d), [`da0b9e2`](https://github.com/mastra-ai/mastra/commit/da0b9e2ba7ecc560213b426d6c097fe63946086e)]:
+  - @mastra/core@1.31.0-alpha.3

package/LICENSE.md

@@ -0,0 +1,30 @@
+Portions of this software are licensed as follows:
+
+- All content that resides under any directory named "ee/" within this
+  repository, including but not limited to:
+  - `packages/core/src/auth/ee/`
+  - `packages/server/src/server/auth/ee/`
+    is licensed under the license defined in `ee/LICENSE`.
+
+- All third-party components incorporated into the Mastra Software are
+  licensed under the original license provided by the owner of the
+  applicable component.
+
+- Content outside of the above-mentioned directories or restrictions is
+  available under the "Apache License 2.0" as defined below.
+
+# Apache License 2.0
+
+Copyright (c) 2025 Kepler Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,146 @@
+# @mastra/slack
+
+Slack integration for Mastra agents. Handles app creation, OAuth, slash commands, and messaging.
+
+## Quick Start
+
+```ts
+import { Mastra } from '@mastra/core/mastra';
+import { Agent } from '@mastra/core/agent';
+import { SlackProvider } from '@mastra/slack';
+
+const myAgent = new Agent({
+  id: 'my-agent',
+  name: 'My Agent',
+  model: 'openai/gpt-4.1',
+  instructions: 'You are a helpful assistant.',
+});
+
+const slack = new SlackProvider({
+  refreshToken: process.env.SLACK_APP_CONFIG_REFRESH_TOKEN,
+  // For local dev, set SLACK_BASE_URL to your tunnel URL
+  // In production, this is auto-derived from server config
+  baseUrl: process.env.SLACK_BASE_URL,
+});
+
+const mastra = new Mastra({
+  agents: { myAgent },
+  channels: { slack },
+});
+
+// Or configure credentials later (e.g., from UI or vault)
+// slack.configure({ refreshToken: 'xoxe-1-...' });
+
+// Connect an agent to Slack (creates app, returns OAuth URL)
+const { authorizationUrl } = await slack.connect('my-agent', {
+  name: 'My Bot',
+  description: 'An AI assistant',
+  iconUrl: 'https://example.com/my-bot-icon.png',
+  slashCommands: [
+    { command: '/ask', prompt: 'Answer: {{text}}' },
+    { command: '/help', prompt: 'List your capabilities.' },
+  ],
+});
+```
+
+## Setup
+
+1. **Get App Configuration Tokens** from https://api.slack.com/apps (look for "Your App Configuration Tokens" section)
+
+2. **Set up a tunnel** for local development:
+
+   ```bash
+   cloudflared tunnel --url http://localhost:4111
+   ```
+
+3. **Add to .env**:
+   ```
+   SLACK_APP_CONFIG_TOKEN=xoxe.xoxp-...
+   SLACK_APP_CONFIG_REFRESH_TOKEN=xoxe-1-...
+   SLACK_BASE_URL=https://abc123.trycloudflare.com
+   ```
+
+> ⚠️ **Token Rotation**: Slack config access tokens expire after 12 hours, but the refresh token does not expire (it's single-use — each rotation returns a new pair). Tokens auto-rotate and are persisted to storage, so the `.env` values are only used as the initial seed. If you lose your persisted storage (e.g., DB wipe), you'll need fresh tokens from the Slack dashboard.
+
+## Storage & Persistence
+
+`SlackProvider` automatically uses Mastra's storage if configured. Just add `storage` to your Mastra config:
+
+```ts
+import { LibSQLStore } from '@mastra/libsql';
+
+const mastra = new Mastra({
+  agents: { myAgent },
+  storage: new LibSQLStore({ url: 'file:./mastra.db' }),
+  channels: {
+    slack: new SlackProvider({
+      refreshToken: process.env.SLACK_APP_CONFIG_REFRESH_TOKEN!,
+    }),
+  },
+});
+```
+
+When Mastra has storage configured, `SlackProvider` automatically:
+
+- Persists rotated config tokens (so you don't need fresh tokens after restart)
+- Persists Slack app installations
+- Detects config changes (e.g., agent renames) and updates manifests on startup
+
+Without storage, data is lost on restart and apps are recreated.
+
+## How It Works
+
+1. Register a `SlackProvider` on your `Mastra` instance
+2. Call `slack.connect(agentId)` to provision a Slack app and get an OAuth URL
+3. Visit the OAuth URL to install the app to your Slack workspace
+4. After installation, messages and slash commands route to your agent
+5. Config access tokens auto-rotate (they expire every 12 hours) and are saved to storage
+
+## Slash Commands
+
+Commands use prompt templates with variable substitution:
+
+```ts
+await slack.connect('my-agent', {
+  slashCommands: [
+    {
+      command: '/ask',
+      description: 'Ask the AI a question',
+      prompt: 'Answer this question: {{text}}',
+    },
+    {
+      command: '/summarize',
+      description: 'Summarize content',
+      prompt: 'Summarize the following in 2-3 sentences: {{text}}',
+    },
+  ],
+});
+```
+
+Available variables: `{{text}}`, `{{userId}}`, `{{channelId}}`, `{{teamId}}`
+
+## App Icons
+
+Each agent's Slack app can have its own icon:
+
+```ts
+await slack.connect('my-agent', {
+  iconUrl: 'https://example.com/my-bot-avatar.png',
+});
+```
+
+The image should be:
+
+- Square (1:1 aspect ratio)
+- At least 512x512 pixels
+- PNG, JPG, or GIF format
+
+The icon is uploaded automatically when the Slack app is created.
+
+## Disconnecting
+
+```ts
+await slack.disconnect('my-agent');
+```
+
+This deletes the Slack app and removes the local installation record.