# @aere/cloud

The official client for the [Aere Cloud API](https://aere.network/cloud.html) — one keyed
endpoint for RPC, post-quantum signature verification, chain data, notarization, webhooks and
gas sponsorship on Aere Network (chain 2800). Zero dependencies; runs in Node 18+ and modern
browsers.

## Install

```
npm install @aere/cloud
```

Get a key: the free trial is self-serve at [aere.network/cloud.html#subscribe](https://aere.network/cloud.html#subscribe).
A key looks like `ak2800.<your-0x-address>.<secret>`.

## Use

```js
import { AereCloud } from '@aere/cloud';

const aere = new AereCloud({ apiKey: process.env.AERE_KEY });

// chain data
const head = await aere.dataHead();
const anchors = await aere.anchors(5);            // post-quantum anchor certificates
const set = await aere.validators();              // live QBFT validator set

// JSON-RPC
const block = await aere.blockNumber();

// post-quantum verification, computed by the chain's own precompiles
const { valid } = await aere.pqVerify({
  scheme: 'ml-dsa-44', publicKey: '0x…', signature: '0x…', message: '0x…',
});

// notarize a document hash — Aere pays the gas
const receipt = await aere.notarize('0x' + sha256Hex);
const proof = await aere.proofOf('0x' + sha256Hex); // { notarized, firstSeenAt, … }

// 1.2.0 (2026-09-17): the proof with its post-quantum finality: first appearance from the contract log,
// the anchor that covers it, a verdict, and how to verify every claim without Aere Cloud
const full = await aere.proof('0x' + sha256Hex);    // { block, txHash, finality: 'post-quantum', pqAnchor: {…}, verify: {…} }

// quantum readiness of a domain's public TLS edge (free, no key); attest:true notarizes the report digest on chain
const scan = await aere.readiness('example.com');                    // { score, verdict, summary, findings, … }
const attested = await aere.readiness('example.com', { attest: true }); // + attestation: { reportHash, txHash, proof, … }
// the whole public perimeter of a domain (1.3.0): named hosts + common prefixes found through DNS, one report; keyed
const perimeter = await aere.readinessPerimeter('example.com', { hosts: ['api', 'mail'] });
// perimeter.summary: { measured, withoutPqKeyExchange: [...], soonestCertificateExpiry, worstScore, verdict, complete }
// while summary.complete is false, call again: finished scans are cached; { attest: true } notarizes a complete report
// the audit log of a day as a FILE (1.4.0): the exact bytes whose sha256 is the digest you notarize; format: 'cef' for a SIEM
const file = await aere.auditExport({ day: '2026-09-17' });            // file.verified === true: sha256(file.bytes) is the stated digest
const fin = await aere.pqFinality('latest', 'testnet', 'both'); // AIP-21: { finality, agreement, postQuantumConfirmedByBoth, besu: {…}, nethermind: {…} }

// pqVerify: pass interface:'external' to verify a standard FIPS 204/205 signature (the precompile implements the
// internal interface; the gateway builds M' = 0x00 || len(ctx) || ctx || message for you)
const v = await aere.pqVerify({ scheme: 'ml-dsa-44', interface: 'external', publicKey, signature, message });

// transfer history for an address (token from genesis, native from launch)
const tx = await aere.transfers('0xYourAddress', 50);

// a smart account with a POST-QUANTUM owner (Falcon-512), gas sponsored:
const acct = await aere.sponsorCreatePqAccount('0x09' + falconPkHex, 0);
// -> { txHash, account: '0x…', alreadyDeployed: false }
```

A Python mirror of this client lives in `sdk/python/` (`pip install aere-cloud`): same routes,
same semantics, snake_case names.

Every method throws `AereCloudError` on a non-2xx response, carrying `.status` and the server's
JSON `.body` so you can act on the exact error.

## Webhooks

Create a webhook and verify every delivery — never trust a webhook payload without checking its
signature:

```js
import { AereCloud, verifyWebhook } from '@aere/cloud';

const aere = new AereCloud({ apiKey: process.env.AERE_KEY });
const wh = await aere.createWebhook({ type: 'pq-anchors', url: 'https://you.example/hook' });
// store wh.secret now — it is shown once

// in your webhook handler (raw body, not re-serialized):
app.post('/hook', async (req, res) => {
  const ok = await verifyWebhook(req.rawBody, req.headers['x-aere-signature'], WEBHOOK_SECRET);
  if (!ok) return res.status(401).end();
  handle(JSON.parse(req.rawBody));
  res.status(200).end();
});
```

Webhook types: `pq-anchors` (every 32nd-block certificate), `address-activity` (transactions
touching a watched address, pass `watch`), `subscription-events` (your billing events).

## Reference

Full API reference and OpenAPI spec: [aere.network/cloud-docs.html](https://aere.network/cloud-docs.html)
· live status you compute in your own browser: [aere.network/cloud-status.html](https://aere.network/cloud-status.html)

MIT licensed.