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

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 now installed through `Client.init({ adapter })`.
+ *
+ * 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,76 @@
+import { GLOBAL_CONTAINER } from '../kernel/di/container';
+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)
+// 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 now installed through `Client.init({ adapter })`.
+ *
+ * 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,9 @@
+/**
+ * Registers client-side platform-specific capability implementations.
+ *
+ * @remarks
+ * Deprecated in favor of `Client.init({ adapter })` and custom client adapters.
+ *
+ * This legacy helper now installs only the built-in Node fallback bindings.
+ */
+export declare function registerClientCapabilities(): Promise<void>;

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

@@ -0,0 +1,33 @@
+import { di } from '../runtime/client/client-container';
+import { IGtaPedAppearanceBridge } from './contracts/client/IGtaPedAppearanceBridge';
+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';
+/**
+ * Registers client-side platform-specific capability implementations.
+ *
+ * @remarks
+ * Deprecated in favor of `Client.init({ adapter })` and custom client adapters.
+ *
+ * This legacy helper now installs only the built-in Node fallback bindings.
+ */
+export async function registerClientCapabilities() {
+    const [{ NodeMessagingTransport }, { NodePedAppearanceClient }, { NodeHasher }] = await Promise.all([
+        import('./node/transport/adapter'),
+        import('./node/node-ped-appearance-client'),
+        import('./node/node-hasher'),
+    ]);
+    if (!di.isRegistered(MessagingTransport)) {
+        const transport = new NodeMessagingTransport('client');
+        di.registerInstance(MessagingTransport, transport);
+        di.registerInstance(EventsAPI, transport.events);
+        di.registerInstance(RpcAPI, transport.rpc);
+    }
+    if (!di.isRegistered(IGtaPedAppearanceBridge)) {
+        di.registerSingleton(IGtaPedAppearanceBridge, NodePedAppearanceClient);
+    }
+    if (!di.isRegistered(IHasher)) {
+        di.registerSingleton(IHasher, NodeHasher);
+    }
+}

package/dist/contracts/client.d.ts

@@ -0,0 +1,5 @@
+export * from '../adapters/contracts/IHasher';
+export * from '../adapters/contracts/transport';
+export * from '../adapters/contracts/types';
+export * from '../adapters/contracts/runtime';
+export * from '../adapters/contracts/client';

package/dist/contracts/client.js

@@ -0,0 +1,5 @@
+export * from '../adapters/contracts/IHasher';
+export * from '../adapters/contracts/transport';
+export * from '../adapters/contracts/types';
+export * from '../adapters/contracts/runtime';
+export * from '../adapters/contracts/client';

package/dist/contracts/server.d.ts

@@ -0,0 +1,19 @@
+export * from '../adapters/contracts/IEngineEvents';
+export * from '../adapters/contracts/IExports';
+export * from '../adapters/contracts/IHasher';
+export * from '../adapters/contracts/IPlatformContext';
+export * from '../adapters/contracts/IPlayerInfo';
+export * from '../adapters/contracts/IResourceInfo';
+export * from '../adapters/contracts/ITick';
+export * from '../adapters/contracts/transport';
+export * from '../adapters/contracts/types';
+export * from '../adapters/contracts/runtime';
+export * from '../adapters/contracts/server';
+export * from '../adapters/contracts/server/player-lifecycle/IPlayerLifecycleServer';
+export * from '../adapters/contracts/server/player-lifecycle/types';
+export * from '../adapters/contracts/server/player-appearance/IPlayerAppearanceLifecycleServer';
+export * from '../adapters/contracts/server/player-state/IPlayerStateSyncServer';
+export * from '../adapters/contracts/server/npc-lifecycle/INpcLifecycleServer';
+export * from '../adapters/contracts/server/npc-lifecycle/types';
+export * from '../adapters/contracts/server/vehicle-lifecycle/IVehicleLifecycleServer';
+export * from '../adapters/contracts/server/vehicle-lifecycle/types';

package/dist/contracts/server.js

