@atproto/api 0.4.3 → 0.5.0

package/docs/moderation.md

@@ -0,0 +1,144 @@
+# Moderation API
+
+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:
+
+- 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)
+
+## Configuration
+
+Every moderation function takes a set of options which look like this:
+
+```typescript
+{
+  // the logged-in user's DID
+  userDid: 'did:plc:1234...',
+
+  // is adult content allowed?
+  adultContentEnabled: true,
+
+  // the user's labeler settings
+  labelerSettings: [
+    {
+      labeler: {
+        did: '...',
+        displayName: 'My mod service'
+      },
+      settings: {
+        porn: 'hide',
+        sexual: 'warn',
+        nudity: 'ignore',
+        // ...
+      }
+    }
+  ]
+}
+```
+
+This should match the following interfaces:
+
+```typescript
+interface ModerationOpts {
+  userDid: string
+  adultContentEnabled: boolean
+  labelerSettings: LabelerSettings[]
+}
+
+interface Labeler {
+  did: string
+  displayName: string
+}
+
+type LabelPreference = 'ignore' | 'warn' | 'hide'
+
+interface LabelerSettings {
+  labeler: Labeler
+  settings: Record<string, LabelPreference>
+}
+```
+
+## Posts
+
+Applications need to produce the [Post Moderation Behaviors](./moderation-behaviors/posts.md) using the `moderatePost()` API.
+
+```typescript
+import {moderatePost} from '@atproto/api'
+
+const postMod = moderatePost(postView, getOpts())
+
+if (postMod.content.filter) {
+  // dont 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
+}
+```
+
+## Profiles
+
+Applications need to produce the [Profile Moderation Behaviors](./moderation-behaviors/profiles.md) using the `moderateProfile()` API.
+
+```typescript
+import {moderateProfile} from '@atproto/api'
+
+const profileMod = moderateProfile(profileView, getOpts())
+
+if (profileMod.acount.filter) {
+  // dont render in discovery
+}
+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
+  }
+}
+if (profileMod.account.alert) {
+  // render a warning on the account (use profileMod.account.cause to explain)
+}
+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 (profileMod.profile.alert) {
+  // render a warning on the profile (use profileMod.profile.cause to explain)
+}
+if (profileMod.avatar.blur) {
+  // render the avatar behind a cover
+}
+if (profileMod.avatar.alert) {
+  // render an alert on the avatar
+}
+```

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@atproto/api",
-  "version": "0.4.3",
-  "main": "dist/index.js",
+  "version": "0.5.0",
+  "main": "src/index.ts",
   "scripts": {
-    "codegen": "lex gen-api ./src/client ../../lexicons/com/atproto/*/* ../../lexicons/app/bsky/*/*",
+    "codegen": "yarn docgen && node ./scripts/generate-code.mjs && lex gen-api ./src/client ../../lexicons/com/atproto/*/* ../../lexicons/app/bsky/*/*",
+    "docgen": "node ./scripts/generate-docs.mjs",
     "build": "node ./build.js",
     "postbuild": "tsc --build tsconfig.build.json",
     "update-main-to-dist": "node ./update-pkg.js --update-main-to-dist",
@@ -29,6 +30,7 @@
   },
   "devDependencies": {
     "@atproto/lex-cli": "*",
-    "@atproto/pds": "*"
+    "@atproto/pds": "*",
+    "common-tags": "^1.8.2"
   }
 }

package/scripts/code/label-groups.mjs

