node/README.md

# hightrusted CAPTURE — Node.js SDK

> **Status:** v0.1 Preview — API stabil, SDK in aktiver Entwicklung

Offizielles Node.js-SDK für die [hightrusted CAPTURE API](https://capture.hightrusted.net) —
forensische Web-Captures mit qualifiziertem Zeitstempel nach RFC 3161 / eIDAS Art. 41.

**Made in Germany.** Server in Deutschland. DSGVO-nativ. Quelloffen unter MIT.

## Installation

```bash
npm install @hightrusted/capture
```

## Quickstart

```javascript
import { Client } from '@hightrusted/capture';

const client = new Client({ apiKey: 'ht_live_...' });

// Synchron — wartet bis zu 30 s auf das fertige PDF
const capture = await client.capture({ url: 'https://example.com' });

console.log(capture.id);
console.log(capture.verify_url);
console.log(capture.timestamp.issued_at);

// PDF herunterladen
await client.downloadPdf(capture.id, './beweis.pdf');
```

## Drei Aufruf-Modi

### Synchron (Default)
```javascript
const capture = await client.capture({ url: 'https://example.com' });
```

### Asynchron mit Polling
```javascript
const capture = await client.captureAsync({
  url: 'https://example.com',
  reference: 'case-001',
  waitForReady: true,   // Default — pollt bis ready
  maxWaitMs: 60_000,
});
```

### Webhook
```javascript
const job = await client.captureWebhook({
  url: 'https://example.com',
  webhookUrl: 'https://your-app.tld/webhooks/capture',
  reference: 'case-001',
});
// Server liefert das fertige Capture per HTTP-POST aus
```

## Verifikation (kostenlos, ohne Quota)

```javascript
// Per Capture-ID
const result = await client.verify({ source: 'cap_...' });

// Per Verify-URL
const result = await client.verify({ source: 'https://verify.hightrusted.net/c/...' });

// Per PDF-Upload (Buffer oder Blob)
const pdf = await readFile('./beweis.pdf');
const result = await client.verify({ pdf });

console.log(result.valid);                     // true
console.log(result.audit_log.chain_valid);     // true
```

## Webhook-Signatur prüfen

```javascript
import express from 'express';
import { verifyWebhookSignature } from '@hightrusted/capture';

const app = express();

app.post(
  '/webhooks/capture',
  express.raw({ type: 'application/json' }),  // RAW body — wichtig!
  (req, res) => {
    const sig = req.header('X-Hightrusted-Signature');
    if (!verifyWebhookSignature(req.body, sig, 'wh_secret_...')) {
      return res.status(401).json({ error: 'invalid_signature' });
    }
    const payload = JSON.parse(req.body);
    // ...
    res.status(200).json({ ok: true });
  }
);
```

## Fehler-Behandlung

```javascript
import {
  Client,
  InvalidApiKeyError,
  QuotaExceededError,
  RateLimitedError,
  UnreachableUrlError,
} from '@hightrusted/capture';

try {
  const capture = await client.capture({ url: 'https://example.com' });
} catch (err) {
  if (err instanceof InvalidApiKeyError) console.error('API-Key ungültig');
  else if (err instanceof QuotaExceededError) console.error('Quota erschöpft');
  else if (err instanceof RateLimitedError)
    console.error(`Rate-limited, retry in ${err.retryAfterSeconds}s`);
  else throw err;
}
```

## API-Key

Bearer-Token, Erzeugung unter
https://capture.hightrusted.net/dashboard/api-keys

```javascript
const client = new Client({ apiKey: 'ht_live_...' });
// alternativ via Umgebungsvariable HIGHTRUSTED_API_KEY
const client = new Client();
```

## Voraussetzungen

- Node.js 18 oder höher (`fetch`, `AbortSignal.timeout`, `FormData` werden vorausgesetzt)
- ESM only — `import`-Syntax. Wenn du CommonJS brauchst, dynamic import nutzen:
  ```javascript
  const { Client } = await import('@hightrusted/capture');
  ```

## Entwicklung

```bash
git clone ssh://git@git.hightrusted.net:2222/hightrusted-capture/node.git
cd node
npm install
npm test       # 13 Tests mit Node native test runner
```

## Roadmap

- [x] v0.1 — Basis-Client (sync + async + webhook), Verify, Download, typisierte Errors
- [ ] v0.2 — TypeScript-Defs, retry-after-Helper
- [ ] v0.3 — Stream-API für große PDFs
- [ ] v1.0 — Stabile API, semantische Versionierung

## Verwandte Repositorys

**Im selben Produkt** ([`hightrusted-capture`](https://git.hightrusted.net/hightrusted-capture)):

- [`openapi`](https://git.hightrusted.net/hightrusted-capture/openapi) — OpenAPI 3.1 Spec
- [`postman`](https://git.hightrusted.net/hightrusted-capture/postman) — Postman Collection
- [`examples`](https://git.hightrusted.net/hightrusted-capture/examples) — Beispiel-Anwendungen
- [`python`](https://git.hightrusted.net/hightrusted-capture/python) — Python-SDK
- [`php`](https://git.hightrusted.net/hightrusted-capture/php) — PHP-SDK

**Plattform-übergreifend** ([`hightrusted`](https://git.hightrusted.net/hightrusted)):

- [`platform`](https://git.hightrusted.net/hightrusted/platform)
- [`developer-portal`](https://git.hightrusted.net/hightrusted/developer-portal)
- [`compliance`](https://git.hightrusted.net/hightrusted/compliance)

## Support

- **Doku:** https://capture.hightrusted.net/api/docs
- **Status:** https://status.hightrusted.net
- **Developer Support:** developers@hightrusted.net
- **Sicherheit:** siehe [SECURITY.md](./SECURITY.md)

## Lizenz

MIT — siehe [LICENSE](./LICENSE).

---

**hightrusted GmbH** — *The European Trust Infrastructure.*
Made in Germany. DSGVO-nativ. eIDAS-konform.