@empereur-rouge/pms-sdk 0.5.0 → 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` :

package/dist/index.cjs

@@ -21,6 +21,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   DAY_MS: () => DAY_MS,
+  ErrorCode: () => ErrorCode,
+  HttpError: () => HttpError,
   PmsClient: () => PmsClient,
   PmsWallet: () => PmsWallet,
   decryptPayload: () => decryptPayload,
@@ -418,7 +420,25 @@ var DEFAULT_CONFIG = {
   enableRacing: true,
   retries: 2,
   perAttemptTimeoutMs: 4e3,
-  retryBaseDelayMs: 100
+  retryBaseDelayMs: 100,
+  // Vide par défaut : les méthodes admin lèvent une erreur explicite si
+  // appelées sans jeton (voir PmsClient.requireAdminToken).
+  adminToken: ""
+};
+var ErrorCode = {
+  /** En-tête d'authentification manquant (admin requis). */
+  MissingAuth: 1001,
+  /** Jeton d'authentification invalide. */
+  InvalidAuth: 1002,
+  /**
+   * Proposition de gouvernance rejetée (timelock non écoulé, proposition
+   * non en attente, ou identifiant inconnu). HTTP 409.
+   */
+  GovernanceRejected: 3071,
+  /** Émission native (mint) désactivée. HTTP 503. */
+  MintDisabled: 5031,
+  /** Erreur interne générique (dette : handler non encore migré). */
+  Internal: 9999
 };
 
 // src/crypto.ts
@@ -617,6 +637,204 @@ var PmsClient = class {
     return this.fetch("/v1/reserves/latest", void 0, { idempotent: true });
   }
   // ═══════════════════════════════════════════════════════════════════════
+  // Gouvernance — lectures publiques (GET, sans authentification)
+  // ═══════════════════════════════════════════════════════════════════════
+  /**
+   * Liste les propositions de gouvernance EN ATTENTE (statut `pending`).
+   *
+   * Lecture publique — aucun `adminToken` requis.
+   *
+   * @returns Le tableau des propositions en attente (vide si aucune).
+   *
+   * @example
+   * ```typescript
+   * const pending = await client.getGovernancePending();
+   * for (const p of pending) {
+   *     console.log(`${p.proposal_id} enacts after ${new Date(p.enact_after_ms)}`);
+   * }
+   * ```
+   */
+  async getGovernancePending() {
+    const res = await this.fetch(
+      "/v1/governance/pending",
+      void 0,
+      { idempotent: true }
+    );
+    return res.pending ?? [];
+  }
+  /**
+   * Liste les propositions de gouvernance TERMINÉES (enactées ou annulées).
+   *
+   * Lecture publique — aucun `adminToken` requis.
+   *
+   * @returns Le tableau de l'historique des propositions (vide si aucune).
+   */
+  async getGovernanceHistory() {
+    const res = await this.fetch(
+      "/v1/governance/history",
+      void 0,
+      { idempotent: true }
+    );
+    return res.history ?? [];
+  }
+  /**
+   * Liste les blocs de gouvernance ancrés dans le DAG (un par proposition,
+   * enactment, ou annulation).
+   *
+   * Lecture publique — aucun `adminToken` requis.
+   *
+   * @returns `{ count, blocks }` — le nombre et la liste des blocs.
+   */
+  async getGovernanceBlocks() {
+    return this.fetch(
+      "/v1/governance/blocks",
+      void 0,
+      { idempotent: true }
+    );
+  }
+  // ═══════════════════════════════════════════════════════════════════════
+  // Gouvernance — actions ADMIN (POST, requièrent adminToken)
+  // ═══════════════════════════════════════════════════════════════════════
+  /**
+   * Soumet une proposition de gouvernance ancrée dans le DAG.
+   *
+   * Méthode ADMIN — requiert `adminToken` dans la config du client
+   * (envoyé en `Authorization: Bearer <adminToken>`). Lève une erreur
+   * explicite avant tout appel réseau si le jeton est absent.
+   *
+   * @param req.update - Mise à jour de config à proposer.
+   * @param req.tier - Palier de gouvernance (minuscules, voir
+   *   [`GovernanceTier`]).
+   * @param req.reason - Raison libre (optionnelle).
+   * @returns `{ status, proposal_id, block_id, tier, announced_at_ms,
+   *   enact_after_ms }`.
+   *
+   * @example
+   * ```typescript
+   * const res = await client.proposeGovernance({
+   *     update: { SetEmissionCorridor: { ceiling_bps: 1500, floor_bps: 0, target_bps: 1000, epoch_duration_sec: 86400 } },
+   *     tier: "constitution",
+   *     reason: "raise emission ceiling for Q3",
+   * });
+   * console.log(res.proposal_id, "enacts after", new Date(res.enact_after_ms));
+   * ```
+   */
+  async proposeGovernance(req) {
+    return this.fetchAdmin("proposeGovernance", "/admin/governance/propose", {
+      method: "POST",
+      body: JSON.stringify({
+        update: req.update,
+        tier: req.tier,
+        reason: req.reason ?? ""
+      })
+    });
+  }
+  /**
+   * Enacte une proposition de gouvernance dont le timelock est écoulé.
+   *
+   * Méthode ADMIN — requiert `adminToken`. Le moteur rejette (HTTP 409,
+   * code [`ErrorCode.GovernanceRejected`] = 3071) si le timelock n'est pas
+   * écoulé, si la proposition n'est pas en attente, ou si l'identifiant est
+   * inconnu.
+   *
+   * @param proposalId - Identifiant de la proposition à enacter.
+   * @param reason - Raison libre (optionnelle).
+   * @returns `{ status, proposal_id, block_id }`.
+   */
+  async enactProposal(proposalId, reason) {
+    return this.fetchAdmin(
+      "enactProposal",
+      `/admin/governance/enact/${encodeURIComponent(proposalId)}`,
+      {
+        method: "POST",
+        body: JSON.stringify({ reason: reason ?? "" })
+      }
+    );
+  }
+  /**
+   * Annule une proposition de gouvernance en attente.
+   *
+   * Méthode ADMIN — requiert `adminToken`. Rejet HTTP 409 / code 3071 si la
+   * proposition n'est pas en attente ou si l'identifiant est inconnu.
+   *
+   * @param proposalId - Identifiant de la proposition à annuler.
+   * @param reason - Raison libre (optionnelle).
+   * @returns `{ status, proposal_id, block_id }`.
+   */
+  async cancelProposal(proposalId, reason) {
+    return this.fetchAdmin(
+      "cancelProposal",
+      `/admin/governance/cancel/${encodeURIComponent(proposalId)}`,
+      {
+        method: "POST",
+        body: JSON.stringify({ reason: reason ?? "" })
+      }
+    );
+  }
+  /**
+   * Applique (ou propose) une mise à jour de configuration.
+   *
+   * Méthode ADMIN — requiert `adminToken`. Le moteur distingue DEUX issues
+   * selon le sens du changement, et le SDK les EXPOSE explicitement via une
+   * union discriminée sur `applied` — un 202 n'est JAMAIS traité comme un
+   * succès appliqué :
+   * - **HTTP 200** (durcissement) → `{ applied: true, ... }` : la mise à
+   *   jour est instantanément en vigueur.
+   * - **HTTP 202** (assouplissement) → `{ applied: false, proposalId,
+   *   enactAfterMs, ... }` : la mise à jour est placée sous timelock de
+   *   gouvernance, PAS encore appliquée. Elle s'auto-enacte à l'expiration
+   *   du timelock, ou via [`enactProposal`].
+   *
+   * @param update - Mise à jour de config (envoyée brute, sans wrapper).
+   * @returns Une [`ConfigChangeResult`] discriminée sur `applied`.
+   *
+   * @example
+   * ```typescript
+   * const r = await client.setConfig({ SetMintEnabled: { enabled: false } });
+   * if (r.applied) {
+   *     console.log("appliqué instantanément:", r.updateApplied);
+   * } else {
+   *     console.log("timelocké, enact après", new Date(r.enactAfterMs));
+   * }
+   * ```
+   */
+  async setConfig(update) {
+    const { status, body } = await this.fetchAdminWithStatus(
+      "setConfig",
+      "/admin/config",
+      {
+        method: "POST",
+        body: JSON.stringify(update)
+      }
+    );
+    const isApplied = status === 200 && body.status !== "proposed";
+    if (isApplied) {
+      return {
+        applied: true,
+        status: "applied",
+        mode: body.mode ?? "",
+        updateApplied: body.update_applied ?? "",
+        tier: body.tier ?? "",
+        proposalId: body.proposal_id ?? "",
+        proposalBlockId: body.proposal_block_id ?? "",
+        enactBlockId: body.enact_block_id ?? "",
+        config: body.config ?? null
+      };
+    }
+    return {
+      applied: false,
+      status: "proposed",
+      mode: body.mode ?? "",
+      update: body.update ?? "",
+      tier: body.tier ?? "",
+      proposalId: body.proposal_id ?? "",
+      proposalBlockId: body.proposal_block_id ?? "",
+      announcedAtMs: body.announced_at_ms ?? 0,
+      enactAfterMs: body.enact_after_ms ?? 0,
+      message: body.message ?? ""
+    };
+  }
+  // ═══════════════════════════════════════════════════════════════════════
   // Wallet API (Custodial — Server-Side)
   // ═══════════════════════════════════════════════════════════════════════
   /**
@@ -1439,6 +1657,62 @@ var PmsClient = class {
   // ═══════════════════════════════════════════════════════════════════════
   // Helper HTTP
   // ═══════════════════════════════════════════════════════════════════════
+  /**
+   * @internal
+   * Garantit qu'un `adminToken` est configuré avant un appel admin.
+   * Lève une erreur claire (sans appel réseau) sinon.
+   */
+  requireAdminToken(method) {
+    const token = this.config.adminToken;
+    if (!token || token.trim() === "") {
+      throw new Error(
+        `PmsClient.${method}() requires an admin token. Set it via new PmsClient({ ..., adminToken: '<token>' }). Admin methods send it as 'Authorization: Bearer <adminToken>'. Public reads (getGovernancePending/History/Blocks) do NOT need it.`
+      );
+    }
+    return token;
+  }
+  /**
+   * @internal
+   * Effectue un appel admin authentifié (en-tête `Authorization: Bearer`).
+   *
+   * Les écritures admin ne sont PAS idempotentes — pas de retry automatique
+   * (single-attempt via la branche non-idempotente de `fetchUrl`). L'auth est
+   * injectée par appel (pas dans le bloc d'en-têtes partagé de `fetchOnce`)
+   * pour éviter de fuiter le jeton admin vers des nœuds découverts/seeds lors
+   * du racing — cf. `submitBlockRacing`. `method` ne sert qu'au libellé de
+   * l'erreur "jeton manquant".
+   */
+  async fetchAdmin(method, path, init) {
+    return this.fetchUrl(this.config.nodeUrl, path, this.withAdminAuth(method, init));
+  }
+  /**
+   * @internal
+   * Variante d'appel admin qui expose le STATUT HTTP en plus du corps parsé.
+   * Nécessaire pour [`setConfig`], qui doit distinguer 200 (applied) de 202
+   * (proposed) — deux corps de réponse différents pour deux issues. Délègue à
+   * la même primitive `fetchOnceWithStatus` que tous les autres appels, donc
+   * hérite du merge de signal et du tagging d'abort sans duplication.
+   */
+  async fetchAdminWithStatus(method, path, init) {
+    const url = `${this.config.nodeUrl.replace(/\/$/, "")}/${path.replace(/^\//, "")}`;
+    const auth = this.withAdminAuth(method, init);
+    return this.fetchOnceWithStatus(url, auth, this.config.timeout, auth.signal ?? void 0);
+  }
+  /**
+   * @internal
+   * Vérifie la présence du jeton admin (sinon erreur claire, sans réseau) et
+   * injecte l'en-tête `Authorization: Bearer <token>` dans un RequestInit.
+   */
+  withAdminAuth(method, init) {
+    const token = this.requireAdminToken(method);
+    return {
+      ...init,
+      headers: {
+        ...init?.headers,
+        "Authorization": `Bearer ${token}`
+      }
+    };
+  }
   async fetch(path, init, opts) {
     return this.fetchUrl(this.config.nodeUrl, path, init, opts);
   }
@@ -1446,8 +1720,26 @@ var PmsClient = class {
    * Single-attempt HTTP request. Throws a tagged error on transient conditions
    * (network failure, per-attempt abort, 5xx) so the retry loop can decide
    * whether to retry. 4xx and other non-2xx are thrown as fatal HttpError.
+   *
+   * Thin wrapper over `fetchOnceWithStatus` that discards the HTTP status —
+   * every caller that only needs the parsed body goes through here.
    */
   async fetchOnce(url, init, attemptTimeoutMs, outerSignal) {
+    return (await this.fetchOnceWithStatus(url, init, attemptTimeoutMs, outerSignal)).body;
+  }
+  /**
+   * Single-attempt HTTP request returning BOTH the numeric HTTP status and the
+   * parsed body. The shared fetch primitive: applies the default headers
+   * (`Content-Type`, public `X-API-Key`), merges the caller's signal with the
+   * per-attempt timeout, tags per-attempt aborts as `PerAttemptTimeoutError`
+   * (so the retry loop can act on them), and constructs `HttpError` on non-2xx.
+   *
+   * NOTE: admin `Authorization: Bearer` is NOT injected here — it is added
+   * per-admin-call by `withAdminAuth` so the admin token never leaks to
+   * discovered/seed nodes during `submitBlockRacing`. Only the public,
+   * scoped `X-API-Key` is broadcast.
+   */
+  async fetchOnceWithStatus(url, init, attemptTimeoutMs, outerSignal) {
     const attemptController = new AbortController();
     const attemptTimer = setTimeout(() => attemptController.abort(), attemptTimeoutMs);
     const signal = mergeSignalsAny(attemptController.signal, outerSignal);
@@ -1466,14 +1758,14 @@ var PmsClient = class {
       if (!res.ok) {
         const text2 = await res.text().catch(() => "");
         const retryAfter = res.headers?.get?.("Retry-After") ?? null;
-        throw new HttpError(res.status, `HTTP ${res.status} (${url}): ${text2}`, retryAfter);
+        throw new HttpError(res.status, `HTTP ${res.status} (${url}): ${text2}`, retryAfter, text2);
       }
       const text = await res.text();
       if (!text) {
-        return {};
+        return { status: res.status, body: {} };
       }
       try {
-        return JSON.parse(text);
+        return { status: res.status, body: JSON.parse(text) };
       } catch {
         throw new Error(`Invalid JSON response: ${text.substring(0, 50)}...`);
       }
@@ -1536,11 +1828,30 @@ var PmsClient = class {
 var HttpError = class extends Error {
   status;
   retryAfter;
-  constructor(status, message, retryAfter) {
+  /** Raw response body text (may be empty). */
+  body;
+  /** Stable numeric error code parsed from `{code,message}`, if present. */
+  code;
+  /** Engine-provided message from `{code,message}`, if present. */
+  engineMessage;
+  constructor(status, message, retryAfter, body = "") {
     super(message);
     this.name = "HttpError";
     this.status = status;
     this.retryAfter = retryAfter;
+    this.body = body;
+    if (body) {
+      try {
+        const parsed = JSON.parse(body);
+        if (parsed && typeof parsed === "object" && typeof parsed.code === "number") {
+          this.code = parsed.code;
+          if (typeof parsed.message === "string") {
+            this.engineMessage = parsed.message;
+          }
+        }
+      } catch {
+      }
+    }
   }
 };
 var PerAttemptTimeoutError = class extends Error {
@@ -1610,6 +1921,8 @@ function mergeAbortSignals(a, b) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DAY_MS,
+  ErrorCode,
+  HttpError,
   PmsClient,
   PmsWallet,
   decryptPayload,