@open-core/framework 0.1.0-alpha.1 → 0.2.0-beta.1

package/dist/server/decorators/command.js

@@ -1,23 +0,0 @@
-"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.
- * This method will be registered and then executed by the command service.
- * It will depend on the chat you have implemented following the dependency conventions.
- *
- * @param configOrName - The command name (e.g. "revive", "deposit")
- * @validation zod schema
- * @handlerSignature ```ts
- *  (player: Server.Player, args: any[]) => any
- * ```
- */
-function Command(configOrName) {
-    return (target, propertyKey, descriptor) => {
-        const config = typeof configOrName === 'string' ? { command: configOrName } : configOrName;
-        const paramTypes = Reflect.getMetadata('design:paramtypes', target, propertyKey);
-        const metadata = Object.assign(Object.assign({}, config), { methodName: propertyKey, target: target.constructor, paramTypes });
-        Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.COMMAND, metadata, target, propertyKey);
-    };
-}

package/dist/server/decorators/controller.js

@@ -1,36 +0,0 @@
-"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 = [];
-/**
- * Class decorator used to mark a class as a Server Controller.
- *
- * This decorator performs the following actions:
- * 1. Marks the class as `@injectable` (via tsyringe) for dependency injection.
- * 2. Defines metadata identifying the class as a 'server' type controller.
- * 3. Automatically adds the class constructor to the `serverControllerRegistry`.
- *
- * @returns The decorator function to apply to the class.
- *
- * @example
- * ```ts
- * import { Controller } from '@core/server/decorators'
- *
- * @Server.Controller()
- * export class PlayerController {
- *   constructor(private playerService: PlayerService) {
- *     // Dependency injection works automatically here
- *   }
- * }
- * ```
- */
-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/export.d.ts

@@ -1,39 +0,0 @@
-/**
- * Export
- * -----------------------------------------
- * Declares a method as an externally accessible export
- * within the FiveM environment.
- *
- * Methods decorated with `@Export()` are automatically
- * registered by the framework and exposed as native
- * FXServer exports, allowing other resources to call them
- * using:
- *
- *   exports.resourceName.exportName(...)
- *
- * This decorator is typically used inside controller
- * classes, where the framework’s module loader inspects
- * metadata to register commands, events and exports
- * consistently.
- *
- * @param name Optional name to expose. If omitted,
- *             the method name is used.
- *
- * ```ts
- * @Server.Controller()
- * export class AccountController {
- *   @Server.Export('getAccountById')
- *   getAccount(id: string) {
- *     return this.accountService.find(id)
- *   }
- * }
- *
- * // From another resource:
- * // const result = exports['core-resource'].getAccountById('1234')
- *```
- * Internally, this decorator stores metadata used by
- * the server bootstrap to automatically register the
- * export through FXServer's `global.exports` API.
- *
- */
-export declare function Export(name?: string): (target: any, propertyKey: string) => void;

package/dist/server/decorators/export.js

@@ -1,47 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Export = Export;
-const metadata_server_keys_1 = require("../system/metadata-server.keys");
-/**
- * Export
- * -----------------------------------------
- * Declares a method as an externally accessible export
- * within the FiveM environment.
- *
- * Methods decorated with `@Export()` are automatically
- * registered by the framework and exposed as native
- * FXServer exports, allowing other resources to call them
- * using:
- *
- *   exports.resourceName.exportName(...)
- *
- * This decorator is typically used inside controller
- * classes, where the framework’s module loader inspects
- * metadata to register commands, events and exports
- * consistently.
- *
- * @param name Optional name to expose. If omitted,
- *             the method name is used.
- *
- * ```ts
- * @Server.Controller()
- * export class AccountController {
- *   @Server.Export('getAccountById')
- *   getAccount(id: string) {
- *     return this.accountService.find(id)
- *   }
- * }
- *
- * // From another resource:
- * // const result = exports['core-resource'].getAccountById('1234')
- *```
- * Internally, this decorator stores metadata used by
- * the server bootstrap to automatically register the
- * export through FXServer's `global.exports` API.
- *
- */
-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

