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

package/dist/kernel/logger/transports/transport.interface.d.ts

@@ -0,0 +1,40 @@
+import { LogEntry, LogLevel } from '../logger.types';
+/**
+ * Contract that all log transports must implement.
+ *
+ * A transport is responsible for delivering log entries to a specific destination
+ * (console, file, database, external service, etc.).
+ *
+ * @example
+ * ```typescript
+ * class FileTransport implements LogTransport {
+ *   name = 'file'
+ *   minLevel = LogLevel.WARN
+ *
+ *   write(entry: LogEntry): void {
+ *     fs.appendFileSync('app.log', JSON.stringify(entry) + '\n')
+ *   }
+ * }
+ * ```
+ */
+export interface LogTransport {
+    /**
+     * Unique identifier for this transport.
+     * Used for debugging and transport management.
+     */
+    readonly name: string;
+    /**
+     * Minimum log level this transport will handle.
+     * Entries below this level will be ignored by this transport.
+     */
+    minLevel: LogLevel;
+    /**
+     * Process and deliver a log entry to its destination.
+     * @param entry - The log entry to process
+     */
+    write(entry: LogEntry): void;
+    /**
+     * Optional cleanup method called when the transport is removed or the logger is destroyed.
+     */
+    destroy?(): void;
+}

package/dist/kernel/logger/transports/websocket.transport.d.ts

@@ -0,0 +1,69 @@
+import { type LogEntry, LogLevel } from '../logger.types';
+import { LogTransport } from './transport.interface';
+/**
+ * Configuration for WebSocket log transport.
+ */
+export interface WebSocketTransportOptions {
+    /** WebSocket server URL */
+    url: string;
+    /** Auto-reconnect on disconnect */
+    reconnect?: boolean;
+    /** Reconnect interval in milliseconds */
+    reconnectInterval?: number;
+    /** Maximum buffer size when disconnected */
+    bufferSize?: number;
+}
+/**
+ * WebSocket-based log transport for streaming logs to external tools.
+ *
+ * Used during development to stream logs to the CLI or other monitoring tools.
+ * Buffers messages when disconnected and flushes on reconnection.
+ *
+ * @example
+ * ```typescript
+ * const transport = new WebSocketLogTransport({
+ *   url: 'ws://localhost:3848',
+ *   reconnect: true,
+ * })
+ * await transport.connect()
+ * logger.addTransport(transport)
+ * ```
+ */
+export declare class WebSocketLogTransport implements LogTransport {
+    readonly name = "websocket";
+    minLevel: LogLevel;
+    private ws;
+    private buffer;
+    private options;
+    private connected;
+    private reconnectTimer;
+    private messageHandlers;
+    constructor(options: WebSocketTransportOptions, minLevel?: LogLevel);
+    /**
+     * Connects to the WebSocket server.
+     */
+    connect(): Promise<void>;
+    /**
+     * Writes a log entry to the WebSocket or buffer.
+     */
+    write(entry: LogEntry): void;
+    /**
+     * Sends a raw message through the WebSocket.
+     */
+    send(message: unknown): void;
+    /**
+     * Registers a handler for incoming messages.
+     */
+    onMessage(handler: (data: unknown) => void): void;
+    /**
+     * Checks if currently connected.
+     */
+    isConnected(): boolean;
+    /**
+     * Disconnects and cleans up resources.
+     */
+    destroy(): void;
+    private bufferEntry;
+    private flushBuffer;
+    private scheduleReconnect;
+}

package/dist/kernel/logger/transports/websocket.transport.js

