# Client JavaScript navigateur UDCShare (sécurisé)

Ce client est destiné au **navigateur**. Il appelle votre backend et ne contient **aucune clé API UDCShare**.

## Pourquoi un backend est obligatoire

Une clé UDCShare authentifie le propriétaire de la ressource API. Si vous la placez dans le JavaScript du navigateur, chaque visiteur peut la récupérer et appeler l'API avec les droits de votre projet. En mode multi-utilisateur, ne laissez jamais le navigateur choisir librement l'identifiant externe d'un autre utilisateur.

Architecture correcte :

1. L'utilisateur se connecte à votre application.
2. Le navigateur envoie son fichier à votre backend avec sa session.
3. Votre backend vérifie la session et les droits de l'utilisateur.
4. Votre backend appelle UDCShare avec sa variable secrète X-API-Key et la route du projet.
5. En mode API-only individuel, le backend définit X-External-User-ID depuis l'identité vérifiée, jamais depuis une valeur non fiable fournie par le navigateur.

## Installation

Incluez le fichier :

~~~html
<script src="./udcshare.js"></script>
~~~

Initialisez le client avec l'URL de vos propres routes backend :

~~~js
const udcshare = new UDCShareClient({ backendUrl: "/api/udcshare" });
~~~

Le backend doit exposer ces routes internes à votre application :

| Méthode | Route de votre backend | Action |
|---|---|---|
| POST | /api/udcshare/files | Vérifie la session puis transmet le fichier à UDCShare |
| GET | /api/udcshare/files | Liste uniquement les fichiers autorisés pour l'utilisateur connecté |
| DELETE | /api/udcshare/files/:id | Vérifie l'appartenance avant suppression |
| GET | /api/udcshare/usage | Renvoie les compteurs du compte/clé autorisés à cet administrateur |
| GET | /api/udcshare/stats | Renvoie les statistiques privées de la ressource du projet |
| GET | /api/udcshare/status | Vérifie l'état de la ressource et du Drive |

## Exemple d'upload avec progression

~~~html
<input type="file" id="fileInput">
<button id="uploadButton">Envoyer</button>
<progress id="progress" value="0" max="100"></progress>
<script src="./udcshare.js"></script>
<script>
  const client = new UDCShareClient({ backendUrl: "/api/udcshare" });
  document.getElementById("uploadButton").addEventListener("click", async () => {
    const file = document.getElementById("fileInput").files[0];
    try {
      const result = await client.uploadFile(file, {
        onProgress: progress => {
          document.getElementById("progress").value = progress.percentage;
        }
      });
      console.log("Upload terminé", result);
    } catch (error) {
      console.error(error.code, error.message);
    }
  });
</script>
~~~

## Statistiques et diagnostic

~~~js
const [usage, stats, status] = await Promise.all([
  client.getUsage(),
  client.getStats(),
  client.getStatus()
]);
console.log({ quota: usage.quota, requests: usage.requests, uploads: usage.uploads });
console.log({ scope: stats.scope, files: stats.total_files, drive: stats.google_drive });
console.log(status.overall_status);
~~~

Ne montrez les statistiques de compte et de projet qu'aux administrateurs autorisés dans votre application.

## Backend de référence

- [Exemple Node.js / Express sécurisé](../nodejs-upload-api/README.md)
- [Guide général d'intégration](../../../../docs/GUIDE_INTEGRATION_API_DEVELOPPEUR.md)
- [Exemples API multi-langages](../../../../docs/EXEMPLES_INTEGRATION_API.md)

**Ne faites jamais d'appel direct à UDCShare avec X-API-Key depuis un navigateur.** Le client ne fait pas de retry automatique sur un upload interrompu : vérifiez d'abord si le fichier est déjà présent pour éviter les doublons.
