@open-core/framework 0.1.0-alpha.1 → 0.2.0-beta.1

package/dist/runtime/server/services/appearance.service.js

@@ -0,0 +1,307 @@
+"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 __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppearanceService = void 0;
+const tsyringe_1 = require("tsyringe");
+const INetTransport_1 = require("../../../adapters/contracts/INetTransport");
+const IPedAppearanceServer_1 = require("../../../adapters/contracts/IPedAppearanceServer");
+const IPlayerServer_1 = require("../../../adapters/contracts/IPlayerServer");
+/**
+ * Server-side appearance management service.
+ *
+ * @remarks
+ * Handles validating and applying ped appearance data on the server.
+ * Provides security validation and server-authoritative appearance control.
+ *
+ * **Security Model:**
+ * - All appearance changes should be validated server-side
+ * - Server applies components/props directly (available natives)
+ * - Server emits events to client for client-only natives (headBlend, overlays, tattoos)
+ * - Client never sends appearance data directly to other clients
+ *
+ * **Persistence:**
+ * The framework does NOT handle persistence internally.
+ * After calling `applyAppearance`, you receive the validated data back.
+ * You decide when and where to save it (database, file, etc.).
+ *
+ * @example
+ * ```typescript
+ * // Apply appearance to a player
+ * const result = await appearanceService.applyAppearance(playerSrc, appearanceData)
+ * if (result.success) {
+ *   // Save to your database
+ *   await myDatabase.saveAppearance(playerId, result.appearance)
+ * }
+ *
+ * // Validate appearance without applying
+ * const validation = appearanceService.validateAppearance(appearanceData)
+ * if (!validation.valid) {
+ *   console.log('Errors:', validation.errors)
+ * }
+ * ```
+ */
+let AppearanceService = class AppearanceService {
+    constructor(pedAdapter, playerServer, netTransport) {
+        this.pedAdapter = pedAdapter;
+        this.playerServer = playerServer;
+        this.netTransport = netTransport;
+    }
+    /**
+     * Applies validated appearance to a player.
+     *
+     * @remarks
+     * This method:
+     * 1. Validates the appearance data
+     * 2. Applies server-side natives (components, props)
+     * 3. Emits event to client for client-only natives
+     * 4. Returns the validated appearance for persistence
+     *
+     * @param playerSrc - Player source/client ID
+     * @param appearance - Appearance data to apply
+     * @returns Result with success status and validated appearance
+     */
+    async applyAppearance(playerSrc, appearance) {
+        const validation = this.validateAppearance(appearance);
+        if (!validation.valid) {
+            return { success: false, errors: validation.errors };
+        }
+        const ped = this.playerServer.getPed(playerSrc);
+        if (ped === 0) {
+            return { success: false, errors: ['Player ped not found'] };
+        }
+        // Apply server-side natives (components and props)
+        this.applyServerSideAppearance(ped, appearance);
+        // Emit event to client for client-only natives
+        this.netTransport.emitNet('opencore:appearance:apply', parseInt(playerSrc, 10), appearance);
+        return { success: true, appearance };
+    }
+    /**
+     * Applies only components and props (server-side available natives).
+     *
+     * @remarks
+     * Use this for quick clothing changes without full appearance update.
+     *
+     * @param playerSrc - Player source/client ID
+     * @param appearance - Partial appearance with components/props only
+     * @returns Success status
+     */
+    applyClothing(playerSrc, appearance) {
+        const ped = this.playerServer.getPed(playerSrc);
+        if (ped === 0) {
+            return false;
+        }
+        this.applyServerSideAppearance(ped, appearance);
+        return true;
+    }
+    /**
+     * Resets a player's appearance to default.
+     *
+     * @param playerSrc - Player source/client ID
+     * @returns Success status
+     */
+    resetAppearance(playerSrc) {
+        const ped = this.playerServer.getPed(playerSrc);
+        if (ped === 0) {
+            return false;
+        }
+        this.pedAdapter.setDefaultComponentVariation(ped);
+        // Notify client to reset client-only appearance elements
+        this.netTransport.emitNet('opencore:appearance:reset', parseInt(playerSrc, 10));
+        return true;
+    }
+    /**
+     * Validates appearance data without applying it.
+     *
+     * @remarks
+     * Use this to validate appearance data before storing or applying.
+     * All validation rules are enforced to prevent invalid/malicious data.
+     *
+     * @param appearance - Appearance data to validate
+     * @returns Validation result with errors if any
+     */
+    validateAppearance(appearance) {
+        const errors = [];
+        if (!appearance) {
+            return { valid: false, errors: ['Appearance data is null or undefined'] };
+        }
+        // Validate components (0-11)
+        if (appearance.components) {
+            for (const [id, data] of Object.entries(appearance.components)) {
+                const componentId = parseInt(id, 10);
+                if (Number.isNaN(componentId) || componentId < 0 || componentId > 11) {
+                    errors.push(`Invalid component ID: ${id} (must be 0-11)`);
+                }
+                if (data.drawable === undefined || data.drawable < -1) {
+                    errors.push(`Invalid drawable for component ${id}`);
+                }
+                if (data.texture === undefined || data.texture < 0) {
+                    errors.push(`Invalid texture for component ${id}`);
+                }
+            }
+        }
+        // Validate props (0-7)
+        if (appearance.props) {
+            for (const [id, data] of Object.entries(appearance.props)) {
+                const propId = parseInt(id, 10);
+                if (Number.isNaN(propId) || propId < 0 || propId > 7) {
+                    errors.push(`Invalid prop ID: ${id} (must be 0-7)`);
+                }
+                if (data.drawable === undefined) {
+                    errors.push(`Missing drawable for prop ${id}`);
+                }
+                if (data.texture === undefined || data.texture < 0) {
+                    errors.push(`Invalid texture for prop ${id}`);
+                }
+            }
+        }
+        // Validate faceFeatures (0-19, values -1.0 to 1.0)
+        if (appearance.faceFeatures) {
+            for (const [id, value] of Object.entries(appearance.faceFeatures)) {
+                const index = parseInt(id, 10);
+                if (Number.isNaN(index) || index < 0 || index > 19) {
+                    errors.push(`Invalid face feature index: ${id} (must be 0-19)`);
+                }
+                if (typeof value !== 'number' || value < -1.0 || value > 1.0) {
+                    errors.push(`Face feature ${id} value out of range: ${value} (must be -1.0 to 1.0)`);
+                }
+            }
+        }
+        // Validate headBlend
+        if (appearance.headBlend) {
+            const hb = appearance.headBlend;
+            if (typeof hb.shapeFirst !== 'number' || hb.shapeFirst < 0 || hb.shapeFirst > 45) {
+                errors.push('Invalid shapeFirst (must be 0-45)');
+            }
+            if (typeof hb.shapeSecond !== 'number' || hb.shapeSecond < 0 || hb.shapeSecond > 45) {
+                errors.push('Invalid shapeSecond (must be 0-45)');
+            }
+            if (typeof hb.skinFirst !== 'number' || hb.skinFirst < 0 || hb.skinFirst > 45) {
+                errors.push('Invalid skinFirst (must be 0-45)');
+            }
+            if (typeof hb.skinSecond !== 'number' || hb.skinSecond < 0 || hb.skinSecond > 45) {
+                errors.push('Invalid skinSecond (must be 0-45)');
+            }
+            if (typeof hb.shapeMix !== 'number' || hb.shapeMix < 0 || hb.shapeMix > 1) {
+                errors.push('Invalid shapeMix (must be 0.0-1.0)');
+            }
+            if (typeof hb.skinMix !== 'number' || hb.skinMix < 0 || hb.skinMix > 1) {
+                errors.push('Invalid skinMix (must be 0.0-1.0)');
+            }
+            if (hb.shapeThird !== undefined && (hb.shapeThird < 0 || hb.shapeThird > 45)) {
+                errors.push('Invalid shapeThird (must be 0-45)');
+            }
+            if (hb.skinThird !== undefined && (hb.skinThird < 0 || hb.skinThird > 45)) {
+                errors.push('Invalid skinThird (must be 0-45)');
+            }
+            if (hb.thirdMix !== undefined && (hb.thirdMix < 0 || hb.thirdMix > 1)) {
+                errors.push('Invalid thirdMix (must be 0.0-1.0)');
+            }
+        }
+        // Validate headOverlays (0-12)
+        if (appearance.headOverlays) {
+            for (const [id, overlay] of Object.entries(appearance.headOverlays)) {
+                const overlayId = parseInt(id, 10);
+                if (Number.isNaN(overlayId) || overlayId < 0 || overlayId > 12) {
+                    errors.push(`Invalid overlay ID: ${id} (must be 0-12)`);
+                }
+                if (typeof overlay.index !== 'number' || overlay.index < 0) {
+                    errors.push(`Invalid overlay index for ID ${id}`);
+                }
+                if (typeof overlay.opacity !== 'number' || overlay.opacity < 0 || overlay.opacity > 1) {
+                    errors.push(`Invalid overlay opacity for ID ${id} (must be 0.0-1.0)`);
+                }
+                if (overlay.colorType !== undefined && ![0, 1, 2].includes(overlay.colorType)) {
+                    errors.push(`Invalid overlay colorType for ID ${id} (must be 0, 1, or 2)`);
+                }
+            }
+        }
+        // Validate hairColor
+        if (appearance.hairColor) {
+            if (typeof appearance.hairColor.colorId !== 'number' || appearance.hairColor.colorId < 0) {
+                errors.push('Invalid hair colorId');
+            }
+            if (typeof appearance.hairColor.highlightColorId !== 'number' ||
+                appearance.hairColor.highlightColorId < 0) {
+                errors.push('Invalid hair highlightColorId');
+            }
+        }
+        // Validate eyeColor (0-31)
+        if (appearance.eyeColor !== undefined) {
+            if (typeof appearance.eyeColor !== 'number' ||
+                appearance.eyeColor < 0 ||
+                appearance.eyeColor > 31) {
+                errors.push(`Invalid eye color: ${appearance.eyeColor} (must be 0-31)`);
+            }
+        }
+        // Validate tattoos
+        if (appearance.tattoos) {
+            if (!Array.isArray(appearance.tattoos)) {
+                errors.push('Tattoos must be an array');
+            }
+            else {
+                for (let i = 0; i < appearance.tattoos.length; i++) {
+                    const tattoo = appearance.tattoos[i];
+                    if (!tattoo.collection || typeof tattoo.collection !== 'string') {
+                        errors.push(`Invalid tattoo collection at index ${i}`);
+                    }
+                    if (!tattoo.overlay || typeof tattoo.overlay !== 'string') {
+                        errors.push(`Invalid tattoo overlay at index ${i}`);
+                    }
+                }
+            }
+        }
+        // Validate model
+        if (appearance.model !== undefined) {
+            if (typeof appearance.model !== 'string' || appearance.model.length === 0) {
+                errors.push('Invalid model (must be a non-empty string)');
+            }
+        }
+        return { valid: errors.length === 0, errors };
+    }
+    /**
+     * Applies server-side appearance natives (components and props only).
+     *
+     * @param ped - Ped entity handle
+     * @param appearance - Appearance data
+     */
+    applyServerSideAppearance(ped, appearance) {
+        // Apply components
+        if (appearance.components) {
+            for (const [componentId, data] of Object.entries(appearance.components)) {
+                this.pedAdapter.setComponentVariation(ped, parseInt(componentId, 10), data.drawable, data.texture, 2);
+            }
+        }
+        // Apply props
+        if (appearance.props) {
+            for (const [propId, data] of Object.entries(appearance.props)) {
+                if (data.drawable === -1) {
+                    this.pedAdapter.clearProp(ped, parseInt(propId, 10));
+                }
+                else {
+                    this.pedAdapter.setPropIndex(ped, parseInt(propId, 10), data.drawable, data.texture, true);
+                }
+            }
+        }
+    }
+};
+exports.AppearanceService = AppearanceService;
+exports.AppearanceService = AppearanceService = __decorate([
+    (0, tsyringe_1.injectable)(),
+    __param(0, (0, tsyringe_1.inject)(IPedAppearanceServer_1.IPedAppearanceServer)),
+    __param(1, (0, tsyringe_1.inject)(IPlayerServer_1.IPlayerServer)),
+    __param(2, (0, tsyringe_1.inject)(INetTransport_1.INetTransport)),
+    __metadata("design:paramtypes", [IPedAppearanceServer_1.IPedAppearanceServer,
+        IPlayerServer_1.IPlayerServer,
+        INetTransport_1.INetTransport])
+], AppearanceService);

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

