@neus/sdk 1.0.2 → 1.0.4

package/README.md

@@ -1,6 +1,8 @@
-# NEUS SDK
+# @neus/sdk
 
-JavaScript client (and optional widgets) for the NEUS Network verification API.
+[![npm](https://img.shields.io/npm/v/%40neus%2Fsdk?logo=npm&label=%40neus%2Fsdk&color=98C0EF)](https://www.npmjs.com/package/@neus/sdk)
+
+**Portable trust, shipped as APIs and widgets.** The JavaScript SDK runs NEUS verification, polling, and **`gateCheck`**. Store **`proofId`** (your **proof ID**) once, then reuse. NEUS runs the checks; you do not fork verifier logic into your repo.
 
 ## Install
 
@@ -8,105 +10,81 @@ JavaScript client (and optional widgets) for the NEUS Network verification API.
 npm install @neus/sdk
 ```
 
-## Create a proof (browser wallet flow)
+## One-command onboarding
+
+```bash
+npx -y -p @neus/sdk neus init
+```
+
+Prints the hosted MCP URL and documentation links in your terminal - fast setup in IDEs and agent clients.
 
-This path requests a wallet signature in the browser and submits the verification request:
+## Minimal working example
 
 ```javascript
 import { NeusClient } from '@neus/sdk';
 
-const client = new NeusClient({ apiUrl: 'https://api.neus.network' });
+const client = new NeusClient();
 
-const res = await client.verify({
+const proof = await client.verify({
   verifier: 'ownership-basic',
   content: 'Hello NEUS',
-  wallet: window.ethereum
-});
-
-// Proof ID (qHash): stable identifier you can store and use for status polling
-const proofId = res.qHash;
-const status = await client.getStatus(proofId);
-```
-
-## Client configuration
-
-```javascript
-const client = new NeusClient({
-  // Optional: point at a self-hosted deployment
-  apiUrl: 'https://api.neus.network',
-  // Optional: request timeout (ms)
-  timeout: 30000,
+  wallet: window.ethereum,
 });
-```
-
-## Create a proof (server / manual signing)
 
-If you already have a signature over the NEUS Standard Signing String, submit it directly:
+const proofId = proof.proofId;
 
-```javascript
-const res = await client.verify({
+const check = await client.gateCheck({
+  address: '0x...',
   verifierIds: ['ownership-basic'],
-  data: {
-    owner: '0x1111111111111111111111111111111111111111',
-    content: 'Hello NEUS',
-    reference: { type: 'url', id: 'https://example.com' }
-  },
-  walletAddress: '0x1111111111111111111111111111111111111111',
-  signature: '0x...',
-  signedTimestamp: Date.now(),
-  chainId: 84532,
-  options: { privacyLevel: 'private' }
 });
 ```
 
-## What verifiers are available?
+> [Hosted Verify](https://docs.neus.network/cookbook/auth-hosted-verify) | [Get started](https://docs.neus.network/get-started)
 
-Use the API directly (avoids drift):
+## Core methods
 
-- `GET /api/v1/verification/verifiers`
+| Method | Purpose |
+| --- | --- |
+| `client.verify()` | Create proof |
+| `client.getProof()` | Fetch by `proofId` |
+| `client.pollProofStatus()` | Wait for async completion |
+| `client.gateCheck()` | **Server eligibility** (use for real gates) |
+| `client.checkGate()` | Local preview only |
+| `getHostedCheckoutUrl()` | Hosted verify URL |
 
-## Gate checks (recommended for server-side gating)
+## VerifyGate (React)
 
-For production server-side gating, prefer the minimal public endpoint:
+Defaults: unlisted public create (`privacyLevel: 'public'`, `publicDisplay: false`). Set `proofOptions` for other visibility.
 
-```javascript
-const res = await client.gateCheck({
-  address: '0x...',
-  verifierIds: ['token-holding'],
-  contractAddress: '0x...',
-  minBalance: '100',
-  chainId: 1,
-  // Optional: require a recent proof for point-in-time verifiers (example: last hour)
-  since: Date.now() - 60 * 60 * 1000
-});
+```jsx
+import { VerifyGate } from '@neus/sdk/widgets';
 
-if (!res.data?.eligible) {
-  throw new Error('Access denied');
-}
+<VerifyGate appId="your-app-id" requiredVerifiers={['ownership-basic']}>
+  <ProtectedContent />
+</VerifyGate>
 ```
 
-Note: `gateCheck` evaluates **existing public/discoverable proofs**. For strict real-time decisions, create a new proof via `client.verify(...)` (or `POST /api/v1/verification`) and use the final status.
-
-## Resilience & Polling
-
-The SDK is designed for production stability:
-- **Automatic Backoff**: `pollProofStatus()` automatically detects rate limiting (`429`) and applies jittered exponential backoff.
-- **Wallet Identification**: Automatically attaches headers to preferred wallet-based limiting for higher reliability behind shared IPs (NATs).
-
-- Private proof by Proof ID (qHash): `client.getPrivateStatus(qHash, wallet)`
-- Private proofs by wallet/DID: `client.getPrivateProofsByWallet(walletOrDid, { limit, offset }, wallet)`
+[Widgets README](./widgets/README.md)
 
-## React widgets
-
-For UI gating, see `./widgets/README.md`.
-
-Widget imports:
+## Config
 
 ```javascript
-import { VerifyGate, ProofBadge } from '@neus/sdk/widgets';
+const client = new NeusClient({
+  apiUrl: 'https://api.neus.network',
+  appId: 'my-app',
+  timeout: 30000,
+});
 ```
 
-## Reference docs
+## Docs
+
+- [Quickstart](https://docs.neus.network/quickstart)
+- [SDK](https://docs.neus.network/sdks/javascript)
+- [MCP](https://docs.neus.network/mcp/overview) (IDEs and assistants)
+- [Widgets](https://docs.neus.network/widgets/overview)
+- [API](https://docs.neus.network/api/overview)
+- [Hosted Verify](https://docs.neus.network/cookbook/auth-hosted-verify)
+
+## Contributing
 
-- API Reference: `../docs/api/README.md`
-- OpenAPI (JSON): `../docs/api/public-api.json`
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for how to propose documentation, SDK, and example changes.

package/SECURITY.md

@@ -1,29 +1,33 @@
-# 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 (public surface)
-
-- **Verification submission** (`POST /api/v1/verification`) is authenticated by a signature over the **NEUS Standard Signing String**.
-- **Status by Proof ID (qHash)** (`GET /api/v1/verification/status/{qHash}`) is safe to call publicly.
-- **Owner-only reads** of private proof payloads require an additional owner signature. The SDK uses:
-  - `x-wallet-address`
-  - `x-signature`
-  - `x-signed-timestamp`
-
-## 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
-  - third-party auth credentials or provider tokens (if your integration uses them)
-
-## Recommended privacy defaults
-
-- `privacyLevel: 'private'`
-- `publicDisplay: false`
-- `storeOriginalContent: false`
-
-“Discoverable” proofs are **public** (`privacyLevel='public'`) and explicitly opted into discovery (`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 `proofId`** 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** stored results with **original content stored** (owner-authenticated reads).
+
+**`VerifyGate`** create mode defaults to **unlisted public** (`privacyLevel: 'public'`, `publicDisplay: false`, `storeOriginalContent: true`) so gates and `gateCheck` work without extra options.
+
+For raw SDK flows that must power **`gateCheck`** without owner-authenticated access, set **unlisted public** explicitly (`privacyLevel: 'public'`, `publicDisplay: false`). Anyone with the proof id can resolve public proofs. Do not treat unlisted as secret.
+
+**Hide original content** (metadata/hash only): set `storeOriginalContent: false` when your product must not persist original bytes.
+
+Controls:
+
+- `privacyLevel` - private (vaulted to the wallet) vs public (eligible for policy checks without proving owner identity)
+- `publicDisplay` - discovery vs unlisted
+- `storeOriginalContent` - retain original content vs hash/metadata only
+
+Discoverable listings require **`privacyLevel: 'public'`** and **`publicDisplay: true`**.