argus-discord-analytics 0.2.2 → 0.3.0

package/dist/index.d.mts

@@ -21,7 +21,7 @@
  * argus.trackRevenue({ source: 'patreon', amount: 500, tier: 'Premium' });
  * ```
  */
-declare const SDK_VERSION = "0.2.2";
+declare const SDK_VERSION = "0.3.0";
 interface ArgusConfig {
     /** Your Argus API key (starts with arg_live_ or arg_test_) */
     apiKey: string;
@@ -52,6 +52,23 @@ interface TrackEvent {
     metadata?: Record<string, unknown>;
     timestamp?: number;
     latencyMs?: number;
+    /** User segment for monetization analytics (e.g., 'premium', 'free', 'trial') */
+    segment?: string;
+}
+/**
+ * Options for tracking with user segmentation
+ * Use segment to track premium vs free user behavior
+ */
+interface TrackOptions {
+    serverId?: string;
+    userId?: string;
+    metadata?: Record<string, unknown>;
+    /**
+     * User segment for monetization analytics.
+     * Track premium vs free users to see conversion insights.
+     * @example 'premium', 'free', 'trial', 'supporter', 'legendary'
+     */
+    segment?: string;
 }
 interface HeartbeatConfig {
     /** Heartbeat interval in ms (default: 30000) */
@@ -112,6 +129,9 @@ declare class Argus {
      * client.on('interactionCreate', (interaction) => {
      *   argus.track(interaction);
      * });
+     *
+     * // With user segmentation for premium vs free analytics
+     * argus.track(interaction, { segment: user.isPremium ? 'premium' : 'free' });
      * ```
      */
     track(interaction: {
@@ -127,15 +147,22 @@ declare class Argus {
         message?: {
             id: string;
         };
+    }, options?: {
+        segment?: string;
     }): void;
     /**
      * Track a custom event
+     *
+     * @example
+     * ```typescript
+     * // Track with user segment for monetization analytics
+     * argus.trackEvent('command', 'gacha', {
+     *   segment: user.tier, // 'supporter', 'epic', 'legendary'
+     *   userId: user.id,
+     * });
+     * ```
      */
-    trackEvent(type: 'command' | 'error' | 'custom', name: string, options?: {
-        serverId?: string;
-        userId?: string;
-        metadata?: Record<string, unknown>;
-    }): void;
+    trackEvent(type: 'command' | 'error' | 'custom', name: string, options?: TrackOptions): void;
     /**
      * Track a command (convenience method)
      * Accepts either a command name string or a Discord.js interaction object
@@ -146,10 +173,14 @@ declare class Argus {
      * // Automatically extracts subcommands: /show profile -> "show profile"
      * argus.trackCommand(interaction);
      *
-     * // Option 2: Pass command name as string
+     * // Option 2: With user segmentation for premium vs free analytics
+     * argus.trackCommand(interaction, { segment: user.isPremium ? 'premium' : 'free' });
+     *
+     * // Option 3: Pass command name as string
      * argus.trackCommand('ban', {
      *   serverId: interaction.guildId,
-     *   userId: interaction.user.id
+     *   userId: interaction.user.id,
+     *   segment: 'premium',
      * });
      * ```
      */
@@ -161,11 +192,7 @@ declare class Argus {
             id: string;
         };
         options?: unknown;
-    }, options?: {
-        serverId?: string;
-        userId?: string;
-        metadata?: Record<string, unknown>;
-    }): void;
+    }, options?: TrackOptions): void;
     /**
      * Track an error
      */
