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

package/dist/runtime/server/types/core-exports.d.ts

@@ -0,0 +1,285 @@
+import { Principal } from '../contracts/security/permission.types';
+import { GuardOptions } from '../decorators/guard';
+import { StateRequirement } from '../decorators/requiresState';
+import { ThrottleOptions } from '../decorators/throttle';
+import { CommandInfo } from '../services/ports/command-execution.port';
+/**
+ * Serialized player data for cross-resource transfer.
+ *
+ * @remarks
+ * This DTO contains all session data that can be transferred from CORE to RESOURCE.
+ * Used by PlayerDirectory exports to provide real player data to remote resources.
+ */
+export interface SerializedPlayerData {
+    /** FiveM server client ID (source) */
+    clientID: number;
+    /** Persistent account ID (undefined if not authenticated) */
+    accountID?: string;
+    /** Platform identifiers (license, steam, discord, etc.) */
+    identifiers?: {
+        license?: string;
+        steam?: string;
+        discord?: string;
+        [key: string]: string | undefined;
+    };
+    /** Session metadata (transient key-value storage) */
+    meta: Record<string, unknown>;
+    /** Active state flags (dead, cuffed, etc.) */
+    states: string[];
+}
+/**
+ * Security metadata collected from decorators for remote validation.
+ *
+ * @remarks
+ * Transmitted from RESOURCE to CORE during command registration.
+ * CORE validates these constraints before delegating execution back to RESOURCE.
+ */
+export interface SecurityMetadata {
+    /** @Guard decorator options (rank/permission requirements) */
+    guard?: GuardOptions;
+    /** @Throttle decorator options (rate limiting configuration) */
+    throttle?: ThrottleOptions;
+    /** @RequiresState decorator options (player state validation) */
+    requiresState?: StateRequirement;
+}
+/**
+ * Metadata sent when a RESOURCE registers a command with CORE.
+ */
+export interface CommandRegistrationDto {
+    /** Command name (without leading slash) */
+    command: string;
+    /** Optional description shown in help */
+    description?: string;
+    /** Optional usage hint (e.g., "/revive <player>") */
+    usage?: string;
+    /** Whether command allows unauthenticated access */
+    isPublic: boolean;
+    /** Resource name that owns this command */
+    resourceName: string;
+    /** Security metadata for CORE validation (optional) */
+    security?: SecurityMetadata;
+}
+/**
+ * Type-safe interface for CORE resource exports.
+ *
+ * @remarks
+ * Used by remote services (RemoteCommandService, RemotePlayerService, etc.)
+ * to access CORE functionality via FiveM exports with full type safety.
+ *
+ * Usage:
+ * ```ts
+ * const core = (exports as any)[coreResourceName] as CoreExports
+ * core.registerCommand({ ... })
+ * ```
+ */
+export interface CorePrincipalExports {
+    /**
+     * Gets the full Principal object for a player.
+     *
+     * @param source - FiveM client/server ID
+     * @returns Principal data or null if not authenticated
+     */
+    getPrincipal(source: number): Promise<Principal | null>;
+    /**
+     * Gets Principal by account ID (works for offline players too).
+     *
+     * @param accountId - Database account identifier
+     * @returns Principal data or null
+     */
+    getPrincipalByAccountId(accountId: string): Promise<Principal | null>;
+    /**
+     * Forces a refresh of the player's permissions from persistence.
+     *
+     * @param source - FiveM client/server ID
+     */
+    refreshPrincipal(source: number): Promise<void>;
+    /**
+     * Checks if player has a specific permission.
+     *
+     * @param source - FiveM client/server ID
+     * @param permission - Permission string to check
+     * @returns True if player has permission (or wildcard '*')
+     */
+    hasPermission(source: number, permission: string): Promise<boolean>;
+    /**
+     * Checks if player has at least the required rank.
+     *
+     * @param source - FiveM client/server ID
+     * @param requiredRank - Minimum rank value
+     * @returns True if playerRank >= requiredRank
+     */
+    hasRank(source: number, requiredRank: number): Promise<boolean>;
+    /**
+     * Checks if player has ANY of the specified permissions.
+     *
+     * @param source - FiveM client/server ID
+     * @param permissions - Array of permissions to check
+     * @returns True if player has at least one permission
+     */
+    hasAnyPermission(source: number, permissions: string[]): Promise<boolean>;
+    /**
+     * Checks if player has ALL of the specified permissions.
+     *
+     * @param source - FiveM client/server ID
+     * @param permissions - Array of permissions to check
+     * @returns True if player has all permissions
+     */
+    hasAllPermissions(source: number, permissions: string[]): Promise<boolean>;
+    /**
+     * Gets all permissions for a player.
+     *
+     * @param source - FiveM client/server ID
+     * @returns Array of permission strings
+     */
+    getPermissions(source: number): Promise<string[]>;
+    /**
+     * Gets the rank value for a player.
+     *
+     * @param source - FiveM client/server ID
+     * @returns Rank number or null if not set
+     */
+    getRank(source: number): Promise<number | null>;
+    /**
+     * Gets the principal name/role name for a player.
+     *
+     * @param source - FiveM client/server ID
+     * @returns Role name or null
+     */
+    getPrincipalName(source: number): Promise<string | null>;
+    /**
+     * Gets principal metadata for a player.
+     *
+     * @param source - FiveM client/server ID
+     * @param key - Metadata key
+     * @returns Metadata value or null
+     */
+    getPrincipalMeta(source: number, key: string): Promise<unknown>;
+    /**
+     * Enforces access control requirements, throwing on failure.
+     *
+     * @remarks
+     * Used by RESOURCE mode to delegate security validation to CORE.
+     * Validates rank and/or permission requirements and throws if player
+     * doesn't meet the criteria.
+     *
+     * @param source - FiveM client/server ID
+     * @param requirements - Guard options containing rank and/or permission requirements
+     *
+     * @throws AppError - AUTH:UNAUTHORIZED, GAME:NO_RANK_IN_PRINCIPAL, or AUTH:PERMISSION_DENIED
+     */
+    enforce(source: number, requirements: GuardOptions): Promise<void>;
+}
+export interface CoreCommandsExports {
+    /**
+     * Registers a command from a RESOURCE with CORE.
+     *
+     * @remarks
+     * CORE maintains command registry and routes execution back to the owning resource.
+     * Handlers remain in the RESOURCE and are invoked via event when command executes.
+     *
+     * @param metadata - Command registration metadata
+     */
+    registerCommand(metadata: CommandRegistrationDto): void;
+    /**
+     * Executes a registered command (called by RESOURCE when delegating).
+     *
+     * @param clientID - Player client ID
+     * @param commandName - Command name (without leading slash)
+     * @param args - Raw argument strings
+     */
+    executeCommand(clientID: number, commandName: string, args: string[]): Promise<void>;
+    /**
+     * Returns all registered commands (local + remote).
+     *
+     * @returns Array of command metadata
+     */
+    getAllCommands(): CommandInfo[];
+}
+export interface CorePlayerExports {
+    /**
+     * Gets persistent account ID for a client.
+     *
+     * @param clientID - FiveM client/server ID
+     * @returns Account ID or undefined if not linked
+     */
+    getPlayerId(clientID: number): string | undefined;
+    /**
+     * Retrieves session metadata for a player.
+     *
+     * @param clientID - FiveM client/server ID
+     * @param key - Metadata key
+     * @returns Stored value or undefined
+     */
+    getPlayerMeta(clientID: number, key: string): Promise<any>;
+    /**
+     * Stores session metadata for a player.
+     *
+     * @param clientID - FiveM client/server ID
+     * @param key - Metadata key
+     * @param value - Value to store
+     */
+    setPlayerMeta(clientID: number, key: string, value: unknown): void;
+    /**
+     * Gets complete serialized player data.
+     *
+     * @param clientID - FiveM client/server ID
+     * @returns Serialized player data or null if not found
+     */
+    getPlayerData(clientID: number): SerializedPlayerData | null;
+    getManyData(clientIds: number[]): SerializedPlayerData[];
+    /**
+     * Gets serialized data for all connected players.
+     *
+     * @returns Array of serialized player data
+     */
+    getAllPlayersData(): SerializedPlayerData[];
+    /**
+     * Finds a player by their persistent account ID.
+     *
+     * @param accountId - Database account identifier
+     * @returns Serialized player data or null if not online
+     */
+    getPlayerByAccountId(accountId: string): SerializedPlayerData | null;
+    /**
+     * Gets the current player count.
+     *
+     * @returns Number of connected players
+     */
+    getPlayerCount(): number;
+    /**
+     * Checks if a player with given account ID is online.
+     *
+     * @param accountId - Database account identifier
+     * @returns True if player is connected
+     */
+    isPlayerOnline(accountId: string): boolean;
+    /**
+     * Gets all active state flags for a player.
+     *
+     * @param clientID - FiveM client/server ID
+     * @returns Array of active state strings
+     */
+    getPlayerStates(clientID: number): string[];
+    /**
+     * Checks if player has a specific state.
+     *
+     * @param clientID - FiveM client/server ID
+     * @param state - State identifier to check
+     * @returns True if state is active
+     */
+    hasPlayerState(clientID: number, state: string): boolean;
+    /**
+     * Adds a state flag to a player.
+     *
+     * @param clientID - FiveM client/server ID
+     * @param state - State identifier to add
+     */
+    addPlayerState(clientID: number, state: string): void;
+    /**
+     * Removes a state flag from a player.
+     *
+     * @param clientID - FiveM client/server ID
+     * @param state - State identifier to remove
+     */
+    removePlayerState(clientID: number, state: string): void;
+}

