@lynxflow/seo-engine 2.8.0 → 3.2.0

package/dist/universal-seo-bridge.d.ts

@@ -0,0 +1,174 @@
+/**
+ * 🌉 Universal SEO Tools & Framework Bridge
+ *
+ * Combines and surpasses the best patterns from:
+ * 1. artesaos/seotools (Laravel) -> Fluent chaining Facade API
+ * 2. ethercreative/seo (Craft CMS) -> Rich metadata & preview state
+ * 3. garmeeh/next-seo (Next.js) -> Strict TypeScript types & multi-target compilation
+ *
+ * Compiles seamlessly to:
+ * - Pure HTML tags for Server-Side Rendering (Blade, Twig, Astro, Express, Bun)
+ * - Next.js 13/14/15 App Router Metadata object (`generateMetadata`)
+ * - garmeeh/next-seo drop-in`<NextSeo {...props} />` props
+ * - Craft CMS / EtherCreative SEO data structure
+ * - Google Rich Results JSON-LD with AEO/GEO Direct Answer injection
+ */
+export interface OpenGraphImage {
+    url: string;
+    width?: number;
+    height?: number;
+    alt?: string;
+    type?: string;
+    secureUrl?: string;
+}
+export interface TwitterCardConfig {
+    cardType: "summary" | "summary_large_image" | "app" | "player";
+    site?: string;
+    creator?: string;
+    title?: string;
+    description?: string;
+    image?: string;
+    imageAlt?: string;
+}
+export interface RobotsDirectives {
+    noindex?: boolean;
+    nofollow?: boolean;
+    noarchive?: boolean;
+    nosnippet?: boolean;
+    noimageindex?: boolean;
+    maxSnippet?: number;
+    maxImagePreview?: "none" | "standard" | "large";
+    maxVideoPreview?: number;
+}
+export interface NextAppRouterMetadata {
+    title: string | {
+        default: string;
+        template: string;
+    };
+    description?: string;
+    canonical?: string;
+    alternates?: {
+        canonical?: string;
+        languages?: Record<string, string>;
+    };
+    openGraph?: {
+        title?: string;
+        description?: string;
+        url?: string;
+        siteName?: string;
+        type?: string;
+        images?: {
+            url: string;
+            width?: number;
+            height?: number;
+            alt?: string;
+        }[];
+    };
+    twitter?: {
+        card?: string;
+        title?: string;
+        description?: string;
+        site?: string;
+        creator?: string;
+        images?: string[];
+    };
+    robots?: {
+        index?: boolean;
+        follow?: boolean;
+        nocache?: boolean;
+        googleBot?: {
+            index?: boolean;
+            follow?: boolean;
+            maxSnippet?: number;
+            maxImagePreview?: string;
+        };
+    };
+    other?: Record<string, string>;
+}
+export interface NextSeoProps {
+    title?: string;
+    description?: string;
+    canonical?: string;
+    noindex?: boolean;
+    nofollow?: boolean;
+    languageAlternates?: {
+        hrefLang: string;
+        href: string;
+    }[];
+    openGraph?: {
+        url?: string;
+        type?: string;
+        title?: string;
+        description?: string;
+        images?: OpenGraphImage[];
+        siteName?: string;
+        article?: Record<string, any>;
+    };
+    twitter?: {
+        handle?: string;
+        site?: string;
+        cardType?: string;
+    };
+    additionalMetaTags?: {
+        name?: string;
+        property?: string;
+        content: string;
+    }[];
+    additionalLinkTags?: {
+        rel: string;
+        href: string;
+        hrefLang?: string;
+    }[];
+}
+export declare class UniversalSeoTools {
+    private _title;
+    private _siteName;
+    private _titleSeparator;
+    private _description;
+    private _canonicalUrl;
+    private _robots;
+    private _alternates;
+    private _ogTitle;
+    private _ogDescription;
+    private _ogUrl;
+    private _ogType;
+    private _ogImages;
+    private _ogProperties;
+    private _twitter;
+    private _jsonLdSchemas;
+    private _directAnswer?;
+    /**
+     * Factory method for creating an instance
+     */
+    static create(): UniversalSeoTools;
+    setTitle(title: string, siteName?: string, separator?: string): this;
+    setDescription(description: string): this;
+    setCanonical(url: string): this;
+    setRobots(directives: RobotsDirectives): this;
+    addAlternate(hrefLang: string, href: string): this;
+    private _ogFacade?;
+    private _twitterFacade?;
+    private _jsonLdFacade?;
+    get opengraph(): any;
+    get twitter(): any;
+    get jsonLd(): any;
+    setDirectAnswer(summary: string, citationSource?: string): this;
+    /**
+     * Compiles the metadata into a single raw HTML string for `<head>` insertion.
+     * Compatible with Laravel Blade `{!! SEOTools::generate() !!}`, PHP, Astro, Express, etc.
+     */
+    generateHtml(): string;
+    /**
+     * Compiles the metadata into Next.js 13/14/15 App Router `Metadata` format.
+     */
+    toNextMetadata(): NextAppRouterMetadata;
+    /**
+     * Compiles into`garmeeh/next-seo` drop-in`<NextSeo {...props} />` configuration.
+     */
+    toNextSeoProps(): NextSeoProps;
+    /**
+     * Compiles into Craft CMS / EtherCreative SEO data payload.
+     */
+    toCraftSeoData(): Record<string, any>;
+    private escapeHtml;
+}

