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

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

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+import { ClassConstructor } from '../../../kernel/di/class-constructor';
+import { Player } from '../entities/player';
+import { SecurityMetadata } from '../types/core-exports.types';
+export interface CommandConfig {
+    /**
+     * The command name (e.g. "revive", "deposit"), used in chat "/revive"
+     */
+    command: string;
+    /**
+     * The command description, maybe "/help revive"
+     */
+    description?: string;
+    /**
+     * The command usage, maybe "/revive <player>"
+     */
+    usage?: string;
+    /**
+     * Optional Zod schema for command argument validation.
+     *
+     * - `z.tuple([...])`: positional args validation.
+     * - `z.object({...})`: named args validation (maps args to parameter names).
+     *
+     * If omitted, the framework auto-validates only primitive arg types (`string|number|boolean|any[]`).
+     */
+    schema?: z.ZodType;
+}
+export interface CommandMetadata extends CommandConfig {
+    methodName: string;
+    target: ClassConstructor;
+    paramTypes: any;
+    paramNames: string[];
+    expectsPlayer: boolean;
+    isPublic?: boolean;
+    /** Security metadata for remote validation */
+    security?: SecurityMetadata;
+    /** True if the last parameter uses the spread operator (...args) */
+    hasSpreadParam?: boolean;
+}
+type ServerCommandHandler = (() => any) | ((player: Player, ...args: any[]) => any);
+/**
+ * Registers a method as a chat command.
+ *
+ * @remarks
+ * Handler rules:
+ * - If the handler has parameters, the first parameter must be `Player`.
+ *
+ * Validation rules:
+ * - If schema is provided:
+ *   - `z.tuple([...])` validates positional args.
+ *   - `z.object({...})` validates named args by mapping chat args to parameter names.
+ * - If schema is omitted, the framework can only auto-validate primitive types
+ *   (`string|number|boolean|any[]`). Complex payloads should use an explicit Zod schema.
+ *
+ * @param configOrName - Command name, full config, or just command name with schema as second arg.
+ * @param schema - Optional Zod schema when using short form @Command("name", schema).
+ *
+ * @throws Error - If applied to a method without a valid descriptor.
+ * @throws Error - If the method has parameters but does not declare `Player` as the first parameter.
+ *
+ * @example
+ * ```ts
+ * import { z, Infer } from '@open-core/framework'
+ *
+ * const AmountSchema = z.object({ amount: z.number() })
+ *
+ * @Server.Controller()
+ * export class BankController {
+ *   // Simple command (no schema)
+ *   @Server.Command('help')
+ *   help(player: Player) { }
+ *
+ *   // With schema directly (recommended)
+ *   @Server.Command('deposit', AmountSchema)
+ *   deposit(player: Player, data: Infer<typeof AmountSchema>) { }
+ *
+ *   // With full config object (for description, usage, etc.)
+ *   @Server.Command({ command: 'withdraw', schema: AmountSchema, usage: '/withdraw <amount>' })
+ *   withdraw(player: Player, data: Infer<typeof AmountSchema>) { }
+ * }
+ * ```
+ */
+export declare function Command(name: string, schema: z.ZodType): <T extends ServerCommandHandler>(target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) => void;
+export declare function Command(name: string): <T extends ServerCommandHandler>(target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) => void;
+export declare function Command(config: CommandConfig): <T extends ServerCommandHandler>(target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) => void;
+export declare function Command(config: CommandConfig, schema: z.ZodType): <T extends ServerCommandHandler>(target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) => void;
+export {};

package/dist/runtime/server/decorators/command.js

