@open-core/framework 0.1.0-alpha.1

package/dist/client/types/game-events.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * Game Events - Native GTA V internal events captured by FiveM
+ *
+ * Documentation: https://docs.fivem.net/docs/game-references/game-events/
+ *
+ * These are low-level events from the RAGE engine. The arguments are
+ * passed as arrays from the native layer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GameEventParsers = void 0;
+// ─────────────────────────────────────────────────────────────────────────────
+// Event Parsers - Convert raw args to typed objects
+// ─────────────────────────────────────────────────────────────────────────────
+exports.GameEventParsers = {
+    /**
+     * Parse CEventNetworkEntityDamage arguments
+     */
+    parseEntityDamage(args) {
+        return {
+            victim: args[0],
+            attacker: args[1],
+            arg2: args[2],
+            arg3: args[3],
+            arg4: args[4],
+            victimDied: args[5] === 1,
+            weaponHash: args[6],
+            arg7: args[7],
+            arg8: args[8],
+            arg9: args[9],
+        };
+    },
+    /**
+     * Parse CEventNetworkPlayerEnteredVehicle arguments
+     */
+    parsePlayerEnteredVehicle(args) {
+        return {
+            player: args[0],
+            vehicle: args[1],
+        };
+    },
+    /**
+     * Parse CEventNetworkPlayerLeftVehicle arguments
+     */
+    parsePlayerLeftVehicle(args) {
+        return {
+            player: args[0],
+            vehicle: args[1],
+        };
+    },
+    /**
+     * Parse CEventShockingSeenPedKilled arguments
+     */
+    parseSeenPedKilled(args) {
+        return {
+            witness: args[0],
+            victim: args[1],
+        };
+    },
+    /**
+     * Parse CEventNetworkVehicleUndrivable arguments
+     */
+    parseVehicleUndrivable(args) {
+        return {
+            vehicle: args[0],
+            attacker: args[1],
+            weaponHash: args[2],
+        };
+    },
+    /**
+     * Parse CEventGunShot arguments
+     */
+    parseGunShot(args) {
+        return {
+            shooter: args[0],
+            coords: {
+                x: args[1],
+                y: args[2],
+                z: args[3],
+            },
+        };
+    },
+};

package/dist/client/types/index.d.ts

@@ -0,0 +1 @@
+export * from './game-events';

package/dist/client/types/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./game-events"), exports);

