@annadata/capacitor-mqtt-quic 0.1.7 → 0.1.8

package/AnnadataCapacitorMqttQuic.podspec

@@ -8,8 +8,8 @@ Pod::Spec.new do |s|
   s.summary = 'MQTT-over-QUIC Capacitor plugin (iOS)'
   s.license = package['license']
   s.homepage = 'https://github.com/annadata/capacitor-mqtt-quic'
-  s.author = 'Yakub Mohammad'
-  s.authors = { 'Yakub Mohammad' => 'yakub@annadata.ai' }
+  s.author = 'Mr. Yakub Mohammad'
+  s.authors = { 'Mr. Yakub Mohammad' => 'yakub@annadata.ai' }
   s.source = { :git => 'https://github.com/annadata/capacitor-mqtt-quic', :tag => s.version.to_s }
   s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
   s.resources = ['ios/Sources/MqttQuicPlugin/Resources/*.pem']

package/Package.swift

@@ -0,0 +1,59 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+// AnnadataCapacitorMqttQuic – Swift Package for Capacitor 8 (SPM).
+// At plugin root so Capacitor's SPM logic detects and adds it to CapApp-SPM automatically.
+// Requires ios/libs/MqttQuicLibs.xcframework. After building (see build-native.sh), run:
+//   cd ios && ./create-xcframework.sh
+let package = Package(
+    name: "AnnadataCapacitorMqttQuic",
+    platforms: [.iOS(.v15)],
+    products: [
+        .library(
+            name: "AnnadataCapacitorMqttQuic",
+            targets: ["AnnadataCapacitorMqttQuic"]
+        )
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0")
+    ],
+    targets: [
+        .binaryTarget(
+            name: "MqttQuicLibs",
+            path: "ios/libs/MqttQuicLibs.xcframework"
+        ),
+        .target(
+            name: "NGTCP2Bridge",
+            dependencies: ["MqttQuicLibs"],
+            path: "ios/Sources/MqttQuicPlugin/QUIC",
+            sources: ["NGTCP2Bridge.mm"],
+            publicHeadersPath: ".",
+            cxxSettings: [
+                .define("NGTCP2_ENABLED"),
+                .define("NGHTTP3_ENABLED"),
+                .headerSearchPath("../../../include")
+            ],
+            linkerSettings: [
+                .linkedLibrary("c++")
+            ]
+        ),
+        .target(
+            name: "AnnadataCapacitorMqttQuic",
+            dependencies: [
+                "NGTCP2Bridge",
+                .product(name: "Capacitor", package: "capacitor-swift-pm")
+            ],
+            path: "ios/Sources/MqttQuicPlugin",
+            exclude: [
+                "MQTT/MQTT5ReasonCodes.swift.rej",
+                "QUIC/NGTCP2Bridge.mm",
+                "QUIC/NGTCP2Bridge.h"
+            ],
+            resources: [.process("Resources")],
+            swiftSettings: [
+                .define("NGTCP2_ENABLED"),
+                .define("NGHTTP3_ENABLED")
+            ]
+        )
+    ]
+)

package/README.md

@@ -2,7 +2,7 @@
 
 MQTT-over-QUIC Capacitor plugin for **iOS**, **Android**, and **Web (browser/PWA)**. Native: ngtcp2 + WolfSSL for QUIC; Web: MQTT over WebSocket (WSS), same API and event listeners.
 
-**Capacitor:** Supports **Capacitor 7** and **Capacitor 8**.
+**Capacitor:** **8.0+** (tested with Capacitor 8).
 
 **Features:**
 - ✅ **MQTT 5.0** support with full properties and reason codes
