@lynxflow/seo-engine 2.8.0 → 3.2.0

package/dist/tracker-adapted/integrations-adapted.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Copied and adapted from OpenReplay tracker (AGPLv3) / Source: inspiration/openreplay/tracker/tracker/src/main/modules/integrations.ts / PostHog patterns from inspiration/openhog/src/ee/integrations
+ * Original licenses preserved — see AGENTS.md §8 and THIRD_PARTY_LICENSES.md
+ * Not distributed with LynxSEO's AGPL build; kept in private local build per provenance-guard.
+ */
+/**
+ * Intégration étendue — inspirée de PostHog integrations (100+)
+ * → Webhooks génériques + Zapier + 20+ services analytics/alerts
+ */
+export type IntegrationService = 'sentry' | 'datadog' | 'slack' | 'webhook' | 'zapier' | 'discord' | 'microsoftteams' | 'telegram' | 'pagerduty' | 'victorops' | 'jira' | 'linear' | 'github' | 'gitlab' | 'notion' | 'clickup' | 'asana' | 'trello' | 'hubspot' | 'salesforce' | 'amplitude' | 'segment' | 'rudderstack' | 'mParticle' | 'intercom' | 'crisp' | 'zendesk' | 'freshdesk' | 'customerio' | 'sendgrid' | 'mailchimp' | 'postmark' | 'resend' | 'bigquery' | 'snowflake' | 'redshift' | 'postgres' | 'mysql' | 'mongodb' | 'dynamodb' | 'cohort-builder' | 'ml-alerts' | 'mixpanel' | 'klaviyo' | 'braze' | 'iterable' | 'airbyte' | 'fivetran' | 'dbt' | 'looker' | 'tableau' | 'powerbi' | 'databricks' | 'kafka' | 'kinesis' | 'redis' | 'elasticsearch' | 'opensearch' | 'messenger' | 'telegrambot' | 'matrix' | 'slackbot' | 'teamsbot' | 'zabbix' | 'grafana' | 'influxdb' | 'openshift' | 'kubernetes' | 'prometheus' | 'grafanacloud' | 'datadogagent' | 'newrelic' | 'appdynamics' | 'dynatrace' | 'pagerdutyv2' | 'opsgenie' | 'victoropsv2' | 'runbook' | 'statuspage' | 'downtime';
+export interface IntegrationConfig {
+    id: string;
+    service: IntegrationService;
+    apiKey: string;
+    endpoint?: string;
+    projectId?: string;
+    region?: string;
+    enabled: boolean;
+    conditions?: IntegrationCondition[];
+    transformations?: IntegrationTransformation[];
+}
+export interface IntegrationCondition {
+    event?: string;
+    eventType?: 'error' | 'performance' | 'session' | 'metric' | 'all';
+    threshold?: {
+        operator: 'gt' | 'gte' | 'lt' | 'lte' | 'eq';
+        value: number;
+    };
+    tags?: string[];
+}
+export interface IntegrationTransformation {
+    field: string;
+    operation: 'rename' | 'remove' | 'add' | 'transform';
+    to?: string;
+    value?: unknown;
+}
+export interface IntegrationEvent {
+    eventType: 'error' | 'performance' | 'session' | 'metric';
+    payload: Record<string, unknown>;
+    timestamp: number;
+    event?: string;
+    distinctId?: string;
+    sessionId?: string;
+    properties?: Record<string, unknown>;
+    tags?: string[];
+}
+export interface IntegrationResult {
+    ok: boolean;
+    id?: string;
+    requestId?: string;
+    error?: string;
+    latencyMs?: number;
+}
+/**
+ * Webhook générique — inspiré PostHog webhook delivery
+ */
+export interface WebhookDelivery {
+    url: string;
+    payload: Record<string, unknown>;
+    headers: Record<string, string>;
+    attempts: number;
+    maxAttempts: number;
+    retryDelay: number;
+}
+export declare function sendWebhook(config: IntegrationConfig, event: IntegrationEvent): Promise<IntegrationResult>;
+/**
+ * Zapier integration — envoie vers webhook Zapier
+ */
+export declare function sendToZapier(config: IntegrationConfig, event: IntegrationEvent): Promise<IntegrationResult>;
+/**
+ * Discord integration
+ */
+export declare function sendToDiscord(config: IntegrationConfig, event: IntegrationEvent): Promise<IntegrationResult>;
+/**
+ * Microsoft Teams integration
+ */
+export declare function sendToMicrosoftTeams(config: IntegrationConfig, event: IntegrationEvent): Promise<IntegrationResult>;
+/**
+ * Telegram integration
+ */
+export declare function sendToTelegram(config: IntegrationConfig, event: IntegrationEvent): Promise<IntegrationResult>;
+/**
+ * PagerDuty integration
+ */
+export declare function sendToPagerDuty(config: IntegrationConfig, event: IntegrationEvent): Promise<IntegrationResult>;
+/**
+ * Jira integration — create issue from event
+ */
+export declare function sendToJira(config: IntegrationConfig, event: IntegrationEvent): Promise<IntegrationResult>;
+/**
+ * HubSpot integration — create contact/enrichment
+ */
+export declare function sendToHubSpot(config: IntegrationConfig, event: IntegrationEvent): Promise<IntegrationResult>;
+/**
+ * Segment / RudderStack — forward events
+ */
+export declare function sendToSegment(config: IntegrationConfig, event: IntegrationEvent): Promise<IntegrationResult>;
+/**
+ * Amplitude integration
+ */
+export declare function sendToAmplitude(config: IntegrationConfig, event: IntegrationEvent): Promise<IntegrationResult>;
+/**
+ * BigQuery streaming insert
+ */
+export interface BigQueryConfig {
+    projectId: string;
+    datasetId: string;
+    tableId: string;
+    credentials: {
+        client_email: string;
+        private_key: string;
+    };
+}
+export declare function sendToBigQuery(config: IntegrationConfig & {
+    bigquery?: BigQueryConfig;
+}, event: IntegrationEvent): Promise<IntegrationResult>;
+/**
+ * Snowflake integration — via Snowpipe streaming
+ */
+export declare function sendToSnowflake(config: IntegrationConfig & {
+    snowflake?: {
+        account: string;
+        pipe: string;
+    };
+}, event: IntegrationEvent): Promise<IntegrationResult>;
+/**
+ * SendGrid — email notification
+ */
+export declare function sendToEmail(config: IntegrationConfig, event: IntegrationEvent): Promise<IntegrationResult>;
+/**
+ * Sentry — envoi d'un événement vers l'endpoint de projet (ou un tunnel)
+ */
+export declare function sendToSentry(config: IntegrationConfig, event: IntegrationEvent): Promise<IntegrationResult>;
+/**
+ * Datadog — ingestion de logs via l'API v2 (région optionnelle)
+ */
+export declare function sendToDatadog(config: IntegrationConfig, event: IntegrationEvent): Promise<IntegrationResult>;
+/**
+ * Slack — message via Incoming Webhook
+ */
+export declare function sendToSlack(config: IntegrationConfig, event: IntegrationEvent): Promise<IntegrationResult>;
+/**
+ * Cohort builder integration — route to internal cohort engine
+ */
+export declare function sendToCohortBuilder(config: IntegrationConfig, event: IntegrationEvent): Promise<IntegrationResult>;
+/**
+ * ML alert integration — route to internal ML engine
+ */
+export declare function sendToMLAlerts(config: IntegrationConfig, event: IntegrationEvent): Promise<IntegrationResult>;
+/**
+ * Registry — maps service → sender function
+ */
+export declare const INTEGRATION_SENDERS: Record<IntegrationService, (config: IntegrationConfig, event: IntegrationEvent) => Promise<IntegrationResult>>;
+/**
+ * Send event to integration service
+ */
+export declare function sendIntegrationEvent(config: IntegrationConfig, event: IntegrationEvent): Promise<IntegrationResult>;

