VibeJoy API & Developer Docs

# ── ONE-TIME SETUP ──────────────────────────────────────────────────────────

# Set up brand context (required before campaigns)
vibejoy brand setup \
  --name "Acme CRM" \
  --offer "We help SDR teams automate outreach and book more meetings" \
  --icp "VP Sales at 50-500 person B2B SaaS companies" \
  --tone "Direct" \
  --goal "Book calls"

# Connect SendGrid (required before email delivery)
vibejoy sendgrid connect \
  --key "SG.your_sendgrid_key" \
  --from-name "Jane at Acme" \
  --from-email "jane@acme.com"

# Verify everything is ready
vibejoy status

# ── REPEATABLE CAMPAIGN PIPELINE ─────────────────────────────────────────────

# Step 1: Find companies hiring for roles your SaaS automates
vibejoy find --signal hiring --query "RevOps Manager" --location "United Kingdom" --limit 25 --output leads.csv

# Step 2: Enrich — target only the decision-maker you want
vibejoy enrich --unenriched --titles "CEO,Founder,CTO"

# Or filter by seniority level (c_suite, founder, vp, director, manager, owner)
# vibejoy enrich --unenriched --seniority "c_suite,founder"

# Or enrich a specific batch, targeting CFOs only
# vibejoy enrich --file leads.csv --titles "CFO,Finance Director" --output enriched.csv

# Step 3: Create campaign, add all enriched leads, and activate in one command
vibejoy campaign create \
  --audience "RevOps managers scaling their CRM stack" \
  --goal "book a 20-minute product demo" \
  --all-leads \
  --email1-date 2026-07-10 \
  --activate

# Step 4: Get social content (LinkedIn + Reddit) to schedule via Zernio
vibejoy campaign social --id CAMPAIGN_ID --output social.txt

# Step 5: Monitor stats
vibejoy stats
vibejoy campaign list

const BASE = 'http://localhost:3001';
const KEY  = 'vj_your_api_key_here';
const headers = { 'Authorization': `Bearer ${KEY}`, 'Content-Type': 'application/json' };

// ── ONE-TIME SETUP ────────────────────────────────────────────────────────────

// Step 0a: Set up brand context (do this once — the AI uses it for all campaigns)
await fetch(`${BASE}/api/brand`, {
  method: 'POST', headers,
  body: JSON.stringify({
    businessName: 'Acme CRM',
    offer: 'We help SDR teams automate outreach and book more meetings',
    icp: 'VP Sales at 50-500 person B2B SaaS companies',
    tone: 'Direct',   // Bold | Warm | Direct | Professional | Conversational
    goal: 'Book calls' // Get leads | Get signups | Build awareness | Book calls
  })
}).then(r => r.json());

// Step 0b: Connect SendGrid (do this once — required for email delivery)
await fetch(`${BASE}/api/integrations/sendgrid/connect`, {
  method: 'POST', headers,
  body: JSON.stringify({
    apiKey: 'SG.your_sendgrid_api_key',
    fromName: 'Jane at Acme',
    fromEmail: 'jane@acme.com'   // must be a verified sender in SendGrid
  })
}).then(r => r.json());

// ── REPEATABLE CAMPAIGN PIPELINE ──────────────────────────────────────────────

// Step 1: Find hiring signal leads
const { leads } = await fetch(`${BASE}/api/leads/intent/jobs`, {
  method: 'POST', headers,
  body: JSON.stringify({ jobTitles: ['RevOps Manager'], location: 'United Kingdom', maxResults: 25 })
}).then(r => r.json());

console.log(`Found ${leads.length} leads`);
const leadIds = leads.map(l => l._id);

// Step 2: Enrich contacts (parallel, streams progress if you use /enrich-stream)
const { enriched, newLeadsCreated } = await fetch(`${BASE}/api/leads/enrich`, {
  method: 'POST', headers,
  body: JSON.stringify({ leadIds })
}).then(r => r.json());

