pl-api: works on docs

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

packages/pl-api/README.md

@@ -4,6 +4,25 @@ A JavaScript library for interacting with Mastodon API-compatible servers, focus
 
 `pl-api` attempts to abstract out the implementation details when supporting different backends, implementing the same features in different ways. It uses [Valibot](https://valibot.dev/) to ensure type safety and normalize API responses.
 
+Example:
+```ts
+import { PlApiClient, type CreateApplicationParams } from 'pl-api';
+
+const { ACCESS_TOKEN } = process.env;
+
+const client = new PlApiClient('https://mastodon.example/', ACCESS_TOKEN, {
+  fetchInstance: true,
+  onInstanceFetchSuccess: () => console.log('Instance fetched'),
+});
+
+await client.statuses.createStatus({
+  status: 'Hello, world!',
+  language: 'en',
+});
+```
+
+Some sort of documentation is available on https://pl.mkljczk.pl/pl-api-docs
+
 > This project should be considered unstable before the 1.0.0 release. I will not provide any changelog or information on breaking changes until then.
 
 ## Projects using `pl-api`

packages/pl-api/lib/client.ts

@@ -230,6 +230,9 @@ import type {
 } from './params/admin';
 import type { PaginatedResponse } from './responses';
 
+/**
+ * @category Clients
+ */
 class PlApiClient {
 
   baseURL: string;

packages/pl-api/lib/directory-client.ts

@@ -15,6 +15,9 @@ interface Params {
   registrations?: 'instant' | 'manual';
 }
 
+/**
+ * @category Clients
+ */
 class PlApiDirectoryClient {
 
   accessToken = undefined;

packages/pl-api/lib/entities/account-warning.ts

@@ -9,7 +9,10 @@ const appealSchema = v.object({
   state: v.picklist(['approved', 'rejected', 'pending']),
 });
 
-/** @see {@link https://docs.joinmastodon.org/entities/AccountWarning/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/AccountWarning/}
+*/
 const accountWarningSchema = v.object({
   id: v.string(),
   action: v.picklist(['none', 'disable', 'mark_statuses_as_sensitive', 'delete_statuses', 'sensitive', 'silence', 'suspend']),

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

@@ -166,6 +166,9 @@ type WithMoved = {
 
 type Account = v.InferOutput<typeof accountWithMovedAccountSchema> & WithMoved;
 
+/**
+ * @category Schemas
+ */
 const accountSchema: v.BaseSchema<any, Account, v.BaseIssue<unknown>> = untypedAccountSchema as any;
 
 const untypedCredentialAccountSchema = v.pipe(v.any(), preprocessAccount, v.object({
@@ -199,6 +202,9 @@ const untypedCredentialAccountSchema = v.pipe(v.any(), preprocessAccount, v.obje
 
 type CredentialAccount = v.InferOutput<typeof untypedCredentialAccountSchema> & WithMoved;
 
+/**
+ * @category Schemas
+ */
 const credentialAccountSchema: v.BaseSchema<any, CredentialAccount, v.BaseIssue<unknown>> = untypedCredentialAccountSchema as any;
 
 const untypedMutedAccountSchema = v.pipe(v.any(), preprocessAccount, v.object({
@@ -208,6 +214,9 @@ const untypedMutedAccountSchema = v.pipe(v.any(), preprocessAccount, v.object({
 
 type MutedAccount = v.InferOutput<typeof untypedMutedAccountSchema> & WithMoved;
 
+/**
+ * @category Schemas
+ */
 const mutedAccountSchema: v.BaseSchema<any, MutedAccount, v.BaseIssue<unknown>> = untypedMutedAccountSchema as any;
 
 export {

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

@@ -1,6 +1,9 @@
 import * as v from 'valibot';
 
-/** @see {@link https://docs.joinmastodon.org/entities/announcement/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/announcement/}
+ */
 const announcementReactionSchema = v.object({
   name: v.fallback(v.string(), ''),
   count: v.fallback(v.pipe(v.number(), v.integer(), v.minValue(0)), 0),

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

@@ -6,7 +6,10 @@ import { mentionSchema } from './mention';
 import { tagSchema } from './tag';
 import { datetimeSchema, filteredArray } from './utils';
 
-/** @see {@link https://docs.joinmastodon.org/entities/announcement/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/announcement/}
+ */
 const announcementSchema = v.object({
   id: v.string(),
   content: v.fallback(v.string(), ''),

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

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

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

@@ -2,7 +2,10 @@ import * as v from 'valibot';
 
 import { datetimeSchema, mimeSchema } from './utils';
 
-/** @see {@link https://docs.pleroma.social/backend/development/API/pleroma_api/#post-apiv1pleromabackups} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.pleroma.social/backend/development/API/pleroma_api/#post-apiv1pleromabackups}
+ */
 const backupSchema = v.object({
   id: v.pipe(v.unknown(), v.transform(String)),
   contentType: mimeSchema,

packages/pl-api/lib/entities/bookmark-folder.ts

@@ -1,5 +1,8 @@
 import * as v from 'valibot';
 
+/**
+ * @category Schemas
+ */
 const bookmarkFolderSchema = v.object({
   id: v.pipe(v.unknown(), v.transform(String)),
   name: v.fallback(v.string(), ''),

packages/pl-api/lib/entities/chat-message.ts

@@ -5,7 +5,10 @@ import { mediaAttachmentSchema } from './media-attachment';
 import { previewCardSchema } from './preview-card';
 import { datetimeSchema, filteredArray } from './utils';
 
-/** @see {@link https://docs.pleroma.social/backend/development/API/chats/#getting-the-messages-for-a-chat} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.pleroma.social/backend/development/API/chats/#getting-the-messages-for-a-chat}
+ */
 const chatMessageSchema = v.object({
   id: v.string(),
   content: v.fallback(v.string(), ''),

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

@@ -4,7 +4,10 @@ import { accountSchema } from './account';
 import { chatMessageSchema } from './chat-message';
 import { datetimeSchema } from './utils';
 
-/** @see {@link https://docs.pleroma.social/backend/development/API/chats/#getting-a-list-of-chats} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.pleroma.social/backend/development/API/chats/#getting-a-list-of-chats}
+ */
 const chatSchema = v.object({
   id: v.string(),
   account: accountSchema,

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

@@ -2,7 +2,10 @@ import * as v from 'valibot';
 
 import { statusSchema } from './status';
 
-/** @see {@link https://docs.joinmastodon.org/entities/Context/} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/Context/}
+ */
 const contextSchema = v.object({
   ancestors: v.array(statusSchema),
   descendants: v.array(statusSchema),

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

@@ -4,7 +4,10 @@ import { accountSchema } from './account';
 import { statusSchema } from './status';
 import { filteredArray } from './utils';
 
-/** @see {@link https://docs.joinmastodon.org/entities/Conversation} */
+/**
+ * @category Schemas
+ * @see {@link https://docs.joinmastodon.org/entities/Conversation}
+ */
 const conversationSchema = v.object({
   id: v.string(),
   unread: v.fallback(v.boolean(), false),

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

@@ -2,6 +2,8 @@ import * as v from 'valibot';
 
 /**
  * Represents a custom emoji.
+ *
+ * @category Schemas
  * @see {@link https://docs.joinmastodon.org/entities/CustomEmoji/}
  */
 const customEmojiSchema = v.object({

packages/pl-api/lib/entities/domain-block.ts

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

packages/pl-api/lib/features.ts

@@ -9,101 +9,137 @@ const any = (arr: Array<any>): boolean => arr.some(Boolean);
 
 /**
  * Ditto, a Nostr server with Mastodon API.
+ *
+ * @category Software
  * @see {@link https://gitlab.com/soapbox-pub/ditto}
  */
 const DITTO = 'Ditto';
 
 /**
  * Firefish, a fork of Misskey. Formerly known as Calckey.
+ *
+ * @category Software
  * @see {@link https://joinfirefish.org/}
  */
 const FIREFISH = 'Firefish';
 
 /**
  * Friendica, decentralized social platform implementing multiple federation protocols.
+ *
+ * @category Software
  * @see {@link https://friendi.ca/}
  */
 const FRIENDICA = 'Friendica';
 
 /**
  * GoToSocial, an ActivityPub server written in Golang.
+ *
+ * @category Software
  * @see {@link https://gotosocial.org/}
  */
 const GOTOSOCIAL = 'GoToSocial';
 
 /**
  * Iceshrimp, yet another Misskey fork.
+ *
+ * @category Software
  * @see {@link https://iceshrimp.dev/}
  */
 const ICESHRIMP = 'Iceshrimp';
 
 /**
  * Mastodon, the software upon which this is all based.
+ *
+ * @category Software
  * @see {@link https://joinmastodon.org/}
  */
 const MASTODON = 'Mastodon';
 
 /**
  * Mitra, a Rust backend with cryptocurrency integrations.
+ *
+ * @category Software
  * @see {@link https://codeberg.org/silverpill/mitra}
  */
 const MITRA = 'Mitra';
 
 /**
  * Pixelfed, a federated image sharing platform.
+ *
+ * @category Software
  * @see {@link https://pixelfed.org/}
  */
 const PIXELFED = 'Pixelfed';
 
 /**
  * Pleroma, a feature-rich alternative written in Elixir.
+ *
+ * @category Software
  * @see {@link https://pleroma.social/}
  */
 const PLEROMA = 'Pleroma';
 
 /**
  * Takahē, backend with support for serving multiple domains.
+ *
+ * @category Software
  * @see {@link https://jointakahe.org/}
  */
 const TAKAHE = 'Takahe';
 
 /**
  * Toki, a C# Fediverse server.
+ *
+ * @category Software
  * @see {@link https://github.com/purifetchi/Toki}
  */
 const TOKI = 'Toki';
 
 /**
  * Akkoma, a Pleroma fork.
+ *
+ * @category Software
  * @see {@link https://akkoma.dev/AkkomaGang/akkoma}
  */
 const AKKOMA = 'akkoma';
 
 /**
  * glitch-soc, fork of Mastodon with a number of experimental features.
+ *
+ * @category Software
  * @see {@link https://glitch-soc.github.io/docs/}
  */
 const GLITCH = 'glitch';
 
 /**
  * glitch-soc, fork of Mastodon that provides local posting and a wider range of content types.
+ *
+ * @category Software
  * @see {@link https://github.com/hometown-fork/hometown}
  */
 const HOMETOWN = 'hometown';
 
 /**
  * Pl, fork of Pleroma developed by pl-api author.
+ *
+ * @category Software
  * @see {@link https://github.com/mkljczk/pl}
  */
 const PL = 'pl';
 
 /**
  * Rebased, fork of Pleroma developed by Soapbox author.
+ *
+ * @category Software
  * @see {@link https://gitlab.com/soapbox-pub/rebased}
  */
 const REBASED = 'soapbox';
 
-/** Backend name reserved only for tests. */
+/**
+ * Backend name reserved only for tests.
+ *
+ * @category Software
+ */
 const UNRELEASED = 'unreleased';
 
 /** Parse features for the given instance */

packages/pl-api/typedoc.config.mjs

@@ -4,6 +4,9 @@ const config = {
   entryPoints: ['./lib/main.ts'],
   plugin: ['typedoc-material-theme', 'typedoc-plugin-valibot'],
   themeColor: '#d80482',
+  navigation: {
+    includeCategories: true,
+  },
 };
 
 export default config;