From 117caa912225bfc226fdef8fd7330bc6633c96dc Mon Sep 17 00:00:00 2001
From: beetzung <bee.tzung.jr@gmail.com>
Date: Sat, 28 Feb 2026 16:58:55 +0100
Subject: [PATCH] Add SDK service contracts for core infrastructure.

Introduce interface-only service APIs and feature models for auth, device, settings, notifications, connectivity, and telemetry to scaffold implementation without backend-specific naming.

Made-with: Cursor
---
 .../kotlin/org/db3/airmq/sdk/auth/AuthService.kt  | 10 ++++++++++
 .../kotlin/org/db3/airmq/sdk/auth/model/Auth.kt   |  8 ++++++++
 .../airmq/sdk/connectivity/ConnectivityService.kt | 11 +++++++++++
 .../airmq/sdk/connectivity/model/Connectivity.kt  |  7 +++++++
 .../org/db3/airmq/sdk/device/DeviceService.kt     | 11 +++++++++++
 .../org/db3/airmq/sdk/device/model/Device.kt      | 10 ++++++++++
 .../sdk/notifications/NotificationService.kt      | 10 ++++++++++
 .../airmq/sdk/notifications/model/Notification.kt |  6 ++++++
 .../org/db3/airmq/sdk/settings/SettingsService.kt | 10 ++++++++++
 .../org/db3/airmq/sdk/settings/model/Settings.kt  |  8 ++++++++
 .../db3/airmq/sdk/telemetry/TelemetryService.kt   | 15 +++++++++++++++
 .../db3/airmq/sdk/telemetry/model/Telemetry.kt    |  8 ++++++++
 12 files changed, 114 insertions(+)
 create mode 100644 sdk/src/main/kotlin/org/db3/airmq/sdk/auth/AuthService.kt
 create mode 100644 sdk/src/main/kotlin/org/db3/airmq/sdk/auth/model/Auth.kt
 create mode 100644 sdk/src/main/kotlin/org/db3/airmq/sdk/connectivity/ConnectivityService.kt
 create mode 100644 sdk/src/main/kotlin/org/db3/airmq/sdk/connectivity/model/Connectivity.kt
 create mode 100644 sdk/src/main/kotlin/org/db3/airmq/sdk/device/DeviceService.kt
 create mode 100644 sdk/src/main/kotlin/org/db3/airmq/sdk/device/model/Device.kt
 create mode 100644 sdk/src/main/kotlin/org/db3/airmq/sdk/notifications/NotificationService.kt
 create mode 100644 sdk/src/main/kotlin/org/db3/airmq/sdk/notifications/model/Notification.kt
 create mode 100644 sdk/src/main/kotlin/org/db3/airmq/sdk/settings/SettingsService.kt
 create mode 100644 sdk/src/main/kotlin/org/db3/airmq/sdk/settings/model/Settings.kt
 create mode 100644 sdk/src/main/kotlin/org/db3/airmq/sdk/telemetry/TelemetryService.kt
 create mode 100644 sdk/src/main/kotlin/org/db3/airmq/sdk/telemetry/model/Telemetry.kt

