@oasis/web4-api-client

Official JavaScript/TypeScript client for the OASIS Web4 API - Decentralized avatar management, karma system, NFTs, and cross-provider data storage.

🚀 Installation

npm install @oasis/web4-api-client

or

yarn add @oasis/web4-api-client

📖 Quick Start

Basic Usage

import { OASISWeb4Client } from '@oasis/web4-api-client';

// Initialize the client
const client = new OASISWeb4Client({
  apiUrl: 'http://localhost:5000/api',
  debug: true
});

// Authenticate
const authResult = await client.authenticate('holochain', {
  username: '[e-mail]',
  password: 'password123'
});

if (!authResult.isError) {
  console.log('Logged in:', authResult.result.avatar);
}

React Example

import { useState, useEffect } from 'react';
import { OASISWeb4Client } from '@oasis/web4-api-client';

function App() {
  const [client] = useState(() => new OASISWeb4Client());
  const [avatar, setAvatar] = useState(null);

  const login = async (provider: string) => {
    const result = await client.authenticate(provider);
    if (!result.isError) {
      setAvatar(result.result.avatar);
    }
  };

  return (
    <div>
      <button onClick={() => login('holochain')}>Login</button>
      {avatar && <p>Welcome, {avatar.username}!</p>}
    </div>
  );
}

🔑 Authentication

Authenticate with Provider

const result = await client.authenticateWithProvider('ethereum');

Set Auth Token

client.setAuthToken('your-jwt-token');

Logout

await client.logout();

👤 Avatar Management

Get Avatar

// By ID
const avatar = await client.getAvatar('avatar-id');

// By username
const avatar = await client.getAvatarByUsername('john_doe');

// By email
const avatar = await client.getAvatarByEmail('[e-mail]');

Create Avatar

const newAvatar = await client.createAvatar({
  username: 'john_doe',
  email: '[e-mail]',
  password: 'secure-password',
  firstName: 'John',
  lastName: 'Doe',
  acceptTerms: true
});

Update Avatar

const updated = await client.updateAvatar('avatar-id', {
  bio: 'Web3 enthusiast',
  image: 'https://example.com/avatar.jpg'
});

Search Avatars

const results = await client.searchAvatars('john');

🏆 Karma System

Get Karma

const karma = await client.getKarma('avatar-id');
console.log('Total karma:', karma.result.total);
console.log('Rank:', karma.result.rank);

Add Karma

await client.addKarma('avatar-id', {
  amount: 100,
  reason: 'Completed quest',
  karmaType: 'QuestCompleted'
});

Get Karma History

const history = await client.getKarmaHistory('avatar-id', 50);

Get Leaderboard

const leaderboard = await client.getKarmaLeaderboard('month', 100);

🎨 NFT Operations

Get NFTs

const nfts = await client.getNFTs('avatar-id');

Mint NFT

const nft = await client.mintNFT('avatar-id', {
  name: 'My Awesome NFT',
  description: 'A unique digital asset',
  imageUrl: 'https://example.com/nft.png',
  collection: 'OASIS Collection',
  price: 1000,
  metadata: {
    attributes: [
      { trait_type: 'Rarity', value: 'Legendary' }
    ]
  }
});

Transfer NFT

await client.transferNFT('nft-id', 'recipient-avatar-id');

Burn NFT

await client.burnNFT('nft-id');

💾 Data Storage

Save Data

await client.saveData('avatar-id', 'preferences', {
  theme: 'dark',
  notifications: true
});

Get Data

// Get all data
const allData = await client.getData('avatar-id');

// Get specific key
const prefs = await client.getData('avatar-id', 'preferences');

Delete Data

await client.deleteData('avatar-id', 'preferences');

🔌 Provider Management

Get Available Providers

const providers = await client.getAvailableProviders();

Get Current Provider

const current = await client.getCurrentProvider();

Switch Provider

await client.switchProvider('ipfs');

💬 Messaging

Get Chat Messages

const messages = await client.getChatMessages('chat-id', 100);

Send Message

await client.sendMessage('chat-id', 'avatar-id', 'Hello, world!');

🌐 Social Features

Get Social Feed

// Global feed
const feed = await client.getSocialFeed('global');

// Friends feed
const friendsFeed = await client.getSocialFeed('friends', 'avatar-id');

Get Friends

const friends = await client.getFriends('avatar-id');

Add Friend

await client.addFriend('avatar-id', 'friend-avatar-id');

Like Post

await client.likePost('post-id');

Get Achievements

const achievements = await client.getAchievements('avatar-id');

⚙️ Configuration

Advanced Configuration

const client = new OASISWeb4Client({
  apiUrl: 'https://api.oasis.network',
  timeout: 60000,           // Request timeout in ms
  debug: true,              // Enable debug logging
  autoRetry: true,          // Auto-retry failed requests
  maxRetries: 5             // Maximum retry attempts
});

Environment Variables

OASIS_WEB4_API_URL=http://localhost:5000/api

🔒 Error Handling

All methods return an OASISResult object:

interface OASISResult<T> {
  isError: boolean;
  message: string;
  result: T | null;
  isSaved?: boolean;
}

Example error handling:

const result = await client.getAvatar('avatar-id');

if (result.isError) {
  console.error('Error:', result.message);
} else {
  console.log('Avatar:', result.result);
}

📚 TypeScript Support

Full TypeScript support with complete type definitions:

import { OASISWeb4Client, Avatar, Karma, NFT } from '@oasis/web4-api-client';

const client = new OASISWeb4Client();

// Types are automatically inferred
const avatar: Avatar = result.result;

🧪 Testing

npm test

📄 License

MIT

🔗 Links

• Documentation

• GitHub

• Discord

🤝 Contributing

Contributions are welcome! Please see our Contributing Guide.