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

package/dist/server/templates/repository/repository.contract.js

@@ -1,342 +0,0 @@
-"use strict";
-/**
- * Repository Contract
- *
- * Abstract base class for implementing the Repository Pattern.
- * Provides common CRUD operations with support for pagination, ordering, and field selection.
- *
- * @example
- * ```typescript
- * interface User {
- *   id: number
- *   name: string
- *   email: string
- *   createdAt: Date
- * }
- *
- * class UserRepository extends Repository<User> {
- *   protected tableName = 'users'
- *
- *   constructor(db: DatabaseContract) {
- *     super(db)
- *   }
- *
- *   protected toEntity(row: any): User {
- *     return {
- *       id: row.id,
- *       name: row.name,
- *       email: row.email,
- *       createdAt: new Date(row.created_at)
- *     }
- *   }
- *
- *   protected toRow(entity: User): Record<string, any> {
- *     return {
- *       id: entity.id,
- *       name: entity.name,
- *       email: entity.email,
- *       created_at: entity.createdAt.toISOString()
- *     }
- *   }
- * }
- *
- * // Usage
- * const userRepo = new UserRepository(db)
- * const user = await userRepo.findById(1)
- * const users = await userRepo.findMany({ active: true }, { limit: 10, orderBy: { createdAt: 'DESC' } })
- * ```
- */
-var __rest = (this && this.__rest) || function (s, e) {
-    var t = {};
-    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
-        t[p] = s[p];
-    if (s != null && typeof Object.getOwnPropertySymbols === "function")
-        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
-            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
-                t[p[i]] = s[p[i]];
-        }
-    return t;
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Repository = void 0;
-/**
- * Abstract Repository base class
- *
- * Extend this class to create type-safe repositories for your entities.
- *
- * @typeParam TEntity - The entity type this repository manages
- * @typeParam TId - The type of the primary key (defaults to number)
- */
-class Repository {
-    /**
-     * Creates a new repository instance
-     *
-     * @param db - The database contract/service to use for queries
-     */
-    constructor(db) {
-        this.db = db;
-        /**
-         * The primary key column name (defaults to 'id')
-         */
-        this.primaryKey = 'id';
-    }
-    // ─────────────────────────────────────────────────────────────────────────────
-    // CRUD Operations
-    // ─────────────────────────────────────────────────────────────────────────────
-    /**
-     * Find an entity by its primary key
-     *
-     * @param id - The primary key value
-     * @returns The entity or null if not found
-     *
-     * @example
-     * ```typescript
-     * const user = await userRepo.findById(1)
-     * if (user) {
-     *   console.log(user.name)
-     * }
-     * ```
-     */
-    async findById(id) {
-        const sql = `SELECT * FROM ${this.tableName} WHERE ${this.primaryKey} = ?`;
-        const row = await this.db.single(sql, [id]);
-        return row ? this.toEntity(row) : null;
-    }
-    /**
-     * Find a single entity matching the given conditions
-     *
-     * @param where - Conditions to match (equality only)
-     * @returns The first matching entity or null
-     *
-     * @example
-     * ```typescript
-     * const user = await userRepo.findOne({ email: 'john@example.com' })
-     * ```
-     */
-    async findOne(where) {
-        const { clause, params } = this.buildWhereClause(where);
-        const sql = `SELECT * FROM ${this.tableName}${clause} LIMIT 1`;
-        const row = await this.db.single(sql, params);
-        return row ? this.toEntity(row) : null;
-    }
-    /**
-     * Find multiple entities with optional filtering, pagination, and ordering
-     *
-     * @param where - Optional conditions to filter by
-     * @param options - Query options (select, orderBy, limit, offset)
-     * @returns Result containing data array and optional total count
-     *
-     * @example
-     * ```typescript
-     * // Simple query
-     * const { data: users } = await userRepo.findMany({ active: true })
-     *
-     * // With pagination and ordering
-     * const result = await userRepo.findMany(
-     *   { role: 'admin' },
-     *   { limit: 10, offset: 20, orderBy: { createdAt: 'DESC' } }
-     * )
-     * console.log(`Page of ${result.data.length} admins`)
-     * ```
-     */
-    async findMany(where, options) {
-        const selectClause = this.buildSelectClause(options === null || options === void 0 ? void 0 : options.select);
-        const { clause: whereClause, params } = this.buildWhereClause(where);
-        const orderClause = this.buildOrderClause(options === null || options === void 0 ? void 0 : options.orderBy);
-        const limitClause = this.buildLimitClause(options === null || options === void 0 ? void 0 : options.limit, options === null || options === void 0 ? void 0 : options.offset);
-        const sql = `SELECT ${selectClause} FROM ${this.tableName}${whereClause}${orderClause}${limitClause}`;
-        const rows = await this.db.query(sql, params);
-        const data = rows.map((row) => this.toEntity(row));
-        // If pagination is used, also get total count
-        let total;
-        if ((options === null || options === void 0 ? void 0 : options.limit) !== undefined) {
-            total = await this.count(where);
-        }
-        return { data, total };
-    }
-    /**
-     * Count entities matching the given conditions
-     *
-     * @param where - Optional conditions to filter by
-     * @returns The count of matching entities
-     *
-     * @example
-     * ```typescript
-     * const activeCount = await userRepo.count({ active: true })
-     * ```
-     */
-    async count(where) {
-        const { clause, params } = this.buildWhereClause(where);
-        const sql = `SELECT COUNT(*) as count FROM ${this.tableName}${clause}`;
-        const result = await this.db.scalar(sql, params);
-        return result !== null && result !== void 0 ? result : 0;
-    }
-    /**
-     * Save an entity (insert if new, update if exists)
-     *
-     * If the entity has a primary key value, it will be updated.
-     * Otherwise, a new record will be inserted.
-     *
-     * @param entity - The entity to save
-     * @returns The saved entity with updated ID (for inserts)
-     *
-     * @example
-     * ```typescript
-     * // Insert new user
-     * const newUser = await userRepo.save({ name: 'John', email: 'john@example.com' })
-     * console.log(newUser.id) // Generated ID
-     *
-     * // Update existing user
-     * user.name = 'John Doe'
-     * await userRepo.save(user)
-     * ```
-     */
-    async save(entity) {
-        const row = this.toRow(entity);
-        const id = row[this.primaryKey];
-        if (id !== undefined && id !== null) {
-            // Update existing entity
-            await this.update(id, row);
-            return entity;
-        }
-        else {
-            // Insert new entity
-            const insertedId = await this.insertRow(row);
-            // Return entity with the new ID
-            return this.toEntity(Object.assign(Object.assign({}, row), { [this.primaryKey]: insertedId }));
-        }
-    }
-    /**
-     * Delete an entity by its primary key
-     *
-     * @param id - The primary key of the entity to delete
-     * @returns true if deleted, false if not found
-     *
-     * @example
-     * ```typescript
-     * const deleted = await userRepo.delete(1)
-     * if (deleted) {
-     *   console.log('User deleted')
-     * }
-     * ```
-     */
-    async delete(id) {
-        const sql = `DELETE FROM ${this.tableName} WHERE ${this.primaryKey} = ?`;
-        const result = await this.db.execute(sql, [id]);
-        return result.affectedRows > 0;
-    }
-    /**
-     * Delete entities matching the given conditions
-     *
-     * @param where - Conditions to match for deletion
-     * @returns Number of deleted entities
-     *
-     * @example
-     * ```typescript
-     * const count = await userRepo.deleteWhere({ active: false })
-     * console.log(`Deleted ${count} inactive users`)
-     * ```
-     */
-    async deleteWhere(where) {
-        const { clause, params } = this.buildWhereClause(where);
-        if (!clause) {
-            throw new Error('deleteWhere requires at least one condition to prevent accidental full table deletion');
-        }
-        const sql = `DELETE FROM ${this.tableName}${clause}`;
-        const result = await this.db.execute(sql, params);
-        return result.affectedRows;
-    }
-    // ─────────────────────────────────────────────────────────────────────────────
-    // Protected Helper Methods
-    // ─────────────────────────────────────────────────────────────────────────────
-    /**
-     * Update an entity by ID
-     */
-    async update(id, row) {
-        const _a = row, _b = this.primaryKey, _ = _a[_b], updateData = __rest(_a, [typeof _b === "symbol" ? _b : _b + ""]);
-        const columns = Object.keys(updateData);
-        const setClause = columns.map((col) => `${col} = ?`).join(', ');
-        const values = columns.map((col) => updateData[col]);
-        const sql = `UPDATE ${this.tableName} SET ${setClause} WHERE ${this.primaryKey} = ?`;
-        await this.db.execute(sql, [...values, id]);
-    }
-    /**
-     * Insert a new row and return the inserted ID
-     */
-    async insertRow(row) {
-        const _a = row, _b = this.primaryKey, _ = _a[_b], insertData = __rest(_a, [typeof _b === "symbol" ? _b : _b + ""]);
-        const columns = Object.keys(insertData);
-        const placeholders = columns.map(() => '?').join(', ');
-        const values = columns.map((col) => insertData[col]);
-        const sql = `INSERT INTO ${this.tableName} (${columns.join(', ')}) VALUES (${placeholders})`;
-        const result = await this.db.insert(sql, values);
-        return result.insertId;
-    }
-    /**
-     * Build SELECT clause from field selection
-     */
-    buildSelectClause(select) {
-        if (!select || select.length === 0) {
-            return '*';
-        }
-        return select.map((field) => String(field)).join(', ');
-    }
-    /**
-     * Build WHERE clause from conditions
-     */
-    buildWhereClause(where) {
-        if (!where || Object.keys(where).length === 0) {
-            return { clause: '', params: [] };
-        }
-        const conditions = [];
-        const params = [];
-        for (const [key, value] of Object.entries(where)) {
-            if (value === null) {
-                conditions.push(`${key} IS NULL`);
-            }
-            else if (value === undefined) {
-                continue; // Skip undefined values
-            }
-            else {
-                conditions.push(`${key} = ?`);
-                params.push(value);
-            }
-        }
-        if (conditions.length === 0) {
-            return { clause: '', params: [] };
-        }
-        return {
-            clause: ` WHERE ${conditions.join(' AND ')}`,
-            params,
-        };
-    }
-    /**
-     * Build ORDER BY clause from orderBy options
-     */
-    buildOrderClause(orderBy) {
-        if (!orderBy || Object.keys(orderBy).length === 0) {
-            return '';
-        }
-        const orders = Object.entries(orderBy)
-            .filter(([_, direction]) => direction)
-            .map(([field, direction]) => `${field} ${direction}`);
-        if (orders.length === 0) {
-            return '';
-        }
-        return ` ORDER BY ${orders.join(', ')}`;
-    }
-    /**
-     * Build LIMIT/OFFSET clause
-     */
-    buildLimitClause(limit, offset) {
-        if (limit === undefined) {
-            return '';
-        }
-        let clause = ` LIMIT ${limit}`;
-        if (offset !== undefined && offset > 0) {
-            clause += ` OFFSET ${offset}`;
-        }
-        return clause;
-    }
-}
-exports.Repository = Repository;

