webspresso 0.0.97 → 0.0.99

package/index.d.ts

@@ -5,6 +5,7 @@
 import type { Application, NextFunction, Request, RequestHandler, Response } from 'express';
 import type { Knex } from 'knex';
 import type { ZodObject, ZodTypeAny } from 'zod';
+import type { EventEmitter } from 'events';
 
 /** Registered as createApp middlewares[name]: plain handler or (options) => handler (for middleware: ['name', options]). */
 export type WebspressoRegisteredMiddleware =
@@ -45,6 +46,7 @@ export interface CreateAppOptions {
         enabled?: boolean;
         stylesheets?: boolean;
         scripts?: boolean;
+        auto?: boolean;
       };
   /** Trust proxy configuration (default: 1) */
   trustProxy?: boolean | number | string;
@@ -66,6 +68,17 @@ export interface CreateAppOptions {
   compression?: boolean | CompressionOptions;
   /** Shutdown and lifecycle configuration */
   shutdown?: ShutdownOptions;
+  /** Development tooling and DX options */
+  dev?: {
+    banner?: boolean;
+    routeTable?: boolean;
+    profiler?: boolean;
+    nPlusOne?: boolean;
+    nPlusOneThreshold?: number;
+    slowQueryMs?: number;
+    verbose?: boolean;
+    colors?: boolean;
+  };
   server?: {
     port?: number;
     shutdown?: ShutdownOptions;
@@ -83,10 +96,84 @@ export interface CreateAppOptions {
   services?: {
     dir?: string;
   };
+  /** Development SSE live/hot reload configuration */
+  devReload?: boolean | DevReloadOptions;
+  /** Client-side JS incremental bundler (esbuild context() API) */
+  bundle?: boolean | DevBundlerOptions;
   setupRoutes?: (app: Application, ctx: SetupRoutesContext) => void;
   [key: string]: unknown;
 }
 
+export interface DevReloadOptions {
+  enabled?: boolean;
+  watch?: string[];
+  watchCss?: boolean;
+  watchTemplates?: boolean;
+  watchPublicAll?: boolean;
+  templateExtensions?: string[];
+  pageExtensions?: string[];
+  autoInject?: boolean;
+  debounce?: number;
+}
+
+export interface DevReloadHub {
+  broadcast(type: 'css' | 'full' | 'error' | 'clear-error' | string, payload?: Record<string, unknown>): void;
+  close(): void;
+  getClientsCount(): number;
+  getWatchersCount(): number;
+  getWatchedPaths(): string[];
+  attachNunjucks(env: unknown): void;
+  setOnTemplateChange(fn: (file?: string) => void): void;
+  invalidateTemplateCache(file?: string): void;
+  triggerTemplateReload(filename?: string, reason?: string): void;
+  triggerCssReload(filename?: string): void;
+  handleSse(req: any, res: any): void;
+  handleScript(req: any, res: any): void;
+  autoInjectMiddleware(req: any, res: any, next: () => void): void;
+}
+
+export interface DevBundlerOptions {
+  enabled?: boolean;
+  entryPoints?: string[] | Record<string, string>;
+  outdir?: string;
+  bundle?: boolean;
+  sourcemap?: boolean;
+  minify?: boolean;
+  target?: string | string[];
+  format?: string;
+  metafile?: boolean;
+  plugins?: any[];
+  esbuild?: any;
+  watch?: boolean;
+  esbuildOptions?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface DevBundler {
+  isAvailable(): boolean;
+  isWatching(): boolean;
+  isDisposed(): boolean;
+  getEntryPoints(): string[] | Record<string, string>;
+  getOutdir(): string;
+  startWatch(): Promise<any>;
+  rebuild(): Promise<any>;
+  dispose(): Promise<void>;
+  getContext(): any;
+}
+
+export interface BuildBundleResult {
+  result: unknown;
+  manifest: Record<string, unknown>;
+  manifestPath: string;
+}
+
+export function createDevBundler(options?: DevBundlerOptions, devReloadHub?: unknown): DevBundler;
+export function buildBundle(options?: DevBundlerOptions): Promise<BuildBundleResult>;
+export function generateManifest(metafile: unknown, options?: unknown): Record<string, unknown>;
+export function createManifestPlugin(options?: unknown): unknown;
+export function findDefaultEntryPoints(cwd?: string): string[] | Record<string, string>;
+export function findPageEntryPoints(cwd?: string): Record<string, string>;
+
 export interface ServiceContext {
   req?: Request;
   res?: Response;
@@ -314,6 +401,11 @@ export interface WebspressoApplication extends Application {
   enableShutdownHooks(): this;
   disableShutdownHooks(): this;
   setErrorHandler(handler: (error: unknown, req: Request, res: Response, next: NextFunction) => Promise<unknown> | unknown): this;
+  broadcastDevReload?(type: 'css' | 'full' | string, payload?: Record<string, unknown>): void;
+  devReloadHub?: DevReloadHub;
+  devBundler?: DevBundler;
+  printDevBanner?(opts?: Record<string, unknown>): void;
+  formatDevBanner?(opts?: Record<string, unknown>): { bannerText: string; plainText: string; summary: Record<string, unknown> };
 }
 
 export interface CreateAppResult {
@@ -326,6 +418,11 @@ export interface CreateAppResult {
 
 export function createApp(options?: CreateAppOptions): CreateAppResult;
 
+export function formatDevBanner(context?: Record<string, unknown>, options?: Record<string, unknown>): { bannerText: string; plainText: string; summary: Record<string, unknown> };
+export function printDevBanner(context?: Record<string, unknown>, options?: Record<string, unknown>): void;
+export function formatRouteTable(routeTable: unknown, options?: Record<string, unknown>): string;
+export function createDevProfilerMiddleware(options?: Record<string, unknown>): RequestHandler;
+
 // --- Exceptions & Errors ---
 
 export interface ErrorOptions {
@@ -444,8 +541,47 @@ export function mountPages(
   registerDynamicFileRoutes: () => void;
 };
 
+export interface CascadingLayoutInfo {
+  layoutRelPath: string;
+  fullPath: string;
+  configPath: string | null;
+}
+
+export namespace cascading {
+  export function getDirectoryChain(relativeFilePath: string): string[];
+  export function templateHasExtends(templateBody?: string | null, fullPath?: string): boolean;
+  export function findCascadingMiddlewareFiles(baseDir: string, relativeFilePath: string, isDev?: boolean): string[];
+  export function loadCascadingMiddlewares(
+    baseDir: string,
+    relativeFilePath: string,
+    middlewareRegistry?: Record<string, unknown>,
+    isDev?: boolean
+  ): Array<(req: any, res: any, next: (err?: any) => void) => void>;
+  export function runMiddleware(mw: Function, req: any, res: any): Promise<void>;
+  export function runMiddlewareChain(chain: Function[], req: any, res: any): Promise<void>;
+  export function findCascadingLayouts(baseDir: string, relativeFilePath: string, isDev?: boolean): CascadingLayoutInfo[];
+  export function executeCascadingLayoutLoads(layouts: CascadingLayoutInfo[], req: any, ctx: any, isDev?: boolean): Promise<void>;
+  export function applyCascadingLayouts(
+    nunjucksEnv: any,
+    layouts: CascadingLayoutInfo[],
+    pageHtml: string,
+    renderContext: Record<string, unknown>,
+    isDev?: boolean
+  ): string;
+  export function clearCascadingCaches(): void;
+}
+
+export function resolveMiddlewares(
+  middlewareConfig: unknown[] | null | undefined,
+  middlewareRegistry?: Record<string, unknown>
+): Array<(req: any, res: any, next: (err?: any) => void) => void>;
+
 export function filePathToRoute(filePath: string, pagesDir: string): string;
 
+export function isRouteGroupSegment(segment: string): boolean;
+
+export function stripRouteGroups(route: string): string;
+
 export function extractMethodFromFilename(filename: string): {
   method: string;
   baseName: string;
@@ -521,6 +657,19 @@ export const utils: Record<string, unknown>;
 
 export class AssetManager {
   constructor(options?: Record<string, unknown>);
+  resolve(assetPath: string): string;
+  asset(assetPath: string): string;
+  js(src: string, attributes?: Record<string, unknown>): string;
+  css(href: string, attributes?: Record<string, unknown>): string;
+  pageJs(name: string, attributes?: Record<string, unknown>): string;
+  pageJsUrl(name: string): string;
+  pageCss(name: string, attributes?: Record<string, unknown>): string;
+  pageCssUrl(name: string): string;
+  hasPageJs(name: string): boolean;
+  hasPageCss(name: string): boolean;
+  getRouteAssetCandidates(routeFile?: string, routePath?: string): string[];
+  pageAssets(nameOrOptions?: string | Record<string, unknown>, attributes?: Record<string, unknown>): string;
+  pageAssetsForRoute(routeFile?: string, routePath?: string, options?: Record<string, unknown>): string;
   [key: string]: unknown;
 }
 
@@ -603,10 +752,111 @@ export interface RelationDefinition {
   localKey?: string;
 }
 
+export interface AdminPermissions {
+  create?: boolean;
+  edit?: boolean;
+  delete?: boolean;
+}
+
+export interface AdminSortConfig {
+  column: string;
+  direction?: 'asc' | 'desc';
+}
+
+export type AdminBadgeColor =
+  | 'green'
+  | 'red'
+  | 'blue'
+  | 'amber'
+  | 'yellow'
+  | 'purple'
+  | 'violet'
+  | 'indigo'
+  | 'gray'
+  | string;
+
+export interface AdminColumnConfig {
+  label?: string;
+  badge?: Record<string, AdminBadgeColor>;
+  hidden?: boolean;
+  readonly?: boolean;
+  sortable?: boolean;
+  [key: string]: unknown;
+}
+
+export interface AdminActionConfig {
+  id: string;
+  label: string;
+  icon?: string;
+  color?: string;
+  models?: string | string[];
+  confirm?: boolean;
+  confirmMessage?: string;
+  showWhen?: Record<string, unknown>;
+  handler?: (record: any, modelName: string, ctx: any) => Promise<unknown> | unknown;
+  visible?: (record: any, modelName: string) => boolean;
+}
+
+export interface AdminBulkActionConfig {
+  id: string;
+  label: string;
+  icon?: string;
+  color?: string;
+  models?: string | string[];
+  confirm?: boolean;
+  confirmMessage?: string;
+  handler?: (records: any[], modelName: string, ctx: any) => Promise<unknown> | unknown;
+}
+
+export interface AdminHookContext<TData = any, TRecord = any> {
+  model: string;
+  data?: TData;
+  record?: TRecord;
+  id?: string | number;
+  req?: any;
+  user?: any;
+  db?: any;
+  stats?: any;
+}
+
+export interface AdminHooksConfig {
+  beforeCreate?: (ctx: AdminHookContext) => Promise<void> | void;
+  afterCreate?: (ctx: AdminHookContext) => Promise<void> | void;
+  beforeUpdate?: (ctx: AdminHookContext) => Promise<void> | void;
+  afterUpdate?: (ctx: AdminHookContext) => Promise<void> | void;
+  beforeDelete?: (ctx: AdminHookContext) => Promise<void> | void;
+  afterDelete?: (ctx: AdminHookContext) => Promise<void> | void;
+  beforeRestore?: (ctx: AdminHookContext) => Promise<void> | void;
+  afterRestore?: (ctx: AdminHookContext) => Promise<void> | void;
+  onRecordView?: (ctx: AdminHookContext) => Promise<void> | void;
+  onDashboardLoad?: (ctx: AdminHookContext) => Promise<void> | void;
+  [key: string]: ((ctx: AdminHookContext) => Promise<void> | void) | undefined;
+}
+
+export interface AdminRelationConfig {
+  displayField?: string;
+  searchFields?: string[];
+  limit?: number;
+  [key: string]: unknown;
+}
+
 export interface AdminMetadata {
   enabled?: boolean;
   label?: string;
   icon?: string | null;
+  group?: string | null;
+  menuOrder?: number | null;
+  listColumns?: string[];
+  searchFields?: string[];
+  displayField?: string;
+  readOnly?: boolean;
+  permissions?: AdminPermissions;
+  defaultSort?: AdminSortConfig;
+  columns?: Record<string, AdminColumnConfig>;
+  actions?: AdminActionConfig[];
+  bulkActions?: AdminBulkActionConfig[];
+  hooks?: AdminHooksConfig;
+  relations?: Record<string, AdminRelationConfig>;
   customFields?: Record<string, unknown>;
   queries?: Record<string, (repo: Repository) => Promise<unknown>>;
 }
@@ -653,6 +903,7 @@ export interface ModelOptions<TSchema extends ZodObject<any> = ZodObject<Record<
     maxIncludes?: number;
     maxFilterConditions?: number;
   };
+  searchable?: string[];
   cache?: boolean | 'auto' | 'smart' | { strategy: 'auto' | 'smart' };
 }
 
@@ -687,6 +938,7 @@ export interface ModelDefinition<TModel = Record<string, any>> {
     maxIncludes?: number;
     maxFilterConditions?: number;
   };
+  searchable?: string[];
   hooks: Record<string, unknown>;
   cache?: boolean | 'auto' | 'smart' | { strategy: 'auto' | 'smart' };
 }
@@ -723,7 +975,10 @@ export function getColumnMeta(schema: ZodTypeAny): unknown;
 
 export interface FindOptions {
   with?: string[];
+  include?: string[];
   select?: string[];
+  limit?: number;
+  offset?: number;
 }
 
 export interface PaginatedResult<T = Record<string, any>> {
@@ -734,6 +989,16 @@ export interface PaginatedResult<T = Record<string, any>> {
   totalPages: number;
 }
 
+export interface SearchOptions {
+  mode?: 'auto' | 'fts' | 'like';
+  language?: string;
+  matchAllWords?: boolean;
+  exact?: boolean;
+  rank?: boolean;
+  ftsTable?: string;
+  boolean?: 'and' | 'or';
+}
+
 export interface QueryBuilder<T = Record<string, any>> {
   where(column: keyof T | string, value: unknown): this;
   where(column: keyof T | string, operator: string, value: unknown): this;
@@ -743,14 +1008,19 @@ export interface QueryBuilder<T = Record<string, any>> {
   whereBetween(column: keyof T | string, range: [unknown, unknown]): this;
   select(...columns: (keyof T | string)[]): this;
   orderBy(column: keyof T | string, direction?: 'asc' | 'desc'): this;
+  orderByRaw(sql: string, bindings?: unknown[]): this;
+  search(term: string, columns?: string | string[], options?: SearchOptions): this;
+  orSearch(term: string, columns?: string | string[], options?: SearchOptions): this;
   limit(n: number): this;
   offset(n: number): this;
   with(...relations: string[]): this;
+  include(...relations: string[]): this;
   withTrashed(): this;
   onlyTrashed(): this;
   first(): Promise<T | null>;
   list(): Promise<T[]>;
   get(): Promise<T[]>;
+  find(): Promise<T[]>;
   count(): Promise<number>;
   paginate(page?: number, perPage?: number): Promise<PaginatedResult<T>>;
   exists(): Promise<boolean>;
@@ -765,6 +1035,7 @@ export interface Repository<T = Record<string, any>> {
   findById(id: string | number, options?: FindOptions): Promise<T | null>;
   findOne(conditions: Partial<T> | Record<string, unknown>, options?: FindOptions): Promise<T | null>;
   findAll(options?: FindOptions): Promise<T[]>;
+  find(conditions?: Partial<T> | Record<string, unknown>, options?: FindOptions): Promise<T[]>;
   create(data: Partial<T> | Record<string, unknown>): Promise<T>;
   createMany(data: (Partial<T> | Record<string, unknown>)[]): Promise<T[]>;
   update(id: string | number, data: Partial<T> | Record<string, unknown>): Promise<T | null>;
@@ -777,6 +1048,8 @@ export interface Repository<T = Record<string, any>> {
   count(conditions?: Partial<T> | Record<string, unknown>): Promise<number>;
   exists(conditions: Partial<T> | Record<string, unknown>): Promise<boolean>;
   with(...relations: string[]): QueryBuilder<T>;
+  include(...relations: string[]): QueryBuilder<T>;
+  search(term: string, columns?: string | string[], options?: SearchOptions): QueryBuilder<T>;
   model: ModelDefinition<T>;
 }
 
@@ -855,8 +1128,30 @@ export interface MigrationManager {
   unlock(): Promise<void>;
 }
 
+export interface WebspressoModels {
+  [key: string]: Record<string, any>;
+}
+
+export interface WebspressoServices {
+  [key: string]: { input: any; output: any };
+}
+
+export interface WebspressoServiceCaller {
+  <K extends keyof WebspressoServices>(
+    name: K,
+    input?: WebspressoServices[K]['input'],
+    opts?: unknown
+  ): Promise<WebspressoServices[K]['output']>;
+  <TInput = unknown, TOutput = unknown>(
+    name: string,
+    input?: TInput,
+    opts?: unknown
+  ): Promise<TOutput>;
+}
+
 export interface TransactionContext {
   trx: Knex.Transaction;
+  getRepository<K extends keyof WebspressoModels>(modelName: K, scopeContext?: ScopeContext): Repository<WebspressoModels[K]>;
   getRepository<T = Record<string, any>>(modelName: string, scopeContext?: ScopeContext): Repository<T>;
   createRepository<T = Record<string, any>>(model: ModelDefinition<T>, scopeContext?: ScopeContext): Repository<T>;
 }
@@ -868,6 +1163,7 @@ export interface DatabaseInstance {
   hasModel(name: string): boolean;
   getAllModels(): ModelDefinition<any>[];
   registerModel<T = Record<string, any>>(model: ModelDefinition<T>): void;
+  getRepository<K extends keyof WebspressoModels>(modelName: K, scopeContext?: ScopeContext): Repository<WebspressoModels[K]>;
   getRepository<T = Record<string, any>>(modelName: string, scopeContext?: ScopeContext): Repository<T>;
   createRepository<T = Record<string, any>>(model: ModelDefinition<T>, scopeContext?: ScopeContext): Repository<T>;
   query<T = Record<string, any>>(modelName: string, scopeContext?: ScopeContext): QueryBuilder<T>;
@@ -974,21 +1270,316 @@ export function validateQueryComplexity(
   includes: string[];
 };
 
-// --- Built-in plugins (subset re-exported from main index.js) ---
+export function buildSearchClause(params: {
+  knex: any;
+  model: any;
+  term: string;
+  columns?: string | string[];
+  options?: SearchOptions;
+}): {
+  raw: true;
+  sql: string;
+  bindings: any[];
+  boolean: 'and' | 'or';
+  rankClause: { sql: string; bindings: any[] } | null;
+} | null;
+
+export function tokenizeSearchTerm(term: string): string[];
+
+export function detectDialect(knex: any): 'sqlite' | 'postgres' | 'mysql' | 'generic';
+
+export interface SchemaExplorerPluginOptions {
+  /** Raw JSON API endpoint path (default: '/_schema') */
+  path?: string;
+  /** Force enable/disable raw API (default: auto based on NODE_ENV) */
+  enabled?: boolean;
+  /** Model names to exclude from schema exploration */
+  exclude?: string[];
+  /** Include column metadata (default: true) */
+  includeColumns?: boolean;
+  /** Include relation metadata (default: true) */
+  includeRelations?: boolean;
+  /** Include scope configuration (default: true) */
+  includeScopes?: boolean;
+  /** Custom authorization check for raw endpoint */
+  authorize?: (req: any) => boolean;
+  /** Register interactive page in Admin Panel when adminPanelPlugin is present (default: true) */
+  admin?: boolean;
+  /** Path within admin panel (default: '/schema') */
+  adminPath?: string;
+  /** Admin sidebar menu label (default: 'Schema Explorer') */
+  menuLabel?: string;
+  /** Admin sidebar icon (default: 'database') */
+  menuIcon?: string;
+  /** Admin sidebar menu order (default: 85) */
+  menuOrder?: number;
+  /** Admin page title (default: menuLabel or 'Schema Explorer') */
+  title?: string;
+  /** Admin page title alias */
+  adminTitle?: string;
+  /** Admin API prefix (default: '/schema') */
+  apiPrefix?: string;
+}
+
+export interface DashboardPluginOptions {
+  /** Base URL path for the developer dashboard (default: '/_webspresso') */
+  path?: string;
+  /** Custom dashboard title displayed in HTML <title> and header (default: 'Webspresso Developer Dashboard') */
+  title?: string;
+  /** Enable or disable the plugin (default: true) */
+  enabled?: boolean;
+}
+
+export function dashboardPlugin(options?: DashboardPluginOptions): WebspressoPlugin;
+export function devToolbarPlugin(options?: DashboardPluginOptions): WebspressoPlugin;
+export function devtoolsPlugin(options?: DashboardPluginOptions): WebspressoPlugin;
+
+export function schemaExplorerPlugin(options?: SchemaExplorerPluginOptions): WebspressoPlugin;
 
-export function schemaExplorerPlugin(options?: Record<string, unknown>): WebspressoPlugin;
+export interface AdminPanelPluginOptions {
+  /** Database instance (required) */
+  db?: any;
+  /** Base URL path for the admin panel (default: '/_admin') */
+  path?: string;
+  /** Enable or disable the plugin (default: true) */
+  enabled?: boolean;
+  /** Custom admin panel title displayed in HTML <title> and header (default: 'Admin Panel') */
+  title?: string;
+  /** Dynamic page title template where %s is page title and %b is base title (default: '%s | %b') */
+  titleTemplate?: string;
+  /** Session secret for admin auth cookie encryption */
+  sessionSecret?: string;
+  /** Auth manager instance for optional user management integration */
+  auth?: any;
+  /** User management configuration */
+  userManagement?: {
+    enabled?: boolean;
+    model?: string;
+    fields?: Record<string, string>;
+  };
+  /** Staff user management option (default: true) */
+  adminUsers?: boolean | { enabled?: boolean };
+  /** Custom registry configuration callback */
+  configure?: (registry: any) => void;
+  /** POST URL for file uploads */
+  uploadUrl?: string;
+  /** Sanitize rich-text HTML values (default: true) */
+  richTextSanitize?: boolean;
+  /** Auto-register data exchange export/import services (default: true) */
+  dataExchange?: boolean;
+  /** Admin login brute-force protection / rate limiting (default: enabled with 5 attempts per 15 mins) */
+  loginRateLimit?: boolean | {
+    enabled?: boolean;
+    maxAttempts?: number;
+    windowMs?: number;
+    blockDurationMs?: number;
+  };
+  [key: string]: unknown;
+}
 
-export function adminPanelPlugin(options?: Record<string, unknown>): WebspressoPlugin;
+export function adminPanelPlugin(options?: AdminPanelPluginOptions): WebspressoPlugin;
 
 export function dataExchangePlugin(options?: Record<string, unknown>): WebspressoPlugin;
 
-export function siteAnalyticsPlugin(options?: Record<string, unknown>): WebspressoPlugin;
+export interface SiteAnalyticsRetentionConfig {
+  enabled?: boolean;
+  days?: number;
+  errorDays?: number;
+  intervalMs?: number;
+  runOnStart?: boolean;
+}
+
+export interface SiteAnalyticsPurgeResult {
+  viewsDeleted: number;
+  errorsDeleted: number;
+  viewsCutoff: string;
+  errorsCutoff: string;
+}
+
+export interface SiteAnalyticsPurgeOptions {
+  days?: number;
+  errorDays?: number;
+  olderThan?: Date;
+  errorsOlderThan?: Date;
+  tableName?: string;
+  errorsTableName?: string;
+}
+
+export interface SiteAnalyticsPluginOptions {
+  db?: any;
+  tableName?: string;
+  errorsTableName?: string;
+  excludePaths?: (string | RegExp)[];
+  excludeBots?: boolean;
+  customBots?: string[];
+  anonymizeIp?: boolean;
+  trustProxy?: boolean;
+  collectErrors?: boolean;
+  dashboard?: boolean;
+  retentionDays?: number;
+  errorRetentionDays?: number;
+  cleanupIntervalMs?: number;
+  autoCleanup?: boolean;
+  cleanupOnStart?: boolean;
+  retention?: boolean | SiteAnalyticsRetentionConfig;
+  [key: string]: unknown;
+}
+
+export function siteAnalyticsPlugin(options?: SiteAnalyticsPluginOptions): WebspressoPlugin & {
+  api?: {
+    purge(options?: SiteAnalyticsPurgeOptions): Promise<SiteAnalyticsPurgeResult>;
+    purgeAnalyticsData(knex: any, options?: SiteAnalyticsPurgeOptions): Promise<SiteAnalyticsPurgeResult>;
+    startCleanup(intervalMs?: number): void;
+    stopCleanup(): void;
+    getRetentionConfig(): SiteAnalyticsRetentionConfig;
+  };
+  dispose?(): void;
+  shutdown?(): void;
+};
+
+export interface AuditLogRetentionConfig {
+  enabled?: boolean;
+  autoCleanup?: boolean;
+  days?: number;
+  intervalMs?: number;
+  runOnStart?: boolean;
+}
+
+export interface AuditLogPluginOptions {
+  db: any;
+  title?: string;
+  adminTitle?: string;
+  pageTitle?: string;
+  adminPath?: string;
+  tableName?: string;
+  includeDefaultPage?: boolean;
+  apiPrefix?: string;
+  registerRecordAction?: boolean;
+  retentionDays?: number;
+  cleanupIntervalMs?: number;
+  autoCleanup?: boolean;
+  cleanupOnStart?: boolean;
+  cleanupStartDelayMs?: number;
+  retention?: boolean | AuditLogRetentionConfig;
+  [key: string]: unknown;
+}
+
+export function auditLogPlugin(options?: AuditLogPluginOptions): WebspressoPlugin & {
+  api?: {
+    purge(options?: { tableName?: string; days?: number; retentionDays?: number; olderThan?: Date | string | number }): Promise<number>;
+    purgeAuditLogs(knex?: any, options?: { tableName?: string; days?: number; retentionDays?: number; olderThan?: Date | string | number }): Promise<number>;
+    startCleanup(intervalMs?: number): void;
+    stopCleanup(): void;
+    getRetentionConfig(): AuditLogRetentionConfig;
+    queryLogs(filters?: Record<string, unknown>): Promise<any[]>;
+    queryTimeline(model: string, recordId: string | number): Promise<any[]>;
+    getRecordTimeline(model: string, recordId: string | number): Promise<any[]>;
+    getMigrationTemplate(tableName?: string): string;
+  };
+  dispose?(): void;
+  shutdown?(): void;
+};
+
+export interface EmailRetentionConfig {
+  enabled?: boolean;
+  autoCleanup?: boolean;
+  days?: number;
+  intervalMs?: number;
+  runOnStart?: boolean;
+}
+
+export interface EmailPluginOptions {
+  db?: any;
+  title?: string;
+  adminTitle?: string;
+  transport?: any;
+  smtp?: any;
+  defaults?: Record<string, unknown>;
+  templatesDir?: string;
+  templates?: Record<string, string>;
+  tableName?: string;
+  includeAdminPage?: boolean;
+  adminPath?: string;
+  apiPrefix?: string;
+  auth?: any;
+  authEmails?: any;
+  emailTemplates?: any;
+  manifest?: any;
+  logToDb?: boolean;
+  retentionDays?: number;
+  cleanupIntervalMs?: number;
+  autoCleanup?: boolean;
+  cleanupOnStart?: boolean;
+  cleanupStartDelayMs?: number;
+  retention?: boolean | EmailRetentionConfig;
+  [key: string]: unknown;
+}
 
-export function auditLogPlugin(options?: Record<string, unknown>): WebspressoPlugin;
+export function emailPlugin(options?: EmailPluginOptions): WebspressoPlugin & {
+  api?: {
+    send(options: Record<string, unknown>): Promise<any>;
+    sendTemplate(name: string, options: Record<string, unknown>): Promise<any>;
+    preview(nameOrOpts: any, data?: Record<string, unknown>): Promise<any>;
+    registerTemplate(id: string, source: string): void;
+    listTemplates(): any[];
+    verifyConnection(): Promise<any>;
+    queryLogs(filters?: Record<string, unknown>): Promise<any>;
+    purge(options?: { tableName?: string; days?: number; retentionDays?: number; olderThan?: Date | string | number }): Promise<number>;
+    purgeLogs(options?: { tableName?: string; days?: number; retentionDays?: number; olderThan?: Date | string | number }): Promise<number>;
+    startCleanup(intervalMs?: number): void;
+    stopCleanup(): void;
+    getRetentionConfig(): EmailRetentionConfig;
+    getMigrationTemplate(tableName?: string): string;
+    isTransportReady(): boolean;
+    loadFromManifest(chunks: any): void;
+    emailPluginOptionsFromManifest(manifest: any): any;
+  };
+  dispose?(): void;
+  shutdown?(): void;
+};
 
 export function recaptchaPlugin(options?: Record<string, unknown>): WebspressoPlugin;
 
-export function swaggerPlugin(options?: Record<string, unknown>): WebspressoPlugin;
+export interface SwaggerPluginOptions {
+  /** Base path for docs (default: '/_swagger') */
+  path?: string;
+  /** UI playground engine: 'swagger' or 'scalar' (default: 'swagger') */
+  ui?: 'swagger' | 'scalar';
+  /** Enable plugin (defaults to true in development) */
+  enabled?: boolean;
+  /** Custom authorization guard */
+  authorize?: (req: any) => boolean;
+  /** Automatically merge ORM model schemas into components.schemas */
+  includeOrmSchemas?: boolean;
+  /** Exclude specific ORM models from documentation */
+  ormExclude?: string[];
+  /** OpenAPI info.title override */
+  title?: string;
+  /** OpenAPI info.version override */
+  version?: string;
+  /** OpenAPI info.description override */
+  description?: string;
+  /** Primary server URL in spec */
+  serverUrl?: string;
+  /** Theme for Scalar UI ('default', 'purple', 'solarized', etc.) */
+  theme?: string;
+  /** Dark mode default for Scalar UI */
+  darkMode?: boolean;
+  /** Auto-register in Admin Panel if admin-panel plugin is present (default: true) */
+  admin?: boolean;
+  /** Admin menu and page title (default: 'API Docs') */
+  adminTitle?: string;
+  /** Admin menu sort order (default: 92) */
+  adminOrder?: number;
+  /** Custom options passed to Scalar */
+  scalarOptions?: Record<string, unknown>;
+  /** Custom options passed to Swagger UI */
+  swaggerOptions?: Record<string, unknown>;
+}
+
+export function swaggerPlugin(options?: SwaggerPluginOptions): WebspressoPlugin;
+export function openapiPlugin(options?: SwaggerPluginOptions): WebspressoPlugin;
+export function apiDocsPlugin(options?: SwaggerPluginOptions): WebspressoPlugin;
 
 export function healthCheckPlugin(options?: Record<string, unknown>): WebspressoPlugin;
 
@@ -1124,6 +1715,86 @@ export interface BasicAuthPluginOptions {
 
 export function basicAuthPlugin(options?: BasicAuthPluginOptions): WebspressoPlugin;
 
+export interface ApiKeyRecord {
+  id?: number | string;
+  name: string;
+  key_hash: string;
+  key_hint: string;
+  prefix?: string;
+  user_id?: number | string | null;
+  scopes?: string[] | string | null;
+  rate_limit?: number | null;
+  metadata?: any;
+  expires_at?: Date | string | null;
+  last_used_at?: Date | string | null;
+  revoked_at?: Date | string | null;
+  created_at?: Date | string;
+  updated_at?: Date | string;
+  user?: any;
+  [key: string]: any;
+}
+
+export interface ApiKeyPluginOptions {
+  /** Database instance or Knex instance. */
+  db?: any;
+  /** Knex instance. */
+  knex?: any;
+  /** Table name for API keys. Default 'api_keys'. */
+  tableName?: string;
+  /** Default key prefix. Default 'wsp_live_'. */
+  prefix?: string;
+  /** Random byte length for key generation. Default 24. */
+  byteLength?: number;
+  /** Protect all matching routes globally. Default false. */
+  global?: boolean;
+  /** Route prefixes to protect when global: true. Default true (all routes). */
+  routes?: string | string[] | boolean;
+  /** Path prefixes to bypass authentication. */
+  skipPaths?: string[];
+  /** Custom predicate function to skip authentication. */
+  skip?: (req: Request) => boolean;
+  /** Static in-memory keys for testing, serverless, or microservices. */
+  keys?: Array<{ key?: string; key_hash?: string; name?: string; scopes?: string[] | string; [key: string]: any }> | Record<string, any>;
+  /** Automatically update last_used_at timestamp. Default true. */
+  trackUsage?: boolean;
+  /** Throttle interval in milliseconds for last_used_at updates. Default 60000. */
+  updateLastUsedThrottleMs?: number;
+  /** Allow query parameter extraction (?apiKey=...). Default false. */
+  allowQueryParam?: boolean;
+  /** Query parameter name. Default 'apiKey'. */
+  queryParamName?: string;
+  /** Custom key extraction function. */
+  extractKey?: (req: Request) => string | null;
+  /** Custom key lookup by SHA-256 hash. */
+  findKeyByHash?: (hash: string, req?: Request) => Promise<ApiKeyRecord | null> | ApiKeyRecord | null;
+  /** Custom verification hook. */
+  verify?: (rawKey: string, req?: Request) => Promise<ApiKeyRecord | null> | ApiKeyRecord | null;
+  /** Custom user loader for key. */
+  getUser?: (record: ApiKeyRecord, req?: Request) => Promise<any> | any;
+  /** Callback hook on successful authentication. */
+  onAuthenticated?: (req: Request, record: ApiKeyRecord) => void | Promise<void>;
+  /** Custom 401 Unauthorized response handler, string, or object. */
+  unauthorizedResponse?: ((req: Request, res: Response, info?: any) => unknown) | string | Record<string, unknown>;
+  /** Custom 403 Forbidden response handler, string, or object. */
+  forbiddenResponse?: ((req: Request, res: Response, info?: any) => unknown) | string | Record<string, unknown>;
+}
+
+export interface ApiKeyRouteOptions {
+  /** Required scope(s) for this route. Supports wildcards ('*', 'reports:*'). */
+  scopes?: string | string[];
+  /** Whether all required scopes must be present (true) or any scope (false). Default true. */
+  requireAllScopes?: boolean;
+  /** If true, allows requests without API key to pass through without error. Default false. */
+  optional?: boolean;
+  /** Custom 401 Unauthorized response. */
+  unauthorizedResponse?: ((req: Request, res: Response, info?: any) => unknown) | string | Record<string, unknown>;
+  /** Custom 403 Forbidden response. */
+  forbiddenResponse?: ((req: Request, res: Response, info?: any) => unknown) | string | Record<string, unknown>;
+}
+
+export function apiKeyPlugin(options?: ApiKeyPluginOptions): WebspressoPlugin;
+export function createApiKeyMiddleware(options?: ApiKeyPluginOptions & ApiKeyRouteOptions): RequestHandler;
+
 export interface ContentPluginOptions {
   db: import('./index').Database;
   adminPath?: string;
@@ -1183,6 +1854,42 @@ export function createLocalFileProvider(options?: {
   publicBasePath?: string;
 }): UploadStorageProvider;
 
+export interface OrphanedUploadsResult {
+  destDir: string;
+  totalFiles: number;
+  totalBytes: number;
+  totalBytesFormatted: string;
+  referencedCount: number;
+  orphanedCount: number;
+  orphanedBytes: number;
+  orphanedBytesFormatted: string;
+  orphanedFiles: Array<{
+    relativePath: string;
+    absolutePath: string;
+    size: number;
+    publicUrl: string;
+    mtime: Date;
+  }>;
+  dryRun?: boolean;
+  deletedCount?: number;
+  deletedBytes?: number;
+  deletedBytesFormatted?: string;
+  deletedFiles?: string[];
+}
+
+export function scanOrphanedUploads(options?: {
+  db?: any;
+  destDir?: string;
+  publicBasePath?: string;
+}): Promise<OrphanedUploadsResult>;
+
+export function pruneOrphanedUploads(options?: {
+  db?: any;
+  destDir?: string;
+  publicBasePath?: string;
+  dryRun?: boolean;
+}): Promise<OrphanedUploadsResult>;
+
 // --- Realtime Layer Types ---
 
 export interface RealtimeSubscriptionCallbacks {
@@ -1508,6 +2215,13 @@ export class MemoryQueueAdapter implements QueueAdapter {
   getJob(jobId: string | number): Promise<Job | null>;
   getStats(): Promise<{ pending: number; running: number; completed: number; failed: number; total: number }>;
   clear(): Promise<void>;
+  clean?(options?: {
+    status?: string | string[];
+    days?: number;
+    retentionDays?: number;
+    olderThan?: Date | string | number;
+    limit?: number;
+  }): Promise<number>;
 }
 
 export class DatabaseQueueAdapter implements QueueAdapter {
@@ -1521,6 +2235,13 @@ export class DatabaseQueueAdapter implements QueueAdapter {
   getJob(jobId: string | number): Promise<Job | null>;
   getStats(): Promise<{ pending: number; running: number; completed: number; failed: number; total: number }>;
   clear(): Promise<void>;
+  clean(options?: {
+    status?: string | string[];
+    days?: number;
+    retentionDays?: number;
+    olderThan?: Date | string | number;
+    limit?: number;
+  }): Promise<number>;
 }
 
 export class RedisQueueAdapter implements QueueAdapter {
@@ -1533,6 +2254,13 @@ export class RedisQueueAdapter implements QueueAdapter {
   getJob(jobId: string | number): Promise<Job | null>;
   getStats(): Promise<{ pending: number; running: number; completed: number; failed: number; total: number }>;
   clear(): Promise<void>;
+  clean(options?: {
+    status?: string | string[];
+    days?: number;
+    retentionDays?: number;
+    olderThan?: Date | string | number;
+    limit?: number;
+  }): Promise<number>;
 }
 
 export interface DispatchOptions {
@@ -1543,28 +2271,130 @@ export interface DispatchOptions {
   backoff?: number | { type?: 'exponential' | 'fixed'; delay?: number };
 }
 
-export class QueueManager extends import('events').EventEmitter {
+export interface QueueRetentionConfig {
+  enabled?: boolean;
+  autoCleanup?: boolean;
+  days?: number;
+  statuses?: string[];
+  intervalMs?: number;
+  runOnStart?: boolean;
+}
+
+export interface ScheduleOptions {
+  id?: string;
+  overlap?: boolean;
+  maxRuns?: number;
+  utc?: boolean;
+  runImmediately?: boolean;
+  delay?: number | Date;
+  attempts?: number;
+  priority?: number;
+  timeout?: number;
+  backoff?: number | { type?: 'exponential' | 'fixed'; delay?: number };
+  [key: string]: unknown;
+}
+
+export interface ScheduleInfo {
+  id: string;
+  name: string;
+  cronExpression: string;
+  cron?: CronExpression;
+  data: unknown;
+  options: ScheduleOptions;
+  runsCount: number;
+  lastRunAt: Date | null;
+  nextRunAt: Date | null;
+  isRunning: boolean;
+  activeJobId: string | number | null;
+  registeredAt: Date;
+}
+
+export class CronExpression {
+  rawExpression: string;
+  resolvedExpression: string;
+  utc: boolean;
+  minutes: Set<number>;
+  hours: Set<number>;
+  doms: Set<number>;
+  months: Set<number>;
+  dows: Set<number>;
+  constructor(expression: string, options?: { utc?: boolean });
+  match(date?: Date): boolean;
+  getNextDate(fromDate?: Date): Date | null;
+  getNextDates(count?: number, fromDate?: Date): Date[];
+  static isValid(expression: string): boolean;
+  static parse(expression: string, options?: { utc?: boolean }): CronExpression;
+}
+
+export function parseCron(expression: string, options?: { utc?: boolean }): CronExpression;
+export function isValidCron(expression: string): boolean;
+export function resolveCronAlias(str: string): string;
+export const CRON_ALIASES: Record<string, string>;
+
+export class TaskScheduler {
+  queue: QueueManager;
+  maxIntervalMs: number;
+  isRunning: boolean;
+  schedules: Map<string, any>;
+  constructor(queue: QueueManager, options?: { autoStart?: boolean; maxIntervalMs?: number });
+  schedule(cronExpression: string | CronExpression, jobName: string, data?: unknown, options?: ScheduleOptions): ScheduleInfo;
+  cron(cronExpression: string | CronExpression, jobName: string, data?: unknown, options?: ScheduleOptions): ScheduleInfo;
+  unschedule(idOrJobName: string): boolean;
+  getSchedules(): ScheduleInfo[];
+  getSchedule(idOrJobName: string): ScheduleInfo | null;
+  trigger(idOrJobName: string): Promise<Job | null>;
+  start(): this;
+  stop(): this;
+  clear(): void;
+  destroy(): void;
+}
+
+export class QueueManager extends EventEmitter {
   adapter: QueueAdapter;
   concurrency: number;
   pollInterval: number;
   isRunning: boolean;
   isPaused: boolean;
   isDraining: boolean;
+  retentionConfig: QueueRetentionConfig;
+  scheduler: TaskScheduler;
   constructor(options?: {
     adapter?: QueueAdapter;
     concurrency?: number;
     pollInterval?: number;
     jobsDir?: string | null;
     autoStart?: boolean;
+    retention?: boolean | QueueRetentionConfig;
+    retentionDays?: number;
+    retentionStatuses?: string[];
+    cleanupIntervalMs?: number;
+    autoCleanup?: boolean;
+    cleanupOnStart?: boolean;
   });
   define(name: string, handler: (job: Job, ctx: { queue: QueueManager }) => Promise<any> | any, options?: DispatchOptions): this;
   has(name: string): boolean;
   dispatch(name: string, data?: unknown, options?: DispatchOptions): Promise<Job>;
+  schedule(cronExpression: string | CronExpression, name: string, data?: unknown, options?: ScheduleOptions): ScheduleInfo;
+  cron(cronExpression: string | CronExpression, name: string, data?: unknown, options?: ScheduleOptions): ScheduleInfo;
+  unschedule(idOrJobName: string): boolean;
+  getSchedules(): ScheduleInfo[];
+  getSchedule(idOrJobName: string): ScheduleInfo | null;
   start(): this;
   pause(): this;
   resume(): this;
   drain(timeoutMs?: number): Promise<void>;
   stop(): Promise<void>;
+  clean(options?: {
+    status?: string | string[];
+    days?: number;
+    retentionDays?: number;
+    olderThan?: Date | string | number;
+    limit?: number;
+  }): Promise<number>;
+  runCleanup(): Promise<number>;
+  startCleanup(customIntervalMs?: number): void;
+  stopCleanup(): void;
+  getRetentionConfig(): QueueRetentionConfig;
   getStats(): Promise<Record<string, unknown>>;
   getJob(jobId: string | number): Promise<Job | null>;
   loadJobsFromDirectory(dirPath: string): void;
@@ -1576,6 +2406,12 @@ export function createQueueManager(options?: {
   pollInterval?: number;
   jobsDir?: string | null;
   autoStart?: boolean;
+  retention?: boolean | QueueRetentionConfig;
+  retentionDays?: number;
+  retentionStatuses?: string[];
+  cleanupIntervalMs?: number;
+  autoCleanup?: boolean;
+  cleanupOnStart?: boolean;
 }): QueueManager;
 
 export function queuePlugin(options?: {
@@ -1588,7 +2424,28 @@ export function queuePlugin(options?: {
   pollInterval?: number;
   jobsDir?: string;
   autoStart?: boolean;
-}): PluginDefinition;
+  retention?: boolean | QueueRetentionConfig;
+  retentionDays?: number;
+  retentionStatuses?: string[];
+  cleanupIntervalMs?: number;
+  autoCleanup?: boolean;
+  cleanupOnStart?: boolean;
+}): WebspressoPlugin & {
+  api?: {
+    getQueueManager(): QueueManager | null;
+    clean(options?: {
+      status?: string | string[];
+      days?: number;
+      retentionDays?: number;
+      olderThan?: Date | string | number;
+      limit?: number;
+    }): Promise<number>;
+    schedule(cronExpression: string | CronExpression, name: string, data?: unknown, options?: ScheduleOptions): ScheduleInfo | undefined;
+    cron(cronExpression: string | CronExpression, name: string, data?: unknown, options?: ScheduleOptions): ScheduleInfo | undefined;
+    unschedule(idOrJobName: string): boolean | undefined;
+    getSchedules(): ScheduleInfo[];
+  };
+};
 
 // --- SSR Streaming & Chunked Transfer ---
 
@@ -1619,6 +2476,54 @@ export const ssr: {
   renderStream: typeof renderStream;
 };
 
+// --- Server-Sent Events (SSE) Streaming ---
+
+export interface SseOptions {
+  status?: number;
+  headers?: Record<string, string>;
+  heartbeat?: number | boolean;
+  heartbeatComment?: string;
+  retry?: number;
+  map?: (chunk: any) => any;
+}
+
+export interface SseEventObject {
+  data?: any;
+  event?: string;
+  id?: string | number;
+  retry?: number;
+}
+
+export class ServerSentEventsStream extends EventEmitter {
+  req: import('http').IncomingMessage;
+  res: import('http').ServerResponse;
+  options: SseOptions;
+  isOpen: boolean;
+  isClosed: boolean;
+
+  constructor(req: import('http').IncomingMessage, res: import('http').ServerResponse, options?: SseOptions);
+  send(payloadOrData: any | SseEventObject, event?: string, id?: string | number): Promise<boolean>;
+  comment(text: string): boolean;
+  heartbeat(comment?: string): boolean;
+  retry(ms: number): boolean;
+  pipe(source: AsyncIterable<any> | Iterable<any> | import('stream').Readable, mapFn?: (chunk: any) => any): Promise<void>;
+  stream(generatorFn: (stream: ServerSentEventsStream) => any): Promise<void>;
+  close(): void;
+}
+
+export function createSseStream(
+  req: import('http').IncomingMessage,
+  res: import('http').ServerResponse,
+  sourceOrOptions?: SseOptions | AsyncIterable<any> | Iterable<any> | import('stream').Readable | ((stream: ServerSentEventsStream) => any),
+  maybeOptions?: SseOptions
+): ServerSentEventsStream | Promise<void>;
+
+export const sseStream: {
+  ServerSentEventsStream: typeof ServerSentEventsStream;
+  createSseStream: typeof createSseStream;
+  formatSseFrame: (data?: any, event?: string, id?: string | number, retry?: number) => string;
+};
+
 // --- Model Context Protocol (MCP) Plugin ---
 
 export interface McpPluginOptions {
@@ -1863,7 +2768,7 @@ export interface PageContext<TParams = Record<string, string>, TQuery = Record<s
   res: import('express').Response;
   params: TParams;
   query: TQuery;
-  service: <TInput = unknown, TOutput = unknown>(name: string, input?: TInput, opts?: unknown) => Promise<TOutput>;
+  service: WebspressoServiceCaller;
   module: string | null;
   config: Record<string, unknown>;
   logger: Console;
@@ -1897,7 +2802,7 @@ export interface ApiContext<TBody = any, TParams = Record<string, string>, TQuer
   query: TQuery;
   body: TBody;
   input: { body?: TBody; params?: TParams; query?: TQuery; headers?: Record<string, string> };
-  service: <TInput = unknown, TOutput = unknown>(name: string, input?: TInput, opts?: unknown) => Promise<TOutput>;
+  service: WebspressoServiceCaller;
   module: string | null;
   config: Record<string, unknown>;
   logger: Console;
@@ -1980,6 +2885,279 @@ export function compileRouteTable(
   options?: { explicitRoutes?: Array<{ method?: string; path: string }>; isDev?: boolean }
 ): RouteTable;
 
+export interface GenerateTypesOptions {
+  /** Root directory of the project (default: process.cwd()) */
+  rootDir?: string;
+  /** Alias for rootDir */
+  cwd?: string;
+  /** Models directory relative to root (default: 'models') */
+  modelsDir?: string;
+  /** Services directory relative to root (default: 'services') */
+  servicesDir?: string;
+  /** Pages directory relative to root (default: 'pages') */
+  pagesDir?: string;
+  /** Output directory (default: '.webspresso') */
+  outDir?: string;
+  /** Custom output file path (default: '.webspresso/types.d.ts') */
+  outFile?: string;
+  /** Create companion webspresso-env.d.ts at project root (default: true) */
+  createEnvFile?: boolean;
+  /** Write declaration files to disk (default: true) */
+  write?: boolean;
+  /** Suppress console output (default: false) */
+  silent?: boolean;
+}
+
+export interface GenerateTypesResult {
+  code: string;
+  modelsCount: number;
+  servicesCount: number;
+  routesCount: number;
+  outFile: string;
+  envFile: string | null;
+}
+
+export function generateTypes(options?: GenerateTypesOptions): GenerateTypesResult;
+
+// --- OAuth 2.0 & Social Login Plugin ---
+
+export class OAuthError extends Error {
+  code: string;
+  details?: any;
+  constructor(message: string, code?: string, details?: any);
+}
+
+export interface OAuthUserProfile {
+  provider: string;
+  id: string;
+  email?: string | null;
+  emailVerified?: boolean;
+  name?: string | null;
+  firstName?: string | null;
+  lastName?: string | null;
+  username?: string | null;
+  avatarUrl?: string | null;
+  bio?: string | null;
+  location?: string | null;
+  locale?: string | null;
+  raw: Record<string, any>;
+  [key: string]: any;
+}
+
+export interface OAuthProviderConfig {
+  name?: string;
+  clientId: string;
+  clientSecret: string;
+  redirectUri?: string;
+  authorizationUrl?: string;
+  tokenUrl?: string;
+  userInfoUrl?: string;
+  scopes?: string[] | string;
+  defaultScopes?: string[];
+  params?: Record<string, any>;
+  normalizeProfile?: (raw: any, extra?: any) => OAuthUserProfile;
+  fetchExtra?: (tokens: any) => Promise<any>;
+}
+
+export interface OAuthClientConfig {
+  secret?: string;
+  stateTtlMs?: number;
+  providers?: Record<string, OAuthProviderConfig>;
+}
+
+export class OAuthClient {
+  secret: string;
+  stateTtlMs: number;
+  providers: Record<string, OAuthProviderConfig>;
+  constructor(config?: OAuthClientConfig);
+  registerProvider(name: string, options?: OAuthProviderConfig): this;
+  getProvider(name: string): OAuthProviderConfig;
+  getProviderNames(): string[];
+  getAuthorizationUrl(providerName: string, options?: {
+    redirectUri?: string;
+    scopes?: string[] | string;
+    stateData?: Record<string, any>;
+    pkce?: boolean;
+    extraParams?: Record<string, any>;
+  }): { url: string; state: string; codeVerifier?: string };
+  exchangeCode(providerName: string, params: {
+    code: string;
+    redirectUri?: string;
+    codeVerifier?: string;
+  }): Promise<Record<string, any>>;
+  fetchUserProfile(providerName: string, tokens: Record<string, any>): Promise<OAuthUserProfile>;
+  handleCallback(providerName: string, params: {
+    code: string;
+    state: string;
+    redirectUri?: string;
+  }): Promise<{ provider: string; user: OAuthUserProfile; tokens: Record<string, any>; stateData: Record<string, any> }>;
+}
+
+export function createOAuthClient(config?: OAuthClientConfig): OAuthClient;
+export function generatePKCE(): { codeVerifier: string; codeChallenge: string; codeChallengeMethod: 'S256' };
+export function createSignedState(payload: Record<string, any>, secret: string): string;
+export function verifySignedState(stateString: string, secret: string, maxAgeMs?: number): Record<string, any>;
+
+export interface OAuthPluginOptions {
+  client?: OAuthClient;
+  providers?: Record<string, OAuthProviderConfig>;
+  secret?: string;
+  pathPrefix?: string;
+  routes?: boolean;
+  pkce?: boolean;
+  stateTtlMs?: number;
+  defaultReturnTo?: string;
+  failureRedirect?: string;
+  findOrCreateUser?: (params: {
+    provider: string;
+    profile: OAuthUserProfile;
+    tokens: Record<string, any>;
+    stateData: Record<string, any>;
+    req: any;
+    res: any;
+    db?: any;
+  }) => Promise<any>;
+  onSuccess?: (params: {
+    provider: string;
+    user: any;
+    profile: OAuthUserProfile;
+    tokens: Record<string, any>;
+    stateData: Record<string, any>;
+    req: any;
+    res: any;
+    client: OAuthClient;
+  }) => Promise<void | any>;
+  onError?: (params: {
+    error: Error | OAuthError;
+    provider: string;
+    req: any;
+    res: any;
+    client: OAuthClient;
+  }) => Promise<void | any>;
+  db?: any;
+}
+
+export function oauthPlugin(options?: OAuthPluginOptions): WebspressoPlugin;
+
+// ==========================================
+// 2FA / TOTP (RFC 6238, RFC 4226, RFC 4648)
+// ==========================================
+
+export interface Base32EncodeOptions {
+  padding?: boolean;
+}
+
+export interface TotpSecretOptions extends Base32EncodeOptions {
+  length?: number;
+}
+
+export interface HotpOptions {
+  digits?: number;
+  algorithm?: 'sha1' | 'sha256' | 'sha512' | string;
+  encoding?: 'base32' | 'ascii' | 'utf8' | 'hex';
+}
+
+export interface TotpOptions extends HotpOptions {
+  time?: number | Date;
+  step?: number;
+  epoch?: number;
+}
+
+export interface TotpVerifyOptions extends TotpOptions {
+  window?: number;
+  detailed?: boolean;
+}
+
+export interface TotpUriOptions {
+  secret: string;
+  account?: string;
+  issuer?: string;
+  label?: string;
+  algorithm?: string;
+  digits?: number;
+  period?: number;
+}
+
+export interface QrSvgOptions {
+  size?: number;
+  margin?: number;
+  darkColor?: string;
+  lightColor?: string;
+  version?: number;
+  ecc?: 'L' | 'M' | 'Q' | 'H';
+  mask?: number;
+}
+
+export interface RecoveryCodeOptions {
+  count?: number;
+  length?: number;
+  hyphen?: boolean;
+}
+
+export interface TotpSetupOptions extends TotpSecretOptions {
+  user?: any;
+  account?: string;
+  issuer?: string;
+  recoveryCodeCount?: number;
+  qrOptions?: QrSvgOptions;
+  algorithm?: string;
+  digits?: number;
+  period?: number;
+}
+
+export interface TotpSetupResult {
+  secret: string;
+  uri: string;
+  qrSvg: string;
+  qrDataUri: string;
+  recoveryCodes: string[];
+  recoveryCodesHashed: string[];
+}
+
+export function base32Encode(buffer: Buffer | string, options?: Base32EncodeOptions): string;
+export function base32Decode(input: string): Buffer;
+export function generateTotpSecret(options?: TotpSecretOptions): string;
+export function generateHotp(secret: string | Buffer, counter: number | bigint, options?: HotpOptions): string;
+export function verifyHotp(token: string, secret: string | Buffer, counter: number | bigint, options?: HotpOptions): boolean;
+export function generateTotp(secret: string | Buffer, options?: TotpOptions): string;
+export function verifyTotp(token: string, secret: string | Buffer, options?: TotpVerifyOptions): boolean | { valid: boolean; delta: number | null };
+export function generateTotpUri(options: TotpUriOptions): string;
+export function generateTotpQrSvg(uriOrOptions: string | TotpUriOptions, svgOptions?: QrSvgOptions): string;
+export function generateTotpQrDataUri(uriOrOptions: string | TotpUriOptions, svgOptions?: QrSvgOptions): string;
+export function generateRecoveryCodes(options?: RecoveryCodeOptions): string[];
+export function hashRecoveryCode(code: string): string;
+export function verifyRecoveryCode(code: string, hashedCodes: string[]): { valid: boolean; matchedIndex: number; remainingHashedCodes: string[] };
+export function createTotpSetup(options?: TotpSetupOptions): TotpSetupResult;
+
+export function createQrMatrix(text: string, options?: QrSvgOptions): { matrix: boolean[][]; size: number; version: number };
+export function generateQrSvg(text: string, options?: QrSvgOptions): string;
+export function generateQrDataUri(text: string, options?: QrSvgOptions): string;
+
+export namespace totp {
+  export {
+    base32Encode,
+    base32Decode,
+    generateTotpSecret,
+    generateHotp,
+    verifyHotp,
+    generateTotp,
+    verifyTotp,
+    generateTotpUri,
+    generateTotpQrSvg,
+    generateTotpQrDataUri,
+    generateRecoveryCodes,
+    hashRecoveryCode,
+    verifyRecoveryCode,
+    createTotpSetup,
+    createQrMatrix,
+    generateQrSvg,
+    generateQrDataUri,
+  };
+}
+
+
+
+