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
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
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
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,readyornot_ready.pull,runsKept,ruleSets,newRuleFailures,checkandlabel.
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:mestrafor a save made here, otherwiseindesign,figma,canvaorupload.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.