@@ -0,0 +1,33 @@
+import { Server } from '../../..';
+import { RGB } from '../../../kernel/utils';
+/**
+ * Service for sending chat messages to players.
+ *
+ * @remarks
+ * This service emits framework chat events over the network.
+ */
+export declare class ChatService {
+    /**
+     * Broadcast a chat message to all connected players.
+     *
+     * @param message - Message body.
+     * @param author - Author label shown in chat. Defaults to `SYSTEM`.
+     * @param color - Message color (RGB). Defaults to white.
+     */
+    broadcast(message: string, author?: string, color?: RGB): void;
+    /**
+     * Send a private chat message to a single player.
+     *
+     * @param player - Target player.
+     * @param message - Message body.
+     * @param author - Author label shown in chat. Defaults to `Private`.
+     * @param color - Message color (RGB).
+     */
+    sendPrivate(player: Server.Player, message: string, author?: string, color?: RGB): void;
+    /**
+     * Clear chat for a single player.
+     *
+     * @param player - Target player.
+     */
+    clearChat(player: Server.Player): void;
+}

package/dist/{server → runtime/server}/services/chat.service.js

@@ -8,19 +8,45 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChatService = void 0;
 const tsyringe_1 = require("tsyringe");
+/**
+ * Service for sending chat messages to players.
+ *
+ * @remarks
+ * This service emits framework chat events over the network.
+ */
 let ChatService = class ChatService {
+    /**
+     * Broadcast a chat message to all connected players.
+     *
+     * @param message - Message body.
+     * @param author - Author label shown in chat. Defaults to `SYSTEM`.
+     * @param color - Message color (RGB). Defaults to white.
+     */
     broadcast(message, author = 'SYSTEM', color = { r: 255, g: 255, b: 255 }) {
         emitNet('core:chat:message', -1, {
             args: [author, message],
             color: color,
         });
     }
+    /**
+     * Send a private chat message to a single player.
+     *
+     * @param player - Target player.
+     * @param message - Message body.
+     * @param author - Author label shown in chat. Defaults to `Private`.
+     * @param color - Message color (RGB).
+     */
     sendPrivate(player, message, author = 'Private', color = { r: 200, g: 200, b: 200 }) {
         emitNet('core:chat:addMessage', player.clientID, {
             args: [author, message],
             color: color,
         });
     }
+    /**
+     * Clear chat for a single player.
+     *
+     * @param player - Target player.
+     */
     clearChat(player) {
         emitNet('core:chat:clear', player.clientID);
     }

package/dist/{server → runtime/server}/services/config.service.js

@@ -62,7 +62,7 @@ let ConfigService = class ConfigService {
     getNumber(key, defaultValue) {
         const value = GetConvar(this.PREFIX + key, String(defaultValue));
         const parsed = Number(value);
-        return isNaN(parsed) ? defaultValue : parsed;
+        return Number.isNaN(parsed) ? defaultValue : parsed;
     }
     /**
      * Gets a boolean configuration value.

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

@@ -0,0 +1,49 @@
+import { CommandMetadata } from '../../decorators/command';
+import { Player } from '../../entities';
+import { CommandExecutionPort, type CommandInfo } from '../ports/command-execution.port';
+/**
+ * Local command execution service (CORE/STANDALONE modes).
+ *
+ * @remarks
+ * Maintains an in-memory registry of command handlers and executes them with full validation.
+ * Controllers declare commands via @Command decorator. During bootstrap, the framework
+ * scans and registers handlers via CommandProcessor.
+ *
+ * Execution pipeline:
+ * - Enforces authentication (secure by default unless marked @Public)
+ * - Validates arguments using Zod schemas (explicit or auto-generated)
+ * - Coerces argument types before invoking handlers
+ */
+export declare class CommandService extends CommandExecutionPort {
+    private commands;
+    /**
+     * Registers a command handler.
+     *
+     * @param meta - Command metadata collected from the {@link Command} decorator.
+     * @param handler - The bound method to invoke.
+     */
+    register(meta: CommandMetadata, handler: Function): void;
+    /**
+     * Executes a registered command.
+     *
+     * @remarks
+     * **Security**: Commands require authentication by default unless marked with @Public().
+     * Unauthenticated attempts are blocked gracefully with player notification.
+     *
+     * Argument parsing behavior depends on the schema:
+     * - Zod object schema: maps raw args to parameter names.
+     * - Zod tuple schema: validates positional args.
+     * - No schema: attempts to generate a schema from parameter types.
+     *
+     * @param player - Player invoking the command.
+     * @param commandName - Command name (without the leading `/`).
+     * @param args - Raw argument list (strings).
+     *
+     * @throws AppError - If the command does not exist, the schema mismatches parameters, or validation fails.
+     */
+    execute(player: Player, commandName: string, args: string[]): Promise<any>;
+    /**
+     * Returns a list of all registered commands.
+     */
+    getAllCommands(): CommandInfo[];
+}

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

@@ -0,0 +1,112 @@
+"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.CommandService = void 0;
+const tsyringe_1 = require("tsyringe");
+const logger_1 = require("../../../../kernel/shared/logger");
+const utils_1 = require("../../../../kernel/utils");
+const command_validation_helper_1 = require("../../helpers/command-validation.helper");
+const command_execution_port_1 = require("../ports/command-execution.port");
+/**
+ * Local command execution service (CORE/STANDALONE modes).
+ *
+ * @remarks
+ * Maintains an in-memory registry of command handlers and executes them with full validation.
+ * Controllers declare commands via @Command decorator. During bootstrap, the framework
+ * scans and registers handlers via CommandProcessor.
+ *
+ * Execution pipeline:
+ * - Enforces authentication (secure by default unless marked @Public)
+ * - Validates arguments using Zod schemas (explicit or auto-generated)
+ * - Coerces argument types before invoking handlers
+ */
+let CommandService = class CommandService extends command_execution_port_1.CommandExecutionPort {
+    constructor() {
+        super(...arguments);
+        this.commands = new Map();
+    }
+    /**
+     * Registers a command handler.
+     *
+     * @param meta - Command metadata collected from the {@link Command} decorator.
+     * @param handler - The bound method to invoke.
+     */
+    register(meta, handler) {
+        var _a;
+        if (this.commands.has(meta.command.toLowerCase())) {
+            logger_1.loggers.command.error(`Command '${meta.command}' is already registered. Skipped`, {
+                command: meta.command,
+            });
+        }
+        this.commands.set(meta.command.toLowerCase(), {
+            meta,
+            handler,
+            isPublic: (_a = meta.isPublic) !== null && _a !== void 0 ? _a : false,
+        });
+        const publicFlag = meta.isPublic ? ' [Public]' : '';
+        const schemaFlag = meta.schema ? ' [Validated]' : '';
+        logger_1.loggers.command.debug(`Registered: /${meta.command}${publicFlag}${schemaFlag}`);
+    }
+    /**
+     * Executes a registered command.
+     *
+     * @remarks
+     * **Security**: Commands require authentication by default unless marked with @Public().
+     * Unauthenticated attempts are blocked gracefully with player notification.
+     *
+     * Argument parsing behavior depends on the schema:
+     * - Zod object schema: maps raw args to parameter names.
+     * - Zod tuple schema: validates positional args.
+     * - No schema: attempts to generate a schema from parameter types.
+     *
+     * @param player - Player invoking the command.
+     * @param commandName - Command name (without the leading `/`).
+     * @param args - Raw argument list (strings).
+     *
+     * @throws AppError - If the command does not exist, the schema mismatches parameters, or validation fails.
+     */
+    async execute(player, commandName, args) {
+        const entry = this.commands.get(commandName.toLowerCase());
+        if (!entry)
+            throw new utils_1.AppError('COMMAND:NOT_FOUND', `Command not found: ${commandName}`, 'client');
+        const { meta, handler, isPublic } = entry;
+        // ═══════════════════════════════════════════════════════════════
+        // SECURE BY DEFAULT: Require authentication unless @Public()
+        // ═══════════════════════════════════════════════════════════════
+        if (!isPublic) {
+            if (!player.accountID) {
+                logger_1.loggers.security.warn(`Unauthenticated command attempt blocked`, {
+                    command: commandName,
+                    clientId: player.clientID,
+                });
+                player.emit('core:auth:required', { command: commandName });
+                player.send('You must be authenticated to use this command', 'error');
+                return;
+            }
+        }
+        return await (0, command_validation_helper_1.validateAndExecuteCommand)(meta, player, args, handler);
+    }
+    /**
+     * Returns a list of all registered commands.
+     */
+    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 : '',
+                isPublic: c.isPublic,
+            });
+        });
+    }
+};
+exports.CommandService = CommandService;
+exports.CommandService = CommandService = __decorate([
+    (0, tsyringe_1.injectable)()
+], CommandService);

