@luciq/react-native 19.2.1 → 19.3.0-40271-SNAPSHOT

package/android/src/main/java/ai/luciq/reactlibrary/RNLuciqNetworkLoggerModule.java

@@ -32,6 +32,8 @@ import java.util.concurrent.ConcurrentHashMap;
 
 public class RNLuciqNetworkLoggerModule extends EventEmitterModule {
 
+    private static final String NET_TAG = "LCQ-RN-NET";
+
     public final ConcurrentHashMap<String, OnCompleteCallback<NetworkLogSnapshot>> callbackMap = new ConcurrentHashMap<String, OnCompleteCallback<NetworkLogSnapshot>>();
 
     public RNLuciqNetworkLoggerModule(ReactApplicationContext reactContext) {
@@ -57,7 +59,9 @@ public class RNLuciqNetworkLoggerModule extends EventEmitterModule {
     }
 
     private boolean getFlagValue(String key) {
-        return InternalAPM._isFeatureEnabledCP(key, "");
+        boolean value = InternalAPM._isFeatureEnabledCP(key, "");
+        Log.d(NET_TAG, "[getFlagValue] key=" + key + ", value=" + value);
+        return value;
     }
 
     private WritableMap convertFromMapToWritableMap(Map<String, Object> map) {
@@ -86,14 +90,18 @@ public class RNLuciqNetworkLoggerModule extends EventEmitterModule {
      */
     @ReactMethod
     public void isNativeInterceptionEnabled(Promise promise) {
+        Log.d(NET_TAG, "[isNativeInterceptionEnabled] Querying CP_NATIVE_INTERCEPTION_ENABLED flag");
         MainThreadHandler.runOnMainThread(new Runnable() {
             @Override
             public void run() {
                 try {
-                    promise.resolve(getFlagValue(CP_NATIVE_INTERCEPTION_ENABLED));
+                    boolean enabled = getFlagValue(CP_NATIVE_INTERCEPTION_ENABLED);
+                    Log.d(NET_TAG, "[isNativeInterceptionEnabled] Result=" + enabled);
+                    promise.resolve(enabled);
                 } catch (Exception e) {
+                    Log.e(NET_TAG, "[isNativeInterceptionEnabled] Error — falling back to false (JS interceptor)", e);
                     e.printStackTrace();
-                    promise.resolve(false); // Will rollback to JS interceptor
+                    promise.resolve(false);
                 }
 
             }
@@ -107,14 +115,18 @@ public class RNLuciqNetworkLoggerModule extends EventEmitterModule {
      */
     @ReactMethod
     public void hasAPMNetworkPlugin(Promise promise) {
+        Log.d(NET_TAG, "[hasAPMNetworkPlugin] Querying APM_NETWORK_PLUGIN_INSTALLED flag");
         MainThreadHandler.runOnMainThread(new Runnable() {
             @Override
             public void run() {
                 try {
-                    promise.resolve(getFlagValue(APM_NETWORK_PLUGIN_INSTALLED));
+                    boolean hasPlugin = getFlagValue(APM_NETWORK_PLUGIN_INSTALLED);
+                    Log.d(NET_TAG, "[hasAPMNetworkPlugin] Result=" + hasPlugin);
+                    promise.resolve(hasPlugin);
                 } catch (Exception e) {
+                    Log.e(NET_TAG, "[hasAPMNetworkPlugin] Error — falling back to false", e);
                     e.printStackTrace();
-                    promise.resolve(false);  // Will rollback to JS interceptor
+                    promise.resolve(false);
                 }
 
             }
@@ -124,12 +136,14 @@ public class RNLuciqNetworkLoggerModule extends EventEmitterModule {
 
     @ReactMethod
     public void registerNetworkLogsListener() {
+        Log.d(NET_TAG, "[registerNetworkLogsListener] Registering network log sanitizer");
         MainThreadHandler.runOnMainThread(new Runnable() {
             @Override
             public void run() {
                 InternalAPM._registerNetworkLogSanitizer((networkLogSnapshot, onCompleteCallback) -> {
                     final String id = String.valueOf(onCompleteCallback.hashCode());
                     callbackMap.put(id, onCompleteCallback);
+                    Log.d(NET_TAG, "[NetworkLogSanitizer] Received snapshot — id=" + id + ", url=" + networkLogSnapshot.getUrl() + ", responseCode=" + networkLogSnapshot.getResponseCode() + ", callbackMapSize=" + callbackMap.size());
 
                     WritableMap networkSnapshotParams = Arguments.createMap();
                     networkSnapshotParams.putString("id", id);
@@ -147,6 +161,7 @@ public class RNLuciqNetworkLoggerModule extends EventEmitterModule {
                     }
 
                     sendEvent(Constants.LCQ_NETWORK_LOGGER_HANDLER, networkSnapshotParams);
+                    Log.d(NET_TAG, "[NetworkLogSanitizer] Sent event to JS: " + Constants.LCQ_NETWORK_LOGGER_HANDLER + " for " + networkLogSnapshot.getUrl());
                 });
             }
         });
@@ -154,10 +169,12 @@ public class RNLuciqNetworkLoggerModule extends EventEmitterModule {
 
     @ReactMethod
     public void resetNetworkLogsListener() {
+        Log.d(NET_TAG, "[resetNetworkLogsListener] Clearing network log sanitizer, callbackMapSize=" + callbackMap.size());
         MainThreadHandler.runOnMainThread(new Runnable() {
             @Override
             public void run() {
                 InternalAPM._registerNetworkLogSanitizer(null);
+                Log.d(NET_TAG, "[resetNetworkLogsListener] Sanitizer cleared");
             }
         });
     }
@@ -172,23 +189,28 @@ public class RNLuciqNetworkLoggerModule extends EventEmitterModule {
             ReadableMap requestHeaders,
             ReadableMap responseHeaders
     ) {
+        Log.d(NET_TAG, "[updateNetworkLogSnapshot] callbackID=" + callbackID + ", url=" + url + ", responseCode=" + responseCode + ", callbackMapSize=" + callbackMap.size());
         try {
-            // Convert ReadableMap to a Java Map for easier handling
             Map<String, Object> requestHeadersMap = convertReadableMapToMap(requestHeaders);
             Map<String, Object> responseHeadersMap = convertReadableMapToMap(responseHeaders);
 
             NetworkLogSnapshot modifiedSnapshot = null;
             if (!url.isEmpty()) {
                 modifiedSnapshot = new NetworkLogSnapshot(url, requestHeadersMap, requestBody, responseHeadersMap, responseBody, responseCode);
+            } else {
+                Log.d(NET_TAG, "[updateNetworkLogSnapshot] Empty URL — snapshot will be null (request filtered/removed)");
             }
 
             final OnCompleteCallback<NetworkLogSnapshot> callback = callbackMap.get(callbackID);
             if (callback != null) {
                 callback.onComplete(modifiedSnapshot);
                 callbackMap.remove(callbackID);
+                Log.d(NET_TAG, "[updateNetworkLogSnapshot] Callback invoked and removed for " + callbackID + ", remaining=" + callbackMap.size());
+            } else {
+                Log.e(NET_TAG, "[updateNetworkLogSnapshot] No callback found for callbackID=" + callbackID + " — possible leak or duplicate call, mapKeys=" + callbackMap.keySet());
             }
         } catch (Exception e) {
-            // Reject the promise to indicate an error occurred
+            Log.e(NET_TAG, "[updateNetworkLogSnapshot] Exception processing snapshot: " + e.getMessage() + " for callbackID=" + callbackID, e);
             Log.e("IB-CP-Bridge", "LuciqNetworkLogger.updateNetworkLogSnapshot failed to parse the network snapshot object.");
         }
     }

package/android/src/main/java/ai/luciq/reactlibrary/RNLuciqReactnativeModule.java

@@ -86,6 +86,7 @@ import javax.annotation.Nullable;
 public class RNLuciqReactnativeModule extends EventEmitterModule {
 
     private static final String TAG = "Luciq-RN-Core";
+    private static final String NET_TAG = "LCQ-RN-NET";
 
     private LuciqCustomTextPlaceHolder placeHolders;
     private static Report currentReport;
@@ -163,6 +164,7 @@ public class RNLuciqReactnativeModule extends EventEmitterModule {
 
 
     ) {
+        Log.d(NET_TAG, "[init] Called — logLevel=" + logLevel + ", useNativeNetworkInterception=" + useNativeNetworkInterception + ", codePushVersion=" + codePushVersion + ", appVariant=" + appVariant);
         MainThreadHandler.runOnMainThread(new Runnable() {
             @Override
             public void run() {
@@ -204,6 +206,7 @@ public class RNLuciqReactnativeModule extends EventEmitterModule {
                 }
 
                 builder.build();
+                Log.d(NET_TAG, "[init] SDK build complete");
             }
         });
     }
@@ -222,6 +225,26 @@ public class RNLuciqReactnativeModule extends EventEmitterModule {
         });
     }
 
+    /**
+     * Checks if the SDK is built or not.
+     *
+     * @param promise Promise that resolves with boolean indicating if enabled
+     */
+    @ReactMethod
+    public void isBuilt(final Promise promise) {
+        MainThreadHandler.runOnMainThread(new Runnable() {
+            @Override
+            public void run() {
+                try {
+                    promise.resolve(Luciq.isBuilt());
+                } catch (Exception e) {
+                    e.printStackTrace();
+                    promise.resolve(false);
+                }
+            }
+        });
+    }
+
     @ReactMethod
     public void setOverAirVersion(@Nullable final ReadableMap overAirVersion) {
         MainThreadHandler.runOnMainThread(new Runnable() {
@@ -949,6 +972,7 @@ public class RNLuciqReactnativeModule extends EventEmitterModule {
                                   final String requestHeaders,
                                   final String responseHeaders,
                                   final double duration) {
+        Log.d(NET_TAG, "[networkLogAndroid-Core] Received from JS: " + method + " " + url + ", status=" + (int) responseCode + ", duration=" + (long) duration + "ms, reqBodyLen=" + (requestBody != null ? requestBody.length() : 0) + ", resBodyLen=" + (responseBody != null ? responseBody.length() : 0));
         try {
             final String date = String.valueOf(System.currentTimeMillis());
 
@@ -965,11 +989,14 @@ public class RNLuciqReactnativeModule extends EventEmitterModule {
                 networkLog.setRequestHeaders(requestHeaders);
                 networkLog.setResponseHeaders(responseHeaders);
             } catch (OutOfMemoryError | Exception exception) {
+                Log.e(NET_TAG, "[networkLogAndroid-Core] OOM/Error setting log contents: " + exception.getMessage() + " for " + method + " " + url);
                 Log.d(TAG, "Error: " + exception.getMessage() + "while trying to set network log contents (request body, response body, request headers, and response headers).");
             }
 
             networkLog.insert();
+            Log.d(NET_TAG, "[networkLogAndroid-Core] Successfully inserted NetworkLog: " + method + " " + url);
         } catch (OutOfMemoryError | Exception exception) {
+            Log.e(NET_TAG, "[networkLogAndroid-Core] OOM/Error inserting network log: " + exception.getMessage() + " for " + method + " " + url);
             Log.d(TAG, "Error: " + exception.getMessage() + "while trying to insert a network log");
         }
     }
@@ -1150,7 +1177,7 @@ public class RNLuciqReactnativeModule extends EventEmitterModule {
      */
     @ReactMethod
     public void registerFeatureFlagsChangeListener() {
-
+        Log.d(NET_TAG, "[registerFeatureFlagsChangeListener] Registering native feature flags listener");
         MainThreadHandler.runOnMainThread(new Runnable() {
             @Override
             public void run() {
@@ -1158,6 +1185,7 @@ public class RNLuciqReactnativeModule extends EventEmitterModule {
                     InternalCore.INSTANCE._setFeaturesStateListener(new FeaturesStateListener() {
                         @Override
                         public void invoke(@NonNull CoreFeaturesState featuresState) {
+                            Log.d(NET_TAG, "[FeatureFlagsListener] Received update — W3CTraceID=" + featuresState.isW3CExternalTraceIdEnabled() + ", generatedHeader=" + featuresState.isAttachingGeneratedHeaderEnabled() + ", caughtHeader=" + featuresState.isAttachingCapturedHeaderEnabled() + ", networkBodyLimit=" + featuresState.getNetworkLogCharLimit());
                             WritableMap params = Arguments.createMap();
                             params.putBoolean("isW3ExternalTraceIDEnabled", featuresState.isW3CExternalTraceIdEnabled());
                             params.putBoolean("isW3ExternalGeneratedHeaderEnabled", featuresState.isAttachingGeneratedHeaderEnabled());
@@ -1165,9 +1193,11 @@ public class RNLuciqReactnativeModule extends EventEmitterModule {
                             params.putInt("networkBodyLimit",featuresState.getNetworkLogCharLimit());
 
                             sendEvent(Constants.LCQ_ON_FEATURE_FLAGS_UPDATE_RECEIVED_CALLBACK, params);
+                            Log.d(NET_TAG, "[FeatureFlagsListener] Sent event to JS: " + Constants.LCQ_ON_FEATURE_FLAGS_UPDATE_RECEIVED_CALLBACK);
                         }
                     });
                 } catch (Exception e) {
+                    Log.e(NET_TAG, "[registerFeatureFlagsChangeListener] Failed to register listener", e);
                     e.printStackTrace();
                 }
 
@@ -1182,13 +1212,16 @@ public class RNLuciqReactnativeModule extends EventEmitterModule {
      */
     @ReactMethod
     public void isW3ExternalTraceIDEnabled(Promise promise) {
-
+        Log.d(NET_TAG, "[isW3ExternalTraceIDEnabled] Querying native flag");
         MainThreadHandler.runOnMainThread(new Runnable() {
             @Override
             public void run() {
                 try {
-                    promise.resolve(InternalCore.INSTANCE._isFeatureEnabled(CoreFeature.W3C_EXTERNAL_TRACE_ID));
+                    boolean enabled = InternalCore.INSTANCE._isFeatureEnabled(CoreFeature.W3C_EXTERNAL_TRACE_ID);
+                    Log.d(NET_TAG, "[isW3ExternalTraceIDEnabled] Result=" + enabled);
+                    promise.resolve(enabled);
                 } catch (Exception e) {
+                    Log.e(NET_TAG, "[isW3ExternalTraceIDEnabled] Error querying flag", e);
                     e.printStackTrace();
                     promise.resolve(false);
                 }
@@ -1204,13 +1237,16 @@ public class RNLuciqReactnativeModule extends EventEmitterModule {
      */
     @ReactMethod
     public void isW3ExternalGeneratedHeaderEnabled(Promise promise) {
-
+        Log.d(NET_TAG, "[isW3ExternalGeneratedHeaderEnabled] Querying native flag");
         MainThreadHandler.runOnMainThread(new Runnable() {
             @Override
             public void run() {
                 try {
-                    promise.resolve(InternalCore.INSTANCE._isFeatureEnabled(CoreFeature.W3C_ATTACHING_GENERATED_HEADER));
+                    boolean enabled = InternalCore.INSTANCE._isFeatureEnabled(CoreFeature.W3C_ATTACHING_GENERATED_HEADER);
+                    Log.d(NET_TAG, "[isW3ExternalGeneratedHeaderEnabled] Result=" + enabled);
+                    promise.resolve(enabled);
                 } catch (Exception e) {
+                    Log.e(NET_TAG, "[isW3ExternalGeneratedHeaderEnabled] Error querying flag", e);
                     e.printStackTrace();
                     promise.resolve(false);
                 }
@@ -1225,13 +1261,16 @@ public class RNLuciqReactnativeModule extends EventEmitterModule {
      */
     @ReactMethod
     public void isW3CaughtHeaderEnabled(Promise promise) {
-
+        Log.d(NET_TAG, "[isW3CaughtHeaderEnabled] Querying native flag");
         MainThreadHandler.runOnMainThread(new Runnable() {
             @Override
             public void run() {
                 try {
-                    promise.resolve(InternalCore.INSTANCE._isFeatureEnabled(CoreFeature.W3C_ATTACHING_CAPTURED_HEADER));
+                    boolean enabled = InternalCore.INSTANCE._isFeatureEnabled(CoreFeature.W3C_ATTACHING_CAPTURED_HEADER);
+                    Log.d(NET_TAG, "[isW3CaughtHeaderEnabled] Result=" + enabled);
+                    promise.resolve(enabled);
                 } catch (Exception e) {
+                    Log.e(NET_TAG, "[isW3CaughtHeaderEnabled] Error querying flag", e);
                     e.printStackTrace();
                     promise.resolve(false);
                 }
@@ -1325,13 +1364,16 @@ public class RNLuciqReactnativeModule extends EventEmitterModule {
      */
     @ReactMethod
     public void getNetworkBodyMaxSize(Promise promise) {
-
+        Log.d(NET_TAG, "[getNetworkBodyMaxSize] Querying network body size limit");
         MainThreadHandler.runOnMainThread(new Runnable() {
             @Override
             public void run() {
                 try {
-                    promise.resolve(InternalCore.INSTANCE.get_networkLogCharLimit());
+                    Object limit = InternalCore.INSTANCE.get_networkLogCharLimit();
+                    Log.d(NET_TAG, "[getNetworkBodyMaxSize] Result=" + limit);
+                    promise.resolve(limit);
                 } catch (Exception e) {
+                    Log.e(NET_TAG, "[getNetworkBodyMaxSize] Error querying limit", e);
                     e.printStackTrace();
                     promise.resolve(false);
                 }

package/android/src/main/java/ai/luciq/reactlibrary/utils/EventEmitterModule.java

@@ -1,5 +1,7 @@
 package ai.luciq.reactlibrary.utils;
 
+import android.util.Log;
+
 import androidx.annotation.Nullable;
 import androidx.annotation.VisibleForTesting;
 
@@ -10,6 +12,7 @@ import com.facebook.react.bridge.WritableMap;
 import com.facebook.react.modules.core.DeviceEventManagerModule;
 
 public abstract class EventEmitterModule extends ReactContextBaseJavaModule {
+    private static final String NET_TAG = "LCQ-RN-NET";
     private int listenerCount = 0;
 
     public EventEmitterModule(ReactApplicationContext context) {
@@ -22,14 +25,18 @@ public abstract class EventEmitterModule extends ReactContextBaseJavaModule {
             getReactApplicationContext()
                     .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class)
                     .emit(event, params);
+        } else {
+            Log.w(NET_TAG, "[EventEmitter] Event DROPPED (no JS listeners): event=" + event + ", module=" + getName() + ", listenerCount=0");
         }
     }
 
     protected void addListener(String ignoredEvent) {
         listenerCount++;
+        Log.d(NET_TAG, "[EventEmitter] addListener — module=" + getName() + ", event=" + ignoredEvent + ", listenerCount=" + listenerCount);
     }
 
     protected void removeListeners(Integer count) {
         listenerCount -= count;
+        Log.d(NET_TAG, "[EventEmitter] removeListeners — module=" + getName() + ", removed=" + count + ", listenerCount=" + listenerCount);
     }
 }

package/dist/constants/Strings.d.ts

@@ -0,0 +1,9 @@
+export declare class LuciqStrings {
+    static readonly customSpanAPMDisabledMessage: string;
+    static readonly customSpanDisabled: string;
+    static readonly customSpanSDKNotInitializedMessage: string;
+    static readonly customSpanNameEmpty: string;
+    static readonly customSpanEndTimeBeforeStartTime: string;
+    static readonly customSpanNameTruncated: string;
+    static readonly customSpanLimitReached: string;
+}

package/dist/constants/Strings.js

@@ -0,0 +1,12 @@
+export class LuciqStrings {
+    static customSpanAPMDisabledMessage = 'APM is disabled, custom span not created. Please enable APM by following the instructions at this link:\n' +
+        'https://docs.luciq.ai/product-guides-and-integrations/product-guides/application-performance-monitoring';
+    static customSpanDisabled = 'Custom span is disabled, custom span not created. Please enable Custom Span by following the instructions at this link:\n' +
+        'https://docs.luciq.ai/product-guides-and-integrations/product-guides/application-performance-monitoring';
+    static customSpanSDKNotInitializedMessage = 'Luciq API was called before the SDK is built. To build it, first by following the instructions at this link:\n' +
+        'https://docs.luciq.ai/product-guides-and-integrations/product-guides/application-performance-monitoring';
+    static customSpanNameEmpty = 'Custom span name cannot be empty. Please provide a valid name for the custom span.';
+    static customSpanEndTimeBeforeStartTime = 'Custom span end time must be after start time. Please provide a valid start and end time for the custom span.';
+    static customSpanNameTruncated = 'Custom span name truncated to 150 characters';
+    static customSpanLimitReached = 'Maximum number of concurrent custom spans (100) reached. Please end some spans before starting new ones.';
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import type { LuciqConfig } from './models/LuciqConfig';
 import Report from './models/Report';
 import type { ThemeConfig } from './models/ThemeConfig';
+import { CustomSpan } from './models/CustomSpan';
 import * as APM from './modules/APM';
 import * as BugReporting from './modules/BugReporting';
 import * as CrashReporting from './modules/CrashReporting';
@@ -15,6 +16,6 @@ import * as Surveys from './modules/Surveys';
 import * as SessionReplay from './modules/SessionReplay';
 import type { SessionMetadata } from './models/SessionMetadata';
 export * from './utils/Enums';
-export { Report, APM, BugReporting, CrashReporting, FeatureRequests, NetworkLogger, SessionReplay, Replies, Surveys, ProactiveReportingConfigOptions, createProactiveReportingConfig, };
+export { Report, CustomSpan, APM, BugReporting, CrashReporting, FeatureRequests, NetworkLogger, SessionReplay, Replies, Surveys, ProactiveReportingConfigOptions, createProactiveReportingConfig, };
 export type { LuciqConfig, Survey, NetworkData, NetworkDataObfuscationHandler, SessionMetadata, ThemeConfig, };
 export default Luciq;

package/dist/index.js

@@ -1,4 +1,5 @@
 import Report from './models/Report';
+import { CustomSpan } from './models/CustomSpan';
 // Modules
 import * as APM from './modules/APM';
 import * as BugReporting from './modules/BugReporting';
@@ -11,5 +12,5 @@ import * as Replies from './modules/Replies';
 import * as Surveys from './modules/Surveys';
 import * as SessionReplay from './modules/SessionReplay';
 export * from './utils/Enums';
-export { Report, APM, BugReporting, CrashReporting, FeatureRequests, NetworkLogger, SessionReplay, Replies, Surveys, createProactiveReportingConfig, };
+export { Report, CustomSpan, APM, BugReporting, CrashReporting, FeatureRequests, NetworkLogger, SessionReplay, Replies, Surveys, createProactiveReportingConfig, };
 export default Luciq;

package/dist/models/CustomSpan.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Callback to unregister a span from tracking
+ */
+type UnregisterCallback = (span: CustomSpan) => void;
+/**
+ * Callback to sync span data to native SDK
+ */
+type SyncCallback = (name: string, startTimestamp: number, endTimestamp: number) => Promise<void>;
+/**
+ * Represents a custom span for performance tracking.
+ * A span measures the duration of an operation and reports it to the native SDK.
+ */
+export declare class CustomSpan {
+    private name;
+    private startTime;
+    private startMonotonic;
+    private endTime?;
+    private duration?;
+    private hasEnded;
+    private endPromise?;
+    private unregisterCallback;
+    private syncCallback;
+    /**
+     * Creates a new custom span. The span starts immediately upon creation.
+     * @internal - Use APM.startCustomSpan() instead
+     */
+    constructor(name: string, unregisterCallback: UnregisterCallback, syncCallback: SyncCallback);
+    /**
+     * Ends this custom span and reports it to the native SDK.
+     * This method is idempotent - calling it multiple times is safe.
+     * Subsequent calls will wait for the first call to complete.
+     */
+    end(): Promise<void>;
+    /**
+     * Get the span name
+     */
+    getName(): string;
+    /**
+     * Check if the span has ended
+     */
+    isEnded(): boolean;
+    /**
+     * Get the span duration in milliseconds (only available after end())
+     */
+    getDuration(): number | undefined;
+}
+export {};

package/dist/models/CustomSpan.js

@@ -0,0 +1,82 @@
+/**
+ * Represents a custom span for performance tracking.
+ * A span measures the duration of an operation and reports it to the native SDK.
+ */
+export class CustomSpan {
+    name;
+    startTime; // Date.now() in milliseconds
+    startMonotonic; // performance.now() in milliseconds
+    endTime;
+    duration;
+    hasEnded = false;
+    endPromise;
+    unregisterCallback;
+    syncCallback;
+    /**
+     * Creates a new custom span. The span starts immediately upon creation.
+     * @internal - Use APM.startCustomSpan() instead
+     */
+    constructor(name, unregisterCallback, syncCallback) {
+        this.name = name;
+        this.startTime = Date.now();
+        this.startMonotonic = performance.now();
+        this.unregisterCallback = unregisterCallback;
+        this.syncCallback = syncCallback;
+    }
+    /**
+     * Ends this custom span and reports it to the native SDK.
+     * This method is idempotent - calling it multiple times is safe.
+     * Subsequent calls will wait for the first call to complete.
+     */
+    async end() {
+        // Thread-safe check using Promise-based locking
+        if (this.hasEnded) {
+            if (this.endPromise) {
+                await this.endPromise;
+            }
+            return;
+        }
+        // Create lock and mark as ended
+        let resolveEnd;
+        this.endPromise = new Promise((resolve) => {
+            resolveEnd = resolve;
+        });
+        this.hasEnded = true;
+        try {
+            // Unregister from active spans
+            this.unregisterCallback(this);
+            // Calculate duration using monotonic clock
+            const endMonotonic = performance.now();
+            this.duration = endMonotonic - this.startMonotonic;
+            // Calculate end time using wall clock
+            this.endTime = this.startTime + this.duration;
+            // Convert to microseconds for native SDK
+            const startMicros = this.startTime * 1000;
+            const endMicros = this.endTime * 1000;
+            // Send to native SDK
+            await this.syncCallback(this.name, startMicros, endMicros);
+        }
+        finally {
+            // Release lock
+            resolveEnd();
+        }
+    }
+    /**
+     * Get the span name
+     */
+    getName() {
+        return this.name;
+    }
+    /**
+     * Check if the span has ended
+     */
+    isEnded() {
+        return this.hasEnded;
+    }
+    /**
+     * Get the span duration in milliseconds (only available after end())
+     */
+    getDuration() {
+        return this.duration;
+    }
+}

package/dist/modules/APM.d.ts

@@ -1,3 +1,4 @@
+import type { CustomSpan } from '../models/CustomSpan';
 /**
  * Enables or disables APM
  * @param isEnabled
@@ -80,3 +81,60 @@ export declare const _lcqSleep: () => void;
  * @param isEnabled
  */
 export declare const setScreenRenderingEnabled: (isEnabled: boolean) => void;
+/**
+ * Starts a custom span for performance tracking.
+ *
+ * A custom span measures the duration of an arbitrary operation that is not
+ * automatically tracked by the SDK. The span must be manually ended by calling
+ * the `end()` method on the returned span object.
+ *
+ * @param name - The name of the span. Cannot be empty. Max 150 characters.
+ *               Leading and trailing whitespace will be trimmed.
+ *
+ * @returns Promise<CustomSpan | null> - The span object to end later, or null if:
+ *   - Name is empty after trimming
+ *   - SDK is not initialized
+ *   - APM is disabled
+ *   - Custom spans feature is disabled
+ *   - Maximum concurrent spans limit (100) reached
+ *
+ * @example
+ * ```typescript
+ * const span = await APM.startCustomSpan('Load User Profile');
+ * if (span) {
+ *   try {
+ *     // ... perform operation ...
+ *   } finally {
+ *     await span.end();
+ *   }
+ * }
+ * ```
+ */
+export declare const startCustomSpan: (name: string) => Promise<CustomSpan | null>;
+/**
+ * Records a completed custom span with pre-recorded timestamps.
+ *
+ * Use this method when you have already recorded the start and end times
+ * of an operation and want to report it retroactively.
+ *
+ * @param name - The name of the span. Cannot be empty. Max 150 characters.
+ *               Leading and trailing whitespace will be trimmed.
+ * @param startDate - The start time of the operation
+ * @param endDate - The end time of the operation (must be after startDate)
+ *
+ * @returns Promise<void> - Resolves when the span has been recorded, or logs error if:
+ *   - Name is empty after trimming
+ *   - End date is not after start date
+ *   - SDK is not initialized
+ *   - APM is disabled
+ *   - Custom spans feature is disabled
+ *
+ * @example
+ * ```typescript
+ * const start = new Date();
+ * // ... operation already completed ...
+ * const end = new Date();
+ * await APM.addCompletedCustomSpan('Cache Lookup', start, end);
+ * ```
+ */
+export declare const addCompletedCustomSpan: (name: string, startDate: Date, endDate: Date) => Promise<void>;

package/dist/modules/APM.js

@@ -1,6 +1,7 @@
 import { Platform } from 'react-native';
 import { NativeAPM } from '../native/NativeAPM';
 import { NativeLuciq } from '../native/NativeLuciq';
+import { startCustomSpan as startCustomSpanInternal, addCompletedCustomSpan as addCompletedCustomSpanInternal, } from '../utils/CustomSpansManager';
 /**
  * Enables or disables APM
  * @param isEnabled
@@ -109,3 +110,64 @@ export const _lcqSleep = () => {
 export const setScreenRenderingEnabled = (isEnabled) => {
     NativeAPM.setScreenRenderingEnabled(isEnabled);
 };
+/**
+ * Starts a custom span for performance tracking.
+ *
+ * A custom span measures the duration of an arbitrary operation that is not
+ * automatically tracked by the SDK. The span must be manually ended by calling
+ * the `end()` method on the returned span object.
+ *
+ * @param name - The name of the span. Cannot be empty. Max 150 characters.
+ *               Leading and trailing whitespace will be trimmed.
+ *
+ * @returns Promise<CustomSpan | null> - The span object to end later, or null if:
+ *   - Name is empty after trimming
+ *   - SDK is not initialized
+ *   - APM is disabled
+ *   - Custom spans feature is disabled
+ *   - Maximum concurrent spans limit (100) reached
+ *
+ * @example
+ * ```typescript
+ * const span = await APM.startCustomSpan('Load User Profile');
+ * if (span) {
+ *   try {
+ *     // ... perform operation ...
+ *   } finally {
+ *     await span.end();
+ *   }
+ * }
+ * ```
+ */
+export const startCustomSpan = async (name) => {
+    return startCustomSpanInternal(name);
+};
+/**
+ * Records a completed custom span with pre-recorded timestamps.
+ *
+ * Use this method when you have already recorded the start and end times
+ * of an operation and want to report it retroactively.
+ *
+ * @param name - The name of the span. Cannot be empty. Max 150 characters.
+ *               Leading and trailing whitespace will be trimmed.
+ * @param startDate - The start time of the operation
+ * @param endDate - The end time of the operation (must be after startDate)
+ *
+ * @returns Promise<void> - Resolves when the span has been recorded, or logs error if:
+ *   - Name is empty after trimming
+ *   - End date is not after start date
+ *   - SDK is not initialized
+ *   - APM is disabled
+ *   - Custom spans feature is disabled
+ *
+ * @example
+ * ```typescript
+ * const start = new Date();
+ * // ... operation already completed ...
+ * const end = new Date();
+ * await APM.addCompletedCustomSpan('Cache Lookup', start, end);
+ * ```
+ */
+export const addCompletedCustomSpan = async (name, startDate, endDate) => {
+    return addCompletedCustomSpanInternal(name, startDate, endDate);
+};