# plugin-crm

`@fayz-ai/plugin-crm` · beta · Partial capability

Every business that sells anything needs a way to track who's interested, what's in motion, and what's about to close. Most verticals end up rebuilding the same CRM badly. plugin-crm is the one sales engine — leads, a drag-style pipeline, deals, quotes, and activities — that snaps into a defineSaas app and adapts to the vertical underneath it.

## Overview

A lean CRM for service businesses: leads become deals, deals move through a visual pipeline, and activities and quotes record the history. The plugin mounts the `/sales` page (route and navigation), dashboard widgets and a Settings tab. The `quotes`, `activities` and `pipeline` modules can be switched on and off by config.

On the data side, the CRM follows the Fayz archetype pattern: **leads are people** (`saas_core.persons`, `kind='lead'`) and **deals and quotes are orders** (`saas_core.orders`, `kind='deal'`/`quote`). The plugin adds extension tables in `public` — `pipelines`, `pipeline_stages`, `lead_sources`, `crm_tags`, `crm_activities` and `deal_extensions` — across five migrations covering the base, activities, views + RLS and the seed for a default pipeline. Supabase provider with mock fallback.

When a lead is approved, the CRM can promote the person (`persons.kind`) and create the record in the configured extension table (`clientConversion`). For AI, it exposes `countCustomers` and `listLeads`. Status **beta / partial capability**: ready to dogfood, still evolving.

## When to use it

- Track leads and deals in a visual funnel.
- Issue quotes and log contact activities.
- Turn an approved lead into a customer without leaving the flow.

## Specs

- **Package:** `@fayz-ai/plugin-crm`
- **Version:** 0.3.0
- **Status:** beta
- **Capability:** Partial capability
- **Product type:** Management (Admin/SaaS)
- **Stable channel:** `^0.3.0`
- **Migrations:** 5 migration(s)
- **Factory:** `createCrmPlugin()`

## Data model

Convention: plg_ + tenant_id + RLS.

- `plg_crm_pipelines` — name, is_default, is_active
- `plg_crm_pipeline_stages` — pipeline_id, name, order, color, probability, is_won
- `plg_crm_lead_sources` — name, is_active
- `plg_crm_tags` — name, color, is_active
- `plg_crm_deal_extensions` — order_id, pipeline_id, stage_id, probability, expected_close_date, lead_id
- `plg_crm_activity_types` — name, is_active
- `plg_crm_activities` — deal_id, lead_id, contact_id, contact_name, activity_type, title

## AI tools

| id | mode | description |
| --- | --- | --- |
| `crm.count-customers` | read | Returns the number of active customers/clients. |
| `crm.list-leads` | read | Lists leads with optional filters. |

## Integrations

No hosted connector — external providers come in via the connector spine (`@fayz-ai/core`).

## Integrate

Add the plugin to surfaces.admin.plugins in your app's app.manifest.json and run the doctor to validate:

```json
{ "surfaces": { "admin": { "plugins": [ { "id": "crm", "enabled": true } ] } } }
```

```bash
npx fayz doctor
```