package/dist/server/templates/repository/repository.types.d.ts

@@ -1,51 +0,0 @@
-/**
- * Repository Pattern Types
- *
- * Types and interfaces for the generic repository pattern.
- */
-/**
- * Sort direction for orderBy clauses
- */
-export type OrderDirection = 'ASC' | 'DESC';
-/**
- * Options for findMany queries with pagination, ordering, and field selection
- *
- * @example
- * ```typescript
- * const options: FindOptions<User> = {
- *   select: ['id', 'name', 'email'],
- *   orderBy: { createdAt: 'DESC' },
- *   limit: 10,
- *   offset: 0
- * }
- * ```
- */
-export interface FindOptions<TEntity> {
-    /** Fields to select (SELECT clause). If omitted, selects all fields (*) */
-    select?: (keyof TEntity)[];
-    /** Order by fields with direction */
-    orderBy?: Partial<Record<keyof TEntity, OrderDirection>>;
-    /** Maximum number of records to return */
-    limit?: number;
-    /** Number of records to skip (for pagination) */
-    offset?: number;
-}
-/**
- * Result of a findMany query with optional total count for pagination
- *
- * @example
- * ```typescript
- * const result = await userRepo.findMany({}, { limit: 10 })
- * console.log(`Showing ${result.data.length} of ${result.total} users`)
- * ```
- */
-export interface FindManyResult<TEntity> {
-    /** Array of entities matching the query */
-    data: TEntity[];
-    /** Total count of matching records (useful for pagination) */
-    total?: number;
-}
-/**
- * Where clause condition - partial entity for simple equality matching
- */
-export type WhereCondition<TEntity> = Partial<TEntity>;

