@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/analytics-client.d.ts

@@ -4,11 +4,19 @@
  * Tracks granular per-URL statistics, pageviews, unique visitors, conversions,
  * Core Web Vitals (LCP, INP, CLS), and AI Search Crawlers (ChatGPT, Perplexity, Claude, Googlebot).
  */
+import { ClickHouseClient, type ClickHouseConfig, type QueryOptions } from "./clickhouse/client";
+export type TrafficSource = "organic_search" | "ai_search" | "direct" | "referral" | "social";
 export interface AnalyticsEventPayload {
     path: string;
     referrer?: string;
     userAgent?: string;
     country?: string;
+    /**
+     * Stable, privacy-safe visitor identifier (see PrivacyVisitorHasher). When
+     * supplied, unique visitors are deduplicated per path; when absent, unique
+     * visitors fall back to the human view count.
+     */
+    visitorId?: string;
     durationMs?: number;
     statusCode?: number;
     isAiBot?: boolean;
@@ -63,11 +71,89 @@ export interface AnalyticsSummaryReport {
         "5xx": number;
     };
 }
+export interface AnalyticsProvider {
+    readonly name: string;
+    getSummary(domain: string, period?: "24h" | "7d" | "30d" | "all"): Promise<AnalyticsSummaryReport>;
+    recordEvent?(payload: AnalyticsEventPayload): Promise<boolean>;
+}
+/**
+ * 📈 Plausible Analytics Live Provider
+ */
+export declare class PlausibleAnalyticsProvider implements AnalyticsProvider {
+    readonly name = "Plausible";
+    private apiKey;
+    private siteId;
+    private baseUrl;
+    constructor(apiKey: string, siteId: string, baseUrl?: string);
+    getRealtimeVisitors(domain?: string): Promise<number>;
+    getBreakdown(domain: string, property: "event:page" | "visit:source" | "visit:country" | "visit:device", period?: "24h" | "7d" | "30d" | "all", limit?: number): Promise<any[]>;
+    recordEvent(payload: AnalyticsEventPayload): Promise<boolean>;
+    getSummary(domain: string, period?: "24h" | "7d" | "30d" | "all"): Promise<AnalyticsSummaryReport>;
+}
+/**
+ * 📊 Matomo Analytics Live Provider
+ */
+export declare class MatomoAnalyticsProvider implements AnalyticsProvider {
+    readonly name = "Matomo";
+    private apiToken;
+    private idSite;
+    private matomoUrl;
+    constructor(apiToken: string, idSite: string, matomoUrl?: string);
+    /** Matomo date ranges matching the requested period. */
+    private static dateRange;
+    private static matomoPercent;
+    private fetchReport;
+    getSummary(domain: string, period?: "24h" | "7d" | "30d" | "all"): Promise<AnalyticsSummaryReport>;
+}
+export declare class Ga4AnalyticsProvider implements AnalyticsProvider {
+    readonly name = "GA4";
+    private accessToken;
+    private propertyId;
+    private baseUrl;
+    constructor(accessToken: string, propertyId: string, baseUrl?: string);
+    private static rangeFor;
+    private runReport;
+    private static metric;
+    getSummary(domain: string, period?: "24h" | "7d" | "30d" | "all"): Promise<AnalyticsSummaryReport>;
+}
+/**
+ * 🏠 Local Engine In-Memory Analytics Provider
+ */
+export declare class LocalEngineAnalyticsProvider implements AnalyticsProvider {
+    readonly name = "LocalEngine";
+    static getEmptyReport(domain: string, period?: "24h" | "7d" | "30d" | "all"): AnalyticsSummaryReport;
+    getSummary(domain: string, period?: "24h" | "7d" | "30d" | "all"): Promise<AnalyticsSummaryReport>;
+}
 export declare class LynxAnalyticsClient {
     private apiKey;
     private endpoint;
+    private provider?;
+    private clickhouseClient?;
     private static localUrlRegistry;
-    constructor(apiKey: string, endpoint?: string);
+    private static pathVisitors;
+    private static botCounts;
+    private static countryCounts;
+    private static sourceCounts;
+    private static statusCounts;
+    private static durationTotalMs;
+    private static durationSamples;
+    /**
+     * Classifies a referrer into the traffic-source buckets used by the report.
+     * Unparseable or empty referrers are counted as direct traffic.
+     */
+    static classifyTrafficSource(referrer?: string): TrafficSource;
+    /** Test/reset hook for the in-memory aggregation buffers. */
+    static resetAnalyticsBuffers(): void;
+    private static recordStatus;
+    constructor(apiKeyOrOptions?: string | {
+        apiKey?: string;
+        endpoint?: string;
+        provider?: AnalyticsProvider;
+    }, endpoint?: string);
+    getClickHouseClient(cfg?: ClickHouseConfig): ClickHouseClient;
+    queryClickHouse<T = unknown>(sql: string, opts?: QueryOptions): Promise<T[]>;
+    streamClickHouse<T = unknown>(sql: string, opts?: QueryOptions): AsyncGenerator<T>;
+    queryAnalytics<T = unknown>(query: string, opts?: QueryOptions): Promise<T[]>;
     /**
      * Identifies if a User-Agent belongs to an AI search crawler or traditional search engine.
      */

package/dist/analytics-import.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 📥 Analytics Export Import Normalizer
+ *
+ * Pure parsing layer for historical analytics exports. It accepts raw CSV
+ * content, detects the export layout, normalizes headers and produces
+ * volume-faithful events ready to be inserted into Pulse storage.
+ *
+ * The module is dependency-free: it never touches the network, storage or
+ * the current clock. Running the same input twice always yields the same
+ * output, including generated visitor identifiers.
+ */
+export type AnalyticsExportFormat = "plausible" | "umami" | "simple_analytics";
+export interface NormalizedImportedEvent {
+    eventName: string;
+    urlPath: string;
+    referrer: string | null;
+    countryCode: string | null;
+    device: string;
+    browser: string | null;
+    createdAt: string;
+    visitorId: string;
+}
+export interface AnalyticsImportPreview {
+    format: AnalyticsExportFormat;
+    delimiter: string;
+    headers: string[];
+    totalRows: number;
+    validRows: number;
+    skippedRows: number;
+    warnings: string[];
+    dateRange: {
+        from: string;
+        to: string;
+    } | null;
+    events: NormalizedImportedEvent[];
+}
+export interface AnalyticsImportOptions {
+    format?: AnalyticsExportFormat;
+    projectId?: string;
+    maxRows?: number;
+    now?: Date;
+}
+export declare function parseCsv(text: string): {
+    headers: string[];
+    rows: string[][];
+    delimiter: string;
+};
+export declare function detectAnalyticsExportFormat(csv: string): AnalyticsExportFormat | null;
+export declare function parseAnalyticsExport(csv: string, options?: AnalyticsImportOptions): AnalyticsImportPreview;

package/dist/analytics-plan-generator.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 📋 Analytics Tracking Plan Generator & Type-Safe SDK Emitter
+ *
+ * Plan & Scan architecture principles:
+ * - Bridges the gap between product specs, scanned codebase routes/events, and vertical benchmarks.
+ * - Categorizes events into standard lifecycle stages:
+ *   acquisition, activation, conversion, retention, referral, health, engagement.
+ * - Automatically assigns canonical product roles (e.g. signup_completed, trial_started, core_activation).
+ * - Emits a complete, production-ready, typed TypeScript analytics client module.
+ */
+export type LifecycleStage = "acquisition" | "activation" | "conversion" | "retention" | "referral" | "health" | "engagement";
+export type ProductArchetype = "saas" | "ecommerce" | "content" | "ai_app" | "devtool" | "marketplace" | "consumer" | "general";
+export interface PlanProperty {
+    name: string;
+    type: "string" | "number" | "boolean" | "string[]" | "object";
+    required?: boolean;
+    description: string;
+}
+export interface PlanEvent {
+    name: string;
+    stage: LifecycleStage;
+    description: string;
+    role?: string;
+    properties: PlanProperty[];
+    emittedInCode?: boolean;
+    sources?: string[];
+    origin: "code" | "suggested" | "custom";
+}
+export interface TrackingPlan {
+    version: string;
+    productArchetype: ProductArchetype;
+    generatedAt: string;
+    events: PlanEvent[];
+    roles: Record<string, string>;
+    normalizedRoutes: string[];
+}
+export interface DiscoveredCallSite {
+    name: string;
+    file: string;
+    line: number;
+    via: string;
+}
+export interface DiscoveredRoute {
+    path: string;
+    file?: string;
+    role?: string;
+}
+export declare function classifyLifecycleStage(eventName: string): LifecycleStage;
+export declare const ARCHETYPE_CORE_EVENTS: Record<ProductArchetype, PlanEvent[]>;
+export interface GenerateTrackingPlanOptions {
+    archetype?: ProductArchetype;
+    discoveredCalls?: DiscoveredCallSite[];
+    discoveredRoutes?: DiscoveredRoute[];
+    existingPlan?: TrackingPlan;
+}
+export declare function generateTrackingPlan(options: GenerateTrackingPlanOptions): TrackingPlan;
+export declare function generateAnalyticsSdkCode(plan: TrackingPlan): string;

package/dist/analytics-query-agent.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 📊 Analytics Query Agent (Metabot-style, deterministic)
+ *
+ * Answers a natural-language question from an AnalyticsSummaryReport without
+ * calling an LLM: intent is detected by keywords, and every number comes from
+ * the report. An empty bucket produces an explicit "no data" answer instead of
+ * a plausible-sounding invention.
+ */
+import type { AnalyticsSummaryReport } from "./analytics-client";
+export type AnalyticsIntent = "overview" | "top_pages" | "traffic_sources" | "ai_bots" | "countries" | "conversions";
+export interface AnalyticsAnswer {
+    intent: AnalyticsIntent;
+    question: string;
+    answer: string;
+    /** Structured payload for UIs / MCP tools; always derived from the report. */
+    data: Record<string, unknown>;
+    /** False when the report has no data for the detected intent. */
+    hasData: boolean;
+}
+export declare function detectAnalyticsIntent(question: string): AnalyticsIntent;
+export declare function answerAnalyticsQuestion(question: string, report: AnalyticsSummaryReport): AnalyticsAnswer;

package/dist/analytics-tagging-plan.d.ts

@@ -0,0 +1,130 @@
+/**
+ * 📊 Unified Analytics Tagging Plan Generator (GA4/PostHog)
+ * Generates comprehensive tracking plans for web analytics including events,
+ * parameters, user properties, consent mode, and server-side tracking.
+ */
+export type AnalyticsPlatform = "ga4" | "posthog" | "plausible" | "both" | "all";
+export type EventType = "page_view" | "scroll" | "click" | "form_submit" | "video_engagement" | "file_download" | "external_link" | "search" | "login" | "signup" | "purchase" | "refund" | "custom";
+export interface AnalyticsEvent {
+    name: string;
+    platform: AnalyticsPlatform[];
+    description: string;
+    parameters: AnalyticsParameter[];
+    userProperties?: AnalyticsUserProperty[];
+    triggers: string[];
+}
+export interface AnalyticsParameter {
+    name: string;
+    type: "string" | "number" | "boolean" | "array";
+    description: string;
+    required?: boolean;
+    enum?: string[];
+}
+export interface AnalyticsUserProperty {
+    name: string;
+    type: "string" | "number" | "boolean";
+    description: string;
+}
+export interface ConsentConfig {
+    gdpr: boolean;
+    ccpa: boolean;
+    analytics: boolean;
+    marketing: boolean;
+    functional: boolean;
+    defaultAnalytics: boolean;
+    defaultMarketing: boolean;
+    defaultFunctional: boolean;
+}
+export interface ServerSideConfig {
+    endpoint: string;
+    batchSize: number;
+    retryAttempts: number;
+    apiKey: string;
+    serverSideEvents: EventType[];
+}
+export interface TaggingPlan {
+    platform: AnalyticsPlatform;
+    version: string;
+    generatedAt: string;
+    events: AnalyticsEvent[];
+    userProperties: AnalyticsUserProperty[];
+    consent: ConsentConfig;
+    serverSide?: ServerSideConfig;
+    customDefinitions?: {
+        dimensions: Array<{
+            name: string;
+            scope: "event" | "user";
+            description: string;
+        }>;
+        metrics: Array<{
+            name: string;
+            scope: "event" | "user";
+            description: string;
+            formattingType: string;
+        }>;
+    };
+    featureFlags?: Array<{
+        key: string;
+        description: string;
+    }>;
+}
+export declare class AnalyticsTaggingPlanEngine {
+    /**
+     * Generate a comprehensive tagging plan based on website type and requirements
+     */
+    static generatePlan(websiteType: "ecommerce" | "saas" | "content" | "leadgen" | "portfolio", platform?: AnalyticsPlatform, options?: {
+        includeConsent?: boolean;
+        includeServerSide?: boolean;
+        customEvents?: AnalyticsEvent[];
+    }): TaggingPlan;
+    /**
+     * Get base events for different website types
+     */
+    private static getBaseEvents;
+    private static getEcommerceEvents;
+    private static getSaasEvents;
+    private static getContentEvents;
+    private static getLeadgenEvents;
+    private static getPortfolioEvents;
+    /**
+     * Get common user properties
+     */
+    private static getUserProperties;
+    /**
+     * Get default consent configuration
+     */
+    private static getDefaultConsentConfig;
+    private static getEmptyConsentConfig;
+    /**
+     * Get server-side tracking configuration
+     */
+    private static getServerSideConfig;
+    /**
+     * Get custom definitions for GA4
+     */
+    private static getCustomDefinitions;
+    /**
+     * Get feature flags for PostHog
+     */
+    private static getFeatureFlags;
+    /**
+     * Validate existing tracking implementation against plan
+     */
+    static validateExisting(plan: TaggingPlan, currentEvents: string[]): {
+        missingEvents: string[];
+        extraEvents: string[];
+        coverage: number;
+    };
+    /**
+     * Generate GTM-compatible configuration snippet
+     */
+    static generateGtmConfig(plan: TaggingPlan): string;
+    /**
+     * Generate PostHog initialization snippet
+     */
+    static generatePosthogSnippet(plan: TaggingPlan): string;
+    /**
+     * Generate Plausible Analytics privacy-first snippet
+     */
+    static generatePlausibleSnippet(domain: string, apiEndpoint?: string): string;
+}

package/dist/anti-adblock/stealth-proxy-generator.d.ts

@@ -0,0 +1,49 @@
+/**
+ * StealthProxyGenerator — Générateur de proxy inverse « First-Party Stealth » Anti-Adblock
+ *
+ * Déjoue à 100% les filtres de blocage uBlock Origin, Brave Shields, Pi-hole et AdGuard :
+ * 1. Obfuscation polymorphique des chemins d'URL (ex: /static/app-[hash].js au lieu de /lynx-analytics.js).
+ * 2. Génération de templates prêts à déployer :
+ *    - Cloudflare Worker (Edge Serverless)
+ *    - Caddyfile (Reverse proxy HTTPS automatique)
+ *    - Nginx configuration snippet
+ * 3. Réinjection fidèle des en-têtes d'origine (IP réelle, User-Agent, Referer).
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface StealthProxyOptions {
+    upstreamHost: string;
+    scriptSalt?: string;
+    customScriptPrefix?: string;
+    customIngestPrefix?: string;
+}
+export declare class StealthProxyGenerator {
+    private upstreamHost;
+    private scriptSalt;
+    private customScriptPrefix;
+    private customIngestPrefix;
+    constructor(options: StealthProxyOptions);
+    /**
+     * Calcule le hash polymorphique déterministe pour une date ou un sel donné.
+     */
+    getPolymorphicHash(seed?: string): string;
+    /**
+     * Retourne les chemins d'URL masqués pour le client.
+     */
+    getStealthRoutes(seed?: string): {
+        scriptPath: string;
+        ingestPath: string;
+    };
+    /**
+     * Génère le code complet d'un Cloudflare Worker prêt à déployer.
+     */
+    generateCloudflareWorkerScript(seed?: string): string;
+    /**
+     * Génère un bloc de configuration pour Caddy.
+     */
+    generateCaddyConfig(domain: string, seed?: string): string;
+    /**
+     * Génère un bloc de configuration pour Nginx.
+     */
+    generateNginxConfig(seed?: string): string;
+}

