@hasna/microservices 0.0.9 → 0.0.10

package/microservices/microservice-leads/src/db/migrations.ts

@@ -0,0 +1,93 @@
+export interface MigrationEntry {
+  id: number;
+  name: string;
+  sql: string;
+}
+
+export const MIGRATIONS: MigrationEntry[] = [
+  {
+    id: 1,
+    name: "core_leads",
+    sql: `
+      CREATE TABLE IF NOT EXISTS leads (
+        id TEXT PRIMARY KEY,
+        name TEXT,
+        email TEXT,
+        phone TEXT,
+        company TEXT,
+        title TEXT,
+        website TEXT,
+        linkedin_url TEXT,
+        source TEXT DEFAULT 'manual',
+        status TEXT DEFAULT 'new' CHECK(status IN ('new','contacted','qualified','unqualified','converted','lost')),
+        score INTEGER DEFAULT 0,
+        score_reason TEXT,
+        tags TEXT DEFAULT '[]',
+        notes TEXT,
+        metadata TEXT DEFAULT '{}',
+        enriched INTEGER DEFAULT 0,
+        enriched_at TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_leads_email ON leads(email) WHERE email IS NOT NULL;
+      CREATE INDEX IF NOT EXISTS idx_leads_status ON leads(status);
+      CREATE INDEX IF NOT EXISTS idx_leads_score ON leads(score DESC);
+      CREATE INDEX IF NOT EXISTS idx_leads_source ON leads(source);
+
+      CREATE TABLE IF NOT EXISTS lead_activities (
+        id TEXT PRIMARY KEY,
+        lead_id TEXT NOT NULL REFERENCES leads(id) ON DELETE CASCADE,
+        type TEXT NOT NULL CHECK(type IN ('email_sent','email_opened','call','meeting','note','status_change','score_change','enriched')),
+        description TEXT,
+        metadata TEXT DEFAULT '{}',
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_activities_lead ON lead_activities(lead_id);
+    `,
+  },
+  {
+    id: 2,
+    name: "enrichment_cache",
+    sql: `
+      CREATE TABLE IF NOT EXISTS enrichment_cache (
+        id TEXT PRIMARY KEY,
+        email TEXT UNIQUE,
+        company_data TEXT DEFAULT '{}',
+        person_data TEXT DEFAULT '{}',
+        social_profiles TEXT DEFAULT '{}',
+        tech_stack TEXT DEFAULT '[]',
+        company_size TEXT,
+        industry TEXT,
+        location TEXT,
+        revenue_range TEXT,
+        fetched_at TEXT,
+        source TEXT
+      );
+    `,
+  },
+  {
+    id: 3,
+    name: "lead_lists",
+    sql: `
+      CREATE TABLE IF NOT EXISTS lead_lists (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        description TEXT,
+        filter_query TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE TABLE IF NOT EXISTS lead_list_members (
+        lead_list_id TEXT NOT NULL,
+        lead_id TEXT NOT NULL,
+        added_at TEXT NOT NULL DEFAULT (datetime('now')),
+        PRIMARY KEY(lead_list_id, lead_id),
+        FOREIGN KEY(lead_list_id) REFERENCES lead_lists(id) ON DELETE CASCADE,
+        FOREIGN KEY(lead_id) REFERENCES leads(id) ON DELETE CASCADE
+      );
+    `,
+  },
+];

package/microservices/microservice-leads/src/index.ts

