convex-feedback 0.1.4 → 0.2.0-beta.0

package/src/client/api.ts

@@ -9,9 +9,14 @@ import type {
   EntryKind,
   EntrySort,
   EntryStatus,
+  EntryStatusFilter,
   FeedbackComment,
   FeedbackEntry,
   FeedbackMetadata,
+  AdminFeedbackEntry,
+  EntryPriority,
+  RoadmapItem,
+  RoadmapStatus,
   SimilarEntriesResult,
 } from "../component/model.js";
 
@@ -40,6 +45,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.
    *
@@ -74,6 +82,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.
    *
@@ -165,6 +176,60 @@ export type SetEntryStatusArgs = {
   status: EntryStatus;
 };
 
+export type AdminListEntriesArgs = {
+  /** Convex cursor-pagination options. */
+  paginationOpts: PaginationOptions;
+  kinds?: EntryKind[];
+  status?: EntryStatus;
+  priority?: EntryPriority;
+};
+
+export type AdminSearchEntriesArgs = AdminListEntriesArgs & {
+  searchQuery: string;
+};
+
+export type SetEntryPriorityArgs = {
+  entryId: string;
+  priority: EntryPriority | null;
+};
+
+export type ListRoadmapArgs = {
+  /** Convex cursor-pagination options. */
+  paginationOpts: PaginationOptions;
+  status?: RoadmapStatus;
+};
+export type SearchRoadmapArgs = { searchQuery: string; limit?: number };
+export type CreateRoadmapArgs = {
+  title: string;
+  description?: string;
+  status: RoadmapStatus;
+};
+export type CreateRoadmapForEntryArgs = CreateRoadmapArgs & {
+  entryId: string;
+};
+export type UpdateRoadmapArgs = {
+  roadmapId: string;
+  title: string;
+  description?: string;
+};
+export type DeleteRoadmapArgs = { roadmapId: string };
+export type MoveRoadmapArgs = {
+  roadmapId: string;
+  status: RoadmapStatus;
+  previousItemId?: string;
+  nextItemId?: string;
+};
+export type AttachFeedbackToRoadmapArgs = {
+  roadmapId: string;
+  entryId: string;
+};
+export type DetachFeedbackFromRoadmapArgs = { entryId: string };
+export type ListRoadmapFeedbackArgs = {
+  /** Convex cursor-pagination options. */
+  paginationOpts: PaginationOptions;
+  roadmapId: string;
+};
+
 /**
  * Arguments for setting the current actor's entry-upvote state.
  */
