@neus/sdk 1.1.1 → 1.1.4

package/README.md

@@ -1,206 +1,191 @@
-# @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.
-
-NEUS makes trust portable across apps, agents, and ecosystems before access, payment, or action.
-
-Roadmap: [docs.neus.network/platform/status](https://docs.neus.network/platform/status)
-
-## Install (library)
-
-```bash
-npm install @neus/sdk
-```
-
-## Bring Your Own Agent (BYOA)
-
-Already have an agent setup? Use the CLI to package supported local agent context, including instructions, rules, skills, and MCP server references from **OpenClaw, Cursor, Claude Code, and Claude Desktop**:
-
-```bash
-npx -y -p @neus/sdk neus import
-```
-
-This prepares a local portable-agent manifest. In MCP, call `neus_agent_link` first; if setup is missing, use `neus_agent_create`, complete the hosted or signing steps, then call `neus_agent_link` again until `linked: true`.
-
-*To check what will be imported without writing changes:*
-```bash
-npx -y -p @neus/sdk neus import --dry-run
-```
-
-## Connect editors and assistants
-
-| 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)            |
-| 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`**.
-
-## What you can ship
-
-- Hosted verification flows that return a reusable receipt
-- Server checks before access, rewards, payments, or actions
-- React gates with `VerifyGate`
-- Agent identity and scoped delegation
-- MCP setup for assistants and agent tools
-
-## Fastest path: Hosted Verify
-
-Use Hosted Verify when you want NEUS to handle the signing/verification flow outside your app UI.
-
-```js
-import { getHostedCheckoutUrl } from '@neus/sdk';
-
-const url = getHostedCheckoutUrl({
-  verifiers: ['ownership-basic'],
-  returnUrl: 'https://yourapp.com/auth/callback'
-});
-
-window.location.assign(url);
-```
-
-After completion, NEUS redirects back with a `qHash`. Store it with your user or record.
-
-## Advanced: in-app signing
-
-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'
-});
-
-const proof = await client.verify({
-  verifier: 'ownership-basic',
-  data: {
-    owner: '0x...',
-    contentType: 'application/json',
-    content: JSON.stringify({
-      title: 'Verified claim',
-      type: 'project-update',
-      summary: 'Public summary of what is being proven.'
-    }),
-    reference: {
-      type: 'url',
-      id: 'https://example.com/source',
-      title: 'Source record'
-    }
-  },
-  wallet: window.ethereum // EVM provider
-});
-
-console.log(proof.qHash);
-console.log(proof.proofUrl);
-```
-
-## React widget
-
-Use `VerifyGate` when you want a drop-in verification flow in React.
-
-```jsx
-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'
-          }
-        }
-      }}
-      onVerified={result => {
-        console.log(result.qHash || result.qHashes);
-      }}
-    />
-  );
-}
-```
-
-## Check receipts
-
-Use `gateCheck` from trusted server code when you need allow/deny or eligibility checks.
-
-```js
-import { NeusClient } from '@neus/sdk';
-
-const client = new NeusClient({
-  appId: 'your-app-id'
-});
-
-const result = await client.gateCheck({
-  address: '0x...',
-  verifierIds: ['ownership-basic']
-});
-
-if (!result.data?.eligible) {
-  throw new Error('Access denied');
-}
-```
-
-Never ship access keys in browser code.
-
-## Core methods
-
-| Method                          | Use it for                                  |
-| ------------------------------- | ------------------------------------------- |
-| `getHostedCheckoutUrl()`        | Send a user to Hosted Verify                |
-| `client.verify()`               | Create a proof                              |
-| `client.getProof()`             | Fetch a receipt by `qHash`                  |
-| `client.pollProofStatus()`      | Wait for async completion                   |
-| `client.gateCheck()`            | Server-side eligibility checks              |
-| `client.checkGate()`            | Local preview against already-loaded proofs |
-| `client.createWalletLinkData()` | Wallet-link payloads                        |
-
-## Configuration
-
-```js
-const client = new NeusClient({
-  apiUrl: 'https://api.neus.network',
-  appId: 'your-app-id',
-  timeout: 30000
-});
-```
-
-`appId` is public attribution for your app.
-`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:
-
-```bash
-npx -y -p @neus/sdk neus auth
-npx -y -p @neus/sdk neus auth --access-key <npk_...>   # servers and CI only
-```
-
-Editors with plugin marketplaces can install **`neus-trust@neus`** for the bundled session workflow. OpenClaw, Hermes, and other runtimes: see [NEUS for AI assistants](https://docs.neus.network/mcp/ide-plugin) for exact paths.
-
-## Docs
-
-- Quickstart: https://docs.neus.network/quickstart
-- JavaScript SDK: https://docs.neus.network/sdks/javascript
-- Ownership Basic: https://docs.neus.network/verification/ownership-basic
-- Widgets: https://docs.neus.network/widgets/overview
-- MCP: https://docs.neus.network/mcp/overview
-- API: https://docs.neus.network/api/overview
+# @neus/sdk
+
+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.
+
+Roadmap: [docs.neus.network/platform/status](https://docs.neus.network/platform/status)
+
+## Install (library)
+
+```bash
+npm install @neus/sdk
+```
+
+## Connect editors and assistants
+
+One command detects your environment and configures hosted MCP for Claude Code, Codex, Cursor, or VS Code.
+
+```bash
+npx -y -p @neus/sdk neus setup
+npx -y -p @neus/sdk neus doctor --live
+```
+
+Open your MCP client and ask the assistant to use NEUS Trust.
+
+## 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)            |
+| Install NEUS Trust                | [Install NEUS Trust](https://docs.neus.network/install)                         |
+
+Prefer `neus setup` over hand-editing config files so every host stays on **`https://mcp.neus.network/mcp`**.
+
+## What you can ship
+
+- Hosted verification flows that return a reusable receipt
+- Server checks before access, rewards, payments, or actions
+- React gates with `VerifyGate`
+- Agent identity and scoped delegation
+- MCP setup for assistants and agent tools
+
+## Hosted Verify
+
+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({
+  gateId: 'gate_your-app-name',
+  returnUrl: 'https://yourapp.com/auth/callback'
+});
+
+window.location.assign(url);
+```
+
+After completion, NEUS redirects back with a `qHash`. Store it with your user or record.
+
+## Advanced: in-app signing
+
+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({
+  apiUrl: 'https://api.neus.network'
+});
+
+const proof = await client.verify({
+  verifier: 'ownership-basic',
+  data: {
+    owner: '0x...',
+    contentType: 'application/json',
+    content: JSON.stringify({
+      title: 'Verified claim',
+      type: 'project-update',
+      summary: 'Public summary of what is being proven.'
+    }),
+    reference: {
+      type: 'url',
+      id: 'https://example.com/source',
+      title: 'Source record'
+    }
+  },
+  wallet: window.ethereum // EVM provider
+});
+
+console.log(proof.qHash);
+console.log(proof.proofUrl);
+```
+
+## React widget
+
+Use `VerifyGate` with your published `gateId`:
+
+```jsx
+import { VerifyGate } from '@neus/sdk/widgets';
+
+export function Page() {
+  return (
+    <VerifyGate
+      gateId="gate_your-app-name"
+      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 before access:
+
+```js
+import { NeusClient } from '@neus/sdk';
+
+const client = new NeusClient();
+
+const result = await client.gateCheck({
+  gateId: 'gate_your-app-name',
+  address: '0x...'
+});
+
+if (!result.data?.eligible) {
+  throw new Error('Access denied');
+}
+```
+
+Never ship access keys in browser code.
+
+## Core methods
+
+| Method                          | Use it for                                  |
+| ------------------------------- | ------------------------------------------- |
+| `getHostedCheckoutUrl()`        | Send a user to Hosted Verify                |
+| `client.verify()`               | Create a proof                              |
+| `client.getProof()`             | Fetch a receipt by `qHash`                  |
+| `client.pollProofStatus()`      | Wait for async completion                   |
+| `client.gateCheck()`            | Server-side eligibility checks              |
+| `client.checkGate()`            | Local preview against already-loaded proofs |
+| `client.createWalletLinkData()` | Wallet-link payloads                        |
+
+## Configuration
+
+```js
+const client = new NeusClient({
+  apiUrl: 'https://api.neus.network',
+  timeout: 30000
+});
+```
+
+`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 doctor --live
+```
+
+`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.
+
+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 install **`neus-trust@neus`** for the bundled session workflow:
+
+```text
+/plugin marketplace add https://github.com/neus/network
+/plugin install neus-trust@neus
+```
+
+Other hosts: [Install NEUS Trust](https://docs.neus.network/install).
+
+## Docs
+
+- Quickstart: https://docs.neus.network/quickstart
+- JavaScript SDK: https://docs.neus.network/sdks/javascript
+- Ownership Basic: https://docs.neus.network/verification/ownership-basic
+- Widgets: https://docs.neus.network/widgets/overview
+- MCP: https://docs.neus.network/mcp/overview
+- API: https://docs.neus.network/api/overview

package/SECURITY.md

@@ -1,38 +1,38 @@
-# NEUS SDK security notes
-
-Treat **wallet signatures** and **API keys** as secrets. Do not log them, expose them to clients, or store them in analytics.
-
-## Authentication model
-
-- **Verification requests** are authenticated with a wallet signature over the **CAIP-380 Portable Proof** six-line signing string. Never roll your own message format in production—use the SDK or the hosted preparation step documented for HTTP integrations.
-- **Proof lookups by `qHash`** are safe for public proofs. Private proofs return a minimal payload unless the caller proves ownership (authenticated owner or signed request).
-- **Owner-only reads** of private proof payloads require an extra owner-signed request. The SDK attaches the required signed headers for you.
-
-## Do not
-
-- Do not treat proof signatures as bearer tokens (they are request-bound).
-- Do not embed API keys in browser apps. Keep API keys server-side only.
-- Do not log or persist proof signatures, API keys, or third-party auth credentials (if your integration uses them).
-
-## Privacy defaults
-
-**`client.verify()`** defaults to **private**.
-
-**`VerifyGate`** create mode also defaults to **private**.
-
-Use public visibility only when you need proof reuse without owner-authenticated access:
-
-- unlisted public: `privacyLevel: 'public'`, `publicDisplay: false`
-- listed public: `privacyLevel: 'public'`, `publicDisplay: true`
-
-Do not treat unlisted public proofs as secret.
-
-`storeOriginalContent` is an advanced storage control. Most integrations should leave the default as-is.
-
-Controls:
-
-- `privacyLevel` - private by default; switch to public only for intentional public reuse
-- `publicDisplay` - discovery vs unlisted
-- `storeOriginalContent` - advanced content-storage control
-
-Discoverable listings require **`privacyLevel: 'public'`** and **`publicDisplay: true`**.
+# NEUS SDK security notes
+
+Treat **wallet signatures** and **API keys** as secrets. Do not log them, expose them to clients, or store them in analytics.
+
+## Authentication model
+
+- **Verification requests** are authenticated with a wallet signature over the **CAIP-380 Portable Proof** six-line signing string. Never roll your own message format in production—use the SDK or the hosted preparation step documented for HTTP integrations.
+- **Proof lookups by `qHash`** are safe for public proofs. Private proofs return a minimal payload unless the caller proves ownership (authenticated owner or signed request).
+- **Owner-only reads** of private proof payloads require an extra owner-signed request. The SDK attaches the required signed headers for you.
+
+## Do not
+
+- Do not treat proof signatures as bearer tokens (they are request-bound).
+- Do not embed API keys in browser apps. Keep API keys server-side only.
+- Do not log or persist proof signatures, API keys, or third-party auth credentials (if your integration uses them).
+
+## Privacy defaults
+
+**`client.verify()`** defaults to **private**.
+
+**`VerifyGate`** create mode also defaults to **private**.
+
+Use public visibility only when you need proof reuse without owner-authenticated access:
+
+- unlisted public: `privacyLevel: 'public'`, `publicDisplay: false`
+- listed public: `privacyLevel: 'public'`, `publicDisplay: true`
+
+Do not treat unlisted public proofs as secret.
+
+`storeOriginalContent` is an advanced storage control. Most integrations should leave the default as-is.
+
+Controls:
+
+- `privacyLevel` - private by default; switch to public only for intentional public reuse
+- `publicDisplay` - discovery vs unlisted
+- `storeOriginalContent` - advanced content-storage control
+
+Discoverable listings require **`privacyLevel: 'public'`** and **`publicDisplay: true`**.

package/cjs/client.cjs

@@ -1396,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] });
@@ -1759,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(
@@ -1775,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) {
@@ -1827,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, {
@@ -1845,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 = {}) {
@@ -1853,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) => {
@@ -1874,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);
@@ -1938,10 +1946,10 @@ ${bytes.length}`;
       }
     }
     let mergedHeaders = headersOverride;
-    if (!mergedHeaders) {
+    if (!mergedHeaders && !gateIdParam) {
       try {
         const sponsorHeaders = await this._resolveSponsorGrantHeaders(
-          Array.isArray(params.verifierIds) ? params.verifierIds : params.verifierIds ? [params.verifierIds] : []
+          Array.isArray(verifierIds) ? verifierIds : verifierIds ? [verifierIds] : []
         );
         if (sponsorHeaders && Object.keys(sponsorHeaders).length > 0) {
           mergedHeaders = sponsorHeaders;