@open-core/framework 0.2.2-beta.1 → 0.2.4

package/package.json

@@ -1,99 +1,100 @@
-{
-  "name": "@open-core/framework",
-  "version": "0.2.2-beta.1",
-  "description": "Secure, Event-Driven, OOP Engine for FiveM. Stop scripting, start engineering.",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "type": "commonjs",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/newcore-network/opencore.git"
-  },
-  "homepage": "https://github.com/newcore-network/opencore",
-  "bugs": {
-    "url": "https://github.com/newcore-network/opencore/issues"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.js"
-    },
-    "./server": {
-      "types": "./dist/runtime/server/index.d.ts",
-      "import": "./dist/runtime/server/index.js",
-      "require": "./dist/runtime/server/index.js"
-    },
-    "./client": {
-      "types": "./dist/runtime/client/index.d.ts",
-      "import": "./dist/runtime/client/index.js",
-      "require": "./dist/runtime/client/index.js"
-    },
-    "./shared": {
-      "types": "./dist/kernel/shared/index.d.ts",
-      "import": "./dist/kernel/shared/index.js",
-      "require": "./dist/kernel/shared/index.js"
-    },
-    "./utils": {
-      "types": "./dist/kernel/utils/index.d.ts",
-      "import": "./dist/kernel/utils/index.js",
-      "require": "./dist/kernel/utils/index.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "scripts": {
-    "publish": "pnpm build && npm publish",
-    "build": "tsc -p tsconfig.build.json",
-    "watch": "tsc -p tsconfig.build.json --watch",
-    "check": "biome check .",
-    "check:fix": "biome check --write .",
-    "check:fix:unsafe": "biome check --write --unsafe",
-    "format": "biome format --write .",
-    "lint": "biome lint .",
-    "lint:fix": "biome lint --write .",
-    "typecheck": "tsc --noEmit",
-    "test": "npx vitest run --project unit --project integration --project e2e",
-    "test:watch": "npx vitest --project unit --project integration --project e2e",
-    "test:unit": "npx vitest run --project unit",
-    "test:integration": "npx vitest run --project integration",
-    "test:coverage": "npx vitest run --coverage",
-    "bench": "npx tsx benchmark/index.ts",
-    "bench:core": "npx tsx benchmark/index.ts --core",
-    "bench:load": "npx vitest run --project benchmark",
-    "bench:all": "npx tsx benchmark/index.ts --all"
-  },
-  "keywords": [
-    "framework",
-    "opencore",
-    "fivem",
-    "typescript",
-    "roleplay"
-  ],
-  "author": "OpenCore Team",
-  "license": "MPL-2.0",
-  "packageManager": "pnpm@10.13.1",
-  "dependencies": {
-    "reflect-metadata": "^0.2.2",
-    "tsyringe": "^4.10.0",
-    "uuid": "^13.0.0",
-    "zod": "^4.1.13"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.3.10",
-    "@citizenfx/client": "2.0.22443-1",
-    "@citizenfx/server": "2.0.22443-1",
-    "@types/node": "^24.10.1",
-    "@vitest/coverage-v8": "^4.0.15",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-import": "^2.32.0",
-    "tinybench": "^2.7.0",
-    "tsx": "^4.19.2",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.15"
-  }
-}
+{
+  "name": "@open-core/framework",
+  "version": "0.2.4",
+  "description": "Secure, Event-Driven, OOP Engine for FiveM. Stop scripting, start engineering.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "commonjs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/newcore-network/opencore.git"
+  },
+  "homepage": "https://github.com/newcore-network/opencore",
+  "bugs": {
+    "url": "https://github.com/newcore-network/opencore/issues"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/runtime/server/index.d.ts",
+      "import": "./dist/runtime/server/index.js",
+      "require": "./dist/runtime/server/index.js"
+    },
+    "./client": {
+      "types": "./dist/runtime/client/index.d.ts",
+      "import": "./dist/runtime/client/index.js",
+      "require": "./dist/runtime/client/index.js"
+    },
+    "./shared": {
+      "types": "./dist/kernel/shared/index.d.ts",
+      "import": "./dist/kernel/shared/index.js",
+      "require": "./dist/kernel/shared/index.js"
+    },
+    "./utils": {
+      "types": "./dist/kernel/utils/index.d.ts",
+      "import": "./dist/kernel/utils/index.js",
+      "require": "./dist/kernel/utils/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "watch": "tsc -p tsconfig.build.json --watch",
+    "check": "biome check .",
+    "check:fix": "biome check --write .",
+    "check:fix:unsafe": "biome check --write --unsafe",
+    "format": "biome format --write .",
+    "lint": "biome lint .",
+    "lint:fix": "biome lint --write .",
+    "typecheck": "tsc --noEmit",
+    "test": "npx vitest run --project unit --project integration --project e2e",
+    "test:ci": "npx vitest run --project unit --project integration",
+    "test:watch": "npx vitest --project unit --project integration --project e2e",
+    "test:unit": "npx vitest run --project unit",
+    "test:integration": "npx vitest run --project integration",
+    "test:e2e": "npx vitest run --project e2e",
+    "test:coverage": "npx vitest run --coverage",
+    "bench": "npx tsx benchmark/index.ts",
+    "bench:core": "npx tsx benchmark/index.ts --core",
+    "bench:load": "npx vitest run --project benchmark",
+    "bench:all": "npx tsx benchmark/index.ts --all"
+  },
+  "keywords": [
+    "framework",
+    "opencore",
+    "fivem",
+    "typescript",
+    "roleplay"
+  ],
+  "author": "OpenCore Team",
+  "license": "MPL-2.0",
+  "packageManager": "pnpm@10.13.1",
+  "dependencies": {
+    "reflect-metadata": "^0.2.2",
+    "tsyringe": "^4.10.0",
+    "uuid": "^13.0.0",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.10",
+    "@citizenfx/client": "2.0.22443-1",
+    "@citizenfx/server": "2.0.22443-1",
+    "@types/node": "^24.10.1",
+    "@vitest/coverage-v8": "^4.0.15",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-import": "^2.32.0",
+    "tinybench": "^2.7.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.15"
+  }
+}

