// The API reference's content: each service's endpoints, grouped, and the types they take and
// give, as the handlers in crates/ipx/src/web.rs and crates/directory/src/lib.rs have them. A
// change to a route or a field there wants its line here; gen.mjs turns this into pages.
// Types are written as Rust writes them, the way docs.rs shows a signature; a name in TYPES links
// to its page.

const U = 'http://<your server>:8099';
const D = 'https://directory.ipxreader.app';
const ipxCurl = (m, p, body) =>
  `curl${m === 'GET' ? '' : ` -X ${m}`} -H "Authorization: Bearer ipx_…"${body ? ` \\\n  -H "Content-Type: application/json" -d '${body}'` : ''} \\\n  "${U}${p}"`;
const dirCurl = (m, p, body) =>
  `curl${m === 'GET' ? '' : ` -X ${m}`} -H "Authorization: Bearer <token>"${body ? ` \\\n  -H "Content-Type: application/json" -d '${body}'` : ''} \\\n  "${D}${p}"`;

const NOT_SUBSCRIBED = ['404 Not Found', 'You do not subscribe to the feed, or it does not exist. A feed someone else reads is not yours to see.'];
const NOT_ADMIN = ['403 Forbidden', 'You are not an admin.'];
const NO_DIRECTORY = ['503 Service Unavailable', 'No directory is set up on this server.'];

