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

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

@@ -0,0 +1,149 @@
+import { Principal } from '../types/principal.type';
+import { GuardOptions } from '../decorators/guard';
+import { Player } from '../entities';
+/**
+ * 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 declare abstract class Authorization {
+    /**
+     * Gets the full Principal object for a player.
+     *
+     * @param player - The player entity
+     * @returns Principal data or null if not authenticated
+     */
+    abstract getPrincipal(player: Player): Promise<Principal | null>;
+    /**
+     * Gets Principal by account ID (works for offline players too).
+     *
+     * @param accountId - Account identifier
+     * @returns Principal data or null
+     */
+    abstract getPrincipalByAccountId(accountId: string): Promise<Principal | null>;
+    /**
+     * Forces a refresh of the player's permissions from persistence.
+     *
+     * @remarks
+     * Use this after promoting/demoting a player while they're online.
+     *
+     * @param player - The player to refresh
+     */
+    abstract refreshPrincipal(player: Player): Promise<void>;
+    /**
+     * Checks if player has a specific permission.
+     *
+     * @remarks
+     * Supports wildcard '*' permission for super-admin access.
+     *
+     * @param player - The player entity
+     * @param permission - Permission string to check
+     * @returns True if player has permission
+     */
+    abstract hasPermission(player: Player, permission: string): Promise<boolean>;
+    /**
+     * Checks if player has at least the required rank.
+     *
+     * @remarks
+     * Uses numeric comparison: playerRank >= requiredRank
+     *
+     * @param player - The player entity
+     * @param requiredRank - Minimum rank value
+     * @returns True if playerRank >= requiredRank
+     */
+    abstract hasRank(player: Player, requiredRank: number): Promise<boolean>;
+    /**
+     * Checks if player has ANY of the specified permissions.
+     *
+     * @param player - The player entity
+     * @param permissions - Array of permissions to check
+     * @returns True if player has at least one permission
+     */
+    abstract hasAnyPermission(player: Player, permissions: string[]): Promise<boolean>;
+    /**
+     * Checks if player has ALL of the specified permissions.
+     *
+     * @param player - The player entity
+     * @param permissions - Array of permissions to check
+     * @returns True if player has all permissions
+     */
+    abstract hasAllPermissions(player: Player, permissions: string[]): Promise<boolean>;
+    /**
+     * Gets all permissions for a player.
+     *
+     * @param player - The player entity
+     * @returns Array of permission strings
+     */
+    abstract getPermissions(player: Player): Promise<string[]>;
+    /**
+     * Gets the rank value for a player.
+     *
+     * @param player - The player entity
+     * @returns Rank number or null if not set
+     */
+    abstract getRank(player: Player): Promise<number | null>;
+    /**
+     * Gets the principal name/role name for a player.
+     *
+     * @param player - The player entity
+     * @returns Role name or null
+     */
+    abstract getPrincipalName(player: Player): Promise<string | null>;
+    /**
+     * Gets principal metadata for a player.
+     *
+     * @param player - The player entity
+     * @param key - Metadata key
+     * @returns Metadata value or null
+     */
+    abstract getPrincipalMeta(player: Player, key: string): Promise<unknown>;
+    /**
+     * Enforces access control requirements, throwing on failure.
+     *
+     * @remarks
+     * This is the primary method used by `@Guard` decorator and security validation.
+     * It validates rank and/or permission requirements and throws `AppError` if
+     * the player doesn't meet the criteria.
+     *
+     * **Validation Order:**
+     * 1. Rank check (if `rank` specified)
+     * 2. Permission check (if `permission` specified)
+     *
+     * @param player - The player entity to validate
+     * @param requirements - Guard options containing rank and/or permission requirements
+     *
+     * @throws AppError - `AUTH:UNAUTHORIZED` if player has no principal
+     * @throws AppError - `GAME:NO_RANK_IN_PRINCIPAL` if rank check requested but principal has no rank
+     * @throws AppError - `AUTH:PERMISSION_DENIED` if player doesn't meet requirements
+     *
+     * @example
+     * ```typescript
+     * // In a service or controller
+     * await this.principal.enforce(player, { rank: 5 })
+     * await this.principal.enforce(player, { permission: 'admin.ban' })
+     * await this.principal.enforce(player, { rank: 3, permission: 'mod.kick' })
+     * ```
+     */
+    abstract enforce(player: Player, requirements: GuardOptions): Promise<void>;
+}

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 {
+}