@velajs/cloudflare 1.10.0 → 1.10.1

package/dist/index.d.ts

@@ -1,41 +1,805 @@
-export { cloudflareAdapter, createCloudflareApp } from './cloudflare-factory';
-export type { CreateCloudflareAppOptions } from './cloudflare-factory';
-export { CloudflareApplication } from './cloudflare-application';
-export type { MountOpenApiOptions } from './cloudflare-application';
-export { KVModule } from './modules/kv.module';
-export { D1Module } from './modules/d1.module';
-export { R2Module } from './modules/r2.module';
-export { QueueModule } from './modules/queue.module';
-export { DurableObjectModule } from './modules/durable-object.module';
-export { AIModule } from './modules/ai.module';
-export { VectorizeModule } from './modules/vectorize.module';
-export { HyperdriveModule } from './modules/hyperdrive.module';
-export { EnvModule } from './modules/env.module';
-export { StorageModule, StorageService, StorageManagerService, StorageController, R2StorageDriver, STORAGE_OPTIONS, } from './storage/index';
-export type { StorageModuleOptions, DiskConfig, PresignedUrlConfig } from './storage/index';
-export { KVService } from './services/kv.service';
-export { KVCacheStore } from './services/kv-cache.store';
-export { D1Service } from './services/d1.service';
-export { R2Service } from './services/r2.service';
-export { QueueService } from './services/queue.service';
-export { DurableObjectService } from './services/durable-object.service';
-export { AIService } from './services/ai.service';
-export { VectorizeService } from './services/vectorize.service';
-export { HyperdriveService } from './services/hyperdrive.service';
-export { EnvService } from './services/env.service';
-export { FlagshipFlagDriver, flagshipFlagDriver } from './services/flagship-flag.driver';
-export type { FlagshipBinding, FlagshipFlagDriverOptions } from './services/flagship-flag.driver';
-export { KvFlagDriver, kvFlagDriver } from './services/kv-flag.driver';
-export type { KvFlagDriverOptions } from './services/kv-flag.driver';
-export { Env } from './decorators/env';
-export { Scheduled } from './decorators/scheduled';
-export { QueueConsumer } from './decorators/queue-consumer';
-export { VelaWebSocketDurableObject, CloudflareWebSocketModule, broadcastToRoom, } from './websocket/index';
-export type { WsGatewayRoute } from './websocket/index';
-export { DoCursorLog, durableObjectCursorLog, durableObjectLive, liveInvalidateToRoom, } from './websocket/index';
-export type { CfLiveDriver, DurableObjectLiveOptions } from './websocket/index';
-export { WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer, WsException, } from '@velajs/vela/websocket';
-export type { WsClient, WsServer, WsResponse, WsMessage, OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect, } from '@velajs/vela/websocket';
-export type { CloudflareEnv, ScheduledRegistration, QueueRegistration } from './types';
-export type { ScheduledMetadata } from './decorators/scheduled';
-export type { QueueConsumerMetadata } from './decorators/queue-consumer';
+import { AsyncCacheStore, DynamicModule, InjectionToken, RuntimeAdapter, Type, VelaApplication } from "@velajs/vela";
+import { ConnectedSocket, MessageBody, OnGatewayConnection, OnGatewayDisconnect, OnGatewayInit, SubscribeMessage, WebSocketGateway, WebSocketServer, WsClient, WsDispatcher, WsException, WsMessage, WsResponse, WsServer } from "@velajs/vela/websocket";
+import { CommitStamp, CursorLog, LiveDriver, ResumeVerdict } from "@velajs/vela/live";
+import { DownloadResult, PresignMethod, PresignedUrlResult, StorageBody, StorageDriver, UploadOptions, UploadResult } from "@velajs/vela/storage";
+import { DurableObject } from "cloudflare:workers";
+import { Context, Hono, MiddlewareHandler } from "hono";
+import { FeatureFlagDriver, FlagContext } from "@velajs/feature-flags";
+//#region src/websocket/websocket-routing.d.ts
+interface WsGatewayRoute {
+  path: string;
+  binding: string;
+}
+//#endregion
+//#region src/types.d.ts
+interface CloudflareEnv {
+  [key: string]: unknown;
+}
+interface ScheduledRegistration {
+  instance: unknown;
+  methodName: string;
+  cron: string;
+}
+interface QueueRegistration {
+  instance: unknown;
+  methodName: string;
+  queueName: string;
+}
+//#endregion
+//#region src/cloudflare-application.d.ts
+/**
+ * Options accepted by {@link CloudflareApplication.mountOpenApi}.
+ *
+ * Re-exposes vela's `MountOpenApiOptions` type — derived structurally from
+ * the underlying `VelaApplication.mountOpenApi` signature so consumers don't
+ * have to reach into vela's internal subpaths to type the argument.
+ */
+type MountOpenApiOptions = Parameters<VelaApplication['mountOpenApi']>[0];
+/**
+ * Wraps VelaApplication with Cloudflare-specific handlers:
+ * - `fetch` — HTTP request handler (from Hono)
+ * - `scheduled` — Cron trigger handler (matches `@Scheduled()` decorators
+ *                 AND vela's own `@Cron()` jobs)
+ * - `queue` — Queue consumer handler (matches `@QueueConsumer()` decorators)
+ * - `mountOpenApi` — Serve an OpenAPI document (and optional Scalar UI) on
+ *                    the underlying Hono app
+ *
+ * @example
+ * ```ts
+ * const app = await createCloudflareApp(AppModule);
+ * export default {
+ *   fetch: app.fetch,
+ *   scheduled: app.scheduled.bind(app),
+ *   queue: app.queue.bind(app),
+ * };
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Serve OpenAPI docs alongside your routes
+ * const app = await createCloudflareApp(AppModule);
+ * const document = createOpenApiDocument(AppModule);
+ * app.mountOpenApi({ document, ui: 'scalar' });
+ * // GET /openapi.json -> JSON document
+ * // GET /scalar       -> Scalar UI (loads from CDN)
+ * ```
+ */
+declare class CloudflareApplication {
+  private app;
+  private wsGatewayRoutes;
+  constructor(app: VelaApplication);
+  get fetch(): Hono['fetch'];
+  getHonoApp(): Hono;
+  /**
+   * Resolve a provider from the application's DI container (delegates to
+   * `VelaApplication.get`). Handy for grabbing a service — e.g. an auth service —
+   * to use inside `createCloudflareApp({ middleware: [...] })` request middleware,
+   * which runs outside the DI request pipeline.
+   *
+   * @example
+   * ```ts
+   * const app = await createCloudflareApp(AppModule);
+   * const auth = app.get<BetterAuthService>(BetterAuthService);
+   * ```
+   */
+  get<T>(token: Parameters<VelaApplication['get']>[0]): T;
+  /**
+   * Serve a pre-built OpenAPI document (and optionally a Scalar UI) on the
+   * underlying Hono app. Delegates verbatim to `VelaApplication.mountOpenApi`,
+   * so the JSON endpoint defaults to `/openapi.json` and the Scalar UI (when
+   * opted in) defaults to `/scalar`. Edge-safe — the UI HTML loads Scalar from
+   * a CDN at runtime, nothing is bundled server-side.
+   *
+   * @example
+   * ```ts
+   * import { createOpenApiDocument } from '@velajs/vela';
+   *
+   * const app = await createCloudflareApp(AppModule);
+   * const document = createOpenApiDocument(AppModule, {
+   *   info: { title: 'My API', version: '1.0.0' },
+   * });
+   * app.mountOpenApi({ document, ui: 'scalar' });
+   * // GET /openapi.json -> { openapi: '3.1.0', ... }
+   * // GET /scalar       -> Scalar UI HTML
+   * ```
+   */
+  mountOpenApi(options: MountOpenApiOptions): this;
+  /**
+   * @internal — scans instances for `@WebSocketGateway({ path, binding })`
+   * upgrade routes. Queue/scheduled handlers are NOT scanned anymore: they
+   * come from `app.entrypoints` (`cf:queue` / `cf:scheduled` / `cf:vela-cron`
+   * kinds) at dispatch time.
+   */
+  scanInstances(instances: unknown[]): void;
+  /** @internal — upgrade routes discovered from `@WebSocketGateway({ path, binding })`. */
+  getWsGatewayRoutes(): WsGatewayRoute[];
+  /**
+   * Handle Cloudflare scheduled (cron) events.
+   * Matches the event's cron expression to `@Scheduled()` and vela `@Cron()`
+   * handlers read from `app.entrypoints`; each handler runs inside a fresh
+   * request-scoped child (request-scoped providers rebuild per tick).
+   */
+  scheduled(event: {
+    cron: string;
+    scheduledTime?: number;
+  }, env: CloudflareEnv, ctx: {
+    waitUntil: (promise: Promise<unknown>) => void;
+  }): Promise<void>;
+  /**
+   * Run one entrypoint handler inside a fresh request scope, through the
+   * shared guard → interceptor pipeline (components declared with
+   * `@UseGuards`/`@UseInterceptors`/`@UseFilters` on the consumer class or
+   * method). HTTP-global components deliberately do NOT apply — an HTTP auth
+   * guard has no business rejecting a queue batch. Unclaimed errors rethrow
+   * so the platform's retry semantics stay intact.
+   */
+  private dispatchEntrypoint;
+  /**
+   * Handle Cloudflare Queue consumer events.
+   * Matches the batch queue name to `@QueueConsumer()` handlers read from
+   * `app.entrypoints`; each batch is processed inside a fresh request-scoped
+   * child (request-scoped providers rebuild per batch — no boot-time captives).
+   */
+  queue(batch: {
+    queue: string;
+    messages: unknown[];
+  }, env: CloudflareEnv, ctx: {
+    waitUntil: (promise: Promise<unknown>) => void;
+  }): Promise<void>;
+  close(signal?: string): Promise<void>;
+}
+//#endregion
+//#region src/cloudflare-factory.d.ts
+/**
+ * Options for {@link createCloudflareApp}.
+ *
+ * Mirrors a tight subset of vela's `BootstrapOptions` — only the surface
+ * that makes sense for a Workers consumer is re-exposed.
+ */
+interface CreateCloudflareAppOptions {
+  /**
+   * Forwarded to `VelaFactory.create({ globalPrefix })`. Prepended to every
+   * route registered by `@Controller(...)` (and any other route emitter)
+   * inside the application, so a value of `'/v1'` turns `@Controller('/users')`
+   * into `/v1/users`.
+   *
+   * @example
+   * ```ts
+   * const app = await createCloudflareApp(AppModule, { globalPrefix: '/v1' });
+   * ```
+   */
+  globalPrefix?: string;
+  /**
+   * Extra Hono middleware to register on the underlying Hono app. Runs
+   * AFTER the one-time binding-init middleware this adapter mounts
+   * internally, so any handler in `middleware` can safely read from
+   * `BindingRef` instances and Cloudflare env bindings.
+   *
+   * @example
+   * ```ts
+   * const app = await createCloudflareApp(AppModule, {
+   *   middleware: [
+   *     async (c, next) => {
+   *       c.set('requestId', crypto.randomUUID());
+   *       await next();
+   *     },
+   *   ],
+   * });
+   * ```
+   */
+  middleware?: MiddlewareHandler[];
+}
+/**
+ * Create a Cloudflare Workers application.
+ *
+ * Sets up a one-time Hono middleware that captures `c.env` on the first
+ * request and initializes all configured binding refs. Optional
+ * {@link CreateCloudflareAppOptions} are forwarded to the underlying
+ * `VelaFactory.create` so consumers don't have to wrap the resulting
+ * application in an outer Hono just to set a `globalPrefix` or attach
+ * extra request middleware.
+ *
+ * @example
+ * ```ts
+ * // Minimal — backwards compatible
+ * const app = await createCloudflareApp(AppModule);
+ * export default app; // has .fetch, .scheduled, .queue
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With a global prefix and outer middleware
+ * const app = await createCloudflareApp(AppModule, {
+ *   globalPrefix: '/v1',
+ *   middleware: [
+ *     async (c, next) => {
+ *       c.set('tenantId', c.req.header('x-tenant-id') ?? 'public');
+ *       await next();
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+/**
+ * The Cloudflare platform binding as a vela {@link RuntimeAdapter}: a one-time
+ * request middleware captures `c.env` on the first request and initializes
+ * every `BindingRef`/`EnvRef` (collected at `onBootstrap`, before any request
+ * can arrive). Adapter `requestMiddleware` is prepended to the global chain by
+ * `VelaFactory.create`, so user middleware can safely read binding refs.
+ *
+ * Exposed so consumers composing `VelaFactory.create` themselves can opt in:
+ *
+ * ```ts
+ * const app = await VelaFactory.create(AppModule, { adapters: [cloudflareAdapter()] });
+ * ```
+ */
+declare function cloudflareAdapter(): RuntimeAdapter;
+declare function createCloudflareApp(rootModule: Type, options?: CreateCloudflareAppOptions): Promise<CloudflareApplication>;
+//#endregion
+//#region src/binding-ref.d.ts
+declare class BindingRef<T = unknown> {
+  readonly bindingName: string;
+  private _value;
+  constructor(bindingName: string);
+  get value(): T;
+  /** @internal — called by createCloudflareApp middleware */
+  _initialize(value: T): void;
+}
+//#endregion
+//#region src/modules/create-binding-module.d.ts
+interface BindingModuleStatic {
+  forRoot(options: {
+    binding: string;
+  }): DynamicModule;
+}
+//#endregion
+//#region src/modules/kv.module.d.ts
+declare const KVModule: BindingModuleStatic;
+//#endregion
+//#region src/modules/d1.module.d.ts
+declare const D1Module: BindingModuleStatic;
+//#endregion
+//#region src/modules/r2.module.d.ts
+declare const R2Module: BindingModuleStatic;
+//#endregion
+//#region src/modules/queue.module.d.ts
+declare const QueueModule: BindingModuleStatic;
+//#endregion
+//#region src/modules/durable-object.module.d.ts
+declare const DurableObjectModule: BindingModuleStatic;
+//#endregion
+//#region src/modules/ai.module.d.ts
+declare const AIModule: BindingModuleStatic;
+//#endregion
+//#region src/modules/vectorize.module.d.ts
+declare const VectorizeModule: BindingModuleStatic;
+//#endregion
+//#region src/modules/hyperdrive.module.d.ts
+declare const HyperdriveModule: BindingModuleStatic;
+//#endregion
+//#region src/modules/env.module.d.ts
+/**
+ * Provides {@link EnvService} GLOBALLY so any module's provider factories can
+ * `inject: [EnvService]`. Register once on the root module:
+ *
+ * ```ts
+ * @Module({ imports: [EnvModule.forRoot(), AuthModule.forRootAsync({ ... })] })
+ * class AppModule {}
+ * ```
+ *
+ * The {@link EnvRef} it provides is collected and initialized by
+ * createCloudflareApp's binding-init middleware on the first request (the
+ * factory passes it the full `env`, not a single binding).
+ */
+declare class EnvModule {
+  static forRoot(): DynamicModule;
+}
+//#endregion
+//#region src/storage/storage.types.d.ts
+/** A named storage disk backed by an R2 bucket binding. */
+interface DiskConfig {
+  disk: string;
+  /** R2Bucket binding name from wrangler.toml. */
+  binding: string;
+  /** Optional root prefix; supports path-template tokens ({date}/{year}/…). */
+  root?: string;
+}
+interface PresignedUrlConfig {
+  defaultExpiry: number;
+  maxExpiry: number;
+}
+interface StorageModuleOptions {
+  disks: DiskConfig[];
+  defaultDisk: string;
+  presignedUrl?: PresignedUrlConfig;
+}
+//#endregion
+//#region src/storage/storage.module.d.ts
+declare const ConfigurableModuleClass: import("@velajs/vela").ConfigurableModuleClassType<StorageModuleOptions, "forRoot", "create", {
+  isGlobal?: boolean;
+}>;
+declare class StorageModule extends ConfigurableModuleClass {}
+//#endregion
+//#region src/env-ref.d.ts
+/**
+ * Holds the entire Cloudflare Worker `env` record (bindings + vars/secrets),
+ * not a single binding. Subclasses {@link BindingRef} so createCloudflareApp's
+ * binding-init middleware collects and initializes it through the same path;
+ * the factory special-cases it to pass the full `env` instead of one binding.
+ */
+declare class EnvRef extends BindingRef<Record<string, unknown>> {
+  constructor();
+}
+//#endregion
+//#region src/services/env.service.d.ts
+/**
+ * Injectable access to the full Cloudflare Worker `env` (bindings + vars +
+ * secrets).
+ *
+ * The per-binding services (`D1Service`, `KVService`, …) each expose a single
+ * binding, and the `@Env()` param decorator only works inside a request-scoped
+ * controller handler. `EnvService` fills the gap: it can be injected into
+ * PROVIDER FACTORIES — e.g. `SomeModule.forRootAsync({ inject: [EnvService] })`
+ * — so a factory can read secrets/origins without reaching for the request.
+ *
+ * Reads are lazy. `env` only exists per request, so a factory (which runs at
+ * bootstrap) must capture the `EnvService` and read inside its callback:
+ *
+ * ```ts
+ * AuthModule.forRootAsync({
+ *   inject: [EnvService],
+ *   useFactory: (env: EnvService) => buildAuth(() => env.get<string>('AUTH_SECRET')),
+ * });
+ * ```
+ *
+ * Reading eagerly at bootstrap (`env.get(...)` before any request) throws.
+ */
+declare class EnvService {
+  private ref;
+  constructor(ref: EnvRef);
+  /** The full env record. Throws if read before the first request. */
+  get env(): Record<string, unknown>;
+  /** Read a single env entry (binding, var, or secret) by name. */
+  get<T = unknown>(key: string): T | undefined;
+}
+//#endregion
+//#region src/storage/r2-storage.driver.d.ts
+interface R2StorageDriverConfig {
+  disk: string;
+  bucket: R2Bucket;
+  /** HMAC secret for presigned URLs (typically env.APP_SECRET). */
+  secret?: string;
+}
+/** {@link StorageDriver} over a Cloudflare R2 bucket. */
+declare class R2StorageDriver implements StorageDriver {
+  private readonly config;
+  constructor(config: R2StorageDriverConfig);
+  upload(body: StorageBody, path: string, options: UploadOptions): Promise<UploadResult>;
+  download(path: string): Promise<DownloadResult>;
+  delete(path: string): Promise<void>;
+  exists(path: string): Promise<boolean>;
+  getPresignedUrl(path: string, method: PresignMethod, expiresIn: number): Promise<PresignedUrlResult>;
+}
+//#endregion
+//#region src/storage/storage-manager.service.d.ts
+/**
+ * Resolves R2 buckets by binding NAME (via {@link EnvService}) so multiple disks
+ * coexist without registering N R2Modules. Drivers are created per call — cheap,
+ * and avoids caching a per-request env value on this singleton.
+ */
+declare class StorageManagerService {
+  private readonly options;
+  private readonly env;
+  constructor(options: StorageModuleOptions, env: EnvService);
+  hasDisk(disk: string): boolean;
+  getDiskConfig(disk: string): DiskConfig;
+  getDriver(disk: string): R2StorageDriver;
+}
+//#endregion
+//#region src/storage/storage.service.d.ts
+/**
+ * Multi-disk storage facade. Applies each disk's (templated) root, resolves the
+ * driver, and validates presign expiry. Injectable anywhere via `StorageService`.
+ */
+declare class StorageService {
+  private readonly options;
+  private readonly manager;
+  constructor(options: StorageModuleOptions, manager: StorageManagerService);
+  put(relativePath: string, body: StorageBody, options?: UploadOptions, disk?: string): Promise<UploadResult>;
+  get(relativePath: string, disk?: string): Promise<DownloadResult>;
+  delete(relativePath: string, disk?: string): Promise<void>;
+  exists(relativePath: string, disk?: string): Promise<boolean>;
+  url(relativePath: string, method?: PresignMethod, expiresIn?: number, disk?: string): Promise<PresignedUrlResult>;
+  private resolveDisk;
+  private fullPath;
+  private validateExpiry;
+}
+//#endregion
+//#region src/storage/storage.controller.d.ts
+/**
+ * Presign-proxy: serves objects for HMAC-signed URLs produced by
+ * `StorageService.url()`. R2 has no native presign, so a signed URL points here;
+ * this route verifies the signature (+expiry) before streaming the object.
+ * The wildcard is the FULL object path (root already applied at sign time), so
+ * it is passed straight to the driver.
+ */
+declare class StorageController {
+  private readonly manager;
+  private readonly env;
+  constructor(manager: StorageManagerService, env: EnvService);
+  download(c: Context): Promise<Response>;
+}
+//#endregion
+//#region src/storage/storage.tokens.d.ts
+declare const STORAGE_OPTIONS: InjectionToken<StorageModuleOptions>;
+//#endregion
+//#region src/services/kv.service.d.ts
+/**
+ * Wrapper around a Cloudflare KV namespace binding.
+ * Use `kv.namespace.get(...)`, `kv.namespace.put(...)`, etc. — the namespace
+ * is the standard @cloudflare/workers-types `KVNamespace`.
+ */
+declare class KVService {
+  private ref;
+  constructor(ref: BindingRef<KVNamespace>);
+  get namespace(): KVNamespace;
+}
+//#endregion
+//#region src/services/kv-cache.store.d.ts
+/**
+ * Cloudflare KV-backed {@link CacheStore}. Values are JSON-encoded. Intended as
+ * the slow tier under a `TieredCacheStore` (memory L1 → KV L2), but usable
+ * standalone as `CacheModule.forRootAsync({ inject: [KVService], useFactory: (kv) => ({ store: new KVCacheStore(kv) }) })`.
+ *
+ * Note: Cloudflare KV requires `expirationTtl >= 60s`, so sub-minute TTLs are
+ * clamped up. Keep short TTLs on the memory tier; use KV for longer-lived entries.
+ */
+declare class KVCacheStore implements AsyncCacheStore {
+  private readonly kv;
+  constructor(kv: KVService);
+  private get ns();
+  get<T = unknown>(key: string): Promise<T | undefined>;
+  set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>;
+  del(key: string): Promise<void>;
+  clear(): Promise<void>;
+}
+//#endregion
+//#region src/services/d1.service.d.ts
+declare class D1Service {
+  private ref;
+  constructor(ref: BindingRef<D1Database>);
+  get database(): D1Database;
+}
+//#endregion
+//#region src/services/r2.service.d.ts
+declare class R2Service {
+  private ref;
+  constructor(ref: BindingRef<R2Bucket>);
+  get bucket(): R2Bucket;
+}
+//#endregion
+//#region src/services/queue.service.d.ts
+declare class QueueService<Body = unknown> {
+  private ref;
+  constructor(ref: BindingRef<Queue<Body>>);
+  get queue(): Queue<Body>;
+}
+//#endregion
+//#region src/services/durable-object.service.d.ts
+declare class DurableObjectService {
+  private ref;
+  constructor(ref: BindingRef<DurableObjectNamespace>);
+  get namespace(): DurableObjectNamespace;
+}
+//#endregion
+//#region src/services/ai.service.d.ts
+declare class AIService {
+  private ref;
+  constructor(ref: BindingRef<Ai>);
+  get binding(): Ai;
+}
+//#endregion
+//#region src/services/vectorize.service.d.ts
+declare class VectorizeService {
+  private ref;
+  constructor(ref: BindingRef<VectorizeIndex>);
+  get index(): VectorizeIndex;
+}
+//#endregion
+//#region src/services/hyperdrive.service.d.ts
+declare class HyperdriveService {
+  private ref;
+  constructor(ref: BindingRef<Hyperdrive>);
+  get binding(): Hyperdrive;
+  get connectionString(): string;
+  get host(): string;
+  get port(): number;
+  get user(): string;
+  get password(): string;
+  get database(): string;
+}
+//#endregion
+//#region src/services/flagship-flag.driver.d.ts
+/**
+ * The subset of a Cloudflare **Flagship** binding this driver evaluates against
+ * — the four typed value methods. The binding itself returns the supplied
+ * `defaultValue` on evaluation errors; transport-level failures reject and are
+ * left to propagate (never-throw is the service layer's job, not the driver's).
+ *
+ * @see https://developers.cloudflare.com/flagship/binding/
+ */
+interface FlagshipBinding {
+  getBooleanValue(key: string, defaultValue: boolean, context?: FlagContext): Promise<boolean>;
+  getStringValue(key: string, defaultValue: string, context?: FlagContext): Promise<string>;
+  getNumberValue(key: string, defaultValue: number, context?: FlagContext): Promise<number>;
+  getObjectValue<T extends object>(key: string, defaultValue: T, context?: FlagContext): Promise<T>;
+}
+interface FlagshipFlagDriverOptions {
+  /** Driver name used for `use(name)` / default-driver selection. Default `"flagship"`. */
+  name?: string;
+}
+/**
+ * {@link FeatureFlagDriver} backed by a Cloudflare Flagship binding.
+ *
+ * A thin, honest wrapper: each contract method maps 1:1 onto the binding's
+ * corresponding value method, forwarding the caller's `fallback` (the binding's
+ * `defaultValue`) and evaluation context. The binding resolves the fallback on
+ * evaluation errors; anything the binding *rejects* with (e.g. a `remote: true`
+ * dev-proxy tunnel dropping) propagates — `@velajs/feature-flags`'s service owns
+ * the never-throw guarantee.
+ *
+ * The binding only exists per request in a Worker, so pass a lazy accessor when
+ * wiring from a bootstrap factory (mirroring how {@link EnvService} reads are
+ * deferred); a resolved binding may be passed directly in tests.
+ *
+ * ```ts
+ * FeatureFlagsModule.forRootAsync({
+ *   inject: [EnvService],
+ *   useFactory: (env: EnvService) => ({
+ *     drivers: [flagshipFlagDriver(() => env.get<FlagshipBinding>('FLAGS')!)],
+ *   }),
+ * });
+ * ```
+ *
+ * Evaluation ergonomics (the 1:1 binding-method mapping) are ported from the
+ * Stratal feature-flags service (MIT, © Temitayo Fadojutimi), reshaped as a
+ * bare driver.
+ */
+declare class FlagshipFlagDriver implements FeatureFlagDriver {
+  readonly name: string;
+  private readonly resolve;
+  constructor(binding: FlagshipBinding | (() => FlagshipBinding), options?: FlagshipFlagDriverOptions);
+  getBoolean(key: string, fallback: boolean, ctx?: FlagContext): Promise<boolean>;
+  getString(key: string, fallback: string, ctx?: FlagContext): Promise<string>;
+  getNumber(key: string, fallback: number, ctx?: FlagContext): Promise<number>;
+  getObject<T extends object>(key: string, fallback: T, ctx?: FlagContext): Promise<T>;
+}
+/** Convenience factory for {@link FlagshipFlagDriver}. */
+declare function flagshipFlagDriver(binding: FlagshipBinding | (() => FlagshipBinding), options?: FlagshipFlagDriverOptions): FlagshipFlagDriver;
+//#endregion
+//#region src/services/kv-flag.driver.d.ts
+interface KvFlagDriverOptions {
+  /** Driver name used for `use(name)` / default-driver selection. Default `"kv"`. */
+  name?: string;
+  /** Prefix prepended to every flag key before the KV read. Default `""` (none). */
+  prefix?: string;
+}
+/**
+ * Cloudflare KV-backed {@link FeatureFlagDriver}. Flags are stored as JSON
+ * values under an optional key prefix and read with `get(key, 'json')`. Reads
+ * are type-checked against the requested type: a missing key or a value of the
+ * wrong JSON type returns the caller's `fallback`. KV has no targeting, so the
+ * evaluation context is ignored.
+ *
+ * The driver stays honest — it does **not** swallow errors. A KV failure (or a
+ * `SyntaxError` from a malformed stored value) propagates; the never-throw
+ * guarantee lives in `@velajs/feature-flags`'s service layer.
+ *
+ * Placed like {@link KVCacheStore}: construct it in a wiring factory over a
+ * resolved {@link KVService}.
+ *
+ * ```ts
+ * FeatureFlagsModule.forRootAsync({
+ *   inject: [KVService],
+ *   useFactory: (kv: KVService) => ({ drivers: [new KvFlagDriver(kv, { prefix: 'flag:' })] }),
+ * });
+ * ```
+ */
+declare class KvFlagDriver implements FeatureFlagDriver {
+  private readonly kv;
+  readonly name: string;
+  private readonly prefix;
+  constructor(kv: KVService, options?: KvFlagDriverOptions);
+  private get ns();
+  getBoolean(key: string, fallback: boolean, _ctx?: FlagContext): Promise<boolean>;
+  getString(key: string, fallback: string, _ctx?: FlagContext): Promise<string>;
+  getNumber(key: string, fallback: number, _ctx?: FlagContext): Promise<number>;
+  getObject<T extends object>(key: string, fallback: T, _ctx?: FlagContext): Promise<T>;
+  /**
+   * Reads and JSON-parses the (prefixed) key, returning the parsed value only
+   * when `matches` accepts its type; otherwise the caller's fallback. A missing
+   * key reads as `null` → fallback. Read/parse errors are left to propagate.
+   */
+  private read;
+}
+/** Convenience factory for {@link KvFlagDriver}. */
+declare function kvFlagDriver(kv: KVService, options?: KvFlagDriverOptions): KvFlagDriver;
+//#endregion
+//#region src/decorators/env.d.ts
+/**
+ * Parameter decorator to inject Cloudflare environment bindings.
+ *
+ * Without arguments, returns the entire `env` object.
+ * With a binding name, returns that specific binding.
+ *
+ * @example
+ * ```ts
+ * @Get()
+ * handle(@Env() env: CloudflareEnv) { ... }
+ *
+ * @Get()
+ * handle(@Env('MY_KV') kv: KVNamespace) { ... }
+ * ```
+ */
+declare const Env: (data?: string | undefined, ...pipes: import("@velajs/vela").PipeType[]) => ParameterDecorator;
+//#endregion
+//#region src/decorators/scheduled.d.ts
+interface ScheduledMetadata {
+  cron: string;
+  methodName: string;
+}
+/**
+ * Marks a method as a scheduled (cron) handler.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * class WorkerService {
+ *   @Scheduled('0 * * * *')
+ *   async hourlyCron() {
+ *     console.log('Running hourly');
+ *   }
+ * }
+ * ```
+ */
+declare function Scheduled(cron: string): MethodDecorator;
+//#endregion
+//#region src/decorators/queue-consumer.d.ts
+interface QueueConsumerMetadata {
+  queueName: string;
+  methodName: string;
+}
+/**
+ * Marks a method as a queue consumer handler.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * class WorkerService {
+ *   @QueueConsumer('email-queue')
+ *   async processEmails(batch: MessageBatch) {
+ *     for (const msg of batch.messages) {
+ *       console.log('Processing:', msg.body);
+ *       msg.ack();
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function QueueConsumer(queueName: string): MethodDecorator;
+//#endregion
+//#region src/websocket/websocket.durable-object.d.ts
+/**
+ * Base class for the WebSocket Durable Object. The user exports a named subclass
+ * (matching their `wrangler.toml` `class_name`) built from their `AppModule`:
+ *
+ * ```ts
+ * export class ChatRoom extends VelaWebSocketDurableObject(AppModule) {}
+ * ```
+ *
+ * It owns the raw hibernation socket lifecycle (Hono's `upgradeWebSocket` cannot
+ * bridge DO hibernation) and forwards every event into the runtime-agnostic
+ * `WsDispatcher` via {@link DoWebSocketHost}.
+ */
+declare function VelaWebSocketDurableObject(rootModule: Type): new (ctx: DurableObjectState, env: Record<string, unknown>) => DurableObject<Record<string, unknown>>;
+//#endregion
+//#region src/websocket/cloudflare-websocket.module.d.ts
+/**
+ * Cloudflare counterpart to the core `WebSocketModule.forRoot()`. Import this in
+ * your `AppModule` instead: it provides the gateway dispatcher plus a late-bound
+ * `WS_SERVER` (`WsServerHolder`) that the WebSocket Durable Object wires to a
+ * ctx-backed server per instance. `useClass` ensures a fresh holder per DI
+ * container so colocated DO instances never share a server.
+ */
+declare class CloudflareWebSocketModule {
+  static forRoot(): DynamicModule;
+}
+//#endregion
+//#region src/websocket/broadcast.d.ts
+/**
+ * Push to a room from a Worker HTTP handler / cron / queue consumer (server-
+ * initiated emit). Resolves the room's Durable Object and calls its `broadcast`
+ * RPC method — the same canonical room→DO mapping the upgrade route uses, so it
+ * always reaches the DO holding those sockets.
+ *
+ * @example
+ * ```ts
+ * // In a controller — ns from DurableObjectService.namespace
+ * await broadcastToRoom(ns, `org:${id}`, 'order.created', order);
+ * ```
+ */
+declare function broadcastToRoom(ns: DurableObjectNamespace, room: string, event: string, data?: unknown, options?: {
+  exceptIds?: string[];
+}): Promise<void>;
+//#endregion
+//#region src/websocket/do-state.d.ts
+/** Structural view of the DO's SQLite handle (`ctx.storage.sql`, requires `new_sqlite_classes`). */
+interface SqlStorageLike {
+  exec(query: string, ...bindings: unknown[]): {
+    toArray(): Record<string, unknown>[];
+  };
+}
+//#endregion
+//#region src/websocket/do-live.d.ts
+/**
+ * The durable `CursorLog`: an append-only tag-invalidation log in the DO's
+ * SQLite (`__vela_live_log`, AUTOINCREMENT seq = cursor) plus an epoch UUID in
+ * `__vela_live_meta`. Because the cursor survives hibernation AND trims (it is
+ * read from `sqlite_sequence`, lunora's `ctx-db-cdc.ts` trick), a reconnecting
+ * client whose gap the log still covers gets a tiny `resume` instead of a
+ * re-run — the real-resume half of the live protocol.
+ *
+ * Constructed un-initialized at module-composition time (the same app module
+ * bootstraps in the Worker AND in each DO); `initDoLive` wires the SQLite
+ * handle inside the DO. In the Worker isolate it stays un-initialized — and is
+ * never consulted there, because `durableObjectLive()` routes every
+ * invalidation to the room DO's log (one log scope per room, exactly the
+ * protocol's model).
+ */
+declare class DoCursorLog implements CursorLog {
+  private readonly maxRows;
+  private sql?;
+  private epoch?;
+  constructor(maxRows?: number);
+  /** @internal — called by `initDoLive` with the DO's `ctx.storage.sql`. */
+  _initialize(sql: SqlStorageLike): void;
+  append(tags: string[]): CommitStamp;
+  current(): CommitStamp;
+  evaluateResume(sinceCursor: number, sinceEpoch: string, subscriptionTags: string[]): ResumeVerdict;
+  private assertReady;
+}
+interface DurableObjectLiveOptions {
+  /** The wrangler binding name of the WebSocket DO namespace (e.g. `'CHAT_ROOM'`). */
+  binding: string;
+  /** Room used when an invalidation names none. Matches the client default. */
+  defaultRoom?: string;
+}
+interface CfLiveDriver extends LiveDriver {
+  /** @internal — Worker isolate: capture `env` so the namespace binding resolves per dispatch. */
+  _initializeEnv(env: Record<string, unknown>): void;
+  /** @internal — DO isolate: deliver invalidations straight to this DO's engine. */
+  _setLocalMode(): void;
+}
+/**
+ * The Cloudflare `LiveDriver`. Dual-mode, because the SAME app module
+ * bootstraps in both isolates:
+ *
+ * - **Worker** (HTTP mutations, queue consumers, crons): route the command to
+ *   the room's Durable Object over the `invalidate` RPC — the same canonical
+ *   `roomToDurableId` mapping the upgrade route and `broadcastToRoom` use —
+ *   and return THAT log scope's commit stamp (what `Vela-Commit-Cursor`
+ *   must carry).
+ * - **DO** (writes issued from inside the object): apply to the local engine.
+ */
+declare function durableObjectLive(options: DurableObjectLiveOptions): CfLiveDriver;
+/** Ergonomic alias: the log option for `LiveModule.forRoot` on Cloudflare. */
+declare function durableObjectCursorLog(maxRows?: number): DoCursorLog;
+/**
+ * Invalidate live tags in a room from a Worker (controller / cron / queue
+ * consumer) — the live sibling of `broadcastToRoom`. Returns the room log
+ * scope's commit stamp for `Vela-Commit-Cursor` stamping.
+ */
+declare function liveInvalidateToRoom(ns: DurableObjectNamespace, room: string, tags: string[]): Promise<CommitStamp | undefined>;
+//#endregion
+export { AIModule, AIService, type CfLiveDriver, CloudflareApplication, type CloudflareEnv, CloudflareWebSocketModule, ConnectedSocket, type CreateCloudflareAppOptions, D1Module, D1Service, type DiskConfig, DoCursorLog, type DurableObjectLiveOptions, DurableObjectModule, DurableObjectService, Env, EnvModule, EnvService, type FlagshipBinding, FlagshipFlagDriver, type FlagshipFlagDriverOptions, HyperdriveModule, HyperdriveService, KVCacheStore, KVModule, KVService, KvFlagDriver, type KvFlagDriverOptions, MessageBody, type MountOpenApiOptions, type OnGatewayConnection, type OnGatewayDisconnect, type OnGatewayInit, type PresignedUrlConfig, QueueConsumer, type QueueConsumerMetadata, QueueModule, type QueueRegistration, QueueService, R2Module, R2Service, R2StorageDriver, STORAGE_OPTIONS, Scheduled, type ScheduledMetadata, type ScheduledRegistration, StorageController, StorageManagerService, StorageModule, type StorageModuleOptions, StorageService, SubscribeMessage, VectorizeModule, VectorizeService, VelaWebSocketDurableObject, WebSocketGateway, WebSocketServer, type WsClient, WsException, type WsGatewayRoute, type WsMessage, type WsResponse, type WsServer, broadcastToRoom, cloudflareAdapter, createCloudflareApp, durableObjectCursorLog, durableObjectLive, flagshipFlagDriver, kvFlagDriver, liveInvalidateToRoom };
+//# sourceMappingURL=index.d.ts.map