@@ -0,0 +1,19 @@
+export * from '../adapters/contracts/IEngineEvents';
+export * from '../adapters/contracts/IExports';
+export * from '../adapters/contracts/IHasher';
+export * from '../adapters/contracts/IPlatformContext';
+export * from '../adapters/contracts/IPlayerInfo';
+export * from '../adapters/contracts/IResourceInfo';
+export * from '../adapters/contracts/ITick';
+export * from '../adapters/contracts/transport';
+export * from '../adapters/contracts/types';
+export * from '../adapters/contracts/runtime';
+export * from '../adapters/contracts/server';
+export * from '../adapters/contracts/server/player-lifecycle/IPlayerLifecycleServer';
+export * from '../adapters/contracts/server/player-lifecycle/types';
+export * from '../adapters/contracts/server/player-appearance/IPlayerAppearanceLifecycleServer';
+export * from '../adapters/contracts/server/player-state/IPlayerStateSyncServer';
+export * from '../adapters/contracts/server/npc-lifecycle/INpcLifecycleServer';
+export * from '../adapters/contracts/server/npc-lifecycle/types';
+export * from '../adapters/contracts/server/vehicle-lifecycle/IVehicleLifecycleServer';
+export * from '../adapters/contracts/server/vehicle-lifecycle/types';

package/dist/contracts.d.ts

@@ -0,0 +1,4 @@
+export * from './adapters/contracts/IHasher';
+export * from './adapters/contracts/transport';
+export * from './adapters/contracts/types';
+export * from './adapters/contracts/runtime';

package/dist/contracts.js

@@ -0,0 +1,4 @@
+export * from './adapters/contracts/IHasher';
+export * from './adapters/contracts/transport';
+export * from './adapters/contracts/types';
+export * from './adapters/contracts/runtime';

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 './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 './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;

package/dist/kernel/error/app.error.js

@@ -0,0 +1,15 @@
+export class AppError extends Error {
+    code;
+    details;
+    origin;
+    constructor(code, message, origin, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.origin = origin;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export function isAppError(error) {
+    return error instanceof AppError;
+}

package/dist/kernel/error/common.error-codes.d.ts

@@ -0,0 +1 @@
+export type ErrorOrigin = 'client' | 'server' | 'core' | 'external';

package/dist/kernel/error/framework.error-codes.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Framework error codes grouped by category
+ */
+export type FrameworkErrorCode = CommonErrorCode | AuthErrorCode | ApiErrorCode | NetworkErrorCode | GameErrorCode | SchemaErrorCode | CommandErrorCode | EconomyErrorCode;
+export type CommonErrorCode = 'COMMON:UNKNOWN' | 'COMMON:NOT_IMPLEMENTED';
+export type AuthErrorCode = 'AUTH:UNAUTHORIZED' | 'AUTH:PERMISSION_DENIED';
+export type ApiErrorCode = 'API:ERROR';
+export type NetworkErrorCode = 'NETWORK:ERROR';
+export type GameErrorCode = 'GAME:PLAYER_NOT_FOUND' | 'GAME:NO_RANK_IN_PRINCIPAL' | 'GAME:INVALID_STATE' | 'GAME:BAD_REQUEST';
+export type SchemaErrorCode = 'SCHEMA:VALIDATION_ERROR' | 'SCHEMA:MISMATCH';
+export type CommandErrorCode = 'COMMAND:NOT_FOUND' | 'COMMAND:DUPLICATE';
+export type EconomyErrorCode = 'ECONOMY:INSUFFICIENT_FUNDS';

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

@@ -0,0 +1,4 @@
+export * from './app.error';
+export type * from './common.error-codes';
+export type * from './framework.error-codes';
+export * from './security.error';

package/dist/kernel/error/index.js

@@ -0,0 +1,2 @@
+export * from './app.error';
+export * from './security.error';

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

@@ -0,0 +1,6 @@
+import { AppError } from './app.error';
+import { SecurityAction } from './security.types';
+export declare class SecurityError extends AppError {
+    readonly action: SecurityAction;
+    constructor(action: SecurityAction, message: string, details?: unknown);
+}

package/dist/kernel/error/security.error.js

@@ -0,0 +1,9 @@
+import { AppError } from './app.error';
+export class SecurityError extends AppError {
+    action;
+    constructor(action, message, details) {
+        super('NETWORK:ERROR', message, 'core', details);
+        this.action = action;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}

package/dist/kernel/index.d.ts

@@ -0,0 +1,6 @@
+export * from './di/container';
+export * from './error';
+export * from './logger';
+export * from './schema';
+export * from './shared';
+export * from './utils';

package/dist/kernel/index.js

@@ -0,0 +1,7 @@
+// External to export
+export * from './di/container';
+export * from './error';
+export * from './logger';
+export * from './schema';
+export * from './shared';
+export * from './utils';

package/dist/kernel/logger/client-log-console.d.ts

@@ -0,0 +1,4 @@
+import { IClientLogConsole } from '../../adapters/contracts/client/IClientLogConsole';
+export declare function getClientLogConsole(): IClientLogConsole;
+export declare function setClientLogConsole(logConsole: IClientLogConsole): void;
+export declare function resetClientLogConsoleForTests(): void;