@open-core/framework 0.1.0-alpha.1

package/dist/server/decorators/requiresState.js

@@ -0,0 +1,63 @@
+"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

@@ -0,0 +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

@@ -0,0 +1,63 @@
+"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

@@ -0,0 +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

@@ -0,0 +1,63 @@
+"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

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

package/dist/server/entities/index.js

@@ -0,0 +1,17 @@
+"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

@@ -0,0 +1,157 @@
+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[];
+}

package/dist/server/entities/player.js

@@ -0,0 +1,217 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Player = void 0;
+/**
+ * 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`).
+ */
+class Player {
+    /**
+     * 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) {
+        this.session = session;
+        this.states = new Set();
+    }
+    /**
+     * The numeric FiveM Server ID (Source) of the player.
+     * Useful for internal logic and array indexing.
+     */
+    get clientID() {
+        return this.session.clientID;
+    }
+    /**
+     * The FiveM Server ID as a string.
+     * Required by most FiveM native functions (e.g., `GetPlayerName`, `DropPlayer`).
+     */
+    get clientIDStr() {
+        return this.session.clientID.toString();
+    }
+    /**
+     * 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() {
+        var _a;
+        return (_a = this.session.accountID) === null || _a === void 0 ? void 0 : _a.toString();
+    }
+    /**
+     * The display name of the player (Steam name or FiveM username).
+     */
+    get name() {
+        return GetPlayerName(this.clientIDStr);
+    }
+    /**
+     * 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() {
+        const ids = [];
+        for (let i = 0;; i++) {
+            const id = GetPlayerIdentifier(this.clientIDStr, i);
+            if (!id)
+                break;
+            ids.push(id);
+        }
+        return ids;
+    }
+    /**
+     * 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, ...args) {
+        emitNet(eventName, this.clientID, ...args);
+    }
+    /**
+     * 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) {
+        SetEntityCoords(GetPlayerPed(this.clientIDStr), vector.x, vector.y, vector.z, false, false, false, true);
+    }
+    /**
+     * 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) {
+        this.emit('opencore:spawner:teleport', vector);
+    }
+    /**
+     * Disconnects the player from the server.
+     *
+     * @param reason - The message displayed to the player upon disconnection.
+     */
+    kick(reason = 'Kicked from server') {
+        DropPlayer(this.clientID.toString(), reason);
+    }
+    /**
+     * 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) {
+        SetPlayerRoutingBucket(this.clientID.toString(), bucket);
+    }
+    /**
+     * 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, value) {
+        this.session.meta[key] = value;
+    }
+    /**
+     * 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(key) {
+        return this.session.meta[key];
+    }
+    /**
+     * 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) {
+        this.session.accountID = accountID;
+    }
+    /**
+     * 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) {
+        return this.states.has(state);
+    }
+    /**
+     * 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) {
+        this.states.add(state);
+        // this.emit('core:state:add', state) // ? optional !!
+    }
+    /**
+     * Removes a specific state flag from the player.
+     *
+     * @param state - The state key to remove.
+     */
+    removeState(state) {
+        this.states.delete(state);
+        // this.emit('core:state:remove', state) // ? optional !!
+    }
+    /**
+     * 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, force) {
+        if (force !== undefined) {
+            force ? this.addState(state) : this.removeState(state);
+            return force;
+        }
+        if (this.hasState(state)) {
+            this.removeState(state);
+            return false;
+        }
+        else {
+            this.addState(state);
+            return true;
+        }
+    }
+    /**
+     * Retrieves a snapshot of all currently active state flags for this player.
+     *
+     * @returns An array containing all active state keys.
+     */
+    getStates() {
+        return Array.from(this.states);
+    }
+}
+exports.Player = Player;

package/dist/server/error-handler.d.ts

@@ -0,0 +1,2 @@
+import type { CommandMetadata } from './decorators/command';
+export declare function handleCommandError(error: unknown, meta: CommandMetadata, playerId: number | null): void;