Saltar al contenido principal
Si bien no son obligatorios, los SDKs son una recomendación fuerte para cada plugin en el ecosistema de Lerian. Aceleran la adopción, mejoran la experiencia del desarrollador y reducen errores de integración para los clientes. Al ofrecer SDKs en lenguajes populares, facilitas que los usuarios interactúen con tu plugin y construyan soluciones confiables sobre él. Mejores prácticas para SDKs:
  • Soporta los casos de uso más comunes desde el principio
  • Proporciona manejo de errores claro alineado con el Modelo de errores de Lerian
  • Incluye ejemplos y pruebas para funciones clave
  • Mantén las versiones sincronizadas con los lanzamientos del plugin
Se prefieren SDKs en Go y TypeScript, ya que se alinean con el stack principal de Lerian y el ecosistema de socios.

​
Estructura del repositorio

Organiza el repositorio de tu SDK con un diseño consistente: 
your-plugin-sdk/
├── README.md            # Descripción general, instalación e inicio rápido
├── CHANGELOG.md         # Historial de versiones siguiendo el formato Keep a Changelog
├── LICENSE
├── src/                 # Código fuente
├── examples/            # Ejemplos de código funcionales para casos de uso comunes
├── tests/               # Pruebas unitarias y de integración
└── docs/                # Documentación adicional (opcional)
Incluye un README.md con instrucciones de instalación, un ejemplo mínimo de uso y un enlace a la documentación completa.

​
Convenciones de nomenclatura

Alinea los nombres de paquetes y módulos con los nombres de productos de Lerian:
  • Usa minúsculas para nombres de paquetes: midaz, feesengine, tracer
  • Agrega el prefijo con el nombre de tu organización al publicar en registros: @yourorg/midaz-plugin-sdk
  • Mantén la nomenclatura consistente entre lenguajes: si el módulo Go es midaz-plugin-sdk, el paquete npm sigue el mismo patrón

​
Versionado

Sigue Semantic Versioning (semver):
  • MAJOR — cambios incompatibles en la API pública del SDK
  • MINOR — nuevas funcionalidades, compatibles con versiones anteriores
  • PATCH — corrección de errores, compatibles con versiones anteriores
Sincroniza los lanzamientos del SDK con los lanzamientos de tu plugin. Cuando cambie la versión del plugin, lanza una versión correspondiente del SDK. Documenta el mapeo de versiones plugin-SDK en tu README.md.

​
Manejo de errores

Envuelve las respuestas del Modelo de errores de Lerian en errores tipados:
  • Mapea cada código de error de Lerian a un tipo o clase de error específico en tu SDK
  • Incluye los campos originales code, message y details del error en el error tipado
  • Proporciona métodos auxiliares para verificar tipos de error (ej., IsNotFoundError() en Go, instanceof NotFoundError en TypeScript)
  • Nunca ocultes errores silenciosamente — siempre propágalos o envuélvelos con contexto

​
Lenguajes mínimos

Proporciona SDKs en al menos estos dos lenguajes:
LenguajeJustificación
GoLenguaje principal del stack backend de Lerian
TypeScriptLenguaje principal para frontend e integraciones Node.js
Se incentiva el soporte de lenguajes adicionales (Python, Java, C#) pero no es obligatorio.