npm package: @fyrric/sdk
Description: Official JavaScript SDK for Fyrric - Backend as a Service for Games
Author: Fyrric
Latest version: 1.0.0

# Fyrric SDK

Official JavaScript SDK for Fyrric - Backend as a Service for Games

## Installation

```bash
npm install @fyrric/sdk
```

## Quick Start

```javascript
import Fyrric from '@fyrric/sdk';

const fyrric = new Fyrric('your-api-key');

// Submit a leaderboard score
await fyrric.leaderboard.submit('global', 'player123', 9999, {
    playerName: 'ProGamer',
    metadata: { level: 12 }
});

// Get top players
const topPlayers = await fyrric.leaderboard.getTop('global', { limit: 10 });
console.log(topPlayers);
```

## API Reference

### Authentication

#### Register User
```javascript
const result = await fyrric.auth.register('email@example.com', 'username', 'password123');
// Returns: { user, token, apiKey }
```

#### Login
```javascript
const result = await fyrric.auth.login('email@example.com', 'password123');
// Returns: { user, token, apiKeys }
```

#### Guest Login
```javascript
const result = await fyrric.auth.loginAsGuest();
// Returns: { user, token }
```

---

### Leaderboards

#### Submit Score
```javascript
await fyrric.leaderboard.submit(leaderboardId, playerId, score, {
    playerName: 'Optional Name',
    metadata: { level: 5, time: 120 },
    season: 'default'
});
```

#### Get Top Scores
```javascript
const result = await fyrric.leaderboard.getTop(leaderboardId, {
    limit: 10,
    offset: 0,
    season: 'default'
});
// Returns: { scores: [...], total, limit, offset }
```

#### Get Player Rank
```javascript
const rank = await fyrric.leaderboard.getPlayerRank(leaderboardId, playerId, {
    season: 'default'
});
// Returns: { rank, score, total, ... }
```

#### Get Player History
```javascript
const history = await fyrric.leaderboard.getHistory(leaderboardId, playerId, {
    season: 'default',
    limit: 20
});
// Returns: { history: [...] }
```

---

### Matchmaking

#### Find Match
```javascript
const match = await fyrric.matchmaking.findMatch({
    mode: 'ranked',
    playerId: 'player123',
    skillRating: 1500,
    region: 'us-west',
    partySize: 1
});
// Returns: { matchId, status, players, ... }
```

#### Create Lobby
```javascript
const lobby = await fyrric.matchmaking.createLobby({
    name: 'Pro Players Only',
    mode: 'ranked',
    maxPlayers: 8,
    isPrivate: false,
    settings: { map: 'desert' }
});
// Returns: { lobbyId, lobbyCode, ... }
```

#### Join Lobby
```javascript
const result = await fyrric.matchmaking.joinLobby(lobbyCode, playerId, {
    skillRating: 1500
});
// Returns: { lobbyId, currentPlayers, ... }
```

#### Start Match
```javascript
await fyrric.matchmaking.startMatch(matchId);
```

#### Complete Match
```javascript
await fyrric.matchmaking.completeMatch(matchId, {
    winner: 'team1',
    scores: { team1: 100, team2: 75 }
});
```

#### Get Match Status
```javascript
const match = await fyrric.matchmaking.getMatchStatus(matchId);
// Returns: full match details
```

---

### Cloud Saves

#### Save Player Data
```javascript
await fyrric.saves.save('player123', {
    level: 42,
    experience: 15750,
    inventory: ['sword', 'shield'],
    stats: { strength: 25, agility: 18 }
});
```

#### Load Player Data
```javascript
const saveData = await fyrric.saves.load('player123');
// Returns: { playerId, data, version, savedAt }
```

#### Delete Save
```javascript
await fyrric.saves.delete('player123');
```

---

### Analytics

#### Track Event
```javascript
await fyrric.analytics.track('level_completed', {
    playerId: 'player123',
    properties: { level: 5, time: 127.5, score: 8450 }
});
```

#### Get Events
```javascript
const events = await fyrric.analytics.getEvents({
    startDate: '2024-01-01',
    endDate: '2024-12-31',
    limit: 50
});
// Returns: { events: [...] }
```

#### Get Daily Active Users
```javascript
const dau = await fyrric.analytics.getDailyActiveUsers(30);
// Returns: { dailyActiveUsers: [...] }
```

---

## Configuration

### Custom Base URL
```javascript
const fyrric = new Fyrric('your-api-key', {
    baseURL: 'https://custom-domain.com'
});
```

---

## Error Handling

```javascript
try {
    await fyrric.leaderboard.submit('global', 'player1', 9999);
} catch (error) {
    console.error('Fyrric Error:', error.message);
}
```

---

## TypeScript Support

Coming soon! TypeScript definitions will be included in v1.1.0

---

## Examples

### Complete Game Integration

```javascript
import Fyrric from '@fyrric/sdk';

const fyrric = new Fyrric('your-api-key');

// Initialize game
async function initGame() {
    // Login player
    const user = await fyrric.auth.login('player@example.com', 'password');
    
    // Load saved game
    try {
        const saveData = await fyrric.saves.load(user.user.id);
        loadGameState(saveData.data);
    } catch {
        // No save found, start new game
        startNewGame();
    }
}

// When player completes level
async function onLevelComplete(levelNumber, score, time) {
    // Track analytics
    await fyrric.analytics.track('level_completed', {
        playerId: currentUser.id,
        properties: { level: levelNumber, score, time }
    });
    
    // Submit to leaderboard
    await fyrric.leaderboard.submit('global', currentUser.id, score, {
        playerName: currentUser.username,
        metadata: { level: levelNumber }
    });
    
    // Save progress
    await fyrric.saves.save(currentUser.id, {
        currentLevel: levelNumber + 1,
        totalScore: playerData.totalScore + score
    });
}

// Find multiplayer match
async function findMatch() {
    const match = await fyrric.matchmaking.findMatch({
        mode: 'ranked',
        playerId: currentUser.id,
        skillRating: playerData.rating,
        region: 'auto'
    });
    
    if (match.isReady) {
        startMultiplayerGame(match);
    }
}
```

---

## Support

- Documentation: https://docs.fyrric.io
- GitHub: https://github.com/fyrric/sdk
- Discord: https://discord.gg/fyrric

---

## License

MIT