fix(api): Document the API for getting lists of a bookmark. fixes #2030

8 files changed, 268 insertions, 108 deletions

diff --git a/packages/open-api/karakeep-openapi-spec.json b/packages/open-api/karakeep-openapi-spec.json
index b525d39f..9132a4d9 100644
--- a/packages/open-api/karakeep-openapi-spec.json
+++ b/packages/open-api/karakeep-openapi-spec.json
@@ -349,6 +349,50 @@
       "Cursor": {
         "type": "string"
       },
+      "List": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string",
+            "nullable": true
+          },
+          "icon": {
+            "type": "string"
+          },
+          "parentId": {
+            "type": "string",
+            "nullable": true
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "manual",
+              "smart"
+            ],
+            "default": "manual"
+          },
+          "query": {
+            "type": "string",
+            "nullable": true
+          },
+          "public": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "id",
+          "name",
+          "icon",
+          "parentId",
+          "public"
+        ]
+      },
       "Highlight": {
         "type": "object",
         "properties": {
@@ -400,50 +444,6 @@
           "createdAt"
         ]
       },
-      "List": {
-        "type": "object",
-        "properties": {
-          "id": {
-            "type": "string"
-          },
-          "name": {
-            "type": "string"
-          },
-          "description": {
-            "type": "string",
-            "nullable": true
-          },
-          "icon": {
-            "type": "string"
-          },
-          "parentId": {
-            "type": "string",
-            "nullable": true
-          },
-          "type": {
-            "type": "string",
-            "enum": [
-              "manual",
-              "smart"
-            ],
-            "default": "manual"
-          },
-          "query": {
-            "type": "string",
-            "nullable": true
-          },
-          "public": {
-            "type": "boolean"
-          }
-        },
-        "required": [
-          "id",
-          "name",
-          "icon",
-          "parentId",
-          "public"
-        ]
-      },
       "Tag": {
         "type": "object",
         "properties": {
@@ -1472,6 +1472,70 @@
         }
       }
     },