package/dist/server/templates/repository/repository.types.js

@@ -1,7 +0,0 @@
-"use strict";
-/**
- * Repository Pattern Types
- *
- * Types and interfaces for the generic repository pattern.
- */
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/server/templates/security/permission.types.d.ts

@@ -1,32 +0,0 @@
-/**
- * Represents the security identity of a user/player within the framework.
- * This interface bridges the gap between the Core framework and your specific database implementation.
- */
-export interface Principal {
-    /**
-     * Unique identifier for the user (e.g., database role ID).
-     */
-    id: string;
-    /**
-     * Display name for the role or user, useful for Chat or UI (e.g., "Moderator", "VIP").
-     */
-    name?: string;
-    /**
-     * Numeric weight for hierarchy comparisons.
-     * - Used by the `@Guard({ rank: N })` decorator.
-     * - **Logic:** `UserRank >= RequiredRank`.
-     * - Higher numbers imply higher privileges.
-     */
-    rank?: number;
-    /**
-     * List of specific permission strings assigned to this principal.
-     * - Used by the `@Guard({ permission: 'string' })` decorator.
-     * - Supports the `'*'` wildcard for super-admin access.
-     */
-    permissions: string[];
-    /**
-     * Arbitrary metadata for game-specific logic (e.g., chat colors, badge IDs, staff status).
-     * This prevents the need to modify the Core types for visual extras.
-     */
-    meta?: Record<string, unknown>;
-}