@@ -0,0 +1,65 @@
+/**
+ * microservice-leads — Lead generation, storage, scoring, and data enrichment microservice
+ */
+
+export {
+  createLead,
+  getLead,
+  listLeads,
+  updateLead,
+  deleteLead,
+  searchLeads,
+  findByEmail,
+  bulkImportLeads,
+  exportLeads,
+  addActivity,
+  getActivities,
+  getLeadTimeline,
+  getLeadStats,
+  getPipeline,
+  deduplicateLeads,
+  mergeLeads,
+  type Lead,
+  type CreateLeadInput,
+  type UpdateLeadInput,
+  type ListLeadsOptions,
+  type LeadActivity,
+  type LeadStats,
+  type PipelineStage,
+  type BulkImportResult,
+  type DuplicatePair,
+} from "./db/leads.js";
+
+export {
+  createList,
+  getList,
+  listLists,
+  deleteList,
+  addToList,
+  removeFromList,
+  getListMembers,
+  getSmartListMembers,
+  type LeadList,
+  type CreateListInput,
+} from "./db/lists.js";
+
+export {
+  enrichLead,
+  enrichFromEmail,
+  enrichFromDomain,
+  getCachedEnrichment,
+  cacheEnrichment,
+  bulkEnrich,
+  type EnrichmentData,
+  type CachedEnrichment,
+} from "./lib/enrichment.js";
+
+export {
+  scoreLead,
+  autoScoreAll,
+  getScoreDistribution,
+  type ScoreResult,
+  type ScoreDistribution,
+} from "./lib/scoring.js";
+
+export { getDatabase, closeDatabase } from "./db/database.js";

package/microservices/microservice-leads/src/lib/enrichment.ts

