featuredrop 2.6.1 → 2.7.1

package/dist/react.d.cts

@@ -199,6 +199,94 @@ interface AnalyticsCallbacks {
     /** Fired when all features are dismissed at once */
     onAllDismissed?: () => void;
 }
+/** 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;
+}
 
 interface ThrottleOptions {
     maxSimultaneousBadges?: number;
@@ -340,6 +428,8 @@ interface FeatureDropProviderProps {
     animation?: FeatureDropAnimationPreset;
     /** Custom translation overrides for built-in component strings */
     translations?: Partial<FeatureDropTranslations>;
+    /** Optional engine for AI-powered delivery intelligence (@featuredrop/engine) */
+    engine?: FeatureDropEngine;
     children: ReactNode;
 }
 /**
@@ -348,7 +438,7 @@ interface FeatureDropProviderProps {
  * Wrap your app (or a subtree) with this provider to enable
  * `useFeatureDrop`, `useNewFeature`, `useNewCount`, and other hooks.
  */
-declare function FeatureDropProvider({ manifest, storage, analytics, onError, userContext, matchAudience: matchAudienceFn, appVersion, product, throttle, variantKey, collector, flagBridge, locale, animation, translations: translationOverrides, children, }: FeatureDropProviderProps): react_jsx_runtime.JSX.Element;
+declare function FeatureDropProvider({ manifest, storage, analytics, onError, userContext, matchAudience: matchAudienceFn, appVersion, product, throttle, variantKey, collector, flagBridge, locale, animation, translations: translationOverrides, engine, children, }: FeatureDropProviderProps): react_jsx_runtime.JSX.Element;
 
 interface FeatureDropTheme {
     colors: {
@@ -483,6 +573,8 @@ interface FeatureDropContextValue {
     trackMilestone: (event: string) => void;
     /** Manually override current path for page trigger rules */
     setTriggerPath: (path: string) => void;
+    /** Optional engine instance for AI-powered delivery intelligence */
+    engine: FeatureDropEngine | null;
 }
 declare const FeatureDropContext: react.Context<FeatureDropContextValue | null>;
 

package/dist/react.d.ts

@@ -199,6 +199,94 @@ interface AnalyticsCallbacks {
     /** Fired when all features are dismissed at once */
     onAllDismissed?: () => void;
 }
+/** 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;
+}
 
 interface ThrottleOptions {
     maxSimultaneousBadges?: number;
@@ -340,6 +428,8 @@ interface FeatureDropProviderProps {
     animation?: FeatureDropAnimationPreset;
     /** Custom translation overrides for built-in component strings */
     translations?: Partial<FeatureDropTranslations>;
+    /** Optional engine for AI-powered delivery intelligence (@featuredrop/engine) */
+    engine?: FeatureDropEngine;
     children: ReactNode;
 }
 /**
@@ -348,7 +438,7 @@ interface FeatureDropProviderProps {
  * Wrap your app (or a subtree) with this provider to enable
  * `useFeatureDrop`, `useNewFeature`, `useNewCount`, and other hooks.
  */
-declare function FeatureDropProvider({ manifest, storage, analytics, onError, userContext, matchAudience: matchAudienceFn, appVersion, product, throttle, variantKey, collector, flagBridge, locale, animation, translations: translationOverrides, children, }: FeatureDropProviderProps): react_jsx_runtime.JSX.Element;
+declare function FeatureDropProvider({ manifest, storage, analytics, onError, userContext, matchAudience: matchAudienceFn, appVersion, product, throttle, variantKey, collector, flagBridge, locale, animation, translations: translationOverrides, engine, children, }: FeatureDropProviderProps): react_jsx_runtime.JSX.Element;
 
 interface FeatureDropTheme {
     colors: {
@@ -483,6 +573,8 @@ interface FeatureDropContextValue {
     trackMilestone: (event: string) => void;
     /** Manually override current path for page trigger rules */
     setTriggerPath: (path: string) => void;
+    /** Optional engine instance for AI-powered delivery intelligence */
+    engine: FeatureDropEngine | null;
 }
 declare const FeatureDropContext: react.Context<FeatureDropContextValue | null>;
 

package/dist/react.js

@@ -1077,6 +1077,7 @@ function FeatureDropProvider({
   locale = "en",
   animation = "normal",
   translations: translationOverrides,
+  engine,
   children
 }) {
   const analyticsRef = useRef(analytics);
@@ -1133,20 +1134,20 @@ function FeatureDropProvider({
       seenFeatureIds: readIdSet(SEEN_FEATURES_STORAGE_KEY),
       clickedFeatureIds: readIdSet(CLICKED_FEATURES_STORAGE_KEY),
       triggerContext: (() => {
-        const engine = triggerEngineRef.current;
-        if (!engine) return void 0;
-        engine.setElapsedMs(Date.now() - sessionStartedAtRef.current);
-        return engine.getContext();
+        const engine2 = triggerEngineRef.current;
+        if (!engine2) return void 0;
+        engine2.setElapsedMs(Date.now() - sessionStartedAtRef.current);
+        return engine2.getContext();
       })(),
       flagBridge
     })
   );
   const recompute = useCallback(() => {
-    const engine = triggerEngineRef.current;
+    const engine2 = triggerEngineRef.current;
     let triggerContext;
-    if (engine) {
-      engine.setElapsedMs(Date.now() - sessionStartedAtRef.current);
-      triggerContext = engine.getContext();
+    if (engine2) {
+      engine2.setElapsedMs(Date.now() - sessionStartedAtRef.current);
+      triggerContext = engine2.getContext();
     }
     setFeatureState(
       computeFeatureState({
@@ -1183,6 +1184,12 @@ function FeatureDropProvider({
   useEffect(() => {
     recompute();
   }, [recompute]);
+  useEffect(() => {
+    engine?.initialize?.();
+    return () => {
+      engine?.destroy?.();
+    };
+  }, [engine]);
   const hasTimeTriggers = useMemo(
     () => resolvedManifest.some((feature) => feature.trigger?.type === "time"),
     [resolvedManifest]
@@ -1465,7 +1472,8 @@ function FeatureDropProvider({
       trackUsageEvent,
       trackTriggerEvent,
       trackMilestone,
-      setTriggerPath
+      setTriggerPath,
+      engine: engine ?? null
     }),
     [
       resolvedManifest,
@@ -1499,7 +1507,8 @@ function FeatureDropProvider({
       trackUsageEvent,
       trackTriggerEvent,
       trackMilestone,
-      setTriggerPath
+      setTriggerPath,
+      engine
     ]
   );
   return /* @__PURE__ */ jsx(FeatureDropContext.Provider, { value, children });