Lead Management

// Lead identification happens automatically when users:
// - Submit forms
// - Sign up for trials
// - Request demos
// - Download gated content
// - Subscribe to newsletters

// Configure automatic lead detection
pxlpeak.leads.configure({
  // Auto-create leads on these events
  autoCapture: {
    events: [
      'form_submitted',
      'trial_started',
      'demo_requested',
      'content_downloaded',
      'newsletter_subscribed'
    ],

    // Required fields for lead creation
    requiredFields: ['email'],

    // Optional enrichment fields
    enrichmentFields: ['name', 'company', 'phone', 'jobTitle']
  },

  // Deduplication
  deduplication: {
    field: 'email',
    strategy: 'merge' // merge, replace, skip
  }
});

// Create a lead programmatically
const lead = await pxlpeak.leads.create({
  // Contact information
  email: 'jane.doe@company.com',
  firstName: 'Jane',
  lastName: 'Doe',
  phone: '+1-555-123-4567',

  // Company information
  company: {
    name: 'Acme Corp',
    size: '50-200',
    industry: 'Technology',
    website: 'https://acme.com'
  },

  // Professional details
  jobTitle: 'Marketing Director',
  department: 'Marketing',

  // Lead source
  source: {
    type: 'organic',
    campaign: 'blog_seo',
    medium: 'content',
    referrer: 'https://google.com'
  },

  // Custom properties
  customFields: {
    product_interest: ['analytics', 'attribution'],
    budget_range: '$10k-$50k',
    timeline: 'Q1 2026'
  },

  // Initial status
  status: 'new',

  // Tags
  tags: ['enterprise', 'high-intent', 'marketing-team']
});

// Automatic form tracking
pxlpeak.forms.trackAll({
  // Selectors for forms to track
  include: ['#signup-form', '#demo-form', '.lead-form'],
  exclude: ['#search-form', '#login-form'],

  // Field mapping
  fieldMapping: {
    'email': 'email',
    'full_name': 'name',
    'company_name': 'company',
    'phone_number': 'phone',
    'job_title': 'jobTitle'
  },

  // Events to track
  trackEvents: {
    formViewed: true,
    fieldFocused: true,
    fieldCompleted: true,
    formAbandoned: true,
    formSubmitted: true
  }
});

// Manual form submission tracking
document.getElementById('demo-form').addEventListener('submit', (e) => {
  e.preventDefault();

  const formData = new FormData(e.target);

  pxlpeak.leads.captureFromForm({
    email: formData.get('email'),
    name: formData.get('name'),
    company: formData.get('company'),
    message: formData.get('message'),
    source: 'demo_request_form'
  });

  // Continue with form submission
});

// Get complete lead profile
const profile = await pxlpeak.leads.getProfile('lead_abc123');

console.log(profile);
// {
//   id: 'lead_abc123',
//
//   // Contact info
//   contact: {
//     email: 'jane.doe@company.com',
//     firstName: 'Jane',
//     lastName: 'Doe',
//     phone: '+1-555-123-4567',
//     avatar: 'https://...'
//   },
//
//   // Company
//   company: {
//     name: 'Acme Corp',
//     domain: 'acme.com',
//     industry: 'Technology',
//     size: '50-200',
//     location: 'San Francisco, CA',
//     enrichedData: { revenue: '$10M-$50M', techStack: [...] }
//   },
//
//   // Lead status
//   status: 'qualified',
//   score: 78,
//   stage: 'mql', // visitor, lead, mql, sql, opportunity, customer
//
//   // Engagement summary
//   engagement: {
//     firstSeen: '2025-12-15T10:30:00Z',
//     lastSeen: '2026-01-12T14:22:00Z',
//     totalSessions: 12,
//     totalPageviews: 47,
//     totalEvents: 156,
//     emailsOpened: 5,
//     emailsClicked: 3
//   },
//
//   // Attribution
//   attribution: {
//     firstTouch: { source: 'google', medium: 'organic', campaign: null },
//     lastTouch: { source: 'email', medium: 'newsletter', campaign: 'jan_2026' },
//     touchCount: 8
//   },
//
//   // Lifecycle
//   lifecycle: {
//     createdAt: '2025-12-15T10:30:00Z',
//     qualifiedAt: '2026-01-05T09:15:00Z',
//     assignedTo: 'sales_rep_xyz',
//     lastContactedAt: '2026-01-10T11:00:00Z'
//   }
// }