@@ -1,56 +0,0 @@
-export interface GuardOptions {
-    /**
-     * Minimum rank required to execute the method.
-     * Permissions and Role/Ranks are defined by your Principal Controller
-     */
-    rank?: number;
-    /**
-     * Permission required to execute the method.
-     * Permissions and Role/Ranks are defined by your Principal Controller
-     */
-    permission?: string;
-}
-/**
- * Guard
- * ------------------------------------------------------------
- * Declarative access-control decorator for controller methods.
- *
- * `@Guard()` protects a method by enforcing rank and/or
- * permission requirements before executing it.
- *
- * Requirements are evaluated through the AccessControlService,
- * which determines whether the player (first argument of the
- * method) is authorized to perform the action.
- *
- * Usage of this decorator allows you to express authorization
- * rules directly at the controller level, promoting a clean
- * and explicit security model.
- *
- * @param options GuardOptions
- *   - rank: minimum rank required to execute the method.
- *   - permission: specific permission required.
- *
- * Notes:
- * - The decorated method must receive a `Server.Player`
- *   instance as its first argument.
- * - When compiling improperly (e.g., benchmarks, stripped
- *   decorators), the PropertyDescriptor may be missing.
- *   In that case, only metadata is recorded and execution
- *   fallback is disabled. This should *never* occur in a
- *   production environment.
- *
- * ```ts
- * export class FactionController {
- *   @Server.Guard({ permission: 'factions.manage' })
- *   async createFaction(player: Player, dto: CreateFactionDTO) {
- *     return this.service.create(dto)
- *   }
- *
- *   @Server.Guard({ rank: 3 })
- *   async promoteMember(player: Player, memberID: string) {
- *     return this.service.promote(player, memberID)
- *   }
- * }
- * ```
- */
-export declare function Guard(options: GuardOptions): (target: any, propertyKey: string, descriptor?: PropertyDescriptor) => PropertyDescriptor | undefined;

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

@@ -1,6 +0,0 @@
-/**
- * Listen to FiveM events server-side, check the list below
- *
- * https://docs.fivem.net/docs/scripting-reference/events/server-events/
- */
-export declare function OnFiveMEvent(event: string): (target: any, propertyKey: string) => void;

package/dist/server/decorators/onFiveMEvent.js

@@ -1,14 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.OnFiveMEvent = OnFiveMEvent;
-const metadata_server_keys_1 = require("../system/metadata-server.keys");
-/**
- * Listen to FiveM events server-side, check the list below
- *
- * https://docs.fivem.net/docs/scripting-reference/events/server-events/
- */
-function OnFiveMEvent(event) {
-    return (target, propertyKey) => {
-        Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.FIVEM_EVENT, { event }, target, propertyKey);
-    };
-}

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

@@ -1,22 +0,0 @@
-import type { CoreEventMap } from '../types/core-events';
-/**
- * Method decorator used to register a method as a listener for an internal OpenCore framework event.
- *
- * When the specified framework event is emitted, this method will be automatically triggered
- * with the arguments provided by the event payload.
- *
- * @param event - The name of the core event to listen for (typed strictly to `CoreEventMap`).
- *
- *
- * ```ts
- * @Server.Controller()
- * export class SystemController {
- *
- *   @OnFrameworkEvent('server:ready')
- *   public onServerStart() {
- *     console.log('OpenCore Framework is ready!')
- *   }
- * }
- * ```
- */
-export declare function OnFrameworkEvent<K extends keyof CoreEventMap>(event: K): (target: any, propertyKey: string) => void;

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

