@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/webhooks-dispatcher.d.ts

@@ -0,0 +1,178 @@
+/**
+ * 🪝 Webhooks Dispatcher + Data Out
+ *
+ * Sortie de données vers l'extérieur : CRM, Zapier, n8n, data lake S3.
+ * Complète `webhook-service.ts` (registre simple) avec ce qui manque pour un
+ * vrai dispatching :
+ *
+ * - **signature HMAC-SHA256 réelle** (`t=<unix>,v1=<hex>` sur
+ *   `${timestamp}.${body}`, comme Stripe), vérifiable par le récepteur ;
+ * - **rotation de secret** : plusieurs secrets acceptés, le premier signe ;
+ * - **filtres par événement** (chemin pointé dans `data`, égalité ou `in`) ;
+ * - **classement des erreurs** : 4xx métier = dead letter immédiat, 429/408/5xx
+ *   et erreurs réseau = retry avec backoff exponentiel plafonné ;
+ * - **idempotence** : un même `eventId` n'est pas redélivré à un endpoint qui
+ *   l'a déjà reçu ;
+ * - **dead letters rejouables** ;
+ * - **descripteur d'export S3** (clé, checksum SHA-256, expiration) pour
+ *   brancher un signataire SigV4 côté Worker.
+ *
+ * Le transport et l'horloge sont injectés : les tests ne font aucun I/O et ne
+ * dépendent d'aucune horloge murale.
+ */
+export interface WebhookFilter {
+    /** Chemin pointé dans `event.data`, ex. `customer.plan`. */
+    path: string;
+    equals?: unknown;
+    in?: readonly unknown[];
+    exists?: boolean;
+}
+export interface WebhookEndpoint {
+    id: string;
+    url: string;
+    events: readonly string[];
+    /** Le premier secret signe, les suivants servent à la rotation. */
+    secrets: readonly string[];
+    filters?: readonly WebhookFilter[];
+    active?: boolean;
+    maxAttempts?: number;
+    description?: string;
+}
+export interface WebhookEventEnvelope {
+    id: string;
+    type: string;
+    occurredAt: string;
+    projectId?: string;
+    data: Record<string, unknown>;
+}
+export type DeliveryStatus = "delivered" | "retryable" | "dead_letter" | "skipped";
+export interface DeliveryAttempt {
+    attempt: number;
+    at: string;
+    status?: number;
+    error?: string;
+}
+export interface DeliveryReport {
+    deliveryId: string;
+    endpointId: string;
+    eventId: string;
+    eventType: string;
+    status: DeliveryStatus;
+    attempts: DeliveryAttempt[];
+    statusCode?: number;
+    /** Raison d'un `skipped` (duplicate, endpoint inactif, filtre non satisfait). */
+    reason?: string;
+    nextRetryAt?: string;
+}
+export interface WebhookTransportRequest {
+    url: string;
+    method: "POST";
+    headers: Record<string, string>;
+    body: string;
+}
+export type WebhookTransport = (request: WebhookTransportRequest) => Promise<{
+    status: number;
+}>;
+export interface WebhookDispatcherOptions {
+    transport: WebhookTransport;
+    now?: () => Date;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    maxAttempts?: number;
+    /** Tolérance de l'horloge à la vérification de signature, en secondes. */
+    toleranceSeconds?: number;
+}
+/** Sérialisation stable : la signature ne doit pas dépendre de l'ordre des clés. */
+export declare function stableStringify(value: unknown): string;
+export declare function computeWebhookSignature(options: {
+    secret: string;
+    body: string;
+    timestamp: number;
+}): string;
+export declare function verifyWebhookSignature(options: {
+    header: string | null;
+    body: string;
+    secrets: readonly string[];
+    nowSeconds?: number;
+    toleranceSeconds?: number;
+}): {
+    valid: boolean;
+    reason?: string;
+};
+export declare function matchesFilters(filters: readonly WebhookFilter[] | undefined, data: Record<string, unknown>): boolean;
+/**
+ * 429, 408, 5xx et erreurs réseau sont réessayés ; les autres 4xx sont
+ * définitifs (payload refusé, endpoint supprimé, signature rejetée).
+ */
+export declare function classifyDeliveryStatus(status: number | null): "delivered" | "retry" | "drop";
+export declare class WebhooksDispatcher {
+    private readonly transport;
+    private readonly now;
+    private readonly baseDelayMs;
+    private readonly maxDelayMs;
+    private readonly defaultMaxAttempts;
+    private readonly toleranceSeconds;
+    private readonly endpoints;
+    private readonly deliveries;
+    private sequence;
+    constructor(options: WebhookDispatcherOptions);
+    registerEndpoint(endpoint: WebhookEndpoint): void;
+    listEndpoints(): WebhookEndpoint[];
+    /** Délivre un événement à tous les endpoints actifs qui le demandent. */
+    dispatch(event: WebhookEventEnvelope): Promise<DeliveryReport[]>;
+    /** Rejoue les livraisons échues (à appeler depuis un cron). */
+    retryPending(): Promise<DeliveryReport[]>;
+    /**
+     * Rejoue une dead letter. Le statut repasse à `retryable` puis un nouvel
+     * essai est effectué immédiatement.
+     */
+    replayDeadLetter(deliveryId: string): Promise<DeliveryReport>;
+    listDeadLetters(): DeliveryReport[];
+    getDelivery(deliveryId: string): DeliveryReport | null;
+    private deliveryId;
+    private skipped;
+    private attempt;
+}
+export type ExportFormat = "json" | "ndjson" | "csv";
+export interface S3ExportDescriptor {
+    exportId: string;
+    bucket: string;
+    region: string;
+    /** Endpoint S3-compatible (R2, MinIO). `undefined` = AWS. */
+    endpoint?: string;
+    key: string;
+    contentType: string;
+    body: string;
+    byteLength: number;
+    checksumSha256: string;
+    createdAt: string;
+    /** Date après laquelle l'objet peut être purgé par la rétention. */
+    expiresAt: string;
+    /** La signature SigV4 est déléguée au Worker : aucun secret ici. */
+    requiresSigV4: true;
+}
+export declare function buildS3ObjectKey(options: {
+    prefix?: string;
+    dataset: string;
+    projectId: string;
+    date: string;
+    exportId: string;
+    format: ExportFormat;
+}): string;
+/**
+ * Prépare l'objet à envoyer vers S3/R2. Le corps est sérialisé de façon
+ * stable pour que le checksum soit reproductible.
+ */
+export declare function buildS3ExportDescriptor(options: {
+    bucket: string;
+    region: string;
+    endpoint?: string;
+    prefix?: string;
+    dataset: string;
+    projectId: string;
+    exportId: string;
+    format: ExportFormat;
+    rows: readonly Record<string, unknown>[];
+    retentionDays?: number;
+    now?: Date;
+}): S3ExportDescriptor;

