webspresso 0.0.99 → 0.0.101

package/index.d.ts

@@ -509,6 +509,8 @@ export function getAppContext(): {
   db: DatabaseInstance | null;
   shutdownManager: ShutdownManager | null;
   serviceRegistry: ServiceRegistry | null;
+  events?: any;
+  mailer?: Mailer | null;
 };
 
 export function getDb(): DatabaseInstance;
@@ -523,12 +525,18 @@ export function getServiceRegistry(): ServiceRegistry | null;
 
 export function hasServiceRegistry(): boolean;
 
+export function getMailer(): Mailer | null;
+
+export function hasMailer(): boolean;
+
 export function resetAppContext(): void;
 
 export function setAppContext(partial: {
   db?: DatabaseInstance | null;
   shutdownManager?: ShutdownManager | null;
   serviceRegistry?: ServiceRegistry | null;
+  events?: any;
+  mailer?: Mailer | null;
 }): void;
 
 // --- File router ---
@@ -547,6 +555,19 @@ export interface CascadingLayoutInfo {
   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;
@@ -568,6 +589,16 @@ export namespace cascading {
     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;
 }
 
@@ -649,6 +680,125 @@ export function loadNjkRouteTemplate(
 
 export function clearNjkFrontmatterCaches(): void;
 
+// --- Forms & Flash subsystem (AdonisJS & Django-inspired) ---
+
+export interface FlashMessages {
+  old?: Record<string, any>;
+  errors?: Record<string, string[]>;
+  [key: string]: any;
+}
+
+export function createFlashMiddleware(options?: { cookieName?: string }): import('express').RequestHandler;
+
+export function normalizeErrors(errors: any): Record<string, string[]>;
+
+export interface FieldRenderOptions {
+  label?: string;
+  type?: string;
+  placeholder?: string;
+  required?: boolean;
+  disabled?: boolean;
+  readonly?: boolean;
+  className?: string;
+  wrapperClass?: string;
+  errorClass?: string;
+  showError?: boolean;
+  rows?: number;
+  selectOptions?: (string | { label: string; value: any })[];
+  helpText?: string;
+  value?: any;
+  default?: any;
+  attributes?: Record<string, string>;
+}
+
+export function renderField(name: string, options?: FieldRenderOptions, ctx?: { req?: any; res?: any }): string;
+
+export interface FormForOptions {
+  action?: string;
+  method?: string;
+  exclude?: string[];
+  include?: string[];
+  submitLabel?: string;
+  csrf?: boolean;
+  formClass?: string;
+}
+
+export function renderFormFor(modelOrRepo: any, options?: FormForOptions, ctx?: { req?: any; res?: any }): string;
+
+// --- Authorization & Bouncer (AdonisJS Bouncer & Django Permissions-inspired) ---
+
+export class Bouncer {
+  constructor(user?: any, policyManager?: any);
+  user: any;
+  forUser(user: any): Bouncer;
+  allows(actionOrPolicy: string | Function, ...args: any[]): boolean;
+  denies(actionOrPolicy: string | Function, ...args: any[]): boolean;
+  authorize(actionOrPolicy: string | Function, ...args: any[]): boolean;
+}
+
+export function createBouncer(user?: any, policyManager?: any): Bouncer;
+
+export function createBouncerMiddleware(options?: { policyManager?: any }): import('express').RequestHandler;
+
+export function definePolicy(name: string, rules: Record<string, (user: any, ...args: any[]) => boolean | Promise<boolean>>): void;
+
+export function defineGate(name: string, callback: (user: any, ...args: any[]) => boolean | Promise<boolean>): void;
+
+export function can(user: any, action: string, policy?: string | null, resource?: any): boolean;
+
+export function cannot(user: any, action: string, policy?: string | null, resource?: any): boolean;
+
+export function authorize(user: any, action: string, policy?: string | null, resource?: any): void;
+
+// --- Decoupled Events & Signals (AdonisJS Events & Django Signals-inspired) ---
+
+export interface EventListenerOptions {
+  sender?: any;
+  priority?: number;
+  once?: boolean;
+}
+
+export class EventDispatcher {
+  constructor(options?: { queue?: any; maxListeners?: number; logger?: any });
+  on(event: string, handler: Function, options?: EventListenerOptions): () => void;
+  once(event: string, handler: Function, options?: EventListenerOptions): () => void;
+  off(event: string, handler: Function): this;
+  onAny(handler: (eventName: string, data: any, meta: any) => any, options?: { priority?: number; once?: boolean }): () => void;
+  emit(eventOrInstance: string | object, data?: any, options?: { sender?: any }): boolean;
+  emitAsync(eventOrInstance: string | object, data?: any, options?: { sender?: any }): Promise<Array<{ status: 'fulfilled' | 'rejected'; value?: any; reason?: any }>>;
+  emitParallel(eventOrInstance: string | object, data?: any, options?: { sender?: any }): Promise<Array<{ status: 'fulfilled' | 'rejected'; value?: any; reason?: any }>>;
+  emitSerial(eventOrInstance: string | object, data?: any, options?: { sender?: any }): Promise<any[]>;
+  emitWaterfall(eventOrInstance: string | object, initialData: any, options?: { sender?: any }): Promise<any>;
+  listenAndQueue(event: string, jobName: string, queueOptions?: Record<string, unknown>): () => void;
+  bridgeOrm(modelEvents?: any): () => void;
+  setQueue(queueManager: any): this;
+  eventNames(): string[];
+  listenerCount(event?: string): number;
+  removeAllListeners(event?: string): this;
+  clear(): void;
+}
+
+export function createEventDispatcher(options?: { queue?: any; maxListeners?: number; logger?: any }): EventDispatcher;
+
+export const events: EventDispatcher;
+
+export class Signal {
+  constructor(name: string, dispatcher: EventDispatcher);
+  name: string;
+  dispatcher: EventDispatcher;
+  connect(receiver: Function, options?: EventListenerOptions): () => void;
+  disconnect(receiver: Function): this;
+  send(data?: any, options?: { sender?: any }): boolean;
+  sendAsync(data?: any, options?: { sender?: any }): Promise<Array<{ status: 'fulfilled' | 'rejected'; value?: any; reason?: any }>>;
+  sendSerial(data?: any, options?: { sender?: any }): Promise<any[]>;
+}
+
+export function defineSignal(name: string, dispatcher?: EventDispatcher): Signal;
+
+export function defineListener(event: string | string[], handler: Function, options?: EventListenerOptions): { event: string | string[]; handle: Function; [key: string]: any };
+
+export function loadListeners(dirPath: string, dispatcher: EventDispatcher, options?: { logger?: any }): Array<{ file: string; event: string; handler: Function }>;
+
 // --- Helpers / assets ---
 
 export function createHelpers(context: Record<string, unknown>): Record<string, unknown>;
@@ -745,11 +895,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 {
@@ -955,6 +1114,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()` */
@@ -1040,9 +1201,9 @@ export interface Repository<T = Record<string, any>> {
   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>;
@@ -1126,6 +1287,8 @@ export interface MigrationManager {
   getConfig(): MigrationConfig & { directory: string; tableName: string };
   hasTable(): Promise<boolean>;
   unlock(): Promise<void>;
+  diff(options?: { models?: ModelDefinition<any>[]; includeDrops?: boolean }): Promise<{ hasChanges: boolean; changes: Array<any> }>;
+  makeMigrations(options?: { modelsDir?: string; dryRun?: boolean; includeDrops?: boolean; name?: string }): Promise<{ hasChanges: boolean; created: Array<any>; skipped: Array<any> }>;
 }
 
 export interface WebspressoModels {
@@ -1192,6 +1355,30 @@ export function createMemoryCacheProvider(options?: OrmMemoryCacheOptions): {
   getSizeStats(): { entries: number; tags: number };
 };
 
+// --- ORM: Model Factory & Seeding (AdonisJS Lucid-inspired) ---
+
+export interface FactoryBuilder<T = Record<string, any>> {
+  count(n: number): FactoryBuilder<T>;
+  state(...stateNames: string[]): FactoryBuilder<T>;
+  apply(...stateNames: string[]): FactoryBuilder<T>;
+  merge(overrides: Partial<T>): FactoryBuilder<T>;
+  make(overrides?: Partial<T>): T | T[];
+  create(options: { db?: DatabaseInstance | Repository<T>; merge?: Partial<T> } | DatabaseInstance | Repository<T>): Promise<T | T[]>;
+}
+
+export function defineFactory<T = Record<string, any>>(
+  modelName: string,
+  definitionFn: (ctx: { faker: any; index: number }) => Partial<T>
+): FactoryBuilder<T> & {
+  state(name: string, handler: ((ctx: { faker: any; index: number; current: Partial<T> }) => Partial<T>) | Partial<T>): FactoryBuilder<T>;
+  registerState(name: string, handler: ((ctx: { faker: any; index: number; current: Partial<T> }) => Partial<T>) | Partial<T>): FactoryBuilder<T>;
+};
+
+// --- ORM: Schema Diff & Makemigrations (Django-inspired) ---
+
+export function diffSchema(options: { knex: Knex; models?: ModelDefinition<any>[]; includeDrops?: boolean }): Promise<{ hasChanges: boolean; changes: Array<any> }>;
+export function makeMigrations(options: { knex: Knex; modelsDir?: string; migrationDir?: string; dryRun?: boolean; includeDrops?: boolean; name?: string }): Promise<{ hasChanges: boolean; created: Array<any>; skipped: Array<any> }>;
+
 // --- ORM: nanoid / zod ---
 
 export function generateNanoid(options?: { maxLength?: number } | number): string;
@@ -1533,11 +1720,73 @@ export function emailPlugin(options?: EmailPluginOptions): WebspressoPlugin & {
     isTransportReady(): boolean;
     loadFromManifest(chunks: any): void;
     emailPluginOptionsFromManifest(manifest: any): any;
+    mailer?: Mailer;
+    Mailable?: typeof Mailable;
+    getOutbox?(): any[];
+    clearOutbox?(): void;
+    lastMessage?(): any;
   };
   dispose?(): void;
   shutdown?(): void;
 };
 
+export class Mailable {
+  constructor();
+  to(recipient: string | string[] | any, name?: string): this;
+  from(address: string, name?: string): this;
+  replyTo(address: string): this;
+  cc(recipient: string | string[]): this;
+  bcc(recipient: string | string[]): this;
+  subject(subj: string): this;
+  template(tplName: string): this;
+  html(htmlContent: string): this;
+  text(textContent: string): this;
+  mjml(mjmlContent: string): this;
+  view(templateOrData: string | Record<string, unknown>, data?: Record<string, unknown>): this;
+  data(keyOrObj: string | Record<string, unknown>, value?: any): this;
+  attach(attachment: any): this;
+  header(key: string, value: string): this;
+  prepare(): void;
+  build(): void;
+  toMessage(): Record<string, any>;
+}
+
+export class Mailer {
+  constructor(options?: any);
+  send(mailableOrOptions: Mailable | Record<string, any>): Promise<any>;
+  preview(mailableOrOptions: Mailable | Record<string, any>): Promise<any>;
+  getOutbox(): any[];
+  clearOutbox(): void;
+  lastMessage(): any;
+  verify(): Promise<any>;
+}
+
+export function createMailer(options?: any): Mailer;
+
+export class MemoryTransport {
+  outbox: any[];
+  constructor(options?: any);
+  sendMail(mailOptions: any): Promise<any>;
+  getOutbox(): any[];
+  clearOutbox(): void;
+  lastMessage(): any;
+  findById(id: string): any;
+  verify(): Promise<boolean>;
+}
+
+export class ConsoleTransport {
+  constructor(options?: any);
+  sendMail(mailOptions: any): Promise<any>;
+  verify(): Promise<boolean>;
+}
+
+export class FileTransport {
+  dir: string;
+  constructor(options?: any);
+  sendMail(mailOptions: any): Promise<any>;
+  verify(): Promise<boolean>;
+}
+
 export function recaptchaPlugin(options?: Record<string, unknown>): WebspressoPlugin;
 
 export interface SwaggerPluginOptions {
@@ -1795,6 +2044,82 @@ export interface ApiKeyRouteOptions {
 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;
@@ -2283,8 +2608,11 @@ export interface QueueRetentionConfig {
 export interface ScheduleOptions {
   id?: string;
   overlap?: boolean;
+  preventOverlap?: boolean;
   maxRuns?: number;
   utc?: boolean;
+  timezone?: string;
+  tz?: string;
   runImmediately?: boolean;
   delay?: number | Date;
   attempts?: number;
@@ -2306,6 +2634,7 @@ export interface ScheduleInfo {
   nextRunAt: Date | null;
   isRunning: boolean;
   activeJobId: string | number | null;
+  activeJobIds?: (string | number)[];
   registeredAt: Date;
 }
 
@@ -2313,21 +2642,22 @@ 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 });
-  match(date?: Date): boolean;
-  getNextDate(fromDate?: Date): Date | null;
-  getNextDates(count?: number, fromDate?: Date): Date[];
-  static isValid(expression: string): boolean;
-  static parse(expression: string, options?: { utc?: boolean }): CronExpression;
+  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 }): CronExpression;
-export function isValidCron(expression: string): boolean;
+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>;
 
@@ -2345,6 +2675,8 @@ export class TaskScheduler {
   trigger(idOrJobName: string): Promise<Job | null>;
   start(): this;
   stop(): this;
+  pause(): this;
+  resume(): this;
   clear(): void;
   destroy(): void;
 }
@@ -2379,6 +2711,8 @@ export class QueueManager extends EventEmitter {
   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;
@@ -2453,14 +2787,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;
@@ -3155,10 +3495,196 @@ export namespace totp {
   };
 }
 
+// --- 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,
+  };
+}
+
+// Custom Management Commands (Django & Adonis Ace-inspired)
+export interface CommandOption {
+  flags: string;
+  description?: string;
+  defaultValue?: any;
+}
+
+export interface CommandExecutionContext {
+  db: any;
+  queue: any;
+  services: any;
+  mailer: any;
+  events: any;
+  logger: any;
+  args: string[];
+  flags: Record<string, any>;
+}
+
+export interface CommandDefinition {
+  name: string;
+  description?: string;
+  options?: CommandOption[];
+  handle: (ctx: CommandExecutionContext) => Promise<any> | any;
+}
+
+export interface CommandRegistry {
+  register(cmd: CommandDefinition): CommandDefinition;
+  reload(): void;
+  has(name: string): boolean;
+  get(name: string): CommandDefinition | null;
+  list(): CommandDefinition[];
+  names(): string[];
+  readonly commandsDir: string;
+}
+
+export function defineCommand(definition: CommandDefinition): CommandDefinition;
+export function createCommandRegistry(options?: { commandsDir?: string; autoLoad?: boolean }): CommandRegistry;
+export function executeCommand(
+  commandDef: CommandDefinition,
+  executionOptions?: Partial<CommandExecutionContext>
+): Promise<{ success: boolean; result?: any; error?: Error; durationMs: number }>;
+
+export namespace commands {
+  export {
+    defineCommand,
+    createCommandRegistry,
+    executeCommand,
+  };
+}