featuredrop 1.4.0 → 2.1.0

package/dist/renderer.d.cts

@@ -0,0 +1,250 @@
+/** 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>;
+}
+/** User context for audience targeting */
+interface UserContext {
+    /** Current user's plan (e.g. "pro", "free") */
+    plan?: string;
+    /** Current user's role (e.g. "admin", "viewer") */
+    role?: string;
+    /** Current user's region (e.g. "us", "eu") */
+    region?: string;
+    /** Arbitrary traits for custom matching logic */
+    traits?: Record<string, unknown>;
+}
+/** Custom audience matcher function */
+type AudienceMatchFn = (audience: AudienceRule, userContext: UserContext) => boolean;
+/** Feature flag resolver interface for gating announcement visibility */
+interface FeatureFlagBridge {
+    isEnabled: (flagKey: string, userContext?: UserContext) => boolean;
+}
+/** 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 interaction state used to resolve dependency chains */
+interface FeatureDependencyState {
+    /** IDs marked as seen */
+    seenIds?: ReadonlySet<string>;
+    /** IDs marked as clicked */
+    clickedIds?: ReadonlySet<string>;
+    /** IDs marked as dismissed */
+    dismissedIds?: ReadonlySet<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;
+}
+/** The full feature manifest — an array of feature entries */
+type FeatureManifest = readonly FeatureEntry[];
+/**
+ * Storage adapter interface — implement for your persistence layer.
+ *
+ * The adapter bridges two data sources:
+ * - **Watermark**: a server-side timestamp ("features seen at")
+ * - **Dismissed IDs**: client-side per-feature dismissals
+ */
+interface StorageAdapter {
+    /** Get the user's "features seen at" watermark (ISO string or null) */
+    getWatermark(): string | null;
+    /** Get the set of individually dismissed feature IDs */
+    getDismissedIds(): ReadonlySet<string>;
+    /** Dismiss a single feature by ID */
+    dismiss(id: string): void;
+    /** Dismiss all features — sets watermark to `now` and clears dismissals */
+    dismissAll(now: Date): Promise<void>;
+}
+
+interface ChangelogRendererOptions {
+    manifest: FeatureManifest;
+    storage: StorageAdapter;
+    userContext?: UserContext;
+    matchAudience?: AudienceMatchFn;
+    appVersion?: string;
+    dependencyState?: FeatureDependencyState;
+    triggerContext?: TriggerContext;
+    flagBridge?: FeatureFlagBridge;
+    product?: string;
+    now?: () => Date;
+}
+interface ChangelogRendererState {
+    manifest: FeatureManifest;
+    newFeatures: FeatureEntry[];
+    newFeaturesSorted: FeatureEntry[];
+    newCount: number;
+    watermark: string | null;
+    dismissedIds: ReadonlySet<string>;
+    dependencyState: FeatureDependencyState;
+    triggerContext?: TriggerContext;
+}
+interface ChangelogRendererActions {
+    refresh: () => void;
+    dismiss: (id: string) => void;
+    dismissAll: () => Promise<void>;
+    setManifest: (manifest: FeatureManifest) => void;
+    setUserContext: (userContext?: UserContext) => void;
+    setAppVersion: (appVersion?: string) => void;
+    setAudienceMatcher: (matchAudience?: AudienceMatchFn) => void;
+    setDependencyState: (dependencyState?: FeatureDependencyState) => void;
+    markFeatureSeen: (featureId: string) => void;
+    markFeatureClicked: (featureId: string) => void;
+    setFlagBridge: (flagBridge?: FeatureFlagBridge) => void;
+    setTriggerContext: (triggerContext?: TriggerContext) => void;
+    setTriggerPath: (path: string) => void;
+    trackUsageEvent: (event: string, delta?: number) => void;
+    trackTriggerEvent: (event: string) => void;
+    trackMilestone: (event: string) => void;
+    setTriggerElapsedMs: (elapsedMs: number) => void;
+    setTriggerScrollPercent: (scrollPercent: number) => void;
+    setTriggerMetadata: (metadata: Record<string, unknown>) => void;
+    setProduct: (product?: string) => void;
+}
+interface ChangelogRendererComputed {
+    isNew: (sidebarKey: string) => boolean;
+    getFeature: (sidebarKey: string) => FeatureEntry | undefined;
+    getFeatureById: (id: string) => FeatureEntry | undefined;
+    getFeaturesByCategory: (category: string) => FeatureEntry[];
+}
+interface ChangelogRenderer {
+    readonly state: ChangelogRendererState;
+    readonly actions: ChangelogRendererActions;
+    readonly computed: ChangelogRendererComputed;
+    subscribe: (listener: (state: ChangelogRendererState) => void) => () => void;
+    destroy: () => void;
+}
+declare function createChangelogRenderer({ manifest: initialManifest, storage, userContext: initialUserContext, matchAudience: initialMatchAudience, appVersion: initialAppVersion, dependencyState: initialDependencyState, triggerContext: initialTriggerContext, flagBridge: initialFlagBridge, product: initialProduct, now, }: ChangelogRendererOptions): ChangelogRenderer;
+
+export { type ChangelogRenderer, type ChangelogRendererActions, type ChangelogRendererComputed, type ChangelogRendererOptions, type ChangelogRendererState, createChangelogRenderer };

