@hamzasaleemorg/convex-comments 1.0.0

package/src/component/schema.ts

@@ -0,0 +1,169 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+/**
+ * Comments Component Schema
+ *
+ * Data model:
+ * - Zones: Container for threads, tied to an external entity (e.g., a document)
+ * - Threads: Container for messages within a zone
+ * - Messages: Individual comments with body, mentions, attachments, resolved state
+ * - Reactions: Emoji reactions on messages
+ * - TypingIndicators: Real-time typing status with auto-expiry
+ */
+
+// ============================================================================
+// Validators (exported for use in function args/returns)
+// ============================================================================
+
+/** Attachment metadata - URLs, file references, etc. */
+export const attachmentValidator = v.object({
+  type: v.union(v.literal("url"), v.literal("file"), v.literal("image")),
+  url: v.string(),
+  name: v.optional(v.string()),
+  mimeType: v.optional(v.string()),
+  size: v.optional(v.number()),
+});
+
+/** Mention extracted from message body */
+export const mentionValidator = v.object({
+  userId: v.string(),
+  /** Start position in the body text */
+  start: v.number(),
+  /** End position in the body text */
+  end: v.number(),
+});
+
+/** Link extracted from message body */
+export const linkValidator = v.object({
+  url: v.string(),
+  start: v.number(),
+  end: v.number(),
+});
+
+// ============================================================================
+// Schema Definition
+// ============================================================================
+
+export default defineSchema({
+  /**
+   * Zones - Container for threads, tied to an external entity
+   *
+   * A zone represents a commentable area (e.g., a document, a task, a post).
+   * The `entityId` is a string representation of whatever the parent app uses
+   * to identify the entity (could be a Convex ID, UUID, slug, etc.)
+   */
+  zones: defineTable({
+    /** External entity ID this zone belongs to (stored as string for flexibility) */
+    entityId: v.string(),
+    /** Optional metadata about the zone */
+    metadata: v.optional(v.any()),
+    /** Timestamp when zone was created */
+    createdAt: v.number(),
+  })
+    .index("entityId", ["entityId"]),
+
+  /**
+   * Threads - Container for messages within a zone
+   *
+   * Threads group related messages together. A zone can have multiple threads.
+   */
+  threads: defineTable({
+    /** Zone this thread belongs to */
+    zoneId: v.id("zones"),
+    /** Whether the entire thread is resolved */
+    resolved: v.boolean(),
+    /** User who resolved the thread (if resolved) */
+    resolvedBy: v.optional(v.string()),
+    /** When the thread was resolved */
+    resolvedAt: v.optional(v.number()),
+    /** Timestamp when thread was created */
+    createdAt: v.number(),
+    /** Timestamp of last activity (new message, reaction, etc.) */
+    lastActivityAt: v.number(),
+    /** Optional position data for positioned comments (e.g., x, y coordinates) */
+    position: v.optional(v.object({
+      x: v.number(),
+      y: v.number(),
+      /** Optional anchor data (e.g., element ID, text range) */
+      anchor: v.optional(v.string()),
+    })),
+    /** Optional metadata */
+    metadata: v.optional(v.any()),
+  })
+    .index("zoneId", ["zoneId"])
+    .index("zoneId_lastActivity", ["zoneId", "lastActivityAt"])
+    .index("zoneId_resolved", ["zoneId", "resolved"]),
+
+  /**
+   * Messages - Individual comments within a thread
+   */
+  messages: defineTable({
+    /** Thread this message belongs to */
+    threadId: v.id("threads"),
+    /** User who authored this message (stored as string for flexibility) */
+    authorId: v.string(),
+    /** Message body (plain text or markdown) */
+    body: v.string(),
+    /** Parsed mentions from the body */
+    mentions: v.array(mentionValidator),
+    /** Parsed links from the body */
+    links: v.array(linkValidator),
+    /** Attachments on this message */
+    attachments: v.array(attachmentValidator),
+    /** Whether this message has been edited */
+    isEdited: v.boolean(),
+    /** Whether this message is deleted (soft delete) */
+    isDeleted: v.boolean(),
+    /** Whether this message is resolved */
+    resolved: v.optional(v.boolean()),
+    /** User who resolved the message */
+    resolvedBy: v.optional(v.string()),
+    /** When the message was resolved */
+    resolvedAt: v.optional(v.number()),
+    /** Timestamp when created */
+    createdAt: v.number(),
+    /** Timestamp when last edited */
+    editedAt: v.optional(v.number()),
+  })
+    .index("threadId", ["threadId"])
+    .index("threadId_createdAt", ["threadId", "createdAt"])
+    .index("authorId", ["authorId"]),
+
+  /**
+   * Reactions - Emoji reactions on messages
+   */
+  reactions: defineTable({
+    /** Message this reaction is on */
+    messageId: v.id("messages"),
+    /** User who reacted */
+    userId: v.string(),
+    /** Emoji used (e.g., "👍", "❤️", "🎉") */
+    emoji: v.string(),
+    /** When the reaction was added */
+    createdAt: v.number(),
+  })
+    .index("messageId", ["messageId"])
+    .index("messageId_emoji", ["messageId", "emoji"])
+    .index("messageId_userId", ["messageId", "userId"])
+    .index("messageId_emoji_userId", ["messageId", "emoji", "userId"]),
+
+  /**
+   * TypingIndicators - Real-time typing status
+   *
+   * These records auto-expire after a timeout (handled by scheduled function)
+   */
+  typingIndicators: defineTable({
+    /** Thread where user is typing */
+    threadId: v.id("threads"),
+    /** User who is typing */
+    userId: v.string(),
+    /** When the typing indicator was last updated */
+    updatedAt: v.number(),
+    /** When this indicator should expire (for cleanup) */
+    expiresAt: v.number(),
+  })
+    .index("threadId", ["threadId"])
+    .index("threadId_userId", ["threadId", "userId"])
+    .index("expiresAt", ["expiresAt"]),
+});

