webspresso 0.0.98 → 0.0.100

package/index.d.ts

@@ -541,8 +541,70 @@ export function mountPages(
   registerDynamicFileRoutes: () => void;
 };
 
+export interface CascadingLayoutInfo {
+  layoutRelPath: string;
+  fullPath: string;
+  configPath: string | null;
+}
+
+export interface CascadingErrorBoundaryInfo {
+  dirSegment: string;
+  errorRelPath: string;
+  fullPath: string;
+  configPath: string | null;
+}
+
+export interface CascadingLoadingInfo {
+  dirSegment: string;
+  loadingRelPath: string;
+  fullPath: string;
+}
+
+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 findNearestErrorBoundary(
+    baseDir: string,
+    relativeFilePath: string,
+    isDev?: boolean
+  ): CascadingErrorBoundaryInfo | null;
+  export function findNearestLoadingTemplate(
+    baseDir: string,
+    relativeFilePath: string,
+    isDev?: boolean
+  ): CascadingLoadingInfo | null;
+  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;
@@ -706,11 +768,20 @@ export interface ScopeContext {
 
 export type RelationType = 'belongsTo' | 'hasMany' | 'hasOne';
 
+export type RelationCascadeOption =
+  | boolean
+  | 'delete'
+  | 'restore'
+  | 'all'
+  | ('delete' | 'restore' | 'all')[]
+  | { delete?: boolean; restore?: boolean };
+
 export interface RelationDefinition {
   type: RelationType;
-  model: () => ModelDefinition;
+  model: string | (() => ModelDefinition<any> | string);
   foreignKey: string;
   localKey?: string;
+  cascade?: RelationCascadeOption;
 }
 
 export interface AdminPermissions {
@@ -864,6 +935,7 @@ export interface ModelOptions<TSchema extends ZodObject<any> = ZodObject<Record<
     maxIncludes?: number;
     maxFilterConditions?: number;
   };
+  searchable?: string[];
   cache?: boolean | 'auto' | 'smart' | { strategy: 'auto' | 'smart' };
 }
 
@@ -898,6 +970,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' };
 }
@@ -914,6 +987,8 @@ export function hasModel(name: string): boolean;
 
 export function clearRegistry(): void;
 
+export function isCascadeEnabled(relation: RelationDefinition, operation: 'delete' | 'restore'): boolean;
+
 // --- ORM: schema & columns ---
 
 /** zdb column helpers (id, string, timestamp, …) + `schema()` */
@@ -934,7 +1009,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>> {
@@ -945,6 +1023,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;
@@ -954,14 +1042,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>;
@@ -976,18 +1069,21 @@ 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>;
   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<T | null>;
+  delete(id: string | number, options?: { cascade?: boolean; deletedAt?: Date }): Promise<boolean>;
+  forceDelete(id: string | number, options?: { cascade?: boolean }): Promise<boolean>;
+  restore(id: string | number, options?: { cascade?: boolean; allChildren?: boolean }): Promise<T | null>;
   query(): QueryBuilder<T>;
   raw(sql: string, bindings?: unknown[]): Promise<unknown>;
   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>;
 }
 
@@ -1208,6 +1304,24 @@ export function validateQueryComplexity(
   includes: string[];
 };
 
