featuredrop 2.7.2 → 3.0.1

package/dist/remix.d.cts

@@ -0,0 +1,305 @@
+/** 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[];
+
+/**
+ * featuredrop — Remix integration
+ *
+ * Server-side loader helpers for computing new feature state from session data.
+ *
+ * Typical usage in a Remix loader:
+ *
+ * ```ts
+ * import { getNewFeaturesServer, createFeatureDropHeaders } from "featuredrop/remix";
+ * import { manifest } from "~/features/manifest";
+ *
+ * export async function loader({ request }: LoaderFunctionArgs) {
+ *   const session = await getSession(request.headers.get("Cookie"));
+ *   const dismissedIds: string[] = session.get("fd_dismissed") ?? [];
+ *
+ *   const newFeatures = getNewFeaturesServer(manifest, dismissedIds);
+ *   const headers = createFeatureDropHeaders(manifest, dismissedIds);
+ *
+ *   return json({ newFeatures }, { headers });
+ * }
+ * ```
+ *
+ * All helpers are pure functions — they create a transient MemoryAdapter
+ * internally so there are no shared global state concerns between requests.
+ */
+
+/**
+ * Options bag for server-side newness checks.
+ *
+ * Mirrors the optional parameters of the core `getNewFeatures` function.
+ * All fields are optional — omit what you don't use.
+ */
+interface IsNewOptions {
+    /** Override the current timestamp (defaults to `new Date()`). */
+    now?: Date;
+    /**
+     * User context for audience targeting rules.
+     * Required when any manifest entry has an `audience` field.
+     */
+    userContext?: UserContext;
+    /**
+     * Custom audience matching function.
+     * Replaces the built-in plan/role/region matcher when provided.
+     */
+    matchAudience?: AudienceMatchFn;
+    /**
+     * Current app version string (e.g. `"2.5.0"`).
+     * Required when any manifest entry uses semver `version` constraints.
+     */
+    appVersion?: string;
+    /** Runtime dependency state for progressive feature discovery. */
+    dependencyState?: FeatureDependencyState;
+    /**
+     * Trigger context for contextual display rules.
+     * On the server you typically omit this (triggers are client-side).
+     */
+    triggerContext?: TriggerContext;
+    /** Feature flag bridge for evaluating `flagKey` entries. */
+    flagBridge?: FeatureFlagBridge;
+    /**
+     * Product scope filter.
+     * Use when your manifest covers multiple products and you want to
+     * surface only entries for the current product.
+     */
+    product?: string;
+}
+/**
+ * Return all features that are currently "new" for the given user.
+ *
+ * Creates a short-lived `MemoryAdapter` seeded with the provided
+ * `dismissedIds`, then delegates to `getNewFeatures` from core.
+ *
+ * @param manifest   The full feature manifest.
+ * @param dismissedIds  IDs the user has already dismissed (from session/DB).
+ * @param options    Optional targeting overrides.
+ * @returns          Array of `FeatureEntry` objects considered new.
+ *
+ * @example
+ * ```ts
+ * // In a Remix loader
+ * const dismissed: string[] = session.get("fd_dismissed") ?? [];
+ * const newFeatures = getNewFeaturesServer(manifest, dismissed, {
+ *   userContext: { plan: "pro" },
+ * });
+ * return json({ newFeatures });
+ * ```
+ */
+declare function getNewFeaturesServer(manifest: FeatureManifest, dismissedIds?: readonly string[], options?: IsNewOptions): FeatureEntry[];
+/**
+ * Return the count of features that are currently "new" for the given user.
+ *
+ * Lightweight alternative to `getNewFeaturesServer` when you only need the
+ * number — avoids allocating the full result array on the caller's side.
+ *
+ * @param manifest     The full feature manifest.
+ * @param dismissedIds IDs the user has already dismissed.
+ * @param options      Optional targeting overrides.
+ * @returns            Integer count of new features.
+ *
+ * @example
+ * ```ts
+ * const count = getNewCountServer(manifest, session.get("fd_dismissed") ?? []);
+ * // Pass count to the client as a header or in the JSON payload
+ * ```
+ */
+declare function getNewCountServer(manifest: FeatureManifest, dismissedIds?: readonly string[], options?: IsNewOptions): number;
+/**
+ * Build a `Headers` object carrying the new-feature count.
+ *
+ * Useful when you want the client to know about the badge count without
+ * serialising the entire feature list into the JSON response body.
+ *
+ * The header `X-FD-New-Count` is set to the string representation of the
+ * count. Clients can read it via `useFetcher` or a custom hook.
+ *
+ * @param manifest     The full feature manifest.
+ * @param dismissedIds IDs the user has already dismissed.
+ * @param options      Optional targeting overrides.
+ * @returns            A `Headers` instance with `X-FD-New-Count` set.
+ *
+ * @example
+ * ```ts
+ * export async function loader({ request }: LoaderFunctionArgs) {
+ *   const dismissed: string[] = session.get("fd_dismissed") ?? [];
+ *   const headers = createFeatureDropHeaders(manifest, dismissed);
+ *   return json({ ok: true }, { headers });
+ * }
+ * ```
+ */
+declare function createFeatureDropHeaders(manifest: FeatureManifest, dismissedIds?: readonly string[], options?: IsNewOptions): Headers;
+
+export { type FeatureEntry, type FeatureManifest, type IsNewOptions, createFeatureDropHeaders, getNewCountServer, getNewFeaturesServer };