package/dist/runtime/server/types/core-exports.js

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

package/dist/runtime/server/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from './core-events';
+export * from './core-exports';
+export * from './security.types';
+export * from './vehicle.types';

package/dist/runtime/server/types/index.js

@@ -0,0 +1,20 @@
+"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("./core-events"), exports);
+__exportStar(require("./core-exports"), exports);
+__exportStar(require("./security.types"), exports);
+__exportStar(require("./vehicle.types"), exports);

package/dist/runtime/server/types/security.types.js

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

package/dist/runtime/server/types/vehicle.types.d.ts

@@ -0,0 +1,152 @@
+import { Vector3 } from '../../../kernel/utils';
+/**
+ * Vehicle ownership information
+ */
+export interface VehicleOwnership {
+    /** Client ID of the owner (if player-owned) */
+    clientID?: number;
+    /** Account ID of the owner (if persistent) */
+    accountID?: string;
+    /** Type of ownership */
+    type: 'player' | 'server' | 'temporary' | 'shared';
+}
+/**
+ * Vehicle modification data structure
+ */
+export interface VehicleMods {
+    spoiler?: number;
+    frontBumper?: number;
+    rearBumper?: number;
+    sideSkirt?: number;
+    exhaust?: number;
+    frame?: number;
+    grille?: number;
+    hood?: number;
+    fender?: number;
+    rightFender?: number;
+    roof?: number;
+    engine?: number;
+    brakes?: number;
+    transmission?: number;
+    horns?: number;
+    suspension?: number;
+    armor?: number;
+    turbo?: boolean;
+    xenon?: boolean;
+    xenonColor?: number;
+    wheelType?: number;
+    wheels?: number;
+    windowTint?: number;
+    livery?: number;
+    plateStyle?: number;
+    primaryColor?: number;
+    secondaryColor?: number;
+    pearlescentColor?: number;
+    wheelColor?: number;
+    neonEnabled?: [boolean, boolean, boolean, boolean];
+    neonColor?: [number, number, number];
+    extras?: Record<number, boolean>;
+}
+/**
+ * Options for creating a new vehicle
+ */
+export interface VehicleCreateOptions {
+    /** Vehicle model name or hash */
+    model: string;
+    /** Spawn position */
+    position: Vector3;
+    /** Heading/rotation in degrees */
+    heading?: number;
+    /** License plate text */
+    plate?: string;
+    /** Primary color */
+    primaryColor?: number;
+    /** Secondary color */
+    secondaryColor?: number;
+    /** Initial modifications */
+    mods?: Partial<VehicleMods>;
+    /** Whether vehicle should be persistent (survives server restart if saved) */
+    persistent?: boolean;
+    /** Ownership information */
+    ownership?: Partial<VehicleOwnership>;
+    /** Custom metadata */
+    metadata?: Record<string, any>;
+    /** Routing bucket (default: 0) */
+    routingBucket?: number;
+    /** Whether to lock the vehicle */
+    locked?: boolean;
+    /** Fuel level (0.0-1.0) */
+    fuel?: number;
+}
+/**
+ * Options for modifying an existing vehicle
+ */
+export interface VehicleModificationOptions {
+    /** Network ID of the vehicle to modify */
+    networkId: number;
+    /** Modifications to apply */
+    mods: Partial<VehicleMods>;
+    /** Client ID requesting the modification (for validation) */
+    requestedBy?: number;
+}
+/**
+ * Vehicle metadata stored in state bags
+ */
+export interface VehicleMetadata {
+    /** Custom key-value pairs */
+    [key: string]: any;
+    /** Fuel level */
+    fuel?: number;
+    /** Engine health */
+    engineHealth?: number;
+    /** Body health */
+    bodyHealth?: number;
+    /** Last driver client ID */
+    lastDriver?: number;
+    /** Creation timestamp */
+    createdAt?: number;
+    /** Last modification timestamp */
+    modifiedAt?: number;
+}
+/**
+ * Serialized vehicle data for network transfer
+ */
+export interface SerializedVehicleData {
+    /** Network ID */
+    networkId: number;
+    /** Entity handle (server-side) */
+    handle: number;
+    /** Vehicle model hash */
+    modelHash: number;
+    /** Vehicle model */
+    model: string;
+    /** Current position */
+    position: Vector3;
+    /** Current heading */
+    heading: number;
+    /** License plate */
+    plate: string;
+    /** Ownership information */
+    ownership: VehicleOwnership;
+    /** Applied modifications */
+    mods: VehicleMods;
+    /** Custom metadata */
+    metadata: VehicleMetadata;
+    /** Routing bucket */
+    routingBucket: number;
+    /** Whether vehicle is persistent */
+    persistent: boolean;
+}
+/**
+ * Vehicle spawn result
+ */
+export interface VehicleSpawnResult {
+    /** Network ID of the spawned vehicle */
+    networkId: number;
+    /** Entity handle */
+    handle: number;
+    /** Success status */
+    success: boolean;
+    /** Error message if failed */
+    error?: string;
+}

