feat(api): 🏷️ Port Role and CustomEmoji OpenAPI schemas

classes/database/emoji.ts

@@ -1,7 +1,6 @@
 import { emojiValidatorWithColons, emojiValidatorWithIdentifiers } from "@/api";
 import { proxyUrl } from "@/response";
-import { z } from "@hono/zod-openapi";
-import type { Emoji as APIEmoji } from "@versia/client/types";
+import type { z } from "@hono/zod-openapi";
 import type { CustomEmojiExtension } from "@versia/federation/types";
 import { type Instance, Media, db } from "@versia/kit/db";
 import { Emojis, type Instances, type Medias } from "@versia/kit/tables";
@@ -15,6 +14,7 @@ import {
     inArray,
     isNull,
 } from "drizzle-orm";
+import type { CustomEmoji } from "../schemas/emoji.ts";
 import { BaseInterface } from "./base.ts";
 
 type EmojiType = InferSelectModel<typeof Emojis> & {
@@ -23,16 +23,6 @@ type EmojiType = InferSelectModel<typeof Emojis> & {
 };
 
 export class Emoji extends BaseInterface<typeof Emojis, EmojiType> {
-    public static schema = z.object({
-        id: z.string(),
-        shortcode: z.string(),
-        url: z.string(),
-        visible_in_picker: z.boolean(),
-        category: z.string().optional(),
-        static_url: z.string(),
-        global: z.boolean(),
-    });
-
     public static $type: EmojiType;
     public media: Media;
 
@@ -184,18 +174,18 @@ export class Emoji extends BaseInterface<typeof Emojis, EmojiType> {
         );
     }
 
-    public toApi(): APIEmoji {
+    public toApi(): z.infer<typeof CustomEmoji> {
         return {
             id: this.id,
             shortcode: this.data.shortcode,
             static_url: proxyUrl(this.media.getUrl()).toString(),
             url: proxyUrl(this.media.getUrl()).toString(),
             visible_in_picker: this.data.visibleInPicker,
-            category: this.data.category ?? undefined,
+            category: this.data.category,
             global: this.data.ownerId === null,
             description:
                 this.media.data.content[this.media.getPreferredMimeType()]
-                    .description ?? undefined,
+                    .description ?? null,
         };
     }
 

classes/database/reaction.ts

@@ -12,6 +12,7 @@ import {
     inArray,
 } from "drizzle-orm";
 import { config } from "~/packages/config-manager/index.ts";
+import { CustomEmoji } from "../schemas/emoji.ts";
 import { BaseInterface } from "./base.ts";
 
 type ReactionType = InferSelectModel<typeof Reactions> & {
@@ -30,7 +31,7 @@ export class Reaction extends BaseInterface<typeof Reactions, ReactionType> {
     public static schema: z.ZodType<APIReaction> = z.object({
         id: z.string().uuid(),
         author_id: z.string().uuid(),
-        emoji: z.lazy(() => Emoji.schema),
+        emoji: CustomEmoji,
     });
 
     public static $type: ReactionType;
@@ -169,16 +170,6 @@ export class Reaction extends BaseInterface<typeof Reactions, ReactionType> {
         return this.data.id;
     }
 
-    public toApi(): APIReaction {
-        return {
-            id: this.data.id,
-            author_id: this.data.authorId,
-            emoji: this.hasCustomEmoji()
-                ? new Emoji(this.data.emoji as typeof Emoji.$type).toApi()
-                : this.data.emojiText || "",
-        };
-    }
-
     public getUri(baseUrl: URL): URL {
         return this.data.uri
             ? new URL(this.data.uri)

classes/database/role.ts

@@ -1,7 +1,6 @@
 import { proxyUrl } from "@/response";
-import { z } from "@hono/zod-openapi";
-import {
-    type VersiaRole as APIRole,
+import type {
+    VersiaRole as APIRole,
     RolePermission,
 } from "@versia/client/types";
 import { db } from "@versia/kit/db";
@@ -21,16 +20,6 @@ import { BaseInterface } from "./base.ts";
 type RoleType = InferSelectModel<typeof Roles>;
 
 export class Role extends BaseInterface<typeof Roles> {
-    public static schema = z.object({
-        id: z.string().uuid(),
-        name: z.string().min(1).max(128),
-        permissions: z.array(z.nativeEnum(RolePermission)).default([]),
-        priority: z.number().int().default(0),
-        description: z.string().min(0).max(1024).optional(),
-        visible: z.boolean().default(true),
-        icon: z.string().url().optional(),
-    });
-
     public static $type: RoleType;
 
     public async reload(): Promise<void> {

classes/database/user.ts

@@ -1,5 +1,5 @@
 import { idValidator } from "@/api";
-import { getBestContentType, urlToContentFormat } from "@/content_types";
+import { getBestContentType } from "@/content_types";
 import { randomString } from "@/math";
 import { proxyUrl } from "@/response";
 import { sentry } from "@/sentry";
@@ -52,7 +52,7 @@ import { type Config, config } from "~/packages/config-manager";
 import type { KnownEntity } from "~/types/api.ts";
 import { DeliveryJobType, deliveryQueue } from "../queues/delivery.ts";
 import { PushJobType, pushQueue } from "../queues/push.ts";
-import type { Account } from "../schemas/account.ts";
+import type { Account, Source } from "../schemas/account.ts";
 import { BaseInterface } from "./base.ts";
 import { Emoji } from "./emoji.ts";
 import { Instance } from "./instance.ts";
@@ -686,12 +686,12 @@ export class User extends BaseInterface<typeof Users, UserWithRelations> {
             note: getBestContentType(user.bio).content,
             publicKey: user.public_key.key,
             source: {
-                language: null,
+                language: "en",
                 note: "",
                 privacy: "public",
                 sensitive: false,
                 fields: [],
-            },
+            } as z.infer<typeof Source>,
         };
 
         const userEmojis =
@@ -888,12 +888,12 @@ export class User extends BaseInterface<typeof Users, UserWithRelations> {
                     privateKey: keys.private_key,
                     updatedAt: new Date().toISOString(),
                     source: {
-                        language: null,
+                        language: "en",
                         note: "",
                         privacy: "public",
                         sensitive: false,
                         fields: [],
-                    },
+                    } as z.infer<typeof Source>,
                 })
                 .returning()
         )[0];
@@ -1107,6 +1107,7 @@ export class User extends BaseInterface<typeof Users, UserWithRelations> {
 
     public toApi(isOwnAccount = false): z.infer<typeof Account> {
         const user = this.data;
+
         return {
             id: user.id,
             username: user.username,
@@ -1177,6 +1178,8 @@ export class User extends BaseInterface<typeof Users, UserWithRelations> {
                 )
                 .map((r) => r.toApi()),
             group: false,
+            // TODO
+            last_status_at: null,
         };
     }
 
@@ -1235,17 +1238,8 @@ export class User extends BaseInterface<typeof Users, UserWithRelations> {
             indexable: false,
             username: user.username,
             manually_approves_followers: this.data.isLocked,
-            avatar:
-                urlToContentFormat(
-                    this.getAvatarUrl(config),
-                    this.data.source.avatar?.content_type,
-                ) ?? undefined,
-            header: this.getHeaderUrl(config)
-                ? (urlToContentFormat(
-                      this.getHeaderUrl(config) as URL,
-                      this.data.source.header?.content_type,
-                  ) ?? undefined)
-                : undefined,
+            avatar: this.avatar?.toVersia(),
+            header: this.header?.toVersia(),
             display_name: user.displayName,
             fields: user.fields,
             public_key: {

classes/schemas/account.ts

@@ -3,8 +3,8 @@ import type { Account as ApiAccount } from "@versia/client/types";
 import ISO6391 from "iso-639-1";
 import { config } from "~/packages/config-manager";
 import { zBoolean } from "~/packages/config-manager/config.type";
-import { Emoji } from "../database/emoji.ts";
-import { Role } from "../database/role.ts";
+import { CustomEmoji } from "./emoji.ts";
+import { Role } from "./versia.ts";
 
 export const Field = z.object({
     name: z
@@ -117,7 +117,7 @@ export const Account = z.object({
         .string()
         .uuid()
         .openapi({
-            description: "The account id.",
+            description: "The account ID in the database.",
             example: "9e84842b-4db6-4a9b-969d-46ab408278da",
             externalDocs: {
                 url: "https://docs.joinmastodon.org/entities/Account/#id",
@@ -260,7 +260,7 @@ export const Account = z.object({
                 url: "https://docs.joinmastodon.org/entities/Account/#fields",
             },
         }),
-    emojis: z.array(Emoji.schema).openapi({
+    emojis: z.array(CustomEmoji).openapi({
         description:
             "Custom emoji entities to be used when rendering the profile.",
         externalDocs: {
@@ -384,6 +384,7 @@ export const Account = z.object({
                 url: "https://docs.joinmastodon.org/entities/Account/#following_count",
             },
         }),
+    /* Versia Server API extension */
     uri: z.string().url().openapi({
         description:
             "The location of the user's Versia profile page, as opposed to the local representation.",
@@ -396,7 +397,10 @@ export const Account = z.object({
             name: z.string(),
         })
         .optional(),
-    roles: z.array(Role.schema),
+    /* Versia Server API extension */
+    roles: z.array(Role).openapi({
+        description: "Roles assigned to the account.",
+    }),
     mute_expires_at: z.string().datetime().nullable().openapi({
         description: "When a timed mute will expire, if applicable.",
         example: "2025-03-01T14:00:00.000Z",

classes/schemas/context.ts

@@ -0,0 +1,25 @@
+import { z } from "@hono/zod-openapi";
+import { Status } from "./status.ts";
+
+export const Context = z
+    .object({
+        ancestors: z.array(Status).openapi({
+            description: "Parents in the thread.",
+            externalDocs: {
+                url: "https://docs.joinmastodon.org/entities/Context/#ancestors",
+            },
+        }),
+        descendants: z.array(Status).openapi({
+            description: "Children in the thread.",
+            externalDocs: {
+                url: "https://docs.joinmastodon.org/entities/Context/#descendants",
+            },
+        }),
+    })
+    .openapi({
+        description:
+            "Represents the tree around a given status. Used for reconstructing threads of statuses.",
+        externalDocs: {
+            url: "https://docs.joinmastodon.org/entities/Context/#context",
+        },
+    });

classes/schemas/emoji.ts

@@ -0,0 +1,82 @@
+import { z } from "@hono/zod-openapi";
+import { zBoolean } from "~/packages/config-manager/config.type";
+import { Id } from "./common.ts";
+
+export const CustomEmoji = z
+    .object({
+        /* Versia Server API extension */
+        id: Id.openapi({
+            description: "ID of the custom emoji in the database.",
+            example: "af9ccd29-c689-477f-aa27-d7d95fd8fb05",
+        }),
+        shortcode: z.string().openapi({
+            description: "The name of the custom emoji.",
+            example: "blobaww",
+            externalDocs: {
+                url: "https://docs.joinmastodon.org/entities/CustomEmoji/#shortcode",
+            },
+        }),
+        url: z
+            .string()
+            .url()
+            .openapi({
+                description: "A link to the custom emoji.",
+                example:
+                    "https://cdn.versia.social/emojis/images/000/011/739/original/blobaww.png",
+                externalDocs: {
+                    url: "https://docs.joinmastodon.org/entities/CustomEmoji/#url",
+                },
+            }),
+        static_url: z
+            .string()
+            .url()
+            .openapi({
+                description: "A link to a static copy of the custom emoji.",
+                example:
+                    "https://cdn.versia.social/emojis/images/000/011/739/static/blobaww.png",
+                externalDocs: {
+                    url: "https://docs.joinmastodon.org/entities/CustomEmoji/#static_url",
+                },
+            }),
+        visible_in_picker: z.boolean().openapi({
+            description:
+                "Whether this Emoji should be visible in the picker or unlisted.",
+            example: true,
+            externalDocs: {
+                url: "https://docs.joinmastodon.org/entities/CustomEmoji/#visible_in_picker",
+            },
+        }),
+        category: z
+            .string()
+            .nullable()
+            .openapi({
+                description: "Used for sorting custom emoji in the picker.",
+                example: "Blobs",
+                externalDocs: {
+                    url: "https://docs.joinmastodon.org/entities/CustomEmoji/#category",
+                },
+            }),
+        /* Versia Server API extension */
+        global: zBoolean.openapi({
+            description: "Whether this emoji is visible to all users.",
+            example: false,
+        }),
+        /* Versia Server API extension */
+        description: z
+            .string()
+            .nullable()
+            .openapi({
+                description:
+                    "Emoji description for users using screen readers.",
+                example: "A cute blob.",
+                externalDocs: {
+                    url: "https://docs.joinmastodon.org/entities/CustomEmoji/#description",
+                },
+            }),
+    })
+    .openapi({
+        description: "Represents a custom emoji.",
+        externalDocs: {
+            url: "https://docs.joinmastodon.org/entities/CustomEmoji",
+        },
+    });

classes/schemas/status.ts

@@ -1,12 +1,14 @@
 import { z } from "@hono/zod-openapi";
 import type { Status as ApiNote } from "@versia/client/types";
-import { Emoji, Media } from "@versia/kit/db";
+import { Media } from "@versia/kit/db";
 import ISO6391 from "iso-639-1";
 import { zBoolean } from "~/packages/config-manager/config.type.ts";
 import { Account } from "./account.ts";
 import { PreviewCard } from "./card.ts";
 import { Id } from "./common.ts";
+import { CustomEmoji } from "./emoji.ts";
 import { FilterResult } from "./filters.ts";
+import { NoteReaction } from "./versia.ts";
 
 export const Mention = z
     .object({
@@ -168,7 +170,7 @@ export const Poll = z.object({
             url: "https://docs.joinmastodon.org/entities/Poll/#options",
         },
     }),
-    emojis: z.array(Emoji.schema).openapi({
+    emojis: z.array(CustomEmoji).openapi({
         description: "Custom emoji to be used for rendering poll options.",
         externalDocs: {
             url: "https://docs.joinmastodon.org/entities/Poll/#emojis",
@@ -284,7 +286,7 @@ export const Status = z.object({
                 url: "https://docs.joinmastodon.org/entities/Status/#edited_at",
             },
         }),
-    emojis: z.array(Emoji.schema).openapi({
+    emojis: z.array(CustomEmoji).openapi({
         description: "Custom emoji to be used when rendering status content.",
         externalDocs: {
             url: "https://docs.joinmastodon.org/entities/Status/#emojis",
@@ -455,17 +457,7 @@ export const Status = z.object({
             url: "https://docs.joinmastodon.org/entities/Status/#pinned",
         },
     }),
-    emoji_reactions: z.array(
-        z.object({
-            count: z.number().int().nonnegative(),
-            me: zBoolean,
-            name: z.string(),
-            url: z.string().url().optional(),
-            static_url: z.string().url().optional(),
-            accounts: z.array(Account).optional(),
-            account_ids: z.array(z.string().uuid()).optional(),
-        }),
-    ),
+    reactions: z.array(NoteReaction).openapi({}),
     quote: z
         .lazy((): z.ZodType<ApiNote> => Status as z.ZodType<ApiNote>)
         .nullable(),

classes/schemas/versia.ts

@@ -0,0 +1,77 @@
+import { z } from "@hono/zod-openapi";
+import { RolePermission } from "@versia/client/types";
+import { Id } from "./common.ts";
+import { config } from "~/packages/config-manager/index.ts";
+
+/* Versia Server API extension */
+export const Role = z
+    .object({
+        id: Id.openapi({}).openapi({
+            description: "The role ID in the database.",
+            example: "b4a7e0f0-8f6a-479b-910b-9265c070d5bd",
+        }),
+        name: z.string().min(1).max(128).trim().openapi({
+            description: "The name of the role.",
+            example: "Moderator",
+        }),
+        permissions: z
+            .array(z.nativeEnum(RolePermission))
+            .transform(
+                // Deduplicate permissions
+                (permissions) => Array.from(new Set(permissions)),
+            )
+            .default([])
+            .openapi({
+                description: "The permissions granted to the role.",
+                example: [
+                    RolePermission.ManageEmojis,
+                    RolePermission.ManageAccounts,
+                ],
+            }),
+        priority: z.number().int().default(0).openapi({
+            description:
+                "Role priority. Higher priority roles allow overriding lower priority roles.",
+            example: 100,
+        }),
+        description: z.string().min(0).max(1024).trim().optional().openapi({
+            description: "Short role description.",
+            example: "Allows managing emojis and accounts.",
+        }),
+        visible: z.boolean().default(true).openapi({
+            description: "Whether the role should be shown in the UI.",
+        }),
+        icon: z.string().url().optional().openapi({
+            description: "URL to the role icon.",
+            example: "https://example.com/role-icon.png",
+        }),
+    })
+    .openapi({
+        description:
+            "Information about a role in the system, as well as its permissions.",
+    });
+
+/* Versia Server API extension */
+export const NoteReaction = z
+    .object({
+        name: z
+            .string()
+            .min(1)
+            .max(config.validation.max_emoji_shortcode_size)
+            .trim()
+            .openapi({
+                description: "Custom Emoji shortcode or Unicode emoji.",
+                example: "blobfox_coffee",
+            }),
+        count: z.number().int().nonnegative().openapi({
+            description: "Number of users who reacted with this emoji.",
+            example: 5,
+        }),
+        me: z.boolean().optional().openapi({
+            description:
+                "Whether the current authenticated user reacted with this emoji.",
+            example: true,
+        }),
+    })
+    .openapi({
+        description: "Information about a reaction to a note.",
+    });