feat: Add REST APIs for manipulating highlights. Fixes #620

7 files changed, 348 insertions, 6 deletions

diff --git a/packages/open-api/hoarder-openapi-spec.json b/packages/open-api/hoarder-openapi-spec.json
index a984fcc7..26f0a4b7 100644
--- a/packages/open-api/hoarder-openapi-spec.json
+++ b/packages/open-api/hoarder-openapi-spec.json
@@ -292,6 +292,57 @@
       "Cursor": {
         "type": "string"
       },
+      "Highlight": {
+        "type": "object",
+        "properties": {
+          "bookmarkId": {
+            "type": "string"
+          },
+          "startOffset": {
+            "type": "number"
+          },
+          "endOffset": {
+            "type": "number"
+          },
+          "color": {
+            "type": "string",
+            "enum": [
+              "yellow",
+              "red",
+              "green",
+              "blue"
+            ],
+            "default": "yellow"
+          },
+          "text": {
+            "type": "string",
+            "nullable": true
+          },
+          "note": {
+            "type": "string",
+            "nullable": true
+          },
+          "id": {
+            "type": "string"
+          },
+          "userId": {
+            "type": "string"
+          },
+          "createdAt": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "bookmarkId",
+          "startOffset",
+          "endOffset",
+          "text",
+          "note",
+          "id",
+          "userId",
+          "createdAt"
+        ]
+      },
       "List": {
         "type": "object",
         "properties": {
@@ -870,6 +921,48 @@
         }
       }
     },
