@nice2dev/game-engine 1.1.5 → 1.1.6

package/dist/types/systems/NiceShop.d.ts

@@ -0,0 +1,528 @@
+/**
+ * NiceShop - In-Game Shop & Store System
+ *
+ * Comprehensive shop system for managing in-game purchases, virtual currencies,
+ * item catalogs, discounts, bundles, and storefront display.
+ *
+ * Features:
+ * - Multiple currency support (soft/hard currencies)
+ * - Item catalog management
+ * - Category and filtering
+ * - Discounts and sales
+ * - Bundle deals
+ * - Purchase history
+ * - Limited time offers
+ * - Daily/weekly rotating items
+ * - Wishlist functionality
+ * - Currency conversion
+ * - Refund system
+ * - Purchase validation
+ *
+ * @packageDocumentation
+ */
+import { EventEmitter } from 'events';
+/** Unique item ID */
+export type ShopItemId = string;
+/** Unique currency ID */
+export type CurrencyId = string;
+/** Unique bundle ID */
+export type BundleId = string;
+/** Unique category ID */
+export type CategoryId = string;
+/** Unique transaction ID */
+export type TransactionId = string;
+/** Unique offer ID */
+export type OfferId = string;
+/** Item rarity */
+export type ItemRarity = 'common' | 'uncommon' | 'rare' | 'epic' | 'legendary' | 'mythic';
+/** Item type */
+export type ItemType = 'consumable' | 'equipment' | 'cosmetic' | 'currency' | 'boost' | 'unlock' | 'subscription';
+/** Purchase state */
+export type PurchaseState = 'pending' | 'processing' | 'completed' | 'failed' | 'refunded' | 'cancelled';
+/** Offer type */
+export type OfferType = 'daily' | 'weekly' | 'seasonal' | 'flash' | 'permanent' | 'first_purchase';
+/** Discount type */
+export type DiscountType = 'percentage' | 'fixed' | 'bundle' | 'loyalty';
+/** Currency definition */
+export interface Currency {
+    id: CurrencyId;
+    name: string;
+    symbol: string;
+    icon?: string;
+    isHardCurrency: boolean;
+    exchangeRate?: number;
+    maxAmount?: number;
+    canBeEarned: boolean;
+    canBePurchased: boolean;
+}
+/** Currency balance */
+export interface CurrencyBalance {
+    currencyId: CurrencyId;
+    amount: number;
+    lifetimeEarned: number;
+    lifetimeSpent: number;
+}
+/** Item price */
+export interface ItemPrice {
+    currencyId: CurrencyId;
+    amount: number;
+    originalAmount?: number;
+}
+/** Shop item definition */
+export interface ShopItem {
+    id: ShopItemId;
+    name: string;
+    description: string;
+    type: ItemType;
+    rarity: ItemRarity;
+    categoryId: CategoryId;
+    prices: ItemPrice[];
+    icon?: string;
+    preview?: string;
+    tags: string[];
+    metadata?: Record<string, unknown>;
+    isNew?: boolean;
+    isFeatured?: boolean;
+    isLimitedTime?: boolean;
+    purchaseLimit?: number;
+    requiredLevel?: number;
+    requiredItems?: ShopItemId[];
+    unlockCondition?: string;
+    expiresAt?: number;
+    availableFrom?: number;
+    quantity?: number;
+}
+/** Category definition */
+export interface ShopCategory {
+    id: CategoryId;
+    name: string;
+    description?: string;
+    icon?: string;
+    parentId?: CategoryId;
+    sortOrder: number;
+    isVisible: boolean;
+}
+/** Bundle definition */
+export interface ShopBundle {
+    id: BundleId;
+    name: string;
+    description: string;
+    items: Array<{
+        itemId: ShopItemId;
+        quantity: number;
+    }>;
+    prices: ItemPrice[];
+    savings: number;
+    icon?: string;
+    preview?: string;
+    isLimitedTime?: boolean;
+    expiresAt?: number;
+    purchaseLimit?: number;
+}
+/** Discount definition */
+export interface Discount {
+    id: string;
+    type: DiscountType;
+    value: number;
+    categoryId?: CategoryId;
+    itemIds?: ShopItemId[];
+    minPurchase?: number;
+    maxDiscount?: number;
+    code?: string;
+    validFrom: number;
+    validUntil: number;
+    usageLimit?: number;
+    usageCount: number;
+    isActive: boolean;
+}
+/** Special offer */
+export interface SpecialOffer {
+    id: OfferId;
+    type: OfferType;
+    title: string;
+    description: string;
+    items: Array<{
+        itemId: ShopItemId;
+        quantity: number;
+        discountPercent: number;
+    }>;
+    bundles?: BundleId[];
+    prices: ItemPrice[];
+    icon?: string;
+    background?: string;
+    validFrom: number;
+    validUntil: number;
+    purchaseLimit: number;
+    purchaseCount: number;
+    priority: number;
+}
+/** Transaction record */
+export interface Transaction {
+    id: TransactionId;
+    itemId?: ShopItemId;
+    bundleId?: BundleId;
+    offerId?: OfferId;
+    quantity: number;
+    prices: ItemPrice[];
+    state: PurchaseState;
+    timestamp: number;
+    completedAt?: number;
+    refundedAt?: number;
+    discountApplied?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Wishlist item */
+export interface WishlistItem {
+    itemId: ShopItemId;
+    addedAt: number;
+    notifyOnSale: boolean;
+    targetPrice?: ItemPrice;
+}
+/** Shop statistics */
+export interface ShopStatistics {
+    totalPurchases: number;
+    totalSpent: Record<CurrencyId, number>;
+    itemsPurchased: Record<ShopItemId, number>;
+    favoriteCategory?: CategoryId;
+    averagePurchaseValue: number;
+    lastPurchaseDate?: number;
+    loyaltyPoints: number;
+}
+/** Filter options */
+export interface ShopFilter {
+    categoryId?: CategoryId;
+    types?: ItemType[];
+    rarities?: ItemRarity[];
+    minPrice?: number;
+    maxPrice?: number;
+    currencyId?: CurrencyId;
+    tags?: string[];
+    showOwned?: boolean;
+    showAffordable?: boolean;
+    showNew?: boolean;
+    showFeatured?: boolean;
+    showLimitedTime?: boolean;
+    searchQuery?: string;
+}
+/** Sort options */
+export interface ShopSort {
+    field: 'name' | 'price' | 'rarity' | 'date' | 'popularity';
+    direction: 'asc' | 'desc';
+}
+/** Purchase request */
+export interface PurchaseRequest {
+    itemId?: ShopItemId;
+    bundleId?: BundleId;
+    offerId?: OfferId;
+    quantity: number;
+    currencyId: CurrencyId;
+    discountCode?: string;
+}
+/** Purchase result */
+export interface PurchaseResult {
+    success: boolean;
+    transactionId?: TransactionId;
+    error?: string;
+    itemsReceived?: Array<{
+        itemId: ShopItemId;
+        quantity: number;
+    }>;
+    currencySpent?: ItemPrice;
+    newBalance?: number;
+}
+/** Shop event types */
+export type ShopEventType = 'purchase_started' | 'purchase_completed' | 'purchase_failed' | 'purchase_refunded' | 'currency_changed' | 'item_added' | 'item_removed' | 'item_updated' | 'offer_started' | 'offer_ended' | 'discount_applied' | 'discount_removed' | 'wishlist_added' | 'wishlist_removed' | 'catalog_refreshed';
+/** Shop event data */
+export interface ShopEvent {
+    type: ShopEventType;
+    timestamp: number;
+    itemId?: ShopItemId;
+    bundleId?: BundleId;
+    offerId?: OfferId;
+    transactionId?: TransactionId;
+    currencyId?: CurrencyId;
+    amount?: number;
+    oldBalance?: number;
+    newBalance?: number;
+    error?: string;
+}
+/** Shop event callback */
+export type ShopEventCallback = (event: ShopEvent) => void;
+/** Shop system configuration */
+export interface ShopConfig {
+    currencies: Currency[];
+    defaultCurrencyId: CurrencyId;
+    maxTransactionHistory: number;
+    maxWishlistSize: number;
+    enableRefunds: boolean;
+    refundWindowMs: number;
+    enableDiscountCodes: boolean;
+    loyaltyPointsPerPurchase: number;
+    loyaltyPointsConversionRate: number;
+    autoRefreshCatalogMs?: number;
+    validatePurchases: boolean;
+    purchaseCooldownMs: number;
+}
+/** Default configuration */
+export declare const DEFAULT_SHOP_CONFIG: ShopConfig;
+/**
+ * In-game shop and store system
+ */
+export declare class NiceShop extends EventEmitter {
+    private config;
+    private items;
+    private categories;
+    private bundles;
+    private offers;
+    private discounts;
+    private balances;
+    private transactions;
+    private wishlist;
+    private ownedItems;
+    private statistics;
+    private refreshInterval?;
+    private lastPurchaseTime;
+    constructor(config?: Partial<ShopConfig>);
+    /**
+     * Initialize currency balances
+     */
+    private initializeCurrencies;
+    /**
+     * Start auto-refresh interval
+     */
+    private startAutoRefresh;
+    /**
+     * Emit shop event
+     */
+    private emitEvent;
+    /**
+     * Get currency balance
+     */
+    getBalance(currencyId: CurrencyId): number;
+    /**
+     * Get all balances
+     */
+    getAllBalances(): CurrencyBalance[];
+    /**
+     * Add currency
+     */
+    addCurrency(currencyId: CurrencyId, amount: number, _source?: string): boolean;
+    /**
+     * Remove currency
+     */
+    removeCurrency(currencyId: CurrencyId, amount: number): boolean;
+    /**
+     * Set currency balance
+     */
+    setCurrency(currencyId: CurrencyId, amount: number): void;
+    /**
+     * Convert currency
+     */
+    convertCurrency(fromCurrencyId: CurrencyId, toCurrencyId: CurrencyId, amount: number): boolean;
+    /**
+     * Register shop item
+     */
+    registerItem(item: ShopItem): void;
+    /**
+     * Register multiple items
+     */
+    registerItems(items: ShopItem[]): void;
+    /**
+     * Remove item from catalog
+     */
+    removeItem(itemId: ShopItemId): boolean;
+    /**
+     * Update item
+     */
+    updateItem(itemId: ShopItemId, updates: Partial<ShopItem>): boolean;
+    /**
+     * Get item by ID
+     */
+    getItem(itemId: ShopItemId): ShopItem | undefined;
+    /**
+     * Get all items
+     */
+    getAllItems(): ShopItem[];
+    /**
+     * Get items by category
+     */
+    getItemsByCategory(categoryId: CategoryId): ShopItem[];
+    /**
+     * Filter items
+     */
+    filterItems(filter: ShopFilter, sort?: ShopSort): ShopItem[];
+    /**
+     * Register category
+     */
+    registerCategory(category: ShopCategory): void;
+    /**
+     * Get category
+     */
+    getCategory(categoryId: CategoryId): ShopCategory | undefined;
+    /**
+     * Get all categories
+     */
+    getAllCategories(): ShopCategory[];
+    /**
+     * Get subcategories
+     */
+    getSubcategories(parentId: CategoryId): ShopCategory[];
+    /**
+     * Register bundle
+     */
+    registerBundle(bundle: ShopBundle): void;
+    /**
+     * Get bundle
+     */
+    getBundle(bundleId: BundleId): ShopBundle | undefined;
+    /**
+     * Get all bundles
+     */
+    getAllBundles(): ShopBundle[];
+    /**
+     * Calculate bundle value
+     */
+    calculateBundleValue(bundleId: BundleId, currencyId: CurrencyId): number;
+    /**
+     * Register special offer
+     */
+    registerOffer(offer: SpecialOffer): void;
+    /**
+     * Get active offers
+     */
+    getActiveOffers(): SpecialOffer[];
+    /**
+     * Get offers by type
+     */
+    getOffersByType(type: OfferType): SpecialOffer[];
+    /**
+     * Check expired offers
+     */
+    checkExpiredOffers(): void;
+    /**
+     * Register discount
+     */
+    registerDiscount(discount: Discount): void;
+    /**
+     * Apply discount code
+     */
+    applyDiscountCode(code: string): Discount | undefined;
+    /**
+     * Calculate discounted price
+     */
+    calculateDiscountedPrice(price: number, discount: Discount): number;
+    /**
+     * Get applicable discounts for item
+     */
+    getApplicableDiscounts(itemId: ShopItemId): Discount[];
+    /**
+     * Check if player can afford item
+     */
+    canAfford(itemId: ShopItemId, currencyId?: CurrencyId): boolean;
+    /**
+     * Check if item can be purchased
+     */
+    canPurchase(itemId: ShopItemId): {
+        canPurchase: boolean;
+        reason?: string;
+    };
+    /**
+     * Purchase item
+     */
+    purchaseItem(request: PurchaseRequest): Promise<PurchaseResult>;
+    /**
+     * Refund transaction
+     */
+    refundTransaction(transactionId: TransactionId): boolean;
+    /**
+     * Add to wishlist
+     */
+    addToWishlist(itemId: ShopItemId, notifyOnSale?: boolean, targetPrice?: ItemPrice): boolean;
+    /**
+     * Remove from wishlist
+     */
+    removeFromWishlist(itemId: ShopItemId): boolean;
+    /**
+     * Get wishlist
+     */
+    getWishlist(): WishlistItem[];
+    /**
+     * Check if item is in wishlist
+     */
+    isInWishlist(itemId: ShopItemId): boolean;
+    /**
+     * Get transaction history
+     */
+    getTransactionHistory(limit?: number): Transaction[];
+    /**
+     * Get transaction by ID
+     */
+    getTransaction(transactionId: TransactionId): Transaction | undefined;
+    /**
+     * Get transactions by state
+     */
+    getTransactionsByState(state: PurchaseState): Transaction[];
+    /**
+     * Check if item is owned
+     */
+    isOwned(itemId: ShopItemId): boolean;
+    /**
+     * Get owned quantity
+     */
+    getOwnedQuantity(itemId: ShopItemId): number;
+    /**
+     * Get all owned items
+     */
+    getAllOwnedItems(): Map<ShopItemId, number>;
+    /**
+     * Set owned items (for loading save data)
+     */
+    setOwnedItems(items: Map<ShopItemId, number>): void;
+    /**
+     * Get shop statistics
+     */
+    getStatistics(): ShopStatistics;
+    /**
+     * Get most popular items
+     */
+    getMostPopularItems(limit?: number): ShopItem[];
+    /**
+     * Get featured items
+     */
+    getFeaturedItems(): ShopItem[];
+    /**
+     * Get new items
+     */
+    getNewItems(): ShopItem[];
+    /**
+     * Get limited time items
+     */
+    getLimitedTimeItems(): ShopItem[];
+    /**
+     * Refresh catalog (check expiration, update availability)
+     */
+    refreshCatalog(): void;
+    /**
+     * Export shop state
+     */
+    exportState(): object;
+    /**
+     * Import shop state
+     */
+    importState(state: {
+        balances?: [CurrencyId, CurrencyBalance][];
+        ownedItems?: [ShopItemId, number][];
+        wishlist?: [ShopItemId, WishlistItem][];
+        transactions?: Transaction[];
+        statistics?: ShopStatistics;
+    }): void;
+    /**
+     * Destroy shop system
+     */
+    destroy(): void;
+}
+/**
+ * Create shop system instance
+ */
+export declare function createShopSystem(config?: Partial<ShopConfig>): NiceShop;
+export default NiceShop;

package/dist/types/systems/NiceSignal.d.ts

@@ -0,0 +1,112 @@
+export type SignalListener<T> = (value: T, previous: T) => void;
+export type Unsubscribe = () => void;
+export type Cleanup = () => void;
+export type EffectFn = () => void | Cleanup;
+export interface ReadableSignal<T> {
+    get(): T;
+    subscribe(listener: SignalListener<T>): Unsubscribe;
+}
+export interface WritableSignal<T> extends ReadableSignal<T> {
+    set(value: T): void;
+    update(updater: (current: T) => T): void;
+}
+export declare class Signal<T> implements WritableSignal<T> {
+    private value;
+    private listeners;
+    private dependents;
+    private name?;
+    constructor(initialValue: T, name?: string);
+    get(): T;
+    set(newValue: T): void;
+    update(updater: (current: T) => T): void;
+    peek(): T;
+    subscribe(listener: SignalListener<T>): Unsubscribe;
+    addDependent(effect: EffectInstance): void;
+    removeDependent(effect: EffectInstance): void;
+    private notify;
+    getName(): string | undefined;
+}
+export declare class ComputedSignal<T> implements ReadableSignal<T> {
+    private computation;
+    private cachedValue;
+    private dirty;
+    private listeners;
+    private dependencies;
+    private effect;
+    constructor(computation: () => T);
+    get(): T;
+    subscribe(listener: SignalListener<T>): Unsubscribe;
+    dispose(): void;
+}
+declare class EffectInstance {
+    fn: EffectFn;
+    dependencies: Set<Signal<unknown>>;
+    cleanup: Cleanup | null;
+    disposed: boolean;
+    constructor(fn: EffectFn);
+    run(): void;
+    dispose(): void;
+}
+export declare function batch(fn: () => void): void;
+export declare function signal<T>(initialValue: T, name?: string): Signal<T>;
+export declare function computed<T>(computation: () => T): ComputedSignal<T>;
+export declare function effect(fn: EffectFn): () => void;
+export declare function derived<T, U>(source: ReadableSignal<T>, derivation: (value: T) => U): ComputedSignal<U>;
+export declare function combine<T extends ReadableSignal<unknown>[]>(...signals: T): ComputedSignal<{
+    [K in keyof T]: T[K] extends ReadableSignal<infer U> ? U : never;
+}>;
+export declare function when<T>(source: ReadableSignal<T>, predicate: (value: T) => boolean): Promise<T>;
+export interface SignalStore<T extends Record<string, unknown>> {
+    get<K extends keyof T>(key: K): T[K];
+    set<K extends keyof T>(key: K, value: T[K]): void;
+    update<K extends keyof T>(key: K, updater: (current: T[K]) => T[K]): void;
+    subscribe<K extends keyof T>(key: K, listener: SignalListener<T[K]>): Unsubscribe;
+    getSignal<K extends keyof T>(key: K): Signal<T[K]>;
+}
+export declare function createStore<T extends Record<string, unknown>>(initialState: T): SignalStore<T>;
+export declare class SignalArray<T> {
+    private items;
+    private lengthSignal;
+    constructor(initial?: T[]);
+    get(): T[];
+    at(index: number): T | undefined;
+    length(): number;
+    push(...items: T[]): number;
+    pop(): T | undefined;
+    shift(): T | undefined;
+    unshift(...items: T[]): number;
+    set(index: number, value: T): void;
+    remove(predicate: (item: T) => boolean): T[];
+    clear(): void;
+    subscribe(listener: SignalListener<T[]>): Unsubscribe;
+}
+export declare function signalArray<T>(initial?: T[]): SignalArray<T>;
+export declare class SignalMap<K, V> {
+    private mapSignal;
+    private sizeSignal;
+    constructor(initial?: Iterable<[K, V]>);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    delete(key: K): boolean;
+    has(key: K): boolean;
+    clear(): void;
+    size(): number;
+    entries(): IterableIterator<[K, V]>;
+    keys(): IterableIterator<K>;
+    values(): IterableIterator<V>;
+    subscribe(listener: SignalListener<Map<K, V>>): Unsubscribe;
+}
+export declare function signalMap<K, V>(initial?: Iterable<[K, V]>): SignalMap<K, V>;
+declare const _default: {
+    signal: typeof signal;
+    computed: typeof computed;
+    effect: typeof effect;
+    batch: typeof batch;
+    derived: typeof derived;
+    combine: typeof combine;
+    when: typeof when;
+    createStore: typeof createStore;
+    signalArray: typeof signalArray;
+    signalMap: typeof signalMap;
+};
+export default _default;