mugib_sdk 1.0.41

Official Flutter SDK for Mugib chat sessions, voice agents, and session payload with one apiKey.

Changelog

1.0.41

• Voice Core fallback. /token fallback_url is now used when the Edge stream_url is unreachable (same behavior as voice-widget.js). Reconnects stay on Core after a fallback so a dead Edge does not loop.
• Localhost / raw-IP Edge hosts are skipped on the device (self-signed certs).

1.0.40

• Inbox photos on history. MugibChatMessage.attachments now carries the same catalog images (rooms, cars, products, courses, trips) that streamed replies already expose via MugibStreamAttachments. getHistory() and poll recent turns stay in sync with the widget and desk.

1.0.39

• Docs: README now documents the optional mugib_sdk_push add-on (proactive push with automatic App ID) and updated version references. No API changes.

1.0.38

• Automatic App ID. getPushConfig({bundleId, platform}) now lets Mujib resolve the Firebase App ID for the exact app automatically (it looks up or registers the matching app in the central Firebase project and caches it), so developers never paste an App ID. Called without arguments, behavior is unchanged (globally-configured App IDs are returned).

1.0.37

• Central Firebase for push (no per-app Firebase setup). New mugib.getPushConfig() fetches the non-secret Firebase client identifiers from Mujib (project id, sender id, api key, per-platform app id). Apps initialize a dedicated Firebase app from these values — no bundled google-services.json / GoogleService-Info.plist. The Firebase service account (the send credential) stays encrypted on the Mujib server and never reaches the device.
• Adds MugibPushConfig model with androidOptions / iosOptions helpers.
• setPushToken / device_id behavior unchanged; see docs §3.6 for the full centralized push flow.

1.0.36

• Mobile SDK is now its own sdk channel. SDK traffic is separated from the web widget: every request carries an X-Channel: sdk header so Mujib tracks app installations as distinct contacts.
• Managed device identity. The SDK generates and persists a stable device_id per installation and sends it automatically as the sdk contact identity — you never add it to your business payload. Read it via mugib.deviceId() if needed.
• Outbound push. New mugib.setPushToken(...) registers the app's FCM token (sent as a top-level field, never inside payload). This lets Mujib reach the user with a push notification for follow-ups, surveys, and marketing campaigns when the app is backgrounded or closed. Configure the Firebase service account in Portal → Channels → Mobile App (SDK).
• Adds shared_preferences dependency for durable device-id storage.

1.0.35

• Adaptive barge-in. The voice barge-in threshold now rises above the caller's ambient noise floor (tracked live), so background noise in a loud room is not mistaken for an interruption. The server//token value is always kept as a lower bound.
• Self-tuning echo guard. The post-playback grace window widens automatically when residual speaker echo is detected and decays back once the environment is clean (bounded to 600 ms), improving robustness on devices with weak hardware AEC.
• Audio interruption handling. Voice calls now react to OS audio interruptions (incoming phone call, Siri/Assistant, another app taking focus): mic capture/uplink pauses and buffered agent audio is preserved, then the session reactivates and resumes automatically when focus returns.
• client_state now also reports the live noise_floor so the server can co-tune its own VAD/echo gating.
• No public API changes.

1.0.34

• Image attachments in chat. Mujib can now show/send catalog images (inbox apps: inventory, cars, hotel, courses, trips).
• MugibChatReply.attachments — List<MugibChatAttachment> on blocking replies (send()), each with type (image), url, optional caption.
• New SSE event: streamed replies emit MugibStreamAttachments (via sendStream()); the JSON contents are no longer leaked into reply text.
• New public types: MugibChatAttachment, MugibStreamAttachments, helper parseMugibAttachments.
• No breaking change. Existing send() / sendStream() / sendStreamText() callers keep working; attachments are additive and optional to render.

1.0.33

• Add UPGRADE.md — copy-paste notice for app teams (Arabic + English)
• Please upgrade: mugib_sdk: ^1.0.33
• No endpoint or call-API change. Same /token, start(), send(), payload
• Voice Edge routing is already in 1.0.29+ (Core returns stream_url)
• Optional UI: MugibCallState.searching during KB / tool waits
• App voice handoff = Inbox follow-up, not a live join; use watchHandoff() for chat
• Server strips unresolved {{VAR}} placeholders — do not substitute in the app
• Flush playback on interrupted only