// Get lead activity timeline
const timeline = await pxlpeak.leads.getTimeline('lead_abc123', {
  limit: 50,
  types: ['pageview', 'event', 'email', 'form', 'meeting', 'note']
});

// Returns chronological activity:
// [
//   {
//     type: 'pageview',
//     timestamp: '2026-01-12T14:22:00Z',
//     data: { page: '/pricing', duration: 45, scrollDepth: 80 }
//   },
//   {
//     type: 'email',
//     timestamp: '2026-01-12T10:15:00Z',
//     data: { action: 'clicked', campaign: 'pricing_followup', link: '/demo' }
//   },
//   {
//     type: 'event',
//     timestamp: '2026-01-11T16:30:00Z',
//     data: { name: 'feature_explored', properties: { feature: 'attribution' } }
//   }
// ]

// Configure automatic enrichment
pxlpeak.leads.enrichment.configure({
  providers: [
    {
      name: 'clearbit',
      apiKey: process.env.CLEARBIT_API_KEY,
      enrich: ['company', 'person']
    },
    {
      name: 'zoominfo',
      apiKey: process.env.ZOOMINFO_API_KEY,
      enrich: ['company', 'contacts']
    }
  ],

  // When to enrich
  triggers: {
    onLeadCreate: true,
    onMissingData: true,
    refreshInterval: '30d' // Re-enrich every 30 days
  },

  // Data mapping
  fieldMapping: {
    'clearbit.company.name': 'company.name',
    'clearbit.company.industry': 'company.industry',
    'clearbit.company.employees': 'company.size',
    'clearbit.person.title': 'jobTitle',
    'clearbit.person.seniority': 'seniority'
  }
});

// Manual enrichment
const enrichedLead = await pxlpeak.leads.enrich('lead_abc123');

// Configure lead scoring model
await pxlpeak.leads.scoring.configure({
  // Maximum score
  maxScore: 100,

  // Demographic scoring (who they are)
  demographic: {
    jobTitle: [
      { match: /\b(ceo|cto|cmo|vp|director)\b/i, points: 20 },
      { match: /\b(manager|lead)\b/i, points: 10 },
      { match: /\b(analyst|specialist)\b/i, points: 5 }
    ],

    companySize: [
      { range: [500, Infinity], points: 20 },
      { range: [100, 499], points: 15 },
      { range: [50, 99], points: 10 },
      { range: [10, 49], points: 5 }
    ],

    industry: [
      { match: ['Technology', 'SaaS', 'Software'], points: 15 },
      { match: ['Finance', 'Healthcare'], points: 10 },
      { match: ['Retail', 'E-commerce'], points: 8 }
    ]
  },

  // Behavioral scoring (what they do)
  behavioral: {
    events: [
      { name: 'pricing_page_viewed', points: 10, maxOccurrences: 3 },
      { name: 'demo_requested', points: 25 },
      { name: 'trial_started', points: 30 },
      { name: 'feature_explored', points: 5, maxOccurrences: 5 },
      { name: 'content_downloaded', points: 8, maxOccurrences: 3 },
      { name: 'email_opened', points: 2, maxOccurrences: 5 },
      { name: 'email_clicked', points: 5, maxOccurrences: 5 }
    ],

    pageviews: [
      { urlPattern: /\/pricing/, points: 8 },
      { urlPattern: /\/enterprise/, points: 10 },
      { urlPattern: /\/case-studies/, points: 5 },
      { urlPattern: /\/docs/, points: 3 }
    ],

    engagement: {
      sessionDuration: [
        { minutes: [5, Infinity], points: 5 },
        { minutes: [2, 5], points: 3 }
      ],
      pagesPerSession: [
        { count: [5, Infinity], points: 5 },
        { count: [3, 5], points: 3 }
      ],
      returnVisits: [
        { count: [5, Infinity], points: 10 },
        { count: [3, 5], points: 5 }
      ]
    }
  },

  // Score decay (recency matters)
  decay: {
    enabled: true,
    halfLife: 30, // Days until score halves
    minimumScore: 10,
    excludeEvents: ['demo_requested', 'trial_started'] // These don't decay
  },

  // Negative scoring
  negative: {
    events: [
      { name: 'unsubscribed', points: -20 },
      { name: 'bounced_email', points: -10 }
    ],
    inactivityDays: [
      { days: 30, points: -5 },
      { days: 60, points: -10 },
      { days: 90, points: -15 }
    ]
  }
});