console.log(`Enriched ${enriched} leads, ${newLeadsCreated} extra contacts found`);

// Step 3: Generate + add recipients + activate in one call
// Pass allEnrichedLeads: true to auto-add every enriched lead
// Pass activate: true to go live immediately (requires SendGrid connected)
const { campaignId, name, output, activated, recipientCount } = await fetch(`${BASE}/api/campaigns/generate`, {
  method: 'POST', headers,
  body: JSON.stringify({
    targetAudience: 'RevOps managers scaling their tech stack',
    campaignGoal: 'book a 20-minute product demo',
    extraContext: 'Mention we integrate with their existing CRM',
    allEnrichedLeads: true,                                  // add all enriched leads
    email1At: new Date(Date.now() + 24*60*60*1000).toISOString(), // send tomorrow
    activate: true,                                          // go live immediately
  })
}).then(r => r.json());

console.log(`Campaign: ${name} (ID: ${campaignId})`);
console.log(`Recipients: ${recipientCount} | Activated: ${activated}`);
console.log(`Email 1 subject: ${output.emails?.email1?.subject}`);

// Step 5: Check stats any time
const stats = await fetch(`${BASE}/api/dashboard/stats`, { headers }).then(r => r.json());
console.log(`Total leads: ${stats.totalLeads} | Emails sent: ${stats.totalEmailsSent}`);

import requests

BASE = "http://localhost:3001"
KEY  = "vj_your_api_key_here"
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

# ── ONE-TIME SETUP ────────────────────────────────────────────────────────────

# Set up brand context
requests.post(f"{BASE}/api/brand", headers=HEADERS, json={
    "businessName": "Acme CRM",
    "offer": "We help SDR teams automate outreach and book more meetings",
    "icp": "VP Sales at 50-500 person B2B SaaS companies",
    "tone": "Direct",
    "goal": "Book calls"
})

# Connect SendGrid
requests.post(f"{BASE}/api/integrations/sendgrid/connect", headers=HEADERS, json={
    "apiKey": "SG.your_sendgrid_api_key",
    "fromName": "Jane at Acme",
    "fromEmail": "jane@acme.com"
})

# ── REPEATABLE CAMPAIGN PIPELINE ──────────────────────────────────────────────

# Step 1: Find leads
r = requests.post(f"{BASE}/api/leads/intent/jobs",
    headers=HEADERS,
    json={"jobTitles": ["RevOps Manager"], "location": "United Kingdom", "maxResults": 25})
leads = r.json()["leads"]
lead_ids = [l["_id"] for l in leads]
print(f"Found {len(lead_ids)} leads")

# Step 2: Enrich
r = requests.post(f"{BASE}/api/leads/enrich", headers=HEADERS, json={"leadIds": lead_ids})
print(r.json())  # { enriched, newLeadsCreated, failed }

# Step 3: Generate + add all enriched leads + activate in one call
from datetime import datetime, timedelta
tomorrow = (datetime.utcnow() + timedelta(days=1)).isoformat() + "Z"

r = requests.post(f"{BASE}/api/campaigns/generate", headers=HEADERS, json={
    "targetAudience": "RevOps managers scaling their tech stack",
    "campaignGoal": "book a 20-minute product demo",
    "allEnrichedLeads": True,   # auto-add every enriched lead as recipient
    "email1At": tomorrow,        # send tomorrow
    "activate": True             # go live immediately (requires SendGrid)
})
data = r.json()
print(f"Campaign: {data['name']} | Recipients: {data['recipientCount']} | Live: {data['activated']}")

#!/bin/bash
# Daily VibeJoy pipeline — finds CEOs/CFOs at companies hiring for relevant roles,
# enriches new ones, and adds them to a live campaign.
# Schedule: run daily at 7am with cron: 0 7 * * * /path/to/vibejoy-daily.sh

set -e  # stop on any error

