nucleus-core-ts 0.8.0

package/dist/src/Services/Captcha/types.d.ts

@@ -0,0 +1,69 @@
+export type CaptchaType = "math" | "image" | "puzzle" | "text";
+export type CaptchaDifficulty = "easy" | "medium" | "hard";
+export interface CaptchaConfig {
+    enabled?: boolean;
+    type?: CaptchaType;
+    difficulty?: CaptchaDifficulty;
+    expiresIn?: string;
+    maxAttempts?: number;
+    caseSensitive?: boolean;
+    rateLimit?: {
+        maxGeneratePerMinute?: number;
+        maxGeneratePerHour?: number;
+    };
+}
+export interface CaptchaChallenge {
+    id: string;
+    type: CaptchaType;
+    question: string;
+    answer: string;
+    imageData?: string;
+    puzzleData?: PuzzleData;
+    expiresAt: number;
+    attempts: number;
+    maxAttempts: number;
+    caseSensitive: boolean;
+}
+export interface PuzzleData {
+    pieces: PuzzlePiece[];
+    correctOrder: number[];
+    imageUrl?: string;
+}
+export interface PuzzlePiece {
+    id: number;
+    x: number;
+    y: number;
+}
+export interface CaptchaGenerateResult {
+    success: boolean;
+    challengeId: string;
+    type: CaptchaType;
+    question: string;
+    imageData?: string;
+    puzzleData?: Omit<PuzzleData, "correctOrder">;
+    expiresAt: number;
+    rateLimited?: boolean;
+    message?: string;
+}
+export interface CaptchaValidateResult {
+    success: boolean;
+    valid: boolean;
+    message?: string;
+    attemptsRemaining?: number;
+}
+export interface CaptchaServiceDeps {
+    redis: {
+        get: (key: string) => Promise<string | null>;
+        set: (key: string, value: string, options?: {
+            ex?: number;
+        }) => Promise<void>;
+        del: (key: string) => Promise<void>;
+    };
+    logger: {
+        info: (message: string, context?: Record<string, unknown>) => void;
+        warn: (message: string, context?: Record<string, unknown>) => void;
+        error: (message: string, context?: Record<string, unknown>) => void;
+    };
+    config: CaptchaConfig;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/Services/Gmail/index.d.ts

@@ -0,0 +1,62 @@
+import type { Logger } from "../Logger";
+export interface EmailAttachment {
+    filename: string;
+    content: Buffer;
+    contentType: string;
+}
+export interface EmailPayload {
+    to: string | string[];
+    subject: string;
+    html?: string;
+    text?: string;
+    from?: string;
+    replyTo?: string;
+    attachments?: EmailAttachment[];
+}
+export interface GmailServiceConfig {
+    enabled: boolean;
+    jsonFilePath?: string;
+    fromEmail: string;
+    fromName?: string;
+}
+export declare class GmailService {
+    private gmail;
+    private fromEmail;
+    private fromName;
+    private logger;
+    private initialized;
+    constructor(config: GmailServiceConfig, logger: Logger);
+    private encodeHeaderValue;
+    isAvailable(): boolean;
+    private initialize;
+    private createEmailMessage;
+    sendEmail(payload: EmailPayload): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    sendWelcomeEmail(email: string, name: string, appName?: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    sendVerificationEmail(email: string, name: string, verificationLink: string, appName?: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    sendPasswordResetEmail(email: string, name: string, resetLink: string, appName?: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    sendMagicLinkEmail(email: string, magicLink: string, appName?: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    sendAlertEmail(to: string, subject: string, html: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    sendInvitationEmail(email: string, inviteLink: string, appName?: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Logger/Logger.d.ts

@@ -0,0 +1,77 @@
+import type { AuditTransport, LogContext, LoggerConfig, LoggerTransport, LogLevel, TraceOptions } from "./types";
+export declare class Logger {
+    private config;
+    private transports;
+    private auditTransports;
+    private context;
+    private correlationId?;
+    private static instance;
+    constructor(config?: Partial<LoggerConfig>, context?: LogContext, correlationId?: string);
+    static getInstance(config?: Partial<LoggerConfig>): Logger;
+    static resetInstance(): void;
+    child(context: LogContext, correlationId?: string): Logger;
+    withCorrelationId(correlationId: string): Logger;
+    addTransport(transport: LoggerTransport): void;
+    addAuditTransport(transport: AuditTransport): void;
+    setLevel(level: LogLevel): void;
+    setAuditEnabled(enabled: boolean): void;
+    isAuditEnabled(): boolean;
+    private shouldLog;
+    private createEntry;
+    private log;
+    debug(message: string, context?: LogContext): void;
+    info(message: string, context?: LogContext): void;
+    warn(message: string, context?: LogContext): void;
+    error(message: string, error?: unknown, context?: LogContext): void;
+    fatal(message: string, error?: unknown, context?: LogContext): void;
+    time(label: string): () => void;
+    timeAsync<T>(label: string, fn: () => Promise<T>, context?: LogContext): Promise<T>;
+    request(options: {
+        method: string;
+        path: string;
+        statusCode: number;
+        duration: number;
+        correlationId?: string;
+        userId?: string;
+        ip?: string;
+        userAgent?: string;
+    }): void;
+    db(options: {
+        operation: string;
+        table: string;
+        duration: number;
+        rowCount?: number;
+        error?: unknown;
+    }): void;
+    flush(): Promise<void>;
+    audit(options: {
+        entityName: string;
+        entityId?: string | null;
+        operation: string;
+        userId?: string | null;
+        summary?: string;
+        oldValues?: Record<string, unknown>;
+        newValues?: Record<string, unknown>;
+        ipAddress?: string;
+        userAgent?: string;
+        path?: string;
+        query?: string;
+    }): Promise<void>;
+    auditOnly(options: {
+        entityName: string;
+        entityId?: string | null;
+        operation: string;
+        userId?: string | null;
+        summary?: string;
+        oldValues?: Record<string, unknown>;
+        newValues?: Record<string, unknown>;
+        ipAddress?: string;
+        userAgent?: string;
+        path?: string;
+        query?: string;
+    }): void;
+    trace(options: TraceOptions): Promise<void>;
+    traceSync(options: TraceOptions): void;
+}
+export declare const logger: Logger;
+//# sourceMappingURL=Logger.d.ts.map

package/dist/src/Services/Logger/index.d.ts

@@ -0,0 +1,5 @@
+export { Logger, logger } from "./Logger";
+export { BufferedTransport, ConsoleAuditTransport, ConsoleTransport, DatabaseAuditTransport, } from "./transports";
+export type { AuditEntry, AuditTransport, CallerInfo, ErrorInfo, LogContext, LogEntry, LoggerConfig, LoggerTransport, LogLevel, TraceOptions, } from "./types";
+export { formatDuration, formatError, redactSensitiveData, safeStringify, } from "./utils";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Logger/transports.d.ts

@@ -0,0 +1,54 @@
+import type { AuditEntry, AuditTransport, LogEntry, LoggerTransport } from "./types";
+export declare class ConsoleTransport implements LoggerTransport {
+    name: string;
+    private colorize;
+    private prettyPrint;
+    constructor(options?: {
+        colorize?: boolean;
+        prettyPrint?: boolean;
+    });
+    log(entry: LogEntry): void;
+    private logJson;
+    private logPretty;
+    private getConsoleMethod;
+}
+export declare class BufferedTransport implements LoggerTransport {
+    name: string;
+    private buffer;
+    private bufferSize;
+    private flushIntervalMs;
+    private innerTransport;
+    private flushTimer;
+    private isFlushing;
+    constructor(innerTransport: LoggerTransport, options?: {
+        bufferSize?: number;
+        flushIntervalMs?: number;
+    });
+    log(entry: LogEntry): void;
+    flush(): Promise<void>;
+    destroy(): void;
+}
+export declare class DatabaseAuditTransport implements AuditTransport {
+    name: string;
+    private db;
+    private table;
+    private enabled;
+    constructor(options: {
+        db: unknown;
+        table: unknown;
+        enabled?: boolean;
+    });
+    setDb(db: unknown): void;
+    setTable(table: unknown): void;
+    setEnabled(enabled: boolean): void;
+    write(entry: AuditEntry): Promise<void>;
+}
+export declare class ConsoleAuditTransport implements AuditTransport {
+    name: string;
+    private enabled;
+    constructor(options?: {
+        enabled?: boolean;
+    });
+    write(entry: AuditEntry): void;
+}
+//# sourceMappingURL=transports.d.ts.map

package/dist/src/Services/Logger/types.d.ts

@@ -0,0 +1,88 @@
+export type LogLevel = "debug" | "info" | "warn" | "error" | "fatal";
+export type LogContext = Record<string, unknown>;
+export interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    message: string;
+    context?: LogContext;
+    correlationId?: string;
+    service?: string;
+    caller?: CallerInfo;
+    error?: ErrorInfo;
+    duration?: number;
+}
+export interface CallerInfo {
+    file: string;
+    line: number;
+    function: string;
+}
+export interface ErrorInfo {
+    name: string;
+    message: string;
+    stack?: string;
+    code?: string | number;
+}
+export interface LoggerConfig {
+    level: LogLevel;
+    service: string;
+    environment: "development" | "production" | "test";
+    redactKeys: string[];
+    colorize: boolean;
+    prettyPrint: boolean;
+    includeCallerInfo: boolean;
+    asyncBufferSize: number;
+    flushIntervalMs: number;
+    auditEnabled: boolean;
+}
+export interface TraceOptions {
+    message: string;
+    level?: LogLevel;
+    context?: LogContext;
+    error?: unknown;
+    audit?: {
+        entityName: string;
+        entityId?: string | null;
+        operation: string;
+        userId?: string | null;
+        summary?: string;
+        oldValues?: Record<string, unknown>;
+        newValues?: Record<string, unknown>;
+        ipAddress?: string;
+        userAgent?: string;
+        path?: string;
+        query?: string;
+    };
+    log?: boolean;
+    writeAudit?: boolean;
+}
+export interface LoggerTransport {
+    name: string;
+    log(entry: LogEntry): void | Promise<void>;
+    flush?(): void | Promise<void>;
+}
+export interface AuditTransport {
+    name: string;
+    write(entry: AuditEntry): void | Promise<void>;
+}
+export interface AuditEntry {
+    id: string;
+    timestamp: string;
+    entityName: string;
+    entityId: string | null;
+    operation: string;
+    userId: string | null;
+    summary: string;
+    oldValues: Record<string, unknown>;
+    newValues: Record<string, unknown>;
+    ipAddress: string;
+    userAgent: string;
+    path: string;
+    query: string;
+    correlationId?: string;
+}
+export declare const LOG_LEVEL_PRIORITY: Record<LogLevel, number>;
+export declare const LOG_LEVEL_COLORS: Record<LogLevel, string>;
+export declare const RESET_COLOR = "\u001B[0m";
+export declare const DIM_COLOR = "\u001B[2m";
+export declare const BOLD_COLOR = "\u001B[1m";
+//# sourceMappingURL=types.d.ts.map

package/dist/src/Services/Logger/utils.d.ts

@@ -0,0 +1,8 @@
+import type { CallerInfo, ErrorInfo, LogContext } from "./types";
+export declare function redactSensitiveData(obj: unknown, redactKeys?: string[], seen?: WeakSet<WeakKey>): unknown;
+export declare function getCallerInfo(stackOffset?: number): CallerInfo;
+export declare function formatError(error: unknown): ErrorInfo;
+export declare function mergeContext(base: LogContext | undefined, additional: LogContext | undefined): LogContext | undefined;
+export declare function formatDuration(ms: number): string;
+export declare function safeStringify(obj: unknown, indent?: number): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/src/Services/Monitoring/AlertService.d.ts

@@ -0,0 +1,29 @@
+import type { GmailService } from "../Gmail";
+import type { Logger } from "../Logger";
+import type { AlertEvent, AlertType, MonitoringConfig, MonitoringSnapshot } from "./types";
+interface AlertServiceDeps {
+    logger: Logger;
+    gmail?: GmailService;
+    config: MonitoringConfig;
+    appId: string;
+}
+export declare class AlertService {
+    private logger;
+    private gmail?;
+    private config;
+    private appId;
+    private state;
+    private cooldownMs;
+    constructor(deps: AlertServiceDeps);
+    private parseTimeToMs;
+    checkAndAlert(snapshot: MonitoringSnapshot): Promise<AlertEvent[]>;
+    private createAlert;
+    private getSeverity;
+    private sendAlerts;
+    private buildEmailHtml;
+    getActiveAlerts(): AlertEvent[];
+    acknowledgeAlert(alertId: string): boolean;
+    clearAlert(type: AlertType): void;
+}
+export {};
+//# sourceMappingURL=AlertService.d.ts.map

package/dist/src/Services/Monitoring/collectors/ApplicationCollector.d.ts

@@ -0,0 +1,30 @@
+import type { ApplicationMetrics, MonitoringConfig } from "../types";
+export declare class ApplicationCollector {
+    private config;
+    private requestCount;
+    private responseTimes;
+    private errorCount;
+    private rateLimitBlocks;
+    private byEndpoint;
+    private byMethod;
+    private byStatus;
+    private byErrorType;
+    private lastCollectTime;
+    constructor(config: MonitoringConfig["application"]);
+    recordRequest(params: {
+        endpoint: string;
+        method: string;
+        status: number;
+        responseTimeMs: number;
+        isError?: boolean;
+        errorType?: string;
+    }): void;
+    recordRateLimitBlock(): void;
+    collect(): ApplicationMetrics | null;
+    reset(): void;
+    getRequestsPerMinute(): number;
+    getErrorRate(): number;
+    getRateLimitBlocksPerMinute(): number;
+    getAvgResponseTime(): number;
+}
+//# sourceMappingURL=ApplicationCollector.d.ts.map

package/dist/src/Services/Monitoring/collectors/SystemCollector.d.ts

@@ -0,0 +1,13 @@
+import type { MonitoringConfig, SystemMetrics } from "../types";
+export declare class SystemCollector {
+    private config;
+    private lastCpuInfo;
+    constructor(config: MonitoringConfig["system"]);
+    collect(): Promise<SystemMetrics | null>;
+    private collectCpu;
+    private collectMemory;
+    private collectDisk;
+    private collectNetwork;
+    private collectProcess;
+}
+//# sourceMappingURL=SystemCollector.d.ts.map

package/dist/src/Services/Monitoring/collectors/index.d.ts

@@ -0,0 +1,3 @@
+export { ApplicationCollector } from "./ApplicationCollector";
+export { SystemCollector } from "./SystemCollector";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Monitoring/index.d.ts

@@ -0,0 +1,109 @@
+import type { RedisManager } from "../../Managers/Redis";
+import type { GmailService } from "../Gmail";
+import type { Logger } from "../Logger";
+import type { AlertEvent, MetricPoint, MonitoringConfig, MonitoringSnapshot } from "./types";
+export { AlertService } from "./AlertService";
+export * from "./types";
+interface MonitoringServiceDeps {
+    redis: RedisManager;
+    logger: Logger;
+    gmail?: GmailService;
+    config: MonitoringConfig;
+    appId: string;
+    flushToDb?: (metrics: MetricPoint[]) => Promise<void>;
+}
+interface MergedConfig {
+    enabled: boolean;
+    system: {
+        enabled: boolean;
+        collectInterval: string;
+        metrics: {
+            cpu: boolean;
+            memory: boolean;
+            disk: boolean;
+            network: boolean;
+            process: boolean;
+        };
+    };
+    application: {
+        enabled: boolean;
+        metrics: {
+            requests: boolean;
+            responseTime: boolean;
+            errors: boolean;
+            rateLimits: boolean;
+        };
+    };
+    database: {
+        enabled: boolean;
+        metrics: {
+            connections: boolean;
+            queryTime: boolean;
+            slowQueryThreshold: string;
+        };
+    };
+    redis: {
+        enabled: boolean;
+    };
+    persistence: {
+        enabled: boolean;
+        flushInterval: string;
+        retentionDays: number;
+    };
+    alerts: {
+        enabled: boolean;
+        email: {
+            enabled: boolean;
+            recipients: string[];
+        };
+        thresholds: {
+            cpuPercent: number;
+            memoryPercent: number;
+            diskPercent: number;
+            errorRatePercent: number;
+            responseTimeMs: number;
+            rateLimitBlocksPerMinute: number;
+        };
+        cooldown: string;
+    };
+}
+export declare class MonitoringService {
+    private redis;
+    private logger;
+    private config;
+    private appId;
+    private flushToDb?;
+    private systemCollector;
+    private applicationCollector;
+    private alertService;
+    private collectInterval;
+    private flushInterval;
+    private pendingMetrics;
+    private isRunning;
+    constructor(deps: MonitoringServiceDeps);
+    private mergeConfig;
+    private parseTimeToMs;
+    start(): void;
+    stop(): void;
+    private collect;
+    private addMetricPoints;
+    private storeSnapshot;
+    private flush;
+    recordRequest(params: {
+        endpoint: string;
+        method: string;
+        status: number;
+        responseTimeMs: number;
+        isError?: boolean;
+        errorType?: string;
+    }): void;
+    recordRateLimitBlock(): void;
+    getLatestSnapshot(): Promise<MonitoringSnapshot | null>;
+    getHistory(minutes?: number): Promise<MonitoringSnapshot[]>;
+    getActiveAlerts(): AlertEvent[];
+    acknowledgeAlert(alertId: string): boolean;
+    isEnabled(): boolean;
+    getConfig(): MergedConfig;
+}
+export declare function createMonitoringService(deps: MonitoringServiceDeps): MonitoringService;
+//# sourceMappingURL=index.d.ts.map