@@ -1,58 +0,0 @@
-import type { z } from 'zod';
-import type { Player } from '../entities/player';
-export interface NetEventOptions {
-    eventName: string;
-    schema?: z.ZodType;
-    paramTypes?: any;
-}
-type ServerNetHandler<TArgs extends any[] = any[]> = (player: Player, ...args: TArgs) => any;
-/**
- * Registers a server-side network event handler.
- *
- * The decorated method is invoked when the client triggers
- * `emitNet(eventName, ...)`.
- *
- * ## Player Injection
- * The first argument of the handler **must be `Player`** and is automatically
- * replaced with a `Server.Player` instance representing the client that
- * fired the event. You do NOT need to read `source` manually.
- *
- * ## Auto-Validation
- * Arguments after `Player` are automatically validated based on their TypeScript types:
- * - `string` → `z.string()`
- * - `number` → `z.number()`
- * - `boolean` → `z.boolean()`
- * - `any[]` → `z.array(z.any())` (array content not validated)
- *
- * ## Explicit Schema (Advanced)
- * For stricter validation (ranges, formats, nested objects), provide a Zod schema:
- *
- * @example Auto-validation (simple)
- * ```ts
- * @OnNet("auth:login")
- * handleLogin(player: Player, username: string, password: string) {
- *   // username and password are validated as strings automatically
- * }
- * ```
- *
- * @example Explicit schema (strict validation)
- * ```ts
- * const transferSchema = z.object({
- *   targetId: z.number().positive(),
- *   amount: z.number().min(1).max(1000000),
- * })
- *
- * @OnNet("bank:transfer", { schema: transferSchema })
- * handleTransfer(player: Player, data: z.infer<typeof transferSchema>) {
- *   // data.amount is guaranteed to be between 1 and 1,000,000
- * }
- * ```
- *
- * @param eventName - The network event name to listen for.
- * @param options - Optional configuration object.
- * @param options.schema - Zod schema for strict payload validation.
- */
-export declare function OnNet<TArgs extends any[]>(eventName: string, options?: {
-    schema?: z.ZodType;
-}): <H extends ServerNetHandler<TArgs>>(target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<H>) => void;
-export {};

package/dist/server/decorators/onNet.js

@@ -1,57 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.OnNet = OnNet;
-const metadata_server_keys_1 = require("../system/metadata-server.keys");
-/**
- * Registers a server-side network event handler.
- *
- * The decorated method is invoked when the client triggers
- * `emitNet(eventName, ...)`.
- *
- * ## Player Injection
- * The first argument of the handler **must be `Player`** and is automatically
- * replaced with a `Server.Player` instance representing the client that
- * fired the event. You do NOT need to read `source` manually.
- *
- * ## Auto-Validation
- * Arguments after `Player` are automatically validated based on their TypeScript types:
- * - `string` → `z.string()`
- * - `number` → `z.number()`
- * - `boolean` → `z.boolean()`
- * - `any[]` → `z.array(z.any())` (array content not validated)
- *
- * ## Explicit Schema (Advanced)
- * For stricter validation (ranges, formats, nested objects), provide a Zod schema:
- *
- * @example Auto-validation (simple)
- * ```ts
- * @OnNet("auth:login")
- * handleLogin(player: Player, username: string, password: string) {
- *   // username and password are validated as strings automatically
- * }
- * ```
- *
- * @example Explicit schema (strict validation)
- * ```ts
- * const transferSchema = z.object({
- *   targetId: z.number().positive(),
- *   amount: z.number().min(1).max(1000000),
- * })
- *
- * @OnNet("bank:transfer", { schema: transferSchema })
- * handleTransfer(player: Player, data: z.infer<typeof transferSchema>) {
- *   // data.amount is guaranteed to be between 1 and 1,000,000
- * }
- * ```
- *
- * @param eventName - The network event name to listen for.
- * @param options - Optional configuration object.
- * @param options.schema - Zod schema for strict payload validation.
- */
-function OnNet(eventName, options) {
-    return (target, propertyKey, descriptor) => {
-        const paramTypes = Reflect.getMetadata('design:paramtypes', target, propertyKey);
-        const metadata = { eventName, schema: options === null || options === void 0 ? void 0 : options.schema, paramTypes };
-        Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.NET_EVENT, metadata, target, propertyKey);
-    };
-}

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

