capdebug 0.1.0 → 0.2.0

package/README.md

@@ -168,7 +168,45 @@ CapDebug.unobserveEvent('online');
 
 ---
 
-## Native Device Diagnostics
+## Native Telemetry & Diagnostics
+
+### Emitting Telemetry from Swift & Kotlin
+
+`capdebug` includes static native helpers so native plugins, background workers, or services can emit debug events directly into the WebView's CapDebug event bus:
+
+#### iOS (Swift)
+```swift
+import CapDebug
+
+CapDebugPlugin.emit(
+    type: "native.video.compress",
+    message: "Video compression completed",
+    data: ["outputBitrate": 1500000, "codec": "h264"],
+    level: "info",
+    duration: 342.5 // ms
+)
+```
+
+#### Android (Kotlin)
+```kotlin
+import com.capdebug.plugin.CapDebugPlugin
+import com.getcapacitor.JSObject
+
+val data = JSObject().apply {
+    put("file", "recording.m4a")
+    put("format", "aac")
+}
+
+CapDebugPlugin.emit(
+    type: "native.audio.transcode",
+    message: "Audio transcode finished",
+    data: data,
+    level: "info",
+    duration: 180L // ms
+)
+```
+
+### Querying Native Device Diagnostics in TypeScript
 
 When running in Capacitor iOS or Android (or web fallback), diagnostics are fetched on-demand when opening the **Device** tab or via programmatic calls:
 

package/android/src/main/java/com/capdebug/plugin/CapDebugPlugin.kt

@@ -20,6 +20,60 @@ import java.util.Locale
 @CapacitorPlugin(name = "CapDebug")
 class CapDebugPlugin : Plugin() {
 
+    override fun load() {
+        super.load()
+        activeBridge = bridge
+    }
+
+    companion object {
+        private var activeBridge: com.getcapacitor.Bridge? = null
+
+        /**
+         * Emits a telemetry or debug event directly from Android native code into CapDebug.
+         */
+        @JvmStatic
+        @JvmOverloads
+        fun emit(
+            type: String,
+            message: String? = null,
+            data: JSObject? = null,
+            level: String = "info",
+            duration: Long? = null,
+            source: String = "native",
+            bridge: com.getcapacitor.Bridge? = null
+        ) {
+            val targetBridge = bridge ?: activeBridge ?: return
+
+            // Zero-overhead guard: No-op in production release builds
+            val isDebuggable = try {
+                val context = targetBridge.context
+                (context.applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE) != 0
+            } catch (e: Exception) {
+                false
+            }
+
+            if (!isDebuggable) {
+                return
+            }
+
+            val payload = JSObject().apply {
+                put("source", source)
+                put("platform", "android")
+                put("type", type)
+                put("level", level)
+                message?.let { put("message", it) }
+                put("timestamp", System.currentTimeMillis())
+                data?.let { put("data", it) }
+                duration?.let { put("duration", it) }
+            }
+
+            val js = "window.dispatchEvent(new CustomEvent('capdebug', { detail: $payload }));"
+            targetBridge.webView?.post {
+                targetBridge.webView?.evaluateJavascript(js, null)
+            }
+        }
+    }
+
     @PluginMethod
     fun getDeviceInfo(call: PluginCall) {
         try {