tek-wallet

v0.0.823

Published

a day ago

A custom React provider with TypeScript support

0High
0Medium
0Low

TekWallet Documentation

📋 Mục lục

⚙️ Cấu hình

1. Provider Setup

Để sử dụng TekWallet, bạn cần wrap ứng dụng của mình trong TekWalletProvider. Provider này yêu cầu một số cấu hình cơ bản:

import "swiper/css";
import { TekWalletProvider, ThemeModes } from "tek-wallet";

// Cấu hình cơ bản
<TekWalletProvider
  isSSO
  accessToken={accessToken} // Token từ SSO
>
  <YourApp />
</TekWalletProvider>;

Cấu hình nâng cao:

import { TekWalletProvider, ThemeModes } from "tek-wallet";

<TekWalletProvider
  theme={theme} // Custom theme object
  themeMode={ThemeModes.DARK} // Chế độ theme: DARK hoặc LIGHT
  isSSO
  accessToken={accessToken}
  options={{
    useDefaultToastMessage: true, // Sử dụng toast message mặc định
    hideDefaultActivities: true, // Ẩn activities mặc định
    hideActivitySectionInAssetView: true, // Ẩn section activities trong AssetView
    useBasicAmountGroupInAssetView: true, // Sử dụng basic amount group trong AssetView
    hideBackButtons: {
      // Ẩn nút back trong các view cụ thể
      activity: true,
    },
    disableRefetchOnFocus: true, // Vô hiệu hóa việc refetch dữ liệu khi focus lại vào cửa sổ
  }}
  topOffset={viewportStatusBarHeight || 0} // Offset từ top (thường dùng cho mobile)
  onLogout={handleLogout} // Callback khi logout
  overrideQRScanMethod={isMobileApp ? scanQRCode : undefined} // Override QR scan method
>
  {children}
</TekWalletProvider>;

2. TekWalletProvider Props

Props cơ bản:

| Prop | Type | Required | Mô tả | | ------------- | --------- | -------- | ----------------------------- | | isSSO | boolean | ✅ | Bật chế độ SSO authentication | | accessToken | string | ✅ | Token xác thực từ SSO |

Props nâng cao:

| Prop | Type | Required | Mô tả | | ---------------------- | ------------ | -------- | ---------------------------------------------------- | | theme | object | ❌ | Custom theme object | | themeMode | ThemeModes | ❌ | Chế độ theme: DARK hoặc LIGHT | | topOffset | number | ❌ | Offset từ top (thường dùng cho mobile status bar) | | onLogout | function | ❌ | Callback function khi user logout | | overrideQRScanMethod | function | ❌ | Override QR scan method (thường dùng cho mobile app) |

Options object:

| Option | Type | Default | Mô tả | | -------------------------------- | --------- | ------- | --------------------------------------------------------- | | useDefaultToastMessage | boolean | false | Sử dụng toast message mặc định của hệ thống | | hideDefaultActivities | boolean | false | Ẩn activities mặc định | | hideActivitySectionInAssetView | boolean | false | Ẩn section activities trong AssetView | | useBasicAmountGroupInAssetView | boolean | false | Sử dụng basic amount group trong AssetView | | hideBackButtons | object | {} | Ẩn nút back trong các view cụ thể | | disableRefetchOnFocus | boolean | false | Vô hiệu hóa việc refetch dữ liệu khi focus lại vào cửa sổ |

hideBackButtons object:

| Property | Type | Mô tả | | ---------- | --------- | ------------------------------- | | activity | boolean | Ẩn nút back trong activity view |

3. Environment Variables

Các biến môi trường cần thiết:

NEXT_PUBLIC_TEK_WALLET_APP_SLUG=your_app_slug
NEXT_PUBLIC_TEK_WALLET_SERVER_URL=your_server_url
NEXT_PUBLIC_TEK_WALLET_ABLY_API_KEY=your_ably_api_key

🧩 Components

RequiredConnect

Component này được sử dụng để kiểm tra trạng thái kết nối ví trước khi thực hiện các hành động yêu cầu ví phải được kết nối.

import { RequiredConnect, useWallet } from "tek-wallet";

const { tokens } = useWallet();

<RequiredConnect>
  <Button.Primary onClick={() => console.log(tokens)}>Log balances</Button.Primary>
</RequiredConnect>;

Các Components Chính

| Component | Mô tả | | --------------------- | ------------------------------------------ | | LockToken | Cho phép người dùng khóa token trong ví | | SwapToken | Hỗ trợ chức năng hoán đổi token | | UpdateLockedToken | Cho phép cập nhật thông tin token đã khóa | | ReceiveFunction | Xử lý chức năng nhận token | | ReceiveDirectly | Component nhận token trực tiếp qua QR code | | AssetView | Hiển thị tài sản trong ví | | WithdrawFunction | Xử lý chức năng rút token |

Components Xác nhận (Confirm)

