@neus/sdk 1.1.5 → 1.1.7

package/cjs/client.cjs

@@ -1530,6 +1530,11 @@ ${bytes.length}`;
       storeOriginalContent: typeof options?.storeOriginalContent === "boolean" ? options.storeOriginalContent : true
     };
     if (typeof options?.enableIpfs === "boolean") optionsPayload.enableIpfs = options.enableIpfs;
+    if (options?.publishToHub === true) {
+      optionsPayload.publishToHub = true;
+    } else {
+      delete optionsPayload.publishToHub;
+    }
     const requestData = {
       verifierIds: normalizedVerifierIds,
       data,
@@ -1738,30 +1743,50 @@ ${bytes.length}`;
       }
       throw new ValidationError(`Failed to sign revocation: ${error.message}`);
     }
-    const res = await this._makeRequest("POST", `/api/v1/proofs/revoke-self/${qHash}`, {
+    const json = await this._makeRequest("POST", `/api/v1/proofs/revoke-self/${qHash}`, {
       walletAddress: address,
       signature,
       signedTimestamp,
       ...signerIsEvm ? {} : { chain, signatureMethod }
     });
-    const json = await res.json();
     if (!json.success) {
       throw new ApiError(json.error?.message || "Failed to revoke proof", json.error);
     }
     return true;
   }
+  _buildProofsByWalletQuery(options = {}) {
+    const qs = [];
+    if (options.limit) qs.push(`limit=${encodeURIComponent(String(options.limit))}`);
+    const cursorRaw = options.cursor !== null && options.cursor !== void 0 ? String(options.cursor).trim() : "";
+    if (cursorRaw) qs.push(`cursor=${encodeURIComponent(cursorRaw)}`);
+    else if (options.offset !== void 0 && options.offset !== null) {
+      qs.push(`offset=${encodeURIComponent(String(options.offset))}`);
+    }
+    if (options.q) qs.push(`q=${encodeURIComponent(String(options.q))}`);
+    if (options.qHash) qs.push(`qHash=${encodeURIComponent(String(options.qHash).toLowerCase())}`);
+    if (options.verifierId) qs.push(`verifierId=${encodeURIComponent(String(options.verifierId))}`);
+    if (options.verifierIds) qs.push(`verifierIds=${encodeURIComponent(String(options.verifierIds))}`);
+    if (options.tags) qs.push(`tags=${encodeURIComponent(String(options.tags))}`);
+    if (options.tagPrefix) qs.push(`tagPrefix=${encodeURIComponent(String(options.tagPrefix))}`);
+    if (options.tagContains) qs.push(`tagContains=${encodeURIComponent(String(options.tagContains))}`);
+    if (options.tagPrefixesAll) qs.push(`tagPrefixesAll=${encodeURIComponent(String(options.tagPrefixesAll))}`);
+    if (options.status) qs.push(`status=${encodeURIComponent(String(options.status))}`);
+    if (options.appId) qs.push(`appId=${encodeURIComponent(String(options.appId))}`);
+    if (options.chainCoverage) qs.push(`chainCoverage=${encodeURIComponent(String(options.chainCoverage))}`);
+    if (options.privacyLevel) qs.push(`privacyLevel=${encodeURIComponent(String(options.privacyLevel))}`);
+    if (options.includeHistory) qs.push("includeHistory=1");
+    if (options.includeFacets) qs.push(`includeFacets=${encodeURIComponent(String(options.includeFacets))}`);
+    if (options.visibility) qs.push(`visibility=${encodeURIComponent(String(options.visibility))}`);
+    if (options.isPublicRead) qs.push("isPublicRead=1");
+    return qs;
+  }
   async getProofsByWallet(walletAddress, options = {}) {
     if (!walletAddress || typeof walletAddress !== "string") {
       throw new ValidationError("walletAddress is required");
     }
     const id = walletAddress.trim();
     const pathId = /^0x[a-fA-F0-9]{40}$/i.test(id) ? id.toLowerCase() : id;
-    const qs = [];
-    if (options.limit) qs.push(`limit=${encodeURIComponent(String(options.limit))}`);
-    const cursorRaw = options.cursor !== null && options.cursor !== void 0 ? String(options.cursor).trim() : "";
-    if (cursorRaw) qs.push(`cursor=${encodeURIComponent(cursorRaw)}`);
-    else if (options.offset) qs.push(`offset=${encodeURIComponent(String(options.offset))}`);
-    if (options.qHash) qs.push(`qHash=${encodeURIComponent(options.qHash.toLowerCase())}`);
+    const qs = this._buildProofsByWalletQuery(options);
     const query = qs.length ? `?${qs.join("&")}` : "";
     const response = await this._makeRequest(
       "GET",
@@ -1774,10 +1799,11 @@ ${bytes.length}`;
     return {
       success: true,
       proofs: Array.isArray(proofs) ? proofs : [],
-      totalCount: response.data?.totalCount ?? proofs.length,
+      totalCount: typeof response.data?.totalCount === "number" ? response.data.totalCount : null,
       hasMore: Boolean(response.data?.hasMore),
       nextOffset: response.data?.nextOffset ?? null,
-      nextCursor: typeof response.data?.nextCursor === "string" && response.data.nextCursor.trim() ? response.data.nextCursor.trim() : null
+      nextCursor: typeof response.data?.nextCursor === "string" && response.data.nextCursor.trim() ? response.data.nextCursor.trim() : null,
+      facets: response.data?.facets || null
     };
   }
   async getPrivateProofsByWallet(walletAddress, options = {}, wallet = null) {
@@ -1827,12 +1853,7 @@ ${bytes.length}`;
       }
       throw new ValidationError(`Failed to sign message: ${error.message}`);
     }
-    const qs = [];
-    if (options.limit) qs.push(`limit=${encodeURIComponent(String(options.limit))}`);
-    const cursorRaw = options.cursor !== null && options.cursor !== void 0 ? String(options.cursor).trim() : "";
-    if (cursorRaw) qs.push(`cursor=${encodeURIComponent(cursorRaw)}`);
-    else if (options.offset) qs.push(`offset=${encodeURIComponent(String(options.offset))}`);
-    if (options.qHash) qs.push(`qHash=${encodeURIComponent(options.qHash.toLowerCase())}`);
+    const qs = this._buildProofsByWalletQuery(options);
     const query = qs.length ? `?${qs.join("&")}` : "";
     const response = await this._makeRequest("GET", `/api/v1/proofs/by-wallet/${encodeURIComponent(pathId)}${query}`, null, {
       "x-wallet-address": signerWalletAddress,
@@ -1847,7 +1868,7 @@ ${bytes.length}`;
     return {
       success: true,
       proofs: Array.isArray(proofs) ? proofs : [],
-      totalCount: response.data?.totalCount ?? proofs.length,
+      totalCount: typeof response.data?.totalCount === "number" ? response.data.totalCount : null,
       hasMore: Boolean(response.data?.hasMore),
       nextOffset: response.data?.nextOffset ?? null,
       nextCursor: typeof response.data?.nextCursor === "string" && response.data.nextCursor.trim() ? response.data.nextCursor.trim() : null
@@ -1964,6 +1985,64 @@ ${bytes.length}`;
     }
     return response;
   }
+  /**
+   * Get the public snapshot of a published gate: requirements, charge, schedule,
+   * checkout plan, and reward presence. Never returns the secret reward value —
+   * that is delivered post-verify via fulfillGate().
+   *
+   * @param {string} gateId Published gate handle
+   * @returns {Promise<object>} Public gate snapshot
+   */
+  async getGate(gateId) {
+    const id = String(gateId || "").trim();
+    if (!id || id.length > 80 || !/^[a-zA-Z0-9:_-]+$/.test(id)) {
+      throw new ValidationError("Valid gateId is required");
+    }
+    const response = await this._makeRequest("GET", `/api/v1/profile/gates/${encodeURIComponent(id)}`);
+    if (!response.success || !response.data?.gate) {
+      throw new ApiError(`Gate lookup failed: ${response.error?.message || "Gate not found"}`, response.error);
+    }
+    return response.data.gate;
+  }
+  /**
+   * Post-verify reward delivery for hosted gate checkout. Requires a verified
+   * proof (qHash) for the gate; paid gates also require payment evidence
+   * (paymentCheckoutSessionId for card, or paymentTxHash for USDC).
+   *
+   * @param {object} params
+   * @param {string} params.gateId Published gate handle
+   * @param {string} params.qHash Verified proof receipt id
+   * @param {string} [params.walletAddress] Wallet bound to the proof (required without a session cookie)
+   * @param {string} [params.paymentCheckoutSessionId] Stripe checkout session id (card rail)
+   * @param {string} [params.paymentTxHash] USDC payment transaction hash (wallet rail)
+   * @returns {Promise<object>} `{ success, data: { gateId, qHash, fulfillment, successReturnUrl? } }`
+   */
+  async fulfillGate(params = {}) {
+    const gateId = String(params.gateId || "").trim();
+    if (!gateId || gateId.length > 80 || !/^[a-zA-Z0-9:_-]+$/.test(gateId)) {
+      throw new ValidationError("Valid gateId is required");
+    }
+    const qHash = String(params.qHash || "").trim();
+    if (!/^0x[a-fA-F0-9]{64}$/.test(qHash)) {
+      throw new ValidationError("Valid qHash is required");
+    }
+    const body = { qHash };
+    const walletAddress = String(params.walletAddress || "").trim();
+    if (walletAddress) body.walletAddress = walletAddress;
+    const paymentCheckoutSessionId = String(params.paymentCheckoutSessionId || "").trim();
+    if (paymentCheckoutSessionId) body.paymentCheckoutSessionId = paymentCheckoutSessionId;
+    const paymentTxHash = String(params.paymentTxHash || "").trim();
+    if (paymentTxHash) body.paymentTxHash = paymentTxHash;
+    const response = await this._makeRequest(
+      "POST",
+      `/api/v1/profile/gates/${encodeURIComponent(gateId)}/fulfill`,
+      body
+    );
+    if (!response.success) {
+      throw new ApiError(`Gate fulfillment failed: ${response.error?.message || "Unknown error"}`, response.error);
+    }
+    return response;
+  }
   async checkGate(params) {
     const { walletAddress, requirements, proofs: preloadedProofs } = params;
     if (!validateUniversalAddress(walletAddress)) {

package/cjs/index.cjs

@@ -2223,6 +2223,11 @@ ${bytes.length}`;
           storeOriginalContent: typeof options?.storeOriginalContent === "boolean" ? options.storeOriginalContent : true
         };
         if (typeof options?.enableIpfs === "boolean") optionsPayload.enableIpfs = options.enableIpfs;
+        if (options?.publishToHub === true) {
+          optionsPayload.publishToHub = true;
+        } else {
+          delete optionsPayload.publishToHub;
+        }
         const requestData = {
           verifierIds: normalizedVerifierIds,
           data,
@@ -2431,30 +2436,50 @@ ${bytes.length}`;
           }
           throw new ValidationError(`Failed to sign revocation: ${error.message}`);
         }
-        const res = await this._makeRequest("POST", `/api/v1/proofs/revoke-self/${qHash}`, {
+        const json = await this._makeRequest("POST", `/api/v1/proofs/revoke-self/${qHash}`, {
           walletAddress: address,
           signature,
           signedTimestamp,
           ...signerIsEvm ? {} : { chain, signatureMethod }
         });
-        const json = await res.json();
         if (!json.success) {
           throw new ApiError(json.error?.message || "Failed to revoke proof", json.error);
         }
         return true;
       }
+      _buildProofsByWalletQuery(options = {}) {
+        const qs = [];
+        if (options.limit) qs.push(`limit=${encodeURIComponent(String(options.limit))}`);
+        const cursorRaw = options.cursor !== null && options.cursor !== void 0 ? String(options.cursor).trim() : "";
+        if (cursorRaw) qs.push(`cursor=${encodeURIComponent(cursorRaw)}`);
+        else if (options.offset !== void 0 && options.offset !== null) {
+          qs.push(`offset=${encodeURIComponent(String(options.offset))}`);
+        }
+        if (options.q) qs.push(`q=${encodeURIComponent(String(options.q))}`);
+        if (options.qHash) qs.push(`qHash=${encodeURIComponent(String(options.qHash).toLowerCase())}`);
+        if (options.verifierId) qs.push(`verifierId=${encodeURIComponent(String(options.verifierId))}`);
+        if (options.verifierIds) qs.push(`verifierIds=${encodeURIComponent(String(options.verifierIds))}`);
+        if (options.tags) qs.push(`tags=${encodeURIComponent(String(options.tags))}`);
+        if (options.tagPrefix) qs.push(`tagPrefix=${encodeURIComponent(String(options.tagPrefix))}`);
+        if (options.tagContains) qs.push(`tagContains=${encodeURIComponent(String(options.tagContains))}`);
+        if (options.tagPrefixesAll) qs.push(`tagPrefixesAll=${encodeURIComponent(String(options.tagPrefixesAll))}`);
+        if (options.status) qs.push(`status=${encodeURIComponent(String(options.status))}`);
+        if (options.appId) qs.push(`appId=${encodeURIComponent(String(options.appId))}`);
+        if (options.chainCoverage) qs.push(`chainCoverage=${encodeURIComponent(String(options.chainCoverage))}`);
+        if (options.privacyLevel) qs.push(`privacyLevel=${encodeURIComponent(String(options.privacyLevel))}`);
+        if (options.includeHistory) qs.push("includeHistory=1");
+        if (options.includeFacets) qs.push(`includeFacets=${encodeURIComponent(String(options.includeFacets))}`);
+        if (options.visibility) qs.push(`visibility=${encodeURIComponent(String(options.visibility))}`);
+        if (options.isPublicRead) qs.push("isPublicRead=1");
+        return qs;
+      }
       async getProofsByWallet(walletAddress, options = {}) {
         if (!walletAddress || typeof walletAddress !== "string") {
           throw new ValidationError("walletAddress is required");
         }
         const id = walletAddress.trim();
         const pathId = /^0x[a-fA-F0-9]{40}$/i.test(id) ? id.toLowerCase() : id;
-        const qs = [];
-        if (options.limit) qs.push(`limit=${encodeURIComponent(String(options.limit))}`);
-        const cursorRaw = options.cursor !== null && options.cursor !== void 0 ? String(options.cursor).trim() : "";
-        if (cursorRaw) qs.push(`cursor=${encodeURIComponent(cursorRaw)}`);
-        else if (options.offset) qs.push(`offset=${encodeURIComponent(String(options.offset))}`);
-        if (options.qHash) qs.push(`qHash=${encodeURIComponent(options.qHash.toLowerCase())}`);
+        const qs = this._buildProofsByWalletQuery(options);
         const query = qs.length ? `?${qs.join("&")}` : "";
         const response = await this._makeRequest(
           "GET",
@@ -2467,10 +2492,11 @@ ${bytes.length}`;
         return {
           success: true,
           proofs: Array.isArray(proofs) ? proofs : [],
-          totalCount: response.data?.totalCount ?? proofs.length,
+          totalCount: typeof response.data?.totalCount === "number" ? response.data.totalCount : null,
           hasMore: Boolean(response.data?.hasMore),
           nextOffset: response.data?.nextOffset ?? null,
-          nextCursor: typeof response.data?.nextCursor === "string" && response.data.nextCursor.trim() ? response.data.nextCursor.trim() : null
+          nextCursor: typeof response.data?.nextCursor === "string" && response.data.nextCursor.trim() ? response.data.nextCursor.trim() : null,
+          facets: response.data?.facets || null
         };
       }
       async getPrivateProofsByWallet(walletAddress, options = {}, wallet = null) {
@@ -2520,12 +2546,7 @@ ${bytes.length}`;
           }
           throw new ValidationError(`Failed to sign message: ${error.message}`);
         }
-        const qs = [];
-        if (options.limit) qs.push(`limit=${encodeURIComponent(String(options.limit))}`);
-        const cursorRaw = options.cursor !== null && options.cursor !== void 0 ? String(options.cursor).trim() : "";
-        if (cursorRaw) qs.push(`cursor=${encodeURIComponent(cursorRaw)}`);
-        else if (options.offset) qs.push(`offset=${encodeURIComponent(String(options.offset))}`);
-        if (options.qHash) qs.push(`qHash=${encodeURIComponent(options.qHash.toLowerCase())}`);
+        const qs = this._buildProofsByWalletQuery(options);
         const query = qs.length ? `?${qs.join("&")}` : "";
         const response = await this._makeRequest("GET", `/api/v1/proofs/by-wallet/${encodeURIComponent(pathId)}${query}`, null, {
           "x-wallet-address": signerWalletAddress,
@@ -2540,7 +2561,7 @@ ${bytes.length}`;
         return {
           success: true,
           proofs: Array.isArray(proofs) ? proofs : [],
-          totalCount: response.data?.totalCount ?? proofs.length,
+          totalCount: typeof response.data?.totalCount === "number" ? response.data.totalCount : null,
           hasMore: Boolean(response.data?.hasMore),
           nextOffset: response.data?.nextOffset ?? null,
           nextCursor: typeof response.data?.nextCursor === "string" && response.data.nextCursor.trim() ? response.data.nextCursor.trim() : null
@@ -2657,6 +2678,64 @@ ${bytes.length}`;
         }
         return response;
       }
+      /**
+       * Get the public snapshot of a published gate: requirements, charge, schedule,
+       * checkout plan, and reward presence. Never returns the secret reward value —
+       * that is delivered post-verify via fulfillGate().
+       *
+       * @param {string} gateId Published gate handle
+       * @returns {Promise<object>} Public gate snapshot
+       */
+      async getGate(gateId) {
+        const id = String(gateId || "").trim();
+        if (!id || id.length > 80 || !/^[a-zA-Z0-9:_-]+$/.test(id)) {
+          throw new ValidationError("Valid gateId is required");
+        }
+        const response = await this._makeRequest("GET", `/api/v1/profile/gates/${encodeURIComponent(id)}`);
+        if (!response.success || !response.data?.gate) {
+          throw new ApiError(`Gate lookup failed: ${response.error?.message || "Gate not found"}`, response.error);
+        }
+        return response.data.gate;
+      }
+      /**
+       * Post-verify reward delivery for hosted gate checkout. Requires a verified
+       * proof (qHash) for the gate; paid gates also require payment evidence
+       * (paymentCheckoutSessionId for card, or paymentTxHash for USDC).
+       *
+       * @param {object} params
+       * @param {string} params.gateId Published gate handle
+       * @param {string} params.qHash Verified proof receipt id
+       * @param {string} [params.walletAddress] Wallet bound to the proof (required without a session cookie)
+       * @param {string} [params.paymentCheckoutSessionId] Stripe checkout session id (card rail)
+       * @param {string} [params.paymentTxHash] USDC payment transaction hash (wallet rail)
+       * @returns {Promise<object>} `{ success, data: { gateId, qHash, fulfillment, successReturnUrl? } }`
+       */
+      async fulfillGate(params = {}) {
+        const gateId = String(params.gateId || "").trim();
+        if (!gateId || gateId.length > 80 || !/^[a-zA-Z0-9:_-]+$/.test(gateId)) {
+          throw new ValidationError("Valid gateId is required");
+        }
+        const qHash = String(params.qHash || "").trim();
+        if (!/^0x[a-fA-F0-9]{64}$/.test(qHash)) {
+          throw new ValidationError("Valid qHash is required");
+        }
+        const body = { qHash };
+        const walletAddress = String(params.walletAddress || "").trim();
+        if (walletAddress) body.walletAddress = walletAddress;
+        const paymentCheckoutSessionId = String(params.paymentCheckoutSessionId || "").trim();
+        if (paymentCheckoutSessionId) body.paymentCheckoutSessionId = paymentCheckoutSessionId;
+        const paymentTxHash = String(params.paymentTxHash || "").trim();
+        if (paymentTxHash) body.paymentTxHash = paymentTxHash;
+        const response = await this._makeRequest(
+          "POST",
+          `/api/v1/profile/gates/${encodeURIComponent(gateId)}/fulfill`,
+          body
+        );
+        if (!response.success) {
+          throw new ApiError(`Gate fulfillment failed: ${response.error?.message || "Unknown error"}`, response.error);
+        }
+        return response;
+      }
       async checkGate(params) {
         const { walletAddress, requirements, proofs: preloadedProofs } = params;
         if (!validateUniversalAddress(walletAddress)) {

package/cli/neus.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { spawnSync } from 'node:child_process';
+import { exec, spawnSync } from 'node:child_process';
 import { createHash, randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -12,6 +12,13 @@ import {
 } from '../mcp-hosts.js';
 
 const __cliDir = path.dirname(fileURLToPath(import.meta.url));
+const CLI_PACKAGE_VERSION = (() => {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(__cliDir, '..', 'package.json'), 'utf8')).version;
+  } catch {
+    return '0.0.0';
+  }
+})();
 
 const NEUS_APP_URL = 'https://neus.network';
 const NEUS_TOKEN_ENDPOINT = 'https://neus.network/api/v1/auth/mcp/token';
@@ -137,6 +144,7 @@ function describeClientResult(command, result) {
   }
   if (result.changed) return 'updated';
   if (result.authConfigured) return 'signed in';
+  if (result.configured) return 'ready';
   return 'ready';
 }
 
@@ -296,6 +304,7 @@ function envAccessKey() {
 
 /** --access-key flag, else NEUS_ACCESS_KEY from the environment, else browser sign-in. */
 function resolveAccessKey(options) {
+  if (options?.oauth) return '';
   const explicit = String(options.accessKey || '').trim();
   if (explicit) return explicit;
   return envAccessKey();
@@ -307,6 +316,7 @@ function resolveLiveAccessKey(options, scope, cwd) {
   if (explicit) return explicit;
   const installed = readInstalledAccessKey(scope, cwd);
   if (installed) return installed;
+  if (options?.oauth) return '';
   return envAccessKey();
 }
 
@@ -579,7 +589,8 @@ function parseArgs(argv) {
     live: false,
     json: false,
     dryRun: false,
-    project: false
+    project: false,
+    oauth: false
   };
 
   for (let index = 1; index < argv.length; index += 1) {
@@ -635,6 +646,10 @@ function parseArgs(argv) {
       index += 1;
       continue;
     }
+    if (token === '--oauth') {
+      options.oauth = true;
+      continue;
+    }
     if (token === '--help' || token === '-h') {
       return { command: 'help', options };
     }
@@ -668,6 +683,7 @@ function printUsage(exitCode = 0) {
     '  --client <name[,name]>   Limit setup to claude, codex, cursor, or vscode',
     '  --project                Write shared project config instead of user config',
     '  --access-key <npk_...>   Override profile access key (else uses NEUS_ACCESS_KEY if set)',
+    '  --oauth                    Force browser OAuth (ignore NEUS_ACCESS_KEY in the environment)',
     '  --from <source>          Import source: auto, cursor, claude-code, or claude-desktop',
     '  --to <format>            Export format: manifest or json',
     '  --output <path>          Write exported manifest to a specific path',
@@ -1383,7 +1399,7 @@ async function runLiveMcpDiagnostics(accessKey) {
       params: {
         protocolVersion: '2025-11-25',
         capabilities: {},
-        clientInfo: { name: 'neus-cli', version: '1.1.5' }
+        clientInfo: { name: 'neus-cli', version: CLI_PACKAGE_VERSION }
       },
       accessKey,
       signal: controller.signal
@@ -1699,9 +1715,12 @@ async function runAuthBrowser(options) {
         logStep('next', 'wait', 'finish sign-in in the browser');
       }
 
-      const { exec } = require('node:child_process');
-      const openCmd = process.platform === 'win32' ? 'start' : process.platform === 'darwin' ? 'open' : 'xdg-open';
-      exec(`${openCmd} "${authUrl}"`, err => {
+      const openCommand = process.platform === 'win32'
+        ? `cmd /c start "" "${authUrl.replace(/"/g, '\\"')}"`
+        : process.platform === 'darwin'
+          ? `open "${authUrl.replace(/"/g, '\\"')}"`
+          : `xdg-open "${authUrl.replace(/"/g, '\\"')}"`;
+      exec(openCommand, { shell: true }, err => {
         if (err && !options.json) {
           logStep('warn', 'browser', 'open the URL above manually');
         }
@@ -1816,6 +1835,12 @@ async function runSetup(options) {
   }
 
   if (options.json) {
+    payload.authRequired = !accessKey && !options.dryRun;
+    if (payload.authRequired) {
+      payload.nextCommand = clients.length === 1 && clients[0] === 'codex'
+        ? 'neus auth --client codex'
+        : 'neus auth';
+    }
     printJson(payload);
     return payload;
   }