package/dist/api-playground-catalog.d.ts

@@ -0,0 +1,34 @@
+/**
+ * API Playground Catalog — Catalogue et générateur d'appels interactifs pour les API LynxSEO & Pulse
+ * Conçu pour tester et explorer les API directement depuis le dashboard.
+ */
+export interface ApiParameter {
+    name: string;
+    type: "string" | "number" | "boolean";
+    required: boolean;
+    defaultValue?: string | number | boolean;
+    description: string;
+}
+export type ApiPlaygroundJsonValue = string | number | boolean | null | ApiPlaygroundJsonValue[] | {
+    [key: string]: ApiPlaygroundJsonValue;
+};
+export interface ApiEndpointDefinition {
+    id: string;
+    group: "analytics" | "seo" | "ai_coworkers" | "admin";
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    path: string;
+    title: string;
+    description: string;
+    parameters: ApiParameter[];
+    defaultRequestBody?: Record<string, ApiPlaygroundJsonValue>;
+}
+export declare const API_PLAYGROUND_CATALOG: ApiEndpointDefinition[];
+export interface CurlSnippetOptions {
+    method: string;
+    path: string;
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    queryParams?: Record<string, string>;
+    body?: unknown;
+}
+export declare function generateCurlSnippet(options: CurlSnippetOptions): string;

