@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

npm install @logopulse/sdk
# or
yarn add @logopulse/sdk

Quick Start

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: '[email protected]' });

// 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

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)

/**
 * 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:

// 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

// 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.

// 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:

export SERVICE_NAME=tracelot-inventory

License

MIT