@quantabit/level-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QuantaBit Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# @quantabit/level-sdk
+
+> QuantaBit Level System SDK - User levels, experience points, and privilege management
+
+## 📦 Installation
+
+```bash
+npm install @quantabit/level-sdk
+# or
+yarn add @quantabit/level-sdk
+```
+
+## 🚀 Quick Start
+
+### 1. Setup Provider
+
+```jsx
+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
+
+```jsx
+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
+
+```jsx
+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
+
+```typescript
+// 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:
+
+```css
+:root {
+  --level-primary: #10b981;
+  --level-gold: #fbbf24;
+  --level-silver: #9ca3af;
+  --level-bronze: #d97706;
+}
+```
+
+## 📄 License
+
+MIT License
+
+
+
+---
+
+## 🌐 Brand & Links
+- Official Mainnet: [QuantaBit Chain](https://qbitchain.io/)
+- Developer Platform: [Developer Platform](https://developer.quantabit.io/)
+- Open Platform: [Open Platform](https://open.quantabit.io/)
+- Payment Platform: [Pay Platform](https://pay.qbitwallet.io/)
+- Feedback: [Feedback](https://xwin.live/qbit)