Create transaction reports

Use DocAuthDocument.transactionWithReport() to verify document content before and after a transaction. The method returns the callback result and a TransactionReport.

The report contains canonical content digests and a typed change list. It doesn’t replace the document or save it to storage.

Create and verify a report

The following Node.js example imports review.docx, adds a paragraph, and verifies the report’s afterDigest. It hashes the exact string returned by saveDocumentJSONString({ canonical: true }).

import { createHash } from 'node:crypto';
import { readFile } from 'node:fs/promises';
import { createDocAuthSystem } from '@nutrient-sdk/document-authoring/node';

async function addReviewSummary() {
  const system = await createDocAuthSystem();

  try {
    const input = await readFile('review.docx');
    const document = await system.import(input, { format: 'docx' });

    const { result, report } = await document.transactionWithReport(async ({ draft }) => {
      const paragraph = draft.body().content().addParagraph();
      paragraph.asTextView().setText('Review completed.');

      return {
        commit: true,
        result: { addedParagraph: true },
      };
    });

    const canonical = await document.saveDocumentJSONString({ canonical: true });
    const actualDigest = createHash('sha256').update(canonical, 'utf8').digest('hex');

    if (actualDigest !== report.afterDigest) {
      throw new Error('The saved document does not match the transaction report.');
    }

    console.log(JSON.stringify({ result, report, verified: true }, null, 2));
    return { result, report };
  } catch (error) {
    console.error('Failed to create or verify the transaction report.', error);
    throw error;
  } finally {
    system.destroy();
  }
}

await addReviewSummary();

The command prints verified: true when the canonical document matches report.afterDigest. The report also includes these values:

• The beforeDigest value identifies the canonical document before the transaction.
• The afterDigest value identifies the canonical document after the transaction.
• The changes value lists revision, comment, and direct changes from the committed transaction.
• The txId value identifies the transaction within the current document session.
• The authorLabel value contains the author label supplied by the host.

Use reports only when needed

Report generation is opt-in. transactionWithReport() serializes and hashes canonical document content to produce before and after digests. For unchanged snapshots, it reuses the before digest as the after digest.

Use transaction() when the workflow doesn’t need those digests. This method doesn’t create digests and returns only the callback result.

Keep each report with its transaction

A report describes one transaction. It doesn’t compare arbitrary document versions or provide a complete history across sessions.

No-op and rolled-back transactions have matching beforeDigest and afterDigest values. A committed transaction can also have matching digests when it doesn’t change canonical content.

Treat author labels as metadata

Transaction reports are unsigned. A digest verifies canonical document content, but it doesn’t prove who created or approved that content.

The host supplies authorLabel. To verify who made or approved a change, associate the label with an authenticated user and their permissions in your application.

Learn more

Use these guides for related review and editing workflows:

• Refer to the programmatic editing guide to run atomic document transactions and choose an editing operation.
• Refer to the programmatic tracked changes guide to list, accept, reject, and withdraw revisions.