From 693fcbc32b64568671b5163a1acda33a65e843f0 Mon Sep 17 00:00:00 2001
From: Asad <105254706+AsadHumayun@users.noreply.github.com>
Date: Tue, 27 Jan 2026 23:03:09 +0000
Subject: [PATCH] feat(structures): add Stage Instance structure (#11397)

* feat(structures): update barrel exports for stage instance structure

* feat(structures): add stage instance structure

* docs(structure): cleanup and use see/link correctly

---------

Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
---
 packages/structures/src/index.ts              |  1 +
 .../src/stageInstances/StageInstance.ts       | 85 +++++++++++++++++++
 .../structures/src/stageInstances/index.ts    |  1 +
 3 files changed, 87 insertions(+)
 create mode 100644 packages/structures/src/stageInstances/StageInstance.ts
 create mode 100644 packages/structures/src/stageInstances/index.ts

diff --git a/packages/structures/src/index.ts b/packages/structures/src/index.ts
index 22c9c5592..e9688cd87 100644
--- a/packages/structures/src/index.ts
+++ b/packages/structures/src/index.ts
@@ -10,6 +10,7 @@ export * from './polls/index.js';
 export * from './stickers/index.js';
 export * from './teams/index.js';
 export * from './users/index.js';
+export * from './stageInstances/index.js';
 export * from './Structure.js';
 export * from './subscriptions/index.js';
 export * from './Mixin.js';
diff --git a/packages/structures/src/stageInstances/StageInstance.ts b/packages/structures/src/stageInstances/StageInstance.ts
new file mode 100644
index 000000000..6549eb07a
--- /dev/null
+++ b/packages/structures/src/stageInstances/StageInstance.ts
@@ -0,0 +1,85 @@
+import { DiscordSnowflake } from '@sapphire/snowflake';
+import type { APIStageInstance } from 'discord-api-types/v10';
+import { Structure } from '../Structure.js';
+import { kData } from '../utils/symbols.js';
+import { isIdSet } from '../utils/type-guards.js';
+import type { Partialize } from '../utils/types.js';
+
+/**
+ * Represents any stage instance on Discord.
+ *
+ * @typeParam Omitted - Specify the properties that will not be stored in the raw data field as a union, implement via `DataTemplate`
+ */
+export class StageInstance<Omitted extends keyof APIStageInstance | '' = ''> extends Structure<
+	APIStageInstance,
+	Omitted
+> {
+	/**
+	 * The template used for removing data from the raw data stored for each stage instance
+	 */
+	public static override readonly DataTemplate: Partial<APIStageInstance> = {};
+
+	/**
+	 * @param data - The raw data received from the API for the stage instance
+	 */
+	public constructor(data: Partialize<APIStageInstance, Omitted>) {
+		super(data);
+	}
+
+	/**
+	 * The stage instance's id
+	 */
+	public get id() {
+		return this[kData].id;
+	}
+
+	/**
+	 * The guild id of the associated stage channel
+	 */
+	public get guildId() {
+		return this[kData].guild_id;
+	}
+
+	/**
+	 * The id of the associated stage channel
+	 */
+	public get channelId() {
+		return this[kData].channel_id;
+	}
+
+	/**
+	 * The topic of the stage instance (1-120 characters)
+	 */
+	public get topic() {
+		return this[kData].topic;
+	}
+
+	/**
+	 * The privacy level of the stage instance
+	 */
+	public get privacyLevel() {
+		return this[kData].privacy_level;
+	}
+
+	/**
+	 * The id of the scheduled event for this stage instance
+	 */
+	public get guildScheduledEventId() {
+		return this[kData].guild_scheduled_event_id;
+	}
+
+	/**
+	 * The timestamp the stage instance was created at
+	 */
+	public get createdTimestamp() {
+		return isIdSet(this.id) ? DiscordSnowflake.timestampFrom(this.id) : null;
+	}
+
+	/**
+	 * The time the stage instance was created at
+	 */
+	public get createdAt() {
+		const createdTimestamp = this.createdTimestamp;
+		return createdTimestamp ? new Date(createdTimestamp) : null;
+	}
+}
diff --git a/packages/structures/src/stageInstances/index.ts b/packages/structures/src/stageInstances/index.ts
new file mode 100644
index 000000000..085b4caac
--- /dev/null
+++ b/packages/structures/src/stageInstances/index.ts
@@ -0,0 +1 @@
+export * from './StageInstance.js';