# 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`](https://kernstra.com/docs/web-sdk/api/events#ev-documentchanged). The panel is described under [Document features](https://kernstra.com/docs/web-sdk/guides/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`.

- Kind: namespace
- Access: `doc.attachments`

## Usage

```ts
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

### `list`

```ts
list(): Promise<AttachmentInfo[]>
```

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

- Kind: method
- Since: 1.0.0

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).

Throws:

- `DOCUMENT_CLOSED` — the document has been closed.

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

Page: https://kernstra.com/docs/web-sdk/api/doc-attachments/list

### `data`

```ts
data(index: number): Promise<Uint8Array>
```

One attachment's bytes. Needs the `extract` feature.

- Kind: method
- Since: 1.0.0

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

Returns `Promise<Uint8Array>`: The attachment's bytes.

Throws:

- `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.

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

Page: https://kernstra.com/docs/web-sdk/api/doc-attachments/data

## Editing

### `add`

```ts
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.

- Kind: method
- Since: 1.0.0

| 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()`.

Throws:

- `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.

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

Page: https://kernstra.com/docs/web-sdk/api/doc-attachments/add

### `delete`

```ts
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.

- Kind: method
- Since: 1.0.0

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

Returns `Promise<void>`

Throws:

- `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.

```ts
await doc.attachments.delete(index);
```

Page: https://kernstra.com/docs/web-sdk/api/doc-attachments/delete

Web page: https://kernstra.com/docs/web-sdk/api/doc-attachments