@@ -0,0 +1,36 @@
+import { Player } from '../entities/player';
+import { getParameterNames, getSpreadParameterIndices } from '../helpers/function-helper';
+import { METADATA_KEYS } from '../system/metadata-server.keys';
+// Implementation
+export function Command(configOrName, schema) {
+    return (target, propertyKey, descriptor) => {
+        if (!descriptor.value)
+            throw new Error(`@Command(): descriptor.value is undefined for method '${propertyKey}'`);
+        // Build config from various input forms
+        let config;
+        if (typeof configOrName === 'string') {
+            config = { command: configOrName, schema };
+        }
+        else {
+            config = configOrName;
+        }
+        const paramTypes = Reflect.getMetadata('design:paramtypes', target, propertyKey) ?? [];
+        const expectsPlayer = paramTypes.length > 0 && paramTypes[0] === Player;
+        if (paramTypes.length > 0 && !expectsPlayer) {
+            throw new Error(`@Command '${config.command}': first parameter must be Player if parameters are present`);
+        }
+        const paramNames = getParameterNames(descriptor.value);
+        const spreadIndices = getSpreadParameterIndices(descriptor.value);
+        const hasSpreadParam = spreadIndices.length > 0 && spreadIndices[spreadIndices.length - 1];
+        const metadata = {
+            ...config,
+            methodName: propertyKey,
+            target: target.constructor,
+            paramTypes,
+            paramNames,
+            expectsPlayer,
+            hasSpreadParam,
+        };
+        Reflect.defineMetadata(METADATA_KEYS.COMMAND, metadata, target, propertyKey);
+    };
+}

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

@@ -0,0 +1,26 @@
+import { ClassConstructor } from '../../../kernel/di/class-constructor';
+export declare const _serverControllerRegistryByResource: Map<string, Set<ClassConstructor>>;
+export declare function getServerControllerRegistry(resourceName?: string): ClassConstructor[];
+/**
+ * Class decorator used to mark a class as a Server Controller.
+ *
+ * This decorator performs the following actions:
+ * 1. Marks the class as `@injectable` (via tsyringe) for dependency injection.
+ * 2. Defines metadata identifying the class as a 'server' type controller.
+ * 3. Automatically adds the class constructor to the `_serverControllerRegistryByResource`.
+ *
+ * @returns The decorator function to apply to the class.
+ *
+ * @example
+ * ```ts
+ * import { Controller } from '@core/server/decorators'
+ *
+ * @Server.Controller()
+ * export class PlayerController {
+ *   constructor(private playerService: PlayerService) {
+ *     // Dependency injection works automatically here
+ *   }
+ * }
+ * ```
+ */
+export declare function Controller(): (target: ClassConstructor) => void;

package/dist/runtime/server/decorators/controller.js