package/dist/kernel/di/tokens.d.ts

@@ -1,30 +0,0 @@
-/**
- * Dependency Injection Tokens for OpenCore.
- *
- * Using string tokens instead of class references for injection
- * avoids issues with circular dependencies and "TypeInfo not known"
- * errors in certain build environments.
- */
-export declare const DI_TOKENS: {
-    readonly CommandExecutionPort: symbol;
-    readonly PlayerDirectoryPort: symbol;
-    readonly PrincipalPort: symbol;
-    readonly DecoratorProcessor: "DecoratorProcessor";
-    readonly DatabaseService: symbol;
-    readonly HttpService: symbol;
-    readonly ChatService: symbol;
-    readonly RateLimiterService: symbol;
-    readonly PrincipalProvider: symbol;
-    readonly AuthProvider: symbol;
-    readonly Exports: symbol;
-    readonly EngineEvents: symbol;
-    readonly NetTransport: symbol;
-    readonly Tick: symbol;
-    readonly PlayerInfo: symbol;
-    readonly ResourceInfo: symbol;
-    readonly EntityServer: symbol;
-    readonly VehicleServer: symbol;
-    readonly PlayerServer: symbol;
-    readonly Hasher: symbol;
-    readonly PedAppearanceServer: symbol;
-};

package/dist/kernel/di/tokens.js

@@ -1,38 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DI_TOKENS = void 0;
-/**
- * Dependency Injection Tokens for OpenCore.
- *
- * Using string tokens instead of class references for injection
- * avoids issues with circular dependencies and "TypeInfo not known"
- * errors in certain build environments.
- */
-exports.DI_TOKENS = {
-    // Ports
-    CommandExecutionPort: Symbol.for('CommandExecutionPort'),
-    PlayerDirectoryPort: Symbol.for('PlayerDirectoryPort'),
-    PrincipalPort: Symbol.for('PrincipalPort'),
-    // Decorator Processors
-    DecoratorProcessor: 'DecoratorProcessor',
-    // Services
-    DatabaseService: Symbol.for('DatabaseService'),
-    HttpService: Symbol.for('HttpService'),
-    ChatService: Symbol.for('ChatService'),
-    RateLimiterService: Symbol.for('RateLimiterService'),
-    // Providers
-    PrincipalProvider: Symbol.for('PrincipalProvider'),
-    AuthProvider: Symbol.for('AuthProvider'),
-    // Adapters
-    Exports: Symbol.for('IExports'),
-    EngineEvents: Symbol.for('IEngineEvents'),
-    NetTransport: Symbol.for('INetTransport'),
-    Tick: Symbol.for('ITick'),
-    PlayerInfo: Symbol.for('IPlayerInfo'),
-    ResourceInfo: Symbol.for('IResourceInfo'),
-    EntityServer: Symbol.for('IEntityServer'),
-    VehicleServer: Symbol.for('IVehicleServer'),
-    PlayerServer: Symbol.for('IPlayerServer'),
-    Hasher: Symbol.for('IHasher'),
-    PedAppearanceServer: Symbol.for('IPedAppearanceServer'),
-};

