@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/plugins/visitor-interest/index.d.ts

@@ -0,0 +1,77 @@
+/**
+ * LynxSEO - Visitor Interest Plugin
+ * Inspiré de Matomo Visitor Interest (GPLv3 / AGPLv3 compatible).
+ *
+ * Distribution des pages vues et durée par visite, analyse de l'engagement visiteur.
+ */
+import { type LynxSeoPlugin, type PluginManifest, type PluginContext, type PluginEvent } from "../../plugin/types";
+export interface VisitPage {
+    url: string;
+    timestamp: string;
+    timeOnPage: number;
+}
+export interface VisitProfile {
+    visitorId: string;
+    siteId: string;
+    pageViews: number;
+    totalDuration: number;
+    pages: VisitPage[];
+    bounce: boolean;
+    firstPage?: string;
+    lastPage?: string;
+}
+export interface InterestDistribution {
+    pagesPerVisit: number;
+    avgDuration: number;
+    bounceRate: number;
+    depthDistribution: Record<string, number>;
+}
+export interface CustomVisitInput {
+    durationSeconds: number;
+    pagesCount: number;
+    daysSinceLastVisit?: number;
+}
+export interface VisitorInterestReportOptions {
+    customVisits?: CustomVisitInput[];
+}
+export interface DistributionBracket {
+    range: string;
+    visits: number;
+    percentage: number;
+    bounceRate?: number;
+}
+export interface RetentionBreakdown {
+    firstTimeVisitors: number;
+    returningVisitors: number;
+    returnRatePercentage: number;
+}
+export interface VisitorInterestReport {
+    siteId: string;
+    totalVisits: number;
+    avgVisitDurationSeconds: number;
+    avgPagesPerVisit: number;
+    engagementScore: number;
+    durationDistribution: DistributionBracket[];
+    pageDistribution: DistributionBracket[];
+    recencyDistribution: DistributionBracket[];
+    retentionBreakdown: RetentionBreakdown;
+}
+export declare class VisitorInterestPlugin implements LynxSeoPlugin {
+    readonly manifest: PluginManifest;
+    private ctx?;
+    private visits;
+    private currentVisit;
+    enable(ctx: PluginContext): Promise<void>;
+    onEvent(event: PluginEvent): Promise<void>;
+    /**
+     * Récupère la distribution d'intérêt pour un site.
+     */
+    getDistribution(siteId: string): InterestDistribution;
+    /**
+     * Récupère les profils de visite d'un site.
+     */
+    getProfiles(siteId: string, limit?: number): VisitProfile[];
+    getReport(siteId: string, options?: VisitorInterestReportOptions): VisitorInterestReport;
+    disable(): Promise<void>;
+}
+export default VisitorInterestPlugin;

