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

package/dist/adapters/node/transport/node.rpc.js

@@ -0,0 +1,71 @@
+import { randomUUID } from 'node:crypto';
+import { RpcAPI } from '../../contracts/transport/rpc.api';
+export class NodeRpc extends RpcAPI {
+    context;
+    handlers = new Map();
+    constructor(context) {
+        super();
+        this.context = context;
+    }
+    on(name, handler) {
+        this.handlers.set(name, handler);
+    }
+    call(name, ...args) {
+        const { target, payload } = this.normalizeInvocation(name, 'call', args);
+        return this.executeCall(name, payload, target);
+    }
+    notify(name, ...args) {
+        const { target, payload } = this.normalizeInvocation(name, 'notify', args);
+        return this.executeNotify(name, payload, target);
+    }
+    normalizeInvocation(name, kind, args) {
+        if (this.context === 'server') {
+            if (args.length === 0) {
+                throw new Error(`NodeRpc: missing target for '${kind}' '${name}' in server context`);
+            }
+            const [target, ...payload] = args;
+            if (!this.isValidTarget(target)) {
+                throw new Error(`NodeRpc: invalid target for '${kind}' '${name}'`);
+            }
+            if (kind === 'call' && target === 'all') {
+                throw new Error(`NodeRpc: target=all is not supported for call '${name}'`);
+            }
+            return { target, payload };
+        }
+        return { target: undefined, payload: args };
+    }
+    isValidTarget(value) {
+        if (value === 'all')
+            return true;
+        if (typeof value === 'number')
+            return true;
+        if (Array.isArray(value))
+            return value.every((item) => typeof item === 'number');
+        return false;
+    }
+    async executeCall(name, payload, _target) {
+        const handler = this.handlers.get(name);
+        if (!handler) {
+            throw new Error(`NodeRpc: no handler registered for '${name}'`);
+        }
+        const requestId = randomUUID();
+        const result = await Promise.resolve(handler({
+            requestId,
+            clientId: this.context === 'server' ? undefined : undefined,
+            raw: undefined,
+        }, ...(payload ?? [])));
+        return result;
+    }
+    async executeNotify(name, payload, _target) {
+        const handler = this.handlers.get(name);
+        if (!handler) {
+            return;
+        }
+        const requestId = randomUUID();
+        await Promise.resolve(handler({
+            requestId,
+            clientId: undefined,
+            raw: undefined,
+        }, ...(payload ?? [])));
+    }
+}

package/dist/adapters/platform/index.d.ts

@@ -0,0 +1 @@
+export * from './platform-registry';

package/dist/adapters/platform/index.js

@@ -0,0 +1 @@
+export * from './platform-registry';

package/dist/adapters/platform/platform-registry.d.ts

@@ -0,0 +1,101 @@
+import type { DependencyContainer } from 'tsyringe';
+/**
+ * Platform adapter interface for registering platform-specific implementations.
+ *
+ * @remarks
+ * Each supported platform (FiveM, RageMP, alt:V, etc.) should implement this
+ * interface to provide automatic detection and dependency registration.
+ */
+export interface PlatformAdapter {
+    /**
+     * Unique platform identifier.
+     * @example 'cfx', 'ragemp', 'altv', 'node'
+     */
+    readonly name: string;
+    /**
+     * Priority for platform detection (higher = checked first).
+     * Useful when multiple platforms might match.
+     * @default 0
+     */
+    readonly priority?: number;
+    /**
+     * Detect if the current runtime is this platform.
+     * @returns true if running on this platform
+     */
+    detect(): boolean;
+    /**
+     * Register all platform-specific adapters in the DI container.
+     * @param container - The dependency injection container
+     */
+    register(container: DependencyContainer): Promise<void>;
+}
+/**
+ * Registry for platform adapters.
+ * Allows dynamic registration and detection of platforms.
+ */
+declare class PlatformRegistry {
+    private adapters;
+    private currentPlatform;
+    /**
+     * Register a platform adapter.
+     * @param adapter - Platform adapter to register
+     */
+    register(adapter: PlatformAdapter): void;
+    /**
+     * Unregister a platform adapter.
+     * @param name - Platform name to unregister
+     */
+    unregister(name: string): void;
+    /**
+     * Get all registered platform adapters.
+     */
+    getAll(): readonly PlatformAdapter[];
+    /**
+     * Get a specific platform adapter by name.
+     * @param name - Platform name
+     */
+    get(name: string): PlatformAdapter | undefined;
+    /**
+     * Detect the current platform from registered adapters.
+     * @returns The detected platform adapter or undefined
+     */
+    detect(): PlatformAdapter | undefined;
+    /**
+     * Detect and register platform capabilities in the container.
+     *
+     * @param container - DI container to register adapters in
+     * @param forcePlatform - Optional platform name to force (skip detection)
+     * @returns The registered platform adapter
+     * @throws Error if no platform is detected
+     */
+    detectAndRegister(container: DependencyContainer, forcePlatform?: string): Promise<PlatformAdapter>;
+    /**
+     * Get the currently active platform.
+     * Only available after detectAndRegister has been called.
+     */
+    getCurrent(): PlatformAdapter | null;
+    /**
+     * Check if a specific platform is currently active.
+     * @param name - Platform name to check
+     */
+    isCurrentPlatform(name: string): boolean;
+    /**
+     * Clear all registered adapters (mainly for testing).
+     */
+    clear(): void;
+}
+/**
+ * Global platform registry instance.
+ */
+export declare const platformRegistry: PlatformRegistry;
+/**
+ * Convenience function to register a platform adapter.
+ * @param adapter - Platform adapter to register
+ */
+export declare function registerPlatform(adapter: PlatformAdapter): void;
+/**
+ * Get the current platform name.
+ * @returns Platform name or 'unknown' if not detected
+ */
+export declare function getCurrentPlatformName(): string;
+export {};