@@ -301,6 +366,24 @@ export interface FeedbackPublicApi<
   Name extends string | undefined = string | undefined,
   RateLimitResult = never,
 > {
+  /** Returns whether the host actor has admin permissions. */
+  isAdmin: FunctionReference<
+    "query",
+    "public",
+    Record<string, never>,
+    boolean,
+    Name
+  >;
+
+  /** Returns whether the current request has an authenticated host actor. */
+  isAuthenticated: FunctionReference<
+    "query",
+    "public",
+    Record<string, never>,
+    boolean,
+    Name
+  >;
+
   /** Returns a cursor-paginated entry list. */
   listEntries: FunctionReference<
     "query",
@@ -364,6 +447,106 @@ export interface FeedbackPublicApi<
     Name
   >;
 
+  adminListEntries: FunctionReference<
+    "query",
+    "public",
+    AdminListEntriesArgs,
+    PaginationResult<AdminFeedbackEntry>,
+    Name
+  >;
+  adminGetEntry: FunctionReference<
+    "query",
+    "public",
+    GetEntryArgs,
+    AdminFeedbackEntry | null,
+    Name
+  >;
+  adminSearchEntries: FunctionReference<
+    "query",
+    "public",
+    AdminSearchEntriesArgs,
+    PaginationResult<AdminFeedbackEntry>,
+    Name
+  >;
+  setEntryPriority: FunctionReference<
+    "mutation",
+    "public",
+    SetEntryPriorityArgs,
+    null | RateLimitResult,
+    Name
+  >;
+
+  listRoadmap: FunctionReference<
+    "query",
+    "public",
+    ListRoadmapArgs,
+    PaginationResult<RoadmapItem>,
+    Name
+  >;
+  searchRoadmap: FunctionReference<
+    "query",
+    "public",
+    SearchRoadmapArgs,
+    RoadmapItem[],
+    Name
+  >;
+  createRoadmap: FunctionReference<
+    "mutation",
+    "public",
+    CreateRoadmapArgs,
+    string | RateLimitResult,
+    Name
+  >;
+  createRoadmapForEntry: FunctionReference<
+    "mutation",
+    "public",
+    CreateRoadmapForEntryArgs,
+    string | RateLimitResult,
+    Name
+  >;
+  updateRoadmap: FunctionReference<
+    "mutation",
+    "public",
+    UpdateRoadmapArgs,
+    null | RateLimitResult,
+    Name
+  >;
+  deleteRoadmap: FunctionReference<
+    "mutation",
+    "public",
+    DeleteRoadmapArgs,
+    null | RateLimitResult,
+    Name
+  >;
+  moveRoadmapItem: FunctionReference<
+    "mutation",
+    "public",
+    MoveRoadmapArgs,
+    number | RateLimitResult,
+    Name
+  >;
+  attachFeedbackToRoadmap: FunctionReference<
+    "mutation",
+    "public",
+    AttachFeedbackToRoadmapArgs,
+    null | RateLimitResult,
+    Name
+  >;
+  detachFeedbackFromRoadmap: FunctionReference<
+    "mutation",
+    "public",
+    DetachFeedbackFromRoadmapArgs,
+    null | RateLimitResult,
+    Name
+  >;
+  listRoadmapFeedback: FunctionReference<
+    "query",
+    "public",
+    ListRoadmapFeedbackArgs,
+    PaginationResult<FeedbackEntry>,
+    Name
+  >;
+
   /** Sets entry-upvote state, or returns a configured rate-limit rejection. */
   setEntryUpvote: FunctionReference<
     "mutation",

package/src/client/config.ts

@@ -42,7 +42,7 @@ export interface FeedbackEntriesConfig {
   /**
    * Whether entry authors may edit their own title and body.
    *
-   * Moderators are governed separately by the resolved actor permissions.
+   * Admins are governed separately by the resolved actor permissions.
    *
    * @default true
    */

package/src/client/index.ts

@@ -23,14 +23,20 @@ import {
 
 import type { ComponentApi } from "../component/_generated/component.js";
 import {
+  adminEntryValidator,
   commentSortValidator,
   entryKindValidator,
+  entryPriorityValidator,
   entrySortValidator,
+  entryStatusFilterValidator,
   entryStatusValidator,
   feedbackMetadataValidator,
   publicCommentValidator,
   publicEntryValidator,
+  roadmapItemValidator,
+  roadmapStatusValidator,
   similarEntriesValidator,
+  actorIsAdmin,
   type FeedbackActor,
 } from "../component/model.js";
 import type { FeedbackPublicApi } from "./api.js";
@@ -40,15 +46,20 @@ import {
 } from "./config.js";
 
 export type {
+  AdminFeedbackEntry,
   CommentSort,
   EntryKind,
+  EntryPriority,
   EntrySort,
   EntryStatus,
+  EntryStatusFilter,
   FeedbackActor,
   FeedbackComment,
   FeedbackEntry,
   FeedbackMetadata,
   FeedbackMetadataValue,
+  RoadmapItem,
+  RoadmapStatus,
   SimilarEntriesResult,
 } from "../component/model.js";
 export type { FeedbackPublicApi } from "./api.js";
@@ -125,10 +136,13 @@ export interface ThrowingFeedbackRateLimitConfig {
   behavior?: "throw";
 
   /**
-   * Whether all configured limiter groups apply to moderators.
+   * Whether all configured limiter groups apply to admins.
    *
    * @default false
    */
+  limitAdmins?: boolean;
+
+  /** @deprecated Use `limitAdmins`. */
   limitModerators?: boolean;
 
   /** Not accepted in throwing mode; select `"return"` to provide a validator. */
@@ -168,10 +182,13 @@ export interface ReturningFeedbackRateLimitConfig<
   returns: ReturnsValidator;
 
   /**
-   * Whether all configured limiter groups apply to moderators.
+   * Whether all configured limiter groups apply to admins.
    *
    * @default false
    */
+  limitAdmins?: boolean;
+
+  /** @deprecated Use `limitAdmins`. */
   limitModerators?: boolean;
 }
 
@@ -260,10 +277,10 @@ export type ThrowingExposeFeedbackOptions = Omit<
   /** Optional component behavior and throwing rate-limit overrides. */
   config?: FeedbackConfigOverrides & {
     /**
-     * Controls throwing behavior and the moderator exemption.
+     * Controls throwing behavior and the admin exemption.
      *
      * Omit this object to use `behavior: "throw"` and
-     * `limitModerators: false`.
+     * `limitAdmins: false`.
      */
     rateLimiting?: FeedbackRateLimitConfig;
   };
@@ -314,9 +331,9 @@ function requireActor(actor: FeedbackActor | null): FeedbackActor {
   return actor;
 }
 
-function requireModerator(actor: FeedbackActor): void {
-  if (!actor.isModerator) {
-    throw new ConvexError("Moderator permissions are required.");
+function requireAdmin(actor: FeedbackActor): void {
+  if (!actorIsAdmin(actor)) {
+    throw new ConvexError("Admin permissions are required.");
   }
 }
 
@@ -347,10 +364,9 @@ async function applyRateLimiter<
     | ReturningFeedbackRateLimitConfig<FeedbackRateLimitReturnValidator>
     | undefined,
 ): Promise<RateLimitResult<ReturnsValidator> | undefined> {
-  if (
-    limiter === undefined ||
-    (actor.isModerator && rateLimitConfig?.limitModerators !== true)
-  ) {
+  const limitAdmins =
+    rateLimitConfig?.limitAdmins ?? rateLimitConfig?.limitModerators ?? false;
+  if (limiter === undefined || (actorIsAdmin(actor) && !limitAdmins)) {
     return undefined;
   }
 
@@ -421,13 +437,50 @@ function buildFeedbackApi<
     v.object({ active: v.boolean(), likeCount: v.number() }),
     rateLimitReturnValidator,
   );
+  const numberReturns = rateLimitedReturns(
+    v.number(),
+    rateLimitReturnValidator,
+  );
+
+  const requireAdminActor = async (ctx: FeedbackAuthContext) => {
+    const actor = requireActor(await options.actor(ctx));
+    requireAdmin(actor);
+    return actor;
+  };
+
+  const applyAdminEditLimit = async (
+    ctx: FeedbackRateLimitContext,
+    actor: FeedbackActor,
+  ) =>
+    await applyRateLimiter(
+      ctx,
+      actor,
+      options.rateLimiters?.editContent,
+      rateLimitConfig,
+    );
 
   return {
+    isAdmin: queryGeneric({
+      args: {},
+      returns: v.boolean(),
+      handler: async (ctx) => {
+        const actor = await options.actor(ctx);
+        return actor !== null && actorIsAdmin(actor);
+      },
+    }),
+
+    isAuthenticated: queryGeneric({
+      args: {},
+      returns: v.boolean(),
+      handler: async (ctx) => (await options.actor(ctx)) !== null,
+    }),
+
     listEntries: queryGeneric({
       args: {
         paginationOpts: paginationOptsValidator,
         kinds: v.optional(v.array(entryKindValidator)),
         status: v.optional(entryStatusValidator),
+        statusFilter: v.optional(entryStatusFilterValidator),
         sort: v.optional(entrySortValidator),
       },
       returns: paginationResultValidator(publicEntryValidator),
@@ -441,6 +494,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),
         });
@@ -455,7 +511,9 @@ function buildFeedbackApi<
         return await ctx.runQuery(component.entries.get, {
           entryId: args.entryId,
           ...actorIdFields(actor),
-          ...(actor?.isModerator === true ? { viewerIsModerator: true } : {}),
+          ...(actor !== null && actorIsAdmin(actor)
+            ? { viewerIsAdmin: true }
+            : {}),
         });
       },
     }),
@@ -465,6 +523,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),
@@ -475,6 +534,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,
@@ -578,7 +640,7 @@ function buildFeedbackApi<
       returns: nullReturns,
       handler: async (ctx, args) => {
         const actor = requireActor(await options.actor(ctx));
-        requireModerator(actor);
+        requireAdmin(actor);
         const limited = await applyRateLimiter(
           asRateLimitContext(ctx),
           actor,
@@ -594,6 +656,87 @@ function buildFeedbackApi<
       },
     }),
 
