argus-discord-analytics 0.3.0 → 0.4.0

package/dist/index.d.mts

@@ -21,7 +21,7 @@
  * argus.trackRevenue({ source: 'patreon', amount: 500, tier: 'Premium' });
  * ```
  */
-declare const SDK_VERSION = "0.3.0";
+declare const SDK_VERSION = "0.4.0";
 interface ArgusConfig {
     /** Your Argus API key (starts with arg_live_ or arg_test_) */
     apiKey: string;
@@ -75,6 +75,40 @@ interface HeartbeatConfig {
     interval?: number;
     /** Include latency measurement */
     measureLatency?: boolean;
+    /** Shard ID for sharded bots */
+    shardId?: number;
+    /** Total number of shards */
+    shardCount?: number;
+    /** Guild count for this shard */
+    guildCount?: number;
+}
+interface GatewayEventConfig {
+    /** Shard ID the event occurred on */
+    shardId?: number;
+    /** Rate limit bucket (for rate_limit events) */
+    bucket?: string;
+    /** Retry after in ms (for rate_limit events) */
+    retryAfter?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+interface ResourceMetrics {
+    /** CPU usage percentage (0-100) */
+    cpuPercent?: number;
+    /** Total memory usage in MB */
+    memoryMb?: number;
+    /** Heap used in MB */
+    heapUsedMb?: number;
+    /** Heap total in MB */
+    heapTotalMb?: number;
+    /** Number of guilds/servers */
+    guildCount?: number;
+    /** Number of cached users */
+    cachedUsers?: number;
+    /** Number of cached channels */
+    cachedChannels?: number;
+    /** Shard ID (optional for per-shard metrics) */
+    shardId?: number;
 }
 interface ServerEvent {
     type: 'server';
@@ -113,6 +147,9 @@ declare class Argus {
     private botId;
     private isHeartbeatEnabled;
     private commandStartTimes;
+    private shardId;
+    private shardCount;
+    private guildCount;
     constructor(apiKeyOrConfig: string | ArgusConfig);
     private log;
     private startFlushTimer;
@@ -331,6 +368,12 @@ declare class Argus {
      *
      * // Or customize the interval
      * argus.startHeartbeat({ interval: 60000 }); // 1 minute
+     *
+     * // For sharded bots - track per-shard status
+     * argus.startHeartbeat({
+     *   shardId: shard.id,
+     *   shardCount: client.shard?.count || 1
+     * });
      * ```
      */
     startHeartbeat(config?: HeartbeatConfig): void;
