feat: allow getting and setting a post's suggested sort

src/reddit/index.ts

@@ -12,7 +12,7 @@ export { LockableControls } from "./lockable/controls";
 export type { LockableData } from "./lockable/object";
 export { Lockable } from "./lockable/object";
 export { PostControls } from "./post/controls";
-export type { PostData } from "./post/object";
+export type { PostData, SuggestedSort } from "./post/object";
 export { Post } from "./post/object";
 export type { PostSort } from "./post/types";
 export { ReplyableControls } from "./replyable/controls";

src/reddit/post/controls.ts

@@ -2,7 +2,7 @@ import type { Client } from "../../client";
 import type { Query } from "../../gateway/types";
 import type { Data, Maybe } from "../../helper/types";
 import type { Listing, ListingObject, RedditListing } from "../listing/listing";
-import type { PostData } from "../post/object";
+import type { PostData, SuggestedSort } from "../post/object";
 import type { LinkPostOptions } from "../subreddit/controls";
 import type {
   RedditObject,
@@ -170,6 +170,23 @@ export class PostControls extends LockableControls {
     await this.gateway.post("api/set_contest_mode", body);
   }
 
+  /**
+   * Set the suggested sort for a post.
+   *
+   * @param id The ID of the post to update the suggested sort for.
+   * @param sort The new suggested sort. If this is `undefined` the sort will be
+   * cleared.
+   *
+   * @returns A promise that resolves when the post's suggested sort has been
+   * updated.
+   */
+  async setSuggestedSort(id: string, sort: Maybe<SuggestedSort>) {
+    await this.gateway.post("api/set_suggested_sort", {
+      id: this.namespace(id),
+      sort: sort ?? "",
+    });
+  }
+
   /**
    * Get the duplicates of a post.
    *

src/reddit/post/object.ts

@@ -7,6 +7,16 @@ import type { LinkPostOptions } from "../subreddit/controls";
 
 import { Lockable } from "../lockable/object";
 
+export type SuggestedSort =
+  | "confidence"
+  | "controversial"
+  | "live"
+  | "new"
+  | "old"
+  | "qa"
+  | "random"
+  | "top";
+
 // TODO: Fully document Media
 // This looks like it can be split into two interfaces?
 // export interface Media {
@@ -189,12 +199,11 @@ export interface PostData extends LockableData {
   /** The number of subscribers the subreddit this was posted to has. */
   subredditSubscribers: number;
 
-  // TODO: Document or remove PostData.suggestedSort
   /**
    * The suggested way to sort the comments of this post, or undefined if no
    * such suggestion has been given.
    */
-  // suggestedSort: Maybe<Sort>;
+  suggestedSort: Maybe<SuggestedSort>;
 
   // TODO: Document or remove PostData.thumbnail*
   // thumbnail: 'self' | string;
@@ -277,7 +286,7 @@ export class Post extends Lockable implements PostData {
   // secureMediaEmbed: SecureMediaEmbed;
   spoiler: boolean;
   subredditSubscribers: number;
-  // suggestedSort: Maybe<Sort>;
+  suggestedSort: Maybe<SuggestedSort>;
   // thumbnail: string;
   // thumbnailHeight?: number;
   // thumbnailWidth?: number;
@@ -337,7 +346,7 @@ export class Post extends Lockable implements PostData {
     // this.secureMediaEmbed = data.secureMediaEmbed;
     this.spoiler = data.spoiler;
     this.subredditSubscribers = data.subredditSubscribers;
-    // this.suggestedSort = data.suggestedSort;
+    this.suggestedSort = data.suggestedSort;
     // this.thumbnail = data.thumbnail;
     // this.thumbnailHeight = data.thumbnailHeight;
     // this.thumbnailWidth = data.thumbnailWidth;
@@ -408,6 +417,18 @@ export class Post extends Lockable implements PostData {
     return this.controls.setContestMode(this.id, enabled);
   }
 
+  /**
+   * Set the suggested sort for this post.
+   *
+   * @param sort The new suggested sort. If this is `undefined` the sort will be
+   * cleared.
+   * @returns A promise that resolves when this post's suggested sort has been
+   * updated.
+   */
+  async setSuggestedSort(sort: Maybe<SuggestedSort>) {
+    return this.controls.setSuggestedSort(this.id, sort);
+  }
+
   /**
    * Get the duplicates of this post.
    *