1.0.10 ā€¢ Published 9 months ago

@worqhat/worqhat-tracker v1.0.10

Weekly downloads
-
License
Apache-2.0
Repository
github
Last release
9 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.

nodejssdkworqhatworqhat-sdkworqhat-node
axiosform-data
1.0.10

9 months ago

1.0.9

9 months ago

1.0.8

9 months ago

1.0.7

9 months ago

1.0.6

9 months ago

1.0.5

9 months ago

1.0.4

9 months ago

1.0.2

9 months ago

1.0.1

9 months ago