🐾 Wuffi Tap Mini App Library

wuffi-tap-mini-app-lib is a utility library designed for embedding mini-apps within the Wuffi Tap platform. It provides an abstraction layer for authentication, game management, and communication with the host application, making it easier to build interactive and engaging mini-apps.

✨ Features

• Authentication: Retrieve user authentication data, including JWT, user details, and backend API URL.
• Game Management: Close the game from within the mini-app.
• Financial Management: Track user treat balances for in-app purchases.
• Cross-window Communication: Simplify communication with the Wuffi Tap host app via the postMessage API.

📦 Installation

Install the library using npm or yarn:

npm install wuffi-tap-mini-app-lib

or

yarn add wuffi-tap-mini-app-lib

🚀 Usage

Example Mini-App Component

Below is an example of a mini-game that interacts with the Wuffi Tap host:

import { useEffect, useState } from "react";
import { IAuthenData, miniAppWrapper } from "wuffi-tap-mini-app-lib";
import axiosClient from "./axiosClient"; // Custom Axios instance

export function MiniGameExample() {
  const [authData, setAuthData] = useState<IAuthenData | null>(null);

  useEffect(() => {
    miniAppWrapper
      .requestAuthData()
      .then((data) => {
        setAuthData(data));

        // If the mini-app backend uses the Wuffi Tap API, set these headers for API calls
        axiosClient.defaults.baseURL = data.boostrap.apiURL;
        axiosClient.defaults.headers.common["telegram-user-id"] = data.user.id;
        axiosClient.defaults.headers.common[
          "Authorization"
        ] = `Bearer ${data.jwt}`;
      }
      .catch((err) => console.error("Error fetching auth data", err));
  }, []);

  const handleClose = () => {
    miniAppWrapper.closeMiniApp();
  };

  const handleBuyTreats = () => {
    miniAppWrapper.navigateToBuyMoreTreats();
  };

  return (
    <div>
      <h1>Mini Game</h1>
      {authData ? (
        <div>
          <p>Welcome, {authData.user.first_name} {authData.user.last_name}</p>
          <p>Total Paws: {authData.tapStatus?.totalPawsEarned}</p>
          <p>Available Treats: {authData.balance.treat}</p>
        </div>
      ) : (
        <p>Loading user data...</p>
      )}
      <button onClick={handleBuyTreats}>Buy More Treats</button>
      <button onClick={handleClose}>Close Game</button>
    </div>
  );
}

📋 Methods

requestAuthData()

Requests authentication data from the Wuffi Tap host application.

Example:

miniAppWrapper.requestAuthData().then((authData: IAuthenData) => {
  console.log("JWT:", authData.jwt);
  console.log("User:", authData.user);
  console.log("Treat Balance:", authData.balance.treat);
  console.log("API URL:", authData.bootstrap.apiURL);
});

closeMiniApp()

Closes the mini-app, sending a message to the Wuffi Tap host application.

Example:

miniAppWrapper.closeMiniApp().then(() => {
  console.log("Mini-app closed.");
});

navigateToBuyMoreTreats()

Navigates to the in-app purchase screen to buy additional treats.

Example:

miniAppWrapper.navigateToBuyMoreTreats().then(() => {
  console.log("Navigated to buy more treats.");
});

🛠 Data Structures

IAuthenData

Defines the structure for authentication data:

export interface IAuthenData {
  jwt: string; // JWT token for secure API calls
  user: IUser; // User details
  tapStatus?: ITapStatus; // Tap status data
  balance: IBalance; // Financial balance details
  bootstrap: IBoostrap; // User-specific API configuration
}

IUser

Defines the structure for user information:

export interface IUser {
  id: string; // Unique user ID
  first_name: string; // First name
  last_name: string; // Last name
}

ITapStatus

Defines the structure for tap status information:

export interface ITapStatus {
  totalPawsEarned: number; // Total paws earned
  totalTapsCount: number; // Total taps count
  currentEnergy: number; // Current energy available
  currentEnergyUpdateTime: number; // Last update timestamp for energy
  totalSeasonPawsEarned: number; // Total paws earned in the current season
}

IBalance

Defines the structure for the user's treat balance:

export interface IBalance {
  treat: number; // Number of treats available
}

IBoostrap

Defines the structure for user-specific API configuration:

export interface IBoostrap {
  apiURL: string; // URL for backend API communication
}

📡 Communication Mechanism

The library uses the postMessage API for communication between the mini-app and the Wuffi Tap host application. It listens for and sends messages to handle the following actions:

• REQUEST_AUTH_DATA: Requests authentication data from the host app.
• SEND_AUTH_DATA: Receives authentication data from the host app.
• CLOSE_GAME: Closes the mini-game.
• NAVIGATE_TO_BUY_MORE_TREATS: Directs the user to an in-app purchase screen.

🔗 Important Notes

1. JWT Authentication: The Wuffi Tap host currently sends a JWT to the mini-app for secure backend API interactions.
2. User-Specific Configuration: The apiURL provided in the bootstrap object ensures the mini-app can interact with user-specific backends.

⚠️ Short-term Solution: This approach is a temporary measure until the mini-app backend is fully decoupled from the Wuffi Tap API. Future updates will eliminate the dependency on the Wuffi Tap host for backend interactions.

🛠 Development

Build

To build the library, run:

npm run build

Testing

To run tests:

npm run test