// Define lead qualification thresholds
await pxlpeak.leads.scoring.setThresholds({
  stages: [
    { stage: 'cold', minScore: 0, maxScore: 19 },
    { stage: 'warm', minScore: 20, maxScore: 49 },
    { stage: 'hot', minScore: 50, maxScore: 74 },
    { stage: 'mql', minScore: 75, maxScore: 89 }, // Marketing Qualified Lead
    { stage: 'sql', minScore: 90, maxScore: 100 }  // Sales Qualified Lead
  ],

  // Automatic actions on stage change
  automation: {
    mql: {
      actions: [
        { type: 'notify', recipients: ['sales-team@company.com'] },
        { type: 'slack', channel: '#new-mqls' },
        { type: 'assign', rule: 'round_robin' }
      ]
    },
    sql: {
      actions: [
        { type: 'create_task', assignee: 'owner', task: 'Schedule discovery call' },
        { type: 'sync_crm', priority: 'high' }
      ]
    }
  }
});

// Subscribe to score changes
pxlpeak.leads.scoring.onScoreChange((event) => {
  console.log(`Lead ${event.leadId} score changed: ${event.previousScore} → ${event.newScore}`);
  console.log(`Reason: ${event.reason}`);
  console.log(`New stage: ${event.stage}`);

  if (event.thresholdCrossed === 'mql') {
    // Lead just became an MQL
    notifySalesTeam(event.leadId);
  }
});

// Get scoring breakdown for a lead
const scoreBreakdown = await pxlpeak.leads.scoring.getBreakdown('lead_abc123');
// {
//   totalScore: 78,
//   demographic: {
//     total: 35,
//     breakdown: [
//       { factor: 'jobTitle', value: 'Marketing Director', points: 20 },
//       { factor: 'companySize', value: '50-200', points: 10 },
//       { factor: 'industry', value: 'Technology', points: 5 }
//     ]
//   },
//   behavioral: {
//     total: 48,
//     breakdown: [
//       { factor: 'demo_requested', count: 1, points: 25 },
//       { factor: 'pricing_page_viewed', count: 3, points: 10 },
//       { factor: 'email_clicked', count: 2, points: 8 },
//       { factor: 'return_visits', count: 5, points: 5 }
//     ]
//   },
//   decay: -5,
//   negative: 0
// }

// Create a dynamic segment
const segment = await pxlpeak.leads.segments.create({
  name: 'High-Intent Enterprise Leads',
  description: 'Enterprise leads showing strong buying signals',

  // Dynamic criteria (auto-updates)
  criteria: {
    all: [
      // Company criteria
      { field: 'company.size', operator: 'gte', value: 200 },

      // Score criteria
      { field: 'score', operator: 'gte', value: 50 },

      // Behavioral criteria
      {
        any: [
          { field: 'events.demo_requested', operator: 'exists' },
          { field: 'events.pricing_viewed', operator: 'gte', value: 2 }
        ]
      },

      // Recency
      { field: 'lastSeenAt', operator: 'within', value: '14d' }
    ],

    // Exclusions
    none: [
      { field: 'status', operator: 'eq', value: 'disqualified' },
      { field: 'tags', operator: 'contains', value: 'competitor' }
    ]
  },

  // Refresh frequency
  refreshInterval: 'hourly'
});

