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

package/dist/runtime/server/ports/authorization.api-port.js

@@ -0,0 +1,28 @@
+/**
+ * Core port that provides access to player authorization and permissions.
+ *
+ * @remarks
+ * This port defines a framework-owned boundary for querying permission-related data
+ * regardless of the current runtime mode (CORE, RESOURCE, etc.).
+ *
+ * Implementations of this port are responsible for resolving permission information
+ * from the authoritative source (local provider, remote core exports, etc.).
+ *
+ * **Mode Differences:**
+ * - **CORE/STANDALONE**: Uses the user-provided PrincipalProviderContract directly
+ * - **RESOURCE**: Delegates to CORE via exports
+ *
+ * **Usage:**
+ * ```typescript
+ * @injectable()
+ * class MyService {
+ *   constructor(private principal: PrincipalPort) {}
+ *
+ *   async canBan(player: Player): Promise<boolean> {
+ *     return await this.principal.hasPermission(player, 'admin.ban')
+ *   }
+ * }
+ * ```
+ */
+export class Authorization {
+}

package/dist/runtime/server/ports/channel.api-port.d.ts

@@ -0,0 +1,218 @@
+import { RGB } from 'src/kernel';
+import { Channel } from '../concepts/channel';
+import { Player } from '../entities';
+import { ChannelMetadata, ChannelType, IChannelValidator } from '../types';
+export declare abstract class Channels {
+    /**
+     * Sets a custom validator for channel operations.
+     *
+     * @remarks
+     * Validators control who can subscribe to channels and who can broadcast messages.
+     * Only works in CORE/STANDALONE mode. In RESOURCE mode, validators must be set in CORE.
+     *
+     * @param validator - Custom validator implementing IChannelValidator
+     *
+     * @example
+     * ```typescript
+     * channels.setValidator({
+     *   canSubscribe: (player, channelId) => {
+     *     return !player.hasState('banned')
+     *   },
+     *   canBroadcast: (player, channelId) => {
+     *     return !player.hasState('muted')
+     *   }
+     * })
+     * ```
+     */
+    abstract setValidator(validator: IChannelValidator): void;
+    /**
+     * Creates a new channel.
+     *
+     * @param id - Unique channel identifier (e.g., 'group:police', 'radio:100')
+     * @param metadata - Channel configuration (type, persistence, etc.)
+     * @param maxSubscribers - Optional maximum number of subscribers
+     * @returns The created channel
+     * @throws Error if channel with the same ID already exists
+     *
+     * @example
+     * ```typescript
+     * const channel = channels.create('radio:100', {
+     *   type: ChannelType.RADIO,
+     *   frequency: 100,
+     *   persistent: true
+     * })
+     * ```
+     */
+    abstract create(id: string, metadata: ChannelMetadata, maxSubscribers?: number): Channel;
+    /**
+     * Creates a private channel for specific players.
+     *
+     * @remarks
+     * Automatically subscribes all provided players to the channel.
+     * Channel ID is auto-generated and non-persistent.
+     *
+     * @param players - Array of players to include in the private channel
+     * @param metadata - Channel configuration (type should be PRIVATE)
+     * @returns The created private channel with all players subscribed
+     *
+     * @example
+     * ```typescript
+     * const privateChannel = channels.createPrivate([player1, player2], {
+     *   type: ChannelType.PRIVATE,
+     *   persistent: false
+     * })
+     * channels.broadcast(privateChannel.id, player1, 'Private message')
+     * ```
+     */
+    abstract createPrivate(players: Player[], metadata: ChannelMetadata): Channel;
+    abstract get(id: string): Channel | undefined;
+    abstract delete(id: string): boolean;
+    abstract exists(id: string): boolean;
+    /**
+     * Subscribes a player to a channel.
+     *
+     * @remarks
+     * If a validator is set, it will be checked before subscribing.
+     * Players can only be subscribed once to the same channel.
+     *
+     * @param channelId - Channel identifier
+     * @param player - Player to subscribe
+     * @param metadata - Optional subscription metadata
+     * @returns true if subscribed successfully, false if validation failed or already subscribed
+     * @throws Error if channel doesn't exist
+     *
+     * @example
+     * ```typescript
+     * if (channels.subscribe('group:police', player)) {
+     *   // Player joined the group channel
+     * }
+     * ```
+     */
+    abstract subscribe(channelId: string, player: Player, metadata?: Record<string, unknown>): boolean;
+    /**
+     * Unsubscribes a player from a channel.
+     *
+     * @param channelId - Channel identifier
+     * @param player - Player to unsubscribe
+     * @returns true if unsubscribed successfully, false if channel doesn't exist or player wasn't subscribed
+     */
+    abstract unsubscribe(channelId: string, player: Player): boolean;
+    abstract isSubscribed(channelId: string, player: Player): boolean;
+    /**
+     * Broadcasts a message to all subscribers of a channel.
+     *
+     * @remarks
+     * If a validator is set, it will check if the sender can broadcast.
+     * Only sends to currently subscribed players.
+     *
+     * @param channelId - Channel identifier
+     * @param sender - Player sending the message
+     * @param message - Message content
+     * @param author - Display name for the sender (defaults to sender.name)
+     * @param color - Message color (defaults to white)
+     * @throws Error if channel doesn't exist
+     *
+     * @example
+     * ```typescript
+     * channels.broadcast(
+     *   'group:police',
+     *   player,
+     *   'Suspect heading north',
+     *   undefined,
+     *   { r: 0, g: 100, b: 255 }
+     * )
+     * ```
+     */
+    abstract broadcast(channelId: string, sender: Player, message: string, author?: string, color?: RGB): void;
+    /**
+     * Broadcasts a system message to all subscribers of a channel.
+     *
+     * @remarks
+     * System messages bypass validator checks and don't require a sender.
+     *
+     * @param channelId - Channel identifier
+     * @param message - Message content
+     * @param author - Display name (defaults to 'SYSTEM')
+     * @param color - Message color (defaults to light blue)
+     * @throws Error if channel doesn't exist
+     *
+     * @example
+     * ```typescript
+     * channels.broadcastSystem(
+     *   'group:police',
+     *   'group meeting in 5 minutes',
+     *   'DISPATCH'
+     * )
+     * ```
+     */
+    abstract broadcastSystem(channelId: string, message: string, author?: string, color?: RGB): void;
+    abstract getSubscribers(channelId: string): Player[];
+    /**
+     * Gets all channels of a specific type.
+     *
+     * @param type - Channel type to filter by
+     * @returns Array of channels matching the type
+     *
+     * @example
+     * ```typescript
+     * const groupChannels = channels.getChannelsByType(ChannelType.group)
+     * ```
+     */
+    abstract getChannelsByType(type: ChannelType): Channel[];
+    /**
+     * Gets all channels a player is subscribed to.
+     *
+     * @param player - Player to check
+     * @returns Array of channels the player is subscribed to
+     *
+     * @example
+     * ```typescript
+     * const playerChannels = channels.getChannelsByPlayer(player)
+     * playerChannels.forEach(ch => {
+     *   console.log(`Player is in channel: ${ch.id}`)
+     * })
+     * ```
+     */
+    abstract getChannelsByPlayer(player: Player): Channel[];
+    abstract getAllChannels(): Channel[];
+    /**
+     * Clears all channels and their subscribers.
+     *
+     * @remarks
+     * Persistent channels are cleared but not deleted.
+     * Only available in CORE/STANDALONE mode.
+     */
+    abstract clear(): void;
+    /**
+     * Deletes all non-persistent (temporary) channels.
+     *
+     * @remarks
+     * Useful for cleanup operations. Persistent channels are not affected.
+     * Only available in CORE/STANDALONE mode.
+     */
+    abstract clearNonPersistent(): void;
+    /**
+     * Creates a temporary proximity-based channel around a player.
+     *
+     * @remarks
+     * Automatically subscribes all players within the specified radius.
+     * Channel is non-persistent and should be deleted after use.
+     * Calculates 3D distance between players.
+     *
+     * @param originPlayer - Player at the center of the proximity area
+     * @param radius - Distance radius in game units
+     * @param channelId - Optional custom channel ID (auto-generated if not provided)
+     * @returns The created channel with nearby players subscribed, or undefined if origin player has no position
+     *
+     * @example
+     * ```typescript
+     * // Create proximity channel for local chat
+     * const nearby = channels.createProximityChannel(player, 50.0)
+     * if (nearby) {
+     *   channels.broadcast(nearby.id, player, 'Hello nearby players!')
+     *   channels.delete(nearby.id) // Clean up
+     * }
+     * ```
+     */
+    abstract createProximityChannel(originPlayer: Player, radius: number, channelId?: string): Channel | undefined;
+}