+    "/bookmarks/{bookmarkId}/highlights": {
+      "get": {
+        "description": "Get highlights of a bookmark",
+        "summary": "Get highlights 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": {
+                    "highlights": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/Highlight"
+                      }
+                    }
+                  },
+                  "required": [
+                    "highlights"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/lists": {
       "get": {
         "description": "Get all lists",
diff --git a/packages/open-api/lib/bookmarks.ts b/packages/open-api/lib/bookmarks.ts
index 0ddf921e..12a122fa 100644
--- a/packages/open-api/lib/bookmarks.ts
+++ b/packages/open-api/lib/bookmarks.ts
@@ -12,6 +12,7 @@ import {
 } from "@hoarder/shared/types/bookmarks";
 
 import { BearerAuth } from "./common";
+import { HighlightSchema } from "./highlights";
 import {
   BookmarkSchema,
   PaginatedBookmarksSchema,
@@ -217,3 +218,25 @@ registry.registerPath({
     },
   },
 });
+
+registry.registerPath({
+  method: "get",
+  path: "/bookmarks/{bookmarkId}/highlights",
+  description: "Get highlights of a bookmark",
+  summary: "Get highlights 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({ highlights: z.array(HighlightSchema) }),
+        },
+      },
+    },
+  },
+});
diff --git a/packages/open-api/lib/highlights.ts b/packages/open-api/lib/highlights.ts
new file mode 100644
index 00000000..fc4c2aed
--- /dev/null
+++ b/packages/open-api/lib/highlights.ts
@@ -0,0 +1,162 @@
+import {
+  extendZodWithOpenApi,
+  OpenAPIRegistry,
+} from "@asteasolutions/zod-to-openapi";
+import { z } from "zod";
+
+import {
+  zHighlightSchema,
+  zNewHighlightSchema,
+  zUpdateHighlightSchema,
+} from "@hoarder/shared/types/highlights";
+
+import { BearerAuth } from "./common";
+import { PaginationSchema } from "./pagination";
+
+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({
+    param: {
+      name: "highlightId",
+      in: "path",
+    },
+    example: "ieidlxygmwj87oxz5hxttoc8",
+  }),
+);
+
+registry.registerPath({
+  method: "get",
+  path: "/highlights",
+  description: "Get all highlights",
+  summary: "Get all highlights",
+  tags: ["Highlights"],
+  security: [{ [BearerAuth.name]: [] }],
+  request: {
+    query: PaginationSchema,
+  },
+  responses: {
+    200: {
+      description: "Object with all highlights data.",
+      content: {
+        "application/json": {
+          schema: PaginatedHighlightsSchema,
+        },
+      },
+    },
+  },
+});
+
+registry.registerPath({
+  method: "post",
+  path: "/highlights",
+  description: "Create a new highlight",
+  summary: "Create a new highlight",
+  tags: ["Highlights"],
+  security: [{ [BearerAuth.name]: [] }],
+  request: {
+    body: {
+      description: "The highlight to create",
+      content: {
+        "application/json": {
+          schema: zNewHighlightSchema,
+        },
+      },
+    },
+  },
+  responses: {
+    201: {
+      description: "The created highlight",
+      content: {
+        "application/json": {
+          schema: HighlightSchema,
+        },
+      },
+    },
+  },
+});
+registry.registerPath({
+  method: "get",
+  path: "/highlights/{highlightId}",
+  description: "Get highlight by its id",
+  summary: "Get a single highlight",
+  tags: ["Highlights"],
+  security: [{ [BearerAuth.name]: [] }],
+  request: {
+    params: z.object({ highlightId: HighlightIdSchema }),
+  },
+  responses: {
+    200: {
+      description: "Object with highlight data.",
+      content: {
+        "application/json": {
+          schema: HighlightSchema,
+        },
+      },
+    },
+  },
+});
+
+registry.registerPath({
+  method: "delete",
+  path: "/highlights/{highlightId}",
+  description: "Delete highlight by its id",
+  summary: "Delete a highlight",
+  tags: ["Highlights"],
+  security: [{ [BearerAuth.name]: [] }],
+  request: {
+    params: z.object({ highlightId: HighlightIdSchema }),
+  },
+  responses: {
+    200: {
+      description: "The deleted highlight",
+      content: {
+        "application/json": {
+          schema: HighlightSchema,
+        },
+      },
+    },
+  },
+});
+
+registry.registerPath({
+  method: "patch",
+  path: "/highlights/{highlightId}",
+  description: "Update highlight by its id",
+  summary: "Update a highlight",
+  tags: ["Highlights"],
+  security: [{ [BearerAuth.name]: [] }],
+  request: {
+    params: z.object({ highlightId: HighlightIdSchema }),
+    body: {
+      description:
+        "The data to update. Only the fields you want to update need to be provided.",
+      content: {
+        "application/json": {
+          schema: zUpdateHighlightSchema.omit({ highlightId: true }),
+        },
+      },
+    },
+  },
+  responses: {
+    200: {
+      description: "The updated highlight",
+      content: {
+        "application/json": {
+          schema: HighlightSchema,
+        },
+      },
+    },
+  },
+});
diff --git a/packages/shared/types/bookmarks.ts b/packages/shared/types/bookmarks.ts
index 359ff7c4..41f689cd 100644
--- a/packages/shared/types/bookmarks.ts
+++ b/packages/shared/types/bookmarks.ts
@@ -1,5 +1,6 @@
 import { z } from "zod";
 
+import { zCursorV2 } from "./pagination";
 import { zBookmarkTagSchema } from "./tags";
 
 const MAX_TITLE_LENGTH = 250;
@@ -147,11 +148,6 @@ export type ZNewBookmarkRequest = z.infer<typeof zNewBookmarkRequestSchema>;
 export const DEFAULT_NUM_BOOKMARKS_PER_PAGE = 20;
 export const MAX_NUM_BOOKMARKS_PER_PAGE = 100;
 
