@atproto/api 0.11.0-next.0 → 0.11.0

package/docs/moderation.md

@@ -2,17 +2,11 @@
 
 Applying the moderation system is a challenging task, but we've done our best to simplify it for you. The Moderation API helps handle a wide range of tasks, including:
 
+- Moderator labeling
 - User muting (including mutelists)
 - User blocking
-- Moderator labeling
-
-For more information, see the [Moderation Documentation](./docs/moderation.md) or the associated [Labels Reference](./docs/labels.md).
-
-Additional docs:
-
-- [Labels Reference](./labels.md)
-- [Post Moderation Behaviors](./moderation-behaviors/posts.md)
-- [Profile Moderation Behaviors](./moderation-behaviors/profiles.md)
+- Mutewords
+- Hidden posts
 
 ## Configuration
 
@@ -23,131 +17,244 @@ Every moderation function takes a set of options which look like this:
   // the logged-in user's DID
   userDid: 'did:plc:1234...',
 
-  // is adult content allowed?
-  adultContentEnabled: true,
+  moderationPrefs: {
+    // is adult content allowed?
+    adultContentEnabled: true,
 
-  // the global label settings (used on self-labels)
-  labels: {
-    porn: 'hide',
-    sexual: 'warn',
-    nudity: 'ignore',
-    // ...
-  },
+    // the global label settings (used on self-labels)
+    labels: {
+      porn: 'hide',
+      sexual: 'warn',
+      nudity: 'ignore',
+      // ...
+    },
 
-  // the per-labeler settings
-  labelers: [
-    {
-      labeler: {
-        did: '...',
-        displayName: 'My mod service'
-      },
-      labels: {
-        porn: 'hide',
-        sexual: 'warn',
-        nudity: 'ignore',
-        // ...
+    // the subscribed labelers and their label settings
+    labelers: [
+      {
+        did: 'did:plc:1234...',
+        labels: {
+          porn: 'hide',
+          sexual: 'warn',
+          nudity: 'ignore',
+          // ...
+        }
       }
-    }
-  ]
+    ],
+
+    mutedWords: [/* ... */],
+    hiddenPosts: [/* ... */]
+  },
+
+  // custom label definitions
+  labelDefs: {
+    // labelerDid => defs[]
+    'did:plc:1234...': [
+      /* ... */
+    ]
+  }
 }
 ```
 
 This should match the following interfaces:
 
 ```typescript
