@open-core/framework 1.0.1-beta.1

package/dist/server/templates/security/permission.types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Represents the security identity of a user/player within the framework.
+ * This interface bridges the gap between the Core framework and your specific database implementation.
+ */
+export interface Principal {
+    /**
+     * Unique identifier for the user (e.g., database role ID).
+     */
+    id: string;
+    /**
+     * Display name for the role or user, useful for Chat or UI (e.g., "Moderator", "VIP").
+     */
+    name?: string;
+    /**
+     * Numeric weight for hierarchy comparisons.
+     * - Used by the `@Guard({ rank: N })` decorator.
+     * - **Logic:** `UserRank >= RequiredRank`.
+     * - Higher numbers imply higher privileges.
+     */
+    rank?: number;
+    /**
+     * List of specific permission strings assigned to this principal.
+     * - Used by the `@Guard({ permission: 'string' })` decorator.
+     * - Supports the `'*'` wildcard for super-admin access.
+     */
+    permissions: string[];
+    /**
+     * Arbitrary metadata for game-specific logic (e.g., chat colors, badge IDs, staff status).
+     * This prevents the need to modify the Core types for visual extras.
+     */
+    meta?: Record<string, unknown>;
+}

package/dist/server/templates/security/permission.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/server/templates/security/principal-provider.contract.d.ts

@@ -0,0 +1,43 @@
+import type { Server } from '../../..';
+import type { LinkedID } from '../../services';
+import type { Principal } from './permission.types';
+/**
+ * **Authorization**
+ *
+ * This abstract class defines how the Security Layer retrieves user permissions.
+ * The Framework does not know about your database (SQL, Mongo, JSON or API); it relies on
+ * your implementation of this provider to resolve a `Principal`.
+ *
+ * @example
+ * ```ts
+ * // In your game resource:
+ * class MyAuthProvider implements PrincipalProviderContract { ... }
+ * ```
+ */
+export declare abstract class PrincipalProviderContract {
+    /**
+     * Retrieves the security principal (Role/Permissions) for a connected player.
+     *
+     * **Performance Note:** This method is called frequently (on every guarded interaction).
+     * It is highly recommended to cache the result in memory (e.g., in `Player.session`).
+     *
+     * @param player - The active Server Player entity.
+     * @returns A Promise resolving to the `Principal` data, or `null` if the player is not authenticated.
+     */
+    abstract getPrincipal(player: Server.Player): Promise<Principal | null>;
+    /**
+     * Forces a refresh of the player's permissions from the persistence layer.
+     * Useful when a player is promoted/demoted while online.
+     *
+     * @param player - The active Server Player entity to refresh.
+     */
+    abstract refreshPrincipal(player: Server.Player): Promise<void>;
+    /**
+     * Retrieves a principal by their Account ID, even if they are offline.
+     * Useful for web panels, discord bots, or offline bans.
+     *
+     * @param linkedID - The unique linked ID (Account ID).
+     * @returns The Principal data or null.
+     */
+    abstract getPrincipalByLinkedID(linkedID: LinkedID): Promise<Principal | null>;
+}

package/dist/server/templates/security/principal-provider.contract.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrincipalProviderContract = void 0;
+/**
+ * **Authorization**
+ *
+ * This abstract class defines how the Security Layer retrieves user permissions.
+ * The Framework does not know about your database (SQL, Mongo, JSON or API); it relies on
+ * your implementation of this provider to resolve a `Principal`.
+ *
+ * @example
+ * ```ts
+ * // In your game resource:
+ * class MyAuthProvider implements PrincipalProviderContract { ... }
+ * ```
+ */
+class PrincipalProviderContract {
+}
+exports.PrincipalProviderContract = PrincipalProviderContract;

package/dist/server/templates/security/security-handler.contract.d.ts