+    adminListEntries: queryGeneric({
+      args: {
+        paginationOpts: paginationOptsValidator,
+        kinds: v.optional(v.array(entryKindValidator)),
+        status: v.optional(entryStatusValidator),
+        priority: v.optional(entryPriorityValidator),
+      },
+      returns: paginationResultValidator(adminEntryValidator),
+      handler: async (ctx, args) => {
+        const actor = await requireAdminActor(ctx);
+        return await ctx.runQuery(component.admin.listEntries, {
+          ...(args.kinds === undefined ? {} : { kinds: args.kinds }),
+          ...(args.status === undefined ? {} : { status: args.status }),
+          ...(args.priority === undefined ? {} : { priority: args.priority }),
+          paginationOpts: clampPagination(
+            args.paginationOpts,
+            config.entries.maxPageSize,
+          ),
+          viewerActorId: actor.id,
+        });
+      },
+    }),
+
+    adminGetEntry: queryGeneric({
+      args: { entryId: v.string() },
+      returns: v.union(adminEntryValidator, v.null()),
+      handler: async (ctx, args) => {
+        const actor = await requireAdminActor(ctx);
+        return await ctx.runQuery(component.admin.getEntry, {
+          entryId: args.entryId,
+          viewerActorId: actor.id,
+        });
+      },
+    }),
+
+    adminSearchEntries: queryGeneric({
+      args: {
+        paginationOpts: paginationOptsValidator,
+        searchQuery: v.string(),
+        kinds: v.optional(v.array(entryKindValidator)),
+        status: v.optional(entryStatusValidator),
+        priority: v.optional(entryPriorityValidator),
+      },
+      returns: paginationResultValidator(adminEntryValidator),
+      handler: async (ctx, args) => {
+        const actor = await requireAdminActor(ctx);
+        return await ctx.runQuery(component.admin.searchEntries, {
+          searchQuery: args.searchQuery,
+          ...(args.kinds === undefined ? {} : { kinds: args.kinds }),
+          ...(args.status === undefined ? {} : { status: args.status }),
+          ...(args.priority === undefined ? {} : { priority: args.priority }),
+          paginationOpts: clampPagination(
+            args.paginationOpts,
+            config.entries.maxPageSize,
+          ),
+          viewerActorId: actor.id,
+        });
+      },
+    }),
+
+    setEntryPriority: mutationGeneric({
+      args: {
+        entryId: v.string(),
+        priority: v.union(entryPriorityValidator, v.null()),
+      },
+      returns: nullReturns,
+      handler: async (ctx, args) => {
+        const actor = await requireAdminActor(ctx);
+        const limited = await applyAdminEditLimit(
+          asRateLimitContext(ctx),
+          actor,
+        );
+        if (limited !== undefined) return limited;
+        return await ctx.runMutation(component.entries.setPriority, {
+          actor,
+          entryId: args.entryId,
+          priority: args.priority,
+        });
+      },
+    }),
+
     setEntryUpvote: mutationGeneric({
       args: { entryId: v.string(), desiredState: v.boolean() },
       returns: entryUpvoteReturns,
@@ -729,6 +872,190 @@ function buildFeedbackApi<
         });
       },
     }),