package/dist/adapters/platform/platform-registry.js

@@ -0,0 +1,113 @@
+/**
+ * Registry for platform adapters.
+ * Allows dynamic registration and detection of platforms.
+ */
+class PlatformRegistry {
+    adapters = [];
+    currentPlatform = null;
+    /**
+     * Register a platform adapter.
+     * @param adapter - Platform adapter to register
+     */
+    register(adapter) {
+        // Avoid duplicates
+        if (this.adapters.some((a) => a.name === adapter.name)) {
+            return;
+        }
+        this.adapters.push(adapter);
+        // Sort by priority (descending)
+        this.adapters.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+    }
+    /**
+     * Unregister a platform adapter.
+     * @param name - Platform name to unregister
+     */
+    unregister(name) {
+        this.adapters = this.adapters.filter((a) => a.name !== name);
+    }
+    /**
+     * Get all registered platform adapters.
+     */
+    getAll() {
+        return this.adapters;
+    }
+    /**
+     * Get a specific platform adapter by name.
+     * @param name - Platform name
+     */
+    get(name) {
+        return this.adapters.find((a) => a.name === name);
+    }
+    /**
+     * Detect the current platform from registered adapters.
+     * @returns The detected platform adapter or undefined
+     */
+    detect() {
+        return this.adapters.find((adapter) => adapter.detect());
+    }
+    /**
+     * Detect and register platform capabilities in the container.
+     *
+     * @param container - DI container to register adapters in
+     * @param forcePlatform - Optional platform name to force (skip detection)
+     * @returns The registered platform adapter
+     * @throws Error if no platform is detected
+     */
+    async detectAndRegister(container, forcePlatform) {
+        let platform;
+        if (forcePlatform) {
+            platform = this.get(forcePlatform);
+            if (!platform) {
+                throw new Error(`[OpenCore] Platform '${forcePlatform}' not found. Available: ${this.adapters.map((a) => a.name).join(', ')}`);
+            }
+        }
+        else {
+            platform = this.detect();
+            if (!platform) {
+                throw new Error(`[OpenCore] No platform detected. Registered platforms: ${this.adapters.map((a) => a.name).join(', ')}`);
+            }
+        }
+        await platform.register(container);
+        this.currentPlatform = platform;
+        return platform;
+    }
+    /**
+     * Get the currently active platform.
+     * Only available after detectAndRegister has been called.
+     */
+    getCurrent() {
+        return this.currentPlatform;
+    }
+    /**
+     * Check if a specific platform is currently active.
+     * @param name - Platform name to check
+     */
+    isCurrentPlatform(name) {
+        return this.currentPlatform?.name === name;
+    }
+    /**
+     * Clear all registered adapters (mainly for testing).
+     */
+    clear() {
+        this.adapters = [];
+        this.currentPlatform = null;
+    }
+}
+/**
+ * Global platform registry instance.
+ */
+export const platformRegistry = new PlatformRegistry();
+/**
+ * Convenience function to register a platform adapter.
+ * @param adapter - Platform adapter to register
+ */
+export function registerPlatform(adapter) {
+    platformRegistry.register(adapter);
+}
+/**
+ * Get the current platform name.
+ * @returns Platform name or 'unknown' if not detected
+ */
+export function getCurrentPlatformName() {
+    return platformRegistry.getCurrent()?.name ?? 'unknown';
+}

