# SSB Client-kit Spec: Common Queries & UX guidelines

The main things clients need to do. This can evolve into a more detailed specification, maybe implemented by a high-level library or by #patchql.

Started by cinnamon on 2019-06-26

Inspirations:
* [Building Consentful Tech](http://www.consentfultech.io/CTZine.pdf)
* [Design Justice](http://designjusticenetwork.org/network-principles)
* [Data Feminism](https://bookbook.pubpub.org/data-feminism)
* [Web Content Accessibility Guidelines](https://www.w3.org/TR/2008/REC-WCAG20-20081211/#guidelines)

Layers from high level to low level
* [SSB principles](https://www.scuttlebutt.nz/principles/)
* UX principles (below)
* Agreement on schema for common message types
* API / library for clients to use (below)
* drivers for the client library to talk to the backend (patchql, hermie-box, cooler)
* scuttlebot process which replicates with other nodes
* [replication protocol](https://ssbc.github.io/scuttlebutt-protocol-guide/)

# UX principles

Users decide what they want to see - freedom of attention / free listening
* Blocking, blur blocked profile images, etc
* Share the labor of blocking within a community - protect each other
* Control what social radius you want to see
* Limit contact with strangers if you want to
* Hide channels and words

Users decide who can see them and their content - choose your audience
* Privacy settings, private messages, respect blocks and deletions
* Understandable privacy implications for all actions

Users own their data; their profile is their space
* Deletion of posts

Accessible by a diversity of humans
* Screen reader support, keyboard shortcuts, font settings, etc. [WCAG](https://www.w3.org/TR/2008/REC-WCAG20-20081211/#guidelines) is a good list of these needs
* Control resource usage (bandwidth, storage) - important for low-income accessibility

"Calm technology", anxiety reducing design, no dark patterns
* Can hide notifications, turn off animations and images
* Authors can use content warnings to be gentle with their audience

Systemic health
* Default semi-centralized blocklists with healthy human power structures around them
* Impersonation defenses
* Preserve context around posts
* Illegibile, unspiderable, unprofitable, uncapturable
* Warrens, not plazas

# Client API / library functions and queries

## Posts, threads, messages

Some of the use cases below could be combined into more general functions. Each of these will also need more options like pagination and filtering.

Options
* filter by message type
* filter by number of hops
* blocking policies
* exclude posts with certain channels or words?
* exclude blocked users?
* exclude people blocked by N of your friends?
* exclude people blocked by various kinds of blocklists?
* follow hops across pubs?
* forward or reverse chronological order
* pagination
* only count the items in the query, don't return the content
* async mode - streams, promises, async-iterables, ???

Algorithmic feed sorting?
* sort by relevance (for search views)
* prioritize users who are closer to you in some way
* prioritize posts from users who post rarely
* algorithmic spam filtering

Get the default view (messages related to people you follow)

Get messages for a channel

Get messages for all channels you're subscribed to

Get messages related to a user (authored by, liked, follow events, block events...)

Get messages by message type (gatherings, ...)

Get a complete thread

Get a single message and its metadata and backlinks

Get threads you're participating in

Get threads started by you

Get mentions

Get recently used channel names

Get recently used tags

Get messages by tag

## Search

Search by user, blob, message, channel, tag, or full text

List of usernames sorted by how connected you are to them (for @mention autocompletion)

Search images/blobs

## Publishing

Publish a post / comment / blog
* content warning field (TBD)
* comments: only show from friends, or disable? (TBD)

Publish a private message

Publish a blob

Delete-request a message

Delete-request a blob?

Publish/edit a gathering

Like/react to a post

(Un)Tag a post (public or private)

(Un)Subscribe to a channel (public or private)

## Private messages

Get feed of private messages

## Private groups

?

## Nicknames & 3rd party avatars

Get for a user, respecting blocks, only showing from appropriate people (TBD)

Set for a user

## Social graph & blocking

Follow/unfollow

Block/unblock and Ignore/unignore (private block)

List of blocked users and who blocked them

List of people you blocked

List of people blocking you (? maybe best to skip this one)

Some kind of invite code system to find friends more easily
* Invite code is their feed ID + a pub they're on?
* DHT?

Get/set list of words and channels you want to hide (stored as private message or as client-specific setting?)

Other blocking policies, like
* hide people who are blocked by N of your friends
* hide everyone who is following a certain account (like an abusive public figure)
* hide everyone followed by a certain account (like a pub)
* inherit another users' blocks
* shared blocklists (not specified yet)
* semi-centralized blocklists?

## User profiles

Get current user's identity

Get a user profile

Set your user profile

Get/set `sameAs` data for your account

Get the set of `sameAs` feeds for a user

Get a user's tags

Get a user's subscribed channels

Get a list of channels used in the user's posts

List of "Who to follow" users - this requires some thought; how do we choose them?

## Blobs

Get a blob data

## Privacy settings

Get & set public web gateway visibility

## Resource management

Get info about storage space used by feeds & blobs

"Clear cache", remove blobs, compact the log

## Pubs

Join a pub by invite code

List pubs following you (hosting your content)

List pubs you're following (bringing people into your social radius)

List all pubs?

## Syncing & indexing

List peers you're connecting to right now (pubs and local peers)

Get indexing progress bar info

## Low-level settings and state

List local SSB identities & create new ones (and set scuttleverse cap key)

Get/set replication hops

Control which pubs you connect to

Turn local peer finding on/off

Seen/unseen status of messages

Tor settings?

## Utilities

Render markdown to HTML & handle emojis
* [ssb-markdown](https://github.com/ssbc/ssb-markdown) handles this

Author markdown, autocomplete emojicodes and @usernames

Hash-based avatar images or colors

Remove location metadata from images that you post

## Client-specific settings

These settings are specific to the client you're in and will not be saved to your SSB feed.

Safe reading mode
* hide people you're not directly following and all their content, notifications, mentions, private messages, etc etc
* hide "who to follow" or limit its radius
* hide pub names and icons; click to show them

Hide a specific thread so it won't keep popping to the top of your feed

Font size, font color, contrast, color-blind-safe colors, font typeface (e.g. dyslexia fonts)

Grayscale mode

Infinite scroll on/off

Disable images or click-to-view them

Disable animated images

Disable unread notification badges

Auto-expand content warnings

Hide / de-emphasize engagement stats and numbers (follower count, like count, etc)

Keyboard shortcuts

Image alt-text

Spellcheck