Files · OpenAI Lead Intake for BigCommerce Small Business Sales

# OpenAI Lead Intake for BigCommerce Small Business Sales
 
> Automatically qualify, route, and respond to BigCommerce contact-form leads so no customer inquiry falls through the cracks.
 
A Next.js API that receives BigCommerce contact-form webhooks, classifies inquiry intent via `@reaatech/confidence-router`, routes to specialist handlers via `@reaatech/agent-handoff-routing`, generates AI auto-replies via OpenAI, and maintains cross-email conversation context via `@reaatech/session-continuity`.
 
## Architecture
 
```
Webhook → Repair (structured-repair-core) → Classify (confidence-router)
    → Route (agent-handoff-routing) → Handle (sales / support / returns / human_triage)
```
 
The entire flow is observability-backed with Langfuse. Malformed payloads are normalized by `@reaatech/structured-repair-core` before processing.
 
## Prerequisites
 
- BigCommerce store with API access
- OpenAI API key
- Slack workspace with bot token
- SendGrid account with verified sender
- Langfuse account (free tier works)
- HubSpot account (for support ticket creation)
 
## Getting Started
 
```bash
pnpm install
cp .env.example .env        # fill in your keys
pnpm dev                    # start Next.js dev server
pnpm tsx src/scripts/register-webhooks.ts   # register BigCommerce webhook
```
 
## API Reference
 
### `POST /api/webhooks/bigcommerce`
 
Receives BigCommerce contact-form submission events and processes the lead pipeline.
 
| Response Code | Condition |
|---|---|
| `200` | Successfully handled (`{ handled: true, target, sessionId }`) |
| `200` | Test/ping event (`{ handled: false, reason: "test_event" }`) |
| `400` | Missing email in payload |
| `401` | Invalid HMAC signature |
| `500` | Internal error |
 
### `GET /api/webhooks/bigcommerce`
 
Returns `{ status: "ok", service: "bigcommerce-lead-intake" }`.
 
### `GET /api/health`
 
Returns `{ status: "ok", timestamp }`.
 
## Tech Stack
 
| Package | Version | Role |
|---|---|---|
| `@hubspot/api-client` | 13.5.0 | Support ticket creation |
| `@reaatech/agent-handoff` | 0.1.0 | Core types and utilities for agent handoff |
| `@reaatech/agent-handoff-routing` | 0.1.0 | Weighted scoring router for specialist dispatch |
| `@reaatech/confidence-router` | 0.1.1 | Intent classification with threshold-based routing |
| `@reaatech/session-continuity` | 0.1.0 | Multi-turn conversation context management |
| `@reaatech/session-continuity-storage-memory` | 0.1.0 | In-memory storage adapter for sessions |
| `@reaatech/session-continuity-tokenizers` | 0.1.0 | Token counting for session budget |
| `@reaatech/structured-repair-core` | 1.0.0 | Malformed JSON repair via Zod schemas |
| `@sendgrid/mail` | 8.1.6 | Email dispatch |
| `@slack/web-api` | 7.16.0 | Sales alert notifications |
| `langfuse` | 3.38.20 | LLM observability and tracing |
| `next` | 16.2.7 | Next.js framework for API routes |
| `openai` | 6.42.0 | AI auto-reply generation via Responses API |
| `react` | 19.2.4 | React library (Next.js peer) |
| `react-dom` | 19.2.4 | React DOM (Next.js peer) |
| `zod` | 4.4.3 | Runtime schema validation |
 
## Testing
 
```bash
pnpm test    # vitest run --coverage (90%+ threshold)
```
 
## Project layout
 
```
app/api/webhooks/bigcommerce/route.ts    Webhook handler
app/api/health/route.ts                  Health check endpoint
src/lib/repair.ts                        Input repair service
src/lib/classify.ts                      Intent classification
src/lib/route-handoff.ts                 Agent handoff routing
src/lib/session.ts                       Session lifecycle manager
src/lib/bigcommerce-client.ts            BigCommerce API client
src/lib/openai-client.ts                 OpenAI auto-reply generation
src/lib/observability.ts                 Langfuse tracing
src/lib/slack.ts                         Slack notifications
src/lib/sendgrid.ts                      Email dispatch
src/handlers/sales.ts                    Sales inquiry handler
src/handlers/support.ts                  Support inquiry handler
src/handlers/returns.ts                  Returns inquiry handler
tests/                                   Vitest test suite
```
 
## License
 
MIT — see [LICENSE](./LICENSE).