@logopulse/sdk 1.0.0

package/README.md

@@ -0,0 +1,182 @@
+# @logopulse/sdk
+
+**Generic TypeScript/JavaScript SDK for tracking customer analytics events for any B2B SaaS platform.**
+
+Track the pulse of every customer - no matter what entities or events your SaaS tracks.
+
+## Installation
+
+```bash
+npm install @logopulse/sdk
+# or
+yarn add @logopulse/sdk
+```
+
+## Quick Start
+
+```typescript
+import { createLogoPulse } from '@logopulse/sdk';
+
+// Initialize once (singleton)
+const analytics = createLogoPulse({
+  apiUrl: 'https://api.logopulse.io/production',
+  apiKey: 'your-api-key-here',
+  orgId: 'your-company-id',
+  timeout: 5000, // Optional (default: 5000ms)
+});
+
+// Track any event type - LogoPulse auto-discovers entity types!
+await analytics.track('batch.created', accountId, { batchId: 'batch-123' });
+await analytics.track('order.processed', accountId, { orderId: 'order-456', total: 250.50 });
+await analytics.track('payment.received', accountId, { amount: 250.50 });
+await analytics.track('user.login', accountId, { email: 'user@company.com' });
+
+// Track custom entity types - no setup required!
+await analytics.track('tip.received', accountId, { tipId: 'tip-789', amount: 5.00 });
+await analytics.track('payout.completed', accountId, { payoutId: 'payout-123' });
+await analytics.track('export.generated', accountId, { format: 'csv', rows: 1500 });
+```
+
+## Usage
+
+### Initialization
+
+```typescript
+import { createLogoPulse } from '@logopulse/sdk';
+
+const analytics = createLogoPulse({
+  apiUrl: 'https://api.logopulse.io/production',
+  apiKey: 'your-api-key',
+  orgId: 'your-company',       // Your SaaS company identifier
+  timeout: 5000,                 // Optional (default: 5000ms)
+});
+```
+
+### Track Events
+
+The SDK has **one method**: `track(eventType, accountId, data, options)`
+
+```typescript
+/**
+ * Track an analytics event
+ * @param eventType - Event name in "entity.action" format (e.g., "batch.created")
+ * @param accountId - Your customer's account ID
+ * @param data - Custom event data (optional)
+ * @param options - Additional metadata (optional)
+ */
+await analytics.track(
+  'batch.created',
+  'customer-account-123',
+  {
+    batchId: 'batch-abc-123',
+    productName: 'Widget',
+    quantity: 100,
+    expiryDate: '2025-12-31'
+  },
+  {
+    userId: 'user-456',         // Optional: User who triggered event
+    traceId: 'trace-789',        // Optional: Distributed tracing ID
+    source: 'inventory-service', // Optional: Service name
+  }
+);
+```
+
+## Event Types
+
+LogoPulse uses the `entity.action` format (e.g., `batch.created`, `order.processed`).
+
+**Common entity types:**
+- `batch`, `order`, `payment`, `user`, `document`, `warehouse`, `shipment`
+- `tip`, `payout`, `export`, `import`, `report`, `integration`
+- **Any custom entity you want to track!**
+
+**Common actions:**
+- `created`, `updated`, `deleted`, `processed`, `completed`
+- `uploaded`, `generated`, `connected`, `disconnected`, `synced`
+
+**Examples:**
+
+```typescript
+// E-commerce
+await analytics.track('order.created', accountId, { orderId, total });
+await analytics.track('payment.received', accountId, { amount });
+await analytics.track('shipment.delivered', accountId, { shipmentId });
+
+// Inventory management
+await analytics.track('batch.created', accountId, { batchId, quantity });
+await analytics.track('stock.synced', accountId, { productCount, warehouseCount });
+
+// Food delivery
+await analytics.track('tip.received', accountId, { tipId, amount });
+await analytics.track('payout.completed', accountId, { payoutId, driverId });
+await analytics.track('delivery.completed', accountId, { deliveryId, duration });
+
+// Document management
+await analytics.track('document.uploaded', accountId, { documentId, fileSize });
+await analytics.track('report.generated', accountId, { reportType, rows });
+
+// User lifecycle
+await analytics.track('user.signup', accountId, { email, name });
+await analytics.track('user.login', accountId, { userId });
+await analytics.track('subscription.activated', accountId, { plan, mrr });
+await analytics.track('subscription.cancelled', accountId);
+
+// Integrations
+await analytics.track('integration.connected', accountId, { integrationName: 'Stripe' });
+await analytics.track('integration.disconnected', accountId, { integrationName: 'Shopify' });
+```
+
+## Integration Example
+
+```typescript
+// Initialize once in your service entry point
+import { createLogoPulse } from '@logopulse/sdk';
+
+createLogoPulse({
+  apiUrl: process.env.LOGOPULSE_API_URL,
+  apiKey: process.env.LOGOPULSE_API_KEY,
+  orgId: process.env.LOGOPULSE_ORG_ID,
+});
+
+// Use in your service methods
+import { getLogoPulse } from '@logopulse/sdk';
+
+export class BatchService {
+  async createBatch(accountId: string, data: CreateBatchRequest): Promise<Batch> {
+    const batch = await db.batches.create(data);
+
+    // Track analytics (non-blocking, errors logged but not thrown)
+    getLogoPulse()
+      .track('batch.created', accountId, {
+        batchId: batch.id,
+        productName: batch.productName,
+        quantity: batch.quantity
+      })
+      .catch(err => console.error('Analytics error:', err));
+
+    return batch;
+  }
+}
+```
+
+## Error Handling
+
+The SDK automatically catches and logs errors to prevent analytics from breaking your main application flow. Failed tracking calls are logged but do not throw exceptions.
+
+```typescript
+// This will log errors but not throw
+await analytics.trackBatchCreated(accountId, batchId);
+// Your code continues even if tracking fails
+```
+
+## Environment Variables
+
+Set `SERVICE_NAME` environment variable to automatically tag events with their source:
+
+```bash
+export SERVICE_NAME=tracelot-inventory
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+export interface LogoPulseConfig {
+    apiUrl: string;
+    apiKey: string;
+    orgId: string;
+    timeout?: number;
+}
+export interface AnalyticsEvent {
+    eventType: string;
+    eventVersion?: string;
+    timestamp?: string;
+    orgId: string;
+    accountId: string;
+    data?: Record<string, any>;
+    source?: string;
+    userId?: string;
+    traceId?: string;
+}
+/**
+ * LogoPulse SDK
+ * Track client analytics events
+ */
+export declare class LogoPulse {
+    private client;
+    private config;
+    constructor(config: LogoPulseConfig);
+    /**
+     * Track an analytics event
+     */
+    track(eventType: string, accountId: string, data?: Record<string, any>, options?: {
+        timestamp?: string;
+        userId?: string;
+        traceId?: string;
+        source?: string;
+    }): Promise<void>;
+}
+export declare function createLogoPulse(config: LogoPulseConfig): LogoPulse;
+export declare function getLogoPulse(): LogoPulse;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,MAAM,CAAkB;gBAEpB,MAAM,EAAE,eAAe;IAanC;;OAEG;IACG,KAAK,CACT,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC1B,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GACA,OAAO,CAAC,IAAI,CAAC;CAqBjB;AAOD,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAGlE;AAED,wBAAgB,YAAY,IAAI,SAAS,CAKxC"}

package/dist/index.js

@@ -0,0 +1,65 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogoPulse = void 0;
+exports.createLogoPulse = createLogoPulse;
+exports.getLogoPulse = getLogoPulse;
+const axios_1 = __importDefault(require("axios"));
+/**
+ * LogoPulse SDK
+ * Track client analytics events
+ */
+class LogoPulse {
+    constructor(config) {
+        this.config = config;
+        this.client = axios_1.default.create({
+            baseURL: config.apiUrl,
+            timeout: config.timeout || 5000,
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Api-Key': config.apiKey,
+            },
+        });
+    }
+    /**
+     * Track an analytics event
+     */
+    async track(eventType, accountId, data, options) {
+        try {
+            const event = {
+                eventType,
+                eventVersion: '1.0',
+                timestamp: options?.timestamp || new Date().toISOString(),
+                orgId: this.config.orgId,
+                accountId,
+                data: data || {},
+                source: options?.source || process.env.SERVICE_NAME || 'unknown',
+                userId: options?.userId,
+                traceId: options?.traceId,
+            };
+            await this.client.post('/v1/events', event);
+        }
+        catch (error) {
+            // Log error but don't throw - analytics shouldn't break main flow
+            console.error(`LogoPulse tracking error (${eventType}):`, error.message);
+        }
+    }
+}
+exports.LogoPulse = LogoPulse;
+/**
+ * Create a singleton instance
+ */
+let instance = null;
+function createLogoPulse(config) {
+    instance = new LogoPulse(config);
+    return instance;
+}
+function getLogoPulse() {
+    if (!instance) {
+        throw new Error('LogoPulse not initialized. Call createLogoPulse() first.');
+    }
+    return instance;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;AAmFA,0CAGC;AAED,oCAKC;AA7FD,kDAA6C;AAqB7C;;;GAGG;AACH,MAAa,SAAS;IAIpB,YAAY,MAAuB;QACjC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QAErB,IAAI,CAAC,MAAM,GAAG,eAAK,CAAC,MAAM,CAAC;YACzB,OAAO,EAAE,MAAM,CAAC,MAAM;YACtB,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;YAC/B,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,WAAW,EAAE,MAAM,CAAC,MAAM;aAC3B;SACF,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK,CACT,SAAiB,EACjB,SAAiB,EACjB,IAA0B,EAC1B,OAKC;QAED,IAAI,CAAC;YACH,MAAM,KAAK,GAAmB;gBAC5B,SAAS;gBACT,YAAY,EAAE,KAAK;gBACnB,SAAS,EAAE,OAAO,EAAE,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACzD,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK;gBACxB,SAAS;gBACT,IAAI,EAAE,IAAI,IAAI,EAAE;gBAChB,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,SAAS;gBAChE,MAAM,EAAE,OAAO,EAAE,MAAM;gBACvB,OAAO,EAAE,OAAO,EAAE,OAAO;aAC1B,CAAC;YAEF,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;QAC9C,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,kEAAkE;YAClE,OAAO,CAAC,KAAK,CAAC,6BAA6B,SAAS,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QAC3E,CAAC;IACH,CAAC;CAEF;AAnDD,8BAmDC;AAED;;GAEG;AACH,IAAI,QAAQ,GAAqB,IAAI,CAAC;AAEtC,SAAgB,eAAe,CAAC,MAAuB;IACrD,QAAQ,GAAG,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC;IACjC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAgB,YAAY;IAC1B,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@logopulse/sdk",
+  "version": "1.0.0",
+  "description": "Track the pulse of every customer - SDK for B2B SaaS customer health analytics",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -w",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tracelot/logopulse.git",
+    "directory": "sdk"
+  },
+  "keywords": [
+    "analytics",
+    "tracking",
+    "customer-health",
+    "b2b-saas",
+    "churn-prediction",
+    "logopulse"
+  ],
+  "author": "Tracelot",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.7.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.10",
+    "typescript": "^5.5.3"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}