@neus/sdk 1.1.0 → 1.1.1

package/README.md

@@ -1,206 +1,206 @@
-# @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.
-
-**Status:** [Live and Operational for Production Apps](https://docs.neus.network/platform/status).
-
-## Install (library)
-
-```bash
-npm install @neus/sdk
-```
-
-## Bring Your Own Agent (BYOA) in 30 Seconds
-
-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:
-
-```bash
-npx -y -p @neus/sdk neus import
-```
-
-This automatically prepares your portable NEUS agent manifest, maps your credentials, and secures a reusable trust receipt for your workflows.
-
-*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)            |
-| Claude Code skill bundle          | [NEUS for Claude Code](https://docs.neus.network/mcp/claude-code-marketplace) |
-
-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 receipt ID. Store it with your user or record.
-
-## Create a receipt directly
-
-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.
-
-```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
-```
-
-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).
-
-## 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 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

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);
@@ -1418,7 +1543,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);
     }
@@ -1811,7 +1937,20 @@ ${bytes.length}`;
         };
       }
     }
-    const response = await this._makeRequest("GET", `/api/v1/proofs/check?${qs.toString()}`, null, headersOverride);
+    let mergedHeaders = headersOverride;
+    if (!mergedHeaders) {
+      try {
+        const sponsorHeaders = await this._resolveSponsorGrantHeaders(
+          Array.isArray(params.verifierIds) ? params.verifierIds : params.verifierIds ? [params.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,