convex-feedback 0.1.4 → 0.2.0-beta.0

package/src/component/crons.ts

@@ -0,0 +1,16 @@
+import { cronJobs } from "convex/server";
+
+import { internal } from "./_generated/api.js";
+
+const crons = cronJobs();
+
+// Interval jobs run as soon as they are first deployed. The 30-day repeat is a
+// temporary, low-frequency self-healing safeguard for missed legacy records.
+crons.interval(
+  "self-heal entry status filters",
+  { hours: 24 * 30 },
+  internal.migrations.backfillStatusFilter,
+  {},
+);
+
+export default crons;

package/src/component/entries.ts

@@ -18,8 +18,12 @@ import {
 } from "./helpers.js";
 import {
   actorValidator,
+  actorIsAdmin,
   entryKindValidator,
+  entryPriorityValidator,
   entrySortValidator,
+  entryStatusFilterForStatus,
+  entryStatusFilterValidator,
   entryStatusValidator,
   feedbackMetadataValidator,
   publicEntryValidator,
@@ -63,6 +67,7 @@ export const list = query({
     paginationOpts: paginationOptsValidator,
     kinds: v.optional(v.array(entryKindValidator)),
     status: v.optional(entryStatusValidator),
+    statusFilter: v.optional(entryStatusFilterValidator),
     sort: entrySortValidator,
     viewerActorId: v.optional(v.string()),
   },
@@ -70,11 +75,82 @@ export const list = query({
   handler: async (ctx, args) => {
     const db = paginator(ctx.db, schema);
     const kinds = normalizeKindFilter(args.kinds);
-    const { status } = args;
+    const { status, statusFilter } = args;
+
+    if (status !== undefined && statusFilter !== undefined) {
+      throw new ConvexError(
+        "`status` and `statusFilter` cannot be used together.",
+      );
+    }
 
     let result: PaginationResult<Doc<"entries">>;
 
-    if (kinds === undefined) {
+    if (statusFilter !== undefined) {
+      if (kinds === undefined) {
+        result =
+          args.sort === "top"
+            ? await db
+                .query("entries")
+                .withIndex("by_status_filter_upvotes", (q) =>
+                  q.eq("statusFilter", statusFilter),
+                )
+                .order("desc")
+                .paginate(args.paginationOpts)
+            : await db
+                .query("entries")
+                .withIndex("by_status_filter", (q) =>
+                  q.eq("statusFilter", statusFilter),
+                )
+                .order("desc")
+                .paginate(args.paginationOpts);
+      } else if (kinds.length === 1) {
+        const kind = kinds[0];
+
+        if (kind === undefined) {
+          throw new ConvexError("Invalid kind filter.");
+        }
+
+        result =
+          args.sort === "top"
+            ? await db
+                .query("entries")
+                .withIndex("by_kind_status_filter_upvotes", (q) =>
+                  q.eq("kind", kind).eq("statusFilter", statusFilter),
+                )
+                .order("desc")
+                .paginate(args.paginationOpts)
+            : await db
+                .query("entries")
+                .withIndex("by_kind_status_filter", (q) =>
+                  q.eq("kind", kind).eq("statusFilter", statusFilter),
+                )
+                .order("desc")
+                .paginate(args.paginationOpts);
+      } else {
+        const streams = kinds.map((kind) =>
+          args.sort === "top"
+            ? stream(ctx.db, schema)
+                .query("entries")
+                .withIndex("by_kind_status_filter_upvotes", (q) =>
+                  q.eq("kind", kind).eq("statusFilter", statusFilter),
+                )
+                .order("desc")
+            : stream(ctx.db, schema)
+                .query("entries")
+                .withIndex("by_kind_status_filter", (q) =>
+                  q.eq("kind", kind).eq("statusFilter", statusFilter),
+                )
+                .order("desc"),
+        );
+
+        result = await mergedStream(
+          streams,
+          args.sort === "top"
+            ? ["upvoteCount", "_creationTime"]
+            : ["_creationTime"],
+        ).paginate(args.paginationOpts);
+      }
+    } else if (kinds === undefined) {
       result =
         args.sort === "top"
           ? status === undefined
@@ -202,7 +278,7 @@ export const get = query({
   args: {
     entryId: v.id("entries"),
     viewerActorId: v.optional(v.string()),
-    viewerIsModerator: v.optional(v.boolean()),
+    viewerIsAdmin: v.optional(v.boolean()),
   },
   returns: v.union(publicEntryValidator, v.null()),
   handler: async (ctx, args) => {
@@ -213,7 +289,7 @@ export const get = query({
           ctx,
           entry,
           args.viewerActorId,
-          args.viewerIsModerator === true,
+          args.viewerIsAdmin === true,
         );
   },
 });
@@ -223,6 +299,7 @@ export const search = query({
     searchQuery: v.string(),
     kinds: v.optional(v.array(entryKindValidator)),
     status: v.optional(entryStatusValidator),
+    statusFilter: v.optional(entryStatusFilterValidator),
     limit: v.number(),
     viewerActorId: v.optional(v.string()),
   },
@@ -235,11 +312,67 @@ export const search = query({
     }
 
     const kinds = normalizeKindFilter(args.kinds);
-    const { status } = args;
+    const { status, statusFilter } = args;
+
+    if (status !== undefined && statusFilter !== undefined) {
+      throw new ConvexError(
+        "`status` and `statusFilter` cannot be used together.",
+      );
+    }
 
     let entries: Doc<"entries">[];
 
-    if (kinds === undefined) {
+    if (statusFilter !== undefined) {
+      if (kinds === undefined) {
+        entries = await ctx.db
+          .query("entries")
+          .withSearchIndex("search", (q) =>
+            q
+              .search("searchText", searchQuery)
+              .eq("statusFilter", statusFilter),
+          )
+          .take(args.limit);
+      } else if (kinds.length === 1) {
+        const kind = kinds[0];
+
+        if (kind === undefined) {
+          throw new ConvexError("Invalid kind filter.");
+        }
+
+        entries = await ctx.db
+          .query("entries")
+          .withSearchIndex("search", (q) =>
+            q
+              .search("searchText", searchQuery)
+              .eq("kind", kind)
+              .eq("statusFilter", statusFilter),
+          )
+          .take(args.limit);
+      } else {
+        const firstKind = kinds[0];
+        const secondKind = kinds[1];
+
+        if (firstKind === undefined || secondKind === undefined) {
+          throw new ConvexError("Invalid kind filter.");
+        }
+
+        entries = await ctx.db
+          .query("entries")
+          .withSearchIndex("search", (q) =>
+            q
+              .search("searchText", searchQuery)
+              .eq("statusFilter", statusFilter),
+          )
+          // eslint-disable-next-line @convex-dev/no-filter-in-query
+          .filter((q) =>
+            q.or(
+              q.eq(q.field("kind"), firstKind),
+              q.eq(q.field("kind"), secondKind),
+            ),
+          )
+          .take(args.limit);
+      }
+    } else if (kinds === undefined) {
       entries =
         status === undefined
           ? await ctx.db
@@ -453,6 +586,7 @@ export const create = mutation({
       actorId: args.actorId,
       kind: args.kind,
       status: args.defaultStatus,
+      statusFilter: entryStatusFilterForStatus(args.defaultStatus),
       title,
       body,
       normalizedTitle: normalizeTitle(title),
@@ -488,7 +622,7 @@ export const update = mutation({
     if (entry === null) throw new ConvexError("Entry not found.");
 
     const canEdit =
-      args.actor.isModerator ||
+      actorIsAdmin(args.actor) ||
       (args.editableByAuthor && entry.actorId === args.actor.id);
     if (!canEdit) throw new ConvexError("Not authorized to edit this entry.");
 
@@ -504,6 +638,7 @@ export const update = mutation({
       body,
       normalizedTitle: normalizeTitle(title),
       searchText: `${title}\n${body}`,
+      statusFilter: entryStatusFilterForStatus(entry.status),
       updatedAt: Date.now(),
     });
     return null;
@@ -518,14 +653,37 @@ export const setStatus = mutation({
   },
   returns: v.null(),
   handler: async (ctx, args) => {
-    if (!args.actor.isModerator) {
-      throw new ConvexError("Moderator access is required to change status.");
+    if (!actorIsAdmin(args.actor)) {
+      throw new ConvexError("Admin access is required to change status.");
     }
     if ((await ctx.db.get("entries", args.entryId)) === null) {
       throw new ConvexError("Entry not found.");
     }
     await ctx.db.patch("entries", args.entryId, {
       status: args.status,
+      statusFilter: entryStatusFilterForStatus(args.status),
+      updatedAt: Date.now(),
+    });
+    return null;
+  },
+});
+
+export const setPriority = mutation({
+  args: {
+    actor: actorValidator,
+    entryId: v.id("entries"),
+    priority: v.union(entryPriorityValidator, v.null()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    if (!actorIsAdmin(args.actor)) {
+      throw new ConvexError("Admin access is required to change priority.");
+    }
+    if ((await ctx.db.get("entries", args.entryId)) === null) {
+      throw new ConvexError("Entry not found.");
+    }
+    await ctx.db.patch("entries", args.entryId, {
+      priority: args.priority === null ? undefined : args.priority,
       updatedAt: Date.now(),
     });
     return null;
@@ -557,14 +715,20 @@ export const setUpvote = mutation({
         entryId: args.entryId,
       });
       const upvoteCount = entry.upvoteCount + 1;
-      await ctx.db.patch("entries", args.entryId, { upvoteCount });
+      await ctx.db.patch("entries", args.entryId, {
+        upvoteCount,
+        statusFilter: entryStatusFilterForStatus(entry.status),
+      });
       return { active: true, upvoteCount };
     }
 
     if (!args.desiredState && existing !== null) {
       await ctx.db.delete("reactions", existing._id);
       const upvoteCount = Math.max(0, entry.upvoteCount - 1);
-      await ctx.db.patch("entries", args.entryId, { upvoteCount });
+      await ctx.db.patch("entries", args.entryId, {
+        upvoteCount,
+        statusFilter: entryStatusFilterForStatus(entry.status),
+      });
       return { active: false, upvoteCount };
     }
 

package/src/component/helpers.ts

@@ -2,7 +2,12 @@ import { ConvexError } from "convex/values";
 
 import type { DataModel } from "./_generated/dataModel.js";
 import type { QueryCtx } from "./types.js";
-import type { FeedbackComment, FeedbackEntry } from "./model.js";
+import type {
+  AdminFeedbackEntry,
+  FeedbackComment,
+  FeedbackEntry,
+  RoadmapItem,
+} from "./model.js";
 
 const metadataMaximumKeysPerSection = 32;
 const metadataMaximumKeyLength = 64;
@@ -137,6 +142,44 @@ export async function serializeEntry(
   };
 }
 
+export function serializeRoadmapItem(
+  item: DataModel["roadmap"]["document"],
+  position = item.position,
+): RoadmapItem {
+  return {
+    id: item._id,
+    creationTime: item._creationTime,
+    title: item.title,
+    ...(item.description === undefined
+      ? {}
+      : { description: item.description }),
+    status: item.status,
+    position,
+    createdAt: item.createdAt,
+    updatedAt: item.updatedAt,
+    feedbackCount: item.feedbackCount,
+  };
+}
+
+export async function serializeAdminEntry(
+  ctx: QueryCtx,
+  entry: DataModel["entries"]["document"],
+  viewerActorId: string,
+): Promise<AdminFeedbackEntry> {
+  const [base, roadmap] = await Promise.all([
+    serializeEntry(ctx, entry, viewerActorId, true),
+    entry.roadmapId === undefined
+      ? null
+      : ctx.db.get("roadmap", entry.roadmapId),
+  ]);
+
+  return {
+    ...base,
+    ...(entry.priority === undefined ? {} : { priority: entry.priority }),
+    ...(roadmap === null ? {} : { roadmap: serializeRoadmapItem(roadmap) }),
+  };
+}
+
 export async function serializeComment(
   ctx: QueryCtx,
   comment: DataModel["comments"]["document"],

package/src/component/migrations.ts

@@ -0,0 +1,44 @@
+import { v } from "convex/values";
+
+import { internal } from "./_generated/api.js";
+import { internalMutation } from "./_generated/server.js";
+import { entryStatusFilterForStatus } from "./model.js";
+
+const statusFilterMigrationBatchSize = 100;
+
+/**
+ * Backfills one bounded batch of legacy entries and schedules the next batch.
+ *
+ * The indexed undefined lookup and deterministic status mapping make this
+ * safe to run concurrently, retry, or invoke again after completion.
+ */
+export const backfillStatusFilter = internalMutation({
+  args: {},
+  returns: v.object({
+    updated: v.number(),
+    hasMore: v.boolean(),
+  }),
+  handler: async (ctx) => {
+    const entries = await ctx.db
+      .query("entries")
+      .withIndex("by_status_filter", (q) => q.eq("statusFilter", undefined))
+      .take(statusFilterMigrationBatchSize);
+
+    for (const entry of entries) {
+      await ctx.db.patch("entries", entry._id, {
+        statusFilter: entryStatusFilterForStatus(entry.status),
+      });
+    }
+
+    const hasMore = entries.length === statusFilterMigrationBatchSize;
+    if (hasMore) {
+      await ctx.scheduler.runAfter(
+        0,
+        internal.migrations.backfillStatusFilter,
+        {},
+      );
+    }
+
+    return { updated: entries.length, hasMore };
+  },
+});

package/src/component/model.ts

@@ -16,11 +16,28 @@ export const entryStatusValidator = v.union(
   v.literal("closed"),
 );
 
+export const entryStatusFilterValidator = v.union(
+  v.literal("open"),
+  v.literal("closed"),
+);
+
 export const entrySortValidator = v.union(
   v.literal("top"),
   v.literal("newest"),
 );
 
+export const entryPriorityValidator = v.union(
+  v.literal("low"),
+  v.literal("medium"),
+  v.literal("high"),
+);
+
+export const roadmapStatusValidator = v.union(
+  v.literal("planned"),
+  v.literal("in_progress"),
+  v.literal("shipped"),
+);
+
 export const commentSortValidator = v.union(
   v.literal("top"),
   v.literal("newest"),
@@ -29,7 +46,34 @@ export const commentSortValidator = v.union(
 
 export const actorValidator = v.object({
   id: v.string(),
-  isModerator: v.boolean(),
+  isAdmin: v.optional(v.boolean()),
+  /** @deprecated Use `isAdmin`. */
+  isModerator: v.optional(v.boolean()),
+});
+
+/**
+ * Resolves the current admin flag while keeping the pre-`isAdmin` actor shape
+ * working for existing hosts. The new field wins when both are present.
+ */
+export function actorIsAdmin(actor: {
+  isAdmin?: boolean;
+  isModerator?: boolean;
+}): boolean {
+  return actor.isAdmin === undefined
+    ? actor.isModerator === true
+    : actor.isAdmin === true;
+}
+
+export const roadmapItemValidator = v.object({
+  id: v.string(),
+  creationTime: v.number(),
+  title: v.string(),
+  description: v.optional(v.string()),
+  status: roadmapStatusValidator,
+  position: v.number(),
+  createdAt: v.number(),
+  updatedAt: v.number(),
+  feedbackCount: v.number(),
 });
 
 export const feedbackMetadataValueValidator = v.union(
@@ -83,6 +127,12 @@ export const similarEntriesValidator = v.object({
   similar: v.array(publicEntryValidator),
 });
 
+export const adminEntryValidator = publicEntryValidator.extend({
+  priority: v.optional(entryPriorityValidator),
+  roadmap: v.optional(roadmapItemValidator),
+  metadata: v.optional(feedbackMetadataValidator),
+});
+
 /**
  * Category of feedback represented by an entry.
  *
@@ -100,6 +150,15 @@ export type EntryKind = Infer<typeof entryKindValidator>;
  */
 export type EntryStatus = Infer<typeof entryStatusValidator>;
 
+/** Coarse status bucket used by the indexed board and search filters. */
+export type EntryStatusFilter = Infer<typeof entryStatusFilterValidator>;
+
+export function entryStatusFilterForStatus(
+  status: EntryStatus,
+): EntryStatusFilter {
+  return status === "closed" ? "closed" : "open";
+}
+
 /**
  * Server-side ordering strategy for feedback entries.
  *
@@ -109,6 +168,15 @@ export type EntryStatus = Infer<typeof entryStatusValidator>;
  */
 export type EntrySort = Infer<typeof entrySortValidator>;
 
+/** Internal triage priority visible only through the admin API. */
+export type EntryPriority = Infer<typeof entryPriorityValidator>;
+
+/** Workflow stage for an admin roadmap item. */
+export type RoadmapStatus = Infer<typeof roadmapStatusValidator>;
+
+/** Admin-managed roadmap item and its current attached-feedback count. */
+export type RoadmapItem = Infer<typeof roadmapItemValidator>;
+
 /**
  * Server-side ordering strategy for comments and replies.
  *
@@ -130,9 +198,13 @@ export type CommentSort = Infer<typeof commentSortValidator>;
  * application user ID, anonymous installation ID, or another stable
  * host-controlled identifier.
  *
+ * @property isAdmin
+ * Whether the actor can perform admin-only actions such as changing entry
+ * status or modifying content they do not own. When omitted, the deprecated
+ * `isModerator` field is used.
+ *
  * @property isModerator
- * Whether the actor can perform moderator-only actions such as changing entry
- * status or modifying content they do not own.
+ * @deprecated Use `isAdmin`.
  */
 export type FeedbackActor = Infer<typeof actorValidator>;
 
@@ -185,11 +257,14 @@ export type FeedbackMetadata = Infer<typeof feedbackMetadataValidator>;
  *
  * @property metadata
  * Creation-time diagnostic metadata. Present only when `getEntry` is queried
- * by a moderator. Ordinary entry lists, searches, and non-moderator reads omit
+ * by an admin. Ordinary entry lists, searches, and non-admin reads omit
  * this property.
  */
 export type FeedbackEntry = Infer<typeof publicEntryValidator>;
 
+/** Feedback entry enriched with private triage metadata for admin clients. */
+export type AdminFeedbackEntry = Infer<typeof adminEntryValidator>;
+
 /**
  * Public representation of a comment or reply.
  *