blue-js-sdk 2.0.1 → 2.0.3

package/ai-path/index.js

@@ -58,8 +58,17 @@ export {
   rpcQueryBalance,
   rpcQueryNode,
   // v1.5.2: Session recovery (referenced in docs but was missing from exports)
-  recoverOrphans,
+  recoverOrphans as recoverSession,
+  // v2.0.2: Plan operations for AI agents using subscription-based access
+  connectViaSubscription,
+  connectViaPlan,
+  subscribeToPlan,
+  hasActiveSubscription,
+  querySubscriptions,
+  queryPlanNodes,
+  queryFeeGrants,
+  buildFeeGrantMsg,
+  broadcastWithFeeGrant,
+  rpcQueryNodesForPlan,
+  rpcQuerySubscriptionsForAccount,
 } from '../index.js';
-
-// Re-export recoverOrphans as recoverSession (the name used in ai-path docs)
-export { recoverOrphans as recoverSession };

package/chain/client.js

@@ -43,7 +43,8 @@ import {
   encodeMsgEndLease,
 } from '../plan-operations.js';
 
-import { GAS_PRICE } from '../defaults.js';
+import { GAS_PRICE, RPC_ENDPOINTS } from '../defaults.js';
+import { ValidationError, ChainError, ErrorCodes } from '../errors.js';
 
 // ─── CosmJS Registry ─────────────────────────────────────────────────────────
 
