@open-core/framework 0.1.0-alpha.1

package/dist/server/error-handler.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleCommandError = handleCommandError;
+const utils_1 = require("../utils");
+const logger_1 = require("../shared/logger");
+function normalizeError(error, origin) {
+    if ((0, utils_1.isAppError)(error)) {
+        return error;
+    }
+    if (error instanceof Error) {
+        return new utils_1.AppError('UNKNOWN', error.message, origin, { stack: error.stack });
+    }
+    return new utils_1.AppError('UNKNOWN', String(error), origin, { raw: error });
+}
+function handleCommandError(error, meta, playerId) {
+    const appError = normalizeError(error, 'server');
+    logger_1.loggers.command.error(`Command execution failed: /${meta.command}`, {
+        command: meta.command,
+        handler: meta.methodName,
+        playerId,
+        code: appError.code,
+        origin: appError.origin,
+        errorMessage: appError.message,
+        details: appError.details,
+    });
+    if (playerId !== null) {
+        switch (appError.code) {
+            case 'VALIDATION_ERROR':
+            case 'INSUFFICIENT_FUNDS':
+            case 'PERMISSION_DENIED':
+            case 'UNAUTHORIZED':
+                emitNet('chat:addMessage', playerId, {
+                    args: ['^1Error', appError.message],
+                });
+                break;
+            default:
+                emitNet('chat:addMessage', playerId, {
+                    args: ['^1Error', 'Ha ocurrido un error interno.'],
+                });
+                break;
+        }
+    }
+}

package/dist/server/helpers/resolve-method.d.ts

@@ -0,0 +1,5 @@
+export declare function resolveMethod(instance: Record<string, any>, methodName: string, errorMessage: string): {
+    handler: Function;
+    handlerName: string;
+    proto: any;
+} | undefined;

package/dist/server/helpers/resolve-method.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveMethod = resolveMethod;
+const logger_1 = require("../../shared/logger");
+function resolveMethod(instance, methodName, errorMessage) {
+    const proto = Object.getPrototypeOf(instance);
+    const method = instance[methodName];
+    if (typeof method !== 'function') {
+        logger_1.loggers.scanner.error(errorMessage, {
+            className: instance.constructor.name,
+            methodName,
+        });
+        return;
+    }
+    const handler = method.bind(instance);
+    const handlerName = `${instance.constructor.name}.${methodName}`;
+    return { handler, handlerName, proto };
+}

package/dist/server/index.d.ts

@@ -0,0 +1,10 @@
+export * from './core';
+export * from './decorators';
+export * from './templates';
+export * from './services';
+export * from './entities';
+export * from './configs';
+export * from './setup';
+export type * from './types/core-events';
+import './controllers/command.controller';
+import './controllers/chat.controller';

package/dist/server/index.js

@@ -0,0 +1,31 @@
+"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 });
+// Framework modules
+__exportStar(require("./core"), exports);
+__exportStar(require("./decorators"), exports);
+__exportStar(require("./templates"), exports);
+__exportStar(require("./services"), exports);
+// Entities
+__exportStar(require("./entities"), exports);
+// Configs
+__exportStar(require("./configs"), exports);
+__exportStar(require("./setup"), exports);
+// Controllers
+require("./controllers/command.controller");
+require("./controllers/chat.controller");
+const container_1 = require("./container");
+globalThis.oc_container = container_1.di;

package/dist/server/loaders/exports.loader.js

@@ -0,0 +1,23 @@
+"use strict";
+// import { di } from '../container'
+// import { CommandService } from '../services/command.service'
+// import { handleCommandError } from '../error-handler'
+// export const exportsLoader = () => {
+//   const commandService = di.resolve(CommandService)
+//   exports('core:ExecuteCommand', async (src: number, name: string, args: string[], raw: string) => {
+//     try {
+//       await commandService.execute(Number(src), name, args, raw)
+//       return { ok: true }
+//     } catch (error) {
+//       handleCommandError(
+//         error,
+//         { name, methodName: 'ExportExecution', target: Object },
+//         Number(src),
+//       )
+//       return { ok: false }
+//     }
+//   })
+//   exports('core:GetCommands', () => {
+//     return commandService.getDefinitions()
+//   })
+// }