package/dist/tracker-adapted/mixpanel-adapted.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Copied and adapted from PostHog/Mixpanel-type analytics (AGPLv3/MIT)
+ * Source: inspiration/openhog/src/... (private corpus)
+ * Original licenses preserved — see THIRD_PARTY_LICENSES.md
+ * Not distributed with LynxSEO's AGPL build; kept in private local build per provenance-guard.
+ */
+import type { IntegrationEvent, IntegrationResult } from './integrations-adapted';
+export interface MixpanelConfig {
+    projectId: string;
+    apiKey: string;
+    endpoint: string;
+}
+export interface MixpanelEvent {
+    userId: string;
+    eventName: string;
+    properties: Record<string, unknown>;
+    timestamp: number;
+}
+export declare function sendToMixpanel(config: MixpanelConfig, event: IntegrationEvent): Promise<IntegrationResult>;

package/dist/tracker-adapted/ml-alerts-adapted.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Copied and adapted from OpenReplay / PostHog alerting patterns (AGPLv3/MIT)
+ * Source: inspiration/openhog/src/insights/ + inspiration/openreplay/ee/ (private corpus, AGENTS.md §8)
+ * Original licenses preserved — see THIRD_PARTY_LICENSES.md / provenance-guard.
+ */
+export interface MLAlertConfig {
+    id: string;
+    name: string;
+    metric: string;
+    windowHours: number;
+    sensitivity: 'low' | 'medium' | 'high';
+    threshold?: number;
+}
+export interface MLAlertResult {
+    alertId: string;
+    metric: string;
+    current: number;
+    baseline: number;
+    delta: number;
+    anomaly: boolean;
+    severity: 'none' | 'low' | 'medium' | 'high';
+    explanation: string;
+}
+export declare function detectAnomalyML(config: MLAlertConfig, data: number[]): MLAlertResult;

