beekon_flutter 0.4.0

Flutter plugin for the Beekon location SDK (Android + iOS).

Changelog

All notable changes to beekon_flutter are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

0.4.0 - 2026-07-08

Wraps native 0.4.0. Adds the explicit permission-request layer (permission-request-flow-v1). Additive; no breaking changes.

Added

• Explicit permission-request API — Beekon.requestPermission(permission), Beekon.requestNextNeededPermission() (requests the first required-but-unsatisfied permission in the doctor list, or returns null), and Beekon.openSettings(permission), with the new PermissionRequestResult and PermissionRequestOutcome types. The SDK still never requests permissions implicitly — these run only when you call them, in-context; the read-only getRequiredPermissions() doctor is unchanged. Coexists with permission_handler.

0.3.2 - 2026-07-07

Still wraps native 0.3.0 — a wrapper-side reconciliation pass against the native 0.3.0 surface. Additive; no breaking changes.

Added

• Location battery telemetry — Location now surfaces batteryPercent, isCharging, and powerSaveMode (each null when the platform did not report a value), mirroring the native Location.
• Typed GeofencesManagedByServer — thrown by addGeofences / removeGeofences in cloud mode, where geofences are server-owned (previously surfaced as a raw PlatformException).
• Typed InvalidUserId — thrown by setUserId when the id contains control characters or exceeds 256 UTF-8 bytes. Now consistent across iOS and Android (Android's native IllegalArgumentException is mapped to the same typed error).

Changed

• Error codes now map to the same typed BeekonException on both platforms for every native error, closing a prior iOS/Android skew on setUserId failures.

0.3.1 - 2026-07-07

Changed

• Internal — renamed the plugin's Android package in.wayq.beekon_flutter → com.getbeekon.flutter (and the example app to com.getbeekon.flutter.example) for brand consistency with the native com.getbeekon.sdk. Implementation detail only — the Dart API and the beekon_flutter package name are unchanged, and Flutter regenerates each host's plugin registrant on build. Still wraps native 0.3.0.

0.3.0 - 2026-07-07

Wraps native SDK 0.3.0. Breaking (pre-1.0) — the native public API was reshaped.

Changed

• BREAKING — wraps native SDK 0.3.0. Requires Android io.github.beekonlabs:beekon:0.3.0 (Kotlin package com.getbeekon.sdk) and iOS BeekonKit 0.3.0.
• StopReason: cloudModeUnavailable removed, backgroundStartDenied added — a background foreground-service start was denied; the session is kept and a later resume recovers it. Mirrors the native reshape.
• Cloud endpoint now derives https://api.<cell>.getbeekon.com from the cell-aware project key (bkproj_<cell>_<secret>) — there is no baked-in default endpoint.

Fixed

• setUserId and removeGeofences now surface native validation / GeofencesManagedByServer errors through the normal error channel (both became throwing in native 0.3.0).

0.2.0 - 2026-07-02

Changed

• BREAKING — BeekonConfig is now a sealed three-arm type cloud / custom / local, replacing the previous two-arm cloud / selfManaged. Build it with BeekonConfig.cloud(...), BeekonConfig.custom(sync: ...), or BeekonConfig.local(...). The old BeekonConfig.selfManaged(...) constructor is removed: a selfManaged with a sync becomes custom; without a sync it becomes local.
• BREAKING — tracking parameters now nest under TrackingConfig. The tracking knobs (minTimeBetweenLocationsSeconds, minDistanceBetweenLocationsMeters, accuracyMode, whenStationary, stationaryRadiusMeters, detectActivity) move off the config constructors into a TrackingConfig value passed as tracking: on the custom / local arms.
• Native SDK pins bumped to 0.2.0 — Android (io.github.beekonlabs:beekon) and iOS (beekon-ios-binary) now track 0.2.0.

Added

• Beekon.setUserId(String?) — sets the user id sent top-level (user_id) in every sync upload envelope and used for Beekon Cloud MTU metering. extras is now fully opaque; use setUserId for the metered user identity.

Requires the native SDKs ≥ 0.2.0.

0.1.3 - 2026-06-28

Changed

• Native SDK pins bumped to 0.1.3 — Android (io.github.beekonlabs:beekon) now tracks 0.1.3.

Fixed

• Android activity type no longer stuck at unknown for moving fixes (native fix in beekon 0.1.3). The Android activity type was sourced from the Activity Transition API (deltas only) plus a one-shot prime that was discarded after the first result, and the engine reset the detected activity on every stationary→active restart — so a device already moving when the detector restarted (common under StationaryMode.pauseWithCheckIns, where a stationary process can die and resume cold on a geofence exit) reported unknown for the entire trip. 0.1.3 keeps the detected activity across restarts and continuously re-acquires the current activity while moving (iOS CMMotionActivityManager parity), gated to Active mode so idle battery is unchanged. iOS was unaffected. See the beekon-android CHANGELOG for details.

0.1.2 - 2026-06-28

Added

• Per-geofence local notifications — BeekonGeofence now takes an optional notification: GeofenceNotification(onEnter?, onExit?, delivery). Each direction's NotificationContent carries title / body (required), importance (NotificationImportance, default high), deepLink, and a data string map. With delivery set to NotificationDelivery.local (the default), the SDK renders the OS notification on the device at crossing time — it works offline and even when the app has been killed. NotificationDelivery.cloud is reserved (cloud mode only, not yet implemented). In self-managed mode delivery must be local; cloud mode accepts local or cloud. Adds the GeofenceNotification, NotificationContent, NotificationDelivery, and NotificationImportance types. Requires the native SDKs ≥ 0.1.2.
• getRequiredPermissions() — the permission "doctor". Returns the OS permissions the current configuration needs as a List<PermissionRequirement> (permission: BeekonPermission — location / backgroundLocation / activityRecognition / notifications; importance: PermissionImportance — required / recommended; satisfied against the live grant; and a human-readable rationale). The config-aware companion to the location-only getPermissionStatus() — call it after configure(). Read-only and never prompts; Beekon still never requests permission, and start() does not preflight. Requires the native SDKs ≥ 0.1.2.

0.1.1 - 2026-06-23

Changed

• Native SDK pins bumped to 0.1.1 — Android Maven coordinate and iOS SwiftPM binary now track BeekonKit / beekon 0.1.1 (device control plane, build-time license gate, and related native fixes since 0.1.0).

Added

• Build-gate product id — setWrapperInfo now declares the Flutter wrapper product id for build-time license enforcement (build-gate-v1).

0.1.0 - 2026-06-15

Changed

• Moved to the beekonlabs GitHub org. The Android native dependency coordinate is now io.github.beekonlabs:beekon (was io.github.wayqteam:beekon), and the iOS binary/source repos are under github.com/beekonlabs. This is internal to the plugin — the pub.dev package name (beekon_flutter) is unchanged and no consumer code changes are required.

Added

• getPermissionStatus() — read-only permission query. Returns the current location grant as a PermissionStatus (level: notDetermined / denied / restricted / foreground / background; nullable accuracy: full / reduced) for pre-start checks, without ever prompting. Adds the PermissionLevel / PermissionAccuracy enums and isAuthorized / canTrackInBackground getters. Beekon still never requests permission — the app owns that; during tracking, loss surfaces on state. On Android, "not yet asked" and "denied" both report notDetermined; restricted is iOS-only. Requires native SDKs ≥ the release that adds the API.

0.0.9 - 2026-06-14

Added

• Beekon Cloud mode (cloud-mode-v1): BeekonConfig.cloud({projectKey, endpoint?, notification?, logLevel}) — a bkproj_ project key with server-owned config, geofences and license; default endpoint https://api.getbeekon.com. Adds the BeekonMode enum, StopReason.cloudModeUnavailable, and InvalidConfiguration. Requires native SDKs ≥ 0.0.9.
• Diagnostic logging (log-format-v1): Beekon.getLog/exportLog/clearLog/ setLogLevel/log, the logs Stream<LogEntry>, forwardLogsToConsole, and the LogEntry / LogLevel types. Requires native SDKs ≥ 0.0.9.
• SyncConfig.syncThreshold (beekon#20): pending-fix count that triggers an early upload of regular fixes ahead of the intervalSeconds schedule (not subject to the Android ~15 min WorkManager floor). 0 (the default) leaves regular fixes to the schedule. Independent of this setting, a geofence event and a session stop with pending fixes always flush immediately while sync is configured. Requires the native SDKs ≥ 0.0.9.

Changed

• BREAKING: BeekonConfig is now a sealed two-arm type built via BeekonConfig.cloud(...) / BeekonConfig.selfManaged(...); the unnamed const BeekonConfig({...}) constructor was removed. Tracking params, sync, and licenseKey now live only on the selfManaged arm.

0.0.8

Built against the native 0.0.8 API; requires native ≥ 0.0.8 at runtime. No wrapper API changes.

Changed

• Native pins bumped to 0.0.8 (Maven io.github.beekonlabs:beekon, SwiftPM beekon-ios-binary). 0.0.8 embeds the production ES256 license verification keyset, so genuine license-format-v1 tokens resolve to Licensed / Evaluation on-device, and hardens wire/license conformance. The license surface remains a pure pass-through — no validation in the wrapper.

0.0.7

Built against the native 0.0.7 API; requires native ≥ 0.0.7 at runtime.

Added

• License surface (license-format-v1) — a pure pass-through to the native verifier; the wrapper performs no validation of its own.
  • BeekonConfig.licenseKey — supply a license token (a license-format-v1 JWS). The highest-priority channel, overriding the Android manifest / iOS Info.plist value; null/blank means unset. Safe to commit to source control (app-id- and product-bound).
  • Beekon.licenseStatus() (one-shot) and Beekon.licenseStatusUpdates (replay-1 stream) expose the current platform's status: sealed LicenseStatus (NotDetermined / Licensed(tier, entitlements) / Evaluation / Expired / UpdateEntitlementLapsed / Invalid(reason)) plus LicenseInvalidReason. Purely observational — no status ever blocks, degrades, or delays the SDK; Android and iOS may legally diverge for the same app.
  • The plugin identifies itself to the verifier as the flutter product during native registration.
• Native pins bumped to 0.0.7 (Maven io.github.beekonlabs:beekon, SwiftPM beekon-ios-binary).

0.0.6

Built against the native 0.0.6 API; requires native ≥ 0.0.6 at runtime.

Added

• Native token refresh — SyncConfig.auth (AuthConfig) lets the SDK attach and natively refresh the upload access token, proactively before expiry and reactively on 401/403, in the background and on a cold launch. Rotated credentials surface on the new Beekon.authChanges stream (AuthTokens). Adds AuthStrategy, AuthBodyFormat, and AuthResponseMapping. null keeps the legacy static-headers behaviour.
• On-demand fix — getCurrentLocation({timeout, accuracy}) returns a single fresh location (or null on timeout), independent of tracking; throws the new LocationUnavailable (LocationUnavailableReason) on a precondition failure.
• Restored NotificationConfig.smallIcon — an optional Android foreground-service status-bar icon (drawable/mipmap resource name; null keeps the host launcher icon). Android-only; iOS ignores it. Reverses the 0.0.5 "smallIcon removed" note.

0.0.5

Full rebuild against the native 0.0.5 API — a breaking, no-backward-compat release (Beekon is pre-1.0). The Dart surface is now a faithful 1:1 mirror of the native Beekon (Android) / Beekon.shared (iOS).

Added

• Server sync: SyncConfig on BeekonConfig, plus sync(), setExtras(), pendingUploadCount(), and the syncStatus stream (SyncIdle/SyncPending/SyncFailed).
• Geofencing: addGeofences() / removeGeofences() / listGeofences() and the geofenceEvents stream (BeekonGeofence, GeofenceEvent, Transition).
• Richer config: accuracyMode, whenStationary, stationaryRadiusMeters, detectActivity (AccuracyMode, StationaryMode).
• Richer Location: id, quality, trigger, motion, activity, isMock (LocationQuality, LocationTrigger, MotionState, ActivityType).
• deleteLocations({before}), resumeIfNeeded(), and StopReason.locationUnavailable.

Changed

• intervalSeconds → minTimeBetweenLocationsSeconds; distanceMeters → minDistanceBetweenLocationsMeters.
• history(from, to) → getLocations(from: , to: ).
• AndroidNotification{title,text,smallIcon} → NotificationConfig{title,text} (Android-only; smallIcon removed).
• iOS registers the background-refresh task and installs cold-launch resume hooks during plugin registration; Android no longer calls initialize() (the SDK auto-initializes via AndroidX Startup).
• Native pins bumped to 0.0.5 (Maven io.github.beekonlabs:beekon, SwiftPM beekon-ios-binary).

Removed

• PermissionDenied / LocationServicesDisabled exceptions — permission and service problems now surface only on state as Stopped(reason). The only thrown errors are StorageException and InvalidGeofence.

0.0.3

First synchronized release across all four registries (Maven Central, beekonlabs/beekon-ios-binary xcframework, pub.dev, npm). The native floors bumped: iOS BeekonKit.xcframework now ships with importable .swiftinterface files and keeps GRDB out of the public ABI; the Android AAR's Kotlin metadata is at 2.1 so Kotlin 2.1.x/2.2.x consumers can read it without -Xskip-metadata-version-check. Location accuracy/speed/bearing/altitude are now nullable to faithfully represent providers that don't deliver them.

The 0.0.2 slot was used as a release dry-run — only the Android AAR landed on Maven Central (the registry is immutable). pub.dev sees this as a non-incremental jump from 0.0.1 to 0.0.3; that is intentional.

0.0.1

Initial release.

Added

• Flutter plugin bridging the native Beekon location SDKs (Android .aar, iOS BeekonKit xcframework) into Dart.
• Public API mirroring the native surface: Beekon.instance.initialize / configure / start / stop / shutdown, state and positions streams, history(from, to).
• Sealed BeekonState (Idle/Starting/Tracking/Paused/Stopped) and BeekonException types for exhaustive Dart 3 pattern matching.
• Position (lat/lng/accuracy/speed/bearing/altitude/timestamp) and BeekonConfig (preset, Duration interval override, AndroidNotification for the foreground service).
• Pigeon-generated type-safe channels (BeekonHostApi + event channels for state and positions).
• Example app demonstrating live tracking, state transitions, and history queries.
• iOS distribution via SwiftPM (binary target on beekonlabs/beekon-ios-binary); requires Flutter 3.44+ or Flutter 3.32–3.43 with flutter config --enable-swift-package-manager.
• Android distribution via Maven Central (io.github.beekonlabs:beekon).