# Editing sizes with the SDK

Open a size, edit it by role or ref, check and preview it, and save it, with sessions that recover for you.

This page is the SDK side of [Editing a size](https://withmestra.com/docs/api/editing-a-size/). The key needs the Designs permission (see [Authentication](https://withmestra.com/docs/api/authentication/)). The examples use a client made as in the [overview](https://withmestra.com/docs/developers/sdk/).

## Open a size

```ts
const size = await mestra.openSize("run-4f2a", "300x250");
```

The first argument is the run's id. The second is the size's key. You get a `SizeSession`. It holds:

- `elements`: what is in the design. Each has `ref`, `role`, `name`, `kind`, `kept`, `frame` and `text`. A role is lower case with words joined by `_`.
- `lastCheck`: the latest check against the design rules.
- `label`: the checkpoint the session stands on. It starts as `loaded`.
- `sceneHash`: what the next save sends as `If-Match`.
- `format`: the size's key, name, width, height and unit, when the API sends them.

Opening a size that can't be edited throws a `MestraError` with the code `not_editable`.

## Edit

```ts
const answer = await size.edit("set_text", { role: "headline", text: "Summer sale" });
if (answer.refused) {
  console.log(answer.refused, answer.detail, answer.candidates);
}
```

Name the element by `ref`, or by `role` when one element has it. If two elements have the role, you get a refusal, not a guess. `answer.candidates` lists them.

A refusal is data, not an exception. `answer.refused` is a code such as `unknown_role` or `ambiguous_role`, and is an empty string when the edit was made. `detail` and `limit` say why. A refused edit changes nothing.

Every answer also holds `elements`, `check`, `fixes`, `noChange` and `label`. `label` is the checkpoint a made edit created (`e1`, `e2` and on).

To make several edits in one request, use `editMany`. They share one checkpoint and stop at the first refusal.

```ts
const answer = await size.editMany([
  { name: "set_text", input: { role: "headline", text: "Summer sale" } },
  { name: "set_colour", input: { role: "headline", colour: "#ff0000" } },
]);
```

Some edits are for masters only. On a size, `set_role`, `set_shape` and `set_opacity` throw a `MestraError` with the code `master_only`. The text fields `verticalAlign`, `caps` and `paras` come back as a refusal. See [Editing masters](https://withmestra.com/docs/developers/sdk/editing-masters/).

## Go back

```ts
await size.undo("loaded"); // back to how it opened
```

`undo` takes `loaded`, an `e<n>` label an edit answered, `current` or `best`. It answers like an edit.

## Check and preview

```ts
const check = await size.check({ render: true });
console.log(check.check.failures, check.check.warnings);
```

`check()` judges the design against the rules. With `render: true` it is drawn as well, and the answer can add `standIns`, `lossy`, `hash` and `current`.

```ts
import {
  writeFile,
} from "node:fs/promises";

const picture = await size.preview();
await writeFile("preview.png", picture.png);
console.log(picture.width, picture.height, picture.current);
```

`preview()` answers with:

- `png`: the picture, as bytes.
- `width` and `height`.
- `check`: the check.
- `current`: false when you made an edit while it was drawn, so the picture shows an earlier state.
- `standIns`, `lossy` and `hash`.

## Use your own picture

```ts
import {
  readFile,
} from "node:fs/promises";

const bytes = new Uint8Array(await readFile("photo.png"));
const photo = await size.uploadPicture(bytes);
await size.edit("swap_picture", { role: "photo", sha256: photo.sha256 });
```

`uploadPicture` keeps the picture for the session. It works out the SHA-256 for you and reads PNG or JPEG from the bytes. You can pass the type as a second argument. The answer holds `sha256`, `mime`, `width`, `height` and `created`. `created` is false when the session or run already held the picture. The API's limits apply: see [Upload a picture](https://withmestra.com/docs/api/editing-a-size/#upload-a-picture).

## Save

```ts
const saved = await size.save();
console.log(saved.sceneHash, saved.round, saved.pull);
```

Saving is free. The answer holds `sceneHash`, `fileId`, `round`, `publications`, `pull`, `check` and `label`. The session keeps the new `sceneHash` for the next save.

Saving is safe to retry. Pass your own `idempotencyKey` and send the same one again if you lose the answer. Nothing is saved twice. If you pass none, the SDK makes a new key for each call.

```ts
await size.save({ idempotencyKey: "6f0c2a4e-8d7b-4c59-9a43-1d2b7e5f9a10" });
```

A save that can't keep the design throws a `MestraError` and saves nothing. The codes are `stand_in`, `lossy` and `cannot_draw`.

## When a session ends

A session ends after an hour unused, or if Mestra restarts. The SDK handles that for you. When a call finds the session gone, it:

1. opens the same size again;
2. checks that it is still the design you were editing;
3. replays your edits, restores and uploads since you opened or last saved;
4. tries the call again.

If someone else changed the size meanwhile, it throws `SizeChangedError` and replays nothing. Open the size again and redo your edits. If a replayed edit comes out differently, it throws `ReplayDivergedError`. Nothing is saved.

A save that finds its session gone is first tried again with the same key, because the first save may already have been recorded. Only then does it reopen and replay.

A `SessionGoneError` reaches you only if recovery itself finds the session gone.

## Errors to expect

- `SizeChangedError` (`412`, `scene_changed`): the size changed since you opened it.
- `MestraError` with `editor_busy` or `editor_unavailable`: the editor had no room. Try again shortly.
- `MestraError` with `review_moved`: a review round arrived while you saved. Save again.

See [Errors](https://withmestra.com/docs/developers/sdk/errors/) for all of them.
