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

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

@@ -0,0 +1,286 @@
+import { Principal } from './principal.type';
+import { GuardOptions } from '../decorators/guard';
+import { StateRequirement } from '../decorators/requiresState';
+import { ThrottleOptions } from '../decorators/throttle';
+import { CommandInfo } from '../ports/internal/command-execution.port';
+import { LinkedID } from './linked-id';
+/**
+ * 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 InternalPrincipalExports {
+    /**
+     * 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 - 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 InternalCommandsExports {
+    /**
+     * 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 InternalPlayerExports {
+    /**
+     * Gets persistent account ID for a client.
+     *
+     * @param clientID - FiveM client/server ID
+     * @returns Account ID or undefined if not linked
+     */
+    getPlayerId(clientID: number): LinkedID | 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 - 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 - 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/framework-events.types.d.ts

@@ -0,0 +1,22 @@
+import { Player } from '../entities';
+export interface PlayerSessionCreatedPayload {
+    clientId: number;
+    license: string | undefined;
+}
+export interface PlayerSessionDestroyedPayload {
+    clientId: number;
+}
+export interface PlayerFullyConnectedPayload {
+    player: Player;
+}
+export interface PlayerSessionRecoveredPayload {
+    clientId: number;
+    player: Player;
+    license: string | undefined;
+}
+export type FrameworkEventsMap = {
+    'internal:playerSessionCreated': PlayerSessionCreatedPayload;
+    'internal:playerSessionDestroyed': PlayerSessionDestroyedPayload;
+    'internal:playerFullyConnected': PlayerFullyConnectedPayload;
+    'internal:playerSessionRecovered': PlayerSessionRecoveredPayload;
+};

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

@@ -0,0 +1,9 @@
+export * from './channel.types';
+export * from './core-exports.types';
+export * from './framework-events.types';
+export * from './linked-id';
+export * from './npc.types';
+export * from './parallel.types';
+export * from './player-session.types';
+export * from './principal.type';
+export * from './vehicle.types';

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

@@ -0,0 +1,9 @@
+export * from './channel.types';
+export * from './core-exports.types';
+export * from './framework-events.types';
+export * from './linked-id';
+export * from './npc.types';
+export * from './parallel.types';
+export * from './player-session.types';
+export * from './principal.type';
+export * from './vehicle.types';

package/dist/runtime/server/types/linked-id.d.ts

@@ -0,0 +1,6 @@
+import { UUIDTypes } from 'uuid';
+/**
+ * Type representing a linked account identifier. This come from your persistence layer
+ * and is used to associate a Player session with their stored data.
+ */
+export type LinkedID = string | UUIDTypes | number;

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

@@ -0,0 +1,36 @@
+import { Vector3 } from '../../../kernel/utils/vector3';
+export interface NpcMetadata {
+    [key: string]: unknown;
+}
+export interface NpcSpawnOptions {
+    id?: string;
+    model: string | number;
+    position: Vector3;
+    heading?: number;
+    networked?: boolean;
+    pedType?: number;
+    routingBucket?: number;
+    persistent?: boolean;
+    metadata?: NpcMetadata;
+}
+export interface NpcSpawnResult {
+    success: boolean;
+    id?: string;
+    handle?: number;
+    netId?: number;
+    error?: string;
+}
+export interface SerializedNpcData {
+    id: string;
+    handle: number;
+    netId?: number;
+    model: string;
+    modelHash: number;
+    position: Vector3;
+    heading: number;
+    routingBucket: number;
+    persistent: boolean;
+    createdAt: number;
+    meta: Record<string, unknown>;
+    states: string[];
+}

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