package/dist/runtime/server/ports/channel.api-port.js

@@ -0,0 +1,2 @@
+export class Channels {
+}

package/dist/runtime/server/ports/internal/command-execution.port.d.ts

@@ -0,0 +1,48 @@
+import { CommandMetadata } from '../../decorators/command';
+import { Player } from '../../entities';
+/**
+ * Command information returned by getAllCommands.
+ */
+export interface CommandInfo {
+    command: string;
+    description?: string;
+    usage?: string;
+    isPublic: boolean;
+}
+/**
+ * Abstract port for command registration and execution.
+ *
+ * @remarks
+ * This port provides mode-agnostic access to the command system.
+ * Implementations:
+ * - CommandService (local): CORE/STANDALONE modes maintain command registry locally
+ * - RemoteCommandService (remote): RESOURCE mode delegates to CORE via exports
+ */
+export declare abstract class CommandExecutionPort {
+    /**
+     * Registers a command handler.
+     *
+     * @param metadata - Command metadata from decorator
+     * @param handler - Bound method to invoke when command is executed
+     */
+    abstract register(metadata: CommandMetadata, handler: (...args: any[]) => any): void;
+    /**
+     * Executes a registered command.
+     *
+     * @param player - Player invoking the command
+     * @param commandName - Command name (without leading slash)
+     * @param args - Raw argument strings
+     */
+    abstract execute(player: Player, commandName: string, args: string[]): Promise<void>;
+    /**
+     * Returns metadata for a command if registered in this runtime.
+     *
+     * @remarks
+     * Used to enrich error observation (usage/description/etc.).
+     */
+    abstract getCommandMeta(commandName: string): CommandMetadata | undefined;
+    /**
+     * Returns all registered commands.
+     */
+    abstract getAllCommands(): CommandInfo[];
+}

