# Dokicasa Market Scanner SDK: istruzioni per assistenti AI

Da consegnare a un assistente AI per integrare il Market Scanner di Dokicasa in un'app
JavaScript/TypeScript con l'SDK ufficiale. Guida completa:
https://docs.dokicasa.it/market-scanner-sdk

Se manca un dato (token, ambiente, tipo di ricerca), chiedilo all'utente. Non inventarlo.

## Installazione

```bash
npm install @dokicasa/sdk
npm install pusher-js   # facoltativo, per il tempo reale
```

## Regole

- Client: `createClient({ token, environment: 'sandbox' | 'production', realtime: { Pusher } })`.
  Si sviluppa in `sandbox` (dati finti, nessun costo); in `production` ogni ricerca costa.
- Il token API e' segreto: solo lato server, oppure nel browser il token del singolo utente,
  mai quello del partner. Non scriverlo nel codice: leggerlo da variabile d'ambiente.
- Lanciare e attendere: `dk.scanner.run(tipo, parametri, { onProgress })`. Separati:
  `create` poi `wait(id)`. L'SDK non rilancia mai da solo una ricerca (costa): non
  aggiungere ritentativi sulle ricerche.
- I tipi di ricerca e i loro parametri sono in https://docs.dokicasa.it/market-scanner#tipi
  (es. `visura-catasto` vuole comune, provincia, foglio, particella, tipo_visura).
- Ricerche in piu' passi: se `result.needs_selection`, rilanciare con `selected_value`.
- Documenti: `dk.scanner.downloadDocument(richiesta)` -> `{ data, filename, contentType }`.
- Errori: usare le classi (`InsufficientFundsError` con `checkoutLink`, `ValidationError`
  con `fields` e `isDuplicate`, `ServiceUnavailableError`, `RateLimitError`,
  `CensusInProgressError`, `ScanFailedError`, `TimeoutError`, `AbortError`). Un
  `ValidationError` con `isDuplicate` vuol dire ricerca identica appena fatta: non e' un
  errore da mostrare come tale.
- Annullare l'attesa (`signal`) non ferma la ricerca: si riprende con `wait(id)`.
- Webhook: `parseWebhook({ body: corpoGrezzo, signature: header Signature, secret: token })`
  sul corpo grezzo, prima di JSON.parse.
- Partner SSO: `dk.as({ email })` o `dk.as('<slug>:<id esterno>')` per chiamare per conto di
  un utente collegato (header X-Dokicasa-User, da far abilitare a Dokicasa).
- React: `import { DokicasaProvider, useScanner } from '@dokicasa/sdk/react'`; Vue: `import
  { DokicasaPlugin, useScanner } from '@dokicasa/sdk/vue'` con `app.use(DokicasaPlugin, { client })`.
  `useScanner()` da' `phase`, `isRunning`, `percentage`, `progress`, `requestId`, `result`, `error`
  e `run`, `resume`, `cancel`, `reset` (in Vue sono ComputedRef). Non riscrivere a mano la logica
  di attesa nei componenti: usa l'hook. Un `useScanner()` per ogni ricerca contemporanea.
- Nel browser: token del singolo utente; il dominio dell'app va abilitato da Dokicasa (CORS).
- A fine uso `dk.close()` chiude il socket.
