@datalyr/api 1.2.0 → 1.2.2

package/README.md

@@ -1,195 +1,346 @@
 # @datalyr/api
 
-Official API SDK for Datalyr server-side tracking with identity resolution support.
+Server-side analytics and attribution SDK for Node.js. Track events, identify users, and preserve attribution data from your backend.
 
 ## Installation
 
 ```bash
 npm install @datalyr/api
-# or
-yarn add @datalyr/api
-# or
-pnpm add @datalyr/api
 ```
 
 ## Quick Start
 
 ```javascript
-const { Datalyr } = require('@datalyr/api');
-// or
 import { Datalyr } from '@datalyr/api';
 
-// Initialize with your API key
-const datalyr = new Datalyr('your_api_key_here');
+// String shorthand
+const datalyr = new Datalyr('dk_your_api_key');
+
+// Or with config object
+const datalyr = new Datalyr({
+  apiKey: 'dk_your_api_key',
+  debug: true,
+});
 
 // Track an event
+await datalyr.track('user_123', 'signup_completed', { plan: 'pro' });
+
+// Identify a user
+await datalyr.identify('user_123', { email: 'user@example.com' });
+
+// Flush and shut down
+await datalyr.close();
+```
+
+## Configuration
+
+The constructor accepts a `DatalyrConfig` object or an API key string.
+
+```javascript
+// Config object
+const datalyr = new Datalyr({
+  apiKey: 'dk_...',           // Required. Must start with "dk_".
+  host: 'https://ingest.datalyr.com/track',  // API endpoint (default: 'https://ingest.datalyr.com/track')
+  flushAt: 20,                // Flush when queue reaches this size (default: 20, range: 1-100)
+  flushInterval: 10000,       // Flush timer interval in ms (default: 10000)
+  debug: false,               // Log events and errors to console (default: false)
+  timeout: 10000,             // HTTP request timeout in ms (default: 10000, range: 1000-60000)
+  retryLimit: 3,              // Max retries for failed requests (default: 3)
+  maxQueueSize: 1000,         // Max queued events before dropping oldest (default: 1000, range: 100-10000)
+});
+
+// String shorthand — uses all defaults
+const datalyr = new Datalyr('dk_your_api_key');
+```
+
+## Methods
+
+### track()
+
+Two call signatures:
+
+```javascript
+// Object form (TrackOptions)
+await datalyr.track({
+  event: 'Purchase Completed',     // Required
+  userId: 'user_123',              // Optional
+  anonymousId: 'anon_from_browser', // Optional — override the auto-generated anonymous ID
+  properties: {                    // Optional
+    amount: 99.99,
+    currency: 'USD',
+  },
+});
+
+// Legacy form
 await datalyr.track('user_123', 'Purchase Completed', {
   amount: 99.99,
   currency: 'USD',
-  products: ['item_1', 'item_2']
 });
 
-// Identify a user
+// Pass null as userId for anonymous events
+await datalyr.track(null, 'page_loaded', { url: '/pricing' });
+```
+
+### identify()
+
+```javascript
+await datalyr.identify(userId: string, traits?: any);
+```
+
+Links a user ID to traits. Internally sends a `$identify` event.
+
+```javascript
 await datalyr.identify('user_123', {
   email: 'user@example.com',
-  name: 'John Doe',
-  plan: 'premium'
+  name: 'Jane Doe',
+  plan: 'premium',
 });
+```
 