// Get segment members
const members = await segment.getMembers({ limit: 100, offset: 0 });

// Trigger actions when leads enter/exit segments
await pxlpeak.leads.segments.setAutomation('segment_xyz', {
  onEnter: [
    {
      action: 'enroll_sequence',
      sequence: 'enterprise_nurture',
      delay: 0
    },
    {
      action: 'tag',
      tags: ['enterprise-prospect']
    },
    {
      action: 'notify',
      channel: 'slack',
      message: 'New enterprise lead: {{lead.name}} from {{lead.company.name}}'
    }
  ],

  onExit: [
    {
      action: 'untag',
      tags: ['enterprise-prospect']
    },
    {
      action: 'remove_from_sequence',
      sequence: 'enterprise_nurture'
    }
  ]
});

// Create a nurture sequence
const sequence = await pxlpeak.leads.sequences.create({
  name: 'Enterprise Nurture Track',
  description: '6-email sequence for enterprise prospects',

  // Enrollment criteria
  enrollment: {
    segments: ['high_intent_enterprise'],
    trigger: 'segment_entry', // or 'manual', 'event'

    // Prevent re-enrollment
    cooldown: '90d',

    // Exit conditions
    exitOn: [
      { event: 'demo_completed' },
      { event: 'trial_started' },
      { status: 'customer' }
    ]
  },

  // Sequence steps
  steps: [
    {
      type: 'email',
      delay: 0, // Immediate
      email: {
        templateId: 'enterprise_welcome',
        subject: 'Welcome to pxlpeak, {{firstName}}',
        fromName: 'Sarah at pxlpeak'
      }
    },
    {
      type: 'wait',
      delay: '3d'
    },
    {
      type: 'email',
      email: {
        templateId: 'enterprise_case_study',
        subject: 'How {{similarCompany}} increased ROI by 40%'
      }
    },
    {
      type: 'condition',
      condition: {
        field: 'events.email_clicked',
        operator: 'gte',
        value: 1,
        window: '7d'
      },
      ifTrue: {
        type: 'email',
        email: { templateId: 'high_engagement_followup' }
      },
      ifFalse: {
        type: 'email',
        email: { templateId: 'low_engagement_reengagement' }
      }
    },
    {
      type: 'wait',
      delay: '5d'
    },
    {
      type: 'task',
      task: {
        title: 'Personal outreach: {{lead.name}}',
        assignee: 'owner',
        dueIn: '2d'
      }
    }
  ],

  // Settings
  settings: {
    sendWindow: { start: '09:00', end: '17:00' },
    timezone: 'lead', // Use lead's timezone
    skipWeekends: true,
    throttle: { maxPerDay: 1 }
  }
});

// Set up personalization rules
await pxlpeak.leads.personalization.configure({
  // Website personalization
  website: {
    rules: [
      {
        segment: 'enterprise_leads',
        changes: [
          { selector: '.hero-headline', content: 'Enterprise Analytics at Scale' },
          { selector: '.cta-button', content: 'Request Enterprise Demo' },
          { selector: '.pricing-cta', hide: true },
          { selector: '.enterprise-banner', show: true }
        ]
      },
      {
        segment: 'returning_visitors',
        changes: [
          { selector: '.hero-headline', content: 'Welcome back, {{firstName}}!' },
          { selector: '.last-viewed', show: true }
        ]
      }
    ]
  },

  // Email personalization
  email: {
    dynamicContent: {
      'industry_content': {
        'technology': 'Tech companies like yours...',
        'healthcare': 'Healthcare organizations need...',
        'default': 'Companies across industries...'
      }
    },

    sendTimeOptimization: {
      enabled: true,
      algorithm: 'engagement_based' // or 'timezone', 'fixed'
    }
  }
});

