@atproto/api 0.4.4 → 0.5.0

package/src/moderation/index.ts

@@ -0,0 +1,343 @@
+import { AppBskyActorDefs } from '../client/index'
+import {
+  ModerationSubjectProfile,
+  ModerationSubjectPost,
+  ModerationSubjectFeedGenerator,
+  ModerationSubjectUserList,
+  ModerationOpts,
+  ModerationDecision,
+  ModerationUI,
+} from './types'
+import { decideAccount } from './subjects/account'
+import { decideProfile } from './subjects/profile'
+import { decidePost } from './subjects/post'
+import {
+  decideQuotedPost,
+  decideQuotedPostAccount,
+  decideQuotedPostWithMedia,
+  decideQuotedPostWithMediaAccount,
+} from './subjects/quoted-post'
+import { decideFeedGenerator } from './subjects/feed-generator'
+import { decideUserList } from './subjects/user-list'
+import {
+  takeHighestPriorityDecision,
+  downgradeDecision,
+  isModerationDecisionNoop,
+  isQuotedPost,
+  isQuotedPostWithMedia,
+  toModerationUI,
+} from './util'
+
+// profiles
+// =
+
+export interface ProfileModeration {
+  decisions: {
+    account: ModerationDecision
+    profile: ModerationDecision
+  }
+  account: ModerationUI
+  profile: ModerationUI
+  avatar: ModerationUI
+}
+
+export function moderateProfile(
+  subject: ModerationSubjectProfile,
+  opts: ModerationOpts,
+): ProfileModeration {
+  // decide the moderation the account and the profile
+  const account = decideAccount(subject, opts)
+  const profile = decideProfile(subject, opts)
+
+  // if the decision is supposed to blur media,
+  // - have it apply to the view if it's on the account
+  // - otherwise ignore it
+  if (account.blurMedia) {
+    account.blur = true
+  }
+
+  // dont give profile.filter because that is meaningless
+  profile.filter = false
+
+  // downgrade based on authorship
+  if (!isModerationDecisionNoop(account) && account.did === opts.userDid) {
+    downgradeDecision(account, { alert: true })
+  }
+  if (!isModerationDecisionNoop(profile) && profile.did === opts.userDid) {
+    downgradeDecision(profile, { alert: true })
+  }
+
+  // derive avatar blurring from account & profile, but override for mutes because that shouldnt blur
+  let avatarBlur = false
+  let avatarNoOverride = false
+  if ((account.blur || account.blurMedia) && account.cause?.type !== 'muted') {
+    avatarBlur = true
+    avatarNoOverride = account.noOverride || profile.noOverride
+  } else if (profile.blur || profile.blurMedia) {
+    avatarBlur = true
+    avatarNoOverride = account.noOverride || profile.noOverride
+  }
+
+  // dont blur the account for blocking & muting
+  if (
+    account.cause?.type === 'blocking' ||
+    account.cause?.type === 'blocked-by' ||
+    account.cause?.type === 'muted'
+  ) {
+    account.blur = false
+    account.noOverride = false
+  }
+
+  return {
+    decisions: { account, profile },
+
+    // moderate all content based on account
+    account:
+      account.filter || account.blur || account.alert
+        ? toModerationUI(account)
+        : {},
+
+    // moderate the profile details based on the profile
+    profile:
+      profile.filter || profile.blur || profile.alert
+        ? toModerationUI(profile)
+        : {},
+
+    // blur or alert the avatar based on the account and profile decisions
+    avatar: {
+      blur: avatarBlur,
+      alert: account.alert || profile.alert,
+      noOverride: avatarNoOverride,
+    },
+  }
+}
+
+// posts
+// =
+
+export interface PostModeration {
+  decisions: {
+    post: ModerationDecision
+    account: ModerationDecision
+    profile: ModerationDecision
+    quote?: ModerationDecision
+    quotedAccount?: ModerationDecision
+  }
+  content: ModerationUI
+  avatar: ModerationUI
+  embed: ModerationUI
+}
+
+export function moderatePost(
+  subject: ModerationSubjectPost,
+  opts: ModerationOpts,
+): PostModeration {
+  // decide the moderation for the post, the post author's account,
+  // and the post author's profile
+  const post = decidePost(subject, opts)
+  const account = decideAccount(subject.author, opts)
+  const profile = decideProfile(subject.author, opts)
+
+  // decide the moderation for any quoted posts
+  let quote: ModerationDecision | undefined
+  let quotedAccount: ModerationDecision | undefined
+  if (isQuotedPost(subject.embed)) {
+    quote = decideQuotedPost(subject.embed, opts)
+    quotedAccount = decideQuotedPostAccount(subject.embed, opts)
+  } else if (isQuotedPostWithMedia(subject.embed)) {
+    quote = decideQuotedPostWithMedia(subject.embed, opts)
+    quotedAccount = decideQuotedPostWithMediaAccount(subject.embed, opts)
+  }
+
+  // downgrade based on authorship
+  if (!isModerationDecisionNoop(post) && post.did === opts.userDid) {
+    downgradeDecision(post, { alert: true })
+  }
+  if (!isModerationDecisionNoop(account) && account.did === opts.userDid) {
+    downgradeDecision(account, { alert: false })
+  }
+  if (!isModerationDecisionNoop(profile) && profile.did === opts.userDid) {
+    downgradeDecision(profile, { alert: false })
+  }
+  if (quote && !isModerationDecisionNoop(quote) && quote.did === opts.userDid) {
+    downgradeDecision(quote, { alert: true })
+  }
+  if (
+    quotedAccount &&
+    !isModerationDecisionNoop(quotedAccount) &&
+    quotedAccount.did === opts.userDid
+  ) {
+    downgradeDecision(quotedAccount, { alert: false })
+  }
+
+  // derive filtering from feeds from the post, post author's account,
+  // quoted post, and quoted post author's account
+  const mergedForFeed = takeHighestPriorityDecision(
+    post,
+    account,
+    quote,
+    quotedAccount,
+  )
+
+  // derive view blurring from the post and the post author's account
+  const mergedForView = takeHighestPriorityDecision(post, account)
+
+  // derive embed blurring from the quoted post and the quoted post author's account
+  const mergedQuote = takeHighestPriorityDecision(quote, quotedAccount)
+
+  // derive avatar blurring from account & profile, but override for mutes because that shouldnt blur
+  let blurAvatar = false
+  if ((account.blur || account.blurMedia) && account.cause?.type !== 'muted') {
+    blurAvatar = true
+  } else if (
+    (profile.blur || profile.blurMedia) &&
+    profile.cause?.type !== 'muted'
+  ) {
+    blurAvatar = true
+  }
+
+  return {
+    decisions: { post, account, profile, quote, quotedAccount },
+
+    // content behaviors are pulled from feed and view derivations above
+    content: {
+      cause: !isModerationDecisionNoop(mergedForView)
+        ? mergedForView.cause
+        : mergedForFeed.filter
+        ? mergedForFeed.cause
+        : undefined,
+      filter: mergedForFeed.filter,
+      blur: mergedForView.blur,
+      alert: mergedForView.alert,
+      noOverride: mergedForView.noOverride,
+    },
+
+    // blur or alert the avatar based on the account and profile decisions
+    avatar: {
+      blur: blurAvatar,
+      alert: account.alert || profile.alert,
+      noOverride: account.noOverride || profile.noOverride,
+    },
+
+    // blur the embed if the quoted post required it,
+    // or else if the account or post decision was to blur media
+    embed: !isModerationDecisionNoop(mergedQuote, { ignoreFilter: true })
+      ? {
+          cause: mergedQuote.cause,
+          blur: mergedQuote.blur,
+          alert: mergedQuote.alert,
+          noOverride: mergedQuote.noOverride,
+        }
+      : account.blurMedia
+      ? {
+          cause: account.cause,
+          blur: true,
+          noOverride: account.noOverride,
+        }
+      : post.blurMedia
+      ? {
+          cause: post.cause,
+          blur: true,
+          noOverride: post.noOverride,
+        }
+      : {},
+  }
+}
+
+// feed generators
+// =
+
+export interface FeedGeneratorModeration {
+  decisions: {
+    feedGenerator: ModerationDecision
+    account: ModerationDecision
+    profile: ModerationDecision
+  }
+  content: ModerationUI
+  avatar: ModerationUI
+}
+
+export function moderateFeedGenerator(
+  subject: ModerationSubjectFeedGenerator,
+  opts: ModerationOpts,
+): FeedGeneratorModeration {
+  // decide the moderation for the generator, the generator creator's account,
+  // and the generator creator's profile
+  const feedGenerator = decideFeedGenerator(subject, opts)
+  const account = decideAccount(subject.creator, opts)
+  const profile = decideProfile(subject.creator, opts)
+
+  // derive behaviors from feeds from the generator and the generator's account
+  const merged = takeHighestPriorityDecision(feedGenerator, account)
+
+  return {
+    decisions: { feedGenerator, account, profile },
+
+    // content behaviors are pulled from merged decisions
+    content: {
+      cause: isModerationDecisionNoop(merged) ? undefined : merged.cause,
+      filter: merged.filter,
+      blur: merged.blur,
+      alert: merged.alert,
+      noOverride: merged.noOverride,
+    },
+
+    // blur or alert the avatar based on the account and profile decisions
+    avatar: {
+      blur: account.blurMedia || profile.blurMedia,
+      alert: account.alert,
+      noOverride: account.noOverride || profile.noOverride,
+    },
+  }
+}
+
+// user lists
+// =
+
+export interface UserListModeration {
+  decisions: {
+    userList: ModerationDecision
+    account: ModerationDecision
+    profile: ModerationDecision
+  }
+  content: ModerationUI
+  avatar: ModerationUI
+}
+
+export function moderateUserList(
+  subject: ModerationSubjectUserList,
+  opts: ModerationOpts,
+): UserListModeration {
+  // decide the moderation for the list, the list creator's account,
+  // and the list creator's profile
+  const userList = decideUserList(subject, opts)
+  const account = AppBskyActorDefs.isProfileViewBasic(subject.creator)
+    ? decideAccount(subject.creator, opts)
+    : ModerationDecision.noop()
+  const profile = AppBskyActorDefs.isProfileViewBasic(subject.creator)
+    ? decideProfile(subject.creator, opts)
+    : ModerationDecision.noop()
+
+  // derive behaviors from feeds from the list and the list's account
+  const merged = takeHighestPriorityDecision(userList, account)
+
+  return {
+    decisions: { userList, account, profile },
+
+    // content behaviors are pulled from merged decisions
+    content: {
+      cause: isModerationDecisionNoop(merged) ? undefined : merged.cause,
+      filter: merged.filter,
+      blur: merged.blur,
+      alert: merged.alert,
+      noOverride: merged.noOverride,
+    },
+
+    // blur or alert the avatar based on the account and profile decisions
+    avatar: {
+      blur: account.blurMedia || profile.blurMedia,
+      alert: account.alert,
+      noOverride: account.noOverride || profile.noOverride,
+    },
+  }
+}

