diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 912c3860..3e580b25 100644 --- a/docs/.vitepress/config.ts +++ b/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", diff --git a/docs/api/mastodon.md b/docs/api/mastodon.md index 6150cb64..fdd8db49 100644 --- a/docs/api/mastodon.md +++ b/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. diff --git a/docs/api/reactions.md b/docs/api/reactions.md new file mode 100644 index 00000000..434aec62 --- /dev/null +++ b/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 + } + ] +} +``` diff --git a/docs/api/roles.md b/docs/api/roles.md index 7a363865..2138e488 100644 --- a/docs/api/roles.md +++ b/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", diff --git a/drizzle/schema.ts b/drizzle/schema.ts index 817dfa3c..328514ec 100644 --- a/drizzle/schema.ts +++ b/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,