webspresso 0.0.96 → 0.0.98

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 {
@@ -521,6 +618,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 +713,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>>;
 }
@@ -855,8 +1066,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 +1101,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 +1208,295 @@ export function validateQueryComplexity(
   includes: string[];
 };
 
-// --- Built-in plugins (subset re-exported from main index.js) ---
+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 function schemaExplorerPlugin(options?: Record<string, unknown>): WebspressoPlugin;
+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 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 function auditLogPlugin(options?: Record<string, unknown>): WebspressoPlugin;
+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;
+  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[]>;
+    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 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;
 
@@ -1183,6 +1691,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 +2052,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 +2072,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 +2091,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,19 +2108,35 @@ 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 class QueueManager extends EventEmitter {
   adapter: QueueAdapter;
   concurrency: number;
   pollInterval: number;
   isRunning: boolean;
   isPaused: boolean;
   isDraining: boolean;
+  retentionConfig: QueueRetentionConfig;
   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;
@@ -1565,6 +2146,17 @@ export class QueueManager extends import('events').EventEmitter {
   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 +2168,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 +2186,24 @@ 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>;
+  };
+};
 
 // --- SSR Streaming & Chunked Transfer ---
 
@@ -1863,7 +2478,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 +2512,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 +2595,41 @@ 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;
+
+