@ubean/server 0.1.13 → 0.2.0

package/dist/feature-flags-DWkS6p0D.d.ts

@@ -0,0 +1,386 @@
+import { Context, MiddlewareHandler } from "hono";
+import { UbeanEnv } from "@ubean/shared";
+//#region src/analytics.d.ts
+interface AnalyticsContext {
+  /** 请求路径 */
+  path?: string;
+  /** HTTP 方法 */
+  method?: string;
+  /** 响应状态码 */
+  status?: number;
+  /** 请求耗时(毫秒) */
+  duration?: number;
+  /** Referrer */
+  referrer?: string;
+  /** User-Agent */
+  userAgent?: string;
+  /** Accept-Language 头部 */
+  locale?: string;
+  /** 请求 ID */
+  requestId?: string;
+  /** 客户端 IP */
+  ip?: string;
+  /** 额外的上下文键 */
+  [key: string]: unknown;
+}
+interface AnalyticsEvent {
+  /** 事件名称,如 'page_view'、'click'、'purchase' */
+  name: string;
+  /** 事件时间戳 */
+  timestamp: number;
+  /** 事件类型,默认 'event' */
+  type?: 'page_view' | 'event' | 'custom';
+}
+interface AnalyticsProperties {
+  [key: string]: unknown;
+}
+interface AnalyticsRecord {
+  event: string;
+  type: 'page_view' | 'event' | 'custom';
+  timestamp: number;
+  properties: AnalyticsProperties;
+  context: AnalyticsContext;
+}
+interface AnalyticsProvider {
+  /** provider 名称 */
+  name: string;
+  /** 跟踪一个事件 */
+  track(event: string, properties: AnalyticsProperties, context: AnalyticsContext): void | Promise<void>;
+  /** 可选:刷新缓冲区 */
+  flush?(): Promise<void>;
+  /** 可选:销毁 provider */
+  destroy?(): void;
+}
+interface AnalyticsProviderOptions {
+  /** provider 名称 */
+  name?: string;
+  /** track 实现 */
+  track: AnalyticsProvider['track'];
+  /** flush 实现 */
+  flush?: () => Promise<void>;
+  /** destroy 实现 */
+  destroy?: () => void;
+}
+interface AnalyticsTrackOptions {
+  /** 是否自动抽取上下文字段,默认 true */
+  autoContext?: boolean;
+  /** 附加 properties */
+  properties?: AnalyticsProperties;
+  /** 覆盖事件名(仅 trackPageView 时有效) */
+  eventName?: string;
+  /** 是否阻塞直到 provider 完成,默认 false */
+  awaitFlush?: boolean;
+}
+interface AnalyticsMiddlewareOptions {
+  /** 使用指定 provider(不传则用全局 provider) */
+  provider?: AnalyticsProvider | AnalyticsProvider[];
+  /** 自动跟踪的方法,默认 ['GET'] */
+  methods?: string[];
+  /** 跳过路径(前缀匹配) */
+  exclude?: string[];
+  /** 是否跟踪所有 status(默认仅 2xx/3xx) */
+  trackAllStatus?: boolean;
+  /** 自定义是否跟踪的判定 */
+  shouldTrack?: (c: Context<UbeanEnv>) => boolean | Promise<boolean>;
+  /** 自定义 properties 提取 */
+  getProperties?: (c: Context<UbeanEnv>) => AnalyticsProperties | Promise<AnalyticsProperties>;
+  /** 自定义事件名 */
+  eventName?: string;
+}
+/** log provider:输出到 console */
+declare function createLogAnalyticsProvider(): AnalyticsProvider;
+/** memory provider:存储在内存,用于测试 */
+declare function createMemoryAnalyticsProvider(): AnalyticsProvider & {
+  records: AnalyticsRecord[];
+  clear(): void;
+};
+/** mock provider:记录调用次数,用于断言 */
+declare function createMockAnalyticsProvider(impl?: Partial<AnalyticsProvider>): AnalyticsProvider & {
+  calls: Array<{
+    event: string;
+    properties: AnalyticsProperties;
+    context: AnalyticsContext;
+  }>;
+  callCount: number;
+  reset(): void;
+};
+/** 注册一个 provider 到全局 registry */
+declare function registerAnalyticsProvider(provider: AnalyticsProvider): void;
+/** 取消注册 */
+declare function unregisterAnalyticsProvider(name: string): void;
+/** 从 registry 获取指定名称的 provider */
+declare function getAnalyticsProvider(name: string): AnalyticsProvider | undefined;
+/** 获取所有已注册的 provider */
+declare function listAnalyticsProviders(): AnalyticsProvider[];
+/** 清空 registry(主要供测试使用) */
+declare function clearAnalyticsProviders(): void;
+/** 设置全局默认 provider */
+declare function setGlobalAnalyticsProvider(provider: AnalyticsProvider | AnalyticsProvider[] | null): void;
+/** 获取全局默认 provider(若未设置,返回空 provider) */
+declare function getGlobalAnalyticsProvider(): AnalyticsProvider | AnalyticsProvider[];
+/** 从 Hono 上下文中自动抽取 analytics context */
+declare function extractAnalyticsContext(c: Context<UbeanEnv>): AnalyticsContext;
+/**
+ * 跟踪一次页面浏览
+ */
+declare function trackPageView(c: Context<UbeanEnv>, options?: AnalyticsTrackOptions): Promise<void>;
+/**
+ * 跟踪一次自定义事件
+ */
+declare function trackEvent(c: Context<UbeanEnv>, name: string, properties?: AnalyticsProperties): Promise<void>;
+/** 直接调用 provider 跟踪事件(无 Hono 上下文) */
+declare function trackRaw(event: string, properties?: AnalyticsProperties, context?: AnalyticsContext, provider?: AnalyticsProvider | AnalyticsProvider[]): Promise<void>;
+/**
+ * 定义一个 analytics provider,并注册到全局 registry
+ *
+ * @example
+ * ```ts
+ * const provider = defineAnalyticsProvider({
+ *   name: 'posthog',
+ *   track(event, properties, context) {
+ *     await fetch('https://app.posthog.com/capture/', { ... });
+ *   }
+ * });
+ * ```
+ */
+declare function defineAnalyticsProvider(options: AnalyticsProviderOptions): AnalyticsProvider;
+/**
+ * 创建 analytics 中间件,自动跟踪页面浏览
+ *
+ * @example
+ * ```ts
+ * const memory = createMemoryAnalyticsProvider();
+ * app.use('*', createAnalyticsMiddleware({ provider: memory }));
+ * ```
+ */
+declare function createAnalyticsMiddleware(options?: AnalyticsMiddlewareOptions): MiddlewareHandler<UbeanEnv>;
+/** 定义 analytics 中间件(等同于 createAnalyticsMiddleware) */
+declare function defineAnalytics(options: AnalyticsMiddlewareOptions): MiddlewareHandler<UbeanEnv>;
+/** 从上下文获取 analytics provider(便于在 handler 中手动 track) */
+declare function useAnalytics(c?: Context<UbeanEnv>, provider?: AnalyticsProvider | AnalyticsProvider[]): {
+  trackPageView(properties?: AnalyticsProperties): void;
+  trackEvent(name: string, properties?: AnalyticsProperties): void;
+};
+//#endregion
+//#region src/feature-flags.d.ts
+type FlagValue = boolean | string | number;
+interface FlagContext {
+  /** 用户 ID(用于一致性分配) */
+  userId?: string;
+  /** 设备 ID / 匿名 ID */
+  anonymousId?: string;
+  /** 会话 ID */
+  sessionId?: string;
+  /** 语言/地区 */
+  locale?: string;
+  /** 国家 */
+  country?: string;
+  /** 自定义属性 */
+  attributes?: Record<string, unknown>;
+  /** IP(用于地理分群) */
+  ip?: string;
+  /** Hono 上下文引用(由中间件设置) */
+  [key: string]: unknown;
+}
+type FlagKind = 'boolean' | 'multivariate' | 'percentage';
+interface SegmentRule {
+  /** 匹配的属性名 */
+  attribute: string;
+  /** 操作符 */
+  operator: 'eq' | 'neq' | 'in' | 'not_in' | 'contains' | 'gt' | 'lt' | 'gte' | 'lte' | 'exists' | 'not_exists';
+  /** 期望值 */
+  value?: unknown;
+  /** 期望值列表(in / not_in 用) */
+  values?: unknown[];
+}
+interface Segment {
+  /** 段名称 */
+  name?: string;
+  /** 规则(全部匹配才命中) */
+  rules: SegmentRule[];
+  /** 该段是否启用 */
+  enabled?: boolean;
+}
+interface Variant {
+  /** variant 唯一标识 */
+  key: string;
+  /** variant 显示名 */
+  name?: string;
+  /** variant 权重(用于流量分配,所有 variant 权重之和决定分配比例) */
+  weight: number;
+  /** variant 值(可任意类型,字符串/JSON) */
+  value?: unknown;
+  /** variant 描述 */
+  description?: string;
+}
+interface FeatureFlagOptions {
+  /** flag 类型,默认 'boolean' */
+  kind?: FlagKind;
+  /** 默认值(评估失败时返回) */
+  defaultValue?: FlagValue;
+  /** multivariate 类型的可选值 */
+  variants?: Variant[];
+  /** 百分比 rollout(0-100),仅当 kind='percentage' 时生效 */
+  percentage?: number;
+  /** 用户分群:命中段则启用 */
+  segments?: Segment[];
+  /** 全局开关,默认 true */
+  enabled?: boolean;
+  /** 描述 */
+  description?: string;
+  /** 用于一致性哈希的 salt(避免不同 flag 对同一用户产生相同分配) */
+  salt?: string;
+}
+interface ExperimentOptions {
+  /** 实验描述 */
+  description?: string;
+  /** variants */
+  variants: Variant[];
+  /** 流量分配比例(0-100),默认 100 */
+  traffic?: number;
+  /** 用户分群:命中段才进入实验 */
+  segments?: Segment[];
+  /** 是否启用,默认 true */
+  enabled?: boolean;
+  /** 一致性哈希 salt */
+  salt?: string;
+}
+interface FeatureFlagDefinition extends FeatureFlagOptions {
+  name: string;
+  kind: FlagKind;
+  defaultValue: FlagValue;
+}
+interface ExperimentDefinition extends ExperimentOptions {
+  name: string;
+}
+interface FlagEvaluation {
+  name: string;
+  kind: FlagKind;
+  value: FlagValue;
+  reason: 'default' | 'enabled' | 'disabled' | 'segment' | 'percentage' | 'variant';
+  variant?: string;
+}
+interface ExperimentAssignment {
+  name: string;
+  variant: string;
+  inExperiment: boolean;
+  reason: 'enabled' | 'disabled' | 'segment' | 'traffic' | 'no_variants';
+}
+interface FeatureFlagStore {
+  getFlag(name: string): Promise<FeatureFlagDefinition | undefined>;
+  setFlag(name: string, flag: FeatureFlagDefinition): Promise<void>;
+  deleteFlag(name: string): Promise<void>;
+  listFlags(): Promise<FeatureFlagDefinition[]>;
+  getExperiment(name: string): Promise<ExperimentDefinition | undefined>;
+  setExperiment(name: string, exp: ExperimentDefinition): Promise<void>;
+  deleteExperiment(name: string): Promise<void>;
+  listExperiments(): Promise<ExperimentDefinition[]>;
+}
+interface FeatureFlagsMiddlewareOptions {
+  /** 使用指定 store(不传则用全局 store) */
+  store?: FeatureFlagStore;
+  /** 从 Hono 上下文中提取 flag context */
+  getContext?: (c: Context<UbeanEnv>) => FlagContext | Promise<FlagContext>;
+  /** 把评估结果写入 c.set 的 key 名,默认 'flags' / 'experiments' */
+  flagsVarKey?: string;
+  experimentsVarKey?: string;
+}
+declare function createMemoryFeatureFlagStore(): FeatureFlagStore;
+/** 设置全局 feature flag store */
+declare function setGlobalFeatureFlagStore(store: FeatureFlagStore | null): void;
+/** 获取全局 store(默认内存 store) */
+declare function getGlobalFeatureFlagStore(): FeatureFlagStore;
+/** 清空全局 store 和 registry(供测试使用) */
+declare function clearFeatureFlags(): void;
+/**
+ * 定义一个 feature flag,注册到全局 registry 和 store
+ *
+ * @example
+ * ```ts
+ * defineFeatureFlag('new_dashboard', {
+ *   kind: 'percentage',
+ *   percentage: 50,
+ *   defaultValue: false
+ * });
+ *
+ * defineFeatureFlag('checkout_flow', {
+ *   kind: 'multivariate',
+ *   variants: [
+ *     { key: 'control', weight: 1, value: 'v1' },
+ *     { key: 'treatment', weight: 1, value: 'v2' }
+ *   ],
+ *   defaultValue: 'v1'
+ * });
+ * ```
+ */
+declare function defineFeatureFlag(name: string, options?: FeatureFlagOptions): FeatureFlagDefinition;
+/**
+ * 定义一个 A/B 测试实验,注册到全局 registry 和 store
+ *
+ * @example
+ * ```ts
+ * defineExperiment('checkout_v2_test', {
+ *   variants: [
+ *     { key: 'control', weight: 1, value: 'A' },
+ *     { key: 'treatment', weight: 1, value: 'B' }
+ *   ],
+ *   traffic: 50
+ * });
+ * ```
+ */
+declare function defineExperiment(name: string, options: ExperimentOptions): ExperimentDefinition;
+/**
+ * 评估一个 flag,返回 boolean 或 variant value
+ *
+ * - boolean flag:返回 true / false
+ * - percentage flag:返回 true / false(基于用户身份的稳定百分比)
+ * - multivariate flag:返回选中的 variant value
+ */
+declare function evaluateFlag(name: string, context?: FlagContext, store?: FeatureFlagStore): Promise<FlagValue>;
+/** 评估 flag 并返回原因(用于调试 / debug) */
+declare function evaluateFlagWithReason(name: string, context?: FlagContext, store?: FeatureFlagStore): Promise<FlagEvaluation>;
+/**
+ * 获取一个实验分配给当前用户的 variant key
+ */
+declare function getVariant(name: string, context?: FlagContext, store?: FeatureFlagStore): Promise<string | undefined>;
+/** 获取实验分配详情(用于调试) */
+declare function getVariantAssignment(name: string, context?: FlagContext, store?: FeatureFlagStore): Promise<ExperimentAssignment>;
+/** 默认从 Hono 上下文提取 flag context */
+declare function extractFlagContext(c: Context<UbeanEnv>): FlagContext;
+/**
+ * 创建 feature flags 中间件,把 flag/experiment 评估附加到 context
+ *
+ * @example
+ * ```ts
+ * app.use('*', createFeatureFlagsMiddleware());
+ *
+ * app.get('/', (c) => {
+ *   const flags = useFlags(c);
+ *   if (flags.new_dashboard) {
+ *     return c.render('dashboard-v2');
+ *   }
+ *   return c.render('dashboard');
+ * });
+ * ```
+ */
+declare function createFeatureFlagsMiddleware(options?: FeatureFlagsMiddlewareOptions): MiddlewareHandler<UbeanEnv>;
+/** 从 Hono 上下文中获取所有 flag(由中间件写入) */
+declare function useFlags(c: Context<UbeanEnv>): Record<string, FlagValue>;
+/** 从 Hono 上下文中获取所有 experiment 分配 */
+declare function useExperiments(c: Context<UbeanEnv>): Record<string, string>;
+/** 获取当前请求的 flag context(由中间件写入) */
+declare function useFlagContext(c: Context<UbeanEnv>): FlagContext;
+/** 在 handler 中即时评估一个 flag(如果未启用中间件也可用) */
+declare function evaluateFlagFromContext(c: Context<UbeanEnv>, name: string, store?: FeatureFlagStore): Promise<FlagValue>;
+/** 在 handler 中即时获取一个实验的 variant(如果未启用中间件也可用) */
+declare function getVariantFromContext(c: Context<UbeanEnv>, name: string, store?: FeatureFlagStore): Promise<string | undefined>;
+/** 列出所有已注册的 flag 名称 */
+declare function listFlagNames(): string[];
+/** 列出所有已注册的 experiment 名称 */
+declare function listExperimentNames(): string[];
+/** 从 registry 中删除一个 flag */
+declare function removeFeatureFlag(name: string): void;
+/** 从 registry 中删除一个实验 */
+declare function removeExperiment(name: string): void;
+//#endregion
+export { getGlobalAnalyticsProvider as $, removeExperiment as A, AnalyticsProvider as B, extractFlagContext as C, getVariantFromContext as D, getVariantAssignment as E, useFlags as F, createAnalyticsMiddleware as G, AnalyticsRecord as H, AnalyticsContext as I, createMockAnalyticsProvider as J, createLogAnalyticsProvider as K, AnalyticsEvent as L, setGlobalFeatureFlagStore as M, useExperiments as N, listExperimentNames as O, useFlagContext as P, getAnalyticsProvider as Q, AnalyticsMiddlewareOptions as R, evaluateFlagWithReason as S, getVariant as T, AnalyticsTrackOptions as U, AnalyticsProviderOptions as V, clearAnalyticsProviders as W, defineAnalyticsProvider as X, defineAnalytics as Y, extractAnalyticsContext as Z, createMemoryFeatureFlagStore as _, FeatureFlagOptions as a, trackRaw as at, evaluateFlag as b, FlagContext as c, FlagValue as d, listAnalyticsProviders as et, Segment as f, createFeatureFlagsMiddleware as g, clearFeatureFlags as h, FeatureFlagDefinition as i, trackPageView as it, removeFeatureFlag as j, listFlagNames as k, FlagEvaluation as l, Variant as m, ExperimentDefinition as n, setGlobalAnalyticsProvider as nt, FeatureFlagStore as o, unregisterAnalyticsProvider as ot, SegmentRule as p, createMemoryAnalyticsProvider as q, ExperimentOptions as r, trackEvent as rt, FeatureFlagsMiddlewareOptions as s, useAnalytics as st, ExperimentAssignment as t, registerAnalyticsProvider as tt, FlagKind as u, defineExperiment as v, getGlobalFeatureFlagStore as w, evaluateFlagFromContext as x, defineFeatureFlag as y, AnalyticsProperties as z };