package/dist/server/templates/security/permission.types.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/server/templates/security/principal-provider.contract.d.ts

@@ -1,43 +0,0 @@
-import type { Server } from '../../..';
-import type { LinkedID } from '../../services';
-import type { Principal } from './permission.types';
-/**
- * **Authorization**
- *
- * This abstract class defines how the Security Layer retrieves user permissions.
- * The Framework does not know about your database (SQL, Mongo, JSON or API); it relies on
- * your implementation of this provider to resolve a `Principal`.
- *
- * @example
- * ```ts
- * // In your game resource:
- * class MyAuthProvider implements PrincipalProviderContract { ... }
- * ```
- */
-export declare abstract class PrincipalProviderContract {
-    /**
-     * Retrieves the security principal (Role/Permissions) for a connected player.
-     *
-     * **Performance Note:** This method is called frequently (on every guarded interaction).
-     * It is highly recommended to cache the result in memory (e.g., in `Player.session`).
-     *
-     * @param player - The active Server Player entity.
-     * @returns A Promise resolving to the `Principal` data, or `null` if the player is not authenticated.
-     */
-    abstract getPrincipal(player: Server.Player): Promise<Principal | null>;
-    /**
-     * Forces a refresh of the player's permissions from the persistence layer.
-     * Useful when a player is promoted/demoted while online.
-     *
-     * @param player - The active Server Player entity to refresh.
-     */
-    abstract refreshPrincipal(player: Server.Player): Promise<void>;
-    /**
-     * Retrieves a principal by their Account ID, even if they are offline.
-     * Useful for web panels, discord bots, or offline bans.
-     *
-     * @param linkedID - The unique linked ID (Account ID).
-     * @returns The Principal data or null.
-     */
-    abstract getPrincipalByLinkedID(linkedID: LinkedID): Promise<Principal | null>;
-}

package/dist/server/templates/security/principal-provider.contract.js

@@ -1,19 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PrincipalProviderContract = void 0;
-/**
- * **Authorization**
- *
- * This abstract class defines how the Security Layer retrieves user permissions.
- * The Framework does not know about your database (SQL, Mongo, JSON or API); it relies on
- * your implementation of this provider to resolve a `Principal`.
- *
- * @example
- * ```ts
- * // In your game resource:
- * class MyAuthProvider implements PrincipalProviderContract { ... }
- * ```
- */
-class PrincipalProviderContract {
-}
-exports.PrincipalProviderContract = PrincipalProviderContract;

package/dist/server/templates/security/security-handler.contract.d.ts

@@ -1,5 +0,0 @@
-import type { Server } from '../../..';
-import type { SecurityError } from '../../../utils';
-export declare abstract class SecurityHandlerContract {
-    abstract handleViolation(player: Server.Player, error: SecurityError): Promise<void>;
-}

package/dist/server/templates/security/security-handler.contract.js

@@ -1,6 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SecurityHandlerContract = void 0;
-class SecurityHandlerContract {
-}
-exports.SecurityHandlerContract = SecurityHandlerContract;

package/dist/server/types/core-events.d.ts

@@ -1,22 +0,0 @@
-export interface PlayerSessionCreatedPayload {
-    clientId: number;
-    license: string;
-}
-export interface PlayerSessionDestroyedPayload {
-    clientId: number;
-}
-export interface TransferCompletedPayload {
-    playerId: number;
-    amount: number;
-    targetId: number;
-}
-export interface PlayerFullyConnectedPayload {
-    clientId: number;
-    license: string;
-}
-export type CoreEventMap = {
-    'core:playerSessionCreated': PlayerSessionCreatedPayload;
-    'core:playerSessionDestroyed': PlayerSessionDestroyedPayload;
-    'core:transfer:completed': TransferCompletedPayload;
-    'core:playerFullyConnected': PlayerFullyConnectedPayload;
-};