| Component | Mô tả | | ----------------------- | ---------------------------------------------------------------- | | ConfirmSwapToken | Xử lý chức năng swap token bản đơn giản (khả năng custom cao) | | ConfirmSendExternal | Xử lý chức năng rút token bản đơn giản (khả năng custom cao) | | ConfirmSendInternal | Xử lý chức năng chuyển nội bộ bản đơn giản (khả năng custom cao) |

Components View Đầy đủ

| Component | Mô tả | | -------------------- | ---------------------------------------------------------------------- | | SwapView | Xử lý chức năng swap token bản đầy đủ, có validate, input amount... | | SendExternalView | Xử lý chức năng rút token bản đầy đủ, có validate, input amount... | | SendInternalView | Xử lý chức năng chuyển nội bộ bản đầy đủ, có validate, input amount... | | AssetView | Quản lí asset người dùng |

TekWalletView

Component như một app wallet mini (có router nội bộ)

Sử dụng cơ bản:

// page: "tek-wallet/[[...pathname]]/page.tsx"
"use client";

import { TekWalletView } from "tek-wallet";

function WalletPage() {
  return <TekWalletView />;
}

export default WalletPage;

Với basePath:

Nếu phía trước có path: <path>/tek-wallet/[[...pathname]]/page.tsx thì thêm basePath vào options:

<TekWalletProvider
  isSSO
  accessToken={accessToken}
  options={{
    useDefaultToastMessage: true,
    basePath: <path>
  }}
>
  {props.children}
</TekWalletProvider>

Ví dụ cấu hình đầy đủ cho mobile app:

import { TekWalletProvider, ThemeModes } from "tek-wallet";

function App() {
  const handleLogout = () => {
    // Xử lý logout logic
    console.log("User logged out");
  };

  const scanQRCode = (callback) => {
    // Custom QR scan implementation cho mobile
    // Gọi native QR scanner
    window.nativeQRScanner?.scan(callback);
  };

  return (
    <TekWalletProvider
      theme={customTheme}
      themeMode={ThemeModes.DARK}
      isSSO
      accessToken={accessToken}
      options={{
        useDefaultToastMessage: true,
        hideDefaultActivities: true,
        hideActivitySectionInAssetView: true,
        useBasicAmountGroupInAssetView: true,
        hideBackButtons: {
          activity: true,
        },
      }}
      topOffset={viewportStatusBarHeight || 0}
      onLogout={handleLogout}
      overrideQRScanMethod={isMobileApp ? scanQRCode : undefined}
    >
      <YourApp />
    </TekWalletProvider>
  );
}

ReceiveDirectly

Component cho phép hiển thị QR code và địa chỉ nhận token trực tiếp, hỗ trợ cả nhận nội bộ và nhận từ blockchain.

Props:

| Prop | Type | Required | Mô tả | | ------------- | ----------------------- | -------- | ------------------------------------------------------------ | | tokenSlug | string | ✅ | Slug của token muốn nhận | | method | ReceiveDirectlyMethod | ✅ | Phương thức nhận: RECEIVE_INTERNAL hoặc RECEIVE_EXTERNAL | | networkSlug | string | ❌ | Slug của network (bỏ qua nếu muốn cho user chọn network) | | amount | string \| number | ❌ | Số lượng token muốn nhận (hiển thị trong QR code) | | userInfo | object | ❌ | Thông tin người nhận để hiển thị |

Ref Methods:

| Method | Mô tả | | ------- | ---------- | | open | Mở modal | | close | Đóng modal |

Enum ReceiveDirectlyMethod:

enum ReceiveDirectlyMethod {
  RECEIVE_INTERNAL = "Internal Transfer", // Nhận token nội bộ
  RECEIVE_EXTERNAL = "Blockchain Deposit", // Nhận token từ blockchain
}

Ví dụ 1: Nhận token nội bộ (Internal Transfer)

import { ReceiveDirectly, ReceiveDirectlyMethod } from "tek-wallet";
import { useRef } from "react";

function MyComponent() {
  const receiveRef = useRef(null);

  return (
    <>
      <Button onClick={() => receiveRef.current?.open()}>Nhận USDT nội bộ</Button>

      <ReceiveDirectly
        ref={receiveRef}
        tokenSlug="usdt"
        method={ReceiveDirectlyMethod.RECEIVE_INTERNAL}
        amount={100}
        userInfo={{
          nickname: "John Doe",
          username: "@johndoe",
          avatar: "https://example.com/avatar.jpg",
        }}
      />
    </>
  );
}

Ví dụ 2: Nhận token từ blockchain (Blockchain Deposit)

import { ReceiveDirectly, ReceiveDirectlyMethod } from "tek-wallet";
import { useRef } from "react";

