@open-core/framework 1.0.8 → 1.0.10

package/README.md

@@ -141,6 +141,44 @@ export class ExampleNetController {
 - `@Throttle(limit, windowMs)`
 - `@RequiresState({ missing: [...] })`
 
+### Exports
+
+`@Export()` defines a public resource API. Adapters may expose both direct/local access through `getResource()` and an optional explicit async helper layer through `getRemoteResource()` / `waitForRemoteResource()`.
+
+```ts
+import { Controller, Export } from '@open-core/framework/server'
+import { IExports } from '@open-core/framework/contracts/server'
+
+@Controller()
+export class DatabaseController {
+  @Export('pingDatabase')
+  async pingDatabase() {
+    return { success: true }
+  }
+}
+
+interface DatabaseExports {
+  pingDatabase(): Promise<{ success: boolean }>
+}
+
+class ExampleConsumer {
+  constructor(private readonly exportsService: IExports) {}
+
+  async ping() {
+    const database = await this.exportsService.waitForRemoteResource<DatabaseExports>('database', {
+      exportName: 'pingDatabase',
+    })
+
+    return database.pingDatabase()
+  }
+}
+```
+
+Guidance:
+
+- `getResource()` is for local/synchronous resolution used by framework internals.
+- `waitForRemoteResource()` / `getRemoteResource()` are optional adapter utilities for explicit async resource-to-resource calls.
+
 ### Library events
 
 Use library wrappers to emit domain events and `@OnLibraryEvent()` to observe them.

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

@@ -1,4 +1,42 @@
 export declare abstract class IExports {
+    /**
+     * Registers a local export handler for the current resource.
+     *
+     * @remarks
+     * This is called by the framework during metadata processing when it discovers
+     * methods decorated with `@Export()`.
+     */
     abstract register(exportName: string, handler: (...args: unknown[]) => unknown): void;
+    /**
+     * Resolves exports for a resource using the adapter's direct/local mechanism.
+     *
+     * @remarks
+     * Framework internals rely on this method remaining synchronous and side-effect free.
+     * Adapters should return `undefined` when the resource is not directly resolvable.
+     */
     abstract getResource<T = unknown>(resourceName: string): T | undefined;
+    /**
+     * Returns an async proxy for resource exports when the adapter provides a remote helper layer.
+     *
+     * @remarks
+     * This is optional and should not change the semantics of `getResource()`.
+     * Consumers should treat methods on the returned proxy as async.
+     */
+    getRemoteResource<T = unknown>(_resourceName: string): T;
+    /**
+     * Calls a single exported method through the adapter's optional remote helper layer.
+     */
+    callRemoteExport<TResult = unknown>(_resourceName: string, _exportName: string, ..._args: unknown[]): Promise<TResult>;
+    /**
+     * Waits until a resource exposes exports compatible with the adapter's remote helper layer.
+     *
+     * @param _options.exportName Optional export name that must be present before resolving.
+     * @param _options.timeoutMs Maximum time to wait before failing.
+     * @param _options.intervalMs Polling interval used by adapters that implement polling.
+     */
+    waitForRemoteResource<T = unknown>(_resourceName: string, _options?: {
+        exportName?: string;
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<T>;
 }

package/dist/adapters/contracts/IExports.js

@@ -1,2 +1,28 @@
 export class IExports {
+    /**
+     * Returns an async proxy for resource exports when the adapter provides a remote helper layer.
+     *
+     * @remarks
+     * This is optional and should not change the semantics of `getResource()`.
+     * Consumers should treat methods on the returned proxy as async.
+     */
+    getRemoteResource(_resourceName) {
+        throw new Error('[OpenCore] Remote exports are not supported by the active adapter.');
+    }
+    /**
+     * Calls a single exported method through the adapter's optional remote helper layer.
+     */
+    callRemoteExport(_resourceName, _exportName, ..._args) {
+        return Promise.reject(new Error('[OpenCore] Remote exports are not supported by the active adapter.'));
+    }
+    /**
+     * Waits until a resource exposes exports compatible with the adapter's remote helper layer.
+     *
+     * @param _options.exportName Optional export name that must be present before resolving.
+     * @param _options.timeoutMs Maximum time to wait before failing.
+     * @param _options.intervalMs Polling interval used by adapters that implement polling.
+     */
+    waitForRemoteResource(_resourceName, _options) {
+        return Promise.reject(new Error('[OpenCore] Remote exports are not supported by the active adapter.'));
+    }
 }

package/dist/adapters/node/node-exports.d.ts

@@ -7,6 +7,13 @@ export declare class NodeExports implements IExports {
     private exports;
     register(exportName: string, handler: (...args: any[]) => any): void;
     getResource(resourceName: string): any;
+    getRemoteResource<T = unknown>(_resourceName: string): T;
+    callRemoteExport<TResult = unknown>(_resourceName: string, _exportName: string, ..._args: unknown[]): Promise<TResult>;
+    waitForRemoteResource<T = unknown>(_resourceName: string, _options?: {
+        exportName?: string;
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<T>;
     /**
      * Get all registered exports as an object
      */

package/dist/adapters/node/node-exports.js

@@ -23,6 +23,15 @@ let NodeExports = class NodeExports {
         throw new Error(`Cross-resource exports not supported in Node.js runtime. ` +
             `Attempted to access resource: ${resourceName}`);
     }
+    getRemoteResource(_resourceName) {
+        throw new Error('[OpenCore] Remote exports are not supported in Node.js runtime.');
+    }
+    callRemoteExport(_resourceName, _exportName, ..._args) {
+        return Promise.reject(new Error('[OpenCore] Remote exports are not supported in Node.js runtime.'));
+    }
+    waitForRemoteResource(_resourceName, _options) {
+        return Promise.reject(new Error('[OpenCore] Remote exports are not supported in Node.js runtime.'));
+    }
     /**
      * Get all registered exports as an object
      */

package/dist/runtime/server/bootstrap.js

@@ -278,13 +278,32 @@ async function tryImportAutoLoad() {
         await import('./.opencore/autoload.server.controllers');
     }
     catch (err) {
-        if (err instanceof Error && err.message.includes('Cannot find module')) {
+        if (isAutoloadModuleNotFound(err)) {
             loggers.bootstrap.warn(`[Bootstrap] No server controllers autoload file found, skipping.`);
             return;
         }
+        const message = err instanceof Error ? err.message : String(err);
+        loggers.bootstrap.error(`[Bootstrap] Failed to import server controllers autoload file.`, {
+            error: message,
+        });
         throw err;
     }
 }
+function isAutoloadModuleNotFound(err) {
+    if (!err || typeof err !== 'object') {
+        return false;
+    }
+    const error = err;
+    const message = typeof error.message === 'string' ? error.message : '';
+    const requireStack = Array.isArray(error.requireStack) ? error.requireStack : [];
+    if (error.code !== 'MODULE_NOT_FOUND' && !message.includes('Cannot find module')) {
+        return false;
+    }
+    if (message.includes('autoload.server.controllers')) {
+        return true;
+    }
+    return requireStack.some((entry) => entry.includes('autoload.server.controllers'));
+}
 /**
  * Runs session recovery to restore sessions for players already connected.
  *

package/dist/runtime/server/controllers/player-export.controller.d.ts

@@ -23,6 +23,8 @@ export declare class PlayerExportController implements InternalPlayerExports {
     isPlayerOnline(accountId: string): boolean;
     getPlayerMeta(clientID: number, key: string): Promise<any>;
     setPlayerMeta(clientID: number, key: string, value: any): void;
+    linkPlayerAccount(clientID: number, accountID: string): void;
+    unlinkPlayerAccount(clientID: number): void;
     getPlayerStates(clientID: number): string[];
     hasPlayerState(clientID: number, state: string): boolean;
     addPlayerState(clientID: number, state: string): void;

package/dist/runtime/server/controllers/player-export.controller.js

@@ -11,6 +11,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { inject } from 'tsyringe';
+import { loggers } from '../../../kernel/logger';
 import { Controller } from '../decorators/controller';
 import { Export } from '../decorators/export';
 import { serializeServerPlayerData } from '../adapter/serialization';
@@ -67,6 +68,27 @@ let PlayerExportController = class PlayerExportController {
     setPlayerMeta(clientID, key, value) {
         this.playerService.setMeta(clientID, key, value);
     }
+    linkPlayerAccount(clientID, accountID) {
+        const player = this.playerService.getByClient(clientID);
+        if (!player)
+            return;
+        player.linkAccount(accountID);
+        loggers.session.debug('Remote player account linked in CORE', {
+            clientID,
+            accountID,
+        });
+    }
+    unlinkPlayerAccount(clientID) {
+        const player = this.playerService.getByClient(clientID);
+        if (!player)
+            return;
+        const previousAccountID = player.accountID;
+        player.unlinkAccount();
+        loggers.session.debug('Remote player account unlinked in CORE', {
+            clientID,
+            accountID: previousAccountID,
+        });
+    }
     // ═══════════════════════════════════════════════════════════════
     // State Management
     // ═══════════════════════════════════════════════════════════════
@@ -141,6 +163,18 @@ __decorate([
     __metadata("design:paramtypes", [Number, String, Object]),
     __metadata("design:returntype", void 0)
 ], PlayerExportController.prototype, "setPlayerMeta", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number, String]),
+    __metadata("design:returntype", void 0)
+], PlayerExportController.prototype, "linkPlayerAccount", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number]),
+    __metadata("design:returntype", void 0)
+], PlayerExportController.prototype, "unlinkPlayerAccount", null);
 __decorate([
     Export(),
     __metadata("design:type", Function),

package/dist/runtime/server/implementations/remote/player.remote.d.ts

@@ -35,6 +35,10 @@ export declare class RemotePlayerImplementation extends Players {
      */
     private get core();
     private createPlayerFromData;
+    /**
+     * Proxies remote session mutations to CORE so security-critical data remains authoritative.
+     */
+    private attachAuthoritativeMutators;
     /**
      * Returns a Player instance with real session data from CORE.
      */

package/dist/runtime/server/implementations/remote/player.remote.js

@@ -77,7 +77,73 @@ let RemotePlayerImplementation = class RemotePlayerImplementation extends Player
         return coreExports;
     }
     createPlayerFromData(data) {
-        return createRemoteServerPlayer(data, this.playerAdapters);
+        const player = createRemoteServerPlayer(data, this.playerAdapters);
+        this.attachAuthoritativeMutators(player);
+        return player;
+    }
+    /**
+     * Proxies remote session mutations to CORE so security-critical data remains authoritative.
+     */
+    attachAuthoritativeMutators(player) {
+        const core = this.core;
+        const originalSetMeta = player.setMeta.bind(player);
+        const originalLinkAccount = player.linkAccount.bind(player);
+        const originalUnlinkAccount = player.unlinkAccount.bind(player);
+        const originalAddState = player.addState.bind(player);
+        const originalRemoveState = player.removeState.bind(player);
+        const originalToggleState = player.toggleState.bind(player);
+        player.setMeta = (key, value) => {
+            core.setPlayerMeta(player.clientID, key, value);
+            originalSetMeta(key, value);
+            loggers.session.debug('Remote player meta delegated to CORE', {
+                clientID: player.clientID,
+                key,
+            });
+        };
+        player.linkAccount = (accountID) => {
+            core.linkPlayerAccount(player.clientID, accountID.toString());
+            originalLinkAccount(accountID);
+            loggers.session.debug('Remote player linkAccount delegated to CORE', {
+                clientID: player.clientID,
+                accountID: accountID.toString(),
+            });
+        };
+        player.unlinkAccount = () => {
+            const previousAccountID = player.accountID;
+            core.unlinkPlayerAccount(player.clientID);
+            originalUnlinkAccount();
+            loggers.session.debug('Remote player unlinkAccount delegated to CORE', {
+                clientID: player.clientID,
+                accountID: previousAccountID,
+            });
+        };
+        player.addState = (state) => {
+            core.addPlayerState(player.clientID, state);
+            originalAddState(state);
+            loggers.session.debug('Remote player state added in CORE', {
+                clientID: player.clientID,
+                state,
+            });
+        };
+        player.removeState = (state) => {
+            core.removePlayerState(player.clientID, state);
+            originalRemoveState(state);
+            loggers.session.debug('Remote player state removed in CORE', {
+                clientID: player.clientID,
+                state,
+            });
+        };
+        player.toggleState = (state, force) => {
+            const next = force ?? !player.hasState(state);
+            if (next) {
+                player.addState(state);
+            }
+            else {
+                player.removeState(state);
+            }
+            originalToggleState(state, next);
+            return next;
+        };
     }
     /**
      * Returns a Player instance with real session data from CORE.

package/dist/runtime/server/types/core-exports.types.d.ts

@@ -225,6 +225,19 @@ export interface InternalPlayerExports {
      * @param value - Value to store
      */
     setPlayerMeta(clientID: number, key: string, value: unknown): void;
+    /**
+     * Links a persistent account to the authoritative CORE player session.
+     *
+     * @param clientID - FiveM client/server ID
+     * @param accountID - Persistent account identifier
+     */
+    linkPlayerAccount(clientID: number, accountID: string): void;
+    /**
+     * Removes any linked account from the authoritative CORE player session.
+     *
+     * @param clientID - FiveM client/server ID
+     */
+    unlinkPlayerAccount(clientID: number): void;
     /**
      * Gets complete serialized player data.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-core/framework",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "Secure, event-driven TypeScript Framework & Runtime engine for CitizenFX (Cfx).",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",