From e62f8542a1933ba71dfd236741ad3afc76b89f22 Mon Sep 17 00:00:00 2001 From: lain Date: Mon, 27 Apr 2020 13:48:09 +0200 Subject: Docs: Add chat motivation and api description. --- docs/API/chats.md | 197 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 docs/API/chats.md (limited to 'docs/API') diff --git a/docs/API/chats.md b/docs/API/chats.md new file mode 100644 index 000000000..39f493b47 --- /dev/null +++ b/docs/API/chats.md @@ -0,0 +1,197 @@ +# Chats + +Chats are a way to represent an IM-style conversation between two actors. They are not the same as direct messages and they are not `Status`es, even though they have a lot in common. + +## Why Chats? + +There are no 'visibility levels' in ActivityPub, their definition is purely a Mastodon convention. Direct Messaging between users on the fediverse has mostly been modeled by using ActivityPub addressing following Mastodon conventions on normal `Note` objects. In this case, a 'direct message' would be a message that has no followers addressed and also does not address the special public actor, but just the recipients in the `to` field. It would still be a `Note` and is presented with other `Note`s as a `Status` in the API. + +This is an awkward setup for a few reasons: + +- As DMs generally still follow the usual `Status` conventions, it is easy to accidentally pull somebody into a DM thread by mentioning them. (e.g. "I hate @badguy so much") +- It is possible to go from a publicly addressed `Status` to a DM reply, back to public, then to a 'followers only' reply, and so on. This can be become very confusing, as it is unclear which user can see which part of the conversation. +- The standard `Status` format of implicit addressing also leads to rather ugly results if you try to display the messages as a chat, because all the recipients are always mentioned by name in the message. +- As direct messages are posted with the same api call (and usually same frontend component) as public messages, accidentally making a public message private or vice versa can happen easily. Client bugs can also lead to this, accidentally making private messages public. + +As a measure to improve this situation, the `Conversation` concept and related Pleroma extensions were introduced. While it made it possible to work around a few of the issues, many of the problems remained and it didn't see much adoption because it was too complicated to use correctly. + +## Chats explained +For this reasons, Chats are a new and different entity, both in the API as well as in ActivityPub. A quick overview: + +- Chats are meant to represent an instant message conversation between two actors. For now these are only 1-on-1 conversations, but the other actor can be a group in the future. +- Chat messages have the ActivityPub type `ChatMessage`. They are not `Note`s. Servers that don't understand them will just drop them. +- The only addressing allowed in `ChatMessage`s is one single ActivityPub actor in the `to` field. +- There's always only one Chat between two actors. If you start chatting with someone and later start a 'new' Chat, the old Chat will be continued. +- `ChatMessage`s are posted with a different api, making it very hard to accidentally send a message to the wrong person. +- `ChatMessage`s don't show up in the existing timelines. +- Chats can never go from private to public. They are always private between the two actors. + +## Caveats + +- Chats are NOT E2E encrypted (yet). Security is still the same as email. + +## API + +In general, the way to send a `ChatMessage` is to first create a `Chat`, then post a message to that `Chat`. The actors in the API are generally given by their ActivityPub id to make it easier to support later `Group` scenarios. + +This is the overview of using the API. The API is also documented via OpenAPI, so you can view it and play with it by pointing SwaggerUI or a similar OpenAPI tool to `https://yourinstance.tld/api/openapi`. + +### Creating or getting a chat. + +To create or get an existing Chat for a certain recipient (identified by AP ID) +you can call: + +`POST /api/v1/pleroma/chats/by-ap-id/{ap_id}` + +The ap_id of the recipients needs to be www-form encoded, so + +``` +https://originalpatchou.li/user/lambda +``` + +would become + +``` +https%3A%2F%2Foriginalpatchou.li%2Fuser%2Flambda +``` + +The full call would then be + +``` +POST /api/v1/pleroma/chats/by-ap-id/https%3A%2F%2Foriginalpatchou.li%2Fuser%2Flambda +``` + +There will only ever be ONE Chat for you and a given recipient, so this call +will return the same Chat if you already have one with that user. + +Returned data: + +```json +{ + "recipient" : "https://dontbulling.me/users/lain", + "recipient_account": { + "id": "someflakeid", + "username": "somenick", + ... + }, + "id" : "1", + "unread" : 2 +} +``` + +### Getting a list of Chats + +`GET /api/v1/pleroma/chats` + +This will return a list of chats that you have been involved in, sorted by their +last update (so new chats will be at the top). + +Returned data: + +```json +[ + { + "recipient" : "https://dontbulling.me/users/lain", + "recipient_account": { + "id": "someflakeid", + "username": "somenick", + ... + }, + "id" : "1", + "unread" : 2 + } +] +``` + +The recipient of messages that are sent to this chat is given by their AP ID. +The usual pagination options are implemented. + +### Getting the messages for a Chat + +For a given Chat id, you can get the associated messages with + +`GET /api/v1/pleroma/chats/{id}/messages` + +This will return all messages, sorted by most recent to least recent. The usual +pagination options are implemented + +Returned data: + +```json +[ + { + "actor": "https://dontbulling.me/users/lain", + "chat_id": "1", + "content": "Check this out :firefox:", + "created_at": "2020-04-21T15:11:46.000Z", + "emojis": [ + { + "shortcode": "firefox", + "static_url": "https://dontbulling.me/emoji/Firefox.gif", + "url": "https://dontbulling.me/emoji/Firefox.gif", + "visible_in_picker": false + } + ], + "id": "13" + }, + { + "actor": "https://dontbulling.me/users/lain", + "chat_id": "1", + "content": "Whats' up?", + "created_at": "2020-04-21T15:06:45.000Z", + "emojis": [], + "id": "12" + } +] +``` + +### Posting a chat message + +Posting a chat message for given Chat id works like this: + +`POST /api/v1/pleroma/chats/{id}/messages` + +Parameters: +- content: The text content of the message + +Currently, no formatting beyond basic escaping and emoji is implemented, as well as no +attachments. This will most probably change. + +Returned data: + +```json +{ + "actor": "https://dontbulling.me/users/lain", + "chat_id": "1", + "content": "Check this out :firefox:", + "created_at": "2020-04-21T15:11:46.000Z", + "emojis": [ + { + "shortcode": "firefox", + "static_url": "https://dontbulling.me/emoji/Firefox.gif", + "url": "https://dontbulling.me/emoji/Firefox.gif", + "visible_in_picker": false + } + ], + "id": "13" +} +``` + +### Notifications + +There's a new `pleroma:chat_mention` notification, which has this form: + +```json +{ + "id": "someid", + "type": "pleroma:chat_mention", + "account": { ... } // User account of the sender, + "chat_message": { + "chat_id": "1", + "id": "10", + "content": "Hello", + "actor": "https://dontbulling.me/users/lain" + }, + "created_at": "somedate" +} +``` -- cgit v1.2.3 From b550ef56119b9f735cf3fe279a5457e36ab92951 Mon Sep 17 00:00:00 2001 From: lain Date: Mon, 27 Apr 2020 17:52:16 +0200 Subject: Docs: Align chat api changes with docs. --- docs/API/chats.md | 36 +++++++++++------------------------- 1 file changed, 11 insertions(+), 25 deletions(-) (limited to 'docs/API') diff --git a/docs/API/chats.md b/docs/API/chats.md index 39f493b47..24c4b4d06 100644 --- a/docs/API/chats.md +++ b/docs/API/chats.md @@ -32,33 +32,21 @@ For this reasons, Chats are a new and different entity, both in the API as well ## API -In general, the way to send a `ChatMessage` is to first create a `Chat`, then post a message to that `Chat`. The actors in the API are generally given by their ActivityPub id to make it easier to support later `Group` scenarios. +In general, the way to send a `ChatMessage` is to first create a `Chat`, then post a message to that `Chat`. `Group`s will later be supported by making them a sub-type of `Account`. This is the overview of using the API. The API is also documented via OpenAPI, so you can view it and play with it by pointing SwaggerUI or a similar OpenAPI tool to `https://yourinstance.tld/api/openapi`. ### Creating or getting a chat. -To create or get an existing Chat for a certain recipient (identified by AP ID) +To create or get an existing Chat for a certain recipient (identified by Account ID) you can call: -`POST /api/v1/pleroma/chats/by-ap-id/{ap_id}` +`POST /api/v1/pleroma/chats/by-account-id/{account_id}` -The ap_id of the recipients needs to be www-form encoded, so +The account id is the normal FlakeId of the usre ``` -https://originalpatchou.li/user/lambda -``` - -would become - -``` -https%3A%2F%2Foriginalpatchou.li%2Fuser%2Flambda -``` - -The full call would then be - -``` -POST /api/v1/pleroma/chats/by-ap-id/https%3A%2F%2Foriginalpatchou.li%2Fuser%2Flambda +POST /api/v1/pleroma/chats/by-account-id/someflakeid ``` There will only ever be ONE Chat for you and a given recipient, so this call @@ -68,8 +56,7 @@ Returned data: ```json { - "recipient" : "https://dontbulling.me/users/lain", - "recipient_account": { + "account": { "id": "someflakeid", "username": "somenick", ... @@ -91,8 +78,7 @@ Returned data: ```json [ { - "recipient" : "https://dontbulling.me/users/lain", - "recipient_account": { + "account": { "id": "someflakeid", "username": "somenick", ... @@ -120,7 +106,7 @@ Returned data: ```json [ { - "actor": "https://dontbulling.me/users/lain", + "account_id": "someflakeid", "chat_id": "1", "content": "Check this out :firefox:", "created_at": "2020-04-21T15:11:46.000Z", @@ -135,7 +121,7 @@ Returned data: "id": "13" }, { - "actor": "https://dontbulling.me/users/lain", + "account_id": "someflakeid", "chat_id": "1", "content": "Whats' up?", "created_at": "2020-04-21T15:06:45.000Z", @@ -161,7 +147,7 @@ Returned data: ```json { - "actor": "https://dontbulling.me/users/lain", + "account_id": "someflakeid", "chat_id": "1", "content": "Check this out :firefox:", "created_at": "2020-04-21T15:11:46.000Z", @@ -190,7 +176,7 @@ There's a new `pleroma:chat_mention` notification, which has this form: "chat_id": "1", "id": "10", "content": "Hello", - "actor": "https://dontbulling.me/users/lain" + "account_id": "someflakeid" }, "created_at": "somedate" } -- cgit v1.2.3 From 528ea779a61d12f74ee9669bbd28783bf66aa5cc Mon Sep 17 00:00:00 2001 From: lain Date: Wed, 29 Apr 2020 17:56:24 +0000 Subject: Apply suggestion to docs/API/chats.md --- docs/API/chats.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/API') diff --git a/docs/API/chats.md b/docs/API/chats.md index 24c4b4d06..26e83570e 100644 --- a/docs/API/chats.md +++ b/docs/API/chats.md @@ -99,7 +99,7 @@ For a given Chat id, you can get the associated messages with `GET /api/v1/pleroma/chats/{id}/messages` This will return all messages, sorted by most recent to least recent. The usual -pagination options are implemented +pagination options are implemented. Returned data: -- cgit v1.2.3 From 7ff2a7dae2fa651cea579aeca40e2c030d19fcd5 Mon Sep 17 00:00:00 2001 From: lain Date: Mon, 4 May 2020 13:12:21 +0200 Subject: Docs: Add Chat mark_as_read docs --- docs/API/chats.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) (limited to 'docs/API') diff --git a/docs/API/chats.md b/docs/API/chats.md index 26e83570e..8d925989c 100644 --- a/docs/API/chats.md +++ b/docs/API/chats.md @@ -66,6 +66,27 @@ Returned data: } ``` +### Marking a chat as read + +To set the `unread` count of a chat to 0, call + +`POST /api/v1/pleroma/chats/:id/read` + +Returned data: + +```json +{ + "account": { + "id": "someflakeid", + "username": "somenick", + ... + }, + "id" : "1", + "unread" : 0 +} +``` + + ### Getting a list of Chats `GET /api/v1/pleroma/chats` -- cgit v1.2.3 From 4c197023903a183790fb2dc67b5637bfabd53bcb Mon Sep 17 00:00:00 2001 From: Roman Chvanikov Date: Sat, 9 May 2020 14:32:08 +0300 Subject: Add docs --- docs/API/admin_api.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/API') diff --git a/docs/API/admin_api.md b/docs/API/admin_api.md index c455047cc..fa74e7460 100644 --- a/docs/API/admin_api.md +++ b/docs/API/admin_api.md @@ -1096,6 +1096,10 @@ Loads json generated from `config/descriptions.exs`. ### Stats +- Query Params: + - *optional* `instance`: **string** instance hostname (without protocol) to get stats for +- Example: `https://mypleroma.org/api/pleroma/admin/stats?instance=lain.com` + - Response: ```json -- cgit v1.2.3 From e297d8c649a03510023cff61dc6e0c7131bc29dc Mon Sep 17 00:00:00 2001 From: lain Date: Sun, 10 May 2020 12:34:12 +0200 Subject: Documentation: Add attachment docs --- docs/API/chats.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/API') diff --git a/docs/API/chats.md b/docs/API/chats.md index 8d925989c..3ddc13541 100644 --- a/docs/API/chats.md +++ b/docs/API/chats.md @@ -160,6 +160,7 @@ Posting a chat message for given Chat id works like this: Parameters: - content: The text content of the message +- media_id: The id of an upload that will be attached to the message. Currently, no formatting beyond basic escaping and emoji is implemented, as well as no attachments. This will most probably change. -- cgit v1.2.3 From 17be3ff669865102848df034045eb2889eed3976 Mon Sep 17 00:00:00 2001 From: lain Date: Sun, 10 May 2020 13:01:20 +0200 Subject: Documentation: Add last_message to chat docs. --- docs/API/chats.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs/API') diff --git a/docs/API/chats.md b/docs/API/chats.md index 3ddc13541..1f6175f77 100644 --- a/docs/API/chats.md +++ b/docs/API/chats.md @@ -62,7 +62,8 @@ Returned data: ... }, "id" : "1", - "unread" : 2 + "unread" : 2, + "last_message" : {...} // The last message in that chat } ``` @@ -105,7 +106,8 @@ Returned data: ... }, "id" : "1", - "unread" : 2 + "unread" : 2, + "last_message" : {...} // The last message in that chat } ] ``` -- cgit v1.2.3 From 8cc8d960af87cdc1e2398a8470155b0930f43f5c Mon Sep 17 00:00:00 2001 From: lain Date: Sun, 10 May 2020 13:27:40 +0200 Subject: Documentation: Add GET /chats/:id --- docs/API/chats.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'docs/API') diff --git a/docs/API/chats.md b/docs/API/chats.md index 1f6175f77..ed160abd9 100644 --- a/docs/API/chats.md +++ b/docs/API/chats.md @@ -43,12 +43,17 @@ you can call: `POST /api/v1/pleroma/chats/by-account-id/{account_id}` -The account id is the normal FlakeId of the usre - +The account id is the normal FlakeId of the user ``` POST /api/v1/pleroma/chats/by-account-id/someflakeid ``` +If you already have the id of a chat, you can also use + +``` +GET /api/v1/pleroma/chats/:id +``` + There will only ever be ONE Chat for you and a given recipient, so this call will return the same Chat if you already have one with that user. -- cgit v1.2.3 From a61120f497e5d17be1207eacd11525edb7b6db36 Mon Sep 17 00:00:00 2001 From: lain Date: Tue, 12 May 2020 13:25:25 +0200 Subject: Documention: Add chat message deletion docs --- docs/API/chats.md | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'docs/API') diff --git a/docs/API/chats.md b/docs/API/chats.md index ed160abd9..ad36961ae 100644 --- a/docs/API/chats.md +++ b/docs/API/chats.md @@ -192,6 +192,14 @@ Returned data: } ``` +### Deleting a chat message + +Deleting a chat message for given Chat id works like this: + +`DELETE /api/v1/pleroma/chats/{chat_id}/messages/{message_id}` + +Returned data is the deleted message. + ### Notifications There's a new `pleroma:chat_mention` notification, which has this form: -- cgit v1.2.3 From 0f0acc740d30c47d093f27875d4decf0693b2845 Mon Sep 17 00:00:00 2001 From: lain Date: Wed, 13 May 2020 15:31:28 +0200 Subject: Chat: Allow posting without content if an attachment is present. --- docs/API/chats.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'docs/API') diff --git a/docs/API/chats.md b/docs/API/chats.md index ad36961ae..1ea18ff5f 100644 --- a/docs/API/chats.md +++ b/docs/API/chats.md @@ -166,11 +166,10 @@ Posting a chat message for given Chat id works like this: `POST /api/v1/pleroma/chats/{id}/messages` Parameters: -- content: The text content of the message +- content: The text content of the message. Optional if media is attached. - media_id: The id of an upload that will be attached to the message. -Currently, no formatting beyond basic escaping and emoji is implemented, as well as no -attachments. This will most probably change. +Currently, no formatting beyond basic escaping and emoji is implemented. Returned data: -- cgit v1.2.3 From 1d18721a3c60aa0acc7d1ba858a92277e544a54a Mon Sep 17 00:00:00 2001 From: lain Date: Fri, 15 May 2020 13:18:41 +0200 Subject: Chats: Add updated_at to Schema and docs. --- docs/API/chats.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'docs/API') diff --git a/docs/API/chats.md b/docs/API/chats.md index 1ea18ff5f..2e415e4da 100644 --- a/docs/API/chats.md +++ b/docs/API/chats.md @@ -68,7 +68,8 @@ Returned data: }, "id" : "1", "unread" : 2, - "last_message" : {...} // The last message in that chat + "last_message" : {...}, // The last message in that chat + "updated_at": "2020-04-21T15:11:46.000Z" } ``` @@ -88,7 +89,8 @@ Returned data: ... }, "id" : "1", - "unread" : 0 + "unread" : 0, + "updated_at": "2020-04-21T15:11:46.000Z" } ``` @@ -112,7 +114,8 @@ Returned data: }, "id" : "1", "unread" : 2, - "last_message" : {...} // The last message in that chat + "last_message" : {...}, // The last message in that chat + "updated_at": "2020-04-21T15:11:46.000Z" } ] ``` -- cgit v1.2.3 From 3249141588c8f73f1958f782041798fbde05e69f Mon Sep 17 00:00:00 2001 From: Alexander Strizhakov Date: Wed, 27 May 2020 09:42:28 +0300 Subject: validate actor type --- docs/API/admin_api.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) (limited to 'docs/API') diff --git a/docs/API/admin_api.md b/docs/API/admin_api.md index c455047cc..639c3224d 100644 --- a/docs/API/admin_api.md +++ b/docs/API/admin_api.md @@ -511,7 +511,23 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - `discoverable` - `actor_type` -- Response: none (code `200`) +- Response: + +```json +{"status": "success"} +``` + +```json +{"errors": + {"actor_type": "is invalid"}, + {"email": "has invalid format"}, + ... + } +``` + +```json +{"error": "Unable to update user."} +``` ## `GET /api/pleroma/admin/reports` -- cgit v1.2.3 From 394258d548d20d1bea50166bc31f8e48462080dd Mon Sep 17 00:00:00 2001 From: Alex Gleason Date: Thu, 28 May 2020 16:10:06 -0500 Subject: Docs: Attachement limitations in MastoAPI differences --- docs/API/differences_in_mastoapi_responses.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) (limited to 'docs/API') diff --git a/docs/API/differences_in_mastoapi_responses.md b/docs/API/differences_in_mastoapi_responses.md index e65fd5da4..434ade9a4 100644 --- a/docs/API/differences_in_mastoapi_responses.md +++ b/docs/API/differences_in_mastoapi_responses.md @@ -6,10 +6,6 @@ A Pleroma instance can be identified by " (compatible; Pleroma Pleroma uses 128-bit ids as opposed to Mastodon's 64 bits. However just like Mastodon's ids they are lexically sortable strings -## Attachment cap - -Some apps operate under the assumption that no more than 4 attachments can be returned or uploaded. Pleroma however does not enforce any limits on attachment count neither when returning the status object nor when posting. - ## Timelines Adding the parameter `with_muted=true` to the timeline queries will also return activities by muted (not by blocked!) users. @@ -32,12 +28,20 @@ Has these additional fields under the `pleroma` object: - `thread_muted`: true if the thread the post belongs to is muted - `emoji_reactions`: A list with emoji / reaction maps. The format is `{name: "☕", count: 1, me: true}`. Contains no information about the reacting users, for that use the `/statuses/:id/reactions` endpoint. -## Attachments +## Media Attachments Has these additional fields under the `pleroma` object: - `mime_type`: mime type of the attachment. +### Attachment cap + +Some apps operate under the assumption that no more than 4 attachments can be returned or uploaded. Pleroma however does not enforce any limits on attachment count neither when returning the status object nor when posting. + +### Limitations + +Pleroma does not process remote images and therefore cannot include fields such as `meta` and `blurhash`. It does not support focal points or aspect ratios. The frontend is expected to handle it. + ## Accounts The `id` parameter can also be the `nickname` of the user. This only works in these endpoints, not the deeper nested ones for following etc. -- cgit v1.2.3 From b08baf905b09ac49ed908eff8b43593d890612dd Mon Sep 17 00:00:00 2001 From: lain Date: Fri, 29 May 2020 16:03:55 +0200 Subject: Docs: Document streaming differences --- docs/API/differences_in_mastoapi_responses.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/API') diff --git a/docs/API/differences_in_mastoapi_responses.md b/docs/API/differences_in_mastoapi_responses.md index e65fd5da4..a9d1f2f38 100644 --- a/docs/API/differences_in_mastoapi_responses.md +++ b/docs/API/differences_in_mastoapi_responses.md @@ -226,3 +226,7 @@ Has theses additional parameters (which are the same as in Pleroma-API): Has these additional fields under the `pleroma` object: - `unread_count`: contains number unread notifications + +## Streaming + +There is an additional `user:pleroma_chat` stream. Incoming chat messages will make the current chat be sent to this `user` stream. The `event` of an incoming chat message is `pleroma:chat_update`. The payload is the updated chat with the incoming chat message in the `last_message` field. -- cgit v1.2.3 From 32431ad1ee88d260b720fab05fce76eb75bfe107 Mon Sep 17 00:00:00 2001 From: lain Date: Fri, 29 May 2020 16:07:40 +0200 Subject: Docs: Also add the streaming docs to the Chat api doc. --- docs/API/chats.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/API') diff --git a/docs/API/chats.md b/docs/API/chats.md index 2e415e4da..2eca5adf6 100644 --- a/docs/API/chats.md +++ b/docs/API/chats.md @@ -220,3 +220,7 @@ There's a new `pleroma:chat_mention` notification, which has this form: "created_at": "somedate" } ``` + +### Streaming + +There is an additional `user:pleroma_chat` stream. Incoming chat messages will make the current chat be sent to this `user` stream. The `event` of an incoming chat message is `pleroma:chat_update`. The payload is the updated chat with the incoming chat message in the `last_message` field. -- cgit v1.2.3 From 127ccc4e1c76c2782b26a0cfbb154bc1317f31b3 Mon Sep 17 00:00:00 2001 From: lain Date: Tue, 2 Jun 2020 14:05:53 +0200 Subject: NotificationController: Don't return chat_mentions by default. --- docs/API/chats.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/API') diff --git a/docs/API/chats.md b/docs/API/chats.md index 2eca5adf6..d1d39f495 100644 --- a/docs/API/chats.md +++ b/docs/API/chats.md @@ -204,7 +204,7 @@ Returned data is the deleted message. ### Notifications -There's a new `pleroma:chat_mention` notification, which has this form: +There's a new `pleroma:chat_mention` notification, which has this form. It is not given out in the notifications endpoint by default, you need to explicitly request it with `include_types[]=pleroma:chat_mention`: ```json { -- cgit v1.2.3 From c16315d055d07206dddb228583956d5b718ecdd4 Mon Sep 17 00:00:00 2001 From: Egor Kislitsyn Date: Wed, 3 Jun 2020 19:10:11 +0400 Subject: Add OpenAPI spec for AdminAPI.ReportController --- docs/API/admin_api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/API') diff --git a/docs/API/admin_api.md b/docs/API/admin_api.md index 639c3224d..92816baf9 100644 --- a/docs/API/admin_api.md +++ b/docs/API/admin_api.md @@ -547,7 +547,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret ```json { - "totalReports" : 1, + "total" : 1, "reports": [ { "account": { @@ -768,7 +768,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - 400 Bad Request `"Invalid parameters"` when `status` is missing - On success: `204`, empty response -## `POST /api/pleroma/admin/reports/:report_id/notes/:id` +## `DELETE /api/pleroma/admin/reports/:report_id/notes/:id` ### Delete report note -- cgit v1.2.3 From 286bd8eb83e3fd9a2546e27c5e5d98f5316934a0 Mon Sep 17 00:00:00 2001 From: lain Date: Wed, 3 Jun 2020 19:24:37 +0200 Subject: Docs: Add `mark_message_as_read` to docs --- docs/API/chats.md | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) (limited to 'docs/API') diff --git a/docs/API/chats.md b/docs/API/chats.md index d1d39f495..c0ef75664 100644 --- a/docs/API/chats.md +++ b/docs/API/chats.md @@ -94,6 +94,15 @@ Returned data: } ``` +### Marking a single chat message as read + +To set the `unread` property of a message to `false` + +`POST /api/v1/pleroma/chats/:id/messages/:message_id/read` + +Returned data: + +The modified chat message ### Getting a list of Chats @@ -149,7 +158,8 @@ Returned data: "visible_in_picker": false } ], - "id": "13" + "id": "13", + "unread": true }, { "account_id": "someflakeid", @@ -157,7 +167,8 @@ Returned data: "content": "Whats' up?", "created_at": "2020-04-21T15:06:45.000Z", "emojis": [], - "id": "12" + "id": "12", + "unread": false } ] ``` @@ -190,7 +201,8 @@ Returned data: "visible_in_picker": false } ], - "id": "13" + "id": "13", + "unread": false } ``` @@ -215,7 +227,8 @@ There's a new `pleroma:chat_mention` notification, which has this form. It is no "chat_id": "1", "id": "10", "content": "Hello", - "account_id": "someflakeid" + "account_id": "someflakeid", + "unread": false }, "created_at": "somedate" } -- cgit v1.2.3 From 6e103a18af6cfd7f454a911e2f0e1ae35cd45aa4 Mon Sep 17 00:00:00 2001 From: lain Date: Thu, 4 Jun 2020 14:49:36 +0200 Subject: Docs: Document WebPush changes. --- docs/API/chats.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/API') diff --git a/docs/API/chats.md b/docs/API/chats.md index c0ef75664..abeee698f 100644 --- a/docs/API/chats.md +++ b/docs/API/chats.md @@ -237,3 +237,7 @@ There's a new `pleroma:chat_mention` notification, which has this form. It is no ### Streaming There is an additional `user:pleroma_chat` stream. Incoming chat messages will make the current chat be sent to this `user` stream. The `event` of an incoming chat message is `pleroma:chat_update`. The payload is the updated chat with the incoming chat message in the `last_message` field. + +### Web Push + +If you want to receive push messages for this type, you'll need to add the `pleroma:chat_mention` type to your alerts in the push subscription. -- cgit v1.2.3 From c5e3f2454c736e09de5c433a2bf578e8eb0e70c3 Mon Sep 17 00:00:00 2001 From: lain Date: Sat, 6 Jun 2020 10:35:38 +0200 Subject: Docs: Unify parameters in examples. --- docs/API/chats.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/API') diff --git a/docs/API/chats.md b/docs/API/chats.md index abeee698f..761047336 100644 --- a/docs/API/chats.md +++ b/docs/API/chats.md @@ -41,7 +41,7 @@ This is the overview of using the API. The API is also documented via OpenAPI, s To create or get an existing Chat for a certain recipient (identified by Account ID) you can call: -`POST /api/v1/pleroma/chats/by-account-id/{account_id}` +`POST /api/v1/pleroma/chats/by-account-id/:account_id` The account id is the normal FlakeId of the user ``` @@ -136,7 +136,7 @@ The usual pagination options are implemented. For a given Chat id, you can get the associated messages with -`GET /api/v1/pleroma/chats/{id}/messages` +`GET /api/v1/pleroma/chats/:id/messages` This will return all messages, sorted by most recent to least recent. The usual pagination options are implemented. @@ -177,7 +177,7 @@ Returned data: Posting a chat message for given Chat id works like this: -`POST /api/v1/pleroma/chats/{id}/messages` +`POST /api/v1/pleroma/chats/:id/messages` Parameters: - content: The text content of the message. Optional if media is attached. @@ -210,7 +210,7 @@ Returned data: Deleting a chat message for given Chat id works like this: -`DELETE /api/v1/pleroma/chats/{chat_id}/messages/{message_id}` +`DELETE /api/v1/pleroma/chats/:chat_id/messages/:message_id` Returned data is the deleted message. -- cgit v1.2.3 From 680fa5fa36d8b30a9a9749edacf1a2c69fded29a Mon Sep 17 00:00:00 2001 From: lain Date: Sun, 7 Jun 2020 15:41:46 +0200 Subject: Docs: Update docs on mark as read. --- docs/API/chats.md | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/API') diff --git a/docs/API/chats.md b/docs/API/chats.md index 761047336..81ff57941 100644 --- a/docs/API/chats.md +++ b/docs/API/chats.md @@ -79,6 +79,11 @@ To set the `unread` count of a chat to 0, call `POST /api/v1/pleroma/chats/:id/read` + +Parameters: +- last_read_id: Given this id, all chat messages until this one will be marked as read. This should always be used. + + Returned data: ```json -- cgit v1.2.3 From 1a2acce7c5927cd113ebcffd0acc7a5c547bbf0e Mon Sep 17 00:00:00 2001 From: lain Date: Sun, 7 Jun 2020 20:23:17 +0200 Subject: Docs: Document new mandatory parameter. --- docs/API/chats.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/API') diff --git a/docs/API/chats.md b/docs/API/chats.md index 81ff57941..9eb581943 100644 --- a/docs/API/chats.md +++ b/docs/API/chats.md @@ -75,13 +75,13 @@ Returned data: ### Marking a chat as read -To set the `unread` count of a chat to 0, call +To mark a number of messages in a chat up to a certain message as read, you can use `POST /api/v1/pleroma/chats/:id/read` Parameters: -- last_read_id: Given this id, all chat messages until this one will be marked as read. This should always be used. +- last_read_id: Given this id, all chat messages until this one will be marked as read. Required. Returned data: -- cgit v1.2.3 From 89b85f65297ef4b8ce92eacb27c90e8f7c874f54 Mon Sep 17 00:00:00 2001 From: lain Date: Mon, 8 Jun 2020 11:09:53 +0200 Subject: ChatController: Remove nonsensical pagination. --- docs/API/chats.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/API') diff --git a/docs/API/chats.md b/docs/API/chats.md index 9eb581943..aa6119670 100644 --- a/docs/API/chats.md +++ b/docs/API/chats.md @@ -135,7 +135,7 @@ Returned data: ``` The recipient of messages that are sent to this chat is given by their AP ID. -The usual pagination options are implemented. +No pagination is implemented for now. ### Getting the messages for a Chat -- cgit v1.2.3 From efdfc85c2d8e5118c1aa18e4f04026ec90cd11d2 Mon Sep 17 00:00:00 2001 From: Maksim Pechnikov Date: Mon, 15 Jun 2020 15:24:00 +0300 Subject: update docs --- docs/API/admin_api.md | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 63 insertions(+), 1 deletion(-) (limited to 'docs/API') diff --git a/docs/API/admin_api.md b/docs/API/admin_api.md index 92816baf9..6659b605d 100644 --- a/docs/API/admin_api.md +++ b/docs/API/admin_api.md @@ -1224,4 +1224,66 @@ Loads json generated from `config/descriptions.exs`. - Response: - On success: `204`, empty response - On failure: - - 400 Bad Request `"Invalid parameters"` when `status` is missing \ No newline at end of file + - 400 Bad Request `"Invalid parameters"` when `status` is missing + +## `GET /api/pleroma/admin/media_proxy_caches` + +### Get a list of all banned MediaProxy URLs in Cachex + +- Authentication: required +- Params: +- *optional* `page`: **integer** page number +- *optional* `page_size`: **integer** number of log entries per page (default is `50`) + +- Response: + +``` json +{ + "urls": [ + "http://example.com/media/a688346.jpg", + "http://example.com/media/fb1f4d.jpg" + ] +} + +``` + +## `POST /api/pleroma/admin/media_proxy_caches/delete` + +### Remove a banned MediaProxy URL from Cachex + +- Authentication: required +- Params: + - `urls` + +- Response: + +``` json +{ + "urls": [ + "http://example.com/media/a688346.jpg", + "http://example.com/media/fb1f4d.jpg" + ] +} + +``` + +## `POST /api/pleroma/admin/media_proxy_caches/purge` + +### Purge a MediaProxy URL + +- Authentication: required +- Params: + - `urls` + - `ban` + +- Response: + +``` json +{ + "urls": [ + "http://example.com/media/a688346.jpg", + "http://example.com/media/fb1f4d.jpg" + ] +} + +``` -- cgit v1.2.3 From 90613348ed8078e1906f7ffd18eebfa1a3b7f25a Mon Sep 17 00:00:00 2001 From: Maksim Date: Wed, 17 Jun 2020 12:56:13 +0000 Subject: Apply suggestion to docs/API/admin_api.md --- docs/API/admin_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/API') diff --git a/docs/API/admin_api.md b/docs/API/admin_api.md index 6659b605d..8a3d60187 100644 --- a/docs/API/admin_api.md +++ b/docs/API/admin_api.md @@ -1253,7 +1253,7 @@ Loads json generated from `config/descriptions.exs`. - Authentication: required - Params: - - `urls` + - `urls` (array) - Response: -- cgit v1.2.3 From abfb1c756b62c24589d2881d77bf5974a80809d3 Mon Sep 17 00:00:00 2001 From: Maksim Date: Wed, 17 Jun 2020 12:56:17 +0000 Subject: Apply suggestion to docs/API/admin_api.md --- docs/API/admin_api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/API') diff --git a/docs/API/admin_api.md b/docs/API/admin_api.md index 8a3d60187..c7f56cf5f 100644 --- a/docs/API/admin_api.md +++ b/docs/API/admin_api.md @@ -1273,8 +1273,8 @@ Loads json generated from `config/descriptions.exs`. - Authentication: required - Params: - - `urls` - - `ban` + - `urls` (array) + - `ban` (boolean) - Response: -- cgit v1.2.3 From 4975ed86bcca330373a68c9e6c6798a6b2167b14 Mon Sep 17 00:00:00 2001 From: Alexander Strizhakov Date: Thu, 18 Jun 2020 18:50:03 +0300 Subject: emoji pagination for pack show action --- docs/API/pleroma_api.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) (limited to 'docs/API') diff --git a/docs/API/pleroma_api.md b/docs/API/pleroma_api.md index 70d4755b7..d8d3ba85f 100644 --- a/docs/API/pleroma_api.md +++ b/docs/API/pleroma_api.md @@ -450,17 +450,25 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa * Response: JSON, list with updated files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message. ## `GET /api/pleroma/emoji/packs` + ### Lists local custom emoji packs + * Method `GET` * Authentication: not required -* Params: None +* Params: + * `page`: page number for packs (default 1) + * `page_size`: page size for packs (default 50) * Response: JSON, "ok" and 200 status and the JSON hashmap of pack name to pack contents ## `GET /api/pleroma/emoji/packs/:name` + ### Get pack.json for the pack + * Method `GET` * Authentication: not required -* Params: None +* Params: + * `page`: page number for files (default 1) + * `page_size`: page size for files (default 50) * Response: JSON, pack json with `files` and `pack` keys with 200 status or 404 if the pack does not exist ## `GET /api/pleroma/emoji/packs/:name/archive` -- cgit v1.2.3 From 3e3f9253e6db17b691c7393ad7a5f89df84348ea Mon Sep 17 00:00:00 2001 From: Alexander Strizhakov Date: Fri, 19 Jun 2020 10:17:24 +0300 Subject: adding overall count for packs and files --- docs/API/pleroma_api.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) (limited to 'docs/API') diff --git a/docs/API/pleroma_api.md b/docs/API/pleroma_api.md index d8d3ba85f..e5bc29eb2 100644 --- a/docs/API/pleroma_api.md +++ b/docs/API/pleroma_api.md @@ -458,7 +458,17 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa * Params: * `page`: page number for packs (default 1) * `page_size`: page size for packs (default 50) -* Response: JSON, "ok" and 200 status and the JSON hashmap of pack name to pack contents +* Response: `packs` key with JSON hashmap of pack name to pack contents and `count` key for count of packs. + +```json +{ + "packs": { + "pack_name": {...}, // pack contents + ... + }, + "count": 0 // packs count +} +``` ## `GET /api/pleroma/emoji/packs/:name` @@ -469,7 +479,15 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa * Params: * `page`: page number for files (default 1) * `page_size`: page size for files (default 50) -* Response: JSON, pack json with `files` and `pack` keys with 200 status or 404 if the pack does not exist +* Response: JSON, pack json with `files`, `files_count` and `pack` keys with 200 status or 404 if the pack does not exist. + +```json +{ + "files": {...}, + "files_count": 0, // emoji count in pack + "pack": {...} +} +``` ## `GET /api/pleroma/emoji/packs/:name/archive` ### Requests a local pack archive from the instance -- cgit v1.2.3 From 02ca8a363f738ece7b605940690f6a538f6c2fa8 Mon Sep 17 00:00:00 2001 From: Alexander Strizhakov Date: Fri, 19 Jun 2020 14:46:38 +0300 Subject: default page size for files --- docs/API/pleroma_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/API') diff --git a/docs/API/pleroma_api.md b/docs/API/pleroma_api.md index e5bc29eb2..b7eee5192 100644 --- a/docs/API/pleroma_api.md +++ b/docs/API/pleroma_api.md @@ -478,7 +478,7 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa * Authentication: not required * Params: * `page`: page number for files (default 1) - * `page_size`: page size for files (default 50) + * `page_size`: page size for files (default 30) * Response: JSON, pack json with `files`, `files_count` and `pack` keys with 200 status or 404 if the pack does not exist. ```json -- cgit v1.2.3 From c5863438ba9079a01a832fe48e203907fe5b37cd Mon Sep 17 00:00:00 2001 From: Alexander Strizhakov Date: Sat, 20 Jun 2020 13:53:57 +0300 Subject: proper error codes for error in adminFE --- docs/API/admin_api.md | 56 ++++++++++++++++++++++++++++----------------------- 1 file changed, 31 insertions(+), 25 deletions(-) (limited to 'docs/API') diff --git a/docs/API/admin_api.md b/docs/API/admin_api.md index c7f56cf5f..b6fb43dcb 100644 --- a/docs/API/admin_api.md +++ b/docs/API/admin_api.md @@ -488,35 +488,39 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret ### Change the user's email, password, display and settings-related fields -- Params: - - `email` - - `password` - - `name` - - `bio` - - `avatar` - - `locked` - - `no_rich_text` - - `default_scope` - - `banner` - - `hide_follows` - - `hide_followers` - - `hide_followers_count` - - `hide_follows_count` - - `hide_favorites` - - `allow_following_move` - - `background` - - `show_role` - - `skip_thread_containment` - - `fields` - - `discoverable` - - `actor_type` - -- Response: +* Params: + * `email` + * `password` + * `name` + * `bio` + * `avatar` + * `locked` + * `no_rich_text` + * `default_scope` + * `banner` + * `hide_follows` + * `hide_followers` + * `hide_followers_count` + * `hide_follows_count` + * `hide_favorites` + * `allow_following_move` + * `background` + * `show_role` + * `skip_thread_containment` + * `fields` + * `discoverable` + * `actor_type` + +* Responses: + +Status: 200 ```json {"status": "success"} ``` +Status: 400 + ```json {"errors": {"actor_type": "is invalid"}, @@ -525,8 +529,10 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret } ``` +Status: 404 + ```json -{"error": "Unable to update user."} +{"error": "Not found"} ``` ## `GET /api/pleroma/admin/reports` -- cgit v1.2.3