package/dist/weekly-report.d.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+export interface PageMetric {
+    path: string;
+    views: number;
+    uniqueVisitors: number;
+}
+export interface WeeklyReportInput {
+    periodStart: string;
+    periodEnd: string;
+    totalTraffic: number;
+    totalEvents: number;
+    topPages: PageMetric[];
+    bounceRate?: number;
+    conversions?: number;
+}
+export interface WeeklyReport {
+    periodStart: string;
+    periodEnd: string;
+    totalTraffic: number;
+    totalEvents: number;
+    topPages: PageMetric[];
+    bounceRate: number;
+    conversions: number;
+    generatedAt: string;
+}
+export declare const WeeklyReportSchema: z.ZodObject<{
+    periodStart: z.ZodString;
+    periodEnd: z.ZodString;
+    totalTraffic: z.ZodNumber;
+    totalEvents: z.ZodNumber;
+    topPages: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        views: z.ZodNumber;
+        uniqueVisitors: z.ZodNumber;
+    }, z.core.$strip>>;
+    bounceRate: z.ZodNumber;
+    conversions: z.ZodNumber;
+    generatedAt: z.ZodString;
+}, z.core.$strip>;
+export declare function buildWeeklyReport(input: WeeklyReportInput, now?: string): WeeklyReport;

package/dist/white-label-exports.d.ts