1.0.32

• Example: show MugibCallState.searching ("Looking that up…") during KB/tool waits so the demo matches the live protocol
• Docs: state list includes searching; web/Flutter voice handoff flags Inbox follow-up (nobody joins the live audio); flush playback on interrupted only
• Comments: reconnect opens a new server bridge — session / resume query params are forward-compat only

1.0.31

• Chat: live-agent replies use the same session.send() and reply field as the bot — no new endpoint and no app code change required
• Additive: MugibChatReply.agentMessages and MugibHandoffPoll.recent
• sendStream accepts a JSON handoff response (same reply text)
• Compatibility: existing send() / poll() / watchHandoff() unchanged

1.0.30

• Chat: additive session.watchHandoff() auto-poll stream (cancel to stop); existing poll() unchanged
• Voice/UI: optional Material post-call CSAT via showMugibPostCallCsat and MugibPostCallCsatListener when MugibVoiceCallOptions.chatSessionId is set
• Voice: expose linkedChatSessionId / canOfferPostCallCsat after start
• Compatibility: no breaking API changes for existing apps

1.0.29

• Voice: honor Core-routed stream_url from /token so calls can land on a Mugib Edge host (with Core fallback when no Edge is online)

1.0.28

• Voice: new MugibCallState.searching when the agent runs KB / MCP / tools (server state: searching) so UIs can show a "looking that up" indicator

1.0.27

• Docs: pin install examples to ^1.0.26+ and clarify Gemini Live / OpenAI Realtime use the same SDK voice API

1.0.26

• Voice: accept OpenAI Realtime agents (openai_realtime) on the same Mugib stream path as Gemini Live — no app API changes; provider is chosen on the agent
• Voice: isMugibVoiceAi covers both gemini_live and openai_realtime
• Compatibility: Gemini Live agents and existing start() / token / stream usage are unchanged for customers

1.0.25

• Docs: explain stream-token security, 45-second handshake TTL, unlimited established-call duration, reconnect behavior, and legacy SDK migration
• Docs: update Portal examples and all Flutter dependency references

1.0.24

• Voice: authenticate WebSocket handshakes with the short-lived, single-use stream_token returned by /voice-agents/{id}/token
• Voice: request a fresh stream token for every automatic reconnect
• Compatibility: retain API-key WebSocket fallback for older Mugib backends

1.0.23

• Voice: lower playback buffer default (960 frames ≈ 40ms @ 24kHz, was 166ms) for faster time-to-first-audio and response latency
• Voice: parallel WebSocket connect + playback setup during call start

1.0.22

• Voice: echo_guard_ms and barge_in_threshold come from Mugib /token and WebSocket ready — no per-app tuning; Admin settings are the single source of truth
• Voice: MugibVoiceToken includes server echo-guard fields; VoiceEchoGuard.applyServerConfig

1.0.21

• Voice: echo guard — suppresses mic uplink during agent playback unless input level exceeds a barge-in threshold; sends client_state to the server every ~150 ms
• Voice: preferSpeaker (default false) on MugibVoiceClient / MugibVoiceSession — earpiece/receiver routing on iOS and Android for cleaner AEC; opt in to loudspeaker when needed (preferSpeaker: true)
• Voice: VoiceEchoGuard — coordinates client-side gating with VoicePlaybackCoordinator (grace window + level-based barge-in)
• Voice: Android speakerphone follows preferSpeaker instead of always forcing speaker
• Voice: iOS audio session no longer forces defaultToSpeaker unless preferSpeaker is true
• Server (Mugib backend): matching uplink gate via voice.echo_guard_ms and voice.barge_in_threshold settings (migration 130)
• Voice: MugibVoiceService.client() — forwards preferSpeaker to MugibVoiceClient

Upgrade note: If you previously worked around echo with allow_interruption: false in Portal, you can re-enable barge-in and rely on echo guard instead.

1.0.20

• Voice: rollback to the stable 1.0.12 stack — removes Silero VAD, uplink level gates, and post-greeting mic blocks that caused cut-offs, delay, and silent uplink on iOS/web
• Voice: mic uplink stays open when barge-in is enabled; pauses only when the agent has interruption disabled and PCM is still playing
• Voice: VoicePlaybackCoordinator defers listening until agent audio drains

1.0.12

