1.0.10 • Published 10 months ago

@worqhat/worqhat-tracker v1.0.10

Weekly downloads
-
License
Apache-2.0
Repository
github
Last release
10 months ago

WorqHat Tracker

CircleCI

A robust Node.js package for tracking user activities, signups, and errors through Discord webhooks. This package provides a simple and efficient way to monitor your application's events in real-time.

Features

  • šŸš€ User signup tracking
  • šŸ“Š Activity tracking
  • āš ļø Error tracking
  • šŸ’Ŗ TypeScript support
  • āœ… Input validation
  • šŸ“ Formatted Discord messages
  • ⚔ Async/await support

Installation

npm install @worqhat/worqhat-tracker
# or
yarn add @worqhat/worqhat-tracker

Quick Start

Import and initialize the tracker:

import WorqhatTracker from '@worqhat/worqhat-tracker';

const tracker = new WorqhatTracker({
  userTrackerUrl: 'YOUR_USER_WEBHOOK_URL',
  activityTrackerUrl: 'YOUR_ACTIVITY_WEBHOOK_URL',
  errorTrackerUrl: 'YOUR_ERROR_WEBHOOK_URL',
  timeout: 5000, // Optional: default is 30000ms
});

Usage Examples

// Track user signup
await tracker.trackUser({
  uid: 'user123',
  name: 'John Doe',
  email: 'john@example.com',
  date: new Date().toISOString(),
  platform: 'web',
  metadata: {
    // Optional: Additional custom data
    referral: 'google',
    userAgent: navigator.userAgent,
    subscription: 'premium',
  },
});

// Track user activity
await tracker.trackActivity({
  uid: 'user123',
  activity: 'purchased_subscription',
  platform: 'mobile',
  metadata: {
    // Optional: Additional custom data
    planType: 'annual',
    amount: 99.99,
    paymentMethod: 'stripe',
  },
});

// Track errors
await tracker.trackError({
  uid: 'user123',
  error: 'Payment failed: Invalid card',
  platform: 'web',
  metadata: {
    // Optional: Additional custom data
    errorCode: 'PAY_001',
    cardType: 'visa',
    attemptCount: 2,
    stackTrace: error.stack,
  },
});

API Reference

Tracker Configuration

interface TrackerConfig {
  userTrackerUrl: string; // Discord webhook URL for user tracking
  activityTrackerUrl: string; // Discord webhook URL for activity tracking
  errorTrackerUrl: string; // Discord webhook URL for error tracking
  timeout?: number; // Request timeout in milliseconds
}

User Tracking

interface UserTrackerData {
  uid: string;     // Required: User ID (must be alphanumeric)
  name: string;    // Required: User's name
  email: string;   // Required: Valid email address
  date: string;    // Required: Date string
  platform: string; // Required: Platform identifier
  metadata?: Record<string, any>; // Optional: Additional custom data
}

await tracker.trackUser(data: UserTrackerData)

Activity Tracking

interface ActivityTrackerData {
  uid: string;     // User identifier
  activity: string; // Activity description
  platform: string; // Platform identifier
  metadata?: Record<string, any>; // Optional: Additional custom data
}

await tracker.trackActivity(data: ActivityTrackerData)

Error Tracking

interface ErrorTrackerData {
  uid: string;     // User identifier
  error: string;   // Error message
  platform: string; // Platform identifier
  metadata?: Record<string, any>; // Optional: Additional custom data
}

await tracker.trackError(data: ErrorTrackerData)

Discord Message Format

User Signup

### šŸ‘¤ User Signup Tracker

UID : user123
Name : John Doe
Email : john@example.com
Date : 2024-03-15T10:30:00Z
Platform: web

šŸ•’ 2024-03-15T10:30:00Z

Activity

### Activity Tracker

UID : user123
Activity: purchased_subscription
Platform: mobile

šŸ•’ 2024-03-15T10:30:00Z

Error

### āš ļø Error Tracker

UID : user123
Error : Payment failed: Invalid card
Platform: web

šŸ•’ 2024-03-15T10:30:00Z

Validation

The package includes built-in validation for:

  • Required fields
  • Email format
  • Empty strings
  • UID format (minimum 3 characters)
  • Date format (ISO string)

Error Handling

All methods return Promises and throw errors for:

  • Missing required fields
  • Invalid data formats
  • Network errors
  • Webhook errors

Example error handling:

try {
  await tracker.trackUser({
    uid: 'user123',
    name: 'John Doe',
    email: 'invalid-email', // Will throw error
    date: new Date().toISOString(),
    platform: 'web',
  });
} catch (error) {
  console.error('Tracking failed:', error.message);
}

Development

# Install dependencies
npm install

# Run tests
npm test

# Build package
npm run build

# Run linter
npm run lint

# Format code
npm run prettier

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

MIT License - see the LICENSE file for details.

Support

For support, please open an issue in the GitHub repository or contact the WorqHat team.

@worqhat/worqhat-tracker

A powerful tracking library for monitoring user signups, activities, and errors through Discord webhooks. Compatible with both frontend frameworks (React, Vue, Vite) and backend (Node.js) environments.

Features

  • šŸ‘¤ User Signup Tracking: Monitor new user registrations with detailed information
  • šŸ“Š Activity Tracking: Track user activities and interactions
  • āš ļø Error Tracking: Capture and log errors with user context
  • 🌐 Cross-Platform: Works in both browser and Node.js environments
  • ⚔ TypeScript Support: Full TypeScript support with type definitions
  • šŸ”’ Input Validation: Built-in validation for user IDs, emails, and required fields

Installation

npm install @worqhat/worqhat-tracker
# or
yarn add @worqhat/worqhat-tracker
# or
pnpm add @worqhat/worqhat-tracker