@@ -1,32 +0,0 @@
-/**
- * OnTick
- * ------------------------------------------------------------
- * Marks a method to be executed on every server tick.
- *
- * Methods decorated with `@OnTick()` are automatically
- * registered by the framework's scheduler and invoked on each
- * FXServer tick (~ every 0–10 ms depending on workload).
- *
- * This decorator should be used for lightweight recurring
- * logic: status updates, background checks, cleanup tasks,
- * or time-based processes relevant to gameplay.
- *
- * Heavy or blocking operations should be avoided inside tick
- * handlers, as they directly impact global server performance.
- *
- * ```ts
- * export class SyncController {
- *   @OnTick()
- *   updatePlayers() {
- *     // Runs every tick
- *     this.service.syncPositions()
- *   }
- * }
- *
- * ```
- *
- * Internally, the decorator only stores metadata. The
- * server bootstrap scans for this metadata and binds the
- * method to FiveM's tick cycle.
- */
-export declare function OnTick(): (target: any, propertyKey: string) => void;

package/dist/server/decorators/onTick.js

@@ -1,40 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.OnTick = OnTick;
-const metadata_server_keys_1 = require("../system/metadata-server.keys");
-/**
- * OnTick
- * ------------------------------------------------------------
- * Marks a method to be executed on every server tick.
- *
- * Methods decorated with `@OnTick()` are automatically
- * registered by the framework's scheduler and invoked on each
- * FXServer tick (~ every 0–10 ms depending on workload).
- *
- * This decorator should be used for lightweight recurring
- * logic: status updates, background checks, cleanup tasks,
- * or time-based processes relevant to gameplay.
- *
- * Heavy or blocking operations should be avoided inside tick
- * handlers, as they directly impact global server performance.
- *
- * ```ts
- * export class SyncController {
- *   @OnTick()
- *   updatePlayers() {
- *     // Runs every tick
- *     this.service.syncPositions()
- *   }
- * }
- *
- * ```
- *
- * Internally, the decorator only stores metadata. The
- * server bootstrap scans for this metadata and binds the
- * method to FiveM's tick cycle.
- */
-function OnTick() {
-    return (target, propertyKey) => {
-        Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.TICK, {}, target, propertyKey);
-    };
-}

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

@@ -1,27 +0,0 @@
-/**
- * Marks a server-side NetEvent handler as publicly accessible.
- *
- * This decorator disables authentication requirements for the
- * decorated method. It should only be applied to endpoints used for:
- * - Login
- * - Registration
- * - Public information retrieval
- *
- * ## Security Warning
- * This decorator must be used with caution. Public endpoints must NOT
- * modify sensitive game state unless necessary.
- *
- * ## Example
- * ```ts
- * class AuthServerController {
- *   @Public()
- *   @OnNet("auth:login")
- *   async login(player: Server.Player, credentials: AuthCredentials) {
- *     // no authentication required for this event
- *   }
- * }
- * ```
- *
- * @returns Method decorator that marks a handler as unauthenticated.
- */
-export declare function Public(): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;

package/dist/server/decorators/requiresState.js

@@ -1,63 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RequiresState = RequiresState;
-const utils_1 = require("../../utils");
-/**
- * Enforces gameplay state requirements before executing a method.
- *
- * The decorator intercepts the method call and verifies whether
- * the player satisfies required state flags (e.g. "dead", "cuffed",
- * "on_duty_police").
- *
- * ## Whitelist (`has`)
- * The player MUST have *all* required states. Missing any state blocks execution.
- *
- * ## Blacklist (`missing`)
- * The player MUST NOT have any of the forbidden states.
- *
- * ## Error Handling
- * - Throws a normal Error if the method is called without a valid Player.
- * - Throws an `AppError(GAME_STATE_ERROR)` if validation fails.
- *
- * ## Example
- * ```ts
- * @RequiresState({ missing: ["dead", "cuffed"] })
- * openInventory(player: Server.Player) { ... }
- *
- * @RequiresState({
- *   has: ["police_duty"],
- *   missing: ["dead"],
- *   errorMessage: "You must be on duty to access the armory."
- * })
- * openArmory(player: Server.Player) { ... }
- * ```
- *
- * @param req - State validation configuration.
- */
-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