@@ -0,0 +1,164 @@
+import { LogLevel } from '../logger.types';
+/**
+ * WebSocket-based log transport for streaming logs to external tools.
+ *
+ * Used during development to stream logs to the CLI or other monitoring tools.
+ * Buffers messages when disconnected and flushes on reconnection.
+ *
+ * @example
+ * ```typescript
+ * const transport = new WebSocketLogTransport({
+ *   url: 'ws://localhost:3848',
+ *   reconnect: true,
+ * })
+ * await transport.connect()
+ * logger.addTransport(transport)
+ * ```
+ */
+export class WebSocketLogTransport {
+    name = 'websocket';
+    minLevel;
+    ws = null;
+    buffer = [];
+    options;
+    connected = false;
+    reconnectTimer = null;
+    messageHandlers = [];
+    constructor(options, minLevel = LogLevel.DEBUG) {
+        this.minLevel = minLevel;
+        this.options = {
+            url: options.url,
+            reconnect: options.reconnect ?? true,
+            reconnectInterval: options.reconnectInterval ?? 5000,
+            bufferSize: options.bufferSize ?? 100,
+        };
+    }
+    /**
+     * Connects to the WebSocket server.
+     */
+    async connect() {
+        return new Promise((resolve, reject) => {
+            try {
+                this.ws = new WebSocket(this.options.url);
+                this.ws.onopen = () => {
+                    this.connected = true;
+                    this.flushBuffer();
+                    resolve();
+                };
+                this.ws.onclose = () => {
+                    this.connected = false;
+                    this.ws = null;
+                    if (this.options.reconnect) {
+                        this.scheduleReconnect();
+                    }
+                };
+                this.ws.onerror = (error) => {
+                    if (!this.connected) {
+                        reject(error);
+                    }
+                };
+                this.ws.onmessage = (event) => {
+                    try {
+                        const data = JSON.parse(event.data);
+                        for (const handler of this.messageHandlers) {
+                            handler(data);
+                        }
+                    }
+                    catch {
+                        // Ignore parse errors
+                    }
+                };
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    }
+    /**
+     * Writes a log entry to the WebSocket or buffer.
+     */
+    write(entry) {
+        const message = {
+            type: 'log',
+            payload: {
+                level: entry.level,
+                domain: entry.domain,
+                message: entry.message,
+                timestamp: entry.timestamp,
+                context: entry.context,
+                error: entry.error
+                    ? {
+                        name: entry.error.name,
+                        message: entry.error.message,
+                        stack: entry.error.stack,
+                    }
+                    : undefined,
+            },
+        };
+        if (this.connected && this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(message));
+        }
+        else {
+            this.bufferEntry(entry);
+        }
+    }
+    /**
+     * Sends a raw message through the WebSocket.
+     */
+    send(message) {
+        if (this.connected && this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(message));
+        }
+    }
+    /**
+     * Registers a handler for incoming messages.
+     */
+    onMessage(handler) {
+        this.messageHandlers.push(handler);
+    }
+    /**
+     * Checks if currently connected.
+     */
+    isConnected() {
+        return this.connected;
+    }
+    /**
+     * Disconnects and cleans up resources.
+     */
+    destroy() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            this.ws.onclose = null;
+            this.ws.close();
+            this.ws = null;
+        }
+        this.connected = false;
+        this.buffer = [];
+        this.messageHandlers = [];
+    }
+    bufferEntry(entry) {
+        this.buffer.push(entry);
+        if (this.buffer.length > this.options.bufferSize) {
+            this.buffer.shift();
+        }
+    }
+    flushBuffer() {
+        for (const entry of this.buffer) {
+            this.write(entry);
+        }
+        this.buffer = [];
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer)
+            return;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect().catch(() => {
+                // Will retry via onclose handler
+            });
+        }, this.options.reconnectInterval);
+    }
+}

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

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+/**
+ * Infers the output type from a Zod schema.
+ *
+ * @example
+ * ```ts
+ * import { z, Infer } from '@open-core/framework'
+ *
+ * const UserSchema = z.object({
+ *   name: z.string(),
+ *   age: z.number(),
+ * })
+ *
+ * // In handler parameter
+ * onEvent(player: Player, data: Infer<typeof UserSchema>) {
+ *   data.name  // string
+ *   data.age   // number
+ * }
+ * ```
+ */
+export type Infer<T extends z.ZodType> = z.infer<T>;
+/**
+ * Infers the input type from a Zod schema.
+ * Useful when schema has transforms that change the output type.
+ */
+export type Input<T extends z.ZodType> = z.input<T>;
+/**
+ * Infers the output type from a Zod schema.
+ * Alias for Infer<T>.
+ */
+export type Output<T extends z.ZodType> = z.output<T>;
+export { z };

