feat: forum topics

.changeset/green-countries-promise.md

@@ -0,0 +1,7 @@
+---
+"@guildedjs/guilded-api-typings": patch
+"guilded.js": patch
+"@guildedjs/rest": patch
+---
+
+feat: forum topics

packages/guilded-api-typings/lib/v1/rest/Forum.ts

@@ -1,4 +1,4 @@
-import type { ForumTopicPayload } from "../structs/Forum";
+import type { ForumTopicPayload, ForumTopicSummaryPayload } from "../structs/Forum";
 
 /**
  * POST
@@ -11,3 +11,65 @@ export interface RESTPostForumTopicBody {
     title: string;
     content: string;
 }
+
+/**
+ * PUT
+ * /channels/:channelId/topics/:forumTopicId/pin
+ */
+export type RESTPutForumTopicPinResult = never;
+
+/**
+ * DELETE
+ * /channels/:channelId/topics/:forumTopicId/pin
+ */
+export type RESTDeleteForumTopicPinResult = never;
+
+/**
+ * POST
+ * /channels/:channelId/topics
+ */
+export interface RESTPostForumTopicsBody {
+    title: string;
+    content: string;
+}
+export interface RESTPostForumTopicsResult {
+    forumTopic: ForumTopicPayload;
+}
+
+/**
+ * GET
+ * /channels/:channelId/topics
+ */
+export interface RESTGetForumTopicsQuery {
+    before?: string;
+    limit?: number;
+}
+export interface RESTGetForumTopicsResult {
+    forumTopics: ForumTopicSummaryPayload[];
+}
+
+/**
+ * GET
+ * /channels/:channelId/topics/:forumTopicId
+ */
+export interface RESTGetForumTopicResult {
+    forumTopic: ForumTopicPayload;
+}
+
+/**
+ * PATCH
+ * /channels/:channelId/topics/:forumTopicId
+ */
+export interface RESTPatchForumTopicBody {
+    title: string;
+    content: string;
+}
+export interface RESTPatchForumTopicResult {
+    forumTopic: ForumTopicPayload;
+}
+
+/**
+ * DELETE
+ * /channels/:channelId/topics/:forumTopicId
+ */
+export type RESTDeleteForumTopicResult = never;

packages/guilded-api-typings/lib/v1/structs/Forum.ts