Quick Start

import { Tracker } from '@worqhat/worqhat-tracker';

// Initialize the tracker
const tracker = new Tracker({
  userTrackerUrl: 'YOUR_USER_WEBHOOK_URL',
  activityTrackerUrl: 'YOUR_ACTIVITY_WEBHOOK_URL',
  errorTrackerUrl: 'YOUR_ERROR_WEBHOOK_URL',
  timeout: 5000, // Optional: Default is 5000ms
});

Usage

Track User Signups

await tracker.trackUser({
  uid: 'user123', // Unique user identifier
  name: 'John Doe', // User's name
  email: 'john@example.com', // User's email
  date: '2024-01-20', // Signup date
  platform: 'web', // Platform identifier
  metadata: {
    // Optional: Additional custom data
    referral: 'google',
    userAgent: navigator.userAgent,
    subscription: 'premium',
  },
});

Track User Activities

await tracker.trackActivity({
  uid: 'user123', // User identifier
  activity: 'Purchased Premium Plan', // Activity description
  platform: 'mobile', // Platform where activity occurred
  metadata: {
    // Optional: Additional custom data
    planType: 'annual',
    amount: 99.99,
    paymentMethod: 'stripe',
  },
});

Track Errors

await tracker.trackError({
  uid: 'user123', // User identifier
  error: 'Payment Failed: Invalid card', // Error message
  platform: 'web', // Platform where error occurred
  metadata: {
    // Optional: Additional custom data
    errorCode: 'PAY_001',
    cardType: 'visa',
    attemptCount: 2,
    stackTrace: error.stack,
  },
});

API Reference

Tracker Configuration

The Tracker class accepts a configuration object with the following properties:

interface TrackerConfig {
  userTrackerUrl: string; // Discord webhook URL for user tracking
  activityTrackerUrl: string; // Discord webhook URL for activity tracking
  errorTrackerUrl: string; // Discord webhook URL for error tracking
  timeout?: number; // Request timeout in milliseconds (default: 5000)
}

User Tracking

interface UserTrackerData {
  uid: string; // Required: User ID (must be alphanumeric)
  name: string; // Required: User's name
  email: string; // Required: Valid email address
  date: string; // Required: Date string
  platform: string; // Required: Platform identifier
  metadata?: Record<string, any>; // Optional: Additional custom data
}

Activity Tracking

interface ActivityTrackerData {
  uid: string; // Required: User ID (must be alphanumeric)
  activity: string; // Required: Description of the activity
  platform: string; // Required: Platform identifier
  metadata?: Record<string, any>; // Optional: Additional custom data
}

Error Tracking

interface ErrorTrackerData {
  uid: string; // Required: User ID (must be alphanumeric)
  error: string; // Required: Error message or description
  platform: string; // Required: Platform identifier
  metadata?: Record<string, any>; // Optional: Additional custom data
}

Discord Webhook Setup

  1. Create a Discord server or use an existing one
  2. Go to Server Settings > Integrations > Webhooks
  3. Create three separate webhooks for:
    • User tracking
    • Activity tracking
    • Error tracking
  4. Copy the webhook URLs and use them in your tracker configuration

Validation Rules

  • User ID: Must be alphanumeric
  • Email: Must be a valid email format
  • Required Fields: All fields marked as required must be present
  • Platform: Should be a string identifying the platform (e.g., 'web', 'mobile', 'desktop')

Error Handling

The tracker throws errors in the following cases:

  • Missing required configuration URLs
  • Invalid user ID format
  • Invalid email format
  • Missing required fields in tracking data
  • Network errors during webhook requests

Example error handling:

try {
  await tracker.trackUser({
    uid: 'user123',
    name: 'John Doe',
    email: 'john@example.com',
    date: '2024-01-20',
    platform: 'web',
  });
} catch (error) {
  console.error('Tracking failed:', error.message);
}

Framework-Specific Usage

React/Vite

import { Tracker } from '@worqhat/worqhat-tracker';

function App() {
  const tracker = new Tracker({
    userTrackerUrl: process.env.VITE_USER_WEBHOOK_URL,
    activityTrackerUrl: process.env.VITE_ACTIVITY_WEBHOOK_URL,
    errorTrackerUrl: process.env.VITE_ERROR_WEBHOOK_URL,
  });

  // Use in components/hooks
}

Node.js

const { Tracker } from require('@worqhat/worqhat-tracker');
// or
import { Tracker } from '@worqhat/worqhat-tracker';

const tracker = new Tracker({
  userTrackerUrl: process.env.USER_WEBHOOK_URL,
  activityTrackerUrl: process.env.ACTIVITY_WEBHOOK_URL,
  errorTrackerUrl: process.env.ERROR_WEBHOOK_URL
});

Best Practices

  1. Environment Variables: Store webhook URLs in environment variables
  2. Error Handling: Always implement proper error handling
  3. User Privacy: Be mindful of privacy when tracking user data
  4. Rate Limiting: Consider Discord's rate limits when sending many events
  5. Validation: Validate data before sending to prevent invalid submissions
  6. Metadata Usage:
    • Keep metadata objects concise and relevant
    • Avoid sending sensitive information in metadata
    • Structure metadata consistently across your application
    • Consider adding version information in metadata for better tracking
    • Use metadata for contextual information that might help in debugging or analytics

License

MIT License - see the LICENSE file for details

Support

For issues and feature requests, please create an issue on our GitHub repository.

1.0.10

10 months ago

1.0.9

10 months ago

1.0.8

10 months ago

1.0.7

10 months ago

1.0.6

10 months ago

1.0.5

10 months ago

1.0.4

10 months ago

1.0.2

10 months ago

1.0.1

10 months ago