#Como usar o SDK TypeScript da Clickmax

O pacote @clickmax/public-sdk chama a API da Clickmax a partir de código JavaScript ou TypeScript. Cada endpoint tem um método tipado, e cada chamada devolve um resultado com o valor ou com o erro.

Antes de começar, você precisa de:

• uma chave de API do workspace, criada por um proprietário ou administrador em Configurações > Conexões > API (detalhes em Autenticação na API da Clickmax);
• um runtime com fetch e AbortSignal.any, como Node.js 22 ou mais recente, Deno, Bun ou Cloudflare Workers;
• um projeto que use módulos ES, porque o pacote não tem versão CommonJS.

#Fazer a primeira chamada

npm install @clickmax/public-sdk

yarn add @clickmax/public-sdk

pnpm add @clickmax/public-sdk

bun add @clickmax/public-sdk

deno add npm:@clickmax/public-sdk

import { Clickmax } from '@clickmax/public-sdk'

const clickmax = new Clickmax(process.env.CLICKMAX_API_KEY!)

const clickmax = new Clickmax(process.env.CLICKMAX_API_KEY!, {
  headers: { 'x-request-source': 'sync-de-tags' }, // enviados em toda requisição
  timeout: 60_000, // milissegundos; o padrão é 60000 e 0 desativa
  fetch: globalThis.fetch, // padrão
})

const created = await clickmax.tags.create({ name: 'VIP', color: 'ff8800' })

const result = await clickmax.tags.list()

if (!result.ok) {
  const { type, code, requestId } = result.error
  console.error('tags.list falhou', { type, code, requestId })
} else {
  console.log(result.value.data)
}

const [ok, error, tags] = await clickmax.tags.list()

if (!ok) {
  console.error('tags.list falhou', {
    type: error.type,
    code: error.code,
    requestId: error.requestId,
  })
} else {
  console.log(tags.data)
}

#Tratar cada tipo de erro

O error de um resultado com falha é um ClickmaxError, que estende Error:

const result = await clickmax.tags.create({ name: 'VIP' })

if (!result.ok) {
  const { error } = result

  switch (error.type) {
    case 'invalid_request':
      console.error('Entrada recusada', {
        op: 'tags.create',
        code: error.code,
        issues: error.issues,
      })
      break
    case 'authentication':
      console.error('Confira a chave, o ambiente e a lista de IPs permitidos', {
        op: 'tags.create',
        code: error.code,
        requestId: error.requestId,
      })
      break
    case 'rate_limit':
      console.error('Limite de requisições atingido', {
        op: 'tags.create',
        retryAfterSeconds: error.retryAfter ?? 10,
      })
      break
    default:
      console.error('tags.create falhou', {
        op: 'tags.create',
        type: error.type,
        code: error.code,
        message: error.message,
        requestId: error.requestId,
      })
  }
}

Os campos type, code, requestId e issues vêm do corpo de erro da API, e os valores possíveis estão em Erros na API da Clickmax. O erro também tem status (o status HTTP, ou 0 quando nenhuma resposta chegou), message (texto para logs, que pode mudar entre versões), retryAfter (os segundos do cabeçalho Retry-After, quando a API envia) e raw (o corpo da resposta como veio). Se a resposta de erro não vier em JSON, o SDK deduz o type pelo status HTTP.

Quando a requisição não recebe uma resposta utilizável, o SDK usa tipos próprios:

Quando o SDK recusa um argumento antes de enviar a requisição, como um timeout negativo ou um corpo que não pode ser convertido em JSON, o resultado falha com type invalid_request, code invalid_argument e status 0.

Ao pedir ajuda ao suporte, informe o error.requestId.

#Tentar de novo após o limite de requisições

Todas as chaves de um workspace dividem o limite de 100 requisições a cada 10 segundos. Quando ele é ultrapassado, o resultado falha com type rate_limit e retryAfter indica quantos segundos esperar:

async function listTags() {
  for (let attempt = 0; attempt < 3; attempt++) {
    const result = await clickmax.tags.list()

    if (result.ok || result.error.type !== 'rate_limit') return result

    await new Promise((resolve) => setTimeout(resolve, (result.error.retryAfter ?? 10) * 1000))
  }

  return clickmax.tags.list()
}

Repita automaticamente os erros rate_limit. Nos erros api, network e timeout, repita com intervalos crescentes (backoff) só quando for seguro fazer a chamada de novo. Um erro invalid_request, authentication ou permission volta igual enquanto a requisição ou a conta não mudarem.

#Mudar as opções de uma única chamada

O último argumento de todo método aceita signal, timeout, headers e fetch. Cada opção substitui o valor da instância só naquela chamada:

const controller = new AbortController()

await clickmax.tags.list({ signal: controller.signal, timeout: 5_000 })

await clickmax.tags.create(
  { name: 'VIP' },
  { headers: { 'x-request-id': crypto.randomUUID() } },
)

Os cabeçalhos da chamada são aplicados por cima dos cabeçalhos da instância. O cabeçalho Authorization sempre usa a chave da instância e não pode ser trocado por chamada.

#Usar vários workspaces

Cada instância guarda a própria chave e as próprias opções, e as instâncias não compartilham estado. Crie uma instância por workspace:

const lojaA = new Clickmax(process.env.LOJA_A_API_KEY!)
const lojaB = new Clickmax(process.env.LOJA_B_API_KEY!)

const [resultA, resultB] = await Promise.all([lojaA.tags.list(), lojaB.tags.list()])

#Validar dados com zod

O subcaminho @clickmax/public-sdk/zod exporta schemas do zod para a entrada e para a resposta de sucesso de cada endpoint. O uso é opcional: o cliente não importa esses schemas e não valida a entrada antes de enviar a requisição. Para usá-los, instale o zod 4 (4.1.13 ou uma versão 4.x mais recente) no seu projeto:

npm install zod

yarn add zod

pnpm add zod

bun add zod

deno add npm:zod

O nome do schema junta o recurso e o método em PascalCase com um sufixo:

A referência interativa mostra o método HTTP de cada endpoint. Métodos do próprio cliente usam só o nome do método, como WhoamiResponse para clickmax.whoami().

import { TagsCreateBody } from '@clickmax/public-sdk/zod'

const input = TagsCreateBody.safeParse(formulario)

if (!input.success) {
  console.error('Tag inválida', { op: 'tags.create', issues: input.error.issues })
} else {
  await clickmax.tags.create(input.data)
}

Os schemas são escritos com zod/mini, e o bundler inclui no seu build só os schemas que você importa.

#Atualizar o pacote

Cada versão do pacote corresponde à API v0 no momento em que foi publicada. Como a v0 ainda pode mudar, fixe a versão que você testou e teste a integração antes de atualizar.