feat: add support for manage lists endpoints (#63)

* feat: add list manager and method for creating/deleting a list

* feat(ListManager): add methods to update list and add/remove member

* feat(ListManager): add methods to follow and unfollow a list

* feat(ListManager): add methods to pin or unpin a list

* fix: update twitter-types to use the fixed interface names

* feat(List): add description and private property

Author: iShibi

.vscode/settings.json

@@ -38,5 +38,6 @@
   },
   "typescript.suggest.autoImports": true,
   "typescript.referencesCodeLens.enabled": true,
-  "typescript.implementationsCodeLens.enabled": true
+  "typescript.implementationsCodeLens.enabled": true,
+  "typescript.tsdk": "node_modules\\typescript\\lib"
 }

package-lock.json

@@ -56,7 +56,7 @@
     "jest": "^27.1.0",
     "lint-staged": "^11.1.2",
     "prettier": "^2.4.1",
-    "twitter-types": "^0.15.0",
+    "twitter-types": "^0.15.1",
     "typedoc": "^0.22.4",
     "typescript": "^4.4.3"
   },

package.json

@@ -3,7 +3,7 @@ import { RESTManager } from '../rest/RESTManager';
 import { ClientEvents, StreamType } from '../util';
 import { CustomError, CustomTypeError } from '../errors';
 import { SampledTweetStream, FilteredTweetStream } from '../streams';
-import { UserManager, TweetManager, SpaceManager } from '../managers';
+import { UserManager, TweetManager, SpaceManager, ListManager } from '../managers';
 import { ClientCredentials, RequestData, ClientUser } from '../structures';
 import type { Response } from 'undici';
 import type { ClientCredentialsInterface, ClientOptions } from '../typings';
