Score Anything Loyalty SDK

Official SDK for integrating with the Score Anything Loyalty platform. Manage points, challenges, rewards, leaderboards, and user profiles with ease.

Features

• 🎯 Points Management - Award, deduct, and track loyalty points (Karma)
• 🏆 Challenges - Create and manage user challenges with progress tracking
• 🎁 Rewards - Handle reward catalog and redemption
• 📊 Leaderboards - Query rankings and user positions
• 👤 User Profiles - Manage user data and achievements
• ⚛️ React Support - First-class React integration with hooks
• 📘 TypeScript - Full TypeScript support with type definitions
• 🔄 React Query - Built-in caching and state management

Installation

npm install @3halves-labs/score-loyalty-sdk

For React integration, you'll also need React Query:

npm install @tanstack/react-query

Quick Start

Basic Usage (JavaScript/TypeScript)

import { LoyaltyClient } from '@3halves-labs/score-loyalty-sdk';

// Initialize the client
const client = new LoyaltyClient({
  apiUrl: 'https://your-loyalty-api.com',
  apiKey: 'your-api-key',
  userId: 'user-123'
});

// Award points
await client.awardPoints(100, 'Completed first game');

// Get challenges
const challenges = await client.getChallenges({ status: 'active' });

// Redeem a reward
await client.redeemReward('reward-id');

React Integration

import { LoyaltyProvider, usePoints, useChallenges } from '@3halves-labs/score-loyalty-sdk/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <LoyaltyProvider config={{
        apiUrl: 'https://your-api.com',
        apiKey: 'your-key',
        userId: 'user-123'
      }}>
        <Dashboard />
      </LoyaltyProvider>
    </QueryClientProvider>
  );
}

function Dashboard() {
  const { data: points, isLoading } = usePoints();
  const { data: challenges } = useChallenges({ status: 'active' });

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      <h1>You have {points} points!</h1>
      <ChallengeList challenges={challenges?.data || []} />
    </div>
  );
}

Core API

Points

// Get current points
const points = await client.getPoints();

// Award points
await client.awardPoints(100, 'Challenge completed');

// Deduct points
await client.deductPoints(50, 'Reward redeemed');

// Get transaction history
const history = await client.getPointsHistory();

Challenges

// Get all challenges
const challenges = await client.getChallenges();

// Filter challenges
const activeChallenges = await client.getChallenges({
  status: 'active',
  type: 'daily'
});

// Get challenge progress
const progress = await client.getChallengeProgress('challenge-id');

// Complete a challenge
const completion = await client.completeChallenge('challenge-id', {
  score: 100
});

Rewards

// Get all rewards
const rewards = await client.getRewards();

// Filter rewards
const availableRewards = await client.getRewards({
  available: true,
  maxCost: 500
});

// Redeem a reward
const redemption = await client.redeemReward('reward-id');

// Get redemption history
const history = await client.getRedemptionHistory();

Leaderboard

// Get leaderboard
const leaderboard = await client.getLeaderboard({
  period: 'weekly',
  limit: 100
});

// Get user's rank
const rank = await client.getUserRank();

User Profile

// Get profile
const profile = await client.getProfile();

// Update profile
await client.updateProfile({
  userName: 'NewName',
  avatar: 'https://...'
});

// Get achievements
const achievements = await client.getAchievements();

React Hooks

All hooks support React Query options for caching, refetching, and more.

Points Hooks

const { data: points } = usePoints();
const { data: history } = usePointsHistory();
const { mutate: awardPoints } = useAwardPoints();

// Award points
awardPoints({ amount: 100, reason: 'Game completed' });

Challenge Hooks

const { data: challenges } = useChallenges({ status: 'active' });
const { data: challenge } = useChallenge('challenge-id');
const { data: progress } = useChallengeProgress('challenge-id');
const { mutate: complete } = useCompleteChallenge();

// Complete challenge
complete({ challengeId: 'challenge-id', data: { score: 100 } });

Reward Hooks

const { data: rewards } = useRewards({ available: true });
const { data: reward } = useReward('reward-id');
const { mutate: redeem } = useRedeemReward();

// Redeem reward
redeem({ rewardId: 'reward-id' });

Leaderboard Hooks

const { data: leaderboard } = useLeaderboard({ period: 'weekly' });
const { data: rank } = useUserRank();

Profile Hooks

const { data: profile } = useProfile();
const { mutate: updateProfile } = useUpdateProfile();

// Update profile
updateProfile({ updates: { userName: 'NewName' } });

TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

import type {
  Challenge,
  Reward,
  UserProfile,
  LeaderboardEntry,
  PointTransaction
} from '@3halves-labs/score-loyalty-sdk';

const challenge: Challenge = {
  id: '123',
  name: 'Daily Login',
  type: 'daily',
  status: 'active',
  points: 10,
  // ... TypeScript will validate the structure
};

Error Handling

try {
  await client.awardPoints(100, 'Completed task');
} catch (error) {
  if (error instanceof Error) {
    console.error('Failed to award points:', error.message);
  }
}

With React hooks:

const { mutate, error, isError } = useAwardPoints({
  onError: (error) => {
    console.error('Award failed:', error.message);
  }
});

if (isError) {
  return <div>Error: {error.message}</div>;
}

Documentation

• Getting Started Guide
• API Reference
• React Integration
• Examples

License

MIT © 3 Halves Labs

Support

• GitHub Issues
• Documentation