Merge pull request #32310 from willwull/master

[snoowrap] Add missing properties and fix method types.
2026-10-02 22:07:06 +00:00 · 2019-01-24 15:18:22 -08:00
parent d1f62ef599 d3f09f715e
commit 53e1ef554c
9 changed files with 314 additions and 58 deletions
@@ -10,7 +10,10 @@ export default class Comment extends VoteableContent<Comment> {
  collapsed_reason: any; // ?
  collapsed: boolean;
  controversiality: number;
+  depth: number;
  ignore_reports: boolean;
+  /** True if comment author is the same as the Submission author */
+  is_submitter: boolean;
  link_id: string;
  parent_id: string;
  removed: boolean;
@@ -18,6 +18,10 @@ export interface ListingOptions {
  count?: number;
 }

+export interface SortedListingOptions extends ListingOptions {
+  time?: 'all' | 'hour' | 'day' | 'week' | 'month' | 'year';
+}
+
 interface FetchMoreOptions {
  amount: number;
  skipReplies?: boolean;
@@ -6,32 +6,96 @@ import Submission from './Submission';
 import Subreddit from './Subreddit';

 export default class RedditUser extends RedditContent<RedditUser> {
+  /** Number of Reddit coins, only returned for your own user */
+  coins?: number;
  comment_karma: number;
-  features?: Features; // this seems to only be returned for your own user
-  gold_creddits: number;
-  gold_expiration: number | null;
-  has_mail: boolean;
+  /** Only returned for your own user */
+  features?: Features;
+  /** Only returned for your own user */
+  force_password_reset?: boolean;
+  /** Only returned for your own user */
+  gold_creddits?: number;
+  /** Only returned for your own user */
+  gold_expiration?: number | null;
+  /** Only returned for your own user */
+  has_android_subscription?: boolean;
+  /** Only returned for your own user */
+  has_external_account?: boolean;
+  /** Only returned for your own user */
+  has_ios_subscription?: boolean;
+  /** Only returned for your own user */
+  has_mail?: boolean;
  has_mod_mail: boolean;
+  /** Only returned for your own user */
+  has_paypal_subscription?: boolean;
+  /** Only returned for your own user */
+  has_stripe_subscription?: boolean;
  has_subscribed: boolean;
-  has_verified_email: boolean;
+  /** Only returned for your own user */
+  has_subscribed_to_premium?: boolean;
+  has_verified_mail: boolean;
+  /** Only returned for your own user */
+  has_visited_new_profile?: boolean;
  hide_from_robots: boolean;
-  in_beta: boolean;
-  inbox_count: number;
+  /** Image URL of the user's avatar */
+  icon_img: string;
+  /** Only returned for your own user */
+  in_beta?: boolean;
+  /** Only returned for your own user */
+  in_chat?: boolean;
+  /** Only returned for your own user */
+  in_redesign_beta?: boolean;
+  /** Only returned for your own user */
+  inbox_count?: number;
  is_employee: boolean;
-  is_friend: boolean;
+  /** Only returned for other users, not yourself */
+  is_friend?: boolean;
  is_gold: boolean;
  is_mod: boolean;
-  is_sponsor: boolean;
-  is_suspended: boolean;
+  /** Only returned for your own user */
+  is_sponsor?: boolean;
+  /** Only returned for your own user */
+  is_suspended?: boolean;
  link_karma: number;
-  modhash: string | null;
-  new_modmail_exists: boolean;
-  over_18: boolean;
-  pref_no_profanity: boolean;
+  modhash?: string | null;
+  /** Only returned for your own user */
+  new_modmail_exists?: boolean | null;
+  /** Only returned for your own user */
+  num_friends?: number;
+  /** Only returned for your own user */
+  oauth_client_id?: string;
+  /** Only returned for your own user */
+  over_18?: boolean;
+  /** Only returned for your own user */
+  pref_autoplay?: boolean;
+  /** Only returned for your own user */
+  pref_clickgadget?: number;
+  /** Only returned for your own user */
+  pref_geopopular?: string;
+  /** Only returned for your own user */
+  pref_nightmode?: boolean;
+  /** Only returned for your own user */
+  pref_no_profanity?: boolean;
  pref_show_snoovatar: boolean;
-  pref_top_karma_subreddits: any; // ?
+  /** Only returned for your own user */
+  pref_show_trending?: boolean;
+  /** Only returned for your own user */
+  pref_show_twitter?: boolean;
+  /** Only returned for your own user */
+  pref_top_karma_subreddits?: boolean;
+  /** Only returned for your own user */
+  pref_video_autoplay?: boolean;
+  /** Only returned for your own user */
+  seen_layout_switch?: boolean;
+  /** Only returned for your own user */
+  seen_premium_adblock_modal?: boolean;
+  /** Only returned for your own user */
+  seen_redesign_modal?: boolean;
+  /** Only returned for your own user */
+  seen_subreddit_chat_ftux?: boolean;
  subreddit: Subreddit | null;
-  suspension_expiration_utc: number | null;
+  /** Only returned for your own user */
+  suspension_expiration_utc?: number | null;
  verified: boolean;

  assignFlair(options: any): Promise<this>;
@@ -53,8 +117,18 @@ export default class RedditUser extends RedditContent<RedditUser> {
 }

 interface Features {
+  chat: boolean;
+  chat_group_rollout: boolean;
+  chat_rollout: boolean;
+  chat_subreddit: boolean;
  do_not_track: boolean;
+  email_verification: ExperimentFeature;
+  mweb_sharing_clipboard: ExperimentFeature;
+  mweb_xpromo_revamp_v2: ExperimentFeature;
  show_amp_link: boolean;
+  show_nps_survey: boolean;
+  spez_modal: boolean;
+  top_content_email_digest_v2: ExperimentFeature;
  live_happening_now: boolean;
  adserver_reporting: boolean;
  geopopular: boolean;
@@ -3,42 +3,112 @@ import Comment from './Comment';
 import Listing, { ListingOptions } from './Listing';
 import RedditUser from './RedditUser';
 import Subreddit, { FlairTemplate } from './Subreddit';
-import VoteableContent from './VoteableContent';
+import VoteableContent, { RichTextFlair } from './VoteableContent';
+
+interface Media {
+  oembed?: {
+    /** The username of the uploader of the source media */
+    author_name?: string;
+    /** URL to the author's profile on the source website */
+    author_url?: string;
+    description?: string;
+    height: number;
+    html: string;
+    /** Name of the source website, e.g. "gfycat", "YouTube" */
+    provider_name: string;
+    /** URL of the source website, e.g. "https://www.youtube.com" */
+    provider_url: string;
+    thumbnail_height: number;
+    thumbnail_url: string;
+    thumbnail_width: number;
+    /** Name of the media on the content site, e.g. YouTube video title */
+    title: string;
+    type: 'video' | 'rich';
+    version: string;
+    width: number;
+  };
+  reddit_video?: {
+    dash_url: string;
+    duration: number;
+    fallback_url: string;
+    height: number;
+    hls_url: string;
+    is_gif: boolean;
+    scrubber_media_url: string;
+    transcoding_status: string;
+  };
+  type?: string;
+}
+
+interface MediaEmbed {
+  /** HTML string of the media, usually an iframe */
+  content?: string;
+  height?: number;
+  scrolling?: boolean;
+  width?: number;
+}
+
+interface SecureMediaEmbed extends MediaEmbed {
+  media_domain_url?: string;
+}

 export default class Submission extends VoteableContent<Submission> {
-  brand_safe: boolean;
  clicked: boolean;
  comments: Listing<Comment>;
+  /** Categories for original content, e.g. "comics", "drawing_and_painting" */
+  content_categories: string[] | null;
+  contest_mode: boolean;
  domain: string;
  hidden: boolean;
  hide_score: boolean;
+  is_crosspostable: boolean;
+  is_meta: boolean;
+  is_original_content: boolean;
+  is_reddit_media_domain: boolean;
+  is_robot_indexable: boolean;
  is_self: boolean;
  is_video: boolean;
+  link_flair_background_color: string;
  link_flair_css_class: string | null;
+  link_flair_richtext: RichTextFlair[];
+  link_flair_template_id: string | null;
  link_flair_text: string | null;
+  link_flair_text_color: 'dark' | 'light';
+  link_flair_type: 'text' | 'richtext';
  locked: boolean;
-  media_embed: any; // ?
-  media: any; // ?
+  media: Media | null;
+  media_embed: MediaEmbed;
+  media_only: boolean;
  num_comments: number;
+  num_crossposts: number;
  over_18: boolean;
-  permalink: string;
+  parent_whitelist_status: string;
+  pinned: boolean;
+  previous_visits: number[];
+  pwls: number;
  post_hint: string;
  preview: { enabled: boolean; images: ImagePreview[] };
  quarantine: boolean;
  removal_reason: string | null;
-  secure_media_embed: any; // ?
-  secure_media: any; // ?
-  selftext_html: string;
+  /** Same content as media, except HTTPS */
+  secure_media: Media | null;
+  secure_media_embed: SecureMediaEmbed;
  selftext: string;
+  selftext_html: string | null;
+  spam?: boolean;
  spoiler: boolean;
-  suggested_sort: Sort;
-  thumbnail_height: number | null;
+  subreddit_subscribers: number;
+  suggested_sort: Sort | null;
  thumbnail: string;
+  thumbnail_height?: number | null;
+  thumbnail_width?: number | null;
  title: string;
  upvote_ratio: number;
  url: string;
  view_count: number | null;
  visited: boolean;
+  whitelist_status: string;
+  wls: number;

  assignFlair(options: { text: string; cssClass: string; }): Promise<this>;
  disableContestMode(): Promise<this>;
@@ -6,30 +6,54 @@ import RedditContent from './RedditContent';
 import RedditUser from './RedditUser';
 import Submission from './Submission';
 import WikiPage, { WikiPageRevision } from './WikiPage';
+import { RichTextFlair } from './VoteableContent';

 export default class Subreddit extends RedditContent<Subreddit> {
  accounts_active_is_fuzzed: boolean;
  accounts_active: number;
  active_user_count: number;
  advertiser_category: string | null;
+  all_original_content: boolean;
+  allow_discovery: boolean;
  allow_images: boolean;
+  allow_videogifs: boolean;
+  allow_videos: boolean;
+  /** HEX color code */
+  banner_background_color: string;
+  /** URL of the banner image used on desktop Reddit */
+  banner_background_image: string;
+  /** URL of the banner image used on the mobile Reddit app */
  banner_img: string;
  banner_size: [number, number] | null;
+  can_assign_link_flair: boolean;
+  can_assign_user_flair: boolean;
  collapse_deleted_comments: boolean;
  comment_score_hide_mins: number;
+  /** Image URL of the subreddit icon */
+  community_icon: string;
  description_html: string;
  description: string;
-  display_name_prefixed: string;
  display_name: string;
-  header_img: string;
+  display_name_prefixed: string;
+  emojis_custom_size: [number, number] | null;
+  emojis_enabled: boolean;
+  has_menu_widget: boolean;
+  header_img: string | null;
  header_size: [number, number] | null;
  header_title: string | null;
  hide_ads: boolean;
  icon_img: string;
  icon_size: [number, number] | null;
+  is_enrolled_in_new_modmail: boolean | null;
  key_color: string;
  lang: string;
+  link_flair_enabled: boolean;
+  link_flair_position: '' | 'left' | 'right';
+  /** Will be null if user is not subscribed to this subreddit */
+  notification_level: string | null;
  over18: boolean;
+  /** HEX color code */
+  primary_color: string;
  public_description_html: string;
  public_description: string;
  public_traffic: boolean;
@@ -47,14 +71,26 @@ export default class Subreddit extends RedditContent<Subreddit> {
  suggested_comment_sort: Sort | null;
  title: string;
  url: string;
+  user_can_flair_in_sr: boolean;
+  user_flair_background_color: string | null;
+  user_flair_css_class: string | null;
+  user_flair_enabled_in_sr: boolean;
+  user_flair_position: '' | 'left' | 'right';
+  user_flair_richtext: RichTextFlair[];
+  user_flair_template_id: string | null;
+  user_flair_text: string | null;
+  user_flair_text_color: 'dark' | 'light' | null;
+  user_has_favorited: boolean;
  user_is_banned: boolean;
  user_is_contributor: boolean;
  user_is_moderator: boolean;
  user_is_muted: boolean;
  user_is_subscriber: boolean;
+  user_sr_flair_enabled: boolean;
  user_sr_theme_enabled: boolean;
  whitelist_status: string;
  wiki_enabled: boolean;
+  wls: number;

  acceptModeratorInvite(): Promise<this>;
  addContributor(options: { name: string; }): Promise<this>;
@@ -2,31 +2,79 @@ import RedditUser from './RedditUser';
 import ReplyableContent from './ReplyableContent';
 import Subreddit from './Subreddit';

+interface RichTextFlair {
+  /** The string representation of the emoji */
+  a?: string;
+  /** The type of the flair entry */
+  e: 'text' | 'emoji';
+  /** URL of the emoji image */
+  u?: string;
+  /** The text content of a text flair */
+  t?: string;
+}
+
+interface Gildings {
+  /** Number of Reddit Silver awarded */
+  gid_1: number;
+  /** Number of Reddit Gold awarded */
+  gid_2: number;
+  /** Number of Reddit Platinum awarded */
+  gid_3: number;
+}
+
+export type SubredditType =
+  | 'gold_restricted'
+  | 'archived'
+  | 'restricted'
+  | 'employees_only'
+  | 'gold_only'
+  | 'private'
+  | 'user'
+  | 'public';
+
 export default class VoteableContent<T> extends ReplyableContent<T> {
  approved_at_utc: number | null;
  approved_by: RedditUser | null;
  archived: boolean;
-  author_flair_css_class: string | null;
-  author_flair_text: string | null;
  author: RedditUser;
+  author_flair_background_color: string | null;
+  author_flair_css_class: string | null;
+  author_flair_richtext: RichTextFlair[];
+  author_flair_template_id: string | null;
+  author_flair_text: string | null;
+  author_flair_text_color: string | null;
+  author_flair_type: 'text' | 'richtext';
+  author_fullname: string;
+  author_patreon_flair: boolean;
  banned_at_utc: number | null;
  banned_by: RedditUser | null;
  can_gild: boolean;
  can_mod_post: boolean;
-  distinguished: string | null;
+  distinguished: 'admin' | 'moderator' | null;
  downs: number;
  edited: number | boolean;
  gilded: number;
-  likes: any; // ?
+  gildings: Gildings;
+  /** true = upvoted, false = downvoted, null = hasn't voted */
+  likes: boolean | null;
+  mod_note: string;
+  /** The name of the user that added the mod_note */
+  mod_reason_by: string;
+  mod_reason_title: string;
  mod_reports: string[];
+  no_follow: boolean;
  num_reports: number;
+  permalink: string;
+  removal_reason: any; // ?
  report_reasons: string[];
  saved: boolean;
  score: number;
+  send_replies: boolean;
  stickied: boolean;
-  subreddit_name_prefixed: string;
-  subreddit_type: string;
  subreddit: Subreddit;
+  subreddit_id: string;
+  subreddit_name_prefixed: string;
+  subreddit_type: SubredditType;
  ups: number;
  user_reports: string[];

@@ -1,5 +1,5 @@
 export { default as Comment } from './Comment';
-export { default as Listing, ListingOptions } from './Listing';
+export { default as Listing, ListingOptions, SortedListingOptions } from './Listing';
 export { default as LiveThread, LiveThreadSettings } from './LiveThread';
 export { default as MultiReddit, MultiRedditProperties } from './MultiReddit';
 export { default as PrivateMessage } from './PrivateMessage';
@@ -1,16 +1,18 @@
-// Type definitions for snoowrap 1.16
+// Type definitions for snoowrap 1.15
 // Project: https://github.com/not-an-aardvark/snoowrap
 // Definitions by: Vito Samson <https://github.com/vitosamson>
 //                 TheAppleFreak <https://github.com/TheAppleFreak>
+//                 Willy Liu <https://github.com/willwull>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
 // TypeScript Version: 2.3

-import { CoreOptions as RequestOptions } from 'request';
+import { Options as RequestOptions } from 'request';

 import {
  Comment as _Comment,
  Listing as _Listing,
  ListingOptions,
+  SortedListingOptions,
  LiveThread as _LiveThread,
  LiveThreadSettings,
  MultiReddit as _MultiReddit,
@@ -57,38 +59,38 @@ declare class Snoowrap {
  getBlockedUsers(): Promise<_RedditUser[]>;
  getCaptchaImage(identifier: string): Promise<string>;
  getComment(commentId: string): _Comment;
-  getContributorSubreddits(options?: ListingOptions): _Listing<_Subreddit>;
-  getControversial(subredditName?: string, options?: ListingOptions): _Listing<_Submission>;
-  getDefaultSubreddits(options?: ListingOptions): _Listing<_Subreddit>;
+  getContributorSubreddits(options?: ListingOptions): Promise<_Listing<_Subreddit>>;
+  getControversial(subredditName?: string, options?: SortedListingOptions): Promise<_Listing<_Submission>>;
+  getDefaultSubreddits(options?: ListingOptions): Promise<_Listing<_Subreddit>>;
  getFriends(): Promise<_RedditUser[]>;
-  getGoldSubreddits(options?: ListingOptions): _Listing<_Subreddit>;
-  getHot(subredditName?: string, options?: ListingOptions): _Listing<_Submission>;
-  getInbox(options?: { filter?: string }): _Listing<_PrivateMessage | _Comment>;
+  getGoldSubreddits(options?: ListingOptions): Promise<_Listing<_Subreddit>>;
+  getHot(subredditName?: string, options?: ListingOptions): Promise<_Listing<_Submission>>;
+  getInbox(options?: { filter?: string }): Promise<_Listing<_PrivateMessage | _Comment>>;
  getKarma(): Promise<Array<{ sr: _Subreddit; comment_karma: number; link_karma: number; }>>;
  getLivethread(threadId: string): _LiveThread;
  getMe(): _RedditUser;
  getMessage(messageId: string): _PrivateMessage;
-  getModeratedSubreddits(options?: ListingOptions): _Listing<_Subreddit>;
-  getModmail(options?: ListingOptions): _Listing<_PrivateMessage>;
+  getModeratedSubreddits(options?: ListingOptions): Promise<_Listing<_Subreddit>>;
+  getModmail(options?: ListingOptions): Promise<_Listing<_PrivateMessage>>;
  getMyMultireddits(): Promise<_MultiReddit[]>;
  getMyTrophies(): Promise<Snoowrap.Trophy[]>;
-  getNew(subredditName?: string, options?: ListingOptions): _Listing<_Submission>;
+  getNew(subredditName?: string, options?: ListingOptions): Promise<_Listing<_Submission>>;
  getNewCaptchaIdentifier(): Promise<string>;
-  getNewComments(subredditName?: string, options?: ListingOptions): _Listing<_Comment>;
-  getNewSubreddits(options?: ListingOptions): _Listing<_Subreddit>;
+  getNewComments(subredditName?: string, options?: ListingOptions): Promise<_Listing<_Comment>>;
+  getNewSubreddits(options?: ListingOptions): Promise<_Listing<_Subreddit>>;
  getOauthScopeList(): Promise<{ [key: string]: { description: string; id: string; name: string } }>;
-  getPopularSubreddit(options?: ListingOptions): _Listing<_Subreddit>;
+  getPopularSubreddit(options?: ListingOptions): Promise<_Listing<_Subreddit>>;
  getPreferences(): Promise<any>;
-  getRandomSubmission(subredditName?: string): _Submission;
-  getRising(subredditName?: string, options?: ListingOptions): _Listing<_Submission>;
+  getRandomSubmission(subredditName?: string): Promise<_Submission>;
+  getRising(subredditName?: string, options?: ListingOptions): Promise<_Listing<_Submission>>;
  getSavedCategories(): Promise<any[]>;
-  getSentMessages(options?: ListingOptions): _Listing<_PrivateMessage>;
+  getSentMessages(options?: ListingOptions): Promise<_Listing<_PrivateMessage>>;
  getStickiedLivethread(): Promise<_LiveThread | undefined>;
  getSubmission(submissionId: string): _Submission;
  getSubreddit(displayName: string): _Subreddit;
  getSubscriptions(options?: ListingOptions): _Listing<_Subreddit>;
-  getTop(subredditName?: string, options?: ListingOptions): _Listing<_Submission>;
-  getUnreadMessages(options?: ListingOptions): _Listing<_PrivateMessage>;
+  getTop(subredditName?: string, options?: SortedListingOptions): Promise<_Listing<_Submission>>;
+  getUnreadMessages(options?: ListingOptions): Promise<_Listing<_PrivateMessage>>;
  getUser(name: string): _RedditUser;
  markAsVisited(links: _Submission[]): Promise<void>;
  markMessagesAsRead(messages: _PrivateMessage[] | string[]): Promise<void>;
@@ -97,10 +99,10 @@ declare class Snoowrap {
  rawRequest(options: RequestOptions): Promise<any>;
  readAllMessages(): Promise<void>;
  revokeRefreshToken(): Promise<void>;
-  search(options: Snoowrap.SearchOptions): _Listing<_Submission>;
+  search(options: Snoowrap.SearchOptions): Promise<_Listing<_Submission>>;
  searchSubredditNames(options: { query: string; exact?: boolean; includeNsfw?: boolean; }): Promise<string[]>;
-  searchSubreddits(options: ListingOptions & { query: string }): _Listing<_Subreddit>;
-  searchSubredditTopics(options: { filter: string; }): Promise<_Subreddit[]>;
+  searchSubreddits(options: ListingOptions & { query: string }): Promise<_Listing<_Subreddit>>;
+  searchSubredditTopics(options: { query: string; }): Promise<_Subreddit[]>;
  submitLink(options: Snoowrap.SubmitLinkOptions): Promise<_Submission>;
  submitSelfpost(options: Snoowrap.SubmitSelfPostOptions): Promise<_Submission>;
  unauthenticatedRequest(options: RequestOptions): Promise<any>; // options: https://www.npmjs.com/package/request
@@ -43,11 +43,15 @@ export function subreddit(name: string): Subreddit {
  return r.getSubreddit(name);
 }

+export function topSubmissions(name: string): Promise<Listing<Submission>> {
+  return r.getTop(name, { time: 'all' });
+}
+
 export function wiki(subreddit: string, page: string): WikiPage {
  return r.getSubreddit(subreddit).getWikiPage(page);
 }

-export function getNewComments(subreddit: string): Listing<Comment> {
+export function getNewComments(subreddit: string): Promise<Listing<Comment>> {
  return r.getNewComments(subreddit);
 }

@@ -62,3 +66,18 @@ export function getConfig(): Snoowrap.ConfigOptions {
 export function setConfig(options: Snoowrap.ConfigOptions): Snoowrap.ConfigOptions {
  return r.config(options);
 }
+
+export function oauthRequest(method: string, uri: string): Promise<any> {
+  return r.oauthRequest({
+    method,
+    uri,
+  });
+}
+
+export function submissionSearch(query: string, subreddit: string): Promise<Listing<Submission>> {
+  return r.search({ query, subreddit });
+}
+
+export function subredditSearch(query: string): Promise<Listing<Subreddit>> {
+  return r.searchSubreddits({ query });
+}