echo "[$(date)] Starting daily VibeJoy pipeline..."

# ── Step 1: Find new companies (duplicates are skipped automatically) ──────────
vibejoy find \
  --signal hiring \
  --query "CFO OR Chief Financial Officer OR Finance Director" \
  --location "United Kingdom" \
  --limit 25

vibejoy find \
  --signal hiring \
  --query "CEO OR Chief Executive OR Managing Director" \
  --location "United States" \
  --limit 25

# ── Step 2: Enrich only leads not yet enriched, targeting CFOs/CEOs ────────────
vibejoy enrich \
  --unenriched \
  --titles "CEO,CFO,Chief Executive,Chief Financial Officer,Managing Director,Finance Director" \
  --seniority "c_suite,founder"

# ── Step 3: Add new enriched leads to the existing live campaign ───────────────
# Replace CAMPAIGN_ID with your actual campaign ID (vibejoy campaign list)
vibejoy campaign activate \
  --id CAMPAIGN_ID \
  --all-leads

echo "[$(date)] Pipeline complete."

# Make executable
chmod +x vibejoy-daily.sh

# Schedule via cron (Linux/macOS) — runs every day at 7am
crontab -e
# Add this line:
0 7 * * * /path/to/vibejoy-daily.sh >> /var/log/vibejoy.log 2>&1

# Windows Task Scheduler — create a Basic Task:
# Program: node
# Arguments: C:\path\to\vibejoy-daily.sh
# Trigger: Daily at 7:00 AM

name: Daily Lead Discovery

on:
  schedule:
    - cron: '0 7 * * 1-5'   # 7am UTC, Monday to Friday
  workflow_dispatch:          # also allows manual trigger from GitHub UI

jobs:
  discover:
    runs-on: ubuntu-latest
    steps:
      - name: Install VibeJoy CLI
        run: npm install -g vibejoy-cli   # or: npm install -g .
      
      - name: Authenticate
        run: vibejoy auth --key ${{ secrets.VIBEJOY_API_KEY }}
        env:
          VIBEJOY_API_KEY: ${{ secrets.VIBEJOY_API_KEY }}

      - name: Find CEOs at companies hiring senior roles
        run: |
          vibejoy find --signal hiring --query "CEO OR Chief Executive" --location "United Kingdom" --limit 20
          vibejoy find --signal hiring --query "CFO OR Finance Director" --location "United States" --limit 20

      - name: Enrich only new leads (CEOs and CFOs only)
        run: |
          vibejoy enrich --unenriched \
            --titles "CEO,CFO,Chief Executive,Finance Director" \
            --seniority "c_suite,founder"

      - name: Add to campaign and re-activate
        run: vibejoy campaign activate --id ${{ secrets.CAMPAIGN_ID }} --all-leads
        env:
          CAMPAIGN_ID: ${{ secrets.CAMPAIGN_ID }}

// Step 1: Find new companies hiring for senior roles (run daily)
// VibeJoy automatically skips companies it already has — safe to run every day
const findRes = await fetch('https://your-api.com/api/leads/intent/jobs', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer vj_your_key', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jobTitles: ['CEO', 'CFO', 'Chief Financial Officer', 'Managing Director'],
    location: 'United Kingdom',
    maxResults: 25
  })
}).then(r => r.json());

console.log(`Found ${findRes.count} new leads, skipped ${findRes.skippedDuplicates} duplicates`);

// Step 2: Enrich only unenriched leads — target CEO/CFO titles specifically
const enrichRes = await fetch('https://your-api.com/api/leads/enrich', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer vj_your_key', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    unenrichedOnly: true,
    titles: ['CEO', 'CFO', 'Chief Executive Officer', 'Chief Financial Officer', 'Managing Director', 'Finance Director'],
    seniority: ['c_suite', 'founder']
  })
}).then(r => r.json());

console.log(`Enriched ${enrichRes.enriched} contacts`);