@@ -0,0 +1,202 @@
+/**
+ * Lead enrichment — AI-powered data enrichment from email and domain
+ */
+
+import { getDatabase } from "../db/database.js";
+import { getLead, updateLead, addActivity } from "../db/leads.js";
+
+export interface EnrichmentData {
+  company?: string;
+  title?: string;
+  industry?: string;
+  location?: string;
+  company_size?: string;
+  revenue_range?: string;
+  tech_stack?: string[];
+  social_profiles?: Record<string, string>;
+  person_data?: Record<string, unknown>;
+  company_data?: Record<string, unknown>;
+}
+
+export interface CachedEnrichment {
+  id: string;
+  email: string;
+  company_data: Record<string, unknown>;
+  person_data: Record<string, unknown>;
+  social_profiles: Record<string, string>;
+  tech_stack: string[];
+  company_size: string | null;
+  industry: string | null;
+  location: string | null;
+  revenue_range: string | null;
+  fetched_at: string | null;
+  source: string | null;
+}
+
+interface CacheRow {
+  id: string;
+  email: string;
+  company_data: string;
+  person_data: string;
+  social_profiles: string;
+  tech_stack: string;
+  company_size: string | null;
+  industry: string | null;
+  location: string | null;
+  revenue_range: string | null;
+  fetched_at: string | null;
+  source: string | null;
+}
+
+function rowToCache(row: CacheRow): CachedEnrichment {
+  return {
+    ...row,
+    company_data: JSON.parse(row.company_data || "{}"),
+    person_data: JSON.parse(row.person_data || "{}"),
+    social_profiles: JSON.parse(row.social_profiles || "{}"),
+    tech_stack: JSON.parse(row.tech_stack || "[]"),
+  };
+}
+
+export function getCachedEnrichment(email: string): CachedEnrichment | null {
+  const db = getDatabase();
+  const row = db
+    .prepare("SELECT * FROM enrichment_cache WHERE email = ?")
+    .get(email) as CacheRow | null;
+  return row ? rowToCache(row) : null;
+}
+
+export function cacheEnrichment(email: string, data: EnrichmentData): CachedEnrichment {
+  const db = getDatabase();
+  const id = crypto.randomUUID();
+
+  db.prepare(
+    `INSERT OR REPLACE INTO enrichment_cache
+     (id, email, company_data, person_data, social_profiles, tech_stack, company_size, industry, location, revenue_range, fetched_at, source)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'), 'ai')`
+  ).run(
+    id,
+    email,
+    JSON.stringify(data.company_data || {}),
+    JSON.stringify(data.person_data || {}),
+    JSON.stringify(data.social_profiles || {}),
+    JSON.stringify(data.tech_stack || []),
+    data.company_size || null,
+    data.industry || null,
+    data.location || null,
+    data.revenue_range || null
+  );
+
+  return getCachedEnrichment(email)!;
+}
+
+/**
+ * Enrich a lead from email — uses AI to research the person based on email domain.
+ * Returns enrichment data. In a production setup, this would call OpenAI/Anthropic.
+ * For now, returns domain-based heuristics.
+ */
+export function enrichFromEmail(email: string): EnrichmentData {
+  const domain = email.split("@")[1];
+  if (!domain) return {};
+
+  // Check cache first
+  const cached = getCachedEnrichment(email);
+  if (cached) {
+    return {
+      company: cached.company_data?.name as string | undefined,
+      industry: cached.industry || undefined,
+      location: cached.location || undefined,
+      company_size: cached.company_size || undefined,
+      revenue_range: cached.revenue_range || undefined,
+      tech_stack: cached.tech_stack,
+      social_profiles: cached.social_profiles,
+      person_data: cached.person_data,
+      company_data: cached.company_data,
+    };
+  }
+
+  // Domain-based heuristic enrichment (production would call AI APIs)
+  const data: EnrichmentData = {};
+
+  // Detect company from email domain
+  const freeEmailDomains = ["gmail.com", "yahoo.com", "hotmail.com", "outlook.com", "aol.com", "protonmail.com"];
+  if (!freeEmailDomains.includes(domain)) {
+    data.company = domain.split(".")[0].charAt(0).toUpperCase() + domain.split(".")[0].slice(1);
+    data.company_data = { domain, name: data.company };
+  }
+
+  // Cache the result
+  cacheEnrichment(email, data);
+
+  return data;
+}
+
+/**
+ * Enrich from domain — AI researches company info.
+ * Returns company data. Production would call AI APIs.
+ */
+export function enrichFromDomain(domain: string): EnrichmentData {
+  const data: EnrichmentData = {};
+  const companyName = domain.split(".")[0].charAt(0).toUpperCase() + domain.split(".")[0].slice(1);
+  data.company = companyName;
+  data.company_data = { domain, name: companyName };
+  return data;
+}
+
+/**
+ * Enrich a single lead by ID
+ */
+export function enrichLead(leadId: string): Lead | null {
+  const lead = getLead(leadId);
+  if (!lead) return null;
+
+  let enrichmentData: EnrichmentData = {};
+
+  if (lead.email) {
+    enrichmentData = enrichFromEmail(lead.email);
+  } else if (lead.website) {
+    try {
+      const domain = new URL(lead.website.startsWith("http") ? lead.website : `https://${lead.website}`).hostname;
+      enrichmentData = enrichFromDomain(domain);
+    } catch {
+      // Invalid URL, skip
+    }
+  }
+
+  // Update lead with enriched data
+  const updates: Record<string, unknown> = { enriched: true, enriched_at: new Date().toISOString() };
+  if (enrichmentData.company && !lead.company) updates.company = enrichmentData.company;
+  if (enrichmentData.title && !lead.title) updates.title = enrichmentData.title;
+  if (enrichmentData.industry) {
+    const meta = { ...lead.metadata, industry: enrichmentData.industry };
+    updates.metadata = meta;
+  }
+
+  updateLead(leadId, updates as any);
+  addActivity(leadId, "enriched", `Enriched from ${lead.email || lead.website || "unknown"}`);
+
+  return getLead(leadId);
+}
+
+// Import Lead type for return
+import type { Lead } from "../db/leads.js";
+
+/**
+ * Bulk enrich multiple leads
+ */
+export function bulkEnrich(leadIds: string[]): { enriched: number; failed: number } {
+  let enriched = 0;
+  let failed = 0;
+
+  for (const id of leadIds) {
+    try {
+      const result = enrichLead(id);
+      if (result) enriched++;
+      else failed++;
+    } catch {
+      failed++;
+    }
+  }
+
+  return { enriched, failed };
+}

package/microservices/microservice-leads/src/lib/scoring.ts

