convex-feedback 0.1.2 → 0.1.4

package/src/component/entries.ts

@@ -14,12 +14,14 @@ import {
   normalizeRequiredText,
   normalizeTitle,
   serializeEntry,
+  validateFeedbackMetadata,
 } from "./helpers.js";
 import {
   actorValidator,
   entryKindValidator,
   entrySortValidator,
   entryStatusValidator,
+  feedbackMetadataValidator,
   publicEntryValidator,
   similarEntriesValidator,
   type EntryKind,
@@ -200,13 +202,19 @@ export const get = query({
   args: {
     entryId: v.id("entries"),
     viewerActorId: v.optional(v.string()),
+    viewerIsModerator: v.optional(v.boolean()),
   },
   returns: v.union(publicEntryValidator, v.null()),
   handler: async (ctx, args) => {
     const entry = await ctx.db.get("entries", args.entryId);
     return entry === null
       ? null
-      : serializeEntry(ctx, entry, args.viewerActorId);
+      : serializeEntry(
+          ctx,
+          entry,
+          args.viewerActorId,
+          args.viewerIsModerator === true,
+        );
   },
 });
 
@@ -424,6 +432,7 @@ export const create = mutation({
     enabledKinds: v.array(entryKindValidator),
     maxTitleLength: v.number(),
     maxBodyLength: v.number(),
+    metadata: v.optional(feedbackMetadataValidator),
   },
   returns: v.id("entries"),
   handler: async (ctx, args) => {
@@ -438,6 +447,7 @@ export const create = mutation({
       args.maxTitleLength,
     );
     const body = normalizeRequiredText(args.body, "Body", args.maxBodyLength);
+    validateFeedbackMetadata(args.metadata);
 
     const entry = await ctx.db.insert("entries", {
       actorId: args.actorId,
@@ -449,6 +459,7 @@ export const create = mutation({
       searchText: `${title}\n${body}`,
       upvoteCount: 1,
       commentCount: 0,
+      ...(args.metadata === undefined ? {} : { metadata: args.metadata }),
     });
 
     await ctx.db.insert("reactions", {

package/src/component/helpers.ts

@@ -4,6 +4,72 @@ import type { DataModel } from "./_generated/dataModel.js";
 import type { QueryCtx } from "./types.js";
 import type { FeedbackComment, FeedbackEntry } from "./model.js";
 
+const metadataMaximumKeysPerSection = 32;
+const metadataMaximumKeyLength = 64;
+const metadataMaximumStringLength = 1_024;
+const metadataMaximumEncodedBytes = 16 * 1_024;
+const forbiddenMetadataKeys = new Set([
+  "__proto__",
+  "constructor",
+  "prototype",
+]);
+
+export function validateFeedbackMetadata(
+  metadata: DataModel["entries"]["document"]["metadata"],
+): void {
+  if (metadata === undefined) return;
+
+  for (const [sectionName, section] of Object.entries(metadata)) {
+    if (section === undefined) continue;
+    const entries = Object.entries(section);
+
+    if (entries.length > metadataMaximumKeysPerSection) {
+      throw new ConvexError(
+        `Metadata section '${sectionName}' must contain ${metadataMaximumKeysPerSection} keys or fewer.`,
+      );
+    }
+
+    for (const [key, value] of entries) {
+      if (key.length === 0) {
+        throw new ConvexError(
+          `Metadata section '${sectionName}' contains an empty key.`,
+        );
+      }
+      if (key.length > metadataMaximumKeyLength) {
+        throw new ConvexError(
+          `Metadata key '${key}' in section '${sectionName}' must be ${metadataMaximumKeyLength} characters or fewer.`,
+        );
+      }
+      if (
+        key.startsWith("_") ||
+        key.startsWith("$") ||
+        forbiddenMetadataKeys.has(key)
+      ) {
+        throw new ConvexError(
+          `Metadata key '${key}' in section '${sectionName}' is reserved and cannot be used.`,
+        );
+      }
+      if (
+        typeof value === "string" &&
+        value.length > metadataMaximumStringLength
+      ) {
+        throw new ConvexError(
+          `Metadata value for '${sectionName}.${key}' must be ${metadataMaximumStringLength} characters or fewer.`,
+        );
+      }
+    }
+  }
+
+  const encodedBytes = new TextEncoder().encode(
+    JSON.stringify(metadata),
+  ).length;
+  if (encodedBytes > metadataMaximumEncodedBytes) {
+    throw new ConvexError(
+      `Metadata must be ${metadataMaximumEncodedBytes} UTF-8 bytes or fewer; received ${encodedBytes} bytes.`,
+    );
+  }
+}
+
 export function normalizeTitle(value: string): string {
   return value.trim().replace(/\s+/g, " ").toLocaleLowerCase("en-US");
 }
@@ -41,6 +107,7 @@ export async function serializeEntry(
   ctx: QueryCtx,
   entry: DataModel["entries"]["document"],
   viewerActorId: string | undefined,
+  includeMetadata = false,
 ): Promise<FeedbackEntry> {
   const reaction =
     viewerActorId !== undefined
@@ -64,6 +131,9 @@ export async function serializeEntry(
     commentCount: entry.commentCount,
     ...(entry.updatedAt === undefined ? {} : { updatedAt: entry.updatedAt }),
     viewerHasUpvoted: reaction !== null,
+    ...(includeMetadata && entry.metadata !== undefined
+      ? { metadata: entry.metadata }
+      : {}),
   };
 }
 

package/src/component/model.ts

@@ -32,6 +32,22 @@ export const actorValidator = v.object({
   isModerator: v.boolean(),
 });
 
+export const feedbackMetadataValueValidator = v.union(
+  v.string(),
+  v.number(),
+  v.boolean(),
+);
+
+export const feedbackMetadataRecordValidator = v.record(
+  v.string(),
+  feedbackMetadataValueValidator,
+);
+
+export const feedbackMetadataValidator = v.object({
+  standard: v.optional(feedbackMetadataRecordValidator),
+  additional: v.optional(feedbackMetadataRecordValidator),
+});
+
 export const publicEntryValidator = v.object({
   id: v.string(),
   creationTime: v.number(),
@@ -44,6 +60,7 @@ export const publicEntryValidator = v.object({
   commentCount: v.number(),
   updatedAt: v.optional(v.number()),
   viewerHasUpvoted: v.boolean(),
+  metadata: v.optional(feedbackMetadataValidator),
 });
 
 export const publicCommentValidator = v.object({
@@ -119,6 +136,14 @@ export type CommentSort = Infer<typeof commentSortValidator>;
  */
 export type FeedbackActor = Infer<typeof actorValidator>;
 
+/** Scalar value accepted in entry diagnostic metadata. */
+export type FeedbackMetadataValue = Infer<
+  typeof feedbackMetadataValueValidator
+>;
+
+/** Flat metadata values grouped by their source. */
+export type FeedbackMetadata = Infer<typeof feedbackMetadataValidator>;
+
 /**
  * Public representation of a feedback, feature-request, or bug-report entry.
  *
@@ -157,6 +182,11 @@ export type FeedbackActor = Infer<typeof actorValidator>;
  * @property viewerHasUpvoted
  * Whether the actor associated with the current query has upvoted the entry.
  * `false` when no viewer actor is available.
+ *
+ * @property metadata
+ * Creation-time diagnostic metadata. Present only when `getEntry` is queried
+ * by a moderator. Ordinary entry lists, searches, and non-moderator reads omit
+ * this property.
  */
 export type FeedbackEntry = Infer<typeof publicEntryValidator>;
 

package/src/component/schema.ts

@@ -1,7 +1,11 @@
 import { defineSchema, defineTable } from "convex/server";
 import { v } from "convex/values";
 
-import { entryKindValidator, entryStatusValidator } from "./model.js";
+import {
+  entryKindValidator,
+  entryStatusValidator,
+  feedbackMetadataValidator,
+} from "./model.js";
 
 const schema = defineSchema({
   entries: defineTable({
@@ -15,6 +19,7 @@ const schema = defineSchema({
     upvoteCount: v.number(),
     commentCount: v.number(),
     updatedAt: v.optional(v.number()),
+    metadata: v.optional(feedbackMetadataValidator),
   })
     .index("by_kind", ["kind"])
     .index("by_status", ["status"])

package/src/react/index.ts

@@ -186,7 +186,7 @@ function positivePageSize(value: number | undefined, fallback: number): number {
  * @typeParam RateLimitResult The validated non-throwing rate-limit rejection
  * type returned by mutation hooks. It is inferred from the supplied API.
  */
-export function createFeedbackHooks<RateLimitResult = never>(
+function createFeedbackHooksImplementation<RateLimitResult>(
   api: FeedbackPublicApi<string | undefined, RateLimitResult>,
   options: FeedbackHooksOptions = {},
 ) {
@@ -334,6 +334,29 @@ export function createFeedbackHooks<RateLimitResult = never>(
   };
 }
 
+type CreatedFeedbackHooks<RateLimitResult> = ReturnType<
+  typeof createFeedbackHooksImplementation<RateLimitResult>
+>;
+
+/** Creates hooks for a feedback API whose rate limiters reject by throwing. */
+export function createFeedbackHooks(
+  api: FeedbackPublicApi<string | undefined, never>,
+  options?: FeedbackHooksOptions,
+): CreatedFeedbackHooks<never>;
+
+/** Creates hooks carrying a validated non-throwing rate-limit result. */
+export function createFeedbackHooks<RateLimitResult>(
+  api: FeedbackPublicApi<string | undefined, RateLimitResult>,
+  options?: FeedbackHooksOptions,
+): CreatedFeedbackHooks<RateLimitResult>;
+
+export function createFeedbackHooks<RateLimitResult>(
+  api: FeedbackPublicApi<string | undefined, RateLimitResult>,
+  options: FeedbackHooksOptions = {},
+): CreatedFeedbackHooks<RateLimitResult> {
+  return createFeedbackHooksImplementation(api, options);
+}
+
 /**
  * Hook collection returned by `createFeedbackHooks`.
  *
@@ -343,6 +366,5 @@ export function createFeedbackHooks<RateLimitResult = never>(
  * @typeParam RateLimitResult The validated non-throwing rate-limit rejection
  * type returned by mutation hooks.
  */
-export type FeedbackHooks<RateLimitResult = never> = ReturnType<
-  typeof createFeedbackHooks<RateLimitResult>
->;
+export type FeedbackHooks<RateLimitResult = never> =
+  CreatedFeedbackHooks<RateLimitResult>;