@@ -0,0 +1,50 @@
+/**
+ * G11 — White-label Exports
+ *
+ * LynxSEO: white-label.ts + PulseExportDropdown.tsx + HtmlPdfReport + PdfExportService
+ *          + white-label-exports.ts (nouveau - fonctions d'export pures)
+ * Inspiration: Metabase export + documentation mentionnée
+ *
+ * NOTE: white-label.ts + PulseExportDropdown.tsx + HtmlPdfReport + PdfExportService
+ * fournissent l'export avec branding LynxSEO, mais white-label-exports.ts propose
+ * les fonctions d'export pures (sans dépendance au framework React) réutilisables
+ * dans des contextes non-HTTP ou scripts batch.
+ */
+/** Options for white-label export */
+export type WhiteLabelExportOptions = {
+    /** Titre du rapport */
+    title: string;
+    /** Sous-titre du rapport */
+    subtitle?: string;
+    /** Nom de la marque */
+    brandName: string;
+    /** Couleur primaire */
+    primaryColor: string;
+    /** Couleur secondaire */
+    secondaryColor?: string;
+    /** Format d'export */
+    format: "pdf" | "html" | "csv";
+    /** Données à inclure */
+    data: any[];
+    /** Filtres appliqués */
+    filters?: Record<string, any>;
+};
+/** Exporter un rapport au format PDF */
+export declare function exportPdf(options: WhiteLabelExportOptions): Promise<{
+    success: boolean;
+    filePath: string;
+    size: number;
+}>;
+/** Exporter un rapport au format HTML */
+export declare function exportHtml(options: WhiteLabelExportOptions): Promise<{
+    success: boolean;
+    filePath: string;
+    size: number;
+}>;
+/** Exporter un rapport au format CSV */
+export declare function exportCsv(options: WhiteLabelExportOptions): Promise<{
+    success: boolean;
+    filePath: string;
+    size: number;
+    data: string;
+}>;

package/dist/word-frequency-analyzer.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 🔠 WordFrequencyAnalyzer
+ *
+ * Implements multi-lingual text tokenization, stop-word elimination,
+ * n-gram frequency extraction (1-gram, 2-gram, 3-gram), keyword density
+ * calculation, keyword stuffing detection, and D3 Word Cloud data generation.
+ */
+export interface WordFrequencyItem {
+    term: string;
+    count: number;
+    density: number;
+    isOverOptimized: boolean;
+}
+export interface WordCloudItem {
+    text: string;
+    value: number;
+    fontSize: number;
+    color: string;
+}
+export interface WordFrequencyAnalysisResult {
+    totalWords: number;
+    uniqueWords: number;
+    oneGrams: WordFrequencyItem[];
+    twoGrams: WordFrequencyItem[];
+    threeGrams: WordFrequencyItem[];
+    overOptimizedTerms: WordFrequencyItem[];
+    wordCloudData: WordCloudItem[];
+}
+export interface WordFrequencyOptions {
+    language?: string;
+    minWordLength?: number;
+    topN?: number;
+    singleWordStuffingThreshold?: number;
+    multiWordStuffingThreshold?: number;
+    minCloudFontSize?: number;
+    maxCloudFontSize?: number;
+}
+export declare const STOP_WORDS: Record<string, Set<string>>;
+export declare class WordFrequencyAnalyzer {
+    /**
+     * Cleans HTML and extracts lowercased word tokens
+     */
+    static tokenize(textOrHtml: string): string[];
+    /**
+     * Analyzes word frequency, n-grams, and keyword density
+     */
+    static analyze(textOrHtml: string, options?: WordFrequencyOptions): WordFrequencyAnalysisResult;
+}

package/dist/xlsx-workbook.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Generic multi-sheet XLSX builder.
+ *
+ * Uses the `exceljs` dependency already declared by this package so callers
+ * (Pulse export, Studio, agents) do not need to duplicate workbook plumbing.
+ * The output is a plain `Uint8Array`, which is what Worker routes can return
+ * directly.
+ */
+export type XlsxCellValue = string | number | boolean | null;
+export interface XlsxSheet {
+    name: string;
+    columns: string[];
+    rows: XlsxCellValue[][];
+}
+export declare function buildXlsxWorkbook(sheets: XlsxSheet[]): Promise<Uint8Array>;

