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

package/dist/runtime/server/entities/vehicle.js

@@ -0,0 +1,245 @@
+import { BaseEntity } from '../../core/entity';
+/**
+ * Runtime representation of a server-managed vehicle entity.
+ *
+ * @remarks
+ * This class stores ownership/mod/metadata state and delegates native calls through
+ * framework adapters. Most mutating methods are no-ops when the entity no longer exists.
+ */
+export class Vehicle extends BaseEntity {
+    session;
+    adapters;
+    ownershipData;
+    modsData = {};
+    metadataData = {};
+    /**
+     * Creates a new vehicle entity wrapper.
+     *
+     * @param handle - Native entity handle.
+     * @param networkId - Network ID for cross-client references.
+     * @param ownership - Initial ownership descriptor.
+     * @param adapters - Entity/vehicle adapters.
+     * @param persistent - Whether orphan mode should keep this entity alive.
+     * @param routingBucket - Initial routing bucket.
+     * @param model - Resolved model string.
+     * @param modelHash - Spawn model hash.
+     */
+    constructor(handle, networkId, ownership, adapters, persistent = false, routingBucket = 0, model, modelHash) {
+        super(`car:${handle}`);
+        this.adapters = adapters;
+        this.ownershipData = ownership;
+        this.session = {
+            handle,
+            networkId,
+            model,
+            modelHash,
+            persistent,
+            routingBucket,
+            createdAt: Date.now(),
+        };
+        if (persistent) {
+            this.adapters.entityServer.setOrphanMode(handle, 2);
+        }
+        this.metadataData.createdAt = this.session.createdAt;
+        this._dimension = routingBucket;
+    }
+    /** Returns the native entity handle. */
+    getHandle() {
+        return this.session.handle;
+    }
+    /** Returns current world coordinates. */
+    getPosition() {
+        return this.adapters.entityServer.getCoords(this.session.handle);
+    }
+    /** Teleports the entity to a target position. */
+    setPosition(position) {
+        if (!this.exists)
+            return;
+        this.adapters.entityServer.setPosition(this.session.handle, position, { clearArea: true });
+    }
+    /** Returns current heading (yaw). */
+    getHeading() {
+        return this.adapters.entityServer.getHeading(this.session.handle);
+    }
+    /** Sets heading (yaw) in degrees. */
+    setHeading(heading) {
+        if (!this.exists)
+            return;
+        this.adapters.entityServer.setHeading(this.session.handle, heading);
+    }
+    /** Native handle shortcut. */
+    get handle() {
+        return this.session.handle;
+    }
+    /** Stable network ID. */
+    get networkId() {
+        return this.session.networkId;
+    }
+    /** Resolved model identifier. */
+    get model() {
+        return this.session.model;
+    }
+    /** Model hash used at spawn time. */
+    get modelHash() {
+        return this.session.modelHash;
+    }
+    /** Whether the vehicle is configured as persistent. */
+    get persistent() {
+        return this.session.persistent;
+    }
+    /** Current routing bucket/dimension. */
+    get routingBucket() {
+        return this.getRoutingBucket();
+    }
+    /** Dimension alias for routing bucket. */
+    get dimension() {
+        return this.getRoutingBucket();
+    }
+    /** Dimension alias for routing bucket. */
+    set dimension(value) {
+        this.setRoutingBucket(value);
+    }
+    /** Snapshot of ownership data. */
+    get ownership() {
+        return { ...this.ownershipData };
+    }
+    /** Snapshot of stored mods. */
+    get mods() {
+        return { ...this.modsData };
+    }
+    /** Snapshot of metadata values. */
+    get metadata() {
+        return { ...this.metadataData };
+    }
+    /** True when the underlying native entity exists. */
+    get exists() {
+        return this.adapters.entityServer.doesExist(this.session.handle);
+    }
+    /** Position shorthand using {@link getPosition}. */
+    get position() {
+        return this.getPosition();
+    }
+    /** Heading shorthand using {@link getHeading}. */
+    get heading() {
+        return this.getHeading();
+    }
+    /** Current license plate text. */
+    get plate() {
+        return this.adapters.vehicleServer.getNumberPlateText(this.session.handle);
+    }
+    /** Merges ownership data and replicates it to state bag. */
+    setOwnership(ownership) {
+        this.ownershipData = { ...this.ownershipData, ...ownership };
+        this.syncStateBag('ownership', this.ownershipData);
+    }
+    /** Merges vehicle mod state and updates modification timestamp. */
+    setMods(mods) {
+        if (!this.exists)
+            return;
+        this.modsData = { ...this.modsData, ...mods };
+        this.metadataData.modifiedAt = Date.now();
+        this.syncStateBag('mods', this.modsData);
+    }
+    /** Stores custom metadata and replicates it to state bag. */
+    setMetadata(key, value) {
+        this.metadataData[key] = value;
+        this.syncStateBag(`meta_${key}`, value);
+    }
+    /** Reads one metadata value by key. */
+    getMetadata(key) {
+        return this.metadataData[key];
+    }
+    /** Reads current routing bucket, using cached value if entity no longer exists. */
+    getRoutingBucket() {
+        if (!this.exists) {
+            return this.session.routingBucket;
+        }
+        return this.adapters.entityServer.getRoutingBucket(this.session.handle);
+    }
+    /** Sets routing bucket and updates local dimension snapshot. */
+    setRoutingBucket(bucket) {
+        if (!this.exists)
+            return;
+        this.adapters.entityServer.setRoutingBucket(this.session.handle, bucket);
+        this.session.routingBucket = bucket;
+        this._dimension = bucket;
+    }
+    /** Sets plate text (trimmed to 8 chars). */
+    setPlate(plate) {
+        if (!this.exists)
+            return;
+        this.adapters.vehicleServer.setNumberPlateText(this.session.handle, plate.substring(0, 8));
+    }
+    /** Sets primary/secondary vehicle colors. */
+    setColors(primaryColor, secondaryColor) {
+        if (!this.exists)
+            return;
+        const [currentPrimary, currentSecondary] = this.adapters.vehicleServer.getColours(this.session.handle);
+        this.adapters.vehicleServer.setColours(this.session.handle, primaryColor ?? currentPrimary, secondaryColor ?? currentSecondary);
+    }
+    /** Flags this vehicle for repair through replicated metadata. */
+    markForRepair() {
+        if (!this.exists)
+            return;
+        this.metadataData.needsRepair = true;
+        this.metadataData.repairRequestedAt = Date.now();
+        this.syncStateBag('needsRepair', true);
+    }
+    /** Sets fuel level in range 0-100. */
+    setFuel(level) {
+        if (!this.exists)
+            return;
+        const clamped = Math.max(0, Math.min(100, level));
+        this.metadataData.fuel = clamped;
+        this.syncStateBag('fuel', clamped);
+    }
+    /** Gets stored fuel level, defaulting to 100. */
+    getFuel() {
+        return this.metadataData.fuel ?? 100;
+    }
+    /** Locks or unlocks doors and replicates lock state. */
+    setDoorsLocked(locked) {
+        if (!this.exists)
+            return;
+        this.adapters.vehicleServer.setDoorsLocked(this.session.handle, locked ? 2 : 1);
+        this.syncStateBag('locked', locked);
+    }
+    /** Teleports vehicle and optionally sets heading. */
+    teleport(position, heading) {
+        if (!this.exists)
+            return;
+        this.setPosition(position);
+        if (heading !== undefined) {
+            this.setHeading(heading);
+        }
+    }
+    /** Deletes the underlying entity. */
+    delete() {
+        if (!this.exists)
+            return;
+        this.adapters.entityServer.delete(this.session.handle);
+    }
+    /** Serializes this vehicle state for transport. */
+    serialize() {
+        return {
+            networkId: this.session.networkId,
+            handle: this.session.handle,
+            modelHash: this.modelHash,
+            model: this.model,
+            position: this.position,
+            heading: this.heading,
+            plate: this.plate,
+            ownership: this.ownership,
+            mods: this.mods,
+            metadata: this.metadata,
+            routingBucket: this.routingBucket,
+            persistent: this.session.persistent,
+        };
+    }
+    /** Writes one replicated value to entity state bag. */
+    syncStateBag(key, value) {
+        if (!this.exists)
+            return;
+        this.adapters.entityServer.getStateBag(this.session.handle).set(key, value, true);
+    }
+}

