backport(TextBasedChannel): add lastPinTimestamp and lastPinAt (#2870)

And clarify Client#channelPinsUpdate's 'time' parameter.

src/client/websocket/packets/handlers/ChannelPinsUpdate.js

@@ -16,16 +16,22 @@ class ChannelPinsUpdate extends AbstractHandler {
     const data = packet.d;
     const channel = client.channels.get(data.channel_id);
     const time = new Date(data.last_pin_timestamp);
-    if (channel && time) client.emit(Constants.Events.CHANNEL_PINS_UPDATE, channel, time);
+    if (channel && time) {
+      // Discord sends null for last_pin_timestamp if the last pinned message was removed
+      channel.lastPinTimestamp = time.getTime() || null;
+
+      client.emit(Constants.Events.CHANNEL_PINS_UPDATE, channel, time);
+    }
   }
 }
 
 /**
  * Emitted whenever the pins of a channel are updated. Due to the nature of the WebSocket event, not much information
  * can be provided easily here - you need to manually check the pins yourself.
+ * <warn>The `time` parameter will be a Unix Epoch Date object when there are no pins left.</warn>
  * @event Client#channelPinsUpdate
  * @param {Channel} channel The channel that the pins update occured in
- * @param {Date} time The time of the pins update
+ * @param {Date} time The time when the last pinned message was pinned
  */
 
 module.exports = ChannelPinsUpdate;

src/structures/DMChannel.js

@@ -29,6 +29,12 @@ class DMChannel extends Channel {
      * @type {?Snowflake}
      */
     this.lastMessageID = data.last_message_id;
+
+    /**
+     * The timestamp when the last pinned message was pinned, if there was one
+     * @type {?number}
+     */
+    this.lastPinTimestamp = data.last_pin_timestamp ? new Date(data.last_pin_timestamp).getTime() : null;
   }
 
   /**
@@ -42,6 +48,7 @@ class DMChannel extends Channel {
 
   // These are here only for documentation purposes - they are implemented by TextBasedChannel
   /* eslint-disable no-empty-function */
+  get lastPinAt() {}
   send() {}
   sendMessage() {}
   sendEmbed() {}

src/structures/GroupDMChannel.js

@@ -99,6 +99,12 @@ class GroupDMChannel extends Channel {
      * @type {?Snowflake}
      */
     this.lastMessageID = data.last_message_id;
+
+    /**
+     * The timestamp when the last pinned message was pinned, if there was one
+     * @type {?number}
+     */
+    this.lastPinTimestamp = data.last_pin_timestamp ? new Date(data.last_pin_timestamp).getTime() : null;
   }
 
   /**
@@ -212,6 +218,7 @@ class GroupDMChannel extends Channel {
 
   // These are here only for documentation purposes - they are implemented by TextBasedChannel
   /* eslint-disable no-empty-function */
+  get lastPinAt() {}
   send() {}
   sendMessage() {}
   sendEmbed() {}

src/structures/TextChannel.js

@@ -37,6 +37,12 @@ class TextChannel extends GuildChannel {
      */
     this.lastMessageID = data.last_message_id;
 
+    /**
+     * The timestamp when the last pinned message was pinned, if there was one
+     * @type {?number}
+     */
+    this.lastPinTimestamp = data.last_pin_timestamp ? new Date(data.last_pin_timestamp).getTime() : null;
+
     /**
      * The ratelimit per user for this channel
      * @type {number}
@@ -115,6 +121,7 @@ class TextChannel extends GuildChannel {
 
   // These are here only for documentation purposes - they are implemented by TextBasedChannel
   /* eslint-disable no-empty-function */
+  get lastPinAt() {}
   send() { }
   sendMessage() { }
   sendEmbed() { }

src/structures/interfaces/TextBasedChannel.js

@@ -30,6 +30,12 @@ class TextBasedChannel {
      * @type {?Message}
      */
     this.lastMessage = null;
+
+    /**
+     * The timestamp when the last pinned message was pinned, if there was one
+     * @type {?number}
+     */
+    this.lastPinTimestamp = null;
   }
 
   /**
@@ -389,6 +395,15 @@ class TextBasedChannel {
     return 0;
   }
 
+  /**
+   * The date when the last pinned message was pinned, if there was one
+   * @type {?Date}
+   * @readonly
+   */
+  get lastPinAt() {
+    return this.lastPinTimestamp ? new Date(this.lastPinTimestamp) : null;
+  }
+
   /**
    * Creates a Message Collector
    * @param {CollectorFilter} filter The filter to create the collector with
@@ -584,6 +599,7 @@ exports.applyToClass = (structure, full = false, ignore = []) => {
       'fetchMessages',
       'fetchMessage',
       'search',
+      'lastPinAt',
       'bulkDelete',
       'startTyping',
       'stopTyping',

typings/index.d.ts

@@ -1554,6 +1554,8 @@ declare module 'discord.js' {
 	};
 
 	type TextBasedChannelFields = {
+		lastPinTimestamp: number;
+		readonly lastPinAt: Date;
 		typing: boolean;
 		typingCount: number;
 		awaitMessages(filter: CollectorFilter, options?: AwaitMessagesOptions): Promise<Collection<string, Message>>;