@atproto/api 0.20.23 → 0.20.26

package/docs/moderation.md

@@ -1,260 +0,0 @@
-# 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:
-
-- Moderator labeling
-- User muting (including mutelists)
-- User blocking
-- Mutewords
-- Hidden posts
-
-## Configuration
-
-Every moderation function takes a set of options which look like this:
-
-```typescript
-{
-  // the logged-in user's DID
-  userDid: 'did:plc:1234...',
-
-  moderationPrefs: {
-    // is adult content allowed?
-    adultContentEnabled: true,
-
-    // the global label settings (used on self-labels)
-    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
-export interface ModerationPrefsLabeler {
-  did: string
-  labels: Record<string, LabelPreference>
-}
-
-export interface ModerationPrefs {
-  adultContentEnabled: boolean
-  labels: Record<string, LabelPreference>
-  labelers: ModerationPrefsLabeler[]
-  mutedWords: AppBskyActorDefs.MutedWord[]
-  hiddenPosts: string[]
-}
-
-export interface ModerationOpts {
-  userDid: string | undefined
-  prefs: ModerationPrefs
-  /**
-   * Map of labeler did -> custom definitions
-   */
-  labelDefs?: Record<string, InterpretedLabelValueDefinition[]>
-}
-```
-
-You can quickly grab the `ModerationPrefs` using the `agent.getPreferences()` method:
-
-```typescript
-const prefs = await agent.getPreferences()
-moderatePost(post, {
-  userDid: /*...*/,
-  prefs: prefs.moderationPrefs,
-  labelDefs: /*...*/
-})
-```
-
-To gather the label definitions (`labelDefs`) see the _Labelers_ section below.
-
-## 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
-BskyAgent.configure({
-  appLabelers: ['did:web:my-labeler.com'],
-})
-```
-
-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.
-
-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'
-}
-```
-
-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 { AtpAgent } from '@atproto/api'
-
-const agent = new AtpAgent({ service: 'https://example.com' })
-// 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)
-```
-
-The response object provides an API for figuring out what your UI should do in different contexts.
-
-```typescript
-res.ui(context) /* =>
-
-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?
-
-  // the reasons for each of the flags:
-  filters: ModerationCause[]
-  blurs: ModerationCause[]
-  alerts: ModerationCause[]
-  informs: ModerationCause[]
-}
-*/
-```
-
-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 (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 (mod.ui('contentMedia').blur) {
-  // cover the post's embedded images with the explanation from mod.ui('contentMedia').blurs[0]
-  if (mod.ui('contentMedia').noOverride) {
-    // dont allow the cover to be removed
-  }
-}
-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
-  }
-}
-for (const alert of mod.ui('contentList').alerts) {
-  // render this alert
-}
-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.config.cjs

@@ -1,23 +0,0 @@
-/** @type {import('jest').Config} */
-module.exports = {
-  displayName: 'API',
-  transform: {
-    '^.+\\.(t|j)s$': [
-      '@swc/jest',
-      {
-        jsc: {
-          parser: { syntax: 'typescript', importAttributes: true },
-          experimental: { keepImportAttributes: true },
-          transform: {},
-        },
-        module: { type: 'es6' },
-      },
-    ],
-  },
-  extensionsToTreatAsEsm: ['.ts'],
-  transformIgnorePatterns: [],
-  testTimeout: 60000,
-  setupFiles: ['<rootDir>/../../test.setup.ts'],
-  setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
-  moduleNameMapper: { '^(\\.\\.?\\/.+)\\.js$': ['$1.ts', '$1.js'] },
-}

package/jest.d.ts

@@ -1,20 +0,0 @@
-declare namespace jest {
-  // eslint-disable-next-line
-  interface Matchers<R, T = {}> {
-    toBeModerationResult(
-      expected: ModerationTestSuiteResultFlag[] | undefined,
-      context?: string,
-      stringifiedResult?: string,
-      ignoreCause?: boolean,
-    ): R
-  }
-
-  interface Expect {
-    toBeModerationResult(
-      expected: ModerationTestSuiteResultFlag[] | undefined,
-      context?: string,
-      stringifiedResult?: string,
-      ignoreCause?: boolean,
-    ): void
-  }
-}

package/jest.setup.ts

@@ -1,97 +0,0 @@
-import { ModerationUI } from './src/index.js'
-import { ModerationTestSuiteResultFlag } from './tests/util/moderation-behavior.js'
-
-expect.extend({
-  toBeModerationResult(
-    actual: ModerationUI,
-    expected: ModerationTestSuiteResultFlag[] | undefined,
-    context = '',
-    stringifiedResult: string | undefined = undefined,
-    _ignoreCause = false,
-  ) {
-    const fail = (msg: string) => ({
-      pass: false,
-      message: () =>
-        `${msg}.${
-          stringifiedResult ? ` Full result: ${stringifiedResult}` : ''
-        }`,
-    })
-    // let cause = actual.causes?.type as string
-    // if (actual.cause?.type === 'label') {
-    //   cause = `label:${actual.cause.labelDef.id}`
-    // } else if (actual.cause?.type === 'muted') {
-    //   if (actual.cause.source.type === 'list') {
-    //     cause = 'muted-by-list'
-    //   }
-    // } else if (actual.cause?.type === 'blocking') {
-    //   if (actual.cause.source.type === 'list') {
-    //     cause = 'blocking-by-list'
-    //   }
-    // }
-    if (!expected) {
-      // if (!ignoreCause && actual.cause) {
-      //   return fail(`${context} expected to be a no-op, got ${cause}`)
-      // }
-      if (actual.inform) {
-        return fail(`${context} expected to be a no-op, got inform=true`)
-      }
-      if (actual.alert) {
-        return fail(`${context} expected to be a no-op, got alert=true`)
-      }
-      if (actual.blur) {
-        return fail(`${context} expected to be a no-op, got blur=true`)
-      }
-      if (actual.filter) {
-        return fail(`${context} expected to be a no-op, got filter=true`)
-      }
-      if (actual.noOverride) {
-        return fail(`${context} expected to be a no-op, got noOverride=true`)
-      }
-    } else {
-      // if (!ignoreCause && cause !== expected.cause) {
-      //   return fail(`${context} expected to be ${expected.cause}, got ${cause}`)
-      // }
-      const expectedInform = expected.includes('inform')
-      if (!!actual.inform !== expectedInform) {
-        return fail(
-          `${context} expected to be inform=${expectedInform}, got ${
-            actual.inform || false
-          }`,
-        )
-      }
-      const expectedAlert = expected.includes('alert')
-      if (!!actual.alert !== expectedAlert) {
-        return fail(
-          `${context} expected to be alert=${expectedAlert}, got ${
-            actual.alert || false
-          }`,
-        )
-      }
-      const expectedBlur = expected.includes('blur')
-      if (!!actual.blur !== expectedBlur) {
-        return fail(
-          `${context} expected to be blur=${expectedBlur}, got ${
-            actual.blur || false
-          }`,
-        )
-      }
-      const expectedFilter = expected.includes('filter')
-      if (!!actual.filter !== expectedFilter) {
-        return fail(
-          `${context} expected to be filter=${expectedFilter}, got ${
-            actual.filter || false
-          }`,
-        )
-      }
-      const expectedNoOverride = expected.includes('noOverride')
-      if (!!actual.noOverride !== expectedNoOverride) {
-        return fail(
-          `${context} expected to be noOverride=${expectedNoOverride}, got ${
-            actual.noOverride || false
-          }`,
-        )
-      }
-    }
-    return { pass: true, message: () => '' }
-  },
-})

package/scripts/code/labels.mjs

@@ -1,77 +0,0 @@
-import { mkdir, writeFile } from 'node:fs/promises'
-import { dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import * as prettier from 'prettier'
-import labelsDef from '../../definitions/labels.json' with { type: 'json' }
-
-const __dirname = dirname(fileURLToPath(import.meta.url))
-
-export async function labels() {
-  const content = await gen()
-
-  const path = join(
-    __dirname,
-    '..',
-    '..',
-    'src',
-    'moderation',
-    'const',
-    'labels.ts',
-  )
-
-  await mkdir(dirname(path), { recursive: true })
-  await writeFile(path, content, 'utf8')
-}
-
-async function gen() {
-  const knownValues = new Set()
-  const flattenedLabelDefs = []
-
-  for (const { alias: aliases, ...label } of labelsDef) {
-    knownValues.add(label.identifier)
-    flattenedLabelDefs.push([label.identifier, { ...label, locales: [] }])
-
-    if (aliases) {
-      for (const alias of aliases) {
-        knownValues.add(alias)
-        flattenedLabelDefs.push([
-          alias,
-          {
-            ...label,
-            identifier: alias,
-            locales: [],
-            comment: `@deprecated alias for \`${label.identifier}\``,
-          },
-        ])
-      }
-    }
-  }
-
-  let labelDefsStr = `{`
-  for (const [key, { comment, ...value }] of flattenedLabelDefs) {
-    const commentStr = comment ? `\n/** ${comment} */\n` : ''
-    labelDefsStr += `${commentStr}'${key}': ${JSON.stringify(value, null, 2)},`
-  }
-  labelDefsStr += `}`
-
-  return prettier.format(
-    `/** this doc is generated by ./scripts/code/labels.mjs **/
-  import {InterpretedLabelValueDefinition, LabelPreference} from '../types.js'
-
-  export type KnownLabelValue = ${Array.from(knownValues)
-    .map((value) => `"${value}"`)
-    .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: Record<KnownLabelValue, InterpretedLabelValueDefinition> = ${labelDefsStr}
-  `,
-    { semi: false, parser: 'typescript', singleQuote: true },
-  )
-}