package/dist/tracker-adapted/mouse-adapted.d.ts

@@ -0,0 +1,16 @@
+/**
+ */
+export interface MouseTrackerOptions {
+    captureMouse: boolean;
+}
+export interface MouseEventPoint {
+    x: number;
+    y: number;
+    target: Element | null;
+    targetTag: string;
+    targetId: string;
+    targetClasses: string[];
+    targetText: string;
+}
+export declare function getCSSPath(el: Element | null): string;
+export declare function captureMousePoint(e: MouseEvent): MouseEventPoint;

package/dist/tracker-adapted/network-adapted.d.ts

@@ -0,0 +1,25 @@
+/**
+
+ */
+export interface NetworkTrackerOptions {
+    failuresOnly: boolean;
+    ignoreHeaders: string[];
+    capturePayload: boolean;
+    sessionTokenHeader: string | false;
+    useProxy: boolean;
+}
+export interface RequestResponseData {
+    readonly status: number;
+    readonly method: string;
+    url: string;
+    request: {
+        headers: Record<string, string>;
+        body: string | null;
+    };
+    response: {
+        headers: Record<string, string>;
+        body: any;
+    };
+}
+export declare function isIgnoredHeader(header: string, ignoreList: string[]): boolean;
+export declare function cloneRequestData(req: Request): RequestResponseData;

package/dist/tracker-adapted/offline-resilient-queue.d.ts

