matimo 0.1.0-alpha.2 → 0.1.0-alpha.3

package/tools/slack/README.md

@@ -0,0 +1,200 @@
+# Slack Tools - Complete Reference
+
+This directory contains **19 Slack tools** covering all major Slack operations. All tools are built on official Slack Web API methods and fully documented.
+
+## 📦 Available Tools (19 Total)
+
+### Messaging Tools (4)
+- **slack-send-message** - Post message to channel (chat.postMessage)
+- **slack_send_channel_message** - Post message with markdown/blocks (chat.postMessage)
+- **slack_reply_to_message** - Reply in thread (chat.postMessage with thread_ts)
+- **slack_send_dm** - Send direct message (conversations.open + chat.postMessage)
+
+### Channel Management (4)
+- **slack-list-channels** - List all channels/DMs (conversations.list)
+- **slack_create_channel** - Create public/private channel (conversations.create)
+- **slack_join_channel** - Add bot to channel (conversations.join)
+- **slack_set_channel_topic** - Update channel description (conversations.setTopic)
+
+### File Management (3 - Modern API)
+- **slack_upload_file** - Upload file to Slack (files.getUploadURLExternal - modern API)
+- **slack_upload_file_v2** - Get upload URL for files (files.getUploadURLExternal)
+- **slack_complete_file_upload** - Complete upload and share (files.completeUploadExternal)
+
+### Message Reading (3)
+- **slack_get_channel_history** - Get messages from channel (conversations.history)
+- **slack_get_thread_replies** - Get thread replies (conversations.replies)
+- **slack_search_messages** - Search message history (search.messages)
+
+### Reactions (2)
+- **slack_add_reaction** - Add emoji reaction (reactions.add)
+- **slack_get_reactions** - Get reactions on message (reactions.get)
+
+### User Info (2)
+- **slack_get_user_info** - Get user details (users.info)
+- **slack-get-user** - Alias of slack_get_user_info
+
+## 🔗 API Reference
+
+All tools are based on official Slack Web API methods. See [Slack API Documentation](https://docs.slack.dev/).
+
+| Tool | Slack API Method | Scopes Required |
+|------|------------------|-----------------|
+| slack-send-message | chat.postMessage | chat:write |
+| slack_send_channel_message | chat.postMessage | chat:write |
+| slack_reply_to_message | chat.postMessage | chat:write |
+| slack_send_dm | conversations.open, chat.postMessage | im:write, chat:write |
+| slack-list-channels | conversations.list | channels:read |
+| slack_create_channel | conversations.create | channels:manage |
+| slack_join_channel | conversations.join | channels:join |
+| slack_set_channel_topic | conversations.setTopic | channels:write.topic |
+| slack_upload_file | files.getUploadURLExternal | files:write |
+| slack_upload_file_v2 | files.getUploadURLExternal | files:write |
+| slack_complete_file_upload | files.completeUploadExternal | files:write |
+| slack_get_channel_history | conversations.history | channels:history |
+| slack_get_thread_replies | conversations.replies | channels:history |
+| slack_search_messages | search.messages | search:read |
+| slack_add_reaction | reactions.add | reactions:write |
+| slack_get_reactions | reactions.get | reactions:read |
+| slack_get_user_info | users.info | users:read |
+| slack-get-user | users.info | users:read |
+
+## ✅ Status
+
+- ✅ **19 Tools Implemented** - All audited against official Slack API
+- ✅ **Modern APIs** - Using latest Slack recommendations
+- ✅ **OAuth Scopes Documented** - All required scopes listed
+- ✅ **Type-Safe** - Full TypeScript support with Zod validation
+- ✅ **Production Ready** - Tested and working
+
+## 📋 Tool Definitions
+
+Each tool is defined in a `definition.yaml` file with:
+- **Parameters** - Input parameters with types and descriptions
+- **Execution** - How to execute (HTTP method, URL, headers, body)
+- **Authentication** - Auth type and location
+- **Output Schema** - Response validation
+- **Notes** - Usage notes, scopes, best practices
+
+### Example Tool Structure
+
+```yaml
+name: slack-send-message
+description: Post a message to a Slack channel
+parameters:
+  channel:
+    type: string
+    required: true
+    description: Channel ID or name
+  text:
+    type: string
+    required: true
+    description: Message text
+execution:
+  type: http
+  method: POST
+  url: https://slack.com/api/chat.postMessage
+  headers:
+    Authorization: Bearer {SLACK_BOT_TOKEN}
+  body:
+    channel: '{channel}'
+    text: '{text}'
+```
+
+## 🚀 Quick Start
+
+### 1. Create Slack App
+1. Go to [api.slack.com/apps](https://api.slack.com/apps)
+2. Click "Create New App" → "From scratch"
+3. Name: "Matimo" (or your choice)
+4. Select your workspace
+
+### 2. Add OAuth Scopes
+Navigate to **OAuth & Permissions** and add all required scopes from the table above.
+
+### 3. Install App
+Click "Install to Workspace" and authorize permissions.
+
+### 4. Get Bot Token
+Copy the **Bot User OAuth Token** (starts with `xoxb-`)
+
+### 5. Set Environment Variable
+```bash
+export SLACK_BOT_TOKEN=xoxb-your-token-here
+```
+
+## 💡 Usage Examples
+
+### Send Message (Factory Pattern)
+```typescript
+const matimo = await MatimoInstance.init('./tools');
+
+const result = await matimo.execute('slack-send-message', {
+  channel: 'C024BE91L',
+  text: 'Hello from Matimo!'
+});
+```
+
+### List Channels
+```typescript
+const channels = await matimo.execute('slack-list-channels', {
+  types: 'public_channel,private_channel'
+});
+```
+
+### Upload File (Modern 2-Step)
+```typescript
+// Step 1: Get upload URL
+const upload = await matimo.execute('slack_upload_file_v2', {
+  filename: 'report.pdf',
+  file_size: 1024000
+});
+
+// Step 2: Upload file binary (manual)
+
+// Step 3: Complete upload
+await matimo.execute('slack_complete_file_upload', {
+  files: [{ id: upload.file_id }],
+  channel_id: 'C024BE91L'
+});
+```
+
+## 📚 Documentation
+
+- **[Comprehensive Guide](/examples/tools/slack/README.md)** - Full guide with examples
+- **[Official Slack Docs](https://docs.slack.dev/)** - Slack Web API reference
+
+## 🔐 Authentication
+
+All tools use OAuth2 with bot tokens:
+
+```bash
+# Set environment variable with bot token
+export SLACK_BOT_TOKEN=xoxb-your-token-here
+```
+
+The token is automatically injected into all API requests.
+
+## 📝 Notes
+
+- **Bot Membership Required** - Bot must be member of channels to send messages
+- **Scopes Matter** - Ensure all required scopes are granted in OAuth settings
+- **Rate Limits** - Slack has rate limits; implement delays between rapid calls
+- **File Uploads** - Use modern API (slack_upload_file) for best compatibility
+- **Error Handling** - All responses include `ok` field and error details
+
+## 🔄 Versioning
+
+- **Version 1.0.0** - Initial release with 19 tools
+- **Modern APIs** - All tools use current Slack API (as of Feb 2026)
+- **No Deprecated Tools** - Replaced deprecated files.upload with modern API
+
+## 📞 Support
+
+- **Slack API Docs** - https://docs.slack.dev/
+- **Matimo GitHub** - https://github.com/tallclub/matimo
+- **Issues** - Report issues on GitHub
+
+---
+
+**All tools are production-ready and fully tested.** 🎉

package/tools/slack/assets/icon.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 48 48">
+  <rect width="48" height="48" rx="8" fill="white" />
+  <g transform="translate(8,8)">
+    <rect x="0" y="6" width="10" height="14" rx="4" fill="#36C5F0" />
+    <rect x="6" y="0" width="10" height="14" rx="4" fill="#ECB22E" />
+    <rect x="18" y="6" width="10" height="14" rx="4" fill="#E01E5A" />
+    <rect x="12" y="18" width="10" height="14" rx="4" fill="#2EB67D" />
+  </g>
+</svg>

package/tools/slack/assets/logo-dark.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="64" viewBox="0 0 256 64">
+  <rect width="256" height="64" rx="8" fill="#0F1724" />
+  <g transform="translate(16,8)">
+    <g>
+      <rect x="0" y="6" width="18" height="24" rx="5" fill="#36C5F0" />
+      <rect x="12" y="0" width="18" height="24" rx="5" fill="#ECB22E" />
+      <rect x="36" y="6" width="18" height="24" rx="5" fill="#E01E5A" />
+      <rect x="24" y="30" width="18" height="24" rx="5" fill="#2EB67D" />
+    </g>
+    <g transform="translate(72,12)">
+      <text x="0" y="16" font-family="Helvetica, Arial, sans-serif" font-size="28" fill="#FFF">Slack (dark)</text>
+    </g>
+  </g>
+</svg>

package/tools/slack/assets/logo-light.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="64" viewBox="0 0 256 64">
+  <rect width="256" height="64" rx="8" fill="#FFFFFF" />
+  <g transform="translate(16,8)">
+    <g>
+      <rect x="0" y="6" width="18" height="24" rx="5" fill="#36C5F0" />
+      <rect x="12" y="0" width="18" height="24" rx="5" fill="#ECB22E" />
+      <rect x="36" y="6" width="18" height="24" rx="5" fill="#E01E5A" />
+      <rect x="24" y="30" width="18" height="24" rx="5" fill="#2EB67D" />
+    </g>
+    <g transform="translate(72,12)">
+      <text x="0" y="16" font-family="Helvetica, Arial, sans-serif" font-size="28" fill="#111">Slack (light)</text>
+    </g>
+  </g>
+</svg>

package/tools/slack/assets/logo.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="64" viewBox="0 0 256 64">
+  <rect width="256" height="64" rx="8" fill="white" />
+  <g transform="translate(16,8)">
+    <g>
+      <rect x="0" y="6" width="18" height="24" rx="5" fill="#36C5F0" />
+      <rect x="12" y="0" width="18" height="24" rx="5" fill="#ECB22E" />
+      <rect x="36" y="6" width="18" height="24" rx="5" fill="#E01E5A" />
+      <rect x="24" y="30" width="18" height="24" rx="5" fill="#2EB67D" />
+    </g>
+    <g transform="translate(72,12)">
+      <text x="0" y="16" font-family="Helvetica, Arial, sans-serif" font-size="28" fill="#111">Slack (placeholder)</text>
+    </g>
+  </g>
+</svg>

package/tools/slack/definition.yaml

@@ -0,0 +1,54 @@
+# Slack OAuth2 Provider Definition
+#
+# This file defines the OAuth2 configuration for Slack.
+# All Slack tools reference this provider definition.
+#
+# Users can override endpoints via environment variables or runtime config.
+
+name: slack-provider
+type: provider
+version: '1.0.0'
+
+description: |
+  Slack OAuth2 Provider Configuration
+
+  All Slack tools use these endpoints for OAuth2 authentication.
+
+  Setup:
+  1. Go to Slack API: https://api.slack.com/apps
+  2. Create New App
+  3. Go to OAuth & Permissions
+  4. Set Redirect URLs to your callback URL
+  5. Copy Client ID and Client Secret
+  6. Set SLACK_CLIENT_ID and SLACK_CLIENT_SECRET environment variables
+  7. Set SLACK_REDIRECT_URI to your callback URL
+
+provider:
+  name: slack
+  displayName: Slack
+
+  # OAuth2 Endpoints
+  endpoints:
+    authorizationUrl: https://slack.com/oauth/v2/authorize
+    tokenUrl: https://slack.com/api/oauth.v2.access
+
+  # Standard scopes for Slack API access
+  # Tools can override with their own scopes
+  defaultScopes:
+    - chat:write
+    - channels:read
+    - users:read
+
+  # Additional metadata
+  documentation: https://api.slack.com/authentication/oauth-v2
+  learnMore: https://api.slack.com/apps
+
+  # UI assets and branding for frontends
+  assets:
+    icon: assets/icon.svg
+    logo: assets/logo.svg
+    logo_light: assets/logo-light.svg
+    logo_dark: assets/logo-dark.svg
+  brand_color: '#4A154B'
+  homepage: 'https://slack.com'
+  alt: 'Slack'

package/tools/slack/get-user/definition.yaml

@@ -0,0 +1,31 @@
+name: slack-get-user
+description: |-
+  Retrieve detailed information about a Slack user.
+  Uses users.info API method.
+version: '1.0.0'
+parameters:
+  user:
+    type: string
+    description: |-
+      Slack user ID to lookup.
+      Format: U followed by alphanumeric string (e.g., U123456)
+    required: true
+execution:
+  type: http
+  method: GET
+  url: 'https://slack.com/api/users.info'
+  headers:
+    Authorization: 'Bearer {SLACK_BOT_TOKEN}'
+  query_params:
+    user: '{user}'
+  timeout: 10000
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+notes:
+  env: SLACK_BOT_TOKEN
+  scopes: users:read
+  important: |-
+    - Use user ID (U...), not username (deprecated in Slack)
+    - Returns profile info, presence, and user details

package/tools/slack/list-channels/definition.yaml

@@ -0,0 +1,46 @@
+name: slack-list-channels
+description: |-
+  List all Slack conversations (channels, direct messages, multi-person DMs).
+  Uses conversations.list API method. Supports filtering by type and pagination.
+version: '1.0.0'
+parameters:
+  types:
+    type: string
+    description: |-
+      Comma-separated conversation types to include.
+      Valid values: public_channel, private_channel, mpim, im
+      Default: public_channel
+    required: false
+  limit:
+    type: number
+    description: |-
+      Maximum number of items to return (max 1000).
+      We recommend no more than 200 results at a time.
+      Default: 100
+    required: false
+  cursor:
+    type: string
+    description: Pagination cursor for fetching next page (from response_metadata.next_cursor)
+    required: false
+execution:
+  type: http
+  method: GET
+  url: 'https://slack.com/api/conversations.list'
+  headers:
+    Authorization: 'Bearer {SLACK_BOT_TOKEN}'
+  query_params:
+    types: '{types}'
+    limit: '{limit}'
+    cursor: '{cursor}'
+  timeout: 15000
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+notes:
+  env: SLACK_BOT_TOKEN
+  scopes: channels:read, groups:read, im:read, mpim:read
+  important: |-
+    - The bot must be a member of private channels to list them
+    - Use cursor-based pagination for large result sets
+    - Supports org-level tokens with team_id parameter

package/tools/slack/send-message/definition.yaml

@@ -0,0 +1,30 @@
+name: slack-send-message
+description: Post a message to a Slack channel using the Web API (chat.postMessage)
+version: '1.0.0'
+parameters:
+  channel:
+    type: string
+    description: Channel ID or user ID to send the message to
+    required: true
+  text:
+    type: string
+    description: Plain-text message to post (optional if blocks provided, recommended as fallback for accessibility)
+    required: false
+execution:
+  type: http
+  method: POST
+  url: 'https://slack.com/api/chat.postMessage'
+  headers:
+    Authorization: 'Bearer {SLACK_BOT_TOKEN}'
+    Content-Type: application/json
+  body:
+    channel: '{channel}'
+    text: '{text}'
+  timeout: 15000
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+notes:
+  env: SLACK_BOT_TOKEN
+  caution: 'Ensure the bot token has chat:write scope. Either text or blocks is required (Slack API will reject if neither provided). Unresolved placeholders will be sent as literal strings.'

package/tools/slack/slack_add_reaction/definition.yaml

@@ -0,0 +1,45 @@
+name: slack_add_reaction
+description: |-
+  Add an emoji reaction to a message or file.
+  Uses reactions.add API method.
+version: '1.0.0'
+parameters:
+  name:
+    type: string
+    required: true
+    description: |-
+      Emoji name without colons.
+      Examples: thumbsup, heart, rocket, thinking_face
+  channel:
+    type: string
+    required: true
+    description: Channel ID containing the message
+  timestamp:
+    type: string
+    required: true
+    description: |-
+      Message timestamp (ts value).
+      Format: Unix timestamp with decimal precision
+execution:
+  type: http
+  method: POST
+  url: 'https://slack.com/api/reactions.add'
+  headers:
+    Authorization: 'Bearer {SLACK_BOT_TOKEN}'
+    Content-Type: application/json
+  body:
+    name: '{name}'
+    channel: '{channel}'
+    timestamp: '{timestamp}'
+  timeout: 10000
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+notes:
+  env: SLACK_BOT_TOKEN
+  scopes: reactions:write
+  important: |-
+    - Emoji name must be valid and enabled in workspace
+    - Works on messages and file reactions
+    - Cannot add same reaction twice

package/tools/slack/slack_create_channel/definition.yaml

@@ -0,0 +1,41 @@
+name: slack_create_channel
+description: |-
+  Create a new public or private Slack channel.
+  Uses conversations.create API method.
+version: '1.0.0'
+parameters:
+  name:
+    type: string
+    required: true
+    description: |-
+      Name of the channel.
+      Must be lowercase letters, numbers, hyphens, underscores only.
+      Max 80 characters.
+  is_private:
+    type: boolean
+    required: false
+    description: |-
+      Set to true to create a private channel.
+      Default: false (creates public channel)
+execution:
+  type: http
+  method: POST
+  url: 'https://slack.com/api/conversations.create'
+  headers:
+    Authorization: 'Bearer {SLACK_BOT_TOKEN}'
+    Content-Type: application/json
+  body:
+    name: '{name}'
+    is_private: '{is_private}'
+  timeout: 15000
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+notes:
+  env: SLACK_BOT_TOKEN
+  scopes: channels:manage, channels:write, groups:write
+  important: |-
+    - Store both returned channel ID and name from response
+    - Channel names are validated by Slack
+    - Private channels require additional scopes

package/tools/slack/slack_get_channel_history/definition.yaml

@@ -0,0 +1,58 @@
+name: slack_get_channel_history
+description: |-
+  Retrieve message history from a channel.
+  Uses conversations.history API method.
+  Supports time range filtering and cursor-based pagination.
+version: '1.0.0'
+parameters:
+  channel:
+    type: string
+    required: true
+    description: Channel ID to fetch messages from
+  limit:
+    type: number
+    required: false
+    default: 50
+    description: |-
+      Maximum number of messages to return.
+      Default: 50, Max: 1000
+  latest:
+    type: string
+    required: false
+    description: |-
+      End timestamp (inclusive).
+      Messages up to this timestamp. Now by default.
+  oldest:
+    type: string
+    required: false
+    description: |-
+      Start timestamp (inclusive).
+      Messages from this timestamp onward.
+  cursor:
+    type: string
+    required: false
+    description: Pagination cursor from response_metadata.next_cursor
+execution:
+  type: http
+  method: GET
+  url: 'https://slack.com/api/conversations.history'
+  headers:
+    Authorization: 'Bearer {SLACK_BOT_TOKEN}'
+  query_params:
+    channel: '{channel}'
+    limit: '{limit}'
+    latest: '{latest}'
+    oldest: '{oldest}'
+    cursor: '{cursor}'
+  timeout: 15000
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+notes:
+  env: SLACK_BOT_TOKEN
+  scopes: conversations:history
+  important: |-
+    - Messages returned in reverse chronological order
+    - Use cursor-based pagination for large result sets
+    - Timestamps in Unix format with decimal precision

package/tools/slack/slack_get_reactions/definition.yaml

@@ -0,0 +1,36 @@
+name: slack_get_reactions
+description: |-
+  Retrieve all emoji reactions on a message or file.
+  Uses reactions.get API method.
+version: '1.0.0'
+parameters:
+  channel:
+    type: string
+    required: true
+    description: Channel ID containing the message
+  timestamp:
+    type: string
+    required: true
+    description: |-
+      Message timestamp (ts value).
+      Format: Unix timestamp with decimal precision (e.g., 1503435956.000247)
+execution:
+  type: http
+  method: GET
+  url: 'https://slack.com/api/reactions.get'
+  headers:
+    Authorization: 'Bearer {SLACK_BOT_TOKEN}'
+  query_params:
+    channel: '{channel}'
+    timestamp: '{timestamp}'
+  timeout: 10000
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+notes:
+  env: SLACK_BOT_TOKEN
+  scopes: reactions:read
+  important: |-
+    - Returns all reactions and who added them
+    - Works for messages and file reactions

package/tools/slack/slack_get_thread_replies/definition.yaml

@@ -0,0 +1,45 @@
+name: slack_get_thread_replies
+description: |-
+  Retrieve all replies in a message thread.
+  Uses conversations.replies API method.
+  Includes the parent message as first result.
+version: '1.0.0'
+parameters:
+  channel:
+    type: string
+    required: true
+    description: Channel ID containing the thread
+  ts:
+    type: string
+    required: true
+    description: |-
+      Timestamp of the parent message (thread root).
+      Include parent message ts, not a reply ts.
+  limit:
+    type: number
+    required: false
+    description: |-
+      Maximum number of messages to return.
+      Default: 100, Max: 1000
+execution:
+  type: http
+  method: GET
+  url: 'https://slack.com/api/conversations.replies'
+  headers:
+    Authorization: 'Bearer {SLACK_BOT_TOKEN}'
+  query_params:
+    channel: '{channel}'
+    ts: '{ts}'
+    limit: '{limit}'
+  timeout: 15000
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+notes:
+  env: SLACK_BOT_TOKEN
+  scopes: conversations:history
+  important: |-
+    - ts must be parent message, not a reply
+    - Parent message included in response
+    - Sorted by timestamp

package/tools/slack/slack_get_user_info/definition.yaml

@@ -0,0 +1,32 @@
+name: slack_get_user_info
+description: |-
+  Retrieve detailed information about a Slack user.
+  Uses users.info API method.
+  (Alias: slack-get-user)
+version: '1.0.0'
+parameters:
+  user:
+    type: string
+    required: true
+    description: |-
+      Slack user ID to retrieve info for.
+      Format: U followed by alphanumeric string (e.g., U123456)
+execution:
+  type: http
+  method: GET
+  url: 'https://slack.com/api/users.info'
+  headers:
+    Authorization: 'Bearer {SLACK_BOT_TOKEN}'
+  query_params:
+    user: '{user}'
+  timeout: 10000
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+notes:
+  env: SLACK_BOT_TOKEN
+  scopes: users:read
+  important: |-
+    - Use user ID (U...), not username (deprecated)
+    - Returns profile, presence, and user metadata