liz/PluralKit
liz/PluralKit
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update documentation for privacy changes

Browse Source
This commit is contained in:
Ske 2020-06-17 21:55:39 +02:00
parent e92700f339
commit 327cd0aafd
2 changed files with 22 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
docs/2-user-guide.md
View File

@ -449,35 +449,33 @@ For example:
When the **member list** is **private**, other users will not be able to view the full member list of your system, but they can still query individual members given their 5-letter ID. If **current fronter** is private, but **front history** isn't, someone can still see the current fronter by looking at the history (this combination doesn't make much sense). When the **member list** is **private**, other users will not be able to view the full member list of your system, but they can still query individual members given their 5-letter ID. If **current fronter** is private, but **front history** isn't, someone can still see the current fronter by looking at the history (this combination doesn't make much sense).
### Member privacy ### Member privacy
There are also nine options for configuring member privacy; There are also six options for configuring member privacy;
- Name - Name
- Description - Description
- Birthday - Birthday
- Pronouns - Pronouns
- Colour - Metadata *(message count, creation date, etc)*
- Date created - Visibility *(whether the member shows up in member lists)*
- Message count
- Visibility
As with system privacy, each can be set to **public** or **private**. The same rules apply for how they are shown too. When set to **public**, anyone who queries your system (by account or system ID, or through the API), will see this information. When set to **private**, the information will only be shown when *you yourself* query the information. The cards will still be displayed in the channel the commands are run in, so it's still your responsibility not to pull up information in servers where you don't want it displayed. As with system privacy, each can be set to **public** or **private**. The same rules apply for how they are shown, too. When set to **public**, anyone who queries your system (by account or system ID, or through the API), will see this information. When set to **private**, the information will only be shown when *you yourself* query the information. The cards will still be displayed in the channel the commands are run in, so it's still your responsibility not to pull up information in servers where you don't want it displayed.
However there are two catches. When name is set to private, it will be replaced by a members display name, but only if they have one! When visibility is set to private, the member will not show up in the member list unless -all is used in the command (and you are part of the system). However, there are two catches:
- When the **name** is set to private, it will be replaced by the member's **display name**, but only if they have one! If the member has no display name, **name privacy will not do anything**. PluralKit still needs some way to refer to a member by name :)
Member info will not be shown in member lists even if someone in the system queries the list, unless the user is part of the system and uses the -all flag. - When **visibility** is set to private, the member will not show up in member lists unless `-all` is used in the command (and you are part of the system).
To update a members privacy you can use the command: To update a members privacy you can use the command:
member <member> privacy <subject> <level> member <member> privacy <subject> <level>
where `<member>` is the name or the id of a member in your system, `<subject>` is either `name`, `description`, `birthday`, `pronouns`, `color`, `metadata`, or `visiblity` corresponding to the options above, and `<level>` is either `public` or `private`. `<subject>` can also be `all` in order to change all subjects at once. where `<member>` is the name or the id of a member in your system, `<subject>` is either `name`, `description`, `birthday`, `pronouns`, `metadata`, or `visiblity` corresponding to the options above, and `<level>` is either `public` or `private`. `<subject>` can also be `all` in order to change all subjects at once.
`metatdata` will affect the message count, the date created, the last fronted, and the last message information. `metatdata` will affect the message count, the date created, the last fronted, and the last message information.
For example: For example:
pk;member John privacy visibility private pk;member John privacy visibility private
pk;member "Craig Johnson" privacy description public pk;member "Craig Johnson" privacy description public
pk;member Robert privacy color public pk;member Robert privacy birthday public
pk;member Skyler privacy all private pk;member Skyler privacy all private
## Moderation commands ## Moderation commands

45
docs/4-api-documentation.md
View File

