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

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

@@ -0,0 +1,78 @@
+import z from 'zod';
+import { Player } from '../entities';
+/**
+ * Metadata stored by {@link OnRPC}.
+ *
+ * @remarks
+ * The framework reads this metadata through {@link OnRpcProcessor} and registers
+ * the handler into the active {@link RpcAPI} transport.
+ */
+export type RpcHandlerOptions = {
+    /** RPC event name */
+    eventName: string;
+    /** Optional Zod schema used to validate incoming args */
+    schema?: z.ZodType;
+    /** Runtime reflection metadata from TypeScript (design:paramtypes) */
+    paramTypes?: unknown[];
+};
+/**
+ * Server-side RPC handler signature.
+ *
+ * @remarks
+ * You may declare the first parameter as {@link Player} if you need session
+ * context in the handler. You can also declare no parameters at all.
+ */
+type ServerNetHandlerRPC<TArgs extends any[] = any[]> = ((player: Player, ...args: TArgs) => Promise<any>) | (() => Promise<any>);
+type RpcHandlerSignatureError = '❌ @OnRPC handlers must be async and return a Promise';
+type EnsureValidRpcHandler<T> = T extends (...args: any[]) => Promise<any> ? T : RpcHandlerSignatureError;
+/**
+ * Register an RPC handler.
+ *
+ * @remarks
+ * Server-only decorator.
+ *
+ * - Server: the handler can be called by clients.
+ * - Client: use `Client.OnRPC()` (client runtime) instead.
+ *
+ * This decorator only registers metadata. The actual wiring happens inside
+ * {@link OnRpcProcessor} (server runtime).
+ *
+ * ## Signature options
+ * - Empty handler: `()`
+ * - With player context: `(player: Player, ...args)`
+ *
+ * If arguments are declared, the first must be {@link Player}. Remaining args
+ * come from the RPC payload.
+ *
+ * ## Validation
+ * You should provide a Zod schema whenever args are not trivially serializable.
+ * If schema is omitted, the framework may attempt to auto-generate one from
+ * reflected types.
+ *
+ * - Tuple schema: use when the RPC sends multiple positional arguments.
+ * - Object schema: use when the RPC sends a single DTO.
+ *
+ * ## Security
+ * Unless the method is marked with `@Public()`, the framework will block the
+ * request if the player is not authenticated (no `accountID`).
+ *
+ * @example Tuple args
+ * ```ts
+ * @OnRPC('inventory:get', z.tuple([z.string(), z.number().int()]))
+ * async getInventory(player: Player, itemType: string, page: number) {
+ *   ...
+ * }
+ * ```
+ *
+ * @example Single DTO arg
+ * ```ts
+ * const CreateVehicleDto = z.object({ model: z.string(), color: z.string() })
+ *
+ * @OnRPC('vehicles:create', CreateVehicleDto)
+ * async createVehicle(player: Player, dto: z.infer<typeof CreateVehicleDto>) {
+ *   ...
+ * }
+ * ```
+ */
+export declare function OnRPC<TArgs extends any[]>(eventName: string, schemaOrOptions?: z.ZodType | Pick<RpcHandlerOptions, 'schema'>): <H extends EnsureValidRpcHandler<ServerNetHandlerRPC<TArgs>>>(target: any, propertyKey: string, _descriptor: TypedPropertyDescriptor<H>) => void;
+export {};

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