package/dist/kernel/schema/index.js

@@ -0,0 +1,4 @@
+import { z } from 'zod';
+// Re-export Zod for convenience
+// Developers can import { z } from '@open-core/framework' instead of 'zod'
+export { z };

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

@@ -0,0 +1 @@
+export * from './player-appearance.types';

package/dist/kernel/shared/index.js

@@ -0,0 +1 @@
+export * from './player-appearance.types';

package/dist/kernel/shared/player-appearance.types.d.ts

@@ -0,0 +1,276 @@
+/**
+ * Component variation data for a ped.
+ *
+ * @remarks
+ * Used for clothing, hair, and other visual components.
+ * Component IDs range from 0 to 11.
+ */
+export interface ComponentVariation {
+    /** Drawable index for the component */
+    drawable: number;
+    /** Texture index for the drawable */
+    texture: number;
+}
+/**
+ * Prop data for a ped.
+ *
+ * @remarks
+ * Used for hats, glasses, watches, and other accessories.
+ * Prop IDs range from 0 to 7.
+ */
+export interface PropVariation {
+    /** Drawable index for the prop (-1 to remove) */
+    drawable: number;
+    /** Texture index for the drawable */
+    texture: number;
+}
+/**
+ * Head blend data for freemode character creation.
+ *
+ * @remarks
+ * Controls the facial structure inheritance from parent faces.
+ * Shape and skin IDs range from 0 to 45.
+ * Mix values range from 0.0 to 1.0.
+ */
+export interface HeadBlendData {
+    /** First parent shape ID (0-45) */
+    shapeFirst: number;
+    /** Second parent shape ID (0-45) */
+    shapeSecond: number;
+    /** Third parent shape ID (0-45), optional */
+    shapeThird?: number;
+    /** First parent skin ID (0-45) */
+    skinFirst: number;
+    /** Second parent skin ID (0-45) */
+    skinSecond: number;
+    /** Third parent skin ID (0-45), optional */
+    skinThird?: number;
+    /** Shape mix between first and second parent (0.0-1.0) */
+    shapeMix: number;
+    /** Skin mix between first and second parent (0.0-1.0) */
+    skinMix: number;
+    /** Third parent mix (0.0-1.0), optional */
+    thirdMix?: number;
+}
+/**
+ * Head overlay data for facial features like makeup, beard, etc.
+ *
+ * @remarks
+ * Overlay IDs range from 0 to 12:
+ * - 0: Blemishes (0-23)
+ * - 1: Facial Hair (0-28)
+ * - 2: Eyebrows (0-33)
+ * - 3: Ageing (0-14)
+ * - 4: Makeup (0-74)
+ * - 5: Blush (0-6)
+ * - 6: Complexion (0-11)
+ * - 7: Sun Damage (0-10)
+ * - 8: Lipstick (0-9)
+ * - 9: Moles/Freckles (0-17)
+ * - 10: Chest Hair (0-16)
+ * - 11: Body Blemishes (0-11)
+ * - 12: Add Body Blemishes (0-1)
+ *
+ * Set index to 255 to disable the overlay.
+ */
+export interface HeadOverlayData {
+    /** Overlay variation index (use 255 to disable) */
+    index: number;
+    /** Opacity of the overlay (0.0-1.0) */
+    opacity: number;
+    /**
+     * Color type for the overlay.
+     * - 0: Default
+     * - 1: Hair colors (eyebrows, beards, chest hair)
+     * - 2: Makeup colors (blush, lipstick)
+     */
+    colorType?: number;
+    /** Primary color ID */
+    colorId?: number;
+    /** Secondary color ID */
+    secondColorId?: number;
+}
+/**
+ * Hair color data including highlights.
+ */
+export interface HairColorData {
+    /** Primary hair color ID */
+    colorId: number;
+    /** Highlight color ID */
+    highlightColorId: number;
+}
+/**
+ * Tattoo/decoration data.
+ *
+ * @remarks
+ * Tattoos are applied using collection and overlay hashes.
+ * Collections are defined in game files (e.g., "mpbeach_overlays").
+ */
+export interface TattooData {
+    /** Collection name hash (e.g., "mpbeach_overlays") */
+    collection: string;
+    /** Overlay name hash within the collection */
+    overlay: string;
+}
+/**
+ * Complete player appearance data structure.
+ *
+ * @remarks
+ * This interface contains all customization options for a freemode ped.
+ * Not all fields are required - only include what needs to be changed.
+ *
+ * @example
+ * ```typescript
+ * const appearance: PlayerAppearance = {
+ *   model: 'mp_m_freemode_01',
+ *   headBlend: {
+ *     shapeFirst: 0,
+ *     shapeSecond: 21,
+ *     skinFirst: 0,
+ *     skinSecond: 21,
+ *     shapeMix: 0.5,
+ *     skinMix: 0.5
+ *   },
+ *   components: {
+ *     3: { drawable: 15, texture: 0 }, // Torso
+ *     4: { drawable: 21, texture: 0 }, // Legs
+ *     6: { drawable: 34, texture: 0 }, // Shoes
+ *   },
+ *   eyeColor: 3,
+ *   hairColor: { colorId: 5, highlightColorId: 0 }
+ * }
+ * ```
+ */
+export interface PlayerAppearance {
+    /**
+     * Ped model name.
+     * @example "mp_m_freemode_01" or "mp_f_freemode_01"
+     */
+    model?: string;
+    /**
+     * Component variations (clothing, hair, etc.).
+     * Keys are component IDs (0-11).
+     */
+    components?: Record<number, ComponentVariation>;
+    /**
+     * Prop variations (hats, glasses, etc.).
+     * Keys are prop IDs (0-7).
+     */
+    props?: Record<number, PropVariation>;
+    /**
+     * Face feature morphs.
+     * Keys are feature indices (0-19), values range from -1.0 to 1.0.
+     *
+     * @remarks
+     * Feature indices:
+     * - 0-5: Nose (width, peak, length, curve, tip, twist)
+     * - 6-7: Eyebrows (up/down, in/out)
+     * - 8-10: Cheeks (height, width, puffed)
+     * - 11: Eye opening
+     * - 12: Lip thickness
+     * - 13-14: Jaw (width, shape)
+     * - 15-18: Chin (height, length, shape, hole)
+     * - 19: Neck thickness
+     */
+    faceFeatures?: Record<number, number>;
+    /**
+     * Head blend data for facial structure.
+     */
+    headBlend?: HeadBlendData;
+    /**
+     * Head overlays (makeup, facial hair, etc.).
+     * Keys are overlay IDs (0-12).
+     */
+    headOverlays?: Record<number, HeadOverlayData>;
+    /**
+     * Hair color and highlights.
+     */
+    hairColor?: HairColorData;
+    /**
+     * Eye color index (0-31).
+     */
+    eyeColor?: number;
+    /**
+     * Tattoos/decorations to apply.
+     */
+    tattoos?: TattooData[];
+}
+/**
+ * Result of appearance validation.
+ */
+export interface AppearanceValidationResult {
+    /** Whether the appearance data is valid */
+    valid: boolean;
+    /** List of validation errors if any */
+    errors: string[];
+}
+/**
+ * Component ID enum for better code readability.
+ */
+export declare enum ComponentId {
+    Face = 0,
+    Mask = 1,
+    Hair = 2,
+    Torso = 3,
+    Legs = 4,
+    Parachute = 5,
+    Shoes = 6,
+    Accessory = 7,
+    Undershirt = 8,
+    Kevlar = 9,
+    Badge = 10,
+    Torso2 = 11
+}
+/**
+ * Prop ID enum for better code readability.
+ */
+export declare enum PropId {
+    Hat = 0,
+    Glasses = 1,
+    Ears = 2,
+    Watch = 6,
+    Bracelet = 7
+}
+/**
+ * Overlay ID enum for better code readability.
+ */
+export declare enum OverlayId {
+    Blemishes = 0,
+    FacialHair = 1,
+    Eyebrows = 2,
+    Ageing = 3,
+    Makeup = 4,
+    Blush = 5,
+    Complexion = 6,
+    SunDamage = 7,
+    Lipstick = 8,
+    MolesFreckles = 9,
+    ChestHair = 10,
+    BodyBlemishes = 11,
+    AddBodyBlemishes = 12
+}
+/**
+ * Face feature index enum for better code readability.
+ */
+export declare enum FaceFeatureIndex {
+    NoseWidth = 0,
+    NosePeak = 1,
+    NoseLength = 2,
+    NoseCurve = 3,
+    NoseTip = 4,
+    NoseTwist = 5,
+    EyebrowHeight = 6,
+    EyebrowDepth = 7,
+    CheekHeight = 8,
+    CheekWidth = 9,
+    CheekDepth = 10,
+    EyeOpening = 11,
+    LipThickness = 12,
+    JawWidth = 13,
+    JawShape = 14,
+    ChinHeight = 15,
+    ChinLength = 16,
+    ChinShape = 17,
+    ChinHole = 18,
+    NeckThickness = 19
+}

