Contribuir para o SDK de TypeScript

Obrigado por ajudar a melhorar o @trucklinemp/sdk, o kit de ferramentas oficial em TypeScript e JavaScript para a Public API, OAuth e webhooks do TrucklineMP.

Este guia destina-se a quem quer alterar o próprio pacote do SDK (novos métodos, correções de erros, tipos, documentação no repositório). Se você precisa apenas usar o SDK em um aplicativo, consulte TypeScript SDK em vez disso.

Pacote	@trucklinemp/sdk
Código-fonte	github.com/trucklinemp/sdk
npm	npmjs.com/package/@trucklinemp/sdk
Licença	MIT

Antes de começar

1. Abra uma issue para alterações maiores, para que os mantenedores possam alinhar o design.
2. Consulte a especificação OpenAPI e o guia da Public API para o contrato HTTP real. O SDK é um cliente fino (thin client) - deve refletir rotas públicas, não inventar rotas privadas.
3. Prefere pull requests pequenos e focados a grandes reescritas.

Requisitos

• Node.js 18+ (o cliente depende do fetch global)
• npm (incluído com o Node)
• Uma conta GitHub e um fork de trucklinemp/sdk

Opcional para verificações manuais de integração:

• Uma chave de API do Console do Desenvolvedor do TrucklineMP

Clonar e instalar

git clone https://github.com/YOUR_USER/sdk.git
cd sdk
npm install

Se estiver trabalhando a partir do monorepo da Truckline, o pacote está em sdk/ com os mesmos scripts.

Scripts

Comando	Objetivo
npm run build	Empacota com tsup → dist/ (entradas main + oauth + webhooks)
npm run typecheck	tsc --noEmit
npm test	Testes unitários Vitest
npm run prepublishOnly	typecheck + test + build (mantenedores)

Execute sempre estes comandos antes de abrir um PR:

npm run typecheck
npm test
npm run build

Estrutura do pacote

sdk/
├── src/
│   ├── index.ts           # Main exports
│   ├── oauth-entry.ts     # @trucklinemp/sdk/oauth
│   ├── webhooks-entry.ts  # @trucklinemp/sdk/webhooks
│   ├── client.ts          # Truckline class
│   ├── http.ts            # fetch, retries, hooks
│   ├── resources.ts       # vtcs, users, events, …
│   ├── models.ts          # Public response types
│   ├── oauth.ts           # TrucklineOAuth + PKCE
│   ├── webhooks.ts        # HMAC + handlers (Node crypto)
│   ├── pagination.ts
│   ├── batch.ts
│   ├── errors.ts
│   ├── types.ts
│   └── version.ts
├── tests/
├── examples/
├── dist/
├── package.json
└── …

Regras de design

• Wrappers finos (thin) sobre os caminhos HTTP. Prefere this.http.get("/users/…") a mapeamentos pesados.
• Codifica segmentos de caminho com encodeURIComponent.
• Passe objetos de query através de withOpts para manter RequestOptions consistente.
• Os tipos vivem em models.ts - mantenha-nos alinhados com a public API / OpenAPI.
• A criptografia de webhook fica em webhooks.ts (apenas Node). Prefere @trucklinemp/sdk/webhooks para handlers no servidor.
• O OAuth vive em oauth.ts e na exportação do subcaminho /oauth.
• Alterações que quebrem compatibilidade em nomes de métodos / opções seguem o semver; campos de resposta opcionais podem crescer sem uma versão major.

Adicionar um método da Public API

Exemplo: a API adiciona GET /users/steam/{steamId}.

1. Confirme o caminho e os parâmetros na OpenAPI / no router público da aplicação web.
2. Adicione um método no recurso apropriado em src/resources.ts:

// UsersResource
getBySteam(steamId: string, options?: RequestOptions) {
  return this.http.get(
    `/users/steam/${encodeURIComponent(steamId)}`,
    options,
  );
}

3. Se adicionar uma nova classe de recurso, constrói-a em Truckline em src/client.ts e exporta quaisquer novos tipos de src/index.ts apenas se forem necessários aos consumidores.
4. Atualize a página de documentação para consumidores (TypeScript SDK) quando a alteração for visível para o usuário.
5. npm run build && npm run typecheck.

Válvula de escape

Se uma rota for rara ou ainda estiver a mudar, quem a chama pode usar:

await tl.get("/path");
await tl.request("GET", "/path", { query: { … } });

Prefere um método nomeado assim que a rota estiver estável e for comummente usada.

Teste rápido local contra a API

import { Truckline } from "trucklinemp-sdk"; // or import from your local checkout's src/index.ts

const tl = new Truckline({
  apiKey: process.env.TRUCKLINE_API_KEY,
});

console.log(await tl.meta.version());

Não envie chaves de API ao repositório. Use apenas variáveis de ambiente.

Pull requests

1. Faça um fork e crie uma branch a partir de main / master (corresponde à branch padrão do repositório).
2. Mantenha o diff limitado a um único assunto.
3. Descreva o que mudou e por quê e associe qualquer issue relacionada à API ou à documentação.
4. Confirme que npm run build e npm run typecheck passam.
5. Atualize o README ou a documentação quando o comportamento for visível para o usuário.

Estilo de commit (sugerenciado)

feat(sdk): add users.getBySteam
fix(sdk): encode path ids on news.get
docs(sdk): document webhook raw-body requirement
chore(sdk): bump version to 0.1.2

Lançamentos (mantenedores)

A publicação está documentada no PUBLISH.md do repositório. Resumo:

1. Aumenta a version em package.json (npm version patch|minor|major).
2. Faça push para a branch padrão (ou execute o workflow de publicação).
3. O CI compila, verifica os tipos e publica no registro npm público quando a versão é nova.

Os contribuidores não precisam de permissões de publicação no npm. Os mantenedores emitem os lançamentos após revisão.

O que não estamos à procura

• Wrappers para endpoints privados, de administração, ou exclusivos de cookies
• Empacotar utilitários não relacionados que aumenprecisasnecessariamente o pacote
• Tipos rígidos e gerados para cada campo da OpenAPI em cada lançamento (ferramentas opcionais são aceitáveis se discutidas primeiro)
• Segredos, chaves ou tokens pessoais no repositório

Conexões relacionadas

Recurso	Conexão
Usar o SDK	TypeScript SDK
Public API	Public API
Webhooks	Webhooks
Console do Desenvolvedor	trucklinemp.com/developer
OpenAPI	openapi.json
Traduções da documentação	Contribuir com traduções

Perguntas sobre as APIs da plataforma (não apenas sobre o pacote do SDK) são bem-vindas através do suporte ou dos canais de desenvolvedores listados em trucklinemp.com.