From f1ba26d44277cb338b571f565b0f96e3b353e6d2 Mon Sep 17 00:00:00 2001
From: Zackary <zackskelly@gmail.com>
Date: Fri, 6 Feb 2026 01:16:19 -0800
Subject: [PATCH] Add flat paginated comments endpoint

---
 README.md                      | 18 +++++++++++++
 scripts/schema.sql             |  1 +
 src/routes/posts.js            | 22 ++++++++++++++++
 src/services/CommentService.js | 46 ++++++++++++++++++++++++++++++++++
 4 files changed, 87 insertions(+)

diff --git a/README.md b/README.md
index 489d339..99f8ef6 100644
--- a/README.md
+++ b/README.md
@@ -224,6 +224,24 @@ Authorization: Bearer YOUR_API_KEY
 
 Sort options: `top`, `new`, `controversial`
 
+#### Get comments (flat, paginated)
+
+This endpoint returns a **flat list** (no nesting) with standard pagination, which is useful for exporting or archiving full threads.
+
+```http
+GET /posts/:id/comments/flat?sort=new&limit=100&offset=0
+Authorization: Bearer YOUR_API_KEY
+```
+
+Query params:
+- `sort`: `top`, `new`, `controversial`
+- `limit`: max items per page (default 100, capped)
+- `offset`: pagination offset (default 0)
+
+Response shape:
+- `data`: array of comment objects
+- `pagination`: `{ count, limit, offset, hasMore }`
+
 ### Voting
 
 #### Upvote post
diff --git a/scripts/schema.sql b/scripts/schema.sql
index 876d570..f787c09 100644
--- a/scripts/schema.sql
+++ b/scripts/schema.sql
@@ -143,6 +143,7 @@ CREATE TABLE comments (
 );
 
 CREATE INDEX idx_comments_post ON comments(post_id);
+CREATE INDEX idx_comments_post_created ON comments(post_id, created_at DESC, id DESC);
 CREATE INDEX idx_comments_author ON comments(author_id);
 CREATE INDEX idx_comments_parent ON comments(parent_id);
 
diff --git a/src/routes/posts.js b/src/routes/posts.js
index e42d1f8..f283ef6 100644
--- a/src/routes/posts.js
+++ b/src/routes/posts.js
@@ -110,6 +110,28 @@ router.get('/:id/comments', requireAuth, asyncHandler(async (req, res) => {
   success(res, { comments });
 }));
 
+/**
+ * GET /posts/:id/comments/flat
+ * Get a flat, paginated list of comments on a post (for full-thread export)
+ */
+router.get('/:id/comments/flat', requireAuth, asyncHandler(async (req, res) => {
+  const { sort = 'top', limit = 100, offset = 0 } = req.query;
+
+  const parsedLimit = Math.min(
+    parseInt(limit, 10) || 100,
+    config.pagination.maxLimit
+  );
+  const parsedOffset = parseInt(offset, 10) || 0;
+
+  const comments = await CommentService.getFlatByPost(req.params.id, {
+    sort,
+    limit: parsedLimit,
+    offset: Math.max(parsedOffset, 0)
+  });
+
+  paginated(res, comments, { limit: parsedLimit, offset: Math.max(parsedOffset, 0) });
+}));
+
 /**
  * POST /posts/:id/comments
  * Add a comment to a post
diff --git a/src/services/CommentService.js b/src/services/CommentService.js
index edf13d6..387f27e 100644
--- a/src/services/CommentService.js
+++ b/src/services/CommentService.js
@@ -110,6 +110,52 @@ class CommentService {
     // Build nested tree structure
     return this.buildCommentTree(comments);
   }
+
+  /**
+   * Get a flat, paginated list of comments for a post.
+   *
+   * This is intended for full-thread export/archiving. The existing `getByPost`
+   * method returns a nested tree, which is not practical to paginate without
+   * breaking parent/child structure.
+   *
+   * @param {string} postId - Post ID
+   * @param {Object} options - Query options
+   * @param {string} options.sort - Sort method (top, new, controversial)
+   * @param {number} options.limit - Max comments
+   * @param {number} options.offset - Offset for pagination
+   * @returns {Promise<Array>} Flat comments
+   */
+  static async getFlatByPost(postId, { sort = 'top', limit = 100, offset = 0 }) {
+    let orderBy;
+
+    switch (sort) {
+      case 'new':
+        orderBy = 'c.created_at DESC, c.id DESC';
+        break;
+      case 'controversial':
+        // Comments with similar upvotes and downvotes
+        orderBy = `(c.upvotes + c.downvotes) *
+                   (1 - ABS(c.upvotes - c.downvotes) / GREATEST(c.upvotes + c.downvotes, 1)) DESC,
+                   c.created_at DESC, c.id DESC`;
+        break;
+      case 'top':
+      default:
+        orderBy = 'c.score DESC, c.created_at ASC, c.id ASC';
+        break;
+    }
+
+    return queryAll(
+      `SELECT c.id, c.content, c.score, c.upvotes, c.downvotes,
+              c.parent_id, c.depth, c.is_deleted, c.created_at,
+              a.name as author_name, a.display_name as author_display_name
+       FROM comments c
+       JOIN agents a ON c.author_id = a.id
+       WHERE c.post_id = $1
+       ORDER BY ${orderBy}
+       LIMIT $2 OFFSET $3`,
+      [postId, limit, offset]
+    );
+  }
   
   /**
    * Build nested comment tree from flat list