package/dist/runtime/client/interfaces/appearance.interface.d.ts

@@ -1,25 +0,0 @@
-export interface PlayerAppearance {
-  components?: Record<
-    number,
-    {
-      drawable: number
-      texture: number
-    }
-  >
-  props?: Record<
-    number,
-    {
-      drawable: number
-      texture: number
-    }
-  >
-  faceFeatures?: Record<number, number>
-  headBlend?: {
-    shapeFirst: number
-    shapeSecond: number
-    shapeMix: number
-    skinFirst: number
-    skinSecond: number
-    skinMix: number
-  }
-}

package/dist/runtime/client/interfaces/appearance.interface.js

@@ -1,2 +0,0 @@
-'use strict'
-Object.defineProperty(exports, '__esModule', { value: true })

package/dist/runtime/server/controllers/command.controller.d.ts

@@ -1,15 +0,0 @@
-import { CommandExecutionPort } from '../services/ports/command-execution.port'
-import { Player } from '../entities'
-/**
- * Network controller for command execution.
- *
- * @remarks
- * Receives command execution requests from clients and delegates to CommandExecutionPort.
- * In CORE mode, executes commands directly or delegates to owning resource.
- * In RESOURCE mode, delegates to CORE via exports.
- */
-export declare class CommandNetworkController {
-  private readonly commandService
-  constructor(commandService: CommandExecutionPort)
-  onCommandReceived(player: Player, command: string, args: string[]): Promise<void>
-}

package/dist/runtime/server/controllers/command.controller.js

@@ -1,100 +0,0 @@
-'use strict'
-var __decorate =
-  (this && this.__decorate) ||
-  function (decorators, target, key, desc) {
-    var c = arguments.length,
-      r =
-        c < 3
-          ? target
-          : desc === null
-            ? (desc = Object.getOwnPropertyDescriptor(target, key))
-            : desc,
-      d
-    if (typeof Reflect === 'object' && typeof Reflect.decorate === 'function')
-      r = Reflect.decorate(decorators, target, key, desc)
-    else
-      for (var i = decorators.length - 1; i >= 0; i--)
-        if ((d = decorators[i]))
-          r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r
-    return c > 3 && r && Object.defineProperty(target, key, r), r
-  }
-var __metadata =
-  (this && this.__metadata) ||
-  ((k, v) => {
-    if (typeof Reflect === 'object' && typeof Reflect.metadata === 'function')
-      return Reflect.metadata(k, v)
-  })
-Object.defineProperty(exports, '__esModule', { value: true })
-exports.CommandNetworkController = void 0
-const onNet_1 = require('../decorators/onNet')
-const command_execution_port_1 = require('../services/ports/command-execution.port')
-const entities_1 = require('../entities')
-const decorators_1 = require('../decorators')
-const logger_1 = require('../../../kernel/shared/logger')
-const utils_1 = require('../../../kernel/utils')
-/**
- * Network controller for command execution.
- *
- * @remarks
- * Receives command execution requests from clients and delegates to CommandExecutionPort.
- * In CORE mode, executes commands directly or delegates to owning resource.
- * In RESOURCE mode, delegates to CORE via exports.
- */
-let CommandNetworkController = class CommandNetworkController {
-  constructor(commandService) {
-    this.commandService = commandService
-  }
-  async onCommandReceived(player, command, args) {
-    try {
-      if (command.startsWith('/')) command = command.slice(1)
-      if (!player.clientID || player.clientID === null || player.clientID === undefined) {
-        console.log('DEBUG; Player entity not received in core:execute-command')
-      }
-      if (args.length > 10 || !/^[a-zA-Z0-9:_-]+$/.test(command)) {
-        logger_1.loggers.command.warn(`Rejected suspicious command: ${command}`, {
-          playerId: player.clientID,
-          playerName: player.name,
-        })
-        return
-      }
-      logger_1.loggers.command.trace(`Received: /${command}`, {
-        playerId: player.clientID,
-        playerName: player.name,
-      })
-      await this.commandService.execute(player, command, args)
-    } catch (error) {
-      if (error instanceof utils_1.AppError) {
-        if (error.code === 'GAME:BAD_REQUEST' || error.code === 'COMMAND:NOT_FOUND')
-          player.send(error.message, 'error')
-        else player.send('An error occurred while executing the command', 'error')
-        logger_1.loggers.command.error(
-          `Execution failed: /${command}`,
-          {
-            playerId: player.clientID,
-          },
-          error,
-        )
-      }
-    }
-  }
-}
-exports.CommandNetworkController = CommandNetworkController
-__decorate(
-  [
-    (0, decorators_1.Public)(),
-    (0, onNet_1.OnNet)('core:execute-command'),
-    __metadata('design:type', Function),
-    __metadata('design:paramtypes', [entities_1.Player, String, Array]),
-    __metadata('design:returntype', Promise),
-  ],
-  CommandNetworkController.prototype,
-  'onCommandReceived',
-  null,
-)
-exports.CommandNetworkController = CommandNetworkController = __decorate(
-  [
-    (0, decorators_1.Controller)(),
-    __metadata('design:paramtypes', [command_execution_port_1.CommandExecutionPort]),
-  ],
-  CommandNetworkController,
-)