package/dist/server/types/core-events.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/server/types/security.types.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/shared/index.d.ts

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

package/dist/shared/index.js

@@ -1,17 +0,0 @@
-"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./logger"), exports);

package/dist/shared/logger/core-logger.d.ts

@@ -1,35 +0,0 @@
-import { LoggerService } from './logger.service';
-/**
- * Singleton logger instance for internal OpenCore framework use.
- *
- * This logger is pre-configured for framework-level logging and should only
- * be used by OpenCore internals. Resource developers should inject LoggerService
- * via DI instead.
- *
- * @internal
- */
-export declare const coreLogger: LoggerService;
-export declare const loggers: {
-    /** Bootstrap and initialization logs */
-    bootstrap: import("./logger.service").ChildLogger;
-    /** Metadata scanning and decorator processing */
-    scanner: import("./logger.service").ChildLogger;
-    /** Player session management */
-    session: import("./logger.service").ChildLogger;
-    /** Command registration and execution */
-    command: import("./logger.service").ChildLogger;
-    /** Network events processing */
-    netEvent: import("./logger.service").ChildLogger;
-    /** Security violations and access control */
-    security: import("./logger.service").ChildLogger;
-    /** Core event bus */
-    eventBus: import("./logger.service").ChildLogger;
-    /** Export registration */
-    exports: import("./logger.service").ChildLogger;
-    /** Tick handlers (server) */
-    tick: import("./logger.service").ChildLogger;
-    /** NUI callbacks (client) */
-    nui: import("./logger.service").ChildLogger;
-    /** Spawn service (client) */
-    spawn: import("./logger.service").ChildLogger;
-};

package/dist/shared/logger/core-logger.js

@@ -1,52 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.loggers = exports.coreLogger = void 0;
-const logger_types_1 = require("./logger.types");
-const logger_service_1 = require("./logger.service");
-const console_transport_1 = require("./transports/console.transport");
-/**
- * Singleton logger instance for internal OpenCore framework use.
- *
- * This logger is pre-configured for framework-level logging and should only
- * be used by OpenCore internals. Resource developers should inject LoggerService
- * via DI instead.
- *
- * @internal
- */
-exports.coreLogger = new logger_service_1.LoggerService({
-    minLevel: logger_types_1.LogLevel.DEBUG,
-    defaultDomain: logger_types_1.LogDomain.FRAMEWORK,
-    defaultSource: 'Core',
-    transports: [
-        new console_transport_1.ConsoleTransport({
-            minLevel: logger_types_1.LogLevel.DEBUG,
-            colors: true,
-            timestamps: true,
-        }),
-    ],
-});
-// Pre-configured child loggers for common framework components
-exports.loggers = {
-    /** Bootstrap and initialization logs */
-    bootstrap: exports.coreLogger.framework('Bootstrap'),
-    /** Metadata scanning and decorator processing */
-    scanner: exports.coreLogger.framework('Scanner'),
-    /** Player session management */
-    session: exports.coreLogger.framework('Session'),
-    /** Command registration and execution */
-    command: exports.coreLogger.framework('Command'),
-    /** Network events processing */
-    netEvent: exports.coreLogger.framework('NetEvent'),
-    /** Security violations and access control */
-    security: exports.coreLogger.framework('Security'),
-    /** Core event bus */
-    eventBus: exports.coreLogger.framework('EventBus'),
-    /** Export registration */
-    exports: exports.coreLogger.framework('Exports'),
-    /** Tick handlers (server) */
-    tick: exports.coreLogger.framework('Tick'),
-    /** NUI callbacks (client) */
-    nui: exports.coreLogger.client('NUI'),
-    /** Spawn service (client) */
-    spawn: exports.coreLogger.client('Spawn'),
-};

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

@@ -1,11 +0,0 @@
-export { LogLevel, LogLevelLabels, LogDomain, LogDomainLabels, parseLogLevel } from './logger.types';
-export type { LogContext, LogEntry } from './logger.types';
-export { createLoggerConfig, DEFAULT_LOGGER_CONFIG } from './logger.config';
-export type { LoggerConfig } from './logger.config';
-export { LoggerService, ChildLogger } from './logger.service';
-export { coreLogger, loggers } from './core-logger';
-export type { LogTransport } from './transports/transport.interface';
-export { ConsoleTransport } from './transports/console.transport';
-export type { ConsoleTransportOptions } from './transports/console.transport';
-export { BufferedTransport } from './transports/buffered.transport';
-export type { BufferedTransportOptions, LogOutputFormat } from './transports/buffered.transport';