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

package/dist/{server → runtime/server}/decorators/index.js

@@ -16,14 +16,17 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Controller = exports.Command = void 0;
 __exportStar(require("./bind"), exports);
-__exportStar(require("./utils"), exports);
 var command_1 = require("./command");
 Object.defineProperty(exports, "Command", { enumerable: true, get: function () { return command_1.Command; } });
-__exportStar(require("./onFrameworkEvent"), exports);
-__exportStar(require("./onNet"), exports);
-__exportStar(require("./onTick"), exports);
 var controller_1 = require("./controller");
 Object.defineProperty(exports, "Controller", { enumerable: true, get: function () { return controller_1.Controller; } });
-__exportStar(require("./throttle"), exports);
+__exportStar(require("./export"), exports);
 __exportStar(require("./guard"), exports);
+__exportStar(require("./onFiveMEvent"), exports);
+__exportStar(require("./onFrameworkEvent"), exports);
+__exportStar(require("./onNet"), exports);
+__exportStar(require("./onTick"), exports);
+__exportStar(require("./public"), exports);
 __exportStar(require("./requiresState"), exports);
+__exportStar(require("./throttle"), exports);
+__exportStar(require("./utils"), exports);

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

@@ -0,0 +1,24 @@
+/**
+ * Registers a method as a server-side listener for a native FiveM event.
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework scans controller
+ * methods and binds handlers to FiveM events.
+ *
+ * FiveM server event reference:
+ * https://docs.fivem.net/docs/scripting-reference/events/server-events/
+ *
+ * @param event - FiveM event name (e.g. `"playerJoining"`).
+ *
+ * @example
+ * ```ts
+ * @Server.Controller()
+ * export class SessionController {
+ *   @Server.OnFiveMEvent('playerJoining')
+ *   onPlayerJoining() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function OnFiveMEvent(event: string): (target: any, propertyKey: string) => void;

package/dist/runtime/server/decorators/onFiveMEvent.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OnFiveMEvent = OnFiveMEvent;
+const metadata_server_keys_1 = require("../system/metadata-server.keys");
+/**
+ * Registers a method as a server-side listener for a native FiveM event.
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework scans controller
+ * methods and binds handlers to FiveM events.
+ *
+ * FiveM server event reference:
+ * https://docs.fivem.net/docs/scripting-reference/events/server-events/
+ *
+ * @param event - FiveM event name (e.g. `"playerJoining"`).
+ *
+ * @example
+ * ```ts
+ * @Server.Controller()
+ * export class SessionController {
+ *   @Server.OnFiveMEvent('playerJoining')
+ *   onPlayerJoining() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+function OnFiveMEvent(event) {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.FIVEM_EVENT, { event }, target, propertyKey);
+    };
+}

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

@@ -0,0 +1,22 @@
+import { CoreEventMap } from '../types/core-events';
+/**
+ * Registers a method as a listener for an internal OpenCore framework event.
+ *
+ * @remarks
+ * This decorator only stores metadata. The framework binds listeners during bootstrap by scanning
+ * controller methods.
+ *
+ * @param event - Core event name, strongly typed to {@link CoreEventMap}.
+ *
+ * @example
+ * ```ts
+ * @Server.Controller()
+ * export class SystemController {
+ *   @Server.OnFrameworkEvent('server:ready')
+ *   onServerReady() {
+ *     console.log('OpenCore framework is ready')
+ *   }
+ * }
+ * ```
+ */
+export declare function OnFrameworkEvent<K extends keyof CoreEventMap>(event: K): (target: any, propertyKey: string) => void;

package/dist/{server → runtime/server}/decorators/onFrameworkEvent.js