package/dist/client/ui-bridge.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Type-safe NUI (Native UI) Bridge for client-server communication.
+ *
+ * Generic types allow for full type safety when sending/receiving messages.
+ * Define your event maps and pass them as type parameters.
+ *
+ * @example
+ * ```typescript
+ * interface ClientToUI {
+ *   'showMenu': { items: string[] }
+ *   'hideMenu': void
+ * }
+ *
+ * interface UIToClient {
+ *   'menuItemSelected': { index: number }
+ *   'menuClosed': void
+ * }
+ *
+ * const nui = new NuiBridge<ClientToUI, UIToClient>()
+ * nui.send('showMenu', { items: ['Option 1', 'Option 2'] })
+ * nui.on('menuItemSelected', async (data) => console.log(data.index))
+ * ```
+ */
+export declare class NuiBridge<TSend extends Record<string, any> = Record<string, any>, TReceive extends Record<string, any> = Record<string, any>> {
+    private _isVisible;
+    private _hasFocus;
+    private _hasCursor;
+    /**
+     * Whether the NUI frame is currently visible
+     */
+    get isVisible(): boolean;
+    /**
+     * Whether the NUI has input focus
+     */
+    get hasFocus(): boolean;
+    /**
+     * Whether the cursor is visible
+     */
+    get hasCursor(): boolean;
+    /**
+     * Send a message to the NUI (UI frame).
+     *
+     * @param action - The action/event name
+     * @param data - The data payload
+     */
+    send<K extends keyof TSend & string>(action: K, data: TSend[K]): void;
+    /**
+     * Send a raw message to the NUI without type checking.
+     *
+     * @param action - The action/event name
+     * @param data - The data payload
+     */
+    sendRaw(action: string, data: any): void;
+    /**
+     * Register a callback for NUI events from the UI.
+     *
+     * @param action - The action/event name to listen for
+     * @param handler - The callback handler
+     * @returns Cleanup function to unregister the callback
+     */
+    on<K extends keyof TReceive & string>(action: K, handler: (data: TReceive[K]) => void | Promise<void>): void;
+    /**
+     * Register a callback that expects a return value.
+     *
+     * @param action - The action/event name to listen for
+     * @param handler - The callback handler that returns data
+     */
+    onWithResponse<K extends keyof TReceive & string, R = any>(action: K, handler: (data: TReceive[K]) => R | Promise<R>): void;
+    /**
+     * Set NUI focus state.
+     *
+     * @param hasFocus - Whether the NUI should have input focus
+     * @param hasCursor - Whether to show the cursor (defaults to hasFocus value)
+     */
+    focus(hasFocus: boolean, hasCursor?: boolean): void;
+    /**
+     * Remove NUI focus (convenience method).
+     */
+    blur(): void;
+    /**
+     * Set NUI visibility state.
+     * Note: This only tracks state, you need to handle actual visibility in your UI.
+     *
+     * @param visible - Whether the NUI should be visible
+     */
+    setVisible(visible: boolean): void;
+    /**
+     * Show the NUI and optionally set focus.
+     *
+     * @param withFocus - Whether to also set focus
+     * @param withCursor - Whether to show cursor (defaults to withFocus)
+     */
+    show(withFocus?: boolean, withCursor?: boolean): void;
+    /**
+     * Hide the NUI and remove focus.
+     */
+    hide(): void;
+    /**
+     * Toggle NUI visibility.
+     *
+     * @param withFocus - Whether to set focus when showing
+     */
+    toggle(withFocus?: boolean): void;
+    /**
+     * Keep input focus but allow game input.
+     * Useful for HUDs that need to capture some keys but not all.
+     *
+     * @param keepInput - Whether to keep game input enabled
+     */
+    setKeepInput(keepInput: boolean): void;
+}
+/**
+ * Default untyped NUI instance for quick usage.
+ * For type-safe usage, create your own instance with proper generics.
+ */
+export declare const NUI: NuiBridge<Record<string, any>, Record<string, any>>;

package/dist/client/ui-bridge.js

