Adding some API comments.

This commit is contained in:
Dessalines 2021-01-18 14:32:18 -05:00
parent e2bcc3f476
commit 365bc490b4
6 changed files with 83 additions and 25 deletions

View file

@ -4,7 +4,7 @@ export interface CreateComment {
content: string;
parent_id?: number;
post_id: number;
form_id?: string;
form_id?: string; // An optional front end ID, to tell which is coming back
auth: string;
}
@ -15,12 +15,18 @@ export interface EditComment {
auth: string;
}
/**
* Only the creator can delete the comment.
*/
export interface DeleteComment {
edit_id: number;
deleted: boolean;
auth: string;
}
/**
* Only a mod or admin can remove the comment.
*/
export interface RemoveComment {
edit_id: number;
removed: boolean;
@ -28,6 +34,9 @@ export interface RemoveComment {
auth: string;
}
/**
* Only the recipient can do this.
*/
export interface MarkCommentAsRead {
comment_id: number;
read: boolean;
@ -42,8 +51,8 @@ export interface SaveComment {
export interface CommentResponse {
comment_view: CommentView;
recipient_ids: number[]; // TODO another way to do this? Maybe a UserMention belongs to Comment
form_id?: string; // An optional front end ID, to tell which is coming ba,
recipient_ids: number[];
form_id?: string; // An optional front end ID, to tell which is coming back
}
export interface CreateCommentLike {
@ -52,6 +61,11 @@ export interface CreateCommentLike {
auth: string;
}
/**
* Comment listing types are `All, Subscribed, Community`
*
* `community_name` can only be used for local communities. To get posts for a federated community, pass `community_id` instead.
*/
export interface GetComments {
type_: string;
sort: string;

View file

@ -47,7 +47,7 @@ export interface BanFromCommunity {
community_id: number;
user_id: number;
ban: boolean;
remove_data: boolean;
remove_data: boolean; // Removes/Restores their comments and posts for that community
reason?: string;
expires?: number;
auth: string;
@ -69,6 +69,9 @@ export interface AddModToCommunityResponse {
moderators: CommunityModeratorView[];
}
/**
* Only mods can edit a community.
*/
export interface EditCommunity {
edit_id: number;
title: string;
@ -86,6 +89,9 @@ export interface DeleteCommunity {
auth: string;
}
/**
* Only admins can remove a community.
*/
export interface RemoveCommunity {
edit_id: number;
removed: boolean;
@ -114,6 +120,9 @@ export interface TransferCommunity {
auth: string;
}
/**
* The main / frontpage community is `community_id: 0`.
*/
export interface CommunityJoin {
community_id: number;
}

View file

@ -32,6 +32,11 @@ export interface GetPostResponse {
online: number;
}
/**
* Post listing types are `All, Subscribed, Community`
*
* `community_name` can only be used for local communities. To get posts for a federated community, pass `community_id` instead.
*/
export interface GetPosts {
type_: string;
sort: string;
@ -46,6 +51,9 @@ export interface GetPostsResponse {
posts: PostView[];
}
/**
* `score` can be 0, -1, or 1
*/
export interface CreatePostLike {
post_id: number;
score: number;
@ -67,6 +75,9 @@ export interface DeletePost {
auth: string;
}
/**
* Only admins and mods can remove a post.
*/
export interface RemovePost {
edit_id: number;
removed: boolean;
@ -74,12 +85,18 @@ export interface RemovePost {
auth: string;
}
/**
* Only admins and mods can lock a post.
*/
export interface LockPost {
edit_id: number;
locked: boolean;
auth: string;
}
/**
* Only admins and mods can sticky a post.
*/
export interface StickyPost {
edit_id: number;
stickied: boolean;

View file

@ -22,6 +22,9 @@ export interface ListCategoriesResponse {
categories: Category[];
}
/**
* Search types are `All, Comments, Posts, Communities, Users, Url`
*/
export interface Search {
q: string;
type_: string;
@ -96,7 +99,7 @@ export interface GetSiteResponse {
banned: UserViewSafe[];
online: number;
version: string;
my_user?: User_;
my_user?: User_; // Gives back your user and settings if logged in
federated_instances: string[];
}

View file

@ -14,6 +14,9 @@ export interface Login {
password: string;
}
/**
* Only the first user will be able to be the admin.
*/
export interface Register {
username: string;
email?: string;
@ -21,14 +24,14 @@ export interface Register {
password_verify: string;
admin: boolean;
show_nsfw: boolean;
captcha_uuid?: string;
captcha_uuid?: string; // Only checked if these are enabled in the server
captcha_answer?: string;
}
export interface GetCaptcha {}
export interface GetCaptchaResponse {
ok?: CaptchaResponse;
ok?: CaptchaResponse; // Will be undefined if captchas are disabled
}
export interface CaptchaResponse {
@ -39,9 +42,9 @@ export interface CaptchaResponse {
export interface SaveUserSettings {
show_nsfw: boolean;
theme: string;
default_sort_type: number;
default_listing_type: number;
theme: string; // Default 'default'
default_sort_type: number; // The Sort types from above, zero indexed as a number
default_listing_type: number; // Post listing types are `All, Subscribed, Community`
lang: string;
avatar?: string;
banner?: string;
@ -57,10 +60,16 @@ export interface SaveUserSettings {
auth: string;
}
/**
* The `jwt` string should be stored and used anywhere `auth` is called for.
*/
export interface LoginResponse {
jwt: string;
}
/**
* `username` can only be used for local users. To get details for a federated user, pass `user_id` instead.
*/
export interface GetUserDetails {
user_id?: number;
username?: string;
@ -106,7 +115,7 @@ export interface AddAdminResponse {
export interface BanUser {
user_id: number;
ban: boolean;
remove_data: boolean;
remove_data: boolean; // Removes/Restores their comments, posts, and communities
reason?: string;
expires?: number;
auth: string;
@ -143,6 +152,9 @@ export interface UserMentionResponse {
user_mention_view: UserMentionView;
}
/**
* Permanently deletes your posts and comments
*/
export interface DeleteAccount {
password: string;
auth: string;
@ -207,6 +219,9 @@ export interface UserJoinResponse {
joined: boolean;
}
/**
* If a community is supplied, returns the report count for only that community, otherwise returns the report count for all communities the user moderates.
*/
export interface GetReportCount {
community?: number;
auth: string;

View file

@ -46,10 +46,10 @@ export interface UserMentionView {
community: CommunitySafe;
recipient: UserSafe;
counts: CommentAggregates;
creator_banned_from_community: boolean; // Left Join to CommunityUserBan
subscribed: boolean; // Left join to CommunityFollower
saved: boolean; // Left join to CommentSaved
my_vote?: number; // Left join to CommentLi,
creator_banned_from_community: boolean;
subscribed: boolean;
saved: boolean;
my_vote?: number;
}
export interface SiteView {
@ -68,12 +68,12 @@ export interface PostView {
post: Post;
creator: UserSafe;
community: CommunitySafe;
creator_banned_from_community: boolean; // Left Join to CommunityUserBan
creator_banned_from_community: boolean;
counts: PostAggregates;
subscribed: boolean; // Left join to CommunityFollower
saved: boolean; // Left join to PostSaved
read: boolean; // Left join to PostRead
my_vote?: number; // Left join to PostLi,
subscribed: boolean;
saved: boolean;
read: boolean;
my_vote?: number;
}
export interface PostReportView {
@ -88,14 +88,14 @@ export interface PostReportView {
export interface CommentView {
comment: Comment;
creator: UserSafe;
recipient?: UserSafe; // Left joins to comment and us,
recipient?: UserSafe;
post: Post;
community: CommunitySafe;
counts: CommentAggregates;
creator_banned_from_community: boolean; // Left Join to CommunityUserBan
subscribed: boolean; // Left join to CommunityFollower
saved: boolean; // Left join to CommentSaved
my_vote?: number; // Left join to CommentLi,
creator_banned_from_community: boolean;
subscribed: boolean;
saved: boolean;
my_vote?: number;
}
export interface CommentReportView {