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

package/dist/server/entities/player.js

@@ -1,217 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Player = void 0;
-/**
- * Core-level representation of a connected player on the server.
- *
- * This class wraps FiveM natives and session information.
- * It serves as an abstraction layer to interact with the connected client
- * (kicking, teleporting, emitting events) without dealing with raw IDs everywhere.
- *
- * ⚠️ **Design Note:** This class does NOT contain gameplay logic (money, jobs, inventory).
- * Domain logic should live in your modules' services/models (e.g., `EconomyService`, `JobModel`).
- */
-class Player {
-    /**
-     * Creates a new Player entity instance.
-     * This is typically instantiated by the `PlayerService` upon connection.
-     *
-     * @param session - The internal session data structure holding ID and metadata.
-     */
-    constructor(session) {
-        this.session = session;
-        this.states = new Set();
-    }
-    /**
-     * The numeric FiveM Server ID (Source) of the player.
-     * Useful for internal logic and array indexing.
-     */
-    get clientID() {
-        return this.session.clientID;
-    }
-    /**
-     * The FiveM Server ID as a string.
-     * Required by most FiveM native functions (e.g., `GetPlayerName`, `DropPlayer`).
-     */
-    get clientIDStr() {
-        return this.session.clientID.toString();
-    }
-    /**
-     * The persistent Account ID linked to this session, if the player is authenticated.
-     * Returns `undefined` if the player has not logged in yet.
-     */
-    get accountID() {
-        var _a;
-        return (_a = this.session.accountID) === null || _a === void 0 ? void 0 : _a.toString();
-    }
-    /**
-     * The display name of the player (Steam name or FiveM username).
-     */
-    get name() {
-        return GetPlayerName(this.clientIDStr);
-    }
-    /**
-     * Retrieves all platform identifiers associated with the player (steam, license, discord, ip, etc.).
-     *
-     * @returns An array of identifier strings (e.g., `['steam:11000...', 'license:2332...']`).
-     */
-    getIdentifiers() {
-        const ids = [];
-        for (let i = 0;; i++) {
-            const id = GetPlayerIdentifier(this.clientIDStr, i);
-            if (!id)
-                break;
-            ids.push(id);
-        }
-        return ids;
-    }
-    /**
-     * Sends a network event exclusively to this specific player (Client-side).
-     * Wrapper for `emitNet` ensuring the correct target Source ID is used.
-     *
-     * @param eventName - The name of the event to trigger on the client.
-     * @param args - Data to send to the client.
-     */
-    emit(eventName, ...args) {
-        emitNet(eventName, this.clientID, ...args);
-    }
-    /**
-     * Teleports the player to a given position using Server-Side natives.
-     *
-     * **Note:** This forces the entity position on the server. For smoother gameplay transitions
-     * (e.g., inside interiors or across the map), consider using `teleportClient`.
-     *
-     * @param vector - The target coordinates (x, y, z).
-     */
-    teleport(vector) {
-        SetEntityCoords(GetPlayerPed(this.clientIDStr), vector.x, vector.y, vector.z, false, false, false, true);
-    }
-    /**
-     * Requests the Client to teleport itself via the Core Spawner system.
-     *
-     * This method is preferred for gameplay logic as it allows the client to handle
-     * loading screens, fading, and collision loading gracefully.
-     *
-     * @param vector - The target coordinates (x, y, z).
-     */
-    teleportClient(vector) {
-        this.emit('opencore:spawner:teleport', vector);
-    }
-    /**
-     * Disconnects the player from the server.
-     *
-     * @param reason - The message displayed to the player upon disconnection.
-     */
-    kick(reason = 'Kicked from server') {
-        DropPlayer(this.clientID.toString(), reason);
-    }
-    /**
-     * Sets the routing bucket (virtual world / dimension) for the player.
-     * Players in different buckets cannot see or interact with each other.
-     *
-     * @param bucket - The bucket ID (0 is the default shared world).
-     */
-    setRoutingBucket(bucket) {
-        SetPlayerRoutingBucket(this.clientID.toString(), bucket);
-    }
-    /**
-     * Stores arbitrary transient metadata for this player's session.
-     * Useful for flags like `isDead`, `isInRaid`, `lastLocation`, etc.
-     *
-     * @param key - The unique key for the metadata.
-     * @param value - The value to store.
-     */
-    setMeta(key, value) {
-        this.session.meta[key] = value;
-    }
-    /**
-     * Retrieves metadata previously stored in the session.
-     *
-     * @template T - The expected type of the value.
-     * @param key - The metadata key.
-     * @returns The value cast to T, or `undefined` if not set.
-     */
-    getMeta(key) {
-        return this.session.meta[key];
-    }
-    /**
-     * Links a persistent Account ID to the current session.
-     * Should be called after successful authentication.
-     *
-     * @param accountID - The unique ID from the database.
-     */
-    linkAccount(accountID) {
-        this.session.accountID = accountID;
-    }
-    /**
-     * Checks if the player currently possesses a specific state flag.
-     *
-     * @param state - The unique string identifier of the state (e.g., 'dead', 'cuffed').
-     * @returns `true` if the state is active, `false` otherwise.
-     */
-    hasState(state) {
-        return this.states.has(state);
-    }
-    /**
-     * Applies a state flag to the player.
-     *
-     * @remarks
-     * Since states are stored in a `Set`, adding an existing state has no effect (idempotent).
-     * Ideally, this should trigger a sync event to the client if needed.
-     *
-     * @param state - The state key to add.
-     */
-    addState(state) {
-        this.states.add(state);
-        // this.emit('core:state:add', state) // ? optional !!
-    }
-    /**
-     * Removes a specific state flag from the player.
-     *
-     * @param state - The state key to remove.
-     */
-    removeState(state) {
-        this.states.delete(state);
-        // this.emit('core:state:remove', state) // ? optional !!
-    }
-    /**
-     * Toggles the presence of a state flag.
-     *
-     * @param state - The state key to toggle.
-     * @param force - If provided, forces the state to be added (`true`) or removed (`false`) regardless of its current status.
-     *
-     * @returns The final status of the state (`true` if active, `false` if inactive).
-     *
-     * @example
-     * ```ts
-     * // Standard toggle
-     * player.toggleState('duty'); // turns on if off, off if on
-     *
-     * // Force enable (equivalent to addState but returns boolean)
-     * player.toggleState('duty', true); // always results in true
-     * ```
-     */
-    toggleState(state, force) {
-        if (force !== undefined) {
-            force ? this.addState(state) : this.removeState(state);
-            return force;
-        }
-        if (this.hasState(state)) {
-            this.removeState(state);
-            return false;
-        }
-        else {
-            this.addState(state);
-            return true;
-        }
-    }
-    /**
-     * Retrieves a snapshot of all currently active state flags for this player.
-     *
-     * @returns An array containing all active state keys.
-     */
-    getStates() {
-        return Array.from(this.states);
-    }
-}
-exports.Player = Player;

package/dist/server/error-handler.d.ts

@@ -1,2 +0,0 @@
-import type { CommandMetadata } from './decorators/command';
-export declare function handleCommandError(error: unknown, meta: CommandMetadata, playerId: number | null): void;

package/dist/server/error-handler.js

@@ -1,43 +0,0 @@
-"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

@@ -1,5 +0,0 @@
-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

@@ -1,18 +0,0 @@
-"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

@@ -1,10 +0,0 @@
-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

@@ -1,31 +0,0 @@
-"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

@@ -1,23 +0,0 @@
-"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

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

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

@@ -1,51 +0,0 @@
-"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

@@ -1,56 +0,0 @@
-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

@@ -1,99 +0,0 @@
-"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

@@ -1,7 +0,0 @@
-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

@@ -1,31 +0,0 @@
-"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

@@ -1,15 +0,0 @@
-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;
-    }[];
-}