@open-core/framework 1.0.1-beta.1

package/dist/server/database/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Database Module Types
+ *
+ * Core types for the database abstraction layer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/server/database.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Database Module Re-export
+ *
+ * This file re-exports the database module for backwards compatibility.
+ * Prefer importing directly from '@open-core/framework/server' or './database/index'
+ */
+export * from './database/index';

package/dist/server/database.js

@@ -0,0 +1,23 @@
+"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 });
+/**
+ * Database Module Re-export
+ *
+ * This file re-exports the database module for backwards compatibility.
+ * Prefer importing directly from '@open-core/framework/server' or './database/index'
+ */
+__exportStar(require("./database/index"), exports);

package/dist/server/decorators/bind.d.ts

@@ -0,0 +1,2 @@
+export type BindingScope = 'singleton' | 'transient';
+export declare function Bind(scope?: BindingScope): (target: any) => void;

package/dist/server/decorators/bind.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Bind = Bind;
+const tsyringe_1 = require("tsyringe");
+function Bind(scope = 'singleton') {
+    return function (target) {
+        (0, tsyringe_1.injectable)()(target);
+        if (scope === 'singleton') {
+            (0, tsyringe_1.singleton)()(target);
+        }
+        else {
+            (0, tsyringe_1.scoped)(tsyringe_1.Lifecycle.ResolutionScoped)(target);
+        }
+    };
+}

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

@@ -0,0 +1,19 @@
+import type { ClassConstructor } from '../../system/class-constructor';
+import type z from 'zod';
+export interface CommandConfig {
+    name: string;
+    description?: string;
+    usage?: string;
+    schema?: z.ZodType;
+}
+export interface CommandMetadata extends CommandConfig {
+    methodName: string;
+    target: ClassConstructor;
+}
+/**
+ * Decorator used to mark a controller method as a command.
+ * The metadata is collected and later bound to FiveM via RegisterCommand().
+ *
+ * @param name - The command name (e.g. "revive", "deposit")
+ */
+export declare function Command(configOrName: string | CommandConfig): (target: any, propertyKey: string) => void;

package/dist/server/decorators/command.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Command = Command;
+const metadata_server_keys_1 = require("../system/metadata-server.keys");
+/**
+ * Decorator used to mark a controller method as a command.
+ * The metadata is collected and later bound to FiveM via RegisterCommand().
+ *
+ * @param name - The command name (e.g. "revive", "deposit")
+ */
+function Command(configOrName) {
+    return (target, propertyKey) => {
+        // Normalizamos: si pasa solo un string, creamos el objeto config
+        const config = typeof configOrName === 'string' ? { name: configOrName } : configOrName;
+        const metadata = Object.assign(Object.assign({}, config), { methodName: propertyKey, target: target.constructor });
+        Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.COMMAND, metadata, target, propertyKey);
+    };
+}

package/dist/server/decorators/controller.d.ts

@@ -0,0 +1,3 @@
+import type { ClassConstructor } from '../../system/class-constructor';
+export declare const serverControllerRegistry: ClassConstructor[];
+export declare function Controller(): (target: ClassConstructor) => void;

package/dist/server/decorators/controller.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serverControllerRegistry = void 0;
+exports.Controller = Controller;
+const tsyringe_1 = require("tsyringe");
+const metadata_server_keys_1 = require("../system/metadata-server.keys");
+exports.serverControllerRegistry = [];
+function Controller() {
+    return function (target) {
+        (0, tsyringe_1.injectable)()(target);
+        Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.CONTROLLER, { type: 'server' }, target);
+        exports.serverControllerRegistry.push(target);
+    };
+}

package/dist/server/decorators/coreEvent.d.ts

@@ -0,0 +1,2 @@
+import type { CoreEventMap } from '../types/core-events';
+export declare function OnCoreEvent<K extends keyof CoreEventMap>(event: K): (target: any, propertyKey: string) => void;

