@open-core/framework 1.0.1-beta.1 → 1.0.2-beta.1

package/dist/server/decorators/onTick.js

@@ -2,6 +2,37 @@
 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,16 +1,27 @@
 /**
- * **Only works on NetEvents in Server-side**
+ * Marks a server-side NetEvent handler as publicly accessible.
  *
- * Marks an endpoint as publicly accessible (no authentication required).
- * Use only for login, register, or public info endpoints.
+ * This decorator disables authentication requirements for the
+ * decorated method. It should only be applied to endpoints used for:
+ * - Login
+ * - Registration
+ * - Public information retrieval
  *
- * @example
+ * ## Security Warning
+ * This decorator must be used with caution. Public endpoints must NOT
+ * modify sensitive game state unless necessary.
+ *
+ * ## Example
  * ```ts
  * class AuthServerController {
- *   @ Server.Public()
- *   @ Server.OnNet('auth:login')
- *   async login(player: Server.Player, credentials: AuthCredentials) { ... }
+ *   @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/public.js

@@ -3,20 +3,31 @@ 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 a server-side NetEvent handler as publicly accessible.
  *
- * Marks an endpoint as publicly accessible (no authentication required).
- * Use only for login, register, or public info endpoints.
+ * This decorator disables authentication requirements for the
+ * decorated method. It should only be applied to endpoints used for:
+ * - Login
+ * - Registration
+ * - Public information retrieval
  *
- * @example
+ * ## Security Warning
+ * This decorator must be used with caution. Public endpoints must NOT
+ * modify sensitive game state unless necessary.
+ *
+ * ## Example
  * ```ts
  * class AuthServerController {
- *   @ Server.Public()
- *   @ Server.OnNet('auth:login')
- *   async login(player: Server.Player, credentials: AuthCredentials) { ... }
+ *   @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.
+ */
 function Public() {
     return function (target, propertyKey, descriptor) {
         Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.PUBLIC, true, target, propertyKey);

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

@@ -22,34 +22,35 @@ export interface StateRequirement {
     errorMessage?: string;
 }
 /**
- * **Game State Guard Decorator**
+ * Enforces gameplay state requirements before executing a method.
  *
- * 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.
+ * The decorator intercepts the method call and verifies whether
+ * the player satisfies required state flags (e.g. "dead", "cuffed",
+ * "on_duty_police").
  *
- * @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.
+ * ## Whitelist (`has`)
+ * The player MUST have *all* required states. Missing any state blocks execution.
  *
- * @param req - The state requirements configuration (whitelist and/or blacklist).
+ * ## Blacklist (`missing`)
+ * The player MUST NOT have any of the forbidden states.
  *
- * @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).
+ * ## 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
+ * ## Example
  * ```ts
- * // Example 1: Action requires being alive (not dead) and not handcuffed
- * @RequiresState({ missing: ['dead', 'cuffed'] })
+ * @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.'
+ *   has: ["police_duty"],
+ *   missing: ["dead"],
+ *   errorMessage: "You must be on duty to access the armory."
  * })
  * openArmory(player: Server.Player) { ... }
  * ```
+ *
+ * @param req - State validation configuration.
  */
 export declare function RequiresState(req: StateRequirement): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;

package/dist/server/decorators/requiresState.js

@@ -3,35 +3,36 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RequiresState = RequiresState;
 const utils_1 = require("../../utils");
 /**
- * **Game State Guard Decorator**
+ * Enforces gameplay state requirements before executing a method.
  *
- * 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.
+ * The decorator intercepts the method call and verifies whether
+ * the player satisfies required state flags (e.g. "dead", "cuffed",
+ * "on_duty_police").
  *
- * @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.
+ * ## Whitelist (`has`)
+ * The player MUST have *all* required states. Missing any state blocks execution.
  *
- * @param req - The state requirements configuration (whitelist and/or blacklist).
+ * ## Blacklist (`missing`)
+ * The player MUST NOT have any of the forbidden states.
  *
- * @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).
+ * ## 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
+ * ## Example
  * ```ts
- * // Example 1: Action requires being alive (not dead) and not handcuffed
- * @RequiresState({ missing: ['dead', 'cuffed'] })
+ * @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.'
+ *   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) {

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

@@ -1,9 +1,48 @@
 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/throttle.js

@@ -4,6 +4,33 @@ exports.Throttle = Throttle;
 const tsyringe_1 = require("tsyringe");
 const rate_limiter_service_1 = require("../services/rate-limiter.service");
 const utils_1 = require("../../utils");
+/**
+ * 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.
+ */
 function Throttle(optionsOrLimit, windowMs) {
     return function (target, propertyKey, descriptor) {
         if (!descriptor) {

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

@@ -1,7 +1,57 @@
 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;

package/dist/server/decorators/utils.js

@@ -3,10 +3,60 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Service = Service;
 exports.Repo = Repo;
 const bind_1 = require("./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`)
+ */
 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');
 }
+/**
+ * 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`)
+ */
 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/error-handler.js

@@ -14,8 +14,8 @@ function normalizeError(error, origin) {
 }
 function handleCommandError(error, meta, playerId) {
     const appError = normalizeError(error, 'server');
-    logger_1.loggers.command.error(`Command execution failed: /${meta.name}`, {
-        command: meta.name,
+    logger_1.loggers.command.error(`Command execution failed: /${meta.command}`, {
+        command: meta.command,
         handler: meta.methodName,
         playerId,
         code: appError.code,

package/dist/server/services/command.service.d.ts

@@ -8,7 +8,7 @@ export declare class CommandService {
     register(meta: CommandMetadata, handler: Function): void;
     execute(player: Server.Player, commandName: string, args: string[], raw: string): Promise<void>;
     getAllCommands(): {
-        name: string;
+        command: string;
         description: string;
         usage: string;
     }[];

package/dist/server/services/command.service.js

@@ -18,26 +18,29 @@ const utils_1 = require("../../utils");
 const zod_1 = __importDefault(require("zod"));
 const security_handler_contract_1 = require("../templates/security/security-handler.contract");
 const logger_1 = require("../../shared/logger");
+const schema_generator_1 = require("../system/schema-generator");
 let CommandService = class CommandService {
     constructor(securityHandler) {
         this.securityHandler = securityHandler;
         this.commands = new Map();
     }
     register(meta, handler) {
-        this.commands.set(meta.name.toLowerCase(), { meta, handler });
-        logger_1.loggers.command.debug(`Registered: /${meta.name}${meta.schema ? ' [Validated]' : ''}`);
+        this.commands.set(meta.command.toLowerCase(), { meta, handler });
+        logger_1.loggers.command.debug(`Registered: /${meta.command}${meta.schema ? ' [Validated]' : ''}`);
     }
     async execute(player, commandName, args, raw) {
+        var _a;
         const entry = this.commands.get(commandName.toLowerCase());
         if (!entry) {
             return;
         }
         const { meta, handler } = entry;
         let validatedArgs = args;
-        if (meta.schema) {
+        // Use explicit schema or auto-generate from paramTypes
+        const schema = (_a = meta.schema) !== null && _a !== void 0 ? _a : (0, schema_generator_1.generateSchemaFromTypes)(meta.paramTypes);
+        if (schema) {
             try {
-                const result = await meta.schema.parseAsync(args);
-                validatedArgs = Array.isArray(result) ? result : [result];
+                validatedArgs = await schema.parseAsync(args);
             }
             catch (error) {
                 if (error instanceof zod_1.default.ZodError) {
@@ -60,7 +63,7 @@ let CommandService = class CommandService {
         return Array.from(this.commands.values()).map((c) => {
             var _a, _b;
             return ({
-                name: c.meta.name,
+                command: c.meta.command,
                 description: (_a = c.meta.description) !== null && _a !== void 0 ? _a : '',
                 usage: (_b = c.meta.usage) !== null && _b !== void 0 ? _b : '',
             });

package/dist/server/system/processors/command.processor.d.ts

@@ -1,9 +1,9 @@
 import { DecoratorProcessor } from '../../../system/decorator-processor';
 import { CommandService } from '../../services';
-import { CommandConfig } from '../../decorators';
+import { CommandMetadata } from '../../decorators/command';
 export declare class CommandProcessor implements DecoratorProcessor {
     private commandService;
     readonly metadataKey: string;
     constructor(commandService: CommandService);
-    process(target: any, methodName: string, metadata: CommandConfig): void;
+    process(target: any, methodName: string, metadata: CommandMetadata): void;
 }

package/dist/server/system/processors/command.processor.js

@@ -20,8 +20,7 @@ let CommandProcessor = class CommandProcessor {
     }
     process(target, methodName, metadata) {
         const handler = target[methodName].bind(target);
-        const fullMeta = Object.assign(Object.assign({}, metadata), { methodName, target: target.constructor });
-        this.commandService.register(fullMeta, handler);
+        this.commandService.register(metadata, handler);
     }
 };
 exports.CommandProcessor = CommandProcessor;

package/dist/server/system/processors/netEvent.processor.js

@@ -20,6 +20,7 @@ const security_handler_contract_1 = require("../../templates/security/security-h
 const utils_1 = require("../../../utils");
 const logger_1 = require("../../../shared/logger");
 const zod_1 = __importDefault(require("zod"));
+const schema_generator_1 = require("../schema-generator");
 let NetEventProcessor = class NetEventProcessor {
     constructor(playerService, securityHandler) {
         this.playerService = playerService;
@@ -53,11 +54,11 @@ let NetEventProcessor = class NetEventProcessor {
                 return;
             }
             let validatedArgs = args;
-            if (metadata.schema) {
+            const schema = (0, schema_generator_1.generateSchemaFromTypes)(metadata.paramTypes);
+            if (schema) {
                 try {
-                    const payload = args[0];
-                    const parsed = metadata.schema.parse(payload);
-                    validatedArgs = [parsed];
+                    const parsed = schema.parse(args);
+                    validatedArgs = Array.isArray(parsed) ? parsed : [parsed];
                 }
                 catch (error) {
                     if (error instanceof zod_1.default.ZodError) {

package/dist/server/system/schema-generator.d.ts

@@ -0,0 +1,2 @@
+import z from 'zod';
+export declare function generateSchemaFromTypes(paramTypes: any[]): z.ZodTuple | null;

package/dist/server/system/schema-generator.js

@@ -0,0 +1,28 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSchemaFromTypes = generateSchemaFromTypes;
+const zod_1 = __importDefault(require("zod"));
+const player_1 = require("../entities/player");
+function typeToZodSchema(type) {
+    switch (type) {
+        case String: return zod_1.default.coerce.string();
+        case Number: return zod_1.default.coerce.number();
+        case Boolean: return zod_1.default.coerce.boolean();
+        case Array: return zod_1.default.array(zod_1.default.any());
+        case Object: return zod_1.default.any();
+        default: return zod_1.default.any();
+    }
+}
+function generateSchemaFromTypes(paramTypes) {
+    var _a;
+    if (!paramTypes || paramTypes.length <= 1)
+        return null;
+    if (paramTypes[0] !== player_1.Player) {
+        throw new Error(`@OnNet: First parameter must be Player, got ${(_a = paramTypes[0]) === null || _a === void 0 ? void 0 : _a.name}`);
+    }
+    const argSchemas = paramTypes.slice(1).map(typeToZodSchema);
+    return zod_1.default.tuple(argSchemas);
+}

package/dist/server/templates/admin/admin.controller-template.d.ts

@@ -1,10 +1,12 @@
-import type { Server } from '../../..';
+import { Player } from "../../entities";
+type CommandArgs = string[] | any;
 /**
  * Template for admin controller implementations.
  */
 export interface AdminControllerTemplate {
-    handleBanCommand(player: Server.Player, args: string[], raw?: string): Promise<void>;
-    handleKickCommand(player: Server.Player, args: string[], raw?: string): Promise<void>;
-    handleMuteCommand(player: Server.Player, args: string[], raw?: string): Promise<void>;
-    handleUnmuteCommand(player: Server.Player, args: string[], raw?: string): Promise<void>;
+    handleBanCommand(player: Player, args: CommandArgs, raw?: string): Promise<void>;
+    handleKickCommand(player: Player, args: CommandArgs, raw?: string): Promise<void>;
+    handleMuteCommand(player: Player, args: CommandArgs, raw?: string): Promise<void>;
+    handleUnmuteCommand(player: Player, args: CommandArgs, raw?: string): Promise<void>;
 }
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-core/framework",
-  "version": "1.0.1-beta.1",
+  "version": "1.0.2-beta.1",
   "description": "Secure, Event-Driven, OOP Engine for FiveM. Stop scripting, start engineering.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,6 +18,24 @@
     "README.md",
     "LICENSE"
   ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js",
+      "require": "./dist/server/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js",
+      "require": "./dist/client/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "watch": "tsc -p tsconfig.build.json --watch",