package/dist/server/loaders/playerSession.loader.d.ts

@@ -0,0 +1 @@
+export declare const playerSessionLoader: () => void;

package/dist/server/loaders/playerSession.loader.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.playerSessionLoader = void 0;
+const tsyringe_1 = require("tsyringe");
+const player_service_1 = require("../services/player.service");
+const persistence_service_1 = require("../services/persistence.service");
+const core_event_bus_1 = require("../bus/core-event-bus");
+const logger_1 = require("../../shared/logger");
+const playerSessionLoader = () => {
+    const playerManager = tsyringe_1.container.resolve(player_service_1.PlayerService);
+    const persistenceService = tsyringe_1.container.resolve(persistence_service_1.PlayerPersistenceService);
+    // Initialize persistence service (resolves provider if configured)
+    persistenceService.initialize();
+    on('playerJoining', async () => {
+        var _a;
+        const clientId = source;
+        const license = (_a = GetPlayerIdentifier(clientId.toString(), 0)) !== null && _a !== void 0 ? _a : undefined;
+        const player = playerManager.bind(clientId, { license });
+        logger_1.loggers.session.info(`Player session created`, {
+            clientId,
+            license: license !== null && license !== void 0 ? license : 'none',
+        });
+        // Load persisted data for the player
+        await persistenceService.handleSessionLoad(player);
+        (0, core_event_bus_1.emitCoreEvent)('core:playerSessionCreated', {
+            clientId,
+            license,
+        });
+        setImmediate(() => {
+            const currentPlayer = playerManager.getByClient(clientId);
+            if (!currentPlayer)
+                return;
+            (0, core_event_bus_1.emitCoreEvent)('core:playerFullyConnected', {
+                clientId,
+                license,
+            });
+        });
+    });
+    on('playerDropped', async (source) => {
+        const clientId = Number(source);
+        const player = playerManager.getByClient(clientId);
+        // Save player data before destroying session
+        if (player) {
+            await persistenceService.handleSessionSave(player);
+        }
+        playerManager.unbindByClient(clientId);
+        (0, core_event_bus_1.emitCoreEvent)('core:playerSessionDestroyed', { clientId });
+        logger_1.loggers.session.info(`Player session destroyed`, { clientId });
+    });
+};
+exports.playerSessionLoader = playerSessionLoader;

package/dist/server/services/access-control.service.d.ts

@@ -0,0 +1,56 @@
+import { Server } from '../..';
+import { PrincipalProviderContract } from '../templates';
+/**
+ * **Core Security Service**
+ *
+ * This service acts as the central enforcement point for the Access Control system.
+ * It uses the configured `PrincipalProvider` to query roles and validates them against requirements.
+ *
+ * It is primarily used internally by the `@Guard` decorator, but can be injected
+ * into services to perform manual checks.
+ */
+export declare class AccessControlService {
+    private readonly principalProvider;
+    constructor(principalProvider: PrincipalProviderContract);
+    /**
+     * Verifies if a player meets a minimum numeric rank requirement.
+     *
+     * @param player - The target player.
+     * @param minRank - The minimum numeric value required (Inclusive).
+     *
+     * @returns `true` if `Principal.rank >= minRank`.
+     *
+     * @throws {AppError} code `UNAUTHORIZED` if the player has no Principal (not logged in).
+     * @throws {AppError} code `NO_RANK_IN_PRINCIPAL` if the Principal exists but has no `rank` defined.
+     */
+    hasRank(player: Server.Player, minRank: number): Promise<boolean>;
+    /**
+     * Verifies if a player possesses a specific permission string.
+     *
+     * @remarks
+     * This method supports the **Wildcard ('*')** permission. If the principal has `'*'`
+     * in their permissions array, this method always returns `true`.
+     *
+     * @param player - The target player.
+     * @param permission - The specific permission key (e.g., `'admin.ban'`).
+     * @returns `true` if the player has the permission or the wildcard.
+     */
+    hasPermission(player: Server.Player, permission: string): Promise<boolean>;
+    /**
+     * **Strict Enforcement**
+     *
+     * Validates a set of requirements against a player. If any requirement fails,
+     * it throws an exception, halting the execution flow.
+     *
+     * Used primarily by the `@Guard` decorator logic.
+     *
+     * @param player - The server player to validate.
+     * @param requirements - An object containing rank and/or permission constraints.
+     *
+     * @throws {AppError} code `PERMISSION_DENIED` if validation fails.
+     */
+    enforce(player: Server.Player, requirements: {
+        minRank?: number;
+        permission?: string;
+    }): Promise<void>;
+}

