API locale et formats d’échange
Cette API est interne au desktop, sans garantie de compatibilité pour des clients tiers. Elle écoute uniquement sur loopback. Les formats d'échange sont versionnés séparément de la version de l'application.
Session HTTP
Le lanceur reçoit /?key=…, une clé aléatoire de 24 octets encodée en hexadécimal. Le serveur l'échange contre le cookie ForgeSession (HttpOnly, SameSite=Strict), puis redirige vers /. Le nom Forge est un héritage technique. Ne copiez pas cette URL dans une issue.
GET /health est non authentifié et retourne une identité technique, pas des données financières. Les autres routes nécessitent la session. Les POST exigent l'origine exacte et application/json ; leur corps est limité à 65 536 caractères JavaScript. Ce n'est pas une limite exprimée en octets UTF-8. Hôte incorrect, requête non authentifiée et origine incorrecte sont refusés.
Routes
| Méthode | Route | Rôle |
|---|---|---|
| GET | /api/state | Instantané calculé |
| GET | /api/export.csv | Export selon kind : crafts, shopping, transactions, returns |
| POST | /api/refresh | Relire les sources |
| POST | /api/settings | Modifier les paramètres validés |
| POST | /api/workspace | Préférences de présentation |
| POST | /api/plan-preview | Calculer une sélection sans la sauver |
| POST | /api/plan | Enregistrer les sélections |
| POST | /api/watchlist | Enregistrer les identifiants suivis |
| POST | /api/restock | Appliquer et enregistrer le plan suggéré |
| POST | /api/session | Démarrer, suspendre ou confirmer une étape |
| POST | /api/returns/batch | Appliquer des décisions avec portée et tokens |
| POST | /api/returns/undo | Annuler le dernier lot de décisions |
| POST | /api/returns/review | Enregistrer une revue de prix |
| POST | /api/returns/scenario | Calculer un scénario de remise en vente |
| POST | /api/returns/tsm | Préparer l'import de groupes TSM |
| POST | /api/returns/companion | Préparer le paquet Companion |
| POST | /api/shutdown | Arrêter le moteur |
Exemple conceptuel de sélection : {"selections":[{"key":"clé-de-recette","quantity":1}]}. Les clés et signatures viennent de l'instantané courant ; ne les fabriquez pas à partir d'un nom traduit. Pour les corps complets, consulter le gestionnaire AppStore appelé par chaque route : le code reste le contrat exécutable.
POST /api/restock remplace les sélections enregistrées par celles du plan suggéré : il peut écraser un plan manuel. Pour un calcul sans persistance, utiliser /api/plan-preview.
Trois canaux distincts
- Desktop → Companion : texte
DP1:contenant une table AceSerializer,kind=DP_COMPANIONetversion=1. Portée royaume/faction/région et personnages, lignes indexées par itemString exact. Maximum 50 personnages, 2 000 clés et 512 000 octets UTF-8 côté export. Le plan expire après 24 h ; chaque prix garde son propre âge de deux heures. Une date future de plus de cinq minutes est refusée. - D&P → TSM : groupes et opérations sérialisés, à importer manuellement dans TSM. Ce format n'est pas le paquet Companion. Les lignes bloquées produisent une limite de publication nulle ; le profil et les variantes restent séparés.
- Companion → desktop : SavedVariables
DonjonsEtPognonsDB, journal observateur version 1. Disponible après sauvegarde du client, lu comme données, jamais exécuté.
Les décodeurs bornent profondeur, quantité et types. Un import rejeté ne doit pas remplacer un plan valide par des données partielles. Voir passage au jeu.