package/dist/runtime/server/ports/internal/command-execution.port.js

@@ -0,0 +1,11 @@
+/**
+ * Abstract port for command registration and execution.
+ *
+ * @remarks
+ * This port provides mode-agnostic access to the command system.
+ * Implementations:
+ * - CommandService (local): CORE/STANDALONE modes maintain command registry locally
+ * - RemoteCommandService (remote): RESOURCE mode delegates to CORE via exports
+ */
+export class CommandExecutionPort {
+}

package/dist/runtime/server/ports/internal/player-session-lifecycle.port.d.ts

@@ -0,0 +1,37 @@
+import { Player } from '../../entities';
+import { PlayerSession } from '../../services';
+/**
+ * Core port responsible for managing the lifecycle of player sessions.
+ *
+ * @remarks
+ * This port defines the authoritative boundary for creating, linking, and
+ * destroying player sessions within the framework.
+ *
+ * Implementations of this port own the session state and are expected to be
+ * invoked in response to connection, authentication, and disconnection events.
+ */
+export declare abstract class PlayerSessionLifecyclePort {
+    /**
+     * Creates and binds a new player session to a connected client.
+     *
+     * @remarks
+     * This method is typically called when a player joins the server or completes
+     * the initial handshake phase. The returned {@link Player} represents the
+     * runtime session associated with the client.
+     *
+     * @param clientID - The FiveM server client ID (`source`).
+     * @param identifiers - Optional platform identifiers (license, steam, etc.).
+     * @returns The newly created {@link Player} instance.
+     */
+    abstract bind(clientID: number, identifiers?: PlayerSession['identifiers']): Player;
+    /**
+     * Terminates and removes the player session associated with a client.
+     *
+     * @remarks
+     * This method should be called when the client disconnects to ensure
+     * session state is properly cleaned up and memory is released.
+     *
+     * @param clientID - The FiveM server client ID (`source`).
+     */
+    abstract unbind(clientID: number): void;
+}

