@neus/sdk 1.1.5 → 1.1.6

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,
@@ -1750,18 +1755,39 @@ ${bytes.length}`;
     }
     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 +1800,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 +1854,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 +1869,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 +1986,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/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/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,
@@ -2443,18 +2448,39 @@ ${bytes.length}`;
         }
         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 +2493,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 +2547,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 +2562,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 +2679,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/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/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;
   }

package/client.js

@@ -1204,6 +1204,12 @@ export class NeusClient {
         typeof options?.storeOriginalContent === 'boolean' ? options.storeOriginalContent : true
     };
     if (typeof options?.enableIpfs === 'boolean') optionsPayload.enableIpfs = options.enableIpfs;
+    // Receipts persist offchain by default; hub registry anchoring is explicit opt-in.
+    if (options?.publishToHub === true) {
+      optionsPayload.publishToHub = true;
+    } else {
+      delete optionsPayload.publishToHub;
+    }
 
     const requestData = {
       verifierIds: normalizedVerifierIds,
@@ -1471,6 +1477,33 @@ export class NeusClient {
     return true;
   }
 
+  _buildProofsByWalletQuery(options = {}) {
+    const qs = [];
+    if (options.limit) qs.push(`limit=${encodeURIComponent(String(options.limit))}`);
+    const cursorRaw = options.cursor !== null && options.cursor !== undefined ? String(options.cursor).trim() : '';
+    if (cursorRaw) qs.push(`cursor=${encodeURIComponent(cursorRaw)}`);
+    else if (options.offset !== undefined && 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');
@@ -1479,12 +1512,7 @@ export class NeusClient {
     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 !== undefined ? 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(
@@ -1500,13 +1528,14 @@ export class NeusClient {
     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
+          : null,
+      facets: response.data?.facets || null,
     };
   }
 
@@ -1569,12 +1598,7 @@ export class NeusClient {
       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 !== undefined ? 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, {
@@ -1592,7 +1616,7 @@ export class NeusClient {
     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:
@@ -1730,6 +1754,67 @@ export class NeusClient {
     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/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/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;
 

package/package.json

@@ -1,147 +1,147 @@
-{
-  "name": "@neus/sdk",
-  "version": "1.1.5",
-  "description": "NEUS makes trust portable across the internet — so people, apps, and AI agents can prove what is real before access, payout, or execution.",
-  "bin": {
-    "neus": "cli/neus.mjs"
-  },
-  "main": "index.js",
-  "type": "module",
-  "types": "types.d.ts",
-  "exports": {
-    ".": {
-      "types": "./types.d.ts",
-      "import": "./index.js",
-      "require": "./cjs/index.cjs"
-    },
-    "./client": {
-      "types": "./types.d.ts",
-      "import": "./client.js",
-      "require": "./cjs/client.cjs"
-    },
-    "./utils": {
-      "import": "./utils.js",
-      "require": "./cjs/utils.cjs"
-    },
-    "./errors": {
-      "import": "./errors.js",
-      "require": "./cjs/errors.cjs"
-    },
-    "./gates": {
-      "import": "./gates.js",
-      "require": "./cjs/gates.cjs"
-    },
-    "./mcp-hosts": {
-      "import": "./mcp-hosts.js",
-      "require": "./cjs/mcp-hosts.cjs"
-    },
-    "./widgets": {
-      "types": "./types.d.ts",
-      "import": "./widgets/index.js",
-      "require": "./widgets.cjs"
-    },
-    "./widgets/verify-gate": {
-      "types": "./types.d.ts",
-      "import": "./widgets/verify-gate/index.js",
-      "require": "./widgets.cjs"
-    }
-  },
-  "sideEffects": false,
-  "scripts": {
-    "test": "npm run build:cjs && vitest run",
-    "test:coverage": "vitest run --coverage",
-    "lint": "eslint . --ignore-pattern widgets/verify-gate/dist/**",
-    "format": "prettier --write \"**/*.js\"",
-    "build": "npm run build:widgets && npm run build:cjs",
-    "build:widgets": "npx esbuild widgets/verify-gate/VerifyGate.jsx widgets/verify-gate/ProofBadge.jsx --bundle --platform=browser --format=esm --outdir=widgets/verify-gate/dist --jsx=automatic --legal-comments=none --external:react --external:react-dom --external:react/jsx-runtime --external:@neus/sdk/client",
-    "build:cjs": "npx esbuild index.js client.js utils.js errors.js gates.js mcp-hosts.js --bundle --platform=node --format=cjs --outdir=cjs --out-extension:.js=.cjs --legal-comments=none --external:ethers --external:@zkpassport/sdk --external:react --external:react-dom --external:react/jsx-runtime",
-    "prepack": "npm run build",
-    "prepublishOnly": "npm run lint && npm test && npm run build"
-  },
-  "keywords": [
-    "neus",
-    "verification",
-    "cryptographic-proofs",
-    "identity",
-    "authentication",
-    "blockchain",
-    "cross-chain",
-    "web3",
-    "passwordless",
-    "universal-protocol",
-    "proof",
-    "ownership",
-    "sdk",
-    "mcp",
-    "model-context-protocol",
-    "oauth"
-  ],
-  "author": "NEUS Network",
-  "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/neus/network.git",
-    "directory": "sdk"
-  },
-  "bugs": {
-    "url": "https://github.com/neus/network/issues"
-  },
-  "homepage": "https://neus.network",
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org"
-  },
-  "engines": {
-    "node": ">=20.0.0"
-  },
-  "peerDependencies": {
-    "ethers": "^6.0.0",
-    "react": ">=17.0.0",
-    "react-dom": ">=17.0.0"
-  },
-  "peerDependenciesMeta": {
-    "@zkpassport/sdk": {
-      "optional": true
-    },
-    "react": {
-      "optional": true
-    },
-    "react-dom": {
-      "optional": true
-    }
-  },
-  "optionalDependencies": {
-    "@zkpassport/sdk": "^0.14.0"
-  },
-  "dependencies": {
-    "bs58": "^6.0.0"
-  },
-  "devDependencies": {
-    "@vitest/coverage-v8": "^4.1.3",
-    "esbuild": "^0.28.0",
-    "eslint": "^8.56.0",
-    "eslint-plugin-react": "^7.37.2",
-    "prettier": "^3.2.0",
-    "vitest": "^4.1.3"
-  },
-  "files": [
-    "cli/neus.mjs",
-    "mcp-hosts.js",
-    "index.js",
-    "client.js",
-    "utils.js",
-    "errors.js",
-    "gates.js",
-    "sponsor.js",
-    "cjs/**",
-    "widgets.cjs",
-    "types.d.ts",
-    "README.md",
-    "SECURITY.md",
-    "LICENSE",
-    "widgets/index.js",
-    "widgets/verify-gate/index.js",
-    "widgets/verify-gate/dist/VerifyGate.js",
-    "widgets/verify-gate/dist/ProofBadge.js"
-  ]
-}
+{
+  "name": "@neus/sdk",
+  "version": "1.1.6",
+  "description": "NEUS makes trust portable across the internet — so people, apps, and AI agents can prove what is real before access, payout, or execution.",
+  "bin": {
+    "neus": "cli/neus.mjs"
+  },
+  "main": "index.js",
+  "type": "module",
+  "types": "types.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types.d.ts",
+      "import": "./index.js",
+      "require": "./cjs/index.cjs"
+    },
+    "./client": {
+      "types": "./types.d.ts",
+      "import": "./client.js",
+      "require": "./cjs/client.cjs"
+    },
+    "./utils": {
+      "import": "./utils.js",
+      "require": "./cjs/utils.cjs"
+    },
+    "./errors": {
+      "import": "./errors.js",
+      "require": "./cjs/errors.cjs"
+    },
+    "./gates": {
+      "import": "./gates.js",
+      "require": "./cjs/gates.cjs"
+    },
+    "./mcp-hosts": {
+      "import": "./mcp-hosts.js",
+      "require": "./cjs/mcp-hosts.cjs"
+    },
+    "./widgets": {
+      "types": "./types.d.ts",
+      "import": "./widgets/index.js",
+      "require": "./widgets.cjs"
+    },
+    "./widgets/verify-gate": {
+      "types": "./types.d.ts",
+      "import": "./widgets/verify-gate/index.js",
+      "require": "./widgets.cjs"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "test": "npm run build:cjs && vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint . --ignore-pattern widgets/verify-gate/dist/**",
+    "format": "prettier --write \"**/*.js\"",
+    "build": "npm run build:widgets && npm run build:cjs",
+    "build:widgets": "npx esbuild widgets/verify-gate/VerifyGate.jsx widgets/verify-gate/ProofBadge.jsx --bundle --platform=browser --format=esm --outdir=widgets/verify-gate/dist --jsx=automatic --legal-comments=none --external:react --external:react-dom --external:react/jsx-runtime --external:@neus/sdk/client",
+    "build:cjs": "npx esbuild index.js client.js utils.js errors.js gates.js mcp-hosts.js --bundle --platform=node --format=cjs --outdir=cjs --out-extension:.js=.cjs --legal-comments=none --external:ethers --external:@zkpassport/sdk --external:react --external:react-dom --external:react/jsx-runtime",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run lint && npm test && npm run build"
+  },
+  "keywords": [
+    "neus",
+    "verification",
+    "cryptographic-proofs",
+    "identity",
+    "authentication",
+    "blockchain",
+    "cross-chain",
+    "web3",
+    "passwordless",
+    "universal-protocol",
+    "proof",
+    "ownership",
+    "sdk",
+    "mcp",
+    "model-context-protocol",
+    "oauth"
+  ],
+  "author": "NEUS Network",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neus/network.git",
+    "directory": "sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/neus/network/issues"
+  },
+  "homepage": "https://neus.network",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "peerDependencies": {
+    "ethers": "^6.0.0",
+    "react": ">=17.0.0",
+    "react-dom": ">=17.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@zkpassport/sdk": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "optionalDependencies": {
+    "@zkpassport/sdk": "^0.14.0"
+  },
+  "dependencies": {
+    "bs58": "^6.0.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.3",
+    "esbuild": "^0.28.0",
+    "eslint": "^8.56.0",
+    "eslint-plugin-react": "^7.37.2",
+    "prettier": "^3.2.0",
+    "vitest": "^4.1.3"
+  },
+  "files": [
+    "cli/neus.mjs",
+    "mcp-hosts.js",
+    "index.js",
+    "client.js",
+    "utils.js",
+    "errors.js",
+    "gates.js",
+    "sponsor.js",
+    "cjs/**",
+    "widgets.cjs",
+    "types.d.ts",
+    "README.md",
+    "SECURITY.md",
+    "LICENSE",
+    "widgets/index.js",
+    "widgets/verify-gate/index.js",
+    "widgets/verify-gate/dist/VerifyGate.js",
+    "widgets/verify-gate/dist/ProofBadge.js"
+  ]
+}

package/types.d.ts

@@ -51,6 +51,12 @@
 
     checkGate(params: CheckGateParams): Promise<CheckGateResult>;
 
+    /** Public gate snapshot (requirements, charge, schedule — never the secret reward value). */
+    getGate(gateId: string): Promise<PublicGateSnapshot>;
+
+    /** Post-verify reward delivery for hosted gate checkout (session or wallet-bound). */
+    fulfillGate(params: FulfillGateParams): Promise<GateFulfillmentResponse>;
+
   }
 
   export type PrivacyLevel = 'public' | 'private';
@@ -102,6 +108,8 @@
     enableIpfs?: boolean;
     storeOriginalContent?: boolean;
     targetChains?: number[];
+    /** Anchor the receipt on the hub registry chain. Defaults to false (receipts persist offchain). */
+    publishToHub?: boolean;
     publicDisplay?: boolean;
     meta?: Record<string, any>;
     verifierOptions?: Record<string, any>;
@@ -429,12 +437,102 @@
     scheme: string;
     label: string;
     amountUsd: number;
-    methods: string[];
+    /** Payment methods offered to visitors: 'usdc' and/or 'stripe' (card). */
+    methods: Array<'usdc' | 'stripe' | string>;
+    /** True when the owner can receive card payouts (Stripe Connect ready). */
+    cardPayoutReady?: boolean;
     appliesTo: string;
+    /** 'verifyThenCharge' (default) or 'chargeThenVerify'. */
     executionOrder?: string;
     recipient?: string;
   };
 
+  /** One gate requirement row on the wire (protocol shape used by published gates). */
+  export interface GateMatchRowWire {
+    path: string;
+    op?: 'eq' | 'gte' | 'lte' | string;
+    value: string;
+  }
+
+  export interface GateRequirementWire {
+    verifierId: string;
+    match?: GateMatchRowWire[];
+    optional?: boolean;
+    minCount?: number;
+    maxAgeMs?: number;
+  }
+
+  /** Public snapshot returned by GET /api/v1/gates/{gateId} — never includes the secret reward value. */
+  export interface PublicGateSnapshot {
+    schemaVersion: number;
+    gateId: string;
+    name?: string;
+    status?: string;
+    version?: number;
+    requirements: GateRequirementWire[];
+    policy?: {
+      visibility?: string;
+      gateFreshnessHours?: number;
+    };
+    monetization?: {
+      charge?: NeusPublicGateCharge | null;
+    };
+    checkout?: {
+      mode?: string;
+      flowPlan?: {
+        batches?: number;
+        hasInteractive?: boolean;
+        hasBackground?: boolean;
+      };
+      description?: string;
+      successReturnUrl?: string;
+    };
+    marketplaceTemplate?: {
+      templateId: string;
+      label?: string;
+      tags?: string[];
+    };
+    schedule?: {
+      startsAt?: string;
+      endsAt?: string;
+    };
+    artifact?: {
+      type: string;
+      label?: string;
+    };
+  }
+
+  export interface FulfillGateParams {
+    gateId: string;
+    /** Verified proof receipt id for this checkout. */
+    qHash: string;
+    /** Required when no session cookie binds the wallet. */
+    walletAddress?: string;
+    /** Stripe checkout session id for paid gates (card rail). */
+    paymentCheckoutSessionId?: string;
+    /** USDC payment transaction hash for paid gates (wallet rail). */
+    paymentTxHash?: string;
+  }
+
+  export interface GateFulfillmentResult {
+    delivery: 'access_granted' | 'redirect' | 'download' | 'reveal' | string;
+    type?: string;
+    value?: string;
+    label?: string;
+    message?: string;
+  }
+
+  export interface GateFulfillmentResponse {
+    success: boolean;
+    data?: {
+      gateId: string;
+      qHash: string;
+      fulfillment: GateFulfillmentResult;
+      successReturnUrl?: string;
+    };
+    error?: any;
+  }
+
   export const NEUS_CONSTANTS: {
     HUB_CHAIN_ID: number;
     TESTNET_CHAINS: number[];
@@ -482,16 +580,36 @@
     cursor?: string;
     chain?: string;
     signatureMethod?: string;
+    q?: string;
+    qHash?: string;
+    verifierId?: string;
+    verifierIds?: string;
+    tags?: string;
+    tagPrefix?: string;
+    tagContains?: string;
+    tagPrefixesAll?: string;
+    status?: string;
+    appId?: string;
+    chainCoverage?: 'hub-only' | 'cross-chain';
+    privacyLevel?: 'public' | 'private';
+    includeHistory?: boolean;
+    includeFacets?: string;
+    visibility?: 'public';
+    isPublicRead?: boolean;
   }
 
   export interface ProofsResult {
     success: boolean;
     proofs: any[];
-    totalCount: number;
+    totalCount: number | null;
     hasMore: boolean;
     nextOffset?: number | null;
     /** Keyset continuation when the API returns cursor paging (preferred over deep offsets). */
     nextCursor?: string | null;
+    facets?: {
+      tags?: string[];
+      truncated?: boolean;
+    } | null;
   }
 
   export interface GateRequirement {
@@ -499,7 +617,11 @@
     maxAgeMs?: number;
     optional?: boolean;
     minCount?: number;
-    match?: Record<string, any>;
+    /**
+     * Either the protocol wire shape (array of { path, op, value } rows — what
+     * published gates store) or a flat { path: value } map for client-side checks.
+     */
+    match?: GateMatchRowWire[] | Record<string, any>;
   }
 
   export interface CheckGateParams {
@@ -577,6 +699,25 @@
       matchedTags?: string[];
       projections?: Array<Record<string, any>> | null;
       criteria?: Record<string, any>;
+      /**
+       * Per-requirement gate evaluation — present whenever `gateId` was passed.
+       * `allRequiredSatisfied === true` is the ONLY readiness signal for gate
+       * checkout; `eligible`/`matchedCount` alone are not sufficient.
+       */
+      gate?: {
+        gateId: string | null;
+        allRequiredSatisfied: boolean;
+        satisfiedVerifierIds: string[];
+        missingVerifierIds: string[];
+        /** verifierId → qHash map for `options.reusedVerifierProofs` on submit (requires includeQHashes=true). */
+        reusedVerifierProofs?: Record<string, string>;
+        /** Per-requirement rows (requires includeQHashes=true). */
+        rows?: Array<{
+          verifierId: string;
+          satisfied: boolean;
+          qHashes?: string[];
+        }>;
+      };
     };
     error?: any;
   }
@@ -830,6 +971,8 @@
   
   interface VerifyOptions {
     targetChains?: number[];
+    /** Anchor the receipt on the hub registry chain. Defaults to false (receipts persist offchain). */
+    publishToHub?: boolean;
     enableIpfs?: boolean;
     privacyLevel?: 'private' | 'public';
     publicDisplay?: boolean;