@neus/sdk 1.1.0 → 1.1.2

package/mcp-hosts.js

@@ -0,0 +1,121 @@
+/**
+ * MCP host install constants shared by the `neus` CLI and product UI.
+ * Browser-safe: no Node-only APIs except the Buffer fallback for non-browser tests.
+ */
+
+export const NEUS_MCP_SERVER_NAME = 'neus';
+export const NEUS_MCP_URL = 'https://mcp.neus.network/mcp';
+export const NEUS_SETUP_CLI = 'npx -y -p @neus/sdk neus setup';
+export const NEUS_AUTH_CLI = 'npx -y -p @neus/sdk neus auth';
+export const NEUS_MCP_SETUP_DOCS_URL = 'https://docs.neus.network/mcp/ide-plugin';
+
+/** CLI `neus setup --client` values. */
+export const MCP_INSTALL_CLIENTS = ['claude', 'codex', 'cursor', 'vscode'];
+
+/** Product Profile "Open in" hosts. */
+export const MCP_INSTALL_HOSTS = ['cursor', 'claude', 'codex'];
+
+export const IDE_HOST_LABELS = {
+  cursor: 'Cursor',
+  claude: 'Claude Code',
+  codex: 'Codex'
+};
+
+export const IDE_HOST_BRAND_LOGOS = {
+  cursor: '/images/brandLogos/cursor.svg',
+  claude: '/images/brandLogos/anthropic.svg',
+  codex: '/images/brandLogos/openai.svg'
+};
+
+/**
+ * @param {string | null | undefined} accessKey
+ * @returns {{ type: 'http'; url: string; headers?: { Authorization: string } }}
+ */
+export function buildNeusMcpHttpConfig(accessKey) {
+  const key = String(accessKey || '').trim();
+  return {
+    type: 'http',
+    url: NEUS_MCP_URL,
+    ...(key ? { headers: { Authorization: `Bearer ${key}` } } : {})
+  };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function encodeBase64Json(value) {
+  const json = JSON.stringify(value);
+  if (typeof globalThis.btoa === 'function') {
+    return globalThis.btoa(json);
+  }
+  return Buffer.from(json, 'utf8').toString('base64');
+}
+
+/**
+ * @param {string | null | undefined} accessKey
+ * @returns {string}
+ */
+export function buildCursorMcpInstallUrl(accessKey) {
+  const config = buildNeusMcpHttpConfig(accessKey);
+  const encoded = encodeBase64Json(config);
+  return `cursor://anysphere.cursor-deeplink/mcp/install?name=${encodeURIComponent(NEUS_MCP_SERVER_NAME)}&config=${encodeURIComponent(encoded)}`;
+}
+
+/**
+ * @param {string | null | undefined} accessKey
+ * @returns {string}
+ */
+export function buildVsCodeMcpInstallUrl(accessKey) {
+  const payload = {
+    name: NEUS_MCP_SERVER_NAME,
+    ...buildNeusMcpHttpConfig(accessKey)
+  };
+  return `vscode:mcp/install?${encodeURIComponent(JSON.stringify(payload))}`;
+}
+
+/**
+ * @param {'claude' | 'codex' | 'cursor' | 'vscode'} client
+ * @returns {string}
+ */
+export function buildAuthCommandForClient(client) {
+  if (client === 'codex') {
+    return `${NEUS_AUTH_CLI} --client codex`;
+  }
+  return NEUS_AUTH_CLI;
+}
+
+/**
+ * @param {'claude' | 'codex' | 'cursor' | 'vscode'} client
+ * @param {string | null | undefined} accessKey
+ * @returns {string}
+ */
+export function buildSetupCommandForClient(client, accessKey) {
+  const key = String(accessKey || '').trim();
+  const setup = key
+    ? `${NEUS_SETUP_CLI} --client ${client} --access-key ${key}`
+    : `${NEUS_SETUP_CLI} --client ${client}`;
+  if (key) return setup;
+  return `${setup}\n${buildAuthCommandForClient(client)}`;
+}
+
+/**
+ * @param {'cursor' | 'claude' | 'codex'} host
+ * @param {string | null | undefined} accessKey
+ * @returns {string}
+ */
+export function buildSetupCommandForHost(host, accessKey) {
+  return buildSetupCommandForClient(host, accessKey);
+}
+
+/**
+ * Cursor supports MCP install deeplinks; Codex uses CLI, not VS Code deeplinks.
+ * @param {'cursor' | 'claude' | 'codex'} host
+ * @returns {boolean}
+ */
+export function supportsMcpInstallDeeplink(host) {
+  if (host !== 'cursor') return false;
+  if (typeof navigator === 'undefined') return false;
+  const ua = navigator.userAgent || '';
+  return !/Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(ua);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neus/sdk",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "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"
@@ -31,6 +31,10 @@
       "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",
@@ -49,8 +53,8 @@
     "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 --loader:.svg=dataurl --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 --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",
+    "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"
   },
@@ -122,19 +126,19 @@
   },
   "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",
