convex-feedback 0.1.3 → 0.1.5

package/src/client/api.ts

@@ -9,8 +9,10 @@ import type {
   EntryKind,
   EntrySort,
   EntryStatus,
+  EntryStatusFilter,
   FeedbackComment,
   FeedbackEntry,
+  FeedbackMetadata,
   SimilarEntriesResult,
 } from "../component/model.js";
 
@@ -39,6 +41,9 @@ export type ListEntriesArgs = {
   /** Restricts entries to this workflow status. */
   status?: EntryStatus;
 
+  /** Restricts entries to the indexed open or closed board bucket. */
+  statusFilter?: EntryStatusFilter;
+
   /**
    * Server-side ordering strategy.
    *
@@ -73,6 +78,9 @@ export type SearchEntriesArgs = {
   /** Optional workflow-status restriction. */
   status?: EntryStatus;
 
+  /** Optional indexed open or closed board bucket. */
+  statusFilter?: EntryStatusFilter;
+
   /**
    * Maximum number of results to return.
    *
@@ -134,6 +142,9 @@ export type CreateEntryArgs = {
 
   /** Entry description/body. */
   body: string;
+
+  /** Optional creation-time diagnostic metadata. */
+  metadata?: FeedbackMetadata;
 };
 
 /**

package/src/client/index.ts

@@ -26,7 +26,9 @@ import {
   commentSortValidator,
   entryKindValidator,
   entrySortValidator,
+  entryStatusFilterValidator,
   entryStatusValidator,
+  feedbackMetadataValidator,
   publicCommentValidator,
   publicEntryValidator,
   similarEntriesValidator,
@@ -43,9 +45,12 @@ export type {
   EntryKind,
   EntrySort,
   EntryStatus,
+  EntryStatusFilter,
   FeedbackActor,
   FeedbackComment,
   FeedbackEntry,
+  FeedbackMetadata,
+  FeedbackMetadataValue,
   SimilarEntriesResult,
 } from "../component/model.js";
 export type { FeedbackPublicApi } from "./api.js";
@@ -425,6 +430,7 @@ function buildFeedbackApi<
         paginationOpts: paginationOptsValidator,
         kinds: v.optional(v.array(entryKindValidator)),
         status: v.optional(entryStatusValidator),
+        statusFilter: v.optional(entryStatusFilterValidator),
         sort: v.optional(entrySortValidator),
       },
       returns: paginationResultValidator(publicEntryValidator),
@@ -438,6 +444,9 @@ function buildFeedbackApi<
           ),
           ...(args.kinds === undefined ? {} : { kinds: args.kinds }),
           ...(args.status === undefined ? {} : { status: args.status }),
+          ...(args.statusFilter === undefined
+            ? {}
+            : { statusFilter: args.statusFilter }),
           sort: args.sort ?? config.entries.defaultSort,
           ...actorIdFields(actor),
         });
@@ -452,6 +461,7 @@ function buildFeedbackApi<
         return await ctx.runQuery(component.entries.get, {
           entryId: args.entryId,
           ...actorIdFields(actor),
+          ...(actor?.isModerator === true ? { viewerIsModerator: true } : {}),
         });
       },
     }),
@@ -461,6 +471,7 @@ function buildFeedbackApi<
         searchQuery: v.string(),
         kinds: v.optional(v.array(entryKindValidator)),
         status: v.optional(entryStatusValidator),
+        statusFilter: v.optional(entryStatusFilterValidator),
         limit: v.optional(v.number()),
       },
       returns: v.array(publicEntryValidator),
@@ -471,6 +482,9 @@ function buildFeedbackApi<
           searchQuery: args.searchQuery,
           ...(args.kinds === undefined ? {} : { kinds: args.kinds }),
           ...(args.status === undefined ? {} : { status: args.status }),
+          ...(args.statusFilter === undefined
+            ? {}
+            : { statusFilter: args.statusFilter }),
           limit: clampPositive(
             args.limit,
             config.search.defaultLimit,
@@ -515,6 +529,7 @@ function buildFeedbackApi<
         kind: entryKindValidator,
         title: v.string(),
         body: v.string(),
+        metadata: v.optional(feedbackMetadataValidator),
       },
       returns: idReturns,
       handler: async (ctx, args) => {
@@ -535,6 +550,7 @@ function buildFeedbackApi<
           enabledKinds: [...config.entries.enabledKinds],
           maxTitleLength: config.limits.titleLength,
           maxBodyLength: config.limits.bodyLength,
+          ...(args.metadata === undefined ? {} : { metadata: args.metadata }),
         });
       },
     }),

package/src/component/README.md

@@ -5,6 +5,8 @@ This directory is the isolated Convex component backend.
 - `schema.ts`: three tables and query-driven indexes.
 - `entries.ts`: entry CRUD, full-text search, duplicate suggestions, entry voting, indexed pagination.
 - `comments.ts`: direct-child pagination, recursive write validation, soft deletion, comment likes.
+- `migrations.ts`: bounded, idempotent legacy-entry backfills.
+- `crons.ts`: immediate upgrade migration and temporary 30-day self-healing schedule.
 - `model.ts`: reusable validators and public model types.
 - `helpers.ts`: normalization, validation, and serializers.
 - `convex.config.ts`: packaged component definition.

package/src/component/_generated/api.ts

@@ -9,8 +9,10 @@
  */
 
 import type * as comments from "../comments.js";
