Skip to content

Multi-SDK

Purpose

First-class client SDKs for C#/.NET, Python, and TypeScript, generated from service Protobuf definitions and distributed via private Gitea package registries with idiomatic async APIs and consistent error handling.

Requirements

Requirement: Single-Source Proto Contracts

Every service with a public API SHALL define its interface in a Protocol Buffers .proto file. Client SDKs for all languages SHALL be generated from this single source.

Scenario: Proto as source of truth

  • WHEN a service adds or modifies an RPC method
  • THEN the change SHALL be made in the .proto file, with SDKs regenerated from it

Requirement: First-Class .NET Client

Each service SHALL provide a NuGet package with a typed gRPC client. The client SHALL support using the service's generated stubs directly.

Scenario: Service invocation

  • WHEN a .NET consumer references the client NuGet package
  • THEN it SHALL be able to call all gRPC methods strongly typed, without manual proto compilation

Requirement: First-Class Python Client

Each service SHALL provide a PyPI package (virtufin-<service>) with async gRPC client wrappers. Generated stubs SHALL use grpcio.

Scenario: Async service invocation

  • WHEN a Python consumer imports the client package and calls an async method
  • THEN the call SHALL be made over gRPC asynchronously

Requirement: First-Class TypeScript Client

Each service SHALL provide an npm package (@virtufin/<service>) with gRPC-Web or ConnectRPC client support.

Scenario: Browser gRPC-Web call

  • WHEN a TypeScript consumer in a browser environment calls a service method
  • THEN the call SHALL use gRPC-Web transport with ConnectRPC

Requirement: Idiomatic Error Handling

Client SDKs SHALL translate gRPC status codes to language-idiomatic exceptions or error types.

Scenario: Not found error

  • WHEN the server returns NOT_FOUND
  • THEN the Python client SHALL raise a typed exception with the gRPC status details
  • THEN the TypeScript client SHALL return a discriminated error
  • THEN the C# client SHALL throw an RpcException

Requirement: Gitea Package Distribution

All SDK packages SHALL be published to the private Gitea package registry. Build pipelines SHALL handle versioning from a shared versions.env.

Scenario: Package publishing

  • WHEN a service is released
  • THEN its NuGet package SHALL be published to the Gitea NuGet registry
  • THEN its PyPI package SHALL be published to the Gitea PyPI registry
  • THEN its npm package SHALL be published to the Gitea npm registry

Requirement: Version Compatibility

Client SDK versions SHALL match the API version of the service they connect to. Breaking proto changes SHALL bump the library major version.

Scenario: API version mismatch

  • WHEN a client SDK v1 connects to a service with an incompatible proto schema
  • THEN the error SHALL be clearly identifiable as a version mismatch