argus-discord-analytics 0.1.0

package/README.md

@@ -0,0 +1,173 @@
+# @argus/sdk
+
+The all-seeing analytics SDK for Discord bots. Track commands, errors, and custom events with ease.
+
+## Installation
+
+```bash
+npm install @argus/sdk
+# or
+yarn add @argus/sdk
+# or
+pnpm add @argus/sdk
+```
+
+## Quick Start
+
+```typescript
+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
+
+```typescript
+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.
+
+```typescript
+client.on('interactionCreate', (interaction) => {
+  argus.track(interaction);
+});
+```
+
+### `argus.trackEvent(type, name, options?)`
+
+Track a custom event.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+await argus.flush();
+```
+
+### `argus.shutdown()`
+
+Gracefully shutdown the Argus instance, flushing any remaining events.
+
+```typescript
+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:
+
+```typescript
+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:
+
+```bash
+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

package/dist/index.d.mts

@@ -0,0 +1,251 @@
+/**
+ * Argus SDK - The all-seeing analytics for Discord bots
+ *
+ * @example
+ * ```typescript
+ * import { Argus } from '@argus/sdk';
+ *
+ * const argus = new Argus('arg_live_xxxxxxxxxxxx');
+ *
+ * // Auto-track all interactions
+ * client.on('interactionCreate', (interaction) => {
+ *   argus.track(interaction);
+ * });
+ *
+ * // Track server joins/leaves
+ * client.on('guildCreate', (guild) => {
+ *   argus.trackServer('join', { serverId: guild.id, memberCount: guild.memberCount });
+ * });
+ *
+ * // Track revenue
+ * argus.trackRevenue({ source: 'patreon', amount: 500, tier: 'Premium' });
+ * ```
+ */
+interface ArgusConfig {
+    /** Your Argus API key (starts with arg_live_ or arg_test_) */
+    apiKey: string;
+    /** API endpoint (defaults to http://localhost:3000) */
+    endpoint?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Batch size before sending (default: 10) */
+    batchSize?: number;
+    /** Flush interval in ms (default: 10000) */
+    flushInterval?: number;
+    /** Whether to hash user IDs for privacy (default: true) */
+    hashUserIds?: boolean;
+    /** Heartbeat interval in ms (default: 30000) */
+    heartbeatInterval?: number;
+}
+interface TrackEvent {
+    type: 'command' | 'error' | 'custom';
+    name: string;
+    serverId?: string;
+    userId?: string;
+    metadata?: Record<string, unknown>;
+    timestamp?: number;
+    latencyMs?: number;
+}
+interface HeartbeatConfig {
+    /** Heartbeat interval in ms (default: 30000) */
+    interval?: number;
+    /** Include latency measurement */
+    measureLatency?: boolean;
+}
+interface ServerEvent {
+    type: 'server';
+    eventType: 'join' | 'leave';
+    serverId: string;
+    memberCount?: number;
+    timestamp: number;
+}
+interface RevenueEvent {
+    type: 'revenue';
+    source: string;
+    amount: number;
+    currency: string;
+    userId?: string;
+    userHash?: string;
+    tier?: string;
+    timestamp: number;
+}
+/**
+ * Argus - The all-seeing analytics for Discord bots
+ */
+declare class Argus {
+    private apiKey;
+    private endpoint;
+    private debug;
+    private batchSize;
+    private flushInterval;
+    private hashUserIds;
+    private heartbeatInterval;
+    private queue;
+    private serverQueue;
+    private revenueQueue;
+    private flushTimer;
+    private heartbeatTimer;
+    private botId;
+    private isHeartbeatEnabled;
+    private commandStartTimes;
+    constructor(apiKeyOrConfig: string | ArgusConfig);
+    private log;
+    private startFlushTimer;
+    /**
+     * Track a Discord.js interaction automatically
+     * Extracts command name, server ID, and user ID from the interaction
+     */
+    track(interaction: {
+        commandName?: string;
+        customId?: string;
+        guildId?: string | null;
+        user?: {
+            id: string;
+        };
+        type?: number;
+    }): void;
+    /**
+     * Track a custom event
+     */
+    trackEvent(type: 'command' | 'error' | 'custom', name: string, options?: {
+        serverId?: string;
+        userId?: string;
+        metadata?: Record<string, unknown>;
+    }): void;
+    /**
+     * Track an error
+     */
+    trackError(error: Error | string, options?: {
+        command?: string;
+        serverId?: string;
+        userId?: string;
+        metadata?: Record<string, unknown>;
+    }): void;
+    /**
+     * Track server join or leave events
+     *
+     * @example
+     * ```typescript
+     * // When bot joins a server
+     * client.on('guildCreate', (guild) => {
+     *   argus.trackServer('join', {
+     *     serverId: guild.id,
+     *     memberCount: guild.memberCount
+     *   });
+     * });
+     *
+     * // When bot leaves/is kicked from a server
+     * client.on('guildDelete', (guild) => {
+     *   argus.trackServer('leave', { serverId: guild.id });
+     * });
+     * ```
+     */
+    trackServer(eventType: 'join' | 'leave', options: {
+        serverId: string;
+        memberCount?: number;
+    }): void;
+    /**
+     * Track revenue events from Patreon, Ko-fi, Stripe, or custom sources
+     *
+     * @example
+     * ```typescript
+     * // Track a Patreon pledge
+     * argus.trackRevenue({
+     *   source: 'patreon',
+     *   amount: 500, // $5.00 in cents
+     *   userId: 'discord_user_id', // optional
+     *   tier: 'Premium'
+     * });
+     *
+     * // Track a Ko-fi donation
+     * argus.trackRevenue({
+     *   source: 'kofi',
+     *   amount: 300,
+     *   currency: 'USD'
+     * });
+     * ```
+     */
+    trackRevenue(options: {
+        source: 'patreon' | 'kofi' | 'stripe' | 'custom' | string;
+        amount: number;
+        currency?: string;
+        userId?: string;
+        tier?: string;
+    }): void;
+    /**
+     * Manually flush all queued events
+     */
+    flush(): Promise<void>;
+    private flushCommandEvents;
+    private flushServerEvents;
+    private flushRevenueEvents;
+    /**
+     * Set the bot ID for all future events
+     */
+    setBotId(botId: string): void;
+    /**
+     * Start sending heartbeat pings to monitor bot uptime
+     *
+     * @example
+     * ```typescript
+     * // Start with default 30 second interval
+     * argus.startHeartbeat();
+     *
+     * // Or customize the interval
+     * argus.startHeartbeat({ interval: 60000 }); // 1 minute
+     * ```
+     */
+    startHeartbeat(config?: HeartbeatConfig): void;
+    /**
+     * Stop sending heartbeat pings
+     */
+    stopHeartbeat(): void;
+    /**
+     * Send a single heartbeat ping
+     */
+    private sendHeartbeat;
+    /**
+     * Start timing a command execution
+     * Call this at the beginning of your command handler
+     *
+     * @example
+     * ```typescript
+     * client.on('interactionCreate', async (interaction) => {
+     *   const timerId = argus.startTimer(interaction.id);
+     *
+     *   try {
+     *     await handleCommand(interaction);
+     *   } finally {
+     *     argus.endTimer(timerId, interaction);
+     *   }
+     * });
+     * ```
+     */
+    startTimer(id: string): string;
+    /**
+     * End timing and track the command with latency
+     */
+    endTimer(timerId: string, interaction: {
+        commandName?: string;
+        customId?: string;
+        guildId?: string | null;
+        user?: {
+            id: string;
+        };
+        type?: number;
+    }): void;
+    /**
+     * Track an event with latency measurement
+     */
+    trackEventWithLatency(type: 'command' | 'error' | 'custom', name: string, latencyMs: number, options?: {
+        serverId?: string;
+        userId?: string;
+        metadata?: Record<string, unknown>;
+    }): void;
+    /**
+     * Shutdown the Argus instance, flushing any remaining events
+     */
+    shutdown(): Promise<void>;
+}
+
+export { Argus, type ArgusConfig, type HeartbeatConfig, type RevenueEvent, type ServerEvent, type TrackEvent, Argus as default };

