DocAuthDocument

DocAuthDocument:

{
  getParticipant(): Participant;
  setParticipant(participant: Participant): void;
  saveDocument(): Promise<object>;
  saveDocumentJSONString(options?: SaveDocumentJSONStringOptions): Promise<string>;
  exportPDF(options?: ExportPDFOptions): Promise<ArrayBuffer>;
  exportDOCX(options?: ExportDOCXOptions): Promise<ArrayBuffer>;
  export(config: ExportConfig): Promise<ArrayBuffer>;
  updateFields(): Promise<void>;
  transaction(callback: TransactionCallback<T>, options?: TransactionOptions): Promise<T>;
  transactionWithReport(callback: TransactionCallback<T>, options?: TransactionOptions): Promise<TransactionWithReportResult<T>>;
  docAuthSystem(): DocAuthSystem;
  on(event: EventName, handler: (payload: EventPayload) => void): DocAuthDocument;
  off(event: EventName, handler?: (payload: EventPayload) => void): DocAuthDocument;
  once(event: EventName, handler: (payload: EventPayload) => void): DocAuthDocument;
}

A document instance. Holds the content and provides methods for saving, exporting to PDF/DOCX, and more.

Create documents via DocAuthEditor and/or DocAuthSystem.

Methods

getParticipant()

>= v1.20.0

getParticipant(): Participant

Returns the participant currently acting on this document.

The participant determines whether programmatic transactions and editor input may mutate or adjudicate the document. The author is only a label; hosts must bind participants to authenticated users themselves because the SDK does not authenticate.

Returns

Participant

setParticipant()

>= v1.20.0

setParticipant(participant): void

Sets the participant that acts on subsequent programmatic transactions and editor input for this document.

Owners have full access. Reviewers may create tracked changes and comments and withdraw their own pending suggestions, but may not accept or reject suggestions or make untracked content changes. Readers are read-only. The author is only a label; hosts must bind participants to authenticated users themselves because the SDK does not authenticate.

Parameters

participant

Participant

Returns

void

saveDocument()

saveDocument(): Promise<object>

Returns the current document in the Document Authoring format as a JavaScript object. This object can be safely persisted.

Returns

Promise<object>

See

DocJSON guide

saveDocumentJSONString()

>= v1.20.0

saveDocumentJSONString(options?): Promise<string>

Returns the current document in the Document Authoring format as a JSON string. This string can be safely persisted.

Pass { canonical: true } to return the canonical DocJSON string used as the content identity for transaction report digests. Omitting the option preserves the existing JSON string output.

Parameters

options?

SaveDocumentJSONStringOptions

Optional JSON serialization options.

Returns

Promise<string>

See

exportPDF()

exportPDF(options?): Promise<ArrayBuffer>

Exports a snapshot of the current document as a PDF file.

Parameters

exportDOCX()

exportDOCX(options?): Promise<ArrayBuffer>

Exports a snapshot of the current document as a DOCX file.

Parameters

options?

ExportDOCXOptions

Returns

Promise<ArrayBuffer>

See

DOCX export guide

export()

>= v1.12.0

export(config): Promise<ArrayBuffer>

Exports a snapshot of the current document in the specified format.

Parameters

config

ExportConfig

Returns

Promise<ArrayBuffer>

See

ExportConfig

updateFields()

NEW

updateFields(): Promise<void>

Updates every field in the document, as Word does when all fields are selected and updated: each table of contents is regenerated, and each page reference, text reference, page number and page count in the main text is recomputed from where the document’s content lands.

Returns

Promise<void>

Remarks

Fields store the value they show, so it can go stale as the document changes; this recomputes them, overwriting values edited by hand. It waits for the document to be laid out completely, and repeats when updating a table of contents moves headings to other pages, at most three times. In the editor the whole update is one undo step. Page numbers and page counts in headers and footers are computed for every page as it is drawn and need no update.

The update is not tracked, so only an owner may run it: for a reviewer or a reader it rejects with a NotPermittedError and changes nothing. Collaborative documents also require a connection for this explicit update.

transaction()

>= v1.10.0

transaction<T>(callback, options?): Promise<T>

Executes a transaction to programmatically read or modify the document.

Type Parameters

T

T = void

Parameters

callback

TransactionCallback<T>

A TransactionCallback function that receives a draft document

options?

>= v1.14.0

TransactionOptions

Transaction options.

Returns

Promise<T>

A Promise that resolves to the result value from the callback

Remarks

Provides programmatic access to the document structure through a draft document that can be read and modified. Changes are atomic and isolated until the transaction commits. In a collaborative document, structural edits, revision decisions, field updates and comments require a connection. Otherwise the transaction rejects with a NotPermittedError and none of its changes commit.

The callback executes after all pending transactions and input have been processed. While the callback runs, document access is blocked, preventing any UI interactions until the transaction completes.

Example

await doc.transaction(async ({ draft }) => {
  const section = draft.body().sections()[0];
  const para = section.content().addParagraph();
  para.asTextView().setText('Hello, World!');
  return { commit: true };
});

See

TransactionCallback for the callback function signature
TransactionResult for return value options
Programmatic for the full programmatic API namespace

transactionWithReport()

>= v1.20.0

transactionWithReport<T>(callback, options?): Promise<TransactionWithReportResult<T>>

Executes a document transaction and returns its callback result with a verifiable report.

Type Parameters

T

T = void

Parameters

callback

TransactionCallback<T>

A TransactionCallback function that receives a draft document.

options?

TransactionOptions

Transaction options.

Returns

Promise<TransactionWithReportResult<T>>

The callback result and transaction report.

Remarks

