@elevora/react/readme.md

Official SDK for Elevora's public API

# @elevora/react

> ⚠️ **Warning**: This SDK is currently under active development and may undergo significant changes. Use with caution in production environments.

Official React SDK for [Elevora's](https://elevora.app) public API. This SDK provides easy integration with Elevora's community building, engagement, and reward systems.

## Requirements
- Sign up on [elevora.app](https://elevora.app) and set up a campaign
- React 16.8+ (for Hooks support)

## Installation

```bash
npm install @elevora/react axios @tanstack/react-query react
```

## Quick Start

1. Wrap your application with the `ElevoraProvider`:

```tsx
import { ElevoraProvider } from '@elevora/react';

function App() {
    return (
        <ElevoraProvider campaignSlug="your-campaign-slug">
            <YourApp />
        </ElevoraProvider>
    );
}
```

2. Use the hooks in your components:

```tsx
import { useElevora } from '@elevora/react';

function YourComponent() {
    const { isConnected, userEntry } = useElevora();
    return (
        <div>
            {isConnected ? (
                <p>Welcome back!</p>
            ) : (
                <p>Please sign in</p>
            )}
        </div>
    );
}
```

## Available Hooks

### useElevora

The main hook for accessing Elevora's context and core functionality.

```tsx
const {
    campaignSlug,        // Current campaign identifier
    campaign,            // Campaign details
    userEntry,           // Current user's entry information
    setToken,            // Function to set auth token
    isConnected,         // Boolean indicating if user is authenticated
    haveEntry,           // Boolean indicating if user has an entry
    signin,             // Function to sign in
    refetch,            // Function to refetch user entry
    logout,             // Function to logout
    user,               // User data
    style,              // Campaign style settings
    refetchUser,        // Function to refetch user data
    isLoadingUser,      // Boolean indicating if user data is loading
    isLoadingEntry      // Boolean indicating if entry data is loading
} = useElevora();
```

### useDailyReward

Hook for managing daily reward claims and streak calculations.

```tsx
const {
    currentStreak,              // Current number of consecutive daily claims
    timeUntilNextClaim,         // Time remaining until next claim (format: "Xh Ym")
    canClaim,                   // Boolean indicating if user can claim reward now
    calculateDailyReward,       // Function to calculate reward points based on streak
    currentStreakNotIncremented // Streak count used for reward calculation
} = useDailyReward(quest);
```

### useMissions

Hook for handling mission validations and tracking progress.

```tsx
const {
    validateQuest,         // Function to validate a quest
    totalMissionsPoints    // Total available points from all missions
} = useMissions({
    onSuccess,            // Optional success callback
    onError,              // Optional error callback
    vibrate              // Optional vibration on success
});
```

### useContentBattle

Hook for managing content battle operations.

```tsx
const {
    currentRound,    // Current round data
    userEntry,       // User's entry data
    submitEntry,     // Function to submit a new entry
    submitVote,      // Function to submit a vote
    refetchRound,    // Function to refresh round data
    refetchEntry     // Function to refresh entry data
} = useContentBattle({
    battleId,           // Optional battle ID
    onSuccess,          // Optional success callback
    onError,            // Optional error callback
    onVoteSuccess,      // Optional vote success callback
    onSubmitEntrySuccess // Optional entry submission success callback
});
```

### useSocialConnect

Hook for managing social media connections.

```tsx
const {
    connectX,        // Function to connect X (Twitter) account
    accountX,        // Connected X (Twitter) handle
    accountTelegram  // Connected Telegram username
} = useSocialConnect();
```

## Types

The SDK exports all API types from the `@elevora/react/schemas` path:

```tsx
import { 
    PublicCampaignsDto, 
    UserEntryPublicDto,
    ValidateQuestDto,
    // ... other types
} from '@elevora/react/schemas';
```

## Error Handling

All hooks that perform operations accept error callbacks to handle failures gracefully:

```tsx
const { validateQuest } = useMissions({
    onError: (error) => {
        console.error('Mission validation failed:', error.message);
    }
});
```

## Customization

The SDK provides access to campaign styling through the `useElevora` hook:

```tsx
const { style } = useElevora();
// Access theme colors, fonts, and other styling properties
```

## Best Practices

1. Always wrap your application with `ElevoraProvider` at the root level
2. Handle loading states and errors appropriately
3. Implement proper error boundaries in your React application
4. Use the provided hooks instead of making direct API calls
5. Leverage the built-in caching and state management provided by the SDK

## Contributing

We welcome contributions! Please see our [contributing guidelines](CONTRIBUTING.md) for details.

## License

MIT License - see the [LICENSE](LICENSE) file for details.

Made with ❤️ by [Thibault Mathian](https://thibault.sh)