@@ -0,0 +1,59 @@
+import z from 'zod';
+import { METADATA_KEYS } from '../system/metadata-server.keys';
+/**
+ * Register an RPC handler.
+ *
+ * @remarks
+ * Server-only decorator.
+ *
+ * - Server: the handler can be called by clients.
+ * - Client: use `Client.OnRPC()` (client runtime) instead.
+ *
+ * This decorator only registers metadata. The actual wiring happens inside
+ * {@link OnRpcProcessor} (server runtime).
+ *
+ * ## Signature options
+ * - Empty handler: `()`
+ * - With player context: `(player: Player, ...args)`
+ *
+ * If arguments are declared, the first must be {@link Player}. Remaining args
+ * come from the RPC payload.
+ *
+ * ## Validation
+ * You should provide a Zod schema whenever args are not trivially serializable.
+ * If schema is omitted, the framework may attempt to auto-generate one from
+ * reflected types.
+ *
+ * - Tuple schema: use when the RPC sends multiple positional arguments.
+ * - Object schema: use when the RPC sends a single DTO.
+ *
+ * ## Security
+ * Unless the method is marked with `@Public()`, the framework will block the
+ * request if the player is not authenticated (no `accountID`).
+ *
+ * @example Tuple args
+ * ```ts
+ * @OnRPC('inventory:get', z.tuple([z.string(), z.number().int()]))
+ * async getInventory(player: Player, itemType: string, page: number) {
+ *   ...
+ * }
+ * ```
+ *
+ * @example Single DTO arg
+ * ```ts
+ * const CreateVehicleDto = z.object({ model: z.string(), color: z.string() })
+ *
+ * @OnRPC('vehicles:create', CreateVehicleDto)
+ * async createVehicle(player: Player, dto: z.infer<typeof CreateVehicleDto>) {
+ *   ...
+ * }
+ * ```
+ */
+export function OnRPC(eventName, schemaOrOptions) {
+    return (target, propertyKey, _descriptor) => {
+        const paramTypes = Reflect.getMetadata('design:paramtypes', target, propertyKey);
+        const schema = schemaOrOptions instanceof z.ZodType ? schemaOrOptions : schemaOrOptions?.schema;
+        const metadata = { eventName, schema, paramTypes };
+        Reflect.defineMetadata(METADATA_KEYS.NET_RPC, metadata, target, propertyKey);
+    };
+}

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

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

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

