convex-feedback 0.1.0 → 0.1.2

package/src/client/api.ts

@@ -14,113 +14,403 @@ import type {
   SimilarEntriesResult,
 } from "../component/model.js";
 
+/**
+ * Arguments for cursor-paginated entry listing.
+ */
+export type ListEntriesArgs = {
+  /**
+   * Convex cursor-pagination options.
+   *
+   * React consumers normally do not construct this directly; `useEntries`
+   * manages it through `usePaginatedQuery`.
+   */
+  paginationOpts: PaginationOptions;
+
+  /**
+   * Entry kinds to include.
+   *
+   * Filtering is performed by Convex before pagination. Omit this field to
+   * include every kind.
+   *
+   * Must contain at least one kind when provided.
+   */
+  kinds?: EntryKind[];
+
+  /** Restricts entries to this workflow status. */
+  status?: EntryStatus;
+
+  /**
+   * Server-side ordering strategy.
+   *
+   * When omitted, `config.entries.defaultSort` is used.
+   */
+  sort?: EntrySort;
+};
+
+/**
+ * Arguments for retrieving one entry.
+ */
+export type GetEntryArgs = {
+  /** Identifier returned by the component for the requested entry. */
+  entryId: string;
+};
+
+/**
+ * Arguments for full-text entry search.
+ */
+export type SearchEntriesArgs = {
+  /** Full-text query matched against the entry's indexed search text. */
+  searchQuery: string;
+
+  /**
+   * Entry kinds to include.
+   *
+   * Filtering occurs inside the Convex query rather than after results reach
+   * the client.
+   */
+  kinds?: EntryKind[];
+
+  /** Optional workflow-status restriction. */
+  status?: EntryStatus;
+
+  /**
+   * Maximum number of results to return.
+   *
+   * When omitted, `config.search.defaultLimit` is used. The server clamps the
+   * value to `config.search.maxLimit`.
+   */
+  limit?: number;
+};
+
+/**
+ * Arguments for exact/similar duplicate detection.
+ */
+export type FindSimilarEntriesArgs = {
+  /**
+   * Proposed entry title.
+   *
+   * Its normalized form is used for exact duplicate detection.
+   */
+  title: string;
+
+  /**
+   * Proposed entry body.
+   *
+   * Combined with the title for the full-text similarity search.
+   */
+  body: string;
+
+  /**
+   * Restricts duplicate detection to one entry kind.
+   *
+   * Omit to search every kind.
+   */
+  kind?: EntryKind;
+
+  /**
+   * Maximum combined number of suggestions returned.
+   *
+   * Exact normalized-title matches consume this limit first. Only remaining
+   * slots are available to full-text matches.
+   *
+   * Therefore:
+   *
+   * `result.exact.length + result.similar.length <= limit`
+   *
+   * When omitted, `config.search.duplicateSuggestionLimit` is used.
+   */
+  limit?: number;
+};
+
+/**
+ * Arguments for creating an entry.
+ */
+export type CreateEntryArgs = {
+  /** Category of entry to create. */
+  kind: EntryKind;
+
+  /** Entry title. */
+  title: string;
+
+  /** Entry description/body. */
+  body: string;
+};
+
+/**
+ * Arguments for editing an existing entry.
+ */
+export type UpdateEntryArgs = {
+  /** Entry to update. */
+  entryId: string;
+
+  /** Complete replacement title. */
+  title: string;
+
+  /** Complete replacement body. */
+  body: string;
+};
+
+/**
+ * Arguments for changing an entry workflow status.
+ */
+export type SetEntryStatusArgs = {
+  /** Entry whose status should change. */
+  entryId: string;
+
+  /** Desired workflow status. */
+  status: EntryStatus;
+};
+
+/**
+ * Arguments for setting the current actor's entry-upvote state.
+ */
+export type SetEntryUpvoteArgs = {
+  /** Entry whose upvote state should change. */
+  entryId: string;
+
+  /**
+   * Desired final state.
+   *
+   * `true` ensures the current actor has an upvote.
+   * `false` ensures the current actor does not have an upvote.
+   *
+   * This is intentionally state-setting rather than toggle semantics, making
+   * the mutation idempotent and safe to retry.
+   */
+  desiredState: boolean;
+};
+
+/**
+ * Authoritative entry-upvote state returned after a mutation.
+ */
+export type SetEntryUpvoteResult = {
+  /** Final upvote state for the current actor. */
+  active: boolean;
+
+  /** Updated total number of entry upvotes. */
+  upvoteCount: number;
+};
+
+/**
+ * Arguments for cursor-paginated comment/reply listing.
+ */
+export type ListCommentsArgs = {
+  /** Convex cursor-pagination options. */
+  paginationOpts: PaginationOptions;
+
+  /** Entry whose conversation should be queried. */
+  entryId: string;
+
+  /**
+   * Direct parent comment.
+   *
+   * Omit to query top-level comments. When supplied, only direct children of
+   * this comment are returned; deeper descendants are not loaded.
+   */
+  parentCommentId?: string;
+
+  /**
+   * Server-side comment ordering strategy.
+   *
+   * When omitted, `config.comments.defaultSort` is used.
+   */
+  sort?: CommentSort;
+};
+
+/**
+ * Arguments for creating a top-level comment or reply.
+ */
+export type CreateCommentArgs = {
+  /** Entry the comment belongs to. */
+  entryId: string;
+
+  /**
+   * Direct parent comment.
+   *
+   * Omit to create a top-level comment.
+   */
+  parentCommentId?: string;
+
+  /** Comment/reply text. */
+  body: string;
+};
+
+/**
+ * Arguments for editing a comment.
+ */
+export type UpdateCommentArgs = {
+  /** Comment to edit. */
+  commentId: string;
+
+  /** Complete replacement body. */
+  body: string;
+};
+
+/**
+ * Arguments for soft-deleting a comment.
+ */
+export type DeleteCommentArgs = {
+  /** Comment to soft-delete. */
+  commentId: string;
+};
+
+/**
+ * Arguments for setting the current actor's comment-like state.
+ */
+export type SetCommentLikeArgs = {
+  /** Comment whose like state should change. */
+  commentId: string;
+
+  /**
+   * Desired final state.
+   *
+   * `true` ensures the actor likes the comment.
+   * `false` ensures the actor does not like the comment.
+   *
+   * This is idempotent rather than toggle-based.
+   */
+  desiredState: boolean;
+};
+
+/**
+ * Authoritative comment-like state returned after a mutation.
+ */
+export type SetCommentLikeResult = {
+  /** Final like state for the current actor. */
+  active: boolean;
+
+  /** Updated total number of comment likes. */
+  likeCount: number;
+};
+
+/**
+ * Public Convex API exposed by `exposeFeedbackApi`.
+ *
+ * The host application exposes these wrappers from its own Convex deployment
+ * after resolving authentication and configuration.
+ *
+ * @typeParam RateLimitResult A validated rejection value returned by mutations
+ * when non-throwing rate limiting is configured. The default `never` preserves
+ * the original success-only mutation results.
+ */
 export interface FeedbackPublicApi<
   Name extends string | undefined = string | undefined,
