TypeScript

O cliente sparkcrm inclui comportamentos de produção herdados do gerador Stainless. Esta página resume o que importa ao integrar o Spark de forma resiliente.

Erros HTTP

Falhas de rede ou respostas 4xx / 5xx lançam subclasses de SparkCRM.APIError:

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

import SparkCRM from "sparkcrm";

try {
  await client.entrypoints.list();
} catch (err) {
  if (err instanceof SparkCRM.RateLimitError) {
    // aguardar e tentar de novo, ou reduzir throughput
  } else if (err instanceof SparkCRM.APIError) {
    console.error(err.status, err.message);
  } else {
    throw err;
  }
}

Mensagens de validação da API (por exemplo variáveis de template faltando) costumam vir em 400 com texto descritivo no corpo.

Retentativas

Por padrão o cliente repete até 2 vezes com backoff exponencial em:

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

Desligar ou ajustar globalmente:

const client = new SparkCRM({
  apiKey: process.env.SPARK_API_KEY,
  maxRetries: 0,
});

Ou por requisição:

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

Timeouts

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

Métodos retornam APIPromise<T>. Para acessar cabeçalhos sem consumir o body:

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

Para dados parseados e Response:

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

Logging

Nível via SPARK_CRM_LOG ou logLevel no construtor: debug, info, warn, error, off (padrão warn). Em debug, requisições e respostas são logadas (cuidado com dados sensíveis em produção). Logger customizado (Pino, Winston, etc.):

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

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

Fetch e proxy

Passe fetch alternativo ou fetchOptions (por exemplo dispatcher do Undici no Node para proxy corporativo). Exemplos no README do repositório.

Parâmetros e endpoints não documentados

O SDK não valida em runtime campos extras — você pode enviar opções ainda não refletidas nos tipos:

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

Para rotas sem método dedicado:

await client.post("/v1/messaging/chats/{chatId}/templates", {
  body: { templateId: "…", commonVariables: { var1: "x" } },
});

Versionamento

O pacote segue SemVer. Mudanças só de tipos podem sair em versão minor sem quebrar runtime. Acompanhe releases no npm e issues no GitHub.

Visão geral

TypeScript — erros e uso avançado

Erros HTTP

Retentativas

Timeouts

Resposta HTTP bruta

Logging

Fetch e proxy

Parâmetros e endpoints não documentados

Versionamento

Leitura relacionada

​Erros HTTP

​Retentativas

​Timeouts

​Resposta HTTP bruta

​Logging

​Fetch e proxy

​Parâmetros e endpoints não documentados

​Versionamento

​Leitura relacionada

Erros HTTP

Retentativas

Timeouts

Resposta HTTP bruta

Logging

Fetch e proxy

Parâmetros e endpoints não documentados

Versionamento

Leitura relacionada