@@ -1,3 +1,5 @@
+import type { MentionsPayload } from "./Message";
+
 export interface ForumTopicPayload {
     /** The ID of the forum topic */
     id: number;
@@ -6,13 +8,26 @@ export interface ForumTopicPayload {
     /** The ID of the channel this forum topic belongs to */
     channelId: string;
     /** The title of the forum topic */
-    title?: string;
+    title: string;
     /** The content of the forum topic */
-    content?: string;
+    content: string;
     /** The ISO 8601 timestamp that the forum topic was created at */
     createdAt: string;
     /** The ID of the user who created this forum topic (Note: If this event has createdByWebhookId present, this field will still be populated, but can be ignored. In this case, the value of this field will always be Ann6LewA) */
     createdBy: string;
     /** The ID of the webhook who created this forum topic, if it was created by a webhook */
     createdByWebhookId?: string;
+    /** When, if at all, this forum topic was updated */
+    updatedAt?: string;
+    /** When, if at all, this forum topic was bumped */
+    bumpedAt?: string;
+    /** Whether this forum topic is pinned */
+    isPinned?: boolean;
+    /** The mentions within this forum topic */
+    mentions?: MentionsPayload;
 }
+
+export type ForumTopicSummaryPayload = Pick<
+    ForumTopicPayload,
+    "id" | "serverId" | "channelId" | "title" | "createdAt" | "createdBy" | "createdByWebhookId" | "updatedAt" | "bumpedAt" | "isPinned"
+>;

packages/guilded-api-typings/lib/v1/ws/Events.ts

@@ -39,6 +39,11 @@ export const WebSocketEvents = {
     DocDeleted: "DocDeleted",
     ChannelMessageReactionCreated: "ChannelMessageReactionCreated",
     ChannelMessageReactionDeleted: "ChannelMessageReactionDeleted",
+    ForumTopicCreated: "ForumTopicCreated",
+    ForumTopicUpdated: "ForumTopicUpdated",
+    ForumTopicDeleted: "ForumTopicDeleted",
+    ForumTopicPinned: "ForumTopicPinned",
+    ForumTopicUnpinned: "ForumTopicUnpinned",
 } as const;
 export type WSEvent = typeof WebSocketEvents;
 

packages/guilded-api-typings/lib/v1/ws/Forum.ts

@@ -0,0 +1,42 @@
+import type { ForumTopicPayload } from "../structs";
+import type { SkeletonWSPayload, WSEvent } from "./Events";
+
+export interface WSForumTopicCreated extends SkeletonWSPayload {
+    d: {
+        serverId: string;
+        forumTopic: ForumTopicPayload;
+    };
+    t: WSEvent["ForumTopicCreated"];
+}
+
+export interface WSForumTopicUpdated extends SkeletonWSPayload {
+    d: {
+        serverId: string;
+        forumTopic: ForumTopicPayload;
+    };
+    t: WSEvent["ForumTopicUpdated"];
+}
+
+export interface WSForumTopicDeleted extends SkeletonWSPayload {
+    d: {
+        serverId: string;
+        forumTopic: ForumTopicPayload;
+    };
+    t: WSEvent["ForumTopicDeleted"];
+}
+
+export interface WSForumTopicPinned extends SkeletonWSPayload {
+    d: {
+        serverId: string;
+        forumTopic: ForumTopicPayload;
+    };
+    t: WSEvent["ForumTopicPinned"];
+}
+
+export interface WSForumTopicUnpinned extends SkeletonWSPayload {
+    d: {
+        serverId: string;
+        forumTopic: ForumTopicPayload;
+    };
+    t: WSEvent["ForumTopicUnpinned"];
+}

packages/guilded-api-typings/lib/v1/ws/index.ts

@@ -2,6 +2,7 @@ export * from "./CalendarEvent";
 export * from "./Channel";
 export * from "./Doc";
 export * from "./Events";
+export * from "./Forum";
 export * from "./List";
 export * from "./Member";
 export * from "./Message";

packages/guilded.js/README.md

@@ -31,7 +31,7 @@ client.login();
 
 <a href="https://npmjs.org/package/guilded.js"><img src="https://nodei.co/npm/guilded.js.png" alt="NPM"></a>
 
-**Recommended that you use node v12+**
+**Recommended that you use node v16+**
 
 -   `npm install guilded.js`
 -   `yarn add guilded.js`

packages/guilded.js/lib/constants.ts

@@ -31,6 +31,11 @@ export const constants = {
         SERVER_CREATED: "serverCreated",
         MESSAGE_REACTION_CREATED: "messageReactionCreated",
         MESSAGE_REACTION_DELETED: "messageReactionDeleted",
+        FORUM_TOPIC_CREATED: "forumTopicCreated",
+        FORUM_TOPIC_DELETED: "forumTopicDeleted",
+        FORUM_TOPIC_UPDATED: "forumTopicUpdated",
+        FORUM_TOPIC_PINNED: "forumTopicPinned",
+        FORUM_TOPIC_UNPINNED: "forumTopicUnpinned",
     },
 } as const;
 export type ClientEvent = typeof constants.clientEvents;

packages/guilded.js/lib/gateway/ClientGatewayHandler.ts

@@ -34,7 +34,12 @@ import type {
     WSCalendarEventUpdated,
     WSCalendarEventRsvpUpdated,
     WSCalendarEventRsvpManyUpdated,
-    WSCalendarEventRsvpDeleted
+    WSCalendarEventRsvpDeleted,
+    WSForumTopicCreated,
+    WSForumTopicDeleted,
+    WSForumTopicUpdated,
+    WSForumTopicPinned,
+    WSForumTopicUnpinned
 } from "@guildedjs/guilded-api-typings";
 import { WebSocketEvents } from "@guildedjs/guilded-api-typings";
 import { TeamWebhookEventHandler } from "./handler/TeamWebhookEventHandler";
@@ -43,6 +48,7 @@ import { TeamChannelEventHandler } from "./handler/TeamChannelEventHandler";
 import { DocEventHandler } from "./handler/DocEventHandler";
 import { ReactionEventHandler } from "./handler/ReactionEventHandler";
 import { CalendarEventHandler, CalendarEventRsvpHandler } from "./handler/CalendarEventHandler";