diff --git a/sdk/src/main/kotlin/org/db3/airmq/sdk/auth/AuthService.kt b/sdk/src/main/kotlin/org/db3/airmq/sdk/auth/AuthService.kt
new file mode 100644
index 0000000..4723178
--- /dev/null
+++ b/sdk/src/main/kotlin/org/db3/airmq/sdk/auth/AuthService.kt
@@ -0,0 +1,10 @@
+package org.db3.airmq.sdk.auth
+
+import org.db3.airmq.sdk.auth.model.Auth
+
+interface AuthService {
+    suspend fun getCurrentSession(): Auth?
+    suspend fun isAuthenticated(): Boolean
+    suspend fun signIn(provider: String, token: String? = null): Result<Auth>
+    suspend fun signOut(): Result<Unit>
+}
diff --git a/sdk/src/main/kotlin/org/db3/airmq/sdk/auth/model/Auth.kt b/sdk/src/main/kotlin/org/db3/airmq/sdk/auth/model/Auth.kt
new file mode 100644
index 0000000..3d1ff5c
--- /dev/null
+++ b/sdk/src/main/kotlin/org/db3/airmq/sdk/auth/model/Auth.kt
@@ -0,0 +1,8 @@
+package org.db3.airmq.sdk.auth.model
+
+data class Auth(
+    val userId: String,
+    val email: String?,
+    val displayName: String?,
+    val isAuthenticated: Boolean
+)
diff --git a/sdk/src/main/kotlin/org/db3/airmq/sdk/connectivity/ConnectivityService.kt b/sdk/src/main/kotlin/org/db3/airmq/sdk/connectivity/ConnectivityService.kt
new file mode 100644
index 0000000..cde4341
--- /dev/null
+++ b/sdk/src/main/kotlin/org/db3/airmq/sdk/connectivity/ConnectivityService.kt
@@ -0,0 +1,11 @@
+package org.db3.airmq.sdk.connectivity
+
+import org.db3.airmq.sdk.connectivity.model.Connectivity
+
+interface ConnectivityService {
+    suspend fun getConnectivity(): Connectivity
+    suspend fun isInternetAvailable(): Boolean
+    suspend fun scanNetworks(): List<String>
+    suspend fun connect(ssid: String, password: String): Result<Unit>
+    suspend fun disconnect(ssid: String): Result<Unit>
+}
diff --git a/sdk/src/main/kotlin/org/db3/airmq/sdk/connectivity/model/Connectivity.kt b/sdk/src/main/kotlin/org/db3/airmq/sdk/connectivity/model/Connectivity.kt
new file mode 100644
index 0000000..4dc6b24
--- /dev/null
+++ b/sdk/src/main/kotlin/org/db3/airmq/sdk/connectivity/model/Connectivity.kt
@@ -0,0 +1,7 @@
+package org.db3.airmq.sdk.connectivity.model
+
+data class Connectivity(
+    val isWifiEnabled: Boolean,
+    val isConnected: Boolean,
+    val connectedSsid: String?
+)
diff --git a/sdk/src/main/kotlin/org/db3/airmq/sdk/device/DeviceService.kt b/sdk/src/main/kotlin/org/db3/airmq/sdk/device/DeviceService.kt
new file mode 100644
index 0000000..d4426af
--- /dev/null
+++ b/sdk/src/main/kotlin/org/db3/airmq/sdk/device/DeviceService.kt
@@ -0,0 +1,11 @@
+package org.db3.airmq.sdk.device
+
+import org.db3.airmq.sdk.device.model.Device
+
+interface DeviceService {
+    suspend fun fetchDevices(): List<Device>
+    suspend fun fetchDevice(deviceId: String): Device?
+    suspend fun saveDevice(device: Device): Result<Device>
+    suspend fun deleteDevice(deviceId: String): Result<Unit>
+    suspend fun updateDeviceLocation(deviceId: String, latitude: Double, longitude: Double): Result<Unit>
+}
diff --git a/sdk/src/main/kotlin/org/db3/airmq/sdk/device/model/Device.kt b/sdk/src/main/kotlin/org/db3/airmq/sdk/device/model/Device.kt
new file mode 100644
index 0000000..be64521
--- /dev/null
+++ b/sdk/src/main/kotlin/org/db3/airmq/sdk/device/model/Device.kt
@@ -0,0 +1,10 @@
+package org.db3.airmq.sdk.device.model
+
+data class Device(
+    val id: String,
+    val name: String,
+    val model: String?,
+    val city: String?,
+    val isOnline: Boolean,
+    val lastSeenEpochMs: Long?
+)
diff --git a/sdk/src/main/kotlin/org/db3/airmq/sdk/notifications/NotificationService.kt b/sdk/src/main/kotlin/org/db3/airmq/sdk/notifications/NotificationService.kt
new file mode 100644
index 0000000..b1ad8d3
--- /dev/null
+++ b/sdk/src/main/kotlin/org/db3/airmq/sdk/notifications/NotificationService.kt
@@ -0,0 +1,10 @@
+package org.db3.airmq.sdk.notifications
+
+import org.db3.airmq.sdk.notifications.model.Notification
+
+interface NotificationService {
+    suspend fun fetchNotificationSettings(): Notification
+    suspend fun updateNotificationSettings(settings: Notification): Result<Notification>
+    suspend fun subscribeToTopic(topic: String): Result<Unit>
+    suspend fun unsubscribeFromTopic(topic: String): Result<Unit>
+}
diff --git a/sdk/src/main/kotlin/org/db3/airmq/sdk/notifications/model/Notification.kt b/sdk/src/main/kotlin/org/db3/airmq/sdk/notifications/model/Notification.kt
new file mode 100644
index 0000000..cd31849
--- /dev/null
+++ b/sdk/src/main/kotlin/org/db3/airmq/sdk/notifications/model/Notification.kt
@@ -0,0 +1,6 @@
+package org.db3.airmq.sdk.notifications.model
+
+data class Notification(
+    val deviceStatusEnabled: Boolean,
+    val subscribedTopics: List<String>
+)
diff --git a/sdk/src/main/kotlin/org/db3/airmq/sdk/settings/SettingsService.kt b/sdk/src/main/kotlin/org/db3/airmq/sdk/settings/SettingsService.kt
new file mode 100644
index 0000000..f68cb46
--- /dev/null
+++ b/sdk/src/main/kotlin/org/db3/airmq/sdk/settings/SettingsService.kt
@@ -0,0 +1,10 @@
+package org.db3.airmq.sdk.settings
+
+import org.db3.airmq.sdk.settings.model.Settings
+
+interface SettingsService {
+    suspend fun fetchSettings(): Settings
+    suspend fun updateSettings(settings: Settings): Result<Settings>
+    suspend fun setAdvancedEnabled(enabled: Boolean): Result<Unit>
+    suspend fun setOfflineDevicesVisible(visible: Boolean): Result<Unit>
+}
diff --git a/sdk/src/main/kotlin/org/db3/airmq/sdk/settings/model/Settings.kt b/sdk/src/main/kotlin/org/db3/airmq/sdk/settings/model/Settings.kt
new file mode 100644
index 0000000..1a5baa7
--- /dev/null
+++ b/sdk/src/main/kotlin/org/db3/airmq/sdk/settings/model/Settings.kt
@@ -0,0 +1,8 @@
+package org.db3.airmq.sdk.settings.model
+
+data class Settings(
+    val city: String?,
+    val showOfflineDevices: Boolean,
+    val advancedEnabled: Boolean,
+    val deviceStatusNotificationsEnabled: Boolean
+)
diff --git a/sdk/src/main/kotlin/org/db3/airmq/sdk/telemetry/TelemetryService.kt b/sdk/src/main/kotlin/org/db3/airmq/sdk/telemetry/TelemetryService.kt
new file mode 100644
index 0000000..b7341e8
--- /dev/null
+++ b/sdk/src/main/kotlin/org/db3/airmq/sdk/telemetry/TelemetryService.kt
@@ -0,0 +1,15 @@
+package org.db3.airmq.sdk.telemetry
+
+import org.db3.airmq.sdk.telemetry.model.Telemetry
+
+interface TelemetryService {
+    suspend fun fetchLatest(deviceId: String, metric: String): Telemetry?
+    suspend fun fetchHistory(
+        deviceId: String,
+        metric: String,
+        fromEpochMs: Long,
+        toEpochMs: Long
+    ): List<Telemetry>
+
+    suspend fun fetchLatestForDevices(deviceIds: List<String>, metric: String): List<Telemetry>
+}
diff --git a/sdk/src/main/kotlin/org/db3/airmq/sdk/telemetry/model/Telemetry.kt b/sdk/src/main/kotlin/org/db3/airmq/sdk/telemetry/model/Telemetry.kt
new file mode 100644
index 0000000..93fe47f
--- /dev/null
+++ b/sdk/src/main/kotlin/org/db3/airmq/sdk/telemetry/model/Telemetry.kt
@@ -0,0 +1,8 @@
+package org.db3.airmq.sdk.telemetry.model
+
+data class Telemetry(
+    val deviceId: String,
+    val metric: String,
+    val value: Double,
+    val timestampEpochMs: Long
+)