package/dist/kernel/shared/player-appearance.types.js

@@ -0,0 +1,74 @@
+/**
+ * Component ID enum for better code readability.
+ */
+export var ComponentId;
+(function (ComponentId) {
+    ComponentId[ComponentId["Face"] = 0] = "Face";
+    ComponentId[ComponentId["Mask"] = 1] = "Mask";
+    ComponentId[ComponentId["Hair"] = 2] = "Hair";
+    ComponentId[ComponentId["Torso"] = 3] = "Torso";
+    ComponentId[ComponentId["Legs"] = 4] = "Legs";
+    ComponentId[ComponentId["Parachute"] = 5] = "Parachute";
+    ComponentId[ComponentId["Shoes"] = 6] = "Shoes";
+    ComponentId[ComponentId["Accessory"] = 7] = "Accessory";
+    ComponentId[ComponentId["Undershirt"] = 8] = "Undershirt";
+    ComponentId[ComponentId["Kevlar"] = 9] = "Kevlar";
+    ComponentId[ComponentId["Badge"] = 10] = "Badge";
+    ComponentId[ComponentId["Torso2"] = 11] = "Torso2";
+})(ComponentId || (ComponentId = {}));
+/**
+ * Prop ID enum for better code readability.
+ */
+export var PropId;
+(function (PropId) {
+    PropId[PropId["Hat"] = 0] = "Hat";
+    PropId[PropId["Glasses"] = 1] = "Glasses";
+    PropId[PropId["Ears"] = 2] = "Ears";
+    PropId[PropId["Watch"] = 6] = "Watch";
+    PropId[PropId["Bracelet"] = 7] = "Bracelet";
+})(PropId || (PropId = {}));
+/**
+ * Overlay ID enum for better code readability.
+ */
+export var OverlayId;
+(function (OverlayId) {
+    OverlayId[OverlayId["Blemishes"] = 0] = "Blemishes";
+    OverlayId[OverlayId["FacialHair"] = 1] = "FacialHair";
+    OverlayId[OverlayId["Eyebrows"] = 2] = "Eyebrows";
+    OverlayId[OverlayId["Ageing"] = 3] = "Ageing";
+    OverlayId[OverlayId["Makeup"] = 4] = "Makeup";
+    OverlayId[OverlayId["Blush"] = 5] = "Blush";
+    OverlayId[OverlayId["Complexion"] = 6] = "Complexion";
+    OverlayId[OverlayId["SunDamage"] = 7] = "SunDamage";
+    OverlayId[OverlayId["Lipstick"] = 8] = "Lipstick";
+    OverlayId[OverlayId["MolesFreckles"] = 9] = "MolesFreckles";
+    OverlayId[OverlayId["ChestHair"] = 10] = "ChestHair";
+    OverlayId[OverlayId["BodyBlemishes"] = 11] = "BodyBlemishes";
+    OverlayId[OverlayId["AddBodyBlemishes"] = 12] = "AddBodyBlemishes";
+})(OverlayId || (OverlayId = {}));
+/**
+ * Face feature index enum for better code readability.
+ */
+export var FaceFeatureIndex;
+(function (FaceFeatureIndex) {
+    FaceFeatureIndex[FaceFeatureIndex["NoseWidth"] = 0] = "NoseWidth";
+    FaceFeatureIndex[FaceFeatureIndex["NosePeak"] = 1] = "NosePeak";
+    FaceFeatureIndex[FaceFeatureIndex["NoseLength"] = 2] = "NoseLength";
+    FaceFeatureIndex[FaceFeatureIndex["NoseCurve"] = 3] = "NoseCurve";
+    FaceFeatureIndex[FaceFeatureIndex["NoseTip"] = 4] = "NoseTip";
+    FaceFeatureIndex[FaceFeatureIndex["NoseTwist"] = 5] = "NoseTwist";
+    FaceFeatureIndex[FaceFeatureIndex["EyebrowHeight"] = 6] = "EyebrowHeight";
+    FaceFeatureIndex[FaceFeatureIndex["EyebrowDepth"] = 7] = "EyebrowDepth";
+    FaceFeatureIndex[FaceFeatureIndex["CheekHeight"] = 8] = "CheekHeight";
+    FaceFeatureIndex[FaceFeatureIndex["CheekWidth"] = 9] = "CheekWidth";
+    FaceFeatureIndex[FaceFeatureIndex["CheekDepth"] = 10] = "CheekDepth";
+    FaceFeatureIndex[FaceFeatureIndex["EyeOpening"] = 11] = "EyeOpening";
+    FaceFeatureIndex[FaceFeatureIndex["LipThickness"] = 12] = "LipThickness";
+    FaceFeatureIndex[FaceFeatureIndex["JawWidth"] = 13] = "JawWidth";
+    FaceFeatureIndex[FaceFeatureIndex["JawShape"] = 14] = "JawShape";
+    FaceFeatureIndex[FaceFeatureIndex["ChinHeight"] = 15] = "ChinHeight";
+    FaceFeatureIndex[FaceFeatureIndex["ChinLength"] = 16] = "ChinLength";
+    FaceFeatureIndex[FaceFeatureIndex["ChinShape"] = 17] = "ChinShape";
+    FaceFeatureIndex[FaceFeatureIndex["ChinHole"] = 18] = "ChinHole";
+    FaceFeatureIndex[FaceFeatureIndex["NeckThickness"] = 19] = "NeckThickness";
+})(FaceFeatureIndex || (FaceFeatureIndex = {}));

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

@@ -0,0 +1,3 @@
+export * from './result';
+export * from './rgb';
+export * from './vector3';

package/dist/kernel/utils/index.js

@@ -0,0 +1,3 @@
+export * from './result';
+export * from './rgb';
+export * from './vector3';

package/dist/kernel/utils/result.d.ts

@@ -0,0 +1,12 @@
+import { AppError } from '../error/app.error';
+export interface Ok<T> {
+    ok: true;
+    value: T;
+}
+export interface Err<E = AppError> {
+    ok: false;
+    error: E;
+}
+export type Result<T, E = AppError> = Ok<T> | Err<E>;
+export declare function ok<T>(value: T): Ok<T>;
+export declare function err<E>(error: E): Err<E>;

package/dist/kernel/utils/result.js

@@ -0,0 +1,6 @@
+export function ok(value) {
+    return { ok: true, value };
+}
+export function err(error) {
+    return { ok: false, error };
+}