@hamzasaleemorg/convex-comments 1.0.0

package/dist/client/index.d.ts

@@ -0,0 +1,745 @@
+/**
+ * Comments Component - Client Library
+ *
+ * This module provides a class-based client for interacting with the
+ * comments component, plus helper functions for re-exporting APIs.
+ */
+import type { Auth, GenericDataModel, GenericMutationCtx, GenericQueryCtx, HttpRouter } from "convex/server";
+import type { ComponentApi } from "../component/_generated/component.js";
+/** Minimal context types for flexibility */
+type QueryCtx = Pick<GenericQueryCtx<GenericDataModel>, "runQuery">;
+type MutationCtx = Pick<GenericMutationCtx<GenericDataModel>, "runQuery" | "runMutation">;
+/** Authentication operation types */
+type AuthOperation = {
+    type: "read";
+    zoneId?: string;
+    threadId?: string;
+} | {
+    type: "create";
+    zoneId?: string;
+    threadId?: string;
+} | {
+    type: "update";
+    messageId?: string;
+    threadId?: string;
+} | {
+    type: "delete";
+    messageId?: string;
+    threadId?: string;
+} | {
+    type: "react";
+    messageId?: string;
+};
+/** Authentication callback that returns the user ID or throws */
+type AuthCallback = (ctx: {
+    auth: Auth;
+}, operation: AuthOperation) => Promise<string>;
+/** Attachment metadata */
+interface Attachment {
+    type: "url" | "file" | "image";
+    url: string;
+    name?: string;
+    mimeType?: string;
+    size?: number;
+}
+/** Mention callbacks */
+interface MentionCallbacks {
+    /** Called when a new message is created */
+    onNewMessage?: (params: {
+        messageId: string;
+        threadId: string;
+        authorId: string;
+        body: string;
+        mentions: Array<{
+            userId: string;
+            start: number;
+            end: number;
+        }>;
+    }) => Promise<void>;
+    /** Called for each mention in a message */
+    onMention?: (params: {
+        messageId: string;
+        mentionedUserId: string;
+        authorId: string;
+        body: string;
+    }) => Promise<void>;
+}
+/**
+ * Class-based client for the Comments component.
+ *
+ * Usage:
+ * ```ts
+ * import { Comments } from "@your-org/comments";
+ * import { components } from "./_generated/api";
+ *
+ * const comments = new Comments(components.comments);
+ *
+ * // In a mutation/query handler:
+ * const zoneId = await comments.getOrCreateZone(ctx, { entityId: "doc_123" });
+ * const threads = await comments.getThreads(ctx, { zoneId });
+ * ```
+ */
+export declare class Comments {
+    readonly component: ComponentApi;
+    private readonly callbacks?;
+    constructor(component: ComponentApi, callbacks?: MentionCallbacks | undefined);
+    /**
+     * Get or create a zone for an entity.
+     */
+    getOrCreateZone(ctx: MutationCtx, args: {
+        entityId: string;
+        metadata?: unknown;
+    }): Promise<string>;
+    /**
+     * Get a zone by entity ID (without creating).
+     */
+    getZone(ctx: QueryCtx, args: {
+        entityId: string;
+    }): Promise<{
+        _creationTime: number;
+        _id: string;
+        createdAt: number;
+        entityId: string;
+        metadata?: any;
+    } | null>;
+    /**
+     * Get a zone by its ID.
+     */
+    getZoneById(ctx: QueryCtx, args: {
+        zoneId: string;
+    }): Promise<{
+        _creationTime: number;
+        _id: string;
+        createdAt: number;
+        entityId: string;
+        metadata?: any;
+    } | null>;
+    /**
+     * Delete a zone and all its contents.
+     */
+    deleteZone(ctx: MutationCtx, args: {
+        zoneId: string;
+    }): Promise<{
+        deletedMessages: number;
+        deletedReactions: number;
+        deletedThreads: number;
+    }>;
+    /**
+     * Create a new thread in a zone.
+     */
+    addThread(ctx: MutationCtx, args: {
+        zoneId: string;
+        position?: {
+            x: number;
+            y: number;
+            anchor?: string;
+        };
+        metadata?: unknown;
+    }): Promise<string>;
+    /**
+     * Get a thread by ID.
+     */
+    getThread(ctx: QueryCtx, args: {
+        threadId: string;
+    }): Promise<{
+        _creationTime: number;
+        _id: string;
+        createdAt: number;
+        lastActivityAt: number;
+        metadata?: any;
+        position?: {
+            anchor?: string;
+            x: number;
+            y: number;
+        };
+        resolved: boolean;
+        resolvedAt?: number;
+        resolvedBy?: string;
+        zoneId: string;
+    } | null>;
+    /**
+     * Get all threads in a zone with pagination.
+     */
+    getThreads(ctx: QueryCtx, args: {
+        zoneId: string;
+        limit?: number;
+        includeResolved?: boolean;
+        cursor?: string;
+    }): Promise<{
+        hasMore: boolean;
+        nextCursor?: string;
+        threads: Array<{
+            firstMessage: null | {
+                _id: string;
+                authorId: string;
+                body: string;
+                createdAt: number;
+            };
+            messageCount: number;
+            thread: {
+                _creationTime: number;
+                _id: string;
+                createdAt: number;
+                lastActivityAt: number;
+                metadata?: any;
+                position?: {
+                    anchor?: string;
+                    x: number;
+                    y: number;
+                };
+                resolved: boolean;
+                resolvedAt?: number;
+                resolvedBy?: string;
+                zoneId: string;
+            };
+        }>;
+    }>;
+    /**
+     * Resolve a thread.
+     */
+    resolveThread(ctx: MutationCtx, args: {
+        threadId: string;
+        userId: string;
+    }): Promise<null>;
+    /**
+     * Unresolve a thread.
+     */
+    unresolveThread(ctx: MutationCtx, args: {
+        threadId: string;
+    }): Promise<null>;
+    /**
+     * Update thread position.
+     */
+    updateThreadPosition(ctx: MutationCtx, args: {
+        threadId: string;
+        position?: {
+            x: number;
+            y: number;
+            anchor?: string;
+        };
+    }): Promise<null>;
+    /**
+     * Delete a thread and all its messages.
+     */
+    deleteThread(ctx: MutationCtx, args: {
+        threadId: string;
+    }): Promise<{
+        deletedMessages: number;
+        deletedReactions: number;
+    }>;
+    /**
+     * Add a comment to a thread.
+     * Returns the message ID and parsed mentions/links.
+     */
+    addComment(ctx: MutationCtx, args: {
+        threadId: string;
+        authorId: string;
+        body: string;
+        attachments?: Attachment[];
+    }): Promise<{
+        links: Array<{
+            end: number;
+            start: number;
+            url: string;
+        }>;
+        mentions: Array<{
+            end: number;
+            start: number;
+            userId: string;
+        }>;
+        messageId: string;
+    }>;
+    /**
+     * Get a single message with reactions.
+     */
+    getMessage(ctx: QueryCtx, args: {
+        messageId: string;
+        currentUserId?: string;
+    }): Promise<{
+        message: {
+            _creationTime: number;
+            _id: string;
+            attachments: Array<{
+                mimeType?: string;
+                name?: string;
+                size?: number;
+                type: "url" | "file" | "image";
+                url: string;
+            }>;
+            authorId: string;
+            body: string;
+            createdAt: number;
+            editedAt?: number;
+            isDeleted: boolean;
+            isEdited: boolean;
+            links: Array<{
+                end: number;
+                start: number;
+                url: string;
+            }>;
+            mentions: Array<{
+                end: number;
+                start: number;
+                userId: string;
+            }>;
+            resolved?: boolean;
+            resolvedAt?: number;
+            resolvedBy?: string;
+            threadId: string;
+        };
+        reactions: Array<{
+            count: number;
+            emoji: string;
+            includesMe: boolean;
+            users: Array<string>;
+        }>;
+    } | null>;
+    /**
+     * Get messages in a thread with pagination.
+     */
+    getMessages(ctx: QueryCtx, args: {
+        threadId: string;
+        limit?: number;
+        cursor?: string;
+        order?: "asc" | "desc";
+        currentUserId?: string;
+        includeDeleted?: boolean;
+    }): Promise<{
+        hasMore: boolean;
+        messages: Array<{
+            message: {
+                _creationTime: number;
+                _id: string;
+                attachments: Array<{
+                    mimeType?: string;
+                    name?: string;
+                    size?: number;
+                    type: "url" | "file" | "image";
+                    url: string;
+                }>;
+                authorId: string;
+                body: string;
+                createdAt: number;
+                editedAt?: number;
+                isDeleted: boolean;
+                isEdited: boolean;
+                links: Array<{
+                    end: number;
+                    start: number;
+                    url: string;
+                }>;
+                mentions: Array<{
+                    end: number;
+                    start: number;
+                    userId: string;
+                }>;
+                resolved?: boolean;
+                resolvedAt?: number;
+                resolvedBy?: string;
+                threadId: string;
+            };
+            reactions: Array<{
+                count: number;
+                emoji: string;
+                includesMe: boolean;
+                users: Array<string>;
+            }>;
+        }>;
+        nextCursor?: string;
+    }>;
+    /**
+     * Edit a message.
+     */
+    editMessage(ctx: MutationCtx, args: {
+        messageId: string;
+        body: string;
+        authorId?: string;
+    }): Promise<{
+        links: Array<{
+            end: number;
+            start: number;
+            url: string;
+        }>;
+        mentions: Array<{
+            end: number;
+            start: number;
+            userId: string;
+        }>;
+    }>;
+    /**
+     * Soft delete a message.
+     */
+    deleteMessage(ctx: MutationCtx, args: {
+        messageId: string;
+        authorId?: string;
+    }): Promise<null>;
+    /**
+     * Add a reaction to a message.
+     */
+    addReaction(ctx: MutationCtx, args: {
+        messageId: string;
+        userId: string;
+        emoji: string;
+    }): Promise<string | null>;
+    /**
+     * Remove a reaction from a message.
+     */
+    removeReaction(ctx: MutationCtx, args: {
+        messageId: string;
+        userId: string;
+        emoji: string;
+    }): Promise<boolean>;
+    /**
+     * Toggle a reaction (add if not present, remove if present).
+     */
+    toggleReaction(ctx: MutationCtx, args: {
+        messageId: string;
+        userId: string;
+        emoji: string;
+    }): Promise<{
+        added: boolean;
+        reactionId?: string;
+    }>;
+    /**
+     * Get all reactions for a message.
+     */
+    getReactions(ctx: QueryCtx, args: {
+        messageId: string;
+        currentUserId?: string;
+    }): Promise<{
+        count: number;
+        emoji: string;
+        includesMe: boolean;
+        users: Array<string>;
+    }[]>;
+    /**
+     * Set typing indicator for a user in a thread.
+     */
+    setIsTyping(ctx: MutationCtx, args: {
+        threadId: string;
+        userId: string;
+        isTyping: boolean;
+    }): Promise<null>;
+    /**
+     * Get all users currently typing in a thread.
+     */
+    getTypingUsers(ctx: QueryCtx, args: {
+        threadId: string;
+        excludeUserId?: string;
+    }): Promise<{
+        updatedAt: number;
+        userId: string;
+    }[]>;
+    /**
+     * Clear all typing indicators for a user.
+     */
+    clearUserTyping(ctx: MutationCtx, args: {
+        userId: string;
+    }): Promise<number>;
+    /**
+     * Resolve a message.
+     */
+    resolveMessage(ctx: MutationCtx, args: {
+        messageId: string;
+        userId: string;
+    }): Promise<null>;
+    /**
+     * Unresolve a message.
+     */
+    unresolveMessage(ctx: MutationCtx, args: {
+        messageId: string;
+    }): Promise<null>;
+}
+/**
+ * Create a re-exportable API for the Comments component.
+ *
+ * This allows apps to expose comments functionality directly to React clients
+ * with authentication. The auth callback is called before each operation.
+ *
+ * Usage:
+ * ```ts
+ * // In convex/comments.ts
+ * import { exposeApi } from "@your-org/comments";
+ * import { components } from "./_generated/api";
+ *
+ * export const { getThreads, addComment, toggleReaction } = exposeApi(
+ *   components.comments,
+ *   {
+ *     auth: async (ctx, operation) => {
+ *       const userId = await getAuthUserId(ctx);
+ *       if (!userId && operation.type !== "read") {
+ *         throw new Error("Authentication required");
+ *       }
+ *       return userId ?? "anonymous";
+ *     },
+ *   }
+ * );
+ * ```
+ */
+export declare function exposeApi(component: ComponentApi, options: {
+    /** Authentication callback - must return user ID or throw */
+    auth: AuthCallback;
+    /** Optional notification callbacks */
+    callbacks?: MentionCallbacks;
+}): {
+    getOrCreateZone: import("convex/server").RegisteredMutation<"public", {
+        metadata?: any;
+        entityId: string;
+    }, Promise<string>>;
+    getZone: import("convex/server").RegisteredQuery<"public", {
+        entityId: string;
+    }, Promise<{
+        _creationTime: number;
+        _id: string;
+        createdAt: number;
+        entityId: string;
+        metadata?: any;
+    } | null>>;
+    addThread: import("convex/server").RegisteredMutation<"public", {
+        metadata?: any;
+        position?: {
+            anchor?: string | undefined;
+            x: number;
+            y: number;
+        } | undefined;
+        zoneId: string;
+    }, Promise<string>>;
+    getThread: import("convex/server").RegisteredQuery<"public", {
+        threadId: string;
+    }, Promise<{
+        _creationTime: number;
+        _id: string;
+        createdAt: number;
+        lastActivityAt: number;
+        metadata?: any;
+        position?: {
+            anchor?: string;
+            x: number;
+            y: number;
+        };
+        resolved: boolean;
+        resolvedAt?: number;
+        resolvedBy?: string;
+        zoneId: string;
+    } | null>>;
+    getThreads: import("convex/server").RegisteredQuery<"public", {
+        cursor?: string | undefined;
+        limit?: number | undefined;
+        includeResolved?: boolean | undefined;
+        zoneId: string;
+    }, Promise<{
+        hasMore: boolean;
+        nextCursor?: string;
+        threads: Array<{
+            firstMessage: null | {
+                _id: string;
+                authorId: string;
+                body: string;
+                createdAt: number;
+            };
+            messageCount: number;
+            thread: {
+                _creationTime: number;
+                _id: string;
+                createdAt: number;
+                lastActivityAt: number;
+                metadata?: any;
+                position?: {
+                    anchor?: string;
+                    x: number;
+                    y: number;
+                };
+                resolved: boolean;
+                resolvedAt?: number;
+                resolvedBy?: string;
+                zoneId: string;
+            };
+        }>;
+    }>>;
+    resolveThread: import("convex/server").RegisteredMutation<"public", {
+        threadId: string;
+    }, Promise<null>>;
+    unresolveThread: import("convex/server").RegisteredMutation<"public", {
+        threadId: string;
+    }, Promise<null>>;
+    addComment: import("convex/server").RegisteredMutation<"public", {
+        attachments?: {
+            name?: string | undefined;
+            mimeType?: string | undefined;
+            size?: number | undefined;
+            url: string;
+            type: "url" | "file" | "image";
+        }[] | undefined;
+        body: string;
+        threadId: string;
+    }, Promise<{
+        links: Array<{
+            end: number;
+            start: number;
+            url: string;
+        }>;
+        mentions: Array<{
+            end: number;
+            start: number;
+            userId: string;
+        }>;
+        messageId: string;
+    }>>;
+    getMessage: import("convex/server").RegisteredQuery<"public", {
+        messageId: string;
+    }, Promise<{
+        message: {
+            _creationTime: number;
+            _id: string;
+            attachments: Array<{
+                mimeType?: string;
+                name?: string;
+                size?: number;
+                type: "url" | "file" | "image";
+                url: string;
+            }>;
+            authorId: string;
+            body: string;
+            createdAt: number;
+            editedAt?: number;
+            isDeleted: boolean;
+            isEdited: boolean;
+            links: Array<{
+                end: number;
+                start: number;
+                url: string;
+            }>;
+            mentions: Array<{
+                end: number;
+                start: number;
+                userId: string;
+            }>;
+            resolved?: boolean;
+            resolvedAt?: number;
+            resolvedBy?: string;
+            threadId: string;
+        };
+        reactions: Array<{
+            count: number;
+            emoji: string;
+            includesMe: boolean;
+            users: Array<string>;
+        }>;
+    } | null>>;
+    getMessages: import("convex/server").RegisteredQuery<"public", {
+        cursor?: string | undefined;
+        includeDeleted?: boolean | undefined;
+        limit?: number | undefined;
+        order?: "asc" | "desc" | undefined;
+        threadId: string;
+    }, Promise<{
+        hasMore: boolean;
+        messages: Array<{
+            message: {
+                _creationTime: number;
+                _id: string;
+                attachments: Array<{
+                    mimeType?: string;
+                    name?: string;
+                    size?: number;
+                    type: "url" | "file" | "image";
+                    url: string;
+                }>;
+                authorId: string;
+                body: string;
+                createdAt: number;
+                editedAt?: number;
+                isDeleted: boolean;
+                isEdited: boolean;
+                links: Array<{
+                    end: number;
+                    start: number;
+                    url: string;
+                }>;
+                mentions: Array<{
+                    end: number;
+                    start: number;
+                    userId: string;
+                }>;
+                resolved?: boolean;
+                resolvedAt?: number;
+                resolvedBy?: string;
+                threadId: string;
+            };
+            reactions: Array<{
+                count: number;
+                emoji: string;
+                includesMe: boolean;
+                users: Array<string>;
+            }>;
+        }>;
+        nextCursor?: string;
+    }>>;
+    editMessage: import("convex/server").RegisteredMutation<"public", {
+        body: string;
+        messageId: string;
+    }, Promise<{
+        links: Array<{
+            end: number;
+            start: number;
+            url: string;
+        }>;
+        mentions: Array<{
+            end: number;
+            start: number;
+            userId: string;
+        }>;
+    }>>;
+    deleteMessage: import("convex/server").RegisteredMutation<"public", {
+        messageId: string;
+    }, Promise<null>>;
+    toggleReaction: import("convex/server").RegisteredMutation<"public", {
+        emoji: string;
+        messageId: string;
+    }, Promise<{
+        added: boolean;
+        reactionId?: string;
+    }>>;
+    getReactions: import("convex/server").RegisteredQuery<"public", {
+        messageId: string;
+    }, Promise<{
+        count: number;
+        emoji: string;
+        includesMe: boolean;
+        users: Array<string>;
+    }[]>>;
+    setIsTyping: import("convex/server").RegisteredMutation<"public", {
+        threadId: string;
+        isTyping: boolean;
+    }, Promise<null>>;
+    getTypingUsers: import("convex/server").RegisteredQuery<"public", {
+        threadId: string;
+    }, Promise<{
+        updatedAt: number;
+        userId: string;
+    }[]>>;
+};
+/**
+ * Register HTTP routes for the Comments component.
+ *
+ * Provides REST-like endpoints for the comments API:
+ * - GET /comments/zones/:entityId - Get zone by entity ID
+ * - GET /comments/threads/:zoneId - Get threads in a zone
+ * - GET /comments/messages/:threadId - Get messages in a thread
+ *
+ * Usage:
+ * ```ts
+ * // In convex/http.ts
+ * import { registerRoutes } from "@your-org/comments";
+ * import { components } from "./_generated/api";
+ *
+ * const http = httpRouter();
+ * registerRoutes(http, components.comments, { pathPrefix: "/api/comments" });
+ * export default http;
+ * ```
+ */
+export declare function registerRoutes(http: HttpRouter, component: ComponentApi, options?: {
+    pathPrefix?: string;
+}): void;
+export default Comments;
+//# sourceMappingURL=index.d.ts.map