package/dist/plugins/visits-summary/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * VisitsSummary Plugin — LynxSEO Engine
+ *
+ * Parité fonctionnelle :
+ * - Matomo Core : Plugin VisitsSummary (Métriques consolidées de visites, visiteurs uniques, pages vues, durée moyenne de session, taux de rebond, actions par visite, et comparatif période N vs N-1 avec deltas)
+ * - PostHog Web Analytics : Synthèse des métriques d'engagement globales
+ *
+ * Licence : AGPL-3.0-or-later
+ */
+import type { LynxSeoPlugin, PluginContext, PluginEvent, PluginManifest } from "../../plugin";
+export interface MetricWithDelta {
+    value: number;
+    previousValue: number;
+    changePercent: number;
+}
+export interface VisitsSummaryMetrics {
+    visits: MetricWithDelta;
+    uniqueVisitors: MetricWithDelta;
+    users: MetricWithDelta;
+    pageviews: MetricWithDelta;
+    uniquePageviews: MetricWithDelta;
+    bounceRate: MetricWithDelta;
+    avgVisitDurationSeconds: MetricWithDelta;
+    actionsPerVisit: MetricWithDelta;
+    conversions: MetricWithDelta;
+    conversionRate: MetricWithDelta;
+}
+export interface VisitsSummaryTimeSeriesPoint {
+    date: string;
+    visits: number;
+    pageviews: number;
+    bounces: number;
+}
+export interface VisitsSummaryReport {
+    siteId: string;
+    period: string;
+    metrics: VisitsSummaryMetrics;
+    sparkline: VisitsSummaryTimeSeriesPoint[];
+    summaryText: string;
+}
+export interface RawVisitRecord {
+    visitorId: string;
+    userId?: string;
+    timestamp: string;
+    durationSeconds: number;
+    actionsCount: number;
+    isBounce: boolean;
+    isConversion: boolean;
+    pageviewsCount: number;
+}
+export declare class VisitsSummaryPlugin implements LynxSeoPlugin {
+    readonly manifest: PluginManifest;
+    private context?;
+    private visitsBySite;
+    enable(ctx: PluginContext): void;
+    onEvent(event: PluginEvent): void;
+    recordVisit(siteId: string, visit: RawVisitRecord): void;
+    private calcDelta;
+    getStats(siteId: string): VisitsSummaryReport;
+    getReport(siteId: string, options?: {
+        period?: string;
+    }): VisitsSummaryReport;
+    private getDefaultReport;
+}

package/dist/plugins/weekly-traffic/index.d.ts

@@ -0,0 +1 @@
+export * from "./weekly-traffic";

package/dist/plugins/weekly-traffic/weekly-traffic.d.ts

@@ -0,0 +1,75 @@
+/**
+ * WeeklyTrafficPlugin — Matrice hebdomadaire 7 jours × 24 heures et analyse d'affluence
+ *
+ * Inspiré de Umami (getWeeklyTraffic.ts), de PostHog (Day/Hour activity matrix)
+ * et de Matomo (VisitTime).
+ *
+ * Implémentation Clean-Room indépendante sous licence AGPL-3.0.
+ */
+import type { LynxSeoPlugin, PluginManifest } from "../../plugin/types";
+export interface WeeklyTrafficSlot {
+    day: number;
+    dayName: string;
+    hour: number;
+    visits: number;
+    intensityPct: number;
+}
+export interface WeeklyTrafficPeak {
+    day: number;
+    dayName: string;
+    hour: number;
+    visits: number;
+    sharePct: number;
+}
+export interface WeekdayWeekendBreakdown {
+    weekdayVisits: number;
+    weekendVisits: number;
+    weekdaySharePct: number;
+    weekendSharePct: number;
+    dominantType: "B2B_WEEKDAY" | "B2C_WEEKEND_EVENINGS" | "BALANCED";
+}
+export interface SeoPublishingWindow {
+    recommendedDay: string;
+    recommendedTimeSlot: string;
+    rationale: string;
+}
+export interface WeeklyTrafficReport {
+    matrix: number[][];
+    totalVisits: number;
+    hourlyTotals: number[];
+    dailyTotals: number[];
+    peak: WeeklyTrafficPeak;
+    quietest: {
+        day: number;
+        dayName: string;
+        hour: number;
+        visits: number;
+    };
+    weekdayWeekend: WeekdayWeekendBreakdown;
+    seoRecommendation: SeoPublishingWindow;
+    generatedAt: string;
+}
+export declare class WeeklyTrafficPlugin implements LynxSeoPlugin {
+    manifest: PluginManifest;
+    readonly id = "weekly-traffic";
+    readonly name = "Weekly Traffic Matrix (7j \u00D7 24h)";
+    readonly version = "1.0.0";
+    private matrix;
+    constructor();
+    reset(): void;
+    /**
+     * Enregistre une visite ou un événement horodaté
+     */
+    recordVisit(timestamp: string | Date, weight?: number): void;
+    /**
+     * Enregistre un lot d'événements
+     */
+    recordBatch(events: Array<{
+        timestamp: string | Date;
+        count?: number;
+    }>): void;
+    /**
+     * Calcule le rapport d'analyse de trafic hebdomadaire complet
+     */
+    computeWeeklyReport(): WeeklyTrafficReport;
+}