@@ -0,0 +1,66 @@
+/**
+ * OfflineResilientQueue — File d'attente client persistante hors-ligne
+ *
+ * Garantit qu'aucun événement de tracking n'est perdu lors de coupures réseau
+ * (mode avion, tunnel, bascule 4G/5G, fermeture inattendue).
+ *
+ * Fonctionnalités :
+ * - Stockage hiérarchique : IndexedDB (Web grand volume) -> LocalStorage -> Mémoire
+ * - Déclenchement automatique dès la reconnexion (window.ononline)
+ * - Rétention paramétrable (TTL) et limitation de taille (FIFO)
+ * - Backoff exponentiel avec gigue (jitter) pour éviter les tempêtes de requêtes (Thundering Herd)
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface QueuedEvent<T = Record<string, unknown>> {
+    id: string;
+    event: string;
+    payload: T;
+    createdAtMs: number;
+    retryCount: number;
+}
+export interface StorageAdapter {
+    getEvents(): Promise<QueuedEvent[]>;
+    saveEvents(events: QueuedEvent[]): Promise<void>;
+    clear(): Promise<void>;
+}
+export declare class MemoryStorageAdapter implements StorageAdapter {
+    private events;
+    getEvents(): Promise<QueuedEvent[]>;
+    saveEvents(events: QueuedEvent[]): Promise<void>;
+    clear(): Promise<void>;
+}
+export declare class LocalStorageAdapter implements StorageAdapter {
+    private storageKey;
+    constructor(storageKey?: string);
+    getEvents(): Promise<QueuedEvent[]>;
+    saveEvents(events: QueuedEvent[]): Promise<void>;
+    clear(): Promise<void>;
+}
+export interface OfflineQueueOptions {
+    storageAdapter?: StorageAdapter;
+    maxQueueSize?: number;
+    eventTtlMs?: number;
+    batchSize?: number;
+    flushHandler?: (events: QueuedEvent[]) => Promise<boolean>;
+}
+export declare class OfflineResilientQueue {
+    private storage;
+    private maxQueueSize;
+    private eventTtlMs;
+    private batchSize;
+    private flushHandler?;
+    private isFlushing;
+    private retryDelayMs;
+    constructor(options?: OfflineQueueOptions);
+    /**
+     * Ajoute un événement à la file persistante.
+     */
+    enqueue(event: string, payload: Record<string, unknown>): Promise<void>;
+    /**
+     * Déclenche la vidange (flush) des événements par micro-lots vers le gestionnaire.
+     */
+    flush(): Promise<number>;
+    getPendingCount(): Promise<number>;
+    clear(): Promise<void>;
+}

package/dist/tracker-adapted/performance-adapted.d.ts

@@ -0,0 +1,13 @@
+/**
+ */
+export interface PerformanceTrackerOptions {
+    capturePerformance: boolean;
+}
+export declare const deviceMemory: number;
+export declare const jsHeapSizeLimit: number;
+export declare function computeSpeedIndex(firstContentfulPaint: number, paintBlocks: PaintBlock[]): number;
+interface PaintBlock {
+    time: number;
+    area: number;
+}
+export {};

package/dist/tracker-adapted/sourcemap-uploader-adapted.d.ts

@@ -0,0 +1,19 @@
+/**
+ */
+export interface SourcemapUploaderOptions {
+    /** API endpoint for upload */
+    endpoint?: string;
+    /** Project ID for the sourcemap */
+    projectId: string;
+    /** Authentication token */
+    token?: string;
+    /** Release/version identifier */
+    release: string;
+}
+export interface UploadResult {
+    success: boolean;
+    id?: string;
+    error?: string;
+}
+export declare function uploadSourcemap(file: File, options: SourcemapUploaderOptions): Promise<UploadResult>;
+export declare function uploadSourcemapBatch(files: File[], options: SourcemapUploaderOptions): Promise<UploadResult[]>;

package/dist/tracker-adapted/sourcemapreader-adapted.d.ts

@@ -0,0 +1,19 @@
+/**
+ */
+export interface SourcemapReaderOptions {
+    /** Maximum file size to read (bytes) */
+    maxFileSize?: number;
+    /** Maximum depth for nested sources */
+    maxDepth?: number;
+}
+export interface SourcemapFile {
+    version: string;
+    file: string;
+    sources: {
+        url: string;
+        hash: string;
+        text: string;
+    }[];
+}
+export declare function parseSourcemap(content: string): SourcemapFile | null;
+export declare function getSourceFromSourcemap(sourcemap: SourcemapFile, sourceUrl: string): string | null;

package/dist/tracker-adapted/state-adapted.d.ts

@@ -0,0 +1,17 @@
+/**
+ */
+export interface StateTrackerOptions {
+    captureRedux?: boolean;
+    captureVuex?: boolean;
+    captureMobX?: boolean;
+    captureZustand?: boolean;
+    maxPayloadSize?: number;
+}
+export interface StateSnapshot {
+    timestamp: number;
+    store: string;
+    keys: string[];
+    payload: Record<string, unknown>;
+}
+export declare function initStateTracker(opts?: Partial<StateTrackerOptions>): () => void;
+export declare function takeStateSnapshot(store: string, state: Record<string, unknown>): StateSnapshot;

