npm package: @funtico/gameloop-sdk
Description: Funtico Gameloop SDK
Author: Funtico
Latest version: 0.0.4

## Installation

### npm

```bash
npm install @funtico/gameloop-sdk
```

### yarn

```bash
yarn add @funtico/gameloop-sdk
```

### pnpm

```bash
pnpm add @funtico/gameloop-sdk
```

### CDN

For quick prototyping or simple integrations, you can use the CDN version:

```html
<script src="https://funtico-frontend-js-sdk.pages.dev/funtico-sdk.min.js"></script>
<script>
  const sdk = new FunticoSDK({
    authClientId: 'your-client-id',
    env: 'sandbox' // or 'production'
  });
  // Use the SDK...
</script>
```

## Quick Start

```typescript
import { FunticoSDK } from '@funtico/gameloop-sdk';

// Initialize SDK for frontend use (no client secret needed)
const sdk = new FunticoSDK({
  authClientId: 'your-auth-client-id',
  env: 'sandbox' // or 'production'
});

// Start authentication flow - simple one-line call
await sdk.signInWithFuntico(
  window.location.origin + '/auth/callback'
);

// Get user info - tokens handled automatically
const userInfo = await sdk.getUserInfo();

// Submit game scores - authentication included
await sdk.saveScore(1500);

// Get leaderboard data - shows top players with their scores
const leaderboard = await sdk.getLeaderboard();

// Sign out - cleanup handled automatically
await sdk.signOut('/login');
```

## Configuration

### Basic Setup

```typescript
import { FunticoSDK } from '@funtico/gameloop-sdk';

const sdk = new FunticoSDK({
  authClientId: 'your-auth-client-id', // Required
  env: 'sandbox' // Optional: 'sandbox' or 'production' (default: 'production')
});
```

### Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `authClientId` | `string` | - | Your Funtico OAuth client ID (required) |
| `env` | `'sandbox' \| 'production'` | `'production'` | Environment to use |

### Environment Setup

- **sandbox**: For development and testing
- **production**: For live applications  

### 📖 **Step-by-Step Explanation**

#### 1. User Initiates Sign-In
```typescript
// In your login button handler
const handleLogin = async () => {
  await sdk.signInWithFuntico(
    window.location.origin + '/auth/callback'
  );
  // User is now redirected to Funtico authentication and after he logs in he will be redirected to /auth/callback
};
```

#### 2. User is authenticated
```typescript
// Get current user information
const user = await sdk.getUserInfo();

// Submit game scores
await sdk.saveScore(1500);

// Get leaderboard data
const leaderboard = await sdk.getLeaderboard();
console.log('Top player:', leaderboard[0].user.username, 'with score:', leaderboard[0].score);

// Sign out when done (redirects to /login)
await sdk.signOut('/login');
```

## Error Handling

The SDK uses a structured error system for reliable error handling:

```typescript
import { SDKError, isSDKError } from '@funtico/gameloop-sdk';

try {
  const userInfo = await sdk.getUserInfo();
} catch (error) {
  if (isSDKError(error)) {
    console.error('SDK Error:', error.name, error.status);
    
    switch (error.name) {
      case 'auth_error':
        // User needs to re-authenticate
        console.log('Please log in again');
        await sdk.signInWithFuntico('/auth/callback');
        break;
        
      case 'internal_server_error':
        // Server or network issues
        console.error('Service temporarily unavailable');
        break;
    }
  } else {
    console.error('Unexpected error:', error);
  }
}
```

### Error Types

| Error Type | Status Codes | Description | Recommended Action |
|------------|--------------|-------------|-------------------|
| `auth_error` | 401, 403 | Authentication required or expired | Redirect to login |
| `internal_server_error` | 400, 500+ | Server or request errors | Show error message, retry |

### Error Class

```typescript
class SDKError {
  name: 'auth_error' | 'internal_server_error';
  status: number;
}

// Type guard function
function isSDKError(error: unknown): error is SDKError
```