@@ -0,0 +1,56 @@
+import { injectable } from 'tsyringe';
+import { METADATA_KEYS } from '../system/metadata-server.keys';
+export const _serverControllerRegistryByResource = new Map();
+function getCurrentResourceNameSafe() {
+    const fn = globalThis.GetCurrentResourceName;
+    if (typeof fn === 'function') {
+        const name = fn();
+        if (typeof name === 'string' && name.trim())
+            return name;
+    }
+    return 'default';
+}
+export function getServerControllerRegistry(resourceName) {
+    const key = resourceName ?? getCurrentResourceNameSafe();
+    let registry = _serverControllerRegistryByResource.get(key);
+    if (!registry) {
+        registry = new Set();
+        _serverControllerRegistryByResource.set(key, registry);
+    }
+    return Array.from(registry);
+}
+/**
+ * Class decorator used to mark a class as a Server Controller.
+ *
+ * This decorator performs the following actions:
+ * 1. Marks the class as `@injectable` (via tsyringe) for dependency injection.
+ * 2. Defines metadata identifying the class as a 'server' type controller.
+ * 3. Automatically adds the class constructor to the `_serverControllerRegistryByResource`.
+ *
+ * @returns The decorator function to apply to the class.
+ *
+ * @example
+ * ```ts
+ * import { Controller } from '@core/server/decorators'
+ *
+ * @Server.Controller()
+ * export class PlayerController {
+ *   constructor(private playerService: PlayerService) {
+ *     // Dependency injection works automatically here
+ *   }
+ * }
+ * ```
+ */
+export function Controller() {
+    return (target) => {
+        injectable()(target);
+        Reflect.defineMetadata(METADATA_KEYS.CONTROLLER, { type: 'server' }, target);
+        const key = getCurrentResourceNameSafe();
+        let registry = _serverControllerRegistryByResource.get(key);
+        if (!registry) {
+            registry = new Set();
+            _serverControllerRegistryByResource.set(key, registry);
+        }
+        registry.add(target);
+    };
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Exposes a method as a FiveM server export.
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework registers the export so that
+ * other resources can call it via `exports['resourceName'][exportName](...)`.
+ *
+ * @param name - Optional export name. If omitted, the method name is used.
+ *
+ * @example
+ * ```ts
+ * @Server.Controller()
+ * export class AccountController {
+ *   @Server.Export('getAccountById')
+ *   getAccountById(id: string) {
+ *     return this.accountService.find(id)
+ *   }
+ * }
+ *
+ * // From another resource:
+ * // const result = exports['core-resource'].getAccountById('1234')
+ * ```
+ */
+export declare function Export(name?: string): (target: any, propertyKey: string) => void;

package/dist/runtime/server/decorators/export.js

@@ -0,0 +1,29 @@
+import { METADATA_KEYS } from '../system/metadata-server.keys';
+/**
+ * Exposes a method as a FiveM server export.
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework registers the export so that
+ * other resources can call it via `exports['resourceName'][exportName](...)`.
+ *
+ * @param name - Optional export name. If omitted, the method name is used.
+ *
+ * @example
+ * ```ts
+ * @Server.Controller()
+ * export class AccountController {
+ *   @Server.Export('getAccountById')
+ *   getAccountById(id: string) {
+ *     return this.accountService.find(id)
+ *   }
+ * }
+ *
+ * // From another resource:
+ * // const result = exports['core-resource'].getAccountById('1234')
+ * ```
+ */
+export function Export(name) {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(METADATA_KEYS.EXPORT, { exportName: name || propertyKey }, target, propertyKey);
+    };
+}

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

@@ -0,0 +1,51 @@
+export interface GuardOptions {
+    /**
+     * Minimum rank required to execute the method.
+     * Permissions and Role/Ranks are defined by your Principal Controller
+     */
+    rank?: number;
+    /**
+     * Permission required to execute the method.
+     * Permissions and Role/Ranks are defined by your Principal Controller
+     */
+    permission?: string;
+}
+/**
+ * Declarative access-control decorator for controller methods.
+ *
+ * @remarks
+ * `@Guard()` protects a method by enforcing rank and/or permission requirements before executing it.
+ *
+ * Requirements are evaluated through {@link Authorization}, which determines whether the
+ * player (first argument of the method) is authorized to perform the action.
+ *
+ * Notes:
+ * - The decorated method must receive a `Player` instance as its first argument.
+ * - In stripped decorator builds (e.g. benchmarks), the `PropertyDescriptor` may be missing.
+ *   In that case the decorator stores metadata only and does not wrap the method.
+ *
+ * @param options - Guard options.
+ * @param options.rank - Minimum rank required.
+ * @param options.permission - Permission required.
+ *
+ * @throws Error - If the method is invoked without a valid `Player` as the first argument.
+ *
+ * ```ts
+ * @Server.Controller()
+ * export class AdminController {
+ *
+ *   @Server.Guard({ permission: 'factions.manage' })
+ *   @Server.Command('newfaction', schema)
+ *   async createFaction(player: Player, dto: Infer<typeof schema>) {
+ *     return this.service.create(dto)
+ *   }
+ *
+ *   @Server.Guard({ rank: 3 })
+ *   @Server.Command('ban')
+ *   async ban(player: Player, targetID: string) {
+ *     return this.service.ban(player, memberID)
+ *   }
+}
+ * ```
+ */
+export declare function Guard(options: GuardOptions): (target: any, propertyKey: string, descriptor?: PropertyDescriptor) => PropertyDescriptor | undefined;

package/dist/runtime/server/decorators/guard.js

