@atproto/api 0.4.3 → 0.5.0

package/scripts/docs/profile-moderation-behaviors.mjs

@@ -0,0 +1,122 @@
+import * as url from 'url'
+import { readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { stripIndents } from 'common-tags'
+
+const __dirname = url.fileURLToPath(new URL('.', import.meta.url))
+
+const profileModerationBehaviorsDef = JSON.parse(
+  readFileSync(
+    join(
+      __dirname,
+      '..',
+      '..',
+      'definitions',
+      'profile-moderation-behaviors.json',
+    ),
+    'utf8',
+  ),
+)
+
+writeFileSync(
+  join(__dirname, '..', '..', 'docs', 'moderation-behaviors', 'profiles.md'),
+  profiles(),
+  'utf8',
+)
+
+function profiles() {
+  let lastTitle = 'NULL'
+  return stripIndents`
+  <!-- this doc is generated by ./scripts/docs/profile-moderation-behaviors.mjs -->
+
+  # Profile moderation behaviors
+  
+  This document is a reference for the expected behaviors for a profile in the application based on some given scenarios. The <code>moderateProfile()</code> command condense down to the following yes or no decisions:
+
+  - <code>res.account.filter</code> Do not show the account in feeds.
+  - <code>res.account.blur</code> Put the account (in listings, when viewing) behind a warning cover.
+  - <code>res.account.noOverride</code> Do not allow the account's blur cover to be lifted.
+  - <code>res.account.alert</code> Add a warning to the account but do not cover it.
+  - <code>res.profile.blur</code> Put the profile details (handle, display name, bio) behind a warning cover.
+  - <code>res.profile.noOverride</code> Do not allow the profile's blur cover to be lifted.
+  - <code>res.profile.alert</code> Add a warning to the profile but do not cover it.
+  - <code>res.avatar.blur</code> Put the avatar behind a cover.
+  - <code>res.avatar.noOverride</code> Do not allow the avatars's blur cover to be lifted.
+  - <code>res.avatar.alert</code> Put a warning icon on the avatar.
+ 
+  Key:
+
+  - ❌ = Filter Content
+  - 🚫 = Blur (no-override)
+  - ✋ = Blur
+  - 🪧 = Alert
+
+  ## Scenarios
+
+  <table>
+    ${Array.from(Object.entries(profileModerationBehaviorsDef.scenarios))
+      .map(([title, scenario], i) => {
+        const str = `
+          ${title.indexOf(lastTitle) === -1 ? postTableHead() : ''}
+          ${scenarioSection(title, scenario)}
+        `
+        lastTitle = title.slice(0, 10)
+        return str
+      })
+      .join('\n\n')}
+  </table>
+  `
+}
+
+function postTableHead() {
+  return `<tr><th>Scenario</th><th>Filter</th><th>Account</th><th>Profile</td><th>Avatar</th></tr>`
+}
+
+function scenarioSection(title, scenario) {
+  return stripIndents`
+  <tr>
+    <td><strong>${title}</strong></td>
+    <td>
+      ${filter(scenario.behaviors.account?.filter)}
+    </td>
+    <td>
+      ${blur(
+        scenario.behaviors.account?.blur,
+        scenario.behaviors.account?.noOverride,
+      )}
+      ${alert(scenario.behaviors.account?.alert)}
+    </td>
+    <td>
+      ${blur(
+        scenario.behaviors.profile?.blur,
+        scenario.behaviors.profile?.noOverride,
+      )}
+      ${alert(scenario.behaviors.profile?.alert)}
+    </td>
+    <td>
+      ${blur(
+        scenario.behaviors.avatar?.blur,
+        scenario.behaviors.avatar?.noOverride,
+      )}
+      ${alert(scenario.behaviors.avatar?.alert)}
+    </td>
+  </tr>
+  `
+}
+
+function filter(val) {
+  return val ? '❌' : ''
+}
+
+function blur(val, noOverride) {
+  if (val) {
+    return noOverride ? '🚫' : '✋'
+  }
+  return ''
+}
+
+function alert(val) {
+  return val ? '🪧' : ''
+}
+
+export {}

package/scripts/generate-code.mjs

@@ -0,0 +1,4 @@
+import './code/labels.mjs'
+import './code/label-groups.mjs'
+
+export {}

package/scripts/generate-docs.mjs

@@ -0,0 +1,5 @@
+import './docs/labels.mjs'
+import './docs/post-moderation-behaviors.mjs'
+import './docs/profile-moderation-behaviors.mjs'
+
+export {}

package/src/client/index.ts

@@ -122,6 +122,7 @@ import * as AppBskyNotificationGetUnreadCount from './types/app/bsky/notificatio
 import * as AppBskyNotificationListNotifications from './types/app/bsky/notification/listNotifications'
 import * as AppBskyNotificationUpdateSeen from './types/app/bsky/notification/updateSeen'
 import * as AppBskyRichtextFacet from './types/app/bsky/richtext/facet'
+import * as AppBskyUnspeccedApplyLabels from './types/app/bsky/unspecced/applyLabels'
 import * as AppBskyUnspeccedGetPopular from './types/app/bsky/unspecced/getPopular'
 import * as AppBskyUnspeccedGetPopularFeedGenerators from './types/app/bsky/unspecced/getPopularFeedGenerators'
 import * as AppBskyUnspeccedGetTimelineSkeleton from './types/app/bsky/unspecced/getTimelineSkeleton'
@@ -241,6 +242,7 @@ export * as AppBskyNotificationGetUnreadCount from './types/app/bsky/notificatio
 export * as AppBskyNotificationListNotifications from './types/app/bsky/notification/listNotifications'
 export * as AppBskyNotificationUpdateSeen from './types/app/bsky/notification/updateSeen'
 export * as AppBskyRichtextFacet from './types/app/bsky/richtext/facet'
+export * as AppBskyUnspeccedApplyLabels from './types/app/bsky/unspecced/applyLabels'
 export * as AppBskyUnspeccedGetPopular from './types/app/bsky/unspecced/getPopular'
 export * as AppBskyUnspeccedGetPopularFeedGenerators from './types/app/bsky/unspecced/getPopularFeedGenerators'
 export * as AppBskyUnspeccedGetTimelineSkeleton from './types/app/bsky/unspecced/getTimelineSkeleton'
@@ -2036,6 +2038,17 @@ export class UnspeccedNS {
     this._service = service
   }
 
+  applyLabels(
+    data?: AppBskyUnspeccedApplyLabels.InputSchema,
+    opts?: AppBskyUnspeccedApplyLabels.CallOptions,
+  ): Promise<AppBskyUnspeccedApplyLabels.Response> {
+    return this._service.xrpc
+      .call('app.bsky.unspecced.applyLabels', opts?.qp, data, opts)
+      .catch((e) => {
+        throw AppBskyUnspeccedApplyLabels.toKnownErr(e)
+      })
+  }
+
   getPopular(
     params?: AppBskyUnspeccedGetPopular.QueryParams,
     opts?: AppBskyUnspeccedGetPopular.CallOptions,

package/src/client/lexicons.ts

@@ -343,6 +343,9 @@ export const schemaDict = {
           invitesDisabled: {
             type: 'boolean',
           },
+          inviteNote: {
+            type: 'string',
+          },
         },
       },
       repoViewDetail: {
@@ -401,6 +404,9 @@ export const schemaDict = {
           invitesDisabled: {
             type: 'boolean',
           },
+          inviteNote: {
+            type: 'string',
+          },
         },
       },
       repoViewNotFound: {
@@ -530,7 +536,6 @@ export const schemaDict = {
       },
       moderation: {
         type: 'object',
-        required: [],
         properties: {
           currentAction: {
             type: 'ref',
@@ -640,6 +645,11 @@ export const schemaDict = {
                 type: 'string',
                 format: 'did',
               },
+              note: {
+                type: 'string',
+                description:
+                  'Additionally add a note describing why the invites were disabled',
+              },
             },
           },
         },
@@ -694,6 +704,11 @@ export const schemaDict = {
                 type: 'string',
                 format: 'did',
               },
+              note: {
+                type: 'string',
+                description:
+                  'Additionally add a note describing why the invites were enabled',
+              },
             },
           },
         },
