SDKs guidelines

Follow Lerian’s SDK best practices — repository layout, error handling, examples, and version alignment — to accelerate plugin adoption.

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:

Language	Rationale
Go	Primary language of the Lerian backend stack
TypeScript	Primary language for frontend and Node.js integrations

Additional language support (Python, Java, C#) is encouraged but not required.