From 65386034b642b36f6fe8f0e9100928dcab9453c1 Mon Sep 17 00:00:00 2001
From: Asad <105254706+AsadHumayun@users.noreply.github.com>
Date: Tue, 27 Jan 2026 23:10:19 +0000
Subject: [PATCH] feat(structures): add SoundboardSound structure (#11390)

* feat(structures): update barrel exports in preparation for new structure

* feat(structures): add SoundboardSound structure

* chore(structures): update doc comment

* chore(structures): address review suggestions

* chore(structures): consistency changes and use isIdSet to retrieve id

* docs(structures): add remarks to conditionally present attributes

---------

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

diff --git a/packages/structures/src/index.ts b/packages/structures/src/index.ts
index e9688cd87..5150b9fd5 100644
--- a/packages/structures/src/index.ts
+++ b/packages/structures/src/index.ts
@@ -7,6 +7,7 @@ export * from './interactions/index.js';
 export * from './invites/index.js';
 export * from './messages/index.js';
 export * from './polls/index.js';
+export * from './soundboards/index.js';
 export * from './stickers/index.js';
 export * from './teams/index.js';
 export * from './users/index.js';
diff --git a/packages/structures/src/soundboards/SoundboardSound.ts b/packages/structures/src/soundboards/SoundboardSound.ts
new file mode 100644
index 000000000..4f1c29674
--- /dev/null
+++ b/packages/structures/src/soundboards/SoundboardSound.ts
@@ -0,0 +1,100 @@
+import { DiscordSnowflake } from '@sapphire/snowflake';
+import type { APISoundboardSound } from 'discord-api-types/v10';
+import { Structure } from '../Structure';
+import { kData } from '../utils/symbols';
+import { isIdSet } from '../utils/type-guards';
+import type { Partialize } from '../utils/types';
+
+/**
+ * Represents any soundboard sound on Discord.
+ *
+ * @typeParam Omitted - Specify the properties that will not be stored in the raw data field as a union, implement via `DataTemplate`
+ * @remarks has substructure `User` which needs to be instantiated and stored by an extending class using it
+ */
+export class SoundboardSound<Omitted extends keyof APISoundboardSound | '' = ''> extends Structure<
+	APISoundboardSound,
+	Omitted
+> {
+	/**
+	 * The template used for removing data from the raw data stored for each soundboard sound.
+	 */
+	public static override readonly DataTemplate: Partial<APISoundboardSound> = {};
+
+	/**
+	 * @param data - The raw data received from the API for the soundboard sound
+	 */
+	public constructor(data: Partialize<APISoundboardSound, Omitted>) {
+		super(data);
+	}
+
+	/**
+	 * The name of this sound
+	 */
+	public get name() {
+		return this[kData].name;
+	}
+
+	/**
+	 * The id of this sound
+	 */
+	public get soundId() {
+		return this[kData].sound_id;
+	}
+
+	/**
+	 * The volume of this sound, from 0 to 1
+	 */
+	public get volume() {
+		return this[kData].volume;
+	}
+
+	/**
+	 * The id of this sound's custom emoji
+	 */
+	public get emojiId() {
+		return this[kData].emoji_id;
+	}
+
+	/**
+	 * The unicode character of this sound's standard emoji
+	 */
+	public get emojiName() {
+		return this[kData].emoji_name;
+	}
+
+	/**
+	 * The id of the guild this sound is in
+	 */
+	public get guildId() {
+		return this[kData].guild_id;
+	}
+
+	/**
+	 * Whether this sound can be used, may be false due to loss of server boosts
+	 */
+	public get available() {
+		return this[kData].available;
+	}
+
+	/**
+	 * The timestamp this sound was created at
+	 *
+	 * @remarks only available for guild soundboard sounds
+	 */
+	public get createdTimestamp() {
+		return isIdSet(this[kData].sound_id) && isIdSet(this[kData].guild_id)
+			? DiscordSnowflake.timestampFrom(this[kData].sound_id)
+			: null;
+	}
+
+	/**
+	 * The time this sound was created at
+	 *
+	 * @remarks only available for guild soundboard sounds
+	 */
+	public get createdAt() {
+		const createdTimestamp = this.createdTimestamp;
+
+		return createdTimestamp ? new Date(createdTimestamp) : null;
+	}
+}
diff --git a/packages/structures/src/soundboards/index.ts b/packages/structures/src/soundboards/index.ts
new file mode 100644
index 000000000..2f3da2acb
--- /dev/null
+++ b/packages/structures/src/soundboards/index.ts
@@ -0,0 +1 @@
+export * from './SoundboardSound.js';