Skip to content

JavaScript SDK

Editing masters with the SDK

This page is the SDK side of Editing a master. A master session works like a size session: 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

TypeScript
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

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

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

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