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

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/public.js

@@ -1,36 +0,0 @@
-"use strict";
-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.
- *
- * 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.
- */
-function Public() {
-    return function (target, propertyKey, descriptor) {
-        Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.PUBLIC, true, target, propertyKey);
-        return descriptor;
-    };
-}

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

@@ -1,56 +0,0 @@
-/**
- * Configuration options for state validation requirements.
- * Defines the logical constraints (whitelist/blacklist) applied to the player's current state flags.
- */
-export interface StateRequirement {
-    /**
-     * **Whitelist:** The player **MUST** possess ALL of these states to proceed.
-     * If the player is missing any one of these, the execution is blocked.
-     * @example ['on_duty_police', 'in_vehicle']
-     */
-    has?: string[];
-    /**
-     * **Blacklist:** The player **MUST NOT** possess ANY of these states to proceed.
-     * If the player has any one of these, the execution is blocked.
-     * @example ['dead', 'cuffed', 'unconscious']
-     */
-    missing?: string[];
-    /**
-     * A custom message to display to the client if validation fails.
-     * If omitted, a default generic message will be generated based on the missing/conflicting state.
-     */
-    errorMessage?: string;
-}
-/**
- * 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.
- */
-export declare function RequiresState(req: StateRequirement): (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/throttle.js

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

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

@@ -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;

package/dist/server/decorators/utils.js

@@ -1,63 +0,0 @@
-"use strict";
-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/entities/index.d.ts

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

package/dist/server/entities/index.js

@@ -1,17 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./player"), exports);

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

@@ -1,157 +0,0 @@
-import type { Vector3 } from '../../utils';
-import type { LinkedID, PlayerSession } from '../services/player.service';
-/**
- * Core-level representation of a connected player on the server.
- *
- * This class wraps FiveM natives and session information.
- * It serves as an abstraction layer to interact with the connected client
- * (kicking, teleporting, emitting events) without dealing with raw IDs everywhere.
- *
- * ⚠️ **Design Note:** This class does NOT contain gameplay logic (money, jobs, inventory).
- * Domain logic should live in your modules' services/models (e.g., `EconomyService`, `JobModel`).
- */
-export declare class Player {
-    private readonly session;
-    private states;
-    /**
-     * Creates a new Player entity instance.
-     * This is typically instantiated by the `PlayerService` upon connection.
-     *
-     * @param session - The internal session data structure holding ID and metadata.
-     */
-    constructor(session: PlayerSession);
-    /**
-     * The numeric FiveM Server ID (Source) of the player.
-     * Useful for internal logic and array indexing.
-     */
-    get clientID(): number;
-    /**
-     * The FiveM Server ID as a string.
-     * Required by most FiveM native functions (e.g., `GetPlayerName`, `DropPlayer`).
-     */
-    get clientIDStr(): string;
-    /**
-     * The persistent Account ID linked to this session, if the player is authenticated.
-     * Returns `undefined` if the player has not logged in yet.
-     */
-    get accountID(): string | undefined;
-    /**
-     * The display name of the player (Steam name or FiveM username).
-     */
-    get name(): string;
-    /**
-     * Retrieves all platform identifiers associated with the player (steam, license, discord, ip, etc.).
-     *
-     * @returns An array of identifier strings (e.g., `['steam:11000...', 'license:2332...']`).
-     */
-    getIdentifiers(): string[];
-    /**
-     * Sends a network event exclusively to this specific player (Client-side).
-     * Wrapper for `emitNet` ensuring the correct target Source ID is used.
-     *
-     * @param eventName - The name of the event to trigger on the client.
-     * @param args - Data to send to the client.
-     */
-    emit(eventName: string, ...args: any[]): void;
-    /**
-     * Teleports the player to a given position using Server-Side natives.
-     *
-     * **Note:** This forces the entity position on the server. For smoother gameplay transitions
-     * (e.g., inside interiors or across the map), consider using `teleportClient`.
-     *
-     * @param vector - The target coordinates (x, y, z).
-     */
-    teleport(vector: Vector3): void;
-    /**
-     * Requests the Client to teleport itself via the Core Spawner system.
-     *
-     * This method is preferred for gameplay logic as it allows the client to handle
-     * loading screens, fading, and collision loading gracefully.
-     *
-     * @param vector - The target coordinates (x, y, z).
-     */
-    teleportClient(vector: Vector3): void;
-    /**
-     * Disconnects the player from the server.
-     *
-     * @param reason - The message displayed to the player upon disconnection.
-     */
-    kick(reason?: string): void;
-    /**
-     * Sets the routing bucket (virtual world / dimension) for the player.
-     * Players in different buckets cannot see or interact with each other.
-     *
-     * @param bucket - The bucket ID (0 is the default shared world).
-     */
-    setRoutingBucket(bucket: number): void;
-    /**
-     * Stores arbitrary transient metadata for this player's session.
-     * Useful for flags like `isDead`, `isInRaid`, `lastLocation`, etc.
-     *
-     * @param key - The unique key for the metadata.
-     * @param value - The value to store.
-     */
-    setMeta(key: string, value: unknown): void;
-    /**
-     * Retrieves metadata previously stored in the session.
-     *
-     * @template T - The expected type of the value.
-     * @param key - The metadata key.
-     * @returns The value cast to T, or `undefined` if not set.
-     */
-    getMeta<T = unknown>(key: string): T | undefined;
-    /**
-     * Links a persistent Account ID to the current session.
-     * Should be called after successful authentication.
-     *
-     * @param accountID - The unique ID from the database.
-     */
-    linkAccount(accountID: LinkedID): void;
-    /**
-     * Checks if the player currently possesses a specific state flag.
-     *
-     * @param state - The unique string identifier of the state (e.g., 'dead', 'cuffed').
-     * @returns `true` if the state is active, `false` otherwise.
-     */
-    hasState(state: string): boolean;
-    /**
-     * Applies a state flag to the player.
-     *
-     * @remarks
-     * Since states are stored in a `Set`, adding an existing state has no effect (idempotent).
-     * Ideally, this should trigger a sync event to the client if needed.
-     *
-     * @param state - The state key to add.
-     */
-    addState(state: string): void;
-    /**
-     * Removes a specific state flag from the player.
-     *
-     * @param state - The state key to remove.
-     */
-    removeState(state: string): void;
-    /**
-     * Toggles the presence of a state flag.
-     *
-     * @param state - The state key to toggle.
-     * @param force - If provided, forces the state to be added (`true`) or removed (`false`) regardless of its current status.
-     *
-     * @returns The final status of the state (`true` if active, `false` if inactive).
-     *
-     * @example
-     * ```ts
-     * // Standard toggle
-     * player.toggleState('duty'); // turns on if off, off if on
-     *
-     * // Force enable (equivalent to addState but returns boolean)
-     * player.toggleState('duty', true); // always results in true
-     * ```
-     */
-    toggleState(state: string, force?: boolean): boolean;
-    /**
-     * Retrieves a snapshot of all currently active state flags for this player.
-     *
-     * @returns An array containing all active state keys.
-     */
-    getStates(): string[];
-}