// Configure lead assignment
await pxlpeak.leads.assignment.configure({
  // Default assignment rule
  default: {
    type: 'round_robin',
    assignees: ['rep_1', 'rep_2', 'rep_3'],

    // Capacity limits
    capacity: {
      maxActiveLeads: 50,
      maxNewPerDay: 10
    },

    // Availability
    respectCalendar: true,
    skipUnavailable: true
  },

  // Segment-specific rules
  rules: [
    {
      segment: 'enterprise_leads',
      type: 'specific',
      assignees: ['enterprise_rep_1', 'enterprise_rep_2'],
      priority: 'high'
    },
    {
      segment: 'inbound_demo_requests',
      type: 'fastest_response',
      assignees: ['all_sales'],
      timeout: '5m' // First to accept gets it
    },
    {
      segment: 'smb_leads',
      type: 'load_balanced',
      assignees: ['smb_team'],
      balanceBy: 'active_leads'
    }
  ],

  // Fallback
  fallback: {
    assignee: 'sales_manager',
    notify: true
  }
});

// Geographic territory assignment
await pxlpeak.leads.assignment.setTerritories({
  territories: [
    {
      name: 'North America - West',
      criteria: {
        any: [
          { field: 'company.location.state', operator: 'in', value: ['CA', 'OR', 'WA', 'NV', 'AZ'] },
          { field: 'company.location.country', operator: 'eq', value: 'CA' } // Canada
        ]
      },
      assignees: ['rep_west_1', 'rep_west_2'],
      type: 'round_robin'
    },
    {
      name: 'North America - East',
      criteria: {
        field: 'company.location.state',
        operator: 'in',
        value: ['NY', 'MA', 'FL', 'TX', 'IL']
      },
      assignees: ['rep_east_1', 'rep_east_2'],
      type: 'round_robin'
    },
    {
      name: 'EMEA',
      criteria: {
        field: 'company.location.continent',
        operator: 'eq',
        value: 'Europe'
      },
      assignees: ['rep_emea'],
      type: 'specific'
    }
  ]
});

// Configure Salesforce integration
await pxlpeak.integrations.configure('salesforce', {
  credentials: {
    instanceUrl: process.env.SF_INSTANCE_URL,
    clientId: process.env.SF_CLIENT_ID,
    clientSecret: process.env.SF_CLIENT_SECRET
  },

  // Object mapping
  mapping: {
    lead: {
      object: 'Lead',
      fields: {
        'email': 'Email',
        'firstName': 'FirstName',
        'lastName': 'LastName',
        'company.name': 'Company',
        'phone': 'Phone',
        'jobTitle': 'Title',
        'score': 'Lead_Score__c',
        'source.type': 'LeadSource'
      }
    },
    contact: {
      object: 'Contact',
      fields: {
        'email': 'Email',
        'firstName': 'FirstName',
        'lastName': 'LastName'
      }
    },
    account: {
      object: 'Account',
      fields: {
        'company.name': 'Name',
        'company.website': 'Website',
        'company.industry': 'Industry'
      }
    }
  },

  // Sync settings
  sync: {
    direction: 'bidirectional', // or 'to_crm', 'from_crm'
    frequency: 'realtime', // or 'hourly', 'daily'

    // Conflict resolution
    conflictResolution: {
      lead: 'crm_wins', // pxlpeak_wins, crm_wins, newest_wins
      activity: 'pxlpeak_wins'
    },

    // Activity sync
    activities: {
      syncPageviews: false, // Too noisy
      syncEvents: true,
      syncEmails: true,
      syncScoreChanges: true
    }
  },

  // Triggers
  triggers: {
    createInCrm: {
      onStage: 'mql',
      createAs: 'Lead'
    },
    convertToContact: {
      onStage: 'customer'
    }
  }
});