package/src/moderation/subjects/account.ts

@@ -0,0 +1,40 @@
+import { ModerationCauseAccumulator } from '../accumulator'
+import {
+  Label,
+  ModerationSubjectProfile,
+  ModerationOpts,
+  ModerationDecision,
+} from '../types'
+
+export function decideAccount(
+  subject: ModerationSubjectProfile,
+  opts: ModerationOpts,
+): ModerationDecision {
+  const acc = new ModerationCauseAccumulator()
+
+  acc.setDid(subject.did)
+  if (subject.viewer?.muted) {
+    if (subject.viewer?.mutedByList) {
+      acc.addMutedByList(subject.viewer?.mutedByList)
+    } else {
+      acc.addMuted(subject.viewer?.muted)
+    }
+  }
+  acc.addBlocking(subject.viewer?.blocking)
+  acc.addBlockedBy(subject.viewer?.blockedBy)
+
+  for (const label of filterAccountLabels(subject.labels)) {
+    acc.addLabel(label, opts)
+  }
+
+  return acc.finalizeDecision(opts)
+}
+
+export function filterAccountLabels(labels?: Label[]): Label[] {
+  if (!labels) {
+    return []
+  }
+  return labels.filter(
+    (label) => !label.uri.endsWith('/app.bsky.actor.profile/self'),
+  )
+}

