From 7f1ffc83717f2dc848b37946ff0e45bbc1f947d9 Mon Sep 17 00:00:00 2001
From: almeidx <github@almeidx.dev>
Date: Sun, 5 Apr 2026 19:27:13 +0100
Subject: [PATCH] feat(ClientApplication): add fetchActivityInstance method

---
 .../src/structures/ClientApplication.js       | 43 +++++++++++++++++++
 packages/discord.js/src/util/APITypes.js      |  5 +++
 packages/discord.js/typings/index.d.ts        | 17 ++++++++
 3 files changed, 65 insertions(+)

diff --git a/packages/discord.js/src/structures/ClientApplication.js b/packages/discord.js/src/structures/ClientApplication.js
index 072286a8e..e7d7844fd 100644
--- a/packages/discord.js/src/structures/ClientApplication.js
+++ b/packages/discord.js/src/structures/ClientApplication.js
@@ -446,6 +446,49 @@ 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());
   }
+
+  /**
+   * Represents the location of an activity instance.
+   *
+   * @typedef {Object} ActivityLocation
+   * @property {string} id Unique identifier for the location
+   * @property {ActivityLocationKind} kind The kind of location
+   * @property {Snowflake} channelId The id of the channel
+   * @property {?Snowflake} guildId The id of the guild
+   */
+
+  /**
+   * Represents an activity instance.
+   *
+   * @typedef {Object} ActivityInstanceData
+   * @property {Snowflake} applicationId The application id
+   * @property {string} instanceId The activity instance id
+   * @property {Snowflake} launchId Unique identifier for the launch
+   * @property {ActivityLocation} location The location the instance is running in
+   * @property {Snowflake[]} users The ids of the users connected to the instance
+   */
+
+  /**
+   * Fetches an activity instance for this application.
+   *
+   * @param {string} instanceId The id of the activity instance
+   * @returns {Promise<ActivityInstanceData>}
+   */
+  async fetchActivityInstance(instanceId) {
+    const data = await this.client.rest.get(Routes.applicationActivityInstance(this.id, instanceId));
+    return {
+      applicationId: data.application_id,
+      instanceId: data.instance_id,
+      launchId: data.launch_id,
+      location: {
+        id: data.location.id,
+        kind: data.location.kind,
+        channelId: data.location.channel_id,
+        guildId: data.location.guild_id ?? null,
+      },
+      users: data.users,
+    };
+  }
 }
 
 exports.ClientApplication = ClientApplication;
diff --git a/packages/discord.js/src/util/APITypes.js b/packages/discord.js/src/util/APITypes.js
index 1e11f8692..75638dbd1 100644
--- a/packages/discord.js/src/util/APITypes.js
+++ b/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}
diff --git a/packages/discord.js/typings/index.d.ts b/packages/discord.js/typings/index.d.ts
index be0aeac86..6057f0ea2 100644
--- a/packages/discord.js/typings/index.d.ts
+++ b/packages/discord.js/typings/index.d.ts
@@ -9,6 +9,7 @@ import { WebSocketManager, WebSocketManagerOptions } from '@discordjs/ws';
 import { AsyncEventEmitter } from '@vladfrangu/async_event_emitter';
 import {
   ActivityFlags,
+  ActivityLocationKind,
   ActivityType,
   APIActionRowComponent,
   APIApplicationCommand,
@@ -1004,6 +1005,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<ActivityInstanceData>;
   public fetchRoleConnectionMetadataRecords(): Promise<ApplicationRoleConnectionMetadata[]>;
   public fetchSKUs(): Promise<Collection<Snowflake, SKU>>;
   public editRoleConnectionMetadataRecords(
@@ -7402,6 +7404,21 @@ export interface ClientApplicationInstallParams {
   scopes: readonly OAuth2Scopes[];
 }
 
+export interface ActivityLocation {
+  channelId: Snowflake;
+  guildId: Snowflake | null;
+  id: string;
+  kind: ActivityLocationKind;
+}
+
+export interface ActivityInstanceData {
+  applicationId: Snowflake;
+  instanceId: string;
+  launchId: Snowflake;
+  location: ActivityLocation;
+  users: readonly Snowflake[];
+}
+
 export type Serialized<Value> = Value extends bigint | symbol | (() => any)
   ? never
   : Value extends boolean | number | string | undefined