convex-feedback 0.2.0-beta.8 → 0.2.0

package/src/component/README.md

@@ -2,10 +2,12 @@
 
 This directory is the isolated Convex component backend.
 
-- `schema.ts`: four 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.
+- `schema.ts`: durable feedback domain tables plus internal roadmap-rebalance bookkeeping, all with query-driven indexes.
+- `entries.ts`: entry CRUD, full-text search, duplicate suggestions, entry voting, indexed pagination, actor activity pagination, and bounded permanent-deletion cleanup.
+- `comments.ts`: direct-child pagination, recursive write validation, bounded subtree deletion, comment likes, and actor activity pagination.
+- `reactions.ts`: actor activity pagination with live entry/comment target resolution.
+- `migrations.ts`: bounded, idempotent status backfills and legacy comment
+  cleanup.
 - `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.
@@ -13,3 +15,29 @@ This directory is the isolated Convex component backend.
 - `_generated/`: generated component API/server/data-model types. Regenerate after backend changes.
 
 Important: component public functions become internal references when installed by a host app. The host must wrap them before exposing them to clients. Component IDs become strings at that boundary.
+
+Lifecycle callbacks belong to the host wrapper, not this component. The wrapper
+may transform or reject creation input before calling a component mutation and
+may run after callbacks with the mutation's returned context. Keep authentication,
+host business rules, and notification providers outside the component; component
+validation remains authoritative.
+
+Actor activity component queries accept a trusted `actorId` and use the
+`by_actor` indexes. `entries.listByActor` can additionally receive
+`includeAdminContext: true` for server-side consumers that need retained
+metadata, priority, or roadmap context. The host `listUser*` wrappers resolve
+the actor from the host callback and expose only their public activity shapes.
+
+Entry deletion is an asynchronous permanent cleanup. The entry is marked as
+deleting and hidden immediately, its roadmap link is detached, and scheduled
+batches remove entry reactions, comment reactions, and all comments before the
+entry document is hard-deleted. Comment deletion also marks its subtree and
+removes descendants and reactions in bounded scheduled batches. Activity reads
+omit pending and completed deletions.
+
+During the upgrade window, `comments.deletedAt` remains an optional internal
+schema field only so older installations can deploy safely. The legacy comment
+migration permanently removes tombstones, their descendants, and orphaned
+reactions in bounded batches. Its progress markers and `deletedAt` field are
+internal only. After supported installations have migrated, a future release
+can remove those compatibility fields from the schema.

package/src/component/_generated/api.ts

@@ -15,6 +15,7 @@ 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 reactions from "../reactions.js";
 import type * as roadmap from "../roadmap.js";
 import type * as types from "../types.js";
 
@@ -33,6 +34,7 @@ const fullApi: ApiFromModules<{
   helpers: typeof helpers;
   migrations: typeof migrations;
   model: typeof model;
+  reactions: typeof reactions;
   roadmap: typeof roadmap;
   types: typeof types;
 }> = anyApi as any;

package/src/component/_generated/component.ts

@@ -87,6 +87,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             | "in_progress"
             | "completed"
             | "closed";
+          statusFilter?: "open" | "closed";
           viewerActorId: string;
         },
         {
@@ -155,6 +156,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             | "in_progress"
             | "completed"
             | "closed";
+          statusFilter?: "open" | "closed";
           viewerActorId: string;
         },
         {
@@ -210,11 +212,37 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           actorId: string;
           body: string;
           entryId: string;
+          includeCallbackContext?: boolean;
           maxCommentLength: number;
           maxDepth: number;
           parentCommentId?: string;
         },
-        string,
+        | { id: string }
+        | {
+            comment: {
+              actorId: string;
+              body: string;
+              depth: number;
+              entryId: string;
+              id: string;
+              parentCommentId?: string;
+            };
+            entry: {
+              actorId: string;
+              id: string;
+              kind: "feedback" | "feature_request" | "bug_report";
+              status:
+                | "open"
+                | "under_review"
+                | "planned"
+                | "in_progress"
+                | "completed"
+                | "closed";
+              title: string;
+            };
+            id: string;
+            parentComment?: { actorId: string; id: string };
+          },
         Name
       >;
       list: FunctionReference<
@@ -239,9 +267,8 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           isDone: boolean;
           page: Array<{
             actorId: string;
-            body: string | null;
+            body: string;
             creationTime: number;
-            deletedAt?: number;
             depth: number;
             entryId: string;
             id: string;
@@ -256,6 +283,41 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         },
         Name
       >;
+      listByActor: FunctionReference<
+        "query",
+        "internal",
+        {
+          actorId: string;
+          paginationOpts: {
+            cursor: string | null;
+            endCursor?: string | null;
+            id?: number;
+            maximumBytesRead?: number;
+            maximumRowsRead?: number;
+            numItems: number;
+          };
+        },
+        {
+          continueCursor: string;
+          isDone: boolean;
+          page: Array<{
+            actorId: string;
+            body: string;
+            creationTime: number;
+            depth: number;
+            entryId: string;
+            entryTitle: string;
+            id: string;
+            likeCount: number;
+            parentCommentId?: string;
+            replyCount: number;
+            updatedAt?: number;
+          }>;
+          pageStatus?: "SplitRecommended" | "SplitRequired" | null;
+          splitCursor?: string | null;
+        },
+        Name
+      >;
       remove: FunctionReference<
         "mutation",
         "internal",
@@ -270,8 +332,34 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
       setLike: FunctionReference<
         "mutation",
         "internal",
-        { actorId: string; commentId: string; desiredState: boolean },
-        { active: boolean; likeCount: number },
+        {
+          actorId: string;
+          commentId: string;
+          desiredState: boolean;
+          includeCallbackContext?: boolean;
+        },
+        | { active: boolean; likeCount: number }
+        | {
+            active: boolean;
+            changed: false;
+            count: number;
+            previousCount: number;
+            transition: null;
+          }
+        | {
+            active: boolean;
+            changed: true;
+            comment: {
+              actorId: string;
+              body: string;
+              entryId: string;
+              id: string;
+              parentCommentId?: string;
+            };
+            count: number;
+            previousCount: number;
+            transition: "added" | "removed";
+          },
         Name
       >;
       update: FunctionReference<
@@ -303,6 +391,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             | "completed"
             | "closed";
           enabledKinds: Array<"feedback" | "feature_request" | "bug_report">;
+          includeCallbackContext?: boolean;
           kind: "feedback" | "feature_request" | "bug_report";
           maxBodyLength: number;
           maxTitleLength: number;
@@ -312,7 +401,30 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           };
           title: string;
         },
-        string,
+        | { id: string }
+        | {
+            entry: {
+              actorId: string;
+              body: string;
+              commentCount: 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"
+                | "planned"
+                | "in_progress"
+                | "completed"
+                | "closed";
+              title: string;
+              upvoteCount: number;
+            };
+            id: string;
+          },
         Name
       >;
       get: FunctionReference<
@@ -401,6 +513,73 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         },
         Name
       >;
+      listByActor: FunctionReference<
+        "query",
+        "internal",
+        {
+          actorId: string;
+          includeAdminContext?: boolean;
+          paginationOpts: {
+            cursor: string | null;
+            endCursor?: string | null;
+            id?: number;
+            maximumBytesRead?: number;
+            maximumRowsRead?: number;
+            numItems: number;
+          };
+        },
+        {
+          continueCursor: string;
+          isDone: boolean;
+          page: Array<{
+            actorId: string;
+            body: string;
+            commentCount: number;
+            creationTime: number;
+            id: string;
+            kind: "feedback" | "feature_request" | "bug_report";
+            metadata?: {
+              additional?: Record<string, string | number | boolean>;
+              standard?: Record<string, string | number | boolean>;
+            };
+            priority?: "low" | "medium" | "high";
+            roadmap?: {
+              createdAt: number;
+              creationTime: number;
+              description?: string;
+              feedbackCount: number;
+              id: string;
+              position: number;
+              status: "planned" | "in_progress" | "shipped";
+              title: string;
+              updatedAt: number;
+            };
+            status:
+              | "open"
+              | "under_review"
+              | "planned"
+              | "in_progress"
+              | "completed"
+              | "closed";
+            title: string;
+            updatedAt?: number;
+            upvoteCount: number;
+          }>;
+          pageStatus?: "SplitRecommended" | "SplitRequired" | null;
+          splitCursor?: string | null;
+        },
+        Name
+      >;
+      remove: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          actor: { id: string; isAdmin?: boolean; isModerator?: boolean };
+          entryId: string;
+        },
+        null,
+        Name
+      >;
       search: FunctionReference<
         "query",
         "internal",
@@ -475,8 +654,40 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
       setUpvote: FunctionReference<
         "mutation",
         "internal",
-        { actorId: string; desiredState: boolean; entryId: string },
-        { active: boolean; upvoteCount: number },
+        {
+          actorId: string;
+          desiredState: boolean;
+          entryId: string;
+          includeCallbackContext?: boolean;
+        },
+        | { active: boolean; upvoteCount: number }
+        | {
+            active: boolean;
+            changed: false;
+            count: number;
+            previousCount: number;
+            transition: null;
+          }
+        | {
+            active: boolean;
+            changed: true;
+            count: number;
+            entry: {
+              actorId: string;
+              id: string;
+              kind: "feedback" | "feature_request" | "bug_report";
+              status:
+                | "open"
+                | "under_review"
+                | "planned"
+                | "in_progress"
+                | "completed"
+                | "closed";
+              title: string;
+            };
+            previousCount: number;
+            transition: "added" | "removed";
+          },
         Name
       >;
       similar: FunctionReference<
@@ -558,6 +769,60 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         Name
       >;
     };
+    reactions: {
+      listByActor: FunctionReference<
+        "query",
+        "internal",
+        {
+          actorId: string;
+          paginationOpts: {
+            cursor: string | null;
+            endCursor?: string | null;
+            id?: number;
+            maximumBytesRead?: number;
+            maximumRowsRead?: number;
+            numItems: number;
+          };
+        },
+        {
+          continueCursor: string;
+          isDone: boolean;
+          page: Array<
+            | {
+                creationTime: number;
+                entry: {
+                  id: string;
+                  kind: "feedback" | "feature_request" | "bug_report";
+                  status:
+                    | "open"
+                    | "under_review"
+                    | "planned"
+                    | "in_progress"
+                    | "completed"
+                    | "closed";
+                  title: string;
+                };
+                id: string;
+                type: "entry_upvote";
+              }
+            | {
+                comment: {
+                  body: string;
+                  entryId: string;
+                  entryTitle: string;
+                  id: string;
+                };
+                creationTime: number;
+                id: string;
+                type: "comment_like";
+              }
+          >;
+          pageStatus?: "SplitRecommended" | "SplitRequired" | null;
+          splitCursor?: string | null;
+        },
+        Name
+      >;
+    };
     roadmap: {
       attachFeedback: FunctionReference<
         "mutation",
@@ -605,6 +870,23 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         null,
         Name
       >;
+      get: FunctionReference<
+        "query",
+        "internal",
+        { roadmapId: string },
+        {
+          createdAt: number;
+          creationTime: number;
+          description?: string;
+          feedbackCount: number;
+          id: string;
+          position: number;
+          status: "planned" | "in_progress" | "shipped";
+          title: string;
+          updatedAt: number;
+        } | null,
+        Name
+      >;
       list: FunctionReference<
         "query",
         "internal",

package/src/component/admin.ts

@@ -14,10 +14,12 @@ import {
   adminEntryValidator,
   entryKindValidator,
   entryPriorityValidator,
+  entryStatusFilterValidator,
   entryStatusValidator,
   type EntryKind,
   type EntryPriority,
   type EntryStatus,
+  type EntryStatusFilter,
 } from "./model.js";
 import schema from "./schema.js";
 
@@ -87,11 +89,14 @@ function matchesFilters(
   entry: Doc<"entries">,
   kinds: EntryKind[] | undefined,
   status: EntryStatus | undefined,
+  statusFilter: EntryStatusFilter | undefined,
   priority: EntryPriority | undefined,
 ): boolean {
   return (
+    entry.deletingAt === undefined &&
     (kinds === undefined || kinds.includes(entry.kind)) &&
     (status === undefined || entry.status === status) &&
+    (statusFilter === undefined || entry.statusFilter === statusFilter) &&
     (priority === undefined || entry.priority === priority)
   );
 }
@@ -110,7 +115,7 @@ export const getEntry = query({
   returns: v.union(adminEntryValidator, v.null()),
   handler: async (ctx, args) => {
     const entry = await ctx.db.get("entries", args.entryId);
-    return entry === null
+    return entry === null || entry.deletingAt !== undefined
       ? null
       : await serializeAdminEntry(ctx, entry, args.viewerActorId);
   },
@@ -120,6 +125,7 @@ export const listEntries = query({
   args: {
     kinds: v.optional(v.array(entryKindValidator)),
     status: v.optional(entryStatusValidator),
+    statusFilter: v.optional(entryStatusFilterValidator),
     priority: v.optional(entryPriorityValidator),
     paginationOpts: paginationOptsValidator,
     viewerActorId: v.string(),
@@ -131,27 +137,50 @@ export const listEntries = query({
     if (kinds?.length === 0) {
       throw new ConvexError("`kinds` must contain at least one kind.");
     }
+    if (args.status !== undefined && args.statusFilter !== undefined) {
+      throw new ConvexError(
+        "`status` and `statusFilter` cannot be used together.",
+      );
+    }
 
     const entriesStream =
-      args.priority !== undefined
-        ? stream(ctx.db, schema)
-            .query("entries")
-            .withIndex("by_priority", (q) => q.eq("priority", args.priority))
-        : args.status !== undefined
+      args.statusFilter !== undefined
+        ? kinds?.length === 1
+          ? stream(ctx.db, schema)
+              .query("entries")
+              .withIndex("by_kind_status_filter", (q) =>
+                q.eq("kind", kinds[0]!).eq("statusFilter", args.statusFilter),
+              )
+          : stream(ctx.db, schema)
+              .query("entries")
+              .withIndex("by_status_filter", (q) =>
+                q.eq("statusFilter", args.statusFilter),
+              )
+        : args.priority !== undefined
           ? stream(ctx.db, schema)
               .query("entries")
-              .withIndex("by_status", (q) => q.eq("status", args.status!))
-          : kinds?.length === 1
+              .withIndex("by_priority", (q) => q.eq("priority", args.priority))
+          : args.status !== undefined
             ? stream(ctx.db, schema)
                 .query("entries")
-                .withIndex("by_kind", (q) => q.eq("kind", kinds[0]!))
-            : stream(ctx.db, schema).query("entries");
+                .withIndex("by_status", (q) => q.eq("status", args.status!))
+            : kinds?.length === 1
+              ? stream(ctx.db, schema)
+                  .query("entries")
+                  .withIndex("by_kind", (q) => q.eq("kind", kinds[0]!))
+              : stream(ctx.db, schema).query("entries");
 
     const result = await entriesStream
       .order("desc")
       .filterWith((entry) =>
         Promise.resolve(
-          matchesFilters(entry, kinds, args.status, args.priority),
+          matchesFilters(
+            entry,
+            kinds,
+            args.status,
+            args.statusFilter,
+            args.priority,
+          ),
         ),
       )
       .paginate(args.paginationOpts);
@@ -172,12 +201,18 @@ export const searchEntries = query({
     searchQuery: v.string(),
     kinds: v.optional(v.array(entryKindValidator)),
     status: v.optional(entryStatusValidator),
+    statusFilter: v.optional(entryStatusFilterValidator),
     priority: v.optional(entryPriorityValidator),
     paginationOpts: paginationOptsValidator,
     viewerActorId: v.string(),
   },
   returns: paginationResultValidator(adminEntryValidator),
   handler: async (ctx, args) => {
+    if (args.status !== undefined && args.statusFilter !== undefined) {
+      throw new ConvexError(
+        "`status` and `statusFilter` cannot be used together.",
+      );
+    }
     const searchQuery = args.searchQuery.trim();
     if (searchQuery.length === 0) {
       return { page: [], isDone: true, continueCursor: "" };
@@ -197,37 +232,60 @@ export const searchEntries = query({
             const withKind =
               kinds?.length === 1 ? searched.eq("kind", kinds[0]!) : searched;
             const withStatus =
-              args.status === undefined
-                ? withKind
-                : withKind.eq("status", args.status);
-            return args.priority === undefined
-              ? withStatus
-              : withStatus.eq("priority", args.priority);
+              args.statusFilter === undefined
+                ? args.status === undefined
+                  ? withKind
+                  : withKind.eq("status", args.status)
+                : withKind.eq("statusFilter", args.statusFilter);
+            const withPriority =
+              args.priority === undefined
+                ? withStatus
+                : withStatus.eq("priority", args.priority);
+            return withPriority.eq("deletingAt", undefined);
           }),
           args.paginationOpts,
         )
       : await (
-          args.priority !== undefined
-            ? stream(ctx.db, schema)
-                .query("entries")
-                .withIndex("by_priority", (q) =>
-                  q.eq("priority", args.priority),
-                )
-            : args.status !== undefined
+          args.statusFilter !== undefined
+            ? kinds?.length === 1
+              ? stream(ctx.db, schema)
+                  .query("entries")
+                  .withIndex("by_kind_status_filter", (q) =>
+                    q
+                      .eq("kind", kinds[0]!)
+                      .eq("statusFilter", args.statusFilter),
+                  )
+              : stream(ctx.db, schema)
+                  .query("entries")
+                  .withIndex("by_status_filter", (q) =>
+                    q.eq("statusFilter", args.statusFilter),
+                  )
+            : args.priority !== undefined
               ? stream(ctx.db, schema)
                   .query("entries")
-                  .withIndex("by_status", (q) => q.eq("status", args.status!))
-              : kinds?.length === 1
+                  .withIndex("by_priority", (q) =>
+                    q.eq("priority", args.priority),
+                  )
+              : args.status !== undefined
                 ? stream(ctx.db, schema)
                     .query("entries")
-                    .withIndex("by_kind", (q) => q.eq("kind", kinds[0]!))
-                : stream(ctx.db, schema).query("entries")
+                    .withIndex("by_status", (q) => q.eq("status", args.status!))
+                : kinds?.length === 1
+                  ? stream(ctx.db, schema)
+                      .query("entries")
+                      .withIndex("by_kind", (q) => q.eq("kind", kinds[0]!))
+                  : stream(ctx.db, schema).query("entries")
         )
           .order("desc")
           .filterWith((entry) =>
             Promise.resolve(
-              matchesFilters(entry, kinds, args.status, args.priority) &&
-                matchesSearch(entry, searchQuery),
+              matchesFilters(
+                entry,
+                kinds,
+                args.status,
+                args.statusFilter,
+                args.priority,
+              ) && matchesSearch(entry, searchQuery),
             ),
           )
           .paginate(args.paginationOpts);