// Configure HubSpot integration
await pxlpeak.integrations.configure('hubspot', {
  credentials: {
    apiKey: process.env.HUBSPOT_API_KEY
  },

  mapping: {
    contact: {
      fields: {
        'email': 'email',
        'firstName': 'firstname',
        'lastName': 'lastname',
        'company.name': 'company',
        'score': 'pxlpeak_score',
        'stage': 'lifecyclestage'
      }
    }
  },

  sync: {
    direction: 'bidirectional',
    frequency: 'realtime',

    // Lifecycle stage mapping
    lifecycleStages: {
      'lead': 'lead',
      'mql': 'marketingqualifiedlead',
      'sql': 'salesqualifiedlead',
      'opportunity': 'opportunity',
      'customer': 'customer'
    }
  }
});

// Analyze lead funnel
const funnelData = await pxlpeak.leads.analytics.funnel({
  dateRange: { start: '2026-01-01', end: '2026-01-31' },

  stages: ['visitor', 'lead', 'mql', 'sql', 'opportunity', 'customer'],

  // Breakdown
  groupBy: 'source.type', // or 'campaign', 'segment'

  // Include timing
  includeVelocity: true
});

console.log(funnelData);
// {
//   stages: [
//     { stage: 'visitor', count: 50000, conversionRate: null },
//     { stage: 'lead', count: 2500, conversionRate: 5.0 },
//     { stage: 'mql', count: 625, conversionRate: 25.0 },
//     { stage: 'sql', count: 156, conversionRate: 25.0 },
//     { stage: 'opportunity', count: 78, conversionRate: 50.0 },
//     { stage: 'customer', count: 31, conversionRate: 39.7 }
//   ],
//
//   velocity: {
//     leadToMql: { median: '12 days', average: '15 days' },
//     mqlToSql: { median: '8 days', average: '11 days' },
//     sqlToOpportunity: { median: '14 days', average: '18 days' },
//     opportunityToCustomer: { median: '21 days', average: '28 days' },
//     totalCycle: { median: '55 days', average: '72 days' }
//   },
//
//   bySource: {
//     'organic': { leads: 1000, customers: 15, rate: 1.5 },
//     'paid': { leads: 800, customers: 10, rate: 1.25 },
//     'referral': { leads: 400, customers: 5, rate: 1.25 },
//     'direct': { leads: 300, customers: 1, rate: 0.33 }
//   }
// }

// Generate lead quality report
const qualityReport = await pxlpeak.leads.analytics.quality({
  dateRange: { start: '2026-01-01', end: '2026-01-31' },

  metrics: [
    'lead_volume',
    'avg_score',
    'qualification_rate',
    'conversion_rate',
    'time_to_qualify',
    'disqualification_reasons'
  ],

  dimensions: ['source', 'campaign', 'segment']
});

## Lead Data Quality Checklist

### Capture
- [ ] Required fields enforced (email minimum)
- [ ] Email validation enabled
- [ ] Duplicate detection configured
- [ ] Bot/spam filtering active

### Enrichment
- [ ] Automatic enrichment enabled
- [ ] Regular re-enrichment scheduled
- [ ] Missing data alerts set up

### Maintenance
- [ ] Inactive lead archival (90+ days)
- [ ] Bounced email cleanup
- [ ] Duplicate merge process
- [ ] Data privacy compliance (GDPR/CCPA)

Lead Scoring Guidelines:

1. Start Simple
   - Begin with 5-10 scoring factors
   - Add complexity based on data
   - Review quarterly

2. Balance Demographics & Behavior
   - Demographics: 30-40% of max score
   - Behavior: 60-70% of max score
   - Recent actions weighted higher

3. Include Negative Scoring
   - Unsubscribes: -20 points
   - Email bounces: -10 points
   - Long inactivity: -5 per month

4. Set Clear Thresholds
   - MQL: 75+ points
   - SQL: 90+ points
   - Review conversion rates to adjust

5. Implement Decay
   - Half-life: 30-60 days
   - Keep conversion events permanent
   - Re-score on new activity