Observe review events

Use editor lifecycle events to observe interactive review operations. Use document events to respond after a transaction commits tracked revision or comment changes.

Before you start, install Nutrient Document Authoring SDK and load it in your app. If you haven’t set it up, refer to the getting started guide.

Observe editor attempts and committed changes

The following example registers editor lifecycle listeners and document listeners. It returns a cleanup function that removes every listener.

import type {
  CommentEventPayload,
  DocAuthDocument,
  DocAuthEditor,
  DocAuthEditorEvents,
  RevisionEventPayload,
} from '@nutrient-sdk/document-authoring';

export function observeReviewActivity(
  editor: DocAuthEditor,
  document: DocAuthDocument,
): () => void {
  const onTrackedChange = (
    event: DocAuthEditorEvents['tracked-change.lifecycle'],
  ) => {
    console.log('Editor tracked change', event);
  };
  const onComment = (event: DocAuthEditorEvents['comment.lifecycle']) => {
    console.log('Editor comment', event);
  };
  const onRevisionAccepted = (event: RevisionEventPayload) => {
    console.log('Committed revision acceptance', event.ids, event.txId);
  };
  const onCommentAdded = (event: CommentEventPayload) => {
    console.log('Committed comment threads', event.ids, event.txId);
  };

  const removeListeners = () => {
    editor.off('tracked-change.lifecycle', onTrackedChange);
    editor.off('comment.lifecycle', onComment);
    document.off('revision.accepted', onRevisionAccepted);
    document.off('comment.threadAdded', onCommentAdded);
  };

  try {
    editor.on('tracked-change.lifecycle', onTrackedChange);
    editor.on('comment.lifecycle', onComment);
    document.on('revision.accepted', onRevisionAccepted);
    document.on('comment.threadAdded', onCommentAdded);
    return removeListeners;
  } catch (error) {
    removeListeners();
    console.error('Failed to register review event listeners.', error);
    throw error;
  }
}

Register document listeners before you start the transaction you want to observe. A new listener uses the current document state as its baseline.

Observe editor operation phases

tracked-change.lifecycle reports create, accept, and reject operations that start in the editor. Each operation emits an attempted phase, followed by completed on success or denied on denial.

A completed create event contains revisionIds. One editor operation can create multiple revisions, so handle every ID in the array. Accept and reject events contain the target revisionId.

comment.lifecycle reports create, reply, edit, delete, resolve, and reopen operations. Comment operations emit attempted and completed phases. They don’t emit a denied phase. A denied comment attempt has no completed event.

Editor lifecycle payloads don’t include document content. They describe the operation and its phase.

Observe committed document changes

DocAuthDocument.on() observes revision and comment changes after a transaction changes the document. These events also work with the Node.js entry point because they belong to the document.

Revision events include these event names:

• revision.created
• revision.edited
• revision.accepted
• revision.rejected
• revision.withdrawn

Comment events include comment.threadAdded, comment.replied, comment.edited, comment.resolved, comment.unresolved, and comment.removed.

Document events group IDs by event type and transaction. Each RevisionEventPayload or CommentEventPayload contains ids, author, origin, and txId. The author value is null when the batch has mixed or unknown authors.

The comment.removed payload also reports reason: removed for an explicit removal, or anchor-deleted when deleting anchored content removes the comment.

Rolled-back transactions don’t emit document lifecycle events. A transaction without a document change has no revision or comment change to report.

Distinguish editor and document events

Editor lifecycle events report attempts and outcomes from the interactive editor, while document events report committed changes from editor input, programmatic transactions, and history operations.

A host-owned transaction can emit document events, but it doesn’t emit tracked-change.lifecycle or comment.lifecycle. A reviewer who rejects their own revision performs an editor reject operation. The committed document event is revision.withdrawn.

Use txId to associate document events from the same transaction. The identifier is scoped to the current document session.

Handle event origins

DocumentEventOrigin has user, programmatic, history, and remote values — remote is reserved, and current collaboration transports don’t set it.

Don’t use remote to detect changes from other collaborators. For now, origin identifies how the transaction started.

Learn more

Use these guides for related review workflows:

• Refer to the tracked changes and editor modes guide to configure editor review behavior.
• Refer to the control review permissions guide to control review permissions.
• Refer to the manage tracked changes programmatically guide to manage revisions in transactions.