docs(api): 📝 Document Reactions API

docs/.vitepress/config.ts

@@ -58,6 +58,10 @@ export default defineConfig({
                         text: "Emojis",
                         link: "/api/emojis",
                     },
+                    {
+                        text: "Reactions",
+                        link: "/api/reactions",
+                    },
                     {
                         text: "Roles",
                         link: "/api/roles",

docs/api/mastodon.md

@@ -369,6 +369,49 @@ An array of [`Roles`](./roles.md#role) that the user has.
 
 URI of the account's Versia entity (for federation). Similar to Mastodon's `uri` field on notes.
 
+## `Status`
+
+One attribute has been added to all returned [`Status`](https://docs.joinmastodon.org/entities/Status/) objects.
+
+This object is returned on routes such as `/api/v1/statuses/:id`, `/api/v1/statuses/:id/context`, etc.
+
+```ts
+type URL = string;
+
+interface NoteReaction {
+    name: string;
+    count: number;
+    me: boolean;
+    url: URL;
+}
+
+type ExtendedStatus = Status & {
+    reactions: NoteReaction[];
+}
+```
+
+```json
+{
+    ...
+    "reactions": [
+        {
+            "name": "like",
+            "count": 3,
+            "me": true,
+        },
+        {
+            "name": "blobfox",
+            "count": 1,
+            "me": false,
+        }
+    ]
+}
+```
+
+### `reactions`
+
+An array of all the [`NoteReactions`](./reactions.md#reaction) for the note. Data for the custom emoji (e.g. URL) can be found in the `emojis` field of the [`Status`](https://docs.joinmastodon.org/entities/Status#emojis).
+
 ## `/api/v1/accounts/update_credentials`
 
 The `username` parameter can now (optionally) be set to change the user's handle.

docs/api/reactions.md

@@ -0,0 +1,176 @@
+# Reactions API
+
+This API is used to send reactions to notes.
+
+## Reaction
+
+```typescript
+type UUID = string;
+
+interface NoteReaction {
+    name: string;
+    count: number;
+    me: boolean;
+    url: URL;
+}
+
+type NoteReactionWithAccounts = NoteReaction & {
+    account_ids: UUID[];
+}
+```
+
+## Get Reactions
+
+All reactions attached to a [`Status`](https://docs.joinmastodon.org/entities/Status) can be found on the note itself, [in the `reactions` field](./mastodon.md#reactions).
+
+## Get Users Who Reacted
+
+```http
+GET /api/v1/statuses/:id/reactions
+```
+
+Get a list of all the users who reacted to a note. Only IDs are returned, not full account objects, to improve performance on very popular notes.
+
+- **Returns:** [`NoteReactionWithAccounts[]`](#reaction)
+- **Authentication:** Not required
+- **Permissions:** `read:reaction`
+- **Version History**:
+  - `0.8.0`: Added.
+
+### Request
+
+#### Example
+
+```http
+GET /api/v1/statuses/123/reactions
+```
+
+### Response
+
+#### `200 OK`
+
+List of reactions and associated users. The `me` field is `true` if the current user has reacted with that emoji.
+
+Data for the custom emoji (e.g. URL) can be found in the `emojis` field of the [`Status`](https://docs.joinmastodon.org/entities/Status#emojis).
+
+```json
+[
+    {
+        "name": "like",
+        "count": 3,
+        "me": true,
+        "account_ids": ["1", "2", "3"]
+    },
+    {
+        "name": "blobfox-coffee",
+        "count": 1,
+        "me": false,
+        "account_ids": ["4"]
+    }
+]
+```
+
+## Add Reaction
+
+```http
+PUT /api/v1/statuses/:id/reactions/:name
+```
+
+Add a reaction to a note.
+
+- **Returns:** [`Status`](https://docs.joinmastodon.org/entities/Status)
+- **Authentication:** Required
+- **Permissions:** `owner:reaction`
+- **Version History**:
+  - `0.8.0`: Added.
+
+### Request
+
+- `name` (string, required): Either a custom emoji shortcode or a Unicode emoji.
+
+#### Example
+
+```http
+PUT /api/v1/statuses/123/reactions/blobfox-coffee
+Authorization: Bearer ...
+```
+
+```http
+PUT /api/v1/statuses/123/reactions/👍
+Authorization: Bearer ...
+```
+
+### Response
+
+#### `201 Created`
+
+Returns the updated note.
+
+```json
+{
+    "id": "123",
+    ...
+    "reactions": [
+        {
+            "name": "👍",
+            "count": 3,
+            "me": true
+        },
+        {
+            "name": "blobfox-coffee",
+            "count": 1,
+            "me": false
+        }
+    ]
+}
+```
+
+## Remove Reaction
+
+```http
+DELETE /api/v1/statuses/:id/reactions/:name
+```
+
+Remove a reaction from a note.
+
+- **Returns:** [`Status`](https://docs.joinmastodon.org/entities/Status)
+- **Authentication:** Required
+- **Permissions:** `owner:reaction`
+- **Version History**:
+  - `0.8.0`: Added.
+
+### Request
+
+- `name` (string, required): Either a custom emoji shortcode or a Unicode emoji.
+
+#### Example
+
+```http
+DELETE /api/v1/statuses/123/reactions/blobfox-coffee
+Authorization: Bearer ...
+```
+
+```http
+DELETE /api/v1/statuses/123/reactions
+Authorization: Bearer ...
+```
+
+### Response
+
+#### `200 OK`
+
+Returns the updated note. If the reaction was not found, the note is returned as is.
+
+```json
+{
+    "id": "123",
+    ...
+    "reactions": [
+        {
+            "name": "👍",
+            "count": 3,
+            "me": true
+        }
+    ]
+}
+```

docs/api/roles.md

@@ -39,6 +39,9 @@ ViewAccounts: "read:account",
 ManageEmojis: "emojis",
 ViewEmojis: "read:emoji",
 ManageOwnEmojis: "owner:emoji",
+ViewReactions: "read:reaction",
+ManageReactions: "reactions",
+ManageOwnReactions: "owner:reaction",
 ManageMedia: "media",
 ManageOwnMedia: "owner:media",
 ManageBlocks: "blocks",

drizzle/schema.ts

@@ -526,6 +526,9 @@ export enum RolePermissions {
     ManageEmojis = "emojis",
     ViewEmojis = "read:emoji",
     ManageOwnEmojis = "owner:emoji",
+    ViewReactions = "read:reaction",
+    ManageReactions = "reactions",
+    ManageOwnReactions = "owner:reaction",
     ManageMedia = "media",
     ManageOwnMedia = "owner:media",
     ManageBlocks = "blocks",
@@ -567,6 +570,8 @@ export const DEFAULT_ROLES = [
     RolePermissions.ManageOwnBoosts,
     RolePermissions.ViewAccounts,
     RolePermissions.ManageOwnEmojis,
+    RolePermissions.ViewReactions,
+    RolePermissions.ManageOwnReactions,
     RolePermissions.ViewEmojis,
     RolePermissions.ManageOwnMedia,
     RolePermissions.ManageOwnBlocks,
@@ -590,6 +595,7 @@ export const ADMIN_ROLES = [
     RolePermissions.ManageLikes,
     RolePermissions.ManageBoosts,
     RolePermissions.ManageEmojis,
+    RolePermissions.ManageReactions,
     RolePermissions.ManageMedia,
     RolePermissions.ManageBlocks,
     RolePermissions.ManageFilters,