AttachmentsApi

The Attachments panel, headless: the document's embedded files. An attachment is addressed by its index, its position in the attachment table as list() reports it; the table is kept in name order, so read it again after an add or a delete. A viewer on the document follows each edit: its panel refreshes, it takes an undo step and fires documentChanged. The panel is described under Document features.

list() needs no feature, but without extract every name is ''; data() needs extract. add() and delete() need edit-pages. Each refuses with FEATURE_NOT_LICENSED without its feature, and the two writes refuse a certified document with INVALID_STATE unless options.invalidateSignatures.

namespacedoc.attachments

Usage

TypeScript

for (const file of await doc.attachments.list()) {
  console.log(file.index, file.name, file.size, 'bytes');
}
const index = await doc.attachments.add('invoice.csv', csvBytes);

Reading

listmethodsince 1.0.0

list(): Promise<AttachmentInfo[]>

Embedded files. Without the extract feature every name is ''. Needs no feature.

Returns Promise<AttachmentInfo[]> Each { index, name, size }: the index to pass to data() / delete(), the name as stored in the file (untrusted input), and the size in bytes (0 when the entry has no file stream).

DOCUMENT_CLOSED — the document has been closed.

TypeScript

const files = await doc.attachments.list();

datamethodsince 1.0.0

data(index: number): Promise<Uint8Array>

One attachment's bytes. Needs the extract feature.

Parameter	Type	Description
index	number	The attachment's index, as `list()` reports it.

Returns Promise<Uint8Array> The attachment's bytes.

INVALID_ARGUMENT — an index that names no attachment.
PAGE_ERROR — the entry has no file stream, or the stream exceeds the SDK's size limit for an attachment.
FEATURE_NOT_LICENSED — the license lacks extract.
DOCUMENT_CLOSED — the document has been closed.

TypeScript

const [first] = await doc.attachments.list();
if (first) {
  const bytes = await doc.attachments.data(first.index);
  saveAs(new Blob([bytes.slice()]), first.name);
}

Editing

addmethodsince 1.0.0

add(name: string, bytes: Uint8Array, options?: SignedDocumentOptions): Promise<number>

Embed a file; it is in every save and export from then on. An index shifts down when an earlier attachment is deleted. Needs the edit-pages feature.

Parameter	Type	Description
name	string	The file name to store.
bytes	Uint8Array	The file's bytes.
options?	SignedDocumentOptions	`{ invalidateSignatures? }`.

Returns Promise<number> Its index in list() (zero-based: its position in the document's table), for data() / delete().

INVALID_ARGUMENT — an empty name.
PAGE_ERROR — the file could not be embedded.
FEATURE_NOT_LICENSED — the license lacks edit-pages.
DOCUMENT_CLOSED — the document has been closed.
INVALID_STATE — a certified document, unless options.invalidateSignatures; or a progressive document still downloading.

TypeScript

const index = await doc.attachments.add('invoice.csv', csvBytes);

deletemethodsince 1.0.0

delete(index: number, options?: SignedDocumentOptions): Promise<void>

Delete an embedded file by its index; refused on a certified document the same way as add(). Needs the edit-pages feature.

Parameter	Type	Description
index	number	The attachment's index, as `list()` reports it.
options?	SignedDocumentOptions	`{ invalidateSignatures? }`.

Returns Promise<void>

INVALID_ARGUMENT — an index that names no attachment.
PAGE_ERROR — the attachment could not be removed.
FEATURE_NOT_LICENSED — the license lacks edit-pages.
DOCUMENT_CLOSED — the document has been closed.
INVALID_STATE — a certified document, unless options.invalidateSignatures; or a progressive document still downloading.

TypeScript

await doc.attachments.delete(index);