package/dist/xray-dashboard.d.ts

@@ -0,0 +1,76 @@
+/**
+ * X-ray: an exploratory dashboard generated from whatever a project already
+ * has (latest crawl, Search Console, rank tracking, GEO scoring) instead of
+ * asking the user to assemble one card by card.
+ *
+ * Pure and dependency-free so the same spec can be rendered by the app, by the
+ * MCP server, or by the static-viz renderer.
+ */
+export type XrayStatus = "good" | "watch" | "critical";
+export type XraySectionId = "crawl" | "search" | "rank" | "geo";
+export interface XrayCrawlSnapshot {
+    pagesCrawled: number;
+    errors4xx: number;
+    errors5xx: number;
+    thinPages: number;
+    missingTitles: number;
+    missingMetaDescriptions: number;
+    slowPages: number;
+    duplicatePages: number;
+    notIndexable: number;
+}
+export interface XraySearchSnapshot {
+    clicks: number;
+    impressions: number;
+    ctr: number;
+    position: number;
+}
+export interface XrayRankSnapshot {
+    trackedKeywords: number;
+    outsideTop10: number;
+    averagePosition: number;
+}
+export interface XrayGeoSnapshot {
+    citabilityScore: number | null;
+    aiCrawlersAllowed: number | null;
+    aiCrawlersTotal: number | null;
+}
+export interface XrayInput {
+    projectName: string;
+    generatedAt: string;
+    crawl: XrayCrawlSnapshot;
+    search?: XraySearchSnapshot;
+    rank?: XrayRankSnapshot;
+    geo?: XrayGeoSnapshot;
+}
+export interface XrayCard {
+    id: string;
+    section: XraySectionId;
+    title: string;
+    value: number;
+    unit: "count" | "percent" | "position" | "score";
+    status: XrayStatus;
+    insight: string;
+    action: string;
+}
+export interface XraySection {
+    id: XraySectionId;
+    title: string;
+    cards: XrayCard[];
+}
+export interface XrayRecommendation {
+    priority: "critical" | "high" | "medium";
+    title: string;
+    rationale: string;
+}
+export interface XrayDashboard {
+    projectName: string;
+    generatedAt: string;
+    healthScore: number;
+    grade: "A" | "B" | "C" | "D";
+    headline: string;
+    cards: XrayCard[];
+    sections: XraySection[];
+    recommendations: XrayRecommendation[];
+}
+export declare function buildXrayDashboard(input: XrayInput): XrayDashboard;

package/dist/yoast-parity.d.ts

@@ -1,24 +1,38 @@
 /**
- * 🟢 Yoast SEO Parity & Real-Time Readability Engine
+ * 🟢 Real-Time On-Page SEO Assessment Suite
  *
  * Implements the iconic Yoast SEO features (13M+ installs):
- * 1. Readability Analysis (Analyse de Lisibilité aux pastilles Vertes/Oranges/Rouges) :
+ * 1. Readability Analysis (Pastilles Vertes/Oranges/Rouges) :
  *    - Flesch Reading Ease Formula (Score de lisibilité)
  *    - Transition Words Detection (Mots de transition > 30%)
  *    - Passive Voice Detection (Voix passive < 10%)
  *    - Sentence Length Distribution (Phrases > 20 mots < 25%)
  *    - Paragraph Length (< 150 mots par paragraphe)
  *    - Subheading Distribution (< 300 mots sous un sous-titre)
- * 2. Google SERP Pixel Width Calculator (Titre max 600px, Description max 960px)
+ *    - Consecutive Sentence Beginnings (< 3 phrases consécutives commençant par le même mot)
+ * 2. SEO Keyphrase Assessment (22 critères de mot-clé) :
+ *    - Keyphrase in SEO Title & Front-Loading
+ *    - Google SERP Pixel Width Calculator (Titre max 600px, Description max 960px)
+ *    - Keyphrase in URL Slug
+ *    - Keyphrase in Introduction (100 premiers mots)
+ *    - Keyphrase in Subheadings (H2, H3)
+ *    - Keyphrase Density (Plage idéale : 0.5% - 3.0%)
+ *    - Keyphrase in Meta Description & Length (120-156 chars)
+ *    - Text Length (300+ mots standard, 900+ mots cornerstone)
+ *    - Internal Links & Outbound Links Presence
+ *    - Image Alt Attributes containing Keyphrase
+ *    - Single H1 Presence
  * 3. Cornerstone Content (Contenu Pilier & Priorisation du Maillage)
  */
