captify 0.1.18 → 1.1.0

package/dist/comments/comments.interfaces.d.ts

@@ -0,0 +1,960 @@
+import { ReactNode } from "react";
+import type { AttachmentStatus } from "./comments.constants";
+import type { UserAwsCredentials } from "../shared/services";
+import type { DynamoDbService } from "../shared/services/dynamodb";
+import type { CommentsTableSchema } from "../db/schemas";
+import type { NotificationsService } from "../notifications/services";
+import type { S3Service } from "../shared/services/s3";
+export type CommentEntityType = "document" | "task" | "dashboard" | "project" | "issue" | "feedback" | "custom";
+export interface CommentAttachment {
+    id: string;
+    commentId: string;
+    fileName: string;
+    fileType: string;
+    fileSize: number;
+    s3Key: string;
+    /** S3 bucket name where the file is stored */
+    bucket?: string;
+    /** Unix timestamp (milliseconds) when the file was uploaded */
+    uploadedAt: number;
+    uploadedBy: string;
+    /** Temporary signed URL for download (populated on fetch) */
+    downloadUrl?: string;
+}
+export interface AttachmentWithUrl extends CommentAttachment {
+    downloadUrl?: string;
+    isLoading?: boolean;
+    isDeleting?: boolean;
+    error?: string;
+}
+export interface CommentMention {
+    userId: string;
+    userName: string;
+    /** Position in content where mention starts */
+    startIndex: number;
+    /** Position in content where mention ends */
+    endIndex: number;
+}
+/** Arbitrary metadata associated with a comment */
+export type CommentMetadata = Record<string, unknown>;
+export interface MentionPosition {
+    /** Display name of the mentioned user */
+    name: string;
+    /** User ID of the mentioned user */
+    id: string;
+    /** Start position in raw content */
+    rawStart: number;
+    /** End position in raw content */
+    rawEnd: number;
+    /** Start position in display content */
+    displayStart: number;
+    /** End position in display content */
+    displayEnd: number;
+}
+export interface CommentAuthor {
+    id: string;
+    name: string;
+    email?: string;
+    avatarUrl?: string;
+}
+export interface Comment {
+    id: string;
+    /** Tenant identifier */
+    tenantId: string;
+    /** ID of the entity this comment belongs to (document, task, etc.) */
+    entityId: string;
+    /** Type of entity */
+    entityType: CommentEntityType;
+    /** Parent comment ID for threading (null for root comments) */
+    parentId?: string;
+    /** Comment author information */
+    author: CommentAuthor;
+    /** Comment text content */
+    content: string;
+    /** File attachments */
+    attachments: CommentAttachment[];
+    /** Users mentioned in this comment */
+    mentions: CommentMention[];
+    /** Optional metadata for custom features */
+    metadata?: CommentMetadata;
+    /** Thread depth level (0 for root comments) */
+    threadDepth: number;
+    /** Number of replies (for root comments) */
+    replyCount: number;
+    /** Unix timestamp (milliseconds) of creation */
+    createdAt: number;
+    /** Unix timestamp (milliseconds) of last update */
+    updatedAt?: number;
+    /** Whether comment has been edited */
+    isEdited: boolean;
+    /** Whether comment is deleted (soft delete) */
+    isDeleted?: boolean;
+}
+export interface CommentThread extends Comment {
+    /** Nested replies */
+    replies: CommentThread[];
+    /** Whether there are more replies to load */
+    hasMoreReplies: boolean;
+    /** Cursor for loading more replies (for pagination) */
+    repliesCursor?: string;
+}
+export interface PaginatedComments {
+    comments: Comment[];
+    /** Cursor for next page */
+    nextCursor?: string;
+    /** Whether there are more results */
+    hasMore: boolean;
+    /** Number of comments on current page */
+    count?: number;
+}
+export interface PaginatedThreadedComments {
+    comments: CommentThread[];
+    /** Cursor for next page */
+    nextCursor?: string;
+    /** Whether there are more results */
+    hasMore: boolean;
+}
+export interface ListCommentsResponse {
+    comments: CommentThread[];
+    /** Number of comments on current page */
+    count: number;
+    nextCursor?: string;
+    hasMore: boolean;
+}
+export interface PaginatedCommentsResponse {
+    comments: Comment[];
+    nextCursor?: string;
+    hasMore: boolean;
+    /** Number of comments on current page */
+    count?: number;
+}
+export interface CommentsCallbacks {
+    /** Called when a new comment is created */
+    onCommentAdded?: (comment: Comment) => void;
+    /** Called when a comment is updated */
+    onCommentEdited?: (comment: Comment) => void;
+    /** Called when a comment is deleted */
+    onCommentDeleted?: (commentId: string) => void;
+    /** Called when a user is mentioned */
+    onMentionAdded?: (userId: string, commentId: string) => void;
+    /** Called when an attachment is uploaded */
+    onAttachmentUploaded?: (attachment: CommentAttachment) => void;
+    /** Called when an attachment is deleted */
+    onAttachmentDeleted?: (attachmentId: string) => void;
+    /** Called on any error */
+    onError?: (error: Error) => void;
+}
+export interface CommentsServiceConfig {
+    /** DynamoDB table name */
+    tableName?: string;
+    /** S3 bucket for attachments (used by factory to configure S3Service) */
+    s3Bucket?: string;
+    /** Default page size for queries */
+    defaultPageSize?: number;
+    /** Enable rate limiting */
+    enableRateLimit?: boolean;
+    /** AWS region */
+    region?: string;
+}
+export interface CommentsServiceDependencies {
+    dynamoDb?: DynamoDbService<CommentsTableSchema>;
+    s3?: S3Service;
+    /** Optional notifications service for creating mention/reply notifications */
+    notifications?: NotificationsService;
+}
+export interface CommentsOperationOptions {
+    /**
+     * User-specific AWS credentials for governance compliance
+     * When provided, the operation uses these credentials instead of service account
+     * This enables IAM-based access control per user
+     */
+    userCredentials?: UserAwsCredentials;
+}
+export interface MentionableUser {
+    id: string;
+    name: string;
+    email?: string;
+    avatarUrl?: string;
+    /** User's role or title (optional) */
+    role?: string;
+}
+export interface ListCommentsRequest {
+    entityId: string;
+    entityType?: CommentEntityType;
+    limit?: number;
+    sortOrder?: "asc" | "desc";
+    cursor?: string;
+    rootOnly?: boolean;
+}
+export interface ListRepliesRequest {
+    limit?: number;
+    sortOrder?: "asc" | "desc";
+    cursor?: string;
+}
+export interface CreateCommentRequest {
+    entityId: string;
+    entityType: CommentEntityType;
+    content: string;
+    parentId?: string;
+    mentions?: string[];
+    metadata?: CommentMetadata;
+}
+export interface UpdateCommentRequest {
+    content?: string;
+    mentions?: string[];
+    metadata?: CommentMetadata;
+}
+/** Sort order for API requests */
+export type ApiSortOrder = "asc" | "desc";
+/** Sort order for comments display */
+export type CommentSortOrder = "newest" | "oldest";
+/** File validation error */
+export interface FileValidationError {
+    fileName: string;
+    error: string;
+}
+/** Configuration for the useCommentAttachments hook */
+export interface UseCommentAttachmentsConfig {
+    /** Initial attachments (for editing) */
+    initialAttachments?: CommentAttachment[];
+    /** Upload file function */
+    onUploadFile: (file: File, onProgress?: (progress: number) => void) => Promise<UploadFileResult>;
+}
+/** State returned by useCommentAttachments hook */
+export interface UseCommentAttachmentsState {
+    /** List of pending attachments */
+    pendingAttachments: PendingAttachment[];
+    /** List of completed attachments */
+    completedAttachments: PendingAttachment[];
+    /** Whether any files are currently uploading */
+    isUploading: boolean;
+    /** Validation errors */
+    validationErrors: FileValidationError[];
+    /** Attachment pending deletion (for confirmation dialog) */
+    attachmentToDelete: PendingAttachment | null;
+    /** Whether deletion is in progress */
+    isDeleting: boolean;
+}
+/** Actions returned by useCommentAttachments hook */
+export interface UseCommentAttachmentsActions {
+    /** Handle file selection from input */
+    handleFileSelect: (e: import("react").ChangeEvent<HTMLInputElement>, fileInputRef: import("react").RefObject<HTMLInputElement | null>) => void;
+    /** Request to remove an attachment (shows confirmation) */
+    handleRemoveAttachment: (attachmentId: string) => void;
+    /** Confirm deletion of attachment */
+    handleConfirmDelete: () => Promise<void>;
+    /** Cancel deletion */
+    handleCancelDelete: () => void;
+    /** Reset attachments */
+    resetAttachments: () => void;
+}
+/** Configuration for the useCommentMentions hook */
+export interface UseCommentMentionsConfig {
+    /** Initial content (may contain mentions) */
+    initialContent?: string;
+    /** Whether mentions are allowed */
+    canMention: boolean;
+    /** Users available for @mentions */
+    mentionableUsers: MentionableUser[];
+    /** Search users dynamically */
+    onSearchUsers?: (query: string) => Promise<MentionableUser[]>;
+}
+/** State returned by useCommentMentions hook */
+export interface UseCommentMentionsState {
+    /** Raw content with full mention format @[Name](id) */
+    rawContent: string;
+    /** Display content with @Name (user-friendly) */
+    displayContent: string;
+    /** Whether the mentions dropdown is visible */
+    showMentions: boolean;
+    /** Current mention search query */
+    mentionQuery: string;
+    /** Filtered/searched mention results */
+    mentionResults: MentionableUser[];
+    /** Current cursor position */
+    cursorPosition: number;
+}
+/** Actions returned by useCommentMentions hook */
+export interface UseCommentMentionsActions {
+    /** Handle textarea content change */
+    handleContentChange: (e: import("react").ChangeEvent<HTMLTextAreaElement>) => void;
+    /** Handle selecting a mention from dropdown */
+    handleSelectMention: (user: MentionableUser, textareaRef: import("react").RefObject<HTMLTextAreaElement | null>) => void;
+    /** Close the mentions dropdown */
+    closeMentions: () => void;
+    /** Reset the content */
+    resetContent: () => void;
+    /** Set raw content directly */
+    setRawContent: (content: string) => void;
+}
+/** API response for listing comments */
+export interface ListCommentsApiResponse {
+    comments: CommentThread[];
+    nextCursor?: string;
+    hasMore: boolean;
+}
+/** Configuration for the comments API hook */
+export interface UseCommentsApiConfig {
+    /** API endpoint for comments */
+    apiEndpoint: string;
+    /** Entity ID */
+    entityId: string;
+    /** Entity type */
+    entityType: CommentEntityType;
+    /** Current user */
+    currentUser: {
+        id: string;
+        name: string;
+        email?: string;
+        avatarUrl?: string;
+    };
+    /** Callback functions */
+    callbacks?: CommentsCallbacks;
+}
+/** Parameters for fetching comments */
+export interface FetchCommentsParams {
+    sortOrder: ApiSortOrder;
+    pageSize: number;
+    enableThreading: boolean;
+    cursor?: string;
+}
+/** Parameters for fetching replies */
+export interface FetchRepliesParams {
+    parentId: string;
+    limit?: number;
+    sortOrder?: ApiSortOrder;
+    cursor?: string;
+}
+/** API response for listing replies */
+export interface ListRepliesApiResponse {
+    comments: CommentThread[];
+    nextCursor?: string;
+    hasMore: boolean;
+}
+/** Configuration for the useComments hook */
+export interface UseCommentsConfig {
+    /** Entity ID being commented on */
+    entityId: string;
+    /** Entity type */
+    entityType: CommentEntityType;
+    /** Current user information */
+    currentUser: {
+        id: string;
+        name: string;
+        email?: string;
+        avatarUrl?: string;
+    };
+    /** API endpoint for comments */
+    apiEndpoint?: string;
+    /** Initial comments (for SSR) */
+    initialComments?: CommentThread[];
+    /** Number of comments per page */
+    pageSize?: number;
+    /** Enable threaded replies */
+    enableThreading?: boolean;
+    /** Default sort order */
+    defaultSortOrder?: CommentSortOrder;
+    /** Callback functions */
+    callbacks?: CommentsCallbacks;
+    /** Enable AI mentions (@askcaptify) */
+    enableAiMentions?: boolean;
+    /** Whether to fetch comments on mount */
+    fetchOnMount?: boolean;
+}
+/** State returned by useComments hook */
+export interface UseCommentsState {
+    /** List of comments */
+    comments: CommentThread[];
+    /** Sorted comments based on current sort order */
+    sortedComments: CommentThread[];
+    /** Loading state */
+    loading: boolean;
+    /** Error message */
+    error: string | null;
+    /** Whether there are more comments to load */
+    hasMore: boolean;
+    /** Current sort order */
+    sortOrder: CommentSortOrder;
+    /** AI reply state */
+    aiReply: AiReplyState;
+}
+/** Actions returned by useComments hook */
+export interface UseCommentsActions {
+    /** Set the sort order */
+    setSortOrder: (order: CommentSortOrder) => void;
+    /** Load more comments */
+    loadMore: () => Promise<void>;
+    /** Add a new comment */
+    addComment: (content: string, attachments?: AttachmentData[], parentId?: string, metadata?: CommentMetadata) => Promise<Comment>;
+    /** Edit an existing comment */
+    editComment: (commentId: string, content: string, attachments?: AttachmentData[], metadata?: CommentMetadata) => Promise<Comment>;
+    /** Delete a comment */
+    deleteComment: (commentId: string) => Promise<void>;
+    /** Delete an attachment */
+    deleteAttachment: (commentId: string, attachmentId: string) => Promise<Comment>;
+    /** Load more replies for a comment */
+    loadMoreReplies: (parentId: string) => Promise<void>;
+    /** Upload a file */
+    uploadFile: (file: File, onProgress?: (progress: number) => void) => Promise<UploadFileResult>;
+}
+/** Result of file upload operation */
+export interface UploadFileResult {
+    id: string;
+    s3Key: string;
+    bucket: string;
+    fileName: string;
+    fileType: string;
+    fileSize: number;
+}
+/** Pending attachment during upload */
+export interface PendingAttachment {
+    id: string;
+    file: File;
+    fileName: string;
+    fileType: string;
+    fileSize: number;
+    s3Key?: string;
+    bucket?: string;
+    progress: number;
+    status: AttachmentStatus;
+    error?: string;
+}
+/** Attachment data for API requests */
+export interface AttachmentData {
+    id: string;
+    fileName: string;
+    fileType: string;
+    fileSize: number;
+    s3Key?: string;
+    bucket?: string;
+}
+/** Context value for comments provider */
+export interface CommentsContextValue {
+    /** Entity ID being commented on */
+    entityId: string;
+    /** Entity type */
+    entityType: CommentEntityType;
+    /** Current user information */
+    currentUser: {
+        id: string;
+        name: string;
+        email?: string;
+        avatarUrl?: string;
+    };
+    /** Whether user can add comments */
+    canComment: boolean;
+    /** Whether user can reply to comments */
+    canReplyComment: boolean;
+    /** Whether user can edit comments */
+    canEditComment: boolean;
+    /** Whether user can delete comments */
+    canDeleteComment: boolean;
+    /** Whether user can upload attachments */
+    canUploadAttachment: boolean;
+    /** Whether user can delete attachments */
+    canDeleteAttachment: boolean;
+    /** Whether user can download attachments */
+    canDownloadAttachment: boolean;
+    /** Whether user can mention other users */
+    canMention: boolean;
+    /** Current comments */
+    comments: CommentThread[];
+    /** Users available for @mentions */
+    mentionableUsers: MentionableUser[];
+    /** Search users for mentions */
+    onSearchUsers?: (query: string) => Promise<MentionableUser[]>;
+    /** Whether threading is enabled */
+    enableThreading: boolean;
+    /** Whether replies should be expanded by default */
+    defaultRepliesExpanded: boolean;
+    /** Add a new comment */
+    onAddComment: (content: string, attachments?: AttachmentData[], parentId?: string, metadata?: CommentMetadata) => Promise<Comment>;
+    /** Edit an existing comment */
+    onEditComment: (commentId: string, content: string, attachments?: AttachmentData[], metadata?: CommentMetadata) => Promise<Comment>;
+    /** Delete a comment */
+    onDeleteComment: (commentId: string) => Promise<void>;
+    /** Delete an attachment from a comment */
+    onDeleteAttachment: (commentId: string, attachmentId: string) => Promise<Comment>;
+    /** Load more replies for a comment */
+    onLoadMoreReplies: (parentId: string) => Promise<void>;
+    /** Upload a file for attachment */
+    onUploadFile: (file: File, onProgress?: (progress: number) => void) => Promise<UploadFileResult>;
+    /** AI reply state (optional - only present when AI mentions are enabled) */
+    aiReply?: AiReplyState;
+}
+/** Props for CommentsProvider component */
+export interface CommentsProviderProps {
+    value: CommentsContextValue;
+    children: ReactNode;
+}
+/** Props for CommentAttachments component */
+export interface CommentAttachmentsProps {
+    /** ID of the comment containing these attachments */
+    commentId: string;
+    /** List of attachments */
+    attachments: CommentAttachment[];
+    /** Whether the user can delete attachments */
+    canDelete?: boolean;
+    /** Custom class name */
+    className?: string;
+}
+/** Props for CommentMentions component */
+export interface CommentMentionsProps {
+    /** List of users to display */
+    users: MentionableUser[];
+    /** Current search query */
+    query: string;
+    /** Selection handler */
+    onSelect: (user: MentionableUser) => void;
+    /** Close handler */
+    onClose: () => void;
+    /** Custom class name */
+    className?: string;
+}
+/** Props for CommentActions component */
+export interface CommentActionsProps {
+    /** Reply action handler */
+    onReply?: () => void;
+    /** Edit action handler */
+    onEdit?: () => void;
+    /** Delete action handler */
+    onDelete?: () => void;
+    /** Resolve action handler */
+    onResolve?: () => void;
+    /** Whether the comment is resolved */
+    isResolved?: boolean;
+    /** Custom class name */
+    className?: string;
+}
+/** Props for Comments component (main entry point) */
+export interface CommentsProps {
+    /** ID of the entity (document, task, etc.) */
+    entityId: string;
+    /** Type of entity */
+    entityType: CommentEntityType;
+    /** Current user information */
+    currentUser: {
+        id: string;
+        name: string;
+        email?: string;
+        avatarUrl?: string;
+    };
+    /** Whether user can add comments (default: true) */
+    canComment?: boolean;
+    /** Whether user can reply to comments (default: true) */
+    canReplyComment?: boolean;
+    /** Whether user can edit comments (default: true) */
+    canEditComment?: boolean;
+    /** Whether user can delete comments (default: true) */
+    canDeleteComment?: boolean;
+    /** Whether user can upload attachments (default: true) */
+    canUploadAttachment?: boolean;
+    /** Whether user can delete attachments (default: true) */
+    canDeleteAttachment?: boolean;
+    /** Whether user can download attachments (default: true) */
+    canDownloadAttachment?: boolean;
+    /** Whether user can mention other users (default: true) */
+    canMention?: boolean;
+    /** Callback functions for integration */
+    callbacks?: CommentsCallbacks;
+    /** Initial comments to display (for SSR) */
+    initialComments?: CommentThread[];
+    /** API endpoint for comments (defaults to /api/comments) */
+    apiEndpoint?: string;
+    /** Users available for @mentions */
+    mentionableUsers?: MentionableUser[];
+    /** Fetch mentionable users dynamically */
+    onSearchUsers?: (query: string) => Promise<MentionableUser[]>;
+    /** Number of comments per page */
+    pageSize?: number;
+    /** Enable threaded replies */
+    enableThreading?: boolean;
+    /** Custom class name */
+    className?: string;
+    /** Placeholder text for comment input */
+    placeholder?: string;
+    /** Show comment count in header */
+    showCount?: boolean;
+    /** Custom header component */
+    header?: ReactNode;
+    /** Custom empty state component */
+    emptyState?: ReactNode;
+    /** Enable AI mentions (@askcaptify) */
+    enableAiMentions?: boolean;
+    /** Hide the root comment form after first submit */
+    hideFormAfterSubmit?: boolean;
+    /** Optional metadata to attach to new comments */
+    commentMetadata?: CommentMetadata | ((parentId?: string) => CommentMetadata | undefined);
+    /** Whether to fetch comments on mount */
+    fetchOnMount?: boolean;
+    /** AI agent endpoint */
+    aiAgentEndpoint?: string;
+    /** AI agent model */
+    aiAgentModel?: string;
+    /** Default sort order for comments */
+    defaultSortOrder?: CommentSortOrder;
+    /** Show sort controls */
+    showSortControls?: boolean;
+    /** Whether replies should be expanded by default */
+    defaultRepliesExpanded?: boolean;
+    /** Show summarize button to generate AI summary of comments */
+    showSummarizeButton?: boolean;
+}
+/** Props for CommentsHeader component */
+export interface CommentsHeaderProps {
+    /** Number of comments */
+    count: number;
+    /** Current sort order */
+    sortOrder: CommentSortOrder;
+    /** Callback when sort order changes */
+    onSortOrderChange: (order: CommentSortOrder) => void;
+    /** Whether to show the comment count */
+    showCount?: boolean;
+    /** Whether to show sort controls */
+    showSortControls?: boolean;
+    /** Custom header content (replaces default count display) */
+    customHeader?: ReactNode;
+    /** Custom class name */
+    className?: string;
+    /** Whether to show the summarize button */
+    showSummarizeButton?: boolean;
+    /** Whether summary is being generated */
+    isSummarizing?: boolean;
+    /** Callback when summarize button is clicked */
+    onSummarize?: () => void;
+}
+/** Props for CommentForm component */
+export interface CommentFormProps {
+    /** Parent comment ID (for replies) */
+    parentId?: string;
+    /** Initial content (for editing) */
+    initialContent?: string;
+    /** Initial attachments (for editing) */
+    initialAttachments?: CommentAttachment[];
+    /** Custom submit handler (for editing) */
+    onSubmit?: (content: string, attachments?: PendingAttachment[]) => Promise<void>;
+    /** Cancel handler */
+    onCancel?: () => void;
+    /** Success callback (called after successful submission) */
+    onSuccess?: () => void;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Submit button label */
+    submitLabel?: string;
+    /** Auto-focus the textarea */
+    autoFocus?: boolean;
+    /** Custom class name */
+    className?: string;
+}
+/** Props for CommentList component */
+export interface CommentListProps {
+    /** List of comments to display */
+    comments: CommentThread[];
+    /** Whether there are more comments to load */
+    hasMore: boolean;
+    /** Loading state */
+    loading: boolean;
+    /** Load more comments callback */
+    onLoadMore: () => void;
+    /** Custom empty state */
+    emptyState?: ReactNode;
+    /** Custom class name */
+    className?: string;
+}
+/** Props for CommentFormAttachments component */
+export interface CommentFormAttachmentsProps {
+    /** List of pending attachments */
+    pendingAttachments: PendingAttachment[];
+    /** Validation errors */
+    validationErrors: FileValidationError[];
+    /** Attachment pending deletion */
+    attachmentToDelete: PendingAttachment | null;
+    /** Whether deletion is in progress */
+    isDeleting: boolean;
+    /** Handle removing an attachment */
+    onRemoveAttachment: (attachmentId: string) => void;
+    /** Confirm deletion */
+    onConfirmDelete: () => void;
+    /** Cancel deletion */
+    onCancelDelete: () => void;
+}
+/** Props for AttachmentItem component */
+export interface AttachmentItemProps {
+    /** Pending attachment to display */
+    attachment: PendingAttachment;
+    /** Remove attachment handler */
+    onRemove: () => void;
+}
+/** Props for CommentItem component */
+export interface CommentItemProps {
+    /** Comment to display */
+    comment: CommentThread;
+    /** Depth level for indentation */
+    depth?: number;
+    /** Whether parent thread is resolved */
+    parentResolved?: boolean;
+    /** Custom class name */
+    className?: string;
+}
+/**
+ * Server-side entity context fetcher type.
+ * Implementations should fetch entity data securely from the database.
+ */
+export type ServerEntityContextFetcher = (params: {
+    entityId: string;
+    entityType: CommentEntityType;
+    tenantId: string;
+    userCredentials?: UserAwsCredentials;
+}) => Promise<string | undefined>;
+/**
+ * Configuration for creating comments AI handlers.
+ */
+export interface CommentsAiHandlerConfig {
+    /**
+     * Server-side fetcher for entity context.
+     * Fetches data securely from the database based on entity type.
+     */
+    entityContextFetcher?: ServerEntityContextFetcher;
+}
+/**
+ * Request parameters for AI reply (minimal - from API request)
+ */
+export interface AiReplyRequestParams {
+    /** Tenant ID */
+    tenantId: string;
+    /** Entity ID being commented on */
+    entityId: string;
+    /** Entity type */
+    entityType: CommentEntityType;
+    /** Comment ID that triggered the AI reply */
+    triggerCommentId: string;
+}
+/**
+ * Extended options for AI reply streaming
+ */
+export interface AiReplyOptions extends CommentsOperationOptions {
+    /** Server-side fetcher for entity context */
+    entityContextFetcher?: ServerEntityContextFetcher;
+}
+/**
+ * Internal parameters for streaming an AI reply (used within service)
+ * @internal
+ */
+export interface AiReplyStreamParams {
+    /** Tenant ID */
+    tenantId: string;
+    /** Entity ID being commented on */
+    entityId: string;
+    /** Entity type */
+    entityType: CommentEntityType;
+    /** Comment ID that triggered the AI reply */
+    triggerCommentId: string;
+    /** Thread context (recent comments for AI context) */
+    threadContext: CommentThread[];
+    /** Entity-specific context provided by consumer app */
+    entityContext?: string;
+    /** User ID who triggered the AI reply */
+    userId?: string;
+}
+/**
+ * State for AI reply streaming (client-side)
+ */
+export interface AiReplyState {
+    /** Whether AI is currently generating a response */
+    isStreaming: boolean;
+    /** Current streaming text (accumulated) */
+    streamingText: string;
+    /** Comment ID being replied to */
+    replyingToCommentId: string | null;
+    /** Error message if any */
+    error: string | null;
+    /** Cancel the ongoing AI stream */
+    cancelStream: () => void;
+    /** Regenerate AI reply (cancels existing stream and triggers new response) */
+    regenerateAiReply: (triggerCommentId?: string) => Promise<void>;
+}
+/**
+ * Actions for AI reply (client-side)
+ */
+export interface AiReplyActions {
+    /** Trigger AI reply for a comment */
+    triggerAiReply: (triggerCommentId: string) => Promise<void>;
+    /** Cancel ongoing stream */
+    cancelStream: () => void;
+    /** Reset AI reply state */
+    resetAiReply: () => void;
+    /** Regenerate AI reply (cancels existing stream and triggers new response) */
+    regenerateAiReply: (triggerCommentId?: string) => Promise<void>;
+}
+/**
+ * Combined AI reply hook return type
+ */
+export interface UseAiReplyReturn extends AiReplyState, AiReplyActions {
+}
+/**
+ * Configuration for useAiReply hook
+ */
+export interface UseAiReplyConfig {
+    /** Entity ID being commented on */
+    entityId: string;
+    /** Entity type */
+    entityType: CommentEntityType;
+    /** API endpoint for comments (defaults to /api/comments) */
+    apiEndpoint?: string;
+    /** Callback when AI reply is saved - used for optimistic UI updates */
+    onAiReplySaved?: (triggerCommentId: string, responseText: string) => void;
+    /** Callback when AI reply fully completes (after save) */
+    onAiReplyComplete?: () => void;
+    /** Callback when AI reply errors */
+    onAiReplyError?: (error: Error) => void;
+}
+/** Props for CommentAiStreamingReply component */
+export interface CommentAiStreamingReplyProps {
+    /** Current streaming text */
+    streamingText: string;
+    /** Cancel stream handler */
+    onCancel: () => void;
+    /** Custom class name */
+    className?: string;
+}
+/** Props for CommentAiErrorDisplay component */
+export interface CommentAiErrorDisplayProps {
+    /** Error message to display */
+    error: string;
+    /** Retry handler */
+    onRetry: () => void;
+    /** Custom class name */
+    className?: string;
+}
+/**
+ * Parameters for determining if AI retry button should be shown
+ */
+export interface ShouldShowAiRetryButtonParams {
+    /** Whether AI reply feature is available */
+    hasAiReplyFeature: boolean;
+    /** Whether the comment mentions the AI assistant */
+    commentHasAiMention: boolean;
+    /** Whether the comment already has an AI reply */
+    hasAiReply: boolean;
+    /** Comment author ID */
+    commentAuthorId: string;
+    /** Current user ID */
+    currentUserId: string;
+    /** Comment ID */
+    commentId: string;
+    /** Whether comment is deleted */
+    isDeleted: boolean;
+    /** Whether AI is currently streaming */
+    isStreaming: boolean;
+    /** Comment ID that AI is replying to */
+    replyingToCommentId: string | null;
+    /** AI reply error message */
+    aiError: string | null;
+}
+/**
+ * Request parameters for comments summary (from API request)
+ */
+export interface SummaryRequestParams {
+    /** Tenant ID */
+    tenantId: string;
+    /** Entity ID being commented on */
+    entityId: string;
+    /** Entity type */
+    entityType: CommentEntityType;
+}
+/**
+ * Extended options for summary streaming
+ */
+export interface SummaryOptions extends CommentsOperationOptions {
+    /** Server-side fetcher for entity context */
+    entityContextFetcher?: ServerEntityContextFetcher;
+}
+/**
+ * Internal parameters for streaming a summary (used within service)
+ * @internal
+ */
+export interface SummaryStreamParams {
+    /** Tenant ID */
+    tenantId: string;
+    /** Entity ID being commented on */
+    entityId: string;
+    /** Entity type */
+    entityType: CommentEntityType;
+    /** All comments to summarize */
+    comments: CommentThread[];
+    /** Entity-specific context provided by consumer app */
+    entityContext?: string;
+}
+/**
+ * State for comments summary (client-side)
+ */
+export interface SummaryState {
+    /** Whether summary is currently being generated */
+    isSummarizing: boolean;
+    /** Current summary text (accumulated during streaming) */
+    summaryText: string;
+    /** Error message if any */
+    error: string | null;
+}
+/**
+ * Cached summary data stored in sessionStorage
+ */
+export interface CachedSummary {
+    /** Cache key based on comments count and latest timestamp */
+    cacheKey: string;
+    /** The cached summary text */
+    text: string;
+}
+/**
+ * Actions for comments summary (client-side)
+ */
+export interface SummaryActions {
+    /** Trigger summary generation (uses cache if available, pass true to force regenerate) */
+    triggerSummary: (forceRegenerate?: boolean) => Promise<void>;
+    /** Cancel ongoing summary stream */
+    cancelSummary: () => void;
+    /** Reset summary state */
+    resetSummary: () => void;
+    /** Clear the cached summary */
+    clearCache: () => void;
+}
+/**
+ * Combined summary hook return type
+ */
+export interface UseCommentsSummaryReturn extends SummaryState, SummaryActions {
+}
+/**
+ * Configuration for useCommentsSummary hook
+ */
+export interface UseCommentsSummaryConfig {
+    /** Entity ID being commented on */
+    entityId: string;
+    /** Entity type */
+    entityType: CommentEntityType;
+    /** API endpoint for comments (defaults to /api/comments) */
+    apiEndpoint?: string;
+    /** Comments to calculate cache key from (for cache invalidation) */
+    comments?: CommentThread[];
+    /** Callback when summary generation completes */
+    onSummaryComplete?: (summaryText: string) => void;
+    /** Callback when summary generation errors */
+    onSummaryError?: (error: Error) => void;
+}
+/** Props for CommentsSummaryDialog component */
+export interface CommentsSummaryDialogProps {
+    /** Whether the dialog is open */
+    isOpen: boolean;
+    /** Callback to close the dialog */
+    onOpenChange: (open: boolean) => void;
+    /** Current summary text */
+    summaryText: string;
+    /** Whether summary is being generated */
+    isSummarizing: boolean;
+    /** Error message if any */
+    error: string | null;
+    /** Callback to regenerate summary */
+    onRegenerate: () => void;
+    /** Custom class name */
+    className?: string;
+}
+//# sourceMappingURL=comments.interfaces.d.ts.map