@open-core/framework 0.2.9 → 0.3.0

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

@@ -11,7 +11,7 @@ export type FrameworkMode = 'CORE' | 'RESOURCE' | 'STANDALONE';
  *
  * - `'local'`: Feature implemented locally in current resource
  *   - Used in CORE/STANDALONE for all features
- *   - Used in RESOURCE for: netEvents, fiveMEvents, exports, http, chat, database
+ *   - Used in RESOURCE for: netEvents, fiveMEvents, exports, http, chat
  *   - Triggers local service implementations
  *
  * @example
@@ -25,239 +25,17 @@ export type FrameworkMode = 'CORE' | 'RESOURCE' | 'STANDALONE';
  */
 export type FeatureProvider = 'core' | 'local';
 export type FeatureScope = 'core' | 'resource' | 'standalone';
-export type FeatureName = 'players' | 'netEvents' | 'fiveMEvents' | 'commands' | 'exports' | 'http' | 'chat' | 'database' | 'principal' | 'auth' | 'sessionLifecycle';
-/**
- * Base feature configuration (all features support this).
- */
-export interface BaseFeatureConfig {
-    /**
-     * Enable or disable this feature.
-     *
-     * @defaultValue Varies by feature and mode (see specific feature docs)
-     */
-    enabled?: boolean;
-}
-/**
- * Feature configuration with configurable provider.
- *
- * @remarks
- * Only applies to: `players`, `commands`, `principal`, `auth`
- *
- * For these features, you can choose:
- * - `'core'`: Use CORE's implementation (RESOURCE mode)
- * - `'local'`: Use local implementation (STANDALONE mode)
- *
- * **Defaults by mode:**
- * - CORE: `'core'`
- * - RESOURCE: `'core'` (delegates to CORE)
- * - STANDALONE: `'local'`
- */
-export interface ProviderFeatureConfig extends BaseFeatureConfig {
-    /**
-     * Provider source for this feature.
-     *
-     * @remarks
-     * - RESOURCE mode: Use `'core'` to delegate to CORE (default)
-     * - STANDALONE mode: Must use `'local'` (default)
-     */
-    provider?: FeatureProvider;
-}
-/**
- * Feature configuration with export option (CORE mode only).
- *
- * @remarks
- * Only applies to: `players`, `principal`, `chat` in CORE mode
- *
- * When `export: true`, the feature exposes FiveM exports for RESOURCE mode access.
- */
-export interface ExportableFeatureConfig extends BaseFeatureConfig {
-    /**
-     * Whether to expose this feature via FiveM exports.
-     *
-     * @remarks
-     * - Only valid in CORE mode
-     * - Requires `exports` feature to be enabled
-     * - Used by RESOURCE mode to access CORE functionality
-     *
-     * @defaultValue false
-     */
-    export?: boolean;
-}
+export type FeatureName = 'players' | 'netEvents' | 'fiveMEvents' | 'commands' | 'exports' | 'chat' | 'principal' | 'sessionLifecycle';
 /**
  * User-facing feature configuration.
  *
  * @remarks
- * This is what users configure in `Server.init({ features: {...} })`.
- * Internal fields like `scope` and `required` are auto-managed by the framework.
+ * Most features are enabled by default and providers are auto-inferred.
+ * Use this config only if you need to explicitly disable a feature.
  */
 export interface UserFeatureConfig {
-    /**
-     * Player management and directory.
-     *
-     * @remarks
-     * **Dependencies**: None
-     * **Provider**: Configurable
-     * - CORE/STANDALONE: Local player management
-     * - RESOURCE: Delegates to CORE
-     *
-     * **Export** (CORE only): When true, exposes player APIs to RESOURCE mode
-     *
-     * @defaultValue
-     * - enabled: true
-     * - provider: 'core' (RESOURCE), 'core' (CORE), 'local' (STANDALONE)
-     * - export: false
-     */
-    players?: ProviderFeatureConfig & ExportableFeatureConfig;
-    /**
-     * Command registration and execution.
-     *
-     * @remarks
-     * **Dependencies**: Requires `players` to be enabled
-     * **Provider**: Configurable
-     * - CORE/STANDALONE: Local command execution
-     * - RESOURCE: Commands register with CORE for centralized security validation
-     *
-     * **Export** (CORE only): Always exported when enabled (for RESOURCE mode access)
-     *
-     * @defaultValue
-     * - enabled: false
-     * - provider: 'core' (RESOURCE), 'local' (CORE/STANDALONE)
-     * - export: true (CORE only, automatic)
-     */
-    commands?: ProviderFeatureConfig;
-    /**
-     * Principal (identity) provider for permissions.
-     *
-     * @remarks
-     * **Dependencies**: None
-     * **Provider**: Configurable
-     * - CORE: User-provided PrincipalProvider implementation
-     * - RESOURCE: Delegates to CORE
-     * - STANDALONE: User-provided PrincipalProvider implementation
-     *
-     * **Export** (CORE only): When true, exposes principal APIs to RESOURCE mode
-     *
-     * @defaultValue
-     * - enabled: false
-     * - provider: 'core' (RESOURCE), 'core' (CORE), 'local' (STANDALONE)
-     * - export: false
-     */
-    principal?: ProviderFeatureConfig & ExportableFeatureConfig;
-    /**
-     * Authentication provider for login/logout.
-     *
-     * @remarks
-     * **Dependencies**: None
-     * **Provider**: Configurable
-     * - CORE: User-provided AuthProvider implementation
-     * - RESOURCE: Delegates to CORE
-     * - STANDALONE: User-provided AuthProvider implementation
-     *
-     * @defaultValue
-     * - enabled: false
-     * - provider: 'core' (RESOURCE), 'core' (CORE), 'local' (STANDALONE)
-     */
-    auth?: ProviderFeatureConfig;
-    /**
-     * Network events (`onNet` decorator support).
-     *
-     * @remarks
-     * **Dependencies**: Requires `players` to be enabled
-     * **Provider**: Auto-determined (not configurable)
-     * - Always `'local'` (events are handled locally in each resource)
-     *
-     * @defaultValue enabled: true
-     */
-    netEvents?: BaseFeatureConfig;
-    /**
-     * FiveM lifecycle events (`onServer`, `onClient`, etc.).
-     *
-     * @remarks
-     * **Dependencies**: None
-     * **Provider**: Auto-determined (not configurable)
-     * - Always `'local'`
-     * - Disabled in RESOURCE mode (only CORE/STANDALONE need lifecycle management)
-     *
-     * @defaultValue
-     * - enabled: true (CORE/STANDALONE), false (RESOURCE)
-     */
-    fiveMEvents?: BaseFeatureConfig;
-    /**
-     * FiveM exports support (`@Export` decorator).
-     *
-     * @remarks
-     * **Dependencies**: None
-     * **Provider**: Auto-determined (not configurable)
-     * - Always `'local'`
-     *
-     * @defaultValue enabled: false
-     */
-    exports?: BaseFeatureConfig;
-    /**
-     * HTTP server and endpoints.
-     *
-     * @remarks
-     * **Dependencies**: None
-     * **Provider**: Auto-determined (not configurable)
-     * - Always `'local'`
-     *
-     * @defaultValue enabled: false
-     */
-    http?: BaseFeatureConfig;
-    /**
-     * Chat message handling.
-     *
-     * @remarks
-     * **Dependencies**: Requires `players` to be enabled
-     * **Provider**: Auto-determined (not configurable)
-     * - Always `'local'`
-     *
-     * **Export** (CORE only): When true, exposes chat APIs to RESOURCE mode
-     *
-     * @defaultValue
-     * - enabled: false
-     * - export: false
-     */
-    chat?: BaseFeatureConfig & ExportableFeatureConfig;
-    /**
-     * Database access.
-     *
-     * @remarks
-     * **Dependencies**: None
-     * **Provider**: Auto-determined (not configurable)
-     * - Always `'local'`
-     *
-     * @defaultValue enabled: false
-     */
-    database?: BaseFeatureConfig;
-    /**
-     * Session lifecycle management (internal).
-     *
-     * @remarks
-     * **Dependencies**: None
-     * **Provider**: Auto-determined (not configurable)
-     * - Disabled in RESOURCE mode (CORE manages sessions)
-     *
-     * @defaultValue
-     * - enabled: true (CORE/STANDALONE), false (RESOURCE)
-     * - recoveryOnRestart: true
-     */
-    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;
-    };
+    /** Disable specific features if needed */
+    disabled?: FeatureName[];
 }
 /**
  * Internal feature contract with all fields resolved.
@@ -313,34 +91,42 @@ export interface FeatureContract {
     recoveryOnRestart?: boolean;
 }
 export type FrameworkFeatures = Record<FeatureName, FeatureContract>;
-export interface ResourceGrants {
-    database?: boolean;
-    principal?: boolean;
-    auth?: boolean;
-}
 export interface DevModeConfig {
-    /** Enable dev mode */
+    /**
+     * Master switch for development mode.
+     * If false, no dev tools will be loaded.
+     */
     enabled: boolean;