@@ -174,6 +201,8 @@ declare class Argus {
         serverId?: string;
         userId?: string;
         metadata?: Record<string, unknown>;
+        /** User segment for monetization analytics */
+        segment?: string;
     }): void;
     /**
      * Track a button click interaction
@@ -186,6 +215,9 @@ declare class Argus {
      *     // Tracked as: "button:buy_premium"
      *   }
      * });
+     *
+     * // With user segmentation
+     * argus.trackButton(interaction, { segment: 'premium' });
      * ```
      */
     trackButton(interaction: {
@@ -197,6 +229,8 @@ declare class Argus {
         message?: {
             id: string;
         };
+    }, options?: {
+        segment?: string;
     }): void;
     /**
      * Track a select menu interaction
@@ -210,6 +244,9 @@ declare class Argus {
      *     // Metadata includes: selectedValues
      *   }
      * });
+     *
+     * // With user segmentation
+     * argus.trackSelectMenu(interaction, { segment: 'premium' });
      * ```
      */
     trackSelectMenu(interaction: {
@@ -219,6 +256,8 @@ declare class Argus {
         user?: {
             id: string;
         };
+    }, options?: {
+        segment?: string;
     }): void;
     /**
      * Track server join or leave events
@@ -334,19 +373,17 @@ declare class Argus {
         };
         type?: number;
         options?: unknown;
+    }, options?: {
+        segment?: string;
     }): 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;
+    trackEventWithLatency(type: 'command' | 'error' | 'custom', name: string, latencyMs: number, options?: TrackOptions): void;
     /**
      * Shutdown the Argus instance, flushing any remaining events
      */
     shutdown(): Promise<void>;
 }
 
-export { Argus, type ArgusConfig, type HeartbeatConfig, type RevenueEvent, SDK_VERSION, type ServerEvent, type TrackEvent, Argus as default };
+export { Argus, type ArgusConfig, type HeartbeatConfig, 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.2.2";
+declare const SDK_VERSION = "0.3.0";
 interface ArgusConfig {
     /** Your Argus API key (starts with arg_live_ or arg_test_) */
     apiKey: string;
@@ -52,6 +52,23 @@ interface TrackEvent {
     metadata?: Record<string, unknown>;
     timestamp?: number;
     latencyMs?: number;
+    /** User segment for monetization analytics (e.g., 'premium', 'free', 'trial') */
+    segment?: string;
+}
+/**
+ * Options for tracking with user segmentation
+ * Use segment to track premium vs free user behavior
+ */
+interface TrackOptions {
+    serverId?: string;
+    userId?: string;
+    metadata?: Record<string, unknown>;
+    /**
+     * User segment for monetization analytics.
+     * Track premium vs free users to see conversion insights.
+     * @example 'premium', 'free', 'trial', 'supporter', 'legendary'
+     */
+    segment?: string;
 }
 interface HeartbeatConfig {
     /** Heartbeat interval in ms (default: 30000) */
@@ -112,6 +129,9 @@ declare class Argus {
      * client.on('interactionCreate', (interaction) => {
      *   argus.track(interaction);
      * });
+     *
+     * // With user segmentation for premium vs free analytics
+     * argus.track(interaction, { segment: user.isPremium ? 'premium' : 'free' });
      * ```
      */
     track(interaction: {
@@ -127,15 +147,22 @@ declare class Argus {
         message?: {
             id: string;
         };
+    }, options?: {
+        segment?: string;
     }): void;
     /**
      * Track a custom event
+     *
+     * @example
+     * ```typescript
+     * // Track with user segment for monetization analytics
+     * argus.trackEvent('command', 'gacha', {
+     *   segment: user.tier, // 'supporter', 'epic', 'legendary'
+     *   userId: user.id,
+     * });
+     * ```
      */
-    trackEvent(type: 'command' | 'error' | 'custom', name: string, options?: {
-        serverId?: string;
-        userId?: string;
-        metadata?: Record<string, unknown>;
-    }): void;
+    trackEvent(type: 'command' | 'error' | 'custom', name: string, options?: TrackOptions): void;
     /**
      * Track a command (convenience method)
      * Accepts either a command name string or a Discord.js interaction object
@@ -146,10 +173,14 @@ declare class Argus {
      * // Automatically extracts subcommands: /show profile -> "show profile"
      * argus.trackCommand(interaction);
      *
-     * // Option 2: Pass command name as string
+     * // Option 2: With user segmentation for premium vs free analytics
+     * argus.trackCommand(interaction, { segment: user.isPremium ? 'premium' : 'free' });
+     *
+     * // Option 3: Pass command name as string
      * argus.trackCommand('ban', {
      *   serverId: interaction.guildId,
-     *   userId: interaction.user.id
+     *   userId: interaction.user.id,
+     *   segment: 'premium',
      * });
      * ```
      */
@@ -161,11 +192,7 @@ declare class Argus {
             id: string;
         };
         options?: unknown;
-    }, options?: {
-        serverId?: string;
-        userId?: string;
-        metadata?: Record<string, unknown>;
-    }): void;
+    }, options?: TrackOptions): void;
     /**
      * Track an error
      */
@@ -174,6 +201,8 @@ declare class Argus {
         serverId?: string;
         userId?: string;
         metadata?: Record<string, unknown>;
+        /** User segment for monetization analytics */
+        segment?: string;
     }): void;
     /**
      * Track a button click interaction
@@ -186,6 +215,9 @@ declare class Argus {
      *     // Tracked as: "button:buy_premium"
      *   }
      * });
+     *
+     * // With user segmentation
+     * argus.trackButton(interaction, { segment: 'premium' });
      * ```
      */
     trackButton(interaction: {
@@ -197,6 +229,8 @@ declare class Argus {
         message?: {
             id: string;
         };
+    }, options?: {
+        segment?: string;
     }): void;
     /**
      * Track a select menu interaction
@@ -210,6 +244,9 @@ declare class Argus {
      *     // Metadata includes: selectedValues
      *   }
      * });
+     *
+     * // With user segmentation
+     * argus.trackSelectMenu(interaction, { segment: 'premium' });
      * ```
      */
     trackSelectMenu(interaction: {
@@ -219,6 +256,8 @@ declare class Argus {
         user?: {
             id: string;
         };
+    }, options?: {
+        segment?: string;
     }): void;
     /**
      * Track server join or leave events
@@ -334,19 +373,17 @@ declare class Argus {
         };
         type?: number;
         options?: unknown;
+    }, options?: {
+        segment?: string;
     }): 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;
+    trackEventWithLatency(type: 'command' | 'error' | 'custom', name: string, latencyMs: number, options?: TrackOptions): void;
     /**
      * Shutdown the Argus instance, flushing any remaining events
      */
     shutdown(): Promise<void>;
 }
 
-export { Argus, type ArgusConfig, type HeartbeatConfig, type RevenueEvent, SDK_VERSION, type ServerEvent, type TrackEvent, Argus as default };
+export { Argus, type ArgusConfig, type HeartbeatConfig, 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.2.2";
+var SDK_VERSION = "0.3.0";
 function hashString(str) {
   let hash = 0;
   for (let i = 0; i < str.length; i++) {
@@ -135,9 +135,12 @@ var Argus = class {
    * client.on('interactionCreate', (interaction) => {
    *   argus.track(interaction);
    * });
+   * 
+   * // With user segmentation for premium vs free analytics
+   * argus.track(interaction, { segment: user.isPremium ? 'premium' : 'free' });
    * ```
    */
-  track(interaction) {
+  track(interaction, options) {
     if (interaction.customId && !interaction.commandName) {
       if (Array.isArray(interaction.values)) {
         return this.trackSelectMenu({
@@ -145,14 +148,14 @@ var Argus = class {
           values: interaction.values,
           guildId: interaction.guildId,
           user: interaction.user
-        });
+        }, options);
       }
       return this.trackButton({
         customId: interaction.customId,
         guildId: interaction.guildId,
         user: interaction.user,
         message: interaction.message
-      });
+      }, options);
     }
     const name = extractFullCommandName(interaction);
     const serverId = interaction.guildId || void 0;
@@ -160,6 +163,7 @@ var Argus = class {
     this.trackEvent("command", name, {
       serverId,
       userId,
+      segment: options?.segment,
       metadata: {
         interactionType: interaction.type
       }
@@ -167,6 +171,15 @@ var Argus = class {
   }
   /**
    * Track a custom event
+   * 
+   * @example
+   * ```typescript
+   * // Track with user segment for monetization analytics
+   * argus.trackEvent('command', 'gacha', {
+   *   segment: user.tier, // 'supporter', 'epic', 'legendary'
+   *   userId: user.id,
+   * });
+   * ```
    */
   trackEvent(type, name, options) {
     const event = {
@@ -176,6 +189,7 @@ var Argus = class {
       userId: options?.userId,
       userHash: options?.userId && this.hashUserIds ? hashString(options.userId) : options?.userId,
       metadata: options?.metadata,
+      segment: options?.segment,
       timestamp: Date.now()
     };
     if (this.hashUserIds) {
@@ -197,10 +211,14 @@ var Argus = class {
    * // Automatically extracts subcommands: /show profile -> "show profile"
    * argus.trackCommand(interaction);
    * 
-   * // Option 2: Pass command name as string
+   * // Option 2: With user segmentation for premium vs free analytics
+   * argus.trackCommand(interaction, { segment: user.isPremium ? 'premium' : 'free' });
+   * 
+   * // Option 3: Pass command name as string
    * argus.trackCommand('ban', {
    *   serverId: interaction.guildId,
-   *   userId: interaction.user.id
+   *   userId: interaction.user.id,
+   *   segment: 'premium',
    * });
    * ```
    */
@@ -216,6 +234,12 @@ var Argus = class {
           serverId: commandOrInteraction.guildId || void 0,
           userId: commandOrInteraction.user?.id
         };
+      } else if (!extractedOptions.serverId && !extractedOptions.userId) {
+        extractedOptions = {
+          ...extractedOptions,
+          serverId: commandOrInteraction.guildId || void 0,
+          userId: commandOrInteraction.user?.id
+        };
       }
     }
     this.trackEvent("command", commandName, extractedOptions);
@@ -229,6 +253,7 @@ var Argus = class {
     this.trackEvent("error", errorMessage, {
       serverId: options?.serverId,
       userId: options?.userId,
+      segment: options?.segment,
       metadata: {
         ...options?.metadata,
         command: options?.command,
@@ -247,12 +272,16 @@ var Argus = class {
    *     // Tracked as: "button:buy_premium"
    *   }
    * });
+   * 
+   * // With user segmentation
+   * argus.trackButton(interaction, { segment: 'premium' });
    * ```
    */
-  trackButton(interaction) {
+  trackButton(interaction, options) {
     this.trackEvent("custom", `button:${interaction.customId}`, {
       serverId: interaction.guildId || void 0,
       userId: interaction.user?.id,
+      segment: options?.segment,
       metadata: {
         interactionType: "button",
         customId: interaction.customId,
@@ -272,12 +301,16 @@ var Argus = class {
    *     // Metadata includes: selectedValues
    *   }
    * });
+   * 
+   * // With user segmentation
+   * argus.trackSelectMenu(interaction, { segment: 'premium' });
    * ```
    */
-  trackSelectMenu(interaction) {
+  trackSelectMenu(interaction, options) {
     this.trackEvent("custom", `select:${interaction.customId}`, {
       serverId: interaction.guildId || void 0,
       userId: interaction.user?.id,
+      segment: options?.segment,
       metadata: {
         interactionType: "select_menu",
         customId: interaction.customId,
@@ -540,11 +573,11 @@ var Argus = class {
    * End timing and track the command with latency
    * Automatically extracts subcommands from the interaction
    */
-  endTimer(timerId, interaction) {
+  endTimer(timerId, interaction, options) {
     const startTime = this.commandStartTimes.get(timerId);
     if (!startTime) {
       this.log("Timer not found:", timerId);
-      this.track(interaction);
+      this.track(interaction, options);
       return;
     }
     const latencyMs = Date.now() - startTime;
@@ -555,6 +588,7 @@ var Argus = class {
     this.trackEventWithLatency("command", name, latencyMs, {
       serverId,
       userId,
+      segment: options?.segment,
       metadata: {
         interactionType: interaction.type
       }
@@ -574,6 +608,7 @@ var Argus = class {
         ...options?.metadata,
         latencyMs
       },
+      segment: options?.segment,
       latencyMs,
       timestamp: Date.now()
     };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 // src/index.ts
-var SDK_VERSION = "0.2.2";
+var SDK_VERSION = "0.3.0";
 function hashString(str) {
   let hash = 0;
   for (let i = 0; i < str.length; i++) {
@@ -109,9 +109,12 @@ var Argus = class {
    * client.on('interactionCreate', (interaction) => {
    *   argus.track(interaction);
    * });
+   * 
+   * // With user segmentation for premium vs free analytics
+   * argus.track(interaction, { segment: user.isPremium ? 'premium' : 'free' });
    * ```
    */
-  track(interaction) {
+  track(interaction, options) {
     if (interaction.customId && !interaction.commandName) {
       if (Array.isArray(interaction.values)) {
         return this.trackSelectMenu({
@@ -119,14 +122,14 @@ var Argus = class {
           values: interaction.values,
           guildId: interaction.guildId,
           user: interaction.user
-        });
+        }, options);
       }
       return this.trackButton({
         customId: interaction.customId,
         guildId: interaction.guildId,
         user: interaction.user,
         message: interaction.message
-      });
+      }, options);
     }
     const name = extractFullCommandName(interaction);
     const serverId = interaction.guildId || void 0;
@@ -134,6 +137,7 @@ var Argus = class {
     this.trackEvent("command", name, {
       serverId,
       userId,
+      segment: options?.segment,
       metadata: {
         interactionType: interaction.type
       }
@@ -141,6 +145,15 @@ var Argus = class {
   }
   /**
    * Track a custom event
+   * 
+   * @example
+   * ```typescript
+   * // Track with user segment for monetization analytics
+   * argus.trackEvent('command', 'gacha', {
+   *   segment: user.tier, // 'supporter', 'epic', 'legendary'
+   *   userId: user.id,
+   * });
+   * ```
    */
   trackEvent(type, name, options) {
     const event = {
@@ -150,6 +163,7 @@ var Argus = class {
       userId: options?.userId,
       userHash: options?.userId && this.hashUserIds ? hashString(options.userId) : options?.userId,
       metadata: options?.metadata,
+      segment: options?.segment,
       timestamp: Date.now()
     };
     if (this.hashUserIds) {
@@ -171,10 +185,14 @@ var Argus = class {
    * // Automatically extracts subcommands: /show profile -> "show profile"
    * argus.trackCommand(interaction);
    * 
-   * // Option 2: Pass command name as string
+   * // Option 2: With user segmentation for premium vs free analytics
+   * argus.trackCommand(interaction, { segment: user.isPremium ? 'premium' : 'free' });
+   * 
+   * // Option 3: Pass command name as string
    * argus.trackCommand('ban', {
    *   serverId: interaction.guildId,
-   *   userId: interaction.user.id
+   *   userId: interaction.user.id,
+   *   segment: 'premium',
    * });
    * ```
    */
@@ -190,6 +208,12 @@ var Argus = class {
           serverId: commandOrInteraction.guildId || void 0,
           userId: commandOrInteraction.user?.id
         };
+      } else if (!extractedOptions.serverId && !extractedOptions.userId) {
+        extractedOptions = {
+          ...extractedOptions,
+          serverId: commandOrInteraction.guildId || void 0,
+          userId: commandOrInteraction.user?.id
+        };
       }
     }
     this.trackEvent("command", commandName, extractedOptions);
@@ -203,6 +227,7 @@ var Argus = class {
     this.trackEvent("error", errorMessage, {
       serverId: options?.serverId,
       userId: options?.userId,
+      segment: options?.segment,
       metadata: {
         ...options?.metadata,
         command: options?.command,
@@ -221,12 +246,16 @@ var Argus = class {
    *     // Tracked as: "button:buy_premium"
    *   }
    * });
+   * 
+   * // With user segmentation
+   * argus.trackButton(interaction, { segment: 'premium' });
    * ```
    */
-  trackButton(interaction) {
+  trackButton(interaction, options) {
     this.trackEvent("custom", `button:${interaction.customId}`, {
       serverId: interaction.guildId || void 0,
       userId: interaction.user?.id,
+      segment: options?.segment,
       metadata: {
         interactionType: "button",
         customId: interaction.customId,
@@ -246,12 +275,16 @@ var Argus = class {
    *     // Metadata includes: selectedValues
    *   }
    * });
+   * 
+   * // With user segmentation
+   * argus.trackSelectMenu(interaction, { segment: 'premium' });
    * ```
    */
-  trackSelectMenu(interaction) {
+  trackSelectMenu(interaction, options) {
     this.trackEvent("custom", `select:${interaction.customId}`, {
       serverId: interaction.guildId || void 0,
       userId: interaction.user?.id,
+      segment: options?.segment,
       metadata: {
         interactionType: "select_menu",
         customId: interaction.customId,
@@ -514,11 +547,11 @@ var Argus = class {
    * End timing and track the command with latency
    * Automatically extracts subcommands from the interaction
    */
-  endTimer(timerId, interaction) {
+  endTimer(timerId, interaction, options) {
     const startTime = this.commandStartTimes.get(timerId);
     if (!startTime) {
       this.log("Timer not found:", timerId);
-      this.track(interaction);
+      this.track(interaction, options);
       return;
     }
     const latencyMs = Date.now() - startTime;
@@ -529,6 +562,7 @@ var Argus = class {
     this.trackEventWithLatency("command", name, latencyMs, {
       serverId,
       userId,
+      segment: options?.segment,
       metadata: {
         interactionType: interaction.type
       }
@@ -548,6 +582,7 @@ var Argus = class {
         ...options?.metadata,
         latencyMs
       },
+      segment: options?.segment,
       latencyMs,
       timestamp: Date.now()
     };

package/package.json

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