package/dist/server/services/access-control.service.js

@@ -0,0 +1,99 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccessControlService = void 0;
+const tsyringe_1 = require("tsyringe");
+const utils_1 = require("../../utils");
+const templates_1 = require("../templates");
+/**
+ * **Core Security Service**
+ *
+ * This service acts as the central enforcement point for the Access Control system.
+ * It uses the configured `PrincipalProvider` to query roles and validates them against requirements.
+ *
+ * It is primarily used internally by the `@Guard` decorator, but can be injected
+ * into services to perform manual checks.
+ */
+let AccessControlService = class AccessControlService {
+    constructor(principalProvider) {
+        this.principalProvider = principalProvider;
+    }
+    /**
+     * Verifies if a player meets a minimum numeric rank requirement.
+     *
+     * @param player - The target player.
+     * @param minRank - The minimum numeric value required (Inclusive).
+     *
+     * @returns `true` if `Principal.rank >= minRank`.
+     *
+     * @throws {AppError} code `UNAUTHORIZED` if the player has no Principal (not logged in).
+     * @throws {AppError} code `NO_RANK_IN_PRINCIPAL` if the Principal exists but has no `rank` defined.
+     */
+    async hasRank(player, minRank) {
+        const principal = await this.principalProvider.getPrincipal(player);
+        if (!principal)
+            throw new utils_1.AppError('UNAUTHORIZED', 'No principal found', 'core');
+        if (principal.rank === undefined)
+            throw new utils_1.AppError('NO_RANK_IN_PRINCIPAL', "You're trying to compare a Principal rank, but there's no defined rank! ", 'core');
+        return principal.rank >= minRank;
+    }
+    /**
+     * Verifies if a player possesses a specific permission string.
+     *
+     * @remarks
+     * This method supports the **Wildcard ('*')** permission. If the principal has `'*'`
+     * in their permissions array, this method always returns `true`.
+     *
+     * @param player - The target player.
+     * @param permission - The specific permission key (e.g., `'admin.ban'`).
+     * @returns `true` if the player has the permission or the wildcard.
+     */
+    async hasPermission(player, permission) {
+        const principal = await this.principalProvider.getPrincipal(player);
+        if (!principal)
+            return false;
+        if (principal.permissions.includes('*'))
+            return true;
+        return principal.permissions.includes(permission);
+    }
+    /**
+     * **Strict Enforcement**
+     *
+     * Validates a set of requirements against a player. If any requirement fails,
+     * it throws an exception, halting the execution flow.
+     *
+     * Used primarily by the `@Guard` decorator logic.
+     *
+     * @param player - The server player to validate.
+     * @param requirements - An object containing rank and/or permission constraints.
+     *
+     * @throws {AppError} code `PERMISSION_DENIED` if validation fails.
+     */
+    async enforce(player, requirements) {
+        if (requirements.minRank !== undefined) {
+            const hasRank = await this.hasRank(player, requirements.minRank);
+            if (!hasRank) {
+                throw new utils_1.AppError('PERMISSION_DENIED', `Access Denied: Requires minimum rank level ${requirements.minRank}`, 'core');
+            }
+        }
+        if (requirements.permission) {
+            const hasPerm = await this.hasPermission(player, requirements.permission);
+            if (!hasPerm) {
+                throw new utils_1.AppError('PERMISSION_DENIED', `Access Denied: Missing required permission '${requirements.permission}'`, 'core');
+            }
+        }
+    }
+};
+exports.AccessControlService = AccessControlService;
+exports.AccessControlService = AccessControlService = __decorate([
+    (0, tsyringe_1.injectable)(),
+    __metadata("design:paramtypes", [templates_1.PrincipalProviderContract])
+], AccessControlService);