// Step 3: Add all enriched leads to a live campaign (safe to re-run — no duplicates added)
const updateRes = await fetch('https://your-api.com/api/campaigns/CAMPAIGN_ID', {
  method: 'PATCH',
  headers: { 'Authorization': 'Bearer vj_your_key', 'Content-Type': 'application/json' },
  body: JSON.stringify({ allEnrichedLeads: true })
}).then(r => r.json());

console.log(`Campaign now has ${updateRes.recipientCount} recipients`);

vibejoy sendgrid connect \
  --key "SG.your_sendgrid_api_key" \
  --from-name "Jane at Acme" \
  --from-email "jane@acme.com"

# Verify it worked
vibejoy status
# ✅ SendGrid email — connected, sending from jane@acme.com

curl -X POST https://your-api.com/api/integrations/sendgrid/connect \
  -H "Authorization: Bearer vj_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "SG.your_sendgrid_api_key",
    "fromName": "Jane at Acme",
    "fromEmail": "jane@acme.com"
  }'

# Print to terminal
vibejoy campaign social --id CAMPAIGN_ID

# Or save to a file (recommended for long content)
vibejoy campaign social --id CAMPAIGN_ID --output social.txt

# Find your campaign ID first if needed
vibejoy campaign list

curl https://your-api.com/api/campaigns/CAMPAIGN_ID \
  -H "Authorization: Bearer vj_your_api_key"

# Response shape — campaign.output contains:
{
  "linkedinPost": "...",           // the LinkedIn post text
  "linkedinDMs": {
    "connectionRequest": "...",    // 280 char max — sent with the connection invite
    "dm1": "...",                  // send 2-3 days after they accept
    "dm2": "...",                  // send 5-7 days after dm1
    "dm3": "..."                   // send 10-14 days after dm2 (graceful exit if no reply)
  },
  "reddit": {
    "originalPost": {
      "subreddit": "r/sales",      // suggested subreddit
      "title": "...",
      "body": "..."
    },
    "replyTemplates": [
      { "scenario": "...", "body": "..." },
      { "scenario": "...", "body": "..." }
    ]
  }
}

Authorization: Bearer vj_your_api_key_here

{
  "mcpServers": {
    "vibejoy": {
      "command": "node",
      "args": ["/absolute/path/to/vibejoy/mcp/index.js"],
      "env": {
        "VIBEJOY_API_KEY": "vj_your_api_key_here",
        "VIBEJOY_API_URL": "http://localhost:3001"
      }
    }
  }
}

{
  "mcpServers": {
    "vibejoy": {
      "command": "node",
      "args": ["/absolute/path/to/vibejoy/mcp/index.js"],
      "env": {
        "VIBEJOY_API_KEY": "vj_your_api_key_here",
        "VIBEJOY_API_URL": "http://localhost:3001"
      }
    }
  }
}

{
  "mcpServers": {
    "vibejoy": {
      "command": "node",
      "args": ["C:\\path\\to\\vibejoy\\mcp\\index.js"],
      "env": {
        "VIBEJOY_API_KEY": "vj_your_api_key_here",
        "VIBEJOY_API_URL": "http://localhost:3001"
      }
    }
  }
}

import OpenAI from 'openai';
import fetch from 'node-fetch';

const openai = new OpenAI();
const VJ_KEY = process.env.VIBEJOY_API_KEY;
const VJ_BASE = 'http://localhost:3001';
const h = { Authorization: `Bearer ${VJ_KEY}`, 'Content-Type': 'application/json' };