@@ -0,0 +1,30 @@
+import { METADATA_KEYS } from '../system/metadata-server.keys';
+/**
+ * Registers a method as a server-side listener for a native Runtime event.
+ * Runtime === CitizenFX (Cfx)
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework scans controller
+ * methods and binds handlers to runtime events.
+ *
+ * CitizenFX server event reference:
+ * https://docs.fivem.net/docs/scripting-reference/events/server-events/
+ *
+ * @param event - event name (e.g. `"playerJoining"`). Runtime events
+ *
+ * @example
+ * ```ts
+ * @Server.Controller()
+ * export class SessionController {
+ *   @Server.OnRuntimeEvent('playerJoining')
+ *   onPlayerJoining() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export function OnRuntimeEvent(event) {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(METADATA_KEYS.RUNTIME_EVENT, { event }, 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,26 @@
+import { METADATA_KEYS } from '../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()
+ *   }
+ * }
+ * ```
+ */
+export function OnTick() {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(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/runtime/server/decorators/public.js

@@ -0,0 +1,32 @@
+import { METADATA_KEYS } from '../system/metadata-server.keys';
+/**
+ * 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 function Public() {
+    return (target, propertyKey, descriptor) => {
+        Reflect.defineMetadata(METADATA_KEYS.PUBLIC, true, target, propertyKey);
+        return descriptor;
+    };
+}

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

@@ -0,0 +1,63 @@
+/**
+ * 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', '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;
+}
+/**
+ * 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 `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: Player) {
+ *     // ...
+ *   }
+ *
+ *   @Server.RequiresState({
+ *     has: ['police_duty'],
+ *     missing: ['dead'],
+ *     errorMessage: 'You must be on duty to access the armory.',
+ *   })
+ *   openArmory(player: Player) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function RequiresState(req: StateRequirement): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;

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

@@ -0,0 +1,70 @@
+import { AppError } from '../../../kernel/error/app.error';
+import { METADATA_KEYS } from '../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 `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: Player) {
+ *     // ...
+ *   }
+ *
+ *   @Server.RequiresState({
+ *     has: ['police_duty'],
+ *     missing: ['dead'],
+ *     errorMessage: 'You must be on duty to access the armory.',
+ *   })
+ *   openArmory(player: Player) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export function RequiresState(req) {
+    return (target, propertyKey, descriptor) => {
+        const originalMethod = descriptor.value;
+        // Store metadata for remote transmission
+        Reflect.defineMetadata(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 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 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 '../../../kernel/error/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: Player, query: string) {
+ *     // ...
+ *   }
+ *
+ *   @Server.Throttle({ limit: 1, windowMs: 5000, message: 'Too fast!' })
+ *   async placeOrder(player: Player) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function Throttle(optionsOrLimit: number | ThrottleOptions, windowMs?: number): (target: any, propertyKey: string, descriptor?: PropertyDescriptor) => PropertyDescriptor | undefined;

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

@@ -0,0 +1,73 @@
+import { container } from 'tsyringe';
+import { SecurityError } from '../../../kernel/error/security.error';
+import { RateLimiterService } from '../services/rate-limiter.service';
+import { METADATA_KEYS } from '../system/metadata-server.keys';
+/**
+ * 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: Player, query: string) {
+ *     // ...
+ *   }
+ *
+ *   @Server.Throttle({ limit: 1, windowMs: 5000, message: 'Too fast!' })
+ *   async placeOrder(player: Player) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export function Throttle(optionsOrLimit, windowMs) {
+    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
+            // 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 = { onExceed: 'LOG', ...optionsOrLimit };
+        }
+        const onExceed = opts.onExceed ?? 'LOG';
+        // Store metadata for remote transmission
+        Reflect.defineMetadata(METADATA_KEYS.THROTTLE, opts, target, propertyKey);
+        descriptor.value = async function (...args) {
+            const player = args[0];
+            if (player?.clientID) {
+                const service = container.resolve(RateLimiterService);
+                const key = `${player.clientID}:${target.constructor.name}:${propertyKey}`;
+                if (!service.checkLimit(key, opts.limit, opts.windowMs)) {
+                    throw new SecurityError(onExceed, opts.message || `Rate limit exceeded on ${propertyKey}`, { limit: opts.limit, key });
+                }
+            }
+            return originalMethod.apply(this, args);
+        };
+        return descriptor;
+    };
+}

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

@@ -0,0 +1,54 @@
+import { BindingScope } from './bind';
+/**
+ * Marks a class as a framework-managed Service.
+ *
+ *
+ * @remarks
+ * This decorator binds the class into the dependency injection container using the provided scope
+ * (default: `singleton`).
+ *
+ * `@Service()` is a convenience wrapper over {@link Bind}. It exists so service-specific behavior
+ * can be added in the future without changing user code.
+ *
+ * @param options.scope - Optional binding scope (`singleton` | `transient`).
+ *
+ * @example
+ * ```ts
+ * @Server.Service()
+ * export class InventoryService {
+ *   addItem() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function Service(options?: {
+    scope?: BindingScope;
+}): (target: any) => void;
+/**
+ * Marks a class as a Repository within the framework.
+ *
+ *
+ * @remarks
+ * A repository abstracts persistence operations (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 {@link Service} to distinguish persistence-oriented
+ * classes from business logic.
+ *
+ * @param options.scope - Optional binding scope (`singleton` | `transient`).
+ *
+ * @example
+ * ```ts
+ * @Server.Repo()
+ * export class AccountRepository {
+ *   async findById(id: string) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function Repo(options?: {
+    scope?: BindingScope;
+}): (target: any) => void;

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

@@ -0,0 +1,54 @@
+import { Bind } from './bind';
+/**
+ * Marks a class as a framework-managed Service.
+ *
+ *
+ * @remarks
+ * This decorator binds the class into the dependency injection container using the provided scope
+ * (default: `singleton`).
+ *
+ * `@Service()` is a convenience wrapper over {@link Bind}. It exists so service-specific behavior
+ * can be added in the future without changing user code.
+ *
+ * @param options.scope - Optional binding scope (`singleton` | `transient`).
+ *
+ * @example
+ * ```ts
+ * @Server.Service()
+ * export class InventoryService {
+ *   addItem() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export function Service(options) {
+    return Bind(options?.scope ?? 'singleton');
+}
+/**
+ * Marks a class as a Repository within the framework.
+ *
+ *
+ * @remarks
+ * A repository abstracts persistence operations (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 {@link Service} to distinguish persistence-oriented
+ * classes from business logic.
+ *
+ * @param options.scope - Optional binding scope (`singleton` | `transient`).
+ *
+ * @example
+ * ```ts
+ * @Server.Repo()
+ * export class AccountRepository {
+ *   async findById(id: string) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export function Repo(options) {
+    return Bind(options?.scope ?? 'singleton');
+}