@neus/sdk 1.1.0 → 1.1.2

package/README.md

@@ -1,10 +1,10 @@
 # @neus/sdk
 
-Create, check, and reuse NEUS trust receipts from apps and backends. The same package ships the **`neus`** CLI for hosted MCP setup and portable agent import.
+Create, check, and reuse NEUS trust receipts from apps and backends. The same package ships the **`neus`** CLI for hosted MCP setup.
 
 NEUS makes trust portable across apps, agents, and ecosystems before access, payment, or action.
 
-**Status:** [Live and Operational for Production Apps](https://docs.neus.network/platform/status).
+Roadmap: [docs.neus.network/platform/status](https://docs.neus.network/platform/status)
 
 ## Install (library)
 
@@ -12,29 +12,25 @@ NEUS makes trust portable across apps, agents, and ecosystems before access, pay
 npm install @neus/sdk
 ```
 
-## Bring Your Own Agent (BYOA) in 30 Seconds
+## Connect editors and assistants
 
-Already have an agent setup? Use the CLI to instantly scan and import your local agent setups—including instructions, memories, rules, skills, and MCP servers from **OpenClaw, Cursor, Claude Code, and Claude Desktop**—straight into the NEUS trust network:
+One command detects your environment and configures hosted MCP for Claude Code, Codex, Cursor, or VS Code.
 
 ```bash
-npx -y -p @neus/sdk neus import
+npx -y -p @neus/sdk neus setup
+npx -y -p @neus/sdk neus doctor --live
 ```
 
-This automatically prepares your portable NEUS agent manifest, maps your credentials, and secures a reusable trust receipt for your workflows.
+Call `neus_context` in your MCP client. For agent workflows, call `neus_agent_link` before assuming identity or delegation is ready.
 
-*To check what will be imported without writing changes:*
-```bash
-npx -y -p @neus/sdk neus import --dry-run
-```
-
-## Connect editors and assistants
+## MCP docs
 
 | Topic                             | Link                                                                          |
 | --------------------------------- | ----------------------------------------------------------------------------- |
 | Setup, JSON snippets, and headers | [MCP setup](https://docs.neus.network/mcp/setup)                              |
 | Tools and session order           | [MCP overview](https://docs.neus.network/mcp/overview)                        |
 | Discovery URLs                    | [Discovery and endpoints](https://docs.neus.network/mcp/endpoints)            |
-| Claude Code skill bundle          | [NEUS for Claude Code](https://docs.neus.network/mcp/claude-code-marketplace) |
+| NEUS for AI assistants          | [NEUS for AI assistants](https://docs.neus.network/mcp/ide-plugin)          |
 
 Prefer `neus setup` over hand-editing config files so every host stays on **`https://mcp.neus.network/mcp`**.
 
@@ -46,32 +42,32 @@ Prefer `neus setup` over hand-editing config files so every host stays on **`htt
 - Agent identity and scoped delegation
 - MCP setup for assistants and agent tools
 
-## Fastest path: Hosted Verify
+## Hosted Verify
 
-Use Hosted Verify when you want NEUS to handle the signing/verification flow outside your app UI.
+Use Hosted Verify when you want NEUS to handle the signing/verification flow outside your app UI. Prefer a **published gate**:
 
 ```js
 import { getHostedCheckoutUrl } from '@neus/sdk';
 
 const url = getHostedCheckoutUrl({
-  verifiers: ['ownership-basic'],
+  gateId: 'gate_abc123',
   returnUrl: 'https://yourapp.com/auth/callback'
 });
 
 window.location.assign(url);
 ```
 
-After completion, NEUS redirects back with a receipt ID. Store it with your user or record.
+After completion, NEUS redirects back with a `qHash`. Store it with your user or record.
 
-## Create a receipt directly
+## Advanced: in-app signing
 
-Use this when your app handles signing. This example is EVM. For non-EVM wallets, pass the provider explicitly and include `chain` as a CAIP-2 value.
+Use this only when your app intentionally handles signing. This example is EVM. For non-EVM accounts, pass the provider explicitly and include `chain` as a CAIP-2 value.
 
 ```js
 import { NeusClient } from '@neus/sdk';
 
 const client = new NeusClient({
-  appId: 'your-app-id'
+  apiUrl: 'https://api.neus.network'
 });
 
 const proof = await client.verify({
@@ -99,7 +95,7 @@ console.log(proof.proofUrl);
 
 ## React widget
 
-Use `VerifyGate` when you want a drop-in verification flow in React.
+Use `VerifyGate` with your published `gateId`:
 
 ```jsx
 import { VerifyGate } from '@neus/sdk/widgets';
@@ -107,44 +103,29 @@ import { VerifyGate } from '@neus/sdk/widgets';
 export function Page() {
   return (
     <VerifyGate
-      appId="your-app-id"
-      requiredVerifiers={['ownership-basic']}
-      verifierData={{
-        'ownership-basic': {
-          owner: '0x...',
-          contentType: 'application/json',
-          content: JSON.stringify({
-            title: 'Verified claim',
-            summary: 'Public summary of what is being proven.'
-          }),
-          reference: {
-            type: 'url',
-            id: 'https://example.com/source'
-          }
-        }
-      }}
+      gateId="gate_abc123"
       onVerified={result => {
         console.log(result.qHash || result.qHashes);
       }}
-    />
+    >
+      <section>Unlocked content</section>
+    </VerifyGate>
   );
 }
 ```
 
 ## Check receipts
 
-Use `gateCheck` from trusted server code when you need allow/deny or eligibility checks.
+Use `gateCheck` from trusted server code when you need allow/deny before access:
 
 ```js
 import { NeusClient } from '@neus/sdk';
 
-const client = new NeusClient({
-  appId: 'your-app-id'
-});
+const client = new NeusClient();
 
 const result = await client.gateCheck({
-  address: '0x...',
-  verifierIds: ['ownership-basic']
+  gateId: 'gate_abc123',
+  address: '0x...'
 });
 
 if (!result.data?.eligible) {
@@ -171,30 +152,27 @@ Never ship access keys in browser code.
 ```js
 const client = new NeusClient({
   apiUrl: 'https://api.neus.network',
-  appId: 'your-app-id',
   timeout: 30000
 });
 ```
 
-`appId` is public attribution for your app.
+`appId` is optional public attribution for advanced server/app flows. Published gate checkout and `gateCheck({ gateId })` do not require it.
 `apiKey` / `npk_*` is optional and server-side only.
 
 ## MCP step-by-step
 
 ```bash
 npx -y -p @neus/sdk neus setup
-npx -y -p @neus/sdk neus auth
 npx -y -p @neus/sdk neus doctor --live
 ```
 
-Re-sign in or rotate credentials:
+`neus setup` configures MCP and signs you in: `NEUS_ACCESS_KEY` from the environment when set, otherwise the selected host starts OAuth. Cursor, VS Code, and Claude Code use browser sign-in on NEUS. Pass `--access-key <npk_...>` only to override.
 
-```bash
-npx -y -p @neus/sdk neus auth
-npx -y -p @neus/sdk neus auth --access-key <npk_...>   # servers and CI only
-```
+Codex owns its local MCP OAuth session. Use `npx -y -p @neus/sdk neus setup --client codex`, then `npx -y -p @neus/sdk neus auth --client codex`.
+
+Integrators embedding install UX in apps should import **`@neus/sdk/mcp-hosts`** (setup commands, deeplinks, host labels) instead of duplicating strings.
 
-Claude Code users can add the optional **`neus-mcp@neus`** skill bundle, then run **`neus setup`** and **`neus auth`**. See [NEUS for Claude Code](https://docs.neus.network/mcp/claude-code-marketplace).
+Editors with plugin marketplaces can install **`neus-trust@neus`** for the bundled session workflow. In Claude Code, run `/plugin marketplace add https://github.com/neus/network` and `/plugin install neus-trust@neus` inside chat. Other hosts: [NEUS for AI assistants](https://docs.neus.network/mcp/ide-plugin).
 
 ## Docs
 

package/cjs/client.cjs

@@ -129,6 +129,83 @@ var ConfigurationError = class extends SDKError {
   }
 };
 
+// sponsor.js
+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 {
+  }
+  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
+  };
+}
+
 // utils.js
 var PORTABLE_PROOF_SIGNER_HEADER = "Portable Proof Verification Request";
 var BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
@@ -746,6 +823,54 @@ var NeusClient = class {
       }
     } catch {
     }