const tools = [
  {
    type: 'function',
    function: {
      name: 'find_leads',
      description: 'Find leads by intent signal',
      parameters: {
        type: 'object',
        properties: {
          source: { type: 'string', enum: ['job_board','reddit','funding','linkedin_post','local'] },
          query:  { type: 'string' },
          location: { type: 'string' },
          limit: { type: 'number' }
        },
        required: ['source','query']
      }
    }
  },
  {
    type: 'function',
    function: {
      name: 'enrich_contacts',
      description: 'Enrich leads with verified emails, job titles, and LinkedIn. Filter by titles or seniority.',
      parameters: {
        type: 'object',
        properties: {
          leadIds: { type: 'array', items: { type: 'string' } },
          titles: { type: 'array', items: { type: 'string' }, description: 'Job title keywords e.g. ["CEO","Founder"]' },
          seniority: { type: 'array', items: { type: 'string' }, description: 'Seniority levels e.g. ["c_suite","vp"]' }
        },
        required: ['leadIds']
      }
    }
  }
];

async function callVibeJoy(name, args) {
  if (name === 'find_leads') {
    const res = await fetch(`${VJ_BASE}/api/leads/intent/jobs`, {
      method: 'POST', headers: h,
      body: JSON.stringify({ jobTitles: [args.query], location: args.location, maxResults: args.limit || 25 })
    });
    return res.json();
  }
  if (name === 'enrich_contacts') {
    const res = await fetch(`${VJ_BASE}/api/leads/enrich`, {
      method: 'POST', headers: h,
      body: JSON.stringify({ leadIds: args.leadIds, titles: args.titles || [], seniority: args.seniority || [] })
    });
    return res.json();
  }
}

// Agent loop
let messages = [{ role: 'user', content: 'Find 10 companies hiring sales ops in London, then enrich them.' }];

while (true) {
  const res = await openai.chat.completions.create({ model: 'gpt-4o', tools, messages });
  const msg = res.choices[0].message;
  messages.push(msg);

  if (res.choices[0].finish_reason === 'stop') {
    console.log(msg.content);
    break;
  }

  for (const call of msg.tool_calls || []) {
    const result = await callVibeJoy(call.function.name, JSON.parse(call.function.arguments));
    messages.push({ role: 'tool', tool_call_id: call.id, content: JSON.stringify(result) });
  }
}

from langchain.agents import create_openai_functions_agent, AgentExecutor
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
import requests, os

BASE = "http://localhost:3001"
H = {"Authorization": f"Bearer {os.environ['VIBEJOY_API_KEY']}", "Content-Type": "application/json"}

@tool
def find_leads(source: str, query: str, location: str = "", limit: int = 25) -> dict:
  """Find leads by intent signal. source: job_board | reddit | funding | linkedin_post | local"""
  r = requests.post(f"{BASE}/api/leads/intent/jobs", headers=H,
    json={"jobTitles": [query], "location": location, "maxResults": limit})
  return r.json()

@tool
def enrich_contacts(lead_ids: list[str]) -> dict:
  """Enrich leads with verified email, title, and LinkedIn"""
  r = requests.post(f"{BASE}/api/leads/enrich", headers=H, json={"leadIds": lead_ids})
  return r.json()

@tool
def get_dashboard_stats() -> dict:
  """Get this month's usage stats"""
  return requests.get(f"{BASE}/api/dashboard/stats", headers=H).json()

llm = ChatOpenAI(model="gpt-4o")
agent = create_openai_functions_agent(llm, [find_leads, enrich_contacts, get_dashboard_stats])
executor = AgentExecutor(agent=agent, tools=[find_leads, enrich_contacts, get_dashboard_stats], verbose=True)

executor.invoke({"input": "Find 20 companies hiring RevOps managers in the UK and enrich them"})

// Node.js: stream enrichment progress
const response = await fetch('http://localhost:3001/api/leads/enrich-stream', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer vj_your_key', 'Content-Type': 'application/json' },
  body: JSON.stringify({ leadIds: [...] })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  for (const line of decoder.decode(value).split('\n')) {
    if (!line.startsWith('data: ')) continue;
    const evt = JSON.parse(line.slice(6));

    if (evt.type === 'progress') {
      console.log(`[${evt.enriched + evt.failed}/${evt.total}] ${evt.leadName}`);
    }
    if (evt.type === 'done') {
      console.log(`Done: ${evt.enriched} enriched, ${evt.newLeadsCreated} new contacts, ${evt.failed} not found`);
    }
  }
}