The report’s beforeDigest and afterDigest identify the document’s canonical DocJSON content, including its model and resources. To verify a saved document, hash the exact string returned by saveDocumentJSONString({ canonical: true }) with SHA-256.

Report generation is opt-in because it serializes and hashes the document before and after the transaction. DocAuthDocument.transaction remains digest-free. Report txId values are scoped to the current document session and are not stable across sessions.

docAuthSystem()

docAuthSystem(): DocAuthSystem

The DocAuthSystem this document is bound to.

Returns

DocAuthSystem

on()

>= v1.20.0

on(event, handler): DocAuthDocument

Adds an event listener that will be called every time the specified document event is emitted.

The document starts tracking events when its first listener is added and stops after its last listener is removed. Adding a listener later uses the current document state as the new baseline.

Parameters

event

EventName

handler

(payload: EventPayload) => void

Returns

DocAuthDocument

The document instance for method chaining.

Example

document
  .on('revision.accepted', ({ ids, origin }) => {
    console.log('Accepted revisions', ids, origin);
  })
  .on('content.change', () => console.log('Document changed'));

Available Events

Event name	Event payload	Description
`revision.created`	`RevisionEventPayload`	Fired when one or more tracked-change revisions are created.
`revision.edited`	`RevisionEventPayload`	Fired when one or more existing tracked-change revisions are edited.
`revision.accepted`	`RevisionEventPayload`	Fired when one or more tracked-change revisions are accepted.
`revision.rejected`	`RevisionEventPayload`	Fired when one or more tracked-change revisions are rejected.
`revision.withdrawn`	`RevisionEventPayload`	Fired when one or more tracked-change revisions are withdrawn.
`comment.threadAdded`	`CommentEventPayload`	Fired when one or more comment threads are added.
`comment.replied`	`CommentEventPayload`	Fired when one or more replies are added to comment threads.
`comment.edited`	`CommentEventPayload`	Fired when the text of one or more comments or replies is edited.
`comment.resolved`	`CommentEventPayload`	Fired when one or more comment threads are resolved.
`comment.unresolved`	`CommentEventPayload`	Fired when one or more comment threads are marked unresolved.
`comment.removed`	`CommentEventPayload & { reason: “removed"	"anchor-deleted” }`
`content.change`	none	Fired after every committed transaction following document initialization.

off()

>= v1.20.0

off(event, handler?): DocAuthDocument

Removes a document event listener. If no handler is provided, removes all listeners for the event.

Parameters

event

EventName

handler?

(payload: EventPayload) => void

Returns

DocAuthDocument

The document instance for method chaining.

Example

const handleAccepted = ({ ids }: RevisionEventPayload) => console.log(ids);
document.on('revision.accepted', handleAccepted);

// Remove one handler.
document.off('revision.accepted', handleAccepted);

// Remove every handler for this event.
document.off('revision.accepted');

Available Events

Event name	Event payload	Description
`revision.created`	`RevisionEventPayload`	Fired when one or more tracked-change revisions are created.
`revision.edited`	`RevisionEventPayload`	Fired when one or more existing tracked-change revisions are edited.
`revision.accepted`	`RevisionEventPayload`	Fired when one or more tracked-change revisions are accepted.
`revision.rejected`	`RevisionEventPayload`	Fired when one or more tracked-change revisions are rejected.
`revision.withdrawn`	`RevisionEventPayload`	Fired when one or more tracked-change revisions are withdrawn.
`comment.threadAdded`	`CommentEventPayload`	Fired when one or more comment threads are added.
`comment.replied`	`CommentEventPayload`	Fired when one or more replies are added to comment threads.
`comment.edited`	`CommentEventPayload`	Fired when the text of one or more comments or replies is edited.
`comment.resolved`	`CommentEventPayload`	Fired when one or more comment threads are resolved.
`comment.unresolved`	`CommentEventPayload`	Fired when one or more comment threads are marked unresolved.
`comment.removed`	`CommentEventPayload & { reason: “removed"	"anchor-deleted” }`
`content.change`	none	Fired after every committed transaction following document initialization.

once()

>= v1.20.0

once(event, handler): DocAuthDocument

Adds an event listener that will be called only once when the specified document event is emitted. The listener is automatically removed after being called.

Parameters

event

EventName

handler

(payload: EventPayload) => void

Returns

DocAuthDocument

The document instance for method chaining.

Example

document.once('comment.threadAdded', ({ ids }) => {
  console.log('First added comment thread', ids);
});

Available Events

Event name	Event payload	Description
`revision.created`	`RevisionEventPayload`	Fired when one or more tracked-change revisions are created.
`revision.edited`	`RevisionEventPayload`	Fired when one or more existing tracked-change revisions are edited.
`revision.accepted`	`RevisionEventPayload`	Fired when one or more tracked-change revisions are accepted.
`revision.rejected`	`RevisionEventPayload`	Fired when one or more tracked-change revisions are rejected.
`revision.withdrawn`	`RevisionEventPayload`	Fired when one or more tracked-change revisions are withdrawn.
`comment.threadAdded`	`CommentEventPayload`	Fired when one or more comment threads are added.
`comment.replied`	`CommentEventPayload`	Fired when one or more replies are added to comment threads.
`comment.edited`	`CommentEventPayload`	Fired when the text of one or more comments or replies is edited.
`comment.resolved`	`CommentEventPayload`	Fired when one or more comment threads are resolved.
`comment.unresolved`	`CommentEventPayload`	Fired when one or more comment threads are marked unresolved.
`comment.removed`	`CommentEventPayload & { reason: “removed"	"anchor-deleted” }`
`content.change`	none	Fired after every committed transaction following document initialization.