@@ -1,48 +0,0 @@
-import type { SecurityAction } from '../types/security.types';
-interface ThrottleOptions {
-    /**
-     * limit of calls per windowMs
-     */
-    limit: number;
-    /**
-     * time window for numeric overload
-     */
-    windowMs: number;
-    /**
-     * action to perform on exceed limit
-     */
-    onExceed?: SecurityAction;
-    /**
-     * custom message to display on exceed limit (ERROR MESSAGE)
-     */
-    message?: string;
-}
-/**
- * Rate-limits how frequently a method can be called by a specific player.
- *
- * Uses `RateLimiterService` and a unique key composed of:
- * `playerID:ClassName:MethodName`.
- *
- * ## Overload
- * - `@Throttle(5, 1000)` → limit = 5 calls per 1000 ms
- * - `@Throttle({ limit, windowMs, onExceed, message })`
- *
- * ## Behavior
- * If the rate limit is exceeded:
- * - A `SecurityError` is thrown.
- * - Optional custom behavior (`onExceed`) may be executed.
- *
- * ## Example
- * ```ts
- * @Throttle(5, 2000)
- * async search(player: Server.Player, query: string) { ... }
- *
- * @Throttle({ limit: 1, windowMs: 5000, message: "Too fast!" })
- * async placeOrder(player: Server.Player) { ... }
- * ```
- *
- * @param optionsOrLimit - Number (simple mode) or full config object.
- * @param windowMs - Time window for numeric overload.
- */
-export declare function Throttle(optionsOrLimit: number | ThrottleOptions, windowMs?: number): (target: any, propertyKey: string, descriptor?: PropertyDescriptor) => PropertyDescriptor | undefined;
-export {};

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

@@ -1,57 +0,0 @@
-import type { BindingScope } from './bind';
-/**
- * Marks a class as a framework-managed Service.
- *
- * The decorator binds the class into the dependency injection
- * container using the provided scope (default: `singleton`).
- *
- * Services represent reusable, stateless or stateful logic such as:
- * - Business rules
- * - Utility layers
- * - Gameplay systems
- * - Internal modules
- *
- * This decorator is a convenience wrapper over `@Bind()`, allowing
- * future extension of service-specific behavior without changing
- * end-user code.
- *
- * ## Example
- * ```ts
- * @Service()
- * export class InventoryService {
- *   addItem() { ... }
- * }
- * ```
- *
- * @param options.scope - Optional binding scope (`singleton` | `transient`)
- */
-export declare function Service(options?: {
-    scope?: BindingScope;
-}): (target: any) => void;
-/**
- * Marks a class as a Repository within the framework.
- *
- * A Repository abstracts persistence operations (e.g., database,
- * API, in-memory, or hybrid storage). It is registered in the
- * dependency injection container using the provided scope
- * (default: `singleton`).
- *
- * `@Repo()` is intentionally separate from `@Service()` to clearly
- * distinguish persistence-oriented classes from business logic.
- * In the future, repository-specific behavior (caching layers,
- * transactional wrappers, profiling, etc.) can be attached here
- * without modifying user code.
- *
- * ## Example
- * ```ts
- * @Repo()
- * export class AccountRepository {
- *   async findById(id: string) { ... }
- * }
- * ```
- *
- * @param options.scope - Optional binding scope (`singleton` | `transient`)
- */
-export declare function Repo(options?: {
-    scope?: BindingScope;
-}): (target: any) => void;