@open-core/framework 0.2.8 → 0.3.0

package/dist/runtime/server/entities/player.js

@@ -1,17 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Player = void 0;
+const entity_1 = require("../../core/entity");
 /**
  * Core-level representation of a connected player on the server.
  *
- * This class wraps FiveM natives and session information.
+ * @remarks
+ * This class wraps platform 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).
+ * **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`).
+ *
+ * This class is platform-agnostic and works across different game engines
+ * (FiveM, RageMP, alt:V, etc.) through the adapter pattern.
  */
-class Player {
+class Player extends entity_1.BaseEntity {
     /**
      * Creates a new Player entity instance.
      * This is typically instantiated by the `PlayerService` upon connection.
@@ -20,25 +25,18 @@ class Player {
      * @param adapters - Platform adapters for player operations.
      */
     constructor(session, adapters) {
+        super(`player:${session.clientID}`);
         this.session = session;
         this.adapters = adapters;
-        this.states = new Set();
         this.position = adapters.playerInfo.getPlayerPosition(session.clientID);
     }
     /**
-     * The numeric FiveM Server ID (Source) of the player.
-     * Useful for internal logic and array indexing.
+     * The numeric client/server ID of the player.
+     * This is the platform-specific player identifier used for native calls.
      */
     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.
@@ -48,37 +46,69 @@ class Player {
         return (_a = this.session.accountID) === null || _a === void 0 ? void 0 : _a.toString();
     }
     /**
-     * The display name of the player (Steam name or FiveM username).
+     * The display name of the player.
      */
     get name() {
         var _a;
         return (_a = this.adapters.playerInfo.getPlayerName(this.clientID)) !== null && _a !== void 0 ? _a : `Player#${this.clientID}`;
     }
+    // ─────────────────────────────────────────────────────────────────
+    // Position / Spatial
+    // ─────────────────────────────────────────────────────────────────
     getPosition() {
-        // re-set last position
         this.position = this.adapters.playerInfo.getPlayerPosition(this.clientID);
         return this.position;
     }
     /**
-     * Retrieves all platform identifiers associated with the player (steam, license, discord, ip, etc.).
+     * Sets the player position using the platform-agnostic API.
+     *
+     * @param vector - The target coordinates (x, y, z).
+     */
+    setPosition(vector) {
+        const ped = this.adapters.playerServer.getPed(this.clientID.toString());
+        this.adapters.entityServer.setPosition(ped, vector, { clearArea: true });
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Identifiers
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Retrieves all platform identifiers associated with the player.
      *
+     * @deprecated Use getPlayerIdentifiers() for structured identifier data.
      * @returns An array of identifier strings (e.g., `['steam:11000...', 'license:2332...']`).
      */
     getIdentifiers() {
-        return this.adapters.playerServer.getIdentifiers(this.clientIDStr);
+        return this.adapters.playerServer.getIdentifiers(this.clientID.toString());
     }
     /**
-     * FiveM license
+     * Retrieves all identifiers as structured objects.
+     *
+     * @returns An array of PlayerIdentifier objects with type, value, and raw fields.
      */
-    getLicense() {
-        return this.adapters.playerServer.getIdentifier(this.clientIDStr, 'license');
+    getPlayerIdentifiers() {
+        return this.adapters.playerServer.getPlayerIdentifiers(this.clientID.toString());
     }
-    getIdentifier(identifier) {
-        return this.adapters.playerServer.getIdentifier(this.clientIDStr, identifier);
+    /**
+     * Gets a specific identifier by type.
+     *
+     * @param identifierType - The type of identifier (e.g., 'steam', 'license', 'discord')
+     * @returns The identifier string or undefined if not found
+     */
+    getIdentifier(identifierType) {
+        return this.adapters.playerServer.getIdentifier(this.clientID.toString(), identifierType);
     }
     /**
-     * Sends a network event exclusively to this specific player (Client-side).
-     * Wrapper for `emitNet` ensuring the correct target Source ID is used.
+     * Gets the player's license identifier.
+     * @deprecated Use getIdentifier('license') for cross-platform compatibility.
+     */
+    getLicense() {
+        return this.getIdentifier('license');
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Network Communication
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Sends a network event exclusively to this specific player (client-side).
      *
      * @param eventName - The name of the event to trigger on the client.
      * @param args - Data to send to the client.
@@ -86,53 +116,84 @@ class Player {
     emit(eventName, ...args) {
         this.adapters.netTransport.emitNet(eventName, this.clientID, ...args);
     }
-    /** used to send a private message to the player */
-    send(message, type = 'chat') {
-        this.adapters.netTransport.emitNet('core:chat:send', this.clientID, message, type);
-    }
     /**
-     * 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`.
+     * Sends a private message to the player.
      *
-     * @param vector - The target coordinates (x, y, z).
+     * @param message - The message text
+     * @param type - Message type for styling
      */
-    teleport(vector) {
-        const ped = this.adapters.playerServer.getPed(this.clientIDStr);
-        this.adapters.entityServer.setCoords(ped, vector.x, vector.y, vector.z, false, false, false, true);
+    send(message, type = 'chat') {
+        this.emit('core:chat:send', message, type);
     }
+    // ─────────────────────────────────────────────────────────────────
+    // Spawning / Teleporting
+    // ─────────────────────────────────────────────────────────────────
     /**
-     * Requests the Client to teleport itself via the Core Spawner system.
+     * Requests the client to teleport via the spawner system.
      *
+     * @remarks
      * 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) {
+    teleport(vector) {
         this.emit('opencore:spawner:teleport', vector);
     }
+    /**
+     * Spawns the player at a position with a specific model.
+     *
+     * @param vector - The spawn coordinates
+     * @param model - The ped model to use (default: 'mp_m_freemode_01')
+     */
     spawn(vector, model = 'mp_m_freemode_01') {
         this.emit('opencore:spawner:spawn', { position: vector, model });
     }
+    // ─────────────────────────────────────────────────────────────────
+    // Connection Management
+    // ─────────────────────────────────────────────────────────────────
     /**
      * Disconnects the player from the server.
      *
      * @param reason - The message displayed to the player upon disconnection.
      */
     kick(reason = 'Kicked from server') {
-        this.adapters.playerServer.drop(this.clientIDStr, reason);
+        this.adapters.playerServer.drop(this.clientID.toString(), reason);
     }
+    // ─────────────────────────────────────────────────────────────────
+    // Dimension / Routing Bucket
+    // ─────────────────────────────────────────────────────────────────
     /**
-     * Sets the routing bucket (virtual world / dimension) for the player.
+     * 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) {
-        this.adapters.playerServer.setRoutingBucket(this.clientIDStr, bucket);
+        this.adapters.playerServer.setRoutingBucket(this.clientID.toString(), bucket);
+        this._dimension = bucket;
     }
+    /**
+     * Gets the current routing bucket.
+     */
+    getRoutingBucket() {
+        return this.adapters.playerServer.getRoutingBucket(this.clientID.toString());
+    }
+    /**
+     * Sets the player dimension (alias for setRoutingBucket).
+     */
+    set dimension(value) {
+        this.setRoutingBucket(value);
+    }
+    /**
+     * Gets the player dimension (alias for getRoutingBucket).
+     */
+    get dimension() {
+        return this.getRoutingBucket();
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Session Metadata (Transient)
+    // ─────────────────────────────────────────────────────────────────
     /**
      * Stores arbitrary transient metadata for this player's session.
      * Useful for flags like `isDead`, `isInRaid`, `lastLocation`, etc.
@@ -146,46 +207,48 @@ class Player {
     /**
      * 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];
     }
+    // ─────────────────────────────────────────────────────────────────
+    // Account Linking
+    // ─────────────────────────────────────────────────────────────────
     /**
      * Links a persistent Account ID to the current session.
      * Should be called after successful authentication.
      *
-     * @param accountID - The unique ID from the database.
+     * @param accountID - The unique ID from the persistent storage.
      */
     linkAccount(accountID) {
         this.session.accountID = accountID;
     }
+    /**
+     * Unlinks the account from the current session.
+     */
     unlinkAccount() {
         this.session.accountID = undefined;
     }
+    // ─────────────────────────────────────────────────────────────────
+    // State Flags
+    // ─────────────────────────────────────────────────────────────────
     /**
      * 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);
+        return super.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 !!
+        super.add(state);
     }
     /**
      * Removes a specific state flag from the player.
@@ -193,82 +256,57 @@ class Player {
      * @param state - The state key to remove.
      */
     removeState(state) {
-        this.states.delete(state);
-        // this.emit('core:state:remove', state) // ? optional !!
+        super.delete(state);
     }
     /**
      * 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
-     * ```
+     * @param force - If provided, forces the state to be added or removed.
+     * @returns The final status of the state.
      */
     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.
+        return super.toggle(state, force);
+    }
+    /**
+     * Retrieves all currently active state flags.
      */
     getStates() {
-        return Array.from(this.states);
+        return super.all();
     }
+    // ─────────────────────────────────────────────────────────────────
+    // Health & Armor
+    // ─────────────────────────────────────────────────────────────────
     /**
      * Gets the current health of the player's ped.
-     *
-     * @returns Current health value (0-200, where 100 is dead).
      */
     getHealth() {
-        const ped = this.adapters.playerServer.getPed(this.clientIDStr);
+        const ped = this.adapters.playerServer.getPed(this.clientID.toString());
         return this.adapters.entityServer.getHealth(ped);
     }
     /**
      * Sets the health of the player's ped.
      *
-     * @param health - Health value to set (0-200).
+     * @param health - Health value to set (platform-specific range).
      */
     setHealth(health) {
-        const ped = this.adapters.playerServer.getPed(this.clientIDStr);
+        const ped = this.adapters.playerServer.getPed(this.clientID.toString());
         this.adapters.entityServer.setHealth(ped, health);
     }
     /**
      * Gets the current armor of the player's ped.
-     *
-     * @returns Current armor value (0-100).
      */
     getArmor() {
-        const ped = this.adapters.playerServer.getPed(this.clientIDStr);
+        const ped = this.adapters.playerServer.getPed(this.clientID.toString());
         return this.adapters.entityServer.getArmor(ped);
     }
     /**
      * Sets the armor of the player's ped.
      *
-     * @param armor - Armor value to set (0-100).
+     * @param armor - Armor value to set (typically 0-100).
      */
     setArmor(armor) {
-        const ped = this.adapters.playerServer.getPed(this.clientIDStr);
+        const ped = this.adapters.playerServer.getPed(this.clientID.toString());
         this.adapters.entityServer.setArmor(ped, armor);
     }
     /**
@@ -280,18 +318,19 @@ class Player {
     /**
      * Checks if the player is alive.
      *
-     * @returns `true` if health is above 100 (dead threshold), `false` otherwise.
+     * @remarks
+     * The threshold (100) is platform-specific. In GTA V-based platforms,
+     * health below 100 means dead.
      */
     isAlive() {
         return this.getHealth() > 100;
     }
+    // ─────────────────────────────────────────────────────────────────
+    // Serialization
+    // ─────────────────────────────────────────────────────────────────
     /**
      * Serializes the player data for cross-resource transfer.
      *
-     * @remarks
-     * Creates a plain object representation of the player session that can be
-     * safely transferred between resources via FiveM exports.
-     *
      * @returns Serialized player data DTO
      */
     serialize() {

package/dist/runtime/server/entities/vehicle.d.ts

@@ -1,6 +1,6 @@
-import { IEntityServer } from '../../../adapters/contracts/IEntityServer';
-import { IVehicleServer } from '../../../adapters/contracts/IVehicleServer';
-import { Vector3 } from '../../../kernel/utils';
+import { IEntityServer } from '../../../adapters/contracts/server/IEntityServer';
+import { IVehicleServer } from '../../../adapters/contracts/server/IVehicleServer';
+import { Vector3 } from '../../../kernel/utils/vector3';
 import { SerializedVehicleData, VehicleMetadata, VehicleMods, VehicleOwnership } from '../types/vehicle.types';
 /**
  * Adapter bundle for vehicle operations.

package/dist/runtime/server/error-handler.js

@@ -1,16 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleCommandError = handleCommandError;
-const logger_1 = require("../../kernel/shared/logger");
-const utils_1 = require("../../kernel/utils");
+const app_error_1 = require("../../kernel/error/app.error");
+const logger_1 = require("../../kernel/logger");
 function normalizeError(error, origin) {
-    if ((0, utils_1.isAppError)(error)) {
+    if ((0, app_error_1.isAppError)(error)) {
         return error;
     }
     if (error instanceof Error) {
-        return new utils_1.AppError('COMMON:UNKNOWN', error.message, origin, { stack: error.stack });
+        return new app_error_1.AppError('COMMON:UNKNOWN', error.message, origin, { stack: error.stack });
     }
-    return new utils_1.AppError('COMMON:UNKNOWN', String(error), origin, { raw: error });
+    return new app_error_1.AppError('COMMON:UNKNOWN', String(error), origin, { raw: error });
 }
 function handleCommandError(error, meta, playerId) {
     const appError = normalizeError(error, 'server');

package/dist/runtime/server/helpers/normalize-app-error.d.ts

@@ -0,0 +1,9 @@
+import { AppError, type ErrorOrigin } from '../../../kernel/error';
+/**
+ * Normalizes unknown thrown values into a consistent {@link AppError}.
+ *
+ * @remarks
+ * Command and event pipelines should never leak raw errors.
+ * This helper ensures observers always receive an AppError.
+ */
+export declare function normalizeToAppError(error: unknown, origin: ErrorOrigin): AppError;

package/dist/runtime/server/helpers/normalize-app-error.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeToAppError = normalizeToAppError;
+const error_1 = require("../../../kernel/error");
+/**
+ * Normalizes unknown thrown values into a consistent {@link AppError}.
+ *
+ * @remarks
+ * Command and event pipelines should never leak raw errors.
+ * This helper ensures observers always receive an AppError.
+ */
+function normalizeToAppError(error, origin) {
+    if ((0, error_1.isAppError)(error)) {
+        return error;
+    }
+    if (error instanceof Error) {
+        return new error_1.AppError('COMMON:UNKNOWN', error.message, origin, { stack: error.stack });
+    }
+    return new error_1.AppError('COMMON:UNKNOWN', String(error), origin, { raw: error });
+}

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

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveMethod = resolveMethod;
-const logger_1 = require("../../../kernel/shared/logger");
-const utils_1 = require("../../../kernel/utils");
+const app_error_1 = require("../../../kernel/error/app.error");
+const logger_1 = require("../../../kernel/logger");
 function resolveMethod(instance, methodName, errorMessage) {
     try {
         const proto = Object.getPrototypeOf(instance);
@@ -20,7 +20,7 @@ function resolveMethod(instance, methodName, errorMessage) {
     }
     catch (error) {
         if (error instanceof Error) {
-            throw new utils_1.AppError('COMMON:UNKNOWN', `[${error.name}] ${error.message}`, 'server', error.stack);
+            throw new app_error_1.AppError('COMMON:UNKNOWN', `[${error.name}] ${error.message}`, 'server', error.stack);
         }
         else
             throw error;

package/dist/runtime/server/index.d.ts

@@ -1,13 +1 @@
-export * from './bootstrap.validation';
-export { onFrameworkEvent } from './bus/internal-event.bus';
-export * from './configs';
-export * from './contracts/index';
-export { init } from './core';
-export * from './decorators';
-export * from './devmode';
-export * from './entities';
-export * from './runtime';
-export * from './services';
-export * from './setup';
-export * from './templates';
-export type * from './types/internal-events';
+export * as Server from './api';

package/dist/runtime/server/index.js

@@ -1,5 +1,4 @@
 "use strict";
-// Framework modules
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -11,27 +10,30 @@ var __createBinding = (this && this.__createBinding) || (Object.create ? (functi
     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);
-};
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.init = exports.onFrameworkEvent = void 0;
-__exportStar(require("./bootstrap.validation"), exports);
-var internal_event_bus_1 = require("./bus/internal-event.bus");
-Object.defineProperty(exports, "onFrameworkEvent", { enumerable: true, get: function () { return internal_event_bus_1.onFrameworkEvent; } });
-// Configs
-__exportStar(require("./configs"), exports);
-__exportStar(require("./contracts/index"), exports);
-var core_1 = require("./core");
-Object.defineProperty(exports, "init", { enumerable: true, get: function () { return core_1.init; } });
-__exportStar(require("./decorators"), exports);
-// DevMode (development tools)
-__exportStar(require("./devmode"), exports);
-// Entities
-__exportStar(require("./entities"), exports);
-__exportStar(require("./runtime"), exports);
-__exportStar(require("./services"), exports);
-__exportStar(require("./setup"), exports);
-__exportStar(require("./templates"), exports);
+exports.Server = void 0;
 const container_1 = require("../../kernel/di/container");
-globalThis.oc_container = container_1.di;
+globalThis.oc_container = container_1.GLOBAL_CONTAINER;
+exports.Server = __importStar(require("./api"));