featuredrop 1.4.0 → 2.2.0

package/dist/adapters.d.cts

@@ -0,0 +1,744 @@
+/** 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;
+}
+/** 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>;
+}
+/** Extended server-side dismissal state */
+interface DismissalState {
+    /** Server-side watermark */
+    watermark: string | null;
+    /** Dismissed feature IDs */
+    dismissedIds: string[];
+    /** ISO timestamp of last interaction */
+    lastSeen: string;
+    /** Estimated device count contributing to this state */
+    deviceCount: number;
+}
+/** Server-capable storage adapter */
+interface ServerStorageAdapter extends StorageAdapter {
+    /** Current user for this adapter instance */
+    userId: string;
+    /** Pull latest state from the server/database */
+    sync(): Promise<void>;
+    /** Dismiss multiple features at once */
+    dismissBatch(ids: string[]): Promise<void>;
+    /** Reset state for a target user */
+    resetUser(userId: string): Promise<void>;
+    /** Fetch multiple users' state */
+    getBulkState(userIds: string[]): Promise<Map<string, DismissalState>>;
+    /** Health check */
+    isHealthy(): Promise<boolean>;
+    /** Cleanup resources */
+    destroy(): Promise<void>;
+}
+
+interface LocalStorageAdapterOptions {
+    /** Key prefix for localStorage entries. Default: "featuredrop" */
+    prefix?: string;
+    /** Server-side watermark (ISO string). Typically from user profile. */
+    watermark?: string | null;
+    /** Callback when dismissAll is called. Use for server-side watermark updates. */
+    onDismissAll?: (now: Date) => Promise<void>;
+}
+/**
+ * localStorage-based storage adapter.
+ *
+ * Architecture:
+ * - **Watermark** comes from the server (passed at construction time)
+ * - **Per-feature dismissals** are stored in localStorage (zero server writes)
+ * - **dismissAll()** optionally calls a server callback, then clears localStorage
+ *
+ * Gracefully handles SSR environments where `window`/`localStorage` is unavailable.
+ */
+declare class LocalStorageAdapter implements StorageAdapter {
+    private readonly prefix;
+    private readonly watermarkValue;
+    private readonly onDismissAllCallback?;
+    private readonly dismissedKey;
+    constructor(options?: LocalStorageAdapterOptions);
+    getWatermark(): string | null;
+    getDismissedIds(): ReadonlySet<string>;
+    dismiss(id: string): void;
+    dismissAll(now: Date): Promise<void>;
+}
+
+interface IndexedDBAdapterOptions {
+    prefix?: string;
+    watermark?: string | null;
+    dbName?: string;
+    storeName?: string;
+    onDismissAll?: (now: Date) => Promise<void>;
+    /** Optional remote state fetch for offline-first sync reconciliation. */
+    onSyncState?: () => Promise<{
+        watermark?: string | null;
+        dismissedIds?: string[];
+    }>;
+    /** Optional remote flush for queued single-dismiss operations. */
+    onFlushDismissBatch?: (ids: string[]) => Promise<void>;
+    /** Optional remote flush for queued dismiss-all operations. */
+    onFlushDismissAll?: (watermark: string) => Promise<void>;
+    /** Delay before queued operations are flushed. Default: 500ms. */
+    flushDebounceMs?: number;
+    /** Attach online/visibility listeners to trigger sync+flush. Default: true in browser. */
+    autoSyncOnOnline?: boolean;
+}
+declare class IndexedDBAdapter implements StorageAdapter {
+    private readonly prefix;
+    private readonly dbName;
+    private readonly storeName;
+    private readonly onDismissAllCallback?;
+    private readonly onSyncStateCallback?;
+    private readonly onFlushDismissBatchCallback?;
+    private readonly onFlushDismissAllCallback?;
+    private readonly flushDebounceMs;
+    private readonly autoSyncOnOnline;
+    private watermark;
+    private dismissed;
+    private queue;
+    private readonly hydratePromise;
+    private flushTimer;
+    private flushing;
+    private readonly boundOnlineHandler;
+    private readonly boundVisibilityHandler;
+    constructor(options?: IndexedDBAdapterOptions);
+    getWatermark(): string | null;
+    getDismissedIds(): ReadonlySet<string>;
+    dismiss(id: string): void;
+    dismissAll(now: Date): Promise<void>;
+    /** Flush queued dismiss operations to optional remote callbacks. */
+    flushQueue(): Promise<void>;
+    /** Merge local state with optional remote source, then flush queued writes. */
+    syncFromRemote(): Promise<void>;
+    /** Cleanup optional browser listeners. */
+    destroy(): void;
+    private persist;
+    private hydrateFromIndexedDB;
+    private readIndexedDBState;
+    private writeIndexedDBState;
+    private openDb;
+    private scheduleFlush;
+    private getLastDismissAll;
+    private collectDismissBatch;
+}
+
+/**
+ * In-memory storage adapter.
+ *
+ * Useful for:
+ * - Testing (no side effects)
+ * - Server-side rendering (no `window`/`localStorage`)
+ * - Environments without persistent storage
+ */
+declare class MemoryAdapter implements StorageAdapter {
+    private watermark;
+    private dismissed;
+    constructor(options?: {
+        watermark?: string | null;
+    });
+    getWatermark(): string | null;
+    getDismissedIds(): ReadonlySet<string>;
+    dismiss(id: string): void;
+    dismissAll(now: Date): Promise<void>;
+}
+
+interface RemoteAdapterOptions {
+    /** Base URL for the feature API (e.g. https://api.example.com/api/features) */
+    url: string;
+    /** Optional headers applied to all requests */
+    headers?: Record<string, string>;
+    /** Polling interval in ms for stale-while-revalidate (default: 5 minutes) */
+    fetchInterval?: number;
+    /** Data format, currently supports 'rest' (default) */
+    format?: "rest";
+    /** Optional user identifier to pass to state endpoint */
+    userId?: string;
+    /** Number of retries after the initial request (default: 3) */
+    retryAttempts?: number;
+    /** Base backoff delay used between retries (default: 250ms) */
+    retryBaseDelayMs?: number;
+    /** Consecutive failed operations before opening the circuit (default: 5) */
+    circuitBreakerThreshold?: number;
+    /** Cooldown period while the circuit is open (default: 60s) */
+    circuitBreakerCooldownMs?: number;
+    /** Optional sleep function override for test environments */
+    sleep?: (delayMs: number) => Promise<void>;
+    /** Optional timestamp function override for test environments */
+    now?: () => number;
+    /** Request timeout in milliseconds (default: 10s). */
+    requestTimeoutMs?: number;
+    /** HTTP statuses that should be retried (default: 408,429,500,502,503,504). */
+    retryOnStatuses?: number[];
+    /** Debounce window for batching dismiss calls (default: 150ms). */
+    dismissBatchWindowMs?: number;
+    /** Max ids sent in a single dismiss-batch request (default: 100). */
+    maxDismissBatchSize?: number;
+    /** Disable `/dismiss-batch` endpoint usage and always send single dismiss requests. */
+    disableDismissBatch?: boolean;
+    /** Flush/sync pending state when browser regains connectivity (default: false). */
+    syncOnOnline?: boolean;
+    /** Flush/sync pending state when tab becomes visible again (default: false). */
+    syncOnVisibilityChange?: boolean;
+    /** Optional periodic state sync interval in ms (default: disabled). */
+    syncIntervalMs?: number;
+    /** Optional error hook for diagnostics/telemetry. */
+    onError?: (error: unknown, context: {
+        operation: string;
+        attempt: number;
+    }) => void;
+}
+declare class RemoteAdapter implements StorageAdapter {
+    private readonly baseUrl;
+    private readonly headers;
+    private readonly fetchInterval;
+    private readonly userId?;
+    private dismissedIds;
+    private watermark;
+    private lastManifest;
+    private lastFetchTs;
+    private readonly retryAttempts;
+    private readonly retryBaseDelayMs;
+    private readonly circuitBreakerThreshold;
+    private readonly circuitBreakerCooldownMs;
+    private readonly sleep;
+    private readonly now;
+    private readonly requestTimeoutMs;
+    private readonly retryOnStatuses;
+    private readonly dismissBatchWindowMs;
+    private readonly maxDismissBatchSize;
+    private readonly disableDismissBatch;
+    private readonly syncOnOnline;
+    private readonly syncOnVisibilityChange;
+    private readonly syncIntervalMs;
+    private readonly onError?;
+    private consecutiveFailures;
+    private circuitOpenUntil;
+    private manifestInFlight;
+    private stateSyncInFlight;
+    private dismissFlushInFlight;
+    private dismissFlushTimer;
+    private syncTimer;
+    private pendingDismissIds;
+    private supportsDismissBatch;
+    private readonly boundOnlineHandler;
+    private readonly boundVisibilityHandler;
+    constructor(options: RemoteAdapterOptions);
+    /** Fetch manifest with stale-while-revalidate */
+    fetchManifest(force?: boolean): Promise<FeatureManifest>;
+    /** Fetch state (watermark + dismissed IDs) */
+    syncState(): Promise<void>;
+    getWatermark(): string | null;
+    getDismissedIds(): ReadonlySet<string>;
+    dismiss(id: string): void;
+    dismissAll(now: Date): Promise<void>;
+    /** Cleanup timers/listeners and flush any queued dismiss operations. */
+    destroy(): Promise<void>;
+    /** Returns current adapter health; false while circuit breaker is open. */
+    isHealthy(): Promise<boolean>;
+    private flushDismiss;
+    private flushDismissAll;
+    private isCircuitOpen;
+    private markFailure;
+    private markSuccess;
+    /** Force-flush queued dismiss IDs immediately. */
+    flushPendingDismisses(): Promise<void>;
+    private flushPendingDismissesInternal;
+    private flushDismissBatch;
+    private scheduleDismissFlush;
+    private runRecoverySync;
+    private requestJson;
+    private requestVoid;
+    private request;
+    private shouldRetry;
+    private withRetry;
+}
+
+interface QueryResultRow {
+    watermark?: string | null;
+    dismissed_ids?: string[] | null;
+    dismissedIds?: string[] | null;
+    last_seen?: string | null;
+    lastSeen?: string | null;
+}
+interface PostgresQueryResult<T = QueryResultRow> {
+    rows: T[];
+    rowCount?: number | null;
+}
+type PostgresQueryFn = <T = QueryResultRow>(sql: string, params?: unknown[]) => Promise<PostgresQueryResult<T>>;
+interface PostgresAdapterOptions {
+    userId: string;
+    query: PostgresQueryFn;
+    tableName?: string;
+    autoMigrate?: boolean;
+}
+/**
+ * Postgres-backed storage adapter.
+ *
+ * This adapter is dependency-free by design and accepts a user-provided
+ * query function, allowing integration with pg, drizzle, prisma, etc.
+ */
+declare class PostgresAdapter implements ServerStorageAdapter {
+    readonly userId: string;
+    private readonly query;
+    private readonly tableName;
+    private readonly autoMigrate;
+    private watermark;
+    private dismissedIds;
+    private initialized;
+    constructor(options: PostgresAdapterOptions);
+    getWatermark(): string | null;
+    getDismissedIds(): ReadonlySet<string>;
+    dismiss(id: string): void;
+    dismissAll(now: Date): Promise<void>;
+    sync(): Promise<void>;
+    dismissBatch(ids: string[]): Promise<void>;
+    resetUser(userId: string): Promise<void>;
+    getBulkState(userIds: string[]): Promise<Map<string, DismissalState>>;
+    isHealthy(): Promise<boolean>;
+    destroy(): Promise<void>;
+    private ensureReady;
+}
+
+interface RedisLikePipeline {
+    set(key: string, value: string): RedisLikePipeline;
+    del(key: string): RedisLikePipeline;
+    sadd(key: string, ...members: string[]): RedisLikePipeline;
+    exec(): Promise<unknown>;
+}
+interface RedisLikeClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<unknown>;
+    del(key: string): Promise<unknown>;
+    smembers(key: string): Promise<string[]>;
+    sadd(key: string, ...members: string[]): Promise<unknown>;
+    ping(): Promise<string>;
+    multi(): RedisLikePipeline;
+    quit?(): Promise<unknown>;
+    disconnect?(): void;
+}
+interface RedisAdapterOptions {
+    userId: string;
+    client: RedisLikeClient;
+    keyPrefix?: string;
+}
+/**
+ * Redis-backed storage adapter.
+ * Uses simple key + set structures to keep operations predictable.
+ */
+declare class RedisAdapter implements ServerStorageAdapter {
+    readonly userId: string;
+    private readonly client;
+    private readonly keyPrefix;
+    private watermark;
+    private dismissedIds;
+    constructor(options: RedisAdapterOptions);
+    getWatermark(): string | null;
+    getDismissedIds(): ReadonlySet<string>;
+    dismiss(id: string): void;
+    dismissAll(now: Date): Promise<void>;
+    sync(): Promise<void>;
+    dismissBatch(ids: string[]): Promise<void>;
+    resetUser(userId: string): Promise<void>;
+    getBulkState(userIds: string[]): Promise<Map<string, DismissalState>>;
+    isHealthy(): Promise<boolean>;
+    destroy(): Promise<void>;
+    private watermarkKey;
+    private dismissedKey;
+    private lastSeenKey;
+}
+
+interface HybridAdapterOptions {
+    local: StorageAdapter;
+    remote: ServerStorageAdapter;
+    /** If true, sync from remote before writes. Default false */
+    syncBeforeWrite?: boolean;
+    /** Batch window for queued dismiss writes. Default: 500ms */
+    dismissBatchWindowMs?: number;
+    /** Optional periodic sync interval in ms. Default: disabled (0) */
+    syncIntervalMs?: number;
+    /** Sync on browser visibility return. Default: true */
+    syncOnVisibilityChange?: boolean;
+    /** Sync on browser online event. Default: true */
+    syncOnOnline?: boolean;
+}
+/**
+ * Hybrid adapter that combines local immediacy with remote persistence.
+ */
+declare class HybridAdapter implements ServerStorageAdapter {
+    readonly userId: string;
+    private readonly local;
+    private readonly remote;
+    private readonly syncBeforeWrite;
+    private readonly dismissBatchWindowMs;
+    private readonly syncIntervalMs;
+    private readonly syncOnVisibilityChange;
+    private readonly syncOnOnline;
+    private pendingDismissIds;
+    private dismissTimer;
+    private syncTimer;
+    private flushInFlight;
+    private syncInFlight;
+    private readonly boundVisibilityHandler;
+    private readonly boundOnlineHandler;
+    constructor(options: HybridAdapterOptions);
+    getWatermark(): string | null;
+    getDismissedIds(): ReadonlySet<string>;
+    dismiss(id: string): void;
+    dismissAll(now: Date): Promise<void>;
+    sync(): Promise<void>;
+    dismissBatch(ids: string[]): Promise<void>;
+    resetUser(userId: string): Promise<void>;
+    getBulkState(userIds: string[]): Promise<Map<string, DismissalState>>;
+    isHealthy(): Promise<boolean>;
+    destroy(): Promise<void>;
+    /** Manually flush queued dismiss operations to the remote adapter. */
+    flushPendingDismisses(): Promise<void>;
+    private flushPendingDismissesInternal;
+    private scheduleDismissFlush;
+}
+
+interface MySQLRow {
+    user_id?: string;
+    watermark?: string | null;
+    dismissed_ids?: string[] | string | null;
+    dismissedIds?: string[] | string | null;
+    last_seen?: string | null;
+    lastSeen?: string | null;
+}
+interface MySQLQueryResult<T = MySQLRow> {
+    rows: T[];
+}
+type MySQLQueryFn = <T = MySQLRow>(sql: string, params?: unknown[]) => Promise<MySQLQueryResult<T>>;
+interface MySQLAdapterOptions {
+    userId: string;
+    query: MySQLQueryFn;
+    tableName?: string;
+    autoMigrate?: boolean;
+}
+declare class MySQLAdapter implements ServerStorageAdapter {
+    readonly userId: string;
+    private readonly query;
+    private readonly tableName;
+    private readonly autoMigrate;
+    private watermark;
+    private dismissedIds;
+    private initialized;
+    constructor(options: MySQLAdapterOptions);
+    getWatermark(): string | null;
+    getDismissedIds(): ReadonlySet<string>;
+    dismiss(id: string): void;
+    dismissAll(now: Date): Promise<void>;
+    sync(): Promise<void>;
+    dismissBatch(ids: string[]): Promise<void>;
+    resetUser(userId: string): Promise<void>;
+    getBulkState(userIds: string[]): Promise<Map<string, DismissalState>>;
+    isHealthy(): Promise<boolean>;
+    destroy(): Promise<void>;
+    private ensureReady;
+}
+
+interface MongoStateDoc {
+    userId: string;
+    watermark?: string | null;
+    dismissedIds?: string[];
+    lastSeen?: string;
+}
+interface MongoFindCursor<T> {
+    toArray: () => Promise<T[]>;
+}
+interface MongoLikeCollection {
+    findOne: (filter: Record<string, unknown>) => Promise<MongoStateDoc | null>;
+    updateOne: (filter: Record<string, unknown>, update: Record<string, unknown>, options?: Record<string, unknown>) => Promise<unknown>;
+    deleteOne: (filter: Record<string, unknown>) => Promise<unknown>;
+    find?: (filter: Record<string, unknown>) => MongoFindCursor<MongoStateDoc>;
+}
+interface MongoAdapterOptions {
+    userId: string;
+    collection: MongoLikeCollection;
+}
+declare class MongoAdapter implements ServerStorageAdapter {
+    readonly userId: string;
+    private readonly collection;
+    private watermark;
+    private dismissedIds;
+    constructor(options: MongoAdapterOptions);
+    getWatermark(): string | null;
+    getDismissedIds(): ReadonlySet<string>;
+    dismiss(id: string): void;
+    dismissAll(now: Date): Promise<void>;
+    sync(): Promise<void>;
+    dismissBatch(ids: string[]): Promise<void>;
+    resetUser(userId: string): Promise<void>;
+    getBulkState(userIds: string[]): Promise<Map<string, DismissalState>>;
+    isHealthy(): Promise<boolean>;
+    destroy(): Promise<void>;
+}
+
+interface SQLiteRow {
+    user_id?: string;
+    watermark?: string | null;
+    dismissed_ids?: string[] | string | null;
+    dismissedIds?: string[] | string | null;
+    last_seen?: string | null;
+    lastSeen?: string | null;
+}
+interface SQLiteQueryResult<T = SQLiteRow> {
+    rows: T[];
+}
+type SQLiteQueryFn = <T = SQLiteRow>(sql: string, params?: unknown[]) => Promise<SQLiteQueryResult<T>>;
+interface SQLiteAdapterOptions {
+    userId: string;
+    query: SQLiteQueryFn;
+    tableName?: string;
+    autoMigrate?: boolean;
+}
+declare class SQLiteAdapter implements ServerStorageAdapter {
+    readonly userId: string;
+    private readonly query;
+    private readonly tableName;
+    private readonly autoMigrate;
+    private watermark;
+    private dismissedIds;
+    private initialized;
+    constructor(options: SQLiteAdapterOptions);
+    getWatermark(): string | null;
+    getDismissedIds(): ReadonlySet<string>;
+    dismiss(id: string): void;
+    dismissAll(now: Date): Promise<void>;
+    sync(): Promise<void>;
+    dismissBatch(ids: string[]): Promise<void>;
+    resetUser(userId: string): Promise<void>;
+    getBulkState(userIds: string[]): Promise<Map<string, DismissalState>>;
+    isHealthy(): Promise<boolean>;
+    destroy(): Promise<void>;
+    private ensureReady;
+}
+
+interface SupabaseErrorLike {
+    message?: string;
+}
+interface SupabaseMaybeSingleResult<T> {
+    data: T | null;
+    error: SupabaseErrorLike | null;
+}
+interface SupabaseMutationResult {
+    error: SupabaseErrorLike | null;
+}
+interface SupabaseSelectQuery<T> {
+    eq: (column: string, value: unknown) => SupabaseSelectQuery<T>;
+    maybeSingle: () => Promise<SupabaseMaybeSingleResult<T>>;
+}
+interface SupabaseMutationQuery {
+    eq: (column: string, value: unknown) => Promise<SupabaseMutationResult>;
+}
+interface SupabaseTableClient<T> {
+    select: (columns: string) => SupabaseSelectQuery<T>;
+    upsert: (value: Record<string, unknown>) => Promise<SupabaseMutationResult>;
+    update: (value: Record<string, unknown>) => SupabaseMutationQuery;
+    delete: () => SupabaseMutationQuery;
+}
+interface SupabaseRealtimeChannelLike {
+    on: (event: "postgres_changes", filter: Record<string, unknown>, callback: () => void) => SupabaseRealtimeChannelLike;
+    subscribe: (callback?: (status: string) => void) => SupabaseRealtimeChannelLike;
+}
+interface SupabaseClientLike {
+    from: <T = SupabaseStateRow>(table: string) => SupabaseTableClient<T>;
+    channel?: (name: string) => SupabaseRealtimeChannelLike;
+    removeChannel?: (channel: SupabaseRealtimeChannelLike) => void | Promise<void>;
+}
+interface SupabaseStateRow {
+    [key: string]: unknown;
+    user_id: string;
+    watermark?: string | null;
+    dismissed_ids?: string[] | null;
+    last_seen?: string | null;
+}
+interface SupabaseAdapterOptions {
+    userId: string;
+    client: SupabaseClientLike;
+    tableName?: string;
+    realtime?: boolean;
+}
+declare class SupabaseAdapter implements ServerStorageAdapter {
+    readonly userId: string;
+    private readonly client;
+    private readonly tableName;
+    private readonly realtime;
+    private watermark;
+    private dismissedIds;
+    private realtimeChannel;
+    private syncing;
+    constructor(options: SupabaseAdapterOptions);
+    getWatermark(): string | null;
+    getDismissedIds(): ReadonlySet<string>;
+    dismiss(id: string): void;
+    dismissAll(now: Date): Promise<void>;
+    sync(): Promise<void>;
+    dismissBatch(ids: string[]): Promise<void>;
+    resetUser(userId: string): Promise<void>;
+    getBulkState(userIds: string[]): Promise<Map<string, DismissalState>>;
+    isHealthy(): Promise<boolean>;
+    destroy(): Promise<void>;
+    private fetchState;
+    private upsertState;
+    private setupRealtime;
+}
+
+export { HybridAdapter, type HybridAdapterOptions, IndexedDBAdapter, type IndexedDBAdapterOptions, LocalStorageAdapter, type LocalStorageAdapterOptions, MemoryAdapter, MongoAdapter, type MongoAdapterOptions, type MongoLikeCollection, MySQLAdapter, type MySQLAdapterOptions, type MySQLQueryFn, type MySQLQueryResult, PostgresAdapter, type PostgresAdapterOptions, type PostgresQueryFn, type PostgresQueryResult, RedisAdapter, type RedisAdapterOptions, type RedisLikeClient, type RedisLikePipeline, RemoteAdapter, type RemoteAdapterOptions, SQLiteAdapter, type SQLiteAdapterOptions, type SQLiteQueryFn, type SQLiteQueryResult, SupabaseAdapter, type SupabaseAdapterOptions, type SupabaseClientLike, type SupabaseRealtimeChannelLike };