thislooksfun/snoots

Modnotes

jamesrswift opened this issue · 1 comments

jamesrswift commented

Feature Description

Moderator Notes

I feel like there should be a discussion on how/where modnotes are implemented, as a call to the API requires both a subreddit and a username. There are several questions then on how it should be implemented:

  • Should Modnotes be implemented on a subreddit object or a user object, or both?
  • Should modnotes have its own controller and defined on the client class?
  • Should it take subreddits and users as strings (usernames) or as snoot objects? or both?

Typings

There are also issues on the typings of what is returned from the API calls themselves. I've put an example below:

type ModNoteTypeFilter = 'NOTE' | 'APPROVAL' | 'REMOVAL' | 'BAN' | 'MUTE' | 'INVITE' | 'SPAM' | 'CONTENT_CHANGE' | 'MOD_ACTION' | 'ALL' ;
export interface ModeratorNote {
  subreddit_id: string; // t5
  operator_id: string; // t2
  mod_action_data : {
    action: string;
    reddit_id: string;  // t1 or t3
    details: string;
    description: null // Not sure what the type is of this
  };
  subreddit: string;
  user: string;
  operator: string;
  id: string;
  user_note_data: {
    note: null;  // Not sure what the type is of this
    reddit_id: string; // t1 or t3
    label: null  // Not sure what the type is of this
  }
  user_id: string;  // t2
  created_at: number;
  cursor: string;
  type: ModNoteTypeFilter
}

I imagine ModeratorNote.user_note_data.label is defined as "(BOT_BAN, PERMA_BAN, BAN, ABUSE_WARNING, SPAM_WARNING, SPAM_WATCH, SOLID_CONTRIBUTOR, HELPFUL_USER)" by the API (optionally null).

Added features?

There is a good opportunity here to transform subreddit_ids, operator_ids and reddit_ids into their respective objects, or even to have a Modnote class with the appropriate methods for generating these objects.

API Endpoints

I'm listing these here just to make the discussion a touch easier

DELETE /api/mod/notes
Delete a mod user note where type=NOTE. Query params:

  • note_id: a unique ID for the note to be deleted (should have a ModNote_ prefix)
  • subreddit: subreddit name (not prefixed, from what I can tell)
  • username account username (also not prefixed)

GET /api/mod/notes
Get mod notes for a specific user in a given subreddit. Query params:

  • before: (optional) an encoded string used for pagination with mod notes
  • filter: (optional) one of (NOTE, APPROVAL, REMOVAL, BAN, MUTE, INVITE, SPAM, CONTENT_CHANGE, MOD_ACTION, ALL), to be used for querying specific types of mod notes (default: all)
  • limit: (optional) the number of mod notes to return in the response payload (default: 25, max: 100)'}
  • subreddit: subreddit name (not prefixed, from what I can tell)
  • username account username (also not prefixed)

POST /api/mod/notes
Create a mod user note where type=NOTE. Query params:

  • label: (optional) one of (BOT_BAN, PERMA_BAN, BAN, ABUSE_WARNING, SPAM_WARNING, SPAM_WATCH, SOLID_CONTRIBUTOR, HELPFUL_USER)
  • note: Content of the note, should be a string with a maximum character limit of 250
  • reddit_id: (optional) a fullname of a comment or post (should have either a t1 or t3 prefix)
  • subreddit: subreddit name (not prefixed, from what I can tell)
  • username account username (also not prefixed)

GET /api/mod/notes/recent
Fetch the most recent notes written by a moderator

Both parameters should be comma separated lists of equal lengths. The first subreddit will be paired with the first account to represent a query for a mod written note for that account in that subreddit and so forth for all subsequent pairs of subreddits and accounts. This request accepts up to 500 pairs of subreddit names and usernames. Parameters should be passed as query parameters.

The response will be a list of mod notes in the order that subreddits and accounts were given. If no note exist for a given subreddit/account pair, then null will take its place in the list.

  • subreddits: a comma delimited list of subreddits by name
  • usernames account usernames

Thanks :)

thislooksfun commented

Hello! Thanks for writing all this up. Now for some feedback:

I feel like there should be a discussion on how/where modnotes are implemented, as a call to the API requires both a subreddit and a username. There are several questions then on how it should be implemented:

  • Should Modnotes be implemented on a subreddit object or a user object, or both?
  • Should modnotes have its own controller and defined on the client class?

I think it makes the most sense for it to be implemented on the Subreddit side. Most of the time you are interacting with mod notes is from the Subreddit's perspective anyway. Plus there are already other similar methods in there, like banUser. That being said, it will need to have its own object type, so I can also see an argument for having its own controller.

  • Should it take subreddits and users as strings (usernames) or as snoot objects? or both?

It will take strings. None of the snoots API takes other snoots objects as input, and I don't plan to start. Only the IDs are needed, so why require the caller to pass more information than they really need to?

There are also issues on the typings of what is returned from the API calls themselves

I'm not entirely sure what you mean by this section. If you're worried about not knowing the exact shape of the null fields, don't be. This codebase has quite the precedent of having fields we can't fully define.

There is a good opportunity here to transform subreddit_ids, operator_ids and reddit_ids into their respective objects [...]

Absolutely not. One of the core design principals of snoots is that there will never be any fancy object population behind the scenes. Unless absolutely required, every method in snoots causes at most 1 network request. The only exception to this is Listings, and only because I couldn't find a way to do so without it being a bloated mess. If a user wants to get a derived object from the call they are more than welcome to by calling the appropriate fetch() method themselves.

[...] or even to have a Modnote class with the appropriate methods for generating these objects.

That, on the other hand, is not a bad idea. This addition will require adding a ModNote structure anyway, so I don't see any reason why we couldn't add this.

I'm listing these here just to make the discussion a touch easier

Thank you for documenting that, it's gonna save me some work when I get to implementing this.

Thanks :)

Thank you! :)