package/dist/server/decorators/coreEvent.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OnCoreEvent = OnCoreEvent;
+const metadata_server_keys_1 = require("../system/metadata-server.keys");
+function OnCoreEvent(event) {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.CORE_EVENT, { event }, target, propertyKey);
+    };
+}

package/dist/server/decorators/export.d.ts

@@ -0,0 +1 @@
+export declare function Export(name?: string): (target: any, propertyKey: string) => void;

package/dist/server/decorators/export.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Export = Export;
+const metadata_server_keys_1 = require("../system/metadata-server.keys");
+function Export(name) {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.EXPORT, { exportName: name || propertyKey }, target, propertyKey);
+    };
+}

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

@@ -0,0 +1,5 @@
+export interface GuardOptions {
+    rank?: number;
+    permission?: string;
+}
+export declare function Guard(options: GuardOptions): (target: any, propertyKey: string, descriptor?: PropertyDescriptor) => PropertyDescriptor | undefined;

package/dist/server/decorators/guard.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Guard = Guard;
+const container_1 = require("../container");
+const services_1 = require("../services");
+const logger_1 = require("../../shared/logger");
+function Guard(options) {
+    return function (target, propertyKey, descriptor) {
+        var _a;
+        if (!descriptor) {
+            // In benchmarks or edge cases, only register metadata without method wrapping
+            // This should NOT happen in production code with proper TypeScript compilation
+            logger_1.loggers.security.warn(`@Guard decorator: PropertyDescriptor not available. Only metadata will be registered. This should not happen in production code. Target: ${(_a = target.constructor) === null || _a === void 0 ? void 0 : _a.name}, Method: ${propertyKey}`);
+            Reflect.defineMetadata('core:guard', options, target, propertyKey);
+            return;
+        }
+        const originalMethod = descriptor.value;
+        descriptor.value = async function (...args) {
+            var _a;
+            const player = args[0];
+            if (!player || !player.clientID) {
+                logger_1.loggers.security.warn(`@Guard misuse: First argument is not a Player`, {
+                    method: propertyKey,
+                    targetClass: (_a = target.constructor) === null || _a === void 0 ? void 0 : _a.name,
+                });
+                throw new Error('Guard Security Error: Context is not a player');
+            }
+            const accessControl = container_1.di.resolve(services_1.AccessControlService);
+            await accessControl.enforce(player, {
+                minRank: options.rank,
+                permission: options.permission,
+            });
+            return originalMethod.apply(this, args);
+        };
+        // no need a defined metadata key, as we won't read it later
+        Reflect.defineMetadata('core:guard', options, target, propertyKey);
+        return descriptor;
+    };
+}

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

@@ -0,0 +1,10 @@
+export * from './bind';
+export * from './utils';
+export * from './command';
+export * from './coreEvent';
+export * from './netEvent';
+export * from './onTick';
+export * from './controller';
+export * from './throttle';
+export * from './guard';
+export * from './requiresState';

package/dist/server/decorators/index.js

@@ -0,0 +1,26 @@
+"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("./bind"), exports);
+__exportStar(require("./utils"), exports);
+__exportStar(require("./command"), exports);
+__exportStar(require("./coreEvent"), exports);
+__exportStar(require("./netEvent"), exports);
+__exportStar(require("./onTick"), exports);
+__exportStar(require("./controller"), exports);
+__exportStar(require("./throttle"), exports);
+__exportStar(require("./guard"), exports);
+__exportStar(require("./requiresState"), exports);

package/dist/server/decorators/netEvent.d.ts

