@open-core/framework 1.0.2-beta.1 → 1.0.5-beta.1

package/dist/kernel/error/app.error.d.ts

@@ -0,0 +1,9 @@
+import { ErrorOrigin } from './common.error-codes';
+import { FrameworkErrorCode } from './framework.error-codes';
+export declare class AppError extends Error {
+    readonly code: FrameworkErrorCode;
+    readonly details?: unknown;
+    readonly origin: ErrorOrigin;
+    constructor(code: FrameworkErrorCode, message: string, origin: ErrorOrigin, details?: unknown);
+}
+export declare function isAppError(error: unknown): error is AppError;

package/dist/kernel/error/app.error.js

@@ -0,0 +1,15 @@
+export class AppError extends Error {
+    code;
+    details;
+    origin;
+    constructor(code, message, origin, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.origin = origin;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export function isAppError(error) {
+    return error instanceof AppError;
+}

package/dist/kernel/error/common.error-codes.d.ts

@@ -0,0 +1 @@
+export type ErrorOrigin = 'client' | 'server' | 'core' | 'external';

package/dist/kernel/error/framework.error-codes.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Framework error codes grouped by category
+ */
+export type FrameworkErrorCode = CommonErrorCode | AuthErrorCode | ApiErrorCode | NetworkErrorCode | GameErrorCode | SchemaErrorCode | CommandErrorCode | EconomyErrorCode;
+export type CommonErrorCode = 'COMMON:UNKNOWN' | 'COMMON:NOT_IMPLEMENTED';
+export type AuthErrorCode = 'AUTH:UNAUTHORIZED' | 'AUTH:PERMISSION_DENIED';
+export type ApiErrorCode = 'API:ERROR';
+export type NetworkErrorCode = 'NETWORK:ERROR';
+export type GameErrorCode = 'GAME:PLAYER_NOT_FOUND' | 'GAME:NO_RANK_IN_PRINCIPAL' | 'GAME:INVALID_STATE' | 'GAME:BAD_REQUEST';
+export type SchemaErrorCode = 'SCHEMA:VALIDATION_ERROR' | 'SCHEMA:MISMATCH';
+export type CommandErrorCode = 'COMMAND:NOT_FOUND' | 'COMMAND:DUPLICATE';
+export type EconomyErrorCode = 'ECONOMY:INSUFFICIENT_FUNDS';

package/dist/kernel/error/index.d.ts

@@ -0,0 +1,4 @@
+export * from './app.error';
+export type * from './common.error-codes';
+export type * from './framework.error-codes';
+export * from './security.error';

package/dist/kernel/error/index.js

@@ -0,0 +1,2 @@
+export * from './app.error';
+export * from './security.error';

package/dist/kernel/error/security.error.d.ts

@@ -0,0 +1,6 @@
+import { AppError } from './app.error';
+import { SecurityAction } from './security.types';
+export declare class SecurityError extends AppError {
+    readonly action: SecurityAction;
+    constructor(action: SecurityAction, message: string, details?: unknown);
+}

package/dist/kernel/error/security.error.js

@@ -0,0 +1,9 @@
+import { AppError } from './app.error';
+export class SecurityError extends AppError {
+    action;
+    constructor(action, message, details) {
+        super('NETWORK:ERROR', message, 'core', details);
+        this.action = action;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}

package/dist/kernel/index.d.ts

@@ -0,0 +1,6 @@
+export * from './di/container';
+export * from './error';
+export * from './logger';
+export * from './schema';
+export * from './shared';
+export * from './utils';

package/dist/kernel/index.js

@@ -0,0 +1,7 @@
+// External to export
+export * from './di/container';
+export * from './error';
+export * from './logger';
+export * from './schema';
+export * from './shared';
+export * from './utils';

package/dist/kernel/logger/core-logger.d.ts

@@ -0,0 +1,31 @@
+import { LoggerService } from './logger.service';
+/**
+ * Singleton logger instance for internal OpenCore framework use.
+ */
+export declare const coreLogger: LoggerService;
+export declare const loggers: {
+    /** Bootstrap and initialization logs */
+    bootstrap: import("./logger.service").ChildLogger;
+    /** Metadata scanning and decorator processing */
+    scanner: import("./logger.service").ChildLogger;
+    /** Player session management */
+    session: import("./logger.service").ChildLogger;
+    /** Command registration and execution */
+    command: import("./logger.service").ChildLogger;
+    /** Network events processing */
+    netEvent: import("./logger.service").ChildLogger;
+    /** Security violations and access control */
+    security: import("./logger.service").ChildLogger;
+    /** Core event bus */
+    eventBus: import("./logger.service").ChildLogger;
+    /** Export registration */
+    exports: import("./logger.service").ChildLogger;
+    /** Tick handlers (server) */
+    tick: import("./logger.service").ChildLogger;
+    /** NUI callbacks (client) */
+    nui: import("./logger.service").ChildLogger;
+    /** Spawn service (client) */
+    spawn: import("./logger.service").ChildLogger;
+    /** */
+    api: import("./logger.service").ChildLogger;
+};

package/dist/kernel/logger/core-logger.js

@@ -0,0 +1,66 @@
+import { GLOBAL_CONTAINER } from '../di/container';
+import { getLogLevel, isClientEnvironment } from './logger.env';
+import { LoggerService } from './logger.service';
+import { LogDomain } from './logger.types';
+import { ConsoleTransport } from './transports/console.transport';
+import { SimpleConsoleTransport } from './transports/simple-console.transport';
+/**
+ * Creates the appropriate transport based on the runtime environment.
+ * - Client: SimpleConsoleTransport (no ANSI colors)
+ * - Server: ConsoleTransport (with ANSI colors)
+ */
+function createTransport() {
+    const logLevel = getLogLevel();
+    if (isClientEnvironment()) {
+        return new SimpleConsoleTransport({
+            minLevel: logLevel,
+            timestamps: true,
+            showContext: false,
+        });
+    }
+    return new ConsoleTransport({
+        minLevel: logLevel,
+        colors: true,
+        timestamps: true,
+    });
+}
+const defaultLoggerConfig = {
+    minLevel: getLogLevel(),
+    defaultDomain: LogDomain.FRAMEWORK,
+    defaultSource: 'Core',
+    transports: [createTransport()],
+};
+// Register for DI
+GLOBAL_CONTAINER.registerInstance('LoggerConfig', defaultLoggerConfig);
+GLOBAL_CONTAINER.registerSingleton(LoggerService);
+/**
+ * Singleton logger instance for internal OpenCore framework use.
+ */
+export const coreLogger = GLOBAL_CONTAINER.resolve(LoggerService);
+// Pre-configured child loggers for common framework components
+export const loggers = {
+    /** Bootstrap and initialization logs */
+    bootstrap: coreLogger.framework('Bootstrap'),
+    /** Metadata scanning and decorator processing */
+    scanner: coreLogger.framework('Scanner'),
+    /** Player session management */
+    session: coreLogger.framework('Session'),
+    /** Command registration and execution */
+    command: coreLogger.framework('Command'),
+    /** Network events processing */
+    netEvent: coreLogger.framework('NetEvent'),
+    /** Security violations and access control */
+    security: coreLogger.framework('Security'),
+    /** Core event bus */
+    eventBus: coreLogger.framework('EventBus'),
+    /** Export registration */
+    exports: coreLogger.framework('Exports'),
+    /** Tick handlers (server) */
+    tick: coreLogger.framework('Tick'),
+    /** NUI callbacks (client) */
+    nui: coreLogger.client('NUI'),
+    /** Spawn service (client) */
+    spawn: coreLogger.client('Spawn'),
+    /** */
+    api: coreLogger.framework('API'),
+};

package/dist/kernel/logger/index.d.ts

@@ -0,0 +1,14 @@
+export { coreLogger, loggers } from './core-logger';
+export type { LoggerConfig } from './logger.config';
+export { createLoggerConfig, DEFAULT_LOGGER_CONFIG } from './logger.config';
+export { getLogLevel, isClientEnvironment, isDebugMode, isFiveMEnvironment, isServerEnvironment, } from './logger.env';
+export { ChildLogger, LoggerService } from './logger.service';
+export type { LogContext, LogEntry } from './logger.types';
+export { LogDomain, LogDomainLabels, LogLevel, LogLevelLabels, parseLogLevel } from './logger.types';
+export type { BufferedTransportOptions, LogOutputFormat } from './transports/buffered.transport';
+export { BufferedTransport } from './transports/buffered.transport';
+export type { ConsoleTransportOptions } from './transports/console.transport';
+export { ConsoleTransport } from './transports/console.transport';
+export type { SimpleConsoleTransportOptions } from './transports/simple-console.transport';
+export { SimpleConsoleTransport } from './transports/simple-console.transport';
+export type { LogTransport } from './transports/transport.interface';

package/dist/kernel/logger/index.js

@@ -0,0 +1,12 @@
+// Core Logger (internal framework use)
+export { coreLogger, loggers } from './core-logger';
+// Config
+export { createLoggerConfig, DEFAULT_LOGGER_CONFIG } from './logger.config';
+// Environment utilities
+export { getLogLevel, isClientEnvironment, isDebugMode, isFiveMEnvironment, isServerEnvironment, } from './logger.env';
+// Service
+export { ChildLogger, LoggerService } from './logger.service';
+export { LogDomain, LogDomainLabels, LogLevel, LogLevelLabels, parseLogLevel } from './logger.types';
+export { BufferedTransport } from './transports/buffered.transport';
+export { ConsoleTransport } from './transports/console.transport';
+export { SimpleConsoleTransport } from './transports/simple-console.transport';

package/dist/kernel/logger/logger.config.d.ts

@@ -0,0 +1,47 @@
+import { LogDomain, LogLevel } from './logger.types';
+import { LogTransport } from './transports/transport.interface';
+/**
+ * Global configuration options for the LoggerService.
+ */
+export interface LoggerConfig {
+    /**
+     * Global minimum log level. Logs below this level will be ignored entirely.
+     * Individual transports can have their own minLevel that's higher than this.
+     * @default LogLevel.DEBUG
+     */
+    minLevel: LogLevel;
+    /**
+     * Default domain/origin for logs when none is provided.
+     * @default LogDomain.SERVER
+     */
+    defaultDomain: LogDomain;
+    /**
+     * Default source name to use when none is provided.
+     * @default 'App'
+     */
+    defaultSource: string;
+    /**
+     * Array of transports that will receive log entries.
+     * If empty, a default ConsoleTransport will be used.
+     */
+    transports: LogTransport[];
+}
+/**
+ * Default configuration used when no custom config is provided.
+ */
+export declare const DEFAULT_LOGGER_CONFIG: LoggerConfig;
+/**
+ * Creates a new logger configuration by merging with defaults.
+ *
+ * @example
+ * ```typescript
+ * const config = createLoggerConfig({
+ *   minLevel: LogLevel.INFO,
+ *   transports: [
+ *     new ConsoleTransport({ colors: true }),
+ *     new MyCustomFileTransport()
+ *   ]
+ * })
+ * ```
+ */
+export declare function createLoggerConfig(partial: Partial<LoggerConfig>): LoggerConfig;

package/dist/kernel/logger/logger.config.js

@@ -0,0 +1,32 @@
+import { LogDomain, LogLevel } from './logger.types';
+import { ConsoleTransport } from './transports/console.transport';
+/**
+ * Default configuration used when no custom config is provided.
+ */
+export const DEFAULT_LOGGER_CONFIG = {
+    minLevel: LogLevel.DEBUG,
+    defaultDomain: LogDomain.SERVER,
+    defaultSource: 'App',
+    transports: [new ConsoleTransport()],
+};
+/**
+ * Creates a new logger configuration by merging with defaults.
+ *
+ * @example
+ * ```typescript
+ * const config = createLoggerConfig({
+ *   minLevel: LogLevel.INFO,
+ *   transports: [
+ *     new ConsoleTransport({ colors: true }),
+ *     new MyCustomFileTransport()
+ *   ]
+ * })
+ * ```
+ */
+export function createLoggerConfig(partial) {
+    return {
+        ...DEFAULT_LOGGER_CONFIG,
+        ...partial,
+        transports: partial.transports ?? DEFAULT_LOGGER_CONFIG.transports,
+    };
+}

package/dist/kernel/logger/logger.env.d.ts

@@ -0,0 +1,35 @@
+import { LogLevel } from './logger.types';
+/**
+ * Detects the current runtime environment side.
+ *
+ * @returns 'client' | 'server' | 'node'
+ */
+export declare function detectEnvironmentSide(): 'client' | 'server' | 'node';
+/**
+ * Detects if we're running in a FiveM client environment.
+ */
+export declare function isClientEnvironment(): boolean;
+/**
+ * Detects if we're running in a FiveM server environment.
+ */
+export declare function isServerEnvironment(): boolean;
+/**
+ * Detects if we're running in a FiveM environment (client or server).
+ */
+export declare function isFiveMEnvironment(): boolean;
+/**
+ * Gets the globally configured log level for the framework.
+ *
+ * @remarks
+ * The log level is resolved in the following order:
+ * 1. Build-time injection (`__OPENCORE_LOG_LEVEL__`) via CLI.
+ * 2. Fallback to `INFO` level.
+ *
+ * @returns The resolved {@link LogLevel}
+ */
+export declare function getLogLevel(): LogLevel;
+/**
+ * Checks if debug mode is enabled based on log level.
+ * Debug mode is enabled when log level is DEBUG or TRACE.
+ */
+export declare function isDebugMode(): boolean;

package/dist/kernel/logger/logger.env.js

@@ -0,0 +1,59 @@
+import { LogLevel, parseLogLevel } from './logger.types';
+/**
+ * Detects the current runtime environment side.
+ *
+ * @returns 'client' | 'server' | 'node'
+ */
+export function detectEnvironmentSide() {
+    if (typeof __OPENCORE_TARGET__ !== 'undefined') {
+        return __OPENCORE_TARGET__;
+    }
+    if (typeof globalThis.GetPlayerPed === 'function' &&
+        typeof globalThis.GetNumPlayerIndices !== 'function') {
+        return 'client';
+    }
+    if (typeof globalThis.GetNumPlayerIndices === 'function') {
+        return 'server';
+    }
+    return 'node';
+}
+/**
+ * Detects if we're running in a FiveM client environment.
+ */
+export function isClientEnvironment() {
+    return detectEnvironmentSide() === 'client';
+}
+/**
+ * Detects if we're running in a FiveM server environment.
+ */
+export function isServerEnvironment() {
+    return detectEnvironmentSide() === 'server';
+}
+/**
+ * Detects if we're running in a FiveM environment (client or server).
+ */
+export function isFiveMEnvironment() {
+    const side = detectEnvironmentSide();
+    return side === 'client' || side === 'server';
+}
+/**
+ * Gets the globally configured log level for the framework.
+ *
+ * @remarks
+ * The log level is resolved in the following order:
+ * 1. Build-time injection (`__OPENCORE_LOG_LEVEL__`) via CLI.
+ * 2. Fallback to `INFO` level.
+ *
+ * @returns The resolved {@link LogLevel}
+ */
+export function getLogLevel() {
+    const level = typeof __OPENCORE_LOG_LEVEL__ !== 'undefined' ? __OPENCORE_LOG_LEVEL__ : 'INFO';
+    return parseLogLevel(level);
+}
+/**
+ * Checks if debug mode is enabled based on log level.
+ * Debug mode is enabled when log level is DEBUG or TRACE.
+ */
+export function isDebugMode() {
+    return getLogLevel() <= LogLevel.DEBUG;
+}

package/dist/kernel/logger/logger.service.d.ts

@@ -0,0 +1,175 @@
+import { type LoggerConfig } from './logger.config';
+import { type LogContext, LogDomain, LogLevel } from './logger.types';
+import { LogTransport } from './transports/transport.interface';
+/**
+ * Central logging service for the framework.
+ *
+ * Provides structured logging with support for multiple transports,
+ * log levels, and contextual metadata for traceability.
+ *
+ * @example
+ * ```typescript
+ * // Using with dependency injection
+ * @injectable()
+ * class MyController {
+ *   constructor(private logger: LoggerService) {}
+ *
+ *   doSomething() {
+ *     this.logger.info('Operation started', { source: 'MyController' })
+ *     this.logger.debug('Processing data', { playerId: 123 })
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Manual instantiation with custom config
+ * const logger = new LoggerService({
+ *   minLevel: LogLevel.INFO,
+ *   transports: [new ConsoleTransport(), new FileTransport()]
+ * })
+ * ```
+ */
+export declare class LoggerService {
+    private config;
+    constructor(config?: Partial<LoggerConfig>);
+    /**
+     * Log a TRACE level message. Most verbose, for deep debugging.
+     */
+    trace(message: string, context?: LogContext): void;
+    /**
+     * Log a DEBUG level message. Development-time information.
+     */
+    debug(message: string, context?: LogContext): void;
+    /**
+     * Log an INFO level message. General operational information.
+     */
+    info(message: string, context?: LogContext): void;
+    /**
+     * Log a WARN level message. Something unexpected but not necessarily wrong.
+     */
+    warn(message: string, context?: LogContext): void;
+    /**
+     * Log an ERROR level message. Something went wrong but the app can continue.
+     */
+    error(message: string, context?: LogContext, error?: Error): void;
+    /**
+     * Log a FATAL level message. Critical error, the app may need to stop.
+     */
+    fatal(message: string, context?: LogContext, error?: Error): void;
+    /**
+     * Add a new transport to receive log entries.
+     *
+     * @example
+     * ```typescript
+     * logger.addTransport(new FileTransport({ path: './logs/app.log' }))
+     * ```
+     */
+    addTransport(transport: LogTransport): void;
+    /**
+     * Remove a transport by name.
+     */
+    removeTransport(name: string): boolean;
+    /**
+     * Get all registered transports.
+     */
+    getTransports(): readonly LogTransport[];
+    /**
+     * Clear all transports.
+     */
+    clearTransports(): void;
+    /**
+     * Update the global minimum log level.
+     */
+    setMinLevel(level: LogLevel): void;
+    /**
+     * Get the current minimum log level.
+     */
+    getMinLevel(): LogLevel;
+    /**
+     * Create a server-level logger for server-side application code.
+     * These logs will be tagged with [SERVER] domain.
+     *
+     * @example
+     * ```typescript
+     * const authLogger = logger.server('AuthController')
+     * authLogger.info('User logged in') // [SERVER] INFO [AuthController] User logged in
+     * ```
+     */
+    server(source: string): ChildLogger;
+    /**
+     * Create a framework-level logger for internal OpenCore logging.
+     * These logs will be tagged with [CORE] domain.
+     *
+     * @example
+     * ```typescript
+     * const coreLogger = logger.framework('Bootstrap')
+     * coreLogger.error('Missing config') // [CORE] ERROR [Bootstrap] Missing config
+     * ```
+     */
+    framework(source: string): ChildLogger;
+    /**
+     * Create a client-level logger for client-side code.
+     * These logs will be tagged with [CLIENT] domain.
+     *
+     * @example
+     * ```typescript
+     * const hudLogger = logger.client('HUD')
+     * hudLogger.debug('Rendering') // [CLIENT] DEBUG [HUD] Rendering
+     * ```
+     */
+    client(source: string): ChildLogger;
+    /**
+     * Create an external services logger for third-party APIs, databases, etc.
+     * These logs will be tagged with [EXTERNAL] domain.
+     *
+     * @example
+     * ```typescript
+     * const stripeLogger = logger.external('StripeAPI')
+     * stripeLogger.warn('Rate limit') // [EXTERNAL] WARN [StripeAPI] Rate limit
+     * ```
+     */
+    external(source: string): ChildLogger;
+    /**
+     * Create a child logger with custom domain.
+     * Use this when you need a specific domain not covered by the convenience methods.
+     *
+     * @example
+     * ```typescript
+     * const customLogger = logger.child('MyModule', LogDomain.EXTERNAL)
+     * ```
+     */
+    child(source: string, domain?: LogDomain): ChildLogger;
+    /**
+     * Internal logging logic.
+     *
+     * @remarks
+     * This method performs a two-stage filtering process:
+     * 1. **Global Filtering**: Messages below the `config.minLevel` are ignored immediately.
+     * 2. **Transport Filtering**: Each transport can have its own `minLevel`. The message
+     *    is only sent to transports where `level >= transport.minLevel`.
+     *
+     * @param level - Severity of the log
+     * @param message - Content to log
+     * @param context - Metadata
+     * @param error - Optional error object
+     */
+    private log;
+}
+/**
+ * A lightweight logger wrapper with a preset source and domain context.
+ * Created via LoggerService.child(), .framework(), .client(), or .external()
+ */
+export declare class ChildLogger {
+    private parent;
+    private source;
+    private domain?;
+    constructor(parent: LoggerService, source: string, domain?: LogDomain | undefined);
+    private buildContext;
+    trace(message: string, context?: Omit<LogContext, 'source' | 'domain'>): void;
+    debug(message: string, context?: Omit<LogContext, 'source' | 'domain'>): void;
+    info(message: string, context?: Omit<LogContext, 'source' | 'domain'>): void;
+    warn(message: string, context?: Omit<LogContext, 'source' | 'domain'>): void;
+    error(message: string, context?: Omit<LogContext, 'source' | 'domain'>, error?: Error): void;
+    fatal(message: string, context?: Omit<LogContext, 'source' | 'domain'>, error?: Error): void;
+}