@@ -0,0 +1,80 @@
+import { AppError } from '../../../kernel';
+import { GLOBAL_CONTAINER } from '../../../kernel/di/container';
+import { loggers } from '../../../kernel/logger';
+import { Authorization } from '../ports/authorization.api-port';
+/**
+ * Declarative access-control decorator for controller methods.
+ *
+ * @remarks
+ * `@Guard()` protects a method by enforcing rank and/or permission requirements before executing it.
+ *
+ * Requirements are evaluated through {@link Authorization}, which determines whether the
+ * player (first argument of the method) is authorized to perform the action.
+ *
+ * Notes:
+ * - The decorated method must receive a `Player` instance as its first argument.
+ * - In stripped decorator builds (e.g. benchmarks), the `PropertyDescriptor` may be missing.
+ *   In that case the decorator stores metadata only and does not wrap the method.
+ *
+ * @param options - Guard options.
+ * @param options.rank - Minimum rank required.
+ * @param options.permission - Permission required.
+ *
+ * @throws Error - If the method is invoked without a valid `Player` as the first argument.
+ *
+ * ```ts
+ * @Server.Controller()
+ * export class AdminController {
+ *
+ *   @Server.Guard({ permission: 'factions.manage' })
+ *   @Server.Command('newfaction', schema)
+ *   async createFaction(player: Player, dto: Infer<typeof schema>) {
+ *     return this.service.create(dto)
+ *   }
+ *
+ *   @Server.Guard({ rank: 3 })
+ *   @Server.Command('ban')
+ *   async ban(player: Player, targetID: string) {
+ *     return this.service.ban(player, memberID)
+ *   }
+}
+ * ```
+ */
+export function Guard(options) {
+    return (target, propertyKey, descriptor) => {
+        if (!descriptor) {
+            // In benchmarks or edge cases, only register metadata without method wrapping
+            // This should NOT happen in production code with proper TypeScript compilation
+            loggers.security.warn(`@Guard decorator: PropertyDescriptor not available. Only metadata will be registered. This should not happen in production code. Target: ${target.constructor?.name}, Method: ${propertyKey}`);
+            Reflect.defineMetadata('core:guard', options, target, propertyKey);
+            return;
+        }
+        const originalMethod = descriptor.value;
+        descriptor.value = async function (...args) {
+            const player = args[0];
+            if (!player || !player.clientID) {
+                loggers.security.warn(`@Guard misuse: First argument is not a Player`, {
+                    method: propertyKey,
+                    targetClass: target.constructor?.name,
+                });
+                throw new Error('Guard Security Error: Context is not a player');
+            }
+            const principal = GLOBAL_CONTAINER.resolve(Authorization);
+            try {
+                await principal.enforce(player, options);
+            }
+            catch (error) {
+                // Send user-friendly error message for authorization failures
+                if (error instanceof AppError && error.code === 'AUTH:PERMISSION_DENIED') {
+                    player.send(error.message, 'error');
+                    return;
+                }
+                throw error;
+            }
+            return originalMethod.apply(this, args);
+        };
+        // no need a defined metadata key, as we won't read it later
+        Reflect.defineMetadata('core:guard', options, target, propertyKey);
+        return descriptor;
+    };
+}

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

@@ -0,0 +1,18 @@
+export * from './binaryCall';
+export * from './binaryEvent';
+export * from './binaryService';
+export * from './bind';
+export { Command, CommandConfig } from './command';
+export { Controller } from './controller';
+export * from './export';
+export * from './guard';
+export * from './onFrameworkEvent';
+export * from './onLibraryEvent';
+export * from './onNet';
+export * from './onRuntimeEvent';
+export * from './onTick';
+export * from './public';
+export * from './requiresState';
+export * from './throttle';
+export * from './utils';
+export * from './onRPC';

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