@@ -0,0 +1,36 @@
+import type { z } from 'zod';
+export interface NetEventOptions {
+    eventName: string;
+    schema?: z.ZodType;
+}
+/**
+ * Decorator used to register a server-side NetEvent handler.
+ *
+ * ## Player Injection
+ * The handler method will **always receive a `ServerPlayer` instance as its
+ * first argument**, automatically resolved by the Core based on the client
+ * that triggered the event.
+ *
+ * This means you do NOT need to read `source`, `global.source` or call
+ * `GetPlayerIdentifier()`: the Core resolves the player for you.
+ *
+ * ## Example
+ * ```ts
+ * export class AuthServerController {
+ *   @OnNet('auth:loginAttempt')
+ *   handleLogin(player: ServerPlayer, username: string, password: string) {
+ *     console.log(player.name, 'is trying to log in');
+ *   }
+ * }
+ * ```
+ *
+ * ## Event Arguments
+ * Any arguments sent from the client will be passed **after** the `ServerPlayer`
+ * instance:
+ *
+ * client → emitNet("auth:loginAttempt", username, password)
+ * server → handler(player, username, password)
+ *
+ * @param eventName - The name of the network event to listen for.
+ */
+export declare function OnNet(eventName: string, schema?: z.ZodType): (target: any, propertyKey: string) => void;

package/dist/server/decorators/netEvent.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OnNet = OnNet;
+const metadata_server_keys_1 = require("../system/metadata-server.keys");
+/**
+ * Decorator used to register a server-side NetEvent handler.
+ *
+ * ## Player Injection
+ * The handler method will **always receive a `ServerPlayer` instance as its
+ * first argument**, automatically resolved by the Core based on the client
+ * that triggered the event.
+ *
+ * This means you do NOT need to read `source`, `global.source` or call
+ * `GetPlayerIdentifier()`: the Core resolves the player for you.
+ *
+ * ## Example
+ * ```ts
+ * export class AuthServerController {
+ *   @OnNet('auth:loginAttempt')
+ *   handleLogin(player: ServerPlayer, username: string, password: string) {
+ *     console.log(player.name, 'is trying to log in');
+ *   }
+ * }
+ * ```
+ *
+ * ## Event Arguments
+ * Any arguments sent from the client will be passed **after** the `ServerPlayer`
+ * instance:
+ *
+ * client → emitNet("auth:loginAttempt", username, password)
+ * server → handler(player, username, password)
+ *
+ * @param eventName - The name of the network event to listen for.
+ */
+function OnNet(eventName, schema) {
+    return (target, propertyKey) => {
+        const metadata = { eventName, schema };
+        Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.NET_EVENT, metadata, target, propertyKey);
+    };
+}

package/dist/server/decorators/onTick.d.ts

@@ -0,0 +1 @@
+export declare function OnTick(): (target: any, propertyKey: string) => void;

package/dist/server/decorators/onTick.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OnTick = OnTick;
+const metadata_server_keys_1 = require("../system/metadata-server.keys");
+function OnTick() {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.TICK, {}, target, propertyKey);
+    };
+}

package/dist/server/decorators/public.d.ts

@@ -0,0 +1,16 @@
+/**
+ * **Only works on NetEvents in Server-side**
+ *
+ * Marks an endpoint as publicly accessible (no authentication required).
+ * Use only for login, register, or public info endpoints.
+ *
+ * @example
+ * ```ts
+ * class AuthServerController {
+ *   @ Server.Public()
+ *   @ Server.OnNet('auth:login')
+ *   async login(player: Server.Player, credentials: AuthCredentials) { ... }
+ * }
+ * ```
+ *  */
+export declare function Public(): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;

package/dist/server/decorators/public.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Public = Public;
+const metadata_server_keys_1 = require("../system/metadata-server.keys");
+/**
+ * **Only works on NetEvents in Server-side**
+ *
+ * Marks an endpoint as publicly accessible (no authentication required).
+ * Use only for login, register, or public info endpoints.
+ *
+ * @example
+ * ```ts
+ * class AuthServerController {
+ *   @ Server.Public()
+ *   @ Server.OnNet('auth:login')
+ *   async login(player: Server.Player, credentials: AuthCredentials) { ... }
+ * }
+ * ```
+ *  */
+function Public() {
+    return function (target, propertyKey, descriptor) {
+        Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.PUBLIC, true, target, propertyKey);
+        return descriptor;
+    };
+}