package/scripts/generate-code.mjs

@@ -1,4 +0,0 @@
-import { labels } from './code/labels.mjs'
-export { labels }
-
-labels()

package/src/age-assurance.test.ts

@@ -1,218 +0,0 @@
-import { describe, expect, it } from '@jest/globals'
-import {
-  ageAssuranceRuleIDs,
-  computeAgeAssuranceRegionAccess,
-  getAgeAssuranceRegionConfig,
-} from './age-assurance.js'
-import { AppBskyAgeassuranceDefs } from './client/index.js'
-
-describe('age-assurance', () => {
-  describe('getAgeAssuranceRegionConfig', () => {
-    const config: AppBskyAgeassuranceDefs.Config = {
-      regions: [
-        {
-          countryCode: 'US',
-          regionCode: 'CA',
-          minAccessAge: 13,
-          rules: [],
-        },
-        {
-          countryCode: 'US',
-          minAccessAge: 13,
-          rules: [],
-        },
-      ],
-    }
-
-    it('should find region by country code only', () => {
-      const result = getAgeAssuranceRegionConfig(config, {
-        countryCode: 'US',
-      })
-
-      expect(result).toEqual({
-        countryCode: 'US',
-        minAccessAge: 13,
-        rules: [],
-      })
-    })
-
-    it('should find region by country code and region code', () => {
-      const result = getAgeAssuranceRegionConfig(config, {
-        countryCode: 'US',
-        regionCode: 'CA',
-      })
-
-      expect(result).toEqual({
-        countryCode: 'US',
-        regionCode: 'CA',
-        minAccessAge: 13,
-        rules: [],
-      })
-    })
-
-    it('should return undefined when no matching region found', () => {
-      const result = getAgeAssuranceRegionConfig(config, {
-        countryCode: 'GB',
-      })
-
-      expect(result).toBeUndefined()
-    })
-  })
-
-  describe('computeAgeAssuranceRegionAccess', () => {
-    const region: AppBskyAgeassuranceDefs.ConfigRegion = {
-      countryCode: 'US',
-      minAccessAge: 13,
-      rules: [
-        {
-          $type: ageAssuranceRuleIDs.IfAccountNewerThan,
-          date: '2025-12-10T00:00:00Z',
-          access: 'none',
-        },
-        {
-          $type: ageAssuranceRuleIDs.IfAssuredOverAge,
-          age: 18,
-          access: 'full',
-        },
-        {
-          $type: ageAssuranceRuleIDs.IfAssuredOverAge,
-          age: 16,
-          access: 'safe',
-        },
-        {
-          $type: ageAssuranceRuleIDs.IfDeclaredOverAge,
-          age: 16,
-          access: 'safe',
-        },
-        {
-          $type: ageAssuranceRuleIDs.Default,
-          access: 'none',
-        },
-      ],
-    }
-
-    it('should apply default if no data provided', () => {
-      const result = computeAgeAssuranceRegionAccess(region, {})
-
-      expect(result).toEqual({
-        access: 'none',
-        reason: ageAssuranceRuleIDs.Default,
-      })
-    })
-
-    describe('IfAccountNewerThan', () => {
-      it('should block accounts created after threshold', () => {
-        const result = computeAgeAssuranceRegionAccess(region, {
-          accountCreatedAt: new Date(2025, 11, 15).toISOString(),
-          declaredAge: 18,
-        })
-        expect(result).toEqual({
-          access: 'none',
-          reason: ageAssuranceRuleIDs.IfAccountNewerThan,
-        })
-      })
-
-      it('should allow accounts created before threshold', () => {
-        const result = computeAgeAssuranceRegionAccess(region, {
-          accountCreatedAt: new Date(2025, 10, 1).toISOString(),
-          declaredAge: 18,
-        })
-        expect(result).toEqual({
-          access: 'safe',
-          reason: ageAssuranceRuleIDs.IfDeclaredOverAge,
-        })
-      })
-
-      it('should allow accounts created exactly at threshold', () => {
-        const result = computeAgeAssuranceRegionAccess(region, {
-          accountCreatedAt: new Date(2025, 11, 1).toISOString(),
-          declaredAge: 18,
-        })
-        expect(result).toEqual({
-          access: 'safe',
-          reason: ageAssuranceRuleIDs.IfDeclaredOverAge,
-        })
-      })
-
-      it('should not apply rule when accountCreatedAt is not provided', () => {
-        const result = computeAgeAssuranceRegionAccess(region, {
-          declaredAge: 15,
-        })
-        expect(result).toEqual({
-          access: 'none',
-          reason: ageAssuranceRuleIDs.Default,
-        })
-      })
-
-      it('should not apply rule when assuredAge is present', () => {
-        const result = computeAgeAssuranceRegionAccess(region, {
-          accountCreatedAt: new Date(2025, 11, 15).toISOString(),
-          assuredAge: 20,
-        })
-        expect(result).toEqual({
-          access: 'full',
-          reason: ageAssuranceRuleIDs.IfAssuredOverAge,
-        })
-      })
-    })
-
-    describe('IfDeclaredOverAge rule', () => {
-      it('should allow users at or above age threshold', () => {
-        const result = computeAgeAssuranceRegionAccess(region, {
-          declaredAge: 18,
-        })
-
-        expect(result).toEqual({
-          access: 'safe',
-          reason: ageAssuranceRuleIDs.IfDeclaredOverAge,
-        })
-      })
-
-      it('should allow users above age threshold', () => {
-        const result = computeAgeAssuranceRegionAccess(region, {
-          declaredAge: 25,
-        })
-
-        expect(result).toEqual({
-          access: 'safe',
-          reason: ageAssuranceRuleIDs.IfDeclaredOverAge,
-        })
-      })
-
-      it('should not allow users below age threshold', () => {
-        const result = computeAgeAssuranceRegionAccess(region, {
-          declaredAge: 17,
-        })
-
-        expect(result).toEqual({
-          access: 'safe',
-          reason: ageAssuranceRuleIDs.IfDeclaredOverAge,
-        })
-      })
-    })
-
-    describe('IfAssuredOverAge rule', () => {
-      it('should allow users at or above assured age threshold', () => {
-        const result = computeAgeAssuranceRegionAccess(region, {
-          assuredAge: 18,
-        })
-
-        expect(result).toEqual({
-          access: 'full',
-          reason: ageAssuranceRuleIDs.IfAssuredOverAge,
-        })
-      })
-
-      it('should not allow users below assured age threshold', () => {
-        const result = computeAgeAssuranceRegionAccess(region, {
-          assuredAge: 17,
-        })
-
-        expect(result).toEqual({
-          access: 'safe',
-          reason: ageAssuranceRuleIDs.IfAssuredOverAge,
-        })
-      })
-    })
-  })
-})