@neus/sdk 1.0.9 → 1.0.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +130 -57
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # @neus/sdk
2
2
 
3
- [![npm](https://img.shields.io/npm/v/%40neus%2Fsdk?logo=npm&label=%40neus%2Fsdk&color=98C0EF)](https://www.npmjs.com/package/@neus/sdk)
3
+ Create, check, and reuse NEUS trust receipts from apps.
4
4
 
5
- **Portable trust, shipped as APIs and widgets.** For **Web2-style apps**, prefer **Hosted Verify** (`getHostedCheckoutUrl` or `VerifyGate`) so users never touch `window.ethereum` in your UI. Use **`npk_*` + `gateCheck`** on your server for allow/deny. Store **`qHash`**, then reuse it.
5
+ NEUS turns signed claims, ownership checks, account links, access rules, and verification results into portable receipts your app can store, display, and check later.
6
6
 
7
7
  ## Install
8
8
 
@@ -10,95 +10,168 @@
10
10
  npm install @neus/sdk
11
11
  ```
12
12
 
13
- ## Minimal working example (hosted, no wallet in your page)
13
+ ## What you can build
14
14
 
15
- ```javascript
15
+ - Issue a proof that a user, wallet, org, app, file, release, profile, or result belongs to someone
16
+ - Store the returned `qHash` as a durable trust receipt ID
17
+ - Check receipts later for access, eligibility, provenance, or display
18
+ - Add proof-gated UX with React widgets
19
+ - Connect IDEs and agents through optional MCP
20
+
21
+ ## Fastest path: Hosted Verify
22
+
23
+ Use Hosted Verify when you want NEUS to handle the signing/verification flow outside your app UI.
24
+
25
+ ```js
16
26
  import { getHostedCheckoutUrl } from '@neus/sdk';
17
27
 
18
- window.location.href = getHostedCheckoutUrl({
28
+ const url = getHostedCheckoutUrl({
19
29
  verifiers: ['ownership-basic'],
20
- returnUrl: 'https://myapp.com/neus/callback',
30
+ returnUrl: 'https://yourapp.com/neus/callback'
21
31
  });
32
+
33
+ window.location.assign(url);
22
34
  ```
23
35
 
24
- After Hosted Verify, NEUS redirects to `returnUrl` with **`qHash`** in the query string — persist it on your server next to your user id.
36
+ After completion, NEUS redirects back with a `qHash`.
37
+
38
+ Store that `qHash` in your database next to your user, workspace, project, claim, listing, or record.
25
39
 
26
- ## Server check (use your access key, not in the browser)
40
+ ## Create a signed receipt directly
27
41
 
28
- ```javascript
42
+ Use this when your app already controls the signing flow.
43
+
44
+ ```js
29
45
  import { NeusClient } from '@neus/sdk';
30
46
 
31
- const client = new NeusClient({ appId: 'your-app-id' });
47
+ const client = new NeusClient({
48
+ appId: 'your-app-id'
49
+ });
32
50
 
33
- const check = await client.gateCheck({
34
- address: '0x...',
35
- verifierIds: ['ownership-basic'],
51
+ const proof = await client.verify({
52
+ verifier: 'ownership-basic',
53
+ data: {
54
+ owner: '0x...',
55
+ contentType: 'application/json',
56
+ content: JSON.stringify({
57
+ title: 'Verified claim',
58
+ type: 'project-update',
59
+ summary: 'Public summary of what is being proven.'
60
+ }),
61
+ reference: {
62
+ type: 'url',
63
+ id: 'https://example.com/source',
64
+ title: 'Source record'
65
+ }
66
+ },
67
+ wallet: window.ethereum
36
68
  });
69
+
70
+ console.log(proof.qHash);
71
+ console.log(proof.proofUrl);
37
72
  ```
38
73
 
39
- ## Advanced: sign inside your app
74
+ ## React widget
40
75
 
41
- Only when you intentionally need a browser wallet:
76
+ Use `VerifyGate` when you want a drop-in verification flow in React.
42
77
 
43
- ```javascript
44
- import { NeusClient } from '@neus/sdk';
45
-
46
- const client = new NeusClient({ appId: 'your-app-id' });
78
+ ```jsx
79
+ import { VerifyGate } from '@neus/sdk/widgets';
47
80
 
48
- const proof = await client.verify({
49
- verifier: 'ownership-basic',
50
- content: 'Hello NEUS',
51
- wallet: window.ethereum,
52
- });
53
- const qHash = proof.qHash;
81
+ export function Page() {
82
+ return (
83
+ <VerifyGate
84
+ appId="your-app-id"
85
+ requiredVerifiers={['ownership-basic']}
86
+ verifierData={{
87
+ 'ownership-basic': {
88
+ owner: '0x...',
89
+ contentType: 'application/json',
90
+ content: JSON.stringify({
91
+ title: 'Verified claim',
92
+ summary: 'Public summary of what is being proven.'
93
+ }),
94
+ reference: {
95
+ type: 'url',
96
+ id: 'https://example.com/source'
97
+ }
98
+ }
99
+ }}
100
+ onVerified={(result) => {
101
+ console.log(result.qHash || result.qHashes);
102
+ }}
103
+ />
104
+ );
105
+ }
54
106
  ```
55
107
 
56
- ## Core methods
108
+ ## Check receipts
57
109
 
58
- | Method | Purpose |
59
- | --- | --- |
60
- | `client.verify()` | Create proof |
61
- | `client.getProof()` | Fetch by `qHash` |
62
- | `client.pollProofStatus()` | Wait for async completion |
63
- | `client.gateCheck()` | **Server eligibility** (use for real gates) |
64
- | `client.checkGate()` | Local preview only |
65
- | `getHostedCheckoutUrl()` | Hosted verify URL |
66
- | `client.createWalletLinkData()` | Build advanced direct wallet-link payload |
110
+ Use `gateCheck` from trusted server code when you need allow/deny or eligibility checks.
67
111
 
68
- ## VerifyGate (React)
112
+ ```js
113
+ import { NeusClient } from '@neus/sdk';
69
114
 
70
- Defaults: private create (`privacyLevel: 'private'`, `publicDisplay: false`). Set `proofOptions` only when you intentionally need public visibility.
115
+ const client = new NeusClient({
116
+ appId: 'your-app-id'
117
+ });
71
118
 
72
- ```jsx
73
- import { VerifyGate } from '@neus/sdk/widgets';
119
+ const result = await client.gateCheck({
120
+ address: '0x...',
121
+ verifierIds: ['ownership-basic']
122
+ });
74
123
 
75
- <VerifyGate appId="your-app-id" requiredVerifiers={['ownership-basic']}>
76
- <ProtectedContent />
77
- </VerifyGate>
124
+ if (!result.data?.eligible) {
125
+ throw new Error('Access denied');
126
+ }
78
127
  ```
79
128
 
80
- [Widgets README](./widgets/README.md)
129
+ Access keys are only for trusted server, IDE, or agent environments. Never ship access keys in browser code.
130
+
131
+ ## Core methods
132
+
133
+ | Method | Use it for |
134
+ | ------------------------------- | ------------------------------------------- |
135
+ | `getHostedCheckoutUrl()` | Send a user to Hosted Verify |
136
+ | `client.verify()` | Create a proof |
137
+ | `client.getProof()` | Fetch a proof by `qHash` |
138
+ | `client.pollProofStatus()` | Wait for async completion |
139
+ | `client.gateCheck()` | Server-side eligibility checks |
140
+ | `client.checkGate()` | Local preview against already-loaded proofs |
141
+ | `client.createWalletLinkData()` | Advanced wallet-link payloads |
81
142
 
82
- ## Config
143
+ ## Configuration
83
144
 
84
- ```javascript
145
+ ```js
85
146
  const client = new NeusClient({
86
147
  apiUrl: 'https://api.neus.network',
87
- appId: 'my-app',
88
- timeout: 30000,
148
+ appId: 'your-app-id',
149
+ timeout: 30000
89
150
  });
90
151
  ```
91
152
 
92
- ## Docs
153
+ `appId` is public attribution for your app.
154
+ `apiKey` / `npk_*` is optional and server-side only.
155
+
156
+ ## Optional MCP setup
157
+
158
+ Use MCP when you want IDEs, assistants, or agents to inspect receipts, check proof state, or work with NEUS tools.
159
+
160
+ ```bash
161
+ npx -y -p @neus/sdk neus init
162
+ ```
93
163
 
94
- - [Quickstart](https://docs.neus.network/quickstart)
95
- - [Examples](https://docs.neus.network/examples) — start with the [trust receipts showcase](https://github.com/neus/network/tree/main/examples/trust-receipts-showcase) locally; [live demo](https://neus.network/demo) on the product site
96
- - [SDK](https://docs.neus.network/sdks/javascript)
97
- - [MCP](https://docs.neus.network/mcp/overview) for IDEs and assistants
98
- - [Widgets](https://docs.neus.network/widgets/overview)
99
- - [API](https://docs.neus.network/api/overview)
100
- - [Hosted Verify](https://docs.neus.network/cookbook/auth-hosted-verify)
164
+ Add account-aware/private access only when needed:
101
165
 
102
- ## Contributing
166
+ ```bash
167
+ npx -y -p @neus/sdk neus auth --access-key <npk_...>
168
+ ```
169
+
170
+ ## Docs
103
171
 
104
- See [CONTRIBUTING.md](../CONTRIBUTING.md) for how to propose documentation, SDK, and example changes.
172
+ - Quickstart: https://docs.neus.network/quickstart
173
+ - JavaScript SDK: https://docs.neus.network/sdks/javascript
174
+ - Ownership Basic: https://docs.neus.network/verification/ownership-basic
175
+ - Widgets: https://docs.neus.network/widgets/overview
176
+ - MCP: https://docs.neus.network/mcp/overview
177
+ - API: https://docs.neus.network/api/overview
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@neus/sdk",
3
- "version": "1.0.9",
3
+ "version": "1.0.10",
4
4
  "description": "Issue and check NEUS trust receipts across apps, agents, gates, payments, and workflows.",
5
5
  "bin": {
6
6
  "neus": "cli/neus.mjs"