@foundrynorth/compass-schema 1.0.0 → 1.0.1

package/dist/analyzeTypes.d.ts

@@ -0,0 +1,1059 @@
+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;
+    };
+    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;
+    selectedLocationIds?: string[];
+    locationsByMode?: {
+        dma?: number;
+        overlap?: number;
+        all: number;
+    };
+    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;
+    dmaCode?: string;
+    dmaName?: string;
+    inProspectDma?: boolean;
+    overlapsProspect?: boolean;
+}
+/**
+ * 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;
+    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;
+}
+/**
+ * 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 declare const KnownCompetitorSchema: z.ZodObject<{
+    name: z.ZodString;
+    placeId: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodString>;
+    address: z.ZodOptional<z.ZodString>;
+    website: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    placeId?: string | undefined;
+    notes?: string | undefined;
+    address?: string | undefined;
+    website?: string | undefined;
+}, {
+    name: string;
+    placeId?: string | undefined;
+    notes?: string | undefined;
+    address?: string | undefined;
+    website?: string | undefined;
+}>;
+export declare const AnalyzePlanInputSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    placeId: z.ZodOptional<z.ZodString>;
+    brand: z.ZodOptional<z.ZodString>;
+    businessName: z.ZodOptional<z.ZodString>;
+    city: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodString>;
+    geo: z.ZodOptional<z.ZodString>;
+    targetGeo: z.ZodOptional<z.ZodString>;
+    lat: z.ZodOptional<z.ZodNumber>;
+    lng: z.ZodOptional<z.ZodNumber>;
+    chainDetected: z.ZodOptional<z.ZodBoolean>;
+    selectedAreas: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    businessDescription: z.ZodEffects<z.ZodDefault<z.ZodOptional<z.ZodString>>, string, string | undefined>;
+    url: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
+    knownCompetitors: z.ZodEffects<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        placeId: z.ZodOptional<z.ZodString>;
+        notes: z.ZodOptional<z.ZodString>;
+        address: z.ZodOptional<z.ZodString>;
+        website: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        placeId?: string | undefined;
+        notes?: string | undefined;
+        address?: string | undefined;
+        website?: string | undefined;
+    }, {
+        name: string;
+        placeId?: string | undefined;
+        notes?: string | undefined;
+        address?: string | undefined;
+        website?: string | undefined;
+    }>, "many">, {
+        name: string;
+        placeId?: string | undefined;
+        notes?: string | undefined;
+        address?: string | undefined;
+        website?: string | undefined;
+    }[], {
+        name: string;
+        placeId?: string | undefined;
+        notes?: string | undefined;
+        address?: string | undefined;
+        website?: string | undefined;
+    }[]>;
+    discoverAdditional: z.ZodDefault<z.ZodBoolean>;
+    maxAdditionalCompetitors: z.ZodDefault<z.ZodNumber>;
+    marketId: z.ZodOptional<z.ZodString>;
+    marketCenter: z.ZodOptional<z.ZodObject<{
+        lat: z.ZodNumber;
+        lng: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        lat: number;
+        lng: number;
+    }, {
+        lat: number;
+        lng: number;
+    }>>;
+    serviceAreaConfig: z.ZodOptional<z.ZodObject<{
+        type: z.ZodDefault<z.ZodEnum<["physical", "hq_radius", "metro", "custom_zips"]>>;
+        radiusMiles: z.ZodOptional<z.ZodNumber>;
+        zipCodes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        type: "physical" | "hq_radius" | "metro" | "custom_zips";
+        radiusMiles?: number | undefined;
+        zipCodes?: string[] | undefined;
+    }, {
+        type?: "physical" | "hq_radius" | "metro" | "custom_zips" | undefined;
+        radiusMiles?: number | undefined;
+        zipCodes?: string[] | undefined;
+    }>>;
+    prospectPlaceId: z.ZodOptional<z.ZodString>;
+    prospectBrandName: z.ZodOptional<z.ZodString>;
+    prospectChainMode: z.ZodOptional<z.ZodEnum<["single", "dma", "overlap", "all"]>>;
+    prospectLocationCount: z.ZodOptional<z.ZodNumber>;
+    prospectLocations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        placeId: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        address: z.ZodOptional<z.ZodString>;
+        city: z.ZodOptional<z.ZodString>;
+        state: z.ZodOptional<z.ZodString>;
+        lat: z.ZodOptional<z.ZodNumber>;
+        lng: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        placeId: string;
+        name?: string | undefined;
+        address?: string | undefined;
+        city?: string | undefined;
+        state?: string | undefined;
+        lat?: number | undefined;
+        lng?: number | undefined;
+    }, {
+        placeId: string;
+        name?: string | undefined;
+        address?: string | undefined;
+        city?: string | undefined;
+        state?: string | undefined;
+        lat?: number | undefined;
+        lng?: number | undefined;
+    }>, "many">>;
+    budget: z.ZodOptional<z.ZodObject<{
+        min: z.ZodNumber;
+        max: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        min: number;
+        max: number;
+    }, {
+        min: number;
+        max: number;
+    }>>;
+    planTotalBudget: z.ZodOptional<z.ZodNumber>;
+    planDurationMonths: z.ZodOptional<z.ZodNumber>;
+    goals: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    category: z.ZodOptional<z.ZodString>;
+    analysisDepth: z.ZodDefault<z.ZodOptional<z.ZodEnum<["standard", "deep"]>>>;
+    hubspotCompanyId: z.ZodOptional<z.ZodString>;
+    hubspotUrl: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    businessDescription: string;
+    knownCompetitors: {
+        name: string;
+        placeId?: string | undefined;
+        notes?: string | undefined;
+        address?: string | undefined;
+        website?: string | undefined;
+    }[];
+    discoverAdditional: boolean;
+    maxAdditionalCompetitors: number;
+    analysisDepth: "standard" | "deep";
+    name?: string | undefined;
+    placeId?: string | undefined;
+    brand?: string | undefined;
+    businessName?: string | undefined;
+    city?: string | undefined;
+    state?: string | undefined;
+    geo?: string | undefined;
+    targetGeo?: string | undefined;
+    lat?: number | undefined;
+    lng?: number | undefined;
+    chainDetected?: boolean | undefined;
+    selectedAreas?: string[] | undefined;
+    url?: string | undefined;
+    marketId?: string | undefined;
+    marketCenter?: {
+        lat: number;
+        lng: number;
+    } | undefined;
+    serviceAreaConfig?: {
+        type: "physical" | "hq_radius" | "metro" | "custom_zips";
+        radiusMiles?: number | undefined;
+        zipCodes?: string[] | undefined;
+    } | undefined;
+    prospectPlaceId?: string | undefined;
+    prospectBrandName?: string | undefined;
+    prospectChainMode?: "single" | "dma" | "overlap" | "all" | undefined;
+    prospectLocationCount?: number | undefined;
+    prospectLocations?: {
+        placeId: string;
+        name?: string | undefined;
+        address?: string | undefined;
+        city?: string | undefined;
+        state?: string | undefined;
+        lat?: number | undefined;
+        lng?: number | undefined;
+    }[] | undefined;
+    budget?: {
+        min: number;
+        max: number;
+    } | undefined;
+    planTotalBudget?: number | undefined;
+    planDurationMonths?: number | undefined;
+    goals?: string[] | undefined;
+    category?: string | undefined;
+    hubspotCompanyId?: string | undefined;
+    hubspotUrl?: string | undefined;
+}, {
+    knownCompetitors: {
+        name: string;
+        placeId?: string | undefined;
+        notes?: string | undefined;
+        address?: string | undefined;
+        website?: string | undefined;
+    }[];
+    name?: string | undefined;
+    placeId?: string | undefined;
+    brand?: string | undefined;
+    businessName?: string | undefined;
+    city?: string | undefined;
+    state?: string | undefined;
+    geo?: string | undefined;
+    targetGeo?: string | undefined;
+    lat?: number | undefined;
+    lng?: number | undefined;
+    chainDetected?: boolean | undefined;
+    selectedAreas?: string[] | undefined;
+    businessDescription?: string | undefined;
+    url?: string | undefined;
+    discoverAdditional?: boolean | undefined;
+    maxAdditionalCompetitors?: number | undefined;
+    marketId?: string | undefined;
+    marketCenter?: {
+        lat: number;
+        lng: number;
+    } | undefined;
+    serviceAreaConfig?: {
+        type?: "physical" | "hq_radius" | "metro" | "custom_zips" | undefined;
+        radiusMiles?: number | undefined;
+        zipCodes?: string[] | undefined;
+    } | undefined;
+    prospectPlaceId?: string | undefined;
+    prospectBrandName?: string | undefined;
+    prospectChainMode?: "single" | "dma" | "overlap" | "all" | undefined;
+    prospectLocationCount?: number | undefined;
+    prospectLocations?: {
+        placeId: string;
+        name?: string | undefined;
+        address?: string | undefined;
+        city?: string | undefined;
+        state?: string | undefined;
+        lat?: number | undefined;
+        lng?: number | undefined;
+    }[] | undefined;
+    budget?: {
+        min: number;
+        max: number;
+    } | undefined;
+    planTotalBudget?: number | undefined;
+    planDurationMonths?: number | undefined;
+    goals?: string[] | undefined;
+    category?: string | undefined;
+    analysisDepth?: "standard" | "deep" | undefined;
+    hubspotCompanyId?: string | undefined;
+    hubspotUrl?: string | undefined;
+}>;
+export type KnownCompetitor = z.infer<typeof KnownCompetitorSchema>;
+export type AnalyzePlanInput = z.infer<typeof AnalyzePlanInputSchema>;
+/**
+ * Validation state after processing
+ */
+export interface ValidatedCompetitor extends KnownCompetitor {
+    validated: boolean | 'needs_clarification';
+    status: 'confirmed' | 'not_found' | 'multiple_matches';
+    confidence: number;
+    placeId?: string;
+    verifiedName?: string;
+    verifiedAddress?: string;
+    geometry?: {
+        lat: number;
+        lng: number;
+    };
+    category?: string;
+    rating?: number;
+    reviewCount?: number;
+    options?: Array<{
+        placeId: string;
+        name: string;
+        address: string;
+        distance?: number;
+    }>;
+    suggestion?: string;
+    source: 'user_provided' | 'ai_suggested';
+    originalName?: string;
+    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;
+}
+/**
+ * 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 {
+    placeId: string;
+    name: string;
+    address: string;
+    city: string;
+    state: string;
+    lat: number;
+    lng: number;
+    category: string;
+    businessType?: BusinessType;
+    serviceArea?: ServiceArea | null;
+    serviceAreaOverlap?: ServiceAreaOverlap | null;
+    rating: number;
+    reviewCount: number;
+    metaAds: {
+        present: boolean;
+        activeCount: number;
+        totalSeen: number;
+        oldestAdDate: string | null;
+        impressionsRange: string | null;
+        creative?: {
+            themes: string[];
+            messaging: string[];
+            visualStyle: string;
+            offers: string[];
+            ctaTypes: string[];
+            ads?: Array<{
+                adId?: string;
+                adImage?: string;
+                adCopy?: string;
+                headline?: string;
+                callToAction?: string;
+                publisherPlatforms?: string[];
+                startDate?: string;
+                status?: string;
+            }>;
+        };
+        audience?: {
+            platforms: string[];
+            ageRanges: string[];
+            genders: string[];
+            interests: string[];
+        };
+        estimatedSpend?: {
+            monthly: number;
+            confidence: 'low' | 'medium' | 'high';
+            basis: string;
+        };
+    };
+    website: {
+        url: string | null;
+        accessible: boolean;
+        seo?: {
+            titleTag: string;
+            metaDescription: string;
+            h1Tags: string[];
+            contentWordCount: number;
+            keywordDensity: {
+                [keyword: string]: number;
+            };
+            mobileSpeed: number;
+            desktopSpeed: number;
+            coreWebVitals: boolean;
+            httpsEnabled: boolean;
+            structuredData: string[];
+            nabConsistency: boolean;
+            localKeywords: string[];
+            locationPages: number;
+        };
+        conversion?: {
+            hasBooking: boolean;
+            hasContactForm: boolean;
+            hasPhoneNumber: boolean;
+            hasChatWidget: boolean;
+            ctaCount: number;
+            ctaTypes: string[];
+        };
+    };
+    technologies: string[];
+    sophistication: 'basic' | 'intermediate' | 'advanced';
+    hasEcommerce: boolean;
+    hasAnalytics: boolean;
+    hasBlog: boolean;
+    mobileOptimized: boolean;
+    loadTime: number;
+    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;
+        };
+    };
+    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[];
+        }>;
+    };
+    creatives?: CompetitorCreative[];
+    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[];
+    };
+    digitalMaturity: number;
+    maturityStage: 'Foundation' | 'Growth' | 'Advanced';
+    source: 'prospect' | 'user_provided' | 'ai_suggested';
+    validated: boolean;
+}
+/**
+ * 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[];
+    competitorCount: number;
+    advertisingIntensity: 'low' | 'medium' | 'high';
+    marketGaps: string[];
+    creativeStrategySummary?: string;
+}
+/**
+ * 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 - 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;
+}
+/**
+ * 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;
+}
+/** 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[];
+}
+//# sourceMappingURL=analyzeTypes.d.ts.map