@@ -0,0 +1,191 @@
+/**
+ * ParallelCompute Module Types
+ *
+ * Provides type definitions for the parallel computation system.
+ */
+/**
+ * Task execution mode
+ */
+export type ExecutionMode = 'auto' | 'sync' | 'parallel';
+/**
+ * Worker pool configuration
+ */
+export interface WorkerPoolConfig {
+    /** Minimum number of workers to keep alive */
+    minWorkers: number;
+    /** Maximum number of workers to spawn */
+    maxWorkers: number;
+    /** Time in ms before idle workers are terminated */
+    idleTimeout: number;
+    /** Maximum time in ms a task can run before timeout */
+    taskTimeout: number;
+}
+/**
+ * Options for defining a parallel task
+ */
+export interface ParallelTaskOptions<TInput, TOutput> {
+    /** Unique name for the task (used for debugging and metrics) */
+    name: string;
+    /**
+     * Function to estimate computational cost based on input.
+     * Higher values = more likely to use worker.
+     * Return a number representing relative complexity.
+     */
+    estimateCost?: (input: TInput) => number;
+    /**
+     * If estimated cost exceeds this threshold, automatically use worker.
+     * Default: 10000
+     */
+    workerThreshold?: number;
+    /**
+     * The compute function to execute.
+     *
+     * Requirements/limitations:
+     * - MUST be pure (no closures / no external references).
+     * - Inputs/outputs MUST be structured-cloneable.
+     * - The function body is serialized with `Function#toString()` and evaluated in a worker.
+     */
+    compute: (input: TInput) => TOutput;
+    /**
+     * Optional function to split input into chunks for multiple workers.
+     * Enables parallel processing across multiple workers.
+     */
+    chunker?: (input: TInput, workerCount: number) => TInput[];
+    /**
+     * Optional function to merge results from multiple chunks.
+     * Required if chunker is provided.
+     */
+    merger?: (results: TOutput[]) => TOutput;
+}
+/**
+ * A defined parallel task that can be executed
+ */
+export interface ParallelTask<TInput, TOutput> {
+    /** Task name */
+    readonly name: string;
+    /** Task options */
+    readonly options: ParallelTaskOptions<TInput, TOutput>;
+    /**
+     * Execute the task with automatic mode selection.
+     * Uses worker if estimated cost exceeds threshold.
+     */
+    run(input: TInput): Promise<TOutput>;
+    /**
+     * Force execution on main thread (synchronous).
+     */
+    sync(input: TInput): TOutput;
+    /**
+     * Force execution on worker thread.
+     */
+    parallel(input: TInput): Promise<TOutput>;
+    /**
+     * Execute with multiple workers (requires chunker/merger).
+     */
+    distributed(input: TInput, workerCount?: number): Promise<TOutput>;
+}
+/**
+ * Message sent to worker
+ */
+export interface WorkerMessage {
+    id: string;
+    taskName: string;
+    functionBody: string;
+    input: unknown;
+}
+/**
+ * Response from worker
+ */
+export interface WorkerResponse {
+    id: string;
+    success: boolean;
+    result?: unknown;
+    error?: string;
+    executionTime: number;
+}
+/**
+ * Worker status
+ */
+export type WorkerStatus = 'idle' | 'busy' | 'terminated';
+/**
+ * Worker info for pool management
+ */
+export interface WorkerInfo {
+    id: number;
+    status: WorkerStatus;
+    currentTaskId: string | null;
+    tasksCompleted: number;
+    lastActiveAt: number;
+}
+/**
+ * Metrics for parallel compute service
+ */
+export interface ParallelComputeMetrics {
+    /** Total tasks executed */
+    totalTasks: number;
+    /** Tasks executed on main thread */
+    syncTasks: number;
+    /** Tasks executed on workers */
+    parallelTasks: number;
+    /** Tasks that failed */
+    failedTasks: number;
+    /** Average execution time in ms */
+    avgExecutionTime: number;
+    /** Total time saved by parallelization (estimated) */
+    estimatedTimeSaved: number;
+    /** Current active workers */
+    activeWorkers: number;
+    /** Peak worker count */
+    peakWorkers: number;
+}
+/**
+ * Task execution result with timing info
+ */
+export interface TaskResult<T> {
+    result: T;
+    executionTime: number;
+    mode: 'sync' | 'parallel' | 'distributed';
+    workerCount?: number;
+}
+/**
+ * Built-in compute functions for common operations
+ */
+export interface BuiltInComputes {
+    /**
+     * Filter entities by distance from a position
+     */
+    filterByDistance: <T extends {
+        x: number;
+        y: number;
+        z: number;
+    }>(input: {
+        entities: T[];
+        position: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        radius: number;
+    }) => T[];
+    /**
+     * Sort entities by distance from a position
+     */
+    sortByDistance: <T extends {
+        x: number;
+        y: number;
+        z: number;
+    }>(input: {
+        entities: T[];
+        position: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    }) => T[];
+    /**
+     * Batch process items with a transform function
+     */
+    batchProcess: <T, R>(input: {
+        items: T[];
+        transform: string;
+    }) => R[];
+}

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

@@ -0,0 +1,5 @@
+/**
+ * ParallelCompute Module Types
+ *
+ * Provides type definitions for the parallel computation system.
+ */

package/dist/runtime/server/types/player-session.types.d.ts

@@ -0,0 +1,11 @@
+import { LinkedID } from './linked-id';
+export interface PlayerSession {
+    clientID: number;
+    accountID?: LinkedID;
+    identifiers?: {
+        license?: string;
+        steam?: string;
+        discord?: string;
+    };
+    meta: Record<string, unknown>;
+}

package/dist/runtime/server/types/principal.type.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Represents the security identity of a user/player within the framework.
+ * This interface bridges the gap between the Core framework and your specific implementation.
+ */
+export interface Principal {
+    /**
+     * Unique identifier for the user (e.g., persistent role ID).
+     */
+    id: string;
+    /**
+     * Display name for the role or user, useful for Chat or UI (e.g., "Moderator", "VIP").
+     */
+    name?: string;
+    /**
+     * Numeric weight for hierarchy comparisons.
+     * - Used by the `@Guard({ rank: N })` decorator.
+     * - **Logic:** `UserRank >= RequiredRank`.
+     * - Higher numbers imply higher privileges.
+     */
+    rank?: number;
+    /**
+     * List of specific permission strings assigned to this principal.
+     * - Used by the `@Guard({ permission: 'string' })` decorator.
+     * - Supports the `'*'` wildcard for super-admin access.
+     */
+    permissions: string[];
+    /**
+     * Arbitrary metadata for game-specific logic (e.g., chat colors, badge IDs, staff status).
+     * This prevents the need to modify the Core types for visual extras.
+     */
+    meta?: Record<string, unknown>;
+}