@dokicasa/sdk 0.0.0-stage → 0.1.0

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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Dokidoc S.r.l. (DokiCasa)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,385 @@
1
- # Temporary Holding Version
1
+ ![DokiCasa SDK JavaScript](https://docs.dokicasa.it/sdk/market-scanner/banner.png)
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ ![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white)
4
+ ![Node](https://img.shields.io/badge/Node-%E2%89%A518-339933?logo=node.js&logoColor=white)
5
+ ![ESM + CJS](https://img.shields.io/badge/build-ESM%20%2B%20CJS-00C9B7)
6
+ ![Test](https://img.shields.io/badge/test-49%20%2B%2011%20e2e-00C9B7)
7
+ ![Realtime](https://img.shields.io/badge/realtime-Laravel%20Reverb-FF2D20)
8
+
9
+ L'SDK ufficiale per integrare il **Market Scanner di DokiCasa** in un'applicazione JavaScript o TypeScript, nel browser o in Node.
10
+ Le stesse cose che fa la nostra webapp, con un'API pulita:
11
+
12
+ - **ricerche catastali e documenti** (visure, ispezioni ipotecarie, note, mappe, elaborati planimetrici, intestatari, ricerche per codice fiscale), con un solo `await`;
13
+ - **avanzamento in tempo reale** via WebSocket, con il **polling automatico** come riserva se il socket cade o perde un evento;
14
+ - **censimenti di zona**, **monitoraggi**, **wallet e crediti**, **catalogo prezzi** e **stato del servizio**;
15
+ - **errori tipizzati** (credito insufficiente, censimento in corso, Sister fermo, limiti...), **ritentativi intelligenti**, **timeout** e **annullamento**;
16
+ - **verifica della firma dei webhook**;
17
+ - **tutto configurabile**: ambiente, URL, socket, timeout, ritentativi, polling, header, `fetch`, logger, hook.
18
+
19
+ Documentazione completa: **[docs.dokicasa.it/market-scanner-sdk](https://docs.dokicasa.it/market-scanner-sdk)**.
20
+
21
+ [TOC]
22
+
23
+ ## Installazione
24
+
25
+ ```bash
26
+ npm install @dokicasa/sdk
27
+ # solo se vuoi gli aggiornamenti in tempo reale:
28
+ npm install pusher-js
29
+ ```
30
+
31
+ Funziona con Node 18+ e con i browser moderni. Non ha dipendenze obbligatorie: `pusher-js` serve solo per il tempo reale.
32
+
33
+ ## Avvio rapido
34
+
35
+ ```ts
36
+ import { createClient } from '@dokicasa/sdk';
37
+
38
+ const dk = createClient({
39
+ token: process.env.DOKICASA_TOKEN, // il tuo token API
40
+ environment: 'sandbox', // 'production' quando sei pronto
41
+ });
42
+
43
+ // Visura catastale: lancia la ricerca, aspetta il risultato, scarica il PDF
44
+ const visura = await dk.scanner.run(
45
+ 'visura-catasto',
46
+ { comune: 'Roma', provincia: 'RM', foglio: '123', particella: '45', tipo_visura: 'ANALITICA' },
47
+ { onProgress: (p) => console.log(`${p.status} ${p.percentage}%`) },
48
+ );
49
+
50
+ const pdf = await dk.scanner.downloadDocument(visura);
51
+ // pdf.data (ArrayBuffer), pdf.filename, pdf.contentType
52
+ ```
53
+
54
+ `run` lancia la ricerca e aspetta che finisca. Se ti basta lanciarla, usa `create`; per aspettarla dopo, usa `wait`.
55
+
56
+ ## Configurazione
57
+
58
+ Ogni opzione ha un valore predefinito sensato: di solito basta il token.
59
+
60
+ ```ts
61
+ const dk = createClient({
62
+ token: 'xxx', // oppure getToken: async () => leggiIlToken()
63
+ environment: 'production', // 'production' | 'sandbox'
64
+ baseUrl: 'https://api.dokicasa.it', // sovrascrive l'URL dell'ambiente
65
+ timeoutMs: 60_000, // timeout di ogni chiamata HTTP
66
+ retry: {
67
+ maxRetries: 3, // ritentativi su errori temporanei
68
+ baseDelayMs: 500, // attesa iniziale, poi raddoppia (con jitter)
69
+ maxDelayMs: 10_000,
70
+ methods: ['GET', 'HEAD'], // le ricerche (POST) costano: mai ritentate da sole
71
+ statuses: [408, 425, 429, 500, 502, 503, 504],
72
+ },
73
+ polling: {
74
+ intervalMs: 2_000, // primo controllo dello stato
75
+ maxIntervalMs: 15_000, // il polling rallenta da solo nelle attese lunghe
76
+ backoffFactor: 1.5,
77
+ },
78
+ realtime: {
79
+ // valori predefiniti presi dall'ambiente; tutti sovrascrivibili
80
+ key: '...', wsHost: 'socket.dokicasa.it', wsPort: 443, forceTLS: true,
81
+ authEndpoint: 'https://api.dokicasa.it/broadcasting/auth',
82
+ Pusher, // facoltativo: il costruttore di pusher-js
83
+ pusherOptions: {}, // opzioni extra per pusher-js
84
+ }, // oppure realtime: false = solo polling
85
+ headers: { 'X-Correlation-Id': 'abc' },
86
+ fetch: customFetch, // per Node < 18, proxy, test
87
+ logger: console, // debug / info / warn / error
88
+ onRequest: (req) => {}, // hook prima di ogni chiamata
89
+ onResponse: (res) => {}, // hook dopo ogni risposta (con durata)
90
+ });
91
+ ```
92
+
93
+ | Opzione | Default | A cosa serve |
94
+ |---|---|---|
95
+ | `token` / `getToken` | obbligatorio | Autenticazione `Bearer`. `getToken` viene chiamato a ogni richiesta: comodo se il token si rinnova. |
96
+ | `environment` | `production` | Sceglie URL dell'API e del socket. |
97
+ | `baseUrl` | dall'ambiente | Per ambienti personalizzati o un proxy. |
98
+ | `timeoutMs` | `60000` | Timeout della singola chiamata HTTP. |
99
+ | `retry` | 3 ritentativi sulle letture | `false` per spegnerli. |
100
+ | `polling` | 2 s, fino a 15 s | Intervalli del polling quando il socket non c'è. |
101
+ | `realtime` | attivo se c'è `pusher-js` | `false` per usare solo il polling. |
102
+ | `headers` | — | Header aggiunti a ogni chiamata. |
103
+ | `actingUser` / `actingUserHeader` | — | Partner SSO: chiamate per conto di un utente ([vedi sotto](#partner-sso)). |
104
+ | `fetch` | `globalThis.fetch` | Implementazione di `fetch`. |
105
+ | `logger` | silenzioso | Log di ritentativi, socket e polling. |
106
+ | `onRequest` / `onResponse` | — | Hook per log, metriche e tracciamento. |
107
+
108
+ ### Ambienti
109
+
110
+ | Ambiente | API | Socket |
111
+ |---|---|---|
112
+ | `sandbox` | `https://api-dev.dokicasa.it` | `api-dev.dokicasa.it` |
113
+ | `production` | `https://api.dokicasa.it` | `socket.dokicasa.it` |
114
+
115
+ > Non mischiare gli ambienti: con l'API di sandbox e il socket di produzione il canale si iscrive ma non riceve eventi. Scegliendo `environment` l'SDK li tiene allineati da solo.
116
+
117
+ ## Ricerche
118
+
119
+ ### Tipi di ricerca
120
+
121
+ `dk.scanner.run(tipo, parametri, opzioni)` e `dk.scanner.create(tipo, parametri, opzioni)`. I parametri sono tipizzati per ogni tipo.
122
+
123
+ | Tipo | Cosa fa | Parametri principali |
124
+ |---|---|---|
125
+ | `catasto` | Immobili di una particella | `comune`, `foglio`, `particella`, `search_catasto_type` |
126
+ | `intestatari-catasto` | Intestatari di un immobile | `+ provincia`, `subalterno?` |
127
+ | `tax-data` | Immobili di un codice fiscale o partita IVA | `tax_code`, `provincia?` |
128
+ | `visura-catasto` | Visura per immobile (PDF) | `+ provincia`, `tipo_visura` |
129
+ | `visura-tax-data` | Visura per soggetto (PDF) | `tax_code`, `provincia`, `tipo_visura` |
130
+ | `ispezione-catasto` / `ispezione-tax-data` | Ispezione ipotecaria (PDF) | dati catastali / `tax_code` |
131
+ | `nota-catasto` / `nota-tax-data` | Nota di trascrizione (PDF) | `+ numero_registro_particolare`, `anno_registro`, `tipo_nota` |
132
+ | `mappa-catasto` | Estratto di mappa (PDF) | `tipo_richiesta`, `tipo_foglio`, `formato` |
133
+ | `elaborato-planimetrico` | Elaborato planimetrico (PDF) | dati catastali, poi `elaborato_planimetrico` |
134
+ | `elenco-immobili` | Elenco immobili della particella (PDF) | dati catastali |
135
+ | `search-fiscal-code` | Codice fiscale da nome e cognome | `first_name`, `last_name`, `provincia?` |
136
+ | `search-company` | Società da ragione sociale | `company_name` |
137
+ | `list-addresses` | Immobili da indirizzo | `indirizzo`, `comune`, `provincia` |
138
+
139
+ Lo schema completo di ogni tipo è nella [documentazione delle API](https://api.dokicasa.it/api/documentation#/Scanner).
140
+
141
+ ### Ricerche in più passi
142
+
143
+ Alcune ricerche (visure e ispezioni con più immobili, mappe con più sezioni, omonimi) chiedono una scelta. Si rilancia con il valore scelto:
144
+
145
+ ```ts
146
+ const primo = await dk.scanner.run('visura-catasto', { ...dati, enable_multi_step: true });
147
+
148
+ if (primo.result?.needs_selection) {
149
+ const scelta = primo.result.rows_immobili![0]!.value;
150
+ const visura = await dk.scanner.run('visura-catasto', { ...dati, selected_value: scelta });
151
+ }
152
+ ```
153
+
154
+ ### Risultati, documenti, export
155
+
156
+ ```ts
157
+ const req = await dk.scanner.get(id); // richiesta completa con result
158
+ const stato = await dk.scanner.status(id); // { status, percentage, children? }
159
+
160
+ // tutti i risultati, pagina dopo pagina
161
+ for await (const immobile of dk.scanner.iterateResults(id, { filters: { categoria: ['A/2'] } })) {
162
+ console.log(immobile);
163
+ }
164
+
165
+ const docs = await dk.scanner.documents(id); // documenti legati alla ricerca
166
+ const file = await dk.scanner.downloadDocument(req); // PDF di result.pdf_path
167
+ await dk.scanner.exportXls(id, { comune: ['Roma'] }); // Excel via email (a pagamento)
168
+ await dk.scanner.monitor(id, { models: [] }); // monitora tutto (a pagamento)
169
+ ```
170
+
171
+ ### Prima di lanciare: prezzi e stato del servizio
172
+
173
+ ```ts
174
+ const catalogo = await dk.system.services(); // prezzo e crediti per ogni tipo
175
+ const stato = await dk.system.health(); // Sister: ok, degraded o down, anche per tipo
176
+
177
+ // oppure lascia controllare all'SDK: se il servizio è fermo non lancia (e non spende)
178
+ await dk.scanner.create('visura-catasto', dati, { checkHealth: true });
179
+ ```
180
+
181
+ ## Tempo reale
182
+
183
+ Con `pusher-js` installato, `run` e `wait` seguono l'avanzamento sul canale privato della ricerca, senza polling. Il socket è *best effort*, e l'SDK lo tratta così:
184
+
185
+ - mentre il socket si collega o è attivo, fa solo un **controllo di sicurezza lento**, per recuperare un evento perso (succede, per esempio, durante un riavvio del server);
186
+ - se il socket **cade** o il canale viene **negato**, passa al **polling** con intervalli crescenti;
187
+ - appena iscritto, **rilegge lo stato**: l'evento finale potrebbe essere arrivato prima dell'iscrizione;
188
+ - a fine attesa **chiude il canale**. I canali sono condivisi: si chiudono quando smette di ascoltare l'ultimo.
189
+
190
+ ```ts
191
+ import Pusher from 'pusher-js';
192
+ const dk = createClient({ token, realtime: { Pusher } });
193
+
194
+ // solo ascolto, senza aspettare
195
+ const stop = dk.scanner.watch(id, (e) => console.log(e.status, e.percentage));
196
+ stop();
197
+
198
+ // eventi personali: notifiche, storia dell'immobile pronta, report AML
199
+ dk.realtime.user(userId, {
200
+ onToast: (t) => mostraNotifica(t.title, t.message),
201
+ onPropertyHistory: (e) => e.status === 'ready' && caricaStoria(e.resource_url),
202
+ });
203
+
204
+ dk.realtime.onStateChange((stato) => console.log('socket', stato));
205
+ dk.close(); // chiude il socket quando l'app si smonta
206
+ ```
207
+
208
+ ## Censimento di zona
209
+
210
+ Un censimento è una richiesta padre a cui si aggiungono le ricerche per indirizzo. Si può avere un solo censimento alla volta per utente.
211
+
212
+ ```ts
213
+ const { scanner_request_id: padre } = await dk.census.create();
214
+
215
+ const candidati = await dk.census.findAddresses({ indirizzo: 'Via Roma', comune: 'Torino', provincia: 'TO' });
216
+ const [valore] = Object.keys(candidati.result!.addresses!);
217
+ await dk.census.addAddress(padre, { indirizzo: 'Via Roma', comune: 'Torino', provincia: 'TO', address_value: valore!, numero_civico: '10' });
218
+
219
+ await dk.census.switchToOwners(padre); // facoltativo: anche gli intestatari
220
+ const censimento = await dk.census.wait(padre);
221
+ ```
222
+
223
+ `census.create({ searchMode: 'MULTI_ADDRESS' })` fa invece una ricerca singola su più vie, fino a 5.
224
+
225
+ ## Monitoraggi, wallet e crediti
226
+
227
+ ```ts
228
+ await dk.monitorings.fromCatasto({ comune: 'Milano', provincia: 'MI', foglio: '10', particella: '20', webhook_url: 'https://...' });
229
+ const lista = await dk.monitorings.list({ type: 'IMMOBILE', text: 'Rossi' });
230
+ await dk.monitorings.renew(id);
231
+
232
+ const { wallet } = await dk.account.wallet();
233
+ const crediti = await dk.account.credits();
234
+ const riepilogo = await dk.account.overview(); // crediti, wallet e abbonamenti in una chiamata
235
+ ```
236
+
237
+ ## Errori
238
+
239
+ Ogni errore estende `DokicasaError` e ha un `code`. Quelli dell'API hanno anche `status` e `body`. Per gestire un caso specifico basta `instanceof`:
240
+
241
+ | Classe | Quando | Dati utili |
242
+ |---|---|---|
243
+ | `InsufficientFundsError` | Crediti o saldo insufficienti (`AMOUNT_NOT_ENOUGH`) | `missingAmount`, `checkoutLink` |
244
+ | `CensusInProgressError` | C'è già un censimento in corso (`PENDING_CENSIMENTO`) | |
245
+ | `ServiceUnavailableError` | Sister fermo, in manutenzione o sovraccarico | |
246
+ | `ValidationError` | Dati non validi (422), codice fiscale non valido | `fields`, `isDuplicate` |
247
+ | `RateLimitError` | Troppe richieste (429) | `retryAfterSeconds` |
248
+ | `PartnerPricingRequiredError` | Partner senza listino per quel tipo | `scannerType` |
249
+ | `AuthenticationError` / `PermissionError` / `NotFoundError` | 401 / 403 / 404 | |
250
+ | `ScanFailedError` | La ricerca è finita in `ERROR` o `CANCELLED` | `request` |
251
+ | `TimeoutError` / `AbortError` / `NetworkError` | Tempo scaduto, annullata, rete giù | |
252
+
253
+ ```ts
254
+ import { InsufficientFundsError, ServiceUnavailableError, ValidationError, ScanFailedError } from '@dokicasa/sdk';
255
+
256
+ try {
257
+ await dk.scanner.run('visura-catasto', dati);
258
+ } catch (e) {
259
+ if (e instanceof InsufficientFundsError) return apriCheckout(e.checkoutLink);
260
+ if (e instanceof ValidationError && e.isDuplicate) return avvisa('Ricerca già in corso');
261
+ if (e instanceof ServiceUnavailableError) return avvisa('Catasto momentaneamente non disponibile');
262
+ if (e instanceof ScanFailedError) return avvisa(`Ricerca non riuscita: ${e.request.details ?? ''}`);
263
+ throw e;
264
+ }
265
+ ```
266
+
267
+ ## Attese, timeout e annullamento
268
+
269
+ ```ts
270
+ const controller = new AbortController();
271
+
272
+ const risultato = await dk.scanner.run('ispezione-tax-data', { tax_code: 'RSSMRA80A01H501U' }, {
273
+ signal: controller.signal, // annulla chiamate e attesa
274
+ timeoutMs: 10 * 60_000, // attesa massima (default 15 minuti)
275
+ maxConsecutiveErrors: 5, // errori di rete tollerati durante l'attesa
276
+ throwOnFailure: false, // restituisce la richiesta anche se è finita in ERROR
277
+ realtime: false, // solo polling per questa attesa
278
+ });
279
+ ```
280
+
281
+ Le letture (`GET`) vengono ritentate da sole su rete giù, timeout, 429 e 5xx, con attesa esponenziale e rispettando `Retry-After`. **Le ricerche no**: costano crediti e un doppio lancio può far pagare due volte. Una ricerca identica entro pochi secondi viene comunque rifiutata dall'API come doppione (`ValidationError.isDuplicate`).
282
+
283
+ ## Partner SSO
284
+
285
+ I partner che fanno entrare i propri utenti con l'SSO possono chiamare **per conto di un utente** con l'header `X-Dokicasa-User` (formato `wikicasa:<id>` oppure `email:<email>`):
286
+
287
+ ```ts
288
+ const agente = dk.as({ source: 'wikicasa', id: 98765 }); // oppure dk.as({ email: 'mario@agenzia.it' })
289
+ await agente.account.wallet();
290
+ await agente.scanner.run('catasto', dati);
291
+ ```
292
+
293
+ `as()` restituisce una copia del client: l'originale resta com'era, e anche l'autorizzazione dei canali in tempo reale passa l'header. Il nome dell'header si cambia con `actingUserHeader`.
294
+
295
+ > L'header va abilitato sull'account del partner da DokiCasa: chiedilo al tuo referente.
296
+
297
+ ## Webhook
298
+
299
+ Per ricevere l'esito senza restare in attesa, passa `webhook` (o `callback`) alla ricerca. DokiCasa firma il corpo con HMAC-SHA256 e la chiave è il tuo token API. Verifica la firma **sul corpo grezzo**, prima di fare `JSON.parse`:
300
+
301
+ ```ts
302
+ import { parseWebhook } from '@dokicasa/sdk';
303
+
304
+ app.post('/webhook/dokicasa', express.raw({ type: '*/*' }), async (req, res) => {
305
+ try {
306
+ const evento = await parseWebhook({ body: req.body, signature: req.get('Signature'), secret: process.env.DOKICASA_TOKEN! });
307
+ // evento.scanner_request.status === 'SUCCESS' ...
308
+ res.sendStatus(200);
309
+ } catch {
310
+ res.sendStatus(401);
311
+ }
312
+ });
313
+ ```
314
+
315
+ ## Sicurezza
316
+
317
+ - Il token API vale come una password: **non metterlo nel codice e non pubblicarlo nel frontend**. Nel browser usa il token del singolo utente (per esempio dopo l'SSO), mai quello del partner.
318
+ - Per l'uso server-to-server il tuo account deve avere l'origine abilitata (`ORIGIN_NOT_ALLOWED` altrimenti): chiedilo al tuo referente.
319
+
320
+ ## Demo nel browser
321
+
322
+ Una pagina per provare l'SDK senza scrivere codice: avanzamento con l'origine di ogni aggiornamento (⚡ socket, ↻ polling), scelta nelle ricerche in più passi, download dei PDF, errori spiegati, annullamento e cronologia.
323
+
324
+ ```bash
325
+ npm install && npm run build
326
+ DOKICASA_TOKEN=<token di test> npm run demo # http://localhost:5174, sandbox
327
+ DOKICASA_ENV=production DOKICASA_TOKEN=... npm run demo
328
+ ```
329
+
330
+ Su `http://localhost:5174/esempi` ci sono gli stessi esempi di `examples/` da lanciare dal browser, con il codice e il registro in diretta.
331
+
332
+ Il server della demo non ha dipendenze. Inoltra `/api` e `/broadcasting/auth` all'API, perché dal browser in locale le chiamate dirette verrebbero bloccate dal CORS; il socket invece si collega direttamente a Reverb.
333
+
334
+ ## Esempi
335
+
336
+ Script pronti da lanciare in `examples/` (`DOKICASA_TOKEN=... node examples/01-visura-catastale.mjs`; default sandbox, `DOKICASA_ENV=production` per la produzione):
337
+
338
+ | Esempio | Cosa mostra |
339
+ |---|---|
340
+ | `01-visura-catastale` | Visura con avanzamento in tempo reale e PDF salvato su disco |
341
+ | `02-immobili-da-codice-fiscale` | Immobili di un soggetto e intestatari di un immobile |
342
+ | `03-ricerca-in-piu-passi` | Scelta tra più immobili e rilancio con `selected_value` |
343
+ | `04-censimento-di-zona` | Censimento: padre, indirizzi candidati, attesa, risultati |
344
+ | `05-monitoraggi` | Monitoraggio da catasto, nota, elenco, rimozione |
345
+ | `06-gestione-errori` | Ogni errore con la sua classe e il messaggio per l'utente |
346
+ | `07-eventi-in-tempo-reale` | Ascolto di una ricerca, eventi personali, stato del socket |
347
+ | `08-webhook-server` | Server che riceve i webhook e verifica la firma |
348
+ | `09-partner-sso` | Chiamate per conto di un utente (`as()`) |
349
+ | `10-risultati-ed-export` | Filtri, risultati filtrati, documenti, export e monitoraggio |
350
+ | `11-prezzi-e-stato-servizio` | Catalogo prezzi, stato di Sister, saldo, `checkHealth` |
351
+ | `12-annullamento-e-ripresa` | Annullare un'attesa e riprenderla |
352
+
353
+ ## Prove end-to-end
354
+
355
+ Oltre ai test con server finto, c'è una suite che gira contro la **sandbox vera** (`api-dev.dokicasa.it`): coda asincrona, socket Reverb, PDF, censimento, monitoraggi ed errori reali. Non consuma credito.
356
+
357
+ ```bash
358
+ DOKICASA_E2E_TOKEN=<token di test> npm run test:e2e
359
+ ```
360
+
361
+ ## Sviluppo
362
+
363
+ ```bash
364
+ npm install
365
+ npm test # 49 test con fetch e socket finti: nessuna chiamata vera
366
+ npm run test:e2e # 11 prove contro la sandbox vera (serve DOKICASA_E2E_TOKEN)
367
+ npm run demo # demo nel browser
368
+ npm run typecheck
369
+ npm run build # dist/ in ESM + CJS con i tipi
370
+ ```
371
+
372
+ ```
373
+ src/
374
+ ├── client.ts # DokicasaClient, createClient, as()
375
+ ├── config.ts # opzioni, ambienti, valori predefiniti
376
+ ├── http.ts # fetch, timeout, annullamento, ritentativi, hook
377
+ ├── errors.ts # errori tipizzati
378
+ ├── realtime/ # socket Reverb (pusher-js), canali condivisi
379
+ ├── resources/ # scanner, censimenti, monitoraggi, conto, sistema
380
+ ├── webhooks.ts # verifica della firma
381
+ └── types.ts # tipi di richieste e risultati
382
+ test/ # unit (fetch e socket finti) + e2e/ contro la sandbox
383
+ examples/ # uno script per ogni utilizzo
384
+ demo/ # pagina di prova + server senza dipendenze
385
+ ```