+import { ForumEventHandler } from "./handler/ForumEventHandler";
 
 export class ClientGatewayHandler {
     calendarEventHandler = new CalendarEventHandler(this.client);
@@ -55,6 +61,7 @@ export class ClientGatewayHandler {
     teamChannelHandler = new TeamChannelEventHandler(this.client);
     docHandler = new DocEventHandler(this.client);
     reactionHandler = new ReactionEventHandler(this.client);
+    forumHandler = new ForumEventHandler(this.client);
 
     readonly eventToHandlerMap: Record<keyof WSEvent, (data: SkeletonWSPayload) => boolean> = {
         [WebSocketEvents.CalendarEventCreated]: (data) => this.calendarEventHandler.calendarEventCreated(data as WSCalendarEventCreated),
@@ -89,8 +96,18 @@ export class ClientGatewayHandler {
             this.reactionHandler.messageReactionCreated(data as WSChannelMessageReactionCreatedPayload),
         [WebSocketEvents.ChannelMessageReactionDeleted]: (data) =>
             this.reactionHandler.messageReactionDeleted(data as WSChannelMessageReactionDeletedPayload),
+        [WebSocketEvents.ForumTopicCreated]: (data) => 
+            this.forumHandler.forumTopicCreated(data as WSForumTopicCreated),
+        [WebSocketEvents.ForumTopicDeleted]: (data) => 
+            this.forumHandler.forumTopicDeleted(data as WSForumTopicDeleted),
+        [WebSocketEvents.ForumTopicUpdated]: (data) => 
+            this.forumHandler.forumTopicUpdated(data as WSForumTopicUpdated),
+        [WebSocketEvents.ForumTopicPinned]: (data) => 
+            this.forumHandler.forumTopicPinned(data as WSForumTopicPinned),
+        [WebSocketEvents.ForumTopicUnpinned]: (data) =>
+            this.forumHandler.forumTopicUnpinned(data as WSForumTopicUnpinned)
     };
-
+ 
     constructor(public readonly client: Client) {}
     handleWSMessage(event: keyof WSEvent, data: SkeletonWSPayload): void {
         this.eventToHandlerMap[event]?.(data) ?? this.client.emit("unknownGatewayEvent", data);

packages/guilded.js/lib/gateway/handler/ForumEventHandler.ts

@@ -0,0 +1,53 @@
+import type {
+    WSListItemUncompleted,
+    WSListItemCompleted,
+    WSListItemCreated,
+    WSListItemUpdated,
+    WSListItemDeleted,
+    WSForumTopicCreated,
+    WSForumTopicUpdated,
+    WSForumTopicDeleted,
+    WSForumTopicPinned,
+    WSForumTopicUnpinned,
+} from "@guildedjs/guilded-api-typings";
+import { constants } from "../../constants";
+import type { ListChannel } from "../../structures";
+import { ForumTopic } from "../../structures/Forum";
+import { GatewayEventHandler } from "./GatewayEventHandler";
+
+export class ForumEventHandler extends GatewayEventHandler {
+    forumTopicCreated(data: WSForumTopicCreated) {
+        // This is in the case that a REST request beats us to adding the topic in the cache.
+        const existingTopic = this.client.topics.cache.get(data.d.forumTopic.id);
+        if (existingTopic) return this.client.emit(constants.clientEvents.FORUM_TOPIC_CREATED, existingTopic);
+
+        const newTopic = new ForumTopic(this.client, data.d.forumTopic);
+        if(this.client.topics.shouldCacheForumTopic) this.client.topics.cache.set(newTopic.id, newTopic);
+        return this.client.emit(constants.clientEvents.FORUM_TOPIC_CREATED, newTopic);
+    }
+    forumTopicUpdated(data: WSForumTopicUpdated) {
+        const getCachedtopic = this.client.topics.cache.get(data.d.forumTopic.id);
+        if (!getCachedtopic) {
+            const newtopic = new ForumTopic(this.client, data.d.forumTopic);
+            return this.client.emit(constants.clientEvents.FORUM_TOPIC_UPDATED, newtopic, null);
+        }
+        const frozenOldtopic = Object.freeze(getCachedtopic._clone());
+        getCachedtopic._update(data.d.forumTopic);
+        return this.client.emit(constants.clientEvents.FORUM_TOPIC_UPDATED, getCachedtopic, frozenOldtopic);
+    }
+    forumTopicDeleted(data: WSForumTopicDeleted) {
+        const getCachedtopic = this.client.topics.cache.get(data.d.forumTopic.id);
+        getCachedtopic?._update({ _deletedAt: new Date() });
+        return this.client.emit(constants.clientEvents.FORUM_TOPIC_DELETED, getCachedtopic ?? new ForumTopic(this.client, data.d.forumTopic));
+    }
+    forumTopicPinned(data: WSForumTopicPinned) {
+        const getCachedtopic = this.client.topics.cache.get(data.d.forumTopic.id);
+        getCachedtopic?._update({ isPinned: true });
+        return this.client.emit(constants.clientEvents.FORUM_TOPIC_PINNED, getCachedtopic ?? new ForumTopic(this.client, data.d.forumTopic));
+    }
+    forumTopicUnpinned(data: WSForumTopicUnpinned) {
+        const getCachedtopic = this.client.topics.cache.get(data.d.forumTopic.id);
+        getCachedtopic?._update({ isPinned: false });
+        return this.client.emit(constants.clientEvents.FORUM_TOPIC_UNPINNED, getCachedtopic ?? new ForumTopic(this.client, data.d.forumTopic));
+    }
+}

packages/guilded.js/lib/gateway/handler/MessageEventHandler.ts

@@ -10,7 +10,7 @@ export class MessageEventHandler extends GatewayEventHandler {
         if (existingMessage) return this.client.emit(constants.clientEvents.MESSAGE_CREATED, existingMessage);
 
         const newMessage = new Message(this.client, data.d.message);
-        this.client.messages.cache.set(newMessage.id, newMessage);
+        if (this.client.messages.shouldCacheMessage) this.client.messages.cache.set(newMessage.id, newMessage);
         return this.client.emit(constants.clientEvents.MESSAGE_CREATED, newMessage);
     }
     messageUpdated(data: WSChatMessageUpdatedPayload): boolean {
@@ -26,6 +26,6 @@ export class MessageEventHandler extends GatewayEventHandler {
     messageDeleted(data: WSChatMessageDeletedPayload): boolean {
         const getCachedMessage = this.client.messages.cache.get(data.d.message.id);
         getCachedMessage?._update({ deletedAt: data.d.message.deletedAt });
-        return this.client.emit(constants.clientEvents.MESSAGE_DELETED, getCachedMessage || data.d);
+        return this.client.emit(constants.clientEvents.MESSAGE_DELETED, getCachedMessage ?? data.d);
     }
 }

packages/guilded.js/lib/managers/global/ForumManager.ts

@@ -1,9 +1,45 @@
-import type { ForumTopicPayload, RESTPostForumTopicBody } from "@guildedjs/guilded-api-typings";
+import type { ForumTopicPayload, RESTGetForumTopicsQuery, RESTPatchForumTopicBody, RESTPostForumTopicBody } from "@guildedjs/guilded-api-typings";
+import type { ForumTopic } from "../../structures/Forum";
+import { CacheableStructManager } from "./CacheableStructManager";
 import { GlobalManager } from "./GlobalManager";
 
-export class GlobalForumManager extends GlobalManager {
+export class GlobalForumTopicManager extends CacheableStructManager<number, ForumTopic> {
+    get shouldCacheForumTopic() {
+        return this.client.options.cache?.cacheForumTopics !== false;
+    }
+
     /** Create a topic in a forum */
-    createTopic(channelId: string, options: RESTPostForumTopicBody): Promise<ForumTopicPayload> {
+    createForumTopic(channelId: string, options: RESTPostForumTopicBody): Promise<ForumTopicPayload> {
         return this.client.rest.router.createForumTopic(channelId, options).then((data) => data.forumTopic);
     }
+
+    /** Get all topics in a forum */
+    getForumTopics(channelId: string, options: RESTGetForumTopicsQuery) {
+        return this.client.rest.router.getForumTopics(channelId, options);
+    }
+
+    /** Get a topic in a forum */
+    getForumTopic(channelId: string, forumThreadId: string) {
+        return this.client.rest.router.getForumTopic(channelId, forumThreadId);
+    }
+
+    /** Update a topic in a forum */
+    updateForumTopic(channelId: string, forumThreadId: string, options: RESTPatchForumTopicBody) {
+        return this.client.rest.router.updateForumTopic(channelId, forumThreadId, options);
+    }
+
+    /** Delete a topic in a forum */
+    deleteForumTopic(channelId: string, forumThreadId: string) {
+        return this.client.rest.router.deleteForumTopic(channelId, forumThreadId);
+    }
+
+    /** Pin a topic in a forum */
+    pinForumTopic(channelId: string, forumThreadId: string) {
+        return this.client.rest.router.pinForumTopic(channelId, forumThreadId);
+    }
+
+    /** Unpin a topic in a forum */
+    unpinForumTopic(channelId: string, forumThreadId: string) {
+        return this.client.rest.router.unpinForumTopic(channelId, forumThreadId);
+    }
 }

packages/guilded.js/lib/managers/global/MessageManager.ts

@@ -8,6 +8,10 @@ import type { MessageContent } from "../../typings";
 import { CollectorOptions, MessageCollector } from "../../structures";
 
 export class GlobalMessageManager extends CacheableStructManager<string, Message> {
+    get shouldCacheMessage() {
+        return this.client.options.cache?.cacheMessages !== false;
+    }
+
     /** Get a list of the latest 50 messages from a channel. */
     fetchMany(channelId: string, options: RESTGetChannelMessagesQuery): Promise<Collection<string, Message>> {
         return this.client.rest.router.getChannelMessages(channelId, options).then((data) => {