convex-feedback 0.1.3 → 0.1.4

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"])