pl-api: Update docs

Signed-off-by: marcin mikołajczak <git@mkljczk.pl>

packages/pl-api/lib/entities/admin/pleroma-config.ts

@@ -1,5 +1,8 @@
 import * as v from 'valibot';
 
+/**
+ * @category Schemas
+ */
 const pleromaConfigSchema = v.object({
   configs: v.array(v.object({
     value: v.any(),

packages/pl-api/lib/entities/emoji-reaction.ts

@@ -22,6 +22,8 @@ const customEmojiReactionSchema = v.object({
 
 /**
  * Pleroma emoji reaction.
+ *
+ * @category Schemas
  * @see {@link https://docs.pleroma.social/backend/development/API/differences_in_mastoapi_responses/#statuses}
 */
 const emojiReactionSchema = v.pipe(

packages/pl-api/lib/entities/extended-description.ts

@@ -2,7 +2,10 @@ import * as v from 'valibot';
 
 import { datetimeSchema } from './utils';
 
-/** @see {@link https://docs.joinmastodon.org/entities/ExtendedDescription} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/ExtendedDescription}
+ */
 const extendedDescriptionSchema = v.object({
   updated_at: datetimeSchema,
   content: v.string(),

packages/pl-api/lib/entities/familiar-followers.ts

@@ -3,7 +3,10 @@ import * as v from 'valibot';
 import { accountSchema } from './account';
 import { filteredArray } from './utils';
 
-/** @see {@link https://docs.joinmastodon.org/entities/FamiliarFollowers/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/FamiliarFollowers/}
+ */
 const familiarFollowersSchema = v.object({
   id: v.string(),
   accounts: filteredArray(accountSchema),

packages/pl-api/lib/entities/featured-tag.ts

@@ -1,6 +1,9 @@
 import * as v from 'valibot';
 
-/** @see {@link https://docs.joinmastodon.org/entities/FeaturedTag/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/FeaturedTag/}
+ */
 const featuredTagSchema = v.object({
   id: v.string(),
   name: v.string(),

packages/pl-api/lib/entities/filter-result.ts

@@ -2,7 +2,10 @@ import * as v from 'valibot';
 
 import { filterSchema } from './filter';
 
-/** @see {@link https://docs.joinmastodon.org/entities/FilterResult/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/FilterResult/}
+ */
 const filterResultSchema = v.object({
   filter: filterSchema,
   keyword_matches: v.fallback(v.nullable(v.string()), null),

packages/pl-api/lib/entities/filter.ts

@@ -2,20 +2,29 @@ import * as v from 'valibot';
 
 import { datetimeSchema, filteredArray } from './utils';
 
-/** @see {@link https://docs.joinmastodon.org/entities/FilterKeyword/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/FilterKeyword/}
+ */
 const filterKeywordSchema = v.object({
   id: v.string(),
   keyword: v.string(),
   whole_word: v.boolean(),
 });
 
-/** @see {@link https://docs.joinmastodon.org/entities/FilterStatus/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/FilterStatus/}
+ */
 const filterStatusSchema = v.object({
   id: v.string(),
   status_id: v.string(),
 });
 
-/** @see {@link https://docs.joinmastodon.org/entities/Filter/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/Filter/}
+ */
 const filterSchema = v.pipe(
   v.any(),
   v.transform((filter: any) => {

packages/pl-api/lib/entities/group-member.ts

@@ -10,6 +10,9 @@ enum GroupRoles {
 
 type GroupRole =`${GroupRoles}`;
 
+/**
+ * @category Schemas
+ */
 const groupMemberSchema = v.object({
   id: v.string(),
   account: accountSchema,

packages/pl-api/lib/entities/group-relationship.ts

@@ -2,6 +2,9 @@ import * as v from 'valibot';
 
 import { GroupRoles } from './group-member';
 
+/**
+ * @category Schemas
+ */
 const groupRelationshipSchema = v.object({
   id: v.string(),
   member: v.fallback(v.boolean(), false),

packages/pl-api/lib/entities/group.ts

@@ -4,6 +4,9 @@ import { customEmojiSchema } from './custom-emoji';
 import { groupRelationshipSchema } from './group-relationship';
 import { datetimeSchema, filteredArray } from './utils';
 
+/**
+ * @category Schemas
+ */
 const groupSchema = v.object({
   avatar: v.fallback(v.string(), ''),
   avatar_static: v.fallback(v.string(), ''),

packages/pl-api/lib/entities/instance.ts

@@ -290,7 +290,10 @@ const instanceV1Schema = coerceObject({
   version: v.fallback(v.string(), '0.0.0'),
 });
 
-/** @see {@link https://docs.joinmastodon.org/entities/Instance/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/Instance/}
+ */
 const instanceSchema = v.pipe(
   v.any(),
   v.transform((data: any) => {

packages/pl-api/lib/entities/interaction-policy.ts

@@ -11,7 +11,10 @@ const interactionPolicyRuleSchema = coerceObject({
   with_approval: v.fallback(v.array(interactionPolicyEntrySchema), []),
 });
 
-/** @see {@link https://docs.gotosocial.org/en/latest/api/swagger/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.gotosocial.org/en/latest/api/swagger/}
+ */
 const interactionPolicySchema = coerceObject({
   can_favourite: interactionPolicyRuleSchema,
   can_reblog: interactionPolicyRuleSchema,
@@ -20,6 +23,9 @@ const interactionPolicySchema = coerceObject({
 
 type InteractionPolicy = v.InferOutput<typeof interactionPolicySchema>;
 
+/**
+ * @category Schemas
+ */
 const interactionPoliciesSchema = coerceObject({
   public: interactionPolicySchema,
   unlisted: interactionPolicySchema,

packages/pl-api/lib/entities/interaction-request.ts

@@ -4,7 +4,10 @@ import { accountSchema } from './account';
 import { statusSchema } from './status';
 import { datetimeSchema } from './utils';
 
-/** @see {@link https://docs.gotosocial.org/en/latest/api/swagger.yaml#/definitions/interactionRequest} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.gotosocial.org/en/latest/api/swagger.yaml#/definitions/interactionRequest}
+ */
 const interactionRequestSchema = v.object({
   accepted_at: v.fallback(v.nullable(datetimeSchema), null),
   account: accountSchema,

packages/pl-api/lib/entities/list.ts

@@ -1,6 +1,9 @@
 import * as v from 'valibot';
 
-/** @see {@link https://docs.joinmastodon.org/entities/List/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/List/}
+ */
 const listSchema = v.object({
   id: v.pipe(v.unknown(), v.transform(String)),
   title: v.string(),

packages/pl-api/lib/entities/location.ts

@@ -1,5 +1,8 @@
 import * as v from 'valibot';
 
+/**
+ * @category Schemas
+ */
 const locationSchema = v.object({
   url: v.fallback(v.pipe(v.string(), v.url()), ''),
   description: v.fallback(v.string(), ''),

packages/pl-api/lib/entities/marker.ts

@@ -2,6 +2,10 @@ import * as v from 'valibot';
 
 import { datetimeSchema } from './utils';
 
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/Marker/}
+ */
 const markerSchema = v.pipe(
   v.any(),
   v.transform((marker: any) => marker ? ({
@@ -16,9 +20,11 @@ const markerSchema = v.pipe(
   }),
 );
 
-/** @see {@link https://docs.joinmastodon.org/entities/Marker/} */
 type Marker = v.InferOutput<typeof markerSchema>;
 
+/**
+ * @category Schemas
+ */
 const markersSchema = v.record(v.string(), markerSchema);
 
 type Markers = v.InferOutput<typeof markersSchema>;

packages/pl-api/lib/entities/media-attachment.ts

@@ -3,6 +3,9 @@ import * as v from 'valibot';
 
 import { mimeSchema } from './utils';
 
+/**
+ * @category Schemas
+ */
 const blurhashSchema = v.pipe(v.string(), v.check(
   (value) => isBlurhashValid(value).result,
   'invalid blurhash', // .errorReason
@@ -87,7 +90,10 @@ const unknownAttachmentSchema = v.object({
   type: v.literal('unknown'),
 });
 
-/** @see {@link https://docs.joinmastodon.org/entities/MediaAttachment} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/MediaAttachment}
+ */
 const mediaAttachmentSchema = v.pipe(
   v.any(),
   v.transform((data: any) => {

packages/pl-api/lib/entities/mention.ts

@@ -1,6 +1,9 @@
 import * as v from 'valibot';
 
-/** @see {@link https://docs.joinmastodon.org/entities/Status/#Mention} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/Status/#Mention}
+ */
 const mentionSchema = v.pipe(
   v.object({
     id: v.string(),

packages/pl-api/lib/entities/notification-policy.ts

@@ -2,7 +2,10 @@ import * as v from 'valibot';
 
 const notificationPolicyRuleSchema = v.picklist(['accept', 'filter', 'drop']);
 
-/** @see {@link https://docs.joinmastodon.org/entities/NotificationPolicy} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/NotificationPolicy}
+ */
 const notificationPolicySchema = v.object({
   for_not_following: notificationPolicyRuleSchema,
   for_not_followers: notificationPolicyRuleSchema,

packages/pl-api/lib/entities/notification-request.ts

@@ -4,7 +4,10 @@ import { accountSchema } from './account';
 import { statusSchema } from './status';
 import { datetimeSchema } from './utils';
 
-/** @see {@link https://docs.joinmastodon.org/entities/NotificationRequest} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/NotificationRequest}
+ */
 const notificationRequestSchema = v.object({
   id: v.string(),
   created_at: datetimeSchema,

packages/pl-api/lib/entities/notification.ts

@@ -83,7 +83,10 @@ const eventParticipationRequestNotificationSchema = v.object({
   participation_message: v.fallback(v.nullable(v.string()), null),
 });
 
-/** @see {@link https://docs.joinmastodon.org/entities/Notification/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/Notification/}
+ * */
 const notificationSchema: v.BaseSchema<any, Notification, v.BaseIssue<unknown>> = v.pipe(
   v.any(),
   v.transform((notification: any) => ({

packages/pl-api/lib/entities/oauth-token.ts

@@ -2,7 +2,10 @@ import * as v from 'valibot';
 
 import { datetimeSchema } from './utils';
 
-/** @see {@link https://docs.pleroma.social/backend/development/API/pleroma_api/#get-apioauth_tokens} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.pleroma.social/backend/development/API/pleroma_api/#get-apioauth_tokens}
+ */
 const oauthTokenSchema = v.pipe(
   v.any(),
   v.transform((token: any) => ({

packages/pl-api/lib/entities/poll.ts

@@ -10,7 +10,10 @@ const pollOptionSchema = v.object({
   title_map: v.fallback(v.nullable(v.record(v.string(), v.string())), null),
 });
 
-/** @see {@link https://docs.joinmastodon.org/entities/Poll/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/Poll/}
+ */
 const pollSchema = v.object({
   emojis: filteredArray(customEmojiSchema),
   expired: v.fallback(v.boolean(), false),

packages/pl-api/lib/entities/preview-card.ts

@@ -1,6 +1,9 @@
 import * as v from 'valibot';
 
-/** @see {@link https://docs.joinmastodon.org/entities/PreviewCard/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/PreviewCard/}
+ */
 const previewCardSchema = v.object({
   author_name: v.fallback(v.string(), ''),
   author_url: v.fallback(v.pipe(v.string(), v.url()), ''),

packages/pl-api/lib/entities/relationship-severance-event.ts

@@ -2,7 +2,10 @@ import * as v from 'valibot';
 
 import { datetimeSchema } from './utils';
 
-/** @see {@link https://docs.joinmastodon.org/entities/RelationshipSeveranceEvent/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/RelationshipSeveranceEvent/}
+ */
 const relationshipSeveranceEventSchema = v.object({
   id: v.string(),
   type: v.picklist(['domain_block', 'user_domain_block', 'account_suspension']),

packages/pl-api/lib/entities/relationship.ts

@@ -1,6 +1,9 @@
 import * as v from 'valibot';
 
-/** @see {@link https://docs.joinmastodon.org/entities/Relationship/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/Relationship/}
+ */
 const relationshipSchema = v.object({
   blocked_by: v.fallback(v.boolean(), false),
   blocking: v.fallback(v.boolean(), false),

packages/pl-api/lib/entities/report.ts

@@ -3,7 +3,10 @@ import * as v from 'valibot';
 import { accountSchema } from './account';
 import { datetimeSchema } from './utils';
 
-/** @see {@link https://docs.joinmastodon.org/entities/Report/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/Report/}
+ */
 const reportSchema = v.object({
   id: v.string(),
   action_taken: v.fallback(v.optional(v.boolean()), undefined),

packages/pl-api/lib/entities/role.ts

@@ -2,6 +2,9 @@ import * as v from 'valibot';
 
 const hexSchema = v.pipe(v.string(), v.regex(/^#[a-f0-9]{6}$/i));
 
+/**
+ * @category Schemas
+ */
 const roleSchema = v.object({
   id: v.fallback(v.string(), ''),
   name: v.fallback(v.string(), ''),

packages/pl-api/lib/entities/rule.ts

@@ -6,7 +6,10 @@ const baseRuleSchema = v.object({
   hint: v.fallback(v.string(), ''),
 });
 
-/** @see {@link https://docs.joinmastodon.org/entities/Rule/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/Rule/}
+ */
 const ruleSchema = v.pipe(
   v.any(),
   v.transform((data: any) => ({

packages/pl-api/lib/entities/scheduled-status.ts

@@ -3,7 +3,10 @@ import * as v from 'valibot';
 import { mediaAttachmentSchema } from './media-attachment';
 import { datetimeSchema, filteredArray } from './utils';
 
-/** @see {@link https://docs.joinmastodon.org/entities/ScheduledStatus/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/ScheduledStatus/}
+ */
 const scheduledStatusSchema = v.object({
   id: v.string(),
   scheduled_at: datetimeSchema,

packages/pl-api/lib/entities/scrobble.ts

@@ -3,6 +3,9 @@ import * as v from 'valibot';
 import { accountSchema } from './account';
 import { datetimeSchema } from './utils';
 
+/**
+ * @category Schemas
+ */
 const scrobbleSchema = v.pipe(
   v.any(),
   v.transform((scrobble: any) => scrobble ? {

packages/pl-api/lib/entities/search.ts

@@ -6,7 +6,10 @@ import { statusSchema } from './status';
 import { tagSchema } from './tag';
 import { filteredArray } from './utils';
 
-/** @see {@link https://docs.joinmastodon.org/entities/Search} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/Search}
+ */
 const searchSchema = v.object({
   accounts: filteredArray(accountSchema),
   statuses: filteredArray(statusSchema),

packages/pl-api/lib/entities/status-edit.ts

@@ -5,7 +5,10 @@ import { customEmojiSchema } from './custom-emoji';
 import { mediaAttachmentSchema } from './media-attachment';
 import { datetimeSchema, filteredArray } from './utils';
 
-/** @see {@link https://docs.joinmastodon.org/entities/StatusEdit/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/StatusEdit/}
+ */
 const statusEditSchema = v.object({
   content: v.fallback(v.string(), ''),
   spoiler_text: v.fallback(v.string(), ''),

packages/pl-api/lib/entities/status-source.ts

@@ -2,7 +2,10 @@ import * as v from 'valibot';
 
 import { locationSchema } from './location';
 
-/** @see {@link https://docs.joinmastodon.org/entities/StatusSource/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/StatusSource/}
+ */
 const statusSourceSchema = v.object({
   id: v.string(),
   text: v.fallback(v.string(), ''),

packages/pl-api/lib/entities/status.ts

@@ -134,6 +134,9 @@ const preprocess = (status: any) => {
   return status;
 };
 
+/**
+ * @category Schemas
+ */
 const statusSchema: v.BaseSchema<any, Status, v.BaseIssue<unknown>> = v.pipe(v.any(), v.transform(preprocess), v.object({
   ...baseStatusSchema.entries,
   reblog: v.fallback(v.nullable(v.lazy(() => statusSchema)), null),
@@ -141,6 +144,9 @@ const statusSchema: v.BaseSchema<any, Status, v.BaseIssue<unknown>> = v.pipe(v.a
   quote: v.fallback(v.nullable(v.lazy(() => statusSchema)), null),
 })) as any;
 
+/**
+ * @category Schemas
+ */
 const statusWithoutAccountSchema = v.pipe(v.any(), v.transform(preprocess), v.object({
   ...(v.omit(baseStatusSchema, ['account']).entries),
   account: v.fallback(v.nullable(accountSchema), null),

packages/pl-api/lib/entities/streaming-event.ts

@@ -8,6 +8,9 @@ import { markersSchema } from './marker';
 import { notificationSchema } from './notification';
 import { statusSchema } from './status';
 
+/**
+ * @category Schemas
+ */
 const followRelationshipUpdateSchema = v.object({
   state: v.picklist(['follow_pending', 'follow_accept', 'follow_reject']),
   follower: v.object({
@@ -96,7 +99,10 @@ const markerStreamingEventSchema = v.object({
   payload: v.pipe(v.any(), v.transform((payload: any) => JSON.parse(payload)), markersSchema),
 });
 
-/** @see {@link https://docs.joinmastodon.org/methods/streaming/#events} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/methods/streaming/#events}
+ */
 const streamingEventSchema: v.BaseSchema<any, StreamingEvent, v.BaseIssue<unknown>> = v.pipe(
   v.any(),
   v.transform((event: any) => ({

packages/pl-api/lib/entities/suggestion.ts

@@ -2,7 +2,10 @@ import * as v from 'valibot';
 
 import { accountSchema } from './account';
 
-/** @see {@link https://docs.joinmastodon.org/entities/Suggestion} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/Suggestion}
+ */
 const suggestionSchema = v.pipe(
   v.any(),
   v.transform((suggestion: any) => {

packages/pl-api/lib/entities/tag.ts

@@ -1,12 +1,18 @@
 import * as v from 'valibot';
 
+/**
+ * @category Schemas
+ */
 const historySchema = v.array(v.object({
   day: v.pipe(v.unknown(), v.transform(Number)),
   accounts: v.pipe(v.unknown(), v.transform(Number)),
   uses: v.pipe(v.unknown(), v.transform(Number)),
 }));
 
-/** @see {@link https://docs.joinmastodon.org/entities/tag} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/tag}
+ */
 const tagSchema = v.object({
   name: v.pipe(v.string(), v.minLength(1)),
   url: v.fallback(v.pipe(v.string(), v.url()), ''),

packages/pl-api/lib/entities/token.ts

@@ -1,6 +1,9 @@
 import * as v from 'valibot';
 
-/** @see {@link https://docs.joinmastodon.org/entities/Token/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/Token/}
+ */
 const tokenSchema = v.object({
   access_token: v.string(),
   token_type: v.string(),

packages/pl-api/lib/entities/translation.ts

@@ -14,7 +14,10 @@ const translationMediaAttachment = v.object({
   description: v.fallback(v.string(), ''),
 });
 
-/** @see {@link https://docs.joinmastodon.org/entities/Translation/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/Translation/}
+ */
 const translationSchema = v.pipe(
   v.any(),
   v.transform((translation: any) => {

packages/pl-api/lib/entities/trends-link.ts

@@ -3,7 +3,10 @@ import * as v from 'valibot';
 import { blurhashSchema } from './media-attachment';
 import { historySchema } from './tag';
 
-/** @see {@link https://docs.joinmastodon.org/entities/PreviewCard/#trends-link} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/PreviewCard/#trends-link}
+ */
 const trendsLinkSchema = v.pipe(
   v.any(),
   v.transform((link: any) => ({ ...link, id: link.url })),

packages/pl-api/lib/entities/web-push-subscription.ts

@@ -1,6 +1,9 @@
 import * as v from 'valibot';
 
-/** @see {@link https://docs.joinmastodon.org/entities/WebPushSubscription/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/WebPushSubscription/}
+ */
 const webPushSubscriptionSchema = v.object({
   id: v.pipe(v.unknown(), v.transform(String)),
   endpoint: v.string(),

packages/pl-api/lib/features.ts

@@ -142,7 +142,10 @@ const REBASED = 'soapbox';
  */
 const UNRELEASED = 'unreleased';
 
-/** Parse features for the given instance */
+/**
+ * Parse features for the given instance
+ * @category Utils
+ */
 const getFeatures = (instance: Instance) => {
   const v = parseVersion(instance.version || '');
   const federation = !!instance.pleroma.metadata.federation.enabled;

packages/pl-api/lib/params/accounts.ts

@@ -1,7 +1,13 @@
 import type { LanguageParam, OnlyEventsParam, OnlyMediaParam, PaginationParams, WithMutedParam, WithRelationshipsParam } from './common';
 
+/**
+ * @category Request params
+ */
 type GetAccountParams = WithMutedParam;
 
+/**
+ * @category Request params
+ */
 interface GetAccountStatusesParams extends PaginationParams, WithMutedParam, OnlyEventsParam, OnlyMediaParam, LanguageParam {
   /** Boolean. Filter out statuses in reply to a different account. */
   exclude_replies?: boolean;
@@ -11,9 +17,19 @@ interface GetAccountStatusesParams extends PaginationParams, WithMutedParam, Onl
   tagged?: string;
 }
 
+/**
+ * @category Request params
+ */
 type GetAccountFollowersParams = PaginationParams & WithRelationshipsParam;
+
+/**
+ * @category Request params
+ */
 type GetAccountFollowingParams = PaginationParams & WithRelationshipsParam;
 
+/**
+ * @category Request params
+ */
 interface FollowAccountParams {
   /** Boolean. Receive this account’s reblogs in home timeline? Defaults to true. */
   reblogs?: boolean;
@@ -26,11 +42,17 @@ interface FollowAccountParams {
   languages?: string[];
 }
 
+/**
+ * @category Request params
+ */
 interface GetRelationshipsParams {
   /** Boolean. Whether relationships should be returned for suspended users, defaults to false. */
   with_suspended?: boolean;
 }
 
+/**
+ * @category Request params
+ */
 interface SearchAccountParams {
   /** Integer. Maximum number of results. Defaults to 40 accounts. Max 80 accounts. */
   limit?: number;
@@ -42,6 +64,9 @@ interface SearchAccountParams {
   following?: boolean;
 }
 
+/**
+ * @category Request params
+ */
 interface ReportAccountParams {
   status_ids?: string[];
   comment?: string;
@@ -50,11 +75,24 @@ interface ReportAccountParams {
   rule_ids?: string[];
 }
 
+/**
+ * @category Request params
+ */
 type GetAccountEndorsementsParams = WithRelationshipsParam;
+
+/**
+ * @category Request params
+ */
 type GetAccountFavouritesParams = PaginationParams;
 
+/**
+ * @category Request params
+ */
 type GetScrobblesParams = PaginationParams;
 
+/**
+ * @category Request params
+ */
 interface CreateScrobbleParams {
   /** the title of the media playing */
   title: string;

packages/pl-api/lib/params/admin.ts

@@ -1,5 +1,8 @@
 import type { PaginationParams } from './common';
 
+/**
+ * @category Request params
+ */
 interface AdminGetAccountsParams extends PaginationParams {
   /** String. Filter for `local` or `remote` accounts. */
   origin?: 'local' | 'remote';
@@ -23,8 +26,14 @@ interface AdminGetAccountsParams extends PaginationParams {
   ip?: string;
 }
 
+/**
+ * @category Request params
+ */
 type AdminAccountAction = 'none' | 'sensitive' | 'disable' | 'silence' | 'suspend';
 
+/**
+ * @category Request params
+ */
 interface AdminPerformAccountActionParams {
   /** String. The ID of an associated report that caused this action to be taken. */
   report_id?: string;
@@ -36,8 +45,14 @@ interface AdminPerformAccountActionParams {
   send_email_notification?: boolean;
 }
 
+/**
+ * @category Request params
+ */
 type AdminGetDomainBlocksParams = PaginationParams;
 
+/**
+ * @category Request params
+ */
 interface AdminCreateDomainBlockParams {
   /** String. Whether to apply a `silence`, `suspend`, or `noop` to the domain. Defaults to `silence` */
   severity?: 'silence' | 'suspend' | 'noop';
@@ -53,8 +68,14 @@ interface AdminCreateDomainBlockParams {
   obfuscate?: boolean;
 }
 
+/**
+ * @category Request params
+ */
 type AdminUpdateDomainBlockParams = AdminCreateDomainBlockParams;
 
+/**
+ * @category Request params
+ */
 interface AdminGetReportsParams extends PaginationParams {
   /** Boolean. Filter for resolved reports? */
   resolved?: boolean;
@@ -64,6 +85,9 @@ interface AdminGetReportsParams extends PaginationParams {
   target_account_id?: string;
 }
 
+/**
+ * @category Request params
+ */
 interface AdminUpdateReportParams {
   /** String. Change the classification of the report to `spam`, `violation`, or `other`. */
   category?: 'spam' | 'violation' | 'other';
@@ -71,6 +95,9 @@ interface AdminUpdateReportParams {
   rule_ids?: string[];
 }
 
+/**
+ * @category Request params
+ */
 interface AdminGetStatusesParams {
   limit?: number;
   local_only?: boolean;
@@ -78,15 +105,27 @@ interface AdminGetStatusesParams {
   with_private?: boolean;
 }
 
+/**
+ * @category Request params
+ */
 interface AdminUpdateStatusParams {
   sensitive?: boolean;
   visibility?: 'public' | 'private' | 'unlisted';
 }
 
+/**
+ * @category Request params
+ */
 type AdminGetCanonicalEmailBlocks = PaginationParams;
 
+/**
+ * @category Request params
+ */
 type AdminDimensionKey = 'languages' | 'sources' | 'servers' | 'space_usage' | 'software_versions' | 'tag_servers' | 'tag_languages' | 'instance_accounts' | 'instance_languages';
 
+/**
+ * @category Request params
+ */
 interface AdminGetDimensionsParams {
   /** String (ISO 8601 Datetime). The start date for the time period. If a time is provided, it will be ignored. */
   start_at?: string;
@@ -112,12 +151,24 @@ interface AdminGetDimensionsParams {
   };
 }
 
+/**
+ * @category Request params
+ */
 type AdminGetDomainAllowsParams = PaginationParams;
 
+/**
+ * @category Request params
+ */
 type AdminGetEmailDomainBlocksParams = PaginationParams;
 
+/**
+ * @category Request params
+ */
 type AdminGetIpBlocksParams = PaginationParams;
 
+/**
+ * @category Request params
+ */
 interface AdminCreateIpBlockParams {
   /** String. The IP address and prefix to block. Defaults to 0.0.0.0/32 */
   ip?: string;
@@ -129,10 +180,19 @@ interface AdminCreateIpBlockParams {
   expires_in?: number;
 }
 
+/**
+ * @category Request params
+ */
 type AdminUpdateIpBlockParams = Partial<AdminCreateIpBlockParams>;
 
+/**
+ * @category Request params
+ */
 type AdminMeasureKey = 'active_users' | 'new_users' | 'interactions' | 'opened_reports' | 'resolved_reports' | 'tag_accounts' | 'tag_uses' | 'tag_servers' | 'instance_accounts' | 'instance_media_attachments' | 'instance_reports' | 'instance_statuses' | 'instance_follows' | 'instance_followers';
 
+/**
+ * @category Request params
+ */
 interface AdminGetMeasuresParams {
   tag_accounts?: {
     /** String. When `tag_accounts` is one of the requested keys, you must provide a tag ID to obtain the measure of how many accounts used that hashtag in at least one status within the given time period. */
@@ -172,11 +232,17 @@ interface AdminGetMeasuresParams {
   };
 }
 
+/**
+ * @category Request params
+ */
 interface AdminGetAnnouncementsParams {
   offset?: number;
   limit?: number;
 }
 
+/**
+ * @category Request params
+ */
 interface AdminCreateAnnouncementParams {
   /** announcement content */
   content: string;
@@ -188,8 +254,14 @@ interface AdminCreateAnnouncementParams {
   all_day?: boolean;
 }
 
+/**
+ * @category Request params
+ */
 type AdminUpdateAnnouncementParams = Partial<AdminCreateAnnouncementParams>;
 
+/**
+ * @category Request params
+ */
 interface AdminCreateDomainParams {
   /** domain name */
   domain: string;
@@ -197,6 +269,9 @@ interface AdminCreateDomainParams {
   public?: boolean;
 }
 
+/**
+ * @category Request params
+ */
 interface AdminGetModerationLogParams extends Pick<PaginationParams, 'limit'> {
   /** page number */
   page?: number;
@@ -210,14 +285,23 @@ interface AdminGetModerationLogParams extends Pick<PaginationParams, 'limit'> {
   search?: string;
 }
 
+/**
+ * @category Request params
+ */
 interface AdminCreateRuleParams {
   text: string;
   hint?: string;
   priority?: number;
 }
 
+/**
+ * @category Request params
+ */
 type AdminUpdateRuleParams = Partial<AdminCreateRuleParams>;
 
+/**
+ * @category Request params
+ */
 interface AdminGetGroupsParams {
 }
 

packages/pl-api/lib/params/apps.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Request params
+ */
 interface CreateApplicationParams {
   /** String. A name for your application */
   client_name: string;

packages/pl-api/lib/params/chats.ts

@@ -1,8 +1,18 @@
 import { PaginationParams, WithMutedParam } from './common';
 
+/**
+ * @category Request params
+ */
 type GetChatsParams = PaginationParams & WithMutedParam;
+
+/**
+ * @category Request params
+ */
 type GetChatMessagesParams = PaginationParams;
 
+/**
+ * @category Request params
+ */
 type CreateChatMessageParams = {
   content?: string;
   media_id: string;

packages/pl-api/lib/params/events.ts

@@ -1,5 +1,8 @@
 import { PaginationParams } from './common';
 
+/**
+ * @category Request params
+ */
 interface CreateEventParams {
   /** name of the event */
   name: string;
@@ -19,9 +22,24 @@ interface CreateEventParams {
   content_type?: string;
 }
 
+/**
+ * @category Request params
+ */
 type EditEventParams = Partial<Omit<CreateEventParams, 'join_mode'>>;
+
+/**
+ * @category Request params
+ */
 type GetJoinedEventsParams = PaginationParams;
+
+/**
+ * @category Request params
+ */
 type GetEventParticipationsParams = PaginationParams;
+
+/**
+ * @category Request params
+ */
 type GetEventParticipationRequestsParams = PaginationParams;
 
 export type {

packages/pl-api/lib/params/filtering.ts

@@ -1,5 +1,8 @@
 import type { PaginationParams, WithRelationshipsParam } from './common';
 
+/**
+ * @category Request params
+ */
 interface MuteAccountParams {
   /** Boolean. Mute notifications in addition to statuses? Defaults to true. */
   notifications?: boolean;
@@ -7,12 +10,29 @@ interface MuteAccountParams {
   duration?: number;
 }
 
+/**
+ * @category Request params
+ */
 type GetMutesParams = Omit<PaginationParams, 'min_id'> & WithRelationshipsParam;
+
+/**
+ * @category Request params
+ */
 type GetBlocksParams = PaginationParams & WithRelationshipsParam;
+
+/**
+ * @category Request params
+ */
 type GetDomainBlocksParams = PaginationParams;
 
+/**
+ * @category Request params
+ */
 type FilterContext = 'home' | 'notifications' | 'public' | 'thread' | 'account';
 
+/**
+ * @category Request params
+ */
 interface CreateFilterParams {
   title: string;
   context: Array<FilterContext>;
@@ -24,6 +44,9 @@ interface CreateFilterParams {
   }>;
 }
 
+/**
+ * @category Request params
+ */
 interface UpdateFilterParams {
   title?: string;
   context?: Array<FilterContext>;

packages/pl-api/lib/params/groups.ts

@@ -1,5 +1,8 @@
 import type { PaginationParams } from './common';
 
+/**
+ * @category Request params
+ */
 interface CreateGroupParams {
   display_name: string;
   note?: string;
@@ -7,6 +10,9 @@ interface CreateGroupParams {
   header?: File;
 }
 
+/**
+ * @category Request params
+ */
 interface UpdateGroupParams {
   display_name?: string;
   note?: string;
@@ -14,8 +20,19 @@ interface UpdateGroupParams {
   header?: File | '';
 }
 
+/**
+ * @category Request params
+ */
 type GetGroupMembershipsParams = Omit<PaginationParams, 'min_id'>;
+
+/**
+ * @category Request params
+ */
 type GetGroupMembershipRequestsParams = Omit<PaginationParams, 'min_id'>;
+
+/**
+ * @category Request params
+ */
 type GetGroupBlocksParams = Omit<PaginationParams, 'min_id'>;
 
 export type {

packages/pl-api/lib/params/instance.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Request params
+ */
 interface ProfileDirectoryParams {
   /** Number. Skip the first n results. */
   offset?: number;

packages/pl-api/lib/params/interaction-requests.ts

@@ -1,5 +1,8 @@
 import { PaginationParams } from './common';
 
+/**
+ * @category Request params
+ */
 interface GetInteractionRequestsParams extends PaginationParams {
   /** If set, then only interactions targeting the given status_id will be included in the results. */
   status_id?: string;

packages/pl-api/lib/params/lists.ts

@@ -1,5 +1,8 @@
 import type { PaginationParams } from './common';
 
+/**
+ * @category Request params
+ */
 interface CreateListParams {
   /** String. The title of the list to be created. */
   title: string;
@@ -9,7 +12,14 @@ interface CreateListParams {
   exclusive?: boolean;
 }
 
+/**
+ * @category Request params
+ */
 type UpdateListParams = CreateListParams;
+
+/**
+ * @category Request params
+ */
 type GetListAccountsParams = PaginationParams;
 
 export type {

packages/pl-api/lib/params/media.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Request params
+ */
 interface UploadMediaParams {
   /** Object. The file to be attached, encoded using multipart form data. The file must have a MIME type. */
   file: File;
@@ -12,6 +15,9 @@ interface UploadMediaParams {
   focus?: string;
 }
 
+/**
+ * @category Request params
+ */
 interface UpdateMediaParams {
   /** Object. The custom thumbnail of the media to be attached, encoded using multipart form data. */
   thumbnail?: File;

packages/pl-api/lib/params/my-account.ts

@@ -1,5 +1,8 @@
 import type { PaginationParams } from './common';
 
+/**
+ * @category Request params
+ */
 interface GetBookmarksParams extends PaginationParams {
   /**
    * Bookmark folder ID
@@ -8,16 +11,37 @@ interface GetBookmarksParams extends PaginationParams {
   folder_id?: string;
 }
 
+/**
+ * @category Request params
+ */
 type GetFavouritesParams = PaginationParams;
+
+/**
+ * @category Request params
+ */
 type GetFollowRequestsParams = Omit<PaginationParams, 'min_id'>;
+
+/**
+ * @category Request params
+ */
 type GetEndorsementsParams = Omit<PaginationParams, 'min_id'>;
+
+/**
+ * @category Request params
+ */
 type GetFollowedTagsParams = PaginationParams;
 
+/**
+ * @category Request params
+ */
 interface CreateBookmarkFolderParams {
   name: string;
   emoji?: string;
 }
 
+/**
+ * @category Request params
+ */
 type UpdateBookmarkFolderParams = Partial<CreateBookmarkFolderParams>;
 
 export type {

packages/pl-api/lib/params/notifications.ts

@@ -1,5 +1,8 @@
 import type { PaginationParams } from './common';
 
+/**
+ * @category Request params
+ */
 interface GetNotificationParams extends PaginationParams {
   /** Types to include in the result. */
   types?: string[];
@@ -14,6 +17,9 @@ interface GetNotificationParams extends PaginationParams {
   exclude_visibilities?: string[];
 }
 
+/**
+ * @category Request params
+ */
 interface GetUnreadNotificationCountParams {
   /** Maximum number of results to return. Defaults to 100 notifications. Max 1000 notifications. */
   limit?: number;
@@ -25,6 +31,9 @@ interface GetUnreadNotificationCountParams {
   account_id?: string;
 }
 
+/**
+ * @category Request params
+ */
 interface UpdateNotificationPolicyRequest {
   /** Whether to `accept`, `filter` or `drop` notifications from accounts the user is not following. */
   for_not_following?: boolean;
@@ -38,6 +47,9 @@ interface UpdateNotificationPolicyRequest {
   for_limited_accounts?: boolean;
 }
 
+/**
+ * @category Request params
+ */
 type GetNotificationRequestsParams = PaginationParams;
 
 export type {

packages/pl-api/lib/params/oauth.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Request params
+ */
 interface OauthAuthorizeParams {
   /** String. Should be set equal to `code`. */
   response_type: string;
@@ -13,6 +16,9 @@ interface OauthAuthorizeParams {
   lang?: string;
 }
 
+/**
+ * @category Request params
+ */
 interface GetTokenParams {
   /** String. Set equal to `authorization_code` if `code` is provided in order to gain user-level access. Otherwise, set equal to `client_credentials` to obtain app-level access only. */
   grant_type: string;
@@ -28,6 +34,9 @@ interface GetTokenParams {
   scope?: string;
 }
 
+/**
+ * @category Request params
+ */
 interface RevokeTokenParams {
   /** String. The client ID, obtained during app registration. */
   client_id: string;
@@ -37,6 +46,9 @@ interface RevokeTokenParams {
   token: string;
 }
 
+/**
+ * @category Request params
+ */
 interface MfaChallengeParams {
   client_id: string;
   client_secret: string;

packages/pl-api/lib/params/push-notifications.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Request params
+ */
 interface CreatePushNotificationsSubscriptionParams {
   subscription: {
     /** String. The endpoint URL that is called when a notification event occurs. */
@@ -16,6 +19,9 @@ interface CreatePushNotificationsSubscriptionParams {
   };
 }
 
+/**
+ * @category Request params
+ */
 interface UpdatePushNotificationsSubscriptionParams {
   data?: {
     alerts?: Record<string, boolean>;

packages/pl-api/lib/params/scheduled-statuses.ts

@@ -1,5 +1,8 @@
 import type { PaginationParams } from './common';
 
+/**
+ * @category Request params
+ */
 type GetScheduledStatusesParams = PaginationParams;
 
 export type {

packages/pl-api/lib/params/search.ts

@@ -1,5 +1,8 @@
 import type { PaginationParams, WithRelationshipsParam } from './common';
 
+/**
+ * @category Request params
+ */
 interface SearchParams extends Exclude<PaginationParams, 'since_id'>, WithRelationshipsParam {
   /** String. Specify whether to search for only `accounts`, `hashtags`, `statuses` */
   type?: 'accounts' | 'hashtags' | 'statuses' | 'groups';

packages/pl-api/lib/params/settings.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Request params
+ */
 interface CreateAccountParams {
   /** String. The desired username for the account */
   username: string;
@@ -30,6 +33,9 @@ interface CreateAccountParams {
   accepts_email_list?: boolean;
 }
 
+/**
+ * @category Request params
+ */
 interface UpdateCredentialsParams {
   /** String. The display name to use for the profile. */
   display_name?: string;
@@ -115,6 +121,9 @@ interface UpdateCredentialsParams {
   enable_rss?: boolean;
 }
 
+/**
+ * @category Request params
+ */
 interface UpdateNotificationSettingsParams {
   /**
    * blocks notifications from accounts you do not follow
@@ -127,6 +136,9 @@ interface UpdateNotificationSettingsParams {
   hide_notification_contents?: boolean;
 }
 
+/**
+ * @category Request params
+ */
 type UpdateInteractionPoliciesParams = Record<
   'public' | 'unlisted' | 'private' | 'direct',
   Record<

packages/pl-api/lib/params/statuses.ts

@@ -2,6 +2,9 @@ import { UpdateInteractionPoliciesParams } from './settings';
 
 import type { PaginationParams } from './common';
 
+/**
+ * @category Request params
+ */
 interface CreateStatusWithContent {
   /** The text content of the status. If `media_ids` is provided, this becomes optional. Attaching a `poll` is optional while `status` is provided. */
   status: string;
@@ -9,6 +12,9 @@ interface CreateStatusWithContent {
   media_ids?: string[];
 }
 
+/**
+ * @category Request params
+ */
 interface CreateStatusWithMedia {
   /** The text content of the status. If `media_ids` is provided, this becomes optional. Attaching a `poll` is optional while `status` is provided. */
   status?: string;
@@ -16,6 +22,9 @@ interface CreateStatusWithMedia {
   media_ids: string[];
 }
 
+/**
+ * @category Request params
+ */
 interface CreateStatusOptionalParams {
   poll?: {
     /** Array of String. Possible answers to the poll. If provided, `media_ids` cannot be used, and poll[expires_in] must be provided. */
@@ -90,30 +99,61 @@ interface CreateStatusOptionalParams {
   interaction_policy?: UpdateInteractionPoliciesParams['public'];
 }
 
+/**
+ * @category Request params
+ */
 type CreateStatusParams = (CreateStatusWithContent | CreateStatusWithMedia) & CreateStatusOptionalParams;
 
+/**
+ * @category Request params
+ */
 interface LanguageParam {
   /** Attach translated version of a post. Requires `features.autoTranslate`. */
   language?: string;
 }
 
+/**
+ * @category Request params
+ */
 type GetStatusParams = LanguageParam;
 
+/**
+ * @category Request params
+ */
 type GetStatusesParams = LanguageParam;
 
+/**
+ * @category Request params
+ */
 type GetStatusContextParams = LanguageParam;
 
+/**
+ * @category Request params
+ */
 type GetRebloggedByParams = Omit<PaginationParams, 'min_id'>
 
+/**
+ * @category Request params
+ */
 type GetFavouritedByParams = Omit<PaginationParams, 'min_id'>
 
+/**
+ * @category Request params
+ */
 interface EditStatusOptionalParams {
   sensitive?: boolean;
   spoiler_text?: string;
   language?: string;
 }
 
+/**
+ * @category Request params
+ */
 type EditStatusParams = (CreateStatusWithContent | CreateStatusWithMedia) & EditStatusOptionalParams;
+
+/**
+ * @category Request params
+ */
 type GetStatusQuotesParams = PaginationParams;
 
 export type {

packages/pl-api/lib/params/timelines.ts

@@ -1,5 +1,8 @@
 import type { LanguageParam, OnlyEventsParam, OnlyMediaParam, PaginationParams, WithMutedParam } from './common';
 
+/**
+ * @category Request params
+ */
 interface PublicTimelineParams extends PaginationParams, WithMutedParam, OnlyEventsParam, OnlyMediaParam, LanguageParam {
   /** Boolean. Show only local statuses? Defaults to false. */
   local?: boolean;
@@ -13,6 +16,9 @@ interface PublicTimelineParams extends PaginationParams, WithMutedParam, OnlyEve
   instance?: string;
 }
 
+/**
+ * @category Request params
+ */
 interface HashtagTimelineParams extends PaginationParams, WithMutedParam, OnlyEventsParam, OnlyMediaParam, LanguageParam {
   /** Array of String. Return statuses that contain any of these additional tags. */
   any?: string[];
@@ -26,10 +32,24 @@ interface HashtagTimelineParams extends PaginationParams, WithMutedParam, OnlyEv
   remote?: boolean;
 }
 
+/**
+ * @category Request params
+ */
 type HomeTimelineParams = PaginationParams & WithMutedParam & OnlyEventsParam & LanguageParam;
+
+/**
+ * @category Request params
+ */
 type LinkTimelineParams = PaginationParams & WithMutedParam & LanguageParam;
+
+/**
+ * @category Request params
+ */
 type ListTimelineParams = PaginationParams & WithMutedParam & OnlyEventsParam & LanguageParam;
 
+/**
+ * @category Request params
+ */
 interface GetConversationsParams extends PaginationParams, LanguageParam {
   /**
    * Only return conversations with the given recipients (a list of user ids).
@@ -38,6 +58,9 @@ interface GetConversationsParams extends PaginationParams, LanguageParam {
   recipients?: string[];
 }
 
+/**
+ * @category Request params
+ */
 interface SaveMarkersParams {
   home?: {
     /** String. ID of the last status read in the home timeline. */
@@ -49,7 +72,14 @@ interface SaveMarkersParams {
   };
 }
 
+/**
+ * @category Request params
+ */
 type GroupTimelineParams = PaginationParams & WithMutedParam & OnlyMediaParam & LanguageParam;
+
+/**
+ * @category Request params
+ */
 type BubbleTimelineParams = PaginationParams & WithMutedParam & OnlyEventsParam & OnlyMediaParam & LanguageParam;
 
 export type {

packages/pl-api/lib/params/trends.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Request params
+ */
 interface GetTrends {
   /** Integer. Maximum number of results to return. */
   limit?: number;
@@ -5,8 +8,19 @@ interface GetTrends {
   offset?: number;
 }
 
+/**
+ * @category Request params
+ */
 type GetTrendingTags = GetTrends;
+
+/**
+ * @category Request params
+ */
 type GetTrendingStatuses = GetTrends;
+
+/**
+ * @category Request params
+ */
 type GetTrendingLinks = GetTrends;
 
 export type {