JavaScript SDK
Editing sizes with the SDK
This page is the SDK side of Editing a size. The key needs the Designs permission (see Authentication). The examples use a client made as in the overview.
Open a size
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 hasref,role,name,kind,kept,frameandtext. 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 asloaded.sceneHash: what the next save sends asIf-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
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.
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.
Go back
await size.undo("loaded"); // back to how it openedundo takes loaded, an e<n> label an edit answered, current or best. It answers like an edit.
Check and preview
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.
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.widthandheight.check: the check.current: false when you made an edit while it was drawn, so the picture shows an earlier state.standIns,lossyandhash.
Use your own picture
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.
Save
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.
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:
- opens the same size again;
- checks that it is still the design you were editing;
- replays your edits, restores and uploads since you opened or last saved;
- 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.MestraErrorwitheditor_busyoreditor_unavailable: the editor had no room. Try again shortly.MestraErrorwithreview_moved: a review round arrived while you saved. Save again.
See Errors for all of them.