npm package: @neus/sdk
Description: NEUS SDK - Create and verify cryptographic proofs with simple, clean API
Author: NEUS Network
Latest version: 1.0.3

# NEUS SDK

JavaScript client (and optional widgets) for the NEUS Network verification API.

## Install

```bash
npm install @neus/sdk
```

## Create a proof (browser wallet flow)

This path requests a wallet signature in the browser and submits the verification request:

```javascript
import { NeusClient } from '@neus/sdk';

const client = new NeusClient({ apiUrl: 'https://api.neus.network' });

const res = await client.verify({
  verifier: 'ownership-basic',
  content: 'Hello NEUS'
});

// Proof ID (standard). qHash is a deprecated alias.
const proofId = res.proofId;
const status = await client.getStatus(proofId);
```

## Client configuration

```javascript
const client = new NeusClient({
  // Optional: API base URL (default: https://api.neus.network)
  apiUrl: 'https://api.neus.network',
  // Optional: request timeout (ms)
  timeout: 30000,
});
```

## Create a proof (server / manual signing)

If you already have a signature over the NEUS Standard Signing String, submit it directly:

```javascript
const res = await client.verify({
  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?

Use the API directly (avoids drift):

- `GET /api/v1/verification/verifiers`

## Hosted interactive verifiers

For interactive verifiers (`ownership-social`, `ownership-org-oauth`, `proof-of-human`), use `VerifyGate` hosted checkout mode.
These flows require NEUS-hosted popup/redirect UX (OAuth/ZK), not direct wallet-only creation via `client.verify(...)`.

```jsx
import { VerifyGate } from '@neus/sdk/widgets';

export default function HostedGateExample() {
  return (
    <VerifyGate
      requiredVerifiers={['ownership-social']}
      onVerified={(result) => {
        console.log('Hosted verification complete:', result.proofId);
      }}
    >
      <button>Unlock with Social</button>
    </VerifyGate>
  );
}
```

## Gate checks (recommended for server-side gating)

For production server-side gating, prefer the minimal public endpoint:

```javascript
const res = await client.gateCheck({
  address: 'YOUR_WALLET_OR_DID',
  verifierIds: ['token-holding'],
  contractAddress: '0x...',
  minBalance: '100',
  chainId: 8453,
  // Optional: require a recent proof for point-in-time verifiers (example: last hour)
  since: Date.now() - 60 * 60 * 1000
});

if (!res.data?.eligible) {
  throw new Error('Access denied');
}
```

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: `client.getPrivateStatus(proofId, wallet)`
- Private proofs by wallet/DID: `client.getPrivateProofsByWallet(walletOrDid, { limit, offset }, wallet)` (owner dashboard / first-party UX only; not recommended for integrator gating)
- Revoke your proof: `client.revokeOwnProof(proofId, wallet)`

Example:

```javascript
const privateData = await client.getPrivateStatus(proofId, window.ethereum);

const privateProofs = await client.getPrivateProofsByWallet(
  'YOUR_WALLET_OR_DID',
  { limit: 50, offset: 0 },
  window.ethereum
);

await client.revokeOwnProof(proofId, window.ethereum);
```

Compatibility note: `qHash` remains supported as a deprecated alias (`proofId === qHash`).

## React widgets

For UI gating, see `./widgets/README.md`.

Widget imports:

```javascript
import { VerifyGate, ProofBadge } from '@neus/sdk/widgets';
```

## Reference docs

- API Reference: `../docs/api/README.md`
- OpenAPI (JSON): `../docs/api/public-api.json`