kata_cx 1.0.2

Headless Kata CX Dashboard chat client for Flutter — iOS, Android and Web. Send messages, stream replies, run the CSAT survey, with no UI attached.

Changelog

1.0.2 — 2026-09-17

• KataCx.setup no longer cancels a request it just started. Calling setup again tore down the running client unconditionally, and disposing a client closes its HTTP client — cancelling anything in flight. A native host reaches this path twice by design, because warming the engine and opening the chat both call setup, and the warmed engine has already begun fetching the tenant's settings by the time the second call arrives. The fetch died with "Connection attempt cancelled", the screen fetches settings only once, and the chat kept the fallback bot name and default colours for the rest of the session while the middleware had been answering correctly all along. Setup now keeps the running client when every input matches. Found on a real device; the regression test was checked by removing the fix.

1.0.1 — 2026-09-14

• A keystore that never answers no longer hangs KataCx.setup. SecureStoreBackend probes the platform keystore once and falls back to shared preferences when it is unusable, but it only caught a thrown error. A platform channel that never replies does not throw — it leaves the probe pending forever, and setup with it, giving the SDK's first call the worst failure shape available: no exception, no log line, nothing to search for. The probe is now bounded and silence takes the same fallback branch an exception always did.
• Document the Android INTERNET permission. The Flutter template declares it in the debug and profile manifests only, so a release build reaches no network and every call fails with "connection errored" despite valid credentials. Found by installing the first release APK on a real device.
• Dropped the repository link. It pointed at a private repository, so on a public package page it was a login wall rather than source.

1.0.0 — 2026-09-14

Phase 1 of the port from com.kata.sdk.cx. Feature-complete apart from saveContact, which is deferred.

The client

• KataCx.setup / setupWithCustomServer / client / reset, and a KataCxClient covering settings, send, streaming send, the CSAT survey, session history and clearing.
• Sends are queued serially, so n_chat can never be duplicated by two messages in flight. The visitor's own message is appended synchronously before queueing, as it is on Android, so a slow reply never delays the echo.
• Visitor identity is optional: with one, the session id is {visitorId}_{timestamp}, re-minted per conversation; without, a device-scoped anon_<32 hex> id is used instead.
• Opt-in system notifications behind a KataCxNotifier interface, so this package carries no notification dependency. The default implementation lives in kata_cx_ui.

Wire format

• Models, token parsing and settings defaults: KataCxToken, KataCxEnvironment, KataCxSettings, KataCxMessage, KataCxChatResponse, KataCxSession. Parsing is type-tolerant, so one wrong-typed field from the dashboard cannot take the widget down.
• Request bodies are byte-identical to the Android SDK's, checked against a recording of its actual socket traffic rather than by reading the code. The one deliberate difference: X-Widget-Token is sent on the chat endpoints too, ahead of the middleware enforcing it there.

Transport and storage

• dio on iOS, Android and the VM; fetch_client on web, because the browser XHR adapter buffers the whole response body and would defeat streaming.
• UTF-8 is decoded across the byte stream rather than per chunk, so a multi-byte character split across two socket reads survives.
• Store hydrates once into memory, reads synchronously, writes through a serial queue, expires after 30 days, and is namespaced per token and visitor. flutter_secure_storage with a shared_preferences fallback when the platform keystore is unusable.
• flutter_secure_storage pinned to ^10.3.2: 11.0.0 declares compileSdk = 37, for which no installable Android platform package yet exists. Revisit when either the plugin or AGP catches up.

Testing

• package:kata_cx/testing.dart exports FakeMiddleware and InMemoryStoreBackend.