@@ -64,6 +64,11 @@ export class Client extends BaseClient {
    */
   spaces: SpaceManager;
 
+  /**
+   * The manager for {@link List} objects
+   */
+  lists: ListManager;
+
   /**
    * The class for working with sampled tweet stream
    */
@@ -92,6 +97,7 @@ export class Client extends BaseClient {
     this.tweets = new TweetManager(this);
     this.users = new UserManager(this);
     this.spaces = new SpaceManager(this);
+    this.lists = new ListManager(this);
     this.sampledTweets = new SampledTweetStream(this);
     this.filteredTweets = new FilteredTweetStream(this);
   }

src/client/Client.ts

@@ -16,6 +16,7 @@ const messages = {
   USER_CONTEXT_LOGIN_ERROR: (username: string) => `Could not fetch the user ${username}.`,
   CREDENTIALS_NOT_STRING: "One or more client credentials fields are missing or aren't of type string.",
   SPACE_RESOLVE_ID: (action: string) => `Could not resolve the space ID to ${action}.`,
+  LIST_RESOLVE_ID: (action: string) => `Could not resolve the list ID to ${action}.`,
 };
 
 for (const [key, message] of Object.entries(messages)) {

src/errors/ErrorMessages.ts

@@ -0,0 +1,195 @@
+import { BaseManager } from './BaseManager';
+import { List, RequestData } from '../structures';
+import { CustomError, CustomTypeError } from '../errors';
+import type { Client } from '../client';
+import type { CreateListOptions, ListResolvable, UpdateListOptions, UserResolvable } from '../typings';
+import type {
+  DeleteListDeleteResponse,
+  DeleteListRemoveMemberResponse,
+  DeleteListUnfollowResponse,
+  DeleteListUnpinResponse,
+  PostListAddMemberJSONBody,
+  PostListAddMemberResponse,
+  PostListCreateJSONBody,
+  PostListCreateResponse,
+  PostListFollowJSONBody,
+  PostListFollowResponse,
+  PostListPinJSONBody,
+  PostListPinResponse,
+  PutListUpdateJSONBody,
+  PutListUpdateResponse,
+  Snowflake,
+} from 'twitter-types';
+
+/**
+ * The manager class that holds API methods for {@link List} objects and stores their cache
+ */
+export class ListManager extends BaseManager<Snowflake, ListResolvable, List> {
+  /**
+   * @param client The logged in {@link Client} instance
+   */
+  constructor(client: Client) {
+    super(client, List);
+  }
+
+  /**
+   * Creates a new list.
+   * @param options The options for creating a list
+   * @returns The created {@link List} object
+   */
+  async create(options: CreateListOptions): Promise<List> {
+    if (typeof options !== 'object') throw new CustomTypeError('INVALID_TYPE', 'options', 'object', true);
+    const body: PostListCreateJSONBody = {
+      name: options.name,
+      description: options.description,
+      private: options.private,
+    };
+    const requestData = new RequestData({ body, isUserContext: true });
+    const res: PostListCreateResponse = await this.client._api.lists.post(requestData);
+    const list = this.add(res.data.id, res.data);
+    return list;
+  }
+
+  /**
+   * Deletes a list.
+   * @param list The list to delete
+   * @returns A boolean representing whether the specified list has been deleted
+   */
+  async delete(list: ListResolvable): Promise<boolean> {
+    const listId = this.resolveId(list);
+    if (!listId) throw new CustomError('LIST_RESOLVE_ID', 'delete');
+    const requestData = new RequestData({ isUserContext: true });
+    const res: DeleteListDeleteResponse = await this.client._api.lists(listId).delete(requestData);
+    return res.data.deleted;
+  }
+
+  /**
+   * Updates a lists.
+   * @param list The list to update
+   * @param options The options for updating the list
+   * @returns A boolean representing whether the specified list has been updated
+   */
+  async update(list: ListResolvable, options: UpdateListOptions): Promise<boolean> {
+    const listId = this.resolveId(list);
+    if (!listId) throw new CustomError('LIST_RESOLVE_ID', 'update');
+    if (typeof options !== 'object') throw new CustomTypeError('INVALID_TYPE', 'options', 'object', true);
+    const body: PutListUpdateJSONBody = {
+      name: options.name,
+      description: options.description,
+      private: options.private,
+    };
+    const requestData = new RequestData({ body, isUserContext: true });
+    const res: PutListUpdateResponse = await this.client._api.lists(listId).put(requestData);
+    return res.data.updated;
+  }
+
+  /**
+   * Adds a member to a list
+   * @param list The list to add the member to
+   * @param member The user to add as a member of the list
+   * @returns A boolean representing whether the specified user has been added to the List
+   */
+  async addMember(list: ListResolvable, member: UserResolvable): Promise<boolean> {
+    const listId = this.resolveId(list);
+    if (!listId) throw new CustomError('LIST_RESOLVE_ID', 'add member to');
+    const userId = this.client.users.resolveId(member);
+    if (!userId) throw new CustomError('USER_RESOLVE_ID', 'add to the list');
+    const body: PostListAddMemberJSONBody = {
+      user_id: userId,
+    };
+    const requestData = new RequestData({ body, isUserContext: true });
+    const res: PostListAddMemberResponse = await this.client._api.lists(listId).members.post(requestData);
+    return res.data.is_member;
+  }
+
+  /**
+   * Removes a member from a list.
+   * @param list The list to remove the member from
+   * @param member The member to remove from the list
+   * @returns A boolean representing whether the specified user has been removed from the list
+   */
+  async removeMember(list: ListResolvable, member: UserResolvable): Promise<boolean> {
+    const listId = this.resolveId(list);
+    if (!listId) throw new CustomError('LIST_RESOLVE_ID', 'remove the member from');
+    const userId = this.client.users.resolveId(member);
+    if (!userId) throw new CustomError('USER_RESOLVE_ID', 'remove from the list');
+    const requestData = new RequestData({ isUserContext: true });
+    const res: DeleteListRemoveMemberResponse = await this.client._api
+      .lists(listId)
+      .members(userId)
+      .delete(requestData);
+    return !res.data.is_member;
+  }
+
+  /**
+   * Follows a list.
+   * @param list The list to follow
+   * @returns A boolean representing whether the authorized user followed the list
+   */
+  async follow(list: ListResolvable): Promise<boolean> {
+    const listId = this.resolveId(list);
+    if (!listId) throw new CustomError('LIST_RESOLVE_ID', 'follow');
+    const loggedInUser = this.client.me;
+    if (!loggedInUser) throw new CustomError('NO_LOGGED_IN_USER');
+    const body: PostListFollowJSONBody = {
+      list_id: listId,
+    };
+    const requestData = new RequestData({ body, isUserContext: true });
+    const res: PostListFollowResponse = await this.client._api.users(loggedInUser.id).followed_lists.post(requestData);
+    return res.data.following;
+  }
+
+  /**
+   * Unfollows a list.
+   * @param list The list to unfollow
+   * @returns A boolean representing whether the authorized user unfollowed the list
+   */
+  async unfollow(list: ListResolvable): Promise<boolean> {
+    const listId = this.resolveId(list);
+    if (!listId) throw new CustomError('LIST_RESOLVE_ID', 'unfollow');
+    const loggedInUser = this.client.me;
+    if (!loggedInUser) throw new CustomError('NO_LOGGED_IN_USER');
+    const requestData = new RequestData({ isUserContext: true });
+    const res: DeleteListUnfollowResponse = await this.client._api
+      .users(loggedInUser.id)
+      .followed_lists(listId)
+      .delete(requestData);
+    return !res.data.following;
+  }
+
+  /**
+   * Pins a list.
+   * @param list The list to pin
+   * @returns A boolean representing whether the authorized user pinned the list
+   */
+  async pin(list: ListResolvable): Promise<boolean> {
+    const listId = this.resolveId(list);
+    if (!listId) throw new CustomError('LIST_RESOLVE_ID', 'pin');
+    const loggedInUser = this.client.me;
+    if (!loggedInUser) throw new CustomError('NO_LOGGED_IN_USER');
+    const body: PostListPinJSONBody = {
+      list_id: listId,
+    };
+    const requestData = new RequestData({ body, isUserContext: true });
+    const res: PostListPinResponse = await this.client._api.users(loggedInUser.id).pinned_lists.post(requestData);
+    return res.data.pinned;
+  }
+
+  /**
+   * Unpins a list.
+   * @param list The list to unpin
+   * @returns A boolean representing whether the authorized user unpinned the list
+   */
+  async unpin(list: ListResolvable): Promise<boolean> {
+    const listId = this.resolveId(list);
+    if (!listId) throw new CustomError('LIST_RESOLVE_ID', 'pin');
+    const loggedInUser = this.client.me;
+    if (!loggedInUser) throw new CustomError('NO_LOGGED_IN_USER');
+    const requestData = new RequestData({ isUserContext: true });
+    const res: DeleteListUnpinResponse = await this.client._api
+      .users(loggedInUser.id)
+      .pinned_lists(listId)
+      .delete(requestData);
+    return res.data.pinned;
+  }
+}

src/managers/ListManager.ts

@@ -1,4 +1,5 @@
 export * from './BaseManager';
+export * from './ListManager';
 export * from './SpaceManager';
 export * from './TweetManager';
 export * from './UserManager';

src/managers/index.ts

@@ -0,0 +1,31 @@
+import { BaseStructure } from './BaseStructure';
+import type { Client } from '../client';
+import type { APIList } from 'twitter-types';
+
+export class List extends BaseStructure {
+  /**
+   * The name of the list
+   */
+  name: string;
+
+  /**
+   * The description of the list
+   */
+  description: string | null;
+
+  /**
+   * Whether the list is private
+   */
+  private: boolean | null;
+
+  /**
+   * @param client The logged in {@link Client} instance
+   * @param data The raw data sent by the API for the list
+   */
+  constructor(client: Client, data: APIList) {
+    super(client, data);
+    this.name = data.name;
+    this.description = data.description ?? null;
+    this.private = data.private ?? null;
+  }
+}

src/structures/List.ts

@@ -2,6 +2,7 @@ export * from './misc';
 export * from './BaseStructure';
 export * from './ClientUser';
 export * from './FilteredTweetStreamRule';
+export * from './List';
 export * from './Media';
 export * from './Place';
 export * from './Poll';

src/structures/index.ts

@@ -545,3 +545,28 @@ export interface CountTweetsOptions {
 export interface BaseStructureData {
   id: Snowflake;
 }
+
+/**
+ * The options used for creating a new list
+ */
+export interface CreateListOptions {
+  /**
+   * The name of the list
+   */
+  name: string;
+
+  /**
+   * The description of the list
+   */
+  description?: string;
+
+  /**
+   * Whether the list should be private
+   */
+  private?: boolean;
+}
+
+/**
+ * The options used to update a list
+ */
+export type UpdateListOptions = Partial<CreateListOptions>;