blue-js-sdk 2.1.0 → 2.1.1

package/ai-path/cli.js

@@ -125,6 +125,9 @@ function showHelp() {
   console.log(`  --protocol <type>   Protocol: wireguard or v2ray`);
   console.log(`  --dns <preset>      DNS: google, cloudflare, or hns (Handshake)`);
   console.log(`  --node <address>    Connect to specific node (sentnode1...)`);
+  console.log(`  --subscription <id> Connect via operator-provisioned subscription`);
+  console.log(`  --plan <id>         Connect via plan (subscribe + start session)`);
+  console.log(`  --fee-granter <addr> Operator address that pays gas (sent1...)`);
   console.log('');
   console.log(`${c.bold}NODES OPTIONS${c.reset}`);
   console.log(`  --country <code>    Filter by country`);
@@ -143,6 +146,10 @@ function showHelp() {
   console.log(`  sentinel-ai connect --country DE --protocol wireguard`);
   console.log(`  sentinel-ai connect --node sentnode1abc...`);
   console.log('');
+  console.log(`  ${c.dim}# Connect via subscription (operator-provisioned, zero P2P needed)${c.reset}`);
+  console.log(`  sentinel-ai connect --subscription 1165072 --fee-granter sent1operator...`);
+  console.log(`  sentinel-ai connect --plan 42 --fee-granter sent1operator...`);
+  console.log('');
   console.log(`  ${c.dim}# List nodes${c.reset}`);
   console.log(`  sentinel-ai nodes --country US --limit 10`);
   console.log('');
@@ -295,12 +302,18 @@ async function cmdConnect(flags) {
   if (flags.protocol) opts.protocol = flags.protocol;
   if (flags.dns) opts.dns = flags.dns;
   if (flags.node) opts.nodeAddress = flags.node;
+  if (flags.subscription) opts.subscriptionId = flags.subscription;
+  if (flags.plan) opts.planId = flags.plan;
+  if (flags['fee-granter']) opts.feeGranter = flags['fee-granter'];
 
   console.log(`${info} Connecting to Sentinel dVPN...`);
   if (flags.country) console.log(`  Country:  ${c.cyan}${flags.country}${c.reset}`);
   if (flags.protocol) console.log(`  Protocol: ${c.cyan}${flags.protocol}${c.reset}`);
   if (flags.dns) console.log(`  DNS:      ${c.cyan}${flags.dns}${c.reset}`);
   if (flags.node) console.log(`  Node:     ${c.cyan}${flags.node}${c.reset}`);
+  if (flags.subscription) console.log(`  Subscription: ${c.cyan}${flags.subscription}${c.reset}`);
+  if (flags.plan) console.log(`  Plan:     ${c.cyan}${flags.plan}${c.reset}`);
+  if (flags['fee-granter']) console.log(`  Fee granter: ${c.cyan}${flags['fee-granter']}${c.reset}`);
   console.log('');
 
   const { connect, disconnect } = await import('./index.js');

package/ai-path/connect.js

@@ -19,6 +19,8 @@
 import {
   connectAuto,
   connectDirect,
+  connectViaSubscription,
+  connectViaPlan,
   disconnect as sdkDisconnect,
   isConnected,
   getStatus,
@@ -245,6 +247,14 @@ async function preValidateBalance(mnemonic) {
 /**
  * Connect to Sentinel dVPN. The ONE function an AI agent needs.
  *
+ * Three connection modes:
+ *   1. Direct payment — agent pays per-session from own wallet (default)
+ *   2. Subscription — operator provisioned a subscription for this agent
+ *   3. Plan — subscribe to plan + start session (optionally fee-granted)
+ *
+ * For modes 2 & 3, set opts.feeGranter to the operator's address — the
+ * agent can have 0 P2P balance and the operator covers gas.
+ *
  * Every step is logged with numbered phases (STEP 1/7 through STEP 7/7)
  * so an autonomous agent can track progress and diagnose failures.
  *
@@ -254,6 +264,9 @@ async function preValidateBalance(mnemonic) {
  * @param {string} [opts.nodeAddress] - Specific node (sentnode1...). Skips auto-pick.
  * @param {string} [opts.dns] - DNS preset: 'google', 'cloudflare', 'hns'
  * @param {string} [opts.protocol] - Preferred protocol: 'wireguard' or 'v2ray'
+ * @param {string|number} [opts.subscriptionId] - Connect via existing subscription (operator-provisioned)
+ * @param {string|number} [opts.planId] - Connect via plan (subscribes + starts session)
+ * @param {string} [opts.feeGranter] - Operator address that pays gas (sent1...). Skips balance check.
  * @param {function} [opts.onProgress] - Progress callback: (stage, message) => void
  * @param {number} [opts.timeout] - Connection timeout in ms (default: 120000 — 2 minutes)
  * @param {boolean} [opts.silent] - If true, suppress step-by-step console output
@@ -338,13 +351,17 @@ export async function connect(opts = {}) {
   const balCheck = await preValidateBalance(opts.mnemonic);
   log(3, totalSteps, 'BALANCE', `Balance: ${balCheck.p2p} | Sufficient: ${balCheck.sufficient}`);
 
-  if (!balCheck.sufficient && !opts.dryRun) {
+  // Skip balance gate when fee granter is set — agent may have 0 P2P, operator pays gas
+  if (!balCheck.sufficient && !opts.dryRun && !opts.feeGranter) {
     const err = new Error(`Insufficient balance: ${balCheck.p2p}. Need at least ${formatP2P(MIN_BALANCE_UDVPN)}. Fund address: ${walletAddress}`);
     err.code = 'INSUFFICIENT_BALANCE';
     err.nextAction = 'fund_wallet';
     err.details = { address: walletAddress, balance: balCheck.p2p, minimum: formatP2P(MIN_BALANCE_UDVPN) };
     throw err;
   }
+  if (opts.feeGranter && !balCheck.sufficient) {
+    log(3, totalSteps, 'BALANCE', `Balance below minimum but fee granter ${opts.feeGranter} covers gas`);
+  }
   timings.balance = Date.now() - t0;
 
   // ── STEP 4/7: Node Selection ──────────────────────────────────────────────
@@ -549,7 +566,22 @@ export async function connect(opts = {}) {
   try {
     let result;
 
-    if (resolvedNodeAddress) {
+    // ── Connection mode: subscription > plan > direct > auto ──────────────
+    if (opts.subscriptionId) {
+      // Subscription mode — operator already provisioned a subscription for this agent
+      log(5, totalSteps, 'SESSION', `Connecting via subscription ${opts.subscriptionId}${opts.feeGranter ? ' (fee granted)' : ''}...`);
+      sdkOpts.subscriptionId = opts.subscriptionId;
+      if (opts.feeGranter) sdkOpts.feeGranter = opts.feeGranter;
+      if (resolvedNodeAddress) sdkOpts.nodeAddress = resolvedNodeAddress;
+      result = await connectViaSubscription(sdkOpts);
+    } else if (opts.planId) {
+      // Plan mode — subscribe to plan + start session (optionally fee-granted)
+      log(5, totalSteps, 'SESSION', `Connecting via plan ${opts.planId}${opts.feeGranter ? ' (fee granted)' : ''}...`);
+      sdkOpts.planId = opts.planId;
+      if (opts.feeGranter) sdkOpts.feeGranter = opts.feeGranter;
+      if (resolvedNodeAddress) sdkOpts.nodeAddress = resolvedNodeAddress;
+      result = await connectViaPlan(sdkOpts);
+    } else if (resolvedNodeAddress) {
       // Direct connection — either user specified nodeAddress or country discovery found one
       sdkOpts.nodeAddress = resolvedNodeAddress;
       result = await connectDirect(sdkOpts);

package/ai-path/index.js

@@ -65,10 +65,15 @@ export {
   subscribeToPlan,
   hasActiveSubscription,
   querySubscriptions,
+  querySubscriptionAllocations,
   queryPlanNodes,
   queryFeeGrants,
   buildFeeGrantMsg,
   broadcastWithFeeGrant,
+  // v2.1.0: Subscription sharing + onboarding (operator provisions agent access)
+  shareSubscription,
+  shareSubscriptionWithFeeGrant,
+  onboardPlanUser,
   rpcQueryNodesForPlan,
   rpcQuerySubscriptionsForAccount,
 } from '../index.js';

package/connection/connect.js

@@ -130,7 +130,7 @@ async function connectInternal(opts, paymentStrategy, retryStrategy, state = _de
   try {
     const bal = await getBalance(client, account.address);
     progress(onProgress, logFn, 'wallet', `${account.address} | ${bal.dvpn.toFixed(1)} P2P`);
-    if (!opts.dryRun && bal.udvpn < 100000) {
+    if (!opts.dryRun && !opts.feeGranter && bal.udvpn < 100000) {
       throw new ChainError(ErrorCodes.INSUFFICIENT_BALANCE,
         `Wallet has ${bal.dvpn.toFixed(2)} P2P — need at least 0.1 P2P for a session. Fund address ${account.address} with P2P tokens.`,
         { balance: bal, address: account.address }
@@ -769,8 +769,23 @@ export async function connectViaSubscription(opts) {
     };
 
     checkAborted(signal);
-    progress(null, opts.log || defaultLog, 'session', `Starting session via subscription ${opts.subscriptionId}...`);
-    const result = await broadcastWithInactiveRetry(client, account.address, [msg], opts.log || defaultLog, opts.onProgress);
+
+    // Fee grant: operator pays gas for the agent (e.g., x402 managed plan flow)
+    const feeGranter = opts.feeGranter || null;
+    progress(null, opts.log || defaultLog, 'session', `Starting session via subscription ${opts.subscriptionId}${feeGranter ? ' (fee granted)' : ''}...`);
+
+    let result;
+    if (feeGranter) {
+      try {
+        result = await broadcastWithFeeGrant(client, account.address, [msg], feeGranter);
+      } catch (feeErr) {
+        // Fee grant TX failed — fall back to user-paid
+        progress(null, opts.log || defaultLog, 'session', 'Fee grant failed, paying gas from wallet...');
+        result = await broadcastWithInactiveRetry(client, account.address, [msg], opts.log || defaultLog, opts.onProgress);
+      }
+    } else {
+      result = await broadcastWithInactiveRetry(client, account.address, [msg], opts.log || defaultLog, opts.onProgress);
+    }
     const extracted = extractId(result, /session/i, ['session_id', 'id']);
     if (!extracted) throw new ChainError(ErrorCodes.SESSION_EXTRACT_FAILED, 'Failed to extract session ID from subscription TX result', { txHash: result.transactionHash });
     const sessionId = BigInt(extracted);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blue-js-sdk",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "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",