package/dist/runtime/server/services/access-control.service.d.ts

@@ -1,59 +0,0 @@
-import { Server } from '../../..'
-import { PrincipalProviderContract } from '../contracts'
-/**
- * **Core Security Service**
- *
- * This service acts as the central enforcement point for the Access Control system.
- * It uses the configured `PrincipalProvider` to query roles and validates them against requirements.
- *
- * It is primarily used internally by the `@Guard` decorator, but can be injected
- * into services to perform manual checks.
- */
-export declare class AccessControlService {
-  private readonly principalProvider
-  constructor(principalProvider: PrincipalProviderContract)
-  /**
-   * Verifies if a player meets a minimum numeric rank requirement.
-   *
-   * @param player - The target player.
-   * @param minRank - The minimum numeric value required (Inclusive).
-   *
-   * @returns `true` if `Principal.rank >= minRank`.
-   *
-   * @throws {AppError} code `UNAUTHORIZED` if the player has no Principal (not logged in).
-   * @throws {AppError} code `NO_RANK_IN_PRINCIPAL` if the Principal exists but has no `rank` defined.
-   */
-  hasRank(player: Server.Player, minRank: number): Promise<boolean>
-  /**
-   * Verifies if a player possesses a specific permission string.
-   *
-   * @remarks
-   * This method supports the **Wildcard ('*')** permission. If the principal has `'*'`
-   * in their permissions array, this method always returns `true`.
-   *
-   * @param player - The target player.
-   * @param permission - The specific permission key (e.g., `'admin.ban'`).
-   * @returns `true` if the player has the permission or the wildcard.
-   */
-  hasPermission(player: Server.Player, permission: string): Promise<boolean>
-  /**
-   * **Strict Enforcement**
-   *
-   * Validates a set of requirements against a player. If any requirement fails,
-   * it throws an exception, halting the execution flow.
-   *
-   * Used primarily by the `@Guard` decorator logic.
-   *
-   * @param player - The server player to validate.
-   * @param requirements - An object containing rank and/or permission constraints.
-   *
-   * @throws {AppError} code `PERMISSION_DENIED` if validation fails.
-   */
-  enforce(
-    player: Server.Player,
-    requirements: {
-      minRank?: number
-      permission?: string
-    },
-  ): Promise<void>
-}

package/dist/runtime/server/services/access-control.service.js