package/src/moderation/subjects/feed-generator.ts

@@ -0,0 +1,13 @@
+import {
+  ModerationSubjectFeedGenerator,
+  ModerationDecision,
+  ModerationOpts,
+} from '../types'
+
+export function decideFeedGenerator(
+  subject: ModerationSubjectFeedGenerator,
+  opts: ModerationOpts,
+): ModerationDecision {
+  // TODO handle labels applied on the feed generator itself
+  return ModerationDecision.noop()
+}

package/src/moderation/subjects/post.ts

@@ -0,0 +1,23 @@
+import { ModerationCauseAccumulator } from '../accumulator'
+import {
+  ModerationSubjectPost,
+  ModerationOpts,
+  ModerationDecision,
+} from '../types'
+
+export function decidePost(
+  subject: ModerationSubjectPost,
+  opts: ModerationOpts,
+): ModerationDecision {
+  const acc = new ModerationCauseAccumulator()
+
+  acc.setDid(subject.author.did)
+
+  if (subject.labels?.length) {
+    for (const label of subject.labels) {
+      acc.addLabel(label, opts)
+    }
+  }
+
+  return acc.finalizeDecision(opts)
+}

package/src/moderation/subjects/profile.ts

@@ -0,0 +1,31 @@
+import { ModerationCauseAccumulator } from '../accumulator'
+import {
+  Label,
+  ModerationSubjectProfile,
+  ModerationOpts,
+  ModerationDecision,
+} from '../types'
+
+export function decideProfile(
+  subject: ModerationSubjectProfile,
+  opts: ModerationOpts,
+): ModerationDecision {
+  const acc = new ModerationCauseAccumulator()
+
+  acc.setDid(subject.did)
+
+  for (const label of filterProfileLabels(subject.labels)) {
+    acc.addLabel(label, opts)
+  }
+
+  return acc.finalizeDecision(opts)
+}
+
+export function filterProfileLabels(labels?: Label[]): Label[] {
+  if (!labels) {
+    return []
+  }
+  return labels.filter((label) =>
+    label.uri.endsWith('/app.bsky.actor.profile/self'),
+  )
+}

