@veltdev/sdk
Version:
Velt is an SDK to add collaborative features to your product within minutes. Example: Comments like Figma, Frame.io, Google docs or sheets, Recording like Loom, Huddles like Slack and much more.
269 lines (268 loc) • 8.49 kB
TypeScript
import { CommentAccessMode } from "../../utils/enums";
import { Attachment } from "./attachment.model";
import { CommentAnnotation } from "./comment-annotation.data.model";
import { Comment } from "./comment.data.model";
import { CustomPriority, CustomStatus } from "./custom-filter.data.model";
import { ReactionItem } from "./reaction-annotation.data.model";
import { UserContact } from "./user-contact.data.model";
import { User } from "./user.data.model";
export interface RequestOptions {
organizationId?: string;
documentId?: string;
folderId?: string;
filters?: any;
documentIds?: string[];
allDocuments?: boolean;
}
export interface UpdatePriorityRequest {
annotationId: string;
priority?: CustomPriority;
options?: RequestOptions;
}
export interface UpdateStatusRequest {
annotationId: string;
status: CustomStatus;
options?: RequestOptions;
}
export interface UpdateAccessRequest {
annotationId: string;
accessMode: CommentAccessMode;
options?: RequestOptions;
}
export interface ResolveCommentAnnotationRequest {
annotationId: string;
options?: RequestOptions;
}
export interface GetLinkRequest {
annotationId: string;
options?: RequestOptions;
}
export interface CopyLinkRequest {
annotationId: string;
options?: RequestOptions;
}
/**
* Visibility type for comment annotations.
* - 'public': Visible to everyone (default:velt)
* - 'organizationPrivate': Visible only to users in the specified organization
* - 'restricted': Visible only to specified users (private comments)
*/
export type CommentVisibilityType = 'public' | 'organizationPrivate' | 'restricted';
/**
* Configuration for comment visibility/access control.
*/
export interface CommentVisibilityConfig {
/** The type of visibility for the comment */
type: CommentVisibilityType;
/** Annotation ID for the comment to update visibility */
annotationId?: string;
/** Organization ID for 'organizationPrivate' type visibility */
organizationId?: string;
/** User IDs for 'restricted' type visibility - array of user IDs who can see the comment */
userIds?: string[];
}
/**
* Configuration for private mode (enablePrivateMode/disablePrivateMode).
* Same as CommentVisibilityConfig but without annotationId and organizationId,
* since private mode applies to all new comments.
*/
export type PrivateModeConfig = Omit<CommentVisibilityConfig, 'annotationId' | 'organizationId'>;
export interface AddCommentAnnotationRequest {
annotation: CommentAnnotation;
options?: RequestOptions;
/** Optional visibility configuration for the comment */
visibility?: CommentVisibilityConfig;
}
export interface ApproveCommentAnnotationRequest {
annotationId: string;
options?: RequestOptions;
}
export interface AcceptCommentAnnotationRequest {
annotationId: string;
options?: RequestOptions;
}
export interface RejectCommentAnnotationRequest {
annotationId: string;
options?: RequestOptions;
}
export interface DeleteCommentAnnotationRequest {
annotationId: string;
options?: RequestOptions;
}
/**
* Query parameters for fetching comment annotation counts.
*
* @property organizationId - Filter by organization (enables org-wide aggregation when used alone)
* @property documentIds - Filter by specific document IDs
* @property locationIds - Filter by location IDs within documents
* @property statusIds - Filter by comment status IDs (e.g., "open", "resolved")
* @property folderId - Filter by folder ID (use with allDocuments for folder-wide counts)
* @property allDocuments - When true with folderId, aggregates all documents in folder
* @property locationId - Single location filter (deprecated, use locationIds)
* @property aggregateDocuments - When true, combines all documentIds into single count
* @property filterGhostComments - When true, excludes orphaned/deleted comments from counts
* @property batchedPerDocument - When true, uses efficient batched listeners (4 instead of 100)
* but still returns per-document counts. Best for large document lists (50+).
* Trade-off: slight delay on updates due to debouncing.
* @property debounceMs - Debounce time in milliseconds for batchedPerDocument mode (default: 5000ms).
* Prevents rapid re-fetches when multiple documents update in quick succession.
*/
export interface CommentRequestQuery {
organizationId?: string;
documentIds?: string[];
locationIds?: string[];
statusIds?: string[];
folderId?: string;
allDocuments?: boolean;
locationId?: string;
aggregateDocuments?: boolean;
filterGhostComments?: boolean;
/** Enable batched listeners with per-document counts. Uses 4 listeners instead of N listeners. */
batchedPerDocument?: boolean;
/** Debounce time in ms for batchedPerDocument mode (default: 5000). */
debounceMs?: number;
}
export interface SubscribeCommentAnnotationRequest {
annotationId: string;
options?: RequestOptions;
}
export interface UnsubscribeCommentAnnotationRequest {
annotationId: string;
options?: RequestOptions;
}
export interface AssignUserRequest {
annotationId: string;
assignedTo: UserContact;
options?: RequestOptions;
}
export interface AddCommentRequest {
annotationId: string;
comment: Comment;
assignedTo?: User;
assigned?: boolean;
options?: RequestOptions;
/** Optional visibility configuration for the comment */
visibility?: CommentVisibilityConfig;
}
export interface UpdateCommentRequest {
annotationId: string;
comment: Comment;
skipDeleteThreadConfirmation?: boolean;
merge?: boolean;
options?: RequestOptions;
}
export interface DeleteCommentRequest {
annotationId: string;
commentId: number;
skipDeleteThreadConfirmation?: boolean;
options?: RequestOptions;
}
export interface GetCommentRequest {
annotationId: string;
options?: RequestOptions;
}
export interface AddAttachmentRequest {
annotationId: string;
files: File[];
options?: RequestOptions;
}
export interface AddAttachmentResponse {
valid: boolean;
file?: File;
maxAllowedSize: number;
error?: string;
attachment?: Attachment;
}
export interface DeleteAttachmentRequest {
annotationId: string;
commentId: number;
attachmentId: number;
options?: RequestOptions;
}
export interface GetAttachmentRequest {
annotationId: string;
commentId: number;
options?: RequestOptions;
}
export interface GetRecordingRequest {
annotationId: string;
commentId: number;
options?: RequestOptions;
}
export interface DeleteRecordingRequest {
annotationId: string;
commentId: number;
recorderId: string;
options?: RequestOptions;
}
export interface AddReactionRequest {
annotationId: string;
commentId: number;
reaction: {
reactionId: string;
customReaction?: ReactionItem;
};
options?: RequestOptions;
}
export interface DeleteReactionRequest {
annotationId: string;
commentId: number;
reaction: {
reactionId: string;
customReaction?: ReactionItem;
};
options?: RequestOptions;
}
export interface ToggleReactionRequest {
annotationId: string;
commentId: number;
reaction: {
reactionId: string;
customReaction?: ReactionItem;
};
options?: RequestOptions;
}
export interface SubmitCommentRequest {
targetComposerElementId: string;
}
export interface ClearComposerRequest {
targetComposerElementId: string;
}
export interface GetComposerDataRequest {
targetComposerElementId: string;
}
/**
* FormatConfig - Configuration for format options
*/
export interface FormatConfig {
bold?: {
enable: boolean;
};
italic?: {
enable: boolean;
};
underline?: {
enable: boolean;
};
strikethrough?: {
enable: boolean;
};
}
export interface FetchCommentAnnotationsRequest {
createdAfter?: number;
createdBefore?: number;
updatedAfter?: number;
updatedBefore?: number;
statusIds?: string[];
order?: 'asc' | 'desc';
pageToken?: string;
allDocuments?: boolean;
pageSize?: number;
organizationId?: string;
locationId?: string;
documentIds?: string[];
folderId?: string;
resolvedBy?: string;
userIds?: string[];
mentionedUserIds?: string[];
}