@foundrynorth/compass-schema 1.0.10 → 1.0.11

package/src/analyzeTypes.ts

@@ -0,0 +1,1072 @@
+// shared/analyzeTypes.ts
+
+import { z } from 'zod';
+
+/**
+ * SERVICE AREA TYPES
+ * For home service businesses (HVAC, plumbing, electrical, etc.),
+ * competition is based on service area overlap rather than physical distance.
+ */
+
+export type BusinessType = 'retail' | 'restaurant' | 'service_business' | 'other';
+
+export interface ServiceArea {
+  zips?: string[];
+  cities?: string[];
+  namedRegions?: string[];
+  radiusMiles?: number;
+  coverageScore?: number;
+}
+
+export interface ServiceAreaOverlap {
+  overlapZips: string[];
+  overlapCities: string[];
+  overlapRatio: number;
+  competitorTier: 'primary' | 'secondary' | 'peripheral';
+}
+
+/**
+ * CANONICAL COMPETITOR TYPE
+ * Single source of truth for competitor representation across the platform.
+ * Use this type for:
+ * - Enrichment persistence
+ * - Prompt construction
+ * - UI display on competitor cards
+ * 
+ * This type normalizes competitors from all sources (Google Places, DataForSEO, Perplexity)
+ * into a consistent shape for the entire application.
+ */
+export interface CanonicalCompetitor {
+  id: string;
+  name: string;
+  domain?: string;
+  placeId?: string;
+  location?: { 
+    lat: number; 
+    lng: number; 
+    city?: string; 
+    state?: string;
+    address?: string;
+  };
+  category?: string;
+  sources: string[];
+  metrics?: { 
+    searchShare?: number; 
+    estClicks?: number; 
+    estSpend?: number;
+    rating?: number;
+    reviewCount?: number;
+  };
+  
+  // Chain/multi-location support
+  isChain?: boolean;
+  chainId?: string;
+  chainName?: string;
+  chainType?: 'national' | 'regional' | 'local';
+  locations?: ChainLocation[];
+  locationCount?: number;
+  /**
+   * Selection mode for multi-location chains:
+   * - 'single': Only this specific location
+   * - 'dma': All locations in the same DMA as prospect
+   * - 'overlap': All locations overlapping with prospect's service area
+   * - 'all': All locations nationwide (legacy 'chain' mode)
+   */
+  selectionMode?: ChainSelectionMode;
+  // Which locations were selected (place_ids)
+  selectedLocationIds?: string[];
+  // Counts by selection mode (populated by worker when DMA data available)
+  locationsByMode?: {
+    dma?: number;      // Count of locations in prospect's DMA
+    overlap?: number;  // Count of locations overlapping prospect service area
+    all: number;       // Total location count
+  };
+  aggregatedMetrics?: {
+    totalReviews?: number;
+    avgRating?: number;
+    serviceAreaUnion?: ServiceArea;
+  };
+}
+
+/**
+ * Chain selection mode for multi-location businesses
+ * Determines how many locations to include in analysis
+ */
+export type ChainSelectionMode = 'single' | 'dma' | 'overlap' | 'all';
+
+/**
+ * Individual location within a chain
+ * Used when a competitor or prospect has multiple locations in the market
+ */
+export interface ChainLocation {
+  placeId: string;
+  name: string;
+  address?: string;
+  city?: string;
+  state?: string;
+  lat?: number;
+  lng?: number;
+  distance_km?: number;
+  rating?: number;
+  reviewCount?: number;
+  isPrimary?: boolean;
+  // DMA/geographic filtering (populated by worker when available)
+  dmaCode?: string;         // DMA code (e.g., "613" for Minneapolis)
+  dmaName?: string;         // DMA name (e.g., "Minneapolis-St. Paul")
+  inProspectDma?: boolean;  // Is this location in the same DMA as prospect?
+  overlapsProspect?: boolean; // Does this location's service area overlap prospect?
+}
+
+/**
+ * COMPETITOR CREATIVE TYPES
+ * Unified interface for ad creatives from Google Ads and Facebook Ads
+ * Used for UI display and media planning prompts
+ */
+export interface CompetitorCreative {
+  source: 'google_ads' | 'facebook_ads';
+  platform: 'google' | 'facebook' | 'instagram' | 'audience_network';
+  accountName?: string;
+  accountId?: string;
+  headline?: string;
+  primaryText?: string;
+  description?: string;
+  cta?: string;
+  ctaType?: string;
+  landingUrl?: string;
+  imageUrl?: string;
+  imageUrls?: string[] | Array<{ original: string; resized: string }>;
+  videoUrl?: string;
+  format?: string; // responsive search, display, video, carousel, etc
+  impressions?: number | null;
+  region?: string | null;
+  startDate?: string | null;
+  endDate?: string | null;
+  pageProfileUrl?: string;
+  pageProfilePicture?: string;
+  pageLikeCount?: number;
+  pageCategories?: string[];
+  adLibraryUrl?: string;
+  sourceUrl?: string;
+  raw?: unknown; // keep raw payload for debugging
+}
+
+/**
+ * Facebook Ad structure (from curious_coder/facebook-ads-library-scraper)
+ * Extended to include all fields from the actual API response
+ */
+export interface FacebookAdCreative {
+  adId?: string;
+  adArchiveId?: string;
+  adImage?: string;
+  adImages?: Array<{ original: string; resized: string }>;
+  adCopy?: string;
+  headline?: string;
+  callToAction?: string;
+  ctaType?: string;
+  ctaLink?: string;
+  publisherPlatforms?: string[];
+  startDate?: string;
+  endDate?: string;
+  status?: string;
+  pageName?: string;
+  pageProfileUrl?: string;
+  pageProfilePicture?: string;
+  pageLikeCount?: number;
+  pageCategories?: string[];
+  displayFormat?: string;
+  adLibraryUrl?: string;
+}
+
+/**
+ * Summary of creatives for a competitor
+ */
+export interface CompetitorCreativeSummary {
+  googleAdsCount: number;
+  facebookAdsCount: number;
+  totalCount: number;
+  creatives: CompetitorCreative[];
+}
+
+/**
+ * CRITICAL CHANGE: Known competitors are now REQUIRED (1-5)
+ * Discovery is OPTIONAL and defaults to OFF
+ */
+export const KnownCompetitorSchema = z.object({
+  name: z.string()
+    .min(2, 'Competitor name must be at least 2 characters')
+    .max(100, 'Competitor name too long'),
+
+  placeId: z.string().optional(),
+  // If user already has the Google Place ID (e.g., from previous search)
+
+  notes: z.string().max(200).optional(),
+  // Optional context: "Main competitor", "They dominate paid search", etc.
+
+  address: z.string().optional(),
+  // User can provide address to help disambiguation
+
+  website: z.string()
+    .optional()
+    .transform((val) => {
+      // Allow flexible URL input - normalize to full URL
+      if (!val || val.trim() === '') return undefined;
+      const trimmed = val.trim();
+      
+      // Already has protocol
+      if (trimmed.startsWith('http://') || trimmed.startsWith('https://')) {
+        return trimmed;
+      }
+      
+      // Add https:// if missing
+      return `https://${trimmed}`;
+    })
+  // If user knows the website, helps with validation
+});
+
+export const AnalyzePlanInputSchema = z.object({
+  // =================================================
+  // PROSPECT INFORMATION (mostly unchanged)
+  // =================================================
+  name: z.string().optional(),
+  placeId: z.string().optional(),
+  
+  // Legacy/alternative field names for compatibility
+  brand: z.string().optional(),  // Alternative to 'name'
+  businessName: z.string().optional(),  // Alternative to 'name'
+
+  city: z.string().optional(),
+  state: z.string().optional(),
+  geo: z.string().optional(),
+  targetGeo: z.string().optional(),  // Alternative to 'geo'
+  lat: z.number().optional(),
+  lng: z.number().optional(),
+  
+  // Chain detection and area selection
+  chainDetected: z.boolean().optional(),
+  selectedAreas: z.array(z.string()).optional(),  // Selected geographic areas for chain analysis
+
+  businessDescription: z.string()
+    .optional()
+    .default('')
+    .transform((val) => val?.trim() || ''),
+  // businessDescription is OPTIONAL - category and placeId provide sufficient context for analysis
+
+  url: z.string()
+    .optional()
+    .transform((val) => {
+      // Allow flexible URL input - normalize to full URL
+      if (!val || val.trim() === '') return undefined;
+      const trimmed = val.trim();
+      
+      // Already has protocol
+      if (trimmed.startsWith('http://') || trimmed.startsWith('https://')) {
+        return trimmed;
+      }
+      
+      // Add https:// if missing
+      return `https://${trimmed}`;
+    }),
+
+  // =================================================
+  // COMPETITOR INFORMATION (NEW PRIMARY INPUT)
+  // =================================================
+  knownCompetitors: z.array(KnownCompetitorSchema)
+    .min(1, 'Provide at least 1 known competitor')
+    .max(5, 'Maximum 5 competitors allowed')
+    .refine(
+      (competitors) => {
+        const names = competitors.map(c => c.name.toLowerCase().trim());
+        return new Set(names).size === names.length;
+      },
+      'Duplicate competitor names not allowed'
+    ),
+
+  // =================================================
+  // OPTIONAL AI DISCOVERY
+  // =================================================
+  discoverAdditional: z.boolean().default(false),
+  // Should we find 1-2 more competitors?
+
+  maxAdditionalCompetitors: z.number()
+    .min(0)
+    .max(3)
+    .default(1),
+  // How many additional to find (if discovery enabled)
+
+  // =================================================
+  // ACTIVE MARKET SELECTION (NEW)
+  // =================================================
+  marketId: z.string().optional(),
+  // The active market ID for location bias (e.g., 'mkt_twin-cities')
+  
+  marketCenter: z.object({
+    lat: z.number(),
+    lng: z.number()
+  }).optional(),
+  // Market center coordinates for location-biased API calls
+
+  // =================================================
+  // SERVICE AREA CONFIGURATION (NEW)
+  // =================================================
+  serviceAreaConfig: z.object({
+    type: z.enum(['physical', 'hq_radius', 'metro', 'custom_zips']).default('physical'),
+    radiusMiles: z.number().min(5).max(150).optional(),
+    zipCodes: z.array(z.string()).optional(),
+  }).optional(),
+  // Configuration details: physical (single location), hq_radius (X miles from HQ),
+  // metro (entire metro area), custom_zips (specific zip codes)
+
+  // =================================================
+  // PROSPECT CHAIN/MULTI-LOCATION CONFIGURATION
+  // =================================================
+  prospectPlaceId: z.string().optional(),
+  // Google Place ID for the prospect (if chain, this is the selected location)
+  
+  prospectBrandName: z.string().optional(),
+  // Canonical brand name for chains (e.g., "Caribou Coffee" instead of "Caribou Coffee - Minneapolis")
+  // Used by worker for location enumeration. For non-chains, this may equal the display name.
+  
+  prospectChainMode: z.enum(['single', 'dma', 'overlap', 'all']).optional(),
+  // How to handle prospect if they are a multi-location chain:
+  // - 'single': Analyze only the selected location
+  // - 'dma': Analyze all locations in the prospect's DMA
+  // - 'overlap': Analyze locations overlapping with active market
+  // - 'all': Analyze all locations (default legacy behavior)
+  
+  prospectLocationCount: z.number().optional(),
+  // Total locations for the prospect chain (for UI display)
+
+  // Option D: user-selected locations from multi-result search (worker uses these instead of enumerating)
+  prospectLocations: z.array(z.object({
+    placeId: z.string(),
+    name: z.string().optional(),
+    address: z.string().optional(),
+    city: z.string().optional(),
+    state: z.string().optional(),
+    lat: z.number().optional(),
+    lng: z.number().optional(),
+  })).optional(),
+
+  // =================================================
+  // OPTIONAL METADATA
+  // =================================================
+  budget: z.object({
+    min: z.number().positive(),
+    max: z.number().positive()
+  }).optional(),
+
+  planTotalBudget: z.number().positive().optional(),
+  planDurationMonths: z.number().int().positive().optional(),
+
+  goals: z.array(z.string()).optional(),
+
+  // User override for business category (takes precedence over Google Places)
+  category: z.string().optional(),
+
+  // Analysis depth - controls how deep the enrichment and planning phases go
+  analysisDepth: z.enum(['standard', 'deep']).optional().default('deep'),
+
+  // =================================================
+  // HUBSPOT PRE-LINKED COMPANY (from frontend typeahead)
+  // =================================================
+  hubspotCompanyId: z.string().optional(),
+  hubspotUrl: z.string().optional(),
+});
+
+export type KnownCompetitor = z.infer<typeof KnownCompetitorSchema>;
+export type AnalyzePlanInput = z.infer<typeof AnalyzePlanInputSchema>;
+
+/**
+ * Validation state after processing
+ */
+export interface ValidatedCompetitor extends KnownCompetitor {
+  // Google Places validation results
+  validated: boolean | 'needs_clarification';
+  status: 'confirmed' | 'not_found' | 'multiple_matches';
+  confidence: number; // 0-100
+
+  // If validated successfully
+  placeId?: string;
+  verifiedName?: string; // Official name from Google
+  verifiedAddress?: string;
+  geometry?: {
+    lat: number;
+    lng: number;
+  };
+  category?: string;
+  rating?: number;
+  reviewCount?: number;
+
+  // If multiple matches found
+  options?: Array<{
+    placeId: string;
+    name: string;
+    address: string;
+    distance?: number; // km from prospect
+  }>;
+
+  // If not found
+  suggestion?: string;
+
+  // Source tracking
+  source: 'user_provided' | 'ai_suggested';
+  originalName?: string; // What user typed vs. what Google says
+
+  // Service area support (for HVAC, plumbing, etc.)
+  businessType?: BusinessType;
+  serviceArea?: ServiceArea | null;
+  serviceAreaOverlap?: ServiceAreaOverlap | null;
+}
+
+/**
+ * Base business profile (minimal required fields)
+ */
+export interface BaseBusinessProfile {
+  name: string;
+  placeId: string | null;
+  address: string;
+  category?: string;
+  rating?: number;
+  reviewCount?: number;
+  phone?: string;
+  website?: string;
+  seeded?: boolean;
+  source?: string;
+  validationBypassed?: boolean;
+  bypassedAI?: boolean;
+  lat?: number;
+  lng?: number;
+}
+
+/**
+ * Enrichment augmentation data (additional fields added during enrichment)
+ */
+export interface EnrichmentAugmentation {
+  digitalMaturity?: number;
+  maturityStage?: string;
+  strengths?: string[];
+  gaps?: string[];
+  competitiveContext?: any;
+  comparativeInsights?: any;
+  [key: string]: any; // Allow additional enrichment fields
+}
+
+/**
+ * Validated business (base profile + enrichment data)
+ */
+export interface ValidatedBusiness extends BaseBusinessProfile, Partial<EnrichmentAugmentation> {
+  validated: boolean;
+}
+
+/**
+ * Fully enriched business (all enrichment fields guaranteed)
+ */
+export interface FullyEnrichedBusiness extends ValidatedBusiness {
+  digitalMaturity: number;
+  maturityStage: string;
+  strengths: string[];
+  gaps: string[];
+}
+
+/**
+ * Enrichment result structure
+ */
+export interface EnrichedBusiness {
+  // Core identity
+  placeId: string;
+  name: string;
+  address: string;
+  city: string;
+  state: string;
+  lat: number;
+  lng: number;
+  category: string;
+
+  // Service area support (for HVAC, plumbing, etc.)
+  businessType?: BusinessType;
+  serviceArea?: ServiceArea | null;
+  serviceAreaOverlap?: ServiceAreaOverlap | null;
+
+  // Basic metrics
+  rating: number;
+  reviewCount: number;
+
+  // DEEP enrichment data
+  metaAds: {
+    present: boolean;
+    activeCount: number;
+    totalSeen: number;
+    oldestAdDate: string | null;
+    impressionsRange: string | null;
+
+    // NEW: Creative analysis
+    creative?: {
+      themes: string[];        // ["discount", "quality", "emergency service"]
+      messaging: string[];     // Key phrases from ad copy
+      visualStyle: string;     // "professional" | "playful" | "urgent"
+      offers: string[];        // ["20% off", "free estimate", "same-day"]
+      ctaTypes: string[];      // ["Learn More", "Book Now", "Call Now"]
+      // Actual ad data from Facebook Ads Library (via Apify)
+      ads?: Array<{
+        adId?: string;
+        adImage?: string;       // URL to ad creative image
+        adCopy?: string;        // Full ad body text
+        headline?: string;      // Ad headline
+        callToAction?: string;  // CTA button text
+        publisherPlatforms?: string[];  // ["Facebook", "Instagram"]
+        startDate?: string;     // When ad started running
+        status?: string;        // "active" | "inactive"
+      }>;
+    };
+
+    // NEW: Audience insights
+    audience?: {
+      platforms: string[];     // ["Facebook", "Instagram"]
+      ageRanges: string[];     // ["25-34", "35-44"]
+      genders: string[];       // ["All", "Male", "Female"]
+      interests: string[];     // Inferred from creative themes
+    };
+
+    // NEW: Spend estimation
+    estimatedSpend?: {
+      monthly: number;
+      confidence: 'low' | 'medium' | 'high';
+      basis: string;           // How we calculated it
+    };
+  };
+
+  // Website analysis
+  website: {
+    url: string | null;
+    accessible: boolean;
+
+    // NEW: SEO audit
+    seo?: {
+      titleTag: string;
+      metaDescription: string;
+      h1Tags: string[];
+      contentWordCount: number;
+      keywordDensity: { [keyword: string]: number };
+
+      // Technical SEO
+      mobileSpeed: number;     // Google PageSpeed score 0-100
+      desktopSpeed: number;
+      coreWebVitals: boolean;
+      httpsEnabled: boolean;
+      structuredData: string[]; // ["LocalBusiness", "Organization"]
+
+      // Local SEO
+      nabConsistency: boolean;  // Name/Address/Phone match
+      localKeywords: string[];
+      locationPages: number;
+    };
+
+    // NEW: Conversion optimization
+    conversion?: {
+      hasBooking: boolean;
+      hasContactForm: boolean;
+      hasPhoneNumber: boolean;
+      hasChatWidget: boolean;
+      ctaCount: number;
+      ctaTypes: string[];
+    };
+  };
+
+  // Existing fields
+  technologies: string[];
+  sophistication: 'basic' | 'intermediate' | 'advanced';
+  hasEcommerce: boolean;
+  hasAnalytics: boolean;
+  hasBlog: boolean;
+  mobileOptimized: boolean;
+  loadTime: number;
+
+  // Social media
+  social: {
+    facebook?: {
+      url: string;
+      followers: number;
+      postsPerWeek: number;
+      engagementRate: number;
+      lastPostDate: string;
+    };
+    instagram?: {
+      url: string;
+      followers: number;
+      postsPerWeek: number;
+      engagementRate: number;
+      lastPostDate: string;
+    };
+    linkedin?: {
+      url: string;
+      followers: number;
+    };
+  };
+
+  // Google Ads from Transparency Center (Creative Vault)
+  googleAds?: {
+    active: boolean;
+    adCount: number;
+    advertiserName?: string;
+    lastScrapedAt?: Date;
+    fromCache?: boolean;
+    ads?: Array<{
+      id: string;
+      adType: 'image' | 'video' | 'text';
+      imageUrl?: string;
+      videoUrl?: string;
+      headline?: string;
+      description?: string;
+      landingPage?: string;
+      advertiser?: string;
+      format?: string;
+      lastShownDate?: string;
+      regions?: string[];
+    }>;
+  };
+
+  // Unified creatives array (normalized from Google Ads + Facebook Ads)
+  // This is the primary field for UI display and media planning prompts
+  creatives?: CompetitorCreative[];
+
+  // Strategic analysis (from GPT-4o)
+  strategy: {
+    channelPresence: {
+      [channel: string]: {
+        active: boolean;
+        evidence: string;
+        investmentLevel: 'low' | 'medium' | 'high';
+      };
+    };
+
+    messaging: {
+      primaryThemes: string[];
+      positioning: string;
+      tone: 'professional' | 'casual' | 'playful' | 'authoritative';
+    };
+
+    sophistication: {
+      level: 'beginner' | 'intermediate' | 'advanced';
+      signals: string[];
+      investmentLevel: 'low' | 'medium' | 'high';
+    };
+
+    strengths: string[];
+    gaps: string[];
+  };
+
+  // Digital maturity score
+  digitalMaturity: number; // 0-100
+  maturityStage: 'Foundation' | 'Growth' | 'Advanced';
+
+  // Source tracking
+  source: 'prospect' | 'user_provided' | 'ai_suggested';
+  validated: boolean;
+}
+
+// ============================================================================
+// PLANNING CONTEXT DTO
+// Single structured object for media plan LLM prompts
+// Consolidates prospect intelligence, competitor data, and benchmarks
+// ============================================================================
+
+/**
+ * Prospect context for media planning
+ * Contains essential business information extracted from enrichment
+ */
+export interface PlanningProspect {
+  name: string;
+  category: string;
+  serviceAreaDescription: string;
+  websiteSummary?: string;
+  keyValueProps?: string[];
+  currentChannels?: string[];
+  weaknesses?: string[];
+  gaps?: string[];
+}
+
+/**
+ * Competitor context for media planning
+ * Summarized competitive intelligence including creative themes
+ */
+export interface PlanningCompetitor {
+  name: string;
+  category: string;
+  serviceAreaDescription?: string;
+  adSpendLevel?: 'low' | 'medium' | 'high';
+  googleAdsThemes?: string[];
+  metaAdsThemes?: string[];
+  landingPagePatterns?: string[];
+  activeChannels?: string[];
+  investmentLevel?: 'low' | 'medium' | 'high';
+}
+
+/**
+ * Performance benchmarks for a product/channel
+ * Used to inform realistic KPI expectations
+ */
+export interface PlanningBenchmark {
+  productCode: string;
+  mappedIndustry: string;
+  cpm?: number;
+  ctr?: number;
+  cvr?: number;
+  viewability?: number;
+}
+
+/**
+ * PlanningContext DTO
+ * Single structured object passed to media plan LLM
+ *
+ * This replaces scattered string concatenation with a clean JSON structure
+ * that the model can reference systematically when generating plans.
+ */
+export interface PlanningContext {
+  prospect: PlanningProspect;
+  competitors: PlanningCompetitor[];
+  performanceBenchmarks: PlanningBenchmark[];
+
+  // Market analysis
+  competitorCount: number;
+  advertisingIntensity: 'low' | 'medium' | 'high';
+  marketGaps: string[];
+
+  // Creative strategy summary (from Google/Meta ads analysis)
+  creativeStrategySummary?: string;
+}
+
+// ============================================================================
+// LOCAL MARKET SCORE TYPES
+// Simplified 0-100 score for sales conversations
+// ============================================================================
+
+/**
+ * Local Market Score - single 0-100 number for quick comparison
+ * Distills the 5-pillar Local Authority Score into a sales-friendly format
+ */
+export interface LocalMarketScore {
+  /** Single 0-100 score for quick comparison */
+  score: number;
+  /** Classification for sales conversations */
+  tier: 'Leader' | 'Competitive' | 'Emerging' | 'At Risk';
+  /** Color code for UI (red, orange, yellow, gray) */
+  tierColor: 'red' | 'orange' | 'yellow' | 'gray';
+  /** One-line summary for sales pitch */
+  summary: string;
+  /** Component breakdown for details */
+  breakdown: {
+    localPack: { score: number; maxScore: 40; label: string };
+    reviews: { score: number; maxScore: 30; label: string };
+    gbpProfile: { score: number; maxScore: 20; label: string };
+    digital: { score: number; maxScore: 10; label: string };
+  };
+  /** Calculated timestamp */
+  calculatedAt: string;
+}
+
+// ============================================================================
+// REVENUE IMPACT TYPES
+// Connect local search performance to dollars
+// ============================================================================
+
+/**
+ * Revenue Impact - quantifies the dollar value of local search position
+ */
+export interface RevenueImpact {
+  /** Monthly revenue prospect is currently capturing */
+  currentMonthlyRevenue: number;
+  /** Monthly revenue the market leader captures */
+  leaderMonthlyRevenue: number;
+  /** Monthly revenue gap (what prospect is missing) */
+  monthlyRevenueGap: number;
+  /** Annual revenue opportunity */
+  annualOpportunity: number;
+  /** Benchmarks used for calculation */
+  benchmarks: {
+    avgTicket: number;
+    conversionRate: number;
+    category: string;
+  };
+  /** Position-based CTR breakdown */
+  positionAnalysis: {
+    prospectCTR: number;
+    leaderCTR: number;
+    ctrGap: number;
+  };
+  /** Funnel metrics for transparency */
+  funnel: {
+    monthlySearchVolume: number;
+    prospectClicks: number;
+    prospectConversions: number;
+    leaderClicks: number;
+    leaderConversions: number;
+  };
+  /** Sales-ready talking points */
+  insights: {
+    headline: string;
+    comparison: string;
+    opportunity: string;
+  };
+  /** Calculation timestamp */
+  calculatedAt: string;
+}
+
+// ============================================================================
+// COMPETITIVE NARRATIVE TYPES
+// Wins vs Losses storytelling for sales conversations
+// ============================================================================
+
+/**
+ * Single comparison point in a head-to-head analysis
+ */
+export interface WinLossItem {
+  /** What's being compared */
+  metric: string;
+  /** Prospect's value/status */
+  prospectValue: string | number;
+  /** Competitor's value/status */
+  competitorValue: string | number;
+  /** Whether prospect wins this comparison */
+  prospectWins: boolean;
+  /** Impact level for prioritization */
+  impact: 'high' | 'medium' | 'low';
+  /** One-sentence insight for sales pitch */
+  insight: string;
+  /** Actionable recommendation */
+  action?: string;
+}
+
+/**
+ * Head-to-head comparison with a single competitor
+ */
+export interface HeadToHeadComparison {
+  /** Competitor being compared */
+  competitorName: string;
+  /** List of wins for prospect */
+  wins: WinLossItem[];
+  /** List of losses for prospect */
+  losses: WinLossItem[];
+  /** Overall assessment */
+  summary: {
+    winCount: number;
+    lossCount: number;
+    verdict: 'prospect_leads' | 'competitor_leads' | 'close_match';
+    headline: string;
+  };
+  /** Priority actions based on losses */
+  priorityActions: string[];
+  /** Calculated at timestamp */
+  calculatedAt: string;
+}
+
+/**
+ * Full competitive narrative across all competitors
+ */
+export interface CompetitiveNarrative {
+  /** Prospect name */
+  prospectName: string;
+  /** Head-to-head comparisons with each competitor */
+  headToHead: HeadToHeadComparison[];
+  /** Market-level summary */
+  marketSummary: {
+    /** Where prospect wins vs the market */
+    marketWins: string[];
+    /** Where prospect loses vs the market */
+    marketLosses: string[];
+    /** Overall market position */
+    position: 'leader' | 'competitive' | 'challenger' | 'at_risk';
+    /** Executive summary paragraph */
+    executiveSummary: string;
+  };
+  /** Top 3 actions to take */
+  topActions: Array<{
+    action: string;
+    impact: string;
+    competitor: string;
+  }>;
+  /** Calculated at timestamp */
+  calculatedAt: string;
+}
+
+// ============================================================================
+// INTELLIGENCE DATA — Aggregated enrichment outputs from fn-v2 pipeline
+// Written to plans.intelligenceData JSONB column
+// ============================================================================
+
+/** Prospect enrichment from business lookup + website analysis */
+export interface IntelligenceProspect extends PlanningProspect {
+  url?: string;
+  placeId?: string;
+  address?: string;
+  city?: string;
+  state?: string;
+  phone?: string;
+  rating?: number;
+  reviewCount?: number;
+  techStack?: string[];
+  digitalMaturityScore?: number;
+  pixelsDetected?: string[];
+  socialProfiles?: Record<string, string>;
+  /** Nielsen DMA code for market intelligence lookups */
+  dmaCode?: string;
+}
+
+/** Ad intelligence for a single competitor or prospect */
+export interface AdIntelligenceEntry {
+  entityName: string;
+  googleAdsCount?: number;
+  googleAdsThemes?: string[];
+  metaAdsCount?: number;
+  metaAdsThemes?: string[];
+  estimatedMonthlySpend?: number;
+  activeChannels?: string[];
+  creativeExamples?: Array<{ platform: string; headline?: string; description?: string; imageUrl?: string }>;
+}
+
+/** Pixel / tracking detection results */
+export interface PixelDetectionResult {
+  url: string;
+  pixelsFound: string[];
+  analyticsTools: string[];
+  adPlatforms: string[];
+  tagManagers: string[];
+  remarketingActive: boolean;
+}
+
+/** Domain SEO overview */
+export interface DomainOverviewResult {
+  domain: string;
+  organicKeywords?: number;
+  organicTraffic?: number;
+  domainAuthority?: number;
+  backlinks?: number;
+  topKeywords?: Array<{ keyword: string; position: number; volume: number }>;
+}
+
+/** SEO keyword/ranking analysis (distinct from domain-level overview) */
+export interface SeoAnalysisResult {
+  domain: string;
+  totalKeywordsTracked?: number;
+  keywordsInTop10?: number;
+  keywordsInTop3?: number;
+  organicTraffic?: number;
+  topKeywords?: Array<{ keyword: string; position: number; volume: number; difficulty?: number }>;
+  contentGaps?: string[];
+  technicalIssues?: string[];
+}
+
+/** Landing page audit results */
+export interface LandingPageAuditResult {
+  url: string;
+  mobileScore?: number;
+  desktopScore?: number;
+  loadTimeMs?: number;
+  hasCtaAboveFold?: boolean;
+  hasForm?: boolean;
+  hasPhoneNumber?: boolean;
+  issues?: string[];
+}
+
+/** Social media presence data */
+export interface SocialDataResult {
+  profiles: Array<{
+    platform: string;
+    url?: string;
+    followers?: number;
+    postsPerWeek?: number;
+    engagementRate?: number;
+  }>;
+}
+
+/** Strategy brief output */
+export interface StrategyBriefResult {
+  executiveSummary: string;
+  marketPosition: string;
+  recommendedChannels: Array<{
+    channel: string;
+    productCode?: string;
+    rationale: string;
+    priority: 'high' | 'medium' | 'low';
+  }>;
+  competitiveGaps: string[];
+  targetAudience?: string;
+  messagingThemes?: string[];
+}
+
+/** Market context from market intelligence tables */
+export interface MarketContextResult {
+  seasonality?: {
+    type: string;
+    score: number;
+    peakMonths: string[];
+    monthlyMultipliers: Record<string, number>;
+  };
+  benchmarks?: {
+    avgTicket: number;
+    conversionRate: number;
+    marketSaturationScore?: number;
+    yoyGrowthRate?: number;
+  };
+  marketScore?: {
+    overallScore: number;
+    timingScore: number;
+    competitionScore: number;
+    economicScore?: number;
+    recommendation: string;
+    rationale?: string;
+  };
+  competitiveLandscape?: {
+    totalBusinesses?: number;
+    advertisingPenetration?: number;
+    marketConcentration?: string;
+    opportunityScore?: number;
+  };
+  economicIndicators?: {
+    consumerConfidenceIndex?: number;
+    unemploymentRate?: number;
+    medianHouseholdIncome?: number;
+    economicHealthScore?: number;
+    economicHealthTrend?: string;
+  };
+  searchVolume?: {
+    monthlySearchVolume?: number;
+    topKeywords?: Array<{ keyword: string; volume: number }>;
+    yoyChangePct?: number;
+    trendDirection?: string;
+  };
+}
+
+/**
+ * IntelligenceData — the single structured blob written to plans.intelligenceData.
+ *
+ * fn-v2 analyze-location.ts writes this after all enrichment tools complete.
+ * All fields are optional — data fills in progressively as tools complete.
+ */
+export interface IntelligenceData {
+  /** Enriched prospect profile */
+  prospect?: IntelligenceProspect;
+  /** Enriched competitor profiles */
+  competitors?: PlanningCompetitor[];
+  /** Ad intelligence (prospect + competitors) */
+  adIntelligence?: AdIntelligenceEntry[];
+  /** Pixel / tracking detection for prospect site */
+  pixelDetection?: PixelDetectionResult;
+  /** Domain SEO overview for prospect */
+  domainOverview?: DomainOverviewResult;
+  /** Landing page audit for prospect */
+  landingPageAudit?: LandingPageAuditResult;
+  /** SEO keyword/ranking analysis */
+  seoData?: SeoAnalysisResult;
+  /** Social media presence */
+  socialData?: SocialDataResult;
+  /** Strategy brief from LLM analysis */
+  strategyBrief?: StrategyBriefResult;
+  /** Market intelligence (seasonality, benchmarks, scores) */
+  marketContext?: MarketContextResult;
+
+  /** Metadata */
+  enrichedAt?: string;
+  enrichmentVersion?: string;
+  toolsCompleted?: string[];
+  toolsFailed?: string[];
+}