# chain_client_sdk (Dart)

gRPC client SDK for the Ch∆In hub. Used by Ch∆In Studio
(Tier-2 generic GUI) and any Tier-3 Dart/Flutter domain app
that wants to talk to a running `chain serve`.

One of the three SDK families documented in the platform repo
(`docs/architecture/client-sdks.md`):

  * `chain-module-sdk` (Rust) — flow modules
  * `chain-plugin-sdk` (Rust) — Studio plugins
  * `chain_client_sdk` (Dart) — clients ← this package

Dir / repo carries the `_dart` / `-dart` language suffix
(`fai_chain_client_sdk_dart` / `chain-client-sdk-dart`); the
Dart package name itself does not (Dart-land doesn't need the
suffix).

> **Status:** functional and in production use by Studio. The
> generated proto bindings (`lib/src/generated/chain/v1/`) are
> committed and pinned to the platform's wire protocol
> (`chain.v1`). `HubClient` exposes the full Hub + HubAdmin
> surface — flow execution (`submit` incl. `detach`,
> `submitStreaming`, `runSavedFlow`), detached-invocation
> status/result/cancel, saved flows, store + module management,
> audit log (`eventLog`, `streamEvents`, `verifyEventChain`),
> approvals, federation admin, MCP/n8n endpoint management,
> System-AI administration, and bearer-token auth
> (`HubClient(authToken:)`). Works over native gRPC (desktop /
> CLI) and gRPC-Web (browser) via conditional channel factories.
>
> Not yet published to pub.dev (`publish_to: none`) — consume it
> as a path or git dependency.

## Why a separate SDK package

The platform hub speaks gRPC. Each Dart consumer (Studio plus
each Tier-3 domain app) would otherwise re-generate proto
bindings independently and write near-identical client
boilerplate. This package centralises that work:

- One source of generated proto bindings.
- One typed `HubClient` wrapper with helpers.
- One place to bump when the wire protocol evolves.

## Layout

```
fai_chain_client_sdk_dart/
├── lib/
│   ├── chain_client_sdk.dart        # Public API
│   └── src/
│       ├── hub_client.dart           # Typed client wrapper (~55 methods)
│       ├── channel_factory_io.dart   # Native ClientChannel (HTTP/2)
│       ├── channel_factory_web.dart  # GrpcWebClientChannel.xhr (HTTP/1.1)
│       └── generated/                # protoc output (committed; pinned to platform proto)
├── tools/
│   └── generate.sh                  # Wraps `protoc --dart_out=...` against ../fai_chain/proto
├── example/
└── pubspec.yaml
```

## Repo placement

Published as `fai/chain-client-sdk-dart` on Forgejo
(`git.flemming.ai`).

## Versioning

Tracks the platform's wire-protocol version, not the platform
binary version. As long as `chain.v1` is current, this SDK
stays at `0.x` (will move to `1.0` once the API stabilises);
when a `chain.v2` wire package lands, a `2.x` SDK ships in
parallel during the transition.