@mastra/slack 0.0.0-studio-cli-20260504022012

package/dist/index.d.cts

@@ -0,0 +1,678 @@
+import { Mastra } from '@mastra/core/mastra';
+import { ChannelProvider, ChannelConnectResult, ChannelInstallationInfo, ChannelPlatformInfo } from '@mastra/core/channels';
+import { ApiRoute } from '@mastra/core/server';
+import { SlackAdapter } from '@chat-adapter/slack';
+export { SlackAdapter, createSlackAdapter } from '@chat-adapter/slack';
+import { z } from 'zod';
+import { ChannelsStorage } from '@mastra/core/storage';
+
+/**
+ * Zod schemas for Slack channel data stored in ChannelsStorage.
+ * These define the shape of the `data` JSON blob in ChannelInstallation records.
+ */
+declare const SlashCommandSchema: z.ZodObject<{
+    command: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    usageHint: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    command: string;
+    description?: string | undefined;
+    usageHint?: string | undefined;
+    prompt?: string | undefined;
+}, {
+    command: string;
+    description?: string | undefined;
+    usageHint?: string | undefined;
+    prompt?: string | undefined;
+}>;
+declare const SlackInstallationDataSchema: z.ZodObject<{
+    appId: z.ZodString;
+    clientId: z.ZodString;
+    clientSecret: z.ZodString;
+    signingSecret: z.ZodString;
+    teamId: z.ZodString;
+    teamName: z.ZodOptional<z.ZodString>;
+    botToken: z.ZodString;
+    botUserId: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    slashCommands: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        command: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        usageHint: z.ZodOptional<z.ZodString>;
+        prompt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        command: string;
+        description?: string | undefined;
+        usageHint?: string | undefined;
+        prompt?: string | undefined;
+    }, {
+        command: string;
+        description?: string | undefined;
+        usageHint?: string | undefined;
+        prompt?: string | undefined;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    appId: string;
+    clientId: string;
+    clientSecret: string;
+    signingSecret: string;
+    teamId: string;
+    botToken: string;
+    botUserId: string;
+    description?: string | undefined;
+    teamName?: string | undefined;
+    name?: string | undefined;
+    slashCommands?: {
+        command: string;
+        description?: string | undefined;
+        usageHint?: string | undefined;
+        prompt?: string | undefined;
+    }[] | undefined;
+}, {
+    appId: string;
+    clientId: string;
+    clientSecret: string;
+    signingSecret: string;
+    teamId: string;
+    botToken: string;
+    botUserId: string;
+    description?: string | undefined;
+    teamName?: string | undefined;
+    name?: string | undefined;
+    slashCommands?: {
+        command: string;
+        description?: string | undefined;
+        usageHint?: string | undefined;
+        prompt?: string | undefined;
+    }[] | undefined;
+}>;
+type SlackInstallationData = z.infer<typeof SlackInstallationDataSchema>;
+declare const SlackPendingDataSchema: z.ZodObject<{
+    appId: z.ZodString;
+    clientId: z.ZodString;
+    clientSecret: z.ZodString;
+    signingSecret: z.ZodString;
+    authorizationUrl: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    slashCommands: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        command: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        usageHint: z.ZodOptional<z.ZodString>;
+        prompt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        command: string;
+        description?: string | undefined;
+        usageHint?: string | undefined;
+        prompt?: string | undefined;
+    }, {
+        command: string;
+        description?: string | undefined;
+        usageHint?: string | undefined;
+        prompt?: string | undefined;
+    }>, "many">>;
+    redirectUrl: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    appId: string;
+    clientId: string;
+    clientSecret: string;
+    signingSecret: string;
+    authorizationUrl: string;
+    description?: string | undefined;
+    name?: string | undefined;
+    slashCommands?: {
+        command: string;
+        description?: string | undefined;
+        usageHint?: string | undefined;
+        prompt?: string | undefined;
+    }[] | undefined;
+    redirectUrl?: string | undefined;
+}, {
+    appId: string;
+    clientId: string;
+    clientSecret: string;
+    signingSecret: string;
+    authorizationUrl: string;
+    description?: string | undefined;
+    name?: string | undefined;
+    slashCommands?: {
+        command: string;
+        description?: string | undefined;
+        usageHint?: string | undefined;
+        prompt?: string | undefined;
+    }[] | undefined;
+    redirectUrl?: string | undefined;
+}>;
+type SlackPendingData = z.infer<typeof SlackPendingDataSchema>;
+declare const SlackConfigDataSchema: z.ZodObject<{
+    token: z.ZodOptional<z.ZodString>;
+    refreshToken: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    refreshToken: string;
+    token?: string | undefined;
+}, {
+    refreshToken: string;
+    token?: string | undefined;
+}>;
+type SlackConfigData = z.infer<typeof SlackConfigDataSchema>;
+/** Normalized slash command config as stored in installation data. */
+type StoredSlashCommand = z.infer<typeof SlashCommandSchema>;
+interface SlackInstallation {
+    id: string;
+    agentId: string;
+    webhookId: string;
+    configHash: string;
+    installedAt: Date;
+    appId: string;
+    clientId: string;
+    clientSecret: string;
+    signingSecret: string;
+    teamId: string;
+    teamName?: string;
+    botToken: string;
+    botUserId: string;
+    /** Explicit name passed to connect(), takes priority over agent.name */
+    name?: string;
+    /** Explicit description passed to connect(), takes priority over agent.getDescription() */
+    description?: string;
+    slashCommands?: StoredSlashCommand[];
+}
+interface SlackPendingInstallation {
+    id: string;
+    agentId: string;
+    webhookId: string;
+    configHash: string;
+    createdAt: Date;
+    appId: string;
+    clientId: string;
+    clientSecret: string;
+    signingSecret: string;
+    authorizationUrl: string;
+    /** Explicit name passed to connect(), takes priority over agent.name */
+    name?: string;
+    /** Explicit description passed to connect(), takes priority over agent.getDescription() */
+    description?: string;
+    slashCommands?: StoredSlashCommand[];
+    redirectUrl?: string;
+}
+interface SlackConfigTokens {
+    token?: string;
+    refreshToken: string;
+    updatedAt: Date;
+}
+
+/**
+ * Configuration for SlackProvider at the Mastra level.
+ */
+interface SlackProviderConfig {
+    /**
+     * Slack App Configuration access token for programmatic app creation.
+     * Generate at: https://api.slack.com/apps > "Your App Configuration Tokens"
+     *
+     * Optional — will rotate to get a fresh token on startup using `refreshToken`.
+     */
+    token?: string;
+    /**
+     * Slack App Configuration refresh token.
+     * Used for automatic token rotation. Single-use; each rotation returns a new pair.
+     *
+     * Can be provided here or later via `configure({ refreshToken })`.
+     * If omitted, the provider starts unconfigured and cannot create apps until
+     * `configure()` is called or tokens are loaded from storage.
+     */
+    refreshToken?: string;
+    /**
+     * Base URL for webhook callbacks.
+     * Required when calling connect() to create apps.
+     * Can also be set later via setBaseUrl() or auto-detected from server config.
+     *
+     * For local development, use a tunnel like cloudflared:
+     * ```
+     * baseUrl: 'https://abc123.trycloudflare.com'
+     * ```
+     */
+    baseUrl?: string;
+    /**
+     * Custom storage for installations.
+     * Defaults to using Mastra's ChannelsStorage from the global storage.
+     * Throws if no persistent storage is available.
+     */
+    storage?: ChannelsStorage;
+    /**
+     * Path to redirect to after OAuth completion.
+     * Defaults to "/" (homepage)
+     */
+    redirectPath?: string;
+    /**
+     * Called when a workspace successfully installs the app.
+     */
+    onInstall?: (installation: SlackInstallation) => Promise<void>;
+    /**
+     * Encryption key for sensitive data (clientSecret, signingSecret, botToken).
+     * If not provided, secrets are stored in plaintext (not recommended for production).
+     *
+     * Use a 32+ character random string. Can be set via MASTRA_ENCRYPTION_KEY env var.
+     */
+    encryptionKey?: string;
+}
+/**
+ * Options for connecting an agent to Slack via `slack.connect(agentId, options)`.
+ * This is serializable and can be stored in the database for stored agents.
+ */
+interface SlackConnectOptions {
+    /**
+     * Display name for the Slack bot.
+     * Defaults to agent name, then agent ID.
+     */
+    name?: string;
+    /**
+     * Bot description shown in Slack.
+     * Defaults to "{name} - Powered by Mastra".
+     */
+    description?: string;
+    /**
+     * URL to an image for the app icon.
+     * Should be a square PNG/JPG, minimum 512x512px.
+     * The image will be automatically downloaded and uploaded to Slack.
+     *
+     * @example
+     * iconUrl: 'https://example.com/my-bot-avatar.png'
+     */
+    iconUrl?: string;
+    /**
+     * Slash commands this agent supports.
+     *
+     * Simple form - command triggers agent.generate() with the input text:
+     * ```ts
+     * slashCommands: ['/ask']
+     * ```
+     *
+     * With custom prompt template:
+     * ```ts
+     * slashCommands: [
+     *   {
+     *     command: '/summarize',
+     *     description: 'Summarize a URL',
+     *     prompt: 'Fetch and summarize: {{text}}'
+     *   }
+     * ]
+     * ```
+     *
+     * Use {{text}} as placeholder for user input.
+     */
+    slashCommands?: (string | SlashCommandConfig)[];
+    /**
+     * Customize the Slack app manifest before it's sent to the Manifest API.
+     *
+     * Receives the default manifest (built from name, description, slashCommands,
+     * and internal URLs) and returns the final manifest to use.
+     *
+     * Use this for any advanced Slack configuration: custom scopes, events,
+     * interactivity settings, etc.
+     *
+     * @example
+     * // Add extra scopes
+     * manifest: (m) => ({
+     *   ...m,
+     *   oauth_config: {
+     *     ...m.oauth_config,
+     *     scopes: { bot: [...(m.oauth_config?.scopes?.bot ?? []), 'files:write'] }
+     *   }
+     * })
+     *
+     * @example
+     * // Subscribe to additional events
+     * manifest: (m) => ({
+     *   ...m,
+     *   settings: {
+     *     ...m.settings,
+     *     event_subscriptions: {
+     *       ...m.settings?.event_subscriptions,
+     *       bot_events: [...(m.settings?.event_subscriptions?.bot_events ?? []), 'reaction_added']
+     *     }
+     *   }
+     * })
+     */
+    manifest?: (defaults: SlackAppManifest) => SlackAppManifest;
+    /**
+     * URL to redirect to after successful OAuth completion.
+     * Typically set by the Studio UI to return to the agent page.
+     * Defaults to `SlackProviderConfig.redirectPath` or `/`.
+     */
+    redirectUrl?: string;
+}
+/**
+ * Slash command configuration (fully serializable).
+ *
+ * A slash command is essentially a prompt template that gets filled with user input
+ * and sent to the agent. Like Claude Code's slash commands.
+ */
+interface SlashCommandConfig {
+    /** Command name including slash (e.g., "/ask") */
+    command: string;
+    /** Short description shown in Slack's command picker */
+    description?: string;
+    /** Usage hint shown in Slack (e.g., "[question]") */
+    usageHint?: string;
+    /**
+     * Prompt template sent to the agent.
+     * Use {{text}} as placeholder for user input.
+     *
+     * Defaults to "{{text}}" (just passes input directly).
+     *
+     * @example
+     * prompt: 'Summarize the following URL: {{text}}'
+     * prompt: 'Write {{text}} in TypeScript'
+     */
+    prompt?: string;
+}
+interface SlackMessage {
+    text?: string;
+    blocks?: SlackBlock[];
+    response_type?: 'in_channel' | 'ephemeral';
+    replace_original?: boolean;
+    delete_original?: boolean;
+}
+interface SlackBlock {
+    type: string;
+    [key: string]: unknown;
+}
+/**
+ * Slack App Manifest for programmatic app creation.
+ * @see https://api.slack.com/reference/manifests
+ */
+interface SlackAppManifest {
+    display_information: {
+        name: string;
+        description?: string;
+        background_color?: string;
+        long_description?: string;
+    };
+    features?: {
+        app_home?: {
+            home_tab_enabled?: boolean;
+            messages_tab_enabled?: boolean;
+            messages_tab_read_only_enabled?: boolean;
+        };
+        bot_user?: {
+            display_name: string;
+            always_online?: boolean;
+        };
+        slash_commands?: Array<{
+            command: string;
+            description: string;
+            url: string;
+            usage_hint?: string;
+        }>;
+    };
+    oauth_config?: {
+        redirect_urls?: string[];
+        scopes?: {
+            bot?: string[];
+            user?: string[];
+        };
+    };
+    settings?: {
+        event_subscriptions?: {
+            request_url?: string;
+            bot_events?: string[];
+            user_events?: string[];
+        };
+        interactivity?: {
+            is_enabled?: boolean;
+            request_url?: string;
+            message_menu_options_url?: string;
+        };
+        org_deploy_enabled?: boolean;
+        socket_mode_enabled?: boolean;
+        token_rotation_enabled?: boolean;
+    };
+}
+/**
+ * Credentials returned when creating a Slack app via manifest API.
+ */
+interface SlackAppCredentials {
+    appId: string;
+    clientId: string;
+    clientSecret: string;
+    signingSecret: string;
+    oauthAuthorizeUrl?: string;
+}
+
+/**
+ * Slack channel integration for Mastra.
+ *
+ * Handles:
+ * - Programmatic Slack app creation via manifest API
+ * - OAuth flow for Slack workspace installations
+ * - Webhook routing for events and slash commands
+ * - Message handling via @chat-adapter/slack
+ *
+ * @example
+ * ```ts
+ * import { SlackProvider } from '@mastra/slack';
+ *
+ * // With credentials at construction
+ * const slack = new SlackProvider({
+ *   refreshToken: process.env.SLACK_APP_CONFIG_REFRESH_TOKEN,
+ * });
+ *
+ * // Or configure later (e.g., credentials from UI or vault)
+ * const slack = new SlackProvider();
+ * await slack.configure({ refreshToken: 'xoxe-1-...' });
+ *
+ * const mastra = new Mastra({
+ *   agents: { myAgent },
+ *   channels: { slack },
+ * });
+ *
+ * // Connect an agent to Slack (creates app, returns OAuth connect result)
+ * const result = await slack.connect('my-agent', {
+ *   name: 'My Bot',
+ *   slashCommands: ['/ask', '/help'],
+ * });
+ * if (result.type === 'oauth') {
+ *   // Redirect user to result.authorizationUrl
+ * }
+ * ```
+ */
+declare class SlackProvider implements ChannelProvider {
+    #private;
+    readonly id = "slack";
+    constructor(config?: SlackProviderConfig);
+    /**
+     * Provide or clear Slack App Configuration credentials at runtime.
+     *
+     * Use this when credentials aren't available at construction time — for example,
+     * when they're entered through the Editor UI or loaded from a vault.
+     *
+     * Pass `null` to clear credentials and delete stored tokens.
+     *
+     * @example
+     * ```ts
+     * const slack = new SlackProvider();
+     * // Provide credentials (persists to storage immediately):
+     * await slack.configure({ refreshToken: 'xoxe-1-...' });
+     * // Clear credentials and stored tokens:
+     * await slack.configure(null);
+     * ```
+     */
+    configure(credentials: {
+        refreshToken: string;
+        token?: string;
+    } | null): Promise<void>;
+    /**
+     * Called by Mastra when this channel is registered.
+     * @internal
+     */
+    __attach(mastra: Mastra): void;
+    /**
+     * Set the base URL for webhook callbacks.
+     * Only needed if not using Mastra server config.
+     */
+    setBaseUrl(baseUrl: string): void;
+    /**
+     * Restore active Slack installations from storage.
+     *
+     * For each active installation in the database, this creates a SlackAdapter
+     * and injects AgentChannels into the corresponding Agent so it can receive
+     * Slack events immediately on startup.
+     *
+     * Does NOT auto-provision new apps. Use `connect(agentId, options)` to
+     * create a new Slack app for an agent.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get API routes for the Mastra server.
+     * Add these to your Mastra config via `server.apiRoutes`.
+     *
+     * The mastra instance is automatically injected via createHandler.
+     * On first request, auto-initializes any agents with slack configs.
+     */
+    getRoutes(): ApiRoute[];
+    /**
+     * Connect an agent to Slack by creating a new Slack app.
+     *
+     * @returns OAuth connect result with authorization URL for user redirect
+     */
+    connect(agentId: string, options?: SlackConnectOptions): Promise<ChannelConnectResult>;
+    /**
+     * Disconnect an agent from Slack by deleting its app.
+     */
+    disconnect(agentId: string): Promise<void>;
+    /**
+     * Get the Slack installation for an agent.
+     */
+    getInstallation(agentId: string): Promise<SlackInstallation | null>;
+    /**
+     * List all Slack installations (public info only).
+     * Includes both active and pending installations.
+     */
+    listInstallations(): Promise<ChannelInstallationInfo[]>;
+    /**
+     * Discovery metadata for the editor UI.
+     */
+    getInfo(): ChannelPlatformInfo;
+    /**
+     * Check if the provider has credentials and can create/manage Slack apps.
+     * Returns false if no refresh token has been provided via constructor, `configure()`, or storage.
+     */
+    isConfigured(): boolean;
+    /**
+     * Get the SlackAdapter for an installation.
+     * Used internally for message formatting and posting.
+     */
+    getAdapter(installationId: string): SlackAdapter | undefined;
+}
+
+interface SlackManifestClientConfig {
+    token: string;
+    refreshToken: string;
+    onTokenRotation?: (tokens: {
+        token: string;
+        refreshToken: string;
+    }) => Promise<void>;
+}
+/**
+ * Client for Slack's App Manifest API.
+ * Handles programmatic app creation, deletion, and token rotation.
+ */
+declare class SlackManifestClient {
+    #private;
+    constructor(config: SlackManifestClientConfig);
+    /**
+     * Get current tokens (after potential rotation).
+     */
+    getTokens(): {
+        token: string;
+        refreshToken: string;
+    };
+    /**
+     * Update tokens (e.g., from storage on startup).
+     */
+    setTokens(tokens: {
+        token: string;
+        refreshToken: string;
+    }): void;
+    /**
+     * Rotate the configuration tokens.
+     * Slack config access tokens expire after 12 hours; the refresh token is single-use
+     * and each rotation returns a new access token + refresh token pair.
+     *
+     * Concurrent callers share the same in-flight rotation to avoid burning
+     * single-use refresh tokens.
+     */
+    rotateToken(): Promise<void>;
+    /**
+     * Create a new Slack app from a manifest.
+     */
+    createApp(manifest: SlackAppManifest): Promise<SlackAppCredentials>;
+    /**
+     * Delete a Slack app.
+     */
+    deleteApp(appId: string): Promise<void>;
+    /**
+     * Update an existing Slack app's manifest.
+     */
+    updateApp(appId: string, manifest: SlackAppManifest): Promise<void>;
+    /**
+     * Set the app icon via undocumented apps.icon.set API.
+     */
+    setAppIcon(appId: string, imageData: ArrayBuffer): Promise<void>;
+}
+
+/**
+ * Verify a Slack request signature.
+ * @see https://api.slack.com/authentication/verifying-requests-from-slack
+ */
+declare function verifySlackRequest(params: {
+    signingSecret: string;
+    timestamp: string;
+    body: string;
+    signature: string;
+}): boolean;
+/**
+ * Parse URL-encoded form body from Slack slash commands.
+ * Uses URLSearchParams which correctly handles `+` as space.
+ */
+declare function parseSlackFormBody(body: string): Record<string, string>;
+
+/**
+ * Slash command for manifest building.
+ * Simplified version of SlashCommandConfig for manifest generation.
+ */
+interface SlashCommand {
+    command: string;
+    description?: string;
+    usageHint?: string;
+}
+/**
+ * Default bot scopes required for agent functionality.
+ */
+declare const DEFAULT_BOT_SCOPES: readonly ["chat:write", "chat:write.public", "im:write", "channels:history", "channels:read", "groups:history", "groups:read", "im:history", "im:read", "mpim:history", "mpim:read", "app_mentions:read", "users:read", "reactions:write", "files:read"];
+/**
+ * Default bot events to subscribe to.
+ */
+declare const DEFAULT_BOT_EVENTS: readonly ["app_mention", "message.channels", "message.groups", "message.im", "message.mpim"];
+interface BuildManifestOptions {
+    /** Display name for the Slack app */
+    name: string;
+    /** Description shown in Slack */
+    description?: string;
+    /** URL for event webhooks */
+    webhookUrl: string;
+    /** URL for OAuth redirect */
+    oauthRedirectUrl: string;
+    /** URL for slash command webhooks (defaults to webhookUrl) */
+    commandsUrl?: string;
+    /** Slash commands to register */
+    slashCommands?: SlashCommand[];
+}
+/**
+ * Build a Slack app manifest for an agent.
+ */
+declare function buildManifest(options: BuildManifestOptions): SlackAppManifest;
+
+export { DEFAULT_BOT_EVENTS, DEFAULT_BOT_SCOPES, type SlackAppManifest, type SlackBlock, type SlackConfigData, SlackConfigDataSchema, type SlackConfigTokens, type SlackConnectOptions, type SlackInstallation, type SlackInstallationData, SlackInstallationDataSchema, SlackManifestClient, type SlackMessage, type SlackPendingData, SlackPendingDataSchema, type SlackPendingInstallation, SlackProvider, type SlackProviderConfig, type SlashCommandConfig, buildManifest, parseSlackFormBody, verifySlackRequest };