package/dist/urlytics-engine.d.ts

@@ -1,6 +1,5 @@
 /**
  * 🔍 Universal URL Analytics & Structural Decomposition Engine
- * Inspired by advertools.urlytics
  *
  * Breaks down any URL into structured path segments, query parameters, directory depths,
  * and slug tokens for crawl validation, audit logs, and programmatic matrix matching.

package/dist/user-agent-parser.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Bounded user-agent parsing for telemetry ingestion.
+ *
+ * Parsing is synchronous, so a timer cannot interrupt it; instead the input is
+ * truncated before any pattern runs and the elapsed time is checked between
+ * stages. A hostile header then degrades to a device-only result instead of
+ * monopolising the request.
+ */
+export type UserAgentDevice = "desktop" | "mobile" | "tablet";
+export interface UserAgentInfo {
+    browser: string | null;
+    browserName: string | null;
+    browserVersion: string | null;
+    os: string | null;
+    device: UserAgentDevice;
+    isBot: boolean;
+    truncated: boolean;
+    degraded: boolean;
+}
+export interface ParseUserAgentOptions {
+    maxLength?: number;
+    budgetMs?: number;
+    now?: () => number;
+}
+export declare function parseUserAgent(userAgent: string | null | undefined, options?: ParseUserAgentOptions): UserAgentInfo;

package/dist/user-id-tracking.d.ts

@@ -0,0 +1,74 @@
+/**
+ * User ID — Matomo Plugin "UserId"
+ *
+ * Unification des sessions d'un même utilisateur authentifié à travers les appareils.
+ * Déduit l'UserID depuis le tracker JS, le cookie d'authentification, ou un header custom.
+ */
+export interface UserIdContext {
+    userId?: string;
+    visitorId?: string;
+    isAuthenticated: boolean;
+    source: "tracker" | "auth-cookie" | "header" | "session";
+}
+export interface UserIdMapping {
+    userId: string;
+    visitorIds: string[];
+    firstSeen: Date;
+    lastSeen: Date;
+    sites: string[];
+    sessionCount: number;
+}
+export interface IdentityResolution {
+    canonicalUserId: string;
+    aliases: string[];
+    anonymousIds: string[];
+}
+export declare class UserIdTracker {
+    private mappings;
+    private visitorToUser;
+    private userAliases;
+    private aliasToUser;
+    /**
+     * Réinitialise l'état interne (utile pour les tests et l'isolation).
+     */
+    reset(): void;
+    /**
+     * Rapproche un identifiant antérieur (ex: anonymousId/previousId) d'un identifiant canonique (userId).
+     */
+    alias(userId: string, previousId: string): IdentityResolution;
+    /**
+     * Résout une identité complète à partir de n'importe quel identifiant lié (userId, alias, visitorId).
+     */
+    resolveIdentity(identifier: string): IdentityResolution | undefined;
+    /**
+     * Extrait l'UserID depuis le contexte de requête tracker.
+     * Priorité : header X-User-ID > cookie auth > payload tracker.
+     */
+    extractUserId(context: {
+        headers?: Record<string, string>;
+        query?: Record<string, string>;
+        payload?: Record<string, unknown>;
+        cookies?: Record<string, string>;
+    }): UserIdContext;
+    /**
+     * Lie un visitorId à un userId (unification des sessions cross-device).
+     */
+    linkVisitorToUser(userId: string, visitorId: string, siteId: string): void;
+    /**
+     * Récupère le userId associé à un visitorId, ou undefined.
+     */
+    getUserIdForVisitor(visitorId: string): string | undefined;
+    /**
+     * Récupère la mapping complète pour un userId.
+     */
+    getMapping(userId: string): UserIdMapping | undefined;
+    /**
+     * Liste tous les userIds trackés.
+     */
+    listUserIds(): string[];
+    /**
+     * Nombre d'utilisateurs uniques authentifiés.
+     */
+    countUniqueUsers(): number;
+}
+export declare const userIdTracker: UserIdTracker;