package/dist/plugins/widgetize/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Widgetize Plugin (Inspiré de Matomo Widgetize & Dashboard Embeds)
+ *
+ * Permet d'intégrer des visualisations, compteurs et graphiques analytiques LynxSEO
+ * dans des sites web tiers, portails intranet ou CMS via des iframes et snippets JS sécurisés.
+ */
+import type { LynxSeoPlugin, PluginManifest, PluginContext } from "../../plugin/types";
+export type EmbedWidgetType = "live_counter" | "kpi_summary" | "traffic_trend" | "top_pages" | "top_referrers" | "goal_conversions";
+export type WidgetTheme = "light" | "dark" | "transparent" | "system";
+export interface EmbedWidgetConfig {
+    id: string;
+    projectId: string;
+    title: string;
+    widgetType: EmbedWidgetType;
+    theme: WidgetTheme;
+    allowedOrigins: string[];
+    token: string;
+    expiresAt: string | null;
+    enabled: boolean;
+    refreshIntervalSeconds: number;
+    createdAt: string;
+    totalViews: number;
+}
+export interface WidgetEmbedCodeSnippet {
+    widgetId: string;
+    iframeHtml: string;
+    reactJsx: string;
+    scriptSnippet: string;
+    directEmbedUrl: string;
+}
+export interface WidgetizeReport {
+    projectId: string;
+    widgets: EmbedWidgetConfig[];
+    totalActiveWidgets: number;
+    totalEmbedViewsMonth: number;
+}
+export declare class WidgetizePlugin implements LynxSeoPlugin {
+    manifest: PluginManifest;
+    private widgets;
+    init(_context: PluginContext): Promise<void>;
+    createWidget(params: {
+        projectId: string;
+        title: string;
+        widgetType: EmbedWidgetType;
+        theme?: WidgetTheme;
+        allowedOrigins?: string[];
+        expiresInDays?: number;
+        refreshIntervalSeconds?: number;
+    }): EmbedWidgetConfig;
+    toggleWidget(widgetId: string, enabled: boolean): boolean;
+    deleteWidget(widgetId: string): boolean;
+    generateEmbedCode(widgetId: string, baseUrl?: string): WidgetEmbedCodeSnippet | null;
+    recordWidgetView(widgetId: string, origin?: string): boolean;
+    getWidgetizeReport(projectId: string): WidgetizeReport;
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Postscript SMS Marketing Sync Engine
+ * Synchronisation des abonnés SMS et propriétés zero-party avec Postscript API v2.
+ */
+export interface PostscriptSubscriberPayload {
+    phoneNumber: string;
+    email?: string;
+    keyword?: string;
+    tags?: string[];
+    properties?: Record<string, unknown>;
+}
+export interface PostscriptSyncConfig {
+    apiKey: string;
+    defaultKeyword?: string;
+    fetchFn?: typeof fetch;
+}
+export interface PostscriptSyncResult {
+    success: boolean;
+    subscriberId?: string;
+    error?: string;
+}
+export declare class PostscriptSyncEngine {
+    private apiKey;
+    private defaultKeyword?;
+    private fetchFn;
+    constructor(config: PostscriptSyncConfig);
+    /**
+     * Normalise un numéro de téléphone au format E.164 (+33..., +1...)
+     */
+    normalizePhoneNumber(phone: string): string;
+    /**
+     * Crée ou met à jour un abonné SMS sur Postscript API v2
+     */
+    syncSubscriber(payload: PostscriptSubscriberPayload): Promise<PostscriptSyncResult>;
+}

package/dist/privacy/network-replay-sanitizer.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Network Replay Sanitizer — OpenReplay & Datadog RUM Parity
+ *
+ * Caviarde et assainit les requêtes et réponses HTTP capturées lors des replays de session
+ * (rrweb / OpenReplay network tracker) avant stockage ou retransmission.
+ * Empêche toute fuite de mots de passe, tokens JWT, en-têtes Authorization, cookies ou cartes bancaires.
+ */
+export interface CapturedNetworkRequest {
+    url: string;
+    method: string;
+    status: number;
+    durationMs: number;
+    requestHeaders?: Record<string, string>;
+    responseHeaders?: Record<string, string>;
+    requestBody?: unknown;
+    responseBody?: unknown;
+    timestamp: number;
+}
+export interface SanitizerOptions {
+    customSensitiveKeys?: string[];
+    customSensitiveHeaders?: string[];
+    maskCreditCards?: boolean;
+    maskJwtTokens?: boolean;
+}
+export declare class NetworkReplaySanitizer {
+    /**
+     * Caviarde les en-têtes HTTP (Authorization, Cookies, Tokens).
+     */
+    static sanitizeHeaders(headers?: Record<string, string>, customSensitiveHeaders?: string[]): Record<string, string>;
+    /**
+     * Nettoie les paramètres d'URL sensibles (jetons, clés, mots de passe).
+     */
+    static sanitizeUrl(urlStr: string): string;
+    /**
+     * Assainit récursivement les corps de requête ou réponse (JSON/Objets).
+     */
+    static sanitizePayload(payload: unknown, options?: SanitizerOptions): unknown;
+    /**
+     * Assainit un enregistrement réseau complet de session replay.
+     */
+    static sanitizeRequest(request: CapturedNetworkRequest, options?: SanitizerOptions): CapturedNetworkRequest;
+}

package/dist/privacy/privacy-sanitizer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Privacy Sanitizer & PII Masking Engine — RudderStack Parity
+ * (GDPR, CCPA, HIPAA Compliance)
+ *
+ * Nettoie, anonymise et filtre les données sensibles avant stockage ou transmission :
+ * 1. Anonymisation d'adresse IP (IPv4 sous-réseau /24, IPv6 sous-réseau /48).
+ * 2. Nettoyage d'URL (suppression des jetons d'authentification, clés API, sessions).
+ * 3. Masquage PII (emails, téléphones, cartes bancaires).
+ * 4. Détecteur de fuites PII (scan automatique des numéros de carte de crédit via Luhn, etc.).
+ */
+export interface PrivacySanitizerConfig {
+    anonymizeIps?: boolean;
+    stripSensitiveUrlParams?: boolean;
+    maskEmails?: boolean;
+    maskPhones?: boolean;
+    hashIdentifiers?: boolean;
+    customSensitiveKeys?: string[];
+}
+/**
+ * Anonymise une adresse IPv4 (masquage du dernier octet /24) ou IPv6 (troncature /48).
+ */
+export declare function anonymizeIp(ip: string): string;
+/**
+ * Supprime les paramètres d'URL contenant des secrets ou identifiants d'authentification.
+ */
+export declare function sanitizeUrl(rawUrl: string, extraSensitiveParams?: string[]): string;
+/**
+ * Masque un email (ex: "alexandre.dupont@entreprise.fr" -> "a***t@entreprise.fr").
+ */
+export declare function maskEmail(email: string): string;
+/**
+ * Masque un numéro de téléphone en ne conservant que les 2 premiers et 2 derniers chiffres.
+ */
+export declare function maskPhone(phone: string): string;
+/**
+ * Validation de numéro de carte de crédit par l'algorithme de Luhn
+ */
+export declare function isValidLuhn(digits: string): boolean;
+export interface PiiLeak {
+    path: string;
+    leakType: "credit_card" | "email" | "sensitive_key";
+    sample: string;
+}
+/**
+ * Scanne récursivement un objet pour détecter des fuites involontaires de PII.
+ */
+export declare function detectPiiLeaks(payload: Record<string, unknown>, currentPath?: string): PiiLeak[];
+/**
+ * Assainit un événement complet selon la configuration de confidentialité.
+ */
+export declare function sanitizeEventPayload(event: Record<string, unknown>, config?: PrivacySanitizerConfig): Record<string, unknown>;