@@ -0,0 +1,18 @@
+export * from './binaryCall';
+export * from './binaryEvent';
+export * from './binaryService';
+export * from './bind';
+export { Command } from './command';
+export { Controller } from './controller';
+export * from './export';
+export * from './guard';
+export * from './onFrameworkEvent';
+export * from './onLibraryEvent';
+export * from './onNet';
+export * from './onRuntimeEvent';
+export * from './onTick';
+export * from './public';
+export * from './requiresState';
+export * from './throttle';
+export * from './utils';
+export * from './onRPC';

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

@@ -0,0 +1,24 @@
+import { FrameworkEventsMap } from '../types/framework-events.types';
+/**
+ * Registers a method as a listener for an internal OpenCore framework event.
+ *
+ * @remarks
+ * This decorator only stores metadata. The framework binds listeners during bootstrap by scanning
+ * controller methods.
+ *
+ * The handler should accept the payload type corresponding to the event from {@link FrameworkEventsMap}.
+ *
+ * @param event - Internal event name, strongly typed to {@link FrameworkEventsMap}.
+ *
+ * @example
+ * ```ts
+ * @Server.Controller()
+ * export class SystemController {
+ *   @Server.OnFrameworkEvent('internal:playerFullyConnected')
+ *   onPlayerConnected(payload: PlayerFullyConnectedPayload) {
+ *     console.log(`Player ${payload.player.session.clientId} connected`)
+ *   }
+ * }
+ * ```
+ */
+export declare function OnFrameworkEvent<K extends keyof FrameworkEventsMap>(event: K): (target: object, propertyKey: string | symbol, _descriptor: PropertyDescriptor) => void;

package/dist/runtime/server/decorators/onFrameworkEvent.js

@@ -0,0 +1,28 @@
+import { METADATA_KEYS } from '../system/metadata-server.keys';
+/**
+ * Registers a method as a listener for an internal OpenCore framework event.
+ *
+ * @remarks
+ * This decorator only stores metadata. The framework binds listeners during bootstrap by scanning
+ * controller methods.
+ *
+ * The handler should accept the payload type corresponding to the event from {@link FrameworkEventsMap}.
+ *
+ * @param event - Internal event name, strongly typed to {@link FrameworkEventsMap}.
+ *
+ * @example
+ * ```ts
+ * @Server.Controller()
+ * export class SystemController {
+ *   @Server.OnFrameworkEvent('internal:playerFullyConnected')
+ *   onPlayerConnected(payload: PlayerFullyConnectedPayload) {
+ *     console.log(`Player ${payload.player.session.clientId} connected`)
+ *   }
+ * }
+ * ```
+ */
+export function OnFrameworkEvent(event) {
+    return (target, propertyKey, _descriptor) => {
+        Reflect.defineMetadata(METADATA_KEYS.INTERNAL_EVENT, { event }, target, propertyKey);
+    };
+}

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

@@ -0,0 +1,17 @@
+import { LibraryEventName, LibraryName } from '../../core/library/types';
+export interface LibraryEventDecoratorMetadata {
+    libraryName: LibraryName;
+    eventName: LibraryEventName;
+    eventId: string;
+}
+/**
+ * Registers a method as a listener for a runtime library event.
+ *
+ * @remarks
+ * The event is emitted when a library wrapper calls `library.emit(...)`.
+ * This decorator stores metadata only; listeners are bound during bootstrap.
+ *
+ * @param libraryName - Library identifier (for example: `characters`).
+ * @param eventName - Event name emitted by the library (for example: `session:created`).
+ */
+export declare function OnLibraryEvent(libraryName: LibraryName, eventName: LibraryEventName): (target: object, propertyKey: string | symbol, _descriptor: PropertyDescriptor) => void;

package/dist/runtime/server/decorators/onLibraryEvent.js

