convex-feedback 0.1.0

package/src/client/README.md

@@ -0,0 +1,11 @@
+# Host client layer
+
+This layer is the supported server-side integration boundary between a host Convex app and the component.
+
+- Construct the client with `createFeedback(...)` and the generated component reference.
+- Resolve authentication and moderation in the host app. Components do not own host authentication.
+- Keep `actor.id` stable. It is the identity used for authorship, entry upvotes, and comment likes.
+- Configuration is static code configuration; there is no configuration table.
+- Call the returned methods from host queries/mutations instead of exposing component internals directly.
+
+Do not add user/profile persistence here. Display profiles belong to the host application.

package/src/client/api.ts

@@ -0,0 +1,126 @@
+import type {
+  FunctionReference,
+  PaginationOptions,
+  PaginationResult,
+} from "convex/server";
+
+import type {
+  CommentSort,
+  EntryKind,
+  EntrySort,
+  EntryStatus,
+  FeedbackComment,
+  FeedbackEntry,
+  SimilarEntriesResult,
+} from "../component/model.js";
+
+export interface FeedbackPublicApi<
+  Name extends string | undefined = string | undefined,
+> {
+  listEntries: FunctionReference<
+    "query",
+    "public",
+    {
+      paginationOpts: PaginationOptions;
+      kind?: EntryKind;
+      status?: EntryStatus;
+      sort?: EntrySort;
+    },
+    PaginationResult<FeedbackEntry>,
+    Name
+  >;
+  getEntry: FunctionReference<
+    "query",
+    "public",
+    { entryId: string },
+    FeedbackEntry | null,
+    Name
+  >;
+  searchEntries: FunctionReference<
+    "query",
+    "public",
+    {
+      searchQuery: string;
+      kind?: EntryKind;
+      status?: EntryStatus;
+      limit?: number;
+    },
+    FeedbackEntry[],
+    Name
+  >;
+  findSimilarEntries: FunctionReference<
+    "query",
+    "public",
+    { title: string; body: string; kind?: EntryKind; limit?: number },
+    SimilarEntriesResult,
+    Name
+  >;
+  createEntry: FunctionReference<
+    "mutation",
+    "public",
+    { kind: EntryKind; title: string; body: string },
+    string,
+    Name
+  >;
+  updateEntry: FunctionReference<
+    "mutation",
+    "public",
+    { entryId: string; title: string; body: string },
+    null,
+    Name
+  >;
+  setEntryStatus: FunctionReference<
+    "mutation",
+    "public",
+    { entryId: string; status: EntryStatus },
+    null,
+    Name
+  >;
+  setEntryUpvote: FunctionReference<
+    "mutation",
+    "public",
+    { entryId: string; desiredState: boolean },
+    { active: boolean; upvoteCount: number },
+    Name
+  >;
+  listComments: FunctionReference<
+    "query",
+    "public",
+    {
+      paginationOpts: PaginationOptions;
+      entryId: string;
+      parentCommentId?: string;
+      sort?: CommentSort;
+    },
+    PaginationResult<FeedbackComment>,
+    Name
+  >;
+  createComment: FunctionReference<
+    "mutation",
+    "public",
+    { entryId: string; parentCommentId?: string; body: string },
+    string,
+    Name
+  >;
+  updateComment: FunctionReference<
+    "mutation",
+    "public",
+    { commentId: string; body: string },
+    null,
+    Name
+  >;
+  deleteComment: FunctionReference<
+    "mutation",
+    "public",
+    { commentId: string },
+    null,
+    Name
+  >;
+  setCommentLike: FunctionReference<
+    "mutation",
+    "public",
+    { commentId: string; desiredState: boolean },
+    { active: boolean; likeCount: number },
+    Name
+  >;
+}

package/src/client/config.ts

