130 lines
3.6 KiB
TypeScript
130 lines
3.6 KiB
TypeScript
/**
|
|
* Users as the API shows them, their roles, and the bodies and answers of
|
|
* sign-up, sign-in, profile edits and invites.
|
|
*
|
|
* @module
|
|
*/
|
|
|
|
/** What a user may do beyond the basics; see `ROLE_PERMISSIONS`. */
|
|
export type Role = "user" | "moderator" | "admin";
|
|
|
|
/** Every {@link Role}, least to most privileged. */
|
|
export const ROLES: readonly Role[] = ["user", "moderator", "admin"];
|
|
|
|
/** Checks whether `value` is a {@link Role}. */
|
|
export function isRole(value: unknown): value is Role {
|
|
return typeof value === "string" &&
|
|
(ROLES as readonly string[]).includes(value);
|
|
}
|
|
|
|
/** A user as anyone may see them: no password hash, no email. */
|
|
export interface PublicUser {
|
|
/** The user's id. */
|
|
id: string;
|
|
/** The user's name, fixed at sign-up. */
|
|
username: string;
|
|
/** The user's role. */
|
|
role: Role;
|
|
/** When the user signed up. */
|
|
createdAt: Date;
|
|
/** When the user last changed, if ever. */
|
|
updatedAt?: Date;
|
|
/** The avatar's type, undefined without one. */
|
|
avatarMime?: string;
|
|
/** The user's description of themselves, in Markdown. */
|
|
description?: string;
|
|
/** The name of whoever invited them. */
|
|
invitedByUsername?: string;
|
|
}
|
|
|
|
/** A user as they see themselves: everything but the password hash. */
|
|
export interface SelfUser extends PublicUser {
|
|
/** The address password resets are sent to. */
|
|
email: string;
|
|
}
|
|
|
|
/** A match for the @mention autocomplete. */
|
|
export interface UserSuggestion {
|
|
/** The user's id. */
|
|
id: string;
|
|
/** The user's name. */
|
|
username: string;
|
|
/** The avatar's type, null without one. */
|
|
avatarMime: string | null;
|
|
}
|
|
|
|
/** Someone a user invited, directly or down the line. */
|
|
export interface Invitee {
|
|
/** The user's id. */
|
|
id: string;
|
|
/** The user's name. */
|
|
username: string;
|
|
/** The avatar's type, undefined without one. */
|
|
avatarMime?: string;
|
|
/** The id of whoever invited them, to build the tree. */
|
|
invitedById: string;
|
|
/** When they signed up. */
|
|
createdAt: Date;
|
|
}
|
|
|
|
/** The body of `POST /api/users/login`. */
|
|
export interface LoginUserRequest {
|
|
/** The user's name. */
|
|
username: string;
|
|
/** The user's password. */
|
|
password: string;
|
|
}
|
|
|
|
/** The body of `POST /api/users/register`. */
|
|
export interface RegisterUserRequest {
|
|
/** The name to sign up with. */
|
|
username: string;
|
|
/** The password to sign up with. */
|
|
password: string;
|
|
/** The invite's token. */
|
|
inviteToken: string;
|
|
/** The address password resets will be sent to. */
|
|
email: string;
|
|
}
|
|
|
|
/**
|
|
* Fields of a user to change. `PATCH /api/users/me` takes only `description`
|
|
* and `email` from it; the role and the password change through their own
|
|
* endpoints.
|
|
*/
|
|
export interface UpdateUserRequest {
|
|
/** The new name. */
|
|
username?: string;
|
|
/** The new password. */
|
|
password?: string;
|
|
/** The new role. */
|
|
role?: Role;
|
|
/** The new description; `null` removes it. */
|
|
description?: string | null;
|
|
/** The new email address. */
|
|
email?: string;
|
|
}
|
|
|
|
/** The session token, plus the media-only one for file and thumbnail URLs. */
|
|
export interface AuthTokens {
|
|
/** The session token, sent as a bearer token. */
|
|
token: string;
|
|
/** The token media URLs carry as `?token=`, good for nothing else. */
|
|
mediaToken: string;
|
|
}
|
|
|
|
/** What sign-up and sign-in answer: the user and their tokens. */
|
|
export interface AuthResponse extends AuthTokens {
|
|
/** The signed-in user. */
|
|
user: SelfUser;
|
|
}
|
|
|
|
/** `GET /api/users/me/media-token`: a fresh media token. */
|
|
export type MediaTokenResponse = Pick<AuthTokens, "mediaToken">;
|
|
|
|
/** `POST /api/invites`: the new invite's token. */
|
|
export interface InviteResponse {
|
|
/** The token, which the invite link carries. */
|
|
token: string;
|
|
}
|