From d2ff28e7c4ca748cbe5f61a2c016991ad58bfcb6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?nicole=20miko=C5=82ajczyk?= <git@mkljczk.pl>
Date: Thu, 12 Mar 2026 19:17:31 +0100
Subject: [PATCH] pl-api: add pleroma config description schema
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: nicole mikołajczyk <git@mkljczk.pl>
---
 packages/pl-api/lib/client/admin.ts           |  7 +++
 .../admin/pleroma-config-description.ts       | 54 +++++++++++++++++++
 packages/pl-api/lib/entities/index.ts         |  1 +
 packages/pl-api/lib/features.ts               |  8 +++
 4 files changed, 70 insertions(+)
 create mode 100644 packages/pl-api/lib/entities/admin/pleroma-config-description.ts

diff --git a/packages/pl-api/lib/client/admin.ts b/packages/pl-api/lib/client/admin.ts
index 0d93750bc..08d05e0b1 100644
--- a/packages/pl-api/lib/client/admin.ts
+++ b/packages/pl-api/lib/client/admin.ts
@@ -18,6 +18,7 @@ import {
   adminReportSchema,
   adminRuleSchema,
   adminTagSchema,
+  pleromaConfigDescriptionSchema,
   pleromaConfigSchema,
   statusSchema,
   statusSourceSchema,
@@ -1458,6 +1459,12 @@ const admin = (client: PlApiBaseClient) => {
     },
 
     config: {
+      getPleromaConfigDescriptions: async () => {
+        const response = await client.request('/api/v1/pleroma/admin/config/descriptions');
+
+        return v.parse(v.array(pleromaConfigDescriptionSchema), response.json);
+      },
+
       getPleromaConfig: async () => {
         const response = await client.request('/api/v1/pleroma/admin/config');
 
diff --git a/packages/pl-api/lib/entities/admin/pleroma-config-description.ts b/packages/pl-api/lib/entities/admin/pleroma-config-description.ts
new file mode 100644
index 000000000..b94ac863c
--- /dev/null
+++ b/packages/pl-api/lib/entities/admin/pleroma-config-description.ts
@@ -0,0 +1,54 @@
+import * as v from 'valibot';
+
+/**
+ * @category Admin schemas
+ */
+const pleromaConfigDescriptionChildSchema: v.GenericSchema<PleromaConfigDescriptionChild> =
+  v.looseObject({
+    key: v.optional(v.string()),
+    type: v.union([v.string(), v.array(v.string())]),
+    description: v.optional(v.string()),
+    label: v.optional(v.string()),
+    suggestions: v.optional(v.array(v.any())),
+    children: v.optional(v.lazy(() => v.array(pleromaConfigDescriptionChildSchema))),
+    group: v.optional(v.union([v.string(), v.array(v.string())])),
+  });
+
+/**
+ * @category Admin schemas
+ */
+const pleromaConfigDescriptionSchema = v.object({
+  group: v.optional(v.string()),
+  key: v.optional(v.string()),
+  type: v.union([v.string(), v.array(v.string())]),
+  description: v.optional(v.string()),
+  label: v.optional(v.string()),
+  children: v.array(pleromaConfigDescriptionChildSchema),
+  tab: v.optional(v.string()),
+  related_policy: v.optional(v.string()),
+});
+
+/**
+ * @category Admin entity types
+ */
+type PleromaConfigDescription = v.InferOutput<typeof pleromaConfigDescriptionSchema>;
+
+/**
+ * @category Admin entity types
+ */
+type PleromaConfigDescriptionChild = {
+  key?: string;
+  type: string | string[];
+  description?: string;
+  label?: string;
+  suggestions?: unknown[];
+  children?: PleromaConfigDescriptionChild[];
+  group?: string | string[];
+};
+
+export {
+  pleromaConfigDescriptionSchema,
+  pleromaConfigDescriptionChildSchema,
+  type PleromaConfigDescription,
+  type PleromaConfigDescriptionChild,
+};
diff --git a/packages/pl-api/lib/entities/index.ts b/packages/pl-api/lib/entities/index.ts
index e67f64979..20970277c 100644
--- a/packages/pl-api/lib/entities/index.ts
+++ b/packages/pl-api/lib/entities/index.ts
@@ -15,6 +15,7 @@ export * from './admin/ip-block';
 export * from './admin/measure';
 export * from './admin/moderation-log-entry';
 export * from './admin/pleroma-config';
+export * from './admin/pleroma-config-description';
 export * from './admin/relay';
 export * from './admin/report';
 export * from './admin/rule';
diff --git a/packages/pl-api/lib/features.ts b/packages/pl-api/lib/features.ts
index 21b54c3f6..a9fd76be7 100644
--- a/packages/pl-api/lib/features.ts
+++ b/packages/pl-api/lib/features.ts
@@ -1361,6 +1361,14 @@ const getFeatures = (instance: Instance) => {
      */
     pleromaAdminAnnouncements: any([v.software === AKKOMA, v.software === PLEROMA]),
 
+    /**
+     * @see GET /api/v1/pleroma/admin/config/descriptions
+     * @see GET /api/v1/pleroma/admin/config
+     * @see POST /api/v1/pleroma/admin/config
+     * @see {@link https://docs.pleroma.social/backend/development/API/admin_api/#get-apiv1pleromaadminconfig}
+     */
+    pleromaAdminConfig: any([v.software === AKKOMA, v.software === PLEROMA]),
+
     pleromaAdminModerationLog: any([v.software === AKKOMA, v.software === PLEROMA]),
 
     pleromaAdminRelays: any([v.software === AKKOMA, v.software === PLEROMA]),