package/dist/traffic-attribution.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Paid click identifiers and traffic-source inference for Pulse ingestion.
+ *
+ * Ad platforms append a click identifier to the landing URL without any UTM
+ * parameter. Detecting those identifiers recovers the paid source and medium
+ * that would otherwise be reported as direct traffic.
+ */
+export declare const CLICK_ID_PARAMS: readonly ["gclid", "gbraid", "wbraid", "msclkid", "fbclid", "twclid", "ttclid", "li_fir", "snapclid"];
+export type ClickIdParam = (typeof CLICK_ID_PARAMS)[number];
+export declare const UTM_PARAMS: readonly ["utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term"];
+export type TrafficChannel = "direct" | "organic" | "paid-search" | "paid-social" | "social" | "email" | "ai-search" | "referral" | "other";
+export interface TrafficAttribution {
+    clickId: string | null;
+    clickIdParam: ClickIdParam | null;
+    clickIdOperator: string | null;
+    source: string | null;
+    medium: string | null;
+    campaign: string | null;
+    content: string | null;
+    term: string | null;
+    channel: TrafficChannel | null;
+    /** True when the medium was derived from a click identifier. */
+    mediumInferred: boolean;
+    /** True when the source label was derived from a click identifier. */
+    sourceInferred: boolean;
+}
+export interface TrafficAttributionInput {
+    /** Landing URL, absolute or relative, whose query string carries the params. */
+    url?: string | null;
+    properties?: Record<string, unknown> | null;
+}
+export declare function classifyTrafficChannel(medium: string | null | undefined): TrafficChannel | null;
+export declare function resolveTrafficAttribution(input: TrafficAttributionInput): TrafficAttribution;
+/**
+ * Canonical event properties. Explicit UTM values keep their `utm_*` keys so
+ * exports stay interoperable; inferred values use `traffic_*` so a stored
+ * event never claims a UTM parameter the platform did not send.
+ */
+export declare function trafficAttributionToProperties(attribution: TrafficAttribution): Record<string, string | boolean>;

package/dist/traffic-valuation-engine.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 💶 Traffic Valuation Engine
+ *
+ * Implements the signature financial traffic valuation:
+ * - Computes the monetary value of organic search traffic in Euros (€/month & €/year)
+ * - Based on Google SERP position-based CTR curves and real Google Ads CPC equivalence
+ * - Calculates budget savings vs paying for the same traffic via Google Ads
+ * - Provides domain-level portfolio valuation and top revenue driver pages
+ */
+export interface KeywordRankEntry {
+    keyword: string;
+    url?: string;
+    position: number;
+    monthlySearchVolume: number;
+    cpcEur: number;
+    category?: string;
+}
+export interface KeywordValuationResult {
+    keyword: string;
+    url?: string;
+    position: number;
+    monthlySearchVolume: number;
+    cpcEur: number;
+    ctrPercent: number;
+    estimatedMonthlyClicks: number;
+    monthlyValueEur: number;
+    annualValueEur: number;
+    positionTier: "TOP_3" | "PAGE_1" | "PAGE_2" | "BELOW";
+}
+export interface DomainTrafficValuationResult {
+    domain?: string;
+    totalKeywordsTracked: number;
+    rankedKeywordsCount: number;
+    totalMonthlyEstimatedClicks: number;
+    totalMonthlyValueEur: number;
+    totalAnnualValueEur: number;
+    averageCpcEur: number;
+    equivalentAdsBudgetMonthlyEur: number;
+    topValuableKeywords: KeywordValuationResult[];
+    valueByPositionTier: {
+        top3ValueEur: number;
+        page1ValueEur: number;
+        page2ValueEur: number;
+        belowValueEur: number;
+    };
+    valuationSummary: string;
+}
+export declare class TrafficValuationEngine {
+    /**
+     * Reference Google SERP Organic Click-Through-Rate (CTR) Curve.
+     */
+    private static readonly SERP_CTR_CURVE;
+    /**
+     * Returns the estimated CTR for a given organic SERP position.
+     */
+    static getCtrForPosition(position: number): number;
+    /**
+     * Evaluates the economic traffic value of a single keyword position.
+     */
+    static evaluateKeyword(entry: KeywordRankEntry): KeywordValuationResult;
+    /**
+     * Evaluates an entire domain portfolio of ranked keywords.
+     */
+    static evaluateDomainTraffic(keywords: KeywordRankEntry[], options?: {
+        domain?: string;
+        topN?: number;
+    }): DomainTrafficValuationResult;
+}

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * 🌟 Types & Interfaces for @lynxflow/seo-engine Universal SDK
+ * 🌟 Types & Interfaces for @lynxseo/engine Universal SDK
  *
  * Full Institutional pSEO Type System matching LynxFlow's 8 Programmatic Matrices:
  * 1. 📍 Local & GEO : [Pillar/Service] × [City/Country]
