JavaScript SDK
Editing many sizes with the SDK
This page is the SDK side of Edit many sizes at once. The key needs the Designs permission. Only sizes work this way: a master is saved with its own save().
Edit
const edited = await mestra.editSizes( { campaign: "winter-sale", sizes: "all", // or ["300x250", "728x90"] edit: { name: "set_text", input: { role: "headline", text: "Book now" } }, }, { onProgress: (p) => console.log(`${p.done} of ${p.total}`) },);
for (const r of edited.results) { if (r.outcome === "refused") console.log(r.size, r.refused, r.candidates);}The request takes campaign, sizes (a list of size keys, or "all"), edit, and optionally centres and idempotencyKey. Nothing is saved yet.
Each result has an outcome: applied, no_change, refused, not_editable, busy or failed. A busy size can be tried again. A failed one carries status and code. One size failing does not affect the others.
A result that has a session also has editSession. It is a normal size session, so you can preview it or edit it further. Its elements list is empty until your next edit on it.
Save
const keep = edited.results.flatMap((r) => (r.editSession ? [r.editSession] : []));const saved = await mestra.saveSizes(keep);
for (const r of saved.results) { console.log(r.session, r.outcome, r.code);}saveSizes takes size sessions only. Passing a master session throws a TypeError. Each save stands on its own and is saved or failed. A failed result carries the status and code a single save would have thrown. A save that worked also updates that session’s sceneHash.
It takes an idempotencyKey in its options. With a key, sending the same request again gives the first call’s result.
Waiting
The server answers at once when every size is done within ten seconds. Otherwise it gives you an operation, and the work goes on. editSizes and saveSizes wait for you and give the same answer either way. They read the operation until it is done. Options:
pollIntervalMs: how long between reads. The default is 1000.timeoutMs: how long to wait. The default is 600000, ten minutes. If you stop waiting, the operation carries on, andWaitTimeoutErrorhas its id inoperation.onProgress: called with every snapshot, the first included. A snapshot hasstatus(runningordone),done,total,resultsand, for an operation,operationandkind(editorsave).
To follow it yourself, use the first answer and then watch:
const first = await mestra.startEditSizes({ campaign: "winter-sale", sizes: "all", edit: { name: "set_text", input: { role: "headline", text: "Book now" } },});
for await (const p of mestra.watchSizes(first, { pollIntervalMs: 2000 })) { console.log(p.kind, `${p.done} of ${p.total}`);}startSaveSizes(sessions) is the same for a save. getSizesOperation(id) reads an operation once. watchSizes takes pollIntervalMs, timeoutMs and onProgress too. Results from these calls are plain data, with no editSession.
One at a time
A user’s change across sizes runs one at a time. Another editSizes or saveSizes while one runs throws SizesBusyError (409, sizes_busy). Wait for the first to finish, then try again. Only the person who started an operation can read it. Anyone else, or an operation that has ended, gets OperationGoneError (404, operation_gone).