-interface ModerationOpts {
-  userDid: string
+export interface ModerationPrefsLabeler {
+  did: string
+  labels: Record<string, LabelPreference>
+}
+
+export interface ModerationPrefs {
   adultContentEnabled: boolean
   labels: Record<string, LabelPreference>
-  labelers: LabelerSettings[]
+  labelers: ModerationPrefsLabeler[]
+  mutedWords: AppBskyActorDefs.MutedWord[]
+  hiddenPosts: string[]
 }
 
-interface Labeler {
-  did: string
-  displayName: string
+export interface ModerationOpts {
+  userDid: string | undefined
+  prefs: ModerationPrefs
+  /**
+   * Map of labeler did -> custom definitions
+   */
+  labelDefs?: Record<string, InterpretedLabelValueDefinition[]>
 }
+```
 
-type LabelPreference = 'ignore' | 'warn' | 'hide'
+You can quickly grab the `ModerationPrefs` using the `agent.getPreferences()` method:
 
-interface LabelerSettings {
-  labeler: Labeler
-  labels: Record<string, LabelPreference>
-}
+```typescript
+const prefs = await agent.getPreferences()
+moderatePost(post, {
+  userDid: /*...*/,
+  prefs: prefs.moderationPrefs,
+  labelDefs: /*...*/
+})
 ```
 
-## Posts
+To gather the label definitions (`labelDefs`) see the _Labelers_ section below.
 
-Applications need to produce the [Post Moderation Behaviors](./moderation-behaviors/posts.md) using the `moderatePost()` API.
+## Labelers
+
+Labelers are services that provide moderation labels. Your application will typically have 1+ top-level labelers set with the ability to do "takedowns" on content. This is controlled via this static function, though the default is to use Bluesky's moderation:
 
 ```typescript
-import { moderatePost } from '@atproto/api'
+BskyAgent.configure({
+  appLabelers: ['did:web:my-labeler.com'],
+})
+```
 
-const postMod = moderatePost(postView, getOpts())
+Users may also add their own labelers. The active labelers are controlled via an HTTP header which is automatically set by the agent when `getPreferences` is called, or when the labeler preferences are changed.
 
-if (postMod.content.filter) {
-  // don't render in feeds or similar
-  // in contexts where this is disruptive (eg threads) you should ignore this and instead check blur
-}
-if (postMod.content.blur) {
-  // render the whole object behind a cover (use postMod.content.cause to explain)
-  if (postMod.content.noOverride) {
-    // do not allow the cover the be removed
-  }
-}
-if (postMod.content.alert) {
-  // render a warning on the content (use postMod.content.cause to explain)
-}
-if (postMod.embed.blur) {
-  // render the embedded media behind a cover (use postMod.embed.cause to explain)
-  if (postMod.embed.noOverride) {
-    // do not allow the cover the be removed
-  }
-}
-if (postMod.embed.alert) {
-  // render a warning on the embedded media (use postMod.embed.cause to explain)
-}
-if (postMod.avatar.blur) {
-  // render the avatar behind a cover
-}
-if (postMod.avatar.alert) {
-  // render an alert on the avatar
+Labelers publish a `app.bsky.labeler.service` record that looks like this:
+
+```js
+{
+  $type: 'app.bsky.labeler.service',
+  policies: {
+    // the list of label values the labeler will publish
+    labelValues: [
+      'rude',
+    ],
+    // any custom definitions the labeler will be using
+    labelValueDefinitions: [
+      {
+        identifier: 'rude',
+        blurs: 'content',
+        severity: 'alert',
+        defaultSetting: 'warn',
+        adultOnly: false,
+        locales: [
+          {
+            lang: 'en',
+            name: 'Rude',
+            description: 'Not keeping things civil.',
+          },
+        ],
+      },
+    ],
+  },
+  createdAt: '2024-03-12T17:17:17.215Z'
 }
 ```
 
-## Profiles
+The label value definition are custom labels which only apply to that labeler. Your client needs to sync those definitions in order to correctly interpret them. To do that, call `app.bsky.labeler.getService()` (or the `getServices` batch variant) periodically to fetch their definitions. We recommend caching the response (at time our writing the official client uses a TTL of 6 hours).
+
+Here is how to do this:
+
+```typescript
+import { BskyAgent } from '@atproto/api'
+
+const agent = new BskyAgent()
+// assume `agent` is a signed in session
+const prefs = await agent.getPreferences()
+const labelDefs = await agent.getLabelDefinitions(prefs)
+
+moderatePost(post, {
+  userDid: agent.session.did,
+  prefs: prefs.moderationPrefs,
+  labelDefs,
+})
+```
+
+## The `moderate*()` APIs
+
+The SDK exports methods to moderate the different kinds of content on the network.
+
+```typescript
+import {
+  moderateProfile,
+  moderatePost,
+  moderateNotification,
+  moderateFeedGen,
+  moderateUserList,
+  moderateLabeler,
+} from '@atproto/api'
+```
+
+Each of these follows the same API signature:
+
+```typescript
+const res = moderatePost(post, moderationOptions)
+```
 
-Applications need to produce the [Profile Moderation Behaviors](./moderation-behaviors/profiles.md) using the `moderateProfile()` API.
+The response object provides an API for figuring out what your UI should do in different contexts.
 
 ```typescript
-import { moderateProfile } from '@atproto/api'
+res.ui(context) /* => 
 
-const profileMod = moderateProfile(profileView, getOpts())
+ModerationUI {
+  filter: boolean // should the content be removed from the interface?
+  blur: boolean // should the content be put behind a cover?
+  alert: boolean // should an alert be put on the content? (negative)
+  inform: boolean // should an informational notice be put on the content? (neutral)
+  noOverride: boolean // if blur=true, should the UI disable opening the cover?
 
-if (profileMod.account.filter) {
-  // don't render in discovery
+  // the reasons for each of the flags:
+  filters: ModerationCause[]
+  blurs: ModerationCause[]
+  alerts: ModerationCause[]
+  informs: ModerationCause[]
 }
-if (profileMod.account.blur) {
-  // render the whole account behind a cover (use profileMod.account.cause to explain)
-  if (profileMod.account.noOverride) {
-    // do not allow the cover the be removed
-  }
+*/
+```
+
+There are multiple UI contexts available:
+
+- `profileList` A profile being listed, eg in search or a follower list
+- `profileView` A profile being viewed directly
+- `avatar` The user's avatar in any context
+- `banner` The user's banner in any context
+- `displayName` The user's display name in any context
+- `contentList` Content being listed, eg posts in a feed, posts as replies, a user list list, a feed generator list, etc
+- `contentView` Content being viewed direct, eg an opened post, the user list page, the feedgen page, etc
+- `contentMedia ` Media inside the content, eg a picture embedded in a post
+
+Here's how a post in a feed would use these tools to make a decision:
+
+```typescript
+const mod = moderatePost(post, moderationOptions)
+
+if (mod.ui('contentList').filter) {
+  // dont show the post
 }
-if (profileMod.account.alert) {
-  // render a warning on the account (use profileMod.account.cause to explain)
+if (mod.ui('contentList').blur) {
+  // cover the post with the explanation from mod.ui('contentList').blurs[0]
+  if (mod.ui('contentList').noOverride) {
+    // dont allow the cover to be removed
+  }
 }
-if (profileMod.profile.blur) {
-  // render the profile information (display name, bio) behind a cover
-  if (profileMod.profile.noOverride) {
-    // do not allow the cover the be removed
+if (mod.ui('contentMedia').blur) {
+  // cover the post's embbedded images with the explanation from mod.ui('contentMedia').blurs[0]
+  if (mod.ui('contentMedia').noOverride) {
+    // dont allow the cover to be removed
   }
 }
-if (profileMod.profile.alert) {
-  // render a warning on the profile (use profileMod.profile.cause to explain)
+if (mod.ui('avatar').blur) {
+  // cover the avatar with the explanation from mod.ui('avatar').blurs[0]
+  if (mod.ui('avatar').noOverride) {
+    // dont allow the cover to be removed
+  }
 }
-if (profileMod.avatar.blur) {
-  // render the avatar behind a cover
+for (const alert of mod.ui('contentList').alerts) {
+  // render this alert
 }
-if (profileMod.avatar.alert) {
-  // render an alert on the avatar
+for (const inform of mod.ui('contentList').informs) {
+  // render this inform
 }
 ```
+
+## Sending moderation reports
+
+Any Labeler is capable of receiving moderation reports. As a result, you need to specify which labeler should receive the report. You do this with the `Atproto-Proxy` header:
+
+```typescript
+agent
+  .withProxy('atproto_labeler', 'did:web:my-labeler.com')
+  .createModerationReport({
+    reasonType: 'com.atproto.moderation.defs#reasonViolation',
+    reason: 'They were being such a jerk to me!',
+    subject: { did: 'did:web:bob.com' },
+  })
+```

package/jest.bench.config.js

@@ -0,0 +1,8 @@
+const base = require('./jest.config')
+
+module.exports = {
+  ...base,
+  roots: ['<rootDir>/bench'],
+  testRegex: '(.*.bench.ts)',
+  testTimeout: 3000000,
+}

package/jest.config.js

@@ -1,9 +1,6 @@
-/** @type {import('jest').Config} */
+const base = require('../../jest.config.base.js')
+
 module.exports = {
+  ...base,
   displayName: 'API',
-  transform: { '^.+\\.(t|j)s$': '@swc/jest' },
-  transformIgnorePatterns: [`<rootDir>/node_modules/(?!get-port)`],
-  testTimeout: 60000,
-  setupFiles: ['<rootDir>/../../jest.setup.ts'],
-  setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/api",
-  "version": "0.11.0-next.0",
+  "version": "0.11.0",
   "license": "MIT",
   "description": "Client library for atproto and Bluesky",
   "keywords": [
@@ -15,26 +15,30 @@
     "directory": "packages/api"
   },
   "main": "dist/index.js",
-  "types": "dist/index.d.ts",
   "dependencies": {
     "multiformats": "^9.9.0",
     "tlds": "^1.234.0",
     "typed-emitter": "^2.1.0",
     "zod": "^3.21.4",
-    "@atproto/common-web": "^0.2.3",
-    "@atproto/lexicon": "^0.3.1",
-    "@atproto/syntax": "^0.1.5",
-    "@atproto/xrpc": "^0.4.1"
+    "@atproto/common-web": "^0.2.4",
+    "@atproto/lexicon": "^0.3.3",
+    "@atproto/syntax": "^0.2.1",
+    "@atproto/xrpc": "^0.4.3"
   },
   "devDependencies": {
     "common-tags": "^1.8.2",
-    "jest": "^28.1.2",
-    "@atproto/lex-cli": "^0.3.0"
+    "get-port": "^6.1.2",
+    "@atproto/lex-cli": "^0.3.2",
+    "@atproto/dev-env": "^0.2.38"
   },
   "scripts": {
-    "codegen": "pnpm docgen && node ./scripts/generate-code.mjs && lex gen-api ./src/client ../../lexicons/com/atproto/*/* ../../lexicons/app/bsky/*/*",
-    "docgen": "node ./scripts/generate-docs.mjs",
-    "build": "tsc --build tsconfig.build.json",
-    "test": "jest"
-  }
+    "codegen": "node ./scripts/generate-code.mjs && lex gen-api ./src/client ../../lexicons/com/atproto/*/* ../../lexicons/app/bsky/*/* ../../lexicons/tools/ozone/*/*",
+    "build": "node ./build.js",
+    "postbuild": "tsc --build tsconfig.build.json",
+    "update-main-to-dist": "node ../../update-main-to-dist.js packages/api",
+    "test": "jest",
+    "bench": "jest --config jest.bench.config.js",
+    "bench:profile": "node --inspect-brk ../../node_modules/.bin/jest --config jest.bench.config.js"
+  },
+  "types": "dist/index.d.ts"
 }

package/scripts/code/labels.mjs

@@ -11,12 +11,6 @@ const labelsDef = JSON.parse(
     'utf8',
   ),
 )
-const labelsEn = JSON.parse(
-  readFileSync(
-    join(__dirname, '..', '..', 'definitions', 'locale', 'en', 'labels.json'),
-    'utf8',
-  ),
-)
 
 writeFileSync(
   join(__dirname, '..', '..', 'src', 'moderation', 'const', 'labels.ts'),
@@ -27,10 +21,24 @@ writeFileSync(
 async function gen() {
   return prettier.format(
     `/** this doc is generated by ./scripts/code/labels.mjs **/
-  import {LabelDefinitionMap} from '../types'
+  import {InterpretedLabelValueDefinition, LabelPreference} from '../types'
+
+  export type KnownLabelValue = ${labelsDef
+    .map((label) => `"${label.identifier}"`)
+    .join(' | ')}
+
+  export const DEFAULT_LABEL_SETTINGS: Record<string, LabelPreference> = ${JSON.stringify(
+    Object.fromEntries(
+      labelsDef
+        .filter((label) => label.configurable)
+        .map((label) => [label.identifier, label.defaultSetting]),
+    ),
+  )}
 
-  export const LABELS: LabelDefinitionMap = ${JSON.stringify(
-    genDefMap(),
+  export const LABELS: Record<KnownLabelValue, InterpretedLabelValueDefinition> = ${JSON.stringify(
+    Object.fromEntries(
+      labelsDef.map((label) => [label.identifier, { ...label, locales: [] }]),
+    ),
     null,
     2,
   )}
@@ -39,30 +47,4 @@ async function gen() {
   )
 }
 
-function genDefMap() {
-  const labels = {}
-  for (const group of labelsDef) {
-    for (const label of group.labels) {
-      labels[label.id] = {
-        ...label,
-        groupId: group.id,
-        configurable: group.configurable,
-        strings: {
-          settings: getLabelStrings(label.id, 'settings'),
-          account: getLabelStrings(label.id, 'account'),
-          content: getLabelStrings(label.id, 'content'),
-        },
-      }
-    }
-  }
-  return labels
-}
-
-function getLabelStrings(id, type) {
-  if (labelsEn[id] && labelsEn[id][type]) {
-    return { en: labelsEn[id][type] }
-  }
-  throw new Error('Label strings not found for ' + id)
-}
-
 export {}

package/scripts/generate-code.mjs

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

package/src/agent.ts

@@ -17,8 +17,12 @@ import {
   AtpAgentGlobalOpts,
   AtpPersistSessionHandler,
   AtpAgentOpts,
+  AtprotoServiceType,
 } from './types'
+import { BSKY_LABELER_DID } from './const'
 
+const MAX_MOD_AUTHORITIES = 3
+const MAX_LABELERS = 10
 const REFRESH_SESSION = 'com.atproto.server.refreshSession'
 
 /**
@@ -29,15 +33,13 @@ export class AtpAgent {
   service: URL
   api: AtpServiceClient
   session?: AtpSessionData
+  labelersHeader: string[] = []
+  proxyHeader: string | undefined
+  pdsUrl: URL | undefined // The PDS URL, driven by the did doc. May be undefined.
 
-  /**
-   * The PDS URL, driven by the did doc. May be undefined.
-   */
-  pdsUrl: URL | undefined
-
-  private _baseClient: AtpBaseClient
-  private _persistSession?: AtpPersistSessionHandler
-  private _refreshSessionPromise: Promise<void> | undefined
+  protected _baseClient: AtpBaseClient
+  protected _persistSession?: AtpPersistSessionHandler
+  protected _refreshSessionPromise: Promise<void> | undefined
 
   get com() {
     return this.api.com
@@ -48,11 +50,21 @@ export class AtpAgent {
    */
   static fetch: AtpAgentFetchHandler | undefined = defaultFetchHandler
 
+  /**
+   * The labelers to be used across all requests with the takedown capability
+   */
+  static appLabelers: string[] = [BSKY_LABELER_DID]
+
   /**
    * Configures the API globally.
    */
   static configure(opts: AtpAgentGlobalOpts) {
-    AtpAgent.fetch = opts.fetch
+    if (opts.fetch) {
+      AtpAgent.fetch = opts.fetch
+    }
+    if (opts.appLabelers) {
+      AtpAgent.appLabelers = opts.appLabelers
+    }
   }
 
   constructor(opts: AtpAgentOpts) {
@@ -66,6 +78,27 @@ export class AtpAgent {
     this.api = this._baseClient.service(opts.service)
   }
 
+  clone() {
+    const inst = new AtpAgent({
+      service: this.service,
+    })
+    this.copyInto(inst)
+    return inst
+  }
+
+  copyInto(inst: AtpAgent) {
+    inst.session = this.session
+    inst.labelersHeader = this.labelersHeader
+    inst.proxyHeader = this.proxyHeader
+    inst.pdsUrl = this.pdsUrl
+  }
+
+  withProxy(serviceType: AtprotoServiceType, did: string) {
+    const inst = this.clone()
+    inst.configureProxyHeader(serviceType, did)
+    return inst
+  }
+
   /**
    * Is there any active session?
    */
@@ -81,6 +114,24 @@ export class AtpAgent {
     this._persistSession = handler
   }
 
+  /**
+   * Configures the moderation services to be applied on requests.
+   * NOTE: this is called automatically by getPreferences() and the relevant moderation config
+   * methods in BskyAgent instances.
+   */
+  configureLabelersHeader(labelerDids: string[]) {
+    this.labelersHeader = labelerDids
+  }
+
+  /**
+   * Configures the atproto-proxy header to be applied on requests
+   */
+  configureProxyHeader(serviceType: AtprotoServiceType, did: string) {
+    if (did.startsWith('did:')) {
+      this.proxyHeader = `${did}#${serviceType}`
+    }
+  }
+
   /**
    * Create a new account and hydrate its session in this agent.
    */
@@ -194,13 +245,27 @@ export class AtpAgent {
   /**
    * Internal helper to add authorization headers to requests.
    */
-  private _addAuthHeader(reqHeaders: Record<string, string>) {
+  private _addHeaders(reqHeaders: Record<string, string>) {
     if (!reqHeaders.authorization && this.session?.accessJwt) {
-      return {
+      reqHeaders = {
         ...reqHeaders,
         authorization: `Bearer ${this.session.accessJwt}`,
       }
     }
+    if (this.proxyHeader) {
+      reqHeaders = {
+        ...reqHeaders,
+        'atproto-proxy': this.proxyHeader,
+      }
+    }
+    reqHeaders = {
+      ...reqHeaders,
+      'atproto-accept-labelers': AtpAgent.appLabelers
+        .map((str) => `${str};redact`)
+        .concat(this.labelersHeader.filter((str) => str.startsWith('did:')))
+        .slice(0, MAX_LABELERS)
+        .join(', '),
+    }
     return reqHeaders
   }
 
@@ -224,7 +289,7 @@ export class AtpAgent {
     let res = await AtpAgent.fetch(
       reqUri,
       reqMethod,
-      this._addAuthHeader(reqHeaders),
+      this._addHeaders(reqHeaders),
       reqBody,
     )
 
@@ -237,7 +302,7 @@ export class AtpAgent {
       res = await AtpAgent.fetch(
         reqUri,
         reqMethod,
-        this._addAuthHeader(reqHeaders),
+        this._addHeaders(reqHeaders),
         reqBody,
       )
     }