package/dist/runtime/server/ports/internal/player-session-lifecycle.port.js

@@ -0,0 +1,12 @@
+/**
+ * Core port responsible for managing the lifecycle of player sessions.
+ *
+ * @remarks
+ * This port defines the authoritative boundary for creating, linking, and
+ * destroying player sessions within the framework.
+ *
+ * Implementations of this port own the session state and are expected to be
+ * invoked in response to connection, authentication, and disconnection events.
+ */
+export class PlayerSessionLifecyclePort {
+}

package/dist/runtime/server/ports/players.api-port.d.ts

@@ -0,0 +1,108 @@
+import { Player } from '../entities';
+import { LinkedID } from '../services';
+/**
+ * Core port that provides access to active player sessions.
+ *
+ * @remarks
+ * This port defines a framework-owned boundary for querying and managing player-related data
+ * regardless of the current runtime mode (CORE, RESOURCE, etc.).
+ *
+ * Implementations of this port are responsible for resolving player information
+ * from the authoritative source (local session store, remote core exports, etc.).
+ *
+ * Consumers should treat returned {@link Player} instances as runtime representations
+ * of connected clients, not as persistent domain models.
+ *
+ * **Mode Differences:**
+ * - **CORE/STANDALONE**: Data is local and authoritative
+ * - **RESOURCE**: Data is fetched from CORE via exports
+ */
+export declare abstract class Players {
+    /**
+     * Returns the {@link Player} associated with a given FiveM client ID.
+     *
+     * @param clientID - The FiveM server client ID (`source`).
+     * @returns The corresponding {@link Player} instance, or `undefined` if the player is not connected.
+     */
+    abstract getByClient(clientID: number): Player | undefined;
+    /**
+     * Returns a group of {@link Player} associated with a given fivem clients ids
+     *
+     * @param clientIds The fivem server client ID (`source`)
+     */
+    abstract getMany(clientIds: number[]): Player[];
+    /**
+     * Returns all currently connected players.
+     *
+     * @returns An array of {@link Player} instances representing all active clients.
+     */
+    abstract getAll(): Player[];
+    /**
+     * Returns the persistent account identifier associated with a client.
+     *
+     * @remarks
+     * The returned identifier is typically assigned after authentication and may be
+     * `undefined` if the player has not completed the login or character selection flow.
+     *
+     * @param clientID - The FiveM server client ID (`source`).
+     * @returns The linked account ID, or `undefined` if none is associated.
+     */
+    abstract getAccountLinked(clientID: number): LinkedID | undefined;
+    /**
+     * Retrieves a metadata value associated with a player session.
+     *
+     * @remarks
+     * Metadata values are transient and scoped to the current session.
+     * Implementations may resolve this data locally or delegate to the core runtime.
+     *
+     * @typeParam T - The expected type of the stored value.
+     * @param clientID - The FiveM server client ID (`source`).
+     * @param key - The metadata key to retrieve.
+     * @returns The stored value, or `undefined` if the key does not exist.
+     */
+    abstract getMeta<T = unknown>(clientID: number, key: string): Promise<T | undefined>;
+    /**
+     * Stores a metadata value in the player session.
+     *
+     * @remarks
+     * Metadata is intended for transient runtime state such as flags, gameplay context,
+     * or temporary attributes. It is not persisted across reconnects.
+     *
+     * @param clientID - The FiveM server client ID (`source`).
+     * @param key - The metadata key to store.
+     * @param value - The value to associate with the given key.
+     */
+    abstract setMeta(clientID: number, key: string, value: unknown): void;
+    /**
+     * Returns the {@link Player} associated with a persistent account ID.
+     *
+     * @remarks
+     * Searches all connected players for one with the matching accountID.
+     * Returns `undefined` if no player with that account is currently online.
+     *
+     * @param accountId - The persistent account identifier.
+     * @returns The corresponding {@link Player} instance, or `undefined` if not online.
+     */
+    abstract getByAccountId(accountId: string): Player | undefined;
+    /**
+     * Returns the current number of connected players.
+     *
+     * @remarks
+     * More efficient than `getAll().length` for implementations that
+     * can provide a count without fetching all player data.
+     *
+     * @returns The number of currently connected players.
+     */
+    abstract getPlayerCount(): number;
+    /**
+     * Checks if a player with the given account ID is currently online.
+     *
+     * @remarks
+     * More efficient than `getByAccountId() !== undefined` for implementations
+     * that can check presence without fetching full player data.
+     *
+     * @param accountId - The persistent account identifier.
+     * @returns `true` if the player is online, `false` otherwise.
+     */
+    abstract isOnline(accountId: string): boolean;
+}

