Configurazione

Configura il client listingsapi-js: risoluzione della chiave API, URL di base personalizzato, timeout e tentativi automatici.

Opzioni del costruttore

ListingsAPI accetta un unico oggetto di opzioni, interamente facoltativo:

import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI(); // reads LISTINGSAPI_KEY from env // Every default spelled out:const custom = new ListingsAPI({apiKey: process.env.LISTINGSAPI_KEY,baseUrl: 'https://listingsapi.com',timeout: 240000,   // 4 minutes per attemptmaxRetries: 2,     // up to 3 attempts total});

Individuazione della chiave API

Non inserire mai la chiave direttamente nel codice sorgente. Il costruttore senza argomenti legge LISTINGSAPI_KEY dall'ambiente:

export LISTINGSAPI_KEY="your-api-key"

const client = new ListingsAPI();

Oppure passa una chiave recuperata da un gestore di segreti:

import { getSecret } from './secrets.js'; const apiKey = await getSecret('LISTINGSAPI_KEY');const client = new ListingsAPI({ apiKey });

Se la chiave non viene trovata in nessuna delle due fonti, il costruttore genera immediatamente AuthenticationError, prima che venga effettuata qualsiasi richiesta.

Sostituzione dell'URL di base

Configura il client per usare un proxy interno o un ambiente di staging:

const client = new ListingsAPI({baseUrl: 'https://listings-proxy.internal.example.com',});

Le barre finali vengono rimosse automaticamente, quindi 'https://listingsapi.com/' e 'https://listingsapi.com' si comportano allo stesso modo.

Timeout

Ogni tentativo viene gestito internamente tramite AbortSignal.timeout(timeout) (Node 18+), quindi non devi aggiungere un tuo AbortController alle chiamate SDK. Il valore predefinito è 240000 ms (4 minuti) per tentativo.

Un tentativo che supera il timeout viene considerato un errore di connessione: il client lo ripete finché rimangono tentativi disponibili e, se anche l'ultimo tentativo fallisce, genera APIConnectionError. Riduci il timeout per i percorsi di esecuzione sensibili alla latenza:

const client = new ListingsAPI({ timeout: 15000 }); // 15 s per attempt

Nuovi tentativi automatici

Il client ripete le richieste che ricevono risposte con stato 429, 500, 502, 503 e 504, oltre a quelle che incontrano errori di rete (errori DNS, connessioni rifiutate, timeout), solo per i metodi sicuri: GET, HEAD e OPTIONS. A partire da 0.3.2, una scrittura (POST, DELETE) viene inviata esattamente una volta e il suo eventuale errore viene segnalato immediatamente. Con l'impostazione predefinita maxRetries: 2, ogni lettura prevede fino a 3 tentativi.

L'API v4 non supporta Idempotency-Key e non rileva le scritture ripetute, quindi una scrittura che supera il timeout o restituisce 5xx potrebbe essere già stata applicata. Ripeterla senza verificare creerebbe una seconda sede, un secondo post o una seconda risposta a una recensione. Prima di ripetere una scrittura, rileggi il record usando una chiave che controlli.

L'attesa prima di ogni nuovo tentativo:

1. Se la risposta include un'intestazione Retry-After con un numero positivo di secondi, il client attende esattamente quel tempo.
2. Altrimenti, l'attesa aumenta in modo esponenziale: 500 ms prima del primo nuovo tentativo, poi raddoppia a ogni tentativo successivo (1 s, 2 s e così via).

In caso di errori di rete, i tentativi vengono ripetuti immediatamente, senza attesa. Una volta esauriti i tentativi, l'ultima risposta viene convertita in un errore tipizzato (RateLimitError, InternalServerError e altri; vedi Gestione degli errori), mentre un errore di rete che persiste dopo l'esaurimento dei tentativi genera APIConnectionError.

// Fail fast and own the retry policy yourself:const client = new ListingsAPI({ maxRetries: 0 });

ID delle sedi

Ovunque l'SDK accetti un ID di sede, gli ID numerici vengono codificati automaticamente nel formato base64 dell'API (Location:<id>), mentre gli ID già codificati vengono passati senza modifiche. La funzione di utilità viene esportata se ti serve ottenere direttamente la forma codificata:

import { encodeLocationId } from 'listingsapi-js'; encodeLocationId(16808);                  // 'TG9jYXRpb246MTY4MDg='encodeLocationId('TG9jYXRpb246MTY4MDg='); // returned as-is

Formato delle intestazioni

Ogni richiesta viene autenticata con:

Authorization: API <your-key>Content-Type: application/json

L'SDK imposta automaticamente queste intestazioni a ogni chiamata. Non devi configurarle.

Configurazione del progetto TypeScript

L'SDK è progettato per TypeScript e include le definizioni dei tipi, quindi non è necessario installare un pacchetto @types separato. Fissa la versione per ottenere build riproducibili:

npm install listingsapi-js@0.3.2

Un tsconfig.json minimo per un progetto Node 18+:

{"compilerOptions": {  "target": "ES2022",  "module": "Node16",  "moduleResolution": "Node16",  "strict": true,  "outDir": "dist"}}

Per i progetti ESM con "type": "module" in package.json, usa "module": "Node16" e "moduleResolution": "Node16". Per i progetti CJS, "module": "CommonJS" e "moduleResolution": "Node" funzionano correttamente; il pacchetto include entrambe le build e il codice CommonJS lo carica con const { ListingsAPI } = require('listingsapi-js').

Utilizzo senza TypeScript

listingsapi-js viene compilato in JavaScript puro senza dipendenze a runtime. Puoi importarlo da un file .js o .mjs senza un passaggio di build:

import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI();const page = await client.fetchAllLocations({ first: 5 });for (const location of page.locations) {console.log(location.name, location.city); // Acme Dental Midtown}

Passaggi successivi

• Guida rapida, il tuo primo script funzionante
• Casi d'uso, esempi completi
• Gestione degli errori, la gerarchia degli errori e le strategie per i nuovi tentativi