theleadrouter-mcp 0.1.0

package/.claude/skills/partner-guide/SKILL.md

@@ -0,0 +1,352 @@
+---
+name: partner-guide
+description: "Partner guide for iSCALE lead routing — submitting leads, managing campaigns, posting specs, the partner portal, API keys, sessions, co-registration. Use when integrating lead submission, checking campaign status, or using the partner portal."
+user_invocable: true
+allowed_tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+---
+
+# iSCALE Partner Guide
+
+Guide for partners (affiliates, publishers, lead generators) who submit leads into iSCALE. Covers lead submission, campaign management, the partner portal, and API integration.
+
+## When to use
+- Integrating lead submission into your system
+- Understanding posting specs and required fields
+- Managing campaigns in the partner portal
+- Setting up API keys
+- Using sessions for multi-step lead capture
+- Setting up co-registration flows
+- Checking lead status and payouts
+- Troubleshooting rejected leads
+
+## How Lead Submission Works
+
+You submit leads to iSCALE via API. Each campaign has a unique **posting key** (`lr_xxx`) that identifies your campaign and authorizes the submission.
+
+```
+Your System → POST /api/v1/leads/submit → iSCALE Routing Engine → Buyer(s)
+```
+
+1. You submit a lead with the campaign's posting key
+2. iSCALE validates the lead data against required fields
+3. The routing engine evaluates which buyers want the lead
+4. Lead is delivered to winning buyer(s)
+5. You get paid based on your campaign's pricing (costPerLead or revshare)
+
+## Submitting Leads
+
+### Endpoint
+
+```
+POST /api/v1/leads/submit
+Authorization: Bearer lr_xxx
+Content-Type: application/json
+```
+
+Replace `lr_xxx` with your campaign's posting key.
+
+### Required Fields (Every Lead)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| campaignId | string | Campaign UUID or display ID |
+| firstName | string | Lead's first name |
+| lastName | string | Lead's last name |
+| email | string | Valid email address |
+| phone | string | Phone number (digits only, 10 chars) |
+| zipCode | string | 5-digit zip code |
+| ipAddress | string | Lead's IP address |
+| tcpaConsent | boolean | Must be `true` |
+| trustedFormCertUrl | string | TrustedForm certificate URL |
+
+### Optional Global Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| address | string | Street address |
+| city | string | City |
+| state | string | 2-letter state code ("CA", "TX") |
+| dateOfBirth | string | YYYY-MM-DD format |
+| sub1 — sub10 | string | Your tracking/sub-ID values |
+
+### Vertical Fields
+
+Each vertical (lead category) has additional required or optional fields. For example, a Solar vertical might require:
+
+| Field | Type |
+|-------|------|
+| utilityBill | number |
+| homeOwner | boolean |
+| roofType | string |
+
+### Campaign Fields
+
+Some campaigns have additional fields beyond the vertical. Check the posting spec for the full list.
+
+### Example Request
+
+```json
+{
+  "campaignId": "abc-123",
+  "firstName": "Jane",
+  "lastName": "Smith",
+  "email": "jane@example.com",
+  "phone": "5551234567",
+  "zipCode": "90210",
+  "state": "CA",
+  "ipAddress": "203.0.113.42",
+  "tcpaConsent": true,
+  "trustedFormCertUrl": "https://cert.trustedform.com/abc123",
+  "utilityBill": 150,
+  "homeOwner": true,
+  "sub1": "google",
+  "sub2": "campaign-42"
+}
+```
+
+### Response — Success
+
+```json
+{
+  "data": {
+    "id": "lead-uuid",
+    "shortId": "L-12345",
+    "status": "sold",
+    "revenue": "15.00",
+    "sales": [
+      {
+        "buyerId": "buyer-uuid",
+        "price": "15.00",
+        "deliveryStatus": "delivered"
+      }
+    ]
+  }
+}
+```
+
+### Response — Rejection
+
+```json
+{
+  "data": {
+    "id": "lead-uuid",
+    "shortId": "L-12346",
+    "status": "rejected",
+    "rejectionReason": "No matching contracts"
+  }
+}
+```
+
+### Common Rejection Reasons
+
+| Reason | What it means |
+|--------|---------------|
+| No matching contracts | No buyer contracts matched the lead's data |
+| Duplicate lead | This person was already submitted recently |
+| Cap exceeded | Campaign or buyer caps have been reached |
+| Invalid field: [name] | A required field is missing or invalid |
+| Campaign inactive | The campaign is paused or disabled |
+| TCPA consent required | tcpaConsent must be `true` |
+| Missing TrustedForm certificate | trustedFormCertUrl is required |
+
+## Getting Your Posting Spec
+
+The posting spec tells you exactly what fields to send for a specific campaign.
+
+### Via API
+
+```
+GET /api/v1/campaigns/{campaignId}/posting
+Authorization: Bearer lr_xxx
+```
+
+Returns:
+```json
+{
+  "data": {
+    "postingUrl": "https://leads.iscale.com/api/v1/leads/submit",
+    "postingKey": "lr_xxx",
+    "requiredFields": ["firstName", "lastName", "email", "phone", ...],
+    "verticalFields": [...],
+    "campaignFields": [...],
+    "sampleBody": { ... }
+  }
+}
+```
+
+### Via Partner Portal
+
+Go to **Campaigns > [Your Campaign] > Posting Specs tab**. This shows all fields, types, and a sample request body.
+
+## Partner Portal
+
+The partner portal gives you a dashboard to manage campaigns, view leads, and track payouts.
+
+### Accessing the Portal
+
+- **URL:** Your iSCALE instance URL + `/partner` (e.g., `https://leads.iscale.com/partner`)
+- **Auth:** Login with your partner account credentials
+
+### Portal Pages
+
+| Page | What it shows |
+|------|---------------|
+| **Dashboard** | Overview stats — leads today, revenue, acceptance rate |
+| **People** | Contacts across all your leads, with timeline |
+| **Offers** | Available offers you can enroll in, plus your active campaigns |
+| **Campaign Detail** | Overview, posting specs, leads for a specific campaign |
+| **Payouts** | Payout history and upcoming payouts |
+| **Posting Log** | Real-time log of every lead submission (success/failure) |
+| **Settings** | Your profile, API keys |
+| **Help** | Documentation and support |
+
+### Viewing Leads
+
+Go to **People > Leads tab** to see all submitted leads with:
+- Status (sold, rejected, pending, returned)
+- Revenue earned
+- Submission date
+- Campaign name
+
+Click a lead to see full details including delivery status.
+
+## API Keys
+
+You can access the partner portal API programmatically using API keys.
+
+### Creating an API Key
+
+1. Go to **Settings** in the partner portal
+2. Click **Create API Key**
+3. Copy the key (shown once) — it starts with `lr_`
+
+Or ask your admin to create one from the admin dashboard.
+
+### Using API Keys
+
+```
+GET /api/partner/leads
+Authorization: Bearer lr_your_partner_api_key
+```
+
+### Partner API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/partner/campaigns` | GET | List your campaigns |
+| `/api/partner/campaigns/{id}` | GET | Campaign detail + posting spec |
+| `/api/partner/campaigns/sync` | GET | Lightweight change detection |
+| `/api/partner/leads` | GET | List your leads (filterable) |
+| `/api/partner/leads/{id}` | GET | Lead detail |
+| `/api/partner/offers` | GET | Available offers |
+| `/api/partner/offers/{id}` | GET | Offer detail |
+| `/api/partner/payouts` | GET | Payout history |
+| `/api/partner/settings` | GET/PUT | Your profile |
+| `/api/partner/api-keys` | GET/POST | List/create API keys |
+| `/api/partner/api-keys/{id}` | DELETE | Revoke an API key |
+
+## Sessions — Multi-Step Lead Capture
+
+For multi-step funnels where you collect data across several pages, use the Sessions API.
+
+### How It Works
+
+1. **Create a session** — gets a session key
+2. **PATCH data** at each step — add fields as the user fills them in
+3. **Submit** on the final step — triggers routing
+
+### Flow
+
+```
+Step 1: Create session (get sessionKey)
+Step 2: PATCH { firstName, lastName, email }
+Step 3: PATCH { phone, zipCode, utilityBill }
+Step 4: Submit (triggers routing)
+```
+
+### Key Details
+
+- Session key acts as a bearer token for subsequent requests
+- Sessions expire after **24 hours**
+- Each PATCH merges data — doesn't replace previous data
+- Lead is only created on final submit
+
+## Co-Registration (Coreg)
+
+Submit the same contact through multiple campaigns in a single session.
+
+### How It Works
+
+1. Submit primary lead (normal flow)
+2. Show coreg offers to the user (offers with `visibility: public`)
+3. For each accepted offer, submit a coreg lead with the same contact data
+4. Coreg leads are linked via `parentLeadId`
+
+### Flow
+
+```
+Primary submit → Get coreg offers → Submit to each accepted offer → Close session
+```
+
+## Campaign Status
+
+| Status | Meaning |
+|--------|---------|
+| `active` | Accepting leads |
+| `paused` | Temporarily stopped — leads will be rejected |
+| `inactive` | Disabled — no leads accepted |
+
+If your campaign is paused or inactive, contact your admin.
+
+## Pricing Models
+
+| Model | How you get paid |
+|-------|-----------------|
+| `fixed` | Fixed costPerLead for every accepted lead |
+| `revshare` | Percentage of revenue from buyer payments |
+
+## Caps
+
+Your campaign may have caps that limit volume:
+
+| Cap | What it limits |
+|-----|----------------|
+| dailyCap | Max leads per day |
+| weeklyCap | Max leads per week |
+| monthlyCap | Max leads per month |
+
+Caps reset at midnight in the campaign's timezone. Once hit, leads are rejected until the cap resets.
+
+## Troubleshooting
+
+### "Campaign inactive" rejection
+Your campaign has been paused or disabled. Contact your admin.
+
+### "Invalid field" rejection
+A required field is missing or in the wrong format. Check the posting spec for field types and required flags.
+
+### "Duplicate lead" rejection
+This person (by email/phone) was already submitted recently. Each buyer has their own dedup window (typically 30 days).
+
+### "No matching contracts" rejection
+No buyer contracts matched the lead's data. This could mean:
+- Lead's state/zip doesn't match any buyer's geo filters
+- Lead's demographics don't match buyer requirements
+- All eligible buyers have hit their caps
+- All eligible buyers are paused or out of balance
+
+### "Cap exceeded" rejection
+Your campaign's daily/weekly/monthly cap has been reached. Wait for the cap to reset or ask your admin to increase it.
+
+### Leads showing "pending" status
+The lead was accepted but delivery to the buyer is still in progress. Check back shortly — it should update to "sold" or "failed".
+
+### Not getting paid for leads
+Check that:
+- Leads have status "sold" (not "rejected" or "returned")
+- Your payment cycle is set correctly
+- Your balance reflects recent leads

