questro/dist/points/index.d.mts

A lightweight, modular gamification library for React with unique visual components. Features combo meters, daily challenges, achievement toasts, and progress rings. Add points, badges, quests, leaderboards, levels/XP, streaks, and notifications with zero

import { b as Entity, a as EntityId, E as EventEmitter, S as StorageAdapter } from '../types-B4P_iNGe.mjs';
import * as react_jsx_runtime from 'react/jsx-runtime';
import { ReactNode, HTMLAttributes } from 'react';

interface PointReason {
    action: string;
    description?: string;
    metadata?: Record<string, unknown>;
}
interface PointTransaction extends Entity {
    userId: EntityId;
    amount: number;
    reason: PointReason;
    balance: number;
}
interface PointsState {
    userId: EntityId;
    balance: number;
    transactions: PointTransaction[];
    lifetime: number;
}
interface PointsConfig {
    userId: EntityId;
    initialBalance?: number;
    minBalance?: number;
    maxBalance?: number;
    onBalanceChange?: (balance: number) => void;
}
type PointsEvents = {
    pointsAdded: {
        amount: number;
        reason: PointReason;
        newBalance: number;
    };
    pointsSubtracted: {
        amount: number;
        reason: PointReason;
        newBalance: number;
    };
    balanceChanged: {
        oldBalance: number;
        newBalance: number;
    };
    transactionAdded: PointTransaction;
    [key: string]: unknown;
};
interface PointsService {
    getBalance(): number;
    getLifetimePoints(): number;
    getTransactions(): readonly PointTransaction[];
    addPoints(amount: number, reason: PointReason): PointTransaction;
    subtractPoints(amount: number, reason: PointReason): PointTransaction;
    setBalance(balance: number, reason: PointReason): PointTransaction;
    reset(): void;
    events: EventEmitter<PointsEvents>;
}

declare class PointsServiceImpl implements PointsService {
    private state;
    private config;
    readonly events: EventEmitter<PointsEvents>;
    constructor(config: PointsConfig);
    getBalance(): number;
    getLifetimePoints(): number;
    getTransactions(): readonly PointTransaction[];
    addPoints(amount: number, reason: PointReason): PointTransaction;
    subtractPoints(amount: number, reason: PointReason): PointTransaction;
    setBalance(balance: number, reason: PointReason): PointTransaction;
    reset(): void;
    private createTransaction;
    private emitBalanceChange;
    toJSON(): PointsState;
    static fromJSON(config: PointsConfig, state: PointsState): PointsServiceImpl;
}

interface PointsProviderProps {
    children: ReactNode;
    config: PointsConfig;
    storage?: StorageAdapter<PointsState>;
    storageKey?: string;
}
declare function PointsProvider({ children, config, storage, storageKey, }: PointsProviderProps): react_jsx_runtime.JSX.Element | null;
declare function usePointsContext(): PointsService;

interface UsePointsReturn {
    balance: number;
    lifetime: number;
    transactions: readonly PointTransaction[];
    addPoints: (amount: number, reason: PointReason) => PointTransaction;
    subtractPoints: (amount: number, reason: PointReason) => PointTransaction;
    setBalance: (balance: number, reason: PointReason) => PointTransaction;
    reset: () => void;
}
declare function usePoints(): UsePointsReturn;

interface PointsDisplayProps extends HTMLAttributes<HTMLDivElement> {
    children?: ReactNode;
    format?: (balance: number) => string;
}
declare function PointsDisplay({ children, format, ...props }: PointsDisplayProps): react_jsx_runtime.JSX.Element;
interface LifetimePointsDisplayProps extends HTMLAttributes<HTMLDivElement> {
    children?: ReactNode;
    format?: (lifetime: number) => string;
}
declare function LifetimePointsDisplay({ children, format, ...props }: LifetimePointsDisplayProps): react_jsx_runtime.JSX.Element;
interface PointsAnimationProps {
    children: (balance: number, isIncreasing: boolean) => ReactNode;
}
declare function PointsAnimation({ children }: PointsAnimationProps): react_jsx_runtime.JSX.Element;

export { LifetimePointsDisplay, type PointReason, type PointTransaction, PointsAnimation, type PointsConfig, PointsDisplay, type PointsEvents, PointsProvider, type PointsService, PointsServiceImpl, type PointsState, usePoints, usePointsContext };