@@ -3,21 +3,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OnFrameworkEvent = OnFrameworkEvent;
 const metadata_server_keys_1 = require("../system/metadata-server.keys");
 /**
- * Method decorator used to register a method as a listener for an internal OpenCore framework event.
+ * Registers 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`).
+ * @remarks
+ * This decorator only stores metadata. The framework binds listeners during bootstrap by scanning
+ * controller methods.
  *
+ * @param event - Core event name, strongly typed to {@link CoreEventMap}.
  *
+ * @example
  * ```ts
  * @Server.Controller()
  * export class SystemController {
- *
- *   @OnFrameworkEvent('server:ready')
- *   public onServerStart() {
- *     console.log('OpenCore Framework is ready!')
+ *   @Server.OnFrameworkEvent('server:ready')
+ *   onServerReady() {
+ *     console.log('OpenCore framework is ready')
  *   }
  * }
  * ```

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

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+export interface NetEventOptions {
+    /**
+     * The network event name to register.
+     */
+    eventName: string;
+    /**
+     * Zod schema for payload validation.
+     * - `z.tuple([...])`: validates all positional args.
+     * - otherwise: expects exactly 1 arg and validates `args[0]` (DTO payload pattern).
+     */
+    schema?: z.ZodType;
+    /**
+     * Runtime parameter types for auto-validation.
+     */
+    paramTypes: any;
+}
+/**
+ * Registers a method as a server-side network event handler.
+ *
+ * @remarks
+ * Rules:
+ * - First parameter must be `Player` (injected from the caller).
+ *
+ * Validation:
+ * - If schema is provided:
+ *   - `z.tuple([...])` validates all positional args.
+ *   - otherwise: expects exactly 1 arg and validates `args[0]` (DTO payload pattern).
+ * - If schema is omitted, only primitive args can be auto-validated from runtime param types
+ *   (`string|number|boolean|any[]`). Complex payloads should use an explicit schema.
+ *
+ * Authentication:
+ * - Handlers are typically protected by the framework's net-event security layer.
+ * - Use {@link Public} to explicitly mark a handler as unauthenticated.
+ *
+ * @param eventName - Network event name.
+ * @param schemaOrOptions - Zod schema directly, or options object with schema property.
+ *
+ * @example
+ * ```ts
+ * import { z, Infer } from '@open-core/framework'
+ *
+ * const PayloadSchema = z.object({ message: z.string() })
+ *
+ * @Server.Controller()
+ * export class ExampleController {
+ *   // Simple handler (no schema)
+ *   @Server.OnNet('example:ping')
+ *   ping(player: Player, message: string) { }
+ *
+ *   // With schema directly (recommended)
+ *   @Server.OnNet('example:data', PayloadSchema)
+ *   handleData(player: Player, data: Infer<typeof PayloadSchema>) { }
+ *
+ *   // With options object (legacy)
+ *   @Server.OnNet('example:legacy', { schema: PayloadSchema })
+ *   handleLegacy(player: Player, data: Infer<typeof PayloadSchema>) { }
+ * }
+ * ```
+ */
+export declare function OnNet<_TArgs extends any[]>(eventName: string, schema: z.ZodType): MethodDecorator;
+export declare function OnNet<_TArgs extends any[]>(eventName: string, options?: Pick<NetEventOptions, 'schema'>): MethodDecorator;

package/dist/runtime/server/decorators/onNet.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OnNet = OnNet;
+const zod_1 = require("zod");
+const metadata_server_keys_1 = require("../system/metadata-server.keys");
+// Implementation
+function OnNet(eventName, schemaOrOptions) {
+    return (target, propertyKey, _descriptor) => {
+        const paramTypes = Reflect.getMetadata('design:paramtypes', target, propertyKey);
+        // Detect if second arg is a Zod schema or an options object
+        const schema = schemaOrOptions instanceof zod_1.z.ZodType ? schemaOrOptions : schemaOrOptions === null || schemaOrOptions === void 0 ? void 0 : schemaOrOptions.schema;
+        const metadata = { eventName, schema, paramTypes };
+        Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.NET_EVENT, metadata, target, propertyKey);
+    };
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Registers a method to be executed on every server tick.
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds tick handlers to the
+ * FiveM tick cycle.
+ *
+ * Tick handlers should be lightweight and non-blocking.
+ *
+ * @example
+ * ```ts
+ * @Server.Controller()
+ * export class SyncController {
+ *   @Server.OnTick()
+ *   updatePlayers() {
+ *     this.service.syncPositions()
+ *   }
+ * }
+ * ```
+ */
+export declare function OnTick(): (target: any, propertyKey: string) => void;

package/dist/runtime/server/decorators/onTick.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OnTick = OnTick;
+const metadata_server_keys_1 = require("../system/metadata-server.keys");
+/**
+ * Registers a method to be executed on every server tick.
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds tick handlers to the
+ * FiveM tick cycle.
+ *
+ * Tick handlers should be lightweight and non-blocking.
+ *
+ * @example
+ * ```ts
+ * @Server.Controller()
+ * export class SyncController {
+ *   @Server.OnTick()
+ *   updatePlayers() {
+ *     this.service.syncPositions()
+ *   }
+ * }
+ * ```
+ */
+function OnTick() {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.TICK, {}, target, propertyKey);
+    };
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Marks a server-side net-event handler as publicly accessible.
+ *
+ * @remarks
+ * This decorator disables authentication requirements for the decorated method.
+ * It is intended to be used together with {@link OnNet}.
+ *
+ * Security warning:
+ * - Use with caution.
+ * - Public endpoints should not mutate sensitive game state unless strictly necessary.
+ *
+ * @returns Method decorator that marks a handler as unauthenticated.
+ *
+ * @example
+ * ```ts
+ * @Server.Controller()
+ * export class AuthController {
+ *   @Server.Public()
+ *   @Server.OnNet('auth:login')
+ *   async login(player: Server.Player, credentials: AuthCredentials) {
+ *     // no authentication required for this event
+ *   }
+ * }
+ * ```
+ */
+export declare function Public(): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;