package/dist/privacy-tracker-generator.d.ts

@@ -0,0 +1,81 @@
+/**
+ * ⚡ LynxSEO Ultra-Lightweight Privacy-First Client Tracker Generator
+ *
+ * Generates an optimized, zero-dependency client tracking script that grows
+ * only with the probes it is asked to enable (about 5.5 KB for the pageview
+ * core, under 10 KB with every probe on including the consent gate).
+ * that works without cookies, without preflight CORS requests, and includes:
+ * - Real-time 404 Sentinel & pSEO cluster attribution
+ * - Outbound link and file download auditing
+ * - RUM Performance (Navigation Timing, TTFB, DOM Complete, Page Load latency)
+ * - Front-end JavaScript Error Sentinel (`window.onerror` and unhandled rejections)
+ */
+/**
+ * Query parameters that carry a checkout reference on the provider's return
+ * URL. Ordered from the most provider-specific to the most generic so a
+ * `checkout_session_id` always wins over a bare `session_id`.
+ */
+export declare const CHECKOUT_REF_PARAMS: readonly ["checkout_session_id", "checkout_id", "dodo_checkout_id", "pay_id", "session_id"];
+export interface TrackerScriptOptions {
+    domain: string;
+    /**
+     * Real project identifier. Analytics rows are keyed by `projectId`, so a
+     * snippet that only sends its domain writes rows the dashboard can never
+     * query. Falls back to `domain` for older tags.
+     */
+    siteId?: string;
+    /**
+     * Reads `data-domain` / `data-site-id` / `data-api` from the script tag at
+     * runtime (used by the CDN bundle, where one file serves every project).
+     */
+    readScriptTag?: boolean;
+    endpointUrl?: string;
+    track404Errors?: boolean;
+    trackOutboundLinks?: boolean;
+    trackFileDownloads?: boolean;
+    trackPseoMetadata?: boolean;
+    trackRumPerformance?: boolean;
+    trackErrors?: boolean;
+    trackInteractions?: boolean;
+    /**
+     * Emits `scroll` at the 25/50/75/100 % depth marks of the tallest page.
+     * Separate from `trackInteractions` (which carries click coordinates)
+     * because a site may want reading depth without pointing data.
+     */
+    trackScrolls?: boolean;
+    /**
+     * Observes Cloudflare Turnstile widgets and emits `turnstile_challenge`.
+     * Opt-in for generated tags; the served tracker enables it by default.
+     */
+    trackTurnstile?: boolean;
+    /**
+     * Captures paid click identifiers (gclid, fbclid, …) and UTM parameters from
+     * the landing URL, kept for the browser session so SPA navigations retain
+     * the campaign that brought the visitor in.
+     */
+    trackAttribution?: boolean;
+    /**
+     * Reports the checkout reference found on the provider's return URL so the
+     * webhook — which arrives with no cookie and no session — can be linked to
+     * the visitor who just paid.
+     */
+    trackRevenueDetection?: boolean;
+    hashMode?: boolean;
+    honorDnt?: boolean;
+    ignoreLocalhost?: boolean;
+}
+export declare class PrivacyTrackerGenerator {
+    /**
+     * Generates a ready-to-embed HTML `<script>` tag.
+     */
+    static generateScriptTag(options: TrackerScriptOptions): string;
+    /**
+     * Generates the raw minified JavaScript code for the tracker.
+     * Uses simple CORS requests (Content-Type: text/plain) to avoid OPTIONS preflight round-trips.
+     */
+    static generateMinifiedJs(options: TrackerScriptOptions): string;
+    /**
+     * Generates a server-side response helper for serving `/js/lynx-tracker.js` from a Worker/Edge route.
+     */
+    static getWorkerResponseHeaders(): Record<string, string>;
+}

