@argus/sdk

The all-seeing analytics SDK for Discord bots. Track commands, errors, and custom events with ease.

Installation

npm install @argus/sdk
# or
yarn add @argus/sdk
# or
pnpm add @argus/sdk

Quick Start

import { Argus } from '@argus/sdk';
import { Client, GatewayIntentBits } from 'discord.js';

// Initialize Argus with your API key
const argus = new Argus({
  apiKey: 'arg_live_your_api_key_here',
  endpoint: 'https://your-app.vercel.app', // Your Argus deployment URL
  debug: process.env.NODE_ENV === 'development',
});

const client = new Client({
  intents: [GatewayIntentBits.Guilds],
});

// Auto-track all interactions
client.on('interactionCreate', (interaction) => {
  argus.track(interaction);
});

// Track errors
client.on('error', (error) => {
  argus.trackError(error);
});

// Graceful shutdown
process.on('SIGINT', async () => {
  await argus.shutdown();
  process.exit(0);
});

client.login(process.env.DISCORD_TOKEN);

Configuration

const argus = new Argus({
  // Required: Your Argus API key
  apiKey: 'arg_live_xxxxxxxxxxxx',
  
  // Optional: API endpoint (defaults to http://localhost:3000)
  endpoint: 'https://your-app.vercel.app',
  
  // Optional: Enable debug logging (default: false)
  debug: true,
  
  // Optional: Number of events before auto-flush (default: 10)
  batchSize: 10,
  
  // Optional: Flush interval in milliseconds (default: 10000)
  flushInterval: 10000,
  
  // Optional: Hash user IDs for privacy (default: true)
  hashUserIds: true,
});

API

argus.track(interaction)

Track a Discord.js interaction automatically. Extracts command name, server ID, and user ID.

client.on('interactionCreate', (interaction) => {
  argus.track(interaction);
});

argus.trackEvent(type, name, options?)

Track a custom event.

argus.trackEvent('command', '/play', {
  serverId: '123456789',
  userId: '987654321',
  metadata: { song: 'Never Gonna Give You Up' },
});

argus.trackEvent('custom', 'playlist_created', {
  serverId: '123456789',
  metadata: { playlistName: 'My Playlist', songCount: 10 },
});

argus.trackError(error, options?)

Track an error with optional context.

try {
  await someRiskyOperation();
} catch (error) {
  argus.trackError(error, {
    command: '/play',
    serverId: interaction.guildId,
    userId: interaction.user.id,
  });
}

argus.flush()

Manually flush all queued events to the server.

await argus.flush();

argus.shutdown()

Gracefully shutdown the Argus instance, flushing any remaining events.

process.on('SIGINT', async () => {
  await argus.shutdown();
  process.exit(0);
});

Privacy

By default, Argus hashes user IDs before sending them to the server. This allows you to track unique users without storing their actual Discord IDs.

To disable hashing:

const argus = new Argus({
  apiKey: 'your_api_key',
  hashUserIds: false,
});

REST API Alternative

If you're not using Node.js, you can send events directly to the API:

curl -X POST https://your-app.vercel.app/api/events \
  -H "Authorization: Bearer arg_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "type": "command",
      "name": "/play",
      "serverId": "123456789",
      "userHash": "abc123",
      "timestamp": 1640000000000
    }]
  }'

License

MIT