+    this._sponsorGrantCache = null;
+  }
+  _getBillingWallet() {
+    const raw = this.config.billingWallet || this.config.sponsorOrgWallet || this.config.orgWallet || null;
+    if (typeof raw !== "string") return null;
+    const trimmed = raw.trim().toLowerCase();
+    return /^0x[a-f0-9]{40}$/.test(trimmed) ? trimmed : null;
+  }
+  _resolveIntegratorOrigin() {
+    if (typeof this.config.appOrigin === "string" && this.config.appOrigin.trim()) {
+      return this.config.appOrigin.trim();
+    }
+    try {
+      if (typeof window !== "undefined" && window.location?.origin) {
+        return window.location.origin;
+      }
+    } catch {
+    }
+    return null;
+  }
+  async _resolveSponsorGrantHeaders(verifierIds = []) {
+    const appId = typeof this.config.appId === "string" ? this.config.appId.trim() : "";
+    const orgWallet = this._getBillingWallet();
+    if (!appId || !orgWallet) {
+      return {};
+    }
+    const normalizedVerifierIds = Array.isArray(verifierIds) ? verifierIds.map((v) => String(v || "").trim()).filter(Boolean).slice(0, 25) : [];
+    const cacheKey = `${appId}:${orgWallet}:${normalizedVerifierIds.join(",")}`;
+    const now = Date.now();
+    if (this._sponsorGrantCache && this._sponsorGrantCache.key === cacheKey && this._sponsorGrantCache.expMs > now + 3e4) {
+      return { "X-Sponsor-Grant": this._sponsorGrantCache.token };
+    }
+    const origin = this._resolveIntegratorOrigin();
+    const grant = await fetchSponsorGrant({
+      apiUrl: this.baseUrl,
+      appId,
+      orgWallet,
+      verifierIds: normalizedVerifierIds,
+      origin
+    });
+    const expSeconds = Number(grant?.exp);
+    const expMs = Number.isFinite(expSeconds) && expSeconds > 0 ? expSeconds * 1e3 : now + 15 * 60 * 1e3;
+    this._sponsorGrantCache = {
+      key: cacheKey,
+      token: grant.sponsorGrant,
+      expMs
+    };
+    return { "X-Sponsor-Grant": grant.sponsorGrant };
   }
   _getHubChainId() {
     const configured = Number(this.config?.hubChainId);
@@ -1271,21 +1396,20 @@ var NeusClient = class {
             return hex;
           }
         };
