featuredrop 2.7.1 → 3.0.1

package/dist/nuxt.d.cts

@@ -0,0 +1,282 @@
+/** 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[];
+
+/** Options shared by server helpers */
+interface ServerOptions {
+    /** Current date override (defaults to `new Date()`) */
+    now?: Date;
+    /** User context for audience targeting */
+    userContext?: UserContext;
+    /** Custom audience matcher */
+    matchAudience?: AudienceMatchFn;
+    /** Current app semver string for version targeting */
+    appVersion?: string;
+    /** Dependency state for progressive disclosure */
+    dependencyState?: FeatureDependencyState;
+    /** Trigger context for contextual rules */
+    triggerContext?: TriggerContext;
+    /** Feature flag bridge for flag-gated entries */
+    flagBridge?: FeatureFlagBridge;
+    /** Product scope for multi-product manifests */
+    product?: string;
+}
+/**
+ * Server-safe helper: get new features without browser storage.
+ *
+ * Creates a temporary MemoryAdapter pre-seeded with the provided dismissed IDs
+ * and calls the core `getNewFeatures` function. Safe to use in Nuxt server
+ * routes, `useAsyncData`, or `useFetch` server-side handlers.
+ *
+ * @param manifest     The feature manifest array.
+ * @param dismissedIds IDs already dismissed by this user (from your session/DB).
+ * @param options      Optional targeting overrides.
+ */
+declare function getNewFeaturesServer(manifest: FeatureManifest, dismissedIds?: string[], options?: ServerOptions): FeatureEntry[];
+/**
+ * Server-safe helper: get new feature count.
+ *
+ * Same as `getNewFeaturesServer` but returns the count only. Useful when you
+ * only need the badge number and want to avoid serialising the full manifest.
+ *
+ * @param manifest     The feature manifest array.
+ * @param dismissedIds IDs already dismissed by this user (from your session/DB).
+ * @param options      Optional targeting overrides.
+ */
+declare function getNewCountServer(manifest: FeatureManifest, dismissedIds?: string[], options?: ServerOptions): number;
+/**
+ * Factory that returns a Nitro event handler for a `/api/features` endpoint.
+ *
+ * The `event` parameter is typed as `unknown` to avoid a hard dependency on
+ * `h3` / Nitro — cast it inside `getDismissedIds` to the concrete event type
+ * your Nuxt version uses.
+ *
+ * Usage in `server/api/features.get.ts`:
+ * ```ts
+ * import { defineFeatureDropEventHandler } from "featuredrop/nuxt";
+ * import { manifest } from "~/features/manifest";
+ *
+ * export default defineFeatureDropEventHandler(
+ *   () => manifest,
+ *   (event) => {
+ *     // pull dismissed IDs from session, cookie, or DB
+ *     return useSession(event).dismissed ?? [];
+ *   },
+ * );
+ * ```
+ *
+ * @param getManifest     Returns (or resolves to) the feature manifest.
+ * @param getDismissedIds Optional. Receives the Nitro event and returns the
+ *                        dismissed feature IDs for the current user.
+ */
+declare function defineFeatureDropEventHandler(getManifest: () => FeatureEntry[] | Promise<FeatureEntry[]>, getDismissedIds?: (event: unknown) => string[] | Promise<string[]>): (event: unknown) => Promise<{
+    manifest: FeatureEntry[];
+    newFeatures: FeatureEntry[];
+    newCount: number;
+}>;
+/**
+ * Returns an object suitable for Nuxt's `useHead()` that injects the manifest
+ * and dismissed IDs as an inline JSON script tag.
+ *
+ * This allows the client-side Vue composables (from `featuredrop/vue`) to
+ * read server-resolved data on first render, eliminating the flash where
+ * the new-feature count momentarily appears as zero.
+ *
+ * Usage in a page or layout:
+ * ```ts
+ * import { getHeadScript } from "featuredrop/nuxt";
+ * import { manifest } from "~/features/manifest";
+ *
+ * const { data } = await useAsyncData("features", () =>
+ *   $fetch("/api/features"),
+ * );
+ * useHead(getHeadScript(manifest, data.value?.dismissed));
+ * ```
+ *
+ * Client-side retrieval:
+ * ```ts
+ * const el = document.getElementById("__FEATUREDROP_DATA__");
+ * const { manifest, dismissedIds } = JSON.parse(el?.textContent ?? "{}");
+ * ```
+ *
+ * @param manifest     The feature manifest array.
+ * @param dismissedIds IDs already dismissed by this user.
+ */
+declare function getHeadScript(manifest: FeatureEntry[], dismissedIds?: string[]): {
+    script: Array<{
+        id: string;
+        type: string;
+        innerHTML: string;
+    }>;
+};
+
+export { type AudienceMatchFn, type FeatureDependencyState, type FeatureEntry, type FeatureFlagBridge, type FeatureManifest, type ServerOptions, type TriggerContext, type UserContext, defineFeatureDropEventHandler, getHeadScript, getNewCountServer, getNewFeaturesServer };