package/dist/article-autopilot-orchestrator.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 🚀 Article Autopilot Orchestrator
+ *
+ * End-to-end automated editorial drafting pipeline in 7 sequential stages:
+ *  Stage 1: Intent & Keyword Brief Analysis
+ *  Stage 2: Outline & Headings Builder (H1, H2, H3)
+ *  Stage 3: Sequential Section-by-Section Drafter (rolling context prevention)
+ *  Stage 4: Contextual Internal Linker Injection
+ *  Stage 5: Anti-Watermark & Cliché Scrubbing (HumanityAiScrubber)
+ *  Stage 6: Schema.org JSON-LD Generation (Article + FAQPage)
+ *  Stage 7: Multi-Channel Repurposing (ContentRepurposer 5 formats)
+ */
+import { type HumanityScrubReport } from "./humanity-ai-scrubber";
+import { type RepurposedSuite } from "./content-repurposer";
+export interface AutopilotArticleInput {
+    targetKeyword: string;
+    secondaryKeywords?: string[];
+    targetAudience?: string;
+    searchIntent?: "informational" | "commercial" | "transactional" | "navigational";
+    brandOrAuthorName?: string;
+    canonicalUrl?: string;
+    internalLinksCatalog?: Array<{
+        anchor: string;
+        url: string;
+        relevanceTopic?: string;
+    }>;
+    toneOfVoice?: string;
+    targetWordCount?: number;
+    openRouterApiKey?: string;
+    model?: string;
+    customLlmDrafter?: (prompt: string) => Promise<string>;
+}
+export interface SectionOutline {
+    id: string;
+    h2Title: string;
+    h3Subsections: string[];
+    targetKeywords: string[];
+    purpose: string;
+}
+export interface DraftedSection {
+    outline: SectionOutline;
+    markdownContent: string;
+    wordCount: number;
+}
+export interface AutopilotPipelineResult {
+    seoTitle: string;
+    metaDescription: string;
+    focusKeyphrase: string;
+    canonicalUrl: string;
+    h1: string;
+    fullMarkdown: string;
+    gutenbergHtml: string;
+    totalWordCount: number;
+    sections: DraftedSection[];
+    schemaJsonLd: Record<string, any>;
+    humanityReport: HumanityScrubReport;
+    socialRepurposing: RepurposedSuite;
+    internalLinksInjectedCount: number;
+}
+export declare class ArticleAutopilotOrchestrator {
+    /**
+     * Executes the full 7-stage sequential drafting pipeline asynchronously.
+     * Calls OpenRouter / LLM for live section drafting with rolling context
+     * when an API key or custom drafter is provided.
+     */
+    static executePipelineAsync(input: AutopilotArticleInput): Promise<AutopilotPipelineResult>;
+    /**
+     * Executes the full 7-stage sequential drafting pipeline synchronously (deterministic blueprint).
+     */
+    static executePipeline(input: AutopilotArticleInput): AutopilotPipelineResult;
+    /**
+     * Generates a coherent 4-to-6 section outline tailored to search intent.
+     */
+    private static buildOutline;
+    /**
+     * Drafts a single section while being aware of the accumulated context.
+     */
+    private static draftSection;
+    /**
+     * Builds valid Schema.org @graph with Article, BreadcrumbList, and FAQPage.
+     */
+    private static buildSchemaGraph;
+    /**
+     * Converts markdown to standard WordPress Gutenberg blocks.
+     */
+    private static markdownToGutenberg;
+    private static slugify;
+    private static capitalizeWords;
+    private static escapeRegex;
+}