-export const zCursorV2 = z.object({
-  createdAt: z.date(),
-  id: z.string(),
-});
-
 export const zGetBookmarksRequestSchema = z.object({
   ids: z.array(z.string()).optional(),
   archived: z.boolean().optional(),
diff --git a/packages/shared/types/highlights.ts b/packages/shared/types/highlights.ts
index b766c360..9bda6029 100644
--- a/packages/shared/types/highlights.ts
+++ b/packages/shared/types/highlights.ts
@@ -1,5 +1,7 @@
 import { z } from "zod";
 
+export const DEFAULT_NUM_HIGHLIGHTS_PER_PAGE = 20;
+
 const zHighlightColorSchema = z.enum(["yellow", "red", "green", "blue"]);
 export type ZHighlightColor = z.infer<typeof zHighlightColorSchema>;
 export const SUPPORTED_HIGHLIGHT_COLORS = zHighlightColorSchema.options;
diff --git a/packages/shared/types/pagination.ts b/packages/shared/types/pagination.ts
new file mode 100644
index 00000000..d2312982
--- /dev/null
+++ b/packages/shared/types/pagination.ts
@@ -0,0 +1,6 @@
+import { z } from "zod";
+
+export const zCursorV2 = z.object({
+  createdAt: z.date(),
+  id: z.string(),
+});
diff --git a/packages/trpc/routers/highlights.ts b/packages/trpc/routers/highlights.ts
index 14d0ffa9..e4446679 100644
--- a/packages/trpc/routers/highlights.ts
+++ b/packages/trpc/routers/highlights.ts
@@ -1,13 +1,15 @@
 import { experimental_trpcMiddleware, TRPCError } from "@trpc/server";
-import { and, eq } from "drizzle-orm";
+import { and, eq, lt, lte, or } from "drizzle-orm";
 import { z } from "zod";
 
 import { highlights } from "@hoarder/db/schema";
 import {
+  DEFAULT_NUM_HIGHLIGHTS_PER_PAGE,
   zHighlightSchema,
   zNewHighlightSchema,
   zUpdateHighlightSchema,
 } from "@hoarder/shared/types/highlights";
+import { zCursorV2 } from "@hoarder/shared/types/pagination";
 
 import { authedProcedure, Context, router } from "../index";
 import { ensureBookmarkOwnership } from "./bookmarks";
@@ -77,6 +79,64 @@ export const highlightsAppRouter = router({
       });
       return { highlights: results };
     }),
+  get: authedProcedure
+    .input(z.object({ highlightId: z.string() }))
+    .output(zHighlightSchema)
+    .use(ensureHighlightOwnership)
+    .query(async ({ input, ctx }) => {
+      const result = await ctx.db.query.highlights.findFirst({
+        where: and(
+          eq(highlights.id, input.highlightId),
+          eq(highlights.userId, ctx.user.id),
+        ),
+      });
+      if (!result) {
+        throw new TRPCError({ code: "NOT_FOUND" });
+      }
+      return result;
+    }),
+  getAll: authedProcedure
+    .input(
+      z.object({
+        cursor: zCursorV2.nullish(),
+        limit: z.number().optional().default(DEFAULT_NUM_HIGHLIGHTS_PER_PAGE),
+      }),
+    )
+    .output(
+      z.object({
+        highlights: z.array(zHighlightSchema),
+        nextCursor: zCursorV2.nullable(),
+      }),
+    )
+    .query(async ({ input, ctx }) => {
+      const results = await ctx.db.query.highlights.findMany({
+        where: and(
+          eq(highlights.userId, ctx.user.id),
+          input.cursor
+            ? or(
+                lt(highlights.createdAt, input.cursor.createdAt),
+                and(
+                  eq(highlights.createdAt, input.cursor.createdAt),
+                  lte(highlights.id, input.cursor.id),
+                ),
+              )
+            : undefined,
+        ),
+        limit: input.limit + 1,
+      });
+      let nextCursor: z.infer<typeof zCursorV2> | null = null;
+      if (results.length > input.limit) {
+        const nextItem = results.pop()!;
+        nextCursor = {
+          id: nextItem.id,
+          createdAt: nextItem.createdAt,
+        };
+      }
+      return {
+        highlights: results,
+        nextCursor,
+      };
+    }),
   delete: authedProcedure
     .input(z.object({ highlightId: z.string() }))
     .output(zHighlightSchema)