capacitor-pica-network-logger 0.2.4 → 0.2.6

package/README.md

@@ -4,45 +4,38 @@
 
 # capacitor-pica-network-logger
 
-Capacitor HTTP inspector with debug-only native capture and a JS wrapper that mirrors `@capacitor/http`.
+A Capacitor plugin for logging and inspecting HTTP requests with native inspector UIs on iOS and Android.
 
 ![Network logger walkthrough](assets/pica_network_logger.gif)
 
-## Tech stack
-
-- Capacitor 7
-- Swift (URLProtocol logging on iOS)
-- Kotlin (HttpURLConnection reflection logging on Android)
-- TypeScript wrapper for `@capacitor/http`
-
 ## Features
 
-- Debug-only request/response logging
-- Native inspector UI (standalone Activity/UIViewController)
+- Request/response pair logging with automatic correlation
+- Native inspector UI on iOS (UIKit) and Android (Jetpack Compose + Material 3)
 - Body text search with highlighting in the inspector
-- Persistent log storage across inspector sessions
-- Notifications to open inspector
-- Redaction + max body size from Capacitor config
-- cURL/JSON/HAR exports + copy/share
-- Save cURL/JSON/HAR locally
-- Copy all logs as HAR
+- Persistent log storage (SQLite) across inspector sessions
+- Responsive Android layout (compact, medium, expanded breakpoints)
+- Dark/light theme toggle
+- Configurable header and JSON body field redaction
+- Configurable max body size with truncation
+- Local notifications on each completed request (tap to open inspector)
+- Export as cURL, plain text, or HAR 1.2
+- No-op on web -- safe to import in any environment
 
 See the [Changelog](CHANGELOG.md) for a full history of changes.
 
-## Project layout
+## Platform requirements
 
-- `src/`: JS wrapper and plugin typings
-- `android/`: Capacitor Android plugin + reflection hook
-- `ios/`: Capacitor iOS plugin + URLProtocol logger
-- `examples/sample-app/`: demo app
+| Platform | Minimum version |
+|---|---|
+| Capacitor | 7+ |
+| iOS | 14.0 |
+| Android | API 23 (Android 6.0) |
 
 ## Installation
 
 ```bash
 npm install capacitor-pica-network-logger
-```
-
-```bash
 npx cap sync
 ```
 
@@ -53,71 +46,86 @@ Add to your app's `capacitor.config.ts`:
 ```ts
 plugins: {
   PicaNetworkLogger: {
-    enabled: true,
-    maxBodySize: 131072,
-    notify: true,
-    redactHeaders: ["authorization", "cookie"],
-    redactJsonFields: ["password", "token"]
+    maxBodySize: 131072,        // max chars per body (default: 128 KB)
+    notify: true,               // show notifications per request (default: true)
+    redactHeaders: ["authorization", "cookie"],   // header names to redact (default: none)
+    redactJsonFields: ["password", "token"]        // JSON field names to redact (default: none)
   }
 }
 ```
 
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `maxBodySize` | `number` | `131072` | Maximum characters stored per request/response body. Truncated beyond this. |
+| `notify` | `boolean` | `true` | Post a local notification for each completed request. On Android 13+ requests `POST_NOTIFICATIONS` permission. |
+| `redactHeaders` | `string[]` | `[]` | Header names (case-insensitive) whose values are replaced with `[REDACTED]`. |
+| `redactJsonFields` | `string[]` | `[]` | Top-level JSON body field names (case-insensitive) whose values are replaced with `[REDACTED]`. |
+
 ## Usage
 
-Import the wrapper and use it in place of `@capacitor/http`:
+The plugin exposes three methods: `startRequest`, `finishRequest`, and `openInspector`. Use your own HTTP client (e.g. `fetch`) and wrap calls with the logging methods:
 
 ```ts
-import { CapacitorHttp, PicaNetworkLogger } from 'capacitor-pica-network-logger';
+import { PicaNetworkLogger } from 'capacitor-pica-network-logger';
+
+// 1. Log the start of a request
+const { id } = await PicaNetworkLogger.startRequest({
+  method: 'GET',
+  url: 'https://jsonplaceholder.typicode.com/posts/1',
+  headers: { 'Accept': 'application/json' },
+});
+
+// 2. Make the actual HTTP call
+const response = await fetch('https://jsonplaceholder.typicode.com/posts/1');
+const body = await response.text();
+
+// 3. Log the completion
+await PicaNetworkLogger.finishRequest({
+  id,
+  status: response.status,
+  headers: Object.fromEntries(response.headers.entries()),
+  body,
+});
 
-await CapacitorHttp.get({ url: 'https://example.com' });
+// 4. Open the inspector UI
 await PicaNetworkLogger.openInspector();
 ```
 