@@ -342,6 +385,83 @@ declare class Argus {
      * Send a single heartbeat ping
      */
     private sendHeartbeat;
+    /**
+     * Track a gateway event (reconnect, rate limit, etc.)
+     *
+     * @example
+     * ```typescript
+     * // Track reconnects
+     * client.on('shardReconnecting', (shardId) => {
+     *   argus.trackGatewayEvent('reconnect', { shardId });
+     * });
+     *
+     * // Track rate limits
+     * client.rest.on('rateLimited', (info) => {
+     *   argus.trackGatewayEvent('rate_limit', {
+     *     bucket: info.route,
+     *     retryAfter: info.retryAfter,
+     *   });
+     * });
+     * ```
+     */
+    trackGatewayEvent(eventType: 'reconnect' | 'rate_limit' | 'ready' | 'resume' | 'disconnect' | 'death' | 'spawn', config?: GatewayEventConfig): Promise<void>;
+    /**
+     * Track resource usage (CPU, memory, cache sizes)
+     * Call this periodically (e.g., every 60 seconds) to monitor resource usage
+     *
+     * @example
+     * ```typescript
+     * // Track resources every minute
+     * setInterval(() => {
+     *   argus.trackResources({
+     *     memoryMb: process.memoryUsage().heapUsed / 1024 / 1024,
+     *     guildCount: client.guilds.cache.size,
+     *     cachedUsers: client.users.cache.size,
+     *   });
+     * }, 60000);
+     * ```
+     */
+    trackResources(metrics: ResourceMetrics): Promise<void>;
+    /**
+     * Attach to a Discord.js ShardingManager to auto-track shard events
+     *
+     * @example
+     * ```typescript
+     * const manager = new ShardingManager('./bot.js', { ... });
+     * argus.attachToShardManager(manager);
+     * manager.spawn();
+     * ```
+     */
+    attachToShardManager(manager: {
+        on: (event: string, listener: (...args: unknown[]) => void) => void;
+        shardList?: number[];
+        totalShards?: number | 'auto';
+    }): void;
+    /**
+     * Set up automatic tracking for Discord.js client shard events
+     * Call this from within your bot process to track per-shard events
+     *
+     * @example
+     * ```typescript
+     * // In your bot.js that runs in each shard
+     * argus.attachToClient(client);
+     * ```
+     */
+    attachToClient(client: {
+        on: (event: string, listener: (...args: unknown[]) => void) => void;
+        shard?: {
+            ids: number[];
+            count: number;
+        } | null;
+        guilds?: {
+            cache: {
+                size: number;
+            };
+        };
+        rest?: {
+            on: (event: string, listener: (...args: unknown[]) => void) => void;
+        };
+    }): void;
     /**
      * Start timing a command execution
      * Call this at the beginning of your command handler
@@ -386,4 +506,4 @@ declare class Argus {
     shutdown(): Promise<void>;
 }
 
-export { Argus, type ArgusConfig, type HeartbeatConfig, type RevenueEvent, SDK_VERSION, type ServerEvent, type TrackEvent, type TrackOptions, Argus as default };
+export { Argus, type ArgusConfig, type GatewayEventConfig, type HeartbeatConfig, type ResourceMetrics, type RevenueEvent, SDK_VERSION, type ServerEvent, type TrackEvent, type TrackOptions, Argus as default };

package/dist/index.d.ts

@@ -21,7 +21,7 @@
  * argus.trackRevenue({ source: 'patreon', amount: 500, tier: 'Premium' });
  * ```
  */
-declare const SDK_VERSION = "0.3.0";
+declare const SDK_VERSION = "0.4.0";
 interface ArgusConfig {
     /** Your Argus API key (starts with arg_live_ or arg_test_) */
     apiKey: string;
@@ -75,6 +75,40 @@ interface HeartbeatConfig {
     interval?: number;
     /** Include latency measurement */
     measureLatency?: boolean;
+    /** Shard ID for sharded bots */
+    shardId?: number;
+    /** Total number of shards */
+    shardCount?: number;
+    /** Guild count for this shard */
+    guildCount?: number;
+}
+interface GatewayEventConfig {
+    /** Shard ID the event occurred on */
+    shardId?: number;
+    /** Rate limit bucket (for rate_limit events) */
+    bucket?: string;
+    /** Retry after in ms (for rate_limit events) */
+    retryAfter?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+interface ResourceMetrics {
+    /** CPU usage percentage (0-100) */
+    cpuPercent?: number;
+    /** Total memory usage in MB */
+    memoryMb?: number;
+    /** Heap used in MB */
+    heapUsedMb?: number;
+    /** Heap total in MB */
+    heapTotalMb?: number;
+    /** Number of guilds/servers */
+    guildCount?: number;
+    /** Number of cached users */
+    cachedUsers?: number;
+    /** Number of cached channels */
+    cachedChannels?: number;
+    /** Shard ID (optional for per-shard metrics) */
+    shardId?: number;
 }
 interface ServerEvent {
     type: 'server';
@@ -113,6 +147,9 @@ declare class Argus {
     private botId;
     private isHeartbeatEnabled;
     private commandStartTimes;
+    private shardId;
+    private shardCount;
+    private guildCount;
     constructor(apiKeyOrConfig: string | ArgusConfig);
     private log;
     private startFlushTimer;
@@ -331,6 +368,12 @@ declare class Argus {
      *
      * // Or customize the interval
      * argus.startHeartbeat({ interval: 60000 }); // 1 minute
+     *
+     * // For sharded bots - track per-shard status
+     * argus.startHeartbeat({
+     *   shardId: shard.id,
+     *   shardCount: client.shard?.count || 1
+     * });
      * ```
      */
     startHeartbeat(config?: HeartbeatConfig): void;
@@ -342,6 +385,83 @@ declare class Argus {
      * Send a single heartbeat ping
      */
     private sendHeartbeat;
+    /**
+     * Track a gateway event (reconnect, rate limit, etc.)
+     *
+     * @example
+     * ```typescript
+     * // Track reconnects
+     * client.on('shardReconnecting', (shardId) => {
+     *   argus.trackGatewayEvent('reconnect', { shardId });
+     * });
+     *
+     * // Track rate limits
+     * client.rest.on('rateLimited', (info) => {
+     *   argus.trackGatewayEvent('rate_limit', {
+     *     bucket: info.route,
+     *     retryAfter: info.retryAfter,
+     *   });
+     * });
+     * ```
+     */
+    trackGatewayEvent(eventType: 'reconnect' | 'rate_limit' | 'ready' | 'resume' | 'disconnect' | 'death' | 'spawn', config?: GatewayEventConfig): Promise<void>;
+    /**
+     * Track resource usage (CPU, memory, cache sizes)
+     * Call this periodically (e.g., every 60 seconds) to monitor resource usage
+     *
+     * @example
+     * ```typescript
+     * // Track resources every minute
+     * setInterval(() => {
+     *   argus.trackResources({
+     *     memoryMb: process.memoryUsage().heapUsed / 1024 / 1024,
+     *     guildCount: client.guilds.cache.size,
+     *     cachedUsers: client.users.cache.size,
+     *   });
+     * }, 60000);
+     * ```
+     */
+    trackResources(metrics: ResourceMetrics): Promise<void>;
+    /**
+     * Attach to a Discord.js ShardingManager to auto-track shard events
+     *
+     * @example
+     * ```typescript
+     * const manager = new ShardingManager('./bot.js', { ... });
+     * argus.attachToShardManager(manager);
+     * manager.spawn();
+     * ```
+     */
+    attachToShardManager(manager: {
+        on: (event: string, listener: (...args: unknown[]) => void) => void;
+        shardList?: number[];
+        totalShards?: number | 'auto';
+    }): void;
+    /**
+     * Set up automatic tracking for Discord.js client shard events
+     * Call this from within your bot process to track per-shard events
+     *
+     * @example
+     * ```typescript
+     * // In your bot.js that runs in each shard
+     * argus.attachToClient(client);
+     * ```
+     */
+    attachToClient(client: {
+        on: (event: string, listener: (...args: unknown[]) => void) => void;
+        shard?: {
+            ids: number[];
+            count: number;
+        } | null;
+        guilds?: {
+            cache: {
+                size: number;
+            };
+        };
+        rest?: {
+            on: (event: string, listener: (...args: unknown[]) => void) => void;
+        };
+    }): void;
     /**
      * Start timing a command execution
      * Call this at the beginning of your command handler
@@ -386,4 +506,4 @@ declare class Argus {
     shutdown(): Promise<void>;
 }
 
-export { Argus, type ArgusConfig, type HeartbeatConfig, type RevenueEvent, SDK_VERSION, type ServerEvent, type TrackEvent, type TrackOptions, Argus as default };
+export { Argus, type ArgusConfig, type GatewayEventConfig, type HeartbeatConfig, type ResourceMetrics, type RevenueEvent, SDK_VERSION, type ServerEvent, type TrackEvent, type TrackOptions, Argus as default };

package/dist/index.js

@@ -25,7 +25,7 @@ __export(index_exports, {
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
-var SDK_VERSION = "0.3.0";
+var SDK_VERSION = "0.4.0";
 function hashString(str) {
   let hash = 0;
   for (let i = 0; i < str.length; i++) {
@@ -494,6 +494,12 @@ var Argus = class {
    * 
    * // Or customize the interval
    * argus.startHeartbeat({ interval: 60000 }); // 1 minute
+   * 
+   * // For sharded bots - track per-shard status
+   * argus.startHeartbeat({ 
+   *   shardId: shard.id, 
+   *   shardCount: client.shard?.count || 1 
+   * });
    * ```
    */
   startHeartbeat(config) {
@@ -503,11 +509,21 @@ var Argus = class {
     }
     const interval = config?.interval || this.heartbeatInterval;
     this.isHeartbeatEnabled = true;
+    if (config?.shardId !== void 0) {
+      this.shardId = config.shardId;
+    }
+    if (config?.shardCount !== void 0) {
+      this.shardCount = config.shardCount;
+    }
+    if (config?.guildCount !== void 0) {
+      this.guildCount = config.guildCount;
+    }
     this.sendHeartbeat();
     this.heartbeatTimer = setInterval(() => {
       this.sendHeartbeat();
     }, interval);
-    this.log(`Heartbeat started with ${interval}ms interval`);
+    const shardInfo = this.shardId !== void 0 ? ` (shard ${this.shardId}/${this.shardCount})` : "";
+    this.log(`Heartbeat started with ${interval}ms interval${shardInfo}`);
   }
   /**
    * Stop sending heartbeat pings
@@ -526,26 +542,194 @@ var Argus = class {
   async sendHeartbeat() {
     const startTime = Date.now();
     try {
-      const response = await fetch(`${this.endpoint}/api/heartbeat`, {
+      const endpoint = this.shardId !== void 0 ? `${this.endpoint}/api/shard-heartbeat` : `${this.endpoint}/api/heartbeat`;
+      const body = { timestamp: startTime };
+      if (this.shardId !== void 0) {
+        body.shardId = this.shardId;
+        body.shardCount = this.shardCount || 1;
+        body.guildCount = this.guildCount;
+      }
+      const response = await fetch(endpoint, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
           "Authorization": `Bearer ${this.apiKey}`
         },
-        body: JSON.stringify({
-          timestamp: startTime
-        })
+        body: JSON.stringify(body)
       });
       const latencyMs = Date.now() - startTime;
       if (!response.ok) {
         throw new Error(`HTTP ${response.status}: ${response.statusText}`);
       }
-      this.log(`Heartbeat sent (${latencyMs}ms)`);
+      const shardInfo = this.shardId !== void 0 ? ` [shard ${this.shardId}]` : "";
+      this.log(`Heartbeat sent (${latencyMs}ms)${shardInfo}`);
     } catch (error) {
       this.log("Heartbeat failed:", error);
     }
   }
   // ==========================================
+  // Gateway & Infrastructure Events
+  // ==========================================
+  /**
+   * Track a gateway event (reconnect, rate limit, etc.)
+   * 
+   * @example
+   * ```typescript
+   * // Track reconnects
+   * client.on('shardReconnecting', (shardId) => {
+   *   argus.trackGatewayEvent('reconnect', { shardId });
+   * });
+   * 
+   * // Track rate limits
+   * client.rest.on('rateLimited', (info) => {
+   *   argus.trackGatewayEvent('rate_limit', {
+   *     bucket: info.route,
+   *     retryAfter: info.retryAfter,
+   *   });
+   * });
+   * ```
+   */
+  async trackGatewayEvent(eventType, config) {
+    try {
+      const response = await fetch(`${this.endpoint}/api/infrastructure-events`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify({
+          events: [{
+            type: eventType,
+            shardId: config?.shardId ?? this.shardId,
+            metadata: {
+              bucket: config?.bucket,
+              retryAfter: config?.retryAfter,
+              ...config?.metadata
+            },
+            timestamp: Date.now()
+          }]
+        })
+      });
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      this.log(`Gateway event tracked: ${eventType}`, config?.shardId !== void 0 ? `[shard ${config.shardId}]` : "");
+    } catch (error) {
+      this.log("Failed to track gateway event:", error);
+    }
+  }
+  /**
+   * Track resource usage (CPU, memory, cache sizes)
+   * Call this periodically (e.g., every 60 seconds) to monitor resource usage
+   * 
+   * @example
+   * ```typescript
+   * // Track resources every minute
+   * setInterval(() => {
+   *   argus.trackResources({
+   *     memoryMb: process.memoryUsage().heapUsed / 1024 / 1024,
+   *     guildCount: client.guilds.cache.size,
+   *     cachedUsers: client.users.cache.size,
+   *   });
+   * }, 60000);
+   * ```
+   */
+  async trackResources(metrics) {
+    try {
+      const response = await fetch(`${this.endpoint}/api/resources`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify({
+          cpuPercent: metrics.cpuPercent,
+          memoryMb: metrics.memoryMb,
+          heapUsedMb: metrics.heapUsedMb,
+          heapTotalMb: metrics.heapTotalMb,
+          guildCount: metrics.guildCount,
+          cachedUsers: metrics.cachedUsers,
+          cachedChannels: metrics.cachedChannels,
+          shardId: metrics.shardId ?? this.shardId
+        })
+      });
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      this.log("Resource metrics tracked");
+    } catch (error) {
+      this.log("Failed to track resources:", error);
+    }
+  }
+  /**
+   * Attach to a Discord.js ShardingManager to auto-track shard events
+   * 
+   * @example
+   * ```typescript
+   * const manager = new ShardingManager('./bot.js', { ... });
+   * argus.attachToShardManager(manager);
+   * manager.spawn();
+   * ```
+   */
+  attachToShardManager(manager) {
+    this.log("Attaching to ShardingManager");
+    manager.on("shardCreate", (...args) => {
+      const shard = args[0];
+      this.trackGatewayEvent("spawn", { shardId: shard.id });
+    });
+    this.log("ShardingManager attached - spawn events will be tracked");
+  }
+  /**
+   * Set up automatic tracking for Discord.js client shard events
+   * Call this from within your bot process to track per-shard events
+   * 
+   * @example
+   * ```typescript
+   * // In your bot.js that runs in each shard
+   * argus.attachToClient(client);
+   * ```
+   */
+  attachToClient(client) {
+    if (client.shard) {
+      this.shardId = client.shard.ids[0];
+      this.shardCount = client.shard.count;
+    }
+    if (client.guilds?.cache) {
+      this.guildCount = client.guilds.cache.size;
+    }
+    client.on("ready", () => {
+      this.trackGatewayEvent("ready", { shardId: this.shardId });
+    });
+    client.on("shardReady", (...args) => {
+      const id = args[0];
+      this.trackGatewayEvent("ready", { shardId: id });
+    });
+    client.on("shardReconnecting", (...args) => {
+      const id = args[0];
+      this.trackGatewayEvent("reconnect", { shardId: id });
+    });
+    client.on("shardResume", (...args) => {
+      const id = args[0];
+      this.trackGatewayEvent("resume", { shardId: id });
+    });
+    client.on("shardDisconnect", (...args) => {
+      const id = args[1];
+      this.trackGatewayEvent("disconnect", { shardId: id });
+    });
+    if (client.rest) {
+      client.rest.on("rateLimited", (...args) => {
+        const info = args[0];
+        this.trackGatewayEvent("rate_limit", {
+          shardId: this.shardId,
+          bucket: info.route,
+          retryAfter: info.timeToReset,
+          metadata: { global: info.global }
+        });
+      });
+    }
+    this.log("Discord.js client attached - shard events will be tracked");
+  }
+  // ==========================================
   // Latency Tracking
   // ==========================================
   /**

package/dist/index.mjs

@@ -1,5 +1,5 @@
 // src/index.ts
-var SDK_VERSION = "0.3.0";
+var SDK_VERSION = "0.4.0";
 function hashString(str) {
   let hash = 0;
   for (let i = 0; i < str.length; i++) {
@@ -468,6 +468,12 @@ var Argus = class {
    * 
    * // Or customize the interval
    * argus.startHeartbeat({ interval: 60000 }); // 1 minute
+   * 
+   * // For sharded bots - track per-shard status
+   * argus.startHeartbeat({ 
+   *   shardId: shard.id, 
+   *   shardCount: client.shard?.count || 1 
+   * });
    * ```
    */
   startHeartbeat(config) {
@@ -477,11 +483,21 @@ var Argus = class {
     }
     const interval = config?.interval || this.heartbeatInterval;
     this.isHeartbeatEnabled = true;
+    if (config?.shardId !== void 0) {
+      this.shardId = config.shardId;
+    }
+    if (config?.shardCount !== void 0) {
+      this.shardCount = config.shardCount;
+    }
+    if (config?.guildCount !== void 0) {
+      this.guildCount = config.guildCount;
+    }
     this.sendHeartbeat();
     this.heartbeatTimer = setInterval(() => {
       this.sendHeartbeat();
     }, interval);
-    this.log(`Heartbeat started with ${interval}ms interval`);
+    const shardInfo = this.shardId !== void 0 ? ` (shard ${this.shardId}/${this.shardCount})` : "";
+    this.log(`Heartbeat started with ${interval}ms interval${shardInfo}`);
   }
   /**
    * Stop sending heartbeat pings
@@ -500,26 +516,194 @@ var Argus = class {
   async sendHeartbeat() {
     const startTime = Date.now();
     try {
-      const response = await fetch(`${this.endpoint}/api/heartbeat`, {
+      const endpoint = this.shardId !== void 0 ? `${this.endpoint}/api/shard-heartbeat` : `${this.endpoint}/api/heartbeat`;
+      const body = { timestamp: startTime };
+      if (this.shardId !== void 0) {
+        body.shardId = this.shardId;
+        body.shardCount = this.shardCount || 1;
+        body.guildCount = this.guildCount;
+      }
+      const response = await fetch(endpoint, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
           "Authorization": `Bearer ${this.apiKey}`
         },
-        body: JSON.stringify({
-          timestamp: startTime
-        })
+        body: JSON.stringify(body)
       });
       const latencyMs = Date.now() - startTime;
       if (!response.ok) {
         throw new Error(`HTTP ${response.status}: ${response.statusText}`);
       }
-      this.log(`Heartbeat sent (${latencyMs}ms)`);
+      const shardInfo = this.shardId !== void 0 ? ` [shard ${this.shardId}]` : "";
+      this.log(`Heartbeat sent (${latencyMs}ms)${shardInfo}`);
     } catch (error) {
       this.log("Heartbeat failed:", error);
     }
   }
   // ==========================================
+  // Gateway & Infrastructure Events
+  // ==========================================
+  /**
+   * Track a gateway event (reconnect, rate limit, etc.)
+   * 
+   * @example
+   * ```typescript
+   * // Track reconnects
+   * client.on('shardReconnecting', (shardId) => {
+   *   argus.trackGatewayEvent('reconnect', { shardId });
+   * });
+   * 
+   * // Track rate limits
+   * client.rest.on('rateLimited', (info) => {
+   *   argus.trackGatewayEvent('rate_limit', {
+   *     bucket: info.route,
+   *     retryAfter: info.retryAfter,
+   *   });
+   * });
+   * ```
+   */
+  async trackGatewayEvent(eventType, config) {
+    try {
+      const response = await fetch(`${this.endpoint}/api/infrastructure-events`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify({
+          events: [{
+            type: eventType,
+            shardId: config?.shardId ?? this.shardId,
+            metadata: {
+              bucket: config?.bucket,
+              retryAfter: config?.retryAfter,
+              ...config?.metadata
+            },
+            timestamp: Date.now()
+          }]
+        })
+      });
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      this.log(`Gateway event tracked: ${eventType}`, config?.shardId !== void 0 ? `[shard ${config.shardId}]` : "");
+    } catch (error) {
+      this.log("Failed to track gateway event:", error);
+    }
+  }
+  /**
+   * Track resource usage (CPU, memory, cache sizes)
+   * Call this periodically (e.g., every 60 seconds) to monitor resource usage
+   * 
+   * @example
+   * ```typescript
+   * // Track resources every minute
+   * setInterval(() => {
+   *   argus.trackResources({
+   *     memoryMb: process.memoryUsage().heapUsed / 1024 / 1024,
+   *     guildCount: client.guilds.cache.size,
+   *     cachedUsers: client.users.cache.size,
+   *   });
+   * }, 60000);
+   * ```
+   */
+  async trackResources(metrics) {
+    try {
+      const response = await fetch(`${this.endpoint}/api/resources`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify({
+          cpuPercent: metrics.cpuPercent,
+          memoryMb: metrics.memoryMb,
+          heapUsedMb: metrics.heapUsedMb,
+          heapTotalMb: metrics.heapTotalMb,
+          guildCount: metrics.guildCount,
+          cachedUsers: metrics.cachedUsers,
+          cachedChannels: metrics.cachedChannels,
+          shardId: metrics.shardId ?? this.shardId
+        })
+      });
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      this.log("Resource metrics tracked");
+    } catch (error) {
+      this.log("Failed to track resources:", error);
+    }
+  }
+  /**
+   * Attach to a Discord.js ShardingManager to auto-track shard events
+   * 
+   * @example
+   * ```typescript
+   * const manager = new ShardingManager('./bot.js', { ... });
+   * argus.attachToShardManager(manager);
+   * manager.spawn();
+   * ```
+   */
+  attachToShardManager(manager) {
+    this.log("Attaching to ShardingManager");
+    manager.on("shardCreate", (...args) => {
+      const shard = args[0];
+      this.trackGatewayEvent("spawn", { shardId: shard.id });
+    });
+    this.log("ShardingManager attached - spawn events will be tracked");
+  }
+  /**
+   * Set up automatic tracking for Discord.js client shard events
+   * Call this from within your bot process to track per-shard events
+   * 
+   * @example
+   * ```typescript
+   * // In your bot.js that runs in each shard
+   * argus.attachToClient(client);
+   * ```
+   */
+  attachToClient(client) {
+    if (client.shard) {
+      this.shardId = client.shard.ids[0];
+      this.shardCount = client.shard.count;
+    }
+    if (client.guilds?.cache) {
+      this.guildCount = client.guilds.cache.size;
+    }
+    client.on("ready", () => {
+      this.trackGatewayEvent("ready", { shardId: this.shardId });
+    });
+    client.on("shardReady", (...args) => {
+      const id = args[0];
+      this.trackGatewayEvent("ready", { shardId: id });
+    });
+    client.on("shardReconnecting", (...args) => {
+      const id = args[0];
+      this.trackGatewayEvent("reconnect", { shardId: id });
+    });
+    client.on("shardResume", (...args) => {
+      const id = args[0];
+      this.trackGatewayEvent("resume", { shardId: id });
+    });
+    client.on("shardDisconnect", (...args) => {
+      const id = args[1];
+      this.trackGatewayEvent("disconnect", { shardId: id });
+    });
+    if (client.rest) {
+      client.rest.on("rateLimited", (...args) => {
+        const info = args[0];
+        this.trackGatewayEvent("rate_limit", {
+          shardId: this.shardId,
+          bucket: info.route,
+          retryAfter: info.timeToReset,
+          metadata: { global: info.global }
+        });
+      });
+    }
+    this.log("Discord.js client attached - shard events will be tracked");
+  }
+  // ==========================================
   // Latency Tracking
   // ==========================================
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argus-discord-analytics",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "The all-seeing analytics SDK for Discord bots - track commands, errors, servers, and more",
   "main": "dist/index.js",
   "module": "dist/index.mjs",