@atcute/bluesky-moderation#

interpret Bluesky content moderation labels and user preferences.

npm install @atcute/bluesky-moderation

evaluates posts, profiles, lists, and other content against moderation labels, mutes, blocks, and keyword filters to determine how they should be displayed.

usage#

basic flow#

1. fetch user preferences and labeler definitions
2. run moderation functions on content
3. get display restrictions for your UI context

import {
	DisplayContext,
	getDisplayRestrictions,
	interpretLabelerDefinitions,
	moderatePost,
	type ModerationPreferences,
} from '@atcute/bluesky-moderation';

// 1. set up preferences (see "loading preferences" below)
const prefs: ModerationPreferences = { ... };
const labelDefs = interpretLabelerDefinitions(labelers);

// 2. moderate content
const decision = moderatePost(post, {
	viewerDid: 'did:plc:...',
	prefs,
	labelDefs,
});

// 3. get display restrictions for your context
const ui = getDisplayRestrictions(decision, DisplayContext.ContentList);

if (ui.filters.length > 0) {
	// don't show this post in feeds
}

if (ui.blurs.length > 0) {
	// hide behind a content warning

	if (ui.noOverride) {
		// don't allow user to reveal
	}
}

if (ui.alerts.length > 0 || ui.informs.length > 0) {
	// show warning badges
}

display contexts#

use different contexts depending on where content appears:

// content in feeds/lists
getDisplayRestrictions(decision, DisplayContext.ContentList);

// content in expanded view
getDisplayRestrictions(decision, DisplayContext.ContentView);

// images/videos in content
getDisplayRestrictions(decision, DisplayContext.ContentMedia);

// profile in lists
getDisplayRestrictions(decision, DisplayContext.ProfileList);

// profile in expanded view
getDisplayRestrictions(decision, DisplayContext.ProfileView);

// profile avatar/banner
getDisplayRestrictions(decision, DisplayContext.ProfileMedia);

loading preferences#

import {
	interpretLabelerDefinitions,
	interpretMutedWordPreferences,
	LabelPreference,
	type ModerationPreferences,
} from '@atcute/bluesky-moderation';

// fetch user preferences
const { data } = await rpc.get('app.bsky.actor.getPreferences', {});

const prefs: ModerationPreferences = {
	adultContentEnabled: false,
	globalLabelPrefs: {},
	prefsByLabelers: {},
	keywordFilters: [],
	hiddenPosts: [],
	temporaryMutes: [],
};

for (const pref of data.preferences) {
	switch (pref.$type) {
		case 'app.bsky.actor.defs#adultContentPref':
			prefs.adultContentEnabled = pref.enabled;
			break;

		case 'app.bsky.actor.defs#contentLabelPref':
			// map visibility to LabelPreference
			const labelPref =
				pref.visibility === 'hide'
					? LabelPreference.Hide
					: pref.visibility === 'warn'
						? LabelPreference.Warn
						: LabelPreference.Ignore;

			if (pref.labelerDid) {
				prefs.prefsByLabelers[pref.labelerDid] ??= { labelPrefs: {} };
				prefs.prefsByLabelers[pref.labelerDid].labelPrefs[pref.label] = labelPref;
			} else {
				prefs.globalLabelPrefs[pref.label] = labelPref;
			}
			break;

		case 'app.bsky.actor.defs#mutedWordsPref':
			prefs.keywordFilters = interpretMutedWordPreferences(pref);
			break;

		case 'app.bsky.actor.defs#hiddenPostsPref':
			prefs.hiddenPosts = pref.items;
			break;
	}
}

// fetch labeler definitions
const { data: labelerData } = await rpc.get('app.bsky.labeler.getServices', {
	params: { dids: [...labelerDids], detailed: true },
});

const labelDefs = interpretLabelerDefinitions(
	labelerData.views.filter((v) => v.$type === 'app.bsky.labeler.defs#labelerViewDetailed'),
);

moderating different content types#

import {
	moderateFeedGenerator,
	moderateList,
	moderateNotification,
	moderatePost,
	moderateProfile,
} from '@atcute/bluesky-moderation';

const postDecision = moderatePost(post, opts);
const profileDecision = moderateProfile(profile, opts);
const listDecision = moderateList(list, opts);
const feedDecision = moderateFeedGenerator(feed, opts);
const notifDecision = moderateNotification(notification, opts);