package/dist/server/services/chat.service.d.ts

@@ -0,0 +1,7 @@
+import { Server } from '../..';
+import { RGB } from '../../utils';
+export declare class ChatService {
+    broadcast(message: string, author?: string, color?: RGB): void;
+    sendPrivate(player: Server.Player, message: string, author?: string, color?: RGB): void;
+    clearChat(player: Server.Player): void;
+}

package/dist/server/services/chat.service.js

@@ -0,0 +1,31 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatService = void 0;
+const tsyringe_1 = require("tsyringe");
+let ChatService = class ChatService {
+    broadcast(message, author = 'SYSTEM', color = { r: 255, g: 255, b: 255 }) {
+        emitNet('core:chat:message', -1, {
+            args: [author, message],
+            color: color,
+        });
+    }
+    sendPrivate(player, message, author = 'Private', color = { r: 200, g: 200, b: 200 }) {
+        emitNet('core:chat:addMessage', player.clientID, {
+            args: [author, message],
+            color: color,
+        });
+    }
+    clearChat(player) {
+        emitNet('core:chat:clear', player.clientID);
+    }
+};
+exports.ChatService = ChatService;
+exports.ChatService = ChatService = __decorate([
+    (0, tsyringe_1.injectable)()
+], ChatService);

package/dist/server/services/command.service.d.ts

@@ -0,0 +1,15 @@
+import type { CommandMetadata } from '../decorators/command';
+import { Server } from '../..';
+import { SecurityHandlerContract } from '../templates/security/security-handler.contract';
+export declare class CommandService {
+    private securityHandler;
+    constructor(securityHandler: SecurityHandlerContract);
+    private commands;
+    register(meta: CommandMetadata, handler: Function): void;
+    execute(player: Server.Player, commandName: string, args: string[], raw: string): Promise<void>;
+    getAllCommands(): {
+        command: string;
+        description: string;
+        usage: string;
+    }[];
+}

package/dist/server/services/command.service.js