@@ -20,7 +20,7 @@ MQTT-over-QUIC Capacitor plugin for **iOS**, **Android**, and **Web (browser/PWA
   - Transport abstraction (StreamReader/StreamWriter)
 - **Phase 2**: QUIC transport (ngtcp2) + stream adapters - **In Progress** ⏳
   - Currently uses stub implementations for testing
-  - See [NGTCP2_INTEGRATION_PLAN.md](./NGTCP2_INTEGRATION_PLAN.md) for build instructions
+  - See [NGTCP2_INTEGRATION_PLAN.md](./docs/NGTCP2_INTEGRATION_PLAN.md) for build instructions
 - **Phase 3**: MQTT client API + Capacitor plugin bridge - **Complete** ✅
 - **Phase 4**: Platform integration in annadata-production - **Complete** ✅
 
@@ -274,7 +274,7 @@ await MqttQuic.publish({
 | **Reason Codes** | Detailed error information | Better debugging |
 | **Topic Aliases** | Reduce bandwidth | High-frequency publishing |
 
-See [MQTT5_IMPLEMENTATION_COMPLETE.md](./MQTT5_IMPLEMENTATION_COMPLETE.md) for full details.
+See [MQTT5_IMPLEMENTATION_COMPLETE.md](./docs/MQTT5_IMPLEMENTATION_COMPLETE.md) for full details.
 
 ## TypeScript Interface
 
@@ -357,22 +357,25 @@ This script builds WolfSSL → nghttp3 → ngtcp2 in the correct order for both
 For detailed manual build instructions, see:
 - **iOS**: [ios/NGTCP2_BUILD_INSTRUCTIONS.md](./ios/NGTCP2_BUILD_INSTRUCTIONS.md)
 - **Android**: [android/NGTCP2_BUILD_INSTRUCTIONS.md](./android/NGTCP2_BUILD_INSTRUCTIONS.md)
-- **Full Plan**: [NGTCP2_INTEGRATION_PLAN.md](./NGTCP2_INTEGRATION_PLAN.md)
+- **Full Plan**: [NGTCP2_INTEGRATION_PLAN.md](./docs/NGTCP2_INTEGRATION_PLAN.md)
 
 **Prerequisites:**
-- iOS: macOS with Xcode 14+
+- iOS: macOS with Xcode 15+
 - Android: Android Studio with NDK r25+ (auto-detected from `$ANDROID_HOME`)
 
 ## Production / First-time build
 
-When you install the plugin from npm (`npm install @annadata/capacitor-mqtt-quic`), the published package may include **prebuilt native libs** (iOS and optionally Android, both using **WolfSSL**). In that case you only need:
+When you install the plugin from npm (`npm install @annadata/capacitor-mqtt-quic`), the published package **may** include **prebuilt native libs** (iOS and optionally Android, both using **WolfSSL**). If it does (a "complete" / zero-config package), you only need:
 
 ```bash
 npm install @annadata/capacitor-mqtt-quic
 npx cap sync
+ionic cap run android   # or ios
 ```
 
-**If your Android build fails with "WolfSSL not found"**, run this **one-time** setup from your app project root (requires Android NDK r25+). Both iOS and Android use **WolfSSL** as the TLS backend (license/size/QUIC support):
+**If your Android build fails with "WolfSSL not found"**, the package you installed does not include prebuilt Android libs. Do **one** of the following.
+
+**Option A – One-time build (from your app project root, requires Android NDK r25+):** Both iOS and Android use **WolfSSL** as the TLS backend (license/size/QUIC support):
 
 ```bash
 cd node_modules/@annadata/capacitor-mqtt-quic
@@ -402,14 +405,51 @@ Or add to your app’s `package.json` and run once:
 "setup:wolfssl-android": "cd node_modules/@annadata/capacitor-mqtt-quic && ./build-native.sh --android-only --abi arm64-v8a && ./build-native.sh --android-only --abi armeabi-v7a && ./build-native.sh --android-only --abi x86_64"
 ```
 
-**iOS:** The plugin ships with vendored static libs (`ios/libs/`) using WolfSSL. If you built the plugin from source and those are missing, run from the plugin repo: `./build-native.sh --ios-only`, then pack/publish.
+**Option B – Use a complete package:** Reinstall a version of the plugin that was published with Android prebuilts (see *Publishing a complete package* below). Then no one-time build is needed.
+
+**iOS:** The plugin typically ships with vendored static libs (`ios/libs/`) using WolfSSL. If you built the plugin from source and those are missing, run from the plugin repo: `./build-native.sh --ios-only`, then pack/publish.
+
+### Publishing a complete (zero-config) package
+
+So that **clients have no native build step**, build Android (and iOS) prebuilts **before** publishing, then publish. The tarball will include `android/install/` and consumers can `npm install` and run the app without running `build-native.sh`.
+
+From the **plugin repo** (capacitor-mqtt-quic), before `npm publish`:
+
+```bash
+# 1) Android prebuilts for all ABIs (required for zero-config Android)
+npm run build:android-prebuilts
+
+# 2) iOS prebuilts (if not already present)
+./build-native.sh --ios-only
+
+# 3) Build JS and publish (clean does not remove android/install or ios/libs)
+npm run build
+npm run clean:build-artifacts
+npm version patch   # or minor
+npm publish --access public
+```
+
+See **docs/PRODUCTION_PUBLISH_STEPS.md** for the full checklist.
+
+### Connection error: `{"code":"UNIMPLEMENTED"}`
+
+Capacitor returns this when the **native plugin method is not found** on the current platform. Common causes and fixes:
+
+| Platform | Check |
+|----------|--------|
+| **iOS** | Plugin must be linked. Run `npx cap sync ios` and `cd ios && pod install`, then rebuild in Xcode. Ensure `@annadata/capacitor-mqtt-quic` is in your app’s `package.json` and that the iOS project includes the plugin (Capacitor should auto-discover it). If you use a custom Podfile, ensure the AnnadataCapacitorMqttQuic plugin target is included. |
+| **Android** | Run `npx cap sync android` and rebuild. If you see "WolfSSL not found", run the one-time native build (see above). |
+| **Web / browser** | In browser, the plugin uses the **web** implementation (WSS or WebTransport). If you get UNIMPLEMENTED in the browser, the app may be resolving the native bridge instead of the web plugin—e.g. wrong `capacitor.config` or build. Ensure you’re opening the app as a web build (e.g. `ionic serve` or `cap run web`), not a native app with a WebView. |
+
+After adding the plugin or changing native code, always run **`npx cap sync`** and on iOS **`pod install`**, then rebuild the native app.
 
 ## Development
 
 ### Build Plugin
 
 ```bash
-cd production/capacitor-mqtt-quic
+git clone https://github.com/annadata/capacitor-mqtt-quic.git
+cd capacitor-mqtt-quic
 npm install
 npm run build
 ```
@@ -417,8 +457,8 @@ npm run build
 ### Add to Capacitor App
 
 ```bash
-cd production/annadata-production
-npm i @annadata/capacitor-mqtt-quic
+cd your-capacitor-app
+npm install @annadata/capacitor-mqtt-quic
 npx cap sync
 ```
 
@@ -443,14 +483,14 @@ await MqttQuic.connect({
 
 ## Publishing (maintainers)
 
-To pack the plugin **with native libs** and publish to npm, follow **[PRODUCTION_PUBLISH_STEPS.md](./PRODUCTION_PUBLISH_STEPS.md)**.
+To pack the plugin **with native libs** and publish to npm, follow **[PRODUCTION_PUBLISH_STEPS.md](./docs/PRODUCTION_PUBLISH_STEPS.md)**.
 
 ## Documentation
 
-- [Implementation Summary](./IMPLEMENTATION_SUMMARY.md) - Complete project overview
-- [MQTT 5.0 Implementation](./MQTT5_IMPLEMENTATION_COMPLETE.md) - MQTT 5.0 features and usage
-- [ngtcp2 Integration Plan](./NGTCP2_INTEGRATION_PLAN.md) - Build instructions for real QUIC
-- [MQTT Version Analysis](./MQTT_VERSION_ANALYSIS.md) - Why MQTT 5.0?
+- [Implementation Summary](./docs/IMPLEMENTATION_SUMMARY.md) - Complete project overview
+- [MQTT 5.0 Implementation](./docs/MQTT5_IMPLEMENTATION_COMPLETE.md) - MQTT 5.0 features and usage
+- [ngtcp2 Integration Plan](./docs/NGTCP2_INTEGRATION_PLAN.md) - Build instructions for real QUIC
+- [MQTT Version Analysis](./docs/MQTT_VERSION_ANALYSIS.md) - Why MQTT 5.0?
 
 ## Web / browser support
 
@@ -522,7 +562,7 @@ await MqttQuic.connect({
 - **iOS:** 15.0+
 - **Android:** API 21+ (Android 5.0+)
 - **Web:** Any modern browser; MQTT over WSS
-- **Capacitor:** 7.0+
+- **Capacitor:** 8.0+
 - **QUIC:** ngtcp2 + WolfSSL on native; on web, optional WebTransport (browser's HTTP/3/QUIC) when server supports it
 
 ## Author

package/android/NGTCP2_BUILD_INSTRUCTIONS.md

@@ -337,4 +337,4 @@ After building ngtcp2/nghttp3:
 2. Replace `QuicClientStub` with `NGTCP2Client` in `MQTTClient.kt`
 3. Test connection to MQTT server over QUIC
 
-See `NGTCP2_INTEGRATION_PLAN.md` for detailed implementation guide.
+See [NGTCP2_INTEGRATION_PLAN.md](../docs/NGTCP2_INTEGRATION_PLAN.md) for detailed implementation guide.

package/android/app/src/main/assets/capacitor.config.json

@@ -1,5 +1,5 @@
 {
 	"appId": "ai.annadata.mqttquic",
-	"appName": "MqttQuicPlugin",
+	"appName": "AnnadataCapacitorMqttQuic",
 	"webDir": "www"
 }

package/android/build.gradle

@@ -36,7 +36,10 @@ android {
         testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
         externalNativeBuild {
             cmake {
-                arguments "-DANDROID_STL=c++_shared"
+                arguments "-DANDROID_STL=c++_shared",
+                    "-DWOLFSSL_ROOT_DIR=${file('install/wolfssl-android').absolutePath}",
+                    "-DNGTCP2_INSTALL_DIR=${file('install/ngtcp2-android').absolutePath}",
+                    "-DNGHTTP3_INSTALL_DIR=${file('install/nghttp3-android').absolutePath}"
                 cppFlags "-std=c++17"
             }
         }

package/android/src/main/cpp/CMakeLists.txt

@@ -14,9 +14,10 @@ endif()
 # WolfSSL path (same layout as iOS: TLS backend for ngtcp2). Override via -DWOLFSSL_ROOT_DIR=...
 if(NOT WOLFSSL_ROOT_DIR)
     set(WOLFSSL_ROOT_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../install/wolfssl-android" CACHE PATH "Path to WolfSSL for Android")
-    if(EXISTS "${WOLFSSL_ROOT_DIR}/${ANDROID_ABI}")
-        set(WOLFSSL_ROOT_DIR "${WOLFSSL_ROOT_DIR}/${ANDROID_ABI}" CACHE PATH "Path to WolfSSL for Android (ABI)" FORCE)
-    endif()
+endif()
+# Prefer ABI-specific subdir when present (e.g. when WOLFSSL_ROOT_DIR is passed as base path from Gradle)
+if(EXISTS "${WOLFSSL_ROOT_DIR}/${ANDROID_ABI}")
+    set(WOLFSSL_ROOT_DIR "${WOLFSSL_ROOT_DIR}/${ANDROID_ABI}" CACHE PATH "Path to WolfSSL for Android (ABI)" FORCE)
 endif()
 if(NOT WOLFSSL_INCLUDE_DIR AND EXISTS "${WOLFSSL_ROOT_DIR}/include")
     set(WOLFSSL_INCLUDE_DIR "${WOLFSSL_ROOT_DIR}/include")
@@ -25,7 +26,12 @@ if(NOT WOLFSSL_LIBRARY AND EXISTS "${WOLFSSL_ROOT_DIR}/lib/libwolfssl.a")
     set(WOLFSSL_LIBRARY "${WOLFSSL_ROOT_DIR}/lib/libwolfssl.a")
 endif()
 if(NOT WOLFSSL_LIBRARY OR NOT WOLFSSL_INCLUDE_DIR)
-    message(FATAL_ERROR "WolfSSL not found. Build it first: cd android && ./build-wolfssl.sh --abi ${ANDROID_ABI}. Then run ./build-ngtcp2.sh (default uses WolfSSL).")
+    message(FATAL_ERROR
+        "WolfSSL not found at ${WOLFSSL_ROOT_DIR}. "
+        "One-time fix (from your app project root): "
+        "cd node_modules/@annadata/capacitor-mqtt-quic && "
+        "./build-native.sh --android-only --abi ${ANDROID_ABI} "
+        "(repeat for armeabi-v7a, x86_64). See plugin README 'Production / First-time build'.")
 endif()
 
 # ngtcp2 install/source directories (adjust as needed)
@@ -46,6 +52,14 @@ if(NOT NGHTTP3_INSTALL_DIR)
 endif()
 set(NGHTTP3_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../../nghttp3" CACHE PATH "Path to nghttp3 source")
 
+# Prefer ABI-specific subdir when install dirs are passed as base path from Gradle
+if(EXISTS "${NGTCP2_INSTALL_DIR}/${ANDROID_ABI}")
+    set(NGTCP2_INSTALL_DIR "${NGTCP2_INSTALL_DIR}/${ANDROID_ABI}" CACHE PATH "Path to ngtcp2 install (ABI)" FORCE)
+endif()
+if(EXISTS "${NGHTTP3_INSTALL_DIR}/${ANDROID_ABI}")
+    set(NGHTTP3_INSTALL_DIR "${NGHTTP3_INSTALL_DIR}/${ANDROID_ABI}" CACHE PATH "Path to nghttp3 install (ABI)" FORCE)
+endif()
+
 # Prefer installed libraries (WolfSSL backend: libngtcp2_crypto_wolfssl.a), fallback to source build
 set(NGTCP2_INCLUDE_DIR "")
 set(NGTCP2_LIBRARY "")
@@ -112,7 +126,7 @@ target_include_directories(ngtcp2_client PRIVATE
 )
 
 # Link libraries: WolfSSL + ngtcp2 (same TLS backend as iOS)
-target_link_libraries(ngtcp2_client
+target_link_libraries(ngtcp2_client PRIVATE
     ${WOLFSSL_LIBRARY}
     log
 )

package/android/src/main/cpp/ngtcp2_jni.cpp

@@ -188,7 +188,7 @@ class QuicClient {
     if (!conn_) {
       return 0;
     }
-    int rv = ngtcp2_conn_shutdown_stream_write(conn_, stream_id, 0);
+    int rv = ngtcp2_conn_shutdown_stream_write(conn_, 0, stream_id, 0);
     if (rv != 0) {
       setError(ngtcp2_strerror(rv));
       return -1;
@@ -266,12 +266,12 @@ class QuicClient {
       if (fd == -1) {
         continue;
       }
-      if (connect(fd, rp->ai_addr, rp->ai_addrlen) == 0) {
+      if (::connect(fd, rp->ai_addr, rp->ai_addrlen) == 0) {
         memcpy(&remote_addr_, rp->ai_addr, rp->ai_addrlen);
         remote_addrlen_ = (socklen_t)rp->ai_addrlen;
         break;
       }
-      close(fd);
+      ::close(fd);
       fd = -1;
     }
     freeaddrinfo(res);
@@ -284,7 +284,7 @@ class QuicClient {
     if (getsockname(fd, (struct sockaddr *)&local_addr_, &local_addrlen_) !=
         0) {
       setError("getsockname failed");
-      close(fd);
+      ::close(fd);
       return -1;
     }
 
@@ -333,17 +333,21 @@ class QuicClient {
     bool ca_loaded = false;
     const char *ca_file = std::getenv("MQTT_QUIC_CA_FILE");
     const char *ca_path = std::getenv("MQTT_QUIC_CA_PATH");
-    if ((ca_file && ca_file[0] != '\0') || (ca_path && ca_path[0] != '\0')) {
-      if (wolfSSL_CTX_load_verify_locations(ssl_ctx_, ca_file, ca_path) != 1) {
+    const char *file_arg = (ca_file && ca_file[0] != '\0') ? ca_file : nullptr;
+    const char *path_arg = (ca_path && ca_path[0] != '\0') ? ca_path : nullptr;
+    if (file_arg || path_arg) {
+      if (wolfSSL_CTX_load_verify_locations(ssl_ctx_, file_arg, path_arg) == 1) {
+        ca_loaded = true;
+      } else {
         setError("Failed to load CA bundle from MQTT_QUIC_CA_FILE/CA_PATH");
         return -1;
       }
+    }
+    if (!ca_loaded && wolfSSL_CTX_set_default_verify_paths(ssl_ctx_) == 1) {
       ca_loaded = true;
     }
-    if (!ca_loaded) {
-      if (wolfSSL_CTX_set_default_verify_paths(ssl_ctx_) == 1) {
-        ca_loaded = true;
-      }
+    if (!ca_loaded && wolfSSL_CTX_load_system_CA_certs(ssl_ctx_) == 1) {
+      ca_loaded = true;
     }
     if (!ca_loaded) {
       setError("No CA bundle available for TLS verification");
@@ -660,15 +664,15 @@ class QuicClient {
       ssl_ctx_ = nullptr;
     }
     if (fd_ != -1) {
-      close(fd_);
+      ::close(fd_);
       fd_ = -1;
     }
     if (wakeup_fds_[0] != -1) {
-      close(wakeup_fds_[0]);
+      ::close(wakeup_fds_[0]);
       wakeup_fds_[0] = -1;
     }
     if (wakeup_fds_[1] != -1) {
-      close(wakeup_fds_[1]);
+      ::close(wakeup_fds_[1]);
       wakeup_fds_[1] = -1;
     }
   }
@@ -740,10 +744,11 @@ class QuicClient {
     return 0;
   }
 
-  static int stream_close_cb(ngtcp2_conn *conn, int64_t stream_id,
-                             uint64_t app_error_code, void *user_data,
-                             void *stream_user_data) {
+  static int stream_close_cb(ngtcp2_conn *conn, uint32_t flags,
+                             int64_t stream_id, uint64_t app_error_code,
+                             void *user_data, void *stream_user_data) {
     (void)conn;
+    (void)flags;
     (void)app_error_code;
     (void)stream_user_data;
     auto *client = static_cast<QuicClient *>(user_data);
@@ -926,4 +931,11 @@ Java_ai_annadata_mqttquic_quic_NGTCP2Client_nativeGetLastError(
   return env->NewStringUTF(it->second->last_error());
 }
 
+// Debug-build alias: Kotlin/AGP can mangle the method name to include the module suffix.
+JNIEXPORT jstring JNICALL
+Java_ai_annadata_mqttquic_quic_NGTCP2Client_nativeGetLastError_00024annadata_1capacitor_1mqtt_1quic_1debug__J(
+    JNIEnv *env, jobject thiz, jlong connHandle) {
+  return Java_ai_annadata_mqttquic_quic_NGTCP2Client_nativeGetLastError(env, thiz, connHandle);
+}
+
 } // extern "C"

package/android/src/main/kotlin/ai/annadata/mqttquic/MqttQuicPlugin.kt

@@ -100,7 +100,7 @@ class MqttQuicPlugin : Plugin() {
                         notifyListeners("message", data)
                     }
                 }
-                client.connect(host, port, clientId, username, password, cleanSession, keepalive, sessionExpiryInterval)
+                client.connect(host, port, clientId, username, password, cleanSession ?: true, keepalive ?: 20, sessionExpiryInterval)
                 call.resolve(JSObject().put("connected", true))
                 notifyListeners("connected", JSObject().put("connected", true))
             } catch (e: Exception) {
@@ -199,7 +199,7 @@ class MqttQuicPlugin : Plugin() {
                 val properties = mutableMapOf<Int, Any>()
                 messageExpiryInterval?.let { properties[MQTT5PropertyType.MESSAGE_EXPIRY_INTERVAL.toInt()] = it }
                 contentType?.let { properties[MQTT5PropertyType.CONTENT_TYPE.toInt()] = it }
-                client.publish(topic, data, minOf(qos, 2), if (properties.isNotEmpty()) properties else null)
+                client.publish(topic, data, minOf(qos ?: 0, 2), if (properties.isNotEmpty()) properties else null)
                 call.resolve(JSObject().put("success", true))
             } catch (e: Exception) {
                 val msg = e.message ?: "Publish failed"
@@ -226,7 +226,7 @@ class MqttQuicPlugin : Plugin() {
 
         scope.launch {
             try {
-                client.subscribe(topic, minOf(qos, 2), subscriptionIdentifier)
+                client.subscribe(topic, minOf(qos ?: 0, 2), subscriptionIdentifier)
                 call.resolve(JSObject().put("success", true))
             } catch (e: Exception) {
                 call.reject(e.message ?: "Subscribe failed")

package/android/src/main/kotlin/ai/annadata/mqttquic/client/MQTTClient.kt

@@ -372,9 +372,9 @@ class MQTTClient {
     /** Send PINGREQ at effectiveKeepalive interval so server sees activity and does not close (idle/keepalive). [MQTT-3.1.2-20] */
     private fun startKeepaliveLoop() {
         keepaliveJob?.cancel()
-        val ka = lock.withLock { effectiveKeepalive }
-        if (ka <= 0) return
         keepaliveJob = scope.launch {
+            val ka = lock.withLock { effectiveKeepalive }
+            if (ka <= 0) return@launch
             while (isActive) {
                 delay(ka * 1000L) // seconds to ms
                 val (w, stillConnected) = lock.withLock {
@@ -428,8 +428,7 @@ class MQTTClient {
                                 if (activeProtocolVersion == MQTTProtocolLevel.V5) {
                                     MQTT5Protocol.parsePublishV5(rest, 0, qos, topicAliasMap)
                                 } else {
-                                    val t = MQTTProtocol.parsePublish(rest, 0, qos)
-                                    Triple(t.first, t.second, t.third)
+                                    MQTTProtocol.parsePublish(rest, 0, qos)
                                 }
                             }
 

package/android/src/main/kotlin/ai/annadata/mqttquic/mqtt/MQTTProtocol.kt

@@ -201,9 +201,9 @@ object MQTTProtocol {
     
     /**
      * Parse PUBLISH payload (after fixed header).
-     * Returns (topic, packetId?, payload, newOffset). packetId only for QoS > 0.
+     * Returns (topic, packetId?, payload). packetId only for QoS > 0.
      */
-    fun parsePublish(data: ByteArray, offset: Int, qos: Int): Triple<String, Int?, ByteArray, Int> {
+    fun parsePublish(data: ByteArray, offset: Int, qos: Int): Triple<String, Int?, ByteArray> {
         var off = offset
         val (topic, next) = decodeString(data, off)
         off = next
@@ -214,7 +214,7 @@ object MQTTProtocol {
             off += 2
         }
         val payload = data.copyOfRange(off, data.size)
-        return Triple(topic, pid, payload, data.size)
+        return Triple(topic, pid, payload)
     }
 
     fun buildSubscribe(packetId: Int, topic: String, qos: Int = 0): ByteArray {

package/android/src/main/kotlin/ai/annadata/mqttquic/mqtt/MQTTTypes.kt

@@ -5,21 +5,21 @@ package ai.annadata.mqttquic.mqtt
  */
 
 object MQTTMessageType {
-    const val CONNECT: Byte = 0x10
-    const val CONNACK: Byte = 0x20
-    const val PUBLISH: Byte = 0x30
-    const val PUBACK: Byte = 0x40
-    const val PUBREC: Byte = 0x50
-    const val PUBREL: Byte = 0x62
-    const val PUBCOMP: Byte = 0x70
-    const val SUBSCRIBE: Byte = 0x82
-    const val SUBACK: Byte = 0x90
-    const val UNSUBSCRIBE: Byte = 0xA2
-    const val UNSUBACK: Byte = 0xB0
-    const val PINGREQ: Byte = 0xC0
-    const val PINGRESP: Byte = 0xD0
-    const val DISCONNECT: Byte = 0xE0
-    const val AUTH: Byte = 0xF0
+    const val CONNECT: Byte = 0x10.toByte()
+    const val CONNACK: Byte = 0x20.toByte()
+    const val PUBLISH: Byte = 0x30.toByte()
+    const val PUBACK: Byte = 0x40.toByte()
+    const val PUBREC: Byte = 0x50.toByte()
+    const val PUBREL: Byte = 0x62.toByte()
+    const val PUBCOMP: Byte = 0x70.toByte()
+    const val SUBSCRIBE: Byte = 0x82.toByte()
+    const val SUBACK: Byte = 0x90.toByte()
+    const val UNSUBSCRIBE: Byte = 0xA2.toByte()
+    const val UNSUBACK: Byte = 0xB0.toByte()
+    const val PINGREQ: Byte = 0xC0.toByte()
+    const val PINGRESP: Byte = 0xD0.toByte()
+    const val DISCONNECT: Byte = 0xE0.toByte()
+    const val AUTH: Byte = 0xF0.toByte()
 }
 
 object MQTTConnectFlags {

package/android/src/main/kotlin/ai/annadata/mqttquic/quic/NGTCP2Client.kt

@@ -47,6 +47,7 @@ class NGTCP2Client : QuicClient {
     private external fun nativeClose(connHandle: Long)
     private external fun nativeIsConnected(connHandle: Long): Boolean
     internal external fun nativeCloseStream(connHandle: Long, streamId: Long): Int
+    @JvmName("nativeGetLastError")
     internal external fun nativeGetLastError(connHandle: Long): String
     
     // Connection state

package/docs/IMPLEMENTATION_SUMMARY.md

@@ -182,7 +182,7 @@ Implement `MqttQuicService` web fallback using `mqtt.js` or similar library.
 ```
 capacitor-mqtt-quic/
 ├── ios/
-│   ├── MqttQuicPlugin.podspec
+│   ├── AnnadataCapacitorMqttQuic.podspec
 │   └── Sources/MqttQuicPlugin/
 │       ├── MQTT/              # Phase 1
 │       ├── Transport/         # Phase 1, 2

package/docs/NGTCP2_IMPLEMENTATION_STATUS.md

@@ -129,7 +129,7 @@ The ngtcp2 integration replaces the stub QUIC implementations (`QuicClientStub`)
    - Implement TLS 1.3 handshake
    - Implement UDP packet handlers
 
-4. **Update `MqttQuicPlugin.podspec`:**
+4. **Update `AnnadataCapacitorMqttQuic.podspec`:**
    - Add ngtcp2 library linking
    - Add header search paths
 

package/docs/PRODUCTION_PUBLISH_STEPS.md

@@ -9,7 +9,7 @@ This checklist makes the plugin **production-grade**: pack everything needed (in
 ## Prerequisites
 
 - Node.js 18+
-- **iOS:** macOS, Xcode 14+
+- **iOS:** macOS, Xcode 15+
 - **Android:** Android Studio, NDK r25+ (e.g. via `$ANDROID_HOME/ndk/<version>`)
 - npm account with access to `@annadata` scope
 
@@ -32,9 +32,15 @@ This produces:
 
 The podspec’s `vendored_libraries` point at `ios/libs/`; these **must** be present when you pack/publish.
 
-### Android (optional but recommended for zero-config)
+### Android (required for zero-config / “complete” package)
 
-Android uses **WolfSSL** (same TLS backend as iOS). Build WolfSSL + nghttp3 + ngtcp2 for all ABIs so consumers don’t need to run the one-time setup:
+Android uses **WolfSSL** (same TLS backend as iOS). To ship a **complete** plugin so clients don’t run any native build, build WolfSSL + nghttp3 + ngtcp2 for all ABIs:
+
+```bash
+npm run build:android-prebuilts
+```
+
+Or manually:
 
 ```bash
 ./build-native.sh --android-only --abi arm64-v8a

package/ios/{MqttQuicPlugin.podspec → AnnadataCapacitorMqttQuic.podspec}

@@ -3,7 +3,7 @@ require 'json'
 package = JSON.parse(File.read(File.join(__dir__, '..', 'package.json')))
 
 Pod::Spec.new do |s|
-  s.name = 'MqttQuicPlugin'
+  s.name = 'AnnadataCapacitorMqttQuic'
   s.version = package['version']
   s.summary = 'MQTT-over-QUIC Capacitor plugin (iOS)'
   s.license = package['license']
@@ -12,7 +12,7 @@ Pod::Spec.new do |s|
   s.source = { :git => 'https://github.com/annadata/capacitor-mqtt-quic', :tag => s.version.to_s }
   s.source_files = 'Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
   s.resources = ['Sources/MqttQuicPlugin/Resources/*.pem']
-  s.ios.deployment_target = '14.0'
+  s.ios.deployment_target = '15.0'
   s.dependency 'Capacitor'
   s.swift_version = '5.1'
   s.vendored_libraries = [
@@ -25,8 +25,8 @@ Pod::Spec.new do |s|
   s.private_header_files = 'Sources/**/*.h', 'include/**/*.h'
   s.header_mappings_dir = 'Sources'
   s.pod_target_xcconfig = {
-    'HEADER_SEARCH_PATHS' => '$(PODS_ROOT)/MqttQuicPlugin/include/ngtcp2 $(PODS_ROOT)/MqttQuicPlugin/include/nghttp3 $(PODS_ROOT)/MqttQuicPlugin/include/wolfssl',
-    'LIBRARY_SEARCH_PATHS' => '$(PODS_ROOT)/MqttQuicPlugin/libs',
+    'HEADER_SEARCH_PATHS' => '$(PODS_ROOT)/AnnadataCapacitorMqttQuic/include/ngtcp2 $(PODS_ROOT)/AnnadataCapacitorMqttQuic/include/nghttp3 $(PODS_ROOT)/AnnadataCapacitorMqttQuic/include/wolfssl',
+    'LIBRARY_SEARCH_PATHS' => '$(PODS_ROOT)/AnnadataCapacitorMqttQuic/libs',
     'OTHER_LDFLAGS' => '-lngtcp2 -lngtcp2_crypto_wolfssl -lnghttp3 -lwolfssl',
     'SWIFT_ACTIVE_COMPILATION_CONDITIONS' => 'NGTCP2_ENABLED NGHTTP3_ENABLED'
   }

package/ios/App/App/capacitor.config.json

@@ -1,6 +1,6 @@
 {
 	"appId": "ai.annadata.mqttquic",
-	"appName": "MqttQuicPlugin",
+	"appName": "AnnadataCapacitorMqttQuic",
 	"webDir": "www",
 	"packageClassList": [
 		"MqttQuicPlugin"

package/ios/NGTCP2_BUILD_INSTRUCTIONS.md

@@ -34,7 +34,7 @@ If you have access to pre-built ngtcp2, nghttp3, and OpenSSL libraries:
 2. Place `libnghttp3.a` in `ios/libs/`
 3. Place OpenSSL libraries (`libssl.a`, `libcrypto.a`) in `ios/libs/`
 4. Place headers in `ios/include/ngtcp2/`, `ios/include/nghttp3/`, and `ios/include/openssl/`
-5. Update `MqttQuicPlugin.podspec` to link against these libraries
+5. Update `AnnadataCapacitorMqttQuic.podspec` to link against these libraries
 
 ### Option 2: Build from Source
 
@@ -154,7 +154,7 @@ Then clean and rebuild the iOS app so it links the new xcframework. See the app
 
 ### Option A: CocoaPods
 
-Update `ios/MqttQuicPlugin.podspec`:
+Update `ios/AnnadataCapacitorMqttQuic.podspec`:
 
 ```ruby
 Pod::Spec.new do |s|
@@ -342,4 +342,4 @@ After building ngtcp2:
 2. Replace `QuicClientStub` with `NGTCP2Client` in `MQTTClient.swift`
 3. Test connection to MQTT server over QUIC
 
-See `NGTCP2_INTEGRATION_PLAN.md` for detailed implementation guide.
+See [NGTCP2_INTEGRATION_PLAN.md](../docs/NGTCP2_INTEGRATION_PLAN.md) for detailed implementation guide.

package/ios/Package.swift

@@ -1,17 +1,16 @@
 // swift-tools-version: 5.9
 import PackageDescription
 
-// MqttQuicPlugin iOS – Swift Package for Capacitor 8 (SPM).
-// Requires Libs/MqttQuicLibs.xcframework. After building OpenSSL, ngtcp2, nghttp3
-// (see build-openssl.sh, build-ngtcp2.sh, build-nghttp3.sh), run:
+// AnnadataCapacitorMqttQuic – Swift Package for Capacitor 8 (SPM).
+// Requires Libs/MqttQuicLibs.xcframework. After building (see build-native.sh), run:
 //   ./create-xcframework.sh
 let package = Package(
-    name: "MqttQuicPlugin",
-    platforms: [.iOS(.v14)],
+    name: "AnnadataCapacitorMqttQuic",
+    platforms: [.iOS(.v15)],
     products: [
         .library(
-            name: "MqttQuicPlugin",
-            targets: ["MqttQuicPlugin"]
+            name: "AnnadataCapacitorMqttQuic",
+            targets: ["AnnadataCapacitorMqttQuic"]
         )
     ],
     dependencies: [
@@ -38,7 +37,7 @@ let package = Package(
             ]
         ),
         .target(
-            name: "MqttQuicPlugin",
+            name: "AnnadataCapacitorMqttQuic",
             dependencies: [
                 "NGTCP2Bridge",
                 .product(name: "Capacitor", package: "capacitor-swift-pm")

package/ios/Tests/MQTTProtocolTests.swift

@@ -4,7 +4,7 @@
 //
 
 import XCTest
-@testable import MqttQuicPlugin
+@testable import AnnadataCapacitorMqttQuic
 
 final class MQTTProtocolTests: XCTestCase {
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@annadata/capacitor-mqtt-quic",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "type": "module",
   "description": "MQTT-over-QUIC client for Capacitor (iOS, Android, Web). Native: ngtcp2+WolfSSL; Web: MQTT over WebSocket (WSS), same API.",
   "main": "dist/plugin.cjs.js",
@@ -11,6 +11,7 @@
     "dist",
     "ios",
     "android",
+    "Package.swift",
     "AnnadataCapacitorMqttQuic.podspec",
     "README.md",
     "deps-versions.sh",
@@ -21,6 +22,7 @@
     "build": "npm run build:tsc && npm run build:rollup",
     "build:tsc": "npx tsc",
     "build:rollup": "npx rollup -c rollup.config.js",
+    "build:android-prebuilts": "./build-native.sh --android-only --abi arm64-v8a && ./build-native.sh --android-only --abi armeabi-v7a && ./build-native.sh --android-only --abi x86_64",
     "watch": "rollup -c rollup.config.js -w",
     "lint": "eslint src --ext ts",
     "prepack": "npm run clean:build-artifacts",
@@ -41,7 +43,8 @@
   ],
   "capacitor": {
     "ios": {
-      "src": "ios"
+      "src": "ios",
+      "name": "AnnadataCapacitorMqttQuic"
     },
     "android": {
       "src": "android"