ws.comments

addNote(cell: string, options: { text: string; author?: string }): Promise<void>;

Add a note to a cell (options object form). @param cell - A1-style cell address (e.g. "A1") @param options - Note text and optional author

setNote(address: string, text: string, author?: string): Promise<void>;

@deprecated Use the options-object overload instead. Set the note for a cell (overwrites any existing note). @param address - A1-style cell address (e.g. "A1") @param text - Note text @param author - Optional author name (defaults to 'api') @deprecated Use the options-object overload instead.

getNote(address: string): Promise<Note | null>;

Get the note for a cell as a Note object. @param address - A1-style cell address @returns The Note object, or null if no note

removeNote(address: string): Promise<void>;

Remove the note from a cell. @param address - A1-style cell address

getCount(): Promise<number>;

Get the total number of comments (notes + threaded) on this worksheet.

noteCount(): Promise<number>;

Get the number of notes (legacy comments) in the worksheet. @returns The count of notes only (excludes threaded comments)

listNotes(): Promise<Note[]>;

List all notes (legacy comments) in the worksheet. @returns Array of notes

getNoteAt(index: number): Promise<Note | null>;

Get a note by index from the list of all notes. @param index - Zero-based index into the notes list @returns The Note at that index, or null if out of range

setNoteVisible(address: string, visible: boolean): Promise<void>;

Set the visibility of a note at the given cell address. @param address - A1-style cell address @param visible - Whether the note should be visible

setNoteHeight(address: string, height: number): Promise<void>;

Set the height of a note callout box in points. @param address - A1-style cell address @param height - Height in points

setNoteWidth(address: string, width: number): Promise<void>;

Set the width of a note callout box in points. @param address - A1-style cell address @param width - Width in points

add(cell: string, options: { text: string; author?: string }): Promise<Comment>;

Add a threaded comment to a cell (options object form). @param cell - A1-style cell address @param options - Comment text and optional author

update(commentId: string, updates: CommentUpdate): Promise<void>;

Update an existing comment. @param commentId - Comment identifier @param updates - Object with fields to update (text, mentions, or both)

remove(commentId: string): Promise<void>;

Remove a threaded comment by ID. @param commentId - Comment identifier

resolveThread(threadId: string, resolved: boolean): Promise<void>;

Set the resolved state of a comment thread. @param threadId - Thread identifier (cell ID) @param resolved - Whether the thread should be marked as resolved

list(): Promise<Comment[]>;

List all comments in the worksheet. @returns Array of all comments

getForCell(address: string): Promise<Comment[]>;

Get all comments for a specific cell. @param address - A1-style cell address @returns Array of comments for the cell

addReply(commentId: string, text: string, author: string): Promise<Comment>;

Add a reply to an existing comment. @param commentId - ID of the comment to reply to @param text - Reply text @param author - Author name or identifier @returns The created reply comment

convertNoteToThread(commentId: string): Promise<Comment>;

Convert a legacy note into a modern threaded comment. Flips `commentType` to `'threadedComment'`, clears note callout geometry (`noteHeight`/`noteWidth`/`visible`/`shapeId`), and assigns `threadId`. Idempotent on a comment that is already a threaded comment. @param commentId - ID of the note to convert @returns The updated comment so the caller can re-render in thread mode

getThread(commentId: string): Promise<Comment[]>;

Get all comments in a thread (root + replies), sorted by createdAt. @param commentId - ID of any comment in the thread @returns Array of comments in the thread

getById(commentId: string): Promise<Comment | null>;

Get a single comment by its ID. @param commentId - Comment identifier @returns The comment, or null if not found

getLocation(commentId: string): Promise<string | null>;

Get the A1-style cell address for a comment. Resolves the comment's internal cell reference (CellId) to a human-readable address like "A1", "B3", etc. @param commentId - Comment identifier @returns The A1-style cell address, or null if the comment doesn't exist

getParentByReplyId(replyId: string): Promise<Comment | null>;

Get the parent comment for a reply. @param replyId - ID of the reply comment @returns The parent comment, or null if not found or not a reply

getReplyCount(commentId: string): Promise<number>;

Get the number of replies in a thread (excluding the root comment). @param commentId - ID of any comment in the thread @returns The reply count

getReplyAt(commentId: string, index: number): Promise<Comment | null>;

Get a reply at a specific index within a thread (zero-based, excludes root). @param commentId - ID of any comment in the thread @param index - Zero-based index into the replies @returns The reply comment, or null if out of range

getNoteLocation(address: string): Promise<string | null>;

Get the A1-style cell address for a note. @param address - A1-style cell address @returns The A1-style cell address, or null if no note exists at that address

hasComment(address: string): Promise<boolean>;

Check if a cell has any comments. @param address - A1-style cell address @returns True if the cell has at least one comment

removeForCell(address: string): Promise<number>;

Remove all comments on a cell. @param address - A1-style cell address @returns The number of comments removed

clear(): Promise<void>;

Clear all comments on the worksheet.

clean(): Promise<number>;

Remove orphaned comments (comments referencing non-existent cells). @returns The number of orphaned comments removed