@datalyr/api 1.0.4 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @datalyr/api
 
-Official API SDK for Datalyr server-side tracking.
+Official API SDK for Datalyr server-side tracking with identity resolution support.
 
 ## Installation
 
@@ -52,6 +52,57 @@ await datalyr.group('user_123', 'company_456', {
 await datalyr.close();
 ```
 
+## Identity Resolution (New in v1.1.0)
+
+The SDK now supports anonymous IDs for complete user journey tracking:
+
+```javascript
+// Option 1: Pass anonymous_id from browser/mobile for attribution preservation
+await datalyr.track({
+  event: 'Purchase Completed',
+  userId: 'user_123',
+  anonymousId: req.body.anonymous_id,  // From browser/mobile SDK
+  properties: {
+    amount: 99.99,
+    currency: 'USD'
+  }
+});
+
+// Option 2: Use legacy signature (SDK generates anonymous_id)
+await datalyr.track('user_123', 'Purchase Completed', {
+  amount: 99.99
+});
+
+// Get the SDK's anonymous ID (useful for server-only tracking)
+const anonymousId = datalyr.getAnonymousId();
+```
+
+### Express.js Example with Browser Attribution
+
+```javascript
+app.post('/api/purchase', async (req, res) => {
+  const { items, anonymous_id } = req.body;  // anonymous_id from browser
+  
+  // Track with anonymous_id to preserve attribution (fbclid, gclid, etc.)
+  await datalyr.track({
+    event: 'Purchase Completed',
+    userId: req.user?.id,
+    anonymousId: anonymous_id,  // Links to browser events!
+    properties: {
+      total: calculateTotal(items),
+      items: items.length
+    }
+  });
+  
+  res.json({ success: true });
+});
+```
+
+### Key Benefits:
+- **Attribution Preservation**: Never lose fbclid, gclid, ttclid, or lyr tracking
+- **Complete Journey**: Track users from web → server → mobile
+- **Flexible API**: Support both legacy and new tracking methods
+
 ## Configuration
 
 ```javascript

package/dist/index.d.mts

@@ -16,6 +16,12 @@ interface TrackEvent {
     context?: Record<string, any>;
     timestamp?: string;
 }
+interface TrackOptions {
+    userId?: string;
+    anonymousId?: string;
+    event: string;
+    properties?: Record<string, any>;
+}
 declare class Datalyr {
     private apiKey;
     private host;
@@ -29,7 +35,9 @@ declare class Datalyr {
     private timer?;
     private isFlushing;
     private isClosing;
+    private anonymousId?;
     constructor(config: DatalyrConfig | string);
+    track(options: TrackOptions): Promise<void>;
     track(userId: string | null, event: string, properties?: any): Promise<void>;
     identify(userId: string, traits?: any): Promise<void>;
     page(userId: string, name?: string, properties?: any): Promise<void>;
@@ -39,7 +47,9 @@ declare class Datalyr {
     private sendEvent;
     private startFlushTimer;
     private generateAnonymousId;
+    private getOrCreateAnonymousId;
+    getAnonymousId(): string;
     close(): Promise<void>;
 }
 
-export { Datalyr, type DatalyrConfig, type TrackEvent, Datalyr as default };
+export { Datalyr, type DatalyrConfig, type TrackEvent, type TrackOptions, Datalyr as default };

package/dist/index.d.ts

@@ -16,6 +16,12 @@ interface TrackEvent {
     context?: Record<string, any>;
     timestamp?: string;
 }
+interface TrackOptions {
+    userId?: string;
+    anonymousId?: string;
+    event: string;
+    properties?: Record<string, any>;
+}
 declare class Datalyr {
     private apiKey;
     private host;
@@ -29,7 +35,9 @@ declare class Datalyr {
     private timer?;
     private isFlushing;
     private isClosing;
+    private anonymousId?;
     constructor(config: DatalyrConfig | string);
+    track(options: TrackOptions): Promise<void>;
     track(userId: string | null, event: string, properties?: any): Promise<void>;
     identify(userId: string, traits?: any): Promise<void>;
     page(userId: string, name?: string, properties?: any): Promise<void>;
@@ -39,7 +47,9 @@ declare class Datalyr {
     private sendEvent;
     private startFlushTimer;
     private generateAnonymousId;
+    private getOrCreateAnonymousId;
+    getAnonymousId(): string;
     close(): Promise<void>;
 }
 
-export { Datalyr, type DatalyrConfig, type TrackEvent, Datalyr as default };
+export { Datalyr, type DatalyrConfig, type TrackEvent, type TrackOptions, Datalyr as default };

package/dist/index.js

@@ -25,6 +25,7 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 var Datalyr = class {
+  // Persistent anonymous ID for identity resolution
   constructor(config) {
     this.queue = [];
     this.isFlushing = false;
@@ -62,21 +63,41 @@ var Datalyr = class {
     if (this.maxQueueSize > 1e4) this.maxQueueSize = 1e4;
     this.startFlushTimer();
   }
-  async track(userId, event, properties) {
+  async track(userIdOrOptions, event, properties) {
     if (this.isClosing) {
       if (this.debug) {
-        console.warn("[Datalyr] SDK is closing, event dropped:", event);
+        console.warn("[Datalyr] SDK is closing, event dropped");
       }
       return;
     }
-    if (!event || typeof event !== "string") {
+    let userId;
+    let eventName;
+    let eventProperties;
+    let providedAnonymousId;
+    if (typeof userIdOrOptions === "object" && userIdOrOptions !== null) {
+      userId = userIdOrOptions.userId;
+      eventName = userIdOrOptions.event;
+      eventProperties = userIdOrOptions.properties || {};
+      providedAnonymousId = userIdOrOptions.anonymousId;
+    } else {
+      userId = userIdOrOptions || void 0;
+      eventName = event;
+      eventProperties = properties || {};
+    }
+    if (!eventName || typeof eventName !== "string") {
       throw new Error("Event name is required and must be a string");
     }
+    const anonymousId = providedAnonymousId || this.getOrCreateAnonymousId();
+    const enrichedProperties = {
+      ...eventProperties,
+      anonymous_id: anonymousId
+    };
     const trackEvent = {
       userId: userId || void 0,
-      anonymousId: userId ? void 0 : this.generateAnonymousId(),
-      event,
-      properties: properties || {},
+      anonymousId,
+      // Always include for identity resolution
+      event: eventName,
+      properties: enrichedProperties,
       context: {
         library: "@datalyr/api",
         version: "1.0.4",
@@ -91,7 +112,10 @@ var Datalyr = class {
     if (!userId) {
       throw new Error("userId is required for identify");
     }
-    return this.track(userId, "$identify", { $set: traits });
+    return this.track(userId, "$identify", {
+      $set: traits,
+      anonymous_id: this.getOrCreateAnonymousId()
+    });
   }
   async page(userId, name, properties) {
     return this.track(userId, "$pageview", { name, ...properties });
@@ -219,6 +243,15 @@ var Datalyr = class {
   generateAnonymousId() {
     return "anon_" + Math.random().toString(36).substring(2) + Date.now().toString(36);
   }
+  getOrCreateAnonymousId() {
+    if (!this.anonymousId) {
+      this.anonymousId = this.generateAnonymousId();
+    }
+    return this.anonymousId;
+  }
+  getAnonymousId() {
+    return this.getOrCreateAnonymousId();
+  }
   // Cleanup
   async close() {
     this.isClosing = true;

package/dist/index.mjs

@@ -1,5 +1,6 @@
 // src/index.ts
 var Datalyr = class {
+  // Persistent anonymous ID for identity resolution
   constructor(config) {
     this.queue = [];
     this.isFlushing = false;
@@ -37,21 +38,41 @@ var Datalyr = class {
     if (this.maxQueueSize > 1e4) this.maxQueueSize = 1e4;
     this.startFlushTimer();
   }
-  async track(userId, event, properties) {
+  async track(userIdOrOptions, event, properties) {
     if (this.isClosing) {
       if (this.debug) {
-        console.warn("[Datalyr] SDK is closing, event dropped:", event);
+        console.warn("[Datalyr] SDK is closing, event dropped");
       }
       return;
     }
-    if (!event || typeof event !== "string") {
+    let userId;
+    let eventName;
+    let eventProperties;
+    let providedAnonymousId;
+    if (typeof userIdOrOptions === "object" && userIdOrOptions !== null) {
+      userId = userIdOrOptions.userId;
+      eventName = userIdOrOptions.event;
+      eventProperties = userIdOrOptions.properties || {};
+      providedAnonymousId = userIdOrOptions.anonymousId;
+    } else {
+      userId = userIdOrOptions || void 0;
+      eventName = event;
+      eventProperties = properties || {};
+    }
+    if (!eventName || typeof eventName !== "string") {
       throw new Error("Event name is required and must be a string");
     }
+    const anonymousId = providedAnonymousId || this.getOrCreateAnonymousId();
+    const enrichedProperties = {
+      ...eventProperties,
+      anonymous_id: anonymousId
+    };
     const trackEvent = {
       userId: userId || void 0,
-      anonymousId: userId ? void 0 : this.generateAnonymousId(),
-      event,
-      properties: properties || {},
+      anonymousId,
+      // Always include for identity resolution
+      event: eventName,
+      properties: enrichedProperties,
       context: {
         library: "@datalyr/api",
         version: "1.0.4",
@@ -66,7 +87,10 @@ var Datalyr = class {
     if (!userId) {
       throw new Error("userId is required for identify");
     }
-    return this.track(userId, "$identify", { $set: traits });
+    return this.track(userId, "$identify", {
+      $set: traits,
+      anonymous_id: this.getOrCreateAnonymousId()
+    });
   }
   async page(userId, name, properties) {
     return this.track(userId, "$pageview", { name, ...properties });
@@ -194,6 +218,15 @@ var Datalyr = class {
   generateAnonymousId() {
     return "anon_" + Math.random().toString(36).substring(2) + Date.now().toString(36);
   }
+  getOrCreateAnonymousId() {
+    if (!this.anonymousId) {
+      this.anonymousId = this.generateAnonymousId();
+    }
+    return this.anonymousId;
+  }
+  getAnonymousId() {
+    return this.getOrCreateAnonymousId();
+  }
   // Cleanup
   async close() {
     this.isClosing = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datalyr/api",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "Datalyr API SDK for server-side tracking",
   "main": "dist/index.js",
   "module": "dist/index.mjs",