package/dist/privacy-visitor-hasher.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 🛡️ LynxSEO Privacy-Preserving Visitor Identification Engine
+
+ *
+ * Provides 100% GDPR, CCPA, and PECR-compliant visitor hashing without cookies,
+ * persistent local storage identifiers, or cross-site tracking.
+ */
+export interface VisitorIdentityParams {
+    remoteIp: string;
+    userAgent: string;
+    domain: string;
+    hostname?: string;
+    salt?: string;
+}
+export interface SaltRotationState {
+    currentSalt: string;
+    previousSalt: string | null;
+    lastRotatedDate: string;
+}
+export declare class PrivacyVisitorHasher {
+    private static rotationState;
+    /**
+     * Generates a secure random 32-character hexadecimal salt.
+     */
+    static generateRandomSalt(): string;
+    /**
+     * Returns current UTC date formatted as YYYY-MM-DD.
+     */
+    static getTodayUtcDate(date?: Date): string;
+    /**
+     * Rotates daily salts if a new UTC day has started, keeping the previous day's salt
+     * for a 2-hour grace period to handle midnight-straddling visitor sessions.
+     */
+    static ensureSaltRotation(now?: Date): SaltRotationState;
+    /**
+     * Extracts the root domain from a hostname (e.g., "blog.example.com" -> "example.com").
+     */
+    static getRootDomain(hostname: string): string;
+    /**
+     * Generates an irreversible, privacy-preserving visitor identifier.
+     *
+     * Formula:
+     * SHA-256(Salt + UserAgent + RemoteIP + TargetDomain + RootDomain)
+     *
+     * Guarantees:
+     * 1. Non-reversible: IP address cannot be extracted from the hash.
+     * 2. Zero Cross-Site Tracking: domain & rootDomain are embedded in the hash.
+     * 3. Automatic Daily Expiration: Salt changes daily, preventing long-term profiling.
+     */
+    static generateVisitorId(params: VisitorIdentityParams): string;
+    /**
+     * Generates the previous day's visitor hash (used to reconcile sessions bridging across midnight).
+     */
+    static generatePreviousDayVisitorId(params: VisitorIdentityParams): string | null;
+    /**
+     * Generates a per-pageview or session event fingerprint to prevent duplicate click/view counting.
+     */
+    static generateEventFingerprint(params: VisitorIdentityParams & {
+        path: string;
+        eventName?: string;
+    }): string;
+}

