Metadata-Version: 2.4
Name: fw-nodes-mattermost
Version: 0.0.1a2
Summary: Mattermost nodes for Flowire workflow automation
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.13
Requires-Dist: flowire-sdk>=0.0.1a1
Requires-Dist: httpx>=0.26.0
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# Flowire Mattermost Nodes

Mattermost integration nodes for Flowire workflow automation. This package provides nodes for receiving and sending messages with Mattermost.

## Installation

```bash
cd flowire-app/backend
uv pip install fw-nodes-mattermost
```

Then enable the package in your `.env` file:

```bash
# .env (comma-separated list)
INSTALLED_NODE_PACKAGES=fw-nodes-core,fw-nodes-mattermost
```

## Included Nodes

### Triggers

| Node | Description |
|------|-------------|
| `Mattermost Events` | Receive real-time events (messages, reactions, etc.) via WebSocket |
| `Mattermost Outgoing Webhook` | Receive messages from Mattermost channels via outgoing webhooks |
| `Mattermost Slash Command` | Receive slash command invocations from Mattermost |

### Messaging

| Node | Description |
|------|-------------|
| `Mattermost Post Message` | Post a message to a Mattermost channel |

## Usage Examples

### Mattermost Events (WebSocket)

Receive real-time events from Mattermost via WebSocket connection:

```python
# Node configuration:
{
    "credential_id": "your-mattermost-credential",
    "events": ["posted", "reaction_added", "reaction_removed"],
    "channels": ["channel-id-1", "channel-id-2"],  # Optional: filter by channel
    "teams": ["team-id"]  # Optional: filter by team
}

# Outputs:
# - event_type: Type of event (posted, reaction_added, etc.)
# - user_id: User who triggered the event
# - channel_id: Channel where event occurred
# - team_id: Team where event occurred
# - post_id: Post ID (for posted/reaction events)
# - message: Message content (for posted events)
# - emoji_name: Emoji name (for reaction events)
# - sender_name: Username of the sender
# - raw_event: Full event payload
```

**Advantages over webhooks:**

- Real-time events with no polling delay
- Captures events webhooks can't (typing, status changes, etc.)
- No webhook configuration required in Mattermost admin

### Outgoing Webhook

Receive channel messages when a trigger word is used:

```python
# Node configuration:
{
    "validate_token": true,
    "token": "{{project.mattermost-webhook-token}}"
}

# Outputs:
# - text: The message content
# - user_name: Who posted the message
# - channel_name: Where it was posted
# - trigger_word: The word that triggered the webhook
```

### Slash Command

Receive slash command invocations (e.g., `/mycommand args`):

```python
# Node configuration:
{
    "validate_token": true,
    "token": "{{project.mattermost-slash-token}}"
}

# Outputs:
# - command: The slash command (e.g., "/weather")
# - text: Arguments after the command
# - user_name: Who invoked the command
# - response_url: URL for delayed responses
```

### Post Message

Send messages to Mattermost channels:

```python
# Node configuration:
{
    "credential_id": "your-mattermost-credential",
    "channel_id": "{{slash-command.channel_id}}",
    "message": "Hello from Flowire! Processing your request...",
    "root_id": "{{slash-command.post_id}}"  # Optional: reply in thread
}
```

## Mattermost Setup

### Outgoing Webhook

1. Go to **Integrations > Outgoing Webhooks** in Mattermost
2. Click **Add Outgoing Webhook**
3. Set the callback URL to your Flowire webhook endpoint
4. Configure trigger words or channels
5. Copy the token and store it as a project variable

### Slash Command

1. Go to **Integrations > Slash Commands** in Mattermost
2. Click **Add Slash Command**
3. Set the request URL to your Flowire webhook endpoint
4. Configure the command (e.g., `/mycommand`)
5. Copy the token and store it as a project variable

### Credentials for Post Message

1. In Mattermost, go to **Account Settings > Security > Personal Access Tokens**
2. Generate a new token with appropriate permissions
3. In Flowire, create a Mattermost credential with:
   - **Server URL**: Your Mattermost server (e.g., `https://mattermost.example.com`)
   - **Access Token**: The personal access token

## Development

```bash
# Install with dev dependencies
uv sync --all-extras

# Run linter
ruff check .

# Auto-fix lint issues
ruff check . --fix

# Format code
ruff format .

# Run tests
pytest
```

## Project Structure

```
fw-nodes-mattermost/
├── fw_nodes_mattermost/
│   ├── __init__.py
│   └── nodes/
│       ├── __init__.py
│       ├── stream_trigger.py
│       ├── outgoing_webhook.py
│       ├── slash_command.py
│       └── post_message.py
├── tests/
├── pyproject.toml
└── README.md
```

## License

This project is licensed under the [MIT License](LICENSE).