package/dist/user-journeys-advanced.d.ts

@@ -0,0 +1,30 @@
+export interface UserJourneyEvent {
+    eventType: string;
+    timestamp: number;
+    sessionId: string;
+    url: string;
+    meta?: Record<string, unknown>;
+}
+export interface UserPathNode {
+    eventType: string;
+    count: number;
+    avgTimeOnPageMs?: number;
+    conversionRate: number;
+    nextEvents: Array<{
+        eventType: string;
+        count: number;
+        conversionRate: number;
+    }>;
+}
+export interface UserJourneyReport {
+    rootEvents: UserPathNode[];
+    totalSessions: number;
+    avgDepth: number;
+    topExitPages: Array<{
+        url: string;
+        exitCount: number;
+        exitRate: number;
+    }>;
+}
+/** User Paths — graphique arborescent des flux réels de navigation (G avancé). */
+export declare function computeUserPaths(events: UserJourneyEvent[]): UserJourneyReport;

package/dist/user-journeys.d.ts

@@ -0,0 +1,19 @@
+export interface JourneyStep {
+    id: string;
+    label: string;
+}
+export interface JourneyTransition {
+    from: string;
+    to: string;
+    count: number;
+}
+export interface JourneyState {
+    steps: JourneyStep[];
+    transitions: JourneyTransition[];
+    updatedAt: string;
+}
+export declare function createJourneyState(steps: JourneyStep[], now?: Date): JourneyState;
+export declare function recordTransition(state: JourneyState, from: string, to: string, count?: number, now?: Date): JourneyState;
+export declare function stepCounts(state: JourneyState): Record<string, number>;
+export declare function dropoffRates(state: JourneyState): Record<string, number>;
+export declare function conversionRate(state: JourneyState, from: string, to: string): number;

package/dist/user-traits.d.ts

@@ -0,0 +1,15 @@
+export interface UserTrait {
+    visitorId: string;
+    key: string;
+    value: unknown;
+    updatedAt: string;
+}
+export interface UserTraitsState {
+    traits: UserTrait[];
+    updatedAt: string;
+}
+export declare function createUserTraitsState(now?: Date): UserTraitsState;
+export declare function setTrait(state: UserTraitsState, visitorId: string, key: string, value: unknown, now?: Date): UserTraitsState;
+export declare function getTraits(state: UserTraitsState, visitorId: string): Record<string, unknown>;
+export declare function queryByTrait(state: UserTraitsState, key: string, value: unknown): string[];
+export declare function removeTrait(state: UserTraitsState, visitorId: string, key: string, now?: Date): UserTraitsState;

package/dist/utm-conventions.d.ts

