convex-feedback 0.2.0-beta.9 → 0.2.0

package/README.md

@@ -1,4 +1,4 @@
-[![npm version](https://badge.fury.io/js/convex-feedback.svg)](https://badge.fury.io/js/convex-feedback) [![Convex Component](https://www.convex.dev/components/badge/convex-feedback)](https://www.convex.dev/components/convex-feedback) ![NPM License](https://img.shields.io/npm/l/convex-feedback) ![NPM Downloads](https://img.shields.io/npm/dw/convex-feedback) ![GitHub forks](https://img.shields.io/github/forks/moumen-io/convex-feedback) ![GitHub Repo stars](https://img.shields.io/github/stars/moumen-io/convex-feedback)
+![npm version](https://badge.fury.io/js/convex-feedback.svg) ![Convex Component](https://www.convex.dev/components/badge/convex-feedback) ![NPM License](https://img.shields.io/npm/l/convex-feedback) ![NPM Downloads](https://img.shields.io/npm/dw/convex-feedback) ![GitHub forks](https://img.shields.io/github/forks/moumen-io/convex-feedback) ![GitHub Repo stars](https://img.shields.io/github/stars/moumen-io/convex-feedback)
 
 [Vite demo](https://convex-feedback-vite.vercel.app/) • [Expo demo](https://convex-feedback-expo.vercel.app/) • [React Native demo](https://convex-feedback-native.vercel.app/)
 
@@ -6,7 +6,7 @@
 
 A headless, fully typed Convex component for product feedback, feature requests, bug reports, entry upvotes, lazy nested comments, comment likes, full-text search, duplicate suggestions, and admin workflows.
 
-> Looking for a ready-made public interface? [`convex-feedback-ui`](../convex-feedback-ui/README.md) provides optional React DOM and React Native screens and compound primitives. For internal triage, fork the [Clerk admin panel](../../apps/admin/withClerk/README.md).
+> Looking for a ready-made public interface? `[convex-feedback-ui](../convex-feedback-ui/README.md)` provides optional React DOM and React Native screens and compound primitives. For internal triage, fork the [Clerk admin panel](../../apps/admin/withClerk/README.md).
 
 ## Features
 
@@ -19,13 +19,18 @@ A headless, fully typed Convex component for product feedback, feature requests,
 - Convex full-text search.
 - Exact-title + full-text duplicate suggestions.
 - Host-controlled authentication and admin permissions.
+- Indexed actor-scoped activity for entries, comments, and reactions.
 - Admin priority and roadmap workflows.
 - Optional host-defined mutation rate limiting.
+- Optional host-defined lifecycle callbacks for creation and reaction changes.
 - Configurable limits and behavior
 - Typed React hooks.
 - `convex-test` helper entry point.
 
-The component owns four tables: `entries`, `comments`, `reactions`, and `roadmap`.
+The component persists feedback domain data in `entries`, `comments`, `reactions`,
+and `roadmap`. It also uses `roadmapRebalances` as internal bookkeeping while
+large roadmap reorder operations complete; that state is not part of the public
+feedback model.
 
 ## Requirements
 
@@ -77,6 +82,17 @@ The same job repeats every 30 days for now as a temporary, low-frequency
 self-healing safeguard for missed or legacy records. It should be removed in a
 future release after supported installations have had enough time to upgrade.
 
+### Legacy comment deletion migration
+
+Older releases stored soft-deleted comments with an internal `deletedAt`
+timestamp. The upgrade migration now drains those tombstones, their descendant
+threads, comment reactions, and legacy orphan documents in bounded scheduled
+batches. New comment deletion is permanent; `deletedAt` is retained only as an
+optional internal compatibility field during this migration and is not exposed
+by public types or UI. The migration's progress markers are internal as well.
+After supported installations have migrated, a future release can remove these
+compatibility fields from the schema.
+
 ## 2. Expose the component through your host API
 
 A Convex component cannot make authorization decisions using your host application's authentication state directly. `convex-feedback` therefore exposes a host wrapper: your app resolves the current actor, and the wrapper passes the stable actor identity into the component.
@@ -95,6 +111,7 @@ export const {
   findSimilarEntries,
   createEntry,
   updateEntry,
+  deleteEntry,
   setEntryStatus,
   isAdmin,
   isAuthenticated,
@@ -102,13 +119,17 @@ export const {
   adminGetEntry,
   adminSearchEntries,
   setEntryPriority,
+  listUserEntries,
   setEntryUpvote,
   listComments,
+  listUserComments,
+  listUserReactions,
   createComment,
   updateComment,
   deleteComment,
   setCommentLike,
   listRoadmap,
+  getRoadmapItem,
   searchRoadmap,
   createRoadmap,
   createRoadmapForEntry,
@@ -151,7 +172,7 @@ return {
 
 ## 3. Configure behavior
 
-Configuration is optional static host code; The values shown are the default configuration.
+Configuration is optional static host code; the values shown are the default configuration.
 
 ```ts
 export const feedbackApi = exposeFeedbackApi(components.feedback, {
@@ -251,6 +272,286 @@ export const feedbackApi = exposeFeedbackApi(components.feedback, {
 });
 ```
 
+### Lifecycle callbacks
+
+Lifecycle callbacks are host-wrapper hooks for business logic around creation
+and reaction changes. They are grouped by domain so entry, comment, and reaction
+events stay discoverable and can evolve independently without a flat list of
+unrelated callback names. Configure them at the top level of
+`exposeFeedbackApi`; `config` remains for component behavior:
+
+```ts
+callbacks: {
+  rejection,
+  entries: {
+    beforeCreate,
+    afterCreate,
+  },
+  comments: {
+    beforeCreate,
+    afterCreate,
+  },
+  reactions: {
+    afterChange,
+  },
+}
+```
+
+For entry and comment creation, the lifecycle is:
+
+```text
+auth → rate limiting → beforeCreate → component mutation → afterCreate
+```
+
+For reactions, it is:
+
+```text
+auth → rate limiting → component mutation → afterChange (only if state changed)
+```
+
+`beforeCreate` executes inside the host mutation and receives the full host
+mutation context, including `db`, `auth`, `storage`, `scheduler`, `runQuery`,
+`runMutation`, and `meta`. It runs before the component mutation, so it can do
+simple synchronous validation or business logic, query or mutate host data when
+necessary, sanitize content, return a supported transform, or call `reject()`.
+Callbacks may also be async when the host needs a nested Convex call. A returned
+patch is still passed through the component's normal validation; a callback
+cannot bypass enabled-kind, length, nesting, or other component rules. Entry
+callbacks may patch `kind`, `title`, `body`, and `metadata`. Comment callbacks
+may patch only `body`; `entryId` and `parentCommentId` remain component-owned.
+Callback inputs are readonly snapshots. The wrapper builds component arguments
+from the original mutation arguments plus only the explicitly returned patch,
+so mutating an event object cannot leak changes into component relationships.
+
+For example, a host can sanitize profanity and reject content that becomes
+empty after sanitization:
+
+```ts
+import { v } from "convex/values";
+
+const moderationRejection = v.object({
+  kind: v.literal("content_rejected"),
+  reason: v.string(),
+});
+
+export const feedbackApi = exposeFeedbackApi(components.feedback, {
+  actor: resolveFeedbackActor,
+  callbacks: {
+    rejection: { behavior: "return", returns: moderationRejection },
+    entries: {
+      beforeCreate: (ctx, event, handlers) => {
+        const title = removeProfanity(event.input.title);
+        const body = removeProfanity(event.input.body);
+        if (!title.trim() || !body.trim()) {
+          return handlers.reject({
+            kind: "content_rejected",
+            reason: "Entry content is empty after sanitization",
+          });
+        }
+        return { title, body };
+      },
+    },
+    comments: {
+      beforeCreate: (ctx, event, handlers) => {
+        void ctx;
+        const body = removeProfanity(event.input.body);
+        if (!body.trim()) {
+          return handlers.reject({
+            kind: "content_rejected",
+            reason: "Comment content is empty after sanitization",
+          });
+        }
+        return { body };
+      },
+    },
+  },
+});
+```
+
+The default callback rejection behavior is
+`callbacks.rejection.behavior = "throw"` (or omit `rejection`). It is equivalent
+to:
+
+```ts
+callbacks: {
+  rejection: { behavior: "throw" },
+}
+```
+
+An explicit `reject(value)` becomes a `ConvexError`, and no component mutation
+occurs after that rejection. To return a validated value instead, configure:
+
+```ts
+callbacks: {
+  rejection: {
+    behavior: "return",
+    returns: moderationRejection,
+  },
+}
+```
+
+Only explicit `reject()` calls use this behavior. Normal exceptions thrown by a
+callback still throw, including when return mode is enabled. Return mode changes
+the TypeScript result union of the relevant create mutation:
+`createEntry` and/or `createComment` become `string | CallbackRejection` (and
+retain any rate-limit rejection type). If rate limiting also uses return mode,
+the create mutation's union composes both the rate-limit and callback rejection
+values. Other mutations receive only their configured rate-limit result.
+
+After callbacks are awaited in the originating host mutation. There are three
+important failure models:
+
+1. **Throw or nested mutation failure.** An uncaught `afterCreate` or
+   `afterChange` error, including a failed nested `ctx.runMutation`, runs in the
+   same transaction and rolls back the originating host mutation and its
+   component write.
+2. **Scheduled action.** Schedule external work from the callback when it must
+   happen after commit:
+
+   ```ts
+   await ctx.scheduler.runAfter(
+     0,
+     internal.notifications.sendNotificationToUser,
+     args,
+   );
+   ```
+
+   Scheduling is committed atomically with the mutation. The action runs after
+   commit, so a later action failure cannot roll back persisted entries,
+   comments, or reactions. Scheduled actions are at-most-once and are not
+   automatically retried; use an app-owned outbox or durable workflow when
+   stronger delivery guarantees are required.
+
+3. **Explicit catch.** A callback can catch an error itself when the failure is
+   intentionally non-blocking. There is no package-level option that silently
+   ignores callback exceptions; swallowing an error is an application decision.
+
+Reaction `afterChange` runs only when the actor's desired state actually changes.
+It runs for both additions and removals. The event exposes
+`transition: "added" | "removed"`, `previousCount`, and `count` (the final
+count), plus the reacting actor and the target author/context: `entry` for an
+entry upvote, or `comment` for a comment like. Entry-upvote events also expose
+`entryId`, while comment-like events expose `commentId` and `entryId`; these
+top-level IDs always match the IDs in the nested target context. Comment-like
+events include the comment author and `entryId` without reading or serializing
+the parent entry.
+
+Rich component callback context is requested only when the corresponding
+`afterCreate` or `afterChange` callback is configured. With no after callback,
+creation and reaction mutations keep their lean result path and avoid
+callback-only reads and serialization.
+
+```ts
+afterChange: async (ctx, event) => {
+  if (event.transition !== "added") return;
+
+  const thresholds = [5, 10, 20];
+  const crossed = thresholds.some(
+    (threshold) => event.previousCount < threshold && event.count >= threshold,
+  );
+  if (!crossed) return;
+
+  // event.count is authoritative; event.previousCount prevents duplicates
+  // when a count changes without crossing a configured threshold.
+};
+```
+
+For notifications, keep the provider and recipient policy in the host app.
+This small example uses an app-owned `sendNotificationToUser` internal action;
+the component does not know about email, push, or notification providers:
+
+```ts
+// convex/notifications.ts
+import { internalAction } from "convex/server";
+import { v } from "convex/values";
+
+export const sendNotificationToUser = internalAction({
+  args: {
+    userId: v.string(),
+    title: v.string(),
+    body: v.string(),
+  },
+  handler: async (ctx, args) => {
+    void ctx;
+    // `notificationProvider` is an app-owned email/push integration.
+    await notificationProvider.send(args);
+  },
+});
+```
+
+The host wrapper can then schedule admins, the entry author, the parent
+comment author, and threshold notifications:
+
+```ts
+// convex/feedback.ts
+import { internal } from "./_generated/api";
+
+const ADMIN_USER_IDS = ["admin-1", "admin-2"];
+const REACTION_THRESHOLDS = [5, 10, 20];
+
+export const { createEntry, createComment, setEntryUpvote, setCommentLike } =
+  exposeFeedbackApi(components.feedback, {
+    actor: resolveFeedbackActor,
+    callbacks: {
+      entries: {
+        afterCreate: async (ctx, event) => {
+          await Promise.all(
+            ADMIN_USER_IDS.map((userId) =>
+              ctx.scheduler.runAfter(
+                0,
+                internal.notifications.sendNotificationToUser,
+                {
+                  userId,
+                  title: "New feedback",
+                  body: event.entry.title,
+                },
+              ),
+            ),
+          );
+        },
+      },
+      comments: {
+        afterCreate: async (ctx, event) => {
+          const userId = event.parentComment?.actorId ?? event.entry.actorId;
+          await ctx.scheduler.runAfter(
+            0,
+            internal.notifications.sendNotificationToUser,
+            {
+              userId,
+              title: event.parentComment ? "New reply" : "New comment",
+              body: event.comment.body,
+            },
+          );
+        },
+      },
+      reactions: {
+        afterChange: async (ctx, event) => {
+          if (event.transition !== "added") return;
+          const crossed = REACTION_THRESHOLDS.some(
+            (threshold) =>
+              event.previousCount < threshold && event.count >= threshold,
+          );
+          if (!crossed) return;
+
+          const userId =
+            event.type === "entry_upvote"
+              ? event.entry.actorId
+              : event.comment.actorId;
+          await ctx.scheduler.runAfter(
+            0,
+            internal.notifications.sendNotificationToUser,
+            {
+              userId,
+              title: "Your feedback is getting attention",
+              body: `Reaction count: ${event.count}`,
+            },
+          );
+        },
+      },
+    },
+  });
+```
+
 ## 4. Create typed React hooks
 
 If your client uses React or React Native, bind the generated host API once. Calling `createFeedbackHooks()` without an API argument defaults to `anyApi.feedback`; pass the generated namespace explicitly when the component is exposed elsewhere:
@@ -299,6 +600,92 @@ Metadata is intentionally absent from entry lists, searches, and duplicate sugge
 Public entry results include `viewerIsAuthor` when returned by the current wrapper deployment. It is computed from the server-resolved actor and the stored entry author; clients should use it only to present author-only UI such as an Edit action. `updateEntry` still rechecks ownership in the component
 mutation, so a caller that is not the entry author is rejected. Admins retain their existing permission to edit entries through the admin workflow.
 
+### Actor-scoped activity
+
+The host wrapper also exposes cursor-paginated activity queries for the authenticated actor:
+
+```ts
+const userEntries = await listUserEntries({
+  paginationOpts: { cursor: null, numItems: 20 },
+});
+const userComments = await listUserComments({
+  paginationOpts: { cursor: null, numItems: 20 },
+});
+const userReactions = await listUserReactions({
+  paginationOpts: { cursor: null, numItems: 20 },
+});
+```
+
+A trusted Convex function can compose these wrappers through the generated host API. `ctx.runQuery` keeps the caller's authentication context, so the configured actor callback still selects the actor and no `actorId` is passed:
+
+```ts
+import { api } from "./_generated/api";
+import { query } from "./_generated/server";
+
+export const getMyActivity = query({
+  args: {},
+  handler: async (ctx) => {
+    const entryQuery = api.feedback.listUserEntries;
+    const commentQuery = api.feedback.listUserComments;
+    const reactionQuery = api.feedback.listUserReactions;
+    const opts = { cursor: null, numItems: 20 };
+    const entries = await ctx.runQuery(entryQuery, { paginationOpts: opts });
+    const comments = await ctx.runQuery(commentQuery, { paginationOpts: opts });
+    const reactions = await ctx.runQuery(reactionQuery, {
+      paginationOpts: opts,
+    });
+    return { entries, comments, reactions };
+  },
+});
+```
+
+These wrappers do not accept an `actorId`; they always use the actor returned by the configured host callback. Entries include their own content, status, timestamps, and counts. Comments include their body, `parentCommentId`, and the parent entry title without loading a parent-comment body. Pending deletions are hidden immediately.
+
+Reaction results are discriminated by `type` (`"entry_upvote"` or `"comment_like"`) and include reaction creation time plus resolved live target context. Permanent entry and comment deletion remove dependent reactions in scheduled cleanup batches, so completed deletions do not leave activity records or orphan targets behind.
+
+Trusted server consumers can call the component-level actor query directly with a known `actorId`. `entries.listByActor` additionally accepts `includeAdminContext: true` when an export or other server-side workflow needs retained metadata, priority, or roadmap context; the normal `listUserEntries` wrapper always strips those private fields.
+
+For example, an internal Convex function can query all three activity feeds for a known actor without requiring request authentication:
+
+```ts
+import { components } from "./_generated/api";
+import { internalQuery } from "./_generated/server";
+import { v } from "convex/values";
+
+export const getActorActivity = internalQuery({
+  args: { actorId: v.string() },
+  handler: async (ctx, args) => {
+    const opts = { cursor: null, numItems: 100 };
+    const entries = await ctx.runQuery(
+      components.feedback.entries.listByActor,
+      {
+        actorId: args.actorId,
+        paginationOpts: opts,
+        includeAdminContext: true,
+      },
+    );
+
+    const comments = await ctx.runQuery(
+      components.feedback.comments.listByActor,
+      {
+        actorId: args.actorId,
+        paginationOpts: opts,
+      },
+    );
+
+    const reactions = await ctx.runQuery(
+      components.feedback.reactions.listByActor,
+      {
+        actorId: args.actorId,
+        paginationOpts: opts,
+      },
+    );
+
+    return { entries, comments, reactions };
+  },
+});
+```
+
 ## Admin panel
 
 The standalone [Vite and Expo Clerk admin apps](../../apps/admin/withClerk/README.md) provide an inbox, entry detail workflow, and a stage-based roadmap. They are reference applications to fork and deploy, not reusable UI exports.
@@ -319,7 +706,7 @@ actor: async (ctx) => {
 
 Set the claim and Convex Clerk provider using Clerk's current integration instructions, then export the complete wrapper API shown above as `convex/feedback.ts`. Both reference apps use `anyApi.feedback` by default and reactively check `isAdmin` at their root, offering retry when the access check fails; every admin query and mutation still rechecks the actor on the server.
 
-Admin entries may have an optional `low`, `medium`, or `high` priority and one roadmap relation. Deleting a roadmap item detaches all related feedback. Public entry queries and the existing public UI do not expose priority, while roadmap reads are public.
+Admin entries may have an optional `low`, `medium`, or `high` priority and one roadmap relation. Deleting a roadmap item detaches all related feedback. Permanent entry deletion first hides the entry, detaches its roadmap relation, and schedules bounded cleanup of reactions and comments before hard deletion. Public entry queries and the existing public UI do not expose priority, while roadmap reads are public.
 
 ## Entry kinds and statuses
 
@@ -414,7 +801,7 @@ A comment query returns exactly one direct-child level. Opening a reply branch s
 
 `replyCount` is the number of **direct children**. `entry.commentCount` is the total number of comments/replies belonging to the entry.
 
-Soft-deleted comments remain as tombstones so descendants keep their position in the thread.
+Deleting a comment permanently removes it, all descendants, and their reactions in bounded scheduled batches. The comment and its descendants are hidden as soon as deletion starts; `replyCount` and `entry.commentCount` are updated as documents are removed.
 
 ## Upvotes and likes
 
@@ -449,12 +836,16 @@ The wrapper exposes:
 | `isAuthenticated`       | query    | Whether the current request has an actor             |
 | `createEntry`           | mutation | Create feedback                                      |
 | `updateEntry`           | mutation | Edit feedback; admins may also change its kind       |
+| `deleteEntry`           | mutation | Permanently delete feedback; admins only             |
 | `setEntryStatus`        | mutation | Admin workflow status change                         |
 | `setEntryUpvote`        | mutation | Idempotently set entry upvote state                  |
+| `listUserEntries`       | query    | Entries created by the authenticated actor           |
 | `listComments`          | query    | One paginated direct-child comment level             |
+| `listUserComments`      | query    | Comments created by the authenticated actor          |
+| `listUserReactions`     | query    | Entry upvotes and comment likes by the actor         |
 | `createComment`         | mutation | Create comment or reply                              |
 | `updateComment`         | mutation | Edit a comment                                       |
-| `deleteComment`         | mutation | Soft-delete a comment                                |
+| `deleteComment`         | mutation | Permanently delete a comment subtree                 |
 | `setCommentLike`        | mutation | Idempotently set comment like state                  |
 | `createRoadmapForEntry` | mutation | Create a roadmap item and attach an entry atomically |