npm package: @livespark/theme-sdk
Description: SDK pour créer des thèmes LiveSpark (overlay TikTok Live)
Author: Julien
Latest version: 0.1.7

# @livespark/theme-sdk

SDK pour créer des thèmes LiveSpark (overlay TikTok Live).

## Installation

```bash
npm install @livespark/theme-sdk
```

## Utilisation

### Configuration de base

```typescript
import { createLiveSparkClient } from "@livespark/theme-sdk";

// Le SDK récupère automatiquement le token depuis l'URL ou via postMessage
const client = await createLiveSparkClient();

// Écouter les cadeaux
client.onGift((gift) => {
  console.log(
    "Cadeau reçu:",
    gift.giftName,
    "x",
    gift.giftCount
  );
});

// Écouter les messages de chat
client.onChatMessage((message) => {
  console.log(
    message.viewerName,
    ":",
    message.message
  );
});

// Écouter les nouveaux abonnés
client.onFollow((follow) => {
  console.log(
    "Nouvel abonné:",
    follow.viewerName
  );
});

// Écouter quand un utilisateur rejoint le live
client.onJoin((join) => {
  console.log(
    "👋 Nouvel arrivant:",
    join.viewerName
  );
});

// Écouter les likes sur le live
client.onLike((like) => {
  console.log(
    "❤️",
    like.viewerName,
    "a envoyé",
    like.likeCount,
    "like(s)"
  );
});

// Écouter tous les événements
client.onEvent((event) => {
  console.log(
    "Événement:",
    event.type,
    event.data
  );
});

// Écouter les événements de connexion
client.onConnected(() => {
  console.log("Connecté au live !");
});

client.onReconnected(() => {
  console.log("Reconnecté au live !");
});

client.onDisconnected((reason) => {
  console.log("Déconnecté:", reason);
});

// Vérifier le statut du live
const status = await client.getLiveStatus();
if (status.isLive) {
  console.log("Le live est actif !");
}

// Écouter les changements de statut du live (actif/inactif)
client.onLiveStatusChange((status) => {
  if (status.isLive) {
    console.log(
      "Le live vient de démarrer !",
      status.liveId
    );
  } else {
    console.log("Le live vient de se terminer");
  }
});
```

### Gestion automatique de la reconnexion

Par défaut, le SDK gère automatiquement :

- ✅ **Polling automatique** : Vérifie le statut du live toutes les 10 secondes
- ✅ **Reconnexion automatique** : Se reconnecte automatiquement quand le live redevient actif
- ✅ **Détection des changements** : Notifie via `onLiveStatusChange` quand le live démarre/s'arrête

```typescript
// Configuration par défaut (recommandée)
const client = await createLiveSparkClient({
  autoPolling: true, // Active le polling (défaut: true)
  pollingInterval: 10000, // Vérifie toutes les 10s (défaut: 10000ms)
  autoReconnect: true, // Reconnexion auto (défaut: true)
});

// Désactiver le polling si nécessaire
client.stopPolling();

// Réactiver le polling
client.startPolling();
```

### Vérification du statut sans créer de client

```typescript
import { getLiveStatus } from "@livespark/theme-sdk";

// Vérifier si un live est actif avant d'initialiser le SDK
const status = await getLiveStatus(
  "votre-token",
  {
    devMode: true,
  }
);

if (status.isLive) {
  console.log("Live actif, ID:", status.liveId);
  // Initialiser le client complet
  const client = await createLiveSparkClient({
    token: "votre-token",
    devMode: true,
  });
} else {
  console.log("Aucun live actif");
}
```

### Mode développement

```typescript
const client = await createLiveSparkClient({
  devMode: true, // Utilise http://localhost:4000
  token: "votre-token-de-test",
});
```

### Configuration avancée

```typescript
const client = await createLiveSparkClient({
  apiUrl: "https://custom-api.example.com", // URL personnalisée
  hostOrigin: "https://livespark.live", // Validation de l'origine des messages
  token: "token-manuel", // Token manuel (optionnel)
});
```

## API

### `createLiveSparkClient(options?)`

Crée et initialise un client LiveSpark.

**Options:**

- `token?: string` - Token d'authentification (optionnel si utilisé dans un iframe)
- `devMode?: boolean` - Mode développement (utilise localhost:4000)
- `apiUrl?: string` - URL de l'API personnalisée
- `hostOrigin?: string` - Origine de l'hôte pour la validation des messages
- `autoPolling?: boolean` - Active le polling automatique du statut (défaut: true)
- `pollingInterval?: number` - Intervalle de polling en ms (défaut: 10000)
- `autoReconnect?: boolean` - Reconnexion automatique quand le live redevient actif (défaut: true)

**Retourne:** `Promise<LiveSparkClient>`

### `getLiveStatus(token, options?)`

Vérifie le statut du live sans créer de client complet.

**Paramètres:**

- `token: string` - Token d'authentification (requis)
- `options?: object`
  - `devMode?: boolean` - Mode développement
  - `apiUrl?: string` - URL de l'API personnalisée

**Retourne:** `Promise<LiveSparkStatus>`

### `LiveSparkClient`

**Méthodes:**

- `onGift(handler)` - Écouter les événements de cadeaux
- `onChatMessage(handler)` - Écouter les messages de chat
- `onFollow(handler)` - Écouter les nouveaux abonnés
- `onJoin(handler)` - Écouter quand un utilisateur rejoint le live
- `onLike(handler)` - Écouter les likes sur le live
- `onEvent(handler)` - Écouter tous les événements
- `onConnected(handler)` - Écouter la connexion initiale
- `onReconnected(handler)` - Écouter les reconnexions
- `onDisconnected(handler)` - Écouter les déconnexions
- `onLiveStatusChange(handler)` - Écouter les changements de statut du live
- `getLiveStatus()` - Récupérer le statut du live
- `stopPolling()` - Arrêter le polling automatique
- `startPolling()` - Redémarrer le polling automatique
- `disconnect()` - Déconnecter le client

## Types

### `LiveSparkStatus`

```typescript
{
  isLive: boolean;        // Indique si le live est actif
  liveId?: string;        // ID du live (si actif)
  live?: {                // Informations du live
    id: string;
    title?: string;
    startedAt?: string;
    [key: string]: any;
  };
}
```

### `LiveSparkGiftEvent`

```typescript
{
  eventType: string;
  giftCount: number;
  giftName: string;
  giftValue: number;
  viewerId: string;
  viewerName: string;
}
```

### `LiveSparkChatMessageEvent`

```typescript
{
  eventType: string;
  message: string;
  profilePictureUrl: string;
  viewerId: string;
  viewerName: string;
  timestamp: number;
}
```

### `LiveSparkFollowEvent`

```typescript
{
  eventType: string;
  viewerId: string;
  viewerName: string;
}
```

### `LiveSparkJoinEvent`

```typescript
{
  eventType: string;
  viewerId: string;
  viewerName: string;
  profilePictureUrl?: string;
}
```

### `LiveSparkLikeEvent`

```typescript
{
  eventType: string;
  viewerId: string;
  viewerName: string;
  likeCount: number;      // Nombre de likes envoyés
  totalLikes?: number;    // Total de likes sur le live (optionnel)
}
```

## Licence

MIT