-If you want to keep call sites unchanged, alias `@capacitor/http` to this package in your bundler.
+### API
 
-### Minimal changes (existing `@capacitor/http` usage)
+| Method | Signature | Description |
+|---|---|---|
+| `startRequest` | `(options: StartRequestOptions) => Promise<{ id: string }>` | Log the start of a request. Returns an `id` for correlation. |
+| `finishRequest` | `(options: FinishRequestOptions) => Promise<void>` | Log the completion of a request (status, headers, body, error). |
+| `openInspector` | `() => Promise<void>` | Open the native inspector UI. |
 
-If you already use `@capacitor/http`, you can keep your code as-is by adding a module alias so imports resolve to this package.
-
-**Vite**
+### Types
 
 ```ts
-// vite.config.ts
-import { defineConfig } from 'vite';
-
-export default defineConfig({
-  resolve: {
-    alias: {
-      '@capacitor/http': 'capacitor-pica-network-logger'
-    }
-  }
-});
-```
-
-**Webpack**
+interface StartRequestOptions {
+  method: string;
+  url: string;
+  headers?: Record<string, string>;
+  body?: unknown;
+}
 
-```js
-// webpack.config.js
-module.exports = {
-  resolve: {
-    alias: {
-      '@capacitor/http': 'capacitor-pica-network-logger'
-    }
-  }
-};
+interface FinishRequestOptions {
+  id: string;
+  status?: number;
+  headers?: Record<string, string>;
+  body?: unknown;
+  error?: string;
+}
 ```
 
-**TypeScript paths (editor/typecheck)**
+## Project layout
 
-```json
-// tsconfig.json
-{
-  "compilerOptions": {
-    "paths": {
-      "@capacitor/http": ["node_modules/capacitor-pica-network-logger"]
-    }
-  }
-}
+```
+src/            TypeScript plugin registration and types
+ios/Plugin/     Swift iOS plugin (UIKit inspector, SQLite storage, notifications)
+android/        Kotlin Android plugin (Compose inspector, SQLite storage, notifications)
+examples/       Sample Capacitor app for manual testing
+scripts/        Release script
 ```
 
 ## Build
@@ -137,15 +145,26 @@ npm install
 npm run dev
 ```
 
-## Modifications
+Run on device:
+
+```bash
+# iOS
+cd examples/sample-app && npm run build && npx cap sync ios && npx cap run ios
+
+# Android
+cd examples/sample-app && npm run build && npx cap sync android && npx cap run android
+```
+
+## Release
+
+```bash
+npm run release              # prompts for patch/minor/major
+npm run release -- patch     # patch bump
+npm run release -- 1.0.0     # explicit version
+```
 
-- JS wrapper: `src/httpWithLogging.ts`
-- Android hook: `android/src/main/java/com/linakis/capacitorpicanetworklogger/ReflectionHook.kt`
-- iOS logger: `ios/Plugin/InspectorURLProtocol.swift`
-- UI (iOS): `ios/Plugin/InspectorViewController.swift`
-- UI (Android): `android/src/main/java/com/linakis/capacitorpicanetworklogger/InspectorActivity.kt`
+The release script updates `CHANGELOG.md`, bumps `package.json`, builds, commits, tags, pushes, publishes to npm, and creates a GitHub Release (if `gh` CLI is available).
 
-## Notes
+## License
 
-- Android reflection hook uses `URLStreamHandlerFactory` and will fail if another library set one first.
-- The JS wrapper is still authoritative on Android; reflection logging is best-effort.
+MIT

package/android/src/main/java/com/linakis/capacitorpicanetworklogger/LogRepositoryStore.kt

