Add new automod endpoints in the moderation API

Part of #314

.eslintrc.js

@@ -25,7 +25,7 @@ const memberNames = [
 	'^click_action$',
 	'^(image_)?url_\\dx$',
 	'^emoticon_sets?$',
-	'^is_(?:anonymous|broadcast|gift|user_input_required|sub_only|mature|enabled|paused|in_stock|previewable|playlist|(?:verified|known)_bot|live|auto|permanent|recurring|vacation_enabled|canceled|achieved)$',
+	'^is_(?:anonymous|broadcast|gift|user_input_required|sub_only|mature|enabled|paused|in_stock|previewable|playlist|(?:verified|known)_bot|live|auto|permanent|recurring|vacation_enabled|canceled|achieved|permitted)$',
 	'^minimum_allowed_role$',
 	'^(chatter|view(er)?)_count$',
 	'^min_bits$',
@@ -86,12 +86,17 @@ const memberNames = [
 	'^bits_enabled$',
 	'^configuration_location$',
 	'^request_identity_link$',
-	'^subscriptions_support_level$',
+	'^(?:subscriptions_support|overall)_level$',
 	'^support_email$',
 	'^viewer_summary$',
 	'^aspect_(?:width|height|ratio_[xy])',
 	'^(?:scale|zoom)_pixels',
 	'^(?:current|target)_amount$',
+	'^msg_text$',
+	'^sexuality_sex_or_gender$',
+	'^race_ethnicity_or_religion$',
+	'^sex_based_terms$',
+
 	// HTTP
 	'^Accept$'
 ];

packages/api/src/api/helix/moderation/HelixAutoModSettings.ts

@@ -0,0 +1,99 @@
+import { DataObject, rawDataSymbol, rtfm } from '@twurple/common';
+
+/** @private */
+export interface HelixAutoModSettingsData {
+	broadcaster_id: string;
+	moderator_id: string;
+	overall_level: number | null;
+	disability: number;
+	aggression: number;
+	sexuality_sex_or_gender: number;
+	misogyny: number;
+	bullying: number;
+	swearing: number;
+	race_ethnicity_or_religion: number;
+	sex_based_terms: number;
+}
+
+/**
+ * The AutoMod settings of a channel.
+ */
+@rtfm<HelixAutoModSettings>('api', 'HelixAutoModSettings', 'broadcasterId')
+export class HelixAutoModSettings extends DataObject<HelixAutoModSettingsData> {
+	/**
+	 * The ID of the broadcaster for which the AutoMod settings are retrieved.
+	 */
+	get broadcasterId(): string {
+		return this[rawDataSymbol].broadcaster_id;
+	}
+
+	/**
+	 * The ID of a user that has permission to moderate the broadcaster's chat room.
+	 */
+	get moderatorId(): string {
+		return this[rawDataSymbol].moderator_id;
+	}
+
+	/**
+	 * The default AutoMod level for the broadcaster. This is null if the broadcaster changed individual settings.
+	 */
+	get overallLevel(): number | null {
+		return this[rawDataSymbol].overall_level ? this[rawDataSymbol].overall_level : null;
+	}
+
+	/**
+	 * The Automod level for discrimination against disability.
+	 */
+	get disability(): number {
+		return this[rawDataSymbol].disability;
+	}
+
+	/**
+	 * The Automod level for hostility involving aggression.
+	 */
+	get aggression(): number {
+		return this[rawDataSymbol].aggression;
+	}
+
+	/**
+	 * The AutoMod level for discrimination based on sexuality, sex, or gender.
+	 */
+	get sexualitySexOrGender(): number {
+		return this[rawDataSymbol].sexuality_sex_or_gender;
+	}
+
+	/**
+	 * The Automod level for discrimination against women.
+	 */
+	get misogyny(): number {
+		return this[rawDataSymbol].misogyny;
+	}
+
+	/**
+	 * The Automod level for hostility involving name calling or insults.
+	 */
+	get bullying(): number {
+		return this[rawDataSymbol].bullying;
+	}
+
+	/**
+	 * The Automod level for profanity.
+	 */
+	get swearing(): number {
+		return this[rawDataSymbol].swearing;
+	}
+
+	/**
+	 * The Automod level for racial discrimination.
+	 */
+	get raceEthnicityOrReligion(): number {
+		return this[rawDataSymbol].race_ethnicity_or_religion;
+	}
+
+	/**
+	 * The Automod level for sexual content.
+	 */
+	get sexBasedTerms(): number {
+		return this[rawDataSymbol].sex_based_terms;
+	}
+}

packages/api/src/api/helix/moderation/HelixAutoModStatus.ts

@@ -0,0 +1,27 @@
+import { DataObject, rawDataSymbol, rtfm } from '@twurple/common';
+
+/** @private */
+export interface HelixAutoModStatusData {
+	msg_id: string;
+	is_permitted: boolean;
+}
+
+/**
+ * The status of a message that says whether it is permitted by AutoMod or not.
+ */
+@rtfm<HelixAutoModStatus>('api', 'HelixAutoModStatus', 'messageId')
+export class HelixAutoModStatus extends DataObject<HelixAutoModStatusData> {
+	/**
+	 * The developer-generated ID that was sent with the request data.
+	 */
+	get messageId(): string {
+		return this[rawDataSymbol].msg_id;
+	}
+
+	/**
+	 * Whether the message is permitted by AutoMod or not.
+	 */
+	get isPermitted(): boolean {
+		return this[rawDataSymbol].is_permitted;
+	}
+}

packages/api/src/api/helix/moderation/HelixModerationApi.ts

@@ -6,7 +6,7 @@ import type { HelixPaginatedResult } from '../HelixPaginatedResult';
 import { createPaginatedResult } from '../HelixPaginatedResult';
 import type { HelixForwardPagination } from '../HelixPagination';
 import { makePaginationQuery } from '../HelixPagination';
-import type { HelixPaginatedResponse } from '../HelixResponse';
+import type { HelixPaginatedResponse, HelixResponse } from '../HelixResponse';
 import type { HelixBanData } from './HelixBan';
 import { HelixBan } from './HelixBan';
 import type { HelixBanEventData } from './HelixBanEvent';
@@ -15,6 +15,10 @@ import type { HelixModeratorData } from './HelixModerator';
 import { HelixModerator } from './HelixModerator';
 import type { HelixModeratorEventData } from './HelixModeratorEvent';
 import { HelixModeratorEvent } from './HelixModeratorEvent';
+import type { HelixAutoModStatusData } from './HelixAutoModStatus';
+import { HelixAutoModStatus } from './HelixAutoModStatus';
+import type { HelixAutoModSettingsData } from './HelixAutoModSettings';
+import { HelixAutoModSettings } from './HelixAutoModSettings';
 
 /**
  * Filters for the banned users request.
@@ -36,6 +40,25 @@ export interface HelixModeratorFilter extends HelixForwardPagination {
 	userId: string | string[];
 }
 
+export interface HelixCheckAutoModStatusData {
+	/**
+	 * The developer-generated ID for mapping messages to their status results.
+	 */
+	messageId: string;
+
+	/**
+	 * The text of the message the AutoMod status needs to be checked for.
+	 */
+	messageText: string;
+
+	/**
+	 * The ID of the sender of the message the AutoMod status needs to be checked for.
+	 */
+	userId: string;
+}
+
+export type HelixAutoModSettingsUpdate = Exclude<HelixAutoModSettings, 'broadcasterId' | 'moderatorId'>;
+
 /**
  * The Helix API methods that deal with moderation.
  *
@@ -247,6 +270,32 @@ export class HelixModerationApi extends BaseApi {
 		);
 	}
 
+	/**
+	 * Determines whether a string message meets the channel's AutoMod requirements.
+	 *
+	 * @param channel The channel in which the messages to check are posted.
+	 * @param data An array of message data objects.
+	 */
+	async checkAutoModStatus(
+		channel: UserIdResolvable,
+		data: HelixCheckAutoModStatusData[]
+	): Promise<HelixAutoModStatus[]> {
+		const result = await this._client.callApi<HelixResponse<HelixAutoModStatusData>>({
+			type: 'helix',
+			url: 'moderation/enforcements/status',
+			method: 'POST',
+			scope: 'moderation:read',
+			query: {
+				broadcaster_id: extractUserId(channel)
+			},
+			jsonBody: {
+				data: data
+			}
+		});
+
+		return result.data.map(statusData => new HelixAutoModStatus(statusData));
+	}
+
 	/**
 	 * Processes a message held by AutoMod.
 	 *
@@ -267,4 +316,66 @@ export class HelixModerationApi extends BaseApi {
 			}
 		});
 	}
+
+	/**
+	 * Retrieves the AutoMod settings for a broadcaster.
+	 *
+	 * @param broadcasterId The ID of the broadcaster for which the AutoMod settings are retrieved.
+	 * @param moderatorId The ID of a user that has permission to moderate the broadcaster's chat room.
+	 * This must match the user ID associated with the user OAuth token.
+	 */
+	async getAutoModSettings(
+		broadcasterId: UserIdResolvable,
+		moderatorId: UserIdResolvable
+	): Promise<HelixAutoModSettings[]> {
+		const result = await this._client.callApi<HelixResponse<HelixAutoModSettingsData>>({
+			type: 'helix',
+			url: 'moderation/automod/settings',
+			scope: 'moderator:read:automod_settings',
+			query: {
+				broadcaster_id: extractUserId(broadcasterId),
+				moderator_id: extractUserId(moderatorId)
+			}
+		});
+
+		return result.data.map(data => new HelixAutoModSettings(data));
+	}
+
+	/**
+	 * Updates the AutoMod settings for a broadcaster.
+	 *
+	 * @param broadcasterId The ID of the broadcaster for which the AutoMod settings are updated.
+	 * @param moderatorId The ID of a user that has permission to moderate the broadcaster's chat room.
+	 * This must match the user ID associated with the user OAuth token.
+	 * @param data The updated AutoMod settings that replace the current AutoMod settings.
+	 */
+	async updateAutoModSettings(
+		broadcasterId: UserIdResolvable,
+		moderatorId: UserIdResolvable,
+		data: HelixAutoModSettingsUpdate
+	): Promise<HelixAutoModSettings[]> {
+		const result = await this._client.callApi<HelixResponse<HelixAutoModSettingsData>>({
+			type: 'helix',
+			url: 'moderation/automod/settings',
+			method: 'PUT',
+			scope: 'moderator:manage:automod_settings',
+			query: {
+				broadcaster_id: extractUserId(broadcasterId),
+				moderator_id: extractUserId(moderatorId)
+			},
+			jsonBody: {
+				overall_level: data.overallLevel,
+				aggression: data.aggression,
+				bullying: data.bullying,
+				disability: data.disability,
+				misogyny: data.misogyny,
+				race_ethnicity_or_religion: data.raceEthnicityOrReligion,
+				sex_based_terms: data.sexBasedTerms,
+				sexuality_sex_or_gender: data.sexualitySexOrGender,
+				swearing: data.swearing
+			}
+		});
+
+		return result.data.map(settingsData => new HelixAutoModSettings(settingsData));
+	}
 }