Files · Anthropic Lead Intake for Pipedrive SMB Lead Enrichment

# Anthropic Lead Intake for Pipedrive SMB Lead Enrichment
 
> Automatically enrich and qualify inbound Pipedrive leads with AI, then route to the right salesperson based on fit score.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade AI systems with the `@reaatech/*` package family.
 
## What it does
 
Webhook from Pipedrive → HMAC signature verification → normalisation via `@reaatech/webhook-relay-core` → Anthropic enrichment (company research, intent signals, fit scoring) → confidence-based routing via `@reaatech/confidence-router` → budget enforcement via `@reaatech/agent-budget-engine` → lead update in Pipedrive with enrichment data. Every step is traced to Langfuse via `@reaatech/llm-cost-telemetry`, and session state is managed through `@reaatech/session-continuity`.
 
## Architecture
 
| Module | Purpose |
|---|---|
| `src/api/pipedrive/webhook.ts` | Webhook ingestion — signature verification, payload parsing, normalisation |
| `src/agents/lead-enricher.ts` | Anthropic enrichment — company research, intent signal extraction, fit scoring, confidence routing |
| `src/lib/budget.ts` | Budget enforcement — daily LLM spend cap with soft/hard limits |
| `src/lib/telemetry.ts` | Observability — Langfuse trace recording for every enrichment cycle |
| `src/services/pipedrive.ts` | Pipedrive API client — deal CRUD via the pipedrive SDK |
| `src/services/session.ts` | Session continuity — lead-level conversation context with token-budgeted compression |
 
## Prerequisites
 
| Variable | Description |
|---|---|
| `PIPEDRIVE_API_TOKEN` | Pipedrive API token for lead CRUD via the pipedrive SDK |
| `PIPEDRIVE_WEBHOOK_SECRET` | Shared secret for HMAC signature verification on inbound webhooks |
| `ANTHROPIC_API_KEY` | Anthropic Claude API key |
| `ANTHROPIC_MODEL` | Claude model ID (default `claude-sonnet-4-6`) |
| `LANGFUSE_PUBLIC_KEY` | Langfuse project public key for trace export |
| `LANGFUSE_SECRET_KEY` | Langfuse project secret key |
| `LANGFUSE_HOST` | Langfuse API host (default `https://cloud.langfuse.com`) |
| `DEFAULT_DAILY_BUDGET` | Daily LLM spend cap in USD (e.g. `5.0`) |
| `AGENT_BUDGET_SOFT_CAP` | Ratio triggering warn state (default `0.8`) |
| `AGENT_BUDGET_HARD_CAP` | Ratio triggering hard stop (default `1.0`) |
| `LOG_LEVEL` | Pino log level (default `info`) |
 
## Quick Start
 
```bash
cp .env.example .env   # edit values with your credentials
pnpm install
pnpm dev               # next dev
```
 
## API Reference
 
### `POST /api/webhook/pipedrive`
 
Pipedrive webhook receiver. Verifies the HMAC signature, normalises the payload, enriches the lead via Anthropic, checks the daily budget, writes enrichment data back to Pipedrive, and records a Langfuse trace.
 
**Request headers:**
```
x-pipedrive-signature: <hmac-sha256-hex>
```
 
**Request body:**
```json
{
  "event": "added.deal",
  "current": { "id": 123, "person_name": "Alice", "email": "alice@example.com", "organization_name": "Acme Corp" },
  "previous": null,
  "meta": { "action": "added", "timestamp": "2026-06-14T12:00:00Z" }
}
```
 
**Response `200`:**
```json
{
  "ok": true,
  "enrichment": { "companyProfile": "Acme Corp is a...", "intentSignals": ["hiring spree", "recent funding"], "fitScore": 85, "summary": "High-fit SMB lead" },
  "routing": { "type": "ROUTE", "target": "enterprise-sales" },
  "dealId": "123"
}
```
 
**Error responses:** `401` (invalid signature), `400` (malformed payload), `429` (budget exceeded), `500` (internal error).
 
### `GET /api/leads`
 
Returns a list of recent deals from Pipedrive.
 
**Response `200`:**
```json
{
  "ok": true,
  "data": [{ "id": 123, "title": "Acme Corp", "personName": "Alice" }]
}
```
 
### `POST /api/leads`
 
Creates a lead manually and runs the full enrichment pipeline (same flow as the webhook).
 
**Request body:**
```json
{
  "name": "Alice",
  "email": "alice@example.com",
  "company": "Acme Corp",
  "phone": "+1-555-0123",
  "description": "Interested in enterprise plan"
}
```
 
**Response `200`:**
```json
{
  "ok": true,
  "enrichment": { "companyProfile": "...", "intentSignals": [], "fitScore": 72, "summary": "..." },
  "routing": { "type": "CLARIFY" },
  "dealId": "456"
}
```
 
### `GET /api/budget`
 
Returns the current budget state for LLM spend.
 
**Response `200`:**
```json
{
  "ok": true,
  "data": { "scopeKey": "*", "totalSpent": 1.25, "dailyLimit": 5.0, "state": "active" }
}
```
 
## Running locally
 
```bash
pnpm install
pnpm test            # vitest run with coverage
pnpm dev             # next dev
```
 
## Project layout
 
```
app/                  Next.js App Router pages + API routes
src/                  services, lib, adapters
tests/                vitest suite (mirrors src/)
packages/             API references for every dependency (read these first)
DEV_PLAN.md           build plan for this recipe
```
 
## License
 
MIT — see [LICENSE](./LICENSE).