-export interface YoastReadabilityBullet {
+export interface YoastBullet {
     id: string;
     label: string;
     status: "green" | "orange" | "red";
     scoreValue: number;
     message: string;
 }
+export type YoastReadabilityBullet = YoastBullet;
+export type YoastSeoBullet = YoastBullet;
 export interface YoastAnalysisResult {
     overallReadability: "green" | "orange" | "red";
     fleschReadingScore: number;
@@ -26,7 +40,10 @@ export interface YoastAnalysisResult {
     transitionWordsPercent: number;
     passiveVoicePercent: number;
     longSentencesPercent: number;
-    bullets: YoastReadabilityBullet[];
+    paragraphsTooLongCount: number;
+    subheadingsTooLongCount: number;
+    consecutiveBeginningsViolations: number;
+    bullets: YoastBullet[];
     serpPreview: {
         titlePixelWidth: number;
         titlePixelLimit: 600;
@@ -36,10 +53,74 @@ export interface YoastAnalysisResult {
         descIsTruncated: boolean;
     };
 }
+export interface KeyphraseAnalysisOptions {
+    text: string;
+    keyphrase: string;
+    title?: string;
+    slug?: string;
+    metaDescription?: string;
+    isCornerstone?: boolean;
+    internalLinksCount?: number;
+    outboundLinksCount?: number;
+    imagesAltTexts?: string[];
+    htmlContent?: string;
+}
+export interface YoastKeyphraseResult {
+    overallSeo: "green" | "orange" | "red";
+    seoScore: number;
+    keyphrase: string;
+    keyphraseLength: number;
+    keyphraseDensityPercent: number;
+    keyphraseOccurrences: number;
+    totalWords: number;
+    isCornerstone: boolean;
+    bullets: YoastBullet[];
+}
 export declare class YoastParityEngine {
     private static frenchTransitionWords;
     /**
      * 1. Full Yoast-Style Readability Analysis.
      */
     static analyzeReadability(text: string, title?: string, description?: string): YoastAnalysisResult;
+    /**
+     * 2. Comprehensive Yoast-Style SEO Keyphrase Assessment (22 points).
+     */
+    static analyzeKeyphrase(opts: KeyphraseAnalysisOptions): YoastKeyphraseResult;
+    /**
+     * Analyse plusieurs mots-clés secondaires en complément de la keyphrase primaire.
+     *
+     * @param primaryInput         Paramètres d'analyse de la keyphrase principale
+     * @param secondaryKeyphrases  Liste des keyphrases secondaires à analyser
+     * @returns                    Résultat combiné primaire + secondaires
+     */
+    static analyzeMultiKeyphrases(primaryInput: KeyphraseAnalysisInput, secondaryKeyphrases: SecondaryKeyphraseInput[]): MultiKeyphraseAnalysisResult;
+}
+/** Alias pour KeyphraseAnalysisOptions — compatibilité API Gap 4 */
+export type KeyphraseAnalysisInput = KeyphraseAnalysisOptions;
+/** Alias pour YoastKeyphraseResult — compatibilité API Gap 4 */
+export type KeyphraseAnalysisResult = YoastKeyphraseResult;
+export interface SecondaryKeyphraseInput {
+    keyphrase: string;
+    articleText: string;
+    metaDescription?: string;
+    h2Headings?: string[];
+    h3Headings?: string[];
+}
+export interface SecondaryKeyphraseResult {
+    keyphrase: string;
+    inMetaDescription: boolean;
+    inSubheadings: boolean;
+    density: number;
+    densityStatus: "green" | "orange" | "red";
+    overallStatus: "green" | "orange" | "red";
+    assessments: Array<{
+        id: string;
+        status: "green" | "orange" | "red";
+        message: string;
+    }>;
+}
+export interface MultiKeyphraseAnalysisResult {
+    primary: KeyphraseAnalysisResult;
+    secondary: SecondaryKeyphraseResult[];
+    combinedOverallStatus: "green" | "orange" | "red";
 }

package/dist/yoast-schema-graph.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 🕸️ Yoast Interconnected Schema.org Graph Builder
+ *
+ * Implements the gold-standard Yoast SEO JSON-LD architecture:
+ * Generates an interconnected `@graph` where WebSite, Organization/Person,
+ * WebPage, BreadcrumbList, and Article nodes reference each other via permanent @id URIs.
+ */
+export interface SchemaBreadcrumbItem {
+    name: string;
+    url?: string;
+}
+export interface YoastSchemaGraphOptions {
+    siteUrl: string;
+    siteName: string;
+    siteDescription?: string;
+    canonicalUrl: string;
+    pageTitle: string;
+    metaDescription?: string;
+    pageType?: "Article" | "WebPage" | "AboutPage" | "ContactPage" | "FAQPage";
+    locale?: string;
+    datePublished?: string;
+    dateModified?: string;
+    authorName?: string;
+    authorUrl?: string;
+    organizationName?: string;
+    organizationLogo?: string;
+    organizationSameAs?: string[];
+    primaryImageUrl?: string;
+    primaryImageCaption?: string;
+    breadcrumbs?: SchemaBreadcrumbItem[];
+    categories?: string[];
+    searchUrlTemplate?: string;
+}
+export declare class YoastSchemaGraphBuilder {
+    /**
+     * Generates a fully interconnected Schema.org @graph conforming to Yoast SEO output standards.
+     */
+    static buildGraph(opts: YoastSchemaGraphOptions): Record<string, unknown>;
+}

package/dist/yoast-variable-replacer.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 🏷️ Yoast Snippet Replacement Variable Engine
+ *
+ * Emulates the iconic Yoast SEO variable replacement system (packages/replacement-variable-editor):
+ * Replaces dynamic snippet tags (%%title%%, %%sitename%%, %%sep%%, %%currentyear%%, etc.)
+ * in SEO titles and meta descriptions with actual page/site context.
+ */
+export interface VariableReplacementContext {
+    title?: string;
+    siteName?: string;
+    siteDescription?: string;
+    excerpt?: string;
+    separator?: string;
+    date?: string;
+    modifiedDate?: string;
+    category?: string;
+    primaryCategory?: string;
+    authorName?: string;
+    focusKeyphrase?: string;
+    pageNumber?: number;
+    totalPageCount?: number;
+    customFields?: Record<string, string>;
+}
+export declare class YoastVariableReplacer {
+    static readonly DEFAULT_SEPARATOR = "-";
+    /**
+     * Replaces all %%variables%% in a template string using the provided context.
+     */
+    static replace(template: string, ctx?: VariableReplacementContext): string;
+    /**
+     * Cleans up orphaned separators and extraneous spaces resulting from empty variables.
+     */
+    private static cleanPunctuation;
+}

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

@@ -0,0 +1,28 @@
+export interface YotpoSubscriberPayload {
+    storeId: string;
+    accessToken: string;
+    email?: string;
+    phone?: string;
+    firstName?: string;
+    lastName?: string;
+    externalId?: string;
+    tags?: string[];
+    properties?: Record<string, unknown>;
+}
+export interface YotpoSyncResult {
+    success: boolean;
+    customerId?: string;
+    error?: string;
+}
+export interface YotpoSyncConfig {
+    fetchFn?: typeof fetch;
+}
+export declare class YotpoSyncEngine {
+    private fetchFn;
+    constructor(config?: YotpoSyncConfig);
+    /**
+     * Crée ou met à jour un profil client / abonné SMS sur Yotpo V3 API.
+     * Endpoint: PATCH https://api.yotpo.com/core/v3/stores/{store_id}/customers
+     */
+    syncSubscriber(input: YotpoSubscriberPayload): Promise<YotpoSyncResult>;
+}