package/dist/runtime/server/error-handler.d.ts

@@ -0,0 +1,2 @@
+import { CommandMetadata } from './decorators/command';
+export declare function handleCommandError(error: unknown, meta: CommandMetadata, playerId: number | null): void;

package/dist/runtime/server/error-handler.js

@@ -0,0 +1,39 @@
+import { AppError, isAppError } from '../../kernel/error/app.error';
+import { loggers } from '../../kernel/logger';
+function normalizeError(error, origin) {
+    if (isAppError(error)) {
+        return error;
+    }
+    if (error instanceof Error) {
+        return new AppError('COMMON:UNKNOWN', error.message, origin, { stack: error.stack });
+    }
+    return new AppError('COMMON:UNKNOWN', String(error), origin, { raw: error });
+}
+export function handleCommandError(error, meta, playerId) {
+    const appError = normalizeError(error, 'server');
+    loggers.command.error(`Command execution failed: /${meta.command}`, {
+        command: meta.command,
+        handler: meta.methodName,
+        playerId,
+        code: appError.code,
+        origin: appError.origin,
+        errorMessage: appError.message,
+        details: appError.details,
+    });
+    if (playerId !== null) {
+        switch (appError.code) {
+            case 'ECONOMY:INSUFFICIENT_FUNDS':
+            case 'AUTH:PERMISSION_DENIED':
+            case 'AUTH:UNAUTHORIZED':
+                emitNet('chat:addMessage', playerId, {
+                    args: ['^1Error', appError.message],
+                });
+                break;
+            default:
+                emitNet('chat:addMessage', playerId, {
+                    args: ['^1Error', 'Ha ocurrido un error interno.'],
+                });
+                break;
+        }
+    }
+}