package/dist/runtime/server/types/vehicle.types.js

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

package/package.json

@@ -1,98 +1,98 @@
-{
-  "name": "@open-core/framework",
-  "version": "0.1.0-alpha.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/server/index.d.ts",
-      "import": "./dist/server/index.js",
-      "require": "./dist/server/index.js"
-    },
-    "./client": {
-      "types": "./dist/client/index.d.ts",
-      "import": "./dist/client/index.js",
-      "require": "./dist/client/index.js"
-    },
-    "./shared": {
-      "types": "./dist/shared/index.d.ts",
-      "import": "./dist/shared/index.js",
-      "require": "./dist/shared/index.js"
-    },
-    "./utils": {
-      "types": "./dist/utils/index.d.ts",
-      "import": "./dist/utils/index.js",
-      "require": "./dist/utils/index.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "watch": "tsc -p tsconfig.build.json --watch",
-    "lint": "eslint . --ext .ts",
-    "lint:fix": "eslint . --ext .ts --fix",
-    "format": "prettier --write .",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:unit": "vitest run --project unit",
-    "test:integration": "vitest run --project integration",
-    "test:coverage": "vitest run --coverage",
-    "bench": "tsx benchmark/index.ts",
-    "bench:core": "tsx benchmark/index.ts --core",
-    "bench:load": "vitest run --project benchmark",
-    "bench:all": "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": {
-    "@citizenfx/client": "2.0.22443-1",
-    "@citizenfx/server": "2.0.22443-1",
-    "@types/node": "^24.10.1",
-    "@typescript-eslint/eslint-plugin": "^8.48.1",
-    "@typescript-eslint/parser": "^8.48.1",
-    "@vitest/coverage-v8": "^4.0.15",
-    "eslint": "^9.39.1",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-prettier": "^5.5.4",
-    "prettier": "3.7.1",
-    "tinybench": "^2.7.0",
-    "tsx": "^4.19.2",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.15"
-  }
-}
+{
+  "name": "@open-core/framework",
+  "version": "0.2.1-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": {
+    "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"
+  }
+}

package/dist/client/client-bootstrap.d.ts

@@ -1 +0,0 @@
-export declare function initClientCore(): Promise<void>;