@@ -0,0 +1,77 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandService = void 0;
+const tsyringe_1 = require("tsyringe");
+const utils_1 = require("../../utils");
+const zod_1 = __importDefault(require("zod"));
+const security_handler_contract_1 = require("../templates/security/security-handler.contract");
+const logger_1 = require("../../shared/logger");
+const schema_generator_1 = require("../system/schema-generator");
+let CommandService = class CommandService {
+    constructor(securityHandler) {
+        this.securityHandler = securityHandler;
+        this.commands = new Map();
+    }
+    register(meta, handler) {
+        this.commands.set(meta.command.toLowerCase(), { meta, handler });
+        logger_1.loggers.command.debug(`Registered: /${meta.command}${meta.schema ? ' [Validated]' : ''}`);
+    }
+    async execute(player, commandName, args, raw) {
+        var _a;
+        const entry = this.commands.get(commandName.toLowerCase());
+        if (!entry) {
+            return;
+        }
+        const { meta, handler } = entry;
+        let validatedArgs = args;
+        // Use explicit schema or auto-generate from paramTypes
+        const schema = (_a = meta.schema) !== null && _a !== void 0 ? _a : (0, schema_generator_1.generateSchemaFromTypes)(meta.paramTypes);
+        if (schema) {
+            try {
+                validatedArgs = await schema.parseAsync(args);
+            }
+            catch (error) {
+                if (error instanceof zod_1.default.ZodError) {
+                    throw new utils_1.AppError('VALIDATION_ERROR', `Incorrect usage: ${error.message}`, 'client', {
+                        usage: meta.usage,
+                    });
+                }
+                if (error instanceof utils_1.AppError) {
+                    throw error;
+                }
+                if (error instanceof utils_1.SecurityError) {
+                    this.securityHandler.handleViolation(player, error);
+                }
+                throw error;
+            }
+        }
+        await handler(player, validatedArgs, raw);
+    }
+    getAllCommands() {
+        return Array.from(this.commands.values()).map((c) => {
+            var _a, _b;
+            return ({
+                command: c.meta.command,
+                description: (_a = c.meta.description) !== null && _a !== void 0 ? _a : '',
+                usage: (_b = c.meta.usage) !== null && _b !== void 0 ? _b : '',
+            });
+        });
+    }
+};
+exports.CommandService = CommandService;
+exports.CommandService = CommandService = __decorate([
+    (0, tsyringe_1.injectable)(),
+    __metadata("design:paramtypes", [security_handler_contract_1.SecurityHandlerContract])
+], CommandService);

package/dist/server/services/config.service.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Generic configuration service for accessing FiveM Convars.
+ *
+ * Provides type-safe access to configuration values with automatic
+ * prefix handling and type conversion.
+ *
+ * All keys are automatically prefixed with `opencore_`.
+ *
+ * @example
+ * ```ts
+ * const config = di.resolve(ConfigService)
+ *
+ * // Get string value
+ * const apiUrl = config.get('api_url', 'http://localhost:3000')
+ *
+ * // Get number value
+ * const timeout = config.getNumber('timeout', 5000)
+ *
+ * // Get boolean value
+ * const debug = config.getBoolean('debug', false)
+ *
+ * // Get required value (throws if not set)
+ * const secretKey = config.getRequired('secret_key')
+ *
+ * // Get JSON value
+ * const settings = config.getJson('settings', { enabled: true })
+ * ```
+ *
+ * @scope Singleton
+ */
+export declare class ConfigService {
+    private readonly PREFIX;
+    /**
+     * Gets a string configuration value.
+     *
+     * @param key - The configuration key (without prefix)
+     * @param defaultValue - Default value if not set
+     * @returns The configuration value or default
+     */
+    get(key: string, defaultValue: string): string;
+    /**
+     * Gets a numeric configuration value.
+     *
+     * @param key - The configuration key (without prefix)
+     * @param defaultValue - Default value if not set or invalid
+     * @returns The configuration value as number
+     */
+    getNumber(key: string, defaultValue: number): number;
+    /**
+     * Gets a boolean configuration value.
+     *
+     * Recognizes 'true', '1' as true, everything else as false.
+     *
+     * @param key - The configuration key (without prefix)
+     * @param defaultValue - Default value if not set
+     * @returns The configuration value as boolean
+     */
+    getBoolean(key: string, defaultValue: boolean): boolean;
+    /**
+     * Gets a required configuration value.
+     *
+     * @param key - The configuration key (without prefix)
+     * @returns The configuration value
+     * @throws Error if the value is not set
+     */
+    getRequired(key: string): string;
+    /**
+     * Gets a JSON configuration value.
+     *
+     * @param key - The configuration key (without prefix)
+     * @param defaultValue - Default value if not set or invalid JSON
+     * @returns The parsed JSON value or default
+     */
+    getJson<T>(key: string, defaultValue: T): T;
+}