@@ -0,0 +1,201 @@
+"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.NUI = exports.NuiBridge = void 0;
+const tsyringe_1 = require("tsyringe");
+const logger_1 = require("../shared/logger");
+const nuiLogger = logger_1.coreLogger.child('NUI', logger_1.LogDomain.CLIENT);
+/**
+ * Type-safe NUI (Native UI) Bridge for client-server communication.
+ *
+ * Generic types allow for full type safety when sending/receiving messages.
+ * Define your event maps and pass them as type parameters.
+ *
+ * @example
+ * ```typescript
+ * interface ClientToUI {
+ *   'showMenu': { items: string[] }
+ *   'hideMenu': void
+ * }
+ *
+ * interface UIToClient {
+ *   'menuItemSelected': { index: number }
+ *   'menuClosed': void
+ * }
+ *
+ * const nui = new NuiBridge<ClientToUI, UIToClient>()
+ * nui.send('showMenu', { items: ['Option 1', 'Option 2'] })
+ * nui.on('menuItemSelected', async (data) => console.log(data.index))
+ * ```
+ */
+let NuiBridge = class NuiBridge {
+    constructor() {
+        this._isVisible = false;
+        this._hasFocus = false;
+        this._hasCursor = false;
+    }
+    /**
+     * Whether the NUI frame is currently visible
+     */
+    get isVisible() {
+        return this._isVisible;
+    }
+    /**
+     * Whether the NUI has input focus
+     */
+    get hasFocus() {
+        return this._hasFocus;
+    }
+    /**
+     * Whether the cursor is visible
+     */
+    get hasCursor() {
+        return this._hasCursor;
+    }
+    /**
+     * Send a message to the NUI (UI frame).
+     *
+     * @param action - The action/event name
+     * @param data - The data payload
+     */
+    send(action, data) {
+        SendNuiMessage(JSON.stringify({ action, data }));
+        nuiLogger.debug(`Sent message: ${action}`);
+    }
+    /**
+     * Send a raw message to the NUI without type checking.
+     *
+     * @param action - The action/event name
+     * @param data - The data payload
+     */
+    sendRaw(action, data) {
+        SendNuiMessage(JSON.stringify({ action, data }));
+        nuiLogger.debug(`Sent raw message: ${action}`);
+    }
+    /**
+     * Register a callback for NUI events from the UI.
+     *
+     * @param action - The action/event name to listen for
+     * @param handler - The callback handler
+     * @returns Cleanup function to unregister the callback
+     */
+    on(action, handler) {
+        RegisterNuiCallbackType(action);
+        on(`__cfx_nui:${action}`, async (data, cb) => {
+            try {
+                await handler(data);
+                cb({ ok: true });
+            }
+            catch (error) {
+                nuiLogger.error(`NUI callback error`, { action }, error);
+                cb({ ok: false, error: String(error) });
+            }
+        });
+        nuiLogger.debug(`Registered callback: ${action}`);
+    }
+    /**
+     * Register a callback that expects a return value.
+     *
+     * @param action - The action/event name to listen for
+     * @param handler - The callback handler that returns data
+     */
+    onWithResponse(action, handler) {
+        RegisterNuiCallbackType(action);
+        on(`__cfx_nui:${action}`, async (data, cb) => {
+            try {
+                const result = await handler(data);
+                cb({ ok: true, data: result });
+            }
+            catch (error) {
+                nuiLogger.error(`NUI callback error`, { action }, error);
+                cb({ ok: false, error: String(error) });
+            }
+        });
+        nuiLogger.debug(`Registered callback with response: ${action}`);
+    }
+    /**
+     * Set NUI focus state.
+     *
+     * @param hasFocus - Whether the NUI should have input focus
+     * @param hasCursor - Whether to show the cursor (defaults to hasFocus value)
+     */
+    focus(hasFocus, hasCursor) {
+        this._hasFocus = hasFocus;
+        this._hasCursor = hasCursor !== null && hasCursor !== void 0 ? hasCursor : hasFocus;
+        SetNuiFocus(this._hasFocus, this._hasCursor);
+        nuiLogger.debug(`Focus set: focus=${this._hasFocus}, cursor=${this._hasCursor}`);
+    }
+    /**
+     * Remove NUI focus (convenience method).
+     */
+    blur() {
+        this.focus(false, false);
+    }
+    /**
+     * Set NUI visibility state.
+     * Note: This only tracks state, you need to handle actual visibility in your UI.
+     *
+     * @param visible - Whether the NUI should be visible
+     */
+    setVisible(visible) {
+        this._isVisible = visible;
+        this.send('setVisible', { visible });
+        nuiLogger.debug(`Visibility set: ${visible}`);
+    }
+    /**
+     * Show the NUI and optionally set focus.
+     *
+     * @param withFocus - Whether to also set focus
+     * @param withCursor - Whether to show cursor (defaults to withFocus)
+     */
+    show(withFocus = true, withCursor) {
+        this.setVisible(true);
+        if (withFocus) {
+            this.focus(true, withCursor);
+        }
+    }
+    /**
+     * Hide the NUI and remove focus.
+     */
+    hide() {
+        this.setVisible(false);
+        this.blur();
+    }
+    /**
+     * Toggle NUI visibility.
+     *
+     * @param withFocus - Whether to set focus when showing
+     */
+    toggle(withFocus = true) {
+        if (this._isVisible) {
+            this.hide();
+        }
+        else {
+            this.show(withFocus);
+        }
+    }
+    /**
+     * Keep input focus but allow game input.
+     * Useful for HUDs that need to capture some keys but not all.
+     *
+     * @param keepInput - Whether to keep game input enabled
+     */
+    setKeepInput(keepInput) {
+        SetNuiFocusKeepInput(keepInput);
+        nuiLogger.debug(`Keep input set: ${keepInput}`);
+    }
+};
+exports.NuiBridge = NuiBridge;
+exports.NuiBridge = NuiBridge = __decorate([
+    (0, tsyringe_1.injectable)()
+], NuiBridge);
+/**
+ * Default untyped NUI instance for quick usage.
+ * For type-safe usage, create your own instance with proper generics.
+ */
+exports.NUI = new NuiBridge();

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import 'reflect-metadata';
+export * as Utils from './utils';
+export * as Shared from './shared';
+export * as Server from './server';
+export * as Client from './client';

