@open-core/framework 0.2.7 → 0.2.9

package/README.md

@@ -1,4 +1,12 @@
-# OpenCore Framework (v0.2.4) Open Stable beta
+[![CI](https://github.com/newcore-network/opencore/actions/workflows/ci.yml/badge.svg)](https://github.com/newcore-network/opencore/actions/workflows/ci.yml)
+![npm](https://img.shields.io/npm/v/@open-core/framework?style=flat-square)
+![license](https://img.shields.io/github/license/newcore-network/opencore?style=flat-square)
+![typescript](https://img.shields.io/badge/TypeScript-first-blue?style=flat-square)
+[![cli](https://img.shields.io/badge/CLI-opencore--cli-purple?style=flat-square)](https://opencorejs.dev/docs/cli/introduction)
+[![website](https://img.shields.io/badge/web-opencorejs.dev-black?style=flat-square)](https://opencorejs.dev)
+
+
+# OpenCore Framework - Open Stable beta
 
 OpenCore is a TypeScript multiplayer runtime framework targeting FiveM via an adapter.
 
@@ -11,6 +19,8 @@ It is not a gamemode or RP framework. It provides:
 
 License: MPL-2.0
 
+[Discord Community](https://discord.gg/99g3FgvkPs) | [Website](https://opencorejs.dev) | [OpenCore CLI](https://github.com/newcore-network/opencore-cli)
+
 ## Scope
 
 This package (`@open-core/framework`) contains transversal infrastructure only.

package/dist/adapters/contracts/IEngineEvents.d.ts

@@ -5,7 +5,7 @@ export declare abstract class IEngineEvents {
      * @param eventName - The event name to listen for
      * @param handler - The callback to invoke when the event is emitted
      */
-    abstract on(eventName: string, handler: (...args: any[]) => void): void;
+    abstract on(eventName: string, handler?: (...args: any[]) => void): void;
     /**
      * Emits a local (server-side) event.
      *

package/dist/adapters/contracts/IPlayerServer.d.ts

@@ -70,4 +70,14 @@ export declare abstract class IPlayerServer {
      * @param bucket - Routing bucket ID
      */
     abstract setRoutingBucket(playerSrc: string, bucket: number): void;
+    /**
+     * Gets all currently connected player sources.
+     *
+     * @remarks
+     * Returns the source IDs (as strings) of all players currently connected to the server.
+     * Used for session recovery after resource restarts.
+     *
+     * @returns Array of player source strings
+     */
+    abstract getConnectedPlayers(): string[];
 }

package/dist/adapters/fivem/fivem-engine-events.d.ts

@@ -1,5 +1,5 @@
 import { IEngineEvents } from '../contracts/IEngineEvents';
 export declare class FiveMEngineEvents extends IEngineEvents {
-    on(eventName: string, handler: (...args: any[]) => void): void;
+    on(eventName: string, handler?: (...args: any[]) => void): void;
     emit(eventName: string, ...args: any[]): void;
 }

package/dist/adapters/fivem/fivem-engine-events.js

@@ -4,7 +4,10 @@ exports.FiveMEngineEvents = void 0;
 const IEngineEvents_1 = require("../contracts/IEngineEvents");
 class FiveMEngineEvents extends IEngineEvents_1.IEngineEvents {
     on(eventName, handler) {
-        on(eventName, handler);
+        if (handler)
+            on(eventName, handler);
+        else
+            on(eventName, () => { }); // empty handler
     }
     emit(eventName, ...args) {
         emit(eventName, ...args);

package/dist/adapters/fivem/fivem-player-server.d.ts

@@ -12,4 +12,5 @@ export declare class FiveMPlayerServer extends IPlayerServer {
     getPing(playerSrc: string): number;
     getEndpoint(playerSrc: string): string;
     setRoutingBucket(playerSrc: string, bucket: number): void;
+    getConnectedPlayers(): string[];
 }

package/dist/adapters/fivem/fivem-player-server.js

@@ -56,6 +56,9 @@ let FiveMPlayerServer = class FiveMPlayerServer extends IPlayerServer_1.IPlayerS
     setRoutingBucket(playerSrc, bucket) {
         SetPlayerRoutingBucket(playerSrc, bucket);
     }
+    getConnectedPlayers() {
+        return getPlayers();
+    }
 };
 exports.FiveMPlayerServer = FiveMPlayerServer;
 exports.FiveMPlayerServer = FiveMPlayerServer = __decorate([

package/dist/adapters/node/node-engine-events.d.ts

@@ -8,7 +8,7 @@ import { IEngineEvents } from '../contracts/IEngineEvents';
  */
 export declare class NodeEngineEvents implements IEngineEvents {
     private eventEmitter;
-    on(eventName: string, handler: (...args: any[]) => void): void;
+    on(eventName: string, handler?: (...args: any[]) => void): void;
     /**
      * Utility method for testing: emit an engine event
      */

package/dist/adapters/node/node-engine-events.js

@@ -21,7 +21,10 @@ let NodeEngineEvents = class NodeEngineEvents {
         this.eventEmitter = new node_events_1.EventEmitter();
     }
     on(eventName, handler) {
-        this.eventEmitter.on(eventName, handler);
+        if (handler)
+            this.eventEmitter.on(eventName, handler);
+        else
+            this.eventEmitter.on(eventName, () => { }); // empty handler
     }
     /**
      * Utility method for testing: emit an engine event

package/dist/adapters/node/node-player-server.d.ts

@@ -23,5 +23,6 @@ export declare class NodePlayerServer extends IPlayerServer {
     }): void;
     _wasDropped(playerSrc: string): boolean;
     setRoutingBucket(_playerSrc: string, _bucket: number): void;
+    getConnectedPlayers(): string[];
     _clear(): void;
 }

package/dist/adapters/node/node-player-server.js

@@ -71,6 +71,9 @@ let NodePlayerServer = class NodePlayerServer extends IPlayerServer_1.IPlayerSer
     setRoutingBucket(_playerSrc, _bucket) {
         // Mock: no-op in Node.js
     }
+    getConnectedPlayers() {
+        return Array.from(this.players.keys());
+    }
     _clear() {
         this.players.clear();
         this.droppedPlayers = [];

package/dist/runtime/client/system/processors/nui.processor.js

@@ -20,15 +20,16 @@ let NuiProcessor = class NuiProcessor {
         RegisterNuiCallbackType(metadata.eventName);
         on(`__cfx_nui:${metadata.eventName}`, async (data, cb) => {
             try {
-                await handler(data);
-                cb({ ok: true });
+                const result = await handler(data);
+                cb({ ok: true, data: result });
             }
             catch (error) {
                 logger_1.loggers.nui.error(`NUI callback error`, {
                     event: metadata.eventName,
                     handler: handlerName,
                 }, error);
-                cb({ ok: false, error: String(error) });
+                const message = error instanceof Error ? error.message : String(error);
+                cb({ ok: false, error: message });
             }
         });
         logger_1.loggers.nui.debug(`Registered: ${metadata.eventName} -> ${handlerName}`);

package/dist/runtime/server/bootstrap.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.initServer = initServer;
+const adapters_1 = require("../../adapters");
 const register_capabilities_1 = require("../../adapters/register-capabilities");
 const index_1 = require("../../kernel/di/index");
 const logger_1 = require("../../kernel/shared/logger");
@@ -41,8 +42,10 @@ const bootstrap_validation_1 = require("./bootstrap.validation");
 const index_2 = require("./contracts/index");
 const controller_1 = require("./decorators/controller");
 const runtime_1 = require("./runtime");
+const session_recovery_service_1 = require("./services/core/session-recovery.service");
 const services_register_1 = require("./services/services.register");
 const processors_register_1 = require("./system/processors.register");
+const CORE_WAIT_TIMEOUT = 10000;
 function checkProviders(ctx) {
     if (ctx.mode === 'RESOURCE')
         return;
@@ -108,7 +111,7 @@ async function loadFrameworkControllers(ctx) {
  * @returns A promise that resolves when the Core is fully initialized and ready to process events.
  */
 async function initServer(options) {
-    var _a;
+    var _a, _b, _c, _d;
     (0, runtime_1.validateRuntimeOptions)(options);
     (0, runtime_1.setRuntimeContext)(options);
     const ctx = options;
@@ -117,7 +120,26 @@ async function initServer(options) {
         mode: ctx.mode,
         scope: (0, runtime_1.getFrameworkModeScope)(ctx.mode),
     });
+    // Adapters
     await (0, register_capabilities_1.registerServerCapabilities)();
+    const dependenciesToWaitFor = [];
+    if (ctx.mode === 'RESOURCE') {
+        logger_1.loggers.bootstrap.info(`[WAIT] Standing by for Core '${ctx.coreResourceName}' to be ready...`);
+        dependenciesToWaitFor.push(createCoreDependency(ctx.coreResourceName));
+    }
+    if ((_a = options.onDependency) === null || _a === void 0 ? void 0 : _a.waitFor) {
+        const userDeps = Array.isArray(options.onDependency.waitFor)
+            ? options.onDependency.waitFor
+            : [options.onDependency.waitFor];
+        dependenciesToWaitFor.push(...userDeps);
+    }
+    if (dependenciesToWaitFor.length > 0 || ((_b = options.onDependency) === null || _b === void 0 ? void 0 : _b.onReady)) {
+        await dependencyResolver(dependenciesToWaitFor, (_c = options.onDependency) === null || _c === void 0 ? void 0 : _c.onReady);
+    }
+    if (ctx.mode === 'RESOURCE') {
+        logger_1.loggers.bootstrap.info(`Core ready detected!`);
+    }
+    logger_1.loggers.bootstrap.debug('Dependencies resolved. Proceeding with system boot.');
     (0, services_register_1.registerServicesServer)(ctx);
     logger_1.loggers.bootstrap.debug('Core services registered');
     (0, processors_register_1.registerSystemServer)(ctx);
@@ -203,10 +225,85 @@ async function initServer(options) {
     const scanner = index_1.di.resolve(index_1.MetadataScanner);
     scanner.scan((0, controller_1.getServerControllerRegistry)());
     // Initialize DevMode if enabled
-    if ((_a = ctx.devMode) === null || _a === void 0 ? void 0 : _a.enabled) {
+    if ((_d = ctx.devMode) === null || _d === void 0 ? void 0 : _d.enabled) {
         await initDevMode(ctx.devMode);
     }
+    // Run session recovery if enabled (recovers sessions for players already connected)
+    if (ctx.features.sessionLifecycle.enabled && ctx.features.sessionLifecycle.recoveryOnRestart) {
+        runSessionRecovery();
+    }
     logger_1.loggers.bootstrap.info('OpenCore Server initialized successfully');
+    if (ctx.mode === 'CORE' && index_1.di.isRegistered(adapters_1.IEngineEvents)) {
+        const engineInterface = index_1.di.resolve(adapters_1.IEngineEvents);
+        engineInterface.emit('core:ready');
+    }
+}
+function createCoreDependency(coreName) {
+    return new Promise((resolve, reject) => {
+        let resolved = false;
+        const engineEvents = index_1.di.resolve(adapters_1.IEngineEvents);
+        const cleanup = () => {
+            resolved = true;
+            clearTimeout(timeout);
+        };
+        const timeout = setTimeout(() => {
+            if (!resolved) {
+                reject(new Error(`[OpenCore] Timeout waiting for CORE '${coreName}'. The Core did not emit 'core:ready' within ${CORE_WAIT_TIMEOUT}ms.`));
+            }
+        }, CORE_WAIT_TIMEOUT);
+        const onReady = () => {
+            if (!resolved) {
+                cleanup();
+                resolve();
+            }
+        };
+        engineEvents.on('core:ready', onReady);
+    });
+}
+async function dependencyResolver(waitFor, onReady) {
+    if (waitFor) {
+        const dependencyPromises = Array.isArray(waitFor) ? waitFor : [waitFor];
+        try {
+            await Promise.all(dependencyPromises);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger_1.loggers.bootstrap.fatal(`Failed to resolve startup dependencies`, { error: msg });
+            throw new Error(`[OpenCore] Startup aborted: ${msg}`);
+        }
+    }
+    if (onReady) {
+        try {
+            await onReady();
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger_1.loggers.bootstrap.fatal('Failed to execute onReady hook', { error: msg });
+            throw new Error(`[OpenCore] onReady hook failed: ${msg}`);
+        }
+    }
+}
+/**
+ * Runs session recovery to restore sessions for players already connected.
+ *
+ * @remarks
+ * This is useful during development when hot-reloading resources.
+ * Players remain connected to FiveM but lose their sessions when the resource restarts.
+ * This function detects these orphaned players and recreates their sessions.
+ */
+function runSessionRecovery() {
+    try {
+        const recoveryService = index_1.di.resolve(session_recovery_service_1.SessionRecoveryService);
+        const stats = recoveryService.recoverSessions();
+        if (stats.recovered > 0) {
+            logger_1.loggers.bootstrap.info(`[SessionRecovery] Recovered ${stats.recovered} player session(s)`);
+        }
+    }
+    catch (error) {
+        logger_1.loggers.bootstrap.warn('[SessionRecovery] Failed to run session recovery', {
+            error: error.message,
+        });
+    }
 }
 /**
  * Initializes the DevMode subsystem.

package/dist/runtime/server/decorators/command.d.ts

@@ -81,4 +81,5 @@ type ServerCommandHandler = (() => any) | ((player: Player, ...args: any[]) => a
 export declare function Command(name: string, schema: z.ZodType): <T extends ServerCommandHandler>(target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) => void;
 export declare function Command(name: string): <T extends ServerCommandHandler>(target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) => void;
 export declare function Command(config: CommandConfig): <T extends ServerCommandHandler>(target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) => void;
+export declare function Command(config: CommandConfig, schema: z.ZodType): <T extends ServerCommandHandler>(target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) => void;
 export {};

package/dist/runtime/server/decorators/guard.d.ts

@@ -30,20 +30,22 @@ export interface GuardOptions {
  *
  * @throws Error - If the method is invoked without a valid `Player` as the first argument.
  *
- * @example
  * ```ts
  * @Server.Controller()
- * export class FactionController {
+ * export class AdminController {
+ *
  *   @Server.Guard({ permission: 'factions.manage' })
- *   async createFaction(player: Server.Player, dto: CreateFactionDTO) {
+ *   @Server.Command('newfaction', schema)
+ *   async createFaction(player: Server.Player, dto: Infer<typeof schema>) {
  *     return this.service.create(dto)
  *   }
  *
  *   @Server.Guard({ rank: 3 })
- *   async promoteMember(player: Server.Player, memberID: string) {
- *     return this.service.promote(player, memberID)
+ *   @Server.Command('ban')
+ *   async ban(player: Server.Player, targetID: string) {
+ *     return this.service.ban(player, memberID)
  *   }
- * }
+}
  * ```
  */
 export declare function Guard(options: GuardOptions): (target: any, propertyKey: string, descriptor?: PropertyDescriptor) => PropertyDescriptor | undefined;

package/dist/runtime/server/decorators/guard.js

@@ -25,20 +25,22 @@ const principal_port_1 = require("../services/ports/principal.port");
  *
  * @throws Error - If the method is invoked without a valid `Player` as the first argument.
  *
- * @example
  * ```ts
  * @Server.Controller()
- * export class FactionController {
+ * export class AdminController {
+ *
  *   @Server.Guard({ permission: 'factions.manage' })
- *   async createFaction(player: Server.Player, dto: CreateFactionDTO) {
+ *   @Server.Command('newfaction', schema)
+ *   async createFaction(player: Server.Player, dto: Infer<typeof schema>) {
  *     return this.service.create(dto)
  *   }
  *
  *   @Server.Guard({ rank: 3 })
- *   async promoteMember(player: Server.Player, memberID: string) {
- *     return this.service.promote(player, memberID)
+ *   @Server.Command('ban')
+ *   async ban(player: Server.Player, targetID: string) {
+ *     return this.service.ban(player, memberID)
  *   }
- * }
+}
  * ```
  */
 function Guard(options) {

package/dist/runtime/server/decorators/onNet.d.ts

@@ -48,15 +48,15 @@ type ServerNetHandler<TArgs extends any[] = any[]> = (player: Player, ...args: T
  * export class ExampleController {
  *   // Simple handler (no schema)
  *   @Server.OnNet('example:ping')
- *   ping(player: Player, message: string) { }
+ *   ping(player: Server.Player, message: string) { }
  *
  *   // With schema directly (recommended)
  *   @Server.OnNet('example:data', PayloadSchema)
- *   handleData(player: Player, data: Infer<typeof PayloadSchema>) { }
+ *   handleData(player: Server.Player, data: Infer<typeof PayloadSchema>) { }
  *
  *   // With options object (legacy)
  *   @Server.OnNet('example:legacy', { schema: PayloadSchema })
- *   handleLegacy(player: Player, data: Infer<typeof PayloadSchema>) { }
+ *   handleLegacy(player: Server.Player, data: Infer<typeof PayloadSchema>) { }
  * }
  * ```
  */

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

@@ -240,8 +240,24 @@ export interface UserFeatureConfig {
      *
      * @defaultValue
      * - enabled: true (CORE/STANDALONE), false (RESOURCE)
+     * - recoveryOnRestart: true
      */
-    sessionLifecycle?: BaseFeatureConfig;
+    sessionLifecycle?: BaseFeatureConfig & {
+        /**
+         * Automatically recover sessions for players already connected when the resource restarts.
+         *
+         * @remarks
+         * When enabled, the framework will scan for connected players on startup and
+         * create sessions for any players that don't have an active session.
+         * This is useful during development when hot-reloading resources.
+         *
+         * **Note**: Only basic session data (clientID, identifiers) is recovered.
+         * Players will need to re-authenticate to restore accountID and other auth-related data.
+         *
+         * @defaultValue true
+         */
+        recoveryOnRestart?: boolean;
+    };
 }
 /**
  * Internal feature contract with all fields resolved.
@@ -285,6 +301,16 @@ export interface FeatureContract {
      * When `true`, the feature cannot be disabled (`enabled` must be `true`).
      */
     required: boolean;
+    /**
+     * (sessionLifecycle only) Enable automatic session recovery on resource restart.
+     *
+     * @remarks
+     * When true, scans for connected players on startup and creates sessions
+     * for any that don't have an active session.
+     *
+     * @defaultValue true
+     */
+    recoveryOnRestart?: boolean;
 }
 export type FrameworkFeatures = Record<FeatureName, FeatureContract>;
 export interface ResourceGrants {
@@ -318,6 +344,10 @@ export interface DevModeConfig {
         autoConnectPlayers: number;
     };
 }
+export interface Hooks {
+    waitFor?: Promise<any> | Promise<any>[];
+    onReady?: () => Promise<void> | void;
+}
 export interface ServerRuntimeOptions {
     mode: FrameworkMode;
     features: FrameworkFeatures;
@@ -325,6 +355,7 @@ export interface ServerRuntimeOptions {
     resourceGrants?: ResourceGrants;
     /** Development mode configuration (disabled in production) */
     devMode?: DevModeConfig;
+    onDependency?: Hooks;
 }
 export type RuntimeContext = ServerRuntimeOptions;
 export declare function setRuntimeContext(ctx: RuntimeContext): void;
@@ -399,6 +430,8 @@ export interface ServerInitOptions {
     resourceGrants?: ResourceGrants;
     /** Development mode configuration (disabled in production) */
     devMode?: DevModeConfig;
+    /** If you want to wait for a dependency promise, or when ready do something (By default, the core server will emit a "ready" when it is ready to all resources.)  */
+    onDependency?: Hooks;
 }
 export declare function resolveRuntimeOptions(options: ServerInitOptions): ServerRuntimeOptions;
 export declare function validateRuntimeOptions(options: ServerRuntimeOptions): void;

package/dist/runtime/server/runtime.js

@@ -118,6 +118,7 @@ function createDefaultFeatures(mode) {
             export: false,
             scope,
             required: false,
+            recoveryOnRestart: true,
         },
     };
 }

package/dist/runtime/server/services/core/session-recovery.service.d.ts

@@ -0,0 +1,39 @@
+import { IPlayerServer } from '../../../../adapters/contracts/IPlayerServer';
+import { PlayerDirectoryPort } from '../ports/player-directory.port';
+import { PlayerSessionLifecyclePort } from '../ports/player-session-lifecycle.port';
+/**
+ * Service responsible for recovering player sessions after resource restarts.
+ *
+ * @remarks
+ * When a resource restarts (e.g., during development hot-reload), player sessions
+ * are lost because the PlayerService map is cleared. However, players remain connected
+ * to FiveM. This service detects these orphaned players and recreates their sessions.
+ *
+ * **Recovery Flow:**
+ * 1. Query FiveM for all connected player sources via `getPlayers()`
+ * 2. For each connected player, check if a session exists in PlayerService
+ * 3. If no session exists, create one with basic identifiers (license, steam, discord)
+ * 4. Emit `internal:playerSessionRecovered` event for each recovered session
+ *
+ * **Limitations:**
+ * - Only basic session data is recovered (clientID, identifiers)
+ * - `accountID` is NOT recovered - players must re-authenticate
+ * - Session metadata and states are NOT recovered
+ */
+export declare class SessionRecoveryService {
+    private readonly playerServer;
+    private readonly playerDirectory;
+    private readonly playerSessionLifecycle;
+    constructor(playerServer: IPlayerServer, playerDirectory: PlayerDirectoryPort, playerSessionLifecycle: PlayerSessionLifecyclePort);
+    /**
+     * Scans for connected players and recovers sessions for any without an active session.
+     *
+     * @returns Object containing recovery statistics
+     */
+    recoverSessions(): {
+        total: number;
+        recovered: number;
+        existing: number;
+    };
+    private recoverPlayerSession;
+}

package/dist/runtime/server/services/core/session-recovery.service.js

@@ -0,0 +1,108 @@
+"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.SessionRecoveryService = void 0;
+const tsyringe_1 = require("tsyringe");
+const IPlayerServer_1 = require("../../../../adapters/contracts/IPlayerServer");
+const logger_1 = require("../../../../kernel/shared/logger");
+const internal_event_bus_1 = require("../../bus/internal-event.bus");
+const player_directory_port_1 = require("../ports/player-directory.port");
+const player_session_lifecycle_port_1 = require("../ports/player-session-lifecycle.port");
+/**
+ * Service responsible for recovering player sessions after resource restarts.
+ *
+ * @remarks
+ * When a resource restarts (e.g., during development hot-reload), player sessions
+ * are lost because the PlayerService map is cleared. However, players remain connected
+ * to FiveM. This service detects these orphaned players and recreates their sessions.
+ *
+ * **Recovery Flow:**
+ * 1. Query FiveM for all connected player sources via `getPlayers()`
+ * 2. For each connected player, check if a session exists in PlayerService
+ * 3. If no session exists, create one with basic identifiers (license, steam, discord)
+ * 4. Emit `internal:playerSessionRecovered` event for each recovered session
+ *
+ * **Limitations:**
+ * - Only basic session data is recovered (clientID, identifiers)
+ * - `accountID` is NOT recovered - players must re-authenticate
+ * - Session metadata and states are NOT recovered
+ */
+let SessionRecoveryService = class SessionRecoveryService {
+    constructor(playerServer, playerDirectory, playerSessionLifecycle) {
+        this.playerServer = playerServer;
+        this.playerDirectory = playerDirectory;
+        this.playerSessionLifecycle = playerSessionLifecycle;
+    }
+    /**
+     * Scans for connected players and recovers sessions for any without an active session.
+     *
+     * @returns Object containing recovery statistics
+     */
+    recoverSessions() {
+        const connectedPlayers = this.playerServer.getConnectedPlayers();
+        const stats = { total: connectedPlayers.length, recovered: 0, existing: 0 };
+        if (connectedPlayers.length === 0) {
+            logger_1.loggers.session.debug('[SessionRecovery] No connected players found');
+            return stats;
+        }
+        logger_1.loggers.session.info(`[SessionRecovery] Found ${connectedPlayers.length} connected player(s), checking sessions...`);
+        for (const playerSrc of connectedPlayers) {
+            const clientId = Number(playerSrc);
+            if (Number.isNaN(clientId) || clientId <= 0) {
+                logger_1.loggers.session.warn(`[SessionRecovery] Invalid player source: ${playerSrc}`);
+                continue;
+            }
+            const existingPlayer = this.playerDirectory.getByClient(clientId);
+            if (existingPlayer) {
+                stats.existing++;
+                continue;
+            }
+            this.recoverPlayerSession(clientId);
+            stats.recovered++;
+        }
+        if (stats.recovered > 0) {
+            logger_1.loggers.session.info(`[SessionRecovery] Recovery complete: ${stats.recovered} recovered, ${stats.existing} already existed`);
+        }
+        else {
+            logger_1.loggers.session.debug(`[SessionRecovery] All ${stats.existing} sessions already exist`);
+        }
+        return stats;
+    }
+    recoverPlayerSession(clientId) {
+        const clientIdStr = clientId.toString();
+        const license = this.playerServer.getIdentifier(clientIdStr, 'license');
+        const steam = this.playerServer.getIdentifier(clientIdStr, 'steam');
+        const discord = this.playerServer.getIdentifier(clientIdStr, 'discord');
+        const playerName = this.playerServer.getName(clientIdStr);
+        const player = this.playerSessionLifecycle.bind(clientId, {
+            license,
+            steam,
+            discord,
+        });
+        logger_1.loggers.session.info(`[SessionRecovery] Recovered session for player`, {
+            clientId,
+            name: playerName,
+            license: license ? `${license.substring(0, 20)}...` : 'none',
+        });
+        (0, internal_event_bus_1.emitFrameworkEvent)('internal:playerSessionRecovered', {
+            clientId,
+            player,
+            license,
+        });
+    }
+};
+exports.SessionRecoveryService = SessionRecoveryService;
+exports.SessionRecoveryService = SessionRecoveryService = __decorate([
+    (0, tsyringe_1.injectable)(),
+    __metadata("design:paramtypes", [IPlayerServer_1.IPlayerServer,
+        player_directory_port_1.PlayerDirectoryPort,
+        player_session_lifecycle_port_1.PlayerSessionLifecyclePort])
+], SessionRecoveryService);

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

@@ -2,6 +2,7 @@ export * from '../database';
 export * from './appearance.service';
 export { ChatService } from './chat.service';
 export { ConfigService } from './config.service';
+export { SessionRecoveryService } from './core/session-recovery.service';
 export { type HttpOptions, HttpService } from './http/http.service';
 export * from './parallel';
 export { PlayerPersistenceService } from './persistence.service';

package/dist/runtime/server/services/index.js

@@ -15,13 +15,15 @@ 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 });
-exports.RateLimiterService = exports.PlayerPersistenceService = exports.HttpService = exports.ConfigService = exports.ChatService = void 0;
+exports.RateLimiterService = exports.PlayerPersistenceService = exports.HttpService = exports.SessionRecoveryService = exports.ConfigService = exports.ChatService = void 0;
 __exportStar(require("../database"), exports);
 __exportStar(require("./appearance.service"), exports);
 var chat_service_1 = require("./chat.service");
 Object.defineProperty(exports, "ChatService", { enumerable: true, get: function () { return chat_service_1.ChatService; } });
 var config_service_1 = require("./config.service");
 Object.defineProperty(exports, "ConfigService", { enumerable: true, get: function () { return config_service_1.ConfigService; } });
+var session_recovery_service_1 = require("./core/session-recovery.service");
+Object.defineProperty(exports, "SessionRecoveryService", { enumerable: true, get: function () { return session_recovery_service_1.SessionRecoveryService; } });
 var http_service_1 = require("./http/http.service");
 Object.defineProperty(exports, "HttpService", { enumerable: true, get: function () { return http_service_1.HttpService; } });
 __exportStar(require("./parallel"), exports);