Files · Behavioral Email Trigger Agent for WooCommerce Merchants

# Behavioral Email Trigger Agent for WooCommerce Merchants
 
> Send personalized emails based on real-time browsing and cart behavior, not calendar dates.
 
## Problem
 
The marketing contractor at a $3M WooCommerce store relies on a fixed weekly email schedule, missing opportunities to re-engage shoppers who abandon carts or browse specific categories. Without behavioral triggers, they waste budget on irrelevant campaigns and fail to convert high-intent visitors. The contractor has no time to manually monitor analytics and set up complex automation rules. This results in lost revenue and a poor ROI on email marketing spend.
 
## Architecture
 
```
WooCommerce webhook → Next.js route handler → LLM classification (Vercel AI SDK / OpenAI) → Agent Memory storage (@reaatech/agent-memory) → Email decision engine → QStash queue → Klaviyo email send
```
 
Langfuse provides observability across the entire pipeline.
 
## Packages
 
| Package | Version | Role |
|---------|---------|------|
| `@reaatech/agent-memory` | 0.1.0 | Long-term memory facade for storing behavioral events |
| `@reaatech/agent-memory-core` | 0.1.0 | Core types and enums for memory data structures |
| `@reaatech/agent-memory-retrieval` | 0.1.0 | Context injection and memory formatting for LLM prompts |
| `@reaatech/webhook-relay-core` | 0.2.0 | Config loading, logging, and crypto utilities |
| `@reaatech/webhook-relay-tools` | 0.2.0 | MCP server for webhook management tools |
| `ai` | 6.0.197 | Vercel AI SDK — `generateText` for LLM calls |
| `@ai-sdk/openai` | 3.0.68 | OpenAI provider for Vercel AI SDK |
| `zod` | 4.4.3 | Runtime schema validation |
| `langfuse` | 3.38.20 | LLM observability and tracing |
| `@upstash/qstash` | 2.11.0 | Durable task queuing for email decisions |
| `klaviyo-api` | 22.0.1 | Klaviyo email API client |
 
## API Endpoints
 
| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/webhooks/woocommerce` | Receive WooCommerce behavioral events |
| `GET` | `/api/health` | Health check |
| `GET` | `/api/profile/:email` | Retrieve customer behavior profile |
 
## Environment Variables
 
| Variable | Required | Description |
|----------|----------|-------------|
| `OPENAI_API_KEY` | Yes | OpenAI API key for LLM + embeddings |
| `KLAVIYO_API_KEY` | Yes | Klaviyo email API key |
| `QSTASH_TOKEN` | Yes | Upstash QStash token |
| `QSTASH_CURRENT_SIGNING_KEY` | Yes | QStash current signing key |
| `QSTASH_NEXT_SIGNING_KEY` | Yes | QStash next signing key |
| `LANGFUSE_PUBLIC_KEY` | No | Langfuse public key (tracing) |
| `LANGFUSE_SECRET_KEY` | No | Langfuse secret key (tracing) |
| `LANGFUSE_BASE_URL` | No | Langfuse host (default `https://cloud.langfuse.com`) |
| `WOOCOMMERCE_WEBHOOK_SECRET` | Yes | HMAC secret for WooCommerce webhook verification |
 
## Development
 
```bash
pnpm install
pnpm dev          # next dev
pnpm test         # vitest run with coverage
pnpm typecheck    # tsc --noEmit
pnpm lint         # eslint
```
 
## Testing
 
Tests use MSW (Mock Service Worker) to mock external APIs (OpenAI, Klaviyo, QStash, Langfuse). Services are tested both in isolation (vi.mock) and integrated (real instances with MSW). Coverage thresholds are set at 90% across lines, branches, functions, and statements for runtime code.
 
## License
 
MIT — see [LICENSE](./LICENSE).