package/dist/attentive-sync-engine.d.ts

@@ -0,0 +1,25 @@
+export interface AttentiveSubscriptionInput {
+    phone: string;
+    email?: string;
+    signUpSourceId: string;
+    externalIdentifier?: string;
+    countryCode?: string;
+}
+export interface AttentiveSubscriptionPayload {
+    user: {
+        phone: string;
+        email?: string;
+        externalIdentifier?: string;
+    };
+    signUpSourceId: string;
+}
+export declare class AttentiveSyncEngine {
+    /**
+     * Normalise le numéro pour Attentive (format E.164 obligatoire).
+     */
+    static normalizePhoneNumber(phone: string, defaultCountryPrefix?: string): string | undefined;
+    /**
+     * Construit le payload officiel de souscription SMS pour l'API Attentive v1 (POST /v1/subscriptions).
+     */
+    static buildSubscriptionPayload(input: AttentiveSubscriptionInput): AttentiveSubscriptionPayload | null;
+}

package/dist/attribution-model.d.ts

@@ -0,0 +1,52 @@
+/**
+ * LynxSEO Pulse — Multi-touch attribution.
+ *
+ * Pure crediting layer that turns visitor journeys into channel-level
+ * conversion and revenue reports. It performs no I/O and has no runtime
+ * dependencies, so a given set of journeys always produces the same report.
+ *
+ * Journeys are normalized before crediting:
+ * - only converted journeys count;
+ * - touchpoints with an empty channel or an invalid timestamp are dropped;
+ * - valid touchpoints are ordered chronologically;
+ * - consecutive touches on the same channel are collapsed so a page reload
+ *   cannot split or inflate credit.
+ */
+export type AttributionModel = "first_touch" | "last_touch" | "linear" | "time_decay" | "position_based";
+export interface AttributionTouchpoint {
+    channel: string;
+    timestamp: string;
+    campaign?: string | null;
+}
+export interface AttributionJourney {
+    visitorId: string;
+    touchpoints: AttributionTouchpoint[];
+    converted: boolean;
+    conversionValue?: number;
+}
+export interface AttributionChannelResult {
+    channel: string;
+    touchpoints: number;
+    creditedConversions: number;
+    revenue: number;
+    sharePct: number;
+}
+export interface AttributionReport {
+    model: AttributionModel;
+    totalConversions: number;
+    totalRevenue: number;
+    channels: AttributionChannelResult[];
+    unattributedConversions: number;
+}
+export interface AttributionOptions {
+    timeDecayHalfLifeDays?: number;
+}
+/**
+ * Attributes converted journeys to channels using the requested model.
+ */
+export declare function attributeJourneys(journeys: AttributionJourney[], model: AttributionModel, options?: AttributionOptions): AttributionReport;
+/**
+ * Computes every attribution model over the same journey set so reports can be
+ * compared side by side.
+ */
+export declare function compareAttributionModels(journeys: AttributionJourney[], options?: AttributionOptions): Record<AttributionModel, AttributionReport>;