webspresso 0.0.90 → 0.0.93

package/index.d.ts

@@ -34,7 +34,21 @@ export interface CreateAppOptions {
     version?: string;
     manifestPath?: string;
     prefix?: string;
-  };  /**
+    publicDir?: string;
+  };
+  /**
+   * If truthy, route load() return values for stylesheets and scripts are promoted to pageHead
+   */
+  pageAssets?:
+    | boolean
+    | {
+        enabled?: boolean;
+        stylesheets?: boolean;
+        scripts?: boolean;
+      };
+  /** Trust proxy configuration (default: 1) */
+  trustProxy?: boolean | number | string;
+  /**
    * Custom 404 / 500 / 503 handlers. File-based route errors are forwarded with `next(err)` and hit `serverError` / `timeout`.
    * When `serverError` / `timeout` is a template path, it is not used for paths under `/api` (default JSON instead).
    */
@@ -48,15 +62,235 @@ export interface CreateAppOptions {
   timeout?: string | false;
   auth?: unknown;
   db?: DatabaseInstance | null;
+  /** HTTP response compression options */
+  compression?: boolean | CompressionOptions;
+  /** Shutdown and lifecycle configuration */
+  shutdown?: ShutdownOptions;
+  server?: {
+    port?: number;
+    shutdown?: ShutdownOptions;
+    compression?: boolean | CompressionOptions;
+    trustProxy?: boolean | number | string;
+    [key: string]: unknown;
+  };
   /** Opt-in Alpine / swup assets under `/__webspresso/client-runtime/*`. Env: WEBSPRESSO_ALPINE, WEBSPRESSO_SWUP. */
   clientRuntime?: {
     alpine?: boolean | Record<string, unknown>;
     swup?: boolean | Record<string, unknown>;
   };
+  /** Path to services directory (auto-discovered) */
+  servicesDir?: string;
+  services?: {
+    dir?: string;
+  };
   setupRoutes?: (app: Application, ctx: SetupRoutesContext) => void;
   [key: string]: unknown;
 }
 
