@empereur-rouge/pms-sdk 0.5.0 → 0.7.1

package/dist/index.js

@@ -378,7 +378,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
@@ -577,6 +595,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)
   // ═══════════════════════════════════════════════════════════════════════
   /**
@@ -1399,6 +1615,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);
   }
@@ -1406,8 +1678,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);
@@ -1426,14 +1716,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)}...`);
       }
@@ -1496,11 +1786,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 {
@@ -1569,6 +1878,8 @@ function mergeAbortSignals(a, b) {
 }
 export {
   DAY_MS,
+  ErrorCode,
+  HttpError,
   PmsClient,
   PmsWallet,
   decryptPayload,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@empereur-rouge/pms-sdk",
-    "version": "0.5.0",
+    "version": "0.7.1",
     "description": "TypeScript SDK for PMS (Planetary Monetary System) — wallet management, transactions, NFTs, and DAG interactions",
     "author": "empereur-rouge",
     "license": "MIT",