@open-core/framework 1.0.1-beta.1

package/dist/server/entities/player.d.ts

@@ -0,0 +1,157 @@
+import type { Vector3 } from '../../utils';
+import type { LinkedID, PlayerSession } from '../services/player.service';
+/**
+ * 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`).
+ */
+export declare class Player {
+    private readonly session;
+    private states;
+    /**
+     * 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: PlayerSession);
+    /**
+     * The numeric FiveM Server ID (Source) of the player.
+     * Useful for internal logic and array indexing.
+     */
+    get clientID(): number;
+    /**
+     * The FiveM Server ID as a string.
+     * Required by most FiveM native functions (e.g., `GetPlayerName`, `DropPlayer`).
+     */
+    get clientIDStr(): string;
+    /**
+     * 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(): string | undefined;
+    /**
+     * The display name of the player (Steam name or FiveM username).
+     */
+    get name(): string;
+    /**
+     * 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(): string[];
+    /**
+     * 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: string, ...args: any[]): void;
+    /**
+     * 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: Vector3): void;
+    /**
+     * 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: Vector3): void;
+    /**
+     * Disconnects the player from the server.
+     *
+     * @param reason - The message displayed to the player upon disconnection.
+     */
+    kick(reason?: string): void;
+    /**
+     * 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: number): void;
+    /**
+     * 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: string, value: unknown): void;
+    /**
+     * 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<T = unknown>(key: string): T | undefined;
+    /**
+     * 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: LinkedID): void;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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: string): void;
+    /**
+     * Removes a specific state flag from the player.
+     *
+     * @param state - The state key to remove.
+     */
+    removeState(state: string): void;
+    /**
+     * 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: string, force?: boolean): boolean;
+    /**
+     * Retrieves a snapshot of all currently active state flags for this player.
+     *
+     * @returns An array containing all active state keys.
+     */
+    getStates(): string[];
+}

package/dist/server/entities/player.js

@@ -0,0 +1,217 @@
+"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('core: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

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

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.name}`, {
+        command: meta.name,
+        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/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,29 @@
+"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");

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,42 @@
+"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 (source) => {
+        var _a;
+        const clientId = Number(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,
+        });
+    });
+    on('playerDropped', async () => {
+        const clientId = Number(global.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>;
+}