@luciq/react-native 19.2.2 → 19.3.0

package/scripts/releases/get_slack_id_from_username.sh

@@ -0,0 +1,24 @@
+github_username=$1
+
+case $github_username in
+    'mzelzoghbi')
+        sid='U5697F4EL'
+        ;;
+    'AndrewAminInstabug')
+        sid='U06JVRNMKE1'
+        ;;
+    'ahmedAlaaInstabug')
+        sid='U06AE2G1161'
+        ;;
+    'kholood-ea')
+        sid='U06SU2QR280'
+        ;;
+   'AyaMahmoud148')
+        sid='U07GZSURC8K'
+        ;;
+    'MoKamall')
+        sid='U06JHDS3JJK'
+        ;;
+    *)
+esac
+echo "$sid"

package/src/constants/Strings.ts

@@ -0,0 +1,24 @@
+export class LuciqStrings {
+  static readonly customSpanAPMDisabledMessage: string =
+    '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 readonly customSpanDisabled: string =
+    '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 readonly customSpanSDKNotInitializedMessage: string =
+    '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 readonly customSpanNameEmpty: string =
+    'Custom span name cannot be empty. Please provide a valid name for the custom span.';
+
+  static readonly customSpanEndTimeBeforeStartTime: string =
+    'Custom span end time must be after start time. Please provide a valid start and end time for the custom span.';
+
+  static readonly customSpanNameTruncated: string = 'Custom span name truncated to 150 characters';
+
+  static readonly customSpanLimitReached: string =
+    'Maximum number of concurrent custom spans (100) reached. Please end some spans before starting new ones.';
+}

package/src/index.ts

@@ -2,6 +2,7 @@
 import type { LuciqConfig } from './models/LuciqConfig';
 import Report from './models/Report';
 import type { ThemeConfig } from './models/ThemeConfig';
+import { CustomSpan } from './models/CustomSpan';
 // Modules
 import * as APM from './modules/APM';
 import * as BugReporting from './modules/BugReporting';