+export interface ServiceContext {
+  req?: Request;
+  res?: Response;
+  db?: DatabaseInstance | null;
+  fsy?: Record<string, unknown>;
+  locale?: string;
+  t?: unknown;
+  service?: {
+    <T = unknown>(name: string, input?: unknown, options?: unknown): Promise<T>;
+    invalidate?: (name: string, input?: unknown, ctx?: unknown) => boolean;
+    clearCache?: (name?: string) => boolean;
+  };
+  [key: string]: unknown;
+}
+
+export type ServiceHandler<TInput = unknown, TOutput = unknown> = (
+  input: TInput,
+  ctx: ServiceContext
+) => Promise<TOutput> | TOutput;
+
+export interface ServiceDefinition<TInput = unknown, TOutput = unknown> {
+  schema?: import('zod').ZodType<any> | Record<string, unknown> | ((input: unknown) => unknown) | null;
+  handler: ServiceHandler<TInput, TOutput>;
+  metadata?: Record<string, unknown>;
+  auth?: boolean | string | string[] | ((user: unknown, ctx: ServiceContext) => boolean | Promise<boolean>);
+  cache?:
+    | boolean
+    | string
+    | number
+    | {
+        ttl?: string | number;
+        key?: string | ((input: unknown, ctx: ServiceContext) => string);
+      };
+  timeout?: number | string;
+  transaction?: boolean;
+  [key: string]: unknown;
+}
+
+export class ServiceRegistry {
+  constructor(options?: { servicesDir?: string; isDev?: boolean; logger?: unknown });
+  readonly services: Map<string, ServiceDefinition>;
+  load(): this;
+  register(name: string, definition: ServiceDefinition | ServiceHandler): this;
+  get(name: string): ServiceDefinition | undefined;
+  has(name: string): boolean;
+  list(): string[];
+  invalidate(name: string, input?: unknown, ctx?: unknown): boolean;
+  clearCache(name?: string): boolean;
+  call<T = unknown>(name: string, input?: unknown, ctx?: unknown, options?: unknown): Promise<T>;
+  reload(): this;
+}
+
+export function createServiceRegistry(options?: {
+  servicesDir?: string;
+  isDev?: boolean;
+  logger?: unknown;
+  autoLoad?: boolean;
+}): ServiceRegistry;
+
+export type InferServiceInput<T> = T extends ServiceDefinition<infer TInput, any>
+  ? TInput
+  : T extends { schema: import('zod').ZodType<infer TInput> }
+    ? TInput
+    : T extends (input: infer TInput, ...args: any[]) => any
+      ? TInput
+      : unknown;
+
+export type InferServiceOutput<T> = T extends ServiceDefinition<any, infer TOutput>
+  ? TOutput
+  : T extends (...args: any[]) => Promise<infer TOutput>
+    ? TOutput
+    : T extends (...args: any[]) => infer TOutput
+      ? TOutput
+      : unknown;
+
+export function defineService<TInput = unknown, TOutput = unknown>(
+  definition: ServiceDefinition<TInput, TOutput> | ServiceHandler<TInput, TOutput>
+): ServiceDefinition<TInput, TOutput>;
+
+export const service: typeof defineService;
+
+export interface MemoizeOptions {
+  ttl?: string | number | boolean;
+  maxSize?: number;
+  key?: (input: unknown, ctx?: unknown) => string;
+}
+
+export interface MemoizedFunction<TArgs extends unknown[], TReturn> {
+  (...args: TArgs): Promise<TReturn>;
+  invalidate(...args: TArgs): boolean;
+  delete(...args: TArgs): boolean;
+  clear(): void;
+  has(...args: TArgs): boolean;
+  readonly size: number;
+}
+
+export function memoize<TArgs extends unknown[], TReturn>(
+  fn: (...args: TArgs) => Promise<TReturn> | TReturn,
+  options?: MemoizeOptions
+): MemoizedFunction<TArgs, TReturn>;
+
+export function parseTtlMs(ttl: string | number | boolean): number;
+
+export function stableCacheKey(input: unknown): string;
+
+export function sanitizeInput<T = unknown>(input: T): T;
+
+export function maskSensitiveData<T = unknown>(data: T, customRedactKeys?: string[]): T;
+
+export function discoverServices(
+  servicesDir: string
+): Array<{ name: string; aliases: string[]; filePath: string; relativePath: string }>;
+
+export function filePathToServiceName(relativePath: string): { name: string; aliases: string[] };
+
+export function toCamelCase(str: string): string;
+
+export function createAuthServices(options?: {
+  userModel?: string;
+  fields?: Record<string, string>;
+}): Record<string, ServiceDefinition>;
+
+export function createMailServices(options?: {
+  emailService: unknown;
+  registry?: unknown;
+  db?: unknown;
+  tableName?: string;
+}): Record<string, ServiceDefinition>;
+
+export function createMediaServices(options?: {
+  provider?: unknown;
+  destDir?: string;
+  publicBasePath?: string;
+}): Record<string, ServiceDefinition>;
+
+export function createSystemServices(options?: {
+  db?: unknown;
+  serviceRegistry?: unknown;
+  pluginManager?: unknown;
+}): Record<string, ServiceDefinition>;
+
+export function createExchangeServices(options?: {
+  db?: unknown;
+}): Record<string, ServiceDefinition>;
+
+export function validateServiceInput(schema: unknown, input: unknown, serviceName: string): unknown;
+
+export function executeService(
+  registry: ServiceRegistry,
+  name: string,
+  input?: unknown,
+  ctx?: unknown,
+  options?: unknown
+): Promise<unknown>;
+
+export interface CompressionOptions {
+  enabled?: boolean;
+  threshold?: number;
+  level?: number;
+  encodings?: string[];
+  filter?: (req: Request, res: Response) => boolean;
+  brotli?: Record<string, unknown>;
+  gzip?: Record<string, unknown>;
+  deflate?: Record<string, unknown>;
+}
+
+export interface ShutdownOptions {
+  enabled?: boolean;
+  mode?: 'graceful' | 'force';
+  timeout?: number;
+  signals?: string[];
+  logger?: unknown;
+  exitOnSignal?: boolean;
+}
+
+export interface ServerAdapter {
+  close(): Promise<void>;
+  forceClose?(): void;
+  closeIdleConnections?(): void;
+}
+
+export class NodeHttpAdapter implements ServerAdapter {
+  constructor(server: unknown);
+  close(): Promise<void>;
+  forceClose(): void;
+  closeIdleConnections(): void;
+  destroy(): void;
+  readonly isListening: boolean;
+}
+
+export class ShutdownManager {
+  constructor(options?: ShutdownOptions);
+  readonly isShuttingDown: boolean;
+  readonly isClosed: boolean;
+  mode: 'graceful' | 'force';
+  timeout: number;
+  onShutdown(fn: () => Promise<void> | void): this;
+  registerDisposer(nameOrFn: string | (() => Promise<void> | void), maybeFn?: () => Promise<void> | void): this;
+  registerAdapter(adapter: ServerAdapter): this;
+  enableShutdownHooks(): this;
+  disableShutdownHooks(): this;
+  close(reason?: string): Promise<void>;
+}
+
 export interface SetupRoutesContext {
   nunjucksEnv: unknown;
   authMiddleware?: RequestHandler;
@@ -65,15 +299,97 @@ export interface SetupRoutesContext {
   clientRuntime: { alpine: boolean; swup: boolean };
 }
 
+export interface WebspressoApplication extends Application {
+  server?: unknown;
+  readonly isShuttingDown: boolean;
+  shutdownManager: ShutdownManager;
+  serviceRegistry: ServiceRegistry;
+  onShutdown(fn: () => Promise<void> | void): this;
+  close(reason?: string): Promise<void>;
+  enableShutdownHooks(): this;
+  disableShutdownHooks(): this;
+  setErrorHandler(handler: (error: unknown, req: Request, res: Response, next: NextFunction) => Promise<unknown> | unknown): this;
+}
+
 export interface CreateAppResult {
-  app: Application;
+  app: WebspressoApplication;
   nunjucksEnv: unknown;
   pluginManager: PluginManager;
   authMiddleware?: RequestHandler;
+  shutdownManager: ShutdownManager;
 }
 
 export function createApp(options?: CreateAppOptions): CreateAppResult;
 
+// --- Exceptions & Errors ---
+
+export interface ErrorOptions {
+  code?: string;
+  details?: unknown;
+  cause?: unknown;
+  status?: number;
+  headers?: Record<string, string>;
+  expose?: boolean;
+  [key: string]: unknown;
+}
+
+export class WebspressoError extends Error {
+  name: string;
+  code?: string;
+  details?: unknown;
+  cause?: unknown;
+  status?: number;
+  constructor(message: string, options?: ErrorOptions);
+}
+
+export class HttpError extends WebspressoError {
+  status: number;
+  headers: Record<string, string>;
+  expose: boolean;
+  constructor(status?: number, message?: string, options?: ErrorOptions);
+}
+
+export class BadRequestError extends HttpError { constructor(message?: string, options?: ErrorOptions); }
+export class UnauthorizedError extends HttpError { constructor(message?: string, options?: ErrorOptions); }
+export class ForbiddenError extends HttpError { constructor(message?: string, options?: ErrorOptions); }
+export class NotFoundError extends HttpError { constructor(message?: string, options?: ErrorOptions); }
+export class MethodNotAllowedError extends HttpError { constructor(message?: string, options?: ErrorOptions); }
+export class ConflictError extends HttpError { constructor(message?: string, options?: ErrorOptions); }
+export class PayloadTooLargeError extends HttpError { constructor(message?: string, options?: ErrorOptions); }
+export class UnsupportedMediaTypeError extends HttpError { constructor(message?: string, options?: ErrorOptions); }
+export class UnprocessableEntityError extends HttpError { constructor(message?: string, options?: ErrorOptions); }
+export class TooManyRequestsError extends HttpError { constructor(message?: string, options?: ErrorOptions); }
+
+export class ValidationError extends HttpError {
+  fields: Record<string, string[] | string>;
+  constructor(message?: string, options?: ErrorOptions & { fields?: Record<string, string[] | string> });
+}
+
+export class ConfigurationError extends WebspressoError { constructor(message: string, options?: ErrorOptions); }
+export class PluginError extends WebspressoError { plugin?: string | null; constructor(message: string, options?: ErrorOptions & { plugin?: string }); }
+export class SecurityError extends HttpError { constructor(message?: string, options?: ErrorOptions); }
+export class RequestError extends HttpError { constructor(status?: number, message?: string, options?: ErrorOptions); }
+export class RequestAbortedError extends RequestError { constructor(message?: string, options?: ErrorOptions); }
+export class RouterError extends WebspressoError { constructor(message: string, options?: ErrorOptions); }
+export class RouteNotFoundError extends NotFoundError { path?: string; constructor(pathOrMessage?: string, options?: ErrorOptions); }
+export class RouteGenerationError extends RouterError { constructor(message: string, options?: ErrorOptions); }
+
+export function normalizeError(err: unknown, isDev?: boolean): HttpError | WebspressoError;
+export function toErrorResponseObject(error: unknown, isDev?: boolean): Record<string, unknown>;
+
+export function createCompressionMiddleware(options?: CompressionOptions): RequestHandler;
+
+export namespace compression {
+  export function supportsBrotli(): boolean;
+  export function getDefaultSupportedEncodings(includeBrotli?: boolean): string[];
+  export function parseAcceptEncoding(header?: string | null): Array<{ encoding: string; q: number; index: number }>;
+  export function selectEncoding(acceptEncoding?: string | null, supportedEncodings?: string[]): string | null;
+  export function isCompressible(contentType?: string | null): boolean;
+  export function createCompressionStream(encoding: string, options?: CompressionOptions): unknown;
+  export function createCompressionMiddleware(options?: CompressionOptions): RequestHandler;
+  export function appendVary(res: unknown, field: string): void;
+}
+
 export function resolveClientRuntime(options?: {
   clientRuntime?: {
     alpine?: boolean | Record<string, unknown>;
@@ -87,15 +403,31 @@ export const CLIENT_RUNTIME_BASE: string;
 
 export function attachDbMiddleware(req: Request, res: Response, next: NextFunction): void;
 
-export function getAppContext(): { db: DatabaseInstance | null };
+export function getAppContext(): {
+  db: DatabaseInstance | null;
+  shutdownManager: ShutdownManager | null;
+  serviceRegistry: ServiceRegistry | null;
+};
 
 export function getDb(): DatabaseInstance;
 
 export function hasDb(): boolean;
 
+export function getShutdownManager(): ShutdownManager | null;
+
+export function hasShutdownManager(): boolean;
+
+export function getServiceRegistry(): ServiceRegistry | null;
+
+export function hasServiceRegistry(): boolean;
+
 export function resetAppContext(): void;
 
-export function setAppContext(partial: { db?: DatabaseInstance | null }): void;
+export function setAppContext(partial: {
+  db?: DatabaseInstance | null;
+  shutdownManager?: ShutdownManager | null;
+  serviceRegistry?: ServiceRegistry | null;
+}): void;
 
 // --- File router ---
 
@@ -121,10 +453,31 @@ export function scanDirectory(
 
 export function loadI18n(pagesDir: string, routePath?: string): Record<string, unknown>;
 
+export interface Translator {
+  (key: string, params?: Record<string, unknown> | string, defaultVal?: string | null): string;
+  locale: string;
+  translations: Record<string, unknown>;
+  number(num: number | string | null | undefined, options?: Intl.NumberFormatOptions): string;
+  formatNumber(num: number | string | null | undefined, options?: Intl.NumberFormatOptions): string;
+  currency(amount: number | string | null | undefined, currency?: string, options?: Intl.NumberFormatOptions): string;
+  formatCurrency(amount: number | string | null | undefined, currency?: string, options?: Intl.NumberFormatOptions): string;
+  date(date: Date | string | number | null | undefined, options?: Intl.DateTimeFormatOptions): string;
+  formatDate(date: Date | string | number | null | undefined, options?: Intl.DateTimeFormatOptions): string;
+  relativeTime(val: number | string | null | undefined, unit?: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions): string;
+  formatRelativeTime(val: number | string | null | undefined, unit?: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions): string;
+  plural(count: number | string, forms: Record<string, string>, params?: Record<string, unknown>): string;
+}
+
+export interface CreateTranslatorOptions {
+  locale?: string;
+  fallbackTranslations?: Record<string, unknown>;
+  fallbackLocale?: string;
+}
+
 export function createTranslator(
-  dictionaries: Record<string, unknown>,
-  locale: string
-): (key: string, params?: Record<string, unknown>) => string;
+  dictionaries?: Record<string, unknown>,
+  options?: CreateTranslatorOptions | string
+): Translator;
 
 export function detectLocale(
   req: Request,
@@ -265,10 +618,23 @@ export interface ScopeOptions {
   tenant?: string | null;
 }
 
-export interface ModelOptions {
+// --- ORM: Type Inference Helpers ---
+
+export type InferModel<T> = T extends ModelDefinition<infer TModel>
+  ? TModel
+  : T extends ZodObject<infer TShape>
+    ? import('zod').z.infer<T>
+    : T extends ZodTypeAny
+      ? import('zod').z.infer<T>
+      : Record<string, any>;
+
+export type InferModelCreate<T> = Partial<InferModel<T>> & Record<string, any>;
+export type InferModelUpdate<T> = Partial<InferModel<T>>;
+
+export interface ModelOptions<TSchema extends ZodObject<any> = ZodObject<Record<string, ZodTypeAny>>> {
   name: string;
   table: string;
-  schema: ZodObject<Record<string, ZodTypeAny>>;
+  schema: TSchema;
   primaryKey?: string;
   relations?: Record<string, RelationDefinition>;
   scopes?: ScopeOptions;
@@ -276,10 +642,16 @@ export interface ModelOptions {
   rest?: RestMetadata;
   hooks?: Record<string, (...args: unknown[]) => unknown>;
   hidden?: string[];
+  queryLimits?: {
+    maxLimit?: number;
+    defaultLimit?: number;
+    maxIncludes?: number;
+    maxFilterConditions?: number;
+  };
   cache?: boolean | 'auto' | 'smart' | { strategy: 'auto' | 'smart' };
 }
 
-export interface ModelDefinition {
+export interface ModelDefinition<TModel = Record<string, any>> {
   name: string;
   table: string;
   schema: ZodObject<Record<string, ZodTypeAny>>;
@@ -296,7 +668,7 @@ export interface ModelDefinition {
     label: string;
     icon: string | null;
     customFields: Record<string, unknown>;
-    queries: Record<string, (repo: Repository) => Promise<unknown>>;
+    queries: Record<string, (repo: Repository<TModel>) => Promise<unknown>>;
   };
   rest: {
     enabled: boolean;
@@ -304,15 +676,23 @@ export interface ModelDefinition {
     allowInclude: string[] | null;
   };
   hidden: string[];
+  queryLimits: {
+    maxLimit?: number;
+    defaultLimit?: number;
+    maxIncludes?: number;
+    maxFilterConditions?: number;
+  };
   hooks: Record<string, unknown>;
   cache?: boolean | 'auto' | 'smart' | { strategy: 'auto' | 'smart' };
 }
 
-export function defineModel(options: ModelOptions): ModelDefinition;
+export function defineModel<TSchema extends ZodObject<any>>(
+  options: ModelOptions<TSchema>
+): ModelDefinition<import('zod').z.infer<TSchema>>;
 
-export function getModel(name: string): ModelDefinition | undefined;
+export function getModel<T = Record<string, any>>(name: string): ModelDefinition<T> | undefined;
 
-export function getAllModels(): Map<string, ModelDefinition>;
+export function getAllModels(): Map<string, ModelDefinition<any>>;
 
 export function hasModel(name: string): boolean;
 
@@ -340,58 +720,58 @@ export interface FindOptions {
   select?: string[];
 }
 
-export interface PaginatedResult {
-  data: Record<string, unknown>[];
+export interface PaginatedResult<T = Record<string, any>> {
+  data: T[];
   total: number;
   page: number;
   perPage: number;
   totalPages: number;
 }
 
-export interface QueryBuilder {
-  where(column: string, value: unknown): this;
-  where(column: string, operator: string, value: unknown): this;
-  where(conditions: Record<string, unknown>): this;
+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;
+  where(conditions: Partial<T> | Record<string, unknown>): this;
   orWhere(...args: unknown[]): this;
-  whereIn(column: string, values: unknown[]): this;
-  whereBetween(column: string, range: [unknown, unknown]): this;
-  select(...columns: string[]): this;
-  orderBy(column: string, direction?: 'asc' | 'desc'): this;
+  whereIn(column: keyof T | string, values: unknown[]): this;
+  whereBetween(column: keyof T | string, range: [unknown, unknown]): this;
+  select(...columns: (keyof T | string)[]): this;
+  orderBy(column: keyof T | string, direction?: 'asc' | 'desc'): this;
   limit(n: number): this;
   offset(n: number): this;
   with(...relations: string[]): this;
   withTrashed(): this;
   onlyTrashed(): this;
-  first(): Promise<Record<string, unknown> | null>;
-  list(): Promise<Record<string, unknown>[]>;
-  get(): Promise<Record<string, unknown>[]>;
+  first(): Promise<T | null>;
+  list(): Promise<T[]>;
+  get(): Promise<T[]>;
   count(): Promise<number>;
-  paginate(page?: number, perPage?: number): Promise<PaginatedResult>;
+  paginate(page?: number, perPage?: number): Promise<PaginatedResult<T>>;
   exists(): Promise<boolean>;
-  clone(): QueryBuilder;
+  clone(): QueryBuilder<T>;
   getWiths(): string[];
   delete(): Promise<number>;
-  update(data: Record<string, unknown>): Promise<number>;
+  update(data: Partial<T> | Record<string, unknown>): Promise<number>;
   [key: string]: unknown;
 }
 
-export interface Repository {
-  findById(id: string | number, options?: FindOptions): Promise<Record<string, unknown> | null>;
-  findOne(conditions: Record<string, unknown>, options?: FindOptions): Promise<Record<string, unknown> | null>;
-  findAll(options?: FindOptions): Promise<Record<string, unknown>[]>;
-  create(data: Record<string, unknown>): Promise<Record<string, unknown>>;
-  createMany(data: Record<string, unknown>[]): Promise<Record<string, unknown>[]>;
-  update(id: string | number, data: Record<string, unknown>): Promise<Record<string, unknown> | null>;
-  updateWhere(conditions: Record<string, unknown>, data: Record<string, unknown>): Promise<number>;
+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[]>;
+  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>;
+  updateWhere(conditions: Partial<T> | Record<string, unknown>, data: Partial<T> | Record<string, unknown>): Promise<number>;
   delete(id: string | number): Promise<boolean>;
   forceDelete(id: string | number): Promise<boolean>;
-  restore(id: string | number): Promise<Record<string, unknown> | null>;
-  query(): QueryBuilder;
+  restore(id: string | number): Promise<T | null>;
+  query(): QueryBuilder<T>;
   raw(sql: string, bindings?: unknown[]): Promise<unknown>;
-  count(conditions?: Record<string, unknown>): Promise<number>;
-  exists(conditions: Record<string, unknown>): Promise<boolean>;
-  with(...relations: string[]): QueryBuilder;
-  model: ModelDefinition;
+  count(conditions?: Partial<T> | Record<string, unknown>): Promise<number>;
+  exists(conditions: Partial<T> | Record<string, unknown>): Promise<boolean>;
+  with(...relations: string[]): QueryBuilder<T>;
+  model: ModelDefinition<T>;
 }
 
 // --- ORM: database ---
@@ -471,21 +851,24 @@ export interface MigrationManager {
 
 export interface TransactionContext {
   trx: Knex.Transaction;
-  getRepository(modelName: string, scopeContext?: ScopeContext): Repository;
-  createRepository(model: ModelDefinition, scopeContext?: ScopeContext): Repository;
+  getRepository<T = Record<string, any>>(modelName: string, scopeContext?: ScopeContext): Repository<T>;
+  createRepository<T = Record<string, any>>(model: ModelDefinition<T>, scopeContext?: ScopeContext): Repository<T>;
 }
 
 export interface DatabaseInstance {
   knex: Knex;
   migrate: MigrationManager;
-  getModel(name: string): ModelDefinition;
+  getModel<T = Record<string, any>>(name: string): ModelDefinition<T>;
   hasModel(name: string): boolean;
-  getAllModels(): ModelDefinition[];
-  registerModel(model: ModelDefinition): void;
-  getRepository(modelName: string, scopeContext?: ScopeContext): Repository;
-  createRepository(model: ModelDefinition, scopeContext?: ScopeContext): Repository;
-  query(modelName: string, scopeContext?: ScopeContext): QueryBuilder;
-  transaction<T>(callback: (ctx: TransactionContext) => Promise<T>): Promise<T>;
+  getAllModels(): ModelDefinition<any>[];
+  registerModel<T = Record<string, any>>(model: ModelDefinition<T>): void;
+  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>;
+  transaction<T>(callback: (ctx: TransactionContext) => Promise<T>, scopeContext?: ScopeContext): Promise<T>;
+  runInTransaction<T>(callback: (ctx: TransactionContext) => Promise<T>, scopeContext?: ScopeContext): Promise<T>;
+  getAmbientTransaction(): Knex.Transaction | null;
+  hasActiveTransaction(): boolean;
   createSeeder(): unknown;
   cache: OrmCachePublicApi | null;
   destroy(): Promise<void>;
@@ -493,6 +876,12 @@ export interface DatabaseInstance {
 
 export function createDatabase(config: DatabaseConfig): DatabaseInstance;
 
+export function runWithAmbientTransaction<T>(trx: Knex.Transaction, callback: () => Promise<T> | T): Promise<T>;
+export function getAmbientTransaction(): Knex.Transaction | null;
+export function hasAmbientTransaction(): boolean;
+export function createTransactionContext(trx: Knex.Transaction, scopeContext?: ScopeContext): TransactionContext;
+export function runTransaction<T>(knex: Knex, callback: (ctx: TransactionContext) => Promise<T>, scopeContext?: ScopeContext): Promise<T>;
+
 export function createMemoryCacheProvider(options?: OrmMemoryCacheOptions): {
   get(key: string): unknown;
   set(key: string, value: unknown, opts?: { tags?: string[]; ttlMs?: number }): void;
@@ -549,6 +938,36 @@ export function createEventContext(
   cancel(reason?: string): void;
 };
 
+// --- ORM: Query Complexity & DoS Protection ---
+
+export class QueryComplexityError extends BadRequestError {
+  code: string;
+}
+
+export const DEFAULT_QUERY_LIMITS: {
+  maxLimit: number;
+  defaultLimit: number;
+  maxIncludes: number;
+  maxFilterConditions: number;
+};
+
+export function resolveQueryLimits(model?: ModelDefinition): typeof DEFAULT_QUERY_LIMITS;
+
+export function validateQueryComplexity(
+  model?: ModelDefinition,
+  params?: {
+    perPage?: number;
+    limit?: number;
+    includes?: string[];
+    filterCount?: number;
+    strict?: boolean;
+  }
+): {
+  limit: number;
+  perPage: number;
+  includes: string[];
+};
+
 // --- Built-in plugins (subset re-exported from main index.js) ---
 
 export function schemaExplorerPlugin(options?: Record<string, unknown>): WebspressoPlugin;
@@ -649,6 +1068,56 @@ export interface CsrfPluginOptions {
 
 export function csrfPlugin(options?: CsrfPluginOptions): WebspressoPlugin;
 
+export interface CorsPluginOptions {
+  origin?: string | string[] | RegExp | ((origin: string, cb: (err: Error | null, allow?: boolean | string) => void) => void) | boolean;
+  methods?: string | string[];
+  allowedHeaders?: string | string[];
+  exposedHeaders?: string | string[];
+  credentials?: boolean;
+  maxAge?: number;
+  preflightContinue?: boolean;
+  optionsSuccessStatus?: number;
+  routes?: string | string[] | boolean;
+  global?: boolean;
+}
+
+export function corsPlugin(options?: CorsPluginOptions): WebspressoPlugin;
+
+export interface BasicAuthCredentials {
+  username: string;
+  password?: string;
+  [key: string]: unknown;
+}
+
+export interface BasicAuthPluginOptions {
+  /** Apply basic auth as a global middleware across the application. Default false. */
+  global?: boolean;
+  /** Static username-password dictionary. */
+  users?: Record<string, string>;
+  /** Custom async/sync credential verification function. */
+  verify?: (
+    username: string,
+    password: string,
+    req: Request
+  ) => boolean | BasicAuthCredentials | Promise<boolean | BasicAuthCredentials>;
+  /** Realm string included in WWW-Authenticate header. Default 'Restricted Area'. */
+  realm?: string;
+  /** Whether to send WWW-Authenticate header on 401. Default true. */
+  challenge?: boolean;
+  /** Route prefixes to protect when global: true. Default true (all routes). */
+  routes?: string | string[] | boolean;
+  /** Path prefixes to bypass basic authentication. */
+  skipPaths?: string[];
+  /** Custom predicate function to skip basic authentication. */
+  skip?: (req: Request) => boolean;
+  /** Custom 401 Unauthorized response handler, string, or object. */
+  unauthorizedResponse?: ((req: Request, res: Response) => unknown) | string | Record<string, unknown>;
+  /** Callback hook on successful authentication. */
+  onAuthenticated?: (req: Request, user: BasicAuthCredentials) => void;
+}
+
+export function basicAuthPlugin(options?: BasicAuthPluginOptions): WebspressoPlugin;
+
 export interface ContentPluginOptions {
   db: import('./index').Database;
   adminPath?: string;
@@ -708,6 +1177,169 @@ export function createLocalFileProvider(options?: {
   publicBasePath?: string;
 }): UploadStorageProvider;
 
+// --- Realtime Layer Types ---
+
+export interface RealtimeSubscriptionCallbacks {
+  connected?: () => void;
+  disconnected?: () => void;
+  rejected?: (error: Error) => void;
+  received?: (data: unknown) => void;
+}
+
+export interface RealtimeSubscription {
+  id: string;
+  identifier: string;
+  params: Record<string, unknown>;
+  send(data: unknown): void;
+  perform(action: string, data?: unknown): void;
+  unsubscribe(): void;
+}
+
+export interface RealtimeAdapter {
+  capabilities?: {
+    send?: boolean;
+    perform?: boolean;
+    multiplexing?: boolean;
+    serverEvents?: boolean;
+    binary?: boolean;
+    [key: string]: boolean | undefined;
+  };
+  connect(context: { auth: Record<string, unknown>; client: RealtimeClient }): Promise<void>;
+  disconnect(): void;
+  isConnected(): boolean;
+  subscribe(
+    identifier: string,
+    params: Record<string, unknown>,
+    callbacks: RealtimeSubscriptionCallbacks
+  ): {
+    send?(data: unknown): void;
+    perform?(action: string, data?: unknown): void;
+    unsubscribe(): void;
+  };
+  send?(identifier: string, data: unknown, sub?: RealtimeSubscription): void;
+  perform?(identifier: string, action: string, data?: unknown, sub?: RealtimeSubscription): void;
+  unsubscribe?(identifier: string, params: Record<string, unknown>, sub?: RealtimeSubscription): void;
+  on?(event: string, handler: (...args: any[]) => void): () => void;
+  destroy?(): void;
+}
+
+export type RealtimeAuthStrategy =
+  | false
+  | {
+      strategy: 'cookie';
+    }
+  | {
+      strategy: 'token';
+      getToken: () => string | Promise<string>;
+      refreshToken?: () => string | Promise<string>;
+      onUnauthorized?: (error: Error) => void;
+    }
+  | {
+      strategy: 'custom';
+      resolve: () => Record<string, unknown> | Promise<Record<string, unknown>>;
+    };
+
+export interface RealtimeReconnectOptions {
+  enabled?: boolean;
+  maxAttempts?: number;
+  baseDelay?: number;
+  maxDelay?: number;
+  factor?: number;
+  jitter?: boolean;
+}
+
+export interface RealtimeOptions {
+  adapter: RealtimeAdapter;
+  auth?: RealtimeAuthStrategy;
+  autoConnect?: boolean;
+  reconnect?: RealtimeReconnectOptions;
+  isBrowser?: boolean;
+}
+
+export interface RealtimeClient {
+  capabilities: Record<string, boolean>;
+  isConnected(): boolean;
+  connect(overrideAuth?: Record<string, unknown> | null): Promise<void>;
+  disconnect(): void;
+  reconnect(): Promise<void>;
+  reauthenticate(): Promise<void>;
+  subscribe(
+    identifier: string,
+    params?: Record<string, unknown>,
+    callbacks?: RealtimeSubscriptionCallbacks
+  ): RealtimeSubscription;
+  on(event: 'connected' | 'disconnected' | 'reconnecting' | 'reconnected' | 'unauthorized' | 'error', handler: (...args: any[]) => void): () => void;
+  once(event: string, handler: (...args: any[]) => void): () => void;
+  off(event: string, handler: (...args: any[]) => void): () => void;
+  destroy(): void;
+}
+
+export function createRealtime(options: RealtimeOptions): RealtimeClient;
+export function realtime(options: RealtimeOptions): RealtimeClient & { plugin: WebspressoPlugin };
+export function realtimePlugin(options: RealtimeOptions): WebspressoPlugin;
+
+export interface WebSocketAdapterOptions {
+  url: string | ((context: { auth: Record<string, unknown> }) => string | Promise<string>);
+  authTransport?: 'query' | 'header' | 'protocol' | 'message';
+  queryParamName?: string;
+  protocols?: string | string[];
+  WebSocket?: any;
+  messages?: {
+    subscribe?: (args: { identifier: string; params: Record<string, unknown> }) => unknown;
+    unsubscribe?: (args: { identifier: string; params: Record<string, unknown> }) => unknown;
+    perform?: (args: { identifier: string; action: string; data?: unknown }) => unknown;
+    send?: (args: { identifier: string; data: unknown }) => unknown;
+    auth?: (args: { token: string; metadata: Record<string, unknown> }) => unknown;
+  };
+  capabilities?: Record<string, boolean>;
+}
+
+export function websocket(options: WebSocketAdapterOptions): RealtimeAdapter;
+export function createWebSocketAdapter(options: WebSocketAdapterOptions): RealtimeAdapter;
+
+export interface SseAdapterOptions {
+  url: string | ((context: { auth: Record<string, unknown> }) => string | Promise<string>);
+  queryParamName?: string;
+  EventSource?: any;
+  capabilities?: Record<string, boolean>;
+}
+
+export function sse(options: SseAdapterOptions): RealtimeAdapter;
+export function createSseAdapter(options: SseAdapterOptions): RealtimeAdapter;
+
+export interface SocketIoAdapterOptions {
+  url?: string | ((context: { auth: Record<string, unknown> }) => string | Promise<string>);
+  path?: string;
+  io?: any;
+  socketOptions?: Record<string, unknown>;
+  capabilities?: Record<string, boolean>;
+}
+
+export function socketIo(options: SocketIoAdapterOptions): RealtimeAdapter;
+export function createSocketIoAdapter(options: SocketIoAdapterOptions): RealtimeAdapter;
+
+export interface RedisAdapterOptions {
+  pubClient?: any;
+  subClient?: any;
+  redis?: any;
+  channelPrefix?: string;
+  nodeId?: string;
+  serialize?: (envelope: unknown) => string;
+  deserialize?: (raw: string) => unknown;
+  inMemory?: boolean;
+  capabilities?: Record<string, boolean>;
+}
+
+export interface RedisRealtimeAdapter extends RealtimeAdapter {
+  publish(identifier: string, data: unknown): Promise<void>;
+  perform(identifier: string, action: string, data?: unknown): Promise<void>;
+  readonly isInMemory: boolean;
+  readonly nodeId: string;
+}
+
+export function redis(options?: RedisAdapterOptions): RedisRealtimeAdapter;
+export function createRedisAdapter(options?: RedisAdapterOptions): RedisRealtimeAdapter;
+
 // --- Application kernel (use `kernel.createApp`; not the SSR `createApp`) ---
 
 export type KernelEventSource = 'orm' | 'auth' | 'route' | 'plugin' | 'system';
@@ -807,3 +1439,242 @@ export interface WebspressoKernel {
 }
 
 export const kernel: WebspressoKernel;
+
+// --- Background Job Queue ---
+
+export interface JobJSON {
+  id: string | number;
+  name: string;
+  data: unknown;
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  attempts: number;
+  maxAttempts: number;
+  backoff: unknown;
+  priority: number;
+  timeout: number;
+  progress: number;
+  result: unknown;
+  error: string | null;
+  createdAt: string;
+  updatedAt: string;
+  runAt: string;
+}
+
+export class Job {
+  id: string | number;
+  name: string;
+  data: any;
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  attempts: number;
+  maxAttempts: number;
+  backoff: number | { type?: 'exponential' | 'fixed'; delay?: number };
+  priority: number;
+  timeout: number;
+  progressValue: number;
+  result: any;
+  error: any;
+  createdAt: Date;
+  updatedAt: Date;
+  runAt: Date;
+  constructor(options?: Record<string, any>);
+  progress(percent: number, message?: string): void;
+  getNextRetryDelay(): number;
+  toJSON(): JobJSON;
+}
+
+export interface QueueAdapter {
+  enqueue(job: Job): Promise<Job>;
+  dequeue(jobNames?: string[]): Promise<Job | null>;
+  complete(jobId: string | number, result?: unknown): Promise<Job | null>;
+  fail(jobId: string | number, error?: unknown): Promise<Job | null>;
+  retry(jobId: string | number, delayMs: number, error?: unknown): Promise<Job | null>;
+  getJob(jobId: string | number): Promise<Job | null>;
+  getStats(): Promise<{ pending: number; running: number; completed: number; failed: number; total: number }>;
+  clear(): Promise<void>;
+}
+
+export class MemoryQueueAdapter implements QueueAdapter {
+  enqueue(job: Job): Promise<Job>;
+  dequeue(jobNames?: string[]): Promise<Job | null>;
+  complete(jobId: string | number, result?: unknown): Promise<Job | null>;
+  fail(jobId: string | number, error?: unknown): Promise<Job | null>;
+  retry(jobId: string | number, delayMs: number, error?: unknown): Promise<Job | null>;
+  getJob(jobId: string | number): Promise<Job | null>;
+  getStats(): Promise<{ pending: number; running: number; completed: number; failed: number; total: number }>;
+  clear(): Promise<void>;
+}
+
+export class DatabaseQueueAdapter implements QueueAdapter {
+  constructor(options: { knex: Knex; tableName?: string });
+  ensureTable(): Promise<void>;
+  enqueue(job: Job): Promise<Job>;
+  dequeue(jobNames?: string[]): Promise<Job | null>;
+  complete(jobId: string | number, result?: unknown): Promise<Job | null>;
+  fail(jobId: string | number, error?: unknown): Promise<Job | null>;
+  retry(jobId: string | number, delayMs: number, error?: unknown): Promise<Job | null>;
+  getJob(jobId: string | number): Promise<Job | null>;
+  getStats(): Promise<{ pending: number; running: number; completed: number; failed: number; total: number }>;
+  clear(): Promise<void>;
+}
+
+export class RedisQueueAdapter implements QueueAdapter {
+  constructor(options: { client: unknown; prefix?: string });
+  enqueue(job: Job): Promise<Job>;
+  dequeue(jobNames?: string[]): Promise<Job | null>;
+  complete(jobId: string | number, result?: unknown): Promise<Job | null>;
+  fail(jobId: string | number, error?: unknown): Promise<Job | null>;
+  retry(jobId: string | number, delayMs: number, error?: unknown): Promise<Job | null>;
+  getJob(jobId: string | number): Promise<Job | null>;
+  getStats(): Promise<{ pending: number; running: number; completed: number; failed: number; total: number }>;
+  clear(): Promise<void>;
+}
+
+export interface DispatchOptions {
+  delay?: number | Date;
+  attempts?: number;
+  priority?: number;
+  timeout?: number;
+  backoff?: number | { type?: 'exponential' | 'fixed'; delay?: number };
+}
+
+export class QueueManager extends import('events').EventEmitter {
+  adapter: QueueAdapter;
+  concurrency: number;
+  pollInterval: number;
+  isRunning: boolean;
+  isPaused: boolean;
+  isDraining: boolean;
+  constructor(options?: {
+    adapter?: QueueAdapter;
+    concurrency?: number;
+    pollInterval?: number;
+    jobsDir?: string | null;
+    autoStart?: 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>;
+  start(): this;
+  pause(): this;
+  resume(): this;
+  drain(timeoutMs?: number): Promise<void>;
+  stop(): Promise<void>;
+  getStats(): Promise<Record<string, unknown>>;
+  getJob(jobId: string | number): Promise<Job | null>;
+  loadJobsFromDirectory(dirPath: string): void;
+}
+
+export function createQueueManager(options?: {
+  adapter?: QueueAdapter;
+  concurrency?: number;
+  pollInterval?: number;
+  jobsDir?: string | null;
+  autoStart?: boolean;
+}): QueueManager;
+
+export function queuePlugin(options?: {
+  adapter?: 'memory' | 'database' | 'db' | 'redis' | QueueAdapter;
+  db?: { knex: Knex };
+  knex?: Knex;
+  redisClient?: unknown;
+  tableName?: string;
+  concurrency?: number;
+  pollInterval?: number;
+  jobsDir?: string;
+  autoStart?: boolean;
+}): PluginDefinition;
+
+// --- SSR Streaming & Chunked Transfer ---
+
+export interface HtmlStreamOptions {
+  env: import('nunjucks').Environment;
+  templatePath: string;
+  context?: Record<string, unknown>;
+  defer?: Record<string, Promise<unknown> | { promise: Promise<unknown>; template?: string }>;
+}
+
+export interface RenderStreamOptions {
+  env?: import('nunjucks').Environment;
+  defer?: Record<string, Promise<unknown> | { promise: Promise<unknown>; template?: string }>;
+  status?: number;
+  flushImmediately?: boolean;
+}
+
+export function createHtmlStream(options: HtmlStreamOptions): import('stream').Readable;
+export function renderStream(
+  res: import('express').Response,
+  templatePath: string,
+  context?: Record<string, unknown>,
+  options?: RenderStreamOptions
+): Promise<void>;
+
+export const ssr: {
+  createHtmlStream: typeof createHtmlStream;
+  renderStream: typeof renderStream;
+};
+
+// --- Model Context Protocol (MCP) Plugin ---
+
+export interface McpPluginOptions {
+  path?: string;
+  enabled?: boolean;
+  auth?: {
+    token?: string;
+    localhostOnly?: boolean;
+    verify?: (req: import('express').Request) => boolean | Promise<boolean>;
+  };
+  services?: boolean | {
+    include?: string[];
+    exclude?: string[];
+    readOnly?: boolean;
+    role?: string | string[];
+  };
+  orm?: boolean | {
+    readOnly?: boolean;
+    models?: string[];
+  };
+  system?: boolean;
+  tools?: Array<{
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    handler: (args: any, ctx: any) => Promise<any> | any;
+  }>;
+  resources?: Array<{
+    uri?: string;
+    uriTemplate?: string;
+    name?: string;
+    description?: string;
+    mimeType?: string;
+    handler: (uri: string, paramsOrCtx: any, ctx?: any) => Promise<any> | any;
+  }>;
+  prompts?: Array<{
+    name: string;
+    description?: string;
+    arguments?: Array<{ name: string; description?: string; required?: boolean }>;
+    handler: (args: any, ctx: any) => Promise<any> | any;
+  }>;
+  discovery?: boolean;
+  name?: string;
+  version?: string;
+  instructions?: string;
+}
+
+export class McpServer {
+  name: string;
+  version: string;
+  instructions: string;
+  constructor(options?: { name?: string; version?: string; instructions?: string; context?: Record<string, unknown> });
+  registerTool(toolDef: any): this;
+  registerTools(toolDefs: any[]): this;
+  unregisterTool(name: string): boolean;
+  registerResource(resourceDef: any): this;
+  registerResourceTemplate(templateDef: any): this;
+  registerPrompt(promptDef: any): this;
+  handleMessage(message: any, callContext?: any): Promise<any>;
+}
+
+export function mcpPlugin(options?: McpPluginOptions): WebspressoPlugin;
+export function createMcpServer(options?: McpPluginOptions): McpServer;
+
+