package/dist/{server → runtime/server}/decorators/public.js

@@ -3,33 +3,32 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Public = Public;
 const metadata_server_keys_1 = require("../system/metadata-server.keys");
 /**
- * Marks a server-side NetEvent handler as publicly accessible.
+ * Marks a server-side net-event 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
+ * @remarks
+ * This decorator disables authentication requirements for the decorated method.
+ * It is intended to be used together with {@link OnNet}.
  *
- * ## Security Warning
- * This decorator must be used with caution. Public endpoints must NOT
- * modify sensitive game state unless necessary.
+ * Security warning:
+ * - Use with caution.
+ * - Public endpoints should not mutate sensitive game state unless strictly necessary.
  *
- * ## Example
+ * @returns Method decorator that marks a handler as unauthenticated.
+ *
+ * @example
  * ```ts
- * class AuthServerController {
- *   @Public()
- *   @OnNet("auth:login")
+ * @Server.Controller()
+ * export class AuthController {
+ *   @Server.Public()
+ *   @Server.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) {
+    return (target, propertyKey, descriptor) => {
         Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.PUBLIC, true, target, propertyKey);
         return descriptor;
     };

package/dist/{server → runtime/server}/decorators/requiresState.d.ts

@@ -6,7 +6,7 @@ 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']
+     * @example ['on_duty', 'in_vehicle']
      */
     has?: string[];
     /**
@@ -24,33 +24,40 @@ export interface StateRequirement {
 /**
  * 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").
+ * @remarks
+ * The decorator wraps the original method 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.
+ * Rules:
+ * - The decorated method must receive a `Server.Player` instance as its first argument.
  *
- * ## Blacklist (`missing`)
- * The player MUST NOT have any of the forbidden states.
+ * Validation:
+ * - `req.has`: the player must have *all* of these states.
+ * - `req.missing`: the player must have *none* of these 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.
+ * @param req - State validation configuration.
+ *
+ * @throws Error - If the method is invoked without a `Player` as the first argument.
+ * @throws AppError - If the player does not satisfy the configured requirements.
  *
- * ## Example
+ * @example
  * ```ts
- * @RequiresState({ missing: ["dead", "cuffed"] })
- * openInventory(player: Server.Player) { ... }
+ * @Server.Controller()
+ * export class InventoryController {
+ *   @Server.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) { ... }
+ *   @Server.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.
  */
 export declare function RequiresState(req: StateRequirement): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;

