@atproto/api/scripts/docs/labels.mjs

Client library for atproto and Bluesky

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 {}