-    "CHANGELOG.md",
     "SECURITY.md",
     "LICENSE",
-    "neus-logo.svg",
     "widgets/index.js",
     "widgets/verify-gate/index.js",
     "widgets/verify-gate/dist/VerifyGate.js",

package/sponsor.js

@@ -0,0 +1,95 @@
+import { ValidationError, ApiError, NetworkError } from './errors.js';
+
+/**
+ * Request short-lived billing authorization so verification usage bills the app owner.
+ * Requires a completed app registration (`sponsor-grants` delegation) on orgWallet.
+ */
+export async function fetchSponsorGrant(params = {}) {
+  const {
+    apiUrl = 'https://api.neus.network',
+    appId,
+    orgWallet,
+    verifierIds = [],
+    targetChains = [],
+    origin,
+    expiresInSeconds = 900,
+    fetchImpl = fetch
+  } = params;
+
+  const normalizedAppId = typeof appId === 'string' ? appId.trim() : '';
+  const normalizedOrg = typeof orgWallet === 'string' ? orgWallet.trim().toLowerCase() : '';
+  if (!normalizedAppId) {
+    throw new ValidationError('appId is required for sponsor grant');
+  }
+  if (!normalizedOrg || !/^0x[a-f0-9]{40}$/.test(normalizedOrg)) {
+    throw new ValidationError('orgWallet must be a valid EVM address');
+  }
+
+  let base = String(apiUrl || 'https://api.neus.network').replace(/\/+$/, '');
+  try {
+    const url = new URL(base);
+    if (url.hostname.endsWith('neus.network') && url.protocol === 'http:') {
+      url.protocol = 'https:';
+    }
+    base = url.toString().replace(/\/+$/, '');
+  } catch {
+    void 0;
+  }
+
+  const headers = {
+    'Content-Type': 'application/json',
+    Accept: 'application/json',
+    'X-Neus-App': normalizedAppId,
+    'X-Neus-Sdk': 'js'
+  };
+  if (typeof origin === 'string' && origin.trim()) {
+    headers.Origin = origin.trim();
+  }
+
+  const body = {
+    orgWallet: normalizedOrg,
+    scope: 'sponsored-verification',
+    expiresInSeconds,
+    ...(Array.isArray(verifierIds) && verifierIds.length > 0
+      ? { verifierIds: verifierIds.map((v) => String(v).trim()).filter(Boolean).slice(0, 25) }
+      : {}),
+    ...(Array.isArray(targetChains) && targetChains.length > 0
+      ? { targetChains: targetChains.filter((n) => Number.isFinite(Number(n))).slice(0, 25) }
+      : {})
+  };
+
+  let response;
+  try {
+    response = await fetchImpl(`${base}/api/v1/sponsor/grant`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body)
+    });
+  } catch (error) {
+    throw new NetworkError(`Sponsor grant request failed: ${error?.message || String(error)}`);
+  }
+
+  let payload;
+  try {
+    payload = await response.json();
+  } catch {
+    payload = { success: false, error: { message: 'Invalid JSON response' } };
+  }
+
+  if (!response.ok || payload?.success !== true) {
+    throw ApiError.fromResponse(response, payload);
+  }
+
+  const token = payload?.data?.sponsorGrant;
+  if (!token || typeof token !== 'string') {
+    throw new ApiError('Sponsor grant response missing sponsorGrant token', payload?.error);
+  }
+
+  return {
+    sponsorGrant: token,
+    exp: payload?.data?.exp,
+    orgWallet: payload?.data?.orgWallet || normalizedOrg,
+    appId: payload?.data?.appId || normalizedAppId,
+    maxCredits: payload?.data?.maxCredits
+  };
+}

