versia-pub/server
2
0
Fork 0
mirror of https://github.com/versia-pub/server.git synced 2026-03-13 05:49:16 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

feat(api): 🏷️ Port Account OpenAPI schemas from Mastodon API docs

Browse source
This commit is contained in:
Jesse Wierzbinski 2025-02-05 21:49:39 +01:00
parent 76d1ccc859
commit 2aeada4904
No known key found for this signature in database
95 changed files with 610 additions and 388 deletions
Download patch file Download diff file Expand all files Collapse all files

2
classes/database/application.ts
View file

@ -1,3 +1,4 @@
import { z } from "@hono/zod-openapi";
import type { Application as APIApplication } from "@versia/client/types";
import { Token, db } from "@versia/kit/db";
import { Applications } from "@versia/kit/tables";
@ -9,7 +10,6 @@ import {
eq,
inArray,
} from "drizzle-orm";
import { z } from "zod";
import { BaseInterface } from "./base.ts";
type ApplicationType = InferSelectModel<typeof Applications>;

2
classes/database/emoji.ts
View file

@ -1,5 +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 { CustomEmojiExtension } from "@versia/federation/types";
import { type Instance, Media, db } from "@versia/kit/db";
@ -14,7 +15,6 @@ import {
inArray,
isNull,
} from "drizzle-orm";
import { z } from "zod";
import { BaseInterface } from "./base.ts";
type EmojiType = InferSelectModel<typeof Emojis> & {

2
classes/database/like.ts
View file

@ -1,3 +1,4 @@
import { z } from "@hono/zod-openapi";
import { RolePermission } from "@versia/client/types";
import type { Delete, LikeExtension } from "@versia/federation/types";
import { db } from "@versia/kit/db";
@ -16,7 +17,6 @@ import {
eq,
inArray,
} from "drizzle-orm";
import { z } from "zod";
import { config } from "~/packages/config-manager/index.ts";
import { BaseInterface } from "./base.ts";
import { Note } from "./note.ts";

2
classes/database/media.ts
View file

@ -1,6 +1,7 @@
import { join } from "node:path";
import { mimeLookup } from "@/content_types.ts";
import { proxyUrl } from "@/response";
import { z } from "@hono/zod-openapi";
import type { Attachment as ApiAttachment } from "@versia/client/types";
import type { ContentFormat } from "@versia/federation/types";
import { db } from "@versia/kit/db";
@ -15,7 +16,6 @@ import {
inArray,
} from "drizzle-orm";
import sharp from "sharp";
import { z } from "zod";
import { MediaBackendType } from "~/packages/config-manager/config.type";
import { config } from "~/packages/config-manager/index.ts";
import { ApiError } from "../errors/api-error.ts";

7
classes/database/note.ts
View file

@ -3,6 +3,7 @@ import { localObjectUri } from "@/constants";
import { mergeAndDeduplicate } from "@/lib.ts";
import { sanitizedHtmlStrip } from "@/sanitization";
import { sentry } from "@/sentry";
import { z } from "@hono/zod-openapi";
import { getLogger } from "@logtape/logtape";
import type {
Attachment as ApiAttachment,
@ -35,7 +36,6 @@ import {
} from "drizzle-orm";
import { htmlToText } from "html-to-text";
import { createRegExp, exactly, global } from "magic-regexp";
import { z } from "zod";
import {
contentToHtml,
findManyNotes,
@ -43,6 +43,7 @@ import {
} from "~/classes/functions/status";
import { config } from "~/packages/config-manager";
import { DeliveryJobType, deliveryQueue } from "../queues/delivery.ts";
import { Account } from "../schemas/account.ts";
import { Application } from "./application.ts";
import { BaseInterface } from "./base.ts";
import { Emoji } from "./emoji.ts";
@ -84,7 +85,7 @@ export class Note extends BaseInterface<typeof Notes, NoteTypeWithRelations> {
id: z.string().uuid(),
uri: z.string().url(),
url: z.string().url(),
account: z.lazy(() => User.schema),
account: Account,
in_reply_to_id: z.string().uuid().nullable(),
in_reply_to_account_id: z.string().uuid().nullable(),
reblog: z.lazy(() => Note.schema).nullable(),
@ -162,7 +163,7 @@ export class Note extends BaseInterface<typeof Notes, NoteTypeWithRelations> {
name: z.string(),
url: z.string().url().optional(),
static_url: z.string().url().optional(),
accounts: z.array(z.lazy(() => User.schema)).optional(),
accounts: z.array(Account).optional(),
account_ids: z.array(z.string().uuid()).optional(),
}),
),

7
classes/database/notification.ts
View file

@ -1,3 +1,4 @@
import { z } from "@hono/zod-openapi";
import type { Notification as APINotification } from "@versia/client/types";
import { Note, User, db } from "@versia/kit/db";
import { Notifications } from "@versia/kit/tables";
@ -9,12 +10,12 @@ import {
eq,
inArray,
} from "drizzle-orm";
import { z } from "zod";
import {
transformOutputToUserWithRelations,
userExtrasTemplate,
userRelations,
} from "../functions/user.ts";
import { Account } from "../schemas/account.ts";
import { BaseInterface } from "./base.ts";
export type NotificationType = InferSelectModel<typeof Notifications> & {
@ -27,7 +28,7 @@ export class Notification extends BaseInterface<
NotificationType
> {
public static schema: z.ZodType<APINotification> = z.object({
account: z.lazy(() => User.schema).nullable(),
account: Account.nullable(),
created_at: z.string(),
id: z.string().uuid(),
status: z.lazy(() => Note.schema).optional(),
@ -54,7 +55,7 @@ export class Notification extends BaseInterface<
"group_favourite",
"user_approved",
]),
target: z.lazy(() => User.schema).optional(),
target: Account.optional(),
});
public async reload(): Promise<void> {

2
classes/database/reaction.ts
View file

@ -1,3 +1,4 @@
import { z } from "@hono/zod-openapi";
import type { Emoji as APIEmoji } from "@versia/client/types";
import type { ReactionExtension } from "@versia/federation/types";
import { Emoji, Instance, Note, User, db } from "@versia/kit/db";
@ -10,7 +11,6 @@ import {
eq,
inArray,
} from "drizzle-orm";
import { z } from "zod";
import { config } from "~/packages/config-manager/index.ts";
import { BaseInterface } from "./base.ts";

2
classes/database/relationship.ts
View file

@ -1,3 +1,4 @@
import { z } from "@hono/zod-openapi";
import type { Relationship as APIRelationship } from "@versia/client/types";
import { db } from "@versia/kit/db";
import { Relationships } from "@versia/kit/tables";
@ -10,7 +11,6 @@ import {
eq,
inArray,
} from "drizzle-orm";
import { z } from "zod";
import { BaseInterface } from "./base.ts";
import type { User } from "./user.ts";

2
classes/database/role.ts
View file

@ -1,4 +1,5 @@
import { proxyUrl } from "@/response";
import { z } from "@hono/zod-openapi";
import {
type VersiaRole as APIRole,
RolePermission,
@ -14,7 +15,6 @@ import {
eq,
inArray,
} from "drizzle-orm";
import { z } from "zod";
import { config } from "~/packages/config-manager/index.ts";
import { BaseInterface } from "./base.ts";

2
classes/database/token.ts
View file

@ -1,3 +1,4 @@
import { z } from "@hono/zod-openapi";
import type { Token as ApiToken } from "@versia/client/types";
import { type Application, User, db } from "@versia/kit/db";
import { Tokens } from "@versia/kit/tables";
@ -9,7 +10,6 @@ import {
eq,
inArray,
} from "drizzle-orm";
import { z } from "zod";
import { BaseInterface } from "./base.ts";
type TokenType = InferSelectModel<typeof Tokens> & {

83
classes/database/user.ts
View file

@ -4,10 +4,7 @@ import { randomString } from "@/math";
import { proxyUrl } from "@/response";
import { sentry } from "@/sentry";
import { getLogger } from "@logtape/logtape";
import type {
Account as ApiAccount,
Mention as ApiMention,
} from "@versia/client/types";
import type { Mention as ApiMention } from "@versia/client/types";
import {
EntityValidator,
FederationRequester,
@ -48,13 +45,14 @@ import {
sql,
} from "drizzle-orm";
import { htmlToText } from "html-to-text";
import { z } from "zod";
import type { z } from "zod";
import { findManyUsers } from "~/classes/functions/user";
import { searchManager } from "~/classes/search/search-manager";
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 { BaseInterface } from "./base.ts";
import { Emoji } from "./emoji.ts";
import { Instance } from "./instance.ts";
@ -81,74 +79,6 @@ type UserWithRelations = UserWithInstance & {
* Gives helpers to fetch users from database in a nice format
*/
export class User extends BaseInterface<typeof Users, UserWithRelations> {
// @ts-expect-error Roles are weird
public static schema: z.ZodType<ApiAccount> = z.object({
id: z.string(),
username: z.string(),
acct: z.string(),
display_name: z.string(),
locked: z.boolean(),
discoverable: z.boolean().optional(),
group: z.boolean().nullable(),
noindex: z.boolean().nullable(),
suspended: z.boolean().nullable(),
limited: z.boolean().nullable(),
created_at: z.string(),
followers_count: z.number(),
following_count: z.number(),
statuses_count: z.number(),
note: z.string(),
uri: z.string(),
url: z.string(),
avatar: z.string(),
avatar_static: z.string(),
header: z.string(),
header_static: z.string(),
emojis: z.array(Emoji.schema),
fields: z.array(
z.object({
name: z.string(),
value: z.string(),
verified: z.boolean().optional(),
verified_at: z.string().nullable().optional(),
}),
),
// FIXME: Use a proper type
moved: z.lazy(() => User.schema).nullable(),
bot: z.boolean().nullable(),
source: z
.object({
privacy: z.string().nullable(),
sensitive: z.boolean().nullable(),
language: z.string().nullable(),
note: z.string(),
fields: z.array(
z.object({
name: z.string(),
value: z.string(),
}),
),
avatar: z
.object({
content_type: z.string(),
})
.optional(),
header: z
.object({
content_type: z.string(),
})
.optional(),
})
.optional(),
role: z
.object({
name: z.string(),
})
.optional(),
roles: z.array(Role.schema),
mute_expires_at: z.string().optional(),
});
public static $type: UserWithRelations;
public avatar: Media | null;
@ -1175,7 +1105,7 @@ export class User extends BaseInterface<typeof Users, UserWithRelations> {
return { ok: true };
}
public toApi(isOwnAccount = false): ApiAccount {
public toApi(isOwnAccount = false): z.infer<typeof Account> {
const user = this.data;
return {
id: user.id,
@ -1199,6 +1129,7 @@ export class User extends BaseInterface<typeof Users, UserWithRelations> {
fields: user.fields.map((field) => ({
name: htmlToText(getBestContentType(field.key).content),
value: getBestContentType(field.value).content,
verified_at: null,
})),
bot: user.isBot,
source: isOwnAccount ? user.source : undefined,
@ -1213,8 +1144,8 @@ export class User extends BaseInterface<typeof Users, UserWithRelations> {
moved: null,
noindex: false,
suspended: false,
discoverable: undefined,
mute_expires_at: undefined,
discoverable: null,
mute_expires_at: null,
roles: user.roles
.map((role) => new Role(role))
.concat(

403
classes/schemas/account.ts Normal file
View file

@ -0,0 +1,403 @@
import { z } from "@hono/zod-openapi";
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";
export const Field = z.object({
name: z
.string()
.trim()
.min(1)
.max(config.validation.max_field_name_size)
.openapi({
description: "The key of a given field’s key-value pair.",
example: "Freak level",
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#name",
},
}),
value: z
.string()
.trim()
.min(1)
.max(config.validation.max_field_value_size)
.openapi({
description: "The value associated with the name key.",
example: "<p>High</p>",
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#value",
},
}),
verified_at: z
.string()
.datetime()
.nullable()
.openapi({
description:
"Timestamp of when the server verified a URL value for a rel=“me” link.",
example: null,
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#verified_at",
},
}),
});
export const Source = z
.object({
privacy: z.enum(["public", "unlisted", "private", "direct"]).openapi({
description:
"The default post privacy to be used for new statuses.",
example: "unlisted",
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#source-privacy",
},
}),
sensitive: zBoolean.openapi({
description:
"Whether new statuses should be marked sensitive by default.",
example: false,
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#source-sensitive",
},
}),
language: z
.enum(ISO6391.getAllCodes() as [string, ...string[]])
.openapi({
description: "The default posting language for new statuses.",
example: "en",
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#source-language",
},
}),
follow_requests_count: z
.number()
.int()
.optional()
.openapi({
description: "The number of pending follow requests.",
example: 3,
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#follow_requests_count",
},
}),
note: z
.string()
.trim()
.min(0)
.max(config.validation.max_bio_size)
.refine(
(s) => !config.filters.bio.some((filter) => s.match(filter)),
"Bio contains blocked words",
)
.openapi({
description: "Profile bio, in plain-text instead of in HTML.",
example: "ermmm what the meow meow",
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#source-note",
},
}),
fields: z.array(Field).max(config.validation.max_field_count).openapi({
description: "Metadata about the account.",
}),
})
.openapi({
description:
"An extra attribute that contains source values to be used with API methods that verify credentials and update credentials.",
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#source",
},
});
export const Account = z.object({
id: z
.string()
.uuid()
.openapi({
description: "The account id.",
example: "9e84842b-4db6-4a9b-969d-46ab408278da",
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#id",
},
}),
username: z
.string()
.min(3)
.trim()
.max(config.validation.max_username_size)
.toLowerCase()
.regex(
/^[a-z0-9_-]+$/,
"Username can only contain letters, numbers, underscores and hyphens",
)
.refine(
(s) => !config.filters.username.some((filter) => s.match(filter)),
"Username contains blocked words",
)
.openapi({
description: "The username of the account, not including domain.",
example: "lexi",
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#username",
},
}),
acct: z.string().openapi({
description:
"The Webfinger account URI. Equal to username for local users, or username@domain for remote users.",
example: "lexi@beta.versia.social",
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#acct",
},
}),
url: z
.string()
.url()
.openapi({
description: "The location of the user’s profile page.",
example: "https://beta.versia.social/@lexi",
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#url",
},
}),
display_name: z
.string()
.min(3)
.trim()
.max(config.validation.max_displayname_size)
.refine(
(s) =>
!config.filters.displayname.some((filter) => s.match(filter)),
"Display name contains blocked words",
)
.openapi({
description: "The profile’s display name.",
example: "Lexi :flower:",
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#display_name",
},
}),
note: z
.string()
.min(0)
.max(config.validation.max_bio_size)
.trim()
.refine(
(s) => !config.filters.bio.some((filter) => s.match(filter)),
"Bio contains blocked words",
)
.openapi({
description: "The profile’s bio or description.",
example: "<p>ermmm what the meow meow</p>",
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#note",
},
}),
avatar: z
.string()
.url()
.openapi({
description:
"An image icon that is shown next to statuses and in the profile.",
example:
"https://cdn.versia.social/avatars/cff9aea0-0000-43fe-8b5e-e7c7ea69a488/lexi.webp",
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#avatar",
},
}),
avatar_static: z
.string()
.url()
.openapi({
description:
"A static version of the avatar. Equal to avatar if its value is a static image; different if avatar is an animated GIF.",
example:
"https://cdn.versia.social/avatars/cff9aea0-0000-43fe-8b5e-e7c7ea69a488/lexi.webp",
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#avatar_static",
},
}),
header: z
.string()
.url()
.openapi({
description:
"An image banner that is shown above the profile and in profile cards.",
example:
"https://cdn.versia.social/headers/a049f8e3-878c-4faa-ae4c-a6bcceddbd9d/femboy_2.webp",
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#header",
},
}),
header_static: z
.string()
.url()
.openapi({
description:
"A static version of the header. Equal to header if its value is a static image; different if header is an animated GIF.",
example:
"https://cdn.versia.social/headers/a049f8e3-878c-4faa-ae4c-a6bcceddbd9d/femboy_2.webp",
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#header_static",
},
}),
locked: zBoolean.openapi({
description: "Whether the account manually approves follow requests.",
example: false,
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#locked",
},
}),
fields: z
.array(Field)
.max(config.validation.max_field_count)
.openapi({
description:
"Additional metadata attached to a profile as name-value pairs.",
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#fields",
},
}),
emojis: z.array(Emoji.schema).openapi({
description:
"Custom emoji entities to be used when rendering the profile.",
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#emojis",
},
}),
bot: zBoolean.openapi({
description:
"Indicates that the account may perform automated actions, may not be monitored, or identifies as a robot.",
example: false,
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#bot",
},
}),
group: z.literal(false).openapi({
description: "Indicates that the account represents a Group actor.",
example: false,
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#group",
},
}),
discoverable: zBoolean.nullable().openapi({
description:
"Whether the account has opted into discovery features such as the profile directory.",
example: true,
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#discoverable",
},
}),
noindex: zBoolean
.nullable()
.optional()
.openapi({
description:
"Whether the local user has opted out of being indexed by search engines.",
example: false,
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#noindex",
},
}),
// FIXME: Use a proper type
moved: z
.lazy((): z.ZodType<ApiAccount> => Account as z.ZodType<ApiAccount>)
.nullable()
.optional()
.openapi({
description:
"Indicates that the profile is currently inactive and that its user has moved to a new account.",
example: null,
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#moved",
},
}),
suspended: zBoolean.optional().openapi({
description:
"An extra attribute returned only when an account is suspended.",
example: false,
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#suspended",
},
}),
limited: zBoolean.optional().openapi({
description:
"An extra attribute returned only when an account is silenced. If true, indicates that the account should be hidden behind a warning screen.",
example: false,
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#limited",
},
}),
created_at: z
.string()
.datetime()
.openapi({
description: "When the account was created.",
example: "2024-10-15T22:00:00.000Z",
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#created_at",
},
}),
// TODO
last_status_at: z
.literal(null)
.openapi({
description: "When the most recent status was posted.",
example: null,
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#last_status_at",
},
})
.nullable(),
statuses_count: z
.number()
.min(0)
.int()
.openapi({
description: "How many statuses are attached to this account.",
example: 42,
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#statuses_count",
},
}),
followers_count: z
.number()
.min(0)
.int()
.openapi({
description: "The reported followers of this profile.",
example: 6,
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#followers_count",
},
}),
following_count: z
.number()
.min(0)
.int()
.openapi({
description: "The reported follows of this profile.",
example: 23,
externalDocs: {
url: "https://docs.joinmastodon.org/entities/Account/#following_count",
},
}),
uri: z.string().url().openapi({
description:
"The location of the user's Versia profile page, as opposed to the local representation.",
example:
"https://beta.versia.social/users/9e84842b-4db6-4a9b-969d-46ab408278da",
}),
source: Source.optional(),
role: z
.object({
name: z.string(),
})
.optional(),
roles: z.array(Role.schema),
mute_expires_at: z.string().datetime().nullable().openapi({
description: "When a timed mute will expire, if applicable.",
example: "2025-03-01T14:00:00.000Z",
}),
});