@@ -6,8 +6,8 @@ object LogRepositoryStore {
     private var repository: LogRepository? = null
     private var appContext: android.content.Context? = null
     private var maxBodySize: Int = 131072
-    private var redactHeaders: Set<String> = setOf("authorization", "cookie")
-    private var redactJsonFields: Set<String> = setOf("password", "token")
+    private var redactHeaders: Set<String> = emptySet()
+    private var redactJsonFields: Set<String> = emptySet()
     private var notifyEnabled: Boolean = true
     private val requestStartTs: MutableMap<String, Long> = mutableMapOf()
 
@@ -78,9 +78,15 @@ object LogRepositoryStore {
         data.put("id", id)
         if (status != null) data.put("status", status)
         data.put("headers", headers?.redactedHeaders()?.toJsObject())
-        val truncated = truncate(body?.redactJson())
-        data.put("responseBody", truncated.value)
-        data.put("responseBodyTruncated", truncated.truncated)
+        val contentType = contentType(headers)
+        if (body != null && isBinaryContentType(contentType)) {
+            data.put("responseBody", binaryPlaceholder(contentType))
+            data.put("responseBodyTruncated", false)
+        } else {
+            val truncated = truncate(body?.redactJson())
+            data.put("responseBody", truncated.value)
+            data.put("responseBodyTruncated", truncated.truncated)
+        }
         if (error != null) data.put("error", error)
         if (protocol != null) data.put("protocol", protocol)
         if (ssl != null) data.put("ssl", ssl)
@@ -121,6 +127,36 @@ object LogRepositoryStore {
     }
 
     private data class Truncated(val value: String?, val truncated: Boolean)
+
+    private fun contentType(headers: Map<String, String>?): String? {
+        if (headers == null) return null
+        for ((key, value) in headers) {
+            if (key.lowercase() == "content-type") return value.lowercase()
+        }
+        return null
+    }
+
+    private val binaryPrefixes = listOf(
+        "image/", "video/", "audio/", "application/octet-stream",
+        "application/pdf", "application/zip", "application/gzip",
+        "font/", "application/vnd.", "application/x-protobuf"
+    )
+
+    private fun isBinaryContentType(contentType: String?): Boolean {
+        val ct = contentType ?: return false
+        return binaryPrefixes.any { ct.startsWith(it) }
+    }
+
+    private fun binaryPlaceholder(contentType: String?): String {
+        val ct = contentType ?: "unknown"
+        val mediaType = when {
+            ct.startsWith("image/") -> "Image"
+            ct.startsWith("video/") -> "Video"
+            ct.startsWith("audio/") -> "Audio"
+            else -> "Binary"
+        }
+        return "[$mediaType preview not yet supported ($ct)]"
+    }
 }
 
 private fun Map<String, String>.toJsObject(): JSObject {

package/android/src/main/java/com/linakis/capacitorpicanetworklogger/LoggerConfigProvider.kt

@@ -7,6 +7,7 @@ class LoggerConfigProvider {
     fun getConfig(plugin: Plugin): JSObject {
         val config = plugin.bridge.config.getPluginConfiguration("PicaNetworkLogger")
         val output = JSObject()
+        output.put("enabled", config.getBoolean("enabled", true))
         output.put("maxBodySize", config.getInt("maxBodySize", 131072))
         output.put("redactHeaders", config.getArray("redactHeaders"))
         output.put("redactJsonFields", config.getArray("redactJsonFields"))

package/android/src/main/java/com/linakis/capacitorpicanetworklogger/PicaNetworkLoggerPlugin.kt

@@ -14,11 +14,14 @@ import org.json.JSONObject
 class PicaNetworkLoggerPlugin : Plugin() {
     private val repository = LogRepository()
     private val configProvider = LoggerConfigProvider()
+    private var enabled = true
 
     override fun load() {
         super.load()
-        repository.attach(bridge.context)
         val config = configProvider.getConfig(this)
+        enabled = config.optBoolean("enabled", true)
+        if (!enabled) return
+        repository.attach(bridge.context)
         LogRepositoryStore.attach(bridge.context, repository, config.getInt("maxBodySize"))
         val redactHeaders = config.get("redactHeaders")?.let { value ->
             when (value) {
@@ -54,6 +57,12 @@ class PicaNetworkLoggerPlugin : Plugin() {
 
     @PluginMethod
     fun startRequest(call: PluginCall) {
+        if (!enabled) {
+            val ret = JSObject()
+            ret.put("id", "")
+            call.resolve(ret)
+            return
+        }
         val method = call.getString("method") ?: "GET"
         val url = call.getString("url") ?: ""
         val headers = call.getObject("headers")?.let { obj ->
@@ -69,6 +78,10 @@ class PicaNetworkLoggerPlugin : Plugin() {
 
     @PluginMethod
     fun finishRequest(call: PluginCall) {
+        if (!enabled) {
+            call.resolve()
+            return
+        }
         val id = call.getString("id") ?: return call.reject("Missing id")
         val status = call.getInt("status")
         val headers = call.getObject("headers")?.let { obj ->
@@ -82,6 +95,10 @@ class PicaNetworkLoggerPlugin : Plugin() {
 
     @PluginMethod
     fun openInspector(call: PluginCall) {
+        if (!enabled) {
+            call.resolve()
+            return
+        }
         val context = bridge.context
         val intent = android.content.Intent(context, InspectorActivity::class.java)
         intent.addFlags(android.content.Intent.FLAG_ACTIVITY_NEW_TASK)

package/ios/Plugin/InspectorLogger.swift

@@ -4,8 +4,8 @@ class InspectorLogger {
     static let shared = InspectorLogger()
     private let repository = LogRepository.shared
     private var maxBodySize: Int = 131072
-    private var redactHeaders: Set<String> = ["authorization", "cookie"]
-    private var redactJsonFields: Set<String> = ["password", "token"]
+    private var redactHeaders: Set<String> = []
+    private var redactJsonFields: Set<String> = []
     private var notifyEnabled: Bool = true
     private var requestMethods: [String: String] = [:]
     private var requestUrls: [String: String] = [:]
@@ -64,9 +64,15 @@ class InspectorLogger {
             payload["headers"] = redact(headers)
         }
         if let body = body {
-            let truncated = truncate(redactJson(body))
-            payload["responseBody"] = truncated.value
-            payload["responseBodyTruncated"] = truncated.truncated
+            let contentType = contentType(from: headers)
+            if isBinaryContentType(contentType) {
+                payload["responseBody"] = binaryPlaceholder(contentType)
+                payload["responseBodyTruncated"] = false
+            } else {
+                let truncated = truncate(redactJson(body))
+                payload["responseBody"] = truncated.value
+                payload["responseBodyTruncated"] = truncated.truncated
+            }
         }
         if let error = error {
             payload["error"] = error
@@ -154,4 +160,37 @@ class InspectorLogger {
     func setNotify(enabled: Bool) {
         notifyEnabled = enabled
     }
+
+    private func contentType(from headers: [String: Any]?) -> String? {
+        guard let headers = headers else { return nil }
+        for (key, value) in headers {
+            if key.lowercased() == "content-type", let str = value as? String {
+                return str.lowercased()
+            }
+        }
+        return nil
+    }
+
+    private func isBinaryContentType(_ contentType: String?) -> Bool {
+        guard let ct = contentType else { return false }
+        let binaryPrefixes = ["image/", "video/", "audio/", "application/octet-stream",
+                              "application/pdf", "application/zip", "application/gzip",
+                              "font/", "application/vnd.", "application/x-protobuf"]
+        return binaryPrefixes.contains { ct.hasPrefix($0) }
+    }
+
+    private func binaryPlaceholder(_ contentType: String?) -> String {
+        let ct = contentType ?? "unknown"
+        let mediaType: String
+        if ct.hasPrefix("image/") {
+            mediaType = "Image"
+        } else if ct.hasPrefix("video/") {
+            mediaType = "Video"
+        } else if ct.hasPrefix("audio/") {
+            mediaType = "Audio"
+        } else {
+            mediaType = "Binary"
+        }
+        return "[\(mediaType) preview not yet supported (\(ct))]"
+    }
 }

package/ios/Plugin/PicaNetworkLoggerPlugin.swift

@@ -14,8 +14,13 @@ public class PicaNetworkLoggerPlugin: CAPPlugin, CAPBridgedPlugin {
         CAPPluginMethod(name: "openInspector", returnType: CAPPluginReturnPromise)
     ]
     private let configProvider = LoggerConfigProvider()
+    private var enabled = true
 
     @objc func startRequest(_ call: CAPPluginCall) {
+        guard enabled else {
+            call.resolve(["id": ""])
+            return
+        }
         let id = UUID().uuidString
         let method = call.getString("method") ?? "GET"
         let url = call.getString("url") ?? ""
@@ -32,6 +37,10 @@ public class PicaNetworkLoggerPlugin: CAPPlugin, CAPBridgedPlugin {
     }
 
     @objc func finishRequest(_ call: CAPPluginCall) {
+        guard enabled else {
+            call.resolve()
+            return
+        }
         guard let id = call.getString("id") else {
             call.reject("Missing id")
             return
@@ -55,6 +64,8 @@ public class PicaNetworkLoggerPlugin: CAPPlugin, CAPBridgedPlugin {
     public override func load() {
         super.load()
         let config = configProvider.getConfig(self)
+        enabled = config["enabled"] as? Bool ?? true
+        guard enabled else { return }
         if let size = config["maxBodySize"] as? Int {
             InspectorLogger.shared.setMaxBodySize(size)
         }
@@ -74,6 +85,10 @@ public class PicaNetworkLoggerPlugin: CAPPlugin, CAPBridgedPlugin {
     }
 
     @objc func openInspector(_ call: CAPPluginCall) {
+        guard enabled else {
+            call.resolve()
+            return
+        }
         #if canImport(UIKit)
         DispatchQueue.main.async { [weak self] in
             let inspector = UINavigationController(rootViewController: InspectorViewController())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capacitor-pica-network-logger",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Capacitor HTTP network logger with debug-only native capture",
   "license": "MIT",
   "repository": {