package/dist/adapters/register-capabilities.d.ts

@@ -0,0 +1,61 @@
+import { getCurrentPlatformName, type PlatformAdapter, platformRegistry, registerPlatform } from './platform/platform-registry';
+export { platformRegistry, registerPlatform, getCurrentPlatformName };
+export type { PlatformAdapter };
+/**
+ * Supported platform types.
+ * @deprecated Use platformRegistry.getCurrent()?.name instead for dynamic platform detection.
+ */
+export type Platform = 'cfx' | 'node' | string;
+/**
+ * Detects the current runtime platform.
+ *
+ * @deprecated Use platformRegistry.detect() instead.
+ */
+export declare function detectPlatform(): Platform;
+/**
+ * Registers server-side platform-specific capability implementations.
+ *
+ * @remarks
+ * This function registers adapters needed by the SERVER runtime only.
+ * Client-side adapters are registered separately via `registerClientCapabilities`.
+ *
+ * The function uses the Platform Registry to automatically detect and register
+ * the appropriate platform adapters. You can also force a specific platform
+ * by passing its name.
+ *
+ * @param platform - Optional platform name to force. If not provided, platform is auto-detected.
+ *
+ * @example
+ * ```typescript
+ * // Auto-detect platform
+ * await registerServerCapabilities()
+ *
+ * // Force a specific platform
+ * await registerServerCapabilities('cfx')
+ *
+ * // Register a custom platform before calling
+ * registerPlatform(MyCustomPlatform)
+ * await registerServerCapabilities('myplatform')
+ * ```
+ */
+export declare function registerServerCapabilities(platform?: Platform): Promise<void>;
+/**
+ * Check if a specific platform is currently active.
+ *
+ * @param name - Platform name to check
+ * @returns true if the platform is active
+ *
+ * @example
+ * ```typescript
+ * if (isPlatform('cfx')) {
+ *   // CitizenFX-specific code
+ * }
+ * ```
+ */
+export declare function isPlatform(name: string): boolean;
+/**
+ * Get the current platform adapter.
+ *
+ * @returns The current platform adapter or null if not initialized
+ */
+export declare function getCurrentPlatform(): PlatformAdapter | null;

package/dist/adapters/register-capabilities.js

@@ -0,0 +1,78 @@
+import { GLOBAL_CONTAINER } from '../kernel/di/container';
+import { CfxPlatform } from './cfx/cfx-platform';
+import { NodePlatform } from './node/node-platform';
+import { getCurrentPlatformName, platformRegistry, registerPlatform, } from './platform/platform-registry';
+// Re-export for convenience
+export { platformRegistry, registerPlatform, getCurrentPlatformName };
+// ─────────────────────────────────────────────────────────────────
+// Register built-in platforms
+// ─────────────────────────────────────────────────────────────────
+// Register CitizenFX platform (high priority)
+registerPlatform(CfxPlatform);
+// Register Node.js fallback platform (low priority)
+registerPlatform(NodePlatform);
+// ─────────────────────────────────────────────────────────────────
+// Public API
+// ─────────────────────────────────────────────────────────────────
+/**
+ * Detects the current runtime platform.
+ *
+ * @deprecated Use platformRegistry.detect() instead.
+ */
+export function detectPlatform() {
+    const detected = platformRegistry.detect();
+    return detected?.name ?? 'node';
+}
+/**
+ * Registers server-side platform-specific capability implementations.
+ *
+ * @remarks
+ * This function registers adapters needed by the SERVER runtime only.
+ * Client-side adapters are registered separately via `registerClientCapabilities`.
+ *
+ * The function uses the Platform Registry to automatically detect and register
+ * the appropriate platform adapters. You can also force a specific platform
+ * by passing its name.
+ *
+ * @param platform - Optional platform name to force. If not provided, platform is auto-detected.
+ *
+ * @example
+ * ```typescript
+ * // Auto-detect platform
+ * await registerServerCapabilities()
+ *
+ * // Force a specific platform
+ * await registerServerCapabilities('cfx')
+ *
+ * // Register a custom platform before calling
+ * registerPlatform(MyCustomPlatform)
+ * await registerServerCapabilities('myplatform')
+ * ```
+ */
+export async function registerServerCapabilities(platform) {
+    await platformRegistry.detectAndRegister(GLOBAL_CONTAINER, platform);
+}
+/**
+ * Check if a specific platform is currently active.
+ *
+ * @param name - Platform name to check
+ * @returns true if the platform is active
+ *
+ * @example
+ * ```typescript
+ * if (isPlatform('cfx')) {
+ *   // CitizenFX-specific code
+ * }
+ * ```
+ */
+export function isPlatform(name) {
+    return platformRegistry.isCurrentPlatform(name);
+}
+/**
+ * Get the current platform adapter.
+ *
+ * @returns The current platform adapter or null if not initialized
+ */
+export function getCurrentPlatform() {
+    return platformRegistry.getCurrent();
+}