package/dist/renderer.d.ts

@@ -0,0 +1,250 @@
+/** 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>;
+}
+/** User context for audience targeting */
+interface UserContext {
+    /** Current user's plan (e.g. "pro", "free") */
+    plan?: string;
+    /** Current user's role (e.g. "admin", "viewer") */
+    role?: string;
+    /** Current user's region (e.g. "us", "eu") */
+    region?: string;
+    /** Arbitrary traits for custom matching logic */
+    traits?: Record<string, unknown>;
+}
+/** Custom audience matcher function */
+type AudienceMatchFn = (audience: AudienceRule, userContext: UserContext) => boolean;
+/** Feature flag resolver interface for gating announcement visibility */
+interface FeatureFlagBridge {
+    isEnabled: (flagKey: string, userContext?: UserContext) => boolean;
+}
+/** 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 interaction state used to resolve dependency chains */
+interface FeatureDependencyState {
+    /** IDs marked as seen */
+    seenIds?: ReadonlySet<string>;
+    /** IDs marked as clicked */
+    clickedIds?: ReadonlySet<string>;
+    /** IDs marked as dismissed */
+    dismissedIds?: ReadonlySet<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;
+}
+/** The full feature manifest — an array of feature entries */
+type FeatureManifest = readonly FeatureEntry[];
+/**
+ * Storage adapter interface — implement for your persistence layer.
+ *
+ * The adapter bridges two data sources:
+ * - **Watermark**: a server-side timestamp ("features seen at")
+ * - **Dismissed IDs**: client-side per-feature dismissals
+ */
+interface StorageAdapter {
+    /** Get the user's "features seen at" watermark (ISO string or null) */
+    getWatermark(): string | null;
+    /** Get the set of individually dismissed feature IDs */
+    getDismissedIds(): ReadonlySet<string>;
+    /** Dismiss a single feature by ID */
+    dismiss(id: string): void;
+    /** Dismiss all features — sets watermark to `now` and clears dismissals */
+    dismissAll(now: Date): Promise<void>;
+}
+
+interface ChangelogRendererOptions {
+    manifest: FeatureManifest;
+    storage: StorageAdapter;
+    userContext?: UserContext;
+    matchAudience?: AudienceMatchFn;
+    appVersion?: string;
+    dependencyState?: FeatureDependencyState;
+    triggerContext?: TriggerContext;
+    flagBridge?: FeatureFlagBridge;
+    product?: string;
+    now?: () => Date;
+}
+interface ChangelogRendererState {
+    manifest: FeatureManifest;
+    newFeatures: FeatureEntry[];
+    newFeaturesSorted: FeatureEntry[];
+    newCount: number;
+    watermark: string | null;
+    dismissedIds: ReadonlySet<string>;
+    dependencyState: FeatureDependencyState;
+    triggerContext?: TriggerContext;
+}
+interface ChangelogRendererActions {
+    refresh: () => void;
+    dismiss: (id: string) => void;
+    dismissAll: () => Promise<void>;
+    setManifest: (manifest: FeatureManifest) => void;
+    setUserContext: (userContext?: UserContext) => void;
+    setAppVersion: (appVersion?: string) => void;
+    setAudienceMatcher: (matchAudience?: AudienceMatchFn) => void;
+    setDependencyState: (dependencyState?: FeatureDependencyState) => void;
+    markFeatureSeen: (featureId: string) => void;
+    markFeatureClicked: (featureId: string) => void;
+    setFlagBridge: (flagBridge?: FeatureFlagBridge) => void;
+    setTriggerContext: (triggerContext?: TriggerContext) => void;
+    setTriggerPath: (path: string) => void;
+    trackUsageEvent: (event: string, delta?: number) => void;
+    trackTriggerEvent: (event: string) => void;
+    trackMilestone: (event: string) => void;
+    setTriggerElapsedMs: (elapsedMs: number) => void;
+    setTriggerScrollPercent: (scrollPercent: number) => void;
+    setTriggerMetadata: (metadata: Record<string, unknown>) => void;
+    setProduct: (product?: string) => void;
+}
+interface ChangelogRendererComputed {
+    isNew: (sidebarKey: string) => boolean;
+    getFeature: (sidebarKey: string) => FeatureEntry | undefined;
+    getFeatureById: (id: string) => FeatureEntry | undefined;
+    getFeaturesByCategory: (category: string) => FeatureEntry[];
+}
+interface ChangelogRenderer {
+    readonly state: ChangelogRendererState;
+    readonly actions: ChangelogRendererActions;
+    readonly computed: ChangelogRendererComputed;
+    subscribe: (listener: (state: ChangelogRendererState) => void) => () => void;
+    destroy: () => void;
+}
+declare function createChangelogRenderer({ manifest: initialManifest, storage, userContext: initialUserContext, matchAudience: initialMatchAudience, appVersion: initialAppVersion, dependencyState: initialDependencyState, triggerContext: initialTriggerContext, flagBridge: initialFlagBridge, product: initialProduct, now, }: ChangelogRendererOptions): ChangelogRenderer;
+
+export { type ChangelogRenderer, type ChangelogRendererActions, type ChangelogRendererComputed, type ChangelogRendererOptions, type ChangelogRendererState, createChangelogRenderer };