package/dist/nuxt.d.ts

@@ -0,0 +1,282 @@
+/** 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[];
+
+/** Options shared by server helpers */
+interface ServerOptions {
+    /** Current date override (defaults to `new Date()`) */
+    now?: Date;
+    /** User context for audience targeting */
+    userContext?: UserContext;
+    /** Custom audience matcher */
+    matchAudience?: AudienceMatchFn;
+    /** Current app semver string for version targeting */
+    appVersion?: string;
+    /** Dependency state for progressive disclosure */
+    dependencyState?: FeatureDependencyState;
+    /** Trigger context for contextual rules */
+    triggerContext?: TriggerContext;
+    /** Feature flag bridge for flag-gated entries */
+    flagBridge?: FeatureFlagBridge;
+    /** Product scope for multi-product manifests */
+    product?: string;
+}
+/**
+ * Server-safe helper: get new features without browser storage.
+ *
+ * Creates a temporary MemoryAdapter pre-seeded with the provided dismissed IDs
+ * and calls the core `getNewFeatures` function. Safe to use in Nuxt server
+ * routes, `useAsyncData`, or `useFetch` server-side handlers.
+ *
+ * @param manifest     The feature manifest array.
+ * @param dismissedIds IDs already dismissed by this user (from your session/DB).
+ * @param options      Optional targeting overrides.
+ */
+declare function getNewFeaturesServer(manifest: FeatureManifest, dismissedIds?: string[], options?: ServerOptions): FeatureEntry[];
+/**
+ * Server-safe helper: get new feature count.
+ *
+ * Same as `getNewFeaturesServer` but returns the count only. Useful when you
+ * only need the badge number and want to avoid serialising the full manifest.
+ *
+ * @param manifest     The feature manifest array.
+ * @param dismissedIds IDs already dismissed by this user (from your session/DB).
+ * @param options      Optional targeting overrides.
+ */
+declare function getNewCountServer(manifest: FeatureManifest, dismissedIds?: string[], options?: ServerOptions): number;
+/**
+ * Factory that returns a Nitro event handler for a `/api/features` endpoint.
+ *
+ * The `event` parameter is typed as `unknown` to avoid a hard dependency on
+ * `h3` / Nitro — cast it inside `getDismissedIds` to the concrete event type
+ * your Nuxt version uses.
+ *
+ * Usage in `server/api/features.get.ts`:
+ * ```ts
+ * import { defineFeatureDropEventHandler } from "featuredrop/nuxt";
+ * import { manifest } from "~/features/manifest";
+ *
+ * export default defineFeatureDropEventHandler(
+ *   () => manifest,
+ *   (event) => {
+ *     // pull dismissed IDs from session, cookie, or DB
+ *     return useSession(event).dismissed ?? [];
+ *   },
+ * );
+ * ```
+ *
+ * @param getManifest     Returns (or resolves to) the feature manifest.
+ * @param getDismissedIds Optional. Receives the Nitro event and returns the
+ *                        dismissed feature IDs for the current user.
+ */
+declare function defineFeatureDropEventHandler(getManifest: () => FeatureEntry[] | Promise<FeatureEntry[]>, getDismissedIds?: (event: unknown) => string[] | Promise<string[]>): (event: unknown) => Promise<{
+    manifest: FeatureEntry[];
+    newFeatures: FeatureEntry[];
+    newCount: number;
+}>;
+/**
+ * Returns an object suitable for Nuxt's `useHead()` that injects the manifest
+ * and dismissed IDs as an inline JSON script tag.
+ *
+ * This allows the client-side Vue composables (from `featuredrop/vue`) to
+ * read server-resolved data on first render, eliminating the flash where
+ * the new-feature count momentarily appears as zero.
+ *
+ * Usage in a page or layout:
+ * ```ts
+ * import { getHeadScript } from "featuredrop/nuxt";
+ * import { manifest } from "~/features/manifest";
+ *
+ * const { data } = await useAsyncData("features", () =>
+ *   $fetch("/api/features"),
+ * );
+ * useHead(getHeadScript(manifest, data.value?.dismissed));
+ * ```
+ *
+ * Client-side retrieval:
+ * ```ts
+ * const el = document.getElementById("__FEATUREDROP_DATA__");
+ * const { manifest, dismissedIds } = JSON.parse(el?.textContent ?? "{}");
+ * ```
+ *
+ * @param manifest     The feature manifest array.
+ * @param dismissedIds IDs already dismissed by this user.
+ */
+declare function getHeadScript(manifest: FeatureEntry[], dismissedIds?: string[]): {
+    script: Array<{
+        id: string;
+        type: string;
+        innerHTML: string;
+    }>;
+};
+
+export { type AudienceMatchFn, type FeatureDependencyState, type FeatureEntry, type FeatureFlagBridge, type FeatureManifest, type ServerOptions, type TriggerContext, type UserContext, defineFeatureDropEventHandler, getHeadScript, getNewCountServer, getNewFeaturesServer };