# Données des comptes d'application : clés et objets

Toute application publiée sur jumphp.net qui donne un [compte](/docs/comptes-applications) à ses utilisateurs (pseudo + mot de passe)
peut aussi **garder leurs données sur le serveur**, pour les retrouver sur le PC, le téléphone et le navigateur, sans écrire de serveur
à soi. Deux façons, au choix ou ensemble :

- un **magasin clé-valeur** : des clés (`settings`, `save/slot1`, `score:2026-11`…) qui valent du JSON ou du texte, chacune avec sa
  version, et une **recherche de clés** par préfixe ou par motif (`score:2026-*`) ;
- des **objets entiers** : les octets d'un objet sérialisé (`serialize()` de PHP, igbinary, JSON, MessagePack…) envoyés tels quels,
  **versionnés** : le serveur garde les dernières versions, on relit n'importe laquelle.

Le serveur **ne lit jamais** ces données : il ne désérialise rien, il garde des octets. Chaque compte ne voit que les siennes, et une
application ne voit jamais celles d'une autre (`ada` sur deux applications = deux comptes). Supprimer le compte (`DELETE /me`) efface
tout tout de suite ; un compte inutilisé 18 mois est supprimé avec ses données.

En PHP avec JumPHP, la classe `JumPHP\Platform\AppAccount` fait tout cela pour vous, sans jamais bloquer
([plus bas](#depuis-php-jumphp)).

## L'API

Base : `https://jumphp.net/api/apps/<slug>/account` (la même que la connexion), avec le jeton de l'appareil :
`Authorization: Bearer wzd_…`. CORS ouvert, aucun cookie, réponses jamais mises en cache (`Cache-Control: no-store`).

| Requête | Ce qu'elle fait |
|---|---|
| `GET /storage` | ce que le compte utilise et ses limites : `{usage: {keys, kvBytes, objects, versions, objectsBytes}, limits}` |
| `GET /kv/<clé>` | `{key, type, value, version, size, updatedAt, device}` + `ETag: "<version>"` (`If-None-Match` → 304) |
| `PUT /kv/<clé>` | le corps est la valeur : `Content-Type: application/json` (du JSON) ou `text/plain` (du texte UTF-8) → 201 (nouvelle) ou 200 `{key, type, version, size, updatedAt}` |
| `DELETE /kv/<clé>` | supprime la clé → `{deleted}` |
| `GET /kv` | liste et recherche : `prefix`, `match`, `limit`, `cursor`, `values=1` → `{items: [...], next}` |
| `GET /kv?keys=a,b,c` | lecture groupée (100 clés au plus) : `{items: [... avec value], missing: [...]}` |
| `PUT /objects/<nom>` | une nouvelle version : le corps est l'objet (ses octets) ; `?format=php-serialize`, `?keep=10`, `?encoding=base64`, `?sha256=…`, `?type=…` → 201 / 200 |
| `GET /objects/<nom>` | les octets de la dernière version (`application/octet-stream`) ; `?version=N` une version gardée ; `?encoding=base64` en JSON |
| `GET /objects/<nom>/versions` | l'historique : `{name, latest, keep, versions: [{version, size, sha256, format, contentType, createdAt, device}]}` (la plus récente d'abord) |
| `GET /objects` | les objets : `prefix`, `limit`, `cursor` → `{items: [{name, version, size, sha256, format, contentType, updatedAt, device, keep, versions}], next}` |
| `DELETE /objects/<nom>` | supprime l'objet et toutes ses versions → `{deleted}` |

`device` est l'identifiant de l'appareil qui a écrit (celui de `GET /me`), `updatedAt` / `createdAt` des dates ISO 8601.

### Les clés

Une clé : **1 à 128 caractères** parmi `A-Z a-z 0-9 . _ : / -`, commençant par une lettre ou un chiffre. Les majuscules comptent
(`Save` et `save` sont deux clés). Les `/` et `:` servent à ranger : `save/slot1`, `prefs:audio`. Les clés sont triées octet par octet.

Une valeur : **du JSON** (`Content-Type: application/json` : un objet, un tableau, un nombre, une chaîne, `true`, `null`) ou **du texte**
(`text/plain`, UTF-8, sans octet nul). 64 Ko au plus. Pour des octets quelconques, utilisez un objet. `GET` rend la valeur décodée
dans `value` (un objet JSON vide reste `{}`).

```bash
T='Authorization: Bearer wzd_…'
B=https://jumphp.net/api/apps/mon-app/account
curl -X PUT -H "$T" -H 'Content-Type: application/json' -d '{"volume":0.8,"theme":"dark"}' $B/kv/settings
# → 201 {"key":"settings","type":"json","version":1,"size":29,"updatedAt":"2026-11-20T10:00:00+00:00"}
curl -H "$T" $B/kv/settings
# → {"key":"settings","type":"json","value":{"volume":0.8,"theme":"dark"},"version":1,"size":29,...}
curl -X PUT -H "$T" -H 'Content-Type: text/plain' --data-binary 'acheter du pain' $B/kv/notes/courses
```

### Chercher des clés

`GET /kv` donne les clés dans l'ordre, sans les valeurs (sauf `values=1`), 100 par page (`limit` jusqu'à 1 000, 100 avec les valeurs) :