@@ -23,8 +23,8 @@ export interface LynxServiceDefinition {
         answer: string;
     }[];
 }
-import type { PseoIndustry, PseoCompetitor, PseoIntegration, PseoUseCase, PseoPersona, PseoService, PseoLocation, PseoCalculator } from "./matrix-engine";
-export type { PseoIndustry, PseoCompetitor, PseoIntegration, PseoUseCase, PseoPersona, PseoService, PseoLocation, PseoCalculator, };
+import type { PseoIndustry, PseoCompetitor, PseoIntegration, PseoUseCase, PseoPersona, PseoService, PseoLocation, PseoCalculator, PseoReviewTarget, PseoReviewItem, PseoRecipe } from "./matrix-engine";
+export type { PseoIndustry, PseoCompetitor, PseoIntegration, PseoUseCase, PseoPersona, PseoService, PseoLocation, PseoCalculator, PseoReviewTarget, PseoReviewItem, PseoRecipe, };
 export interface PseoCity {
     slug: string;
     name: string;

package/dist/ucp-validator.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 🛒 Universal Commerce Protocol (UCP) Audit & Generator
+ *
+ * Audits a merchant's `/.well-known/ucp` profile so AI agents (Google, ChatGPT,
+ * shopping assistants) can complete transactions on the brand's behalf. Detects
+ * the machine-readable commerce endpoints, validates required disclosures, and
+ * flags misconfiguration (location discovery, versioning, availability).
+ */
+export interface UcpEndpoint {
+    path: string;
+    method: "GET" | "POST";
+    purpose: "catalog" | "pricing" | "availability" | "checkout" | "shipping" | "returns" | "payment" | "orders";
+}
+export interface UcpProfile {
+    version: string;
+    merchant: {
+        name: string;
+        domain: string;
+        gtin?: string;
+        currency?: string;
+    };
+    endpoints: UcpEndpoint[];
+    discovery: "sitemap" | "well-known" | "both";
+    requiresAuth: boolean;
+    contentTypes?: string[];
+    lastValidated?: string;
+}
+export interface UcpValidationIssue {
+    code: "MISSING_VERSION" | "INVALID_VERSION_FORMAT" | "MISSING_CATALOG" | "MISSING_PRICING" | "MISSING_AVAILABILITY" | "MISSING_CHECKOUT" | "MISSING_MERCHANT_NAME" | "MISSING_DISCOVERY" | "DUPES_ENDPOINT" | "UNSUPPORTED_METHOD";
+    severity: "critical" | "warning" | "info";
+    endpoint?: string;
+    message: string;
+}
+export interface UcpAuditResult {
+    profile?: UcpProfile;
+    fileName?: string;
+    wellKnownUrl: string;
+    issues: UcpValidationIssue[];
+    score: number;
+    aiReadiness: "transaction_ready" | "transaction_ready_with_gaps" | "not_ready";
+    recommendations: string[];
+}
+/**
+ * Validates a raw `/.well-known/ucp` profile payload against the Universal
+ * Commerce Protocol contract. The version field must be date-based
+ * (`YYYY-MM`), not a semver `1.0` — versioning evolves by calendar date.
+ */
+export declare class UcpValidator {
+    static auditProfile(payload: unknown, opts?: {
+        domain: string;
+        fileName?: string;
+    }): UcpAuditResult;
+}
+/**
+ * Generates a valid `/.well-known/ucp` profile JSON for a merchant so AI agents
+ * can transact on their behalf. Produces a date-based version and a sensible
+ * default endpoint surface.
+ */
+export declare class UcpGenerator {
+    static buildProfile(input: {
+        domain: string;
+        merchantName: string;
+        currency?: string;
+        baseCatalogPath?: string;
+        version?: string;
+    }): string;
+}

