npm package: @openverb/crm
Description: The official OpenVerb CRM Master Template. A developer-native, protocol-compliant CRM with AI-powered communication workflows.
Latest version: 0.1.0

# OpenVerb CRM ✨

An embeddable, developer-native CRM built specifically for Next.js applications. 
OpenVerb CRM gives you a beautifully designed, SaaS-ready dashboard out-of-the-box, without locking you into proprietary databases or expensive per-seat email integrations.

It uses a "Master Template" pattern (similar to Shadcn UI). You don't `npm install` a massive blackbox package; you run the CLI, and the raw React components, database proxies, and API routes copy directly into your repository. You own the code forever.

## Architecture

OpenVerb CRM is defined by two profound architectural decoupling concepts:
**1. BYOD (Bring Your Own Database)**
**2. BYOP (Bring Your Own Provider)**

### The Database Adapter (BYOD)
Instead of forcing you to migrate your system to Postgres, MySQL, or Mongo, OpenVerb operates over a generic `db` object interface found in `lib/crm/store.ts`.
By default, this is an in-memory database mock so you can boot the dashboard in 10 seconds and test it out.

When you are ready for production, you just override the proxy:
```typescript
// in lib/crm/store.ts
// Replace the mock export with your Prisma Client
export { default as db } from '@/lib/prisma'
```
Because the CRM internally executes highly deterministic verbs (like `await db.contacts.findMany()`), it plugs into a Prisma/Drizzle schema effortlessly!

### The Email Adapter (BYOP)
Why pay Mailchimp $200/month when you can route your emails through Amazon SES for pennies? 
We built an abstraction layer in `lib/crm/email-adapter.ts` that dynamically injects the sending API for your infrastructure.

Simply set your `.env` file:
```env
# Available: resend, postmark, sendgrid, mailchimp, ses
CRM_EMAIL_PROVIDER=resend
RESEND_API_KEY=re_123456789
```
The CRM handles standardizing your API keys entirely.

### Two-Way Webhooks (Receiving Mail)
Sending mail is easy. *Receiving* mail to let users reply to the CRM natively is the holy grail.
OpenVerb provides a universal inbound webhook route:
`POST /api/crm/webhooks/[provider]`

It natively parses the raw HTTP webhooks from Sendgrid, Postmark, Mailchimp, and AWS SES into an `inbox.receive_message` OpenVerb. The CRM automatically threads the inbound message into the customer's contact history, firing real-time UI updates to your dashboard!

## Features out-of-the-box

- **Theming:** Full `next-themes` and Shadcn variable support. Dark/Light mode just inherits from your app's `:root`.
- **Inbox Engine:** Full threading capability, open/closed workflows, and unread counts.
- **Segments Engine:** Build arbitrary dynamic lists from Contact metadata.
- **AI Copilot Ready:** All actions are structured as "OpenVerb" schemas internally, meaning an LLM can trigger CRM actions implicitly using function calling (`executeVerb('draft.send', {...})`).
- **Campaigns:** Draft and schedule templated broadcasts with analytics abstractions.
- **Horizontal Ecosystem (Optional):** Link multiple independent Next.js apps into a unified dashboard using the [API Federation Guide](./ECOSYSTEM.md).
- **Commercial Licensing Ready:** Includes a "Phone-Home" license verification system for SaaS owners. See the [Management Guide](./SaaS_MANAGEMENT.md).

## Installation

Run the installer straight into any existing Next.js + Tailwind project:

```bash
npx openverb-crm init
```

*This CLI generator script will ask which directory to slide the CRM into, ensuring it drops alongside your existing architecture perfectly.*