@@ -0,0 +1,80 @@
+import type {
+  CommentSort,
+  EntryKind,
+  EntrySort,
+  EntryStatus,
+} from "../component/model.js";
+
+export interface FeedbackConfig {
+  entries: {
+    enabledKinds: readonly EntryKind[];
+    defaultStatus: EntryStatus;
+    defaultSort: EntrySort;
+    maxPageSize: number;
+    editableByAuthor: boolean;
+  };
+  comments: {
+    maxDepth: number;
+    maxPageSize: number;
+    defaultSort: CommentSort;
+    editableByAuthor: boolean;
+    deletableByAuthor: boolean;
+  };
+  search: {
+    duplicateSuggestions: boolean;
+    duplicateSuggestionLimit: number;
+    defaultLimit: number;
+    maxLimit: number;
+  };
+  limits: {
+    titleLength: number;
+    bodyLength: number;
+    commentLength: number;
+  };
+}
+
+export interface FeedbackConfigOverrides {
+  entries?: Partial<FeedbackConfig["entries"]>;
+  comments?: Partial<FeedbackConfig["comments"]>;
+  search?: Partial<FeedbackConfig["search"]>;
+  limits?: Partial<FeedbackConfig["limits"]>;
+}
+
+export const defaultFeedbackConfig: FeedbackConfig = {
+  entries: {
+    enabledKinds: ["feedback", "feature_request", "bug_report"],
+    defaultStatus: "open",
+    defaultSort: "top",
+    maxPageSize: 50,
+    editableByAuthor: true,
+  },
+  comments: {
+    maxDepth: 5,
+    maxPageSize: 50,
+    defaultSort: "top",
+    editableByAuthor: true,
+    deletableByAuthor: true,
+  },
+  search: {
+    duplicateSuggestions: true,
+    duplicateSuggestionLimit: 5,
+    defaultLimit: 20,
+    maxLimit: 50,
+  },
+  limits: {
+    titleLength: 160,
+    bodyLength: 10_000,
+    commentLength: 5_000,
+  },
+};
+
+export function createFeedbackConfig(
+  overrides: FeedbackConfigOverrides = {},
+): FeedbackConfig {
+  return {
+    entries: { ...defaultFeedbackConfig.entries, ...overrides.entries },
+    comments: { ...defaultFeedbackConfig.comments, ...overrides.comments },
+    search: { ...defaultFeedbackConfig.search, ...overrides.search },
+    limits: { ...defaultFeedbackConfig.limits, ...overrides.limits },
+  };
+}

package/src/client/index.ts