package/dist/server/decorators/requiresState.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Configuration options for state validation requirements.
+ * Defines the logical constraints (whitelist/blacklist) applied to the player's current state flags.
+ */
+export interface StateRequirement {
+    /**
+     * **Whitelist:** The player **MUST** possess ALL of these states to proceed.
+     * If the player is missing any one of these, the execution is blocked.
+     * @example ['on_duty_police', 'in_vehicle']
+     */
+    has?: string[];
+    /**
+     * **Blacklist:** The player **MUST NOT** possess ANY of these states to proceed.
+     * If the player has any one of these, the execution is blocked.
+     * @example ['dead', 'cuffed', 'unconscious']
+     */
+    missing?: string[];
+    /**
+     * A custom message to display to the client if validation fails.
+     * If omitted, a default generic message will be generated based on the missing/conflicting state.
+     */
+    errorMessage?: string;
+}
+/**
+ * **Game State Guard Decorator**
+ *
+ * A method decorator that enforces game logic constraints based on the player's dynamic states.
+ * It intercepts the method call and validates the player's flags (e.g., 'dead', 'cuffed', 'driving')
+ * before allowing the controller logic to execute.
+ *
+ * @remarks
+ * - This decorator assumes the **first argument** of the decorated method is a `Server.Player` instance.
+ * - It throws a `GAME_STATE_ERROR` (AppError) if requirements are not met, which should be caught by the global error handler.
+ *
+ * @param req - The state requirements configuration (whitelist and/or blacklist).
+ *
+ * @throws {Error} If the decorated method is called without a valid Player context (Server-side logic error).
+ * @throws {AppError} If the player fails the state validation (Client-facing logic error).
+ *
+ * @example
+ * ```ts
+ * // Example 1: Action requires being alive (not dead) and not handcuffed
+ * @RequiresState({ missing: ['dead', 'cuffed'] })
+ * openInventory(player: Server.Player) { ... }
+ *
+ * // Example 2: Action requires being a police officer on duty
+ * @RequiresState({
+ * has: ['police_duty'],
+ * missing: ['dead'],
+ * errorMessage: 'You must be on duty to access the armory.'
+ * })
+ * openArmory(player: Server.Player) { ... }
+ * ```
+ */
+export declare function RequiresState(req: StateRequirement): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;

package/dist/server/decorators/requiresState.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequiresState = RequiresState;
+const utils_1 = require("../../utils");
+/**
+ * **Game State Guard Decorator**
+ *
+ * A method decorator that enforces game logic constraints based on the player's dynamic states.
+ * It intercepts the method call and validates the player's flags (e.g., 'dead', 'cuffed', 'driving')
+ * before allowing the controller logic to execute.
+ *
+ * @remarks
+ * - This decorator assumes the **first argument** of the decorated method is a `Server.Player` instance.
+ * - It throws a `GAME_STATE_ERROR` (AppError) if requirements are not met, which should be caught by the global error handler.
+ *
+ * @param req - The state requirements configuration (whitelist and/or blacklist).
+ *
+ * @throws {Error} If the decorated method is called without a valid Player context (Server-side logic error).
+ * @throws {AppError} If the player fails the state validation (Client-facing logic error).
+ *
+ * @example
+ * ```ts
+ * // Example 1: Action requires being alive (not dead) and not handcuffed
+ * @RequiresState({ missing: ['dead', 'cuffed'] })
+ * openInventory(player: Server.Player) { ... }
+ *
+ * // Example 2: Action requires being a police officer on duty
+ * @RequiresState({
+ * has: ['police_duty'],
+ * missing: ['dead'],
+ * errorMessage: 'You must be on duty to access the armory.'
+ * })
+ * openArmory(player: Server.Player) { ... }
+ * ```
+ */
+function RequiresState(req) {
+    return function (target, propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        descriptor.value = async function (...args) {
+            const player = args[0];
+            if (!player) {
+                throw new Error(`@RequiresState used on ${propertyKey} without Player context`);
+            }
+            if (req.has) {
+                for (const state of req.has) {
+                    if (!player.hasState(state)) {
+                        throw new utils_1.AppError('GAME_STATE_ERROR', req.errorMessage || `You must be [${state}] to do this.`, 'client');
+                    }
+                }
+            }
+            if (req.missing) {
+                for (const state of req.missing) {
+                    if (player.hasState(state)) {
+                        throw new utils_1.AppError('GAME_STATE_ERROR', req.errorMessage || `You can't do this while you're [${state}].`, 'client');
+                    }
+                }
+            }
+            return originalMethod.apply(this, args);
+        };
+        return descriptor;
+    };
+}