@@ -23,6 +24,7 @@ import type { SessionMetadata } from './models/SessionMetadata';
 export * from './utils/Enums';
 export {
   Report,
+  CustomSpan,
   APM,
   BugReporting,
   CrashReporting,

package/src/models/CustomSpan.ts

@@ -0,0 +1,102 @@
+/**
+ * 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 class CustomSpan {
+  private name: string;
+  private startTime: number; // Date.now() in milliseconds
+  private startMonotonic: number; // performance.now() in milliseconds
+  private endTime?: number;
+  private duration?: number;
+  private hasEnded: boolean = false;
+  private endPromise?: Promise<void>;
+  private unregisterCallback: UnregisterCallback;
+  private syncCallback: SyncCallback;
+
+  /**
+   * Creates a new custom span. The span starts immediately upon creation.
+   * @internal - Use APM.startCustomSpan() instead
+   */
+  constructor(name: string, unregisterCallback: UnregisterCallback, syncCallback: 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(): Promise<void> {
+    // 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: () => void;
+    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(): string {
+    return this.name;
+  }
+
+  /**
+   * Check if the span has ended
+   */
+  isEnded(): boolean {
+    return this.hasEnded;
+  }
+
+  /**
+   * Get the span duration in milliseconds (only available after end())
+   */
+  getDuration(): number | undefined {
+    return this.duration;
+  }
+}

package/src/modules/APM.ts

@@ -2,6 +2,11 @@ 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';
+import type { CustomSpan } from '../models/CustomSpan';
 
 /**
  * Enables or disables APM
@@ -123,3 +128,70 @@ export const _lcqSleep = () => {
 export const setScreenRenderingEnabled = (isEnabled: boolean) => {
   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: string): Promise<CustomSpan | null> => {
+  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: string,
+  startDate: Date,
+  endDate: Date,
+): Promise<void> => {
+  return addCompletedCustomSpanInternal(name, startDate, endDate);
+};

package/src/native/NativeAPM.ts

@@ -47,6 +47,13 @@ export interface ApmNativeModule extends NativeModule {
 
   // Screen Rendering //
   setScreenRenderingEnabled(isEnabled: boolean): void;
+
+  // Custom Spans APIs //
+  syncCustomSpan(name: string, startTimestamp: number, endTimestamp: number): Promise<void>;
+
+  isCustomSpanEnabled(): Promise<boolean>;
+
+  isAPMEnabled(): Promise<boolean>;
 }
 
 export const NativeAPM = NativeModules.LCQAPM;

package/src/native/NativeLuciq.ts

@@ -22,6 +22,7 @@ export interface LuciqNativeModule extends NativeModule {
 
   // Essential APIs //
   setEnabled(isEnabled: boolean): void;
+  isBuilt(): Promise<boolean>;
   init(
     token: string,
     invocationEvents: InvocationEvent[],

package/src/utils/CustomSpansManager.ts

@@ -0,0 +1,202 @@
+import { NativeAPM } from '../native/NativeAPM';
+import { NativeLuciq } from '../native/NativeLuciq';
+import { CustomSpan } from '../models/CustomSpan';
+import { LuciqStrings } from '../constants/Strings';
+
+/**
+ * Tracks currently active custom spans
+ * @internal
+ */
+const activeSpans = new Set<CustomSpan>();
+
+/**
+ * Maximum concurrent custom spans allowed at any time
+ * @internal
+ */
+const MAX_CONCURRENT_SPANS = 100;
+
+/**
+ * Internal: unregister a span from active tracking
+ * @internal
+ */
+const unregisterSpan = (span: CustomSpan): void => {
+  activeSpans.delete(span);
+};
+
+/**
+ * Internal: sync custom span data to native SDK
+ * @internal
+ */
+const syncCustomSpan = async (
+  name: string,
+  startTimestamp: number,
+  endTimestamp: number,
+): Promise<void> => {
+  // Validate inputs (safety net)
+  if (!name || name.trim().length === 0) {
+    console.error(LuciqStrings.customSpanNameEmpty);
+    return;
+  }
+
+  if (endTimestamp <= startTimestamp) {
+    console.error(LuciqStrings.customSpanEndTimeBeforeStartTime);
+    return;
+  }
+
+  // Truncate name if needed (safety net)
+  let spanName = name.trim();
+  if (spanName.length > 150) {
+    spanName = spanName.substring(0, 150);
+  }
+
+  await NativeAPM.syncCustomSpan(spanName, startTimestamp, endTimestamp);
+};
+
+/**
+ * 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
+ */
+export const startCustomSpan = async (name: string): Promise<CustomSpan | null> => {
+  try {
+    // Validate name
+    const trimmedName = name.trim();
+    if (trimmedName.length === 0) {
+      console.error(LuciqStrings.customSpanNameEmpty);
+      return null;
+    }
+
+    // Check SDK initialization
+    const isInitialized = await NativeLuciq.isBuilt();
+    if (!isInitialized) {
+      console.error(LuciqStrings.customSpanSDKNotInitializedMessage);
+      return null;
+    }
+
+    // Check APM enabled
+    const isAPMEnabled = await NativeAPM.isAPMEnabled();
+    if (!isAPMEnabled) {
+      console.log(LuciqStrings.customSpanAPMDisabledMessage);
+      return null;
+    }
+
+    // Check custom spans enabled
+    const isCustomSpanEnabled = await NativeAPM.isCustomSpanEnabled();
+    if (!isCustomSpanEnabled) {
+      console.log(LuciqStrings.customSpanDisabled);
+      return null;
+    }
+
+    // Check concurrent span limit
+    if (activeSpans.size >= MAX_CONCURRENT_SPANS) {
+      console.error(LuciqStrings.customSpanLimitReached);
+      return null;
+    }
+
+    // Truncate name if needed
+    let spanName = trimmedName;
+    if (spanName.length > 150) {
+      spanName = spanName.substring(0, 150);
+      console.log(LuciqStrings.customSpanNameTruncated);
+    }
+
+    // Create and register span with callbacks
+    const span = new CustomSpan(spanName, unregisterSpan, syncCustomSpan);
+    activeSpans.add(span);
+    return span;
+  } catch (error) {
+    console.error('[CustomSpan] Error starting span:', error);
+    return 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>
+ */
+export const addCompletedCustomSpan = async (
+  name: string,
+  startDate: Date,
+  endDate: Date,
+): Promise<void> => {
+  try {
+    // Validate name
+    const trimmedName = name.trim();
+    if (trimmedName.length === 0) {
+      console.error(LuciqStrings.customSpanNameEmpty);
+      return;
+    }
+
+    // Validate timestamps
+    if (endDate <= startDate) {
+      console.error(LuciqStrings.customSpanEndTimeBeforeStartTime);
+      return;
+    }
+
+    // Check SDK initialization
+    const isInitialized = await NativeLuciq.isBuilt();
+    if (!isInitialized) {
+      console.error(LuciqStrings.customSpanSDKNotInitializedMessage);
+      return;
+    }
+
+    // Check APM enabled
+    const isAPMEnabled = await NativeAPM.isAPMEnabled();
+    if (!isAPMEnabled) {
+      console.log(LuciqStrings.customSpanAPMDisabledMessage);
+      return;
+    }
+
+    // Check custom spans enabled
+    const isCustomSpanEnabled = await NativeAPM.isCustomSpanEnabled();
+    if (!isCustomSpanEnabled) {
+      console.log(LuciqStrings.customSpanDisabled);
+      return;
+    }
+
+    // Truncate name if needed
+    let spanName = trimmedName;
+    if (spanName.length > 150) {
+      spanName = spanName.substring(0, 150);
+      console.log(LuciqStrings.customSpanNameTruncated);
+    }
+
+    // Convert to microseconds
+    const startMicros = startDate.getTime() * 1000;
+    const endMicros = endDate.getTime() * 1000;
+
+    // Send to native SDK
+    await syncCustomSpan(spanName, startMicros, endMicros);
+  } catch (error) {
+    console.error('[CustomSpan] Error adding completed span:', error);
+  }
+};
+
+/**
+ * Test-only helper to clear active spans between tests.
+ * @internal
+ */
+export const __resetCustomSpansForTests = (): void => {
+  activeSpans.clear();
+};