API Documentation for mrsmalvic

:D

Location Endpoints

Base path: /api/user/:username/location

GET /api/user/:username/location

• Description: Retrieves the stored location for a given username.
• Parameters:
  • username (URL path): The username to query.
• Response (Success):

  { "success": true, "username": "testuser", "location": "City, Country" }
  

  or

  { "success": true, "username": "testuser", "location": null }
  

• Response (Error):

  { "success": false, "error": "Failed to fetch location" }
  

POST /api/user/:username/location

• Description: Sets or updates the location for a given username.
• Parameters:
  • username (URL path): The username to update.
• Request Body:

  {
    "location": "New City, Country",
    "hidden": false // Optional, boolean
  }
  

• Response (Success):

  { "success": true, "username": "testuser", "location": "New City, Country", "hidden": false }
  

• Response (Error):
  • Status 400: { "success": false, "error": "Location is required" }
  • Status 500: { "success": false, "error": "Failed to set location" }

DELETE /api/user/:username/location

• Description: Deletes the location for a given username (effectively sets it to null).
• Parameters:
  • username (URL path): The username whose location should be deleted.
• Response (Success):

  { "success": true, "username": "testuser", "message": "Location deleted" }
  

• Response (Error):

  { "success": false, "error": "Failed to delete location" }
  

Last.fm Endpoints

Base path: /api/user/:username/lastfm

GET /api/user/:username/lastfm

• Description: Retrieves the stored Last.fm username for a given user.
• Parameters:
  • username (URL path): The username to query.
• Response (Success):

  { "success": true, "username": "testuser", "lastfmUsername": "lastfmuser" }
  

  or

  { "success": true, "username": "testuser", "lastfmUsername": null }
  

• Response (Error):

  { "success": false, "error": "Failed to fetch LastFM username" }
  

POST /api/user/:username/lastfm

• Description: Sets or updates the Last.fm username for a given user.
• Parameters:
  • username (URL path): The username to update.
• Request Body:

  {
    "lastfmUsername": "newlastfmuser"
  }
  

• Response (Success):

  { "success": true, "username": "testuser", "lastfmUsername": "newlastfmuser" }
  

• Response (Error):
  • Status 400: { "success": false, "error": "LastFM username is required" }
  • Status 500: { "success": false, "error": "Failed to set LastFM username" }

DELETE /api/user/:username/lastfm

• Description: Deletes the Last.fm username for a given user (effectively sets it to null).
• Parameters:
  • username (URL path): The username whose Last.fm username should be deleted.
• Response (Success):

  { "success": true, "username": "testuser", "message": "LastFM username deleted" }
  

• Response (Error):

  { "success": false, "error": "Failed to delete LastFM username" }
  

User Preferences Endpoints

Base path: /api/user/:username/preferences

GET /api/user/:username/preferences

• Description: Retrieves all command opt-out preferences for a given user.
• Parameters:
  • username (URL path): The username to query.
• Response (Success):

  {
    "success": true,
    "username": "testuser",
    "optedOutCommands": ["command1", "command2"]
  }
  

  or (if no preferences found)

  {
    "success": true,
    "username": "testuser",
    "optedOutCommands": []
  }
  

• Response (Error):

  { "success": false, "error": "Failed to fetch user preferences" }
  

GET /api/user/:username/preferences/:command

• Description: Checks if a user has opted out of a specific command.
• Parameters:
  • username (URL path): The username to query.
  • command (URL path): The command name to check.
• Response (Success):

  { "success": true, "username": "testuser", "command": "command1", "isOptedOut": true }
  

• Response (Error):

  { "success": false, "error": "Failed to check opt-out status" }
  

POST /api/user/:username/optout

• Description: Adds a command to the user's opt-out list.
• Parameters:
  • username (URL path): The username to update.
• Request Body:

  {
    "command": "command_to_opt_out"
  }
  

• Response (Success):

  { "success": true, "username": "testuser", "command": "command_to_opt_out", "action": "opted-out" }
  

• Response (Error):
  • Status 400: { "success": false, "error": "Command name is required" }
  • Status 500: { "success": false, "error": "Failed to opt out of command" }

POST /api/user/:username/optin

• Description: Removes a command from the user's opt-out list (opts them back in).
• Parameters:
  • username (URL path): The username to update.
• Request Body:

  {
    "command": "command_to_opt_in"
  }
  

• Response (Success):

  { "success": true, "username": "testuser", "command": "command_to_opt_in", "action": "opted-in" }
  

• Response (Error):
  • Status 400: { "success": false, "error": "Command name is required" }
  • Status 500: { "success": false, "error": "Failed to opt in to command" }

POST /api/user/:username/preferences

• Description: Bulk updates (replaces) the entire list of opted-out commands for a user.
• Parameters:
  • username (URL path): The username to update.
• Request Body:

  {
    "optedOutCommands": ["new_command1", "new_command2"]
  }
  

• Response (Success):

  {
    "success": true,
    "username": "testuser",
    "optedOutCommands": ["new_command1", "new_command2"],
    "message": "Preferences updated successfully"
  }
  