package/dist/server/decorators/throttle.d.ts

@@ -0,0 +1,9 @@
+import type { SecurityAction } from '../types/security.types';
+interface ThrottleOptions {
+    limit: number;
+    windowMs: number;
+    onExceed?: SecurityAction;
+    message?: string;
+}
+export declare function Throttle(optionsOrLimit: number | ThrottleOptions, windowMs?: number): (target: any, propertyKey: string, descriptor?: PropertyDescriptor) => PropertyDescriptor | undefined;
+export {};

package/dist/server/decorators/throttle.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Throttle = Throttle;
+const tsyringe_1 = require("tsyringe");
+const rate_limiter_service_1 = require("../services/rate-limiter.service");
+const utils_1 = require("../../utils");
+function Throttle(optionsOrLimit, windowMs) {
+    return function (target, propertyKey, descriptor) {
+        if (!descriptor) {
+            // In benchmarks or edge cases, skip method wrapping
+            // This should NOT happen in production code with proper TypeScript compilation
+            // Note: Throttle cannot work without descriptor, so we just skip it
+            return;
+        }
+        const originalMethod = descriptor.value;
+        let opts;
+        if (typeof optionsOrLimit === 'number') {
+            opts = { limit: optionsOrLimit, windowMs: windowMs || 1000, onExceed: 'LOG' };
+        }
+        else {
+            opts = Object.assign({ onExceed: 'LOG' }, optionsOrLimit);
+        }
+        descriptor.value = async function (...args) {
+            const player = args[0];
+            if (player === null || player === void 0 ? void 0 : player.clientID) {
+                const service = tsyringe_1.container.resolve(rate_limiter_service_1.RateLimiterService);
+                const key = `${player.clientID}:${target.constructor.name}:${propertyKey}`;
+                if (!service.checkLimit(key, opts.limit, opts.windowMs)) {
+                    throw new utils_1.SecurityError(opts.onExceed, opts.message || `Rate limit exceeded on ${propertyKey}`, { limit: opts.limit, key });
+                }
+            }
+            return originalMethod.apply(this, args);
+        };
+        return descriptor;
+    };
+}

package/dist/server/decorators/utils.d.ts

@@ -0,0 +1,7 @@
+import type { BindingScope } from './bind';
+export declare function Service(options?: {
+    scope?: BindingScope;
+}): (target: any) => void;
+export declare function Repo(options?: {
+    scope?: BindingScope;
+}): (target: any) => void;

package/dist/server/decorators/utils.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Service = Service;
+exports.Repo = Repo;
+const bind_1 = require("./bind");
+function Service(options) {
+    var _a;
+    return (0, bind_1.Bind)((_a = options === null || options === void 0 ? void 0 : options.scope) !== null && _a !== void 0 ? _a : 'singleton');
+}
+function Repo(options) {
+    var _a;
+    return (0, bind_1.Bind)((_a = options === null || options === void 0 ? void 0 : options.scope) !== null && _a !== void 0 ? _a : 'singleton');
+}

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

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

package/dist/server/entities/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("./player"), exports);