@open-core/framework 0.1.0-alpha.1

package/dist/server/configs/api.config.js

@@ -0,0 +1,81 @@
+"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.ApiConfig = void 0;
+const decorators_1 = require("../decorators");
+const config_base_1 = require("./config.base");
+/**
+ * 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
+ */
+let ApiConfig = class ApiConfig {
+    constructor() {
+        this.state = {
+            baseUrl: GetConvar('opencore_api_url', 'http://localhost:3000'),
+            timeoutMs: Number(GetConvar('opencore_api_timeout', '5000')),
+        };
+        this._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) {
+        const baseConfigurator = (0, config_base_1.createFluentConfigurator)(this.state);
+        // Extend with custom methods
+        const configurator = Object.assign(Object.assign({}, baseConfigurator), { timeout: (ms) => {
+                this.state.timeoutMs = ms;
+                return configurator;
+            }, addHeader: (key, value) => {
+                this._headers[key] = value;
+                return configurator;
+            } });
+        configFn(configurator);
+    }
+    /**
+     * Gets the currently configured Base URL.
+     */
+    get baseUrl() {
+        return this.state.baseUrl;
+    }
+    /**
+     * Gets the configured timeout in milliseconds.
+     */
+    get timeoutMs() {
+        return this.state.timeoutMs;
+    }
+    /**
+     * Gets a copy of the globally configured headers.
+     */
+    get headers() {
+        return Object.assign({}, this._headers);
+    }
+};
+exports.ApiConfig = ApiConfig;
+exports.ApiConfig = ApiConfig = __decorate([
+    (0, decorators_1.Bind)('singleton')
+], ApiConfig);

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

@@ -0,0 +1,63 @@
+/**
+ * Fluent Configuration Utilities
+ *
+ * Provides utilities for creating Spring Boot-style fluent configuration APIs.
+ * This enables method chaining for cleaner configuration syntax.
+ *
+ * @example
+ * ```ts
+ * interface MyConfigState {
+ *   host: string
+ *   port: number
+ *   enabled: boolean
+ * }
+ *
+ * const state: MyConfigState = { host: 'localhost', port: 3000, enabled: true }
+ * const configurator = createFluentConfigurator(state)
+ *
+ * configurator
+ *   .host('api.example.com')
+ *   .port(8080)
+ *   .enabled(false)
+ * ```
+ */
+/**
+ * Type that transforms a state object into a fluent configurator interface.
+ *
+ * Each property becomes a method that:
+ * - Accepts a value of the same type as the original property
+ * - Returns the configurator for method chaining
+ *
+ * @template T - The state object type
+ */
+export type FluentConfigurator<T> = {
+    [K in keyof T]: (value: T[K]) => FluentConfigurator<T>;
+};
+/**
+ * Creates a fluent configurator from a state object.
+ *
+ * The configurator allows method chaining to set values on the state object.
+ * Each property of the state becomes a method on the configurator.
+ *
+ * @template T - The state object type
+ * @param state - The state object to configure (will be mutated)
+ * @returns A fluent configurator with chainable methods
+ *
+ * @example
+ * ```ts
+ * interface ApiState {
+ *   baseUrl: string
+ *   timeout: number
+ * }
+ *
+ * const state: ApiState = { baseUrl: '', timeout: 5000 }
+ *
+ * createFluentConfigurator(state)
+ *   .baseUrl('https://api.example.com')
+ *   .timeout(10000)
+ *
+ * console.log(state.baseUrl) // 'https://api.example.com'
+ * console.log(state.timeout) // 10000
+ * ```
+ */
+export declare function createFluentConfigurator<T extends object>(state: T): FluentConfigurator<T>;

