# Deal Flow for Mautic

**Revenue pipeline management with Buying Committee Intelligence.**

Deal Flow brings deal tracking, pipeline management, and revenue forecasting directly into Mautic — no external CRM needed. Track deals through customizable stages, map buying committees with multi-contact role labeling, and trigger campaigns based on deal activity.

## Key Features

**Pipeline Management**
- Drag-and-drop kanban board with health indicators
- Customizable pipelines and stages with win probabilities
- Deal list view with search, filters, and batch actions

**Buying Committee Intelligence**
- Associate multiple contacts with each deal
- Role labeling: Decision Maker, Champion, Technical Evaluator, Executive Sponsor, End User
- Contact timeline injection — deals appear on contact activity history
- Deals tab on contact view page

**Campaign Integration**
- Campaign condition: "Contact has matching Deal Flow deal"
- Campaign action: "Move Deal Flow deal to stage"
- 5 segment filters: pipeline, stage, status, stakeholder role, amount

**Revenue Forecasting**
- Weighted pipeline forecast (probability-adjusted)
- Win rate tracking and deal velocity metrics
- Average days to close, cycle time, monthly close rate
- At-risk deal analysis (overdue close dates, stale activity)
- Owner leaderboard and stage coverage

**Integrations**
- REST API for all deal operations
- Inbound webhooks with per-source HMAC signing
- Outbound webhooks via Mautic's native webhook system
- Global search integration
- 8+ dashboard widgets

## Requirements

- Mautic 7.x
- PHP 8.2+

## Installation

```bash
composer require firmoptic/mautic-deal-flow-bundle
php bin/console mautic:plugins:reload
```

## Quick Start

1. **Reload plugins** — Go to Settings > Plugins and click "Install/Upgrade Plugins"
2. **Create a pipeline** — Navigate to Deal Flow > Settings > Pipelines
3. **Add stages** — Create stages with win probabilities (e.g., Prospect 10%, Qualified 25%, Proposal 50%, Negotiation 75%, Closed Won 100%)
4. **Create your first deal** — Go to Deal Flow > New Deal, fill in title, amount, and assign to a pipeline
5. **Add stakeholders** — Associate contacts with roles on the deal edit form

## Configuration

Go to Settings > Configuration > Deal Flow to configure:
- Default currency (USD, EUR, GBP, etc.)
- Pipeline board preferences
- Risk alert thresholds

## Dashboard Widgets

Add Deal Flow widgets to your Mautic dashboard:
- Pipeline Summary (deal count, value, forecast)
- Stage Breakdown (funnel view)
- Revenue Over Time (weekly/cumulative)
- Closing This Month
- Owner Leaderboard
- Stale Deals Alert
- Weighted Forecast
- Overdue Tasks

## Pricing

$149 one-time license + $49/year renewal for updates and support.

## Support

- Issues: https://github.com/tncSean/firmoptic-mautic/issues
- Email: support@firmoptic.com
- Docs: https://firmoptic.com/deal-flow/docs

## License

GPL-3.0-or-later. See [LICENSE](LICENSE).

---

## API Reference

Deal Flow exposes REST endpoints under the Mautic API. Use the same authentication as your Mautic API. Deal Flow permissions apply to API callers.

### Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/dealflow/deals` | List deals |
| POST | `/api/dealflow/deals` | Create a deal |
| GET | `/api/dealflow/deals/{id}` | Get deal details |
| PATCH | `/api/dealflow/deals/{id}` | Update a deal |
| POST | `/api/dealflow/deals/{id}/stage` | Move deal to stage |
| POST | `/api/dealflow/deals/{id}/contacts` | Add contact association |
| POST | `/api/dealflow/deals/{id}/notes` | Add a note |
| POST | `/api/dealflow/deals/{id}/tasks` | Create a task |
| PATCH | `/api/dealflow/deals/{id}/tasks/{taskId}` | Update a task |
| POST | `/api/dealflow/deals/{id}/attachments` | Upload attachment |
| GET | `/api/dealflow/deals/{id}/timeline` | Get deal timeline |

### Example: Create a Deal

```bash
curl -X POST "$MAUTIC_BASE_URL/api/dealflow/deals" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Acme Renewal",
    "company_id": 42,
    "owner_id": 7,
    "amount": "25000.00",
    "currency": "USD",
    "contacts": [{"email": "buyer@example.com", "label": "Decision Maker"}]
  }'
```

## Inbound Webhooks

Path: `POST /dealflow/webhooks/inbound/{sourceKey}`

Create webhook credentials under Deal Flow > Settings > Inbound Webhooks. Each source gets its own endpoint key and HMAC secret.

Supported signature headers:
- `X-DealFlow-Timestamp` + `X-DealFlow-Signature` (timestamped HMAC SHA-256)
- `Webhook-Signature` (Mautic-compatible base64 HMAC SHA-256)

```bash
TIMESTAMP=$(date +%s)
BODY='{"external_ref":"crm-123","note_body":"Discovery completed"}'
SIGNATURE=$(printf '%s.%s' "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -binary | xxd -p -c 256)

curl -X POST "$MAUTIC_BASE_URL/dealflow/webhooks/inbound/src_example" \
  -H "Content-Type: application/json" \
  -H "X-DealFlow-Timestamp: $TIMESTAMP" \
  -H "X-DealFlow-Signature: $SIGNATURE" \
  -d "$BODY"
```