+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;
@@ -1374,6 +1488,7 @@ export interface AuditLogPluginOptions {
   tableName?: string;
   includeDefaultPage?: boolean;
   apiPrefix?: string;
+  registerRecordAction?: boolean;
   retentionDays?: number;
   cleanupIntervalMs?: number;
   autoCleanup?: boolean;
@@ -1391,6 +1506,8 @@ export function auditLogPlugin(options?: AuditLogPluginOptions): WebspressoPlugi
     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;
@@ -1632,6 +1749,162 @@ 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 WebhookEndpoint {
+  id?: number | string;
+  name: string;
+  url: string;
+  secret?: string;
+  events?: string[] | string;
+  is_active?: boolean;
+  description?: string | null;
+  headers?: Record<string, string> | string | null;
+  metadata?: Record<string, any> | string | null;
+  created_at?: Date | string;
+  updated_at?: Date | string;
+  [key: string]: any;
+}
+
+export interface WebhookDelivery {
+  id?: number | string;
+  endpoint_id: number | string;
+  event: string;
+  payload: string;
+  status_code?: number | null;
+  success: boolean;
+  duration_ms?: number | null;
+  error?: string | null;
+  response_body?: string | null;
+  attempt?: number;
+  max_attempts?: number;
+  next_retry_at?: Date | string | null;
+  created_at?: Date | string;
+  updated_at?: Date | string;
+  [key: string]: any;
+}
+
+export interface WebhooksPluginOptions {
+  db?: any;
+  knex?: any;
+  endpointsTable?: string;
+  deliveriesTable?: string;
+  maxAttempts?: number;
+  backoffBaseMs?: number;
+  timeoutMs?: number;
+  wrapPayload?: boolean;
+  queue?: any;
+  endpoints?: WebhookEndpoint[];
+  apiPrefix?: string;
+  includeDefaultPage?: boolean;
+  pageTitle?: string;
+  menuOrder?: number;
+}
+
+export interface WebhookDispatchResult {
+  dispatched: number;
+  deliveries: WebhookDelivery[];
+  results?: Array<{ success?: boolean; statusCode?: number; error?: string; [key: string]: any }>;
+}
+
+export interface WebhookDispatcherInstance {
+  dispatch(event: string, payload: any, options?: { wait?: boolean; endpointId?: number | string }): Promise<WebhookDispatchResult>;
+  pingEndpoint(endpointId: number | string): Promise<any>;
+  retryDelivery(deliveryId: number | string): Promise<any>;
+  createEndpoint(data: Partial<WebhookEndpoint>): Promise<WebhookEndpoint>;
+  getEndpoint(id: number | string): Promise<WebhookEndpoint | null>;
+  updateEndpoint(id: number | string, data: Partial<WebhookEndpoint>): Promise<WebhookEndpoint | null>;
+  deleteEndpoint(id: number | string): Promise<boolean>;
+  listEndpoints(filters?: { active?: boolean; search?: string; limit?: number; offset?: number }): Promise<WebhookEndpoint[]>;
+  listDeliveries(filters?: { endpointId?: number | string; event?: string; success?: boolean | string; page?: number; limit?: number }): Promise<{ items: WebhookDelivery[]; total: number; page: number; limit: number; pages: number }>;
+  getDelivery(id: number | string): Promise<WebhookDelivery | null>;
+  purgeDeliveries(options?: { days?: number }): Promise<number>;
+  dispose(): void;
+  on(event: string, listener: (...args: any[]) => void): this;
+}
+
+export function webhooksPlugin(options?: WebhooksPluginOptions): WebspressoPlugin & {
+  dispatcher: WebhookDispatcherInstance;
+};
+
 export interface ContentPluginOptions {
   db: import('./index').Database;
   adminPath?: string;
@@ -2117,6 +2390,82 @@ export interface QueueRetentionConfig {
   runOnStart?: boolean;
 }
 
+export interface ScheduleOptions {
+  id?: string;
+  overlap?: boolean;
+  preventOverlap?: boolean;
+  maxRuns?: number;
+  utc?: boolean;
+  timezone?: string;
+  tz?: string;
+  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;
+  activeJobIds?: (string | number)[];
+  registeredAt: Date;
+}
+
+export class CronExpression {
+  rawExpression: string;
+  resolvedExpression: string;
+  utc: boolean;
+  timezone: string | null;
+  minutes: Set<number>;
+  hours: Set<number>;
+  doms: Set<number>;
+  months: Set<number>;
+  dows: Set<number>;
+  constructor(expression: string, options?: { utc?: boolean; timezone?: string; tz?: string });
+  match(date?: Date | string | number): boolean;
+  getNextDate(fromDate?: Date | string | number): Date | null;
+  getNextDates(count?: number, fromDate?: Date | string | number): Date[];
+  static isValid(expression: string, options?: { utc?: boolean; timezone?: string; tz?: string }): boolean;
+  static parse(expression: string, options?: { utc?: boolean; timezone?: string; tz?: string }): CronExpression;
+}
+
+export function parseCron(expression: string, options?: { utc?: boolean; timezone?: string; tz?: string }): CronExpression;
+export function isValidCron(expression: string, options?: { utc?: boolean; timezone?: string; tz?: 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;
+  pause(): this;
+  resume(): this;
+  clear(): void;
+  destroy(): void;
+}
+
 export class QueueManager extends EventEmitter {
   adapter: QueueAdapter;
   concurrency: number;
@@ -2125,6 +2474,7 @@ export class QueueManager extends EventEmitter {
   isPaused: boolean;
   isDraining: boolean;
   retentionConfig: QueueRetentionConfig;
+  scheduler: TaskScheduler;
   constructor(options?: {
     adapter?: QueueAdapter;
     concurrency?: number;
@@ -2141,6 +2491,13 @@ export class QueueManager extends EventEmitter {
   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;
+  triggerSchedule(idOrJobName: string): Promise<Job | null>;
+  triggerCron(idOrJobName: string): Promise<Job | null>;
   start(): this;
   pause(): this;
   resume(): this;
@@ -2202,6 +2559,10 @@ export function queuePlugin(options?: {
       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[];
   };
 };
 
@@ -2211,14 +2572,20 @@ export interface HtmlStreamOptions {
   env: import('nunjucks').Environment;
   templatePath: string;
   context?: Record<string, unknown>;
-  defer?: Record<string, Promise<unknown> | { promise: Promise<unknown>; template?: string }>;
+  defer?: Record<string, Promise<unknown> | { promise: Promise<unknown>; template?: string; loadingTemplate?: string }>;
+  nonce?: string;
+  loadingTemplate?: string | null;
+  layouts?: CascadingLayoutInfo[];
 }
 
 export interface RenderStreamOptions {
   env?: import('nunjucks').Environment;
-  defer?: Record<string, Promise<unknown> | { promise: Promise<unknown>; template?: string }>;
+  defer?: Record<string, Promise<unknown> | { promise: Promise<unknown>; template?: string; loadingTemplate?: string }>;
   status?: number;
   flushImmediately?: boolean;
+  nonce?: string;
+  loadingTemplate?: string | null;
+  layouts?: CascadingLayoutInfo[];
 }
 
 export function createHtmlStream(options: HtmlStreamOptions): import('stream').Readable;
@@ -2234,6 +2601,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 {
@@ -2629,8 +3044,381 @@ export interface GenerateTypesResult {
 
 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,
+  };
+}
+
+// --- Magic Link / Passwordless Authentication ---
+
+export interface BuildMagicLinkUrlOptions {
+  baseUrl?: string;
+  path?: string;
+  token: string;
+}
+
+export interface FormatMagicLinkHtmlOptions {
+  name?: string;
+  magicLinkUrl: string;
+  expiresMinutes?: number;
+}
+
+export interface MagicLinkVerifyMiddlewareOptions {
+  tokenParam?: string;
+  redirectTo?: string;
+  failureRedirect?: string;
+  markEmailVerified?: boolean;
+  jwt?: boolean;
+}
+
+export interface MagicLinkRequestOptions {
+  baseUrl?: string;
+  path?: string;
+  tokenTtlMs?: number;
+  hideUserNotFound?: boolean;
+  buildMagicLinkUrl?: (token: string) => string;
+}
+
+export interface MagicLinkRequestResult {
+  sent: boolean;
+  userFound: boolean;
+  expiresAt?: Date;
+  token?: string;
+  magicLinkUrl?: string;
+}
+
+export interface MagicLinkVerifyResult {
+  ok: true;
+  user: any;
+  userId: string | number;
+  accessToken?: string;
+  refreshToken?: string;
+}
+
+export function buildMagicLinkUrl(options: BuildMagicLinkUrlOptions): string;
+export function formatMagicLinkHtml(options: FormatMagicLinkHtmlOptions): string;
+export function createMagicLinkVerifyMiddleware(authManager: any, options?: MagicLinkVerifyMiddlewareOptions): (req: any, res: any, next: any) => Promise<any>;
+export function createMagicLinkRequestHandler(authManager: any, options?: MagicLinkRequestOptions): (req: any, res: any) => Promise<any>;
+
+export namespace magicLink {
+  export {
+    buildMagicLinkUrl,
+    formatMagicLinkHtml,
+    createMagicLinkVerifyMiddleware,
+    createMagicLinkRequestHandler,
+  };
+}
+
+// Active Devices & Session Management
+export interface DeviceInfo {
+  browser: string;
+  os: string;
+  device: 'desktop' | 'mobile' | 'tablet' | 'bot' | 'unknown';
+  isMobile: boolean;
+  isTablet: boolean;
+  isDesktop: boolean;
+  isBot: boolean;
+}
+
+export interface UserSession {
+  id?: number | string;
+  session_id: string;
+  user_id: number | string;
+  ip_address?: string | null;
+  user_agent?: string | null;
+  browser?: string | null;
+  os?: string | null;
+  device?: string | null;
+  last_active_at: Date;
+  created_at?: Date;
+  is_current?: boolean;
+}
+
+export interface SessionTracker {
+  track(sessionId: string, userId: string | number, metadata?: { ip?: string; userAgent?: string; browser?: string; os?: string; device?: string }): Promise<UserSession | null>;
+  touch(sessionId: string): Promise<boolean>;
+  get(sessionId: string): Promise<UserSession | null>;
+  list(userId: string | number, currentSessionId?: string | null): Promise<UserSession[]>;
+  isSessionValid(sessionId: string, userId?: string | number | null): Promise<boolean>;
+  revoke(sessionId: string): Promise<boolean>;
+  revokeOthers(userId: string | number, currentSessionId?: string | null): Promise<number>;
+  revokeAll(userId: string | number): Promise<number>;
+  purgeExpired(maxAgeMs: number): Promise<number>;
+}
+
+export interface SessionManagerOptions {
+  tracker?: SessionTracker;
+  sessionStore?: any;
+  touchThrottleMs?: number;
+  emitter?: any;
+}
+
+export class SessionManager {
+  constructor(options?: SessionManagerOptions);
+  tracker: SessionTracker;
+  sessionStore?: any;
+  touchThrottleMs: number;
+  emitter?: any;
+  track(sessionId: string, userId: string | number, req?: any): Promise<UserSession | null>;
+  touch(sessionId: string): Promise<boolean>;
+  isSessionValid(sessionId: string, userId?: string | number | null): Promise<boolean>;
+  listSessions(userId: string | number, currentSessionId?: string | null): Promise<UserSession[]>;
+  revokeSession(sessionId: string, options?: { userId?: string | number; revokedBy?: string }): Promise<boolean>;
+  revokeOtherSessions(userId: string | number, currentSessionId: string): Promise<number>;
+  revokeAllSessions(userId: string | number): Promise<number>;
+}
+
+export function parseUserAgent(userAgent?: string): DeviceInfo;
+export function getClientIp(req?: any): string;
+export function createUserSessionsTable(knex: any): Promise<void>;
+export function dropUserSessionsTable(knex: any): Promise<void>;
+export function createKnexSessionTracker(db: any, options?: { tableName?: string }): SessionTracker;
+export function createMemorySessionTracker(): SessionTracker;
+export function createListSessionsHandler(authManager: any): (req: any, res: any) => Promise<any>;
+export function createRevokeSessionHandler(authManager: any): (req: any, res: any) => Promise<any>;
+
+export namespace sessions {
+  export {
+    SessionManager,
+    createUserSessionsTable,
+    dropUserSessionsTable,
+    createKnexSessionTracker,
+    createMemorySessionTracker,
+    getClientIp,
+    parseUserAgent,
+    createListSessionsHandler,
+    createRevokeSessionHandler,
+  };
+}