+  RateLimitResult = never,
 > {
+  /** Returns a cursor-paginated entry list. */
   listEntries: FunctionReference<
     "query",
     "public",
-    {
-      paginationOpts: PaginationOptions;
-      kind?: EntryKind;
-      status?: EntryStatus;
-      sort?: EntrySort;
-    },
+    ListEntriesArgs,
     PaginationResult<FeedbackEntry>,
     Name
   >;
+
+  /** Returns one entry or `null` when it does not exist. */
   getEntry: FunctionReference<
     "query",
     "public",
-    { entryId: string },
+    GetEntryArgs,
     FeedbackEntry | null,
     Name
   >;
+
+  /** Performs full-text entry search. */
   searchEntries: FunctionReference<
     "query",
     "public",
-    {
-      searchQuery: string;
-      kind?: EntryKind;
-      status?: EntryStatus;
-      limit?: number;
-    },
+    SearchEntriesArgs,
     FeedbackEntry[],
     Name
   >;
+
+  /** Finds exact and likely duplicate entries. */
   findSimilarEntries: FunctionReference<
     "query",
     "public",
-    { title: string; body: string; kind?: EntryKind; limit?: number },
+    FindSimilarEntriesArgs,
     SimilarEntriesResult,
     Name
   >;
+
+  /** Creates an entry, returning its identifier or a rate-limit rejection. */
   createEntry: FunctionReference<
     "mutation",
     "public",
-    { kind: EntryKind; title: string; body: string },
-    string,
+    CreateEntryArgs,
+    string | RateLimitResult,
     Name
   >;
+
+  /** Replaces entry content, or returns a configured rate-limit rejection. */
   updateEntry: FunctionReference<
     "mutation",
     "public",
-    { entryId: string; title: string; body: string },
-    null,
+    UpdateEntryArgs,
+    null | RateLimitResult,
     Name
   >;
+
+  /** Changes entry status, or returns a configured rate-limit rejection. */
   setEntryStatus: FunctionReference<
     "mutation",
     "public",
-    { entryId: string; status: EntryStatus },
-    null,
+    SetEntryStatusArgs,
+    null | RateLimitResult,
     Name
   >;
+
+  /** Sets entry-upvote state, or returns a configured rate-limit rejection. */
   setEntryUpvote: FunctionReference<
     "mutation",
     "public",
-    { entryId: string; desiredState: boolean },
-    { active: boolean; upvoteCount: number },
+    SetEntryUpvoteArgs,
+    SetEntryUpvoteResult | RateLimitResult,
     Name
   >;
+
+  /** Returns one paginated level of comments or replies. */
   listComments: FunctionReference<
     "query",
     "public",
-    {
-      paginationOpts: PaginationOptions;
-      entryId: string;
-      parentCommentId?: string;
-      sort?: CommentSort;
-    },
+    ListCommentsArgs,
     PaginationResult<FeedbackComment>,
     Name
   >;
+
+  /** Creates a comment/reply, returning its ID or a rate-limit rejection. */
   createComment: FunctionReference<
     "mutation",
     "public",
-    { entryId: string; parentCommentId?: string; body: string },
-    string,
+    CreateCommentArgs,
+    string | RateLimitResult,
     Name
   >;
+
+  /** Replaces comment content, or returns a configured rate-limit rejection. */
   updateComment: FunctionReference<
     "mutation",
     "public",
-    { commentId: string; body: string },
-    null,
+    UpdateCommentArgs,
+    null | RateLimitResult,
     Name
   >;
+
+  /** Soft-deletes a comment, or returns a configured rate-limit rejection. */
   deleteComment: FunctionReference<
     "mutation",
     "public",
-    { commentId: string },
-    null,
+    DeleteCommentArgs,
+    null | RateLimitResult,
     Name
   >;
+
+  /** Sets comment-like state, or returns a configured rate-limit rejection. */
   setCommentLike: FunctionReference<
     "mutation",
     "public",
-    { commentId: string; desiredState: boolean },
-    { active: boolean; likeCount: number },
+    SetCommentLikeArgs,
+    SetCommentLikeResult | RateLimitResult,
     Name
   >;
 }