npm install -g vibejoy
vibejoy auth --key vj_your_api_key_here
vibejoy auth --show   # verify stored key

# --- Hiring signal pipeline ---
# Find companies hiring for the role your SaaS automates
vibejoy find --signal hiring --query "Revenue Operations Manager" --location "United Kingdom" --limit 50 --output /tmp/leads.csv

# Enrich all leads not yet enriched (simplest — no file needed)
vibejoy enrich --unenriched

# Or enrich a specific CSV file
# vibejoy enrich --file /tmp/leads.csv --output /tmp/enriched.csv

# Generate and activate campaign with all enriched leads
vibejoy campaign create \
  --audience "RevOps managers scaling their CRM stack" \
  --goal "book a 20-minute product demo" \
  --all-leads \
  --email1-date 2026-07-15 \
  --activate

# --- Pain signal pipeline ---
# Find people on Reddit expressing your customer's pain
vibejoy find --signal reddit --query "cold email not getting replies" --limit 30 --output /tmp/pain.csv

# Enrich all unenriched leads
vibejoy enrich --unenriched

# Create and activate campaign
vibejoy campaign create \
  --audience "founders frustrated with cold email deliverability" \
  --goal "start a conversation about outbound consistency" \
  --all-leads \
  --email1-date 2026-07-15 \
  --activate

# --- Check results ---
vibejoy stats
vibejoy campaign list

# .github/workflows/weekly-leads.yml
name: Weekly lead run
on:
  schedule:
    - cron: '0 8 * * 1'   # Monday 8am UTC

jobs:
  find-and-enrich:
    runs-on: ubuntu-latest
    steps:
      - run: npm install -g vibejoy
      - run: vibejoy auth --key ${VIBEJOY_API_KEY}
        env:
          VIBEJOY_API_KEY: ${{ secrets.VIBEJOY_API_KEY }}
      - run: |
          EMAIL_DATE=$(date -u -d "+2 days" +%Y-%m-%d 2>/dev/null || date -u -v+2d +%Y-%m-%d)
          vibejoy find --signal hiring --query "SDR" --limit 50 --output leads.csv
          vibejoy enrich --unenriched
          vibejoy campaign create \
            --audience "Sales managers scaling outbound without growing headcount" \
            --goal "start a conversation about pipeline efficiency" \
            --all-leads \
            --email1-date "$EMAIL_DATE" \
            --activate
      - run: vibejoy stats

{
  "event": "lead.enriched",
  "timestamp": "2026-07-08T09:00:00Z",
  "data": {
    "_id": "lead_abc123",
    "businessName": "Acme Corp",
    "contactName": "Jane Smith",
    "contactTitle": "Head of Sales",
    "email": "jane@acme.com",
    "linkedinUrl": "https://linkedin.com/in/janesmith",
    "website": "https://acme.com",
    "intentSource": "job_board",
    "intentSignal": "Hiring: Head of Sales at Acme Corp"
  }
}

import crypto from 'crypto';

export function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

// Express example
app.post('/webhook/vibejoy', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-vibejoy-signature'];
  if (!verifyWebhook(req.body, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  const { event, data } = JSON.parse(req.body);
  console.log(event, data);
  res.sendStatus(200);
});

# Make.com HTTP module: find leads
URL: http://localhost:3001/api/leads/intent/jobs
Method: POST
Headers: Authorization = Bearer vj_your_key
Body type: Raw (JSON)
Body: {"jobTitles": ["SDR"], "location": "London", "maxResults": 25}

# Map leads[].businessName, leads[].website, leads[]._id
# to your CRM, Airtable, or Notion module