@empereur-rouge/pms-sdk 0.3.8 → 0.7.1

package/README.md

@@ -118,6 +118,7 @@ Le client permet d'interagir avec l'API REST des nœuds PMS.
 const client = new PmsClient({
   nodeUrl: "https://node.pms.network",  // URL du nœud principal
   apiKey: "pk_live_votre_cle_ici",       // Clé API (obligatoire)
+  adminToken: "admin_token_ici",         // Optionnel: requis pour les méthodes admin (gouvernance, setConfig)
   seedNodes: [                           // Optionnel: nœuds de secours
     "https://node2.pms.network",
     "https://node3.pms.network",
@@ -132,6 +133,9 @@ const client = new PmsClient({
 > [!IMPORTANT]
 > La clé API est **obligatoire**. Obtenez-la depuis votre dashboard PMS ou auprès de l'administrateur du réseau.
 
+> [!WARNING]
+> `adminToken` n'est requis que pour les méthodes admin (gouvernance `propose`/`enact`/`cancel`, `setConfig`). Il est envoyé en `Authorization: Bearer <adminToken>`, uniquement vers le nœud principal (jamais vers les seeds lors du racing). **Ne jamais l'exposer côté navigateur ni le committer.** Les lectures publiques de gouvernance n'en ont pas besoin.
+
 #### Wallet (Custodial — Server-Side)
 
 Ces méthodes créent/restaurent des wallets **côté serveur**. L'adresse retournée est au format Bech32 (ex: `8e1a...`).
@@ -448,6 +452,78 @@ const result = await client.burnNfts({
 
 ---
 
+### Gouvernance & Émission
+
+La gouvernance est ancrée dans le DAG : un changement de config peut être **proposé** (avec un palier et un timelock), puis **enacté** une fois le timelock écoulé, ou **annulé**. Les lectures sont publiques ; les écritures requièrent `adminToken`.
+
+#### Lectures publiques (aucun `adminToken` requis)
+
+```typescript
+// Propositions en attente (statut "pending")
+const pending = await client.getGovernancePending();
+// [{ proposal_id, tier, status: "pending", reason, announced_at_ms, enact_after_ms, update, proposal_block_id, enact_block_id, cancel_block_id }]
+
+// Propositions terminées (enactées ou annulées)
+const history = await client.getGovernanceHistory();
+
+// Blocs de gouvernance ancrés dans le DAG
+const { count, blocks } = await client.getGovernanceBlocks();
+// blocks: [{ block_id, kind: "proposal" | "enact" | "cancel", proposal_id, tier, status, update, reason, announced_at_ms, enact_after_ms }]
+```
+
+#### Actions admin (requièrent `adminToken`)
+
+```typescript
+// Proposer un changement de config (ici, le couloir d'émission)
+const proposal = await client.proposeGovernance({
+  update: { SetEmissionCorridor: { ceiling_bps: 1500, floor_bps: 0, target_bps: 1000, epoch_duration_sec: 86400 } },
+  tier: "constitution",          // "operator" | "policy" | "constitution" (minuscules)
+  reason: "raise emission ceiling for Q3",
+});
+// { status: "ok", proposal_id, block_id, tier, announced_at_ms, enact_after_ms }
+
+// Enacter une proposition dont le timelock est écoulé
+await client.enactProposal(proposal.proposal_id, "timelock elapsed");
+// { status: "ok", proposal_id, block_id }
+
+// Annuler une proposition en attente
+await client.cancelProposal(proposal.proposal_id);
+```
+
+#### `setConfig` — 200 (appliqué) vs 202 (timelocké)
+
+Un **durcissement** (ex: réduire un plafond, désactiver le mint) est appliqué instantanément ; un **assouplissement** est placé sous timelock de gouvernance. Le SDK expose les deux cas via une union discriminée sur `applied` — **un 202 n'est jamais traité comme un succès appliqué** :
+
+```typescript
+const r = await client.setConfig({ SetMintEnabled: { enabled: false } });
+if (r.applied) {
+  // HTTP 200 — en vigueur immédiatement
+  console.log("appliqué:", r.updateApplied, "bloc:", r.enactBlockId);
+} else {
+  // HTTP 202 — proposé, PAS encore en vigueur
+  console.log("timelocké, enact après", new Date(r.enactAfterMs), "via", r.proposalId);
+}
+```
+
+#### Codes d'erreur stables
+
+Le moteur renvoie ses erreurs au format `{ "code": NNNN, "message": "..." }`. Branchez sur le `code` numérique (stable), pas sur le message :
+
+```typescript
+import { ErrorCode, HttpError } from "@empereur-rouge/pms-sdk";
+
+try {
+  await client.enactProposal(proposalId);
+} catch (e) {
+  if (e instanceof HttpError && e.code === ErrorCode.GovernanceRejected) {
+    // 3071 — timelock non écoulé, proposition non en attente, ou id inconnu
+  }
+}
+// Codes notables : GovernanceRejected (3071), MintDisabled (5031), MissingAuth (1001), InvalidAuth (1002).
+```
+
+---
+
 ### API Avancée
 
 Pour les cas d'usage avancés (construction manuelle de blocs, chiffrement custom), importez depuis le module `advanced` :