sparkling-method 2.1.0-rc.24 → 2.1.0-rc.26

package/ios/Sources/Core/Pipe/MethodPipe+Internal.swift

@@ -4,10 +4,69 @@
 
 import Foundation
 
+private enum MethodInvocationPayloadKeys {
+    static let code = "code"
+    static let data = "data"
+    static let message = "message"
+    static let msg = "msg"
+    static let containerID = "containerID"
+    static let protocolVersion = "protocolVersion"
+}
+
+private func methodInvocationStatusCode(_ status: MethodStatus) -> Int {
+    status.code == .notFound ? MethodStatusCode.unregisteredMethod.rawValue : status.rawCode
+}
+
 extension MethodPipe {
     func executeMethod(methodName: String, params: [String: Any]?, thread: MethodThread = .mainThread, completion: CommonPipeCompletion?) {
+        let invocationId = UUID().uuidString
+        let invocationStart = Date()
+        let invocationCenter = SparklingMethodInvocationCenter.shared
+        let invocationNamespace: String? = "method-pipe"
+        let callbackPayload: (MethodStatus, [String: Any]?) -> [String: Any] = { status, data in
+            var payload: [String: Any] = [
+                MethodInvocationPayloadKeys.code: methodInvocationStatusCode(status),
+                MethodInvocationPayloadKeys.data: data ?? NSNull(),
+                MethodInvocationPayloadKeys.protocolVersion: "1.1.0",
+            ]
+            payload[MethodInvocationPayloadKeys.msg] = status.message ?? NSNull()
+            if let containerID = params?[MethodInvocationPayloadKeys.containerID] as? String {
+                payload[MethodInvocationPayloadKeys.containerID] = containerID
+            }
+            return payload
+        }
+
+        invocationCenter.notifyStart(
+            SparklingMethodInvocationEvent(
+                id: invocationId,
+                name: methodName,
+                namespace: invocationNamespace,
+                platform: "core",
+                params: params,
+                result: nil,
+                statusCode: nil,
+                statusMessage: nil,
+                startTime: invocationStart,
+                endTime: nil
+            )
+        )
+
         guard let method = self.method(forName: methodName) else {
-            completion?(.notFound(), nil)
+            let status = MethodStatus.notFound()
+            let notFound = SparklingMethodInvocationEvent(
+                id: invocationId,
+                name: methodName,
+                namespace: invocationNamespace,
+                platform: "core",
+                params: params,
+                result: callbackPayload(status, nil),
+                statusCode: methodInvocationStatusCode(status),
+                statusMessage: status.message ?? "notFound",
+                startTime: invocationStart,
+                endTime: Date()
+            )
+            invocationCenter.notifyEnd(notFound)
+            completion?(status, nil)
             return
         }
 
@@ -32,10 +91,48 @@ extension MethodPipe {
             }
 
             resultDict[DictKeys.statusMessage] = fStatus.message
+            let callbackResult = callbackPayload(fStatus, resultDict)
+
+            invocationCenter.notifyEnd(
+                SparklingMethodInvocationEvent(
+                    id: invocationId,
+                    name: methodName,
+                    namespace: invocationNamespace,
+                    platform: "core",
+                    params: params,
+                    result: callbackResult,
+                    statusCode: methodInvocationStatusCode(fStatus),
+                    statusMessage: fStatus.message,
+                    startTime: invocationStart,
+                    endTime: Date()
+                )
+            )
+
             completion?(fStatus, resultDict)
         }
+
+        // Notify observers of an early-out failure (mirrors `resultBlk`).
+        let notifyEarlyFailure: (String) -> Void = { message in
+            let status = MethodStatus.invalidParameter(message: message)
+            invocationCenter.notifyEnd(
+                SparklingMethodInvocationEvent(
+                    id: invocationId,
+                    name: methodName,
+                    namespace: invocationNamespace,
+                    platform: "core",
+                    params: params,
+                    result: callbackPayload(status, [MethodInvocationPayloadKeys.message: message]),
+                    statusCode: methodInvocationStatusCode(status),
+                    statusMessage: message,
+                    startTime: invocationStart,
+                    endTime: Date()
+                )
+            )
+        }
+
         let paramsModelType = method.paramsModelClass
         guard var params = params else {
+            notifyEarlyFailure("Pipe inner error: empty params")
             completion?(.invalidParameter(message: "Pipe inner error: empty params"), nil)
             return
         }
@@ -47,6 +144,7 @@ extension MethodPipe {
             let paramsKeys: Set<String> = Set(params.keys)
             let missingKeys = requiredKeyPaths.subtracting(paramsKeys).sorted().joined(separator: ", ")
             if missingKeys.count > 0 {
+                notifyEarlyFailure("Missing required parameter(s): \(missingKeys)")
                 completion?(.invalidParameter(message: "Missing required parameter(s): \(missingKeys)"), nil)
                 return
             }
@@ -60,10 +158,12 @@ extension MethodPipe {
                 throw NSError(domain: "MethodPipe", code: -1, userInfo: [NSLocalizedDescriptionKey: "Invalid params model type: \(paramsModelType)"])
             }
         } catch {
+            notifyEarlyFailure(error.localizedDescription)
             completion?(.invalidParameter(message: error.localizedDescription), nil)
             return
         }
         guard var paramModel = paramModel else {
+            notifyEarlyFailure("Param model conversion failed")
             completion?(.invalidParameter(message: "Param model conversion failed: \(type(of: paramsModelType)) from dict: \(params)"), nil)
             return
         }

package/ios/Sources/Core/Pipe/SparklingMethodInvocationCenter.swift

@@ -0,0 +1,174 @@
+// Copyright (c) 2026 TikTok Pte. Ltd.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+
+import Foundation
+
+/// Snapshot describing one Sparkling Method invocation. The fields mirror the
+/// Android `SparklingMethodInvocationCenter.Event` so debug surfaces can be
+/// kept consistent across platforms.
+public struct SparklingMethodInvocationEvent {
+    public let id: String
+    public let name: String
+    public let namespace: String?
+    public let platform: String
+    public let params: [String: Any]?
+    public let result: [String: Any]?
+    public let statusCode: Int?
+    public let statusMessage: String?
+    public let startTime: Date
+    public let endTime: Date?
+
+    public var durationMs: Int? {
+        guard let end = endTime else { return nil }
+        return Int((end.timeIntervalSince(startTime)) * 1000)
+    }
+}
+
+/// Observer protocol for [SparklingMethodInvocationCenter].
+public protocol SparklingMethodInvocationObserver: AnyObject {
+    func sparklingMethodInvocationDidStart(_ event: SparklingMethodInvocationEvent)
+    func sparklingMethodInvocationDidEnd(_ event: SparklingMethodInvocationEvent)
+}
+
+public extension SparklingMethodInvocationObserver {
+    func sparklingMethodInvocationDidStart(_ event: SparklingMethodInvocationEvent) {}
+}
+
+/// Central hub the Sparkling Method pipe uses to broadcast every invocation
+/// lifecycle event. Debug tools attach themselves at app startup; the pipe
+/// only walks observers when at least one is registered.
+public final class SparklingMethodInvocationCenter {
+    public static let shared = SparklingMethodInvocationCenter()
+
+    /// Notification posted whenever a method invocation starts. The
+    /// `Notification.object` is the `SparklingMethodInvocationCenter` shared
+    /// instance and the underlying `SparklingMethodInvocationEvent` is
+    /// available under `userInfo[SparklingMethodInvocationCenter.eventKey]`.
+    /// Debug surfaces that don't want to take a hard dependency on
+    /// `SparklingMethod` can subscribe by name string instead of importing
+    /// this module.
+    public static let didStartNotification = Notification.Name("SparklingMethodInvocationCenter.didStart")
+    public static let didEndNotification = Notification.Name("SparklingMethodInvocationCenter.didEnd")
+    public static let eventKey = "event"
+
+    private let lock = NSLock()
+    private var observers = NSHashTable<AnyObject>.weakObjects()
+
+    private init() {}
+
+    public func addObserver(_ observer: SparklingMethodInvocationObserver) {
+        lock.lock(); defer { lock.unlock() }
+        observers.add(observer as AnyObject)
+    }
+
+    public func removeObserver(_ observer: SparklingMethodInvocationObserver) {
+        lock.lock(); defer { lock.unlock() }
+        observers.remove(observer as AnyObject)
+    }
+
+    public var hasObservers: Bool {
+        lock.lock(); defer { lock.unlock() }
+        return observers.allObjects.contains { _ in true }
+    }
+
+    func notifyStart(_ event: SparklingMethodInvocationEvent) {
+        for case let observer as SparklingMethodInvocationObserver in snapshot() {
+            observer.sparklingMethodInvocationDidStart(event)
+        }
+        NotificationCenter.default.post(
+            name: SparklingMethodInvocationCenter.didStartNotification,
+            object: self,
+            userInfo: makeNotificationUserInfo(for: event)
+        )
+    }
+
+    func notifyEnd(_ event: SparklingMethodInvocationEvent) {
+        for case let observer as SparklingMethodInvocationObserver in snapshot() {
+            observer.sparklingMethodInvocationDidEnd(event)
+        }
+        NotificationCenter.default.post(
+            name: SparklingMethodInvocationCenter.didEndNotification,
+            object: self,
+            userInfo: makeNotificationUserInfo(for: event)
+        )
+    }
+
+    func notifyNativeToJsEvent(name: String, params: [String: Any]?, containerID: String?) {
+        let now = Date()
+        let payload: [String: Any] = [
+            "event": name,
+            "params": params ?? [:],
+            "containerID": containerID ?? NSNull(),
+        ]
+        let result: [String: Any] = [
+            "status": "sent",
+            "direction": "Native -> JS",
+        ]
+        notifyEnd(
+            SparklingMethodInvocationEvent(
+                id: UUID().uuidString,
+                name: name,
+                namespace: "native-to-js",
+                platform: "lynx",
+                params: payload,
+                result: result,
+                statusCode: 1,
+                statusMessage: "sent",
+                startTime: now,
+                endTime: now
+            )
+        )
+    }
+
+    func notifyCompletedInvocation(
+        name: String,
+        namespace: String?,
+        platform: String,
+        params: [String: Any]?,
+        result: [String: Any]?,
+        statusCode: Int?,
+        statusMessage: String?
+    ) {
+        let now = Date()
+        notifyEnd(
+            SparklingMethodInvocationEvent(
+                id: UUID().uuidString,
+                name: name,
+                namespace: namespace,
+                platform: platform,
+                params: params,
+                result: result,
+                statusCode: statusCode,
+                statusMessage: statusMessage,
+                startTime: now,
+                endTime: now
+            )
+        )
+    }
+
+    /// Build a stable, type-erased dictionary representation of the event so
+    /// debug surfaces can subscribe via `Notification.Name` strings without
+    /// importing this module. Keys mirror the struct field names.
+    private func makeNotificationUserInfo(for event: SparklingMethodInvocationEvent) -> [AnyHashable: Any] {
+        var info: [AnyHashable: Any] = [
+            SparklingMethodInvocationCenter.eventKey: event,
+            "id": event.id,
+            "name": event.name,
+            "platform": event.platform,
+            "startTime": event.startTime,
+        ]
+        if let namespace = event.namespace { info["namespace"] = namespace }
+        if let params = event.params { info["params"] = params }
+        if let result = event.result { info["result"] = result }
+        if let statusCode = event.statusCode { info["statusCode"] = statusCode }
+        if let statusMessage = event.statusMessage { info["statusMessage"] = statusMessage }
+        if let endTime = event.endTime { info["endTime"] = endTime }
+        return info
+    }
+
+    private func snapshot() -> [AnyObject] {
+        lock.lock(); defer { lock.unlock() }
+        return observers.allObjects
+    }
+}

package/ios/Sources/Lynx/Engine/LynxPipeEngine.swift

@@ -31,6 +31,11 @@ class LynxPipeEngine: PipeEngine {
         guard let lynxView = self.lynxView else {
             return
         }
+        SparklingMethodInvocationCenter.shared.notifyNativeToJsEvent(
+            name: name,
+            params: params,
+            containerID: lynxView.containerID
+        )
         var sendMsg = LynxSendMessage(containerID: self.lynxView?.containerID)
         sendMsg.data = params
         sendMsg.code = .succeeded

package/ios/Sources/Lynx/Engine/LynxView+SPKPipe.swift

@@ -46,9 +46,13 @@ extension LynxView {
         }
     }
 
+    private func spk_getLynxContextIfAvailable() -> LynxContext? {
+        perform(#selector(getLynxContext))?.takeUnretainedValue() as? LynxContext
+    }
+
     func spk_clearModuleForDestroy() {
         if !spk_isLynxViewDestorying {
-            if let lynxContext = self.getLynxContext() as? LynxContext {
+            if let lynxContext = spk_getLynxContextIfAvailable() {
                 lynxContext.spk_containerID = self.containerID
                 if let pipeEngine = self.spk_pipeEngine, let namescope = self.namescope {
                     pipeEngine.namescope = namescope

package/ios/Sources/Lynx/Module/SPKLynxNativeModule.swift

@@ -28,11 +28,37 @@ public class SPKLynxNativeModule: NSObject, LynxModule {
 
     public func call(name: String, params: [String: Any], callback: LynxCallbackBlock?) {
         let message = LynxRecvMessage(methodName: name, rawData: params)
-        guard let containerID = message.containerID?.isEmpty == false ? message.containerID : containerID else { return }
+        guard let containerID = message.containerID?.isEmpty == false ?  message.containerID : containerID else {
+            let result = LynxSendMessage.paramsErrorMessage(
+                with: message.containerID,
+                errorMsg: "missing container id"
+            ).toDict()
+            SparklingMethodInvocationCenter.shared.notifyCompletedInvocation(
+                name: name,
+                namespace: "spkPipe",
+                platform: "lynx",
+                params: params,
+                result: result,
+                statusCode: LynxPipeStatusCode.parameterError.rawValue,
+                statusMessage: "missing container id"
+            )
+            callback?(result)
+            return
+        }
         guard let engine = LynxPipeEnginePool.engine(for: containerID) else {
             var errorSendMsg = LynxSendMessage.paramsErrorMessage(with: containerID, errorMsg: "error container id")
             errorSendMsg.recvMessage = message
-            callback?(errorSendMsg.toDict())
+            let result = errorSendMsg.toDict()
+            SparklingMethodInvocationCenter.shared.notifyCompletedInvocation(
+                name: name,
+                namespace: "spkPipe",
+                platform: "lynx",
+                params: params,
+                result: result,
+                statusCode: LynxPipeStatusCode.parameterError.rawValue,
+                statusMessage: "error container id"
+            )
+            callback?(result)
             return
         }
 

package/ios/SparklingMethod.podspec

@@ -2,7 +2,7 @@ require 'json'
 
 Pod::Spec.new do |s|
   s.name           = 'SparklingMethod'
-  s.version        = "2.1.0-rc.24"
+  s.version        = "2.1.0-rc.26"
   s.summary        = "iOS SDK for Sparkling Method"
   s.description    = "Core iOS method runtime for Sparkling, with Lynx integration, dependency injection support, and debug helpers."
   s.license        = "Apache 2.0"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparkling-method",
-  "version": "2.1.0-rc.24",
+  "version": "2.1.0-rc.26",
   "homepage": "https://tiktok.github.io/sparkling/",
   "repository": {
     "type": "git",