@loamly/tracker 2.1.0 → 2.4.0

package/dist/index.d.mts

@@ -67,6 +67,8 @@ declare function createAgenticAnalyzer(): AgenticBrowserAnalyzer;
 interface LoamlyConfig {
     /** Your Loamly API key (found in dashboard) */
     apiKey?: string;
+    /** Workspace ID (required when using public tracker key) */
+    workspaceId?: string;
     /** Custom API host (default: https://app.loamly.ai) */
     apiHost?: string;
     /** Enable debug mode for console logging */
@@ -165,6 +167,22 @@ interface LoamlyTracker {
     pageview: (url?: string) => void;
     /** Track a custom event */
     track: (eventName: string, options?: TrackEventOptions) => void;
+    /**
+     * Track a behavioral event (for secondary modules/plugins)
+     *
+     * This is the recommended way for secondary tracking modules to send events.
+     * It automatically includes workspace_id, visitor_id, session_id, and handles
+     * batching, queueing, and retry logic.
+     *
+     * @example
+     * ```js
+     * Loamly.trackBehavioral('outbound_click', {
+     *   url: 'https://example.com',
+     *   text: 'Click here'
+     * });
+     * ```
+     */
+    trackBehavioral: (eventType: string, eventData: Record<string, unknown>) => void;
     /** Track a conversion/revenue event */
     conversion: (eventName: string, revenue: number, currency?: string) => void;
     /** Identify a user (for linking sessions) */
@@ -173,6 +191,8 @@ interface LoamlyTracker {
     getSessionId: () => string | null;
     /** Get the current visitor ID */
     getVisitorId: () => string | null;
+    /** Get the current workspace ID */
+    getWorkspaceId: () => string | null;
     /** Get AI detection result for current page */
     getAIDetection: () => AIDetectionResult | null;
     /** Get navigation timing analysis */
@@ -214,6 +234,8 @@ interface LoamlyTracker {
 declare const loamly: LoamlyTracker & {
     getAgentic: () => AgenticDetectionResult | null;
     reportHealth: (status: 'initialized' | 'error' | 'ready', errorMessage?: string) => void;
+    trackBehavioral: (eventType: string, eventData: Record<string, unknown>) => void;
+    getWorkspaceId: () => string | null;
 };
 
 /**
@@ -270,7 +292,7 @@ declare function detectAIFromUTM(url: string): AIDetectionResult | null;
  * @license MIT
  * @see https://github.com/loamly/loamly
  */
-declare const VERSION = "2.1.0";
+declare const VERSION = "2.4.0";
 /**
  * Known AI platforms for referrer detection
  */

package/dist/index.d.ts

@@ -67,6 +67,8 @@ declare function createAgenticAnalyzer(): AgenticBrowserAnalyzer;
 interface LoamlyConfig {
     /** Your Loamly API key (found in dashboard) */
     apiKey?: string;
+    /** Workspace ID (required when using public tracker key) */
+    workspaceId?: string;
     /** Custom API host (default: https://app.loamly.ai) */
     apiHost?: string;
     /** Enable debug mode for console logging */
@@ -165,6 +167,22 @@ interface LoamlyTracker {
     pageview: (url?: string) => void;
     /** Track a custom event */
     track: (eventName: string, options?: TrackEventOptions) => void;
+    /**
+     * Track a behavioral event (for secondary modules/plugins)
+     *
+     * This is the recommended way for secondary tracking modules to send events.
+     * It automatically includes workspace_id, visitor_id, session_id, and handles
+     * batching, queueing, and retry logic.
+     *
+     * @example
+     * ```js
+     * Loamly.trackBehavioral('outbound_click', {
+     *   url: 'https://example.com',
+     *   text: 'Click here'
+     * });
+     * ```
+     */
+    trackBehavioral: (eventType: string, eventData: Record<string, unknown>) => void;
     /** Track a conversion/revenue event */
     conversion: (eventName: string, revenue: number, currency?: string) => void;
     /** Identify a user (for linking sessions) */
@@ -173,6 +191,8 @@ interface LoamlyTracker {
     getSessionId: () => string | null;
     /** Get the current visitor ID */
     getVisitorId: () => string | null;
+    /** Get the current workspace ID */
+    getWorkspaceId: () => string | null;
     /** Get AI detection result for current page */
     getAIDetection: () => AIDetectionResult | null;
     /** Get navigation timing analysis */
@@ -214,6 +234,8 @@ interface LoamlyTracker {
 declare const loamly: LoamlyTracker & {
     getAgentic: () => AgenticDetectionResult | null;
     reportHealth: (status: 'initialized' | 'error' | 'ready', errorMessage?: string) => void;
+    trackBehavioral: (eventType: string, eventData: Record<string, unknown>) => void;
+    getWorkspaceId: () => string | null;
 };
 
 /**
@@ -270,7 +292,7 @@ declare function detectAIFromUTM(url: string): AIDetectionResult | null;
  * @license MIT
  * @see https://github.com/loamly/loamly
  */
-declare const VERSION = "2.1.0";
+declare const VERSION = "2.4.0";
 /**
  * Known AI platforms for referrer detection
  */