package/dist/product-analytics.d.ts

@@ -0,0 +1,51 @@
+import type { TelemetryEventHistory } from "./product-health-analyzer";
+/**
+ * Product analytics derived from a raw event stream.
+ *
+ * Every ratio is computed from observed events only: no modelled fallback, no
+ * random noise. Callers receive zeroed ratios when there is not enough data,
+ * which is the honest answer for a dashboard that must drive decisions.
+ */
+export interface ProductAnalyticsEvent {
+    visitorId: string;
+    eventName: string;
+    urlPath: string;
+    createdAt: string;
+    isBot?: boolean | null;
+    referrer?: string | null;
+    properties?: Record<string, unknown> | string | null;
+}
+export interface ProductAnalyticsOptions {
+    now?: Date;
+    /** Events that mark the first value moment (default: first audit/project). */
+    activationEventNames?: string[];
+    /** Events that mark account creation (default: signup/user_created). */
+    signupEventNames?: string[];
+    /** Distinct active days in the 30-day window required to be a power user. */
+    powerUserMinActiveDays?: number;
+    /** Rolling window used for MAU, power users and channel concentration. */
+    activityWindowDays?: number;
+}
+export interface ProductAnalyticsSummary {
+    totalUsers: number;
+    activeUsers: number;
+    dau: number;
+    mau: number;
+    stickiness: number;
+    newUsersLast30Days: number;
+    returningUsersLast30Days: number;
+    churnedUsersLast30Days: number;
+    quickRatio: number;
+    oneVisitShare: number;
+    retentionW1: number;
+    retentionW4: number;
+    activationRate: number;
+    timeToValueMedianHours: number | null;
+    powerUsers: number;
+    powerUserShare: number;
+    sessions: number;
+    topChannelShare: number;
+    errorRate: number;
+    eventHistory: TelemetryEventHistory[];
+}
+export declare function computeProductAnalytics(events: ProductAnalyticsEvent[], options?: ProductAnalyticsOptions): ProductAnalyticsSummary;