+    "/bookmarks/{bookmarkId}/lists": {
+      "get": {
+        "description": "Get lists of a bookmark",
+        "summary": "Get lists of a bookmark",
+        "tags": [
+          "Bookmarks"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/BookmarkId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The list of highlights",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "lists": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/List"
+                      }
+                    }
+                  },
+                  "required": [
+                    "lists"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Bookmark not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string"
+                    },
+                    "message": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/bookmarks/{bookmarkId}/highlights": {
       "get": {
         "description": "Get highlights of a bookmark",
diff --git a/packages/open-api/lib/bookmarks.ts b/packages/open-api/lib/bookmarks.ts
index 57b50a9b..b2159570 100644
--- a/packages/open-api/lib/bookmarks.ts
+++ b/packages/open-api/lib/bookmarks.ts
@@ -16,7 +16,6 @@ import {
 import { AssetIdSchema } from "./assets";
 import { BearerAuth } from "./common";
 import { ErrorSchema } from "./errors";
-import { HighlightSchema } from "./highlights";
 import {
   BookmarkSchema,
   IncludeContentSearchParamSchema,
@@ -24,6 +23,7 @@ import {
   PaginationSchema,
 } from "./pagination";
 import { TagIdSchema } from "./tags";
+import { HighlightSchema, ListSchema } from "./types";
 
 export const registry = new OpenAPIRegistry();
 extendZodWithOpenApi(z);
@@ -339,6 +339,36 @@ registry.registerPath({
 
 registry.registerPath({
   method: "get",
+  path: "/bookmarks/{bookmarkId}/lists",
+  description: "Get lists of a bookmark",
+  summary: "Get lists of a bookmark",
+  tags: ["Bookmarks"],
+  security: [{ [BearerAuth.name]: [] }],
+  request: {
+    params: z.object({ bookmarkId: BookmarkIdSchema }),
+  },
+  responses: {
+    200: {
+      description: "The list of highlights",
+      content: {
+        "application/json": {
+          schema: z.object({ lists: z.array(ListSchema) }),
+        },
+      },
+    },
+    404: {
+      description: "Bookmark not found",
+      content: {
+        "application/json": {
+          schema: ErrorSchema,
+        },
+      },
+    },
+  },
+});
+
+registry.registerPath({
+  method: "get",
   path: "/bookmarks/{bookmarkId}/highlights",
   description: "Get highlights of a bookmark",
   summary: "Get highlights of a bookmark",
diff --git a/packages/open-api/lib/highlights.ts b/packages/open-api/lib/highlights.ts
index 6eb1970e..c642c9cb 100644
--- a/packages/open-api/lib/highlights.ts
+++ b/packages/open-api/lib/highlights.ts
@@ -5,7 +5,6 @@ import {
 import { z } from "zod";
 
 import {
-  zHighlightSchema,
   zNewHighlightSchema,
   zUpdateHighlightSchema,
 } from "@karakeep/shared/types/highlights";
@@ -13,19 +12,11 @@ import {
 import { BearerAuth } from "./common";
 import { ErrorSchema } from "./errors";
 import { PaginationSchema } from "./pagination";
+import { HighlightSchema, PaginatedHighlightsSchema } from "./types";
 
 export const registry = new OpenAPIRegistry();
 extendZodWithOpenApi(z);
 
-export const HighlightSchema = zHighlightSchema.openapi("Highlight");
-
-export const PaginatedHighlightsSchema = z
-  .object({
-    highlights: z.array(HighlightSchema),
-    nextCursor: z.string().nullable(),
-  })
-  .openapi("PaginatedHighlights");
-
 export const HighlightIdSchema = registry.registerParameter(
   "HighlightId",
   z.string().openapi({
diff --git a/packages/open-api/lib/lists.ts b/packages/open-api/lib/lists.ts
index 992b96c4..de67df2f 100644
--- a/packages/open-api/lib/lists.ts
+++ b/packages/open-api/lib/lists.ts
@@ -6,7 +6,6 @@ import { z } from "zod";
 
 import { zSortOrder } from "@karakeep/shared/types/bookmarks";
 import {
-  zBookmarkListSchema,
   zEditBookmarkListSchema,
   zNewBookmarkListSchema,
 } from "@karakeep/shared/types/lists";
@@ -19,6 +18,7 @@ import {
   PaginatedBookmarksSchema,
   PaginationSchema,
 } from "./pagination";
+import { ListSchema } from "./types";
 
 export const registry = new OpenAPIRegistry();
 extendZodWithOpenApi(z);
@@ -34,8 +34,6 @@ export const ListIdSchema = registry.registerParameter(
   }),
 );
 
-export const ListSchema = zBookmarkListSchema.openapi("List");
-
 registry.registerPath({
   method: "get",
   path: "/lists",
diff --git a/packages/open-api/lib/pagination.ts b/packages/open-api/lib/pagination.ts
index 382f00ef..40d440f0 100644
--- a/packages/open-api/lib/pagination.ts
+++ b/packages/open-api/lib/pagination.ts
@@ -1,33 +1,7 @@
-import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
-import { z } from "zod";
-
-import { zBookmarkSchema } from "@karakeep/shared/types/bookmarks";
-
-extendZodWithOpenApi(z);
-
-export const BookmarkSchema = zBookmarkSchema.openapi("Bookmark");
-
-export const PaginatedBookmarksSchema = z
-  .object({
-    bookmarks: z.array(BookmarkSchema),
-    nextCursor: z.string().nullable(),
-  })
-  .openapi("PaginatedBookmarks");
-
-export const CursorSchema = z.string().openapi("Cursor");
-
-export const PaginationSchema = z
-  .object({
-    limit: z.number().optional(),
-    cursor: CursorSchema.optional(),
-  })
-  .openapi("Pagination");
-
-export const IncludeContentSearchParamSchema = z.object({
-  includeContent: z
-    .boolean()
-    .default(true)
-    .describe(
-      "If set to true, bookmark's content will be included in the response. Note, this content can be large for some bookmarks.",
-    ),
-});
+export {
+  BookmarkSchema,
+  CursorSchema,
+  IncludeContentSearchParamSchema,
+  PaginatedBookmarksSchema,
+  PaginationSchema,
+} from "./types";
diff --git a/packages/open-api/lib/tags.ts b/packages/open-api/lib/tags.ts
index 84af39b1..18c14483 100644
--- a/packages/open-api/lib/tags.ts
+++ b/packages/open-api/lib/tags.ts
@@ -7,7 +7,6 @@ import { z } from "zod";
 import { zSortOrder } from "@karakeep/shared/types/bookmarks";
 import {
   zCreateTagRequestSchema,
-  zGetTagResponseSchema,
   zTagBasicSchema,
   zTagListQueryParamsSchema,
   zUpdateTagRequestSchema,
@@ -20,12 +19,11 @@ import {
   PaginatedBookmarksSchema,
   PaginationSchema,
 } from "./pagination";
+import { TagSchema } from "./types";
 
 export const registry = new OpenAPIRegistry();
 extendZodWithOpenApi(z);
 
-export const TagSchema = zGetTagResponseSchema.openapi("Tag");
-
 export const TagIdSchema = registry.registerParameter(
   "TagId",
   z.string().openapi({
diff --git a/packages/open-api/lib/types.ts b/packages/open-api/lib/types.ts
new file mode 100644
index 00000000..3aae48fc
--- /dev/null
+++ b/packages/open-api/lib/types.ts
@@ -0,0 +1,49 @@
+import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
+import { z } from "zod";
+
+import { zBookmarkSchema } from "@karakeep/shared/types/bookmarks";
+import { zHighlightSchema } from "@karakeep/shared/types/highlights";
+import { zBookmarkListSchema } from "@karakeep/shared/types/lists";
+import { zGetTagResponseSchema } from "@karakeep/shared/types/tags";
+
+extendZodWithOpenApi(z);
+
+export const ListSchema = zBookmarkListSchema.openapi("List");
+
+export const BookmarkSchema = zBookmarkSchema.openapi("Bookmark");
+
+export const PaginatedBookmarksSchema = z
+  .object({
+    bookmarks: z.array(BookmarkSchema),
+    nextCursor: z.string().nullable(),
+  })
+  .openapi("PaginatedBookmarks");
+
+export const CursorSchema = z.string().openapi("Cursor");
+
+export const PaginationSchema = z
+  .object({
+    limit: z.number().optional(),
+    cursor: CursorSchema.optional(),
+  })
+  .openapi("Pagination");
+
+export const IncludeContentSearchParamSchema = z.object({
+  includeContent: z
+    .boolean()
+    .default(true)
+    .describe(
+      "If set to true, bookmark's content will be included in the response. Note, this content can be large for some bookmarks.",
+    ),
+});
+
+export const HighlightSchema = zHighlightSchema.openapi("Highlight");
+
+export const PaginatedHighlightsSchema = z
+  .object({
+    highlights: z.array(HighlightSchema),
+    nextCursor: z.string().nullable(),
+  })
+  .openapi("PaginatedHighlights");
+
+export const TagSchema = zGetTagResponseSchema.openapi("Tag");
diff --git a/packages/sdk/src/karakeep-api.d.ts b/packages/sdk/src/karakeep-api.d.ts
index 1ac35e04..d376eb1b 100644
--- a/packages/sdk/src/karakeep-api.d.ts
+++ b/packages/sdk/src/karakeep-api.d.ts
@@ -67,6 +67,7 @@ export interface paths {
             createdAt?: string | null;
             /** @enum {string} */
             crawlPriority?: "low" | "normal";
+            importSessionId?: string;
           } & (
             | {
                 /** @enum {string} */
@@ -511,6 +512,61 @@ export interface paths {
     patch?: never;
     trace?: never;
   };
+  "/bookmarks/{bookmarkId}/lists": {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    /**
+     * Get lists of a bookmark
+     * @description Get lists of a bookmark
+     */
+    get: {
+      parameters: {
+        query?: never;
+        header?: never;
+        path: {
+          bookmarkId: components["parameters"]["BookmarkId"];
+        };
+        cookie?: never;
+      };
+      requestBody?: never;
+      responses: {
+        /** @description The list of highlights */
+        200: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content: {
+            "application/json": {
+              lists: components["schemas"]["List"][];
+            };
+          };
+        };
+        /** @description Bookmark not found */
+        404: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content: {
+            "application/json": {
+              code: string;
+              message: string;
+            };
+          };
+        };
+      };
+    };
+    put?: never;
+    post?: never;
+    delete?: never;
+    options?: never;
+    head?: never;
+    patch?: never;
+    trace?: never;
+  };
   "/bookmarks/{bookmarkId}/highlights": {
     parameters: {
       query?: never;
@@ -2048,6 +2104,20 @@ export interface components {
       nextCursor: string | null;
     };
     Cursor: string;
+    List: {
+      id: string;
+      name: string;
+      description?: string | null;
+      icon: string;
+      parentId: string | null;
+      /**
+       * @default manual
+       * @enum {string}
+       */
+      type: "manual" | "smart";
+      query?: string | null;
+      public: boolean;
+    };
     Highlight: {
       bookmarkId: string;
       startOffset: number;
@@ -2063,20 +2133,6 @@ export interface components {
       userId: string;
       createdAt: string;
     };
-    List: {
-      id: string;
-      name: string;
-      description?: string | null;
-      icon: string;
-      parentId: string | null;
-      /**
-       * @default manual
-       * @enum {string}
-       */
-      type: "manual" | "smart";
-      query?: string | null;
-      public: boolean;
-    };
     Tag: {
       id: string;
       name: string;