function MyComponent() {
  const receiveRef = useRef(null);

  return (
    <>
      <Button onClick={() => receiveRef.current?.open()}>Nhận USDT từ blockchain</Button>

      {/* Cách 1: Chỉ định network cụ thể */}
      <ReceiveDirectly
        ref={receiveRef}
        tokenSlug="usdt"
        method={ReceiveDirectlyMethod.RECEIVE_EXTERNAL}
        networkSlug="trc20"
      />

      {/* Cách 2: Cho phép user chọn network */}
      <ReceiveDirectly
        ref={receiveRef}
        tokenSlug="usdt"
        method={ReceiveDirectlyMethod.RECEIVE_EXTERNAL}
        // Không truyền networkSlug - user sẽ chọn network
      />
    </>
  );
}

Ví dụ 3: Sử dụng với trigger children

<ReceiveDirectly tokenSlug="usdt" method={ReceiveDirectlyMethod.RECEIVE_INTERNAL}>
  <Button>Click để nhận USDT</Button>
</ReceiveDirectly>

Lưu ý:

🔸 Khi sử dụng RECEIVE_INTERNAL, không cần truyền networkSlug
🔸 Khi sử dụng RECEIVE_EXTERNAL mà không truyền networkSlug, user sẽ được yêu cầu chọn network
🔸 Component tự động validate token và network, hiển thị lỗi nếu không hợp lệ
🔸 QR code được tạo tự động dựa trên method và các thông tin được truyền vào
🔸 Với Internal Transfer, QR code chứa thông tin JSON để xử lý chuyển khoản nội bộ
🔸 Với Blockchain Deposit, QR code chứa địa chỉ blockchain wallet

📊 States

Wallet States

| State | Type | Description | | ------------------- | ---------- | ------------------------------------- | | tokens | Token[] | Danh sách tokens trong ví | | isTokensLoading | boolean | Trạng thái đang tải danh sách tokens | | masterWallet | string | Địa chỉ ví hệ thống | | blockchainWallets | string[] | Mảng địa chỉ ví blockchain | | isConnected | boolean | Trạng thái đã kết nối Ably (realtime) |

Operation States

| State | Type | Description | | ------------------------------- | --------- | -------------------------------------------------------------- | | isLoadingWithdrawToken | boolean | Trạng thái đang get list các token được phép withdraw | | isLoadingSendInternalToken | boolean | Trạng thái đang get list các token được phép gửi nội bộ | | isLoadingLockToken | boolean | Trạng thái đang get list các token được phép khóa | | isLoadingLockedToken | boolean | Trạng thái đang get list các token đã khóa | | isLoadingSwapToken | boolean | Trạng thái đang get list các token được phép swap | | isLoadingReceiveExternalToken | boolean | Trạng thái đang get list các token được phép nhận từ bên ngoài | | isLoadingReceiveInternalToken | boolean | Trạng thái đang get list các token được phép nhận nội bộ |

Data States

| State | Type | Description | | -------------- | --------------- | ----------------------------------------------------------- | | lockedTokens | LockedToken[] | Danh sách tokens đã khóa | | fromTokens | Token[] | Danh sách tokens có thể swap | | transaction | Transaction | Dữ liệu event realtime mới nhất (swap token, send token...) |

🔧 Methods

Wallet Management

| Method | Description | | ---------------------- | ---------------------------------------------------------------- | | updateWalletDetail() | Cập nhật lại chi tiết ví, bao gồm địa chỉ ví và danh sách tokens |

Update Operations

| Method | Description | | ------------------------------ | -------------------------------------------------------- | | updateWithdrawToken() | Cập nhật danh sách các token được phép withdraw | | updateSendInternalToken() | Cập nhật danh sách các token được phép gửi nội bộ | | updateLockToken() | Cập nhật danh sách các token được phép khóa | | updateLockedToken() | Cập nhật danh sách các token đã khóa | | updateSwapTokens() | Cập nhật danh sách các token được phép swap | | updateReceiveExternalToken() | Cập nhật danh sách các token được phép nhận từ bên ngoài | | updateReceiveInternalToken() | Cập nhật danh sách các token được phép nhận nội bộ |

Validation

| Method | Description | | -------------------------------- | ------------------------------------ | | validateWalletAddressService() | Validate địa chỉ ví nội bộ / Onchain |

Notification

| Method | Description | | -------------------- | ---------------------- | | pushNotification() | Hiển thị toast message |

🚀 Hướng dẫn sử dụng

Để bắt đầu sử dụng TekWallet, hãy đảm bảo:

✅ Đã cài đặt đầy đủ các dependencies cần thiết
✅ Đã cấu hình đúng các biến môi trường
✅ Đã wrap ứng dụng trong TekWalletProvider
✅ Đã import các components cần thiết từ package

⚠️ Lưu ý

🔒 Đảm bảo luôn sử dụng RequiredConnect cho các hành động yêu cầu ví phải được kết nối
🔧 Các biến môi trường phải được cấu hình đúng để đảm bảo ứng dụng hoạt động chính xác