package/dist/runtime/server/helpers/command-validation.helper.d.ts

@@ -0,0 +1,3 @@
+import { CommandMetadata } from '../decorators/command';
+import { Player } from '../entities';
+export declare function validateAndExecuteCommand(meta: CommandMetadata, player: Player, args: string[], handler: (...args: any[]) => any): Promise<any>;

package/dist/runtime/server/helpers/command-validation.helper.js

@@ -0,0 +1,73 @@
+import z from 'zod';
+import { AppError } from '../../../kernel';
+import { generateSchemaFromTypes } from '../system/schema-generator';
+import { processTupleSchema } from './process-tuple-schema';
+export async function validateAndExecuteCommand(meta, player, args, handler) {
+    const paramNames = meta.expectsPlayer ? meta.paramNames.slice(1) : meta.paramNames;
+    let schema = meta.schema;
+    if (!meta.expectsPlayer) {
+        if (args.length > 0) {
+            throw new AppError('GAME:BAD_REQUEST', `Incorrect usage, use: ${meta.usage}`, 'client', {
+                usage: meta.usage,
+            });
+        }
+        return await handler();
+    }
+    if (!schema) {
+        schema = generateSchemaFromTypes(meta.paramTypes);
+        if (!schema) {
+            if (paramNames.length > 0) {
+                throw new AppError('SCHEMA:MISMATCH', `Command '${meta.command}' has parameters ${paramNames.join(', ')} but no schema was provided.`, 'core');
+            }
+            return await handler(player);
+        }
+    }
+    if (schema instanceof z.ZodObject) {
+        const keys = Object.keys(schema.shape);
+        for (const p of paramNames) {
+            if (!keys.includes(p)) {
+                throw new AppError('SCHEMA:MISMATCH', `Command '${meta.command}' is missing schema for parameter '${p}'.`, 'core');
+            }
+        }
+        for (const key of keys) {
+            if (!paramNames.includes(key)) {
+                throw new AppError('SCHEMA:MISMATCH', `Schema for command '${meta.command}' defines '${key}', but handler does not.`, 'core');
+            }
+        }
+        const inputObj = {};
+        for (let i = 0; i < paramNames.length; i++) {
+            inputObj[paramNames[i]] = args[i];
+        }
+        const validated = await schema.parseAsync(inputObj).catch(() => {
+            throw new AppError('GAME:BAD_REQUEST', `Incorrect usage, use: ${meta.usage}`, 'client', {
+                usage: meta.usage,
+            });
+        });
+        const obj = validated;
+        const finalArgs = paramNames.map((name) => obj[name]);
+        return await handler(player, ...finalArgs);
+    }
+    // TUPLA schema
+    if (schema instanceof z.ZodTuple) {
+        const processedArgs = processTupleSchema(schema, args);
+        const validated = await schema.parseAsync(processedArgs).catch(() => {
+            throw new AppError('GAME:BAD_REQUEST', `Incorrect usage, use: ${meta.usage}`, 'client', {
+                usage: meta.usage,
+            });
+        });
+        const finalArgs = validated;
+        // If the handler uses spread operator (...args), flatten the last array argument
+        // so the handler receives individual arguments instead of a single array.
+        if (meta.hasSpreadParam &&
+            finalArgs.length > 0 &&
+            Array.isArray(finalArgs[finalArgs.length - 1])) {
+            const positional = finalArgs.slice(0, finalArgs.length - 1);
+            const rest = finalArgs[finalArgs.length - 1];
+            return await handler(player, ...positional, ...rest);
+        }
+        // For regular array parameters (args: string[]), pass as-is
+        return await handler(player, ...finalArgs);
+    }
+    // fallback
+    return await handler(player);
+}