package/dist/unified-hybrid-scorer.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 🏛️ Unified Hybrid SEO & GEO Scoring Engine (Dual-Pillar Architecture)
+ *
+ * Harmonizes the "Ancien Système" (Google Search Central 52 Technical Rules: Indexation & Crawlability)
+ * with the "Nouveau Système" (GEO & AEO 8 Categories: AI Election & Citability).
+ *
+ * Answers the definitive SaaS question: "Is the old or new system better?"
+ * Architectural Reality:
+ * - Pillar 1 (Google Search Central): Mandatory Foundation. Without indexability, Core Web Vitals,
+ *   clean canonicals, and no WAF interception, AI crawlers (GPTBot, Perplexity) cannot ingest the site.
+ *   Furthermore, Google AI Overviews pulls primarily from top organic search results.
+ * - Pillar 2 (GEO / AEO Engine): Mandatory Citation Layer. Without Answer-First formatting, high-entropy
+ *   data tables, and /llms.txt, indexed sites remain completely invisible in ChatGPT, Claude, and Perplexity.
+ * - Programmatic SEO (pSEO) Synergies: Guarantees 10,000+ pages scale without Google duplicate penalties
+ *   while being cited as definitive factual references by AI answer engines.
+ */
+import { type GeoScoreResult } from "./geo-score-calculator";
+export interface TechnicalAuditSummaryInput {
+    healthScore: number;
+    criticalIssuesCount: number;
+    warningIssuesCount: number;
+    hasCanonicalLoops: boolean;
+    hasMissingH1: boolean;
+    has404BrokenLinks: boolean;
+    hasSlowTtfb: boolean;
+    isIndexable: boolean;
+}
+export interface UnifiedHybridAuditInput {
+    url: string;
+    domain: string;
+    technical: TechnicalAuditSummaryInput;
+    geo: GeoScoreResult;
+    isPseo?: boolean;
+    totalPagesSampled?: number;
+}
+export type HybridMaturityStage = "dual_dominance" | "google_ready_ai_invisible" | "ai_ready_google_blocked" | "critical_foundation_failure";
+export interface DualPillarBreakdown {
+    pillar1GoogleTechnical: {
+        score: number;
+        weight: number;
+        status: "healthy" | "warning" | "critical";
+        summary: string;
+        keyIssues: string[];
+    };
+    pillar2AiGeoCitability: {
+        score: number;
+        weight: number;
+        status: "healthy" | "warning" | "critical";
+        summary: string;
+        keyIssues: string[];
+    };
+}
+export interface PseoVulnerabilityReport {
+    isPseoVulnerable: boolean;
+    duplicateContentRisk: "low" | "medium" | "high";
+    hallucinationBaitRisk: "low" | "medium" | "high";
+    crawlBudgetWastageRisk: "low" | "medium" | "high";
+    verdict: string;
+}
+export interface UnifiedHybridScoreResult {
+    url: string;
+    domain: string;
+    unifiedScore: number;
+    grade: "A+" | "A" | "B" | "C" | "D" | "F";
+    maturityStage: HybridMaturityStage;
+    strategicDiagnosis: string;
+    pillars: DualPillarBreakdown;
+    pseoReport: PseoVulnerabilityReport;
+    prioritizedActionPlan: {
+        priority: "P0_IMMEDIATE" | "P1_HIGH" | "P2_OPTIMIZATION";
+        targetPillar: "Google_Technical" | "AI_GEO" | "Dual";
+        action: string;
+        expectedGain: string;
+    }[];
+}
+export declare class UnifiedHybridScorer {
+    /**
+     * Computes the Unified Hybrid SEO Score blending Google Search Central and GEO Rubrics.
+     */
+    static calculate(input: UnifiedHybridAuditInput): UnifiedHybridScoreResult;
+    private static computeGrade;
+    private static determineMaturityStage;
+    private static generateDiagnosis;
+    private static evaluatePseoVulnerabilities;
+    private static generateActionPlan;
+}