| Paramètre | |
|---|---|
| `prefix` | les clés qui commencent par ce texte, tel quel (`save/`, `save_` : le `_` n'est pas un joker) |
| `match` | un motif sur **toute** la clé : `*` = n'importe quoi (même rien), `?` = un caractère. `score:2026-*`, `save/slot?`, `*:audio` |
| `limit` | combien de clés par page |
| `cursor` | la page suivante : la valeur de `next` de la réponse précédente (`null` : c'était la dernière) |
| `values` | `1` : les valeurs avec |
| `keys` | à la place des autres : ces clés-là exactement, séparées par des virgules (100 au plus), valeurs comprises |

```bash
curl -H "$T" "$B/kv?prefix=score:&match=*-12&values=1"
# → {"items":[{"key":"score:2026-12","type":"json","version":3,"size":4,"updatedAt":"…","device":"a1b2c3d4e5f6","value":1200}],"next":null}
curl -H "$T" "$B/kv?keys=settings,save/slot1,inconnue"
# → {"items":[{…settings…},{…save/slot1…}],"missing":["inconnue"]}
```

### Versions et `If-Match`

Chaque clé et chaque objet a une **version** qui monte de 1 à chaque écriture (`ETag: "3"`). Pour qu'un appareil n'efface jamais
sans le savoir ce qu'un autre vient d'écrire, il écrit en disant la version qu'il a lue :

- `If-Match: "3"` : l'écriture ne passe que si la version est encore 3 ; sinon **412** `{code: "version_conflict", current: {…}}` avec
  la version actuelle (la valeur comprise pour une clé) : l'appareil fusionne et renvoie avec la nouvelle version ;
- `If-Match: "0"` : seulement si la clé (l'objet) n'existe pas encore ;
- sans `If-Match` : l'écriture passe toujours (la dernière gagne) ; pratique pour un réglage que seul un appareil change.

`DELETE` accepte aussi `If-Match`.

### Les objets entiers (PHP `serialize()`, igbinary, JSON…)

`PUT /objects/<nom>` garde **les octets du corps tels quels** et en fait une nouvelle version. Le nom : 1 à 128 caractères parmi
`A-Z a-z 0-9 . _ : -` (pas de `/`). Paramètres :

| | |
|---|---|
| `format` | ce que sont ces octets, pour vous : `php-serialize`, `igbinary`, `json`, `msgpack`… (1 à 32 de `a-z 0-9 . + _ -`, `raw` par défaut). Le serveur le garde et le rend, sans s'en servir |
| `keep` | combien de versions garder, de 1 à 50 (10 par défaut ; gardé pour les écritures suivantes). Les plus anciennes au-delà sont effacées |
| `encoding=base64` | le corps est le base64 des octets (pour un client qui n'envoie que du texte) |
| `sha256` | l'empreinte des octets : refusé (400) si ce qui arrive ne l'a pas (un envoi coupé en route) |
| `type` | le type MIME à garder (sinon le `Content-Type` de la requête, sinon `application/octet-stream`) |

La réponse : `{name, version, size, sha256, format, contentType, createdAt, device, keep, versions}` (201 pour la première version).

`GET /objects/<nom>` rend **les octets** de la dernière version, toujours en `application/octet-stream` (avec
`X-Content-Type-Options: nosniff` : un navigateur ne les exécute jamais), et leurs métadonnées dans les en-têtes `ETag`,
`X-Object-Version`, `X-Object-Latest`, `X-Object-Format`, `X-Object-Content-Type`, `X-Object-Sha256`. Avec `?encoding=base64` :
du JSON `{name, version, latest, size, sha256, format, contentType, createdAt, device, encoding: "base64", data}`.
`?version=N` relit une version gardée (404 `version_not_found` si elle n'est plus gardée) : pour **revenir en arrière**, relisez-la puis
écrivez-la de nouveau (elle devient la dernière, l'historique reste).

```bash
curl -X PUT -H "$T" --data-binary @partie.ser "$B/objects/partie?format=php-serialize&keep=5"
curl -H "$T" "$B/objects/partie/versions"
curl -H "$T" -o ancienne.ser "$B/objects/partie?version=2"
```

**Désérialiser sans danger** : `unserialize()` de PHP sur des octets venus du réseau peut créer n'importe quel objet et lancer son code
(`__wakeup`, `__destruct`). Donnez toujours la liste des classes permises :
`unserialize($octets, ['allowed_classes' => [Partie::class, Joueur::class]])` (jamais sans `allowed_classes`), ou préférez du JSON.
Le serveur, lui, ne désérialise jamais rien.

## Limites et erreurs

| Par compte | |
|---|---|
| Valeur d'une clé | 64 Ko |
| Clés | 2 000, 4 Mo de valeurs en tout |
| Objet (une version) | 2 Mo |
| Objets | 200, 32 Mo en tout avec leurs versions gardées |
| Versions gardées | 10 par défaut, de 1 à 50 par objet (`keep`) |
| Liste | 1 000 clés par page, 100 avec les valeurs ; lecture groupée : 100 clés |
| Écritures | 600 par 10 minutes, 200 Mo écrits par jour |
| Requêtes d'un appareil | 300 par minute (avec celles du compte) |

Ces données sont celles de votre application (réglages, sauvegardes, progression, listes) : pas des fichiers. Un morceau de musique, une
vidéo ou une image lourde ne tiennent pas dans 2 Mo, et n'ont rien à faire là.

Erreurs, en JSON `{error, code}` : 400 `bad_request` (paramètre, JSON invalide, base64, empreinte) / `bad_key` (clé ou nom refusé),
401 `unauthorized` / `revoked` (se connecter de nouveau), 404 `not_found` (clé, objet) / `version_not_found` (version plus gardée),
412 `version_conflict` (avec `current`), 413 `too_big` (valeur ou objet trop gros) / `quota` (le compte est plein, avec `usage`),
415 `unsupported_type` (ni JSON ni texte) ou texte qui n'est pas de l'UTF-8, 429 `rate_limited` (avec `Retry-After` et `retryAfter`).

## Depuis PHP (JumPHP)

`JumPHP\Platform\AppAccount` est le client de toute cette API (connexion comprise) pour une application JumPHP, sur le bureau, dans le
navigateur et sur Android. Il ne bloque jamais : chaque appel rend une `Task` dont la réponse arrive à une image suivante. Il garde le
jeton de l'appareil dans `var/` de l'application.

```php
use JumPHP\Platform\AppAccount;

$account = AppAccount::for($this->engine, 'mon-app');          // https://jumphp.net/api/apps/mon-app/account
$account->signIn($pseudo, $motDePasse)->then(fn () => $this->status = 'connecté', fn (\Throwable $e) => $this->error = $e->getMessage());

// clé-valeur
$account->set('settings', ['volume' => 0.8]);
$account->get('settings')->then(fn (?array $item) => $this->volume = $item['value']['volume'] ?? 1.0);
$account->search(prefix: 'score:', match: '*-12', values: true)->then(fn (array $page) => $this->scores = $page['items']);

// un objet PHP entier, versionné
$account->store('partie', $this->partie)->then(fn (array $v) => $this->version = $v['version']);
$account->load('partie', [Partie::class, Joueur::class])->then(fn (?Partie $p) => $this->partie = $p ?? new Partie());
$account->versions('partie')->then(fn (array $h) => $this->historique = $h['versions']);
```

La documentation complète de la classe est dans le dépôt de JumPHP : `docs/platform-account.md`.

## Pour le propriétaire de l'application

Avec [le serveur MCP du playground](/docs/avec-claude), votre Claude voit les comptes de **vos** applications (jamais celles des autres,
ni celles d'un projet qu'on vous a seulement partagé) : `app_accounts_stats` (combien de comptes, actifs, ce que pèsent leurs données),
`list_app_accounts` (les pseudos, leur dernière visite, leurs clés et objets : jamais un mot de passe ni un jeton),
`get_app_account_data` (les clés et objets d'un compte, les valeurs seulement si on les demande : pour déboguer) et
`delete_app_account` (supprime un compte et tout ce qu'il garde, avec `confirm: true`). Ces données sont celles de vos utilisateurs :
n'en lisez que ce qu'il faut.