@@ -0,0 +1,22 @@
+import { buildLibraryEventId } from '../../core/library';
+import { METADATA_KEYS } from '../system/metadata-server.keys';
+/**
+ * Registers a method as a listener for a runtime library event.
+ *
+ * @remarks
+ * The event is emitted when a library wrapper calls `library.emit(...)`.
+ * This decorator stores metadata only; listeners are bound during bootstrap.
+ *
+ * @param libraryName - Library identifier (for example: `characters`).
+ * @param eventName - Event name emitted by the library (for example: `session:created`).
+ */
+export function OnLibraryEvent(libraryName, eventName) {
+    return (target, propertyKey, _descriptor) => {
+        const metadata = {
+            libraryName,
+            eventName,
+            eventId: buildLibraryEventId(libraryName, eventName),
+        };
+        Reflect.defineMetadata(METADATA_KEYS.LIBRARY_EVENT, metadata, target, propertyKey);
+    };
+}

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

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import { Player } from '../entities/player';
+export interface NetEventOptions {
+    /**
+     * The network event name to register.
+     */
+    eventName: string;
+    /**
+     * Zod schema for payload validation.
+     * - `z.tuple([...])`: validates all positional args.
+     * - otherwise: expects exactly 1 arg and validates `args[0]` (DTO payload pattern).
+     */
+    schema?: z.ZodType;
+    /**
+     * Runtime parameter types for auto-validation.
+     */
+    paramTypes: any;
+}
+type ServerNetHandler<TArgs extends any[] = any[]> = (player: Player, ...args: TArgs) => any;
+/**
+ * Registers a method as a server-side network event handler.
+ *
+ * @remarks
+ * Rules:
+ * - First parameter must be `Player` (injected from the caller).
+ *
+ * Validation:
+ * - If schema is provided:
+ *   - `z.tuple([...])` validates all positional args.
+ *   - otherwise: expects exactly 1 arg and validates `args[0]` (DTO payload pattern).
+ * - If schema is omitted, only primitive args can be auto-validated from runtime param types
+ *   (`string|number|boolean|any[]`). Complex payloads should use an explicit schema.
+ *
+ * Authentication:
+ * - Handlers are typically protected by the framework's net-event security layer.
+ * - Use {@link Public} to explicitly mark a handler as unauthenticated.
+ *
+ * @param eventName - Network event name.
+ * @param schemaOrOptions - Zod schema directly, or options object with schema property.
+ *
+ * @example
+ * ```ts
+ * import { z, Infer } from '@open-core/framework'
+ *
+ * const PayloadSchema = z.object({ message: z.string() })
+ *
+ * @Server.Controller()
+ * export class ExampleController {
+ *   // Simple handler (no schema)
+ *   @Server.OnNet('example:ping')
+ *   ping(player: Server.Player, message: string) { }
+ *
+ *   // With schema directly (recommended)
+ *   @Server.OnNet('example:data', PayloadSchema)
+ *   handleData(player: Server.Player, data: Infer<typeof PayloadSchema>) { }
+ *
+ *   // With options object (legacy)
+ *   @Server.OnNet('example:legacy', { schema: PayloadSchema })
+ *   handleLegacy(player: Server.Player, data: Infer<typeof PayloadSchema>) { }
+ * }
+ * ```
+ */
+export declare function OnNet<TArgs extends any[]>(eventName: string, schema: z.ZodType): <H extends ServerNetHandler<TArgs>>(target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<H>) => void;
+export declare function OnNet<TArgs extends any[]>(eventName: string, options?: Pick<NetEventOptions, 'schema'>): <H extends ServerNetHandler<TArgs>>(target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<H>) => void;
+export {};

package/dist/runtime/server/decorators/onNet.js

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import { METADATA_KEYS } from '../system/metadata-server.keys';
+// Implementation
+export function OnNet(eventName, schemaOrOptions) {
+    return (target, propertyKey, _descriptor) => {
+        const paramTypes = Reflect.getMetadata('design:paramtypes', target, propertyKey);
+        // Detect if second arg is a Zod schema or an options object
+        const schema = schemaOrOptions instanceof z.ZodType ? schemaOrOptions : schemaOrOptions?.schema;
+        const metadata = { eventName, schema, paramTypes };
+        Reflect.defineMetadata(METADATA_KEYS.NET_EVENT, metadata, target, propertyKey);
+    };
+}