Skip to content

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

TypeScript
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

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

TypeScript
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

TypeScript
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

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

TypeScript
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

TypeScript
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

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

TypeScript
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 for all of them.