package/src/client/config.ts

@@ -5,39 +5,201 @@ import type {
   EntryStatus,
 } from "../component/model.js";
 
+/**
+ * Entry-related component configuration.
+ */
+export interface FeedbackEntriesConfig {
+  /**
+   * Entry kinds that may be created through this component instance.
+   *
+   * @default ["feedback", "feature_request", "bug_report"]
+   */
+  enabledKinds: readonly EntryKind[];
+
+  /**
+   * Status assigned to newly created entries.
+   *
+   * @default "open"
+   */
+  defaultStatus: EntryStatus;
+
+  /**
+   * Default server-side entry ordering when callers do not specify `sort`.
+   *
+   * @default "top"
+   */
+  defaultSort: EntrySort;
+
+  /**
+   * Maximum number of entries a caller may request in one pagination batch.
+   *
+   * Larger requested page sizes are clamped to this value.
+   *
+   * @default 50
+   */
+  maxPageSize: number;
+
+  /**
+   * Whether entry authors may edit their own title and body.
+   *
+   * Moderators are governed separately by the resolved actor permissions.
+   *
+   * @default true
+   */
+  editableByAuthor: boolean;
+}
+
+/**
+ * Comment and reply configuration.
+ */
+export interface FeedbackCommentsConfig {
+  /**
+   * Maximum allowed nesting depth.
+   *
+   * Top-level comments have depth `0`. Attempts to create replies deeper than
+   * this limit are rejected by the component.
+   *
+   * @default 5
+   */
+  maxDepth: number;
+
+  /**
+   * Maximum number of comments or replies that may be requested in one
+   * pagination batch.
+   *
+   * @default 50
+   */
+  maxPageSize: number;
+
+  /**
+   * Default server-side comment ordering.
+   *
+   * @default "top"
+   */
+  defaultSort: CommentSort;
+
+  /**
+   * Whether comment authors may edit their own comments.
+   *
+   * @default true
+   */
+  editableByAuthor: boolean;
+
+  /**
+   * Whether comment authors may soft-delete their own comments.
+   *
+   * Deletion preserves the document so nested replies retain their structure.
+   *
+   * @default true
+   */
+  deletableByAuthor: boolean;
+}
+
+/**
+ * Full-text search and duplicate-detection configuration.
+ */
+export interface FeedbackSearchConfig {
+  /**
+   * Whether similar/duplicate suggestions are enabled.
+   *
+   * When disabled, duplicate-search queries return empty `exact` and
+   * `similar` arrays.
+   *
+   * @default true
+   */
+  duplicateSuggestions: boolean;
+
+  /**
+   * Default combined result limit for duplicate suggestions when the caller
+   * does not provide `limit`.
+   *
+   * Exact matches consume this limit before similar matches.
+   *
+   * @default 5
+   */
+  duplicateSuggestionLimit: number;
+
+  /**
+   * Default result limit for normal full-text entry search.
+   *
+   * @default 20
+   */
+  defaultLimit: number;
+
+  /**
+   * Maximum allowed result limit for search and duplicate queries.
+   *
+   * Larger requested limits are clamped to this value.
+   *
+   * @default 50
+   */
+  maxLimit: number;
+}
+
+/**
+ * Maximum lengths accepted for user-generated content.
+ */
+export interface FeedbackContentLimits {
+  /**
+   * Maximum entry-title length.
+   *
+   * @default 160
+   */
+  titleLength: number;
+
+  /**
+   * Maximum entry-body length.
+   *
+   * @default 10000
+   */
+  bodyLength: number;
+
+  /**
+   * Maximum comment/reply length.
+   *
+   * @default 5000
+   */
+  commentLength: number;
+}
+
+/**
+ * Complete server-side configuration for a feedback component instance.
+ *
+ * Configuration is supplied by the host application and is not persisted in
+ * an additional component table.
+ */
 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;
