featuredrop 2.7.1 → 3.0.1

package/dist/engine.d.ts

@@ -0,0 +1,422 @@
+/** Entry type label — determines default icon/color in UI */
+type FeatureType = "feature" | "improvement" | "fix" | "breaking";
+/** Priority level for announcements */
+type FeaturePriority = "critical" | "normal" | "low";
+/** Call-to-action for a feature entry */
+interface FeatureCTA {
+    /** Button/link label */
+    label: string;
+    /** URL to navigate to */
+    url: string;
+}
+/** Variant-level overrides for A/B announcement testing */
+interface FeatureVariant {
+    /** Optional variant-specific label override */
+    label?: string;
+    /** Optional variant-specific description override */
+    description?: string;
+    /** Optional variant-specific image override */
+    image?: string;
+    /** Optional variant-specific CTA override */
+    cta?: FeatureCTA;
+    /** Optional variant-specific metadata overrides */
+    meta?: Record<string, unknown>;
+}
+/** Audience targeting rule — determines which user segments see a feature */
+interface AudienceRule {
+    /** Plans that should see this feature (e.g. ["pro", "enterprise"]) */
+    plan?: string[];
+    /** Roles that should see this feature (e.g. ["admin", "editor"]) */
+    role?: string[];
+    /** Regions that should see this feature (e.g. ["us", "eu"]) */
+    region?: string[];
+    /** Arbitrary key-value pairs for custom matching logic */
+    custom?: Record<string, unknown>;
+}
+/** Dependency gates for progressive feature discovery */
+interface FeatureDependencies {
+    /** Features the user must have seen before this one can surface */
+    seen?: string[];
+    /** Features the user must have clicked before this one can surface */
+    clicked?: string[];
+    /** Features the user must have dismissed before this one can surface */
+    dismissed?: string[];
+}
+/** Runtime context used by trigger evaluation */
+interface TriggerContext {
+    /** Current app route/path */
+    path?: string;
+    /** Named events observed in this session */
+    events?: ReadonlySet<string>;
+    /** Named milestone flags reached in this session */
+    milestones?: ReadonlySet<string>;
+    /** Usage counters keyed by event/pattern name */
+    usage?: Record<string, number>;
+    /** Session elapsed time in milliseconds */
+    elapsedMs?: number;
+    /** Scroll completion percentage (0-100) */
+    scrollPercent?: number;
+    /** Optional additional trigger context */
+    metadata?: Record<string, unknown>;
+}
+type FeatureTrigger = {
+    type: "page";
+    match: string | RegExp;
+} | {
+    type: "usage";
+    event: string;
+    minActions?: number;
+} | {
+    type: "time";
+    minSeconds: number;
+} | {
+    type: "milestone";
+    event: string;
+} | {
+    type: "frustration";
+    pattern: string;
+    threshold?: number;
+} | {
+    type: "scroll";
+    minPercent?: number;
+} | {
+    type: "custom";
+    evaluate: (context: TriggerContext) => boolean;
+};
+/** A single feature entry in the manifest */
+interface FeatureEntry {
+    /** Unique identifier for the feature */
+    id: string;
+    /** Human-readable label (e.g. "Decision Journal") */
+    label: string;
+    /** Optional longer description (supports markdown in UI components) */
+    description?: string;
+    /**
+     * Semantic version targeting.
+     * If provided as an object, requires `appVersion` to be supplied to the provider/helpers.
+     * - introduced: earliest app version that includes this feature
+     * - showNewUntil: stop showing "new" once appVersion reaches this
+     * - deprecatedAt: hide feature for app versions at or above this (optional safety)
+     * - showIn: range string, e.g. ">=2.5.0 <3.0.0"
+     */
+    version?: string | {
+        introduced?: string;
+        showNewUntil?: string;
+        deprecatedAt?: string;
+        showIn?: string;
+    };
+    /** ISO date when this feature was released */
+    releasedAt: string;
+    /** ISO date after which the "new" badge should stop showing */
+    showNewUntil: string;
+    /** Optional key to match navigation items (e.g. "/journal", "settings") */
+    sidebarKey?: string;
+    /** Optional grouping category (e.g. "ai", "billing", "core") */
+    category?: string;
+    /** Optional product scope (`"*"`, `"askverdict"`, etc.) for multi-product manifests */
+    product?: string;
+    /** Optional URL to link to (e.g. docs page, changelog entry) */
+    url?: string;
+    /** Optional feature flag key; requires a flag bridge to evaluate */
+    flagKey?: string;
+    /** Entry type — determines default icon/color in UI components */
+    type?: FeatureType;
+    /** Priority level — critical entries get special treatment in UI */
+    priority?: FeaturePriority;
+    /** Optional image/screenshot URL */
+    image?: string;
+    /** Optional call-to-action button */
+    cta?: FeatureCTA;
+    /** ISO date — entry is hidden until this date (scheduled publishing) */
+    publishAt?: string;
+    /** Optional arbitrary metadata */
+    meta?: Record<string, unknown>;
+    /** A/B variants keyed by variant name (e.g. control, treatment_a) */
+    variants?: Record<string, FeatureVariant>;
+    /** Percentage split per variant (same order as variants object keys) */
+    variantSplit?: number[];
+    /** Audience targeting — if set, only matching users see this feature */
+    audience?: AudienceRule;
+    /** Dependency requirements (progressive disclosure sequencing) */
+    dependsOn?: FeatureDependencies;
+    /** Contextual trigger rule */
+    trigger?: FeatureTrigger;
+}
+/** Display format hint from the engine */
+type DisplayFormat = "badge" | "toast" | "modal" | "banner" | "inline" | "spotlight";
+/** Interaction type tracked by the engine */
+type InteractionType = "seen" | "dismissed" | "clicked" | "completed" | "snoozed" | "hovered" | "expanded";
+/** Timing decision returned by the engine */
+interface TimingDecision {
+    /** Whether to show the announcement now */
+    show: boolean;
+    /** Reason for the decision */
+    reason: string;
+    /** Suggested delay in ms if not showing now */
+    delayMs?: number;
+    /** Confidence level (0-1) */
+    confidence: number;
+}
+/** Format recommendation from the engine */
+interface FormatRecommendation {
+    /** Recommended display format */
+    primary: DisplayFormat;
+    /** Fallback format if primary component isn't used */
+    fallback: DisplayFormat;
+    /** Reason for the recommendation */
+    reason: string;
+}
+/** Adoption score breakdown */
+interface AdoptionScore {
+    /** Overall score (0-100) */
+    score: number;
+    /** Letter grade */
+    grade: "A" | "B" | "C" | "D" | "F";
+    /** Score breakdown */
+    breakdown: {
+        /** % of features the user has explored */
+        featuresExplored: number;
+        /** Rate of dismissals (lower is better) */
+        dismissRate: number;
+        /** Rate of tour/checklist completion */
+        completionRate: number;
+        /** Whether engagement is rising, stable, or declining */
+        engagementTrend: "rising" | "stable" | "declining";
+    };
+    /** Actionable recommendations */
+    recommendations: string[];
+}
+/** Per-feature adoption status */
+interface FeatureAdoptionStatus {
+    featureId: string;
+    status: "unseen" | "seen" | "explored" | "adopted" | "dismissed";
+    firstSeen?: string;
+    lastInteraction?: string;
+    interactionCount: number;
+}
+/** Delivery context passed to the engine for timing decisions */
+interface DeliveryContext {
+    /** Current route/path */
+    currentPath: string;
+    /** Seconds since session start */
+    sessionAge: number;
+    /** Dismissals in last 5 minutes */
+    recentDismissals: number;
+    /** Feature priority */
+    featurePriority: FeaturePriority;
+}
+/**
+ * Plugin interface for the FeatureDrop engine.
+ *
+ * The open-source library defines this interface.
+ * The proprietary @featuredrop/engine implements it.
+ * Users can also build their own engine implementation.
+ *
+ * The free library works perfectly without any engine.
+ */
+interface FeatureDropEngine {
+    /** Decide whether to show a feature announcement now */
+    shouldShow(featureId: string, context: DeliveryContext): TimingDecision;
+    /** Recommend the best display format for a feature */
+    recommendFormat(featureId: string): FormatRecommendation;
+    /** Get the user's overall adoption score */
+    getAdoptionScore(): AdoptionScore;
+    /** Track a user interaction with a feature */
+    trackInteraction(featureId: string, type: InteractionType): void;
+    /** Get adoption status for a specific feature */
+    getFeatureAdoption(featureId: string): FeatureAdoptionStatus;
+    /** Initialize the engine (called by provider on mount) */
+    initialize?(): void;
+    /** Cleanup resources (called by provider on unmount) */
+    destroy?(): void;
+}
+
+/** Compact behavior profile stored in localStorage */
+interface BehaviorProfile {
+    version: 1;
+    firstSeen: string;
+    sessionCount: number;
+    totalInteractions: number;
+    dismissCount: number;
+    clickCount: number;
+    completionCount: number;
+    formatPrefs: {
+        badge: number;
+        toast: number;
+        modal: number;
+        inline: number;
+        banner: number;
+        spotlight: number;
+    };
+    /** 24-element array, interaction count per hour */
+    hourlyActivity: number[];
+    /** Last 20 dismissed feature IDs (circular buffer) */
+    recentDismissals: string[];
+    /** Per-feature interaction data */
+    featureInteractions: Record<string, {
+        seen: number;
+        clicked: number;
+        dismissed: number;
+        completed: number;
+        lastInteraction: string;
+    }>;
+}
+declare class BehaviorTracker {
+    private profile;
+    private sessionStartTime;
+    constructor();
+    /** Track a feature interaction */
+    trackInteraction(featureId: string, type: InteractionType): void;
+    /** Record a format engagement (user interacted via this format) */
+    trackFormatEngagement(format: keyof BehaviorProfile["formatPrefs"]): void;
+    /** Get current profile */
+    getProfile(): Readonly<BehaviorProfile>;
+    /** Session count */
+    getSessionCount(): number;
+    /** Average session duration (rough estimate based on current session) */
+    getSessionAge(): number;
+    /** Dismiss rate (0-1) */
+    getDismissRate(): number;
+    /** Engagement rate (clicked or completed / total interactions) */
+    getEngagementRate(): number;
+    /** Preferred format based on highest engagement count */
+    getPreferredFormat(): keyof BehaviorProfile["formatPrefs"];
+    /** Top 3 active hours (0-23) */
+    getActiveHours(): number[];
+    /** Recent dismissals (last N feature IDs) */
+    getRecentDismissals(): string[];
+    /** Count of dismissals in last N milliseconds */
+    getRecentDismissalCount(windowMs: number): number;
+    /** Get interaction data for a specific feature */
+    getFeatureInteractions(featureId: string): {
+        seen: number;
+        clicked: number;
+        dismissed: number;
+        completed: number;
+        lastInteraction: string;
+    };
+    /** Clear all behavior data */
+    clearProfile(): void;
+    private load;
+    private save;
+}
+
+interface TimingOptimizerConfig {
+    /** Minimum session age in ms before showing anything (default: 10000) */
+    sessionGateMs: number;
+    /** Max dismissals in the backoff window before backing off (default: 2) */
+    maxDismissalsBeforeBackoff: number;
+    /** Backoff window in ms to count recent dismissals (default: 180000 = 3 min) */
+    dismissBackoffWindowMs: number;
+    /** Cooldown between announcements in ms (default: 60000) */
+    cooldownMs: number;
+    /** Path patterns to exclude (glob-style simple matching) */
+    excludePaths: string[];
+}
+declare class TimingOptimizer {
+    private config;
+    private tracker;
+    private lastAnnouncementTime;
+    constructor(tracker: BehaviorTracker, config?: Partial<TimingOptimizerConfig>);
+    /** Decide whether to show a feature announcement now */
+    shouldShowNow(_featureId: string, context: DeliveryContext): TimingDecision;
+    /** Mark that an announcement was shown (for cooldown tracking) */
+    recordAnnouncementShown(): void;
+    private isExcludedPath;
+}
+
+declare class FormatSelector {
+    private tracker;
+    constructor(tracker: BehaviorTracker);
+    /** Recommend the best display format for a feature */
+    recommendFormat(featureId: string, priority: FeaturePriority): FormatRecommendation;
+    private getBestFormat;
+    private getFallbackFormat;
+}
+
+declare class AdoptionScorer {
+    private tracker;
+    constructor(tracker: BehaviorTracker);
+    /** Calculate overall adoption score (0-100) */
+    getAdoptionScore(manifest: readonly FeatureEntry[]): AdoptionScore;
+    /** Get adoption status for a specific feature */
+    getFeatureAdoption(featureId: string): FeatureAdoptionStatus;
+    private toGrade;
+    private detectTrend;
+}
+
+/** Configuration for creating an AdoptionEngine */
+interface AdoptionEngineConfig {
+    /** Feature manifest (required for adoption scoring) */
+    manifest: readonly FeatureEntry[];
+    /** Timing optimizer settings */
+    timing?: Partial<TimingOptimizerConfig>;
+}
+/**
+ * Client-side behavioral intelligence engine for FeatureDrop.
+ *
+ * Tracks user interactions, optimizes announcement timing,
+ * recommends display formats, and scores feature adoption —
+ * all client-side with zero data transfer.
+ *
+ * @example
+ * ```ts
+ * import { createAdoptionEngine } from 'featuredrop/engine'
+ *
+ * const engine = createAdoptionEngine({
+ *   manifest: features,
+ *   timing: { cooldownMs: 30_000 },
+ * })
+ *
+ * <FeatureDropProvider manifest={features} engine={engine}>
+ *   <App />
+ * </FeatureDropProvider>
+ * ```
+ */
+declare class AdoptionEngine implements FeatureDropEngine {
+    private tracker;
+    private timing;
+    private format;
+    private scorer;
+    private manifest;
+    constructor(config: AdoptionEngineConfig);
+    /** Initialize the engine (called by FeatureDropProvider on mount) */
+    initialize(): void;
+    /** Cleanup resources (called by FeatureDropProvider on unmount) */
+    destroy(): void;
+    /** Decide whether to show a feature announcement now */
+    shouldShow(featureId: string, context: DeliveryContext): TimingDecision;
+    /** Recommend the best display format for a feature */
+    recommendFormat(featureId: string): FormatRecommendation;
+    /** Get the user's overall adoption score */
+    getAdoptionScore(): AdoptionScore;
+    /** Track a user interaction with a feature */
+    trackInteraction(featureId: string, type: InteractionType): void;
+    /** Get adoption status for a specific feature */
+    getFeatureAdoption(featureId: string): FeatureAdoptionStatus;
+    /** Access the behavior tracker for advanced usage */
+    getBehaviorTracker(): BehaviorTracker;
+    /** Clear all behavior data */
+    clearProfile(): void;
+    /** Update the manifest (e.g., if features change at runtime) */
+    updateManifest(manifest: readonly FeatureEntry[]): void;
+}
+/**
+ * Create a new AdoptionEngine instance.
+ *
+ * @example
+ * ```ts
+ * import { createAdoptionEngine } from 'featuredrop/engine'
+ *
+ * const engine = createAdoptionEngine({
+ *   manifest: features,
+ *   timing: {
+ *     cooldownMs: 30_000,
+ *     excludePaths: ['/checkout', '/login'],
+ *   },
+ * })
+ * ```
+ */
+declare function createAdoptionEngine(config: AdoptionEngineConfig): AdoptionEngine;
+
+export { AdoptionEngine, type AdoptionEngineConfig, AdoptionScorer, type BehaviorProfile, BehaviorTracker, FormatSelector, TimingOptimizer, type TimingOptimizerConfig, createAdoptionEngine };