@@ -107,12 +108,59 @@ export function buildRegistry() {
 /**
  * Create a SigningStargateClient connected to Sentinel RPC.
  * Gas price: from defaults.js GAS_PRICE (chain minimum).
+ *
+ * Signatures:
+ *   createClient(rpcUrl, wallet)  — classic: connect to specific RPC with existing wallet
+ *   createClient(mnemonic)        — convenience: create wallet from mnemonic, try RPC endpoints with failover
+ *
+ * @param {string} rpcUrlOrMnemonic - Either an RPC URL (https://...) or a BIP39 mnemonic
+ * @param {DirectSecp256k1HdWallet} [wallet] - Wallet object (required when first arg is RPC URL)
+ * @returns {Promise<SigningStargateClient>} Connected signing client with full Sentinel registry
  */
-export async function createClient(rpcUrl, wallet) {
-  return SigningStargateClient.connectWithSigner(rpcUrl, wallet, {
-    gasPrice: GasPrice.fromString(GAS_PRICE),
-    registry: buildRegistry(),
-  });
+export async function createClient(rpcUrlOrMnemonic, wallet) {
+  // Classic call: createClient(rpcUrl, wallet)
+  if (wallet) {
+    return SigningStargateClient.connectWithSigner(rpcUrlOrMnemonic, wallet, {
+      gasPrice: GasPrice.fromString(GAS_PRICE),
+      registry: buildRegistry(),
+    });
+  }
+
+  // If first arg looks like a URL, it's a missing wallet — throw helpful error
+  if (typeof rpcUrlOrMnemonic === 'string' && /^(https?|wss?):\/\//i.test(rpcUrlOrMnemonic)) {
+    throw new ValidationError(ErrorCodes.INVALID_MNEMONIC,
+      'createClient(rpcUrl, wallet): wallet parameter is required when passing an RPC URL. ' +
+      'Use createClient(mnemonic) for convenience, or createClient(rpcUrl, wallet) with an existing wallet.',
+      { value: rpcUrlOrMnemonic });
+  }
+
+  // Convenience call: createClient(mnemonic) — create wallet + try RPC endpoints
+  // Lazy import to avoid circular dependency
+  const { createWallet, validateMnemonic } = await import('./wallet.js');
+  validateMnemonic(rpcUrlOrMnemonic, 'createClient');
+  const { wallet: derivedWallet } = await createWallet(rpcUrlOrMnemonic);
+  const registry = buildRegistry();
+  const gasPrice = GasPrice.fromString(GAS_PRICE);
+
+  // Try each RPC endpoint until one connects
+  const errors = [];
+  for (const ep of RPC_ENDPOINTS) {
+    try {
+      const client = await SigningStargateClient.connectWithSigner(ep.url, derivedWallet, {
+        gasPrice,
+        registry,
+      });
+      return client;
+    } catch (err) {
+      errors.push({ endpoint: ep.url, name: ep.name, error: err.message });
+    }
+  }
+
+  // All endpoints failed
+  const tried = errors.map(e => `  ${e.name} (${e.endpoint}): ${e.error}`).join('\n');
+  throw new ChainError('ALL_ENDPOINTS_FAILED',
+    `createClient(mnemonic): failed to connect to all ${RPC_ENDPOINTS.length} RPC endpoints:\n${tried}`,
+    { endpoints: errors });
 }
 
 // ─── All Type URL Constants ──────────────────────────────────────────────────

package/cosmjs-setup.js

@@ -50,7 +50,7 @@ import {
   encodeMsgStartLease,
   encodeMsgEndLease,
 } from './plan-operations.js';
-import { GAS_PRICE, LCD_ENDPOINTS, tryWithFallback } from './defaults.js';
+import { GAS_PRICE, RPC_ENDPOINTS, LCD_ENDPOINTS, tryWithFallback } from './defaults.js';
 import { ValidationError, NodeError, ChainError, ErrorCodes } from './errors.js';
 import path from 'path';
 import os from 'os';
@@ -216,12 +216,57 @@ export function buildRegistry() {
 /**
  * Create a SigningStargateClient connected to Sentinel RPC.
  * Gas price: from defaults.js GAS_PRICE (chain minimum).
- */
-export async function createClient(rpcUrl, wallet) {
-  return SigningStargateClient.connectWithSigner(rpcUrl, wallet, {
-    gasPrice: GasPrice.fromString(GAS_PRICE),
-    registry: buildRegistry(),
-  });
+ *
+ * Signatures:
+ *   createClient(rpcUrl, wallet)  — classic: connect to specific RPC with existing wallet
+ *   createClient(mnemonic)        — convenience: create wallet from mnemonic, try RPC endpoints with failover
+ *
+ * @param {string} rpcUrlOrMnemonic - Either an RPC URL (https://...) or a BIP39 mnemonic
+ * @param {DirectSecp256k1HdWallet} [wallet] - Wallet object (required when first arg is RPC URL)
+ * @returns {Promise<SigningStargateClient>} Connected signing client with full Sentinel registry
+ */
+export async function createClient(rpcUrlOrMnemonic, wallet) {
+  // Classic call: createClient(rpcUrl, wallet)
+  if (wallet) {
+    return SigningStargateClient.connectWithSigner(rpcUrlOrMnemonic, wallet, {
+      gasPrice: GasPrice.fromString(GAS_PRICE),
+      registry: buildRegistry(),
+    });
+  }
+
+  // If first arg looks like a URL, it's a missing wallet — throw helpful error
+  if (typeof rpcUrlOrMnemonic === 'string' && /^(https?|wss?):\/\//i.test(rpcUrlOrMnemonic)) {
+    throw new ValidationError(ErrorCodes.INVALID_MNEMONIC,
+      'createClient(rpcUrl, wallet): wallet parameter is required when passing an RPC URL. ' +
+      'Use createClient(mnemonic) for convenience, or createClient(rpcUrl, wallet) with an existing wallet.',
+      { value: rpcUrlOrMnemonic });
+  }
+
+  // Convenience call: createClient(mnemonic) — create wallet + try RPC endpoints
+  validateMnemonic(rpcUrlOrMnemonic, 'createClient');
+  const { wallet: derivedWallet } = await createWallet(rpcUrlOrMnemonic);
+  const registry = buildRegistry();
+  const gasPrice = GasPrice.fromString(GAS_PRICE);
+
+  // Try each RPC endpoint until one connects
+  const errors = [];
+  for (const ep of RPC_ENDPOINTS) {
+    try {
+      const client = await SigningStargateClient.connectWithSigner(ep.url, derivedWallet, {
+        gasPrice,
+        registry,
+      });
+      return client;
+    } catch (err) {
+      errors.push({ endpoint: ep.url, name: ep.name, error: err.message });
+    }
+  }
+
+  // All endpoints failed
+  const tried = errors.map(e => `  ${e.name} (${e.endpoint}): ${e.error}`).join('\n');
+  throw new ChainError('ALL_ENDPOINTS_FAILED',
+    `createClient(mnemonic): failed to connect to all ${RPC_ENDPOINTS.length} RPC endpoints:\n${tried}`,
+    { endpoints: errors });
 }
 
 // ─── TX Helpers ──────────────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blue-js-sdk",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "Decentralized VPN SDK for the Sentinel P2P bandwidth network. WireGuard + V2Ray tunnels, Cosmos blockchain, 900+ nodes. Tested on Windows. macOS/Linux support included but untested.",
   "type": "module",
   "main": "index.js",