@worqhat/worqhat-tracker

WorqHat Tracker

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: '[e-mail]',
  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 : [e-mail]
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: '[e-mail]', // 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: '[e-mail]',
    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.