> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Diretrizes de SDKs

> Siga as melhores práticas de SDKs da Lerian — estrutura do repositório, tratamento de erros, exemplos e alinhamento de versões — para acelerar a adoção.

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](/pt/partners-hub/error-model) da Lerian
* Inclua exemplos e testes para funções-chave
* Mantenha as versões sincronizadas com os releases do plugin

<Tip>
  SDKs em Go e TypeScript são preferidos, pois estão alinhados com a stack principal da Lerian e do ecossistema de parceiros.
</Tip>

## 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)](https://semver.org):

* **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](/pt/partners-hub/error-model) 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:

| Linguagem  | Justificativa                                           |
| ---------- | ------------------------------------------------------- |
| Go         | Linguagem principal da stack backend da Lerian          |
| TypeScript | Linguagem principal para frontend e integrações Node.js |

Suporte a linguagens adicionais (Python, Java, C#) é encorajado, mas não obrigatório.