@@ -0,0 +1,5 @@
+import type { Server } from '../../..';
+import type { SecurityError } from '../../../utils';
+export declare abstract class SecurityHandlerContract {
+    abstract handleViolation(player: Server.Player, error: SecurityError): Promise<void>;
+}

package/dist/server/templates/security/security-handler.contract.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecurityHandlerContract = void 0;
+class SecurityHandlerContract {
+}
+exports.SecurityHandlerContract = SecurityHandlerContract;

package/dist/server/types/core-events.d.ts

@@ -0,0 +1,17 @@
+export interface PlayerSessionCreatedPayload {
+    clientId: number;
+    license: string;
+}
+export interface PlayerSessionDestroyedPayload {
+    clientId: number;
+}
+export interface TransferCompletedPayload {
+    playerId: number;
+    amount: number;
+    targetId: number;
+}
+export type CoreEventMap = {
+    'core:playerSessionCreated': PlayerSessionCreatedPayload;
+    'core:playerSessionDestroyed': PlayerSessionDestroyedPayload;
+    'core:transfer:completed': TransferCompletedPayload;
+};

package/dist/server/types/core-events.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/server/types/security.types.d.ts

@@ -0,0 +1,7 @@
+export type SecurityAction = 'LOG' | 'WARN' | 'KICK' | 'BAN';
+export interface SecurityViolation {
+    code: string;
+    message: string;
+    action: SecurityAction;
+    details?: unknown;
+}

package/dist/server/types/security.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/shared/index.d.ts

@@ -0,0 +1 @@
+export * from './logger';

package/dist/shared/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./logger"), exports);

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

@@ -0,0 +1,35 @@
+import { LoggerService } from './logger.service';
+/**
+ * Singleton logger instance for internal OpenCore framework use.
+ *
+ * This logger is pre-configured for framework-level logging and should only
+ * be used by OpenCore internals. Resource developers should inject LoggerService
+ * via DI instead.
+ *
+ * @internal
+ */
+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;
+};

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

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loggers = exports.coreLogger = void 0;
+const logger_types_1 = require("./logger.types");
+const logger_service_1 = require("./logger.service");
+const console_transport_1 = require("./transports/console.transport");
+/**
+ * Singleton logger instance for internal OpenCore framework use.
+ *
+ * This logger is pre-configured for framework-level logging and should only
+ * be used by OpenCore internals. Resource developers should inject LoggerService
+ * via DI instead.
+ *
+ * @internal
+ */
+exports.coreLogger = new logger_service_1.LoggerService({
+    minLevel: logger_types_1.LogLevel.DEBUG,
+    defaultDomain: logger_types_1.LogDomain.FRAMEWORK,
+    defaultSource: 'Core',
+    transports: [
+        new console_transport_1.ConsoleTransport({
+            minLevel: logger_types_1.LogLevel.DEBUG,
+            colors: true,
+            timestamps: true,
+        }),
+    ],
+});
+// Pre-configured child loggers for common framework components
+exports.loggers = {
+    /** Bootstrap and initialization logs */
+    bootstrap: exports.coreLogger.framework('Bootstrap'),
+    /** Metadata scanning and decorator processing */
+    scanner: exports.coreLogger.framework('Scanner'),
+    /** Player session management */
+    session: exports.coreLogger.framework('Session'),
+    /** Command registration and execution */
+    command: exports.coreLogger.framework('Command'),
+    /** Network events processing */
+    netEvent: exports.coreLogger.framework('NetEvent'),
+    /** Security violations and access control */
+    security: exports.coreLogger.framework('Security'),
+    /** Core event bus */
+    eventBus: exports.coreLogger.framework('EventBus'),
+    /** Export registration */
+    exports: exports.coreLogger.framework('Exports'),
+    /** Tick handlers (server) */
+    tick: exports.coreLogger.framework('Tick'),
+    /** NUI callbacks (client) */
+    nui: exports.coreLogger.client('NUI'),
+    /** Spawn service (client) */
+    spawn: exports.coreLogger.client('Spawn'),
+};

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

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