• Response (Error):
  • Status 400: { "success": false, "error": "optedOutCommands must be an array" }
  • Status 500: { "success": false, "error": "Failed to update user preferences" }

Reminder Endpoints

Base path: /api/reminders and /api/user/:username/reminders

GET /api/user/:username/reminders

• Description: Retrieves all reminders associated with a user (sent, received, and self-reminders). Connects directly to MongoDB collections user_reminders and reminders.
• Parameters:
  • username (URL path): The username to query.
• Query Parameters:
  • type (optional): Filter reminders by type (sent, received, self). If omitted, returns all types.
• Response (Success):

  {
    "success": true,
    "username": "testuser",
    "reminders": [
      {
        "id": "abc123xyz", // friendlyId
        "type": "sent", // or "received", "self"
        "message": "Reminder message",
        "createdAt": "2025-04-14T18:00:00.000Z",
        "reminderTime": "2025-04-14T18:00:00.000Z", // or createdAt for self/user reminders
        "delivered": false, // or true
        "fromUser": "testuser", // or sender if type is 'received'
        "targetUser": "anotheruser", // or recipient if type is 'sent', or self if type is 'self'
        "channel": "#channelname" // Optional
      },
      // ... more reminders
    ]
  }
  

• Response (Error):

  { "success": false, "error": "Failed to fetch reminders" }
  

GET /api/reminders/:friendlyId

• Description: Retrieves a specific reminder by its friendlyId. Checks both user_reminders and reminders collections.
• Parameters:
  • friendlyId (URL path): The unique ID of the reminder.
• Response (Success):

  {
    "success": true,
    "reminder": {
      "id": "abc123xyz",
      "type": "user", // or "self"
      "message": "Reminder message",
      "createdAt": "2025-04-14T18:00:00.000Z",
      "reminderTime": "2025-04-14T18:00:00.000Z",
      "delivered": false,
      "fromUser": "sender",
      "targetUser": "recipient", // or self username
      "channel": "#channelname"
    }
  }
  

• Response (Error):
  • Status 404: { "success": false, "error": "Reminder not found" }
  • Status 500: { "success": false, "error": "Failed to fetch reminder" }

PUT /api/reminders/:id

• Description: Updates the message of an existing reminder. Uses the URL parameter :id as the friendlyId for lookup. Only the sender of a user reminder or the owner of a self-reminder can update it. Delivered user reminders cannot be edited.
• Parameters:
  • id (URL path): The friendlyId of the reminder to update.
• Request Body:

  {
    "message": "Updated reminder message",
    "username": "testuser" // The username attempting the update
  }
  

• Response (Success):

  {
    "success": true,
    "reminder": { ... updated reminder object ... }
  }
  

• Response (Error):
  • Status 400: { "success": false, "error": "Message is required" }
  • Status 403: { "success": false, "error": "Cannot edit a reminder that has already been delivered" }
  • Status 404: { "success": false, "error": "Reminder not found or you do not have permission to update it" }
  • Status 500: { "success": false, "error": "Failed to update reminder" }

DELETE /api/reminders/:id

• Description: Deletes a reminder by its friendlyId. Only the sender/owner can delete it. Uses the URL parameter :id as the friendlyId. Includes extensive logging and multiple query attempts to handle potential ID type mismatches.
• Parameters:
  • id (URL path): The friendlyId of the reminder to delete.
• Request Body:

  {
    "username": "testuser" // The username attempting the deletion
  }
  

• Response (Success):

  { "success": true, "message": "Reminder deleted successfully" }
  

• Response (Error):
  • Status 400: { "success": false, "error": "Username is required" }
  • Status 404: { "success": false, "error": "Reminder not found or you do not have permission to delete it" }
  • Status 500: { "success": false, "error": "Failed to delete reminder" }

Command Statistics Endpoints

Base path: /api/stats

GET /api/stats/commands

• Description: Retrieves summary statistics for all commands tracked. Data comes from the command_stats collection.
• Parameters: None.
• Response (Success):

  {
    "success": true,
    "data": [
      {
        "command": "weather",
        "useCount": 150,
        "successCount": 145,
        "failureCount": 5,
        "lastUsed": "2025-04-19T01:20:00.000Z"
      },
      {
        "command": "time",
        "useCount": 120,
        "successCount": 120,
        "failureCount": 0,
        "lastUsed": "2025-04-19T01:15:00.000Z"
      }
      // ... more commands sorted by useCount descending
    ]
  }
  

• Response (Error):

  { "success": false, "error": "Failed to fetch command stats" }
  

GET /api/stats/commands/:commandName

• Description: Retrieves detailed statistics for a specific command from the command_stats collection, including recent usage examples.
• Parameters:
  • commandName (URL path): The name of the command (case-insensitive).