+import type * as crons from "../crons.js";
 import type * as entries from "../entries.js";
 import type * as helpers from "../helpers.js";
+import type * as migrations from "../migrations.js";
 import type * as model from "../model.js";
 import type * as types from "../types.js";
 
@@ -23,8 +25,10 @@ import { anyApi, componentsGeneric } from "convex/server";
 
 const fullApi: ApiFromModules<{
   comments: typeof comments;
+  crons: typeof crons;
   entries: typeof entries;
   helpers: typeof helpers;
+  migrations: typeof migrations;
   model: typeof model;
   types: typeof types;
 }> = anyApi as any;

package/src/component/_generated/component.ts

@@ -127,6 +127,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           kind: "feedback" | "feature_request" | "bug_report";
           maxBodyLength: number;
           maxTitleLength: number;
+          metadata?: {
+            additional?: Record<string, string | number | boolean>;
+            standard?: Record<string, string | number | boolean>;
+          };
           title: string;
         },
         string,
@@ -135,7 +139,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
       get: FunctionReference<
         "query",
         "internal",
-        { entryId: string; viewerActorId?: string },
+        {
+          entryId: string;
+          viewerActorId?: string;
+          viewerIsModerator?: boolean;
+        },
         {
           actorId: string;
           body: string;
@@ -143,6 +151,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           creationTime: number;
           id: string;
           kind: "feedback" | "feature_request" | "bug_report";
+          metadata?: {
+            additional?: Record<string, string | number | boolean>;
+            standard?: Record<string, string | number | boolean>;
+          };
           status:
             | "open"
             | "under_review"
@@ -178,6 +190,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             | "in_progress"
             | "completed"
             | "closed";
+          statusFilter?: "open" | "closed";
           viewerActorId?: string;
         },
         {
@@ -190,6 +203,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             creationTime: number;
             id: string;
             kind: "feedback" | "feature_request" | "bug_report";
+            metadata?: {
+              additional?: Record<string, string | number | boolean>;
+              standard?: Record<string, string | number | boolean>;
+            };
             status:
               | "open"
               | "under_review"
@@ -221,6 +238,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             | "in_progress"
             | "completed"
             | "closed";
+          statusFilter?: "open" | "closed";
           viewerActorId?: string;
         },
         Array<{
@@ -230,6 +248,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           creationTime: number;
           id: string;
           kind: "feedback" | "feature_request" | "bug_report";
+          metadata?: {
+            additional?: Record<string, string | number | boolean>;
+            standard?: Record<string, string | number | boolean>;
+          };
           status:
             | "open"
             | "under_review"
@@ -286,6 +308,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             creationTime: number;
             id: string;
             kind: "feedback" | "feature_request" | "bug_report";
+            metadata?: {
+              additional?: Record<string, string | number | boolean>;
+              standard?: Record<string, string | number | boolean>;
+            };
             status:
               | "open"
               | "under_review"
@@ -305,6 +331,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             creationTime: number;
             id: string;
             kind: "feedback" | "feature_request" | "bug_report";
+            metadata?: {
+              additional?: Record<string, string | number | boolean>;
+              standard?: Record<string, string | number | boolean>;
+            };
             status:
               | "open"
               | "under_review"

package/src/component/comments.ts

@@ -15,6 +15,7 @@ import {
 import {
   actorValidator,
   commentSortValidator,
+  entryStatusFilterForStatus,
   publicCommentValidator,
 } from "./model.js";
 import schema from "./schema.js";
@@ -121,6 +122,7 @@ export const create = mutation({
 
     await ctx.db.patch("entries", args.entryId, {
       commentCount: entry.commentCount + 1,
+      statusFilter: entryStatusFilterForStatus(entry.status),
     });
 
     if (args.parentCommentId !== undefined) {

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

@@ -14,12 +14,16 @@ import {
   normalizeRequiredText,
   normalizeTitle,
   serializeEntry,
+  validateFeedbackMetadata,
 } from "./helpers.js";
 import {
   actorValidator,
   entryKindValidator,
   entrySortValidator,
+  entryStatusFilterForStatus,
+  entryStatusFilterValidator,
   entryStatusValidator,
+  feedbackMetadataValidator,
   publicEntryValidator,
   similarEntriesValidator,
   type EntryKind,
@@ -61,6 +65,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()),
   },
@@ -68,11 +73,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
@@ -200,13 +276,19 @@ export const get = query({
   args: {
     entryId: v.id("entries"),
     viewerActorId: v.optional(v.string()),
+    viewerIsModerator: v.optional(v.boolean()),
   },
   returns: v.union(publicEntryValidator, v.null()),
   handler: async (ctx, args) => {
     const entry = await ctx.db.get("entries", args.entryId);
     return entry === null
       ? null
-      : serializeEntry(ctx, entry, args.viewerActorId);
+      : serializeEntry(
+          ctx,
+          entry,
+          args.viewerActorId,
+          args.viewerIsModerator === true,
+        );
   },
 });
 
@@ -215,6 +297,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()),
   },
@@ -227,11 +310,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
@@ -424,6 +563,7 @@ export const create = mutation({
     enabledKinds: v.array(entryKindValidator),
     maxTitleLength: v.number(),
     maxBodyLength: v.number(),
+    metadata: v.optional(feedbackMetadataValidator),
   },
   returns: v.id("entries"),
   handler: async (ctx, args) => {
@@ -438,17 +578,20 @@ export const create = mutation({
       args.maxTitleLength,
     );
     const body = normalizeRequiredText(args.body, "Body", args.maxBodyLength);
+    validateFeedbackMetadata(args.metadata);
 
     const entry = await ctx.db.insert("entries", {
       actorId: args.actorId,
       kind: args.kind,
       status: args.defaultStatus,
+      statusFilter: entryStatusFilterForStatus(args.defaultStatus),
       title,
       body,
       normalizedTitle: normalizeTitle(title),
       searchText: `${title}\n${body}`,
       upvoteCount: 1,
       commentCount: 0,
+      ...(args.metadata === undefined ? {} : { metadata: args.metadata }),
     });
 
     await ctx.db.insert("reactions", {
@@ -493,6 +636,7 @@ export const update = mutation({
       body,
       normalizedTitle: normalizeTitle(title),
       searchText: `${title}\n${body}`,
+      statusFilter: entryStatusFilterForStatus(entry.status),
       updatedAt: Date.now(),
     });
     return null;
@@ -515,6 +659,7 @@ export const setStatus = mutation({
     }
     await ctx.db.patch("entries", args.entryId, {
       status: args.status,
+      statusFilter: entryStatusFilterForStatus(args.status),
       updatedAt: Date.now(),
     });
     return null;
@@ -546,14 +691,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

@@ -4,6 +4,72 @@ import type { DataModel } from "./_generated/dataModel.js";
 import type { QueryCtx } from "./types.js";
 import type { FeedbackComment, FeedbackEntry } from "./model.js";
 
+const metadataMaximumKeysPerSection = 32;
+const metadataMaximumKeyLength = 64;
+const metadataMaximumStringLength = 1_024;
+const metadataMaximumEncodedBytes = 16 * 1_024;
+const forbiddenMetadataKeys = new Set([
+  "__proto__",
+  "constructor",
+  "prototype",
+]);
+
+export function validateFeedbackMetadata(
+  metadata: DataModel["entries"]["document"]["metadata"],
+): void {
+  if (metadata === undefined) return;
+
+  for (const [sectionName, section] of Object.entries(metadata)) {
+    if (section === undefined) continue;
+    const entries = Object.entries(section);
+
+    if (entries.length > metadataMaximumKeysPerSection) {
+      throw new ConvexError(
+        `Metadata section '${sectionName}' must contain ${metadataMaximumKeysPerSection} keys or fewer.`,
+      );
+    }
+
+    for (const [key, value] of entries) {
+      if (key.length === 0) {
+        throw new ConvexError(
+          `Metadata section '${sectionName}' contains an empty key.`,
+        );
+      }
+      if (key.length > metadataMaximumKeyLength) {
+        throw new ConvexError(
+          `Metadata key '${key}' in section '${sectionName}' must be ${metadataMaximumKeyLength} characters or fewer.`,
+        );
+      }
+      if (
+        key.startsWith("_") ||
+        key.startsWith("$") ||
+        forbiddenMetadataKeys.has(key)
+      ) {
+        throw new ConvexError(
+          `Metadata key '${key}' in section '${sectionName}' is reserved and cannot be used.`,
+        );
+      }
+      if (
+        typeof value === "string" &&
+        value.length > metadataMaximumStringLength
+      ) {
+        throw new ConvexError(
+          `Metadata value for '${sectionName}.${key}' must be ${metadataMaximumStringLength} characters or fewer.`,
+        );
+      }
+    }
+  }
+
+  const encodedBytes = new TextEncoder().encode(
+    JSON.stringify(metadata),
+  ).length;
+  if (encodedBytes > metadataMaximumEncodedBytes) {
+    throw new ConvexError(
+      `Metadata must be ${metadataMaximumEncodedBytes} UTF-8 bytes or fewer; received ${encodedBytes} bytes.`,
+    );
+  }
+}
+
 export function normalizeTitle(value: string): string {
   return value.trim().replace(/\s+/g, " ").toLocaleLowerCase("en-US");
 }
@@ -41,6 +107,7 @@ export async function serializeEntry(
   ctx: QueryCtx,
   entry: DataModel["entries"]["document"],
   viewerActorId: string | undefined,
+  includeMetadata = false,
 ): Promise<FeedbackEntry> {
   const reaction =
     viewerActorId !== undefined
@@ -64,6 +131,9 @@ export async function serializeEntry(
     commentCount: entry.commentCount,
     ...(entry.updatedAt === undefined ? {} : { updatedAt: entry.updatedAt }),
     viewerHasUpvoted: reaction !== null,
+    ...(includeMetadata && entry.metadata !== undefined
+      ? { metadata: entry.metadata }
+      : {}),
   };
 }
 

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 };
+  },
+});