Skip to content

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

TypeScript
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

TypeScript
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, and WaitTimeoutError has its id in operation.
  • onProgress: called with every snapshot, the first included. A snapshot has status (running or done), done, total, results and, for an operation, operation and kind (edit or save).

To follow it yourself, use the first answer and then watch:

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