package/src/moderation/subjects/quoted-post.ts

@@ -0,0 +1,62 @@
+import { AppBskyEmbedRecord, AppBskyEmbedRecordWithMedia } from '../../client'
+import { ModerationCauseAccumulator } from '../accumulator'
+import { ModerationOpts, ModerationDecision } from '../types'
+import { decideAccount } from './account'
+
+export function decideQuotedPost(
+  subject: AppBskyEmbedRecord.View,
+  opts: ModerationOpts,
+): ModerationDecision {
+  const acc = new ModerationCauseAccumulator()
+
+  if (AppBskyEmbedRecord.isViewRecord(subject.record)) {
+    acc.setDid(subject.record.author.did)
+
+    if (subject.record.labels?.length) {
+      for (const label of subject.record.labels) {
+        acc.addLabel(label, opts)
+      }
+    }
+  }
+
+  return acc.finalizeDecision(opts)
+}
+
+export function decideQuotedPostAccount(
+  subject: AppBskyEmbedRecord.View,
+  opts: ModerationOpts,
+): ModerationDecision {
+  if (AppBskyEmbedRecord.isViewRecord(subject.record)) {
+    return decideAccount(subject.record.author, opts)
+  }
+  return ModerationDecision.noop()
+}
+
+export function decideQuotedPostWithMedia(
+  subject: AppBskyEmbedRecordWithMedia.View,
+  opts: ModerationOpts,
+): ModerationDecision {
+  const acc = new ModerationCauseAccumulator()
+
+  if (AppBskyEmbedRecord.isViewRecord(subject.record.record)) {
+    acc.setDid(subject.record.record.author.did)
+
+    if (subject.record.record.labels?.length) {
+      for (const label of subject.record.record.labels) {
+        acc.addLabel(label, opts)
+      }
+    }
+  }
+
+  return acc.finalizeDecision(opts)
+}
+
+export function decideQuotedPostWithMediaAccount(
+  subject: AppBskyEmbedRecordWithMedia.View,
+  opts: ModerationOpts,
+): ModerationDecision {
+  if (AppBskyEmbedRecord.isViewRecord(subject.record.record)) {
+    return decideAccount(subject.record.record.author, opts)
+  }
+  return ModerationDecision.noop()
+}

package/src/moderation/subjects/user-list.ts

@@ -0,0 +1,13 @@
+import {
+  ModerationSubjectUserList,
+  ModerationOpts,
+  ModerationDecision,
+} from '../types'
+
+export function decideUserList(
+  subject: ModerationSubjectUserList,
+  opts: ModerationOpts,
+): ModerationDecision {
+  // TODO handle labels applied on the list itself
+  return ModerationDecision.noop()
+}

