argus-discord-analytics 0.1.0

package/dist/index.mjs

@@ -0,0 +1,419 @@
+// src/index.ts
+function hashString(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+  return Math.abs(hash).toString(36);
+}
+var Argus = class {
+  constructor(apiKeyOrConfig) {
+    this.queue = [];
+    this.serverQueue = [];
+    this.revenueQueue = [];
+    this.flushTimer = null;
+    this.heartbeatTimer = null;
+    this.botId = null;
+    this.isHeartbeatEnabled = false;
+    this.commandStartTimes = /* @__PURE__ */ new Map();
+    const config = typeof apiKeyOrConfig === "string" ? { apiKey: apiKeyOrConfig } : apiKeyOrConfig;
+    if (!config.apiKey) {
+      throw new Error("Argus: API key is required");
+    }
+    if (!config.apiKey.startsWith("arg_live_") && !config.apiKey.startsWith("arg_test_")) {
+      console.warn("Argus: API key should start with arg_live_ or arg_test_");
+    }
+    this.apiKey = config.apiKey;
+    this.endpoint = config.endpoint || "http://localhost:3000";
+    this.debug = config.debug || false;
+    this.batchSize = config.batchSize || 10;
+    this.flushInterval = config.flushInterval || 1e4;
+    this.hashUserIds = config.hashUserIds !== false;
+    this.heartbeatInterval = config.heartbeatInterval || 3e4;
+    this.startFlushTimer();
+    this.log("Argus initialized");
+  }
+  log(...args) {
+    if (this.debug) {
+      console.log("[Argus]", ...args);
+    }
+  }
+  startFlushTimer() {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+    }
+    this.flushTimer = setInterval(() => this.flush(), this.flushInterval);
+  }
+  /**
+   * Track a Discord.js interaction automatically
+   * Extracts command name, server ID, and user ID from the interaction
+   */
+  track(interaction) {
+    const name = interaction.commandName || interaction.customId || "unknown";
+    const serverId = interaction.guildId || void 0;
+    const userId = interaction.user?.id;
+    this.trackEvent("command", name, {
+      serverId,
+      userId,
+      metadata: {
+        interactionType: interaction.type
+      }
+    });
+  }
+  /**
+   * Track a custom event
+   */
+  trackEvent(type, name, options) {
+    const event = {
+      type,
+      name,
+      serverId: options?.serverId,
+      userId: options?.userId,
+      userHash: options?.userId && this.hashUserIds ? hashString(options.userId) : options?.userId,
+      metadata: options?.metadata,
+      timestamp: Date.now()
+    };
+    if (this.hashUserIds) {
+      delete event.userId;
+    }
+    this.queue.push(event);
+    this.log("Event queued:", event);
+    if (this.queue.length >= this.batchSize) {
+      this.flush();
+    }
+  }
+  /**
+   * Track an error
+   */
+  trackError(error, options) {
+    const errorMessage = error instanceof Error ? error.message : error;
+    const errorStack = error instanceof Error ? error.stack : void 0;
+    this.trackEvent("error", errorMessage, {
+      serverId: options?.serverId,
+      userId: options?.userId,
+      metadata: {
+        ...options?.metadata,
+        command: options?.command,
+        stack: errorStack
+      }
+    });
+  }
+  /**
+   * 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, options) {
+    const event = {
+      type: "server",
+      eventType,
+      serverId: options.serverId,
+      memberCount: options.memberCount,
+      timestamp: Date.now()
+    };
+    this.serverQueue.push(event);
+    this.log("Server event queued:", event);
+    this.flushServerEvents();
+  }
+  /**
+   * 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) {
+    const event = {
+      type: "revenue",
+      source: options.source,
+      amount: options.amount,
+      currency: options.currency || "USD",
+      userId: options.userId,
+      userHash: options.userId && this.hashUserIds ? hashString(options.userId) : options.userId,
+      tier: options.tier,
+      timestamp: Date.now()
+    };
+    if (this.hashUserIds) {
+      delete event.userId;
+    }
+    this.revenueQueue.push(event);
+    this.log("Revenue event queued:", event);
+    this.flushRevenueEvents();
+  }
+  /**
+   * Manually flush all queued events
+   */
+  async flush() {
+    await Promise.all([
+      this.flushCommandEvents(),
+      this.flushServerEvents(),
+      this.flushRevenueEvents()
+    ]);
+  }
+  async flushCommandEvents() {
+    if (this.queue.length === 0) {
+      return;
+    }
+    const events = [...this.queue];
+    this.queue = [];
+    this.log(`Flushing ${events.length} events`);
+    try {
+      const response = await fetch(`${this.endpoint}/api/events`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify({ events })
+      });
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      this.log("Events sent successfully");
+    } catch (error) {
+      this.queue = [...events, ...this.queue];
+      this.log("Failed to send events, re-queued:", error);
+    }
+  }
+  async flushServerEvents() {
+    if (this.serverQueue.length === 0) {
+      return;
+    }
+    const events = [...this.serverQueue];
+    this.serverQueue = [];
+    this.log(`Flushing ${events.length} server events`);
+    try {
+      const response = await fetch(`${this.endpoint}/api/events/server`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify({ events })
+      });
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      this.log("Server events sent successfully");
+    } catch (error) {
+      this.serverQueue = [...events, ...this.serverQueue];
+      this.log("Failed to send server events, re-queued:", error);
+    }
+  }
+  async flushRevenueEvents() {
+    if (this.revenueQueue.length === 0) {
+      return;
+    }
+    const events = [...this.revenueQueue];
+    this.revenueQueue = [];
+    this.log(`Flushing ${events.length} revenue events`);
+    try {
+      const response = await fetch(`${this.endpoint}/api/events/revenue`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify({ events })
+      });
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      this.log("Revenue events sent successfully");
+    } catch (error) {
+      this.revenueQueue = [...events, ...this.revenueQueue];
+      this.log("Failed to send revenue events, re-queued:", error);
+    }
+  }
+  /**
+   * Set the bot ID for all future events
+   */
+  setBotId(botId) {
+    this.botId = botId;
+    this.log("Bot ID set:", botId);
+  }
+  // ==========================================
+  // Heartbeat / Uptime Monitoring
+  // ==========================================
+  /**
+   * 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) {
+    if (this.isHeartbeatEnabled) {
+      this.log("Heartbeat already running");
+      return;
+    }
+    const interval = config?.interval || this.heartbeatInterval;
+    this.isHeartbeatEnabled = true;
+    this.sendHeartbeat();
+    this.heartbeatTimer = setInterval(() => {
+      this.sendHeartbeat();
+    }, interval);
+    this.log(`Heartbeat started with ${interval}ms interval`);
+  }
+  /**
+   * Stop sending heartbeat pings
+   */
+  stopHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+    this.isHeartbeatEnabled = false;
+    this.log("Heartbeat stopped");
+  }
+  /**
+   * Send a single heartbeat ping
+   */
+  async sendHeartbeat() {
+    const startTime = Date.now();
+    try {
+      const response = await fetch(`${this.endpoint}/api/heartbeat`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify({
+          timestamp: startTime
+        })
+      });
+      const latencyMs = Date.now() - startTime;
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      this.log(`Heartbeat sent (${latencyMs}ms)`);
+    } catch (error) {
+      this.log("Heartbeat failed:", error);
+    }
+  }
+  // ==========================================
+  // Latency Tracking
+  // ==========================================
+  /**
+   * 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) {
+    this.commandStartTimes.set(id, Date.now());
+    return id;
+  }
+  /**
+   * End timing and track the command with latency
+   */
+  endTimer(timerId, interaction) {
+    const startTime = this.commandStartTimes.get(timerId);
+    if (!startTime) {
+      this.log("Timer not found:", timerId);
+      this.track(interaction);
+      return;
+    }
+    const latencyMs = Date.now() - startTime;
+    this.commandStartTimes.delete(timerId);
+    const name = interaction.commandName || interaction.customId || "unknown";
+    const serverId = interaction.guildId || void 0;
+    const userId = interaction.user?.id;
+    this.trackEventWithLatency("command", name, latencyMs, {
+      serverId,
+      userId,
+      metadata: {
+        interactionType: interaction.type
+      }
+    });
+  }
+  /**
+   * Track an event with latency measurement
+   */
+  trackEventWithLatency(type, name, latencyMs, options) {
+    const event = {
+      type,
+      name,
+      serverId: options?.serverId,
+      userId: options?.userId,
+      userHash: options?.userId && this.hashUserIds ? hashString(options.userId) : options?.userId,
+      metadata: {
+        ...options?.metadata,
+        latencyMs
+      },
+      latencyMs,
+      timestamp: Date.now()
+    };
+    if (this.hashUserIds) {
+      delete event.userId;
+    }
+    this.queue.push(event);
+    this.log("Event with latency queued:", event);
+    if (this.queue.length >= this.batchSize) {
+      this.flush();
+    }
+  }
+  /**
+   * Shutdown the Argus instance, flushing any remaining events
+   */
+  async shutdown() {
+    this.stopHeartbeat();
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    await this.flush();
+    this.log("Argus shutdown complete");
+  }
+};
+var index_default = Argus;
+export {
+  Argus,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "argus-discord-analytics",
+  "version": "0.1.0",
+  "description": "The all-seeing analytics SDK for Discord bots - track commands, errors, servers, and more",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "discord",
+    "discord.js",
+    "bot",
+    "analytics",
+    "tracking",
+    "metrics",
+    "argus",
+    "dashboard",
+    "commands",
+    "errors"
+  ],
+  "author": "Argus Analytics",
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "discord.js": ">=14.0.0"
+  },
+  "peerDependenciesMeta": {
+    "discord.js": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/apollowinner/argus"
+  },
+  "homepage": "https://tryargus.io"
+}
+