@kido/lead-crmCopy Anchor Link

Architecture Paradigm: Strict Vietnam Telecom Prefix Validation + Stateful Weighted Round-Robin Distributor + Zero-Drop Google Sheets Webhook Dispatcher.

💥 The Real-World BottleneckCopy Anchor Link

Paid marketing campaigns (Facebook Ads, Google Search, TikTok Form Leads) burn thousands of dollars daily, yet lead routing frequently breaks at the ingestion boundary:

1. Vietnam Telecom Format & Carrier Chaos: Landing pages collect numbers formatted in unpredictable ways (+84 987 654 321, 84987654321, 098.765.4321, (098) 765-4321). Naive databases store raw strings that break outbound VOIP auto-dialers (Stringee, Callio) and SMS OTP gateways.
2. Sales Rep Cherry-Picking & Unfair Lead Distribution: When leads land in a shared Slack channel or public sheet, senior reps cherry-pick high-ticket enterprise leads while junior reps starve. This creates toxic team friction and delays First-Response-Time (FRT) beyond the golden 5-minute conversion window.
3. Google Sheets Leading Zero Truncation & CSV Injection: Without explicit text formatting ('0905...), Google Sheets treats Vietnamese phone numbers as integers, stripping leading zeros (0905123456 becomes 905123456). Furthermore, unescaped form fields starting with =, +, or - expose internal spreadsheets to formula injection attacks.

🏛️ 3-Tier Production Evolution LadderCopy Anchor Link

📦 Architecture & Core API ExportsCopy Anchor Link

packages/lead-crm/
├── src/
│   ├── types.ts          # LeadInput, LeadRecord, SalesAgent, UtmParams, Zod schemas
│   ├── validator.ts      # cleanPhoneNumber, isValidVietnamesePhone, getVietnameseCarrier, ingestLead
│   ├── distribution.ts   # RoundRobinDistributor, distributeRoundRobin, DistributorState
│   ├── sheets.ts         # formatGoogleSheetPayload, createGoogleSheetsWebhookRequest, formatVietnamDateTime
│   └── index.ts          # SSoT Barrel Export

Core APIsCopy Anchor Link

1. validator.tsCopy Anchor Link

• cleanPhoneNumber(raw): Strips non-digit characters, converts international +84 / 84 prefixes to standard domestic 0 format.
• isValidVietnamesePhone(phone): Validates phone against official Vietnamese 10-digit numbering regulations (/^0(3[2-9]|5[25689]|7[06-9]|8[1-9]|9\d)\d{7}$/).
• getVietnameseCarrier(phone): Identifies telecom carrier (VIETTEL, MOBIFONE, VINAPHONE, VIETNAMOBILE, GTEL, WINTEL).
• ingestLead(rawInput): Unified entry point validating names, cleaning phones, sanitizing emails, normalizing UTM parameters, and emitting timestamped LeadRecord objects.

2. distribution.tsCopy Anchor Link

• RoundRobinDistributor: Class managing fair lead rotation across active agents. Supports fractional weights, agent enabling/disabling, and deterministic index persistence.
• distributeRoundRobin(agents, currentIndex): Pure functional distribution helper.

3. sheets.tsCopy Anchor Link

• formatPhoneForGoogleSheets(phone): Prepends single quote ('098...) to prevent spreadsheet cell truncation.
• formatGoogleSheetPayload(lead, headers?): Formats structured JSON rows matching Google Apps Script webhooks.
• createGoogleSheetsWebhookRequest(options): Generates complete fetch request options with timeout and Content-Type headers.

💻 Production Implementation & Code SnippetCopy Anchor Link

The following code illustrates an end-to-end webhook handler: ingesting raw landing page leads, identifying the Vietnamese carrier, assigning the lead via weighted round-robin, and dispatching to Google Sheets.

import {
  ingestLead,
  getVietnameseCarrier,
  RoundRobinDistributor,
  createGoogleSheetsWebhookRequest,
  type SalesAgent,
} from '@kido/lead-crm';

// 1. Configure Available Sales Representatives with Weights
const salesTeam: SalesAgent[] = [
  { id: 'agent-01', name: 'Trần Minh Quân', email: 'quan.tm@example.com', weight: 2, isActive: true },
  { id: 'agent-02', name: 'Lê Hoàng Yến', email: 'yen.lh@example.com', weight: 1, isActive: true },
  { id: 'agent-03', name: 'Nguyễn Văn Đạt', email: 'dat.nv@example.com', weight: 1, isActive: true },
];

const distributor = new RoundRobinDistributor(salesTeam);

// 2. Ingest raw landing page payload from web form
const rawFormData = {
  fullName: 'Phạm Thanh Bình',
  phone: '+84 (098) 765-4321', // Dirty format
  email: 'binh.pt@company.vn',
  serviceInterest: 'Gói Tư Vấn Chuyển Đổi Số AI',
  notes: 'Cần tư vấn trong sáng mai',
  utm_source: 'facebook_ads',
  utm_campaign: 'q4_enterprise_ai',
};

const ingestion = ingestLead(rawFormData);

if (!ingestion.success) {
  console.error('Lead Rejected:', ingestion.errors);
  process.exit(1);
}

const cleanLead = ingestion.data;
const carrier = getVietnameseCarrier(cleanLead.phone);

console.log('Ingested Clean Lead:', {
  id: cleanLead.id,
  name: cleanLead.fullName,
  phone: cleanLead.phone,               // "0987654321"
  displayPhone: cleanLead.phoneDisplay, // "0987 654 321"
  e164: cleanLead.phoneE164,           // "+84987654321"
  carrier,                              // "VIETTEL"
  utmSource: cleanLead.utm.source,      // "facebook_ads"
});

// 3. Assign Lead via Weighted Round-Robin
const assignedAgent = distributor.getNextAgent();
console.log(`Lead assigned to Sales Rep: ${assignedAgent?.name} (${assignedAgent?.email})`);

// 4. Dispatch to Google Sheets Webhook
const webhookUrl = 'https://script.google.com/macros/s/AKfycbx_EXAMPLE_APPS_SCRIPT_DEPLOYMENT_ID/exec';

const { url, options } = createGoogleSheetsWebhookRequest({
  webhookUrl,
  lead: {
    ...cleanLead,
    assignedTo: assignedAgent?.name,
  },
  timeoutMs: 5000,
});

async function syncToGoogleSheets() {
  try {
    const response = await fetch(url, options);
    console.log(`Google Sheets Sync Status: ${response.status}`);
  } catch (err) {
    console.error('Google Sheets Sync Failed:', err);
  }
}

syncToGoogleSheets();

⚡ Benchmark & Verified k6 PerformanceCopy Anchor Link

Tested on Bun runtime executing 100,000 lead operations:

🚀 Surgical Extraction & CLI InstallationCopy Anchor Link

# Install lead CRM package
npx @kido/cli add @kido/lead-crm