package/dist/index.js

@@ -0,0 +1,41 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Client = exports.Server = exports.Shared = exports.Utils = void 0;
+require("reflect-metadata");
+exports.Utils = __importStar(require("./utils"));
+exports.Shared = __importStar(require("./shared"));
+exports.Server = __importStar(require("./server"));
+exports.Client = __importStar(require("./client"));

package/dist/server/bootstrap.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Bootstraps the OpenCore Server Application Context.
+ *
+ * This is the primary entry point for the server-side framework. It orchestrates the
+ * initialization of the Dependency Injection (DI) container and establishes the
+ * bridge between the low-level FiveM runtime and the OpenCore architecture.
+ *
+ * **Initialization Lifecycle:**
+ * 1. **Infrastructure Registration:** Registers core infrastructure services (`PlayerService`, `CommandService`, `HttpService`) as Singletons in the IoC container.
+ * 2. **Reflection & Discovery:** Scans all decorated classes (Controllers, Services) to extract metadata defined by `@Command`, `@OnNet`, etc.
+ * 3. **Runtime Binding:** Binds the discovered metadata to actual FiveM natives (e.g., `RegisterCommand`, `onNet`, `exports`).
+ * 4. **Session Management:** Activates the player session tracking system.
+ *
+ * @returns A promise that resolves when the Core is fully initialized and ready to process events.
+ */
+export declare function initServer(): Promise<void>;

package/dist/server/bootstrap.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initServer = initServer;
+const container_1 = require("./container");
+const playerSession_loader_1 = require("./loaders/playerSession.loader");
+const templates_1 = require("./templates");
+const metadata_scanner_1 = require("../system/metadata.scanner");
+const processors_register_1 = require("./system/processors.register");
+const registers_1 = require("./services/registers");
+const logger_1 = require("../shared/logger");
+const auth_provider_contract_1 = require("./templates/auth/auth-provider.contract");
+const controller_1 = require("./decorators/controller");
+const check = () => {
+    if (!container_1.di.isRegistered(templates_1.PrincipalProviderContract)) {
+        const errorMsg = 'No Principal Provider configured. ' +
+            "Please call 'Server.setPrincipalProvider(YourProvider)' before init(). This is required for authentication and authorization.";
+        logger_1.loggers.bootstrap.fatal(errorMsg);
+        throw new Error(`[OpenCore] CRITICAL: ${errorMsg}`);
+    }
+    if (!container_1.di.isRegistered(auth_provider_contract_1.AuthProviderContract)) {
+        const errorMsg = 'No Authentication Provider configured. ' +
+            "Please call 'Server.setAuthProvider(YourProvider)' before init(). This is required for authentication and authorization.";
+        logger_1.loggers.bootstrap.fatal(errorMsg);
+        throw new Error(`[OpenCore] CRITICAL: ${errorMsg}`);
+    }
+};
+/**
+ * Bootstraps the OpenCore Server Application Context.
+ *
+ * This is the primary entry point for the server-side framework. It orchestrates the
+ * initialization of the Dependency Injection (DI) container and establishes the
+ * bridge between the low-level FiveM runtime and the OpenCore architecture.
+ *
+ * **Initialization Lifecycle:**
+ * 1. **Infrastructure Registration:** Registers core infrastructure services (`PlayerService`, `CommandService`, `HttpService`) as Singletons in the IoC container.
+ * 2. **Reflection & Discovery:** Scans all decorated classes (Controllers, Services) to extract metadata defined by `@Command`, `@OnNet`, etc.
+ * 3. **Runtime Binding:** Binds the discovered metadata to actual FiveM natives (e.g., `RegisterCommand`, `onNet`, `exports`).
+ * 4. **Session Management:** Activates the player session tracking system.
+ *
+ * @returns A promise that resolves when the Core is fully initialized and ready to process events.
+ */
+async function initServer() {
+    logger_1.loggers.bootstrap.info('Initializing OpenCore Server...');
+    check();
+    // Register core services
+    (0, registers_1.registerServicesServer)();
+    logger_1.loggers.bootstrap.debug('Core services registered');
+    // Register system processors
+    (0, processors_register_1.registerSystemServer)();
+    logger_1.loggers.bootstrap.debug('System processors registered');
+    // Extras
+    (0, playerSession_loader_1.playerSessionLoader)();
+    logger_1.loggers.bootstrap.debug('Player session loader active');
+    const scanner = container_1.di.resolve(metadata_scanner_1.MetadataScanner);
+    scanner.scan(controller_1.serverControllerRegistry);
+    logger_1.loggers.bootstrap.info('OpenCore Server initialized successfully');
+}