export const ipx = {
  name: 'ipx',
  root: '/docs/api/ipx',
  changelog: 'crates/ipx/CHANGELOG.md',
  intro: `<p>The HTTP API of an iPX server: everything the page does, a script can do. Every request
    and answer is JSON unless an item says otherwise. The page is served by ipx-web, which passes
    <code>/api</code> and <code>/media</code> on to ipx at the same address, so a script talks to
    the address people open in a browser.</p>
    <h2 id="auth">Signing in</h2>
    <p>Send an API token, made in Settings under API tokens or with <a href="${'/docs/api/ipx/auth/post-tokens'}"><code>POST /api/tokens</code></a>:</p>
    <pre><code>Authorization: Bearer ipx_…</code></pre>
    <p>A token acts as the person who made it, and is an admin only if they are. A browser signs in
    with <a href="/docs/api/ipx/auth/post-login"><code>POST /api/login</code></a> instead and is
    given a cookie. Behind Cloudflare Access, Access stops a request with no Access sign-in before
    iPX sees it: send an Access service token's <code>CF-Access-Client-Id</code> and
    <code>CF-Access-Client-Secret</code> beside the API token.</p>
    <h2 id="errors">Errors</h2>
    <p>A request that fails answers with its status and a sentence saying why, as plain text:
    <code>401</code> not signed in, <code>403</code> an admin's to do, <code>404</code> not there or
    not yours, <code>400</code> a request that cannot be done as asked, <code>409</code> a conflict
    the answer explains.</p>
    <h2 id="ids">Ids</h2>
    <p>A feed's id is a short name made from its title, such as <code>99-invisible</code>, and
    appears in the page's address when the feed is open. An episode is its feed's id and its
    <code>guid</code>, the guid URL-encoded in a path. A file (an enclosure) has a number. Times are
    Unix seconds.</p>`,
  groups: [
    {
      id: 'auth', name: 'auth', title: 'Signing in and tokens',
      summary: 'Who you are, signing in and out, and API tokens.',
      items: [
        {
          method: 'POST', path: '/api/login', slug: 'post-login', access: 'none',
          summary: 'Sign in with a name and password, for a session cookie.',
          doc: '<p>Answers who signed in and sets the session cookie, which lasts <code>session_days</code> from the last request. A script is better off with an API token, which needs no password kept.</p>',
          body: 'Credentials', returns: 'Me',
          errors: [['401 Unauthorized', 'The name or password is wrong.']],
          example: `curl -c cookies -H "Content-Type: application/json" \\\n  -d '{"name":"sam","password":"…"}' "${U}/api/login"`,
        },
        {
          method: 'POST', path: '/api/logout', slug: 'post-logout',
          summary: 'Sign out: end the session and clear its cookies.',
          returns: '204 No Content',
        },
        {
          method: 'GET', path: '/api/me', slug: 'get-me',
          summary: 'Who you are, your words that hide items, and the server’s version.',
          returns: 'Me',
          example: ipxCurl('GET', '/api/me'),
        },
        {
          method: 'PATCH', path: '/api/me', slug: 'patch-me',
          summary: 'Change the words that hide an item in every feed you read.',
          body: 'MePatch', returns: '204 No Content',
          errors: [['400 Bad Request', 'More than 500 words, or one over 200 characters.']],
          example: ipxCurl('PATCH', '/api/me', '{"blocked":["sponsor","ad read"]}'),
        },
        {
          method: 'GET', path: '/api/tokens', slug: 'get-tokens',
          summary: 'Your API tokens: names and when each was made and last used, never the token.',
          returns: 'Vec<Token>',
        },
        {
          method: 'POST', path: '/api/tokens', slug: 'post-tokens',
          summary: 'Make an API token that acts as you.',
          doc: '<p>The answer is the only time the token is shown: only its SHA-256 is kept.</p>',
          body: 'NewToken', returns: 'NewTokenMade',
          errors: [['400 Bad Request', 'No name.']],
          example: ipxCurl('POST', '/api/tokens', '{"name":"my script"}'),
        },
        {
          method: 'DELETE', path: '/api/tokens/{id}', slug: 'delete-token',
          summary: 'Revoke one of your API tokens.',
          pathParams: [['id', 'i64', 'The token’s id, from <code>GET /api/tokens</code>.']],
          returns: '204 No Content',
          errors: [['404 Not Found', 'No token of yours has that id.']],
        },
      ],
    },
    {
      id: 'feeds', name: 'feeds', title: 'Feeds',
      summary: 'Your subscriptions: list, subscribe, change, unsubscribe, check, OPML.',
      items: [
        {
          method: 'GET', path: '/api/feeds', slug: 'get-feeds',
          summary: 'Your subscriptions, each with its counts and your settings for it.',
          returns: 'Vec<FeedRow>',
          example: ipxCurl('GET', '/api/feeds'),
        },
        {
          method: 'POST', path: '/api/feeds', slug: 'post-feeds',
          summary: 'Subscribe to a feed, by its address or a site that links one.',
          doc: '<p>A feed someone else on the server already has costs nothing to add: it is fetched once and each file is kept once. An OPML address subscribes to the list, kept in step as a folder.</p>',
          body: 'NewFeed', returns: 'Added',
          errors: [['400 Bad Request', 'The address is not a feed and links none; the answer says what was found.']],
          example: ipxCurl('POST', '/api/feeds', '{"url":"https://feeds.99percentinvisible.org/99percentinvisible"}'),
        },
        {
          method: 'PATCH', path: '/api/feeds/{id}', slug: 'patch-feed',
          summary: 'Change your settings for a feed, or (an admin) the feed’s own.',
          doc: '<p>Send only the fields to change. Which episodes you want, whether to download them, how many at a time, DeadAir and pinning are yours, and change for nobody else. The feed’s address, folder, schedule and category, and marking it shareable again, are the same for everyone and an admin’s to change.</p>',
          pathParams: [['id', 'String', 'The feed’s id.']],
          body: 'FeedPatch', returns: '204 No Content',
          errors: [['400 Bad Request', 'A value out of range, such as a DeadAir pause that is not 200, 300, 400 or 500.'], ['403 Forbidden', 'A field only an admin may change.'], NOT_SUBSCRIBED],
          example: ipxCurl('PATCH', '/api/feeds/99-invisible', '{"keywords":["mini-stories"],"pinned":true}'),
        },
        {
          method: 'DELETE', path: '/api/feeds/{id}', slug: 'delete-feed',
          summary: 'Unsubscribe. The files stay for anyone else who reads the feed.',
          pathParams: [['id', 'String', 'The feed’s id.']],
          returns: '204 No Content', errors: [NOT_SUBSCRIBED],
        },
        {
          method: 'POST', path: '/api/feeds/{id}/read-all', slug: 'post-read-all',
          summary: 'Mark every episode of a feed read, and of every feed in it for an OPML list.',
          pathParams: [['id', 'String', 'The feed’s id.']],
          returns: 'Marked',
        },
        {
          method: 'POST', path: '/api/feeds/{id}/download-latest', slug: 'post-download-latest',
          summary: 'Download a feed’s newest episodes that are not downloaded yet.',
          pathParams: [['id', 'String', 'The feed’s id.']],
          body: 'HowMany', returns: 'Queued', errors: [NOT_SUBSCRIBED],
          example: ipxCurl('POST', '/api/feeds/99-invisible/download-latest', '{"count":3}'),
        },
        {
          method: 'POST', path: '/api/fetch', slug: 'post-fetch',
          summary: 'Check one feed, or all of yours, for new episodes now.',
          doc: '<p>The check runs in the background; <a href="/docs/api/ipx/server/get-events"><code>GET /api/events</code></a> shows it as it goes.</p>',
          body: 'FetchBody', returns: '202 Accepted',
          example: ipxCurl('POST', '/api/fetch', '{"feed":"99-invisible","force":true}'),
        },
        {
          method: 'GET', path: '/api/opml', slug: 'get-opml',
          summary: 'Your subscriptions as an OPML file, for another podcast app.',
          returns: 'OPML (text/x-opml)',
        },
        {
          method: 'POST', path: '/api/opml', slug: 'post-opml',
          summary: 'Subscribe to every feed in an OPML file.',
          body: 'OpmlBody', returns: 'Imported',
          errors: [['400 Bad Request', 'Not OPML.']],
        },
      ],
    },
    {
      id: 'entries', name: 'entries', title: 'Episodes',
      summary: 'Episodes and posts: list, search, mark read or kept, save where you are.',
      items: [
        {
          method: 'GET', path: '/api/feeds/{id}/entries', slug: 'get-feed-entries',
          summary: 'A page of one feed’s episodes, newest first unless sorted.',
          pathParams: [['id', 'String', 'The feed’s id.']],
          query: 'Page', returns: 'EntryPage', errors: [NOT_SUBSCRIBED],
          example: ipxCurl('GET', '/api/feeds/99-invisible/entries?filter=unread&limit=10'),
        },
        {
          method: 'GET', path: '/api/entries', slug: 'get-entries',
          summary: 'The same, across every feed you subscribe to.',
          query: 'Page', returns: 'EntryPage',
          example: ipxCurl('GET', '/api/entries?q=bridges&sort=published&dir=desc'),
        },
        {
          method: 'GET', path: '/api/entries/{feed}/{guid}', slug: 'get-entry',
          summary: 'One episode.',
          pathParams: [['feed', 'String', 'The feed’s id.'], ['guid', 'String', 'The episode’s guid, URL-encoded.']],
          returns: 'EntryRow', errors: [NOT_SUBSCRIBED],
        },
        {
          method: 'POST', path: '/api/entries/{feed}/{guid}/flags', slug: 'post-flags',
          summary: 'Mark an episode read or unread, kept or not.',
          doc: '<p>Answers with the feed’s row, its counts changed, so a list can redraw one line.</p>',
          pathParams: [['feed', 'String', 'The feed’s id.'], ['guid', 'String', 'The episode’s guid, URL-encoded.']],
          body: 'Flags', returns: 'Option<FeedRow>', errors: [NOT_SUBSCRIBED],
          example: ipxCurl('POST', '/api/entries/99-invisible/{guid}/flags', '{"read":true}'),
        },
        {
          method: 'POST', path: '/api/entries/{feed}/{guid}/position', slug: 'post-position',
          summary: 'Save where you are in an episode, for every device you listen on.',
          pathParams: [['feed', 'String', 'The feed’s id.'], ['guid', 'String', 'The episode’s guid, URL-encoded.']],
          body: 'Position', returns: '204 No Content', errors: [NOT_SUBSCRIBED],
          example: ipxCurl('POST', '/api/entries/99-invisible/{guid}/position', '{"secs":1234}'),
        },
        {
          method: 'POST', path: '/api/read-all', slug: 'post-read-all-mine',
          summary: 'Mark every episode of every feed you subscribe to read.',
          returns: 'Marked',
        },
      ],
    },
    {
      id: 'files', name: 'files', title: 'Files',
      summary: 'Downloading, deleting and playing an episode’s file.',
      items: [
        {
          method: 'POST', path: '/api/enclosures/{id}/download', slug: 'post-download',
          summary: 'Download a file now.',
          pathParams: [['id', 'i64', 'The file’s id, an <code>EncRow</code>’s <code>id</code>.']],
          returns: '202 Accepted, or 204 No Content when it is already here', errors: [NOT_SUBSCRIBED],
        },
        {
          method: 'DELETE', path: '/api/enclosures/{id}', slug: 'delete-file',
          summary: 'Delete a downloaded file. It is not downloaded again.',
          doc: '<p>There is one copy of each file, so deleting it deletes it for everyone. If someone else has kept the episode or not played it yet, the first try is refused with who: send it again with <code>?force=true</code> to delete it anyway.</p>',
          pathParams: [['id', 'i64', 'The file’s id.']],
          query: 'Force', returns: '204 No Content',
          errors: [['409 Conflict', 'Someone else still wants it; the answer says who. Send <code>force=true</code> to go ahead.'], NOT_SUBSCRIBED],
        },
        {
          method: 'GET', path: '/media/{id}', slug: 'get-media',
          summary: 'The file itself, with <code>Range</code> requests, so a player can seek.',
          pathParams: [['id', 'i64', 'The file’s id.']],
          returns: 'The file, with its own Content-Type', errors: [NOT_SUBSCRIBED],
        },
        {
          method: 'GET', path: '/media/{id}/deadair.m3u8', slug: 'get-deadair',
          summary: 'The episode with its long silences shortened by DeadAir, as an HLS playlist.',
          doc: '<p>Only once DeadAir has looked at the file: an <code>EncRow</code> with <code>deadair</code> set says how many seconds it saves. <code>/media/{id}/deadair</code> gives the shortened episode as one file to save.</p>',
          pathParams: [['id', 'i64', 'The file’s id.']],
          returns: 'An HLS playlist (application/vnd.apple.mpegurl)', errors: [NOT_SUBSCRIBED],
        },
      ],
    },
    {
      id: 'directory', name: 'directory', title: 'The directory, through iPX',
      summary: 'Browse the directory and subscribe from it; iPX asks it on your behalf.',
      items: [
        {
          method: 'GET', path: '/api/popular', slug: 'get-popular',
          summary: 'The directory’s ten most subscribed feeds.',
          returns: 'Vec<PopularRow>', errors: [NO_DIRECTORY],
        },
        {
          method: 'GET', path: '/api/directory', slug: 'get-directory',
          summary: 'Every feed the directory lists, A to Z.',
          returns: 'Vec<PopularRow>', errors: [NO_DIRECTORY],
        },
        {
          method: 'GET', path: '/api/directory/{id}', slug: 'get-listed',
          summary: 'A feed’s page in the directory: what it says it is and its latest items.',
          pathParams: [['id', 'String', 'The directory’s id for the feed.']],
          returns: 'Listed', errors: [['404 Not Found', 'Not in the directory.'], NO_DIRECTORY],
        },
        {
          method: 'POST', path: '/api/popular/{id}', slug: 'post-popular',
          summary: 'Subscribe to a feed from the directory, by the directory’s id.',
          pathParams: [['id', 'String', 'The directory’s id for the feed.']],
          returns: 'Subscribed', errors: [['400 Bad Request', 'Not in the directory.'], NO_DIRECTORY],
        },
      ],
    },
    {
      id: 'server', name: 'server', title: 'The server',
      summary: 'Its counts and version, and live updates.',
      items: [
        {
          method: 'GET', path: '/api/status', slug: 'get-status',
          summary: 'How many feeds, files waiting and files downloaded, and the version.',
          doc: '<p>The numbers <code>ipx status</code> prints, for a dashboard.</p>',
          returns: 'Status', example: ipxCurl('GET', '/api/status'),
        },
        {
          method: 'GET', path: '/api/events', slug: 'get-events',
          summary: 'A live stream of checks and downloads as they happen (server-sent events).',
          doc: '<p>Each message’s data is one JSON <a href="/docs/api/ipx/types/Event"><code>Event</code></a>. Every event of a check reaches everyone; a feed’s new row (<code>feed_row</code>) only those who subscribe to it.</p>',
          returns: 'text/event-stream of Event',
          example: `curl -N -H "Authorization: Bearer ipx_…" "${U}/api/events"\ndata: {"ev":"feed_start","feed":"99-invisible"}\ndata: {"ev":"feed_done","feed":"99-invisible","new":1,"downloaded":1,"failed":0,"torrents":0}`,
        },
      ],
    },
    {
      id: 'admin', name: 'admin', title: 'Admin',
      summary: 'Server settings, accounts, the log and the directory’s administration. Admins only.',
      items: [
        {
          method: 'GET', path: '/api/settings', slug: 'get-settings', access: 'signed in',
          summary: 'The server’s settings. Anyone signed in may read them.',
          returns: 'Settings',
        },
        {
          method: 'PATCH', path: '/api/settings', slug: 'patch-settings', access: 'admin',
          summary: 'Change the server’s settings. They take effect at once.',
          body: 'SettingsPatch', returns: '204 No Content',
          errors: [['400 Bad Request', 'A value that does not parse, such as a schedule.'], NOT_ADMIN],
          example: ipxCurl('PATCH', '/api/settings', '{"schedule":"every 2h","max_total_gb":200}'),
        },
        {
          method: 'GET', path: '/api/users', slug: 'get-users', access: 'admin',
          summary: 'Every account.', returns: 'Vec<UserRow>', errors: [NOT_ADMIN],
        },
        {
          method: 'POST', path: '/api/users', slug: 'post-users', access: 'admin',
          summary: 'Add an account.',
          doc: '<p>With no password, the account signs in only through single sign-on.</p>',
          body: 'NewUser', returns: '201 Created',
          errors: [['400 Bad Request', 'No name, or one that exists already.'], NOT_ADMIN],
          example: ipxCurl('POST', '/api/users', '{"name":"sam","password":"…"}'),
        },
        {
          method: 'PATCH', path: '/api/users/{id}', slug: 'patch-user', access: 'admin',
          summary: 'Make an account an admin, or not.',
          pathParams: [['id', 'i64', 'The account’s id.']],
          body: 'UserPatch', returns: '204 No Content',
          errors: [['400 Bad Request', 'No such account, or the only admin, who cannot stop being one.'], NOT_ADMIN],
        },
        {
          method: 'DELETE', path: '/api/users/{id}', slug: 'delete-user', access: 'admin',
          summary: 'Remove an account, with its subscriptions and read state. Files stay.',
          pathParams: [['id', 'i64', 'The account’s id.']],
          returns: '204 No Content',
          errors: [['400 Bad Request', 'No such account, or the only admin, who cannot be removed.'], NOT_ADMIN],
        },
        {
          method: 'GET', path: '/api/logs', slug: 'get-logs', access: 'admin',
          summary: 'The newest lines of the server’s log, or those after a given one.',
          query: 'LogQuery', returns: 'LogPage', errors: [NOT_ADMIN],
        },
        {
          method: 'GET', path: '/api/directory-status', slug: 'get-directory-status', access: 'admin',
          summary: 'Who the directory takes this server’s token to be, and how the last share went.',
          returns: 'DirectoryStatus', errors: [NOT_ADMIN],
        },
        {
          method: 'DELETE', path: '/api/directory/{id}', slug: 'delete-listed', access: 'admin',
          summary: 'Remove a feed from the directory and keep it out.',
          doc: '<p>Only when this server’s directory token is <code>rwa</code>; the directory refuses otherwise.</p>',
          pathParams: [['id', 'String', 'The directory’s id for the feed.']],
          returns: '204 No Content', errors: [NOT_ADMIN, NO_DIRECTORY],
        },
        {
          method: 'POST', path: '/api/directory/{id}/refresh', slug: 'post-listed-refresh', access: 'admin',
          summary: 'Have the directory check a feed now. Needs an <code>rwa</code> token.',
          pathParams: [['id', 'String', 'The directory’s id for the feed.']],
          returns: '204 No Content', errors: [NOT_ADMIN, NO_DIRECTORY],
        },
        {
          method: 'GET', path: '/api/directory-admin', slug: 'get-directory-admin', access: 'admin',
          summary: 'The servers sharing with the directory, and the feeds it keeps out. Needs <code>rwa</code>.',
          returns: 'DirectoryAdmin', errors: [NOT_ADMIN, NO_DIRECTORY],
        },
        {
          method: 'DELETE', path: '/api/directory-blocked/{id}', slug: 'delete-directory-blocked', access: 'admin',
          summary: 'Let a feed the directory keeps out back in. Needs <code>rwa</code>.',
          pathParams: [['id', 'String', 'The directory’s id for the feed.']],
          returns: '204 No Content', errors: [NOT_ADMIN, NO_DIRECTORY],
        },
        {
          method: 'DELETE', path: '/api/directory-instances/{name}', slug: 'delete-directory-instance', access: 'admin',
          summary: 'Drop a server’s share from the directory until it next shares. Needs <code>rwa</code>.',
          pathParams: [['name', 'String', 'The server’s token name.']],
          returns: '204 No Content', errors: [NOT_ADMIN, NO_DIRECTORY],
        },
      ],
    },
  ],
  types: [
    { name: 'Credentials', doc: 'A name and password.', fields: [['name', 'String', ''], ['password', 'String', '']] },
    { name: 'Me', doc: 'Who is signed in.', fields: [
      ['name', 'String', 'The account’s name, often an email address.'],
      ['admin', 'bool', ''],
      ['blocked', 'Vec<String>', 'Words that hide an item in every feed you read. <code>GET /api/me</code> only, as are the fields below.'],
      ['sign_out', 'Option<String>', 'Where signing out should go, for someone single sign-on signed in.'],
      ['deadair_saved', 'i64', 'Seconds DeadAir has saved you, all told.'],
      ['version', 'String', 'ipx’s version.'],
    ] },
    { name: 'MePatch', doc: 'What <code>PATCH /api/me</code> changes.', fields: [['blocked', 'Option<Vec<String>>', 'Replaces the list.']] },
    { name: 'Token', doc: 'An API token, as listed.', fields: [['id', 'i64', ''], ['name', 'String', ''], ['created', 'i64', ''], ['last_used', 'Option<i64>', '']] },
    { name: 'NewToken', doc: 'A token to make.', fields: [['name', 'String', 'What it is for, to know it by when revoking it.']] },
    { name: 'NewTokenMade', doc: 'A token just made: the only time it is shown.', fields: [['id', 'i64', ''], ['name', 'String', ''], ['token', 'String', 'Begins <code>ipx_</code>. Send it as <code>Authorization: Bearer</code>.']] },
    { name: 'FeedRow', doc: 'A feed as you see it: the feed, your settings for it and its counts for you.', fields: [
      ['id', 'String', ''], ['url', 'String', ''], ['title', 'Option<String>', ''], ['image', 'Option<String>', ''],
      ['folder', 'Option<String>', ''],
      ['category', 'Option<String>', 'The directory category an admin gave it.'],
      ['feed_category', 'Option<String>', 'The one the feed names itself, which wins.'],
      ['keywords', 'Vec<String>', 'Your words: with any, only episodes that mention one are downloaded.'],
      ['blocked', 'Vec<String>', 'Your words that hide an episode of this feed.'],
      ['deadair', 'bool', 'Played with its silences shortened.'],
      ['deadair_pause', 'i64', 'The pause DeadAir leaves where it cuts, in milliseconds.'],
      ['allow_explicit', 'bool', ''], ['auto_download', 'bool', ''],
      ['max_new_per_check', 'Option<usize>', 'Your own limit, or none for the server’s.'],
      ['group', 'Option<String>', 'The OPML list it came from.'],
      ['orphaned', 'bool', 'In a list that no longer has it, kept for its downloads.'],
      ['managed', 'bool', ''],
      ['schedule', 'Option<String>', 'Its own schedule, such as <code>every 2h</code>.'],
      ['schedule_mins', 'Option<u64>', 'The same in minutes.'],
      ['every_mins', 'u64', 'How often it is checked, all things considered.'],
      ['last_checked', 'Option<i64>', ''], ['next_check', 'Option<i64>', ''],
      ['last_error', 'Option<String>', ''],
      ['failing', 'Option<FailingRow>', 'Set once an error has held for a day.'],
      ['entries', 'i64', ''], ['downloaded', 'i64', ''], ['unread', 'i64', ''],
      ['subscribers', 'i64', 'People on this server, you included.'],
      ['pinned', 'bool', 'At the top of your list.'],
      ['private', 'bool', 'Kept out of the directory.'],
      ['private_by_address', 'bool', 'Private whatever it is marked: a login, or a key in its address.'],
    ] },
    { name: 'FailingRow', doc: 'Why a feed has been failing.', fields: [['reason', 'String', 'In words.'], ['new_url', 'Option<String>', 'Where it seems to have moved.']] },
    { name: 'NewFeed', doc: 'A feed to subscribe to.', fields: [
      ['url', 'String', 'A feed’s address, an OPML list’s, or a site’s page that links its feed.'],
      ['folder', 'Option<String>', ''],
      ['keywords', 'Vec<String>', 'Download only episodes that mention one. Empty for all.'],
      ['allow_explicit', 'bool', 'Download explicit episodes too. False if left out.'],
    ] },
    { name: 'Added', doc: 'A feed subscribed to.', fields: [['id', 'String', 'Its id here.'], ['existing', 'bool', 'You subscribed to it already.']] },
    { name: 'FeedPatch', doc: 'What <code>PATCH /api/feeds/{id}</code> changes. Leave out what stays; <code>null</code> clears a field that can be cleared.', fields: [
      ['keywords', 'Option<Vec<String>>', 'Yours.'], ['blocked', 'Option<Vec<String>>', 'Yours.'],
      ['allow_explicit', 'Option<bool>', 'Yours.'], ['auto_download', 'Option<bool>', 'Yours.'],
      ['max_new_per_check', 'Option<Option<usize>>', 'Yours; <code>null</code> for the server’s.'],
      ['pinned', 'Option<bool>', 'Yours.'],
      ['deadair', 'Option<Option<bool>>', 'Yours; <code>null</code> follows its OPML list’s.'],
      ['deadair_pause', 'Option<i64>', 'Yours: 200, 300, 400 or 500.'],
      ['private', 'Option<bool>', 'Anyone subscribed may mark it private; only an admin unmarks it.'],
      ['url', 'Option<String>', 'Admin.'], ['schedule', 'Option<Option<String>>', 'Admin.'],
      ['folder', 'Option<Option<String>>', 'Admin.'], ['category', 'Option<Option<String>>', 'Admin.'],
    ] },
    { name: 'Marked', doc: '', fields: [['marked', 'i64', 'How many episodes were marked.']] },
    { name: 'HowMany', doc: '', fields: [['count', 'i64', 'From 1 to 100; 5 if left out.']] },
    { name: 'Queued', doc: '', fields: [['queued', 'usize', 'How many files were queued.']] },
    { name: 'FetchBody', doc: 'What to check.', fields: [['feed', 'Option<String>', 'One feed; all of yours if left out.'], ['force', 'bool', 'Check even if it is not due.']] },
    { name: 'OpmlBody', doc: '', fields: [['xml', 'String', 'The OPML file’s text.']] },
    { name: 'Imported', doc: '', fields: [['added', 'usize', ''], ['already', 'usize', 'Feeds you had.']] },
    { name: 'Page', doc: 'Which episodes, as query parameters.', fields: [
      ['offset', 'i64', '0 if left out.'], ['limit', 'i64', '50 if left out.'],
      ['filter', 'Option<String>', '<code>unread</code>, <code>downloaded</code> or <code>flagged</code> (kept).'],
      ['q', 'Option<String>', 'Words to look for in titles and show notes.'],
      ['sort', 'Option<String>', '<code>published</code>, <code>title</code>, <code>feed</code>, <code>type</code>, <code>size</code> or <code>kept</code>. Newest first if left out.'],
      ['dir', 'Option<String>', '<code>asc</code> or <code>desc</code>.'],
    ] },
    { name: 'EntryPage', doc: 'A page of episodes.', fields: [['total', 'i64', 'How many match, over every page.'], ['entries', 'Vec<EntryRow>', '']] },
    { name: 'EntryRow', doc: 'An episode or post, with your state for it.', fields: [
      ['guid', 'String', ''], ['feed_id', 'String', ''], ['title', 'Option<String>', ''], ['link', 'Option<String>', ''],
      ['published', 'Option<i64>', ''],
      ['description', 'Option<String>', 'Show notes, HTML, already sanitized.'],
      ['read', 'bool', ''], ['flagged', 'bool', 'Kept: its file is never cleared to save space.'],
      ['image', 'Option<String>', ''], ['duration', 'Option<i64>', 'Seconds.'],
      ['episode', 'Option<i64>', ''], ['season', 'Option<i64>', ''],
      ['position', 'i64', 'Where you are in it, in seconds.'],
      ['enclosures', 'Vec<EncRow>', 'Its files.'],
    ] },
    { name: 'EncRow', doc: 'An episode’s file.', fields: [
      ['id', 'i64', 'What <code>/media/{id}</code> and the file routes take.'],
      ['feed_id', 'String', ''], ['guid', 'String', ''], ['url', 'String', 'Where the publisher has it.'],
      ['mime', 'Option<String>', ''], ['length', 'Option<i64>', 'Bytes.'],
      ['path', 'Option<String>', 'Where it is on the server, once downloaded.'],
      ['state', 'String', '<code>pending</code> (a check will download it), <code>held</code> (back catalogue, downloaded on request), <code>downloading</code>, <code>done</code>, <code>skipped</code> (a filter or a failure) or <code>reaped</code> (deleted).'],
      ['last_error', 'Option<String>', ''],
      ['deadair', 'Option<i64>', 'Seconds DeadAir saves, when you play it shortened. Absent otherwise.'],
      ['deadair_pending', 'bool', 'DeadAir is still working on it. Absent when false.'],
    ] },
    { name: 'Flags', doc: '', fields: [['read', 'Option<bool>', ''], ['flagged', 'Option<bool>', 'Kept.']] },
    { name: 'Position', doc: '', fields: [['secs', 'i64', 'Seconds in.'], ['duration', 'Option<i64>', 'The length the player measured, for an episode whose feed gives none.']] },
    { name: 'Force', doc: 'A query parameter.', fields: [['force', 'bool', 'Delete it even though someone else wants it.']] },
    { name: 'PopularRow', doc: 'A feed in the directory. Never its address: subscribe by its id.', fields: [
      ['id', 'String', 'The directory’s id for it.'], ['title', 'Option<String>', ''], ['image', 'Option<String>', ''],
      ['subscribers', 'i64', 'On every server sharing with the directory.'],
      ['subscribed', 'bool', 'Yours already.'], ['feed', 'Option<String>', 'Its id here, when it is yours.'],
      ['category', 'Option<String>', ''], ['subcategory', 'Option<String>', ''],
      ['podcast', 'bool', 'Has audio or video.'],
    ] },
    { name: 'Listed', doc: 'A feed’s page in the directory.', fields: [
      ['description', 'Option<String>', 'What it says it is, sanitized.'],
      ['failing', 'Option<String>', 'Why its last check failed, when it did.'],
      ['items', 'Vec<ListedItem>', 'Its latest twenty.'],
      ['can_admin', 'bool', 'You may remove or refresh it.'],
    ] },
    { name: 'ListedItem', doc: '', fields: [['guid', 'String', ''], ['title', 'Option<String>', ''], ['link', 'Option<String>', ''], ['published', 'Option<i64>', ''], ['duration', 'Option<i64>', ''], ['description', 'Option<String>', 'Sanitized.']] },
    { name: 'Subscribed', doc: '', fields: [['id', 'String', 'The feed’s id here.']] },
    { name: 'Status', doc: '', fields: [['feeds', 'usize', ''], ['pending', 'usize', 'Files a check will download.'], ['downloaded', 'usize', ''], ['version', 'String', '']] },
    { name: 'Event', doc: 'One live update. <code>ev</code> says which, and the rest depends on it.', fields: [
      ['feed_start', '{ feed }', 'A feed is being checked.'],
      ['feed_skip', '{ feed }', 'Not due.'],
      ['feed_done', '{ feed, new, downloaded, failed, torrents }', ''],
      ['feed_error', '{ feed, msg }', ''],
      ['feed_row', '{ row: FeedRow }', 'A feed you subscribe to changed.'],
      ['progress', '{ feed, enclosure, file, done, total }', 'Bytes of a download, in whole percents.'],
      ['download_done', '{ feed, enclosure, path, bytes }', ''],
      ['download_error', '{ feed, enclosure, msg, url }', ''],
      ['deadair_done', '{ feed, enclosure, saved_s }', 'DeadAir finished a file.'],
      ['scan_done', '{ feeds }', 'A check finished; how many feeds it looked at.'],
    ] },
    { name: 'Settings', doc: 'The server’s settings.', fields: [
      ['schedule', 'String', 'How often feeds are checked, such as <code>every 60m</code>.'], ['every_mins', 'u64', 'The same in minutes.'],
      ['max_new_per_check', 'usize', 'The newest episodes a check downloads, a feed.'],
      ['media_types', 'Vec<String>', 'What is downloaded, such as <code>audio</code>, <code>video</code>.'],
      ['download_dir', 'String', ''], ['max_total_gb', 'f64', 'Disk to use; 0 for no limit.'],
      ['max_age_days', 'u64', '0 for no limit.'], ['art_cache_mb', 'u64', 'Artwork kept.'],
      ['directory_url', 'String', ''], ['directory_token_set', 'bool', 'The token itself is never sent back.'],
      ['directory_share', 'bool', ''],
    ] },
    { name: 'SettingsPatch', doc: 'What <code>PATCH /api/settings</code> changes. Leave out what stays.', fields: [
      ['schedule', 'Option<String>', ''], ['max_new_per_check', 'Option<usize>', ''], ['media_types', 'Option<Vec<String>>', ''],
      ['max_total_gb', 'Option<f64>', ''], ['max_age_days', 'Option<u64>', ''], ['art_cache_mb', 'Option<u64>', ''],
      ['directory_url', 'Option<String>', 'Empty for no directory.'], ['directory_token', 'Option<String>', 'Replaces it; empty clears it.'],
      ['directory_share', 'Option<bool>', ''],
    ] },
    { name: 'UserRow', doc: 'An account.', fields: [['id', 'i64', ''], ['name', 'String', ''], ['admin', 'bool', ''], ['password', 'bool', 'Has one; without, it signs in only by single sign-on.'], ['created', 'Option<i64>', ''], ['last_login', 'Option<i64>', '']] },
    { name: 'NewUser', doc: '', fields: [['name', 'String', 'No commas, semicolons or line breaks.'], ['password', 'String', 'Empty for single sign-on only.'], ['admin', 'bool', '']] },
    { name: 'UserPatch', doc: '', fields: [['admin', 'bool', '']] },
    { name: 'LogQuery', doc: 'Query parameters.', fields: [['after', 'u64', 'The last <code>seq</code> you have; 0 for the newest lines.'], ['limit', 'usize', '200 if left out.']] },
    { name: 'LogPage', doc: '', fields: [['lines', 'Vec<LogLine>', ''], ['latest', 'u64', 'The newest <code>seq</code>, to ask after next time.']] },
    { name: 'LogLine', doc: '', fields: [['seq', 'u64', ''], ['ts', 'i64', ''], ['level', 'String', ''], ['target', 'String', ''], ['msg', 'String', '']] },
    { name: 'DirectoryStatus', doc: '', fields: [
      ['configured', 'bool', 'An address and token are set.'], ['name', 'Option<String>', 'The token’s name, as the directory knows it.'],
      ['access', 'Option<String>', '<code>ro</code>, <code>rw</code> or <code>rwa</code>.'], ['error', 'Option<String>', 'Why the directory would not say.'],
      ['shared', 'Option<SnapshotResult>', 'How the last share went.'],
    ] },
    { name: 'DirectoryAdmin', doc: '', fields: [['instances', 'Vec<Instance>', 'Servers sharing.'], ['blocked', 'Vec<BlockedRow>', '']] },
    { name: 'BlockedRow', doc: 'A feed the directory keeps out. Never its address.', fields: [['id', 'String', ''], ['title', 'Option<String>', ''], ['at', 'i64', 'When.']] },
    { name: 'Instance', doc: 'A server sharing with the directory.', fields: [['name', 'String', 'Its token’s name.'], ['feeds', 'i64', ''], ['subscribers', 'i64', '']] },
    { name: 'SnapshotResult', doc: 'What the directory made of a share.', fields: [['accepted', 'usize', ''], ['refused_private', 'usize', 'Addresses that look like someone’s paid access.'], ['refused_blocked', 'usize', ''], ['refused_invalid', 'usize', 'Not http(s).']] },
  ],
};