package/dist/runtime/server/decorators/requiresState.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequiresState = RequiresState;
+const utils_1 = require("../../../kernel/utils");
+const metadata_server_keys_1 = require("../system/metadata-server.keys");
+/**
+ * Enforces gameplay state requirements before executing a method.
+ *
+ * @remarks
+ * The decorator wraps the original method and verifies whether the player satisfies required
+ * state flags (e.g. `dead`, `cuffed`, `on_duty_police`).
+ *
+ * Rules:
+ * - The decorated method must receive a `Server.Player` instance as its first argument.
+ *
+ * Validation:
+ * - `req.has`: the player must have *all* of these states.
+ * - `req.missing`: the player must have *none* of these states.
+ *
+ * @param req - State validation configuration.
+ *
+ * @throws Error - If the method is invoked without a `Player` as the first argument.
+ * @throws AppError - If the player does not satisfy the configured requirements.
+ *
+ * @example
+ * ```ts
+ * @Server.Controller()
+ * export class InventoryController {
+ *   @Server.RequiresState({ missing: ['dead', 'cuffed'] })
+ *   openInventory(player: Server.Player) {
+ *     // ...
+ *   }
+ *
+ *   @Server.RequiresState({
+ *     has: ['police_duty'],
+ *     missing: ['dead'],
+ *     errorMessage: 'You must be on duty to access the armory.',
+ *   })
+ *   openArmory(player: Server.Player) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+function RequiresState(req) {
+    return (target, propertyKey, descriptor) => {
+        const originalMethod = descriptor.value;
+        // Store metadata for remote transmission
+        Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.REQUIRES_STATE, req, target, propertyKey);
+        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:INVALID_STATE', 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:INVALID_STATE', req.errorMessage || `You can't do this while you're [${state}].`, 'client');
+                    }
+                }
+            }
+            return originalMethod.apply(this, args);
+        };
+        return descriptor;
+    };
+}

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

@@ -0,0 +1,56 @@
+import { SecurityAction } from '../types/security.types';
+export 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.
+ *
+ * @remarks
+ * Uses {@link RateLimiterService} with a key composed of:
+ * `clientId:ClassName:MethodName`.
+ *
+ * Overloads:
+ * - `@Throttle(5, 1000)` → 5 calls per 1000 ms
+ * - `@Throttle({ limit, windowMs, onExceed, message })`
+ *
+ * Behavior:
+ * - If the rate limit is exceeded, a {@link SecurityError} is thrown.
+ * - If the method is called without a valid `Player` context (first argument), the limiter is skipped.
+ *
+ * @param optionsOrLimit - Number (simple overload) or full config object.
+ * @param windowMs - Time window for the numeric overload.
+ *
+ * @throws SecurityError - When the rate limit is exceeded.
+ *
+ * @example
+ * ```ts
+ * @Server.Controller()
+ * export class MarketController {
+ *   @Server.Throttle(5, 2000)
+ *   async search(player: Server.Player, query: string) {
+ *     // ...
+ *   }
+ *
+ *   @Server.Throttle({ limit: 1, windowMs: 5000, message: 'Too fast!' })
+ *   async placeOrder(player: Server.Player) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function Throttle(optionsOrLimit: number | ThrottleOptions, windowMs?: number): (target: any, propertyKey: string, descriptor?: PropertyDescriptor) => PropertyDescriptor | undefined;

package/dist/{server → runtime/server}/decorators/throttle.js

@@ -2,37 +2,47 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Throttle = Throttle;
 const tsyringe_1 = require("tsyringe");
+const security_error_1 = require("../../../kernel/utils/error/security.error");
 const rate_limiter_service_1 = require("../services/rate-limiter.service");
-const utils_1 = require("../../utils");
+const metadata_server_keys_1 = require("../system/metadata-server.keys");
 /**
  * Rate-limits how frequently a method can be called by a specific player.
  *
- * Uses `RateLimiterService` and a unique key composed of:
- * `playerID:ClassName:MethodName`.
+ * @remarks
+ * Uses {@link RateLimiterService} with a key composed of:
+ * `clientId:ClassName:MethodName`.
  *
- * ## Overload
- * - `@Throttle(5, 1000)` → limit = 5 calls per 1000 ms
+ * Overloads:
+ * - `@Throttle(5, 1000)` → 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.
+ * Behavior:
+ * - If the rate limit is exceeded, a {@link SecurityError} is thrown.
+ * - If the method is called without a valid `Player` context (first argument), the limiter is skipped.
  *
- * ## Example
+ * @param optionsOrLimit - Number (simple overload) or full config object.
+ * @param windowMs - Time window for the numeric overload.
+ *
+ * @throws SecurityError - When the rate limit is exceeded.
+ *
+ * @example
  * ```ts
- * @Throttle(5, 2000)
- * async search(player: Server.Player, query: string) { ... }
+ * @Server.Controller()
+ * export class MarketController {
+ *   @Server.Throttle(5, 2000)
+ *   async search(player: Server.Player, query: string) {
+ *     // ...
+ *   }
  *
- * @Throttle({ limit: 1, windowMs: 5000, message: "Too fast!" })
- * async placeOrder(player: Server.Player) { ... }
+ *   @Server.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) {
+    return (target, propertyKey, descriptor) => {
         if (!descriptor) {
             // In benchmarks or edge cases, skip method wrapping
             // This should NOT happen in production code with proper TypeScript compilation
@@ -47,13 +57,15 @@ function Throttle(optionsOrLimit, windowMs) {
         else {
             opts = Object.assign({ onExceed: 'LOG' }, optionsOrLimit);
         }
+        // Store metadata for remote transmission
+        Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.THROTTLE, opts, target, propertyKey);
         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 });
+                    throw new security_error_1.SecurityError(opts.onExceed, opts.message || `Rate limit exceeded on ${propertyKey}`, { limit: opts.limit, key });
                 }
             }
             return originalMethod.apply(this, args);