-        const isFarcasterWallet = (() => {
+        const isBaseMiniAppWallet = (() => {
           if (typeof window === "undefined") return false;
           try {
             const w = window;
-            const fc = w.farcaster;
-            if (!fc || !fc.context) return false;
-            const fcProvider = fc.provider || fc.walletProvider || fc.context && fc.context.walletProvider;
-            if (fcProvider === provider) return true;
-            if (w.mini && w.mini.wallet === provider && fc && fc.context) return true;
-            if (w.ethereum === provider && fc && fc.context) return true;
+            const mini = w.mini;
+            if (!mini) return false;
+            const miniProvider = mini.wallet || mini.provider;
+            if (miniProvider === provider) return true;
+            if (w.ethereum === provider && mini) return true;
           } catch {
           }
           return false;
         })();
-        if (isFarcasterWallet) {
+        if (isBaseMiniAppWallet) {
           try {
             const hexMsg = toHexUtf82(message);
             signature2 = await provider.request({ method: "personal_sign", params: [hexMsg, walletAddress2] });
@@ -1418,7 +1542,8 @@ ${bytes.length}`;
       ...delegationQHash && { delegationQHash },
       options: optionsPayload
     };
-    const response = await this._makeRequest("POST", "/api/v1/verification", requestData);
+    const sponsorHeaders = await this._resolveSponsorGrantHeaders(normalizedVerifierIds);
+    const response = await this._makeRequest("POST", "/api/v1/verification", requestData, sponsorHeaders);
     if (!response.success) {
       throw new ApiError(`Verification failed: ${response.error?.message || "Unknown error"}`, response.error);
     }
@@ -1633,7 +1758,9 @@ ${bytes.length}`;
     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))}`);
-    if (options.offset) qs.push(`offset=${encodeURIComponent(String(options.offset))}`);
+    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 query = qs.length ? `?${qs.join("&")}` : "";
     const response = await this._makeRequest(
@@ -1649,7 +1776,8 @@ ${bytes.length}`;
       proofs: Array.isArray(proofs) ? proofs : [],
       totalCount: response.data?.totalCount ?? proofs.length,
       hasMore: Boolean(response.data?.hasMore),
-      nextOffset: response.data?.nextOffset ?? null
+      nextOffset: response.data?.nextOffset ?? null,
+      nextCursor: typeof response.data?.nextCursor === "string" && response.data.nextCursor.trim() ? response.data.nextCursor.trim() : null
     };
   }
   async getPrivateProofsByWallet(walletAddress, options = {}, wallet = null) {
@@ -1701,7 +1829,9 @@ ${bytes.length}`;
     }
     const qs = [];
     if (options.limit) qs.push(`limit=${encodeURIComponent(String(options.limit))}`);
-    if (options.offset) qs.push(`offset=${encodeURIComponent(String(options.offset))}`);
+    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 query = qs.length ? `?${qs.join("&")}` : "";
     const response = await this._makeRequest("GET", `/api/v1/proofs/by-wallet/${encodeURIComponent(pathId)}${query}`, null, {
@@ -1719,7 +1849,8 @@ ${bytes.length}`;
       proofs: Array.isArray(proofs) ? proofs : [],
       totalCount: response.data?.totalCount ?? proofs.length,
       hasMore: Boolean(response.data?.hasMore),
-      nextOffset: response.data?.nextOffset ?? null
+      nextOffset: response.data?.nextOffset ?? null,
+      nextCursor: typeof response.data?.nextCursor === "string" && response.data.nextCursor.trim() ? response.data.nextCursor.trim() : null
     };
   }
   async gateCheck(params = {}) {
@@ -1727,6 +1858,8 @@ ${bytes.length}`;
     if (!validateUniversalAddress(address, params.chain)) {
       throw new ValidationError("Valid address is required");
     }
+    const gateIdParam = typeof params.gateId === "string" ? params.gateId.trim() : "";
+    const verifierIds = gateIdParam ? void 0 : params.verifierIds;
     const qs = new URLSearchParams();
     qs.set("address", address);
     const setIfPresent = (key, value) => {
@@ -1748,7 +1881,8 @@ ${bytes.length}`;
       }
       setIfPresent(key, value);
     };