@@ -1,127 +0,0 @@
-'use strict'
-var __decorate =
-  (this && this.__decorate) ||
-  function (decorators, target, key, desc) {
-    var c = arguments.length,
-      r =
-        c < 3
-          ? target
-          : desc === null
-            ? (desc = Object.getOwnPropertyDescriptor(target, key))
-            : desc,
-      d
-    if (typeof Reflect === 'object' && typeof Reflect.decorate === 'function')
-      r = Reflect.decorate(decorators, target, key, desc)
-    else
-      for (var i = decorators.length - 1; i >= 0; i--)
-        if ((d = decorators[i]))
-          r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r
-    return c > 3 && r && Object.defineProperty(target, key, r), r
-  }
-var __metadata =
-  (this && this.__metadata) ||
-  ((k, v) => {
-    if (typeof Reflect === 'object' && typeof Reflect.metadata === 'function')
-      return Reflect.metadata(k, v)
-  })
-Object.defineProperty(exports, '__esModule', { value: true })
-exports.AccessControlService = void 0
-const tsyringe_1 = require('tsyringe')
-const utils_1 = require('../../../kernel/utils')
-const contracts_1 = require('../contracts')
-/**
- * **Core Security Service**
- *
- * This service acts as the central enforcement point for the Access Control system.
- * It uses the configured `PrincipalProvider` to query roles and validates them against requirements.
- *
- * It is primarily used internally by the `@Guard` decorator, but can be injected
- * into services to perform manual checks.
- */
-let AccessControlService = class AccessControlService {
-  constructor(principalProvider) {
-    this.principalProvider = principalProvider
-  }
-  /**
-   * Verifies if a player meets a minimum numeric rank requirement.
-   *
-   * @param player - The target player.
-   * @param minRank - The minimum numeric value required (Inclusive).
-   *
-   * @returns `true` if `Principal.rank >= minRank`.
-   *
-   * @throws {AppError} code `UNAUTHORIZED` if the player has no Principal (not logged in).
-   * @throws {AppError} code `NO_RANK_IN_PRINCIPAL` if the Principal exists but has no `rank` defined.
-   */
-  async hasRank(player, minRank) {
-    const principal = await this.principalProvider.getPrincipal(player)
-    if (!principal) throw new utils_1.AppError('AUTH:UNAUTHORIZED', 'No principal found', 'core')
-    if (principal.rank === undefined)
-      throw new utils_1.AppError(
-        'GAME:NO_RANK_IN_PRINCIPAL',
-        "You're trying to compare a Principal rank, but there's no defined rank! ",
-        'core',
-      )
-    return principal.rank >= minRank
-  }
-  /**
-   * Verifies if a player possesses a specific permission string.
-   *
-   * @remarks
-   * This method supports the **Wildcard ('*')** permission. If the principal has `'*'`
-   * in their permissions array, this method always returns `true`.
-   *
-   * @param player - The target player.
-   * @param permission - The specific permission key (e.g., `'admin.ban'`).
-   * @returns `true` if the player has the permission or the wildcard.
-   */
-  async hasPermission(player, permission) {
-    const principal = await this.principalProvider.getPrincipal(player)
-    if (!principal) return false
-    if (principal.permissions.includes('*')) return true
-    return principal.permissions.includes(permission)
-  }
-  /**
-   * **Strict Enforcement**
-   *
-   * Validates a set of requirements against a player. If any requirement fails,
-   * it throws an exception, halting the execution flow.
-   *
-   * Used primarily by the `@Guard` decorator logic.
-   *
-   * @param player - The server player to validate.
-   * @param requirements - An object containing rank and/or permission constraints.
-   *
-   * @throws {AppError} code `PERMISSION_DENIED` if validation fails.
-   */
-  async enforce(player, requirements) {
-    if (requirements.minRank !== undefined) {
-      const hasRank = await this.hasRank(player, requirements.minRank)
-      if (!hasRank) {
-        throw new utils_1.AppError(
-          'AUTH:PERMISSION_DENIED',
-          `Access Denied: Requires minimum rank level ${requirements.minRank}`,
-          'core',
-        )
-      }
-    }
-    if (requirements.permission) {
-      const hasPerm = await this.hasPermission(player, requirements.permission)
-      if (!hasPerm) {
-        throw new utils_1.AppError(
-          'AUTH:PERMISSION_DENIED',
-          `Access Denied: Missing required permission '${requirements.permission}'`,
-          'core',
-        )
-      }
-    }
-  }
-}
-exports.AccessControlService = AccessControlService
-exports.AccessControlService = AccessControlService = __decorate(
-  [
-    (0, tsyringe_1.injectable)(),
-    __metadata('design:paramtypes', [contracts_1.PrincipalProviderContract]),
-  ],
-  AccessControlService,
-)