@atcute/bluesky-moderation 2.0.4 → 3.0.0

package/README.md

@@ -1,167 +1,165 @@
 # @atcute/bluesky-moderation
 
-interprets Bluesky's content moderation labels.
+interpret Bluesky content moderation labels and user preferences.
 
-```ts
-import type { XRPC } from '@atcute/client';
-import type { AppBskyActorDefs, AppBskyFeedDefs, AppBskyLabelerDefs, At } from '@atcute/client/lexicons';
+```sh
+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
+
+```ts
 import {
 	DisplayContext,
 	getDisplayRestrictions,
 	interpretLabelerDefinitions,
-	interpretMutedWordPreferences,
-	LabelPreference,
 	moderatePost,
 	type ModerationPreferences,
 } from '@atcute/bluesky-moderation';
 
-declare const rpc: XRPC;
-
-// first, let's get the user's preferences
-const labelerDids = new Set<At.Did>([
-	// Bluesky moderation service
-	'did:plc:ar7c4by46qjdydhdevvrndac',
-]);
-
-const modPrefs: ModerationPreferences = {
-	adultContentEnabled: false,
-	globalLabelPrefs: {},
-	prefsByLabelers: {
-		'did:plc:ar7c4by46qjdydhdevvrndac': {
-			labelPrefs: {},
-		},
-	},
-	keywordFilters: [],
-	hiddenPosts: [],
-	temporaryMutes: [],
-};
+// 1. set up preferences (see "loading preferences" below)
+const prefs: ModerationPreferences = { ... };
+const labelDefs = interpretLabelerDefinitions(labelers);
 
-{
-	const { data } = await rpc.get('app.bsky.actor.getPreferences', {});
+// 2. moderate content
+const decision = moderatePost(post, {
+	viewerDid: 'did:plc:...',
+	prefs,
+	labelDefs,
+});
 
-	const labelPrefs: AppBskyActorDefs.ContentLabelPref[] = [];
+// 3. get display restrictions for your context
+const ui = getDisplayRestrictions(decision, DisplayContext.ContentList);
 
-	const globalLabelPrefs = (modPrefs.globalLabelPrefs ??= {});
-	const prefsByLabelers = (modPrefs.prefsByLabelers ??= {});
+if (ui.filters.length > 0) {
+	// don't show this post in feeds
+}
 
-	for (const pref of data.preferences) {
-		switch (pref.$type) {
-			case 'app.bsky.actor.defs#adultContentPref': {
-				modPrefs.adultContentEnabled = pref.enabled;
-				break;
-			}
-			case 'app.bsky.actor.defs#labelersPref': {
-				for (const labeler of pref.labelers) {
-					prefsByLabelers[labeler.did] ??= { labelPrefs: {} };
-					labelerDids.add(labeler.did);
-				}
+if (ui.blurs.length > 0) {
+	// hide behind a content warning
 
-				break;
-			}
-			case 'app.bsky.actor.defs#contentLabelPref': {
-				labelPrefs.push(pref);
-				break;
-			}
-			case 'app.bsky.actor.defs#mutedWordsPref': {
-				modPrefs.keywordFilters = interpretMutedWordPreferences(pref);
-				break;
-			}
-			case 'app.bsky.actor.defs#hiddenPostsPref': {
-				modPrefs.hiddenPosts = pref.items as At.CanonicalResourceUri[];
-				break;
-			}
-		}
+	if (ui.noOverride) {
+		// don't allow user to reveal
 	}
+}
 
-	for (const { labelerDid, label, visibility } of labelPrefs) {
-		let pref: LabelPreference | undefined;
-		switch (visibility) {
-			case 'show':
-			case 'ignore': {
-				pref = LabelPreference.Ignore;
-				break;
-			}
-			case 'warn': {
-				pref = LabelPreference.Warn;
-				break;
-			}
-			case 'hide': {
-				pref = LabelPreference.Hide;
-				break;
-			}
-		}
+if (ui.alerts.length > 0 || ui.informs.length > 0) {
+	// show warning badges
+}
+```
 
-		if (labelerDid === undefined) {
-			globalLabelPrefs[label] = pref;
-		} else if (labelerDid in prefsByLabelers) {
-			const labelerPref = prefsByLabelers[labelerDid]!;
+### display contexts
 
-			labelerPref.labelPrefs[label] = pref;
-		}
-	}
-}
+use different contexts depending on where content appears:
 
-// grab labeler's definitions
-let labelers: AppBskyLabelerDefs.LabelerViewDetailed[] = [];
+```ts
+// content in feeds/lists
+getDisplayRestrictions(decision, DisplayContext.ContentList);
 
-{
-	const { data } = await rpc.get('app.bsky.labeler.getServices', {
-		params: {
-			dids: [...labelerDids],
-			detailed: true,
-		},
-	});
+// content in expanded view
+getDisplayRestrictions(decision, DisplayContext.ContentView);
 
-	labelers = data.views.filter((view) => view.$type === 'app.bsky.labeler.defs#labelerViewDetailed');
-}
+// images/videos in content
+getDisplayRestrictions(decision, DisplayContext.ContentMedia);
 
-// interpret the labeler's definitions into something the library can understand
-const labelDefs = interpretLabelerDefinitions(labelers);
+// profile in lists
+getDisplayRestrictions(decision, DisplayContext.ProfileList);
 
-// then we call the appropriate moderation functions
-{
-	declare const post: AppBskyFeedDefs.PostView;
+// profile in expanded view
+getDisplayRestrictions(decision, DisplayContext.ProfileView);
 
-	const mod = moderatePost(post, {
-		viewerDid: 'did:plc:xyz',
-		labelDefs,
-		prefs: modPrefs,
-	});
+// profile avatar/banner
+getDisplayRestrictions(decision, DisplayContext.ProfileMedia);
+```
 
-	// when displaying the post in feeds...
-	{
-		const ui = getDisplayRestrictions(mod, DisplayContext.ContentList);
+### loading preferences
 
-		if (ui.filters.length > 0) {
-			// don't include the post in the feed
-		}
+```ts
+import {
+	interpretLabelerDefinitions,
+	interpretMutedWordPreferences,
+	LabelPreference,
+	type ModerationPreferences,
+} from '@atcute/bluesky-moderation';
 
-		if (ui.blurs.length > 0) {
-			// hide the post behind a cover
+// fetch user preferences
+const { data } = await rpc.get('app.bsky.actor.getPreferences', {});
+
+const prefs: ModerationPreferences = {
+	adultContentEnabled: false,
+	globalLabelPrefs: {},
+	prefsByLabelers: {},
+	keywordFilters: [],
+	hiddenPosts: [],
+	temporaryMutes: [],
+};
 
-			if (ui.noOverride) {
-				// don't allow the cover to be removed
+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;
 
-		if (ui.alerts.length > 0 || ui.informs.length > 0) {
-			// show warning/inform badges in the post
-		}
+		case 'app.bsky.actor.defs#mutedWordsPref':
+			prefs.keywordFilters = interpretMutedWordPreferences(pref);
+			break;
+
+		case 'app.bsky.actor.defs#hiddenPostsPref':
+			prefs.hiddenPosts = pref.items;
+			break;
 	}
+}
 
-	// when displaying an expanded version of the post...
-	{
-		const ui = getDisplayRestrictions(mod, DisplayContext.ContentView);
+// 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'),
+);
+```
 
-	// when displaying images/videos of a post...
-	{
-		const ui = getDisplayRestrictions(mod, DisplayContext.ProfileMedia);
+### moderating different content types
 
-		// ...
-	}
-}
+```ts
+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);
 ```