package/dist/product-health-analyzer.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 🦔 Product Health & Diagnostic Findings Engine
+ *
+ * Design principles:
+ * - A metric without a vertical benchmark is decorative, not actionable.
+ * - Every diagnostic finding carries "What happened", "Why it matters", and "One concrete action".
+ * - Broken telemetry (silent event drop-off, drift) is flagged as a trust issue above all else.
+ * - Goal-oriented ranking (retention, activation, conversion, acquisition).
+ */
+export type ProductKind = "saas" | "ecommerce" | "content" | "ai_app" | "devtool" | "general";
+export type Goal = "retention" | "activation" | "conversion" | "acquisition";
+export type FindingSeverity = "critical" | "warning" | "opportunity" | "strength";
+export type BenchmarkBand = "poor" | "fair" | "good" | "excellent";
+export interface BenchmarkThreshold {
+    /** Ascending threshold boundaries: [poor->fair, fair->good, good->excellent] */
+    thresholds: [number, number, number];
+    /** True when lower values represent better health (e.g. bounce rate, one-visit churn) */
+    lowerIsBetter?: boolean;
+    /** Rationale for benchmark boundary */
+    basis: string;
+}
+export type VerticalBenchmarkTable = Record<string, Partial<Record<ProductKind | "general", BenchmarkThreshold>>>;
+export declare const VERTICAL_BENCHMARKS: VerticalBenchmarkTable;
+export interface DiagnosticEvidence {
+    label: string;
+    value: string;
+    typical?: string;
+    band?: BenchmarkBand;
+}
+export interface DiagnosticFinding {
+    id: string;
+    severity: FindingSeverity;
+    impact: number;
+    title: string;
+    headline?: string;
+    what: string;
+    why: string;
+    action: string;
+    evidence: DiagnosticEvidence[];
+    metricIds: string[];
+    goalRelevant?: boolean;
+    trust?: boolean;
+}
+export interface TelemetryEventHistory {
+    eventName: string;
+    last7DaysCount: number;
+    prev30DaysCount: number;
+}
+export interface ProductTelemetryMetrics {
+    productKind: ProductKind;
+    activeUsers?: number;
+    dau?: number;
+    mau?: number;
+    retentionW1?: number;
+    retentionW4?: number;
+    activationRate?: number;
+    signupConversion?: number;
+    oneVisitShare?: number;
+    topChannelShare?: number;
+    errorRate?: number;
+    eventHistory?: TelemetryEventHistory[];
+    untrackedKeyMoments?: string[];
+}
+export interface ProductHealthReport {
+    productKind: ProductKind;
+    goal?: Goal;
+    healthScore: number;
+    summary: {
+        criticalCount: number;
+        warningCount: number;
+        opportunityCount: number;
+        strengthCount: number;
+        trustIssueCount: number;
+    };
+    findings: DiagnosticFinding[];
+}
+/** Determine benchmark band and format comparison */
+export declare function evaluateBenchmark(metricId: string, value: number, kind?: ProductKind): {
+    band: BenchmarkBand;
+    typicalRange: string;
+    basis: string;
+} | null;
+/**
+ * Evaluates telemetry signals and generates prioritized prioritized actionable findings.
+ */
+export declare function analyzeProductHealth(metrics: ProductTelemetryMetrics, goal?: Goal): ProductHealthReport;