package/dist/{server/services → runtime/server/services/core}/player.service.d.ts

@@ -1,30 +1,35 @@
-import type { UUIDTypes } from 'uuid';
-import { Player } from '../entities/player';
-/**
- * Type representing a linked account identifier. This come from your persistence layer
- * and is used to associate a Player session with their stored data.
- */
-export type LinkedID = string | UUIDTypes;
-export interface PlayerSession {
-    clientID: number;
-    accountID?: LinkedID;
-    identifiers?: {
-        license?: string;
-        steam?: string;
-        discord?: string;
-    };
-    meta: Record<string, unknown>;
-}
+import { IPlayerInfo } from '../../../../adapters';
+import { IEntityServer } from '../../../../adapters/contracts/IEntityServer';
+import { INetTransport } from '../../../../adapters/contracts/INetTransport';
+import { IPlayerServer } from '../../../../adapters/contracts/IPlayerServer';
+import { Player } from '../../entities';
+import { PlayerDirectoryPort } from '../ports/player-directory.port';
+import { PlayerSessionLifecyclePort } from '../ports/player-session-lifecycle.port';
+import { LinkedID } from '../types/linked-id';
+import { PlayerSession } from '../types/player-session.object';
 /**
  * Service responsible for managing the lifecycle of player sessions.
  * It acts as the central registry for all connected players, mapping FiveM client IDs
  * to Core `Player` entities.
+ *
+ * @remarks
+ * This service is used as a singleton in the dependency container.
+ * It exposes the operations defined by {@link PlayerDirectoryPort} and {@link PlayerSessionLifecyclePort}.
  */
