Configuration

Configurez le client listingsapi-js : résolution de la clé API, remplacement de l’URL de base, délais d’attente et nouvelles tentatives automatiques.

Options du constructeur

ListingsAPI accepte un seul objet d'options, entièrement facultatif :

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});

Résolution de la clé API

N'inscrivez jamais la clé en dur dans le code source. Le constructeur sans argument lit LISTINGSAPI_KEY dans l'environnement :

export LISTINGSAPI_KEY="your-api-key"

const client = new ListingsAPI();

Vous pouvez aussi transmettre une clé récupérée auprès d'un gestionnaire de secrets :

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

Si aucune clé n'est trouvée à l'un ou l'autre de ces emplacements, le constructeur lève immédiatement AuthenticationError, avant l'envoi de toute requête.

Remplacement de l'URL de base

Configurez le client pour qu'il utilise un proxy interne ou un environnement de préproduction :

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

Les barres obliques finales sont supprimées automatiquement : 'https://listingsapi.com/' et 'https://listingsapi.com' produisent donc le même comportement.

Délais d'expiration

Chaque tentative est gérée en interne par AbortSignal.timeout(timeout) (Node 18+), vous n'avez donc pas besoin d'ajouter votre propre AbortController autour des appels au SDK. Le délai par défaut est de 240000 ms (4 minutes) par tentative.

Une tentative dont le délai expire est considérée comme un échec de connexion : le client la renouvelle tant qu'il reste des tentatives, et l'échec final lève APIConnectionError. Réduisez le délai d'expiration pour les traitements sensibles à la latence :

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

Nouvelles tentatives automatiques

Le client renouvelle les requêtes ayant reçu une réponse avec le statut 429, 500, 502, 503 ou 504, ainsi que celles ayant subi une défaillance réseau (erreurs DNS, connexions refusées, délais d'expiration dépassés), uniquement pour les méthodes sûres : GET, HEAD et OPTIONS. À partir de 0.3.2, une écriture (POST, DELETE) est envoyée exactement une fois et son échec est signalé immédiatement. Avec la valeur par défaut maxRetries: 2, chaque lecture fait l'objet de 3 tentatives au maximum.

L'API v4 ne prend pas en charge Idempotency-Key et ne détecte pas les écritures répétées ; une écriture dont le délai expire ou qui renvoie 5xx peut donc avoir déjà été enregistrée. La retenter sans vérification créerait un deuxième établissement, une deuxième publication ou une deuxième réponse à un avis. Relisez l'enregistrement à l'aide d'une clé que vous maîtrisez avant de répéter une écriture.

Délai avant chaque nouvelle tentative :

1. Si la réponse contient un en-tête Retry-After indiquant un nombre positif de secondes, le client attend exactement cette durée.
2. Sinon, le délai d'attente augmente de façon exponentielle : 500 ms avant la première nouvelle tentative, puis le double à chaque nouvelle tentative suivante (1 s, 2 s, etc.).

Les requêtes ayant subi une défaillance réseau sont retentées immédiatement, sans délai d'attente. Une fois les tentatives épuisées, la dernière réponse devient une erreur typée (RateLimitError, InternalServerError et autres ; voir Gestion des erreurs), et une défaillance réseau persistante lève APIConnectionError.

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

Identifiants d'établissement

Partout où le SDK accepte un identifiant d'établissement, les identifiants numériques sont automatiquement encodés au format base64 de l'API (Location:<id>), et les identifiants déjà encodés sont transmis tels quels. La fonction utilitaire est exportée si vous avez vous-même besoin de la forme encodée :

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

Format des en-têtes

Chaque requête est authentifiée avec :

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

Le SDK définit automatiquement ces en-têtes à chaque appel. Vous n'avez pas besoin de les configurer.

Configuration d'un projet TypeScript

Le SDK est conçu en priorité pour TypeScript et inclut les types ; aucun paquet @types distinct n'est donc à installer. Fixez la version pour obtenir des compilations reproductibles :

npm install listingsapi-js@0.3.2

Un tsconfig.json minimal pour un projet Node 18+ :

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

Pour les projets ESM avec "type": "module" dans package.json, utilisez "module": "Node16" et "moduleResolution": "Node16". Pour les projets CJS, "module": "CommonJS" et "moduleResolution": "Node" conviennent ; le paquet inclut les deux versions compilées, et le code CommonJS le charge avec const { ListingsAPI } = require('listingsapi-js').

Utilisation sans TypeScript

listingsapi-js se compile en JavaScript standard sans aucune dépendance à l'exécution. Vous pouvez l'importer depuis un fichier .js ou .mjs sans étape de compilation :

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}

Étapes suivantes

• Démarrage rapide, votre premier script fonctionnel
• Cas d'utilisation, des exemples complets
• Gestion des erreurs, la hiérarchie des erreurs et les stratégies de nouvelle tentative