+
+    listRoadmap: queryGeneric({
+      args: {
+        paginationOpts: paginationOptsValidator,
+        status: v.optional(roadmapStatusValidator),
+      },
+      returns: paginationResultValidator(roadmapItemValidator),
+      handler: async (ctx, args) => {
+        return await ctx.runQuery(component.roadmap.list, {
+          ...args,
+          paginationOpts: clampPagination(
+            args.paginationOpts,
+            config.entries.maxPageSize,
+          ),
+        });
+      },
+    }),
+
+    searchRoadmap: queryGeneric({
+      args: { searchQuery: v.string(), limit: v.optional(v.number()) },
+      returns: v.array(roadmapItemValidator),
+      handler: async (ctx, args) => {
+        return await ctx.runQuery(component.roadmap.search, {
+          searchQuery: args.searchQuery,
+          limit: clampPositive(args.limit, 10, 50),
+        });
+      },
+    }),
+
+    createRoadmap: mutationGeneric({
+      args: {
+        title: v.string(),
+        description: v.optional(v.string()),
+        status: roadmapStatusValidator,
+      },
+      returns: idReturns,
+      handler: async (ctx, args) => {
+        const actor = await requireAdminActor(ctx);
+        const limited = await applyAdminEditLimit(
+          asRateLimitContext(ctx),
+          actor,
+        );
+        if (limited !== undefined) return limited;
+        return await ctx.runMutation(component.roadmap.create, {
+          actor,
+          ...args,
+        });
+      },
+    }),
+
+    createRoadmapForEntry: mutationGeneric({
+      args: {
+        title: v.string(),
+        description: v.optional(v.string()),
+        status: roadmapStatusValidator,
+        entryId: v.string(),
+      },
+      returns: idReturns,
+      handler: async (ctx, args) => {
+        const actor = await requireAdminActor(ctx);
+        const limited = await applyAdminEditLimit(
+          asRateLimitContext(ctx),
+          actor,
+        );
+        if (limited !== undefined) return limited;
+        return await ctx.runMutation(component.roadmap.createForEntry, {
+          actor,
+          ...args,
+        });
+      },
+    }),
+
+    updateRoadmap: mutationGeneric({
+      args: {
+        roadmapId: v.string(),
+        title: v.string(),
+        description: v.optional(v.string()),
+      },
+      returns: nullReturns,
+      handler: async (ctx, args) => {
+        const actor = await requireAdminActor(ctx);
+        const limited = await applyAdminEditLimit(
+          asRateLimitContext(ctx),
+          actor,
+        );
+        if (limited !== undefined) return limited;
+        return await ctx.runMutation(component.roadmap.update, {
+          actor,
+          ...args,
+        });
+      },
+    }),
+
+    deleteRoadmap: mutationGeneric({
+      args: { roadmapId: v.string() },
+      returns: nullReturns,
+      handler: async (ctx, args) => {
+        const actor = await requireAdminActor(ctx);
+        const limited = await applyAdminEditLimit(
+          asRateLimitContext(ctx),
+          actor,
+        );
+        if (limited !== undefined) return limited;
+        return await ctx.runMutation(component.roadmap.remove, {
+          actor,
+          ...args,
+        });
+      },
+    }),
+
+    moveRoadmapItem: mutationGeneric({
+      args: {
+        roadmapId: v.string(),
+        status: roadmapStatusValidator,
+        previousItemId: v.optional(v.string()),
+        nextItemId: v.optional(v.string()),
+      },
+      returns: numberReturns,
+      handler: async (ctx, args) => {
+        const actor = await requireAdminActor(ctx);
+        const limited = await applyAdminEditLimit(
+          asRateLimitContext(ctx),
+          actor,
+        );
+        if (limited !== undefined) return limited;
+        return await ctx.runMutation(component.roadmap.move, {
+          actor,
+          ...args,
+        });
+      },
+    }),
+
+    attachFeedbackToRoadmap: mutationGeneric({
+      args: { roadmapId: v.string(), entryId: v.string() },
+      returns: nullReturns,
+      handler: async (ctx, args) => {
+        const actor = await requireAdminActor(ctx);
+        const limited = await applyAdminEditLimit(
+          asRateLimitContext(ctx),
+          actor,
+        );
+        if (limited !== undefined) return limited;
+        return await ctx.runMutation(component.roadmap.attachFeedback, {
+          actor,
+          ...args,
+        });
+      },
+    }),
+
+    detachFeedbackFromRoadmap: mutationGeneric({
+      args: { entryId: v.string() },
+      returns: nullReturns,
+      handler: async (ctx, args) => {
+        const actor = await requireAdminActor(ctx);
+        const limited = await applyAdminEditLimit(
+          asRateLimitContext(ctx),
+          actor,
+        );
+        if (limited !== undefined) return limited;
+        return await ctx.runMutation(component.roadmap.detachFeedback, {
+          actor,
+          ...args,
+        });
+      },
+    }),
+
+    listRoadmapFeedback: queryGeneric({
+      args: {
+        paginationOpts: paginationOptsValidator,
+        roadmapId: v.string(),
+      },
+      returns: paginationResultValidator(publicEntryValidator),
+      handler: async (ctx, args) => {
+        const actor = await options.actor(ctx);
+        return await ctx.runQuery(component.roadmap.listFeedback, {
+          ...args,
+          paginationOpts: clampPagination(
+            args.paginationOpts,
+            config.entries.maxPageSize,
+          ),
+          ...(actor === null ? {} : { viewerActorId: actor.id }),
+        });
+      },
+    }),
   } satisfies Record<keyof FeedbackPublicApi, unknown>;
 }