TypeScript

Esta página reúne o que você precisa para usar o sparkcrm em produção: erros, retentativas, timeouts e logs.

Erros HTTP

Respostas 4xx e 5xx e falhas de rede lançam subclasses de SparkCRM.APIError:

Status	Classe
400	`BadRequestError`
401	`AuthenticationError`
403	`PermissionDeniedError`
404	`NotFoundError`
409	`ConflictError`
422	`UnprocessableEntityError`
429	`RateLimitError`
≥ 500	`InternalServerError`
Sem resposta HTTP	`APIConnectionError`
Timeout	`APIConnectionTimeoutError`

O corpo de erro da API fica em err.error e tem o formato { statusCode, code, message }. Use code na lógica do seu código e message para exibir ou registrar. Os códigos estão na Introdução à API e nas páginas de cada recurso.

import SparkCRM from "sparkcrm";

try {
  await client.campaigns.start(campaignId, {});
} catch (err) {
  if (err instanceof SparkCRM.RateLimitError) {
    // espere e tente de novo, ou reduza o ritmo de chamadas
  } else if (err instanceof SparkCRM.APIError) {
    const body = err.error as { code?: string; message?: string } | undefined;
    console.error(err.status, body?.code, body?.message);
  } else {
    throw err;
  }
}

Retentativas

Por padrão, o cliente repete a requisição até 2 vezes, com espera crescente entre as tentativas, quando recebe:

erro de conexão;
408, 409 ou 429;
5xx.

Para mudar o padrão de todas as chamadas:

const client = new SparkCRM({
  maxRetries: 0,
});

Ou só de uma chamada:

await client.entrypoints.list({}, { maxRetries: 5 });

Retentativas automáticas podem repetir operações que não são idempotentes. Antes de repetir campaigns.start depois de um timeout, consulte a campanha com campaigns.retrieve para ver se a execução já começou.

Timeouts

O padrão é 60 segundos por tentativa. Com retentativas, o tempo total pode ser maior.

const client = new SparkCRM({
  timeout: 20_000,
});

await client.messaging.chats.sendMessage(chatId, { text: "ok" }, {
  timeout: 5_000,
});

Resposta HTTP bruta

Os métodos retornam APIPromise<T>. Para ler status e cabeçalhos sem ler o corpo:

const response = await client.entrypoints.list().asResponse();
console.log(response.status, response.headers.get("content-type"));

Para receber os dados e a Response juntos:

const { data, response } = await client.entrypoints.list().withResponse();

Logs

Defina o nível com a variável SPARK_CRM_LOG ou com a opção logLevel: debug, info, warn, error ou off. O padrão é warn. No nível debug, requisições e respostas aparecem no log, inclusive dados de contatos. Evite esse nível em produção. Para usar seu próprio logger, como Pino ou Winston:

import SparkCRM from "sparkcrm";
import pino from "pino";

const client = new SparkCRM({
  logger: pino().child({ name: "spark" }),
  logLevel: "info",
});

Fetch e proxy

Passe uma implementação própria em fetch ou opções extras em fetchOptions, como um dispatcher do Undici para usar proxy no Node. Há exemplos por runtime no README do repositório.

Parâmetros fora dos tipos

O SDK não valida os campos em tempo de execução. Para enviar um parâmetro que a API já aceita, mas que ainda não está nos tipos da sua versão:

await client.entrypoints.list({
  // @ts-expect-error parâmetro novo na API
  novoParametro: true,
});

Para chamar uma rota que ainda não tem método no SDK, use client.get, client.post, client.put, client.patch ou client.delete:

await client.post("/v1/rota-nova", {
  body: { campo: "valor" },
});

Versões

O pacote segue versionamento semântico. Mudanças só de tipos podem sair em versões minor, sem quebrar o código em execução. Acompanhe as versões no npm e abra issues no GitHub.

Visão geral

TypeScript — erros e uso avançado

Erros HTTP

Retentativas

Timeouts

Resposta HTTP bruta

Logs

Fetch e proxy

Parâmetros fora dos tipos

Versões

Leitura relacionada

​Erros HTTP

​Retentativas

​Timeouts

​Resposta HTTP bruta

​Logs

​Fetch e proxy

​Parâmetros fora dos tipos

​Versões

​Leitura relacionada

Erros HTTP

Retentativas

Timeouts

Resposta HTTP bruta

Logs

Fetch e proxy

Parâmetros fora dos tipos

Versões

Leitura relacionada