@quantabit/level-sdk

QuantaBit Level System SDK - User levels, experience points, and privilege management

📦 Installation

npm install @quantabit/level-sdk
# or
yarn add @quantabit/level-sdk

🚀 Quick Start

1. Setup Provider

import { LevelProvider } from "@quantabit/level-sdk";
import "@quantabit/level-sdk/styles.css";

function App() {
  return (
    <LevelProvider
      apiUrl="https://api.example.com/v1"
      token="your-auth-token"
      language="en"
      onLevelUp={(level) => console.log("Leveled up to:", level)}
    >
      <YourComponent />
    </LevelProvider>
  );
}

2. Using Components

import {
  LevelBadge,
  LevelProgress,
  LevelCard,
  Leaderboard,
  PrivilegeList
} from '@quantabit/level-sdk';

// Level badge
<LevelBadge level={5} size="medium" showLabel />

// Level progress bar
<LevelProgress showExp showNextLevel animated />

// Level info card
<LevelCard showPrivileges showProgress />

// Leaderboard
<Leaderboard type="exp" limit={20} showCurrentUser />

// Privilege list
<PrivilegeList showUnlocked showLocked grouped />

3. Using Hooks

import { useLevel, useExpHistory, useLeaderboard } from "@quantabit/level-sdk";

function MyComponent() {
  const {
    userLevel, // User level info
    privileges, // Privilege list
    loading,
    loadUserLevel, // Load user level
    addExp, // Add experience
  } = useLevel();

  // Experience history
  const { history, loadHistory } = useExpHistory();

  // Leaderboard
  const { leaderboard, myRank, loadLeaderboard } = useLeaderboard("exp");

  return <div>...</div>;
}

📚 Components

| Component | Description | | --------------- | ---------------------------------------------------------- | | LevelBadge | Level badge showing level icon and name | | LevelProgress | Level progress bar showing current XP and upgrade progress | | LevelCard | Level info card showing level, progress, privileges | | Leaderboard | Level/experience leaderboard | | PrivilegeList | Level privileges list |

🪝 Hooks

| Hook | Description | | ---------------- | ----------------------------- | | useLevel | Get Level Context | | useExpHistory | Experience history management | | useLeaderboard | Leaderboard data management |

⚙️ LevelProvider Configuration

| Prop | Type | Required | Description | | ----------- | ----------------- | -------- | ------------------------------ | | apiUrl | string | Yes | API base URL | | token | string | No | Auth Token | | language | 'zh' \| 'en' | No | Language setting, default zh | | onLevelUp | (level) => void | No | Level up callback | | onError | (error) => void | No | Error callback |

📖 API Types

// Level info
interface UserLevel {
  level: number;
  level_name: string;
  current_exp: number;
  next_level_exp: number;
  total_exp: number;
  progress: number;
  icon?: string;
  badge_url?: string;
}

// Privilege type
interface Privilege {
  id: string;
  type: "discount" | "feature" | "badge" | "limit" | "priority" | "gift";
  name: string;
  description: string;
  required_level: number;
  is_unlocked: boolean;
  icon?: string;
}

// Experience sources
type ExpSource =
  | "daily_login" // Daily login
  | "task_complete" // Task completion
  | "content_create" // Content creation
  | "interaction" // Interaction
  | "purchase" // Purchase
  | "referral" // Referral
  | "achievement" // Achievement
  | "admin_grant"; // Admin grant

🎨 Custom Styling

Use CSS variables for custom theming:

:root {
  --level-primary: #10b981;
  --level-gold: #fbbf24;
  --level-silver: #9ca3af;
  --level-bronze: #d97706;
}

📄 License

MIT License

🌐 Brand & Links

• Official Mainnet: QuantaBit Chain
• Developer Platform: Developer Platform
• Open Platform: Open Platform
• Payment Platform: Pay Platform
• Feedback: Feedback