From 365bc490b482259118c7473d479218d1e6f3fc82 Mon Sep 17 00:00:00 2001 From: Dessalines Date: Mon, 18 Jan 2021 14:32:18 -0500 Subject: [PATCH] Adding some API comments. --- src/interfaces/api/comment.ts | 20 +++++++++++++++++--- src/interfaces/api/community.ts | 11 ++++++++++- src/interfaces/api/post.ts | 17 +++++++++++++++++ src/interfaces/api/site.ts | 5 ++++- src/interfaces/api/user.ts | 27 +++++++++++++++++++++------ src/interfaces/views.ts | 28 ++++++++++++++-------------- 6 files changed, 83 insertions(+), 25 deletions(-) diff --git a/src/interfaces/api/comment.ts b/src/interfaces/api/comment.ts index 635ce8d..e1769a8 100644 --- a/src/interfaces/api/comment.ts +++ b/src/interfaces/api/comment.ts @@ -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; diff --git a/src/interfaces/api/community.ts b/src/interfaces/api/community.ts index 214fdda..78dc3ee 100644 --- a/src/interfaces/api/community.ts +++ b/src/interfaces/api/community.ts @@ -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; } diff --git a/src/interfaces/api/post.ts b/src/interfaces/api/post.ts index 71d8018..1863f49 100644 --- a/src/interfaces/api/post.ts +++ b/src/interfaces/api/post.ts @@ -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; diff --git a/src/interfaces/api/site.ts b/src/interfaces/api/site.ts index b5af2ce..11db1ef 100644 --- a/src/interfaces/api/site.ts +++ b/src/interfaces/api/site.ts @@ -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[]; } diff --git a/src/interfaces/api/user.ts b/src/interfaces/api/user.ts index 6efe468..1607e25 100644 --- a/src/interfaces/api/user.ts +++ b/src/interfaces/api/user.ts @@ -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; diff --git a/src/interfaces/views.ts b/src/interfaces/views.ts index f77485b..814ab89 100644 --- a/src/interfaces/views.ts +++ b/src/interfaces/views.ts @@ -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 {