package/.claude/skills/welcome/SKILL.md

@@ -0,0 +1,351 @@
+---
+name: welcome
+description: "First-time setup wizard for iSCALE + Claude Code. Detects your role, checks MCP connection, and walks you through getting started. Run this when you first clone the repo or are new to iSCALE."
+user_invocable: true
+allowed_tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+---
+
+# iSCALE Welcome Wizard
+
+Interactive first-time setup for new iSCALE users. This skill detects your situation and walks you through everything step by step.
+
+## When this runs
+
+- User says "get started", "set up", "I'm new", "help me get started", "walk me through"
+- User runs `/welcome` explicitly
+- First time opening Claude Code in this repo
+
+## Step 1: Welcome & Role Detection
+
+Start by greeting the user and asking their role:
+
+```
+Welcome to iSCALE Lead Routing!
+
+I'll help you get set up. First, which best describes your role?
+
+1. **Admin** — I manage the platform (set up verticals, partners, buyers, offers, contracts)
+2. **Partner** — I submit leads into iSCALE (affiliate, publisher, lead generator)  
+3. **Buyer** — I receive leads from iSCALE (advertiser, client, law firm)
+
+Which one are you? (1, 2, or 3)
+```
+
+## Step 2: Check MCP Connection
+
+After role selection, check if the MCP server is configured:
+
+1. Check if `.mcp.json` exists in the project root
+2. If it exists, check for an `iscale` entry with `ISCALE_API_URL` and `ISCALE_API_KEY`
+3. If not configured, walk them through setup:
+
+```
+To connect Claude Code to your iSCALE instance, I need two things:
+
+1. **Your iSCALE URL** — the URL where you access iSCALE
+   (e.g., https://leads.iscale.com or https://your-company.iscale.com)
+
+2. **An API key** — you can get one from Settings > API Keys in the admin dashboard
+   (it starts with lr_)
+
+Do you have these ready?
+```
+
+If they have the info, write the `.mcp.json` config and tell them to restart Claude Code.
+
+If they don't have an API key yet:
+- **Admins:** "Go to Settings > API Keys in your admin dashboard and create one."
+- **Partners:** "Ask your admin to create a partner API key for you, or go to Settings in your partner portal."
+- **Buyers:** "Ask your admin to create a buyer API key for you, or go to Settings in your buyer portal."
+
+## Step 3: Role-Specific Walkthrough
+
+Based on their role, run the appropriate guided walkthrough:
+
+### For Admins → Run the Admin Onboarding
+
+```
+Great! You're set up as an admin. Here's what we'll cover:
+
+1. **How iSCALE works** — the big picture (2 min read)
+2. **Entity hierarchy** — what connects to what
+3. **Your first campaign** — step-by-step setup
+4. **Testing** — submit a test lead and verify routing
+5. **Day-to-day operations** — reports, troubleshooting, common tasks
+
+Ready? Let's start with how iSCALE works.
+```
+
+Then walk through each section interactively:
+
+**Section 1: How iSCALE Works**
+```
+iSCALE routes leads from partners to buyers. Here's the flow:
+
+  Partner submits lead → Campaign → Offer → Routing Engine → Contract(s) → Buyer(s)
+
+Key concept: the **Offer** is the hub. It connects campaigns (lead sources) 
+to contracts (buyer agreements) and controls the distribution rules.
+
+Think of it like an auction house:
+- Partners are sellers bringing items (leads)
+- Buyers are bidders with specific criteria (contracts)
+- The Offer is the auction rules (who wins, how many winners)
+
+Make sense? Say "next" to continue, or ask me anything.
+```
+
+**Section 2: Entity Hierarchy**
+```
+Here's what you need to set up, in order:
+
+  1. Vertical (lead category — "Solar", "Medicare", etc.)
+     └── defines what fields leads have
+  
+  2. Partner (who sends you leads)
+     └── Campaign (their specific program, has a posting key)
+  
+  3. Buyer (who buys leads)
+     └── Contract (what they want: filters, caps, price)
+  
+  4. Offer (connects campaigns ↔ contracts)
+     └── distribution rules: exclusive? multisell? highest price wins?
+
+Each entity depends on the one above it. You can't create a campaign 
+without a partner, or a contract without a buyer.
+
+Ready to set up your first campaign? Say "next".
+```
+
+**Section 3: First Campaign Setup**
+```
+Let's set up a complete campaign. I'll walk you through each step.
+
+What vertical (lead type) are you working with? 
+Examples: Solar, Medicare, Auto Insurance, Mass Tort, Home Services
+
+(If you already have verticals set up, I can check — just say "check my verticals")
+```
+
+Then guide them through creating each entity in order, using the MCP tools if connected, or giving them step-by-step UI instructions if not.
+
+**Section 4: Testing**
+```
+Now let's test the flow. I'll help you:
+
+1. Get the posting spec for your new campaign
+2. Submit a test lead
+3. Verify it routed correctly
+4. Check the routing waterfall to see what happened
+
+Ready to test?
+```
+
+**Section 5: Day-to-Day**
+```
+You're all set! Here are the things you'll do most often:
+
+- "Show me today's leads" — quick overview
+- "Why didn't lead L-12345 route?" — troubleshoot routing
+- "What's buyer X's balance?" — check billing
+- "Pull a revenue report for this week" — reporting
+- "Pause contract C-456" — manage entities
+
+You can also run /admin-guide anytime for the full reference.
+
+Any questions?
+```
+
+### For Partners → Run the Partner Onboarding
+
+```
+Great! You're set up as a partner. Here's what we'll cover:
+
+1. **How lead submission works** — the big picture
+2. **Your campaigns** — what's available to you
+3. **Posting specs** — exactly what fields to send
+4. **Your first test lead** — submit one and see what happens
+5. **Day-to-day** — checking leads, payouts, troubleshooting
+
+Ready? Let's go.
+```
+
+**Section 1: How Lead Submission Works**
+```
+You submit leads to iSCALE via API. Here's how it works:
+
+  Your system → POST to iSCALE API → Routing engine finds buyers → You get paid
+
+Each of your campaigns has a **posting key** (starts with lr_). 
+This key identifies your campaign and authorizes the submission.
+
+You send a JSON body with the lead's info (name, email, phone, etc.) 
+and iSCALE tells you immediately if the lead was accepted or rejected.
+
+Make sense? Say "next" to continue.
+```
+
+**Section 2: Your Campaigns**
+If MCP is connected, use `list_campaigns` to show their campaigns:
+```
+Here are your active campaigns:
+
+  Campaign: Solar Leads West Coast (C-123)
+  Vertical: Solar
+  Posting Key: lr_abc***  
+  Caps: 100/day, 500/week
+  
+  Campaign: Medicare AEP (C-456)
+  Vertical: Medicare
+  Posting Key: lr_def***
+  Caps: 50/day
+
+Want to see the posting spec for one of these?
+```
+
+If not connected, tell them where to find this info in the portal.
+
+**Section 3: Posting Spec**
+```
+Let's look at exactly what fields you need to send. 
+Which campaign do you want to integrate first?
+```
+
+Then show the full posting spec with required fields, types, and a copy-paste sample request.
+
+**Section 4: First Test Lead**
+```
+Let's submit a test lead. I'll generate a sample request for you.
+
+⚠️  This will create a REAL lead in the system (with test data).
+Your admin can delete it afterward.
+
+Want me to generate the curl command, or do you want to submit via your own system?
+```
+
+**Section 5: Day-to-Day**
+```
+You're all set! Here's what you'll use most:
+
+- "Show me my leads from today" — check submissions
+- "Why was my last lead rejected?" — troubleshoot rejections  
+- "What's my posting spec for campaign X?" — quick reference
+- "Show me my payouts" — check earnings
+
+You can run /partner-guide anytime for the full reference.
+```
+
+### For Buyers → Run the Buyer Onboarding
+
+```
+Great! You're set up as a buyer. Here's what we'll cover:
+
+1. **How you receive leads** — the big picture
+2. **Your contracts** — what's configured for you
+3. **Filters & caps** — controlling what you receive
+4. **Delivery** — how leads reach your system
+5. **Day-to-day** — checking leads, billing, returns
+
+Ready? Let's go.
+```
+
+**Section 1: How You Receive Leads**
+```
+Partners submit leads into iSCALE. The routing engine checks your 
+contracts — if a lead matches your criteria, it's delivered to you.
+
+  Lead comes in → Routing engine checks your filters → Match? → Delivered to you
+
+You only pay for leads that pass ALL your checks:
+✓ Geographic filters (states/zips you want)
+✓ Demographic filters (age range, etc.)  
+✓ Custom filters (vertical-specific criteria)
+✓ Caps not exceeded (daily/weekly/monthly limits)
+✓ Not a duplicate (if dedup is enabled)
+
+Make sense? Say "next" to continue.
+```
+
+**Section 2: Your Contracts**
+If MCP is connected, use `list_contracts` to show their contracts:
+```
+Here are your active contracts:
+
+  Contract: Solar CA/TX (CT-123)
+  Vertical: Solar
+  Price: $15.00/lead
+  Geo: CA, TX only
+  Caps: 50/day, 200/week
+  
+  Contract: Medicare National (CT-456)  
+  Vertical: Medicare
+  Price: $25.00/lead
+  Geo: All states
+  Caps: 100/day
+
+Want to adjust any of these?
+```
+
+**Section 3: Filters & Caps**
+```
+Your contracts control exactly what leads you receive:
+
+**Geographic filters** — which states/zips
+  Example: Only CA, TX, FL leads; or only 902xx zip codes
+
+**Demographic filters** — age range, etc.
+  Example: Ages 25-65 only
+
+**Custom filters** — vertical-specific criteria  
+  Example: homeOwner = true, utilityBill > $100
+
+**Caps** — volume limits
+  Example: Max 50 leads/day, $1000/day spend
+
+**Schedule** — operating hours
+  Example: Mon-Fri 9am-5pm Pacific (empty = 24/7)
+
+Want to see or adjust the filters on any of your contracts?
+```
+
+**Section 4: Delivery**
+```
+When a lead matches your contract, it's delivered to your system.
+
+Delivery methods:
+- **HTTP POST** — JSON payload to your endpoint (most common)
+- **HTTP GET** — data as query parameters  
+- **Email** — lead data sent to an email address
+
+Your delivery endpoint and field mapping are configured on your 
+contract or intake center. 
+
+Is your delivery endpoint already set up, or do you need help configuring it?
+```
+
+**Section 5: Day-to-Day**
+```
+You're all set! Here's what you'll use most:
+
+- "Show me leads I received today" — check incoming leads
+- "What's my balance?" — check billing
+- "Return lead L-12345" — return a bad lead
+- "Which contracts are hitting caps?" — monitor volume
+- "Pause contract CT-456" — stop receiving leads temporarily
+
+You can run /buyer-guide anytime for the full reference.
+```
+
+## Conversation Style
+
+Throughout the walkthrough:
+- Use plain language, not jargon (explain terms the first time)
+- Keep each section short — max 10 lines of text before asking "ready for next?"
+- Let the user ask questions at any point
+- If MCP is connected, show real data from their instance
+- If not connected, give UI directions ("go to Partners > Create")
+- Don't dump everything at once — this is a conversation, not a manual