@ -70,9 +70,7 @@ The following three models (usually represented in JSON format) represent the va
|description_privacy|string?|Yes|Patching with `private` will set it to private; `public` or `null` will set it to public.| |description_privacy|string?|Yes|Patching with `private` will set it to private; `public` or `null` will set it to public.|
|birthday_privacy|string?|Yes|Patching with `private` will set it to private; `public` or `null` will set it to public.| |birthday_privacy|string?|Yes|Patching with `private` will set it to private; `public` or `null` will set it to public.|
|pronoun_privacy|string?|Yes|Patching with `private` will set it to private; `public` or `null` will set it to public.| |pronoun_privacy|string?|Yes|Patching with `private` will set it to private; `public` or `null` will set it to public.|
|color_privacy|string?|Yes|Patching with `private` will set it to private; `public` or `null` will set it to public.| |metadata_privacy|string?|Yes|Patching with `private` will set it to private; `public` or `null` will set it to public.|
|message_count_privacy|string?|Yes|Patching with `private` will set it to private; `public` or `null` will set it to public.|
|created_timestamp_privacy|string?|Yes|Patching with `private` will set it to private; `public` or `null` will set it to public.|
#### ProxyTag object #### ProxyTag object
@ -178,9 +176,7 @@ If the request is not authenticated with the system's token, members marked as p
"description_privacy": null, "description_privacy": null,
"birthday_privacy": null, "birthday_privacy": null,
"pronoun_privacy": null, "pronoun_privacy": null,
"color_privacy": null, "metadata_privacy": null
"message_count_privacy": null,
"created_timestamp_privacy": null
} }
] ]
``` ```
@ -240,9 +236,7 @@ If the system has chosen to hide its current fronters, this will return `403 For
"description_privacy": null, "description_privacy": null,
"birthday_privacy": null, "birthday_privacy": null,
"pronoun_privacy": null, "pronoun_privacy": null,
"color_privacy": null, "metadata_privacy": null,
"message_count_privacy": null,
"created_timestamp_privacy": null,
"created": "2019-01-01T15:00:00.654321Z" "created": "2019-01-01T15:00:00.654321Z"
} }
] ]
@ -307,7 +301,7 @@ Registers a new switch to your own system given a list of member IDs.
### GET /m/\<id> ### GET /m/\<id>
Queries a member's information by its 5-character member ID. If the member does not exist, will return `404 Not Found`. Queries a member's information by its 5-character member ID. If the member does not exist, will return `404 Not Found`.
If this member is marked private, and the request isn't authenticated with the member's system's token, some fields (currently only `description`) will contain `null` rather than the true value. Regardless of privacy setting, a non-authenticated request will only receive `null` for the `privacy` field. If this member is marked private, and the request isn't authenticated with the member's system's token, some fields will contain `null` rather than the true value (corresponding with the privacy settings). Regardless of privacy setting, a non-authenticated request will only receive `null` for the privacy fields (and `visibility`).
#### Example request #### Example request
GET https://api.pluralkit.me/v1/m/qwert GET https://api.pluralkit.me/v1/m/qwert
@ -330,9 +324,7 @@ If this member is marked private, and the request isn't authenticated with the m
"description_privacy": "private", "description_privacy": "private",
"birthday_privacy": "private", "birthday_privacy": "private",
"pronoun_privacy": "public", "pronoun_privacy": "public",
"color_privacy": "public", "metadata_privacy": "public"
"message_count_privacy": "private",
"created_timestamp_privacy": "public"
} }
``` ```
@ -359,9 +351,7 @@ Creates a new member with the information given. Missing fields (except for name
"description_privacy": "private", "description_privacy": "private",
"birthday_privacy": "private", "birthday_privacy": "private",
"pronoun_privacy": "public", "pronoun_privacy": "public",
"color_privacy": "public", "metadata_privacy": "private"
"message_count_privacy": "private",
"created_timestamp_privacy": "public"
} }
``` ```
(note the absence of a `proxy_tags` field, which is cleared in the response) (note the absence of a `proxy_tags` field, which is cleared in the response)
@ -385,9 +375,7 @@ Creates a new member with the information given. Missing fields (except for name
"description_privacy": "private", "description_privacy": "private",
"birthday_privacy": "private", "birthday_privacy": "private",
"pronoun_privacy": "public", "pronoun_privacy": "public",
"color_privacy": "public", "metadata_privacy": "private"
"message_count_privacy": "private",
"created_timestamp_privacy": "public"
} }
``` ```
@ -414,9 +402,7 @@ Edits a member's information. Missing fields will keep their current values. Wil
"description_privacy": "private", "description_privacy": "private",
"birthday_privacy": "private", "birthday_privacy": "private",
"pronoun_privacy": "public", "pronoun_privacy": "public",
"color_privacy": "public", "metadata_privacy": "private"
"message_count_privacy": "private",
"created_timestamp_privacy": "public"
} }
``` ```
(note the absence of a `proxy_tags` field, which keeps its old value in the response) (note the absence of a `proxy_tags` field, which keeps its old value in the response)
@ -440,9 +426,7 @@ Edits a member's information. Missing fields will keep their current values. Wil
"description_privacy": "private", "description_privacy": "private",
"birthday_privacy": "private", "birthday_privacy": "private",
"pronoun_privacy": "public", "pronoun_privacy": "public",
"color_privacy": "public", "metadata_privacy": "private"
"message_count_privacy": "private",
"created_timestamp_privacy": "public"
} }
``` ```
@ -523,18 +507,15 @@ The returned system and member's privacy settings will be respected, and as such
"description_privacy": "private", "description_privacy": "private",
"birthday_privacy": "private", "birthday_privacy": "private",
"pronoun_privacy": "public", "pronoun_privacy": "public",
"color_privacy": "public", "metadata_privacy": "private"
"message_count_privacy": "private",
"created_timestamp_privacy": "public"
} }
} }
``` ```
## Version history ## Version history
<!-- (Update this on official release) --> * 2020-06-17
* 2020-05-14 * The API now has values for granular member privacy. The new fields are as follows: `visibility`, `name_privacy`, `description_privacy`, `birthday_privacy`, `pronoun_privacy`, `metadata_privacy`. All are strings and accept the values of `public`, `private` and `null`
* The API now has values for granular member privacy. The new fields are as follows: `visibility`, `name_privacy`, `description_privacy`, `birthday_privacy`, `pronoun_privacy`, `color_privacy`, `message_count_privacy`, and `created_timestamp_privacy`. All are strings and accept the values of `public`, `private` and `null` * The `privacy` field has now been deprecated and should not be used. It's still returned (mirroring the `visibility` field), and writing to it will write to *all privacy options*.
* The `privacy` field has now been deprecated and should not be used. It is a reflection of visibility.
* 2020-05-07 * 2020-05-07
* The API (v1) is now formally(ish) defined with OpenAPI v3.0. [The definition file can be found here.](https://github.com/xSke/PluralKit/blob/master/PluralKit.API/openapi.yaml) * The API (v1) is now formally(ish) defined with OpenAPI v3.0. [The definition file can be found here.](https://github.com/xSke/PluralKit/blob/master/PluralKit.API/openapi.yaml)
* 2020-02-10 * 2020-02-10