@@ -0,0 +1,37 @@
+/**
+ * UTM naming conventions shared by the campaign builder, the tracking-plan
+ * generator and the marketing CLIs.
+ *
+ * The rules are deliberately mechanical: lowercase, accent-free, separated by
+ * hyphens, short enough for analytics tools that truncate campaign names. A
+ * value that violates them is reported instead of silently rewritten, so a
+ * typo in a live campaign is caught before launch.
+ */
+export declare const STANDARD_UTM_PARAMS: readonly ["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "utm_id"];
+export type StandardUtmParam = (typeof STANDARD_UTM_PARAMS)[number];
+export interface UtmParameters {
+    source: string;
+    medium: string;
+    campaign: string;
+    term?: string;
+    content?: string;
+    id?: string;
+}
+export type UtmMediumFamily = "paid-search" | "paid-social" | "organic" | "email" | "referral" | "display" | "affiliate" | "other";
+export type UtmIssueSeverity = "error" | "warning" | "info";
+export interface UtmIssue {
+    code: "missing_required" | "too_long" | "not_normalized" | "reserved_prefix" | "generic_campaign" | "uncommon_medium" | "duplicate_source_medium";
+    parameter: keyof UtmParameters;
+    severity: UtmIssueSeverity;
+    message: string;
+}
+export declare const MAX_UTM_VALUE_LENGTH = 60;
+export declare const UTM_VALUE_PATTERN: RegExp;
+export declare function normalizeUtmValue(raw: string, separator?: "-", maxLength?: number): string;
+export declare function canonicalizeUtmSource(source: string): string;
+export declare function classifyUtmMedium(medium: string): UtmMediumFamily;
+export declare function validateUtmParameters(params: Partial<UtmParameters>): UtmIssue[];
+export declare function isUtmUrlSafe(url: string): boolean;
+export declare function buildUtmUrl(baseUrl: string, params: UtmParameters): string;
+export declare function parseUtmParameters(url: string): Partial<UtmParameters>;
+export declare function normalizeUtmParameters(params: UtmParameters): UtmParameters;

package/dist/video-seo-metadata-optimizer.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 🎬 VideoSeoMetadataOptimizer
+ *
+ * Optimise et audite les métadonnées vidéo (YouTube, TikTok, VideoObject SEO) :
+ * - Analyse de titre (longueur 40-70 cars, placement du mot-clé principal, Power Words)
+ * - Analyse de description (liens, timestamps/chapitrage, densité sémantique, call-to-action)
+ * - Validation du chapitrage horodaté (format 00:00 - Titre pour les Key Moments Google)
+ * - Tag optimization (combinaison tags génériques, marque et longue traîne)
+ * - Génération du schéma JSON-LD VideoObject avec clip/hasPart pour les Key Moments Google
+ *
+ * Pure In-Memory, 0 dépendance, < 0.1ms.
+ */
+export interface VideoChapter {
+    timestamp: string;
+    seconds: number;
+    title: string;
+}
+export interface VideoMetadataInput {
+    title: string;
+    description: string;
+    targetKeyword: string;
+    durationSeconds?: number;
+    uploadDate?: string;
+    thumbnailUrl?: string;
+    tags?: string[];
+    channelName?: string;
+    videoUrl?: string;
+}
+export interface VideoSeoAuditResult {
+    score: number;
+    grade: "A+" | "A" | "B" | "C" | "D" | "F";
+    summary: {
+        titleScore: number;
+        descriptionScore: number;
+        chaptersScore: number;
+        tagsScore: number;
+    };
+    chapters: VideoChapter[];
+    hasKeyMomentsReady: boolean;
+    warnings: string[];
+    recommendations: string[];
+    videoSchemaJsonLd: Record<string, unknown>;
+}
+export declare class VideoSeoMetadataOptimizer {
+    /**
+     * Analyse et score les métadonnées d'une vidéo YouTube / Web.
+     */
+    static analyze(input: VideoMetadataInput): VideoSeoAuditResult;
+    /**
+     * Extrait les timestamps depuis la description.
+     * Formats supportés: `00:00 Intro`, `0:45 Partie 1`, `12:30 Conclusion`, `01:15:00 Bonus`.
+     */
+    static extractChapters(text: string): VideoChapter[];
+}

package/dist/video-youtube-analyzer.d.ts

@@ -21,6 +21,17 @@ export declare class VideoYouTubeAnalyzer {
      * Generates Schema.org VideoObject JSON-LD for rich snippets on Google Video Carousel
      */
     static generateVideoObjectSchema(meta: YouTubeVideoMetadata): Record<string, any>;
+    /**
+     * Converts seconds into ISO 8601 duration format (e.g. 330 -> "PT5M30S", 3665 -> "PT1H1M5S").
+     */
+    static secondsToIso8601(totalSeconds: number): string;
+    /**
+     * Automatically parses video description lines to extract chapters/timestamps.
+     */
+    static parseDescriptionChapters(description: string): Array<{
+        time: number;
+        title: string;
+    }>;
     /**
      * Generates responsive, lazy-loaded, SEO-optimized HTML embed with Schema markup
      */

package/dist/wayback-client.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Client pour l'archivage pérenne et la vérification de snapshots sur la Wayback Machine (archive.org).
+ * Mécanisme d'archivage anti-link-rot des pages auditées.
+ */
+export interface WaybackSaveOptions {
+    timeoutMs?: number;
+    userAgent?: string;
+}
+export interface WaybackSaveResult {
+    success: boolean;
+    originalUrl: string;
+    archivedUrl?: string;
+    waybackUrl?: string;
+    timestamp?: string;
+    status?: number;
+    error?: string;
+}
+export interface WaybackSnapshotResult {
+    available: boolean;
+    originalUrl: string;
+    archivedUrl: string | null;
+    timestamp: string | null;
+    status: number | null;
+}
+export declare class WaybackClient {
+    private readonly defaultUserAgent;
+    /**
+     * Envoie une URL à sauvegarder sur la Wayback Machine.
+     * Utilise l'endpoint officiel `https://web.archive.org/save/{url}`.
+     */
+    saveUrl(url: string, options?: WaybackSaveOptions): Promise<WaybackSaveResult>;
+    /**
+     * Vérifie la disponibilité d'un snapshot archivé sur archive.org.
+     */
+    getSnapshot(url: string, requestedTimestamp?: string): Promise<WaybackSnapshotResult>;
+}

package/dist/webhook-service.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 🪝 General-purpose Webhook Delivery Service
+ *
+ * Permet d'enregistrer des URLs de webhook sortantes et de délivrer des événements
+ * avec retry automatique et backoff exponentiel.
+ *
+ * Aucun secret n'est durci ; les URLs et les clés de signature sont fournies
+ * par l'appelant.
+ */
+export interface WebhookSubscription {
+    id: string;
+    url: string;
+    events: string[];
+    secret?: string;
+    active: boolean;
+    createdAt: string;
+    updatedAt: string;
+    failureCount: number;
+    lastFailureAt?: string;
+    lastSuccessAt?: string;
+}
+export interface WebhookDelivery {
+    id: string;
+    subscriptionId: string;
+    event: string;
+    payload: unknown;
+    status: "pending" | "delivered" | "failed";
+    attempts: number;
+    createdAt: string;
+    deliveredAt?: string;
+    lastError?: string;
+}
+export interface WebhookEvent {
+    event: string;
+    payload: unknown;
+    projectId?: string;
+    orgId?: string;
+}
+export declare class WebhookService {
+    private subscriptions;
+    private deliveries;
+    private eventHandlers;
+    /**
+     * Enregistre un nouvel abonnement webhook.
+     */
+    registerSubscription(params: {
+        url: string;
+        events: string[];
+        secret?: string;
+    }): WebhookSubscription;
+    /**
+     * Liste tous les abonnements.
+     */
+    listSubscriptions(): WebhookSubscription[];
+    /**
+     * Récupère un abonnement par ID.
+     */
+    getSubscription(id: string): WebhookSubscription | undefined;
+    /**
+     * Active ou désactive un abonnement.
+     */
+    setSubscriptionActive(id: string, active: boolean): boolean;
+    /**
+     * Supprime un abonnement.
+     */
+    deleteSubscription(id: string): boolean;
+    /**
+     * Délivre un événement à tous les abonnements concernés.
+     * Retourne les IDs de livraison créés.
+     */
+    deliver(event: WebhookEvent): string[];
+    /**
+     * Tente de délivrer une livraison avec retry et backoff.
+     */
+    private attemptDelivery;
+    private handleDeliveryFailure;
+    /**
+     * Retourne l'historique des livraisons pour un abonnement.
+     */
+    getDeliveriesForSubscription(subscriptionId: string): WebhookDelivery[];
+    /**
+     * Retourne toutes les livraisons.
+     */
+    getAllDeliveries(): WebhookDelivery[];
+    /**
+     * S'abonne à un événement localement (pour usage in-process).
+     */
+    on(event: string, handler: (payload: unknown) => void): () => void;
+    /**
+     * Émet un événement localement aux handlers enregistrés.
+     */
+    emit(event: string, payload: unknown): void;
+    /**
+     * Vide toutes les données (utile pour les tests).
+     */
+    clear(): void;
+}
+export declare const defaultWebhookService: WebhookService;