@@ -1652,7 +1667,7 @@ export const schemaDict = {
       },
       reasonSexual: {
         type: 'token',
-        description: 'Unwanted or mis-labeled sexual content',
+        description: 'Unwanted or mislabeled sexual content',
       },
       reasonRude: {
         type: 'token',
@@ -6278,6 +6293,32 @@ export const schemaDict = {
       },
     },
   },
+  AppBskyUnspeccedApplyLabels: {
+    lexicon: 1,
+    id: 'app.bsky.unspecced.applyLabels',
+    defs: {
+      main: {
+        type: 'procedure',
+        description: 'Allow a labeler to apply labels directly.',
+        input: {
+          encoding: 'application/json',
+          schema: {
+            type: 'object',
+            required: ['labels'],
+            properties: {
+              labels: {
+                type: 'array',
+                items: {
+                  type: 'ref',
+                  ref: 'lex:com.atproto.label.defs#label',
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
   AppBskyUnspeccedGetPopular: {
     lexicon: 1,
     id: 'app.bsky.unspecced.getPopular',
@@ -6545,6 +6586,7 @@ export const ids = {
     'app.bsky.notification.listNotifications',
   AppBskyNotificationUpdateSeen: 'app.bsky.notification.updateSeen',
   AppBskyRichtextFacet: 'app.bsky.richtext.facet',
+  AppBskyUnspeccedApplyLabels: 'app.bsky.unspecced.applyLabels',
   AppBskyUnspeccedGetPopular: 'app.bsky.unspecced.getPopular',
   AppBskyUnspeccedGetPopularFeedGenerators:
     'app.bsky.unspecced.getPopularFeedGenerators',

package/src/client/types/app/bsky/unspecced/applyLabels.ts

@@ -0,0 +1,33 @@
+/**
+ * GENERATED CODE - DO NOT MODIFY
+ */
+import { Headers, XRPCError } from '@atproto/xrpc'
+import { ValidationResult, BlobRef } from '@atproto/lexicon'
+import { isObj, hasProp } from '../../../../util'
+import { lexicons } from '../../../../lexicons'
+import { CID } from 'multiformats/cid'
+import * as ComAtprotoLabelDefs from '../../../com/atproto/label/defs'
+
+export interface QueryParams {}
+
+export interface InputSchema {
+  labels: ComAtprotoLabelDefs.Label[]
+  [k: string]: unknown
+}
+
+export interface CallOptions {
+  headers?: Headers
+  qp?: QueryParams
+  encoding: 'application/json'
+}
+
+export interface Response {
+  success: boolean
+  headers: Headers
+}
+
+export function toKnownErr(e: any) {
+  if (e instanceof XRPCError) {
+  }
+  return e
+}

package/src/client/types/com/atproto/admin/defs.ts

@@ -189,6 +189,7 @@ export interface RepoView {
   moderation: Moderation
   invitedBy?: ComAtprotoServerDefs.InviteCode
   invitesDisabled?: boolean
+  inviteNote?: string
   [k: string]: unknown
 }
 
@@ -215,6 +216,7 @@ export interface RepoViewDetail {
   invitedBy?: ComAtprotoServerDefs.InviteCode
   invites?: ComAtprotoServerDefs.InviteCode[]
   invitesDisabled?: boolean
+  inviteNote?: string
   [k: string]: unknown
 }
 

package/src/client/types/com/atproto/admin/disableAccountInvites.ts

@@ -11,6 +11,8 @@ export interface QueryParams {}
 
 export interface InputSchema {
   account: string
+  /** Additionally add a note describing why the invites were disabled */
+  note?: string
   [k: string]: unknown
 }
 

package/src/client/types/com/atproto/admin/enableAccountInvites.ts

@@ -11,6 +11,8 @@ export interface QueryParams {}
 
 export interface InputSchema {
   account: string
+  /** Additionally add a note describing why the invites were enabled */
+  note?: string
   [k: string]: unknown
 }
 

package/src/client/types/com/atproto/moderation/defs.ts

@@ -21,7 +21,7 @@ export const REASONSPAM = 'com.atproto.moderation.defs#reasonSpam'
 export const REASONVIOLATION = 'com.atproto.moderation.defs#reasonViolation'
 /** Misleading identity, affiliation, or content */
 export const REASONMISLEADING = 'com.atproto.moderation.defs#reasonMisleading'
-/** Unwanted or mis-labeled sexual content */
+/** Unwanted or mislabeled sexual content */
 export const REASONSEXUAL = 'com.atproto.moderation.defs#reasonSexual'
 /** Rude, harassing, explicit, or otherwise unwelcoming behavior */
 export const REASONRUDE = 'com.atproto.moderation.defs#reasonRude'

package/src/index.ts

@@ -13,5 +13,9 @@ export * from './agent'
 export * from './rich-text/rich-text'
 export * from './rich-text/sanitization'
 export * from './rich-text/unicode'
+export * from './moderation'
+export * from './moderation/types'
+export { LABELS } from './moderation/const/labels'
+export { LABEL_GROUPS } from './moderation/const/label-groups'
 export { BskyAgent } from './bsky-agent'
 export { AtpAgent as default } from './agent'

package/src/moderation/accumulator.ts

@@ -0,0 +1,181 @@
+import { AppBskyGraphDefs } from '../client/index'
+import {
+  Label,
+  LabelPreference,
+  ModerationCause,
+  ModerationOpts,
+  ModerationDecision,
+} from './types'
+import { LABELS } from './const/labels'
+
+export class ModerationCauseAccumulator {
+  did = ''
+  causes: ModerationCause[] = []
+
+  constructor() {}
+
+  setDid(did: string) {
+    this.did = did
+  }
+
+  addBlocking(blocking: string | undefined) {
+    if (blocking) {
+      this.causes.push({
+        type: 'blocking',
+        source: { type: 'user' },
+        priority: 3,
+      })
+    }
+  }
+
+  addBlockedBy(blockedBy: boolean | undefined) {
+    if (blockedBy) {
+      this.causes.push({
+        type: 'blocked-by',
+        source: { type: 'user' },
+        priority: 4,
+      })
+    }
+  }
+
+  addLabel(label: Label, opts: ModerationOpts) {
+    // look up the label definition
+    const labelDef = LABELS[label.val]
+    if (!labelDef) {
+      // ignore labels we don't understand
+      return
+    }
+
+    // look up the label preference
+    // TODO use the find() when 3P labelers support lands
+    // const labelerSettings = opts.labelerSettings.find(
+    //   (s) => s.labeler.did === label.src,
+    // )
+    const labelerSettings = opts.labelerSettings[0]
+    if (!labelerSettings) {
+      // ignore labels from labelers we don't use
+      return
+    }
+
+    // establish the label preference for interpretation
+    let labelPref: LabelPreference = 'ignore'
+    if (!labelDef.configurable) {
+      labelPref = labelDef.preferences[0]
+    } else if (labelDef.flags.includes('adult') && !opts.adultContentEnabled) {
+      labelPref = 'hide'
+    } else if (labelerSettings.settings[label.val]) {
+      labelPref = labelerSettings.settings[label.val]
+    }
+
+    // ignore labels the user has asked to ignore
+    if (labelPref === 'ignore') {
+      return
+    }
+
+    // establish the priority of the label
+    let priority: 1 | 2 | 5 | 7 | 8
+    if (labelDef.flags.includes('no-override')) {
+      priority = 1
+    } else if (labelPref === 'hide') {
+      priority = 2
+    } else if (labelDef.onwarn === 'blur') {
+      priority = 5
+    } else if (labelDef.onwarn === 'blur-media') {
+      priority = 7
+    } else {
+      priority = 8
+    }
+
+    this.causes.push({
+      type: 'label',
+      label,
+      labelDef,
+      labeler: labelerSettings.labeler,
+      setting: labelPref,
+      priority,
+    })
+  }
+
+  addMuted(muted: boolean | undefined) {
+    if (muted) {
+      this.causes.push({
+        type: 'muted',
+        source: { type: 'user' },
+        priority: 6,
+      })
+    }
+  }
+
+  addMutedByList(mutedByList: AppBskyGraphDefs.ListViewBasic | undefined) {
+    if (mutedByList) {
+      this.causes.push({
+        type: 'muted',
+        source: { type: 'list', list: mutedByList },
+        priority: 6,
+      })
+    }
+  }
+
+  finalizeDecision(opts: ModerationOpts): ModerationDecision {
+    const mod = new ModerationDecision()
+    mod.did = this.did
+    if (!this.causes.length) {
+      return mod
+    }
+
+    // sort the causes by priority and then choose the top one
+    this.causes.sort((a, b) => a.priority - b.priority)
+    mod.cause = this.causes[0]
+    mod.additionalCauses = this.causes.slice(1)
+
+    // blocked user
+    if (mod.cause.type === 'blocking' || mod.cause.type === 'blocked-by') {
+      // filter and blur, dont allow override
+      mod.filter = true
+      mod.blur = true
+      mod.noOverride = true
+    }
+    // muted user
+    else if (mod.cause.type === 'muted') {
+      // filter and blur
+      mod.filter = true
+      mod.blur = true
+    }
+    // labeled subject
+    else if (mod.cause.type === 'label') {
+      // 'hide' setting
+      if (mod.cause.setting === 'hide') {
+        // filter
+        mod.filter = true
+      }
+
+      // 'hide' and 'warn' setting, apply onwarn
+      switch (mod.cause.labelDef.onwarn) {
+        case 'alert':
+          mod.alert = true
+          break
+        case 'blur':
+          mod.blur = true
+          break
+        case 'blur-media':
+          mod.blurMedia = true
+          break
+        case null:
+          // do nothing
+          break
+      }
+
+      // apply noOverride as needed
+      if (mod.cause.labelDef.flags.includes('no-override')) {
+        mod.noOverride = true
+      } else if (
+        mod.cause.labelDef.flags.includes('adult') &&
+        !opts.adultContentEnabled
+      ) {
+        mod.noOverride = true
+      }
+    }
+
+    return mod
+  }
+}

package/src/moderation/const/label-groups.ts

@@ -0,0 +1,143 @@
+/** this doc is generated by ./scripts/code/labels.mjs **/
+import { LabelGroupDefinitionMap } from '../types'
+import { LABELS } from './labels'
+
+export const LABEL_GROUPS: LabelGroupDefinitionMap = {
+  system: {
+    id: 'system',
+    configurable: false,
+    labels: [LABELS['!hide'], LABELS['!no-promote'], LABELS['!warn']],
+    strings: {
+      settings: {
+        en: {
+          name: 'System',
+          description: 'Moderator overrides for special cases.',
+        },
+      },
+    },
+  },
+  legal: {
+    id: 'legal',
+    configurable: false,
+    labels: [LABELS['dmca-violation'], LABELS['doxxing']],
+    strings: {
+      settings: {
+        en: {
+          name: 'Legal',
+          description: 'Content removed for legal reasons.',
+        },
+      },
+    },
+  },
+  sexual: {
+    id: 'sexual',
+    configurable: true,
+    labels: [LABELS['porn'], LABELS['sexual'], LABELS['nudity']],
+    strings: {
+      settings: {
+        en: {
+          name: 'Adult Content',
+          description: 'Content which is sexual in nature.',
+        },
+      },
+    },
+  },
+  violence: {
+    id: 'violence',
+    configurable: true,
+    labels: [
+      LABELS['nsfl'],
+      LABELS['corpse'],
+      LABELS['gore'],
+      LABELS['torture'],
+      LABELS['self-harm'],
+    ],
+    strings: {
+      settings: {
+        en: {
+          name: 'Violence',
+          description: 'Content which is violent or deeply disturbing.',
+        },
+      },
+    },
+  },
+  intolerance: {
+    id: 'intolerance',
+    configurable: true,
+    labels: [
+      LABELS['intolerant-race'],
+      LABELS['intolerant-gender'],
+      LABELS['intolerant-sexual-orientation'],
+      LABELS['intolerant-religion'],
+      LABELS['intolerant'],
+      LABELS['icon-intolerant'],
+    ],
+    strings: {
+      settings: {
+        en: {
+          name: 'Intolerance',
+          description:
+            'Content or behavior which is hateful or intolerant toward a group of people.',
+        },
+      },
+    },
+  },
+  rude: {
+    id: 'rude',
+    configurable: true,
+    labels: [LABELS['threat']],
+    strings: {
+      settings: {
+        en: {
+          name: 'Rude',
+          description: 'Behavior which is rude toward other users.',
+        },
+      },
+    },
+  },
+  curation: {
+    id: 'curation',
+    configurable: true,
+    labels: [LABELS['spoiler']],
+    strings: {
+      settings: {
+        en: {
+          name: 'Curational',
+          description:
+            'Subjective moderation geared towards curating a more positive environment.',
+        },
+      },
+    },
+  },
+  spam: {
+    id: 'spam',
+    configurable: true,
+    labels: [LABELS['spam']],
+    strings: {
+      settings: {
+        en: {
+          name: 'Spam',
+          description: "Content which doesn't add to the conversation.",
+        },
+      },
+    },
+  },
+  misinfo: {
+    id: 'misinfo',
+    configurable: true,
+    labels: [
+      LABELS['account-security'],
+      LABELS['net-abuse'],
+      LABELS['impersonation'],
+      LABELS['scam'],
+    ],
+    strings: {
+      settings: {
+        en: {
+          name: 'Misinformation',
+          description: 'Content which misleads or defrauds users.',
+        },
+      },
+    },
+  },
+}