-    setCsvIfPresent("verifierIds", params.verifierIds);
+    setIfPresent("gateId", gateIdParam);
+    setCsvIfPresent("verifierIds", verifierIds);
     setBoolIfPresent("requireAll", params.requireAll);
     setIfPresent("minCount", params.minCount);
     setIfPresent("sinceDays", params.sinceDays);
@@ -1811,7 +1945,20 @@ ${bytes.length}`;
         };
       }
     }
-    const response = await this._makeRequest("GET", `/api/v1/proofs/check?${qs.toString()}`, null, headersOverride);
+    let mergedHeaders = headersOverride;
+    if (!mergedHeaders && !gateIdParam) {
+      try {
+        const sponsorHeaders = await this._resolveSponsorGrantHeaders(
+          Array.isArray(verifierIds) ? verifierIds : verifierIds ? [verifierIds] : []
+        );
+        if (sponsorHeaders && Object.keys(sponsorHeaders).length > 0) {
+          mergedHeaders = sponsorHeaders;
+        }
+      } catch (error) {
+        this._log("Sponsor grant unavailable for gateCheck (continuing without)", error?.message || String(error));
+      }
+    }
+    const response = await this._makeRequest("GET", `/api/v1/proofs/check?${qs.toString()}`, null, mergedHeaders);
     if (!response.success) {
       throw new ApiError(`Gate check failed: ${response.error?.message || "Unknown error"}`, response.error);
     }

package/cjs/errors.cjs

@@ -26,9 +26,7 @@ __export(errors_exports, {
   NetworkError: () => NetworkError,
   SDKError: () => SDKError,
   ValidationError: () => ValidationError,
-  VerificationError: () => VerificationError,
-  createErrorFromGeneric: () => createErrorFromGeneric,
-  default: () => errors_default
+  VerificationError: () => VerificationError
 });
 module.exports = __toCommonJS(errors_exports);
 var SDKError = class _SDKError extends Error {
@@ -160,36 +158,6 @@ var AuthenticationError = class extends SDKError {
     };
   }
 };
-function createErrorFromGeneric(error, context = {}) {
-  if (error instanceof SDKError) {
-    return error;
-  }
-  if (NetworkError.isNetworkError(error)) {
-    return new NetworkError(
-      error.message || "Network error occurred",
-      error.code || "NETWORK_ERROR",
-      error
-    );
-  }
-  if (error.name === "AbortError" || error.message.includes("timeout")) {
-    return new NetworkError("Request timeout", "TIMEOUT", error);
-  }
-  return new SDKError(
-    error.message || "Unknown error occurred",
-    error.code || "UNKNOWN_ERROR",
-    { originalError: error, context }
-  );
-}
-var errors_default = {
-  SDKError,
-  ApiError,
-  ValidationError,
-  NetworkError,
-  ConfigurationError,
-  VerificationError,
-  AuthenticationError,
-  createErrorFromGeneric
-};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ApiError,
@@ -198,6 +166,5 @@ var errors_default = {
   NetworkError,
   SDKError,
   ValidationError,
-  VerificationError,
-  createErrorFromGeneric
+  VerificationError
 });

package/cjs/gates.cjs

@@ -36,8 +36,7 @@ __export(gates_exports, {
   WEEK: () => WEEK,
   YEAR: () => YEAR,
   combineGates: () => combineGates,
-  createGate: () => createGate,
-  default: () => gates_default
+  createGate: () => createGate
 });
 module.exports = __toCommonJS(gates_exports);
 var HOUR = 60 * 60 * 1e3;
@@ -77,25 +76,6 @@ function combineGates(...gates) {
   }
   return combined;
 }
-var gates_default = {
-  HOUR,
-  DAY,
-  WEEK,
-  MONTH,
-  YEAR,
-  GATE_NFT_HOLDER,
-  GATE_TOKEN_HOLDER,
-  GATE_CONTRACT_ADMIN,
-  GATE_DOMAIN_OWNER,
-  GATE_LINKED_WALLETS,
-  GATE_AGENT_IDENTITY,
-  GATE_AGENT_DELEGATION,
-  GATE_CONTENT_MODERATION,
-  GATE_WALLET_RISK,
-  GATE_PSEUDONYM,
-  createGate,
-  combineGates
-};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DAY,