-// Track a pageview
-await datalyr.page('user_123', 'Homepage', {
-  url: 'https://example.com',
-  referrer: 'https://google.com'
+### page()
+
+```javascript
+await datalyr.page(userId: string, name?: string, properties?: any);
+```
+
+Track a page view. Internally sends a `$pageview` event.
+
+```javascript
+await datalyr.page('user_123', 'Pricing', {
+  url: 'https://example.com/pricing',
+  referrer: 'https://google.com',
 });
+```
 
-// Group a user
+### group()
+
+```javascript
+await datalyr.group(userId: string, groupId: string, traits?: any);
+```
+
+Associate a user with a group (company, team, etc.). Internally sends a `$group` event.
+
+```javascript
 await datalyr.group('user_123', 'company_456', {
   name: 'Acme Corp',
-  industry: 'Technology'
+  industry: 'Technology',
+  employees: 50,
 });
+```
 
-// Clean up when done
-await datalyr.close();
+### flush()
+
+Send all queued events immediately.
+
+```javascript
+await datalyr.flush();
+```
+
+### close()
+
+Stops the flush timer, then attempts a final flush with a **5-second timeout**. Any events still queued after the timeout are dropped. New events tracked after `close()` is called are silently ignored.
+
+```javascript
+process.on('SIGTERM', async () => {
+  await datalyr.close();
+  process.exit(0);
+});
+```
+
+### getAnonymousId()
+
+Returns the SDK instance's persistent anonymous ID. The ID is generated lazily on first use and has the format `anon_<random><timestamp>` (e.g., `anon_k7x2m9f1lxyzabc`).
+
+```javascript
+const anonId = datalyr.getAnonymousId();
 ```
 
-## Identity Resolution (New in v1.1.0)
+## Event Payload
 
-The SDK now supports anonymous IDs for complete user journey tracking:
+Every event sent to the API has this structure:
+
+```javascript
+{
+  event: 'Purchase Completed',
+  userId: 'user_123',              // undefined if not provided
+  anonymousId: 'anon_k7x2m9f...',  // Always present
+  properties: {
+    amount: 99.99,
+    anonymous_id: 'anon_k7x2m9f...',  // Automatically added
+  },
+  context: {
+    library: '@datalyr/api',
+    version: '1.2.1',
+    source: 'api',
+  },
+  timestamp: '2025-01-15T10:30:00.000Z',
+}
+```
+
+Notes:
+- `anonymous_id` is automatically added to `properties` on every event for attribution.
+- The `context` object identifies the SDK and version.
+- `timestamp` is set to the ISO 8601 time when the event was created.
+
+## Batching and Retry Behavior
+
+Events are queued locally and sent in batches, not one at a time.
+
+- **Auto-flush triggers:** when the queue reaches `flushAt` events, or every `flushInterval` ms.
+- **Batch size:** events are sent in parallel batches of 10 within a single flush.
+- **Queue overflow:** when the queue reaches `maxQueueSize`, the oldest event is dropped to make room.
+- **Retry:** 5xx (server) errors are retried up to `retryLimit` times with exponential backoff (1s, 2s, 4s, ... capped at 10s). 4xx (client) errors are permanent failures and are not retried.
+- **Failed events:** events that fail after all retries are re-queued at the front.
+
+## Attribution Preservation
+
+Pass the anonymous ID from your browser or mobile SDK to link server-side events to a client-side session:
 
 ```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
+  anonymousId: req.body.anonymous_id,  // From browser 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
-});
+This preserves UTM parameters, click IDs (gclid, fbclid, ttclid), referrer, landing page, and the full customer journey.
 
-// Get the SDK's anonymous ID (useful for server-only tracking)
-const anonymousId = datalyr.getAnonymousId();
-```
+## Framework Examples
 
-### Express.js Example with Browser Attribution
+### Express.js Middleware
 
 ```javascript
+import express from 'express';
+import { Datalyr } from '@datalyr/api';
+
+const app = express();
+const datalyr = new Datalyr('dk_your_api_key');
+
 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.)
+  const { items, anonymous_id } = req.body;
+
   await datalyr.track({
     event: 'Purchase Completed',
     userId: req.user?.id,
-    anonymousId: anonymous_id,  // Links to browser events!
+    anonymousId: anonymous_id,
     properties: {
       total: calculateTotal(items),
-      items: items.length
-    }
+      item_count: 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
-const datalyr = new Datalyr({
-  apiKey: 'your_api_key_here',
-  host: 'https://api.datalyr.com',  // Optional: custom host
-  flushAt: 20,                      // Optional: batch size (default: 20)
-  flushInterval: 10000,             // Optional: batch interval in ms (default: 10000)
-  debug: true,                      // Optional: enable debug logging (default: false)
-  timeout: 10000,                   // Optional: request timeout in ms (default: 10000)
-  retryLimit: 3,                    // Optional: max retries (default: 3)
-  maxQueueSize: 1000                // Optional: max events in queue (default: 1000)
+process.on('SIGTERM', async () => {
+  await datalyr.close();
+  process.exit(0);
 });
 ```
 
-## Stripe Webhook Example
+### Stripe Webhooks
 
 ```javascript
-const { Datalyr } = require('@datalyr/api');
-const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
+import { Datalyr } from '@datalyr/api';
+import Stripe from 'stripe';
 
-const datalyr = new Datalyr(process.env.DATALYR_API_KEY);
+const datalyr = new Datalyr('dk_your_api_key');
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
 
 app.post('/webhooks/stripe', async (req, res) => {
   const sig = req.headers['stripe-signature'];
   const event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret);
-  
+
   switch (event.type) {
-    case 'checkout.session.completed':
-      await datalyr.track(
-        event.data.object.client_reference_id,
-        'Purchase Completed',
-        {
-          amount: event.data.object.amount_total / 100,
-          currency: event.data.object.currency,
-          stripeSessionId: event.data.object.id
-        }
-      );
+    case 'checkout.session.completed': {
+      const session = event.data.object;
+      await datalyr.track(session.client_reference_id, 'Purchase Completed', {
+        amount: session.amount_total / 100,
+        currency: session.currency,
+        stripe_session_id: session.id,
+      });
       break;
-      
-    case 'customer.subscription.created':
-      await datalyr.track(
-        event.data.object.metadata.userId,
-        'Subscription Started',
-        {
-          plan: event.data.object.items.data[0].price.nickname,
-          mrr: event.data.object.items.data[0].price.unit_amount / 100,
-          interval: event.data.object.items.data[0].price.recurring.interval
-        }
-      );
+    }
+
+    case 'customer.subscription.created': {
+      const subscription = event.data.object;
+      await datalyr.track(subscription.metadata.userId, 'Subscription Started', {
+        plan: subscription.items.data[0].price.nickname,
+        mrr: subscription.items.data[0].price.unit_amount / 100,
+        interval: subscription.items.data[0].price.recurring.interval,
+      });
       break;
+    }
   }
-  
+
   res.json({ received: true });
 });
 ```
 
-## API Reference
+## TypeScript
 
-### `new Datalyr(config)`
+Full type definitions are included. Exported types:
 
-Creates a new Datalyr instance.
+```typescript
+import { Datalyr, DatalyrConfig, TrackOptions, TrackEvent } from '@datalyr/api';
 
-### `track(userId, event, properties?)`
+const config: DatalyrConfig = {
+  apiKey: 'dk_your_api_key',
+  debug: true,
+};
 
-Track a custom event.
+const datalyr = new Datalyr(config);
 
-### `identify(userId, traits?)`
+const options: TrackOptions = {
+  event: 'Purchase Completed',
+  userId: 'user_123',
+  anonymousId: 'anon_from_browser',
+  properties: {
+    amount: 99.99,
+    currency: 'USD',
+  },
+};
 
-Identify a user with traits.
+await datalyr.track(options);
+```
+
+## Troubleshooting
 
-### `page(userId, name?, properties?)`
+**Events not appearing**
 
-Track a pageview.
+1. Verify your API key starts with `dk_`.
+2. Enable `debug: true` to see console output.
+3. Call `await datalyr.flush()` to force-send queued events.
+4. Check for 4xx errors in debug output -- these indicate a client-side issue (bad API key, malformed payload).
 
-### `group(userId, groupId, traits?)`
+**Request timeouts**
 
-Associate a user with a group.
+Increase `timeout` and `retryLimit`:
 
-### `flush()`
+```javascript
+const datalyr = new Datalyr({
+  apiKey: 'dk_your_api_key',
+  timeout: 30000,
+  retryLimit: 5,
+});
+```
 
-Manually flush the event queue.
+**Queue full (oldest events dropped)**
 
-### `close()`
+Increase `maxQueueSize` or flush more aggressively:
 
-Flush remaining events and clean up resources.
+```javascript
+const datalyr = new Datalyr({
+  apiKey: 'dk_your_api_key',
+  maxQueueSize: 5000,
+  flushAt: 50,
+});
+```
 
 ## License
 
-MIT
+MIT

package/dist/index.js

@@ -32,7 +32,7 @@ var Datalyr = class {
     this.isClosing = false;
     if (typeof config === "string") {
       this.apiKey = config;
-      this.host = "https://api.datalyr.com";
+      this.host = "https://ingest.datalyr.com/track";
       this.debug = false;
       this.flushAt = 20;
       this.flushInterval = 1e4;
@@ -41,7 +41,7 @@ var Datalyr = class {
       this.maxQueueSize = 1e3;
     } else {
       this.apiKey = config.apiKey;
-      this.host = config.host || "https://api.datalyr.com";
+      this.host = config.host || "https://ingest.datalyr.com/track";
       this.debug = config.debug || false;
       this.flushAt = config.flushAt || 20;
       this.flushInterval = config.flushInterval || 1e4;
@@ -100,7 +100,7 @@ var Datalyr = class {
       properties: enrichedProperties,
       context: {
         library: "@datalyr/api",
-        version: "1.1.0",
+        version: "1.2.1",
         source: "api"
         // Explicitly set source for server-side API
       },

package/dist/index.mjs

@@ -7,7 +7,7 @@ var Datalyr = class {
     this.isClosing = false;
     if (typeof config === "string") {
       this.apiKey = config;
-      this.host = "https://api.datalyr.com";
+      this.host = "https://ingest.datalyr.com/track";
       this.debug = false;
       this.flushAt = 20;
       this.flushInterval = 1e4;
@@ -16,7 +16,7 @@ var Datalyr = class {
       this.maxQueueSize = 1e3;
     } else {
       this.apiKey = config.apiKey;
-      this.host = config.host || "https://api.datalyr.com";
+      this.host = config.host || "https://ingest.datalyr.com/track";
       this.debug = config.debug || false;
       this.flushAt = config.flushAt || 20;
       this.flushInterval = config.flushInterval || 1e4;
@@ -75,7 +75,7 @@ var Datalyr = class {
       properties: enrichedProperties,
       context: {
         library: "@datalyr/api",
-        version: "1.1.0",
+        version: "1.2.1",
         source: "api"
         // Explicitly set source for server-side API
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datalyr/api",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Datalyr API SDK for server-side tracking",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -43,4 +43,4 @@
   "engines": {
     "node": ">=14.0.0"
   }
-}
+}