package/dist/runtime/server/helpers/function-helper.d.ts

@@ -0,0 +1,6 @@
+export declare function getParameterNames(func: (...args: any[]) => any): string[];
+/**
+ * Detects which parameter indices use the spread operator (...args).
+ * Returns an array of booleans where true means the parameter at that index is a spread parameter.
+ */
+export declare function getSpreadParameterIndices(func: (...args: any[]) => any): boolean[];

package/dist/runtime/server/helpers/function-helper.js

@@ -0,0 +1,28 @@
+export function getParameterNames(func) {
+    const stripped = func
+        .toString()
+        .replace(/\/\/.*$/gm, '')
+        .replace(/\/\*[\s\S]*?\*\//gm, '');
+    const args = stripped
+        .slice(stripped.indexOf('(') + 1, stripped.indexOf(')'))
+        .split(',')
+        .map((arg) => arg.replace(/=[\s\S]*/, '').trim())
+        .filter(Boolean);
+    return args;
+}
+/**
+ * Detects which parameter indices use the spread operator (...args).
+ * Returns an array of booleans where true means the parameter at that index is a spread parameter.
+ */
+export function getSpreadParameterIndices(func) {
+    const stripped = func
+        .toString()
+        .replace(/\/\/.*$/gm, '')
+        .replace(/\/\*[\s\S]*?\*\//gm, '');
+    const argsString = stripped.slice(stripped.indexOf('(') + 1, stripped.indexOf(')'));
+    const args = argsString
+        .split(',')
+        .map((arg) => arg.trim())
+        .filter(Boolean);
+    return args.map((arg) => arg.startsWith('...'));
+}

package/dist/runtime/server/helpers/normalize-app-error.d.ts

@@ -0,0 +1,9 @@
+import { AppError, type ErrorOrigin } from '../../../kernel/error';
+/**
+ * Normalizes unknown thrown values into a consistent {@link AppError}.
+ *
+ * @remarks
+ * Command and event pipelines should never leak raw errors.
+ * This helper ensures observers always receive an AppError.
+ */
+export declare function normalizeToAppError(error: unknown, origin: ErrorOrigin): AppError;

package/dist/runtime/server/helpers/normalize-app-error.js

@@ -0,0 +1,17 @@
+import { AppError, isAppError } from '../../../kernel/error';
+/**
+ * Normalizes unknown thrown values into a consistent {@link AppError}.
+ *
+ * @remarks
+ * Command and event pipelines should never leak raw errors.
+ * This helper ensures observers always receive an AppError.
+ */
+export function normalizeToAppError(error, origin) {
+    if (isAppError(error)) {
+        return error;
+    }
+    if (error instanceof Error) {
+        return new AppError('COMMON:UNKNOWN', error.message, origin, { stack: error.stack });
+    }
+    return new AppError('COMMON:UNKNOWN', String(error), origin, { raw: error });
+}

package/dist/runtime/server/helpers/process-tuple-schema.d.ts

@@ -0,0 +1,20 @@
+import z from 'zod';
+/**
+ * Processes tuple schema validation with greedy handling for rest parameters.
+ *
+ * This function handles two cases:
+ * 1. If last parameter is ZodArray and there are MORE args than schema items,
+ *    collect the extra args into the array position.
+ * 2. If last parameter is ZodString and there are MORE args than schema items,
+ *    join the extra args into a single string.
+ *
+ * Examples:
+ * - handler(player, action: string, ...rest: string[]) with args ["hello", "world", "!"]
+ *   → schema is [z.string(), z.array(z.string())] (2 items)
+ *   → args has 3 items, so we group extra: ["hello", ["world", "!"]]
+ *
+ * - handler(player, command: string, args: string[]) with args ["vida", ["arg1"]]
+ *   → schema is [z.string(), z.array(z.string())] (2 items)
+ *   → args has 2 items, matches schema, no processing needed
+ */
+export declare function processTupleSchema(schema: z.ZodTuple, args: any[]): any[];

package/dist/runtime/server/helpers/process-tuple-schema.js

@@ -0,0 +1,56 @@
+import z from 'zod';
+/**
+ * Processes tuple schema validation with greedy handling for rest parameters.
+ *
+ * This function handles two cases:
+ * 1. If last parameter is ZodArray and there are MORE args than schema items,
+ *    collect the extra args into the array position.
+ * 2. If last parameter is ZodString and there are MORE args than schema items,
+ *    join the extra args into a single string.
+ *
+ * Examples:
+ * - handler(player, action: string, ...rest: string[]) with args ["hello", "world", "!"]
+ *   → schema is [z.string(), z.array(z.string())] (2 items)
+ *   → args has 3 items, so we group extra: ["hello", ["world", "!"]]
+ *
+ * - handler(player, command: string, args: string[]) with args ["vida", ["arg1"]]
+ *   → schema is [z.string(), z.array(z.string())] (2 items)
+ *   → args has 2 items, matches schema, no processing needed
+ */
+export function processTupleSchema(schema, args) {
+    const items = schema.description ? [] : schema._def.items;
+    if (items.length === 0) {
+        return args;
+    }
+    const lastItem = items[items.length - 1];
+    const positionalCount = items.length - 1;
+    // Case: More args than items (Greedy grouping)
+    if (args.length > items.length) {
+        // If last parameter is a string, join extra args with space
+        if (lastItem instanceof z.ZodString) {
+            const positional = args.slice(0, positionalCount);
+            const restString = args.slice(positionalCount).join(' ');
+            return [...positional, restString];
+        }
+        // If last parameter is an array, we keep them as individual elements
+        // for the handler's spread operator (...args) or just as the array itself
+        // if ZodTuple is being used to parse.
+        // However, to avoid nesting [arg1, [arg2, arg3]], we return them flat
+        // if the handler expects a spread, OR we return the array if it's a single param.
+        if (lastItem instanceof z.ZodArray) {
+            // For ZodTuple.parse() to work with a ZodArray at the end,
+            // it actually expects the array as a single element in that position.
+            const positional = args.slice(0, positionalCount);
+            const restArray = args.slice(positionalCount);
+            return [...positional, restArray];
+        }
+    }
+    // Case: Exact match but last is array
+    if (args.length === items.length) {
+        if (lastItem instanceof z.ZodArray && !Array.isArray(args[positionalCount])) {
+            const positional = args.slice(0, positionalCount);
+            return [...positional, [args[positionalCount]]];
+        }
+    }
+    return args;
+}

package/dist/runtime/server/helpers/resolve-method.d.ts

@@ -0,0 +1,5 @@
+export declare function resolveMethod(instance: Record<string, any>, methodName: string, errorMessage: string): {
+    handler: (...args: any[]) => any;
+    handlerName: string;
+    proto: any;
+} | undefined;

package/dist/runtime/server/helpers/resolve-method.js

@@ -0,0 +1,25 @@
+import { AppError } from '../../../kernel/error/app.error';
+import { loggers } from '../../../kernel/logger';
+export function resolveMethod(instance, methodName, errorMessage) {
+    try {
+        const proto = Object.getPrototypeOf(instance);
+        const method = instance[methodName];
+        if (typeof method !== 'function') {
+            loggers.scanner.error(errorMessage, {
+                className: instance.constructor.name,
+                methodName,
+            });
+            return;
+        }
+        const handler = method.bind(instance);
+        const handlerName = `${instance.constructor.name}.${methodName}`;
+        return { handler, handlerName, proto };
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw new AppError('COMMON:UNKNOWN', `[${error.name}] ${error.message}`, 'server', error.stack);
+        }
+        else
+            throw error;
+    }
+}

package/dist/runtime/server/implementations/local/channel.local.d.ts

@@ -0,0 +1,32 @@
+import { EventsAPI } from '../../../../adapters/contracts/transport/events.api';
+import { RGB } from 'src/kernel';
+import { Player } from '../../entities';
+import { Channels } from '../../ports/channel.api-port';
+import { IChannelValidator, ChannelMetadata, ChannelType } from '../../types';
+import { Players } from '../../ports/players.api-port';
+import { Channel } from '../../concepts/channel';
+export declare class LocalChannelImplementation extends Channels {
+    private readonly playerDirectory;
+    private readonly events;
+    private channels;
+    private validator?;
+    constructor(playerDirectory: Players, events: EventsAPI<'server'>);
+    setValidator(validator: IChannelValidator): void;
+    create(id: string, metadata: ChannelMetadata, maxSubscribers?: number): Channel;
+    createPrivate(players: Player[], metadata: ChannelMetadata): Channel;
+    get(id: string): Channel | undefined;
+    delete(id: string): boolean;
+    exists(id: string): boolean;
+    subscribe(channelId: string, player: Player, metadata?: Record<string, unknown>): boolean;
+    unsubscribe(channelId: string, player: Player): boolean;
+    isSubscribed(channelId: string, player: Player): boolean;
+    broadcast(channelId: string, sender: Player, message: string, author?: string, color?: RGB): void;
+    broadcastSystem(channelId: string, message: string, author?: string, color?: RGB): void;
+    getSubscribers(channelId: string): Player[];
+    getChannelsByType(type: ChannelType): Channel[];
+    getChannelsByPlayer(player: Player): Channel[];
+    getAllChannels(): Channel[];
+    clear(): void;
+    clearNonPersistent(): void;
+    createProximityChannel(originPlayer: Player, radius: number, channelId?: string): Channel | undefined;
+}