-export declare class PlayerService {
+export declare class PlayerService implements PlayerDirectoryPort, PlayerSessionLifecyclePort {
+    private readonly playerInfo;
+    private readonly playerServer;
+    private readonly entityServer;
+    private readonly netTransport;
     /**
      * Internal map storing active player sessions indexed by their FiveM client ID (source).
      */
     private playersByClient;
+    /**
+     * Cached adapters bundle for Player instances
+     */
+    private readonly playerAdapters;
+    constructor(playerInfo: IPlayerInfo, playerServer: IPlayerServer, entityServer: IEntityServer, netTransport: INetTransport);
     /**
      * Initializes a new player session for a connecting client.
      *
@@ -54,21 +59,22 @@ export declare class PlayerService {
      *
      * @param clientID - The FiveM server ID of the player disconnecting.
      */
-    unbindByClient(clientID: number): void;
+    unbind(clientID: number): void;
     /**
      * Retrieves the `Player` entity associated with a specific FiveM client ID.
      *
      * @param clientID - The FiveM server ID to look up.
      * @returns The `Player` instance if found, or `null` if the session does not exist.
      */
-    getByClient(clientID: number): Player | null;
+    getByClient(clientID: number): Player | undefined;
+    getMany(clientIds: number[]): Player[];
     /**
      * Helper to retrieve the authenticated Account ID for a given client.
      *
      * @param clientID - The FiveM server ID to look up.
      * @returns The bound Account ID (string/UUID) if the player is logged in, or `null` otherwise.
      */
-    getPlayerId(clientID: number): string | null;
+    getPlayerId(clientID: number): string | undefined;
     /**
      * Stores arbitrary metadata in the player's session.
      * Useful for storing transient state like 'isDead', 'job', 'dimension', etc.
@@ -86,11 +92,31 @@ export declare class PlayerService {
      * @param key - The metadata key to retrieve.
      * @returns The value cast to type `T`, or `undefined` if the key or player doesn't exist.
      */
-    getMeta<T = unknown>(clientID: number, key: string): T | undefined;
+    getMeta<T = unknown>(clientID: number, key: string): Promise<T | undefined>;
     /**
      * Returns a list of all currently active `Player` entities.
      *
      * @returns An array containing all connected players managed by this service.
      */
     getAll(): Player[];
+    /**
+     * Retrieves a Player by their persistent account ID.
+     *
+     * @param accountId - The unique account identifier to search for.
+     * @returns The Player if found, or `undefined` if not online.
+     */
+    getByAccountId(accountId: string): Player | undefined;
+    /**
+     * Returns the current number of connected players.
+     *
+     * @returns Player count.
+     */
+    getPlayerCount(): number;
+    /**
+     * Checks if a player with the given account ID is currently online.
+     *
+     * @param accountId - The account identifier to check.
+     * @returns `true` if online, `false` otherwise.
+     */
+    isOnline(accountId: string): boolean;
 }