@@ -0,0 +1,338 @@
+import {
+  mutationGeneric,
+  paginationOptsValidator,
+  paginationResultValidator,
+  queryGeneric,
+  type Auth,
+  type PaginationOptions,
+} from "convex/server";
+import { ConvexError, v } from "convex/values";
+
+import type { ComponentApi } from "../component/_generated/component.js";
+import {
+  commentSortValidator,
+  entryKindValidator,
+  entrySortValidator,
+  entryStatusValidator,
+  publicCommentValidator,
+  publicEntryValidator,
+  similarEntriesValidator,
+  type FeedbackActor,
+} from "../component/model.js";
+import type { FeedbackPublicApi } from "./api.js";
+import {
+  createFeedbackConfig,
+  type FeedbackConfigOverrides,
+} from "./config.js";
+
+export type {
+  CommentSort,
+  EntryKind,
+  EntrySort,
+  EntryStatus,
+  FeedbackActor,
+  FeedbackComment,
+  FeedbackEntry,
+  SimilarEntriesResult,
+} from "../component/model.js";
+export type { FeedbackPublicApi } from "./api.js";
+export {
+  createFeedbackConfig,
+  defaultFeedbackConfig,
+  type FeedbackConfig,
+  type FeedbackConfigOverrides,
+} from "./config.js";
+
+export interface FeedbackAuthContext {
+  auth: Auth;
+}
+
+export interface ExposeFeedbackOptions {
+  actor: (ctx: FeedbackAuthContext) => Promise<FeedbackActor | null>;
+  config?: FeedbackConfigOverrides;
+}
+
+function requireActor(actor: FeedbackActor | null): FeedbackActor {
+  if (actor === null) {
+    throw new ConvexError("Authentication is required.");
+  }
+  return actor;
+}
+
+function clampPositive(
+  value: number | undefined,
+  fallback: number,
+  maximum: number,
+): number {
+  const candidate = value ?? fallback;
+  if (!Number.isFinite(candidate)) return fallback;
+  return Math.max(1, Math.min(Math.floor(candidate), maximum));
+}
+
+function clampPagination(
+  paginationOpts: PaginationOptions,
+  maximum: number,
+): PaginationOptions {
+  return {
+    ...paginationOpts,
+    numItems: clampPositive(paginationOpts.numItems, maximum, maximum),
+  };
+}
+
+function actorIdFields(actor: FeedbackActor | null): {
+  viewerActorId?: string;
+} {
+  return actor === null ? {} : { viewerActorId: actor.id };
+}
+
+export function exposeFeedbackApi<Name extends string | undefined>(
+  component: ComponentApi<Name>,
+  options: ExposeFeedbackOptions,
+) {
+  const config = createFeedbackConfig(options.config);
+
+  return {
+    listEntries: queryGeneric({
+      args: {
+        paginationOpts: paginationOptsValidator,
+        kind: v.optional(entryKindValidator),
+        status: v.optional(entryStatusValidator),
+        sort: v.optional(entrySortValidator),
+      },
+      returns: paginationResultValidator(publicEntryValidator),
+      handler: async (ctx, args) => {
+        const actor = await options.actor(ctx);
+        return await ctx.runQuery(component.entries.list, {
+          paginationOpts: clampPagination(
+            args.paginationOpts,
+            config.entries.maxPageSize,
+          ),
+          ...(args.kind === undefined ? {} : { kind: args.kind }),
+          ...(args.status === undefined ? {} : { status: args.status }),
+          sort: args.sort ?? config.entries.defaultSort,
+          ...actorIdFields(actor),
+        });
+      },
+    }),
+
+    getEntry: queryGeneric({
+      args: { entryId: v.string() },
+      returns: v.union(publicEntryValidator, v.null()),
+      handler: async (ctx, args) => {
+        const actor = await options.actor(ctx);
+        return await ctx.runQuery(component.entries.get, {
+          entryId: args.entryId,
+          ...actorIdFields(actor),
+        });
+      },
+    }),
+
+    searchEntries: queryGeneric({
+      args: {
+        searchQuery: v.string(),
+        kind: v.optional(entryKindValidator),
+        status: v.optional(entryStatusValidator),
+        limit: v.optional(v.number()),
+      },
+      returns: v.array(publicEntryValidator),
+      handler: async (ctx, args) => {
+        const actor = await options.actor(ctx);
+        return await ctx.runQuery(component.entries.search, {
+          searchQuery: args.searchQuery,
+          ...(args.kind === undefined ? {} : { kind: args.kind }),
+          ...(args.status === undefined ? {} : { status: args.status }),
+          limit: clampPositive(
+            args.limit,
+            config.search.defaultLimit,
+            config.search.maxLimit,
+          ),
+          ...actorIdFields(actor),
+        });
+      },
+    }),
+
+    findSimilarEntries: queryGeneric({
+      args: {
+        title: v.string(),
+        body: v.string(),
+        kind: v.optional(entryKindValidator),
+        limit: v.optional(v.number()),
+      },
+      returns: similarEntriesValidator,
+      handler: async (ctx, args) => {
+        if (!config.search.duplicateSuggestions) {
+          return { exact: [], similar: [] };
+        }
+        const actor = await options.actor(ctx);
+        return await ctx.runQuery(component.entries.similar, {
+          title: args.title,
+          body: args.body,
+          ...(args.kind === undefined ? {} : { kind: args.kind }),
+          limit: clampPositive(
+            args.limit,
+            config.search.duplicateSuggestionLimit,
+            config.search.maxLimit,
+          ),
+          ...actorIdFields(actor),
+        });
+      },
+    }),
+
+    createEntry: mutationGeneric({
+      args: {
+        kind: entryKindValidator,
+        title: v.string(),
+        body: v.string(),
+      },
+      returns: v.string(),
+      handler: async (ctx, args) => {
+        const actor = requireActor(await options.actor(ctx));
+        return await ctx.runMutation(component.entries.create, {
+          actorId: actor.id,
+          kind: args.kind,
+          title: args.title,
+          body: args.body,
+          defaultStatus: config.entries.defaultStatus,
+          enabledKinds: [...config.entries.enabledKinds],
+          maxTitleLength: config.limits.titleLength,
+          maxBodyLength: config.limits.bodyLength,
+        });
+      },
+    }),
+
+    updateEntry: mutationGeneric({
+      args: {
+        entryId: v.string(),
+        title: v.string(),
+        body: v.string(),
+      },
+      returns: v.null(),
+      handler: async (ctx, args) => {
+        const actor = requireActor(await options.actor(ctx));
+        return await ctx.runMutation(component.entries.update, {
+          actor,
+          entryId: args.entryId,
+          title: args.title,
+          body: args.body,
+          editableByAuthor: config.entries.editableByAuthor,
+          maxTitleLength: config.limits.titleLength,
+          maxBodyLength: config.limits.bodyLength,
+        });
+      },
+    }),
+
+    setEntryStatus: mutationGeneric({
+      args: { entryId: v.string(), status: entryStatusValidator },
+      returns: v.null(),
+      handler: async (ctx, args) => {
+        const actor = requireActor(await options.actor(ctx));
+        return await ctx.runMutation(component.entries.setStatus, {
+          actor,
+          entryId: args.entryId,
+          status: args.status,
+        });
+      },
+    }),
+
+    setEntryUpvote: mutationGeneric({
+      args: { entryId: v.string(), desiredState: v.boolean() },
+      returns: v.object({ active: v.boolean(), upvoteCount: v.number() }),
+      handler: async (ctx, args) => {
+        const actor = requireActor(await options.actor(ctx));
+        return await ctx.runMutation(component.entries.setUpvote, {
+          actorId: actor.id,
+          entryId: args.entryId,
+          desiredState: args.desiredState,
+        });
+      },
+    }),
+
+    listComments: queryGeneric({
+      args: {
+        paginationOpts: paginationOptsValidator,
+        entryId: v.string(),
+        parentCommentId: v.optional(v.string()),
+        sort: v.optional(commentSortValidator),
+      },
+      returns: paginationResultValidator(publicCommentValidator),
+      handler: async (ctx, args) => {
+        const actor = await options.actor(ctx);
+        return await ctx.runQuery(component.comments.list, {
+          paginationOpts: clampPagination(
+            args.paginationOpts,
+            config.comments.maxPageSize,
+          ),
+          entryId: args.entryId,
+          ...(args.parentCommentId === undefined
+            ? {}
+            : { parentCommentId: args.parentCommentId }),
+          sort: args.sort ?? config.comments.defaultSort,
+          ...actorIdFields(actor),
+        });
+      },
+    }),
+
+    createComment: mutationGeneric({
+      args: {
+        entryId: v.string(),
+        parentCommentId: v.optional(v.string()),
+        body: v.string(),
+      },
+      returns: v.string(),
+      handler: async (ctx, args) => {
+        const actor = requireActor(await options.actor(ctx));
+        return await ctx.runMutation(component.comments.create, {
+          actorId: actor.id,
+          entryId: args.entryId,
+          ...(args.parentCommentId === undefined
+            ? {}
+            : { parentCommentId: args.parentCommentId }),
+          body: args.body,
+          maxDepth: config.comments.maxDepth,
+          maxCommentLength: config.limits.commentLength,
+        });
+      },
+    }),
+
+    updateComment: mutationGeneric({
+      args: { commentId: v.string(), body: v.string() },
+      returns: v.null(),
+      handler: async (ctx, args) => {
+        const actor = requireActor(await options.actor(ctx));
+        return await ctx.runMutation(component.comments.update, {
+          actor,
+          commentId: args.commentId,
+          body: args.body,
+          editableByAuthor: config.comments.editableByAuthor,
+          maxCommentLength: config.limits.commentLength,
+        });
+      },
+    }),
+
+    deleteComment: mutationGeneric({
+      args: { commentId: v.string() },
+      returns: v.null(),
+      handler: async (ctx, args) => {
+        const actor = requireActor(await options.actor(ctx));
+        return await ctx.runMutation(component.comments.remove, {
+          actor,
+          commentId: args.commentId,
+          deletableByAuthor: config.comments.deletableByAuthor,
+        });
+      },
+    }),
+
+    setCommentLike: mutationGeneric({
+      args: { commentId: v.string(), desiredState: v.boolean() },
+      returns: v.object({ active: v.boolean(), likeCount: v.number() }),
+      handler: async (ctx, args) => {
+        const actor = requireActor(await options.actor(ctx));
+        return await ctx.runMutation(component.comments.setLike, {
+          actorId: actor.id,
+          commentId: args.commentId,
+          desiredState: args.desiredState,
+        });
+      },
+    }),
+  } satisfies Record<keyof FeedbackPublicApi, unknown>;
+}

package/src/component/README.md

@@ -0,0 +1,13 @@
+# Component implementation
+
+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.
+- `model.ts`: reusable validators and public model types.
+- `helpers.ts`: normalization, validation, and serializers.
+- `convex.config.ts`: packaged component definition.
+- `_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.

package/src/component/_generated/api.ts

@@ -0,0 +1,58 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as comments from "../comments.js";
+import type * as entries from "../entries.js";
+import type * as helpers from "../helpers.js";
+import type * as model from "../model.js";
+import type * as types from "../types.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+import { anyApi, componentsGeneric } from "convex/server";
+
+const fullApi: ApiFromModules<{
+  comments: typeof comments;
+  entries: typeof entries;
+  helpers: typeof helpers;
+  model: typeof model;
+  types: typeof types;
+}> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+> = anyApi as any;
+
+export const components = componentsGeneric() as unknown as {};