-    /** Hot reload configuration */
-    hotReload?: {
-        enabled: boolean;
-        port: number;
-        allowedResources?: string[];
-    };
-    /** CLI bridge configuration */
+    /**
+     * CLI bridge configuration for telemetry and logs.
+     * The bridge allows the OpenCore CLI to stream logs and inspect the framework state.
+     */
     bridge?: {
+        /** WebSocket URL of the bridge */
         url: string;
+        /** Whether to connect automatically on startup */
         autoConnect: boolean;
     };
-    /** Event interceptor configuration */
+    /**
+     * Event interceptor configuration for debugging.
+     * Captures and records incoming/outgoing network events and commands.
+     */
     interceptor?: {
+        /** Enable event interception */
         enabled: boolean;
+        /** Whether to record a history of events in memory */
         recordHistory: boolean;
+        /** Maximum number of events to keep in the history buffer */
         maxHistorySize: number;
     };
-    /** Player simulator configuration */
+    /**
+     * Player simulator configuration.
+     * Allows creating virtual players for testing logic without game clients.
+     */
     simulator?: {
+        /** Enable player simulation features */
         enabled: boolean;
+        /** Number of virtual players to connect automatically on startup */
         autoConnectPlayers: number;
     };
 }
@@ -352,7 +138,6 @@ export interface ServerRuntimeOptions {
     mode: FrameworkMode;
     features: FrameworkFeatures;
     coreResourceName: string;
-    resourceGrants?: ResourceGrants;
     /** Development mode configuration (disabled in production) */
     devMode?: DevModeConfig;
     onDependency?: Hooks;
@@ -367,36 +152,10 @@ export declare function getFrameworkModeScope(mode: FrameworkMode): FeatureScope
  * @remarks
  * Defines the runtime mode and feature configuration for OpenCore.
  *
- * @example Minimal CORE Mode
- * ```typescript
- * Server.init({
- *   mode: 'CORE',
- *   features: {
- *     commands: { enabled: true },
- *     principal: { enabled: true },
- *   }
- * })
- * ```
- *
- * @example Minimal RESOURCE Mode
+ * @example Minimal Mode
  * ```typescript
  * Server.init({
- *   mode: 'RESOURCE',
- *   coreResourceName: 'my-core',
- *   features: {
- *     commands: { enabled: true },  // Auto-uses 'core' provider
- *   }
- * })
- * ```
- *
- * @example STANDALONE Mode
- * ```typescript
- * Server.init({
- *   mode: 'STANDALONE',
- *   features: {
- *     players: { enabled: true },
- *     commands: { enabled: true },
- *   }
+ *   mode: 'CORE'
  * })
  * ```
  */
@@ -407,13 +166,7 @@ export interface ServerInitOptions {
      * Feature configuration.
      *
      * @remarks
-     * All features have sensible defaults. You only need to configure:
-     * - `enabled: true` to enable a feature
-     * - `provider` (optional, only for players/commands/principal/auth if you want non-default)
-     * - `export: true` (optional, CORE mode only, for players/principal/chat)
-     *
-     * **Most features auto-determine their provider based on mode.**
-     * Only configure `provider` if you need to override defaults.
+     * Most features are enabled by default. Use this only to disable specific ones.
      */
     features?: UserFeatureConfig;
     /**
@@ -426,8 +179,6 @@ export interface ServerInitOptions {
      * @defaultValue 'core'
      */
     coreResourceName?: string;
-    /** Resource grants configuration (CORE mode only) */
-    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.)  */

package/dist/runtime/server/runtime.js

@@ -12,11 +12,8 @@ const FEATURE_NAMES = [
     'fiveMEvents',
     'commands',
     'exports',
-    'http',
     'chat',
-    'database',
     'principal',
-    'auth',
     'sessionLifecycle',
 ];
 const FEATURE_ALLOWED_SCOPES = {
@@ -25,11 +22,8 @@ const FEATURE_ALLOWED_SCOPES = {
     fiveMEvents: ['core', 'resource', 'standalone'],
     commands: ['core', 'resource', 'standalone'],
     exports: ['core', 'resource', 'standalone'],
-    http: ['core', 'resource', 'standalone'],
     chat: ['core', 'resource', 'standalone'],
-    database: ['core', 'resource', 'standalone'],
     principal: ['core', 'resource', 'standalone'],
-    auth: ['core', 'resource', 'standalone'],
     sessionLifecycle: ['core', 'standalone'],
 };
 let runtimeContext = null;
@@ -53,68 +47,63 @@ function createDefaultFeatures(mode) {
     const scope = getFrameworkModeScope(mode);
     // Provider logic:
     // - CORE/STANDALONE: All features use 'local' (run locally)
-    // - RESOURCE: Some features delegate to CORE ('core'), others run locally ('local')
-    const playersProvider = mode === 'RESOURCE' ? 'core' : 'local';
-    const commandsProvider = mode === 'RESOURCE' ? 'core' : 'local';
-    const principalProvider = mode === 'RESOURCE' ? 'core' : 'local';
-    const authProvider = mode === 'RESOURCE' ? 'core' : 'local';
-    // These always use 'local' regardless of mode
-    const netEventsProvider = 'local';
-    const fiveMEventsProvider = 'local';
-    const exportsProvider = 'local';
-    const httpProvider = 'local';
-    const chatProvider = 'local';
-    const databaseProvider = 'local';
-    const sessionLifecycleProvider = 'local';
-    const sessionLifecycleEnabled = mode !== 'RESOURCE';
-    // Features that should auto-export in CORE mode for RESOURCE access
-    const commandsExport = mode === 'CORE';
-    const playersExport = mode === 'CORE';
-    const principalExport = mode === 'CORE';
+    // - RESOURCE: Identity/Command features delegate to CORE ('core'), others run locally ('local')
+    const remoteProvider = mode === 'RESOURCE' ? 'core' : 'local';
+    const isResource = mode === 'RESOURCE';
+    const isCore = mode === 'CORE';
     return {
         players: {
             enabled: true,
-            provider: playersProvider,
-            export: playersExport,
+            provider: remoteProvider,
+            export: isCore,
             scope,
-            required: false,
+            required: true,
         },
         netEvents: {
             enabled: true,
-            provider: netEventsProvider,
+            provider: 'local',
             export: false,
             scope,
-            required: false,
+            required: true,
         },
         fiveMEvents: {
-            enabled: sessionLifecycleEnabled,
-            provider: fiveMEventsProvider,
+            enabled: true,
+            provider: 'local',
             export: false,
             scope,
             required: false,
         },
         commands: {
-            enabled: false,
-            provider: commandsProvider,
-            export: commandsExport,
+            enabled: true,
+            provider: remoteProvider,
+            export: isCore,
+            scope,
+            required: true,
+        },
+        exports: {
+            enabled: true,
+            provider: 'local',
+            export: false,
+            scope,
+            required: isCore,
+        },
+        chat: {
+            enabled: true,
+            provider: 'local',
+            export: isCore,
             scope,
             required: false,
         },
-        exports: { enabled: false, provider: exportsProvider, export: false, scope, required: false },
-        http: { enabled: false, provider: httpProvider, export: false, scope, required: false },
-        chat: { enabled: false, provider: chatProvider, export: false, scope, required: false },
-        database: { enabled: false, provider: databaseProvider, export: false, scope, required: false },
         principal: {
-            enabled: false,
-            provider: principalProvider,
-            export: principalExport,
+            enabled: true,
+            provider: remoteProvider,
+            export: isCore,
             scope,
             required: false,
         },
-        auth: { enabled: false, provider: authProvider, export: false, scope, required: false },
         sessionLifecycle: {
-            enabled: sessionLifecycleEnabled,
-            provider: sessionLifecycleProvider,
+            enabled: !isResource,
+            provider: 'local',
             export: false,
             scope,
             required: false,
@@ -123,26 +112,27 @@ function createDefaultFeatures(mode) {
     };
 }
 function resolveRuntimeOptions(options) {
-    var _a;
-    const defaults = createDefaultFeatures(options.mode);
-    const features = Object.assign({}, defaults);
-    if (options.features) {
-        for (const name of FEATURE_NAMES) {
-            const override = options.features[name];
-            if (!override)
-                continue;
-            features[name] = Object.assign(Object.assign({}, defaults[name]), override);
+    var _a, _b;
+    const features = createDefaultFeatures(options.mode);
+    if ((_a = options.features) === null || _a === void 0 ? void 0 : _a.disabled) {
+        for (const name of options.features.disabled) {
+            if (features[name]) {
+                features[name].enabled = false;
+            }
         }
     }
     return {
         mode: options.mode,
         features,
-        coreResourceName: (_a = options.coreResourceName) !== null && _a !== void 0 ? _a : 'core',
-        resourceGrants: options.resourceGrants,
+        coreResourceName: (_b = options.coreResourceName) !== null && _b !== void 0 ? _b : 'core',
         devMode: options.devMode,
+        onDependency: options.onDependency,
     };
 }
 function assertFeatureKeys(features) {
+    if (!features) {
+        throw new Error('[OpenCore] Runtime options are missing features configuration');
+    }
     const keys = Object.keys(features);
     for (const key of keys) {
         if (!FEATURE_NAMES.includes(key)) {
@@ -162,8 +152,7 @@ function validateRuntimeOptions(options) {
     const needsCoreExports = mode === 'RESOURCE' &&
         (features.players.provider === 'core' ||
             features.commands.provider === 'core' ||
-            features.principal.provider === 'core' ||
-            features.auth.provider === 'core');
+            features.principal.provider === 'core');
     // Validate coreResourceName exists if needed
     if (mode === 'RESOURCE') {
         const { coreResourceName } = options;
@@ -208,9 +197,6 @@ function validateRuntimeOptions(options) {
     if (features.principal.enabled && mode === 'RESOURCE' && features.principal.provider !== 'core') {
         throw new Error(`[OpenCore] Feature 'principal' must use provider 'core' in RESOURCE mode`);
     }
-    if (features.auth.enabled && mode === 'RESOURCE' && features.auth.provider !== 'core') {
-        throw new Error(`[OpenCore] Feature 'auth' must use provider 'core' in RESOURCE mode`);
-    }
     if (features.commands.enabled && mode === 'RESOURCE' && features.commands.provider !== 'core') {
         throw new Error(`[OpenCore] Feature 'commands' must use provider 'core' in RESOURCE mode`);
     }

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

@@ -1,6 +1,6 @@
 import { INetTransport } from '../../../adapters/contracts/INetTransport';
-import { IPedAppearanceServer } from '../../../adapters/contracts/IPedAppearanceServer';
-import { IPlayerServer } from '../../../adapters/contracts/IPlayerServer';
+import { IPedAppearanceServer } from '../../../adapters/contracts/server/IPedAppearanceServer';
+import { IPlayerServer } from '../../../adapters/contracts/server/IPlayerServer';
 import { AppearanceValidationResult, PlayerAppearance } from '../../../kernel/shared';
 /**
  * Server-side appearance management service.
@@ -18,15 +18,15 @@ import { AppearanceValidationResult, PlayerAppearance } from '../../../kernel/sh
  * **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.).
+ * You decide when and where to save it (persistent storage, 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)
+ *   // Save to your storage
+ *   await myStorage.saveAppearance(playerId, result.appearance)
  * }
  *
  * // Validate appearance without applying

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

@@ -15,8 +15,8 @@ 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");
+const IPedAppearanceServer_1 = require("../../../adapters/contracts/server/IPedAppearanceServer");
+const IPlayerServer_1 = require("../../../adapters/contracts/server/IPlayerServer");
 /**
  * Server-side appearance management service.
  *
@@ -33,15 +33,15 @@ const IPlayerServer_1 = require("../../../adapters/contracts/IPlayerServer");
  * **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.).
+ * You decide when and where to save it (persistent storage, 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)
+ *   // Save to your storage
+ *   await myStorage.saveAppearance(playerId, result.appearance)
  * }
  *
  * // Validate appearance without applying

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

@@ -1,5 +1,6 @@
-import { Server } from '../../..';
-import { RGB } from '../../../kernel/utils';
+import { INetTransport } from '../../../adapters/contracts/INetTransport';
+import { RGB } from '../../../kernel/utils/rgb';
+import { Server } from '..';
 import { PlayerDirectoryPort } from './ports/player-directory.port';
 /**
  * Service for sending chat messages to players.
@@ -9,7 +10,8 @@ import { PlayerDirectoryPort } from './ports/player-directory.port';
  */
 export declare class ChatService {
     private readonly playerDirectory;
-    constructor(playerDirectory: PlayerDirectoryPort);
+    private readonly netTransport;
+    constructor(playerDirectory: PlayerDirectoryPort, netTransport: INetTransport);
     /**
      * Broadcast a chat message to all connected players.
      *