package/dist/runtime/server/ports/players.api-port.js

@@ -0,0 +1,19 @@
+/**
+ * Core port that provides access to active player sessions.
+ *
+ * @remarks
+ * This port defines a framework-owned boundary for querying and managing player-related data
+ * regardless of the current runtime mode (CORE, RESOURCE, etc.).
+ *
+ * Implementations of this port are responsible for resolving player information
+ * from the authoritative source (local session store, remote core exports, etc.).
+ *
+ * Consumers should treat returned {@link Player} instances as runtime representations
+ * of connected clients, not as persistent domain models.
+ *
+ * **Mode Differences:**
+ * - **CORE/STANDALONE**: Data is local and authoritative
+ * - **RESOURCE**: Data is fetched from CORE via exports
+ */
+export class Players {
+}

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

@@ -0,0 +1,192 @@
+export type FrameworkMode = 'CORE' | 'RESOURCE' | 'STANDALONE';
+/**
+ * Feature provider source configuration.
+ *
+ * @remarks
+ * Determines where a feature's implementation comes from:
+ *
+ * - `'core'`: Feature provided by CORE resource via exports
+ *   - Used in RESOURCE mode for: players, principal, auth, commands
+ *   - Triggers remote service implementations that delegate to CORE
+ *
+ * - `'local'`: Feature implemented locally in current resource
+ *   - Used in CORE/STANDALONE for all features
+ *   - Used in RESOURCE for: netEvents, runtimeEvents, exports, http, chat
+ *   - Triggers local service implementations
+ *
+ * @example
+ * ```typescript
+ * // RESOURCE mode - commands delegate to CORE
+ * commands: { enabled: true, provider: 'core' }
+ *
+ * // STANDALONE mode - commands execute locally
+ * commands: { enabled: true, provider: 'local' }
+ * ```
+ */
+export type FeatureProvider = 'core' | 'local';
+export type FeatureScope = 'core' | 'resource' | 'standalone';
+export type FeatureName = 'players' | 'netEvents' | 'runtimeEvents' | 'commands' | 'exports' | 'chat' | 'principal' | 'sessionLifecycle';
+/**
+ * User-facing feature configuration.
+ *
+ * @remarks
+ * Most features are enabled by default and providers are auto-inferred.
+ * Use this config only if you need to explicitly disable a feature.
+ */
+export interface UserFeatureConfig {
+    /** Disable specific features if needed */
+    disabled?: FeatureName[];
+}
+/**
+ * Internal feature contract with all fields resolved.
+ *
+ * @remarks
+ * This is used internally by the framework after merging user config with defaults.
+ * Users don't interact with this directly.
+ *
+ * @internal
+ */
+export interface FeatureContract {
+    /**
+     * Enables or disables the feature at runtime.
+     *
+     * If `required` is `true`, this must also be `true` (otherwise validation will throw).
+     */
+    enabled: boolean;
+    /**
+     * Determines where the implementation comes from.
+     *
+     * - `core`: feature is provided by the core resource (via exports when applicable)
+     * - `local`: feature is implemented/handled locally by the current runtime (resource/standalone)
+     */
+    provider: FeatureProvider;
+    /**
+     * Marks the feature as exportable via FiveM exports.
+     *
+     * Only meaningful in CORE mode. When `true`, the framework dynamically imports
+     * export controllers that expose the feature's API to RESOURCE mode.
+     */
+    export: boolean;
+    /**
+     * The runtime scope this feature contract is intended for.
+     *
+     * Must match the scope derived from the current FrameworkMode
+     */
+    scope: FeatureScope;
+    /**
+     * Marks the feature as mandatory for the current runtime configuration.
+     *
+     * When `true`, the feature cannot be disabled (`enabled` must be `true`).
+     */
+    required: boolean;
+    /**
+     * (sessionLifecycle only) Enable automatic session recovery on resource restart.
+     *
+     * @remarks
+     * When true, scans for connected players on startup and creates sessions
+     * for any that don't have an active session.
+     *
+     * @defaultValue true
+     */
+    recoveryOnRestart?: boolean;
+}
+export type FrameworkFeatures = Record<FeatureName, FeatureContract>;
+export interface DevModeConfig {
+    /**
+     * Master switch for development mode.
+     * If false, no dev tools will be loaded.
+     */
+    enabled: boolean;
+    /**
+     * CLI bridge configuration for telemetry and logs.
+     * The bridge allows the OpenCore CLI to stream logs and inspect the framework state.
+     */
+    bridge?: {
+        /** WebSocket URL of the bridge */
+        url: string;
+        /** Whether to connect automatically on startup */
+        autoConnect: boolean;
+    };
+    /**
+     * Event interceptor configuration for debugging.
+     * Captures and records incoming/outgoing network events and commands.
+     */
+    interceptor?: {
+        /** Enable event interception */
+        enabled: boolean;
+        /** Whether to record a history of events in memory */
+        recordHistory: boolean;
+        /** Maximum number of events to keep in the history buffer */
+        maxHistorySize: number;
+    };
+    /**
+     * Player simulator configuration.
+     * Allows creating virtual players for testing logic without game clients.
+     */
+    simulator?: {
+        /** Enable player simulation features */
+        enabled: boolean;
+        /** Number of virtual players to connect automatically on startup */
+        autoConnectPlayers: number;
+    };
+}
+export interface Hooks {
+    waitFor?: Promise<any> | Promise<any>[];
+    onReady?: () => Promise<void> | void;
+}
+export interface ServerRuntimeOptions {
+    mode: FrameworkMode;
+    features: FrameworkFeatures;
+    coreResourceName: string;
+    /** Development mode configuration (disabled in production) */
+    devMode?: DevModeConfig;
+    onDependency?: Hooks;
+}
+export type RuntimeContext = ServerRuntimeOptions;
+export declare function setRuntimeContext(ctx: RuntimeContext): void;
+export declare function getRuntimeContext(): RuntimeContext;
+export declare function getFrameworkModeScope(mode: FrameworkMode): FeatureScope;
+/**
+ * Server initialization configuration.
+ *
+ * @remarks
+ * Defines the runtime mode and feature configuration for OpenCore.
+ *
+ * @example Minimal Mode
+ * ```typescript
+ * Server.init({
+ *   mode: 'CORE'
+ * })
+ * ```
+ */
+export interface ServerInitOptions {
+    /** Runtime mode determining feature availability and provider sources */
+    mode: FrameworkMode;
+    /**
+     * Feature configuration.
+     *
+     * @remarks
+     * Most features are enabled by default. Use this only to disable specific ones.
+     */
+    features?: UserFeatureConfig;
+    /**
+     * Name of the CORE resource.
+     *
+     * @remarks
+     * - **Required in RESOURCE mode** (to locate CORE exports)
+     * - Optional in CORE/STANDALONE modes
+     *
+     * @defaultValue 'core'
+     */
+    coreResourceName?: string;
+    /** Development mode configuration (disabled in production) */
+    devMode?: DevModeConfig;
+    /** If you want to wait for a dependency promise, or when ready do something (By default, the core server will emit a "ready" when it is ready to all resources.)  */
+    onDependency?: Hooks;
+}
+export declare function resolveRuntimeOptions(options: ServerInitOptions): ServerRuntimeOptions;
+export declare function validateRuntimeOptions(options: ServerRuntimeOptions): void;
+/**
+ * @deprecated Use validateRuntimeOptions instead
+ */
+export declare const validateRuntimeContextOrThrow: typeof validateRuntimeOptions;