Configuração

Configure o cliente listingsapi-js: resolução da chave de API, substituição da URL base, tempos limite e novas tentativas automáticas.

Opções do construtor

ListingsAPI aceita um único objeto de opções, inteiramente opcional:

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

Resolução da chave de API

Nunca inclua a chave diretamente no código-fonte. O construtor sem argumentos lê LISTINGSAPI_KEY do ambiente:

export LISTINGSAPI_KEY="your-api-key"

const client = new ListingsAPI();

Ou passe uma chave que você obteve de um gerenciador de segredos:

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

Se nenhuma chave for encontrada em nenhum dos dois lugares, o construtor lança AuthenticationError imediatamente, antes que qualquer requisição seja feita.

Substituição da URL base

Configure o cliente para usar um proxy interno ou um ambiente de homologação:

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

As barras finais são removidas automaticamente, então 'https://listingsapi.com/' e 'https://listingsapi.com' se comportam da mesma forma.

Tempos limite

Cada tentativa é encapsulada internamente em AbortSignal.timeout(timeout) (Node 18+), então você não precisa usar seu próprio AbortController nas chamadas ao SDK. O padrão é 240000 ms (4 minutos) por tentativa.

Uma tentativa que excede o tempo limite conta como uma falha de conexão: o cliente tenta novamente enquanto houver tentativas disponíveis, e a falha final lança APIConnectionError. Reduza o tempo limite para fluxos sensíveis à latência:

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

Novas tentativas automáticas

O cliente repete as requisições que recebem respostas com status 429, 500, 502, 503 e 504, além daquelas que apresentam falhas de rede (erros de DNS, conexões recusadas, tempos limite excedidos), apenas para os métodos seguros: GET, HEAD e OPTIONS. A partir de 0.3.2, uma escrita (POST, DELETE) é enviada exatamente uma vez, e sua falha é informada imediatamente. Com o padrão maxRetries: 2, cada leitura faz até 3 tentativas.

A API v4 não oferece suporte a Idempotency-Key e não detecta escritas repetidas, então uma escrita que excede o tempo limite ou retorna 5xx pode já ter sido efetivada. Repeti-la sem verificar criaria um segundo local, uma segunda publicação ou uma segunda resposta a uma avaliação. Consulte o registro usando uma chave que você controla antes de repetir uma escrita.

O intervalo antes de cada nova tentativa:

1. Se a resposta contiver um cabeçalho Retry-After com um número positivo de segundos, o cliente aguardará exatamente esse tempo.
2. Caso contrário, o intervalo aumenta exponencialmente: 500 ms antes da primeira nova tentativa, dobrando a cada tentativa seguinte (1 s, 2 s e assim por diante).

As tentativas após falhas de rede são feitas imediatamente, sem intervalo. Quando as tentativas se esgotam, a última resposta se torna um erro tipado (RateLimitError, InternalServerError e outros; consulte Tratamento de erros), e uma falha de rede sem tentativas restantes lança APIConnectionError.

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

IDs de locais

Em qualquer ponto em que o SDK aceite um ID de local, os IDs numéricos são codificados automaticamente no formato base64 da API (Location:<id>), e os IDs já codificados são repassados sem alterações. A função auxiliar é exportada caso você precise obter a forma codificada:

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

Formato dos cabeçalhos

Cada requisição é autenticada com:

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

O SDK define esses cabeçalhos automaticamente em cada chamada. Você não precisa configurá-los.

Configuração de um projeto TypeScript

O SDK foi desenvolvido para TypeScript e inclui as definições de tipos, então não há um pacote @types separado para instalar. Fixe a versão para obter builds reproduzíveis:

npm install listingsapi-js@0.3.2

Um tsconfig.json mínimo para um projeto Node 18+:

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

Para projetos ESM com "type": "module" em package.json, use "module": "Node16" e "moduleResolution": "Node16". Para projetos CJS, "module": "CommonJS" e "moduleResolution": "Node" funcionam bem; o pacote inclui ambos os builds, e o código CommonJS o carrega com const { ListingsAPI } = require('listingsapi-js').

Uso sem TypeScript

listingsapi-js é compilado para JavaScript puro, sem dependências em tempo de execução. Você pode importá-lo de um arquivo .js ou .mjs sem uma etapa de compilação:

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}

Próximos passos

• Início rápido, seu primeiro script funcional
• Casos de uso, exemplos de implementação do início ao fim
• Tratamento de erros, a hierarquia de erros e os padrões de novas tentativas