package/dist/index.d.ts

@@ -0,0 +1,251 @@
+/**
+ * Argus SDK - The all-seeing analytics for Discord bots
+ *
+ * @example
+ * ```typescript
+ * import { Argus } from '@argus/sdk';
+ *
+ * const argus = new Argus('arg_live_xxxxxxxxxxxx');
+ *
+ * // Auto-track all interactions
+ * client.on('interactionCreate', (interaction) => {
+ *   argus.track(interaction);
+ * });
+ *
+ * // Track server joins/leaves
+ * client.on('guildCreate', (guild) => {
+ *   argus.trackServer('join', { serverId: guild.id, memberCount: guild.memberCount });
+ * });
+ *
+ * // Track revenue
+ * argus.trackRevenue({ source: 'patreon', amount: 500, tier: 'Premium' });
+ * ```
+ */
+interface ArgusConfig {
+    /** Your Argus API key (starts with arg_live_ or arg_test_) */
+    apiKey: string;
+    /** API endpoint (defaults to http://localhost:3000) */
+    endpoint?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Batch size before sending (default: 10) */
+    batchSize?: number;
+    /** Flush interval in ms (default: 10000) */
+    flushInterval?: number;
+    /** Whether to hash user IDs for privacy (default: true) */
+    hashUserIds?: boolean;
+    /** Heartbeat interval in ms (default: 30000) */
+    heartbeatInterval?: number;
+}
+interface TrackEvent {
+    type: 'command' | 'error' | 'custom';
+    name: string;
+    serverId?: string;
+    userId?: string;
+    metadata?: Record<string, unknown>;
+    timestamp?: number;
+    latencyMs?: number;
+}
+interface HeartbeatConfig {
+    /** Heartbeat interval in ms (default: 30000) */
+    interval?: number;
+    /** Include latency measurement */
+    measureLatency?: boolean;
+}
+interface ServerEvent {
+    type: 'server';
+    eventType: 'join' | 'leave';
+    serverId: string;
+    memberCount?: number;
+    timestamp: number;
+}
+interface RevenueEvent {
+    type: 'revenue';
+    source: string;
+    amount: number;
+    currency: string;
+    userId?: string;
+    userHash?: string;
+    tier?: string;
+    timestamp: number;
+}
+/**
+ * Argus - The all-seeing analytics for Discord bots
+ */
+declare class Argus {
+    private apiKey;
+    private endpoint;
+    private debug;
+    private batchSize;
+    private flushInterval;
+    private hashUserIds;
+    private heartbeatInterval;
+    private queue;
+    private serverQueue;
+    private revenueQueue;
+    private flushTimer;
+    private heartbeatTimer;
+    private botId;
+    private isHeartbeatEnabled;
+    private commandStartTimes;
+    constructor(apiKeyOrConfig: string | ArgusConfig);
+    private log;
+    private startFlushTimer;
+    /**
+     * Track a Discord.js interaction automatically
+     * Extracts command name, server ID, and user ID from the interaction
+     */
+    track(interaction: {
+        commandName?: string;
+        customId?: string;
+        guildId?: string | null;
+        user?: {
+            id: string;
+        };
+        type?: number;
+    }): void;
+    /**
+     * Track a custom event
+     */
+    trackEvent(type: 'command' | 'error' | 'custom', name: string, options?: {
+        serverId?: string;
+        userId?: string;
+        metadata?: Record<string, unknown>;
+    }): void;
+    /**
+     * Track an error
+     */
+    trackError(error: Error | string, options?: {
+        command?: string;
+        serverId?: string;
+        userId?: string;
+        metadata?: Record<string, unknown>;
+    }): void;
+    /**
+     * Track server join or leave events
+     *
+     * @example
+     * ```typescript
+     * // When bot joins a server
+     * client.on('guildCreate', (guild) => {
+     *   argus.trackServer('join', {
+     *     serverId: guild.id,
+     *     memberCount: guild.memberCount
+     *   });
+     * });
+     *
+     * // When bot leaves/is kicked from a server
+     * client.on('guildDelete', (guild) => {
+     *   argus.trackServer('leave', { serverId: guild.id });
+     * });
+     * ```
+     */
+    trackServer(eventType: 'join' | 'leave', options: {
+        serverId: string;
+        memberCount?: number;
+    }): void;
+    /**
+     * Track revenue events from Patreon, Ko-fi, Stripe, or custom sources
+     *
+     * @example
+     * ```typescript
+     * // Track a Patreon pledge
+     * argus.trackRevenue({
+     *   source: 'patreon',
+     *   amount: 500, // $5.00 in cents
+     *   userId: 'discord_user_id', // optional
+     *   tier: 'Premium'
+     * });
+     *
+     * // Track a Ko-fi donation
+     * argus.trackRevenue({
+     *   source: 'kofi',
+     *   amount: 300,
+     *   currency: 'USD'
+     * });
+     * ```
+     */
+    trackRevenue(options: {
+        source: 'patreon' | 'kofi' | 'stripe' | 'custom' | string;
+        amount: number;
+        currency?: string;
+        userId?: string;
+        tier?: string;
+    }): void;
+    /**
+     * Manually flush all queued events
+     */
+    flush(): Promise<void>;
+    private flushCommandEvents;
+    private flushServerEvents;
+    private flushRevenueEvents;
+    /**
+     * Set the bot ID for all future events
+     */
+    setBotId(botId: string): void;
+    /**
+     * Start sending heartbeat pings to monitor bot uptime
+     *
+     * @example
+     * ```typescript
+     * // Start with default 30 second interval
+     * argus.startHeartbeat();
+     *
+     * // Or customize the interval
+     * argus.startHeartbeat({ interval: 60000 }); // 1 minute
+     * ```
+     */
+    startHeartbeat(config?: HeartbeatConfig): void;
+    /**
+     * Stop sending heartbeat pings
+     */
+    stopHeartbeat(): void;
+    /**
+     * Send a single heartbeat ping
+     */
+    private sendHeartbeat;
+    /**
+     * Start timing a command execution
+     * Call this at the beginning of your command handler
+     *
+     * @example
+     * ```typescript
+     * client.on('interactionCreate', async (interaction) => {
+     *   const timerId = argus.startTimer(interaction.id);
+     *
+     *   try {
+     *     await handleCommand(interaction);
+     *   } finally {
+     *     argus.endTimer(timerId, interaction);
+     *   }
+     * });
+     * ```
+     */
+    startTimer(id: string): string;
+    /**
+     * End timing and track the command with latency
+     */
+    endTimer(timerId: string, interaction: {
+        commandName?: string;
+        customId?: string;
+        guildId?: string | null;
+        user?: {
+            id: string;
+        };
+        type?: number;
+    }): void;
+    /**
+     * Track an event with latency measurement
+     */
+    trackEventWithLatency(type: 'command' | 'error' | 'custom', name: string, latencyMs: number, options?: {
+        serverId?: string;
+        userId?: string;
+        metadata?: Record<string, unknown>;
+    }): void;
+    /**
+     * Shutdown the Argus instance, flushing any remaining events
+     */
+    shutdown(): Promise<void>;
+}
+
+export { Argus, type ArgusConfig, type HeartbeatConfig, type RevenueEvent, type ServerEvent, type TrackEvent, Argus as default };