@@ -0,0 +1,68 @@
+import * as url from 'url'
+import { readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import * as prettier from 'prettier'
+
+const __dirname = url.fileURLToPath(new URL('.', import.meta.url))
+
+const labelsDef = JSON.parse(
+  readFileSync(
+    join(__dirname, '..', '..', 'definitions', 'labels.json'),
+    'utf8',
+  ),
+)
+const labelGroupsEn = JSON.parse(
+  readFileSync(
+    join(
+      __dirname,
+      '..',
+      '..',
+      'definitions',
+      'locale',
+      'en',
+      'label-groups.json',
+    ),
+    'utf8',
+  ),
+)
+
+writeFileSync(
+  join(__dirname, '..', '..', 'src', 'moderation', 'const', 'label-groups.ts'),
+  await gen(),
+  'utf8',
+)
+
+async function gen() {
+  return prettier.format(
+    `/** this doc is generated by ./scripts/code/labels.mjs **/
+  import {LabelGroupDefinitionMap} from '../types'
+  import {LABELS} from './labels'
+
+  export const LABEL_GROUPS: LabelGroupDefinitionMap = {
+    ${genDefMap()}
+  }
+  `,
+    { semi: false, parser: 'babel', singleQuote: true },
+  )
+}
+
+function genDefMap() {
+  const lines = []
+  for (const group of labelsDef) {
+    lines.push(`"${group.id}": {`)
+    lines.push(`  id: "${group.id}",`)
+    lines.push(`  configurable: ${group.configurable ? true : false},`)
+    lines.push(
+      `  labels: [${group.labels
+        .map((label) => `LABELS["${label.id}"]`)
+        .join(', ')}],`,
+    )
+    lines.push(
+      `  strings: {settings: {en: ${JSON.stringify(labelGroupsEn[group.id])}}}`,
+    )
+    lines.push(`},`)
+  }
+  return lines.join('\n')
+}
+
+export {}

package/scripts/code/labels.mjs

@@ -0,0 +1,68 @@
+import * as url from 'url'
+import { readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import * as prettier from 'prettier'
+
+const __dirname = url.fileURLToPath(new URL('.', import.meta.url))
+
+const labelsDef = JSON.parse(
+  readFileSync(
+    join(__dirname, '..', '..', 'definitions', 'labels.json'),
+    'utf8',
+  ),
+)
+const labelsEn = JSON.parse(
+  readFileSync(
+    join(__dirname, '..', '..', 'definitions', 'locale', 'en', 'labels.json'),
+    'utf8',
+  ),
+)
+
+writeFileSync(
+  join(__dirname, '..', '..', 'src', 'moderation', 'const', 'labels.ts'),
+  await gen(),
+  'utf8',
+)
+
+async function gen() {
+  return prettier.format(
+    `/** this doc is generated by ./scripts/code/labels.mjs **/
+  import {LabelDefinitionMap} from '../types'
+
+  export const LABELS: LabelDefinitionMap = ${JSON.stringify(
+    genDefMap(),
+    null,
+    2,
+  )}
+  `,
+    { semi: false, parser: 'babel', singleQuote: true },
+  )
+}
+
+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/docs/labels.mjs

@@ -0,0 +1,164 @@
+import * as url from 'url'
+import { readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { stripIndent } from 'common-tags'
+
+const __dirname = url.fileURLToPath(new URL('.', import.meta.url))
+
+const labelsDef = JSON.parse(
+  readFileSync(
+    join(__dirname, '..', '..', 'definitions', 'labels.json'),
+    'utf8',
+  ),
+)
+const labelGroupsEn = JSON.parse(
+  readFileSync(
+    join(
+      __dirname,
+      '..',
+      '..',
+      'definitions',
+      'locale',
+      'en',
+      'label-groups.json',
+    ),
+    'utf8',
+  ),
+)
+const labelsEn = JSON.parse(
+  readFileSync(
+    join(__dirname, '..', '..', 'definitions', 'locale', 'en', 'labels.json'),
+    'utf8',
+  ),
+)
+
+writeFileSync(join(__dirname, '..', '..', 'docs', 'labels.md'), doc(), 'utf8')
+
+function doc() {
+  return stripIndent`
+  <!-- this doc is generated by ./scripts/docs/labels.mjs -->
+
+  # Labels
+  
+  This document is a reference for the labels used in the SDK.
+
+  **⚠️ Note**: These labels are still in development and may change over time. Not all are currently in use.
+
+  ## Key
+
+  ### Label Preferences
+
+  The possible client interpretations for a label.
+
+  - <code>ignore</code> Do nothing with the label.
+  - <code>warn</code> Provide some form of warning on the content (see "On Warn" behavior).
+  - <code>hide</code> Remove the content from feeds and apply the warning when directly viewed.
+
+  Each label specifies which preferences it can support. If a label is not configurable, it must have only own supported preference.
+
+  ### Configurable?
+
+  Non-configurable labels cannot have their preference changed by the user.
+
+  ### Flags
+
+  Additional behaviors which a label can adopt.
+
+  - <code>no-override</code> The user cannot click through any covering of content created by the label.
+  - <code>adult</code> The user must have adult content enabled to configure the label. If adult content is not enabled, the label must adopt the strictest preference.
+
+  ### On Warn
+
+  The kind of UI behavior used when a warning must be applied.
+
+  - <code>blur</code> Hide all of the content behind an interstitial.
+  - <code>blur-media</code> Hide only the media within the content (ie images) behind an interstitial.
+  - <code>alert</code> Display a descriptive warning but do not hide the content.
+  - <code>null</code> Do nothing.
+
+  ## Label Behaviors
+
+  <table>
+    <tr>
+      <th>ID</th>
+      <th>Group</th>
+      <th>Preferences</th>
+      <th>Configurable</th>
+      <th>Flags</th>
+      <th>On Warn</th>
+    </tr>
+    ${labelsRef()}
+  </table>
+
+  ## Label Group Descriptions
+
+  <table>
+    <tr>
+      <th>ID</th>
+      <th>Description</th>
+    </tr>
+    ${labelGroupsDesc()}
+  </table>
+
+  ## Label Descriptions
+
+  <table>
+    <tr>
+      <th>ID</th>
+      <th>Description</th>
+    </tr>
+    ${labelsDesc()}
+  </table>
+  `
+}
+
+function labelsRef() {
+  const lines = []
+  for (const group of labelsDef) {
+    for (const label of group.labels) {
+      lines.push(stripIndent`
+        <tr>
+          <td>${label.id}</td>
+          <td>${group.id}</td>
+          <td>${label.preferences.join(', ')}</td>
+          <td>${group.configurable ? '✅' : '❌'}</td>
+          <td>${label.flags.join(', ')}</td>
+          <td>${label.onwarn}</td>
+        </tr>
+      `)
+    }
+  }
+  return lines.join('\n')
+}
+
+function labelGroupsDesc() {
+  const lines = []
+  for (const id in labelGroupsEn) {
+    lines.push(stripIndent`
+      <tr>
+        <td>${id}</td>
+        <td><code>general</code><br><strong>${labelGroupsEn[id].name}</strong><br>${labelGroupsEn[id].description}</td>
+      </tr>
+    `)
+  }
+  return lines.join('\n')
+}
+
+function labelsDesc() {
+  const lines = []
+  for (const id in labelsEn) {
+    lines.push(stripIndent`
+      <tr>
+        <td>${id}</td>
+        <td>
+          <code>general</code><br><strong>${labelsEn[id].settings.name}</strong><br>${labelsEn[id].settings.description}<br><br>
+          <code>on an account</code><br><strong>${labelsEn[id].account.name}</strong><br>${labelsEn[id].account.description}<br><br>
+          <code>on content</code><br><strong>${labelsEn[id].content.name}</strong><br>${labelsEn[id].content.description}<br><br>
+        </td>
+      </tr>
+    `)
+  }
+  return lines.join('\n')
+}
+
+export {}

package/scripts/docs/post-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 postModerationBehaviorsDef = JSON.parse(
+  readFileSync(
+    join(
+      __dirname,
+      '..',
+      '..',
+      'definitions',
+      'post-moderation-behaviors.json',
+    ),
+    'utf8',
+  ),
+)
+
+writeFileSync(
+  join(__dirname, '..', '..', 'docs', 'moderation-behaviors', 'posts.md'),
+  posts(),
+  'utf8',
+)
+
+function posts() {
+  let lastTitle = 'NULL'
+  return stripIndents`
+  <!-- this doc is generated by ./scripts/docs/post-moderation-behaviors.mjs -->
+
+  # Post moderation behaviors
+  
+  This document is a reference for the expected behaviors for a post in the application based on some given scenarios. The <code>moderatePost()</code> command condense down to the following yes or no decisions:
+
+  - <code>res.content.filter</code> Do not show the post in feeds.
+  - <code>res.content.blur</code> Put the post behind a warning cover.
+  - <code>res.content.noOverride</code> Do not allow the post's blur cover to be lifted.
+  - <code>res.content.alert</code> Add a warning to the post 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.
+  - <code>res.embed.blur</code> Put the embed content (media, quote post) behind a warning cover.
+  - <code>res.embed.noOverride</code> Do not allow the embed's blur cover to be lifted.
+  - <code>res.embed.alert</code> Put a warning on the embed content (media, quote post).
+ 
+  Key:
+
+  - ❌ = Filter Content
+  - 🚫 = Blur (no-override)
+  - ✋ = Blur
+  - 🪧 = Alert
+
+  ## Scenarios
+
+  <table>
+    ${Array.from(Object.entries(postModerationBehaviorsDef.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>Content</th><th>Avatar</th><th>Embed</th></tr>`
+}
+
+function scenarioSection(title, scenario) {
+  return stripIndents`
+  <tr>
+    <td><strong>${title}</strong></td>
+    <td>
+      ${filter(scenario.behaviors.content?.filter)}
+    </td>
+    <td>
+      ${blur(
+        scenario.behaviors.content?.blur,
+        scenario.behaviors.content?.noOverride,
+      )}
+      ${alert(scenario.behaviors.content?.alert)}
+    </td>
+    <td>
+      ${blur(
+        scenario.behaviors.avatar?.blur,
+        scenario.behaviors.avatar?.noOverride,
+      )}
+      ${alert(scenario.behaviors.avatar?.alert)}
+    </td>
+    <td>
+      ${blur(
+        scenario.behaviors.embed?.blur,
+        scenario.behaviors.embed?.noOverride,
+      )}
+      ${alert(scenario.behaviors.embed?.alert)}
+    </td>
+  </tr>
+  `
+}
+
+function filter(val) {
+  return val ? '❌' : ''
+}
+
+function blur(val, noOverride) {
+  if (val) {
+    return noOverride ? '🚫' : '✋'
+  }
+  return ''
+}
+
+function alert(val) {
+  return val ? '🪧' : ''
+}
+
+export {}