From 51cdd6ea91b154052cd8130af332ea2205251105 Mon Sep 17 00:00:00 2001 From: flemming-it Date: Tue, 7 Jul 2026 13:44:43 +0200 Subject: [PATCH] docs: describe the shipped SDK surface instead of the 2026-05 scaffold status README still claimed generated bindings would land later and Studio ran on mock data; CHANGELOG was the create-package stub. Both now state the actual surface (full Hub+HubAdmin client, streaming, detached invocations, gRPC + gRPC-Web, bearer auth) and the path/git-dep distribution model. Signed-off-by: flemming-it --- CHANGELOG.md | 25 +++++++++++++++++++++-- README.md | 57 +++++++++++++++++++++++++++++++--------------------- 2 files changed, 57 insertions(+), 25 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index effe43c..7f574c9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,24 @@ -## 1.0.0 +# Changelog -- Initial version. +The SDK version tracks the platform release that shipped the +matching wire surface; see the platform repo's `CHANGELOG.md` +for the authoritative per-release detail. + +## 0.18.x (current) + +- Full Hub + HubAdmin coverage: `submit` (incl. `detach:`), + `submitStreaming`, `runSavedFlow` (text/bytes/json inputs), + detached invocation status/result/cancel, saved flows, store + + module management, audit (`eventLog`, `streamEvents`, + `verifyEventChain`), approvals, federation admin + (`listSatellites`, `issueBootstrapToken`, `revokeSatellite`), + MCP/n8n endpoint management, System-AI administration. +- Bearer-token auth via `HubClient(authToken:)`. +- Native gRPC + gRPC-Web transports (conditional import). +- Generated bindings for the renamed `chain.v1` wire package. + +## Earlier + +- 0.x line grew alongside the platform (package started as a + scaffold named `fai_client_sdk`, renamed to + `chain_client_sdk` in the product rename, 2026-06). diff --git a/README.md b/README.md index 86338a9..137e9fb 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,36 @@ # chain_client_sdk (Dart) -gRPC client SDK for the Ch∆In hub. Used by F∆I Studio +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 `fai serve`. +that wants to talk to a running `chain serve`. -One of the three SDK families documented in -`fai/platform/docs/architecture/sdks.md`: +One of the three SDK families documented in the platform repo +(`docs/architecture/client-sdks.md`): - * `fai-module-sdk` (Rust) — flow modules - * `fai-plugin-sdk` (Rust) — Studio plugins - * `chain_client_sdk` (Dart) — clients ← this package + * `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 -(`chain_client_sdk_dart` / `client-sdk-dart`); the Dart package -name itself does not (Dart-land doesn't need the 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 (2026-05-05):** scaffold. Public surface (`HubClient`, -> `HubEndpoint`) is committed; generated proto bindings land in -> a follow-up commit once the codegen step is wired in. Until -> then, downstream apps can compile against the stub and Studio -> uses mock data. +> **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 @@ -35,29 +46,29 @@ boilerplate. This package centralises that work: ## Layout ``` -chain_client_sdk_dart/ +fai_chain_client_sdk_dart/ ├── lib/ │ ├── chain_client_sdk.dart # Public API │ └── src/ -│ ├── hub_client.dart # Typed client wrapper +│ ├── 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 tag) +│ └── generated/ # protoc output (committed; pinned to platform proto) ├── tools/ -│ └── generate.sh # Wraps `protoc --dart_out=...` against ../fai_platform/proto +│ └── generate.sh # Wraps `protoc --dart_out=...` against ../fai_chain/proto ├── example/ └── pubspec.yaml ``` ## Repo placement -Published as `fai/client-sdk-dart` on Forgejo +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 `fai:platform@1.x` is current, this -SDK stays at `0.x` (will move to `1.0` once API stabilises); -when `fai:platform@2.0` lands, a `2.x` SDK ships in parallel -during the transition. +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.