@ubean/server 0.1.12 → 0.2.0

package/dist/index.d.ts

@@ -1,492 +1,187 @@
-import { Hookable } from "hookable";
-import { Context, MiddlewareHandler, Next } from "hono";
-import { RouteRule, RouteRule as RouteRule$1, Span, Span as Span$1, SpanAttributes, SpanAttributes as SpanAttributes$1, SpanContext, SpanEndOptions, SpanEvent, SpanOptions, SpanOptions as SpanOptions$1, SpanStatus, UbeanBindings, UbeanContext, UbeanEnv, UbeanEnv as UbeanEnv$1, UbeanVariables } from "@ubean/types";
-//#region src/cache.d.ts
-interface CacheEntry {
-  body: ArrayBuffer;
-  headers: Record<string, string>;
-  status: number;
-  statusText: string;
-  createdAt: number;
-  expiresAt: number;
-}
-interface CacheStore {
-  get(key: string): Promise<CacheEntry | undefined>;
-  set(key: string, entry: Omit<CacheEntry, 'createdAt' | 'expiresAt'>, ttl: number): Promise<void>;
-  delete(key: string): Promise<boolean>;
-  clear(): Promise<void>;
-}
-declare function createMemoryStore(maxEntries?: number): CacheStore;
-declare function useCacheStore(store?: CacheStore): CacheStore;
-declare function clearCacheStore(): void;
-interface CacheRule {
-  ttl: number;
-  swr?: boolean | number;
-  name?: string;
-}
-declare function createCacheMiddleware(options?: {
-  store?: CacheStore;
-  rules?: Record<string, CacheRule>;
-  defaultTtl?: number;
-}): (c: Context, next: Next) => Promise<Response | undefined>;
-declare function cachedEventHandler<T extends (c: Context) => Response | Promise<Response>>(handler: T, options?: CacheRule): T;
-declare function invalidateRouteCache(keyPattern?: string | RegExp): Promise<void>;
-declare function resolveRouteCacheRules(routeRules: Record<string, RouteRule$1>): Record<string, CacheRule>;
-//#endregion
-//#region src/database.d.ts
-interface DatabaseHooks {
-  'db:connect': (db: Database) => void | Promise<void>;
-  'db:disconnect': (db: Database) => void | Promise<void>;
-  'db:query': (query: string, params?: unknown[]) => void | Promise<void>;
-  'db:error': (error: Error, query?: string) => void | Promise<void>;
-}
-interface Database {
-  sql: <T = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]) => Promise<{
-    rows: T[];
-  }>;
-  exec: (query: string) => Promise<void>;
-  close: () => Promise<void>;
-}
-interface DatabaseConnector {
-  (options?: Record<string, unknown>): DatabaseConnectorInstance;
-}
-interface DatabaseConnectorInstance {
-  dialect?: string;
-  [key: string]: unknown;
-}
-interface DrizzleConfig {
-  schema?: Record<string, unknown>;
-  logger?: boolean | {
-    logQuery?: (query: string, params: unknown[]) => void;
-  };
-  casing?: 'camelCase' | 'snake_case';
-}
-interface DatabaseOptions {
-  connector?: DatabaseConnectorInstance;
-  connectors?: Record<string, DatabaseConnectorInstance>;
-  default?: string;
-}
-interface Migration {
+import { $ as getGlobalAnalyticsProvider, A as removeExperiment, B as AnalyticsProvider, C as extractFlagContext, D as getVariantFromContext, E as getVariantAssignment, F as useFlags, G as createAnalyticsMiddleware, H as AnalyticsRecord, I as AnalyticsContext, J as createMockAnalyticsProvider, K as createLogAnalyticsProvider, L as AnalyticsEvent, M as setGlobalFeatureFlagStore, N as useExperiments, O as listExperimentNames, P as useFlagContext, Q as getAnalyticsProvider, R as AnalyticsMiddlewareOptions, S as evaluateFlagWithReason, T as getVariant, U as AnalyticsTrackOptions, V as AnalyticsProviderOptions, W as clearAnalyticsProviders, X as defineAnalyticsProvider, Y as defineAnalytics, Z as extractAnalyticsContext, _ as createMemoryFeatureFlagStore, a as FeatureFlagOptions, at as trackRaw, b as evaluateFlag, c as FlagContext, d as FlagValue, et as listAnalyticsProviders, f as Segment, g as createFeatureFlagsMiddleware, h as clearFeatureFlags, i as FeatureFlagDefinition, it as trackPageView, j as removeFeatureFlag, k as listFlagNames, l as FlagEvaluation, m as Variant, n as ExperimentDefinition, nt as setGlobalAnalyticsProvider, o as FeatureFlagStore, ot as unregisterAnalyticsProvider, p as SegmentRule, q as createMemoryAnalyticsProvider, r as ExperimentOptions, rt as trackEvent, s as FeatureFlagsMiddlewareOptions, st as useAnalytics, t as ExperimentAssignment, tt as registerAnalyticsProvider, u as FlagKind, v as defineExperiment, w as getGlobalFeatureFlagStore, x as evaluateFlagFromContext, y as defineFeatureFlag, z as AnalyticsProperties } from "./feature-flags-DWkS6p0D.js";
+import { a as cacheLife, c as clearComponentCacheStore, d as revalidatePath, f as revalidateTag, h as wrapWithCache, i as ComponentCacheStore, l as createComponentMemoryStore, m as useComponentCacheStore, n as CachedFunctionOptions, o as cacheTag, p as revalidateTags, r as ComponentCacheEntry, s as clearComponentCache, t as CacheWrapOptions, u as defineCachedFunction } from "./cache-directive-CAxJAQyE.js";
+import { a as clearCacheStore, c as invalidateRouteCache, i as cachedEventHandler, l as resolveRouteCacheRules, n as CacheRule, o as createCacheMiddleware, r as CacheStore, s as createMemoryStore, t as CacheEntry, u as useCacheStore } from "./cache-b-MZlyv0.js";
+import { _ as runScheduledTask, a as resetCronRunCounts, c as CronContext, d as CronTaskMeta, f as ScheduledTask, g as getScheduledTasks, h as defineScheduled, i as parseCron, l as CronSchedule, m as createCronContext, n as SchedulerOptions, o as startCronScheduler, p as clearScheduledTasks, r as createMemoryCronScheduler, s as validateCron, t as CronScheduler, u as CronTaskDefinition } from "./cron-scheduler-BF33PPn4.js";
+import { a as DatabaseOptions, c as closeDatabases, d as migrateDatabase, f as rawSql, h as useDatabase, i as DatabaseHooks, l as defineDatabase, m as runMigrations, n as DatabaseConnector, o as DrizzleConfig, p as registerDb0Create, r as DatabaseConnectorInstance, s as Migration, t as Database, u as getDatabaseHooks } from "./database-CfpFznl-.js";
+import { C as sendEmail, S as renderEmailTemplate, T as useEmailProvider, _ as defineEmailProvider, a as EmailProviderConfig, b as getEmailTransport, c as EmailTransport, d as MockEmailTransport, f as SendmailEmailProviderConfig, g as createEmailTransport, h as clearSentEmails, i as EmailProvider, l as LogEmailProviderConfig, m as clearEmailProviders, n as EmailAttachment, o as EmailProviderType, p as SmtpEmailProviderConfig, r as EmailOptions, s as EmailResult, t as DefineEmailProviderOptions, u as MockEmailProviderConfig, v as getEmailProvider, w as setDefaultEmailProvider, x as getSentEmails, y as getEmailProviderNames } from "./email-BvpEuNn_.js";
+import { _ as startQueueWorkers, a as QueueOptions, c as clearQueueDefinitions, d as getAllQueueStats, f as getQueueDefinitions, g as setQueueDriver, h as sendMessages, i as QueueMessage, l as createMemoryQueueDriver, m as sendMessage, n as QueueDriver, o as QueueStats, p as getQueueStats, r as QueueHandler, s as SendOptions, t as QueueDefinition, u as defineQueue, v as stopQueueWorkers, y as useQueueDriver } from "./queue-GOfTAWlz.js";
+import { A as handleUpgrade, C as defineWebSocket, D as handleClose, E as getWebSocketDefinitions, O as handleError, S as defineRoom, T as getRooms, _ as WebSocketRoom, a as broadcastSSE, b as createRoom, c as createSSEStream, d as getSSEConnections, f as sseHeaders, g as WebSocketHooks, h as WebSocketDefinition, i as SSEOptions, j as registerWebSocket, k as handleMessage, l as defineSSE, m as UpgradeResult, n as SSEHandler, o as clearSSEState, p as Peer, r as SSEMessage, s as closeAllSSE, t as SSEConnection, u as formatSSEMessage, v as broadcast, w as getRoom, x as createWebSocketMiddleware, y as clearWebSocketState } from "./sse-Ct72zhic.js";
+import { a as clearGlobalStorage, c as createStorage, i as UbeanStorage, l as useKV, n as KVOptions, o as createKV, r as StorageDriver, s as createMemoryDriver, t as KVNamespace, u as useStorage } from "./storage-QdlPtPtR.js";
+import { C as getSpan, E as withSpan, S as getRequestId, T as startSpan, _ as createOpenTelemetryExporter, a as REQUEST_ID_HEADER, b as generateRequestId, g as createObservabilityTracer, h as createConsoleExporter, i as ObservabilityTracer, m as TracingMiddlewareOptions, n as ObservabilityExporter, o as RequestIdOptions, r as ObservabilityHooks, t as ObservabilityConfig, v as createSpan, w as setGlobalTracer, x as getGlobalTracer, y as createTracingMiddleware } from "./observability-DUNUEjj3.js";
+import { n as serveStatic, t as ServeStaticOptions } from "./static-K2dRvjpS.js";
+import { A as createFetchMemoizationMiddleware, B as RateLimitOptions, C as isDraftMode, D as FetchInitWithNext, E as FetchCacheOptions, F as after, G as defineRateLimit, H as RateLimitStoreEntry, I as createAfterMiddleware, J as defineCors, K as CorsOptions, L as flushAfterCallbacks, M as getDataCacheSize, N as revalidateDataCachePath, O as clearFetchDataCache, P as revalidateDataCacheTag, R as getAfterCallbackCount, S as enableDraftMode, T as DataCacheMiddlewareOptions, U as createMemoryRateLimitStore, V as RateLimitStore, W as createRateLimitMiddleware, _ as DraftMode, a as RevalidationResult, b as defineDraftMode, c as createSingleFlightMiddleware, d as getInvalidatedKeys, f as getRevalidationEntries, g as unregisterRevalidation, h as runRevalidation, i as RevalidationKey, j as createMemoizedFetch, k as createDataCacheMiddleware, l as defineRevalidation, m as invalidateKey, n as RevalidationEntry, o as SingleFlightOptions, p as invalidate, q as createCorsMiddleware, r as RevalidationFetcher, s as clearRevalidationRegistry, t as RevalidationContext, u as defineSingleFlight, v as DraftModeOptions, w as useDraftMode, x as disableDraftMode, y as createDraftModeMiddleware, z as RateLimitInfo } from "./single-flight-BJyhDLdU.js";
+import { _ as generateCsrfToken, a as createSessionMiddleware, c as useSession, d as createSecurityHeadersMiddleware, f as defineSecurityHeaders, g as defineCsrf, h as createCsrfMiddleware, i as SessionStore, l as ContentSecurityPolicyDirectives, m as CsrfOptions, n as SessionData, o as createStorageSessionStore, p as serializeCsp, r as SessionOptions, s as defineSessionStore, t as Session, u as SecurityHeadersOptions } from "./sessions-BLqFFQTL.js";
+import { Context, MiddlewareHandler } from "hono";
+import { RouteRule, Span, SpanAttributes, SpanContext, SpanEndOptions, SpanEvent, SpanOptions, SpanStatus, UbeanBindings, UbeanContext, UbeanEnv, UbeanEnv as UbeanEnv$1, UbeanVariables } from "@ubean/shared";
+//#region src/cdn-cache.d.ts
+/**
+ * Surrogate key 头部名称(各平台不同)。
+ * Cloudflare 用 `Cache-Tag`,Fastly 用 `Surrogate-Key`,
+ * Vercel 用 `x-vercel-cache-tags`。
+ */
+type SurrogateKeyHeader = 'Cache-Tag' | 'Surrogate-Key' | 'x-vercel-cache-tags' | string;
+/**
+ * CDN 缓存清除适配器接口
+ */
+interface CdnPurgeAdapter {
+  /** 适配器名称(用于日志/调试) */
   name: string;
-  up: string;
-  down?: string;
-}
-declare const RAW_SQL: unique symbol;
-interface RawSqlValue {
-  [RAW_SQL]: true;
-  value: string;
-}
-declare function rawSql(str: string): RawSqlValue;
-type RawSqlFn = <T = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]) => Promise<{
-  rows: T[];
-}>;
-type RawExecFn = (query: string) => Promise<void>;
-type RawCloseFn = () => Promise<void>;
-declare function defineDatabase(options?: DatabaseOptions): Database;
-declare function useDatabase(name?: string): Database;
-declare function closeDatabases(): Promise<void>;
-declare function getDatabaseHooks(): import("hookable").Hookable<DatabaseHooks, import("hookable").HookKeys<DatabaseHooks>>;
-declare function registerDb0Create(fn: (connector: DatabaseConnectorInstance) => {
-  sql: RawSqlFn;
-  exec: RawExecFn;
-  close: RawCloseFn;
-}): void;
-declare function migrateDatabase(db: Database, migrations: string[]): Promise<void>;
-declare function runMigrations(db: Database, migrations: Migration[], options?: {
-  table?: string;
-  log?: boolean;
-}): Promise<{
-  applied: string[];
-}>;
-//#endregion
-//#region src/queue.d.ts
-interface QueueMessage<T = unknown> {
-  id: string;
-  body: T;
-  timestamp: number;
-  attempts: number;
-  headers?: Record<string, string>;
-}
-interface QueueHandler<T = unknown> {
-  (message: QueueMessage<T>): void | Promise<void>;
-}
-interface QueueOptions<T = unknown> {
-  name: string;
-  handler?: QueueHandler<T>;
-  concurrency?: number;
-  retries?: number;
-  retryDelay?: number;
-  deadLetterQueue?: string;
-}
-interface QueueDefinition<T = unknown> extends QueueOptions<T> {
-  handler: QueueHandler<T>;
-}
-interface QueueDriver {
-  send<T>(queueName: string, message: T, options?: SendOptions): Promise<string>;
-  sendBatch<T>(queueName: string, messages: T[], options?: SendOptions): Promise<string[]>;
-  registerHandler?(queueName: string, handler: QueueHandler, options?: QueueOptions): void;
-  start?(): Promise<void>;
-  stop?(): Promise<void>;
-  getQueueDepth?(queueName: string): Promise<number>;
-  deleteMessage?(queueName: string, messageId: string): Promise<boolean>;
-}
-interface SendOptions {
-  delay?: number;
-  headers?: Record<string, string>;
-}
-interface QueueStats {
-  pending: number;
-  processing: number;
-  completed: number;
-  failed: number;
-}
-declare function defineQueue<T = unknown>(options: QueueOptions<T>, handler?: QueueHandler<T>): QueueDefinition<T>;
-declare function createMemoryQueueDriver(): QueueDriver;
-declare function useQueueDriver(): QueueDriver;
-declare function setQueueDriver(driver: QueueDriver): void;
-declare function sendMessage<T = unknown>(queueName: string, body: T, options?: SendOptions): Promise<string>;
-declare function sendMessages<T = unknown>(queueName: string, bodies: T[], options?: SendOptions): Promise<string[]>;
-declare function getQueueDefinitions(): QueueDefinition[];
-declare function clearQueueDefinitions(): void;
-declare function startQueueWorkers(): Promise<void>;
-declare function stopQueueWorkers(): Promise<void>;
-declare function getQueueStats(queueName: string): QueueStats | undefined;
-declare function getAllQueueStats(): Record<string, QueueStats>;
-//#endregion
-//#region src/cron.d.ts
-type CronSchedule = string;
-interface CronTaskMeta {
-  name: string;
-  schedule: CronSchedule;
-  description?: string;
-  timezone?: string;
-  timeout?: number;
-  runOnStart?: boolean;
-}
-interface CronTaskDefinition extends CronTaskMeta {
-  handler: (ctx: CronContext) => void | Promise<void>;
-}
-interface CronContext {
-  name: string;
-  schedule: CronSchedule;
-  timestamp: Date;
-  runCount: number;
-}
-interface ScheduledTask {
-  name: string;
-  schedule: CronSchedule;
-  handler: (ctx: CronContext) => void | Promise<void>;
-  meta: Omit<CronTaskMeta, 'name' | 'schedule'>;
-}
-declare function defineScheduled(metaOrName: CronTaskMeta | string, handler?: (ctx: CronContext) => void | Promise<void>): ScheduledTask;
-declare function getScheduledTasks(): ScheduledTask[];
-declare function clearScheduledTasks(): void;
-declare function runScheduledTask(name: string): Promise<{
-  ok: boolean;
-  duration: number;
-  error?: Error;
-}>;
-declare function createCronContext(name: string, schedule: string): CronContext;
-//#endregion
-//#region src/cron-scheduler.d.ts
-interface CronScheduler {
-  start(): Promise<void>;
-  stop(): Promise<void>;
-  runTask(name: string): Promise<{
-    ok: boolean;
-    duration: number;
-    error?: Error;
-  }>;
-  isRunning(): boolean;
-  getTasks(): ScheduledTask[];
-  getNextRuns(): Array<{
-    name: string;
-    nextRun: Date | null;
-  }>;
-}
-interface SchedulerOptions {
-  timezone?: string;
-  defaultTimeout?: number;
-  onTaskStart?: (task: ScheduledTask) => void;
-  onTaskComplete?: (task: ScheduledTask, result: {
-    ok: boolean;
-    duration: number;
-    error?: Error;
-  }) => void;
-  onTaskError?: (task: ScheduledTask, error: Error) => void;
-}
-type CronField = number[];
-interface ParsedCron {
-  minute: CronField;
-  hour: CronField;
-  dom: CronField;
-  month: CronField;
-  dow: CronField;
-}
-declare function parseCron(schedule: string): ParsedCron | null;
-declare function createMemoryCronScheduler(options?: SchedulerOptions): CronScheduler;
-declare function startCronScheduler(options?: SchedulerOptions): CronScheduler;
-declare function resetCronRunCounts(): void;
-declare function validateCron(schedule: string): boolean;
-//#endregion
-//#region src/websocket.d.ts
-interface Peer {
-  readonly id: string;
-  readonly url: string;
-  readonly headers: Headers;
-  readonly readyState: number;
-  send(data: string | ArrayBuffer | Uint8Array): void;
-  publish(topic: string, data: string | ArrayBuffer | Uint8Array): void;
-  subscribe(topic: string): void;
-  unsubscribe(topic: string): void;
-  close(code?: number, reason?: string): void;
-  getData<T = unknown>(): T | undefined;
-  setData<T>(data: T): void;
-}
-interface WebSocketRoom {
-  readonly name: string;
-  readonly peers: Set<Peer>;
-  broadcast(data: string | ArrayBuffer | Uint8Array, options?: {
-    except?: Peer;
-  }): void;
-  add(peer: Peer): void;
-  remove(peer: Peer): void;
-}
-interface WebSocketHooks {
-  open?: (peer: Peer) => void | Promise<void>;
-  message?: (peer: Peer, message: string | ArrayBuffer) => void | Promise<void>;
-  close?: (peer: Peer, code: number, reason: string) => void | Promise<void>;
-  error?: (peer: Peer, error: Error) => void | Promise<void>;
-}
-interface WebSocketDefinition {
-  path?: string;
-  hooks?: WebSocketHooks;
-  topics?: string[];
-  rooms?: string[];
-}
-declare function createRoom(name: string): WebSocketRoom;
-declare function defineWebSocket(def: WebSocketDefinition): WebSocketDefinition;
-declare function defineRoom(name: string): WebSocketRoom;
-declare function getRoom(name: string): WebSocketRoom | undefined;
-declare function getRooms(): Map<string, WebSocketRoom>;
-declare function broadcast(topic: string, data: string | ArrayBuffer | Uint8Array): void;
-declare function registerWebSocket(path: string, def: WebSocketDefinition): void;
-declare function getWebSocketDefinitions(): Map<string, WebSocketDefinition>;
-interface UpgradeResult {
-  response: Response;
-  peer: Peer;
-}
-declare function handleUpgrade(c: Context<UbeanEnv$1>, options: {
-  send: (data: string | ArrayBuffer | Uint8Array) => void;
-  close: (code?: number, reason?: string) => void;
+  /** 按 surrogate key 清除缓存 */
+  purgeKeys(keys: string[]): Promise<PurgeResult>;
+  /** 按 URL 清除缓存(可选) */
+  purgeUrls?(urls: string[]): Promise<PurgeResult>;
+  /** 清除全部缓存(谨慎使用) */
+  purgeAll?(): Promise<PurgeResult>;
+}
+/**
+ * 清除操作结果
+ */
+interface PurgeResult {
+  /** 是否成功 */
+  success: boolean;
+  /** 被清除的 key/url 数量 */
+  purged: number;
+  /** 平台返回的原始响应(调试用) */
   raw?: unknown;
-}): UpgradeResult;
-declare function handleMessage(peer: Peer, message: string | ArrayBuffer): void;
-declare function handleClose(peer: Peer, code?: number, reason?: string): void;
-declare function handleError(peer: Peer, error: Error): void;
-declare function createWebSocketMiddleware(): MiddlewareHandler<UbeanEnv$1>;
-declare function clearWebSocketState(): void;
-//#endregion
-//#region src/sse.d.ts
-interface SSEMessage {
-  data?: string | object;
-  event?: string;
-  id?: string;
-  retry?: number;
-  comment?: string;
-}
-interface SSEConnection {
-  readonly id: string;
-  send(message: SSEMessage): void;
-  sendData(data: string | object, event?: string): void;
-  comment(text: string): void;
-  close(): void;
-  readonly closed: boolean;
-}
-interface SSEHandler {
-  onConnect?: (connection: SSEConnection) => void | Promise<void>;
-  onClose?: (connection: SSEConnection) => void | Promise<void>;
-}
-interface SSEOptions {
-  headers?: Record<string, string>;
-  retry?: number;
-  keepAlive?: boolean | number;
-}
-declare function formatSSEMessage(msg: SSEMessage): string;
-declare function createSSEStream(c: Context<UbeanEnv$1>, handler: SSEHandler, options?: SSEOptions): Response;
-declare function defineSSE(handler: SSEHandler, options?: SSEOptions): MiddlewareHandler<UbeanEnv$1>;
-declare function getSSEConnections(): Map<string, SSEConnection>;
-declare function broadcastSSE(event: string, data: string | object, filter?: (conn: SSEConnection) => boolean): void;
-declare function closeAllSSE(): void;
-declare function sseHeaders(): Record<string, string>;
-declare function clearSSEState(): void;
-//#endregion
-//#region src/storage.d.ts
-interface StorageDriver {
-  getItemRaw(key: string): Promise<unknown>;
-  setItemRaw(key: string, value: unknown): Promise<void>;
-  removeItem(key: string): Promise<void>;
-  getKeys(base?: string): Promise<string[]>;
-  clear(base?: string): Promise<void>;
-  hasItem(key: string): Promise<boolean>;
-}
-interface UbeanStorage {
-  get<T = unknown>(key: string): Promise<T | null>;
-  set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>;
-  remove(key: string): Promise<void>;
-  keys(base?: string): Promise<string[]>;
-  clear(base?: string): Promise<void>;
-  has(key: string): Promise<boolean>;
-  getMeta(key: string): Promise<{
-    ttl?: number;
-    createdAt?: number;
-    expiresAt?: number;
-  } | null>;
-  mount(base: string, driver: StorageDriver): void;
-}
-declare function createMemoryDriver(): StorageDriver;
-declare function createStorage(options?: {
-  driver?: StorageDriver;
-  base?: string;
-}): UbeanStorage;
-declare function useStorage(storage?: UbeanStorage): UbeanStorage;
-declare function clearGlobalStorage(): void;
-interface KVOptions<T = unknown> {
-  ttl?: number;
-  prefix?: string;
-  serialize?: (value: T) => string;
-  deserialize?: (raw: string) => T;
-}
-interface KVNamespace<T = unknown> {
-  get(key: string): Promise<T | null>;
-  set(key: string, value: T, ttl?: number): Promise<void>;
-  remove(key: string): Promise<void>;
-  keys(): Promise<string[]>;
-  has(key: string): Promise<boolean>;
-  clear(): Promise<void>;
-}
-declare function createKV<T = unknown>(options?: KVOptions<T>): KVNamespace<T>;
-declare function useKV<T = unknown>(name?: string, options?: KVOptions<T>): KVNamespace<T>;
-//#endregion
-//#region src/observability.d.ts
-declare const REQUEST_ID_HEADER = "x-request-id";
-interface RequestIdOptions {
-  headerName?: string;
-  limitLength?: number;
-  generator?: (c: any) => string;
-}
-declare function generateRequestId(): string;
-declare function getRequestId(c: {
-  get: (key: 'requestId') => string;
-}): string;
-interface ObservabilityHooks {
-  'span:start': (span: Span$1) => void | Promise<void>;
-  'span:end': (span: Span$1) => void | Promise<void>;
-  'span:error': (span: Span$1, error: Error) => void | Promise<void>;
-}
-interface ObservabilityExporter {
-  name: string;
-  exportSpan(span: Readonly<Span$1>): void | Promise<void>;
-  flush?(): Promise<void>;
-  shutdown?(): Promise<void>;
-}
-interface ObservabilityConfig {
-  defaultAttributes?: SpanAttributes$1;
-  sensitiveKeys?: string[];
-  exporters?: ObservabilityExporter[];
-  enabled?: boolean;
-}
-declare function createSpan(options: SpanOptions$1): Span$1;
-declare function createObservabilityTracer(config?: ObservabilityConfig): {
-  hooks: Hookable<ObservabilityHooks, import("hookable").HookKeys<ObservabilityHooks>>;
-  startSpan: (options: SpanOptions$1) => Span$1;
-  withSpan: <T>(options: SpanOptions$1 | string, fn: (span: Span$1) => T | Promise<T>) => Promise<T>;
-  getActiveSpan: () => Span$1 | undefined;
-  addExporter: (exporter: ObservabilityExporter) => void;
-  removeExporter: (name: string) => void;
-  redactAttributes: (attrs: SpanAttributes$1) => SpanAttributes$1;
-  flush: () => Promise<void>;
-  shutdown: () => Promise<void>;
-  createSpan: typeof createSpan;
-};
-type ObservabilityTracer = ReturnType<typeof createObservabilityTracer>;
-declare function setGlobalTracer(tracer: ObservabilityTracer | null): void;
-declare function getGlobalTracer(): ObservabilityTracer;
-declare function startSpan(options: SpanOptions$1 | string): Span$1;
-declare function withSpan<T>(options: SpanOptions$1 | string, fn: (span: Span$1) => T | Promise<T>): Promise<T>;
-declare function createOpenTelemetryExporter(options?: {
-  url?: string;
-  headers?: Record<string, string>;
-  serviceName?: string;
-  serviceVersion?: string;
-  fetchImpl?: typeof fetch;
-}): ObservabilityExporter;
-declare function createConsoleExporter(options?: {
-  colors?: boolean;
-  slowThreshold?: number;
-}): ObservabilityExporter;
-interface TracingMiddlewareOptions {
-  tracer?: ObservabilityTracer;
-  includeHeaders?: boolean;
-  headerFilter?: (name: string) => boolean;
-}
-declare function createTracingMiddleware(options?: TracingMiddlewareOptions): (c: any, next: any) => Promise<void>;
-declare function getSpan(c: {
-  get: (key: string) => unknown;
-}): Span$1 | undefined;
-//#endregion
-//#region src/static.d.ts
-interface ServeStaticOptions {
-  publicDir: string;
-  indexFiles?: string[];
-  maxAge?: number;
-}
-declare function serveStatic(options: ServeStaticOptions): MiddlewareHandler<UbeanEnv$1>;
-//#endregion
-//#region src/cors.d.ts
-interface CorsOptions {
-  origin?: string | string[] | boolean | ((origin: string, c: Context<UbeanEnv$1>) => boolean | string | undefined | Promise<boolean | string | undefined>);
-  allowMethods?: string[];
-  allowHeaders?: string[];
-  exposeHeaders?: string[];
-  credentials?: boolean;
-  maxAge?: number;
-  preflightContinue?: boolean;
-}
-declare function createCorsMiddleware(options?: CorsOptions): MiddlewareHandler<UbeanEnv$1>;
-declare function defineCors(options: CorsOptions): MiddlewareHandler<UbeanEnv$1>;
-//#endregion
-//#region src/rate-limit.d.ts
-interface RateLimitOptions {
-  maxRequests?: number;
-  windowMs?: number;
-  keyGenerator?: (c: Context<UbeanEnv$1>) => string;
-  handler?: (c: Context<UbeanEnv$1>, info: RateLimitInfo) => Response | Promise<Response>;
-  skip?: (c: Context<UbeanEnv$1>) => boolean | Promise<boolean>;
-  standardHeaders?: boolean;
-  legacyHeaders?: boolean;
-  store?: RateLimitStore;
-}
-interface RateLimitInfo {
-  limit: number;
-  remaining: number;
-  reset: number;
-  retryAfter: number;
-}
-interface RateLimitStoreEntry {
-  count: number;
-  resetAt: number;
-}
-interface RateLimitStore {
-  get(key: string): Promise<RateLimitStoreEntry | undefined>;
-  set(key: string, entry: RateLimitStoreEntry, ttlMs: number): Promise<void>;
-  increment(key: string, windowMs: number): Promise<RateLimitStoreEntry>;
-  reset(key: string): Promise<void>;
-}
-declare function createRateLimitMiddleware(options?: RateLimitOptions): MiddlewareHandler<UbeanEnv$1>;
-declare function defineRateLimit(options: RateLimitOptions): MiddlewareHandler<UbeanEnv$1>;
-declare function createMemoryRateLimitStore(): RateLimitStore & {
-  destroy(): void;
+  /** 错误信息(失败时) */
+  error?: string;
+}
+/**
+ * Cache-Control 中间件选项
+ */
+interface CacheControlOptions {
+  /** 默认 max-age(秒),浏览器缓存 */
+  defaultMaxAge?: number;
+  /** s-maxage(秒),CDN/共享缓存 */
+  sMaxAge?: number;
+  /** stale-while-revalidate(秒) */
+  staleWhileRevalidate?: number;
+  /** stale-if-error(秒) */
+  staleIfError?: number;
+  /** 是否公开缓存(默认 true) */
+  public?: boolean;
+  /** 是否不可变(用于带 hash 的静态资源) */
+  immutable?: boolean;
+  /** 按路径模式自定义 max-age */
+  rules?: Array<{
+    pattern: string | RegExp;
+    maxAge?: number;
+    sMaxAge?: number;
+    immutable?: boolean;
+  }>;
+  /** 跳过路径(前缀匹配) */
+  exclude?: string[];
+  /** 是否对 404/5xx 设置 no-cache(默认 true) */
+  noCacheOnError?: boolean;
+}
+/**
+ * 为当前响应设置 surrogate key 头部。
+ *
+ * 在路由处理器中调用,为响应打上缓存标签,
+ * 后续可通过 `purgeKeys(adapter, keys)` 批量失效。
+ *
+ * @example
+ * ```typescript
+ * app.get('/products/:id', async (c) => {
+ *   const product = await getProduct(c.req.param('id'));
+ *   defineSurrogateKeys(c, [`product:${product.id}`, 'product-list']);
+ *   return c.json(product);
+ * });
+ * ```
+ */
+declare function defineSurrogateKeys(c: Context<UbeanEnv$1>, keys: string[], header?: SurrogateKeyHeader): void;
+/**
+ * 从请求上下文读取 surrogate keys(通常用于测试/调试)。
+ */
+declare function getSurrogateKeys(c: Context<UbeanEnv$1>, header?: SurrogateKeyHeader): string[];
+/**
+ * 设置全局默认 CDN 清除适配器。
+ */
+declare function setGlobalPurgeAdapter(adapter: CdnPurgeAdapter | null): void;
+/**
+ * 获取全局默认清除适配器。
+ */
+declare function getGlobalPurgeAdapter(): CdnPurgeAdapter | null;
+/**
+ * 使用指定适配器(或全局适配器)按 key 清除 CDN 缓存。
+ *
+ * @example
+ * ```typescript
+ * // 数据变更后失效相关页面缓存
+ * await purgeKeys(['product:42', 'product-list']);
+ * ```
+ */
+declare function purgeKeys(adapterOrKeys: CdnPurgeAdapter | string[], keys?: string[]): Promise<PurgeResult>;
+/**
+ * 按 URL 清除 CDN 缓存。
+ */
+declare function purgeUrls(adapterOrUrls: CdnPurgeAdapter | string[], urls?: string[]): Promise<PurgeResult>;
+/**
+ * 创建 Cache-Control 头部生成中间件。
+ *
+ * 根据路由规则自动设置 `Cache-Control` 响应头,
+ * 支持按路径模式自定义 max-age / s-maxage / immutable 等。
+ *
+ * @example
+ * ```typescript
+ * app.use('*', createCacheControlMiddleware({
+ *   defaultMaxAge: 60,
+ *   sMaxAge: 300,
+ *   rules: [
+ *     { pattern: '/_assets/**', maxAge: 31536000, immutable: true },
+ *     { pattern: '/api/**', maxAge: 0 }
+ *   ],
+ *   exclude: ['/api/health', '/api/webhook']
+ * }));
+ * ```
+ */
+declare function createCacheControlMiddleware(options?: CacheControlOptions): MiddlewareHandler<UbeanEnv$1>;
+/**
+ * Cloudflare 缓存清除适配器
+ *
+ * 使用 Cloudflare API 按 Cache-Tag 清除缓存。
+ * 需要 zone ID 和 API Token(需 Cache Purge 权限)。
+ *
+ * @example
+ * ```typescript
+ * const adapter = createCloudflarePurgeAdapter({
+ *   zoneId: process.env.CF_ZONE_ID!,
+ *   apiToken: process.env.CF_API_TOKEN!
+ * });
+ * setGlobalPurgeAdapter(adapter);
+ * await purgeKeys(['product:42']);
+ * ```
+ */
+declare function createCloudflarePurgeAdapter(options: {
+  zoneId: string;
+  apiToken: string;
+  endpoint?: string;
+}): CdnPurgeAdapter;
+/**
+ * Fastly 缓存清除适配器
+ *
+ * 使用 Fastly API 按 Surrogate-Key 清除缓存。
+ * 需要 service ID 和 API key。
+ */
+declare function createFastlyPurgeAdapter(options: {
+  serviceId: string;
+  apiKey: string;
+  endpoint?: string;
+}): CdnPurgeAdapter;
+/**
+ * Mock purge 适配器(用于测试)
+ *
+ * 记录所有清除操作,便于断言。
+ */
+declare function createMockPurgeAdapter(): CdnPurgeAdapter & {
+  purgedKeys: string[][];
+  purgedUrls: string[][];
+  purgedAllCount: number;
+  reset(): void;
 };
