Skip to main content
While not mandatory, SDKs are a strong recommendation for every plugin in the Lerian ecosystem. They accelerate adoption, improve developer experience, and reduce integration errors for clients. By offering SDKs in popular languages, you make it easier for users to interact with your plugin and build reliable solutions on top of it. Best practices for SDKs:
  • Support the most common use cases out of the box
  • Provide clear error handling aligned with Lerian’s Error Model
  • Include examples and tests for key functions
  • Keep versions in sync with the plugin’s releases
Go and TypeScript SDKs are preferred, as they align with Lerian’s main stack and partner ecosystem.

​
Repository structure

Organize your SDK repository with a consistent layout: 
your-plugin-sdk/
├── README.md            # Overview, installation, and quickstart
├── CHANGELOG.md         # Version history following Keep a Changelog format
├── LICENSE
├── src/                 # Source code
├── examples/            # Working code samples for common use cases
├── tests/               # Unit and integration tests
└── docs/                # Additional documentation (optional)
Include a README.md with installation instructions, a minimal usage example, and a link to the full documentation.

​
Naming conventions

Align package and module names with Lerian product names:
  • Use lowercase for package names: midaz, feesengine, tracer
  • Prefix with your organization name when publishing to registries: @yourorg/midaz-plugin-sdk
  • Keep naming consistent across languages: if the Go module is midaz-plugin-sdk, the npm package follows the same pattern

​
Versioning

Follow Semantic Versioning (semver):
  • MAJOR — breaking changes to the SDK’s public API
  • MINOR — new features, backward-compatible
  • PATCH — bug fixes, backward-compatible
Sync SDK releases with your plugin releases. When the plugin version changes, release a matching SDK version. Document the plugin-to-SDK version mapping in your README.md.

​
Error handling

Wrap responses from the Lerian Error model into typed errors:
  • Map each Lerian error code to a specific error type or class in your SDK
  • Include the original error code, message, and details fields in the typed error
  • Provide helper methods for checking error types (e.g., IsNotFoundError() in Go, instanceof NotFoundError in TypeScript)
  • Never swallow errors silently — always propagate or wrap them with context

​
Minimum languages

Provide SDKs in at least these two languages:
LanguageRationale
GoPrimary language of the Lerian backend stack
TypeScriptPrimary language for frontend and Node.js integrations
Additional language support (Python, Java, C#) is encouraged but not required.