@empereur-rouge/pms-sdk 0.1.0 → 0.3.0

package/README.md

@@ -31,9 +31,10 @@ const wallet = PmsWallet.generate();
 console.log("Mnemonic:", wallet.mnemonic);
 console.log("Address:", wallet.address);
 
-// 2. Connecter au réseau
+// 2. Connecter au réseau (clé API obligatoire)
 const client = new PmsClient({ 
-  nodeUrl: "https://node.pms.network" 
+  nodeUrl: "https://node.pms.network",
+  apiKey: "pk_live_votre_cle_ici",
 });
 
 // 3. Consulter la balance
@@ -116,6 +117,7 @@ Le client permet d'interagir avec l'API REST des nœuds PMS.
 ```typescript
 const client = new PmsClient({
   nodeUrl: "https://node.pms.network",  // URL du nœud principal
+  apiKey: "pk_live_votre_cle_ici",       // Clé API (obligatoire)
   seedNodes: [                           // Optionnel: nœuds de secours
     "https://node2.pms.network",
     "https://node3.pms.network",
@@ -127,6 +129,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.
+
 #### Méthodes de Lecture
 
 ```typescript
@@ -480,6 +485,7 @@ Cela améliore :
 // Désactiver si non souhaité
 const client = new PmsClient({
   nodeUrl: "...",
+  apiKey: "pk_live_...",
   enableRacing: false,
 });
 ```

package/dist/index.cjs

@@ -331,6 +331,11 @@ var PmsClient = class {
    * @param config.seedNodes - Liste des nœuds de seed
    */
   constructor(config) {
+    if (!config.apiKey || config.apiKey.trim() === "") {
+      throw new Error(
+        "PmsClient requires an API key. Get yours at https://dashboard.pms.network or contact your administrator. Usage: new PmsClient({ nodeUrl: '...', apiKey: 'pk_live_...' })"
+      );
+    }
     this.config = {
       ...DEFAULT_CONFIG,
       seedNodes: config.seedNodes ?? [],
@@ -410,6 +415,68 @@ var PmsClient = class {
     return res.utxos ?? [];
   }
   // ═══════════════════════════════════════════════════════════════════════
+  // Wallet API (Custodial — Server-Side)
+  // ═══════════════════════════════════════════════════════════════════════
+  /**
+   * Crée un nouveau wallet côté serveur (custodial).
+   * Le serveur génère le wallet et retourne toutes les clés + adresse Bech32.
+   *
+   * @returns Wallet complet avec adresse, clés et mnemonic
+   *
+   * @example
+   * ```typescript
+   * const wallet = await client.createWallet();
+   * console.log(wallet.address);        // "8e1a..."
+   * console.log(wallet.mnemonic_words); // ["gain", "space", ...]
+   * ```
+   */
+  async createWallet() {
+    return this.fetch("/v1/wallet/create", {
+      method: "POST",
+      body: JSON.stringify({})
+    });
+  }
+  /**
+   * Restaure un wallet depuis une phrase mnémonique BIP39 (24 mots).
+   *
+   * @param mnemonic - 24 mots BIP39 séparés par des espaces
+   * @returns Wallet restauré avec adresse, clés et mnemonic
+   *
+   * @example
+   * ```typescript
+   * const wallet = await client.restoreFromMnemonic(
+   *     "gain space color filter buzz bind side before sauce twist slam history chief patch desk chunk way oblige output turtle purchase scare token rapid"
+   * );
+   * console.log(wallet.address); // "8e1a..."
+   * ```
+   */
+  async restoreFromMnemonic(mnemonic) {
+    return this.fetch("/v1/wallet/restore/mnemonic", {
+      method: "POST",
+      body: JSON.stringify({ mnemonic })
+    });
+  }
+  /**
+   * Restaure un wallet depuis une clé privée hexadécimale.
+   *
+   * @param privateKeyHex - Clé privée hex (64 caractères = 32 bytes)
+   * @returns Wallet restauré avec adresse et clés (sans mnemonic)
+   *
+   * @example
+   * ```typescript
+   * const wallet = await client.restoreFromPrivateKey(
+   *     "da5334ad57455d74e5150e4eb06398ce9cf27762b6f29eac7f82f178bee07406"
+   * );
+   * console.log(wallet.address); // "8e1a..."
+   * ```
+   */
+  async restoreFromPrivateKey(privateKeyHex) {
+    return this.fetch("/v1/wallet/restore/private-key", {
+      method: "POST",
+      body: JSON.stringify({ private_key_hex: privateKeyHex })
+    });
+  }
+  // ═══════════════════════════════════════════════════════════════════════
   // Préparation de Transaction (Server-Side)
   // ═══════════════════════════════════════════════════════════════════════
   /**
@@ -1027,6 +1094,9 @@ var PmsClient = class {
         ...init,
         headers: {
           "Content-Type": "application/json",
+          // Injection automatique de la clé API dans chaque requête.
+          // Le serveur PMS vérifie ce header pour autoriser l'accès.
+          "X-API-Key": this.config.apiKey,
           ...init?.headers
         },
         signal

package/dist/index.d.cts

@@ -460,6 +460,21 @@ interface NftResponse {
     /** @deprecated Les métadonnées sont maintenant chiffrées dans le bloc source */
     metadata?: NftMetadata;
 }
+/** Réponse de création/restauration de wallet (server-side) */
+interface WalletResponse {
+    /** Adresse Bech32 du wallet */
+    address: string;
+    /** Clé privée en base64 */
+    private_key_b64: string;
+    /** Clé privée en hex (64 chars) */
+    private_key_hex: string;
+    /** Clé publique secp256k1 non-compressée (hex) */
+    public_key_hex: string;
+    /** Clé publique X25519 (hex) */
+    x25519_pub_hex: string;
+    /** Mots mnémoniques (24 mots, absent si restauré depuis clé privée) */
+    mnemonic_words?: string[];
+}
 /** Balance d'une adresse */
 interface BalanceInfo {
     /** Adresse */
@@ -473,6 +488,14 @@ interface BalanceInfo {
 interface PmsClientConfig {
     /** URL du nœud principal (ex: "https://node.pms.network") */
     nodeUrl: string;
+    /**
+     * Clé d'API pour authentifier les requêtes.
+     * Obligatoire pour accéder à l'API PMS.
+     * Obtenue depuis le dashboard PMS ou fournie par l'administrateur.
+     *
+     * Exemple: "pk_live_abc123..." ou "pk_test_xyz789..."
+     */
+    apiKey: string;
     /** URLs des noeuds seeds (optionnel, pour racing et fallback) */
     seedNodes?: string[];
     /** ID du réseau (défaut: "pms-mainnet") */
@@ -594,6 +617,50 @@ declare class PmsClient {
      * Récupère les UTXOs d'une adresse.
      */
     getUtxos(address: string): Promise<Utxo[]>;
+    /**
+     * Crée un nouveau wallet côté serveur (custodial).
+     * Le serveur génère le wallet et retourne toutes les clés + adresse Bech32.
+     *
+     * @returns Wallet complet avec adresse, clés et mnemonic
+     *
+     * @example
+     * ```typescript
+     * const wallet = await client.createWallet();
+     * console.log(wallet.address);        // "8e1a..."
+     * console.log(wallet.mnemonic_words); // ["gain", "space", ...]
+     * ```
+     */
+    createWallet(): Promise<WalletResponse>;
+    /**
+     * Restaure un wallet depuis une phrase mnémonique BIP39 (24 mots).
+     *
+     * @param mnemonic - 24 mots BIP39 séparés par des espaces
+     * @returns Wallet restauré avec adresse, clés et mnemonic
+     *
+     * @example
+     * ```typescript
+     * const wallet = await client.restoreFromMnemonic(
+     *     "gain space color filter buzz bind side before sauce twist slam history chief patch desk chunk way oblige output turtle purchase scare token rapid"
+     * );
+     * console.log(wallet.address); // "8e1a..."
+     * ```
+     */
+    restoreFromMnemonic(mnemonic: string): Promise<WalletResponse>;
+    /**
+     * Restaure un wallet depuis une clé privée hexadécimale.
+     *
+     * @param privateKeyHex - Clé privée hex (64 caractères = 32 bytes)
+     * @returns Wallet restauré avec adresse et clés (sans mnemonic)
+     *
+     * @example
+     * ```typescript
+     * const wallet = await client.restoreFromPrivateKey(
+     *     "da5334ad57455d74e5150e4eb06398ce9cf27762b6f29eac7f82f178bee07406"
+     * );
+     * console.log(wallet.address); // "8e1a..."
+     * ```
+     */
+    restoreFromPrivateKey(privateKeyHex: string): Promise<WalletResponse>;
     /**
      * Prépare une transaction de transfert via le serveur.
      * Le serveur sélectionne les UTXOs et calcule les frais.
@@ -848,4 +915,4 @@ declare function formatAmount(sats: bigint): string;
  */
 declare function decryptPayload(encrypted: EncryptedPayload, recipientPrivateKeyHex: string): string;
 
-export { type BalanceInfo, type Block, type BurnNftResponse, type CoordinatorInfoResponse, type CubeAttributes, type HistoryItem, type MintCubeResponse, type NftMetadata, type NftResponse, PmsClient, type PmsClientConfig, PmsWallet, type PrepareTxRequest, type PrepareTxResponse, type RuntimeConfig, type SubmitResponse, type SupplyInfo, type TokenMetadata, type Utxo, type UtxoDetail, type WalletHistoryResp, decryptPayload, formatAmount, fromHex, isValidMnemonic, parseAmount, toHex };
+export { type BalanceInfo, type Block, type BurnNftResponse, type CoordinatorInfoResponse, type CubeAttributes, type HistoryItem, type MintCubeResponse, type NftMetadata, type NftResponse, PmsClient, type PmsClientConfig, PmsWallet, type PrepareTxRequest, type PrepareTxResponse, type RuntimeConfig, type SubmitResponse, type SupplyInfo, type TokenMetadata, type Utxo, type UtxoDetail, type WalletHistoryResp, type WalletResponse, decryptPayload, formatAmount, fromHex, isValidMnemonic, parseAmount, toHex };

package/dist/index.d.ts

@@ -460,6 +460,21 @@ interface NftResponse {
     /** @deprecated Les métadonnées sont maintenant chiffrées dans le bloc source */
     metadata?: NftMetadata;
 }
+/** Réponse de création/restauration de wallet (server-side) */
+interface WalletResponse {
+    /** Adresse Bech32 du wallet */
+    address: string;
+    /** Clé privée en base64 */
+    private_key_b64: string;
+    /** Clé privée en hex (64 chars) */
+    private_key_hex: string;
+    /** Clé publique secp256k1 non-compressée (hex) */
+    public_key_hex: string;
+    /** Clé publique X25519 (hex) */
+    x25519_pub_hex: string;
+    /** Mots mnémoniques (24 mots, absent si restauré depuis clé privée) */
+    mnemonic_words?: string[];
+}
 /** Balance d'une adresse */
 interface BalanceInfo {
     /** Adresse */
@@ -473,6 +488,14 @@ interface BalanceInfo {
 interface PmsClientConfig {
     /** URL du nœud principal (ex: "https://node.pms.network") */
     nodeUrl: string;
+    /**
+     * Clé d'API pour authentifier les requêtes.
+     * Obligatoire pour accéder à l'API PMS.
+     * Obtenue depuis le dashboard PMS ou fournie par l'administrateur.
+     *
+     * Exemple: "pk_live_abc123..." ou "pk_test_xyz789..."
+     */
+    apiKey: string;
     /** URLs des noeuds seeds (optionnel, pour racing et fallback) */
     seedNodes?: string[];
     /** ID du réseau (défaut: "pms-mainnet") */
@@ -594,6 +617,50 @@ declare class PmsClient {
      * Récupère les UTXOs d'une adresse.
      */
     getUtxos(address: string): Promise<Utxo[]>;
+    /**
+     * Crée un nouveau wallet côté serveur (custodial).
+     * Le serveur génère le wallet et retourne toutes les clés + adresse Bech32.
+     *
+     * @returns Wallet complet avec adresse, clés et mnemonic
+     *
+     * @example
+     * ```typescript
+     * const wallet = await client.createWallet();
+     * console.log(wallet.address);        // "8e1a..."
+     * console.log(wallet.mnemonic_words); // ["gain", "space", ...]
+     * ```
+     */
+    createWallet(): Promise<WalletResponse>;
+    /**
+     * Restaure un wallet depuis une phrase mnémonique BIP39 (24 mots).
+     *
+     * @param mnemonic - 24 mots BIP39 séparés par des espaces
+     * @returns Wallet restauré avec adresse, clés et mnemonic
+     *
+     * @example
+     * ```typescript
+     * const wallet = await client.restoreFromMnemonic(
+     *     "gain space color filter buzz bind side before sauce twist slam history chief patch desk chunk way oblige output turtle purchase scare token rapid"
+     * );
+     * console.log(wallet.address); // "8e1a..."
+     * ```
+     */
+    restoreFromMnemonic(mnemonic: string): Promise<WalletResponse>;
+    /**
+     * Restaure un wallet depuis une clé privée hexadécimale.
+     *
+     * @param privateKeyHex - Clé privée hex (64 caractères = 32 bytes)
+     * @returns Wallet restauré avec adresse et clés (sans mnemonic)
+     *
+     * @example
+     * ```typescript
+     * const wallet = await client.restoreFromPrivateKey(
+     *     "da5334ad57455d74e5150e4eb06398ce9cf27762b6f29eac7f82f178bee07406"
+     * );
+     * console.log(wallet.address); // "8e1a..."
+     * ```
+     */
+    restoreFromPrivateKey(privateKeyHex: string): Promise<WalletResponse>;
     /**
      * Prépare une transaction de transfert via le serveur.
      * Le serveur sélectionne les UTXOs et calcule les frais.
@@ -848,4 +915,4 @@ declare function formatAmount(sats: bigint): string;
  */
 declare function decryptPayload(encrypted: EncryptedPayload, recipientPrivateKeyHex: string): string;
 
-export { type BalanceInfo, type Block, type BurnNftResponse, type CoordinatorInfoResponse, type CubeAttributes, type HistoryItem, type MintCubeResponse, type NftMetadata, type NftResponse, PmsClient, type PmsClientConfig, PmsWallet, type PrepareTxRequest, type PrepareTxResponse, type RuntimeConfig, type SubmitResponse, type SupplyInfo, type TokenMetadata, type Utxo, type UtxoDetail, type WalletHistoryResp, decryptPayload, formatAmount, fromHex, isValidMnemonic, parseAmount, toHex };
+export { type BalanceInfo, type Block, type BurnNftResponse, type CoordinatorInfoResponse, type CubeAttributes, type HistoryItem, type MintCubeResponse, type NftMetadata, type NftResponse, PmsClient, type PmsClientConfig, PmsWallet, type PrepareTxRequest, type PrepareTxResponse, type RuntimeConfig, type SubmitResponse, type SupplyInfo, type TokenMetadata, type Utxo, type UtxoDetail, type WalletHistoryResp, type WalletResponse, decryptPayload, formatAmount, fromHex, isValidMnemonic, parseAmount, toHex };

package/dist/index.js

@@ -298,6 +298,11 @@ var PmsClient = class {
    * @param config.seedNodes - Liste des nœuds de seed
    */
   constructor(config) {
+    if (!config.apiKey || config.apiKey.trim() === "") {
+      throw new Error(
+        "PmsClient requires an API key. Get yours at https://dashboard.pms.network or contact your administrator. Usage: new PmsClient({ nodeUrl: '...', apiKey: 'pk_live_...' })"
+      );
+    }
     this.config = {
       ...DEFAULT_CONFIG,
       seedNodes: config.seedNodes ?? [],
@@ -377,6 +382,68 @@ var PmsClient = class {
     return res.utxos ?? [];
   }
   // ═══════════════════════════════════════════════════════════════════════
+  // Wallet API (Custodial — Server-Side)
+  // ═══════════════════════════════════════════════════════════════════════
+  /**
+   * Crée un nouveau wallet côté serveur (custodial).
+   * Le serveur génère le wallet et retourne toutes les clés + adresse Bech32.
+   *
+   * @returns Wallet complet avec adresse, clés et mnemonic
+   *
+   * @example
+   * ```typescript
+   * const wallet = await client.createWallet();
+   * console.log(wallet.address);        // "8e1a..."
+   * console.log(wallet.mnemonic_words); // ["gain", "space", ...]
+   * ```
+   */
+  async createWallet() {
+    return this.fetch("/v1/wallet/create", {
+      method: "POST",
+      body: JSON.stringify({})
+    });
+  }
+  /**
+   * Restaure un wallet depuis une phrase mnémonique BIP39 (24 mots).
+   *
+   * @param mnemonic - 24 mots BIP39 séparés par des espaces
+   * @returns Wallet restauré avec adresse, clés et mnemonic
+   *
+   * @example
+   * ```typescript
+   * const wallet = await client.restoreFromMnemonic(
+   *     "gain space color filter buzz bind side before sauce twist slam history chief patch desk chunk way oblige output turtle purchase scare token rapid"
+   * );
+   * console.log(wallet.address); // "8e1a..."
+   * ```
+   */
+  async restoreFromMnemonic(mnemonic) {
+    return this.fetch("/v1/wallet/restore/mnemonic", {
+      method: "POST",
+      body: JSON.stringify({ mnemonic })
+    });
+  }
+  /**
+   * Restaure un wallet depuis une clé privée hexadécimale.
+   *
+   * @param privateKeyHex - Clé privée hex (64 caractères = 32 bytes)
+   * @returns Wallet restauré avec adresse et clés (sans mnemonic)
+   *
+   * @example
+   * ```typescript
+   * const wallet = await client.restoreFromPrivateKey(
+   *     "da5334ad57455d74e5150e4eb06398ce9cf27762b6f29eac7f82f178bee07406"
+   * );
+   * console.log(wallet.address); // "8e1a..."
+   * ```
+   */
+  async restoreFromPrivateKey(privateKeyHex) {
+    return this.fetch("/v1/wallet/restore/private-key", {
+      method: "POST",
+      body: JSON.stringify({ private_key_hex: privateKeyHex })
+    });
+  }
+  // ═══════════════════════════════════════════════════════════════════════
   // Préparation de Transaction (Server-Side)
   // ═══════════════════════════════════════════════════════════════════════
   /**
@@ -994,6 +1061,9 @@ var PmsClient = class {
         ...init,
         headers: {
           "Content-Type": "application/json",
+          // Injection automatique de la clé API dans chaque requête.
+          // Le serveur PMS vérifie ce header pour autoriser l'accès.
+          "X-API-Key": this.config.apiKey,
           ...init?.headers
         },
         signal

package/package.json

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