package/src/moderation/types.ts

@@ -0,0 +1,141 @@
+import {
+  AppBskyActorDefs,
+  AppBskyFeedDefs,
+  AppBskyGraphDefs,
+  ComAtprotoLabelDefs,
+} from '../client/index'
+
+// labels
+// =
+
+export type Label = ComAtprotoLabelDefs.Label
+
+export type LabelPreference = 'ignore' | 'warn' | 'hide'
+export type LabelDefinitionFlag = 'no-override' | 'adult'
+export type LabelDefinitionOnWarnBehavior =
+  | 'blur'
+  | 'blur-media'
+  | 'alert'
+  | null
+
+export interface LabelDefinitionLocalizedStrings {
+  name: string
+  description: string
+}
+
+export type LabelDefinitionLocalizedStringsMap = Record<
+  string,
+  LabelDefinitionLocalizedStrings
+>
+
+export interface LabelDefinition {
+  id: string
+  groupId: string
+  configurable: boolean
+  preferences: LabelPreference[]
+  flags: LabelDefinitionFlag[]
+  onwarn: LabelDefinitionOnWarnBehavior
+  strings: {
+    settings: LabelDefinitionLocalizedStringsMap
+    account: LabelDefinitionLocalizedStringsMap
+    content: LabelDefinitionLocalizedStringsMap
+  }
+}
+
+export interface LabelGroupDefinition {
+  id: string
+  configurable: boolean
+  labels: LabelDefinition[]
+  strings: {
+    settings: LabelDefinitionLocalizedStringsMap
+  }
+}
+
+export type LabelDefinitionMap = Record<string, LabelDefinition>
+export type LabelGroupDefinitionMap = Record<string, LabelGroupDefinition>
+
+// labelers
+// =
+
+interface Labeler {
+  did: string
+  displayName: string
+}
+
+export interface LabelerSettings {
+  labeler: Labeler
+  settings: Record<string, LabelPreference>
+}
+
+// subjects
+// =
+
+export type ModerationSubjectProfile =
+  | AppBskyActorDefs.ProfileViewBasic
+  | AppBskyActorDefs.ProfileView
+  | AppBskyActorDefs.ProfileViewDetailed
+
+export type ModerationSubjectPost = AppBskyFeedDefs.PostView
+
+export type ModerationSubjectFeedGenerator = AppBskyFeedDefs.GeneratorView
+
+export type ModerationSubjectUserList =
+  | AppBskyGraphDefs.ListViewBasic
+  | AppBskyGraphDefs.ListView
+
+export type ModerationSubject =
+  | ModerationSubjectProfile
+  | ModerationSubjectPost
+  | ModerationSubjectFeedGenerator
+  | ModerationSubjectUserList
+
+// behaviors
+// =
+
+export type ModerationCauseSource =
+  | { type: 'user' }
+  | { type: 'list'; list: AppBskyGraphDefs.ListViewBasic }
+
+export type ModerationCause =
+  | { type: 'blocking'; source: ModerationCauseSource; priority: 3 }
+  | { type: 'blocked-by'; source: ModerationCauseSource; priority: 4 }
+  | {
+      type: 'label'
+      labeler: Labeler
+      label: Label
+      labelDef: LabelDefinition
+      setting: LabelPreference
+      priority: 1 | 2 | 5 | 7 | 8
+    }
+  | { type: 'muted'; source: ModerationCauseSource; priority: 6 }
+
+export interface ModerationOpts {
+  userDid: string
+  adultContentEnabled: boolean
+  labelerSettings: LabelerSettings[]
+}
+
+export class ModerationDecision {
+  static noop() {
+    return new ModerationDecision()
+  }
+
+  constructor(
+    public cause: ModerationCause | undefined = undefined,
+    public alert: boolean = false,
+    public blur: boolean = false,
+    public blurMedia: boolean = false,
+    public filter: boolean = false,
+    public noOverride: boolean = false,
+    public additionalCauses: ModerationCause[] = [],
+    public did: string = '',
+  ) {}
+}
+
+export interface ModerationUI {
+  filter?: boolean
+  blur?: boolean
+  alert?: boolean
+  cause?: ModerationCause
+  noOverride?: boolean
+}