package/src/component/threads.ts

@@ -0,0 +1,319 @@
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server.js";
+
+// ============================================================================
+// Thread Validators
+// ============================================================================
+
+const positionValidator = v.object({
+    x: v.number(),
+    y: v.number(),
+    anchor: v.optional(v.string()),
+});
+
+const threadValidator = v.object({
+    _id: v.id("threads"),
+    _creationTime: v.number(),
+    zoneId: v.id("zones"),
+    resolved: v.boolean(),
+    resolvedBy: v.optional(v.string()),
+    resolvedAt: v.optional(v.number()),
+    createdAt: v.number(),
+    lastActivityAt: v.number(),
+    position: v.optional(positionValidator),
+    metadata: v.optional(v.any()),
+});
+
+const messagePreviewValidator = v.object({
+    _id: v.id("messages"),
+    body: v.string(),
+    authorId: v.string(),
+    createdAt: v.number(),
+});
+
+const threadWithPreviewValidator = v.object({
+    thread: threadValidator,
+    firstMessage: v.union(v.null(), messagePreviewValidator),
+    messageCount: v.number(),
+});
+
+// ============================================================================
+// Thread Functions
+// ============================================================================
+
+/**
+ * Create a new thread in a zone.
+ */
+export const addThread = mutation({
+    args: {
+        zoneId: v.id("zones"),
+        position: v.optional(positionValidator),
+        metadata: v.optional(v.any()),
+    },
+    returns: v.id("threads"),
+    handler: async (ctx, args) => {
+        // Verify zone exists
+        const zone = await ctx.db.get(args.zoneId);
+        if (!zone) {
+            throw new Error(`Zone ${args.zoneId} not found`);
+        }
+
+        const now = Date.now();
+        const threadId = await ctx.db.insert("threads", {
+            zoneId: args.zoneId,
+            resolved: false,
+            createdAt: now,
+            lastActivityAt: now,
+            position: args.position,
+            metadata: args.metadata,
+        });
+
+        return threadId;
+    },
+});
+
+/**
+ * Get a thread by ID.
+ */
+export const getThread = query({
+    args: {
+        threadId: v.id("threads"),
+    },
+    returns: v.union(v.null(), threadValidator),
+    handler: async (ctx, args) => {
+        return await ctx.db.get(args.threadId);
+    },
+});
+
+/**
+ * Get all threads in a zone with optional pagination and filtering.
+ */
+export const getThreads = query({
+    args: {
+        zoneId: v.id("zones"),
+        limit: v.optional(v.number()),
+        includeResolved: v.optional(v.boolean()),
+        cursor: v.optional(v.string()),
+    },
+    returns: v.object({
+        threads: v.array(threadWithPreviewValidator),
+        nextCursor: v.optional(v.string()),
+        hasMore: v.boolean(),
+    }),
+    handler: async (ctx, args) => {
+        const limit = args.limit ?? 50;
+        const includeResolved = args.includeResolved ?? true;
+
+        // Build query
+        let query = ctx.db
+            .query("threads")
+            .withIndex("zoneId_lastActivity", (q) => q.eq("zoneId", args.zoneId))
+            .order("desc");
+
+        // Apply cursor if provided
+        if (args.cursor) {
+            // Cursor is the lastActivityAt timestamp
+            const cursorTime = parseInt(args.cursor, 10);
+            query = ctx.db
+                .query("threads")
+                .withIndex("zoneId_lastActivity", (q) =>
+                    q.eq("zoneId", args.zoneId).lt("lastActivityAt", cursorTime)
+                )
+                .order("desc");
+        }
+
+        // Fetch one extra to check if there are more
+        const threads = await query.take(limit + 1);
+
+        // Filter by resolved status if needed
+        const filteredThreads = includeResolved
+            ? threads
+            : threads.filter((t) => !t.resolved);
+
+        const hasMore = filteredThreads.length > limit;
+        const resultThreads = filteredThreads.slice(0, limit);
+
+        // Get first message preview and count for each thread
+        const threadsWithPreviews = await Promise.all(
+            resultThreads.map(async (thread) => {
+                const messages = await ctx.db
+                    .query("messages")
+                    .withIndex("threadId_createdAt", (q) => q.eq("threadId", thread._id))
+                    .order("asc")
+                    .take(1);
+
+                const firstMessage = messages[0] ?? null;
+
+                // Get message count
+                const allMessages = await ctx.db
+                    .query("messages")
+                    .withIndex("threadId", (q) => q.eq("threadId", thread._id))
+                    .collect();
+
+                const messageCount = allMessages.filter((m) => !m.isDeleted).length;
+
+                return {
+                    thread,
+                    firstMessage: firstMessage
+                        ? {
+                            _id: firstMessage._id,
+                            body: firstMessage.body,
+                            authorId: firstMessage.authorId,
+                            createdAt: firstMessage.createdAt,
+                        }
+                        : null,
+                    messageCount,
+                };
+            })
+        );
+
+        // Generate next cursor
+        const lastThread = resultThreads[resultThreads.length - 1];
+        const nextCursor = hasMore && lastThread
+            ? lastThread.lastActivityAt.toString()
+            : undefined;
+
+        return {
+            threads: threadsWithPreviews,
+            nextCursor,
+            hasMore,
+        };
+    },
+});
+
+/**
+ * Resolve a thread.
+ */
+export const resolveThread = mutation({
+    args: {
+        threadId: v.id("threads"),
+        userId: v.string(),
+    },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const thread = await ctx.db.get(args.threadId);
+        if (!thread) {
+            throw new Error(`Thread ${args.threadId} not found`);
+        }
+
+        await ctx.db.patch(args.threadId, {
+            resolved: true,
+            resolvedBy: args.userId,
+            resolvedAt: Date.now(),
+        });
+
+        return null;
+    },
+});
+
+/**
+ * Unresolve a thread.
+ */
+export const unresolveThread = mutation({
+    args: {
+        threadId: v.id("threads"),
+    },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const thread = await ctx.db.get(args.threadId);
+        if (!thread) {
+            throw new Error(`Thread ${args.threadId} not found`);
+        }
+
+        await ctx.db.patch(args.threadId, {
+            resolved: false,
+            resolvedBy: undefined,
+            resolvedAt: undefined,
+        });
+
+        return null;
+    },
+});
+
+/**
+ * Update thread position (for positioned comments).
+ */
+export const updateThreadPosition = mutation({
+    args: {
+        threadId: v.id("threads"),
+        position: v.optional(positionValidator),
+    },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        await ctx.db.patch(args.threadId, {
+            position: args.position,
+        });
+        return null;
+    },
+});
+
+/**
+ * Delete a thread and all its messages.
+ */
+export const deleteThread = mutation({
+    args: {
+        threadId: v.id("threads"),
+    },
+    returns: v.object({
+        deletedMessages: v.number(),
+        deletedReactions: v.number(),
+    }),
+    handler: async (ctx, args) => {
+        let deletedMessages = 0;
+        let deletedReactions = 0;
+
+        // Get all messages in this thread
+        const messages = await ctx.db
+            .query("messages")
+            .withIndex("threadId", (q) => q.eq("threadId", args.threadId))
+            .collect();
+
+        for (const message of messages) {
+            // Delete reactions on this message
+            const reactions = await ctx.db
+                .query("reactions")
+                .withIndex("messageId", (q) => q.eq("messageId", message._id))
+                .collect();
+
+            for (const reaction of reactions) {
+                await ctx.db.delete(reaction._id);
+                deletedReactions++;
+            }
+
+            // Delete the message
+            await ctx.db.delete(message._id);
+            deletedMessages++;
+        }
+
+        // Delete typing indicators
+        const typingIndicators = await ctx.db
+            .query("typingIndicators")
+            .withIndex("threadId", (q) => q.eq("threadId", args.threadId))
+            .collect();
+
+        for (const indicator of typingIndicators) {
+            await ctx.db.delete(indicator._id);
+        }
+
+        // Delete the thread
+        await ctx.db.delete(args.threadId);
+
+        return { deletedMessages, deletedReactions };
+    },
+});
+
+/**
+ * Internal function to update thread's lastActivityAt.
+ */
+export const updateThreadActivity = mutation({
+    args: {
+        threadId: v.id("threads"),
+    },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        await ctx.db.patch(args.threadId, {
+            lastActivityAt: Date.now(),
+        });
+        return null;
+    },
+});