package/types.d.ts

@@ -1,4 +1,4 @@
-declare module '@neus/sdk' {
+declare module '@neus/sdk' {
   export interface Eip1193Provider {
     request(args: { method: string; params?: unknown[] | Record<string, unknown> }): Promise<unknown>;
   }
@@ -57,9 +57,18 @@ declare module '@neus/sdk' {
 
   export interface NeusClientConfig {
     apiUrl?: string;
+    /** Optional server profile key — MCP/CI only; not required for VerifyGate or gateCheck. */
     apiKey?: string;
+    /** Public app attribution id (non-secret). */
     appId?: string;
-    /** Optional: only when using legacy `delegationQHash` on verify requests. App-linked servers rely on `appId` + Origin + stored delegation. */
+    /** Hub wallet that pays for user verification checks (your NEUS account). */
+    billingWallet?: string;
+    /** Alias for billingWallet. */
+    sponsorOrgWallet?: string;
+    orgWallet?: string;
+    /** Site origin used when issuing billing authorization (defaults to browser origin). */
+    appOrigin?: string;
+    /** Advanced server path only; use appId + billingWallet for the default app flow. */
     appLinkQHash?: string;
     paymentSignature?: string;
     extraHeaders?: Record<string, string>;
@@ -68,6 +77,26 @@ declare module '@neus/sdk' {
     enableLogging?: boolean;
   }
 
+  export interface FetchSponsorGrantParams {
+    apiUrl?: string;
+    appId: string;
+    orgWallet: string;
+    verifierIds?: string[];
+    targetChains?: number[];
+    origin?: string;
+    expiresInSeconds?: number;
+  }
+
+  export interface FetchSponsorGrantResult {
+    sponsorGrant: string;
+    exp?: number;
+    orgWallet: string;
+    appId: string;
+    maxCredits?: number;
+  }
+
+  export function fetchSponsorGrant(params: FetchSponsorGrantParams): Promise<FetchSponsorGrantResult>;
+
   export interface VerificationOptions {
     privacyLevel?: PrivacyLevel;
     enableIpfs?: boolean;
@@ -450,6 +479,7 @@ declare module '@neus/sdk' {
   export interface GetProofsOptions {
     limit?: number;
     offset?: number;
+    cursor?: string;
     chain?: string;
     signatureMethod?: string;
   }
@@ -460,6 +490,8 @@ declare module '@neus/sdk' {
     totalCount: number;
     hasMore: boolean;
     nextOffset?: number | null;
+    /** Keyset continuation when the API returns cursor paging (preferred over deep offsets). */
+    nextCursor?: string | null;
   }
 
   export interface GateRequirement {
@@ -485,6 +517,8 @@ declare module '@neus/sdk' {
 
   export interface GateCheckApiParams {
     address: string;
+    /** Published gate handle; resolves checks server-side (preferred public path). */
+    gateId?: string;
     verifierIds?: string[] | string;
     requireAll?: boolean;
     minCount?: number;
@@ -850,6 +884,8 @@ declare module '@neus/sdk' {
 
 declare module '@neus/sdk/widgets' {
   export interface VerifyGateProps {
+    /** Published gate checkout handle (default integration path). */
+    gateId?: string;
     requiredVerifiers?: string[];
     onVerified?: (result: {
       qHash: string;
@@ -881,12 +917,8 @@ declare module '@neus/sdk/widgets' {
     oauthProvider?: string;
     style?: Record<string, any>;
     children?: any;
-    verifierOptions?: Record<string, any>;
-    verifierData?: Record<string, any>;
-    proofOptions?: Record<string, any>;
     strategy?: 'reuse-or-create' | 'reuse' | 'fresh';
     checkExisting?: boolean;
-    maxProofAgeMs?: number;
     allowPrivateReuse?: boolean;
     showBrand?: boolean;
     disabled?: boolean;
@@ -967,3 +999,31 @@ declare module '@neus/sdk/widgets/verify-gate' {
 declare module '@neus/sdk/client' {
   export { NeusClient } from '@neus/sdk';
 }
+
+declare module '@neus/sdk/mcp-hosts' {
+  export type McpInstallClient = 'claude' | 'codex' | 'cursor' | 'vscode';
+  export type McpInstallHost = 'cursor' | 'claude' | 'codex';
+
+  export const NEUS_MCP_SERVER_NAME: string;
+  export const NEUS_MCP_URL: string;
+  export const NEUS_SETUP_CLI: string;
+  export const NEUS_AUTH_CLI: string;
+  export const NEUS_MCP_SETUP_DOCS_URL: string;
+  export const MCP_INSTALL_CLIENTS: McpInstallClient[];
+  export const MCP_INSTALL_HOSTS: McpInstallHost[];
+  export const IDE_HOST_LABELS: Record<McpInstallHost, string>;
+  export const IDE_HOST_BRAND_LOGOS: Record<McpInstallHost, string>;
+
+  export function buildNeusMcpHttpConfig(accessKey?: string | null): {
+    type: 'http';
+    url: string;
+    headers?: { Authorization: string };
+  };
+
+  export function buildCursorMcpInstallUrl(accessKey?: string | null): string;
+  export function buildVsCodeMcpInstallUrl(accessKey?: string | null): string;
+  export function buildAuthCommandForClient(client: McpInstallClient): string;
+  export function buildSetupCommandForClient(client: McpInstallClient, accessKey?: string | null): string;
+  export function buildSetupCommandForHost(host: McpInstallHost, accessKey?: string | null): string;
+  export function supportsMcpInstallDeeplink(host: McpInstallHost): boolean;
+}

package/utils.js

@@ -1023,6 +1023,8 @@ export function getHostedCheckoutUrl(opts = {}) {
   if (opts.intent) params.set('intent', String(opts.intent));
   if (opts.origin) params.set('origin', String(opts.origin));
   if (opts.oauthProvider) params.set('oauthProvider', String(opts.oauthProvider));
+  if (opts.appId) params.set('appId', String(opts.appId));
+  if (opts.billingWallet) params.set('billingWallet', String(opts.billingWallet).trim().toLowerCase());
   const qs = params.toString();
   return qs ? `${base}?${qs}` : base;
 }

package/widgets/README.md

@@ -10,22 +10,18 @@ npm install @neus/sdk react react-dom
 
 ## VerifyGate
 
-Create mode defaults to **private**. Override `proofOptions` only when you need public visibility for link-based or public checks.
+Create mode opens Hosted Verify. The published gate owns verifier inputs, pricing, and checkout policy.
 
 ```jsx
 import { VerifyGate } from '@neus/sdk/widgets';
 
 export function Page() {
   return (
-    <VerifyGate
-      appId="your-app-id"
-      requiredVerifiers={['nft-ownership']}
-      verifierData={{
-        'nft-ownership': { contractAddress: '0x...', tokenId: '1', chainId: 8453 }
-      }}
-    >
-      <div>Unlocked</div>
-    </VerifyGate>
+    <VerifyGate
+      gateId="gate_abc123"
+    >
+      <div>Unlocked</div>
+    </VerifyGate>
   );
 }
 ```
@@ -35,7 +31,7 @@ export function Page() {
 ```jsx
 import { ProofBadge } from '@neus/sdk/widgets';
 
-<ProofBadge qHash="0x..." showChains />
+<ProofBadge qHash={proof.qHash} showChains />
 ```
 
 ## Docs