• Response (Success):

  {
    "success": true,
    "data": {
      "command": "weather",
      "useCount": 150,
      "successCount": 145,
      "failureCount": 5,
      "lastUsed": "2025-04-19T01:20:00.000Z",
      "recentUsage": [
        { "username": "user1", "channel": "channel1", "timestamp": "2025-04-19T01:20:00.000Z", "success": true },
        { "username": "user2", "channel": "channel2", "timestamp": "2025-04-19T01:18:00.000Z", "success": false }
        // ... up to 100 recent usages
      ]
    }
  }
  

• Response (Success - Basic Count from Logs): If the command exists in command_usage_logs but not command_stats:

  {
      "success": true,
      "data": {
          "command": "somecommand",
          "useCount": 5,
          "successCount": 0,
          "failureCount": 0,
          "lastUsed": null,
          "recentUsage": []
      },
      "message": "Stats summary not generated, returning basic count from logs."
  }
  

• Response (Error):
  • Status 404: { "success": false, "error": "Stats not found for command: <commandName>" }
  • Status 500: { "success": false, "error": "Failed to fetch command stats" }

GET /api/stats/users/:username

• Description: Retrieves command usage statistics aggregated by command for a specific user. Data is aggregated from the command_usage_logs collection.
• Parameters:
  • username (URL path): The username to query (case-insensitive).
• Response (Success):

  {
    "success": true,
    "data": [
      {
        "command": "weather",
        "totalUses": 25,
        "successfulUses": 24,
        "failedUses": 1,
        "lastUsed": "2025-04-19T01:20:00.000Z",
        "avgResponseTime": 150.5 // milliseconds, null if no response times logged
      },
      {
        "command": "time",
        "totalUses": 10,
        "successfulUses": 10,
        "failedUses": 0,
        "lastUsed": "2025-04-18T23:55:00.000Z",
        "avgResponseTime": 50.0
      }
      // ... more commands sorted by totalUses descending
    ]
  }
  

• Response (Error):

  { "success": false, "error": "Failed to fetch user stats" }
  

GET /api/stats/channels/:channelName

• Description: Retrieves command usage statistics aggregated by command for a specific channel. Data is aggregated from the command_usage_logs collection.
• Parameters:
  • channelName (URL path): The channel name to query (case-insensitive).
• Response (Success):

  {
    "success": true,
    "data": [
      {
        "command": "weather",
        "totalUses": 50,
        "uniqueUserCount": 15,
        "successfulUses": 48,
        "failedUses": 2,
        "lastUsed": "2025-04-19T01:20:00.000Z"
      },
      {
        "command": "followage",
        "totalUses": 30,
        "uniqueUserCount": 20,
        "successfulUses": 30,
        "failedUses": 0,
        "lastUsed": "2025-04-19T00:10:00.000Z"
      }
      // ... more commands sorted by totalUses descending
    ]
  }
  

• Response (Error):

  { "success": false, "error": "Failed to fetch channel stats" }
  

GET /api/stats/global

• Description: Retrieves overall global bot usage statistics aggregated from the command_usage_logs collection.
• Parameters: None.
• Response (Success):

  {
    "success": true,
    "data": {
      "totalCommands": 10532,
      "uniqueUsers": 521,
      "uniqueChannels": 85,
      "uniqueCommands": 45,
      "successRate": 98.5, // Percentage
      "avgResponseTime": 112.7 // milliseconds, null if no response times logged
    }
  }
  

  or (if no logs exist yet)

  {
    "success": true,
    "data": {}
  }
  

• Response (Error):

  { "success": false, "error": "Failed to fetch global stats" }
  

GET /api/stats/logs

• Description: Retrieves raw command usage logs from the command_usage_logs collection, with filtering options.
• Parameters: None.
• Query Parameters (Optional):
  • startDate (string): Filter logs on or after this date/time (ISO 8601 or YYYY-MM-DD format).
  • endDate (string): Filter logs on or before this date/time (ISO 8601 or YYYY-MM-DD format). If YYYY-MM-DD, includes the entire day.
  • limit (integer): Maximum number of logs to return (default: 100, max: 1000).
  • username (string): Filter logs by username (case-insensitive).
  • channel (string): Filter logs by channel name (case-insensitive).
  • command (string): Filter logs by command name (case-insensitive).
  • success (boolean): Filter logs by success status (true or false).
• Response (Success):

  {
    "success": true,
    "data": [
      {
        "command": "weather",
        "username": "user1",
        "channel": "channel1",
        "args": ["London"],
        "success": true,
        "responseTime": 180, // milliseconds
        "timestamp": "2025-04-19T01:20:00.000Z",
        "date": "2025-04-19"
      },
      {
        "command": "time",
        "username": "user2",
        "channel": "channel2",
        "args": [],
        "success": true,
        "responseTime": 45,
        "timestamp": "2025-04-19T01:15:00.000Z",
        "date": "2025-04-19"
      }
      // ... more logs sorted by timestamp descending, up to the limit
    ]
  }
  

• Response (Error):
  • Status 400: { "success": false, "error": "Invalid <parameter> format..." }
  • Status 500: { "success": false, "error": "Failed to fetch command usage logs" }