package/dist/adapters/register-client-capabilities.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Registers client-side platform-specific capability implementations.
+ *
+ * @remarks
+ * This function registers adapters needed by the CLIENT runtime only.
+ * Should be called during client bootstrap before services that depend on these adapters.
+ */
+export declare function registerClientCapabilities(): Promise<void>;

package/dist/adapters/register-client-capabilities.js

@@ -0,0 +1,58 @@
+import { di } from '../runtime/client/client-container';
+import { IPedAppearanceClient } from './contracts/client/IPedAppearanceClient';
+import { IHasher } from './contracts/IHasher';
+import { EventsAPI } from './contracts/transport/events.api';
+import { MessagingTransport } from './contracts/transport/messaging.transport';
+import { RpcAPI } from './contracts/transport/rpc.api';
+import { detectCfxGameProfile, isCfxRuntime } from './cfx/runtime-profile';
+/**
+ * Registers client-side platform-specific capability implementations.
+ *
+ * @remarks
+ * This function registers adapters needed by the CLIENT runtime only.
+ * Should be called during client bootstrap before services that depend on these adapters.
+ */
+export async function registerClientCapabilities() {
+    const cfxRuntime = isCfxRuntime();
+    const gameProfile = cfxRuntime ? detectCfxGameProfile() : 'common';
+    if (!di.isRegistered(MessagingTransport)) {
+        if (cfxRuntime) {
+            const [{ FiveMMessagingTransport }] = await Promise.all([import('./fivem/transport/adapter')]);
+            const transport = new FiveMMessagingTransport();
+            di.registerInstance(MessagingTransport, transport);
+            di.registerInstance(EventsAPI, transport.events);
+            di.registerInstance(RpcAPI, transport.rpc);
+        }
+        else {
+            const [{ NodeMessagingTransport }] = await Promise.all([import('./node/transport/adapter')]);
+            const transport = new NodeMessagingTransport('client');
+            di.registerInstance(MessagingTransport, transport);
+            di.registerInstance(EventsAPI, transport.events);
+            di.registerInstance(RpcAPI, transport.rpc);
+        }
+    }
+    if (!di.isRegistered(IPedAppearanceClient)) {
+        if (cfxRuntime && gameProfile !== 'rdr3') {
+            const [{ FiveMPedAppearanceClientAdapter }] = await Promise.all([
+                import('./fivem/fivem-ped-appearance-client'),
+            ]);
+            di.registerSingleton(IPedAppearanceClient, FiveMPedAppearanceClientAdapter);
+        }
+        else {
+            const [{ NodePedAppearanceClient }] = await Promise.all([
+                import('./node/node-ped-appearance-client'),
+            ]);
+            di.registerSingleton(IPedAppearanceClient, NodePedAppearanceClient);
+        }
+    }
+    if (!di.isRegistered(IHasher)) {
+        if (cfxRuntime) {
+            const [{ FiveMHasher }] = await Promise.all([import('./fivem/fivem-hasher')]);
+            di.registerSingleton(IHasher, FiveMHasher);
+        }
+        else {
+            const [{ NodeHasher }] = await Promise.all([import('./node/node-hasher')]);
+            di.registerSingleton(IHasher, NodeHasher);
+        }
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 import 'reflect-metadata';
-export * as Utils from './utils';
-export * as Shared from './shared';
-export * as Server from './server';
-export * as Client from './client';
+export * from './kernel';
+export * from './runtime/core';
+export * from './adapters/contracts';

package/dist/index.js

@@ -1,41 +1,4 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Client = exports.Server = exports.Shared = exports.Utils = void 0;
-require("reflect-metadata");
-exports.Utils = __importStar(require("./utils"));
-exports.Shared = __importStar(require("./shared"));
-exports.Server = __importStar(require("./server"));
-exports.Client = __importStar(require("./client"));
+import 'reflect-metadata';
+export * from './kernel';
+export * from './runtime/core';
+export * from './adapters/contracts';

package/dist/kernel/di/container.d.ts

@@ -0,0 +1,5 @@
+/**
+ * This is the global container for tsyringe, it contains all the dependencies to resolve, etc. Please use with caution.
+ *  When you use in Server is the server-side container ONLY, if you use in Client is ONLY the container of client-side
+ */
+export declare const GLOBAL_CONTAINER: import("tsyringe").DependencyContainer;

package/dist/kernel/di/container.js

@@ -0,0 +1,6 @@
+import { container } from 'tsyringe';
+/**
+ * This is the global container for tsyringe, it contains all the dependencies to resolve, etc. Please use with caution.
+ *  When you use in Server is the server-side container ONLY, if you use in Client is ONLY the container of client-side
+ */
+export const GLOBAL_CONTAINER = container;

package/dist/kernel/di/index.d.ts

@@ -0,0 +1,4 @@
+export * from './class-constructor';
+export * from './container';
+export * from './decorator-processor';
+export * from './metadata.scanner';

package/dist/kernel/di/index.js

@@ -0,0 +1,4 @@
+export * from './class-constructor';
+export * from './container';
+export * from './decorator-processor';
+export * from './metadata.scanner';

package/dist/kernel/di/metadata.scanner.d.ts

@@ -0,0 +1,7 @@
+import { type ClassConstructor } from './class-constructor';
+import { type DecoratorProcessor } from './decorator-processor';
+export declare class MetadataScanner {
+    private processors;
+    constructor(processors: DecoratorProcessor[]);
+    scan(registry: ClassConstructor[]): void;
+}

package/dist/kernel/di/metadata.scanner.js

@@ -0,0 +1,61 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { injectAll, injectable } from 'tsyringe';
+import { loggers } from '../logger';
+import { GLOBAL_CONTAINER } from './container';
+let MetadataScanner = class MetadataScanner {
+    processors;
+    constructor(processors) {
+        this.processors = processors;
+    }
+    scan(registry) {
+        loggers.scanner.info(`Scanning ${registry.length} controllers with ${this.processors.length} processors`);
+        for (const ControllerClass of registry) {
+            let instance;
+            try {
+                instance = GLOBAL_CONTAINER.resolve(ControllerClass);
+            }
+            catch (error) {
+                loggers.scanner.error(`Failed to resolve controller '${ControllerClass.name}' during metadata scan`, {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                continue;
+            }
+            const prototype = Object.getPrototypeOf(instance);
+            const methods = Object.getOwnPropertyNames(prototype).filter((m) => m !== 'constructor' && typeof instance[m] === 'function');
+            for (const methodName of methods) {
+                for (const processor of this.processors) {
+                    const metadata = Reflect.getMetadata(processor.metadataKey, prototype, methodName);
+                    if (metadata) {
+                        try {
+                            processor.process(instance, methodName, metadata);
+                        }
+                        catch (error) {
+                            loggers.scanner.error(`Failed processing metadata for '${ControllerClass.name}.${methodName}'`, {
+                                processor: processor.constructor.name,
+                                error: error instanceof Error ? error.message : String(error),
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        loggers.scanner.debug(`Metadata scan complete`);
+    }
+};
+MetadataScanner = __decorate([
+    injectable(),
+    __param(0, injectAll('DecoratorProcessor')),
+    __metadata("design:paramtypes", [Array])
+], MetadataScanner);
+export { MetadataScanner };

package/dist/kernel/error/app.error.d.ts

@@ -0,0 +1,9 @@
+import { ErrorOrigin } from './common.error-codes';
+import { FrameworkErrorCode } from './framework.error-codes';
+export declare class AppError extends Error {
+    readonly code: FrameworkErrorCode;
+    readonly details?: unknown;
+    readonly origin: ErrorOrigin;
+    constructor(code: FrameworkErrorCode, message: string, origin: ErrorOrigin, details?: unknown);
+}
+export declare function isAppError(error: unknown): error is AppError;