@@ -0,0 +1,134 @@
+/**
+ * Lead scoring — rule-based scoring with AI fallback
+ */
+
+import { getLead, updateLead, addActivity, getActivities, listLeads } from "../db/leads.js";
+import type { Lead } from "../db/leads.js";
+
+export interface ScoreResult {
+  score: number;
+  reason: string;
+}
+
+const FREE_EMAIL_DOMAINS = [
+  "gmail.com", "yahoo.com", "hotmail.com", "outlook.com",
+  "aol.com", "protonmail.com", "mail.com", "icloud.com",
+];
+
+/**
+ * Score a lead using rule-based analysis.
+ * Returns score 0-100 with reason.
+ */
+export function scoreLead(leadId: string): ScoreResult | null {
+  const lead = getLead(leadId);
+  if (!lead) return null;
+
+  let score = 0;
+  const reasons: string[] = [];
+
+  // +10 for company email (not free provider)
+  if (lead.email) {
+    const domain = lead.email.split("@")[1];
+    if (domain && !FREE_EMAIL_DOMAINS.includes(domain)) {
+      score += 10;
+      reasons.push("company email (+10)");
+    }
+  }
+
+  // +15 for having a title
+  if (lead.title) {
+    score += 15;
+    reasons.push("has title (+15)");
+
+    // Bonus for decision-maker titles
+    const decisionMakerKeywords = ["ceo", "cto", "cfo", "coo", "vp", "director", "head", "chief", "founder", "owner", "president"];
+    const titleLower = lead.title.toLowerCase();
+    if (decisionMakerKeywords.some((kw) => titleLower.includes(kw))) {
+      score += 10;
+      reasons.push("decision maker title (+10)");
+    }
+  }
+
+  // +10 for having a phone number
+  if (lead.phone) {
+    score += 10;
+    reasons.push("has phone (+10)");
+  }
+
+  // +20 for having LinkedIn
+  if (lead.linkedin_url) {
+    score += 20;
+    reasons.push("has LinkedIn (+20)");
+  }
+
+  // +10 for having a company
+  if (lead.company) {
+    score += 10;
+    reasons.push("has company (+10)");
+  }
+
+  // +5 per activity (up to 25)
+  const activities = getActivities(leadId);
+  const activityScore = Math.min(activities.length * 5, 25);
+  if (activityScore > 0) {
+    score += activityScore;
+    reasons.push(`${activities.length} activities (+${activityScore})`);
+  }
+
+  // +5 for being enriched
+  if (lead.enriched) {
+    score += 5;
+    reasons.push("enriched (+5)");
+  }
+
+  // Cap at 100
+  score = Math.min(score, 100);
+
+  const reason = reasons.join(", ") || "no scoring signals";
+
+  // Update the lead
+  updateLead(leadId, { score, score_reason: reason });
+  addActivity(leadId, "score_change", `Score updated to ${score}: ${reason}`);
+
+  return { score, reason };
+}
+
+/**
+ * Auto-score all leads with score=0
+ */
+export function autoScoreAll(): { scored: number; total: number } {
+  const leads = listLeads();
+  const unscored = leads.filter((l) => l.score === 0);
+  let scored = 0;
+
+  for (const lead of unscored) {
+    const result = scoreLead(lead.id);
+    if (result) scored++;
+  }
+
+  return { scored, total: unscored.length };
+}
+
+export interface ScoreDistribution {
+  range: string;
+  count: number;
+}
+
+/**
+ * Get score distribution across all leads
+ */
+export function getScoreDistribution(): ScoreDistribution[] {
+  const leads = listLeads();
+  const ranges = [
+    { range: "0-20", min: 0, max: 20 },
+    { range: "21-40", min: 21, max: 40 },
+    { range: "41-60", min: 41, max: 60 },
+    { range: "61-80", min: 61, max: 80 },
+    { range: "81-100", min: 81, max: 100 },
+  ];
+
+  return ranges.map(({ range, min, max }) => ({
+    range,
+    count: leads.filter((l) => l.score >= min && l.score <= max).length,
+  }));
+}