• Voice: defer listening UI/state until buffered agent PCM finishes playing, so false VAD/echo signals no longer cut agent speech mid-sentence
• Voice: wire allowInterruption from /token — mic uplink stays open when barge-in is enabled (default); uplink pauses during agent playback only when the agent has interruption disabled
• Voice: VoicePlaybackCoordinator keeps playback and call state in sync; real interrupted events still flush audio immediately for user barge-in

1.0.11

• Voice: MugibVoiceClient.inputLevel — smoothed mic input level stream (0.0–1.0) for building a live level meter so users can confirm their mic is captured
• Example: full voice-call screen — connect/end, mute, live transcript bubbles, call state pill + timer, animated mic orb + input level meter, and friendly error UI mapped from MugibVoiceErrorCode
• Deps: upgrade web_socket_channel 2 → 3, record 5 → 6, http → 1.5, flutter_lints 4 → 5 (no breaking public API changes)
• Deps: drop unused permission_handler — microphone permission is handled by record.hasPermission(), so consumers no longer pull its heavier Android setup

1.0.10

• Voice: MugibTranscript.partial — server streams incremental STT; replace the last line for the same role when partial is true
• Voice: MugibVoiceClient.transcriptLines — ready-to-render transcript list (no manual partial handling in your UI)
• Voice: MugibTranscriptBuffer helper for custom transcript UIs
• Requires Mugib backend with accumulated voice transcript + partial WebSocket field

1.0.9

• Fix: configure VoIP audio session for speaker-mode voice chat (like ChatGPT/Gemini) — iOS voiceChat + defaultToSpeaker, Android VOICE_COMMUNICATION + MODE_IN_COMMUNICATION + speakerphone for hardware AEC
• Add audio_session dependency; mic stays open during agent speech (barge-in is enforced server-side via Portal allow_interruption, not in the SDK)

1.0.8

• Fix: stop clearing agent audio on state: listening (only interrupted clears playback)
• Fix: pause mic uplink while agent speaks when allow_interruption is false (reduces phone echo)
• Read allow_interruption from /token response (voice agent setting)

1.0.7

• Fix: voice userContext payload — send expect_context=1 on WebSocket URL so the server waits for the context frame (matches browser widget reliability)
• Fix: open WebSocket before PCM playback setup for faster context delivery
• Requires backend with voice payload/KB fixes (expect_context; KB via search_knowledge_base tool + prefetch)

1.0.6

• Docs: explain proactive triggers — configured in Portal (projects/{id}/triggers), optional read via getWidgetTriggers(); returns [] when none configured
• Docs: remove legacy mugib_voice package references — use mugib_sdk only
• Requires backend with fix for GET /api/v1/widget/triggers (200 + empty array, not 500)

1.0.5

• Docs: sync install version to ^1.0.4+ across repo guides
• Add @Deprecated isGeminiLive alias → isMugibVoiceAi (migration from 1.0.3)
• Remove stale gemini_session.dart from package tree

1.0.4

• Fix: SSE streaming no longer drops spaces between tokens — parse data: lines per the SSE spec (strip at most one optional separator space, not all leading whitespace). Fixes merged words in sendStream().

1.0.3

• Rebrand voice stack as Mugib Voice AI in docs and public API (remove Gemini naming)
• Rename GeminiVoiceSession → MugibVoiceSession (internal)
• Rename isGeminiLive → isMugibVoiceAi on agent/token models

1.0.2

• Docs: clarify SDK scope — app connects to Agent; KB/MCP/tools run server-side
• Docs: move handoff poll and tool approval buttons to optional Advanced section
• Docs: minimal quick-start example (send() + send("yes") for confirmations)
• Code comments: label poll() / confirmTool() as optional UI helpers

1.0.1

• Focus SDK on chat + voice + session payload; widget config/triggers read-only on [MugibClient]
• Remove KB/stats from main client facade (advanced via [MugibApiClient] / [MugibKbService])
• Add getWidgetTriggers() for /api/v1/widget/triggers

1.0.0

• Unified mugib_sdk package: chat + voice + KB + widget APIs
• Chat: sessions, messages (JSON + SSE), payload, handoff poll, tool confirmations, conversions, CSAT
• Voice: Mugib Voice AI calls (from former mugib_voice)
• KB: list / add / update / delete via tenant API
• Widget config, stats, metrics