package/dist/server/bus/core-event-bus.d.ts

@@ -0,0 +1,6 @@
+import type { CoreEventMap } from '../types/core-events';
+type CoreEventName = keyof CoreEventMap;
+type CoreEventHandler<E extends CoreEventName> = (payload: CoreEventMap[E]) => void;
+export declare function onCoreEvent<E extends CoreEventName>(event: E, handler: CoreEventHandler<E>): () => void;
+export declare function emitCoreEvent<E extends CoreEventName>(event: E, payload: CoreEventMap[E]): void;
+export {};

package/dist/server/bus/core-event-bus.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.onCoreEvent = onCoreEvent;
+exports.emitCoreEvent = emitCoreEvent;
+const logger_1 = require("../../shared/logger");
+const handlers = {};
+function onCoreEvent(event, handler) {
+    var _a;
+    const list = ((_a = handlers[event]) !== null && _a !== void 0 ? _a : (handlers[event] = []));
+    list.push(handler);
+    return () => {
+        const index = list.indexOf(handler);
+        if (index !== -1)
+            list.splice(index, 1);
+    };
+}
+function emitCoreEvent(event, payload) {
+    const list = handlers[event];
+    if (!list)
+        return;
+    for (const handler of list) {
+        try {
+            handler(payload);
+        }
+        catch (error) {
+            logger_1.loggers.eventBus.error(`Handler error for event`, {
+                event,
+            }, error);
+        }
+    }
+}

package/dist/server/configs/api.config.d.ts

@@ -0,0 +1,71 @@
+import { FluentConfigurator } from './config.base';
+interface ApiConfigState {
+    baseUrl: string;
+    timeoutMs: number;
+}
+/**
+ * Extended configurator interface for API configuration.
+ *
+ * Extends the base fluent configurator with additional methods
+ * specific to API configuration (like addHeader).
+ */
+export interface ApiConfigurator extends FluentConfigurator<ApiConfigState> {
+    /**
+     * Alias for timeoutMs - sets the timeout in milliseconds.
+     * @param ms - Timeout duration in milliseconds.
+     */
+    timeout(ms: number): this;
+    /**
+     * Adds a default header to be included in every API request.
+     * @param key - The HTTP header name (e.g., "Authorization").
+     * @param value - The header value.
+     */
+    addHeader(key: string, value: string): this;
+}
+/**
+ * Configuration service for the Core API module.
+ *
+ * It follows a "Convention over Configuration" approach:
+ * 1. By default, it loads values from FiveM Convars (`opencore_api_url`, `opencore_api_timeout`).
+ * 2. It can be programmatically overridden using the `configure()` method.
+ *
+ * @scope Singleton
+ */
+export declare class ApiConfig {
+    private state;
+    private _headers;
+    /**
+     * Applies programmatic configuration using a functional builder pattern.
+     *
+     * This method allows developers to override default settings or inject dynamic configuration
+     * logic during the server startup phase.
+     *
+     * @example
+     * ```ts
+     * const apiConfig = di.resolve(ApiConfig);
+     * apiConfig.configure(c =>
+     *   c.baseUrl('https://api.production.com')
+     *     .timeout(10000)
+     *     .addHeader('X-API-Key', 'secret')
+     * );
+     * ```
+     *
+     * @param configFn - A callback function that receives the configurator instance.
+     */
+    configure(configFn: (config: ApiConfigurator) => void): void;
+    /**
+     * Gets the currently configured Base URL.
+     */
+    get baseUrl(): string;
+    /**
+     * Gets the configured timeout in milliseconds.
+     */
+    get timeoutMs(): number;
+    /**
+     * Gets a copy of the globally configured headers.
+     */
+    get headers(): {
+        [x: string]: string;
+    };
+}
+export {};