package/dist/server/configs/config.base.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Fluent Configuration Utilities
+ *
+ * Provides utilities for creating Spring Boot-style fluent configuration APIs.
+ * This enables method chaining for cleaner configuration syntax.
+ *
+ * @example
+ * ```ts
+ * interface MyConfigState {
+ *   host: string
+ *   port: number
+ *   enabled: boolean
+ * }
+ *
+ * const state: MyConfigState = { host: 'localhost', port: 3000, enabled: true }
+ * const configurator = createFluentConfigurator(state)
+ *
+ * configurator
+ *   .host('api.example.com')
+ *   .port(8080)
+ *   .enabled(false)
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFluentConfigurator = createFluentConfigurator;
+/**
+ * Creates a fluent configurator from a state object.
+ *
+ * The configurator allows method chaining to set values on the state object.
+ * Each property of the state becomes a method on the configurator.
+ *
+ * @template T - The state object type
+ * @param state - The state object to configure (will be mutated)
+ * @returns A fluent configurator with chainable methods
+ *
+ * @example
+ * ```ts
+ * interface ApiState {
+ *   baseUrl: string
+ *   timeout: number
+ * }
+ *
+ * const state: ApiState = { baseUrl: '', timeout: 5000 }
+ *
+ * createFluentConfigurator(state)
+ *   .baseUrl('https://api.example.com')
+ *   .timeout(10000)
+ *
+ * console.log(state.baseUrl) // 'https://api.example.com'
+ * console.log(state.timeout) // 10000
+ * ```
+ */
+function createFluentConfigurator(state) {
+    const configurator = {};
+    for (const key of Object.keys(state)) {
+        ;
+        configurator[key] = (value) => {
+            state[key] = value;
+            return configurator;
+        };
+    }
+    return configurator;
+}

package/dist/server/configs/index.d.ts

@@ -0,0 +1,2 @@
+export * from './api.config';
+export * from './config.base';

package/dist/server/configs/index.js

@@ -0,0 +1,18 @@
+"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("./api.config"), exports);
+__exportStar(require("./config.base"), exports);

package/dist/server/container.d.ts

@@ -0,0 +1,2 @@
+import 'reflect-metadata';
+export declare const di: import("tsyringe").DependencyContainer;

package/dist/server/container.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.di = void 0;
+require("reflect-metadata");
+const tsyringe_1 = require("tsyringe");
+exports.di = tsyringe_1.container;

package/dist/server/controllers/chat.controller.d.ts

@@ -0,0 +1,10 @@
+import { RGB } from '../../utils';
+import { PlayerService } from '../services';
+import { ChatService } from '../services/chat.service';
+export declare class ChatController {
+    private readonly chatService;
+    private readonly playerService;
+    constructor(chatService: ChatService, playerService: PlayerService);
+    apiBroadcast(message: string, author?: string, color?: RGB): void;
+    apiSendPrivate(targetId: number, message: string, author?: string): void;
+}

package/dist/server/controllers/chat.controller.js

@@ -0,0 +1,50 @@
+"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.ChatController = void 0;
+const controller_1 = require("../decorators/controller");
+const export_1 = require("../decorators/export");
+const services_1 = require("../services");
+const chat_service_1 = require("../services/chat.service");
+let ChatController = class ChatController {
+    constructor(chatService, playerService) {
+        this.chatService = chatService;
+        this.playerService = playerService;
+    }
+    apiBroadcast(message, author = 'SYSTEM', color = { r: 255, g: 255, b: 255 }) {
+        this.chatService.broadcast(message, author, color);
+    }
+    apiSendPrivate(targetId, message, author = 'Private') {
+        const player = this.playerService.getByClient(targetId);
+        if (!player) {
+            throw new Error(`Player with client ID ${targetId} not found`);
+        }
+        this.chatService.sendPrivate(player, message, author);
+    }
+};
+exports.ChatController = ChatController;
+__decorate([
+    (0, export_1.Export)('core:broadcast'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, Object]),
+    __metadata("design:returntype", void 0)
+], ChatController.prototype, "apiBroadcast", null);
+__decorate([
+    (0, export_1.Export)('core:sendprivate'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number, String, String]),
+    __metadata("design:returntype", void 0)
+], ChatController.prototype, "apiSendPrivate", null);
+exports.ChatController = ChatController = __decorate([
+    (0, controller_1.Controller)(),
+    __metadata("design:paramtypes", [chat_service_1.ChatService,
+        services_1.PlayerService])
+], ChatController);

package/dist/server/controllers/command.controller.d.ts

@@ -0,0 +1,7 @@
+import { CommandService } from '../services/command.service';
+import { Player } from '../entities';
+export declare class CommandNetworkController {
+    private readonly commandService;
+    constructor(commandService: CommandService);
+    onCommandReceived(player: Player, command: string, args: string[], raw: string): Promise<void>;
+}

package/dist/server/controllers/command.controller.js

@@ -0,0 +1,47 @@
+"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.CommandNetworkController = void 0;
+const onNet_1 = require("../decorators/onNet");
+const command_service_1 = require("../services/command.service");
+const entities_1 = require("../entities");
+const decorators_1 = require("../decorators");
+const logger_1 = require("../../shared/logger");
+let CommandNetworkController = class CommandNetworkController {
+    constructor(commandService) {
+        this.commandService = commandService;
+    }
+    async onCommandReceived(player, command, args, raw) {
+        try {
+            logger_1.loggers.command.trace(`Received: /${command}`, {
+                playerId: player.clientID,
+                playerName: player.name,
+            });
+            await this.commandService.execute(player, command, args, raw);
+        }
+        catch (error) {
+            logger_1.loggers.command.error(`Execution failed: /${command}`, {
+                playerId: player.clientID,
+            }, error);
+        }
+    }
+};
+exports.CommandNetworkController = CommandNetworkController;
+__decorate([
+    (0, onNet_1.OnNet)('core:internal:executeCommand'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [entities_1.Player, String, Array, String]),
+    __metadata("design:returntype", Promise)
+], CommandNetworkController.prototype, "onCommandReceived", null);
+exports.CommandNetworkController = CommandNetworkController = __decorate([
+    (0, decorators_1.Controller)(),
+    __metadata("design:paramtypes", [command_service_1.CommandService])
+], CommandNetworkController);

package/dist/server/controllers/session.controller.d.ts

@@ -0,0 +1,9 @@
+import { PlayerService } from '../services';
+import { PlayerPersistenceService } from '../services/persistence.service';
+export declare class SessionController {
+    private readonly playerManager;
+    private readonly persistance;
+    constructor(playerManager: PlayerService, persistance: PlayerPersistenceService);
+    onPlayerJoining(): Promise<void>;
+    onPlayerDropped(): Promise<void>;
+}

package/dist/server/controllers/session.controller.js

@@ -0,0 +1,70 @@
+"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.SessionController = void 0;
+const shared_1 = require("../../shared");
+const core_event_bus_1 = require("../bus/core-event-bus");
+const decorators_1 = require("../decorators");
+const onFiveMEvent_1 = require("../decorators/onFiveMEvent");
+const services_1 = require("../services");
+const persistence_service_1 = require("../services/persistence.service");
+let SessionController = class SessionController {
+    constructor(playerManager, persistance) {
+        this.playerManager = playerManager;
+        this.persistance = persistance;
+    }
+    async onPlayerJoining() {
+        var _a;
+        const clientId = source;
+        const license = (_a = GetPlayerIdentifier(clientId.toString(), 0)) !== null && _a !== void 0 ? _a : undefined;
+        const player = this.playerManager.bind(clientId, { license });
+        shared_1.loggers.session.info(`Player session created`, {
+            clientId,
+            license: license !== null && license !== void 0 ? license : 'none',
+        });
+        await this.persistance.handleSessionLoad(player);
+        (0, core_event_bus_1.emitCoreEvent)('core:playerSessionCreated', { clientId, license });
+        setImmediate(() => {
+            const currentPlayer = this.playerManager.getByClient(clientId);
+            if (!currentPlayer)
+                return;
+            (0, core_event_bus_1.emitCoreEvent)('core:playerFullyConnected', { clientId, license });
+        });
+    }
+    async onPlayerDropped() {
+        const clientId = Number(source);
+        const player = this.playerManager.getByClient(clientId);
+        if (player) {
+            await this.persistance.handleSessionSave(player);
+        }
+        this.playerManager.unbindByClient(clientId);
+        (0, core_event_bus_1.emitCoreEvent)('core:playerSessionDestroyed', { clientId });
+        shared_1.loggers.session.info(`Player session destroyed`, { clientId });
+    }
+};
+exports.SessionController = SessionController;
+__decorate([
+    (0, onFiveMEvent_1.OnFiveMEvent)('playerJoining'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], SessionController.prototype, "onPlayerJoining", null);
+__decorate([
+    (0, onFiveMEvent_1.OnFiveMEvent)('playerDropped'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], SessionController.prototype, "onPlayerDropped", null);
+exports.SessionController = SessionController = __decorate([
+    (0, decorators_1.Controller)(),
+    __metadata("design:paramtypes", [services_1.PlayerService,
+        persistence_service_1.PlayerPersistenceService])
+], SessionController);

package/dist/server/core.d.ts

@@ -0,0 +1 @@
+export declare function init(): Promise<void>;

package/dist/server/core.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.init = init;
+const bootstrap_1 = require("./bootstrap");
+async function init() {
+    await (0, bootstrap_1.initServer)();
+}

package/dist/server/database/adapters/oxmysql.adapter.d.ts

@@ -0,0 +1,89 @@
+/**
+ * OxMySQL Adapter
+ *
+ * Default database adapter using oxmysql resource for FiveM.
+ * Requires oxmysql to be installed and running on the server.
+ *
+ * @see https://github.com/overextended/oxmysql
+ * @see https://coxdocs.dev/oxmysql/Functions/transaction
+ */
+import { DatabaseContract } from '../database.contract';
+import type { ExecuteResult, InsertResult, TransactionInput, TransactionSharedParams } from '../types';
+/**
+ * OxMySQL Database Adapter
+ *
+ * Implements DatabaseContract using oxmysql exports.
+ *
+ * @example
+ * ```typescript
+ * import { OxMySQLAdapter } from '@open-core/framework/server'
+ *
+ * // Usually you don't need to instantiate directly,
+ * // use DatabaseService instead
+ * const adapter = new OxMySQLAdapter()
+ * const users = await adapter.query('SELECT * FROM users')
+ * ```
+ */
+export declare class OxMySQLAdapter extends DatabaseContract {
+    private ox;
+    constructor();
+    /**
+     * Execute a query and return all matching rows
+     */
+    query<T = any>(sql: string, params?: any[]): Promise<T[]>;
+    /**
+     * Execute a query and return a single row
+     */
+    single<T = any>(sql: string, params?: any[]): Promise<T | null>;
+    /**
+     * Execute a query and return a single scalar value
+     */
+    scalar<T = any>(sql: string, params?: any[]): Promise<T | null>;
+    /**
+     * Execute an UPDATE or DELETE statement
+     */
+    execute(sql: string, params?: any[]): Promise<ExecuteResult>;
+    /**
+     * Execute an INSERT statement
+     */
+    insert(sql: string, params?: any[]): Promise<InsertResult>;
+    /**
+     * Execute multiple queries within a transaction.
+     *
+     * Supports three formats:
+     *
+     * **1. Specific format (object)**
+     * ```typescript
+     * await db.transaction([
+     *   { query: 'INSERT INTO test (id) VALUES (?)', values: [1] },
+     *   { query: 'INSERT INTO test (id, name) VALUES (?, ?)', values: [2, 'bob'] },
+     * ])
+     * ```
+     *
+     * **2. Specific format (tuple)**
+     * ```typescript
+     * await db.transaction([
+     *   ['INSERT INTO test (id) VALUES (?)', [1]],
+     *   ['INSERT INTO test (id, name) VALUES (?, ?)', [2, 'bob']],
+     * ])
+     * ```
+     *
+     * **3. Shared format (named parameters)**
+     * ```typescript
+     * await db.transaction(
+     *   [
+     *     'INSERT INTO test (id, name) VALUES (@someid, @somename)',
+     *     'UPDATE test SET name = @newname WHERE id = @someid',
+     *   ],
+     *   {
+     *     someid: 2,
+     *     somename: 'John Doe',
+     *     newname: 'John Notdoe',
+     *   }
+     * )
+     * ```
+     *
+     * @see https://coxdocs.dev/oxmysql/Functions/transaction
+     */
+    transaction(queries: TransactionInput, sharedParams?: TransactionSharedParams): Promise<boolean>;
+}