+/**
+ * 清除全局状态(主要用于测试隔离)
+ */
+declare function _resetCdnCache(): void;
 //#endregion
-export { type CacheEntry, type CacheRule, type CacheStore, type CorsOptions, type CronContext, type CronSchedule, type CronScheduler, type CronTaskDefinition, type CronTaskMeta, type Database, type DatabaseConnector, type DatabaseConnectorInstance, type DatabaseHooks, type DatabaseOptions, type DrizzleConfig, type KVNamespace, type KVOptions, type Migration, type ObservabilityConfig, type ObservabilityExporter, type ObservabilityHooks, type ObservabilityTracer, type Peer, type QueueDefinition, type QueueDriver, type QueueHandler, type QueueMessage, type QueueOptions, type QueueStats, REQUEST_ID_HEADER, type RateLimitInfo, type RateLimitOptions, type RateLimitStore, type RateLimitStoreEntry, type RequestIdOptions, type RouteRule, type SSEConnection, type SSEHandler, type SSEMessage, type SSEOptions, type ScheduledTask, type SchedulerOptions, type SendOptions, type ServeStaticOptions, type Span, type SpanAttributes, type SpanContext, type SpanEndOptions, type SpanEvent, type SpanOptions, type SpanStatus, type StorageDriver, type TracingMiddlewareOptions, type UbeanBindings, type UbeanContext, type UbeanEnv, type UbeanStorage, type UbeanVariables, type UpgradeResult, type WebSocketDefinition, type WebSocketHooks, type WebSocketRoom, broadcast, broadcastSSE, cachedEventHandler, clearCacheStore, clearGlobalStorage, clearQueueDefinitions, clearSSEState, clearScheduledTasks, clearWebSocketState, closeAllSSE, closeDatabases, createCacheMiddleware, createConsoleExporter, createCorsMiddleware, createCronContext, createKV, createMemoryCronScheduler, createMemoryDriver, createMemoryQueueDriver, createMemoryRateLimitStore, createMemoryStore, createObservabilityTracer, createOpenTelemetryExporter, createRateLimitMiddleware, createRoom, createSSEStream, createSpan, createStorage, createTracingMiddleware, createWebSocketMiddleware, defineCors, defineDatabase, defineQueue, defineRateLimit, defineRoom, defineSSE, defineScheduled, defineWebSocket, formatSSEMessage, generateRequestId, getAllQueueStats, getDatabaseHooks, getGlobalTracer, getQueueDefinitions, getQueueStats, getRequestId, getRoom, getRooms, getSSEConnections, getScheduledTasks, getSpan, getWebSocketDefinitions, handleClose, handleError, handleMessage, handleUpgrade, invalidateRouteCache, migrateDatabase, parseCron, rawSql as raw, rawSql, rawSql as sqlRaw, registerDb0Create, registerWebSocket, resetCronRunCounts, resolveRouteCacheRules, runMigrations, runScheduledTask, sendMessage, sendMessages, serveStatic, setGlobalTracer, setQueueDriver, sseHeaders, startCronScheduler, startQueueWorkers, startSpan, stopQueueWorkers, useCacheStore, useDatabase, useKV, useQueueDriver, useStorage, validateCron, withSpan };
+export { type AnalyticsContext, type AnalyticsEvent, type AnalyticsMiddlewareOptions, type AnalyticsProperties, type AnalyticsProvider, type AnalyticsProviderOptions, type AnalyticsRecord, type AnalyticsTrackOptions, type CacheControlOptions, type CacheEntry, type CacheRule, type CacheStore, type CacheWrapOptions, type CachedFunctionOptions, type CdnPurgeAdapter, type ComponentCacheEntry, type ComponentCacheStore, type ContentSecurityPolicyDirectives, type CorsOptions, type CronContext, type CronSchedule, type CronScheduler, type CronTaskDefinition, type CronTaskMeta, type CsrfOptions, type DataCacheMiddlewareOptions, type Database, type DatabaseConnector, type DatabaseConnectorInstance, type DatabaseHooks, type DatabaseOptions, type DefineEmailProviderOptions, type DraftMode, type DraftModeOptions, type DrizzleConfig, type EmailAttachment, type EmailOptions, type EmailProvider, type EmailProviderConfig, type EmailProviderType, type EmailResult, type EmailTransport, type ExperimentAssignment, type ExperimentDefinition, type ExperimentOptions, type FeatureFlagDefinition, type FeatureFlagOptions, type FeatureFlagStore, type FeatureFlagsMiddlewareOptions, type FetchCacheOptions, type FetchInitWithNext, type FlagContext, type FlagEvaluation, type FlagKind, type FlagValue, type KVNamespace, type KVOptions, type LogEmailProviderConfig, type Migration, type MockEmailProviderConfig, type MockEmailTransport, type ObservabilityConfig, type ObservabilityExporter, type ObservabilityHooks, type ObservabilityTracer, type Peer, type PurgeResult, type QueueDefinition, type QueueDriver, type QueueHandler, type QueueMessage, type QueueOptions, type QueueStats, REQUEST_ID_HEADER, type RateLimitInfo, type RateLimitOptions, type RateLimitStore, type RateLimitStoreEntry, type RequestIdOptions, type RevalidationContext, type RevalidationEntry, type RevalidationFetcher, type RevalidationKey, type RevalidationResult, type RouteRule, type SSEConnection, type SSEHandler, type SSEMessage, type SSEOptions, type ScheduledTask, type SchedulerOptions, type SecurityHeadersOptions, type Segment, type SegmentRule, type SendOptions, type SendmailEmailProviderConfig, type ServeStaticOptions, type Session, type SessionData, type SessionOptions, type SessionStore, type SingleFlightOptions, type SmtpEmailProviderConfig, type Span, type SpanAttributes, type SpanContext, type SpanEndOptions, type SpanEvent, type SpanOptions, type SpanStatus, type StorageDriver, type SurrogateKeyHeader, type TracingMiddlewareOptions, type UbeanBindings, type UbeanContext, type UbeanEnv, type UbeanStorage, type UbeanVariables, type UpgradeResult, type Variant, type WebSocketDefinition, type WebSocketHooks, type WebSocketRoom, _resetCdnCache, after, broadcast, broadcastSSE, cacheLife, cacheTag, cachedEventHandler, clearAnalyticsProviders, clearCacheStore, clearComponentCache, clearComponentCacheStore, clearEmailProviders, clearFeatureFlags, clearFetchDataCache, clearGlobalStorage, clearQueueDefinitions, clearRevalidationRegistry, clearSSEState, clearScheduledTasks, clearSentEmails, clearWebSocketState, closeAllSSE, closeDatabases, createAfterMiddleware, createAnalyticsMiddleware, createCacheControlMiddleware, createCacheMiddleware, createCloudflarePurgeAdapter, createComponentMemoryStore, createConsoleExporter, createCorsMiddleware, createCronContext, createCsrfMiddleware, createDataCacheMiddleware, createDraftModeMiddleware, createEmailTransport, createFastlyPurgeAdapter, createFeatureFlagsMiddleware, createFetchMemoizationMiddleware, createKV, createLogAnalyticsProvider, createMemoizedFetch, createMemoryAnalyticsProvider, createMemoryCronScheduler, createMemoryDriver, createMemoryFeatureFlagStore, createMemoryQueueDriver, createMemoryRateLimitStore, createMemoryStore, createMockAnalyticsProvider, createMockPurgeAdapter, createObservabilityTracer, createOpenTelemetryExporter, createRateLimitMiddleware, createRoom, createSSEStream, createSecurityHeadersMiddleware, createSessionMiddleware, createSingleFlightMiddleware, createSpan, createStorage, createStorageSessionStore, createTracingMiddleware, createWebSocketMiddleware, defineAnalytics, defineAnalyticsProvider, defineCachedFunction, defineCors, defineCsrf, defineDatabase, defineDraftMode, defineEmailProvider, defineExperiment, defineFeatureFlag, defineQueue, defineRateLimit, defineRevalidation, defineRoom, defineSSE, defineScheduled, defineSecurityHeaders, defineSessionStore, defineSingleFlight, defineSurrogateKeys, defineWebSocket, disableDraftMode, enableDraftMode, evaluateFlag, evaluateFlagFromContext, evaluateFlagWithReason, extractAnalyticsContext, extractFlagContext, flushAfterCallbacks, formatSSEMessage, generateCsrfToken, generateRequestId, getAfterCallbackCount, getAllQueueStats, getAnalyticsProvider, getDataCacheSize, getDatabaseHooks, getEmailProvider, getEmailProviderNames, getEmailTransport, getGlobalAnalyticsProvider, getGlobalFeatureFlagStore, getGlobalPurgeAdapter, getGlobalTracer, getInvalidatedKeys, getQueueDefinitions, getQueueStats, getRequestId, getRevalidationEntries, getRoom, getRooms, getSSEConnections, getScheduledTasks, getSentEmails, getSpan, getSurrogateKeys, getVariant, getVariantAssignment, getVariantFromContext, getWebSocketDefinitions, handleClose, handleError, handleMessage, handleUpgrade, invalidate, invalidateKey, invalidateRouteCache, isDraftMode, listAnalyticsProviders, listExperimentNames, listFlagNames, migrateDatabase, parseCron, purgeKeys, purgeUrls, rawSql as raw, rawSql, rawSql as sqlRaw, registerAnalyticsProvider, registerDb0Create, registerWebSocket, removeExperiment, removeFeatureFlag, renderEmailTemplate, resetCronRunCounts, resolveRouteCacheRules, revalidateDataCachePath, revalidateDataCacheTag, revalidatePath, revalidateTag, revalidateTags, runMigrations, runRevalidation, runScheduledTask, sendEmail, sendMessage, sendMessages, serializeCsp, serveStatic, setDefaultEmailProvider, setGlobalAnalyticsProvider, setGlobalFeatureFlagStore, setGlobalPurgeAdapter, setGlobalTracer, setQueueDriver, sseHeaders, startCronScheduler, startQueueWorkers, startSpan, stopQueueWorkers, trackEvent, trackPageView, trackRaw, unregisterAnalyticsProvider, unregisterRevalidation, useAnalytics, useCacheStore, useComponentCacheStore, useDatabase, useDraftMode, useEmailProvider, useExperiments, useFlagContext, useFlags, useKV, useQueueDriver, useSession, useStorage, validateCron, withSpan, wrapWithCache };