# Editing masters with the SDK

Open a master, make master-only edits, upload a picture and save the next version, and handle a newer version.

This page is the SDK side of [Editing a master](https://withmestra.com/docs/api/editing-a-master/). A master session works like a [size session](https://withmestra.com/docs/developers/sdk/editing-sizes/): `edit`, `editMany`, `undo`, `check`, `preview`, `uploadPicture` and `save` are the same calls. This page covers what differs. The key needs the Designs permission.

## Open a master

```ts
const master = await mestra.openMaster("5625b1a8-2f39-4f06-9ede-73ccdcbc04c3");
const older = await mestra.openMaster("5625b1a8-2f39-4f06-9ede-73ccdcbc04c3", { version: 3 });
```

With no option, you get the latest version. A `MasterSession` also holds `master` (its id, version, latest, name, source app, brand and whether its app can pull changes), `version`, `ifMatch`, `ruleSets` and `copyOverrides`.

## Master-only edits

```ts
await master.edit("set_role", { ref: "tagline", role: "subhead" });
await master.edit("set_opacity", { role: "headline", opacity: 0.9 });
```

`set_role`, `set_shape` and `set_opacity` are for masters only. So are `verticalAlign`, `caps` and `paras` on text. On a size, the first three throw a `MestraError` with the code `master_only`, and the others come back as a refusal. The API guide lists the fields of each.

Master-only edits are not part of [editing many sizes](https://withmestra.com/docs/developers/sdk/many-sizes/).

## Use your own picture

`master.uploadPicture(bytes)` works as on a size. The session holds the picture until you save, and the save keeps it as the picture's new original. If the session ends first, the picture is dropped.

## Save

```ts
import {
  VersionChangedError,
} from "@withmestra/sdk";

try {
  const saved = await master.save();
  console.log(saved.version, saved.status, saved.unchanged);
} catch (e) {
  if (e instanceof VersionChangedError) {
    // Someone, or an app, saved version e.latest since you opened.
    console.log(`Version ${e.latest} was saved by ${e.byName || e.by}`);
  } else throw e;
}
```

A save makes the master's next version. The answer holds:

- `version`: the new version number.
- `ifMatch`: the number for the next save. The session keeps it for you.
- `unchanged`: true, with no new version, when the edits left the master as it was.
- `status`: `checking`, `ready` or `not_ready`.
- `pull`, `runsKept`, `ruleSets`, `newRuleFailures`, `check` and `label`.

The SDK sends the version number as `If-Match`. `save` takes an `idempotencyKey`, as on a size.

## When there is a newer version

If the master has a newer version than the one you opened, `save` throws `VersionChangedError` (`412`, `version_changed`). Nothing is written. It has:

- `latest`: the newer version's number.
- `by`: `mestra` for a save made here, otherwise `indesign`, `figma`, `canva` or `upload`.
- `byName`: who saved it, for a save made here. It is empty for an app's save, and for a key without the Team · Read permission.

Open the master again and redo your edits.

## A lost session

Recovery works as for a size. It reopens the same version by number, never `latest`, and replays your edits. It never moves `ifMatch` forward, so a newer version still gets its `412` at save.