package/src/component/typing.ts

@@ -0,0 +1,168 @@
+import { v } from "convex/values";
+import { mutation, query, internalMutation } from "./_generated/server.js";
+import { internal } from "./_generated/api.js";
+
+// ============================================================================
+// Typing Indicator Configuration
+// ============================================================================
+
+/** How long (in ms) before a typing indicator expires */
+const TYPING_EXPIRY_MS = 5000; // 5 seconds
+
+// ============================================================================
+// Typing Indicator Validators
+// ============================================================================
+
+const typingUserValidator = v.object({
+    userId: v.string(),
+    updatedAt: v.number(),
+});
+
+// ============================================================================
+// Typing Indicator Functions
+// ============================================================================
+
+/**
+ * Set typing indicator for a user in a thread.
+ * Automatically schedules expiry cleanup.
+ */
+export const setIsTyping = mutation({
+    args: {
+        threadId: v.id("threads"),
+        userId: v.string(),
+        isTyping: v.boolean(),
+    },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        // Verify thread exists
+        const thread = await ctx.db.get(args.threadId);
+        if (!thread) {
+            throw new Error(`Thread ${args.threadId} not found`);
+        }
+
+        const now = Date.now();
+        const expiresAt = now + TYPING_EXPIRY_MS;
+
+        // Find existing indicator
+        const existing = await ctx.db
+            .query("typingIndicators")
+            .withIndex("threadId_userId", (q) =>
+                q.eq("threadId", args.threadId).eq("userId", args.userId)
+            )
+            .first();
+
+        if (args.isTyping) {
+            if (existing) {
+                // Update existing indicator
+                await ctx.db.patch(existing._id, {
+                    updatedAt: now,
+                    expiresAt,
+                });
+            } else {
+                // Create new indicator
+                await ctx.db.insert("typingIndicators", {
+                    threadId: args.threadId,
+                    userId: args.userId,
+                    updatedAt: now,
+                    expiresAt,
+                });
+            }
+
+            // Schedule cleanup
+            await ctx.scheduler.runAfter(
+                TYPING_EXPIRY_MS + 1000, // Add a small buffer
+                internal.typing.cleanupExpiredIndicators,
+                {}
+            );
+        } else {
+            // Remove indicator if exists
+            if (existing) {
+                await ctx.db.delete(existing._id);
+            }
+        }
+
+        return null;
+    },
+});
+
+/**
+ * Get all users currently typing in a thread.
+ */
+export const getTypingUsers = query({
+    args: {
+        threadId: v.id("threads"),
+        excludeUserId: v.optional(v.string()),
+    },
+    returns: v.array(typingUserValidator),
+    handler: async (ctx, args) => {
+        const now = Date.now();
+
+        const indicators = await ctx.db
+            .query("typingIndicators")
+            .withIndex("threadId", (q) => q.eq("threadId", args.threadId))
+            .collect();
+
+        // Filter to only non-expired indicators and optionally exclude current user
+        return indicators
+            .filter((i) => {
+                if (i.expiresAt < now) return false;
+                if (args.excludeUserId && i.userId === args.excludeUserId) return false;
+                return true;
+            })
+            .map((i) => ({
+                userId: i.userId,
+                updatedAt: i.updatedAt,
+            }));
+    },
+});
+
+/**
+ * Internal function to cleanup expired typing indicators.
+ */
+export const cleanupExpiredIndicators = internalMutation({
+    args: {},
+    returns: v.number(),
+    handler: async (ctx) => {
+        const now = Date.now();
+        let deleted = 0;
+
+        // Get all expired indicators
+        const expired = await ctx.db
+            .query("typingIndicators")
+            .withIndex("expiresAt", (q) => q.lt("expiresAt", now))
+            .collect();
+
+        for (const indicator of expired) {
+            await ctx.db.delete(indicator._id);
+            deleted++;
+        }
+
+        return deleted;
+    },
+});
+
+/**
+ * Clear all typing indicators for a user across all threads.
+ * Useful when a user disconnects.
+ */
+export const clearUserTyping = mutation({
+    args: {
+        userId: v.string(),
+    },
+    returns: v.number(),
+    handler: async (ctx, args) => {
+        // We need to scan all indicators since we don't have a userId index
+        // In production, you might want to add an index on userId
+        const allIndicators = await ctx.db.query("typingIndicators").collect();
+        let deleted = 0;
+
+        for (const indicator of allIndicators) {
+            if (indicator.userId === args.userId) {
+                await ctx.db.delete(indicator._id);
+                deleted++;
+            }
+        }
+
+        return deleted;
+    },
+});