-  };
+  /** Entry creation, ordering, pagination, and editing rules. */
+  entries: FeedbackEntriesConfig;
+
+  /** Comment nesting, ordering, pagination, and editing rules. */
+  comments: FeedbackCommentsConfig;
+
+  /** Search and duplicate-detection behavior. */
+  search: FeedbackSearchConfig;
+
+  /** User-generated content limits. */
+  limits: FeedbackContentLimits;
 }
 
+/**
+ * Partial configuration accepted by `createFeedbackConfig` and
+ * `exposeFeedbackApi`.
+ *
+ * Missing values fall back to `defaultFeedbackConfig`.
+ */
 export interface FeedbackConfigOverrides {
-  entries?: Partial<FeedbackConfig["entries"]>;
-  comments?: Partial<FeedbackConfig["comments"]>;
-  search?: Partial<FeedbackConfig["search"]>;
-  limits?: Partial<FeedbackConfig["limits"]>;
+  /** Overrides for entry configuration. */
+  entries?: Partial<FeedbackEntriesConfig>;
+
+  /** Overrides for comment configuration. */
+  comments?: Partial<FeedbackCommentsConfig>;
+
+  /** Overrides for search configuration. */
+  search?: Partial<FeedbackSearchConfig>;
+
+  /** Overrides for content limits. */
+  limits?: Partial<FeedbackContentLimits>;
 }
 
 export const defaultFeedbackConfig: FeedbackConfig = {