feat(api): enable ?sortOrder= for relevant resources (#1398)

* feat(api): enable `?sortOrder=` for relevant resources

* fix tests

6 files changed, 89 insertions, 11 deletions

diff --git a/packages/open-api/karakeep-openapi-spec.json b/packages/open-api/karakeep-openapi-spec.json
index 3bdaed54..dbc2e5d0 100644
--- a/packages/open-api/karakeep-openapi-spec.json
+++ b/packages/open-api/karakeep-openapi-spec.json
@@ -551,6 +551,19 @@
           },
           {
             "schema": {
+              "type": "string",
+              "enum": [
+                "asc",
+                "desc"
+              ],
+              "default": "desc"
+            },
+            "required": false,
+            "name": "sortOrder",
+            "in": "query"
+          },
+          {
+            "schema": {
               "type": "number"
             },
             "required": false,
@@ -776,6 +789,20 @@
           },
           {
             "schema": {
+              "type": "string",
+              "enum": [
+                "asc",
+                "desc",
+                "relevance"
+              ],
+              "default": "relevance"
+            },
+            "required": false,
+            "name": "sortOrder",
+            "in": "query"
+          },
+          {
+            "schema": {
               "type": "number"
             },
             "required": false,
@@ -1969,8 +1996,8 @@
     },
     "/lists/{listId}/bookmarks": {
       "get": {
-        "description": "Get the bookmarks in a list",
-        "summary": "Get a bookmarks in a list",
+        "description": "Get bookmarks in the list",
+        "summary": "Get bookmarks in the list",
         "tags": [
           "Lists"
         ],
@@ -1985,6 +2012,19 @@
           },
           {
             "schema": {
+              "type": "string",
+              "enum": [
+                "asc",
+                "desc"
+              ],
+              "default": "desc"
+            },
+            "required": false,
+            "name": "sortOrder",
+            "in": "query"
+          },
+          {
+            "schema": {
               "type": "number"
             },
             "required": false,
@@ -2367,8 +2407,8 @@
     },
     "/tags/{tagId}/bookmarks": {
       "get": {
-        "description": "Get the bookmarks with the tag",
-        "summary": "Get a bookmarks with the tag",
+        "description": "Get bookmarks with the tag",
+        "summary": "Get bookmarks with the tag",
         "tags": [
           "Tags"
         ],
@@ -2383,6 +2423,19 @@
           },
           {
             "schema": {
+              "type": "string",
+              "enum": [
+                "asc",
+                "desc"
+              ],
+              "default": "desc"
+            },
+            "required": false,
+            "name": "sortOrder",
+            "in": "query"
+          },
+          {
+            "schema": {
               "type": "number"
             },
             "required": false,
diff --git a/packages/open-api/lib/bookmarks.ts b/packages/open-api/lib/bookmarks.ts
index e344d656..8fb0eb8c 100644
--- a/packages/open-api/lib/bookmarks.ts
+++ b/packages/open-api/lib/bookmarks.ts
@@ -9,6 +9,7 @@ import {
   zBareBookmarkSchema,
   zManipulatedTagSchema,
   zNewBookmarkRequestSchema,
+  zSortOrder,
   zUpdateBookmarksRequestSchema,
 } from "@karakeep/shared/types/bookmarks";
 
@@ -60,6 +61,10 @@ registry.registerPath({
       .object({
         archived: z.boolean().optional(),
         favourited: z.boolean().optional(),
+        sortOrder: zSortOrder
+          .exclude(["relevance"])
+          .optional()
+          .default(zSortOrder.Enum.desc),
       })
       .merge(PaginationSchema)
       .merge(IncludeContentSearchParamSchema),
@@ -87,6 +92,7 @@ registry.registerPath({
     query: z
       .object({
         q: z.string(),
+        sortOrder: zSortOrder.optional().default(zSortOrder.Enum.relevance),
       })
       .merge(PaginationSchema)
       .merge(IncludeContentSearchParamSchema),
diff --git a/packages/open-api/lib/lists.ts b/packages/open-api/lib/lists.ts
index ab07e425..992b96c4 100644
--- a/packages/open-api/lib/lists.ts
+++ b/packages/open-api/lib/lists.ts
@@ -4,6 +4,7 @@ import {
 } from "@asteasolutions/zod-to-openapi";
 import { z } from "zod";
 
+import { zSortOrder } from "@karakeep/shared/types/bookmarks";
 import {
   zBookmarkListSchema,
   zEditBookmarkListSchema,
@@ -190,13 +191,21 @@ registry.registerPath({
 registry.registerPath({
   method: "get",
   path: "/lists/{listId}/bookmarks",
-  description: "Get the bookmarks in a list",
-  summary: "Get a bookmarks in a list",
+  description: "Get bookmarks in the list",
+  summary: "Get bookmarks in the list",
   tags: ["Lists"],
   security: [{ [BearerAuth.name]: [] }],
   request: {
     params: z.object({ listId: ListIdSchema }),
-    query: PaginationSchema.merge(IncludeContentSearchParamSchema),
+    query: z
+      .object({
+        sortOrder: zSortOrder
+          .exclude(["relevance"])
+          .optional()
+          .default(zSortOrder.Enum.desc),
+      })
+      .merge(PaginationSchema)
+      .merge(IncludeContentSearchParamSchema),
   },
   responses: {
     200: {
diff --git a/packages/open-api/lib/tags.ts b/packages/open-api/lib/tags.ts
index c51e3b84..b8136741 100644
--- a/packages/open-api/lib/tags.ts
+++ b/packages/open-api/lib/tags.ts
@@ -4,6 +4,7 @@ import {
 } from "@asteasolutions/zod-to-openapi";
 import { z } from "zod";
 
+import { zSortOrder } from "@karakeep/shared/types/bookmarks";
 import {
   zGetTagResponseSchema,
   zUpdateTagRequestSchema,
@@ -152,13 +153,21 @@ registry.registerPath({
 registry.registerPath({
   method: "get",
   path: "/tags/{tagId}/bookmarks",
-  description: "Get the bookmarks with the tag",
-  summary: "Get a bookmarks with the tag",
+  description: "Get bookmarks with the tag",
+  summary: "Get bookmarks with the tag",
   tags: ["Tags"],
   security: [{ [BearerAuth.name]: [] }],
   request: {
     params: z.object({ tagId: TagIdSchema }),
-    query: PaginationSchema.merge(IncludeContentSearchParamSchema),
+    query: z
+      .object({
+        sortOrder: zSortOrder
+          .exclude(["relevance"])
+          .optional()
+          .default(zSortOrder.Enum.desc),
+      })
+      .merge(PaginationSchema)
+      .merge(IncludeContentSearchParamSchema),
   },
   responses: {
     200: {
diff --git a/packages/open-api/package.json b/packages/open-api/package.json
index dfbb0bb6..900af481 100644
--- a/packages/open-api/package.json
+++ b/packages/open-api/package.json
@@ -19,6 +19,7 @@
     "typecheck": "tsc --noEmit",
     "generate": "tsx index.ts",
     "format": "prettier . --ignore-path ../../.prettierignore",
+    "format:fix": "prettier . --write --ignore-path ../../.prettierignore",
     "lint": "eslint ."
   },
   "main": "index.ts",
diff --git a/packages/open-api/tsconfig.json b/packages/open-api/tsconfig.json
index d97c8ef4..a795b96a 100644
--- a/packages/open-api/tsconfig.json
+++ b/packages/open-api/tsconfig.json
@@ -5,5 +5,5 @@
   "exclude": ["node_modules"],
   "compilerOptions": {
     "tsBuildInfoFile": "node_modules/.cache/tsbuildinfo.json"
-  },
+  }
 }