package/dist/shared/logger/index.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BufferedTransport = exports.ConsoleTransport = exports.loggers = exports.coreLogger = exports.ChildLogger = exports.LoggerService = exports.DEFAULT_LOGGER_CONFIG = exports.createLoggerConfig = exports.parseLogLevel = exports.LogDomainLabels = exports.LogDomain = exports.LogLevelLabels = exports.LogLevel = void 0;
+// Types
+var logger_types_1 = require("./logger.types");
+Object.defineProperty(exports, "LogLevel", { enumerable: true, get: function () { return logger_types_1.LogLevel; } });
+Object.defineProperty(exports, "LogLevelLabels", { enumerable: true, get: function () { return logger_types_1.LogLevelLabels; } });
+Object.defineProperty(exports, "LogDomain", { enumerable: true, get: function () { return logger_types_1.LogDomain; } });
+Object.defineProperty(exports, "LogDomainLabels", { enumerable: true, get: function () { return logger_types_1.LogDomainLabels; } });
+Object.defineProperty(exports, "parseLogLevel", { enumerable: true, get: function () { return logger_types_1.parseLogLevel; } });
+// Config
+var logger_config_1 = require("./logger.config");
+Object.defineProperty(exports, "createLoggerConfig", { enumerable: true, get: function () { return logger_config_1.createLoggerConfig; } });
+Object.defineProperty(exports, "DEFAULT_LOGGER_CONFIG", { enumerable: true, get: function () { return logger_config_1.DEFAULT_LOGGER_CONFIG; } });
+// Service
+var logger_service_1 = require("./logger.service");
+Object.defineProperty(exports, "LoggerService", { enumerable: true, get: function () { return logger_service_1.LoggerService; } });
+Object.defineProperty(exports, "ChildLogger", { enumerable: true, get: function () { return logger_service_1.ChildLogger; } });
+// Core Logger (internal framework use)
+var core_logger_1 = require("./core-logger");
+Object.defineProperty(exports, "coreLogger", { enumerable: true, get: function () { return core_logger_1.coreLogger; } });
+Object.defineProperty(exports, "loggers", { enumerable: true, get: function () { return core_logger_1.loggers; } });
+var console_transport_1 = require("./transports/console.transport");
+Object.defineProperty(exports, "ConsoleTransport", { enumerable: true, get: function () { return console_transport_1.ConsoleTransport; } });
+var buffered_transport_1 = require("./transports/buffered.transport");
+Object.defineProperty(exports, "BufferedTransport", { enumerable: true, get: function () { return buffered_transport_1.BufferedTransport; } });

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

@@ -0,0 +1,47 @@
+import { LogDomain, LogLevel } from './logger.types';
+import type { 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/shared/logger/logger.config.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LOGGER_CONFIG = void 0;
+exports.createLoggerConfig = createLoggerConfig;
+const logger_types_1 = require("./logger.types");
+const console_transport_1 = require("./transports/console.transport");
+/**
+ * Default configuration used when no custom config is provided.
+ */
+exports.DEFAULT_LOGGER_CONFIG = {
+    minLevel: logger_types_1.LogLevel.DEBUG,
+    defaultDomain: logger_types_1.LogDomain.SERVER,
+    defaultSource: 'App',
+    transports: [new console_transport_1.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()
+ *   ]
+ * })
+ * ```
+ */
+function createLoggerConfig(partial) {
+    var _a;
+    return Object.assign(Object.assign(Object.assign({}, exports.DEFAULT_LOGGER_CONFIG), partial), { transports: (_a = partial.transports) !== null && _a !== void 0 ? _a : exports.DEFAULT_LOGGER_CONFIG.transports });
+}

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

@@ -0,0 +1,161 @@
+import { type LoggerConfig } from './logger.config';
+import { LogDomain, LogLevel, type LogContext } from './logger.types';
+import type { 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;
+    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;
+}