package/dist/remix.d.ts

@@ -0,0 +1,305 @@
+/** 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[];
+
+/**
+ * featuredrop — Remix integration
+ *
+ * Server-side loader helpers for computing new feature state from session data.
+ *
+ * Typical usage in a Remix loader:
+ *
+ * ```ts
+ * import { getNewFeaturesServer, createFeatureDropHeaders } from "featuredrop/remix";
+ * import { manifest } from "~/features/manifest";
+ *
+ * export async function loader({ request }: LoaderFunctionArgs) {
+ *   const session = await getSession(request.headers.get("Cookie"));
+ *   const dismissedIds: string[] = session.get("fd_dismissed") ?? [];
+ *
+ *   const newFeatures = getNewFeaturesServer(manifest, dismissedIds);
+ *   const headers = createFeatureDropHeaders(manifest, dismissedIds);
+ *
+ *   return json({ newFeatures }, { headers });
+ * }
+ * ```
+ *
+ * All helpers are pure functions — they create a transient MemoryAdapter
+ * internally so there are no shared global state concerns between requests.
+ */
+
+/**
+ * Options bag for server-side newness checks.
+ *
+ * Mirrors the optional parameters of the core `getNewFeatures` function.
+ * All fields are optional — omit what you don't use.
+ */
+interface IsNewOptions {
+    /** Override the current timestamp (defaults to `new Date()`). */
+    now?: Date;
+    /**
+     * User context for audience targeting rules.
+     * Required when any manifest entry has an `audience` field.
+     */
+    userContext?: UserContext;
+    /**
+     * Custom audience matching function.
+     * Replaces the built-in plan/role/region matcher when provided.
+     */
+    matchAudience?: AudienceMatchFn;
+    /**
+     * Current app version string (e.g. `"2.5.0"`).
+     * Required when any manifest entry uses semver `version` constraints.
+     */
+    appVersion?: string;
+    /** Runtime dependency state for progressive feature discovery. */
+    dependencyState?: FeatureDependencyState;
+    /**
+     * Trigger context for contextual display rules.
+     * On the server you typically omit this (triggers are client-side).
+     */
+    triggerContext?: TriggerContext;
+    /** Feature flag bridge for evaluating `flagKey` entries. */
+    flagBridge?: FeatureFlagBridge;
+    /**
+     * Product scope filter.
+     * Use when your manifest covers multiple products and you want to
+     * surface only entries for the current product.
+     */
+    product?: string;
+}
+/**
+ * Return all features that are currently "new" for the given user.
+ *
+ * Creates a short-lived `MemoryAdapter` seeded with the provided
+ * `dismissedIds`, then delegates to `getNewFeatures` from core.
+ *
+ * @param manifest   The full feature manifest.
+ * @param dismissedIds  IDs the user has already dismissed (from session/DB).
+ * @param options    Optional targeting overrides.
+ * @returns          Array of `FeatureEntry` objects considered new.
+ *
+ * @example
+ * ```ts
+ * // In a Remix loader
+ * const dismissed: string[] = session.get("fd_dismissed") ?? [];
+ * const newFeatures = getNewFeaturesServer(manifest, dismissed, {
+ *   userContext: { plan: "pro" },
+ * });
+ * return json({ newFeatures });
+ * ```
+ */
+declare function getNewFeaturesServer(manifest: FeatureManifest, dismissedIds?: readonly string[], options?: IsNewOptions): FeatureEntry[];
+/**
+ * Return the count of features that are currently "new" for the given user.
+ *
+ * Lightweight alternative to `getNewFeaturesServer` when you only need the
+ * number — avoids allocating the full result array on the caller's side.
+ *
+ * @param manifest     The full feature manifest.
+ * @param dismissedIds IDs the user has already dismissed.
+ * @param options      Optional targeting overrides.
+ * @returns            Integer count of new features.
+ *
+ * @example
+ * ```ts
+ * const count = getNewCountServer(manifest, session.get("fd_dismissed") ?? []);
+ * // Pass count to the client as a header or in the JSON payload
+ * ```
+ */
+declare function getNewCountServer(manifest: FeatureManifest, dismissedIds?: readonly string[], options?: IsNewOptions): number;
+/**
+ * Build a `Headers` object carrying the new-feature count.
+ *
+ * Useful when you want the client to know about the badge count without
+ * serialising the entire feature list into the JSON response body.
+ *
+ * The header `X-FD-New-Count` is set to the string representation of the
+ * count. Clients can read it via `useFetcher` or a custom hook.
+ *
+ * @param manifest     The full feature manifest.
+ * @param dismissedIds IDs the user has already dismissed.
+ * @param options      Optional targeting overrides.
+ * @returns            A `Headers` instance with `X-FD-New-Count` set.
+ *
+ * @example
+ * ```ts
+ * export async function loader({ request }: LoaderFunctionArgs) {
+ *   const dismissed: string[] = session.get("fd_dismissed") ?? [];
+ *   const headers = createFeatureDropHeaders(manifest, dismissed);
+ *   return json({ ok: true }, { headers });
+ * }
+ * ```
+ */
+declare function createFeatureDropHeaders(manifest: FeatureManifest, dismissedIds?: readonly string[], options?: IsNewOptions): Headers;
+
+export { type FeatureEntry, type FeatureManifest, type IsNewOptions, createFeatureDropHeaders, getNewCountServer, getNewFeaturesServer };