export const directory = {
  name: 'ipx_directory',
  label: 'ipx-directory',
  root: '/docs/api/directory',
  changelog: 'crates/directory/CHANGELOG.md',
  intro: `<p>The HTTP API of the directory of public podcasts that iPX servers share, at
    <code>${D}/v1</code>. Its pages at <a href="${D}">${D.replace('https://', '')}</a> are anyone’s
    to browse; the API needs a token for everything.</p>
    <h2 id="auth">Tokens</h2>
    <pre><code>Authorization: Bearer &lt;token&gt;</code></pre>
    <p>A token has a name and one of three levels of access: <code>ro</code> reads,
    <code>rw</code> also shares, and <code>rwa</code> also removes and blocks feeds and drops a
    server’s share. Tokens are given out by whoever runs the directory, and none can be made or
    revoked over the API.</p>
    <h2 id="errors">Errors</h2>
    <p>A request that fails answers with its status and <code>{"error": "…"}</code>:
    <code>401</code> no token or an unknown one, <code>403</code> a token without the access,
    <code>404</code> not listed.</p>
    <h2 id="ids">Ids</h2>
    <p>A feed’s <code>id</code> is the first 16 hex digits of the SHA-256 of its address with the
    scheme and host in lower case and no default port or fragment, so every server arrives at the
    same one. Descriptions are the publisher’s own HTML, unsanitized: sanitize them before you
    show them.</p>`,
  groups: [
    {
      id: 'feeds', name: 'feeds', title: 'Feeds',
      summary: 'What the directory lists.',
      items: [
        {
          method: 'GET', path: '/v1/me', slug: 'get-me', access: 'ro',
          summary: 'The token’s name and access.', returns: 'Me', example: dirCurl('GET', '/v1/me'),
        },
        {
          method: 'GET', path: '/v1/feeds', slug: 'get-feeds', access: 'ro',
          summary: 'Every feed listed, A to Z.', returns: 'Vec<Listing>', example: dirCurl('GET', '/v1/feeds'),
        },
        {
          method: 'GET', path: '/v1/popular', slug: 'get-popular', access: 'ro',
          summary: 'The most subscribed feeds.', query: 'Limit', returns: 'Vec<Listing>',
          example: dirCurl('GET', '/v1/popular?limit=5'),
        },
        {
          method: 'GET', path: '/v1/feeds/{id}', slug: 'get-feed', access: 'ro',
          summary: 'One feed, with its description and latest twenty items.',
          pathParams: [['id', 'String', 'The feed’s id.']],
          returns: 'FeedPage', errors: [['404 Not Found', 'Not listed.']],
        },
        {
          method: 'GET', path: '/healthz', slug: 'get-healthz', access: 'none',
          summary: '<code>ok</code> when the directory can read its database.', returns: 'text/plain',
        },
      ],
    },
    {
      id: 'share', name: 'share', title: 'Sharing',
      summary: 'A server telling the directory what its people follow.',
      items: [
        {
          method: 'POST', path: '/v1/snapshot', slug: 'post-snapshot', access: 'rw',
          summary: 'Share: every public feed this server’s people follow, and how many follow each.',
          doc: '<p>Replaces everything this token shared before, so send the whole list each time. At most 20,000 feeds. Addresses that look private (a login, a key in the query, a paid-feed host) are refused and counted, never stored. A feed is listed once the directory has read it as one.</p>',
          body: 'Vec<SnapshotEntry>', returns: 'SnapshotResult',
          errors: [['413 Payload Too Large', 'More than 20,000 feeds.']],
          example: dirCurl('POST', '/v1/snapshot', '[{"url":"https://feeds.99percentinvisible.org/99percentinvisible","subscribers":3}]'),
        },
      ],
    },
    {
      id: 'admin', name: 'admin', title: 'Administering it',
      summary: 'Removing and blocking feeds, and the servers sharing. <code>rwa</code> tokens only.',
      items: [
        {
          method: 'DELETE', path: '/v1/feeds/{id}', slug: 'delete-feed', access: 'rwa',
          summary: 'Remove a feed and block it, so no server’s share brings it back.',
          pathParams: [['id', 'String', 'The feed’s id.']], returns: '204 No Content',
        },
        {
          method: 'POST', path: '/v1/feeds/{id}/refresh', slug: 'post-refresh', access: 'rwa',
          summary: 'Check a feed now, answering with its page.',
          pathParams: [['id', 'String', 'The feed’s id.']], returns: 'FeedPage',
        },
        {
          method: 'GET', path: '/v1/blocked', slug: 'get-blocked', access: 'rwa',
          summary: 'The feeds kept out.', returns: 'Vec<Blocked>',
        },
        {
          method: 'DELETE', path: '/v1/blocked/{id}', slug: 'delete-blocked', access: 'rwa',
          summary: 'Let a blocked feed back in.',
          pathParams: [['id', 'String', 'The feed’s id.']], returns: '204 No Content',
        },
        {
          method: 'GET', path: '/v1/instances', slug: 'get-instances', access: 'rwa',
          summary: 'Each token holding a share, with how many feeds and subscribers it gave.',
          returns: 'Vec<Instance>',
        },
        {
          method: 'DELETE', path: '/v1/instances/{name}', slug: 'delete-instance', access: 'rwa',
          summary: 'Drop one token’s share, its counts with it, until it next shares.',
          doc: '<p>To keep a server out for good, revoke its token instead.</p>',
          pathParams: [['name', 'String', 'The token’s name.']], returns: '204 No Content',
        },
      ],
    },
  ],
  types: [
    { name: 'Me', doc: 'A token, as the directory knows it.', fields: [['name', 'String', ''], ['access', 'Access', '']] },
    { name: 'Access', doc: 'A token’s access: <code>"ro"</code>, <code>"rw"</code> or <code>"rwa"</code>.', fields: [] },
    { name: 'Limit', doc: 'A query parameter.', fields: [['limit', 'Option<u64>', 'From 1 to 100; 10 if left out.']] },
    { name: 'Listing', doc: 'A feed listed.', fields: [
      ['id', 'String', ''], ['url', 'String', 'Its address, to subscribe to anywhere.'], ['title', 'Option<String>', ''], ['image', 'Option<String>', ''],
      ['category', 'Option<String>', 'Apple’s category, from the feed’s own.'], ['subcategory', 'Option<String>', ''],
      ['podcast', 'bool', 'Audio or video in its latest items.'],
      ['subscribers', 'i64', 'Summed over every server’s latest share.'],
    ] },
    { name: 'FeedPage', doc: 'A feed’s page: every field of <a href="/docs/api/directory/types/Listing"><code>Listing</code></a>, and these.', fields: [
      ['description', 'Option<String>', 'The feed’s own HTML, unsanitized.'],
      ['failing', 'Option<String>', 'Why its last check failed, in words.'],
      ['items', 'Vec<Item>', 'Its latest twenty.'],
    ] },
    { name: 'Item', doc: 'An episode or post. Never its file.', fields: [['guid', 'String', ''], ['title', 'Option<String>', ''], ['link', 'Option<String>', ''], ['published', 'Option<i64>', 'Unix seconds.'], ['duration', 'Option<i64>', 'Seconds.'], ['description', 'Option<String>', 'Unsanitized.']] },
    { name: 'SnapshotEntry', doc: 'One feed in a share.', fields: [['url', 'String', ''], ['subscribers', 'i64', ''], ['category', 'Option<String>', 'A category for a feed that names none itself.']] },
    { name: 'SnapshotResult', doc: 'What the directory made of a share.', fields: [['accepted', 'usize', ''], ['refused_private', 'usize', ''], ['refused_blocked', 'usize', ''], ['refused_invalid', 'usize', 'Not http(s).']] },
    { name: 'Blocked', doc: '', fields: [['id', 'String', ''], ['url', 'Option<String>', ''], ['title', 'Option<String>', ''], ['at', 'i64', 'When.']] },
    { name: 'Instance', doc: '', fields: [['name', 'String', 'The token’s name.'], ['feeds', 'i64', ''], ['subscribers', 'i64', '']] },
  ],
};