Pular para o conteúdo principal
Embora não sejam obrigatórios, SDKs são uma forte recomendação para todo plugin no ecossistema Lerian. Eles aceleram a adoção, melhoram a experiência do desenvolvedor e reduzem erros de integração para os clientes. Ao oferecer SDKs em linguagens populares, você facilita a interação dos usuários com seu plugin e a construção de soluções confiáveis sobre ele. Boas práticas para SDKs:
  • Suporte aos casos de uso mais comuns prontos para usar
  • Forneça tratamento de erros claro, alinhado com o Modelo de Erros da Lerian
  • Inclua exemplos e testes para funções-chave
  • Mantenha as versões sincronizadas com os releases do plugin
SDKs em Go e TypeScript são preferidos, pois estão alinhados com a stack principal da Lerian e do ecossistema de parceiros.

​
Estrutura do repositório

Organize o repositório do seu SDK com um layout consistente: 
your-plugin-sdk/
├── README.md            # Visão geral, instalação e quickstart
├── CHANGELOG.md         # Histórico de versões seguindo o formato Keep a Changelog
├── LICENSE
├── src/                 # Código-fonte
├── examples/            # Exemplos de código funcionais para casos de uso comuns
├── tests/               # Testes unitários e de integração
└── docs/                # Documentação adicional (opcional)
Inclua um README.md com instruções de instalação, um exemplo mínimo de uso e um link para a documentação completa.

​
Convenções de nomenclatura

Alinhe os nomes de pacotes e módulos com os nomes de produtos da Lerian:
  • Use letras minúsculas para nomes de pacotes: midaz, feesengine, tracer
  • Prefixe com o nome da sua organização ao publicar em registries: @yourorg/midaz-plugin-sdk
  • Mantenha a nomenclatura consistente entre linguagens: se o módulo Go é midaz-plugin-sdk, o pacote npm segue o mesmo padrão

​
Versionamento

Siga o Semantic Versioning (semver):
  • MAJOR — mudanças incompatíveis na API pública do SDK
  • MINOR — novas funcionalidades, compatíveis com versões anteriores
  • PATCH — correções de bugs, compatíveis com versões anteriores
Sincronize os releases do SDK com os releases do seu plugin. Quando a versão do plugin mudar, lance uma versão correspondente do SDK. Documente o mapeamento de versão plugin-SDK no seu README.md.

​
Tratamento de erros

Encapsule as respostas do Modelo de erros da Lerian em erros tipados:
  • Mapeie cada código de erro da Lerian para um tipo ou classe de erro específico no seu SDK
  • Inclua os campos originais code, message e details do erro no erro tipado
  • Forneça métodos auxiliares para verificar tipos de erro (ex.: IsNotFoundError() em Go, instanceof NotFoundError em TypeScript)
  • Nunca engula erros silenciosamente — sempre propague ou encapsule com contexto

​
Linguagens mínimas

Forneça SDKs em pelo menos estas duas linguagens:
LinguagemJustificativa
GoLinguagem principal da stack backend da Lerian
TypeScriptLinguagem principal para frontend e integrações Node.js
Suporte a linguagens adicionais (Python, Java, C#) é encorajado, mas não obrigatório.