> ## 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.

# 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](/en/partners-hub/error-model)
* Include examples and tests for key functions
* Keep versions in sync with the plugin’s releases

<Tip>
  Go and TypeScript SDKs are preferred, as they align with Lerian's main stack and partner ecosystem.
</Tip>

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

* **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](/en/partners-hub/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.