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.

Report digests identify canonical saved content, including resource bytes. Refer to the document locations guide for the separate model-only digest. Don’t compare that digest with beforeDigest or afterDigest.

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 revisions, comments, 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; it 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

Refer to these guides for related review and editing workflows:

• Programmatic editing — Run atomic document transactions and choose an editing operation.
• Programmatic tracked changes — List, accept, reject, and withdraw revisions.