feat(ClientApplication): add fetchActivityInstance method (#11481)

* feat(ClientApplication): add fetchActivityInstance method

* refactor: requested changes

---------

Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>

packages/discord.js/src/index.js

@@ -99,6 +99,8 @@ exports.WebSocketShard = require('./client/websocket/WebSocketShard');
 exports.ActionRow = require('./structures/ActionRow');
 exports.ActionRowBuilder = require('./structures/ActionRowBuilder');
 exports.Activity = require('./structures/Presence').Activity;
+exports.ActivityInstance = require('./structures/ActivityInstance').ActivityInstance;
+exports.ActivityLocation = require('./structures/ActivityLocation').ActivityLocation;
 exports.AnonymousGuild = require('./structures/AnonymousGuild');
 exports.Application = require('./structures/interfaces/Application');
 exports.ApplicationCommand = require('./structures/ApplicationCommand');

packages/discord.js/src/structures/ActivityInstance.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const { ActivityLocation } = require('./ActivityLocation');
+const Base = require('./Base');
+
+/**
+ * Represents an activity instance.
+ *
+ * @extends {Base}
+ */
+class ActivityInstance extends Base {
+  constructor(client, data) {
+    super(client);
+
+    /**
+     * The id of the application
+     *
+     * @type {Snowflake}
+     */
+    this.applicationId = data.application_id;
+
+    /**
+     * The activity instance id
+     *
+     * @type {string}
+     */
+    this.instanceId = data.instance_id;
+
+    /**
+     * The unique identifier for the launch
+     *
+     * @type {Snowflake}
+     */
+    this.launchId = data.launch_id;
+
+    /**
+     * The location the instance is running in
+     *
+     * @type {ActivityLocation}
+     */
+    this.location = new ActivityLocation(client, data.location);
+
+    /**
+     * The ids of the users connected to the instance
+     *
+     * @type {Snowflake[]}
+     */
+    this.users = data.users;
+  }
+}
+
+exports.ActivityInstance = ActivityInstance;

packages/discord.js/src/structures/ActivityLocation.js

@@ -0,0 +1,65 @@
+'use strict';
+
+const Base = require('./Base');
+
+/**
+ * Represents the location of an activity instance.
+ *
+ * @extends {Base}
+ */
+class ActivityLocation extends Base {
+  constructor(client, data) {
+    super(client);
+
+    /**
+     * The unique identifier for the location
+     *
+     * @type {string}
+     */
+    this.id = data.id;
+
+    /**
+     * The kind of location
+     *
+     * @type {ActivityLocationKind}
+     */
+    this.kind = data.kind;
+
+    /**
+     * The id of the channel
+     *
+     * @type {Snowflake}
+     */
+    this.channelId = data.channel_id;
+
+    /**
+     * The id of the guild
+     *
+     * @type {?Snowflake}
+     */
+    this.guildId = data.guild_id ?? null;
+  }
+
+  /**
+   * The channel of this activity location
+   *
+   * @type {?Channel}
+   * @readonly
+   */
+  get channel() {
+    return this.client.channels.cache.get(this.channelId) ?? null;
+  }
+
+  /**
+   * The guild of this activity location
+   *
+   * @type {?Guild}
+   * @readonly
+   */
+  get guild() {
+    if (!this.guildId) return null;
+    return this.client.guilds.cache.get(this.guildId) ?? null;
+  }
+}
+
+exports.ActivityLocation = ActivityLocation;

packages/discord.js/src/structures/ClientApplication.js

@@ -2,6 +2,7 @@
 
 const { Collection } = require('@discordjs/collection');
 const { Routes } = require('discord-api-types/v10');
+const { ActivityInstance } = require('./ActivityInstance');
 const { ApplicationRoleConnectionMetadata } = require('./ApplicationRoleConnectionMetadata');
 const { SKU } = require('./SKU');
 const Team = require('./Team');
@@ -410,6 +411,17 @@ class ClientApplication extends Application {
     const skus = await this.client.rest.get(Routes.skus(this.id));
     return skus.reduce((coll, sku) => coll.set(sku.id, new SKU(this.client, sku)), new Collection());
   }
+
+  /**
+   * Fetches an activity instance for this application.
+   *
+   * @param {string} instanceId The id of the activity instance
+   * @returns {Promise<ActivityInstance>}
+   */
+  async fetchActivityInstance(instanceId) {
+    const data = await this.client.rest.get(Routes.applicationActivityInstance(this.id, instanceId));
+    return new ActivityInstance(this.client, data);
+  }
 }
 
 module.exports = ClientApplication;

packages/discord.js/src/util/APITypes.js

@@ -5,6 +5,11 @@
  * @see {@link https://discord-api-types.dev/api/discord-api-types-v10/enum/ActivityFlags}
  */
 
+/**
+ * @external ActivityLocationKind
+ * @see {@link https://discord-api-types.dev/api/discord-api-types-v10/enum/ActivityLocationKind}
+ */
+
 /**
  * @external ActivityType
  * @see {@link https://discord-api-types.dev/api/discord-api-types-v10/enum/ActivityType}

packages/discord.js/typings/index.d.ts

@@ -53,6 +53,9 @@ import {
   SessionInfo,
 } from '@discordjs/ws';
 import {
+  APIActivityInstance,
+  APIActivityLocation,
+  ActivityLocationKind,
   APIActionRowComponent,
   APIApplicationCommandInteractionData,
   APIApplicationCommandOption,
@@ -318,6 +321,25 @@ export class Activity {
   public toString(): string;
 }
 
+export class ActivityInstance extends Base {
+  private constructor(client: Client<true>, data: APIActivityInstance);
+  public applicationId: Snowflake;
+  public instanceId: string;
+  public launchId: Snowflake;
+  public location: ActivityLocation;
+  public users: Snowflake[];
+}
+
+export class ActivityLocation extends Base {
+  private constructor(client: Client<true>, data: APIActivityLocation);
+  public id: string;
+  public kind: ActivityLocationKind;
+  public channelId: Snowflake;
+  public guildId: Snowflake | null;
+  public get channel(): Channel | null;
+  public get guild(): Guild | null;
+}
+
 export type ActivityFlagsString = keyof typeof ActivityFlags;
 
 export interface BaseComponentData {
@@ -1217,6 +1239,7 @@ export class ClientApplication extends Application {
   public roleConnectionsVerificationURL: string | null;
   public edit(options: ClientApplicationEditOptions): Promise<ClientApplication>;
   public fetch(): Promise<ClientApplication>;
+  public fetchActivityInstance(instanceId: string): Promise<ActivityInstance>;
   public fetchRoleConnectionMetadataRecords(): Promise<ApplicationRoleConnectionMetadata[]>;
   public fetchSKUs(): Promise<Collection<Snowflake, SKU>>;
   public editRoleConnectionMetadataRecords(