@withmestra/sdk 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# @withmestra/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A TypeScript client for Mestra's public API, with a helper for editing designs: open a size or a master, change it by role (the headline, the button), look at the result, and save. Drawing is always done by Mestra's servers: this package never draws anything, it sends your edits and brings back the picture.
+
+## Install
+
+```sh
+npm install @withmestra/sdk
+```
+
+It needs an API key (they start `ptk_`) with the Designs permission, made in Settings, then API. It runs in Node 20 or later and in browsers.
+
+```ts
+import { createMestra } from "@withmestra/sdk";
+
+const mestra = createMestra({ token: process.env.MESTRA_KEY! });
+```
+
+`createMestra` also takes `baseUrl` (default `https://app.withmestra.com`) and `fetch`. `mestra.api` is a typed client for every other call in the API (`mestra.api.GET("/api/v1/campaigns", ...)`), made from the same OpenAPI file as the reference.
+
+## Edit a size
+
+```ts
+// The run's id and the size's key (from the run, or from mestra.editable(runId)).
+const size = await mestra.openSize("run-4f2a", "300x250");
+
+// Name the element by what it is. If two elements have the role you get a refusal, not a guess.
+const answer = await size.edit("set_text", { role: "headline", text: "Summer sale, this week" });
+if (answer.refused) {
+  console.log(answer.refused, answer.detail, answer.candidates); // nothing was changed
+}
+
+const picture = await size.preview();           // { png, width, height, check, current }
+await fs.writeFile("preview.png", picture.png);
+
+await size.undo("loaded");                      // back to how it opened
+await size.edit("set_text", { role: "headline", text: "Summer sale" });
+const saved = await size.save();                // free; joins the run's review
+console.log(saved.sceneHash, saved.round);
+```
+
+- `size.elements` lists what is in the design (`ref`, `role`, `name`, `kind`, `kept`, `frame`, `text`). A role is lower case with words joined by `_`.
+- `size.editMany([{ name, input }, ...])` makes several edits in one request.
+- `size.uploadPicture(bytes)` keeps a picture for the session; then `size.edit("swap_picture", { role: "photo", sha256: picture.sha256 })`.
+- `size.check({ render: true })` judges the drawing against the rules.
+- `save()` is safe to retry: pass your own `idempotencyKey` and send the same one again if you lost the answer. Nothing is saved twice.
+
+### A lost session
+
+A session ends after an hour unused, or if Mestra restarts. The helper handles that for you: it opens the same size again, checks it is still the design you were editing, replays your edits, and retries the call. If the size was changed by someone else meanwhile it throws `SizeChangedError` and replays nothing; if a replayed edit comes out differently it throws `ReplayDivergedError`. A save that finds its session gone is tried again with the same key first, because the first save may already have been recorded.
+
+## Edit a master
+
+```ts
+import { VersionChangedError } from "@withmestra/sdk";
+
+const master = await mestra.openMaster("5625b1a8-2f39-4f06-9ede-73ccdcbc04c3"); // the latest, or { version: 3 }
+
+await master.edit("set_role", { ref: "tagline", role: "subhead" });
+await master.edit("set_opacity", { role: "headline", opacity: 0.9 });
+
+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. Open it again and redo the edits.
+    console.log(`Version ${e.latest} was saved by ${e.byName || e.by}`);
+  } else throw e;
+}
+```
+
+A master's save sends the version number as `If-Match`; the session keeps it for you, and moves it on after each save. Reopening a lost session never moves it forward, so a newer version still gets its 412. `set_role`, `set_shape`, `set_opacity`, and `verticalAlign`, `caps` and `paras` on text are for masters only; on a size the first three throw a `MestraError` with code `master_only`, and the others come back as a refusal.
+
+## Edit many sizes at once
+
+```ts
+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);
+}
+
+// Look at the sizes you want (r.editSession is a normal size session), then save them.
+const keep = edited.results.flatMap((r) => (r.editSession ? [r.editSession] : []));
+const saved = await mestra.saveSizes(keep);
+```
+
+The server answers at once when everything is done within ten seconds; otherwise it gives you an operation and the work goes on. `editSizes` and `saveSizes` poll for you and give the same answer either way. Options: `pollIntervalMs` (default 1000), `timeoutMs` (default 600000, ten minutes; the operation carries on if you stop waiting, and `WaitTimeoutError` names it), and `onProgress`. To follow it yourself, use `startEditSizes` / `startSaveSizes` for the first answer and `for await (const p of mestra.watchSizes(first)) ...` for each step. Only size sessions can be saved this way; save a master with `master.save()`.
+
+An elements list is not returned for a session made by `editSizes`: it fills in with your next edit.
+
+## Errors
+
+A refusal of an edit is not an error. The API answers it with `200`, and you read it on the answer: `refused` is a code (empty when the edit was made), with `detail`, `limit` and, for a role, `candidates`. Everything else is thrown as a `MestraError` with `status`, `code`, `field` and `details` (the rest of the body, such as `limit` or `max`).
+
+| Answer | Where you see it |
+|---|---|
+| `200` with `refused` set: `unknown_role`, `ambiguous_role` (with `candidates`), `bad-number`, `style-refused`, `unknown-ref`, `bad-input` (`master_only:` in `detail` for master fields on a size), others | Data on the answer of `edit`, `editMany`, `undo` |
+| `outcome: "refused"`, `"not_editable"`, `"busy"`, `"failed"` on one size of an edit across sizes; `outcome: "failed"` with `status` and `code` on one size of a save | Data on that size's result |
+| `404` `session_gone` | Recovered by the helper; `SessionGoneError` only if recovery itself finds it gone |
+| `412` `scene_changed` (size changed since opened), or the reopened size differs | `SizeChangedError` |
+| `412` `version_changed` (master has a newer version) | `VersionChangedError` with `latest`, `by`, `byName` |
+| Replayed edit answered a different checkpoint | `ReplayDivergedError` |
+| `409` `sizes_busy` | `SizesBusyError` |
+| `404` `operation_gone` | `OperationGoneError` |
+| Waited longer than `timeoutMs` | `WaitTimeoutError` (`operation`) |
+| `409` `idempotency_conflict` (key used for a different save or edit), `review_moved` (save again) | `MestraError` |
+| `409` `not_editable`, `library_off`, `api_off` | `MestraError` |
+| `400` `master_only` (a master edit on a size, or across sizes), `if_match`; `400` with `field` `name`, `edits`, `X-Mestra-Edit-Session`, `idempotencyKey`, `campaign`, `sizes`, `edit.name` | `MestraError` |
+| `400` picture codes `picture_sum`, `picture_empty`, `picture_short`, `picture_size`, `image_too_large` (`limit`); `411` `picture_length`; `413` `picture_too_big` (`max`); `415` `picture_type`; `422` `run_images_full` (`max`); `429` | `MestraError` |
+| `422` `stand_in`, `lossy`, `cannot_draw` on save (nothing saved) | `MestraError` |
+| `428` `if_match_required` | `MestraError` |
+| `401` `invalid_token`; `403` `wrong_key` (key lacks Designs · Read or Write) | `MestraError` |
+| `404` `campaign_not_found`, `not_editable`, `headless_off`; `404` for a run or size that does not exist | `MestraError` |
+| `502` `render_failed`; `503` `editor_unavailable`, `editor_busy` (retry shortly) | `MestraError` |
+
+## Types
+
+`src/v1.d.ts` is generated from the OpenAPI file; `paths`, `components` and `operations` are exported. The package follows version 1 of the API: new fields can appear, so read defensively.

package/dist/edit.d.ts

@@ -0,0 +1,146 @@
+import { Transport } from "./http.js";
+import type { CheckAnswer, Edit, EditAnswer, EditCheck, EditElement, FormatInfo, MasterInfo, MasterSaveAnswer, Picture, Preview, SizeSaveAnswer } from "./types.js";
+type LogEntry = {
+    kind: "apply";
+    body: Record<string, unknown>;
+    label: string;
+} | {
+    kind: "restore";
+    asked: string;
+    label: string;
+} | {
+    kind: "upload";
+    bytes: Uint8Array;
+    mime: string;
+    sha256: string;
+};
+/**
+ * What a size session and a master session share: the op log, recovery from a lost session, and the calls.
+ *
+ * The log keeps what changed the design since the session opened (edits that made a checkpoint, restores and
+ * uploads). When the server forgets the session (404 `session_gone`) the helper opens it again, checks it is the
+ * same design, replays the log, and retries the call. It never replays onto a design that has changed.
+ */
+export declare abstract class EditSession<Saved> {
+    protected readonly transport: Transport;
+    /** The session id. It changes when a lost session is reopened. */
+    id: string;
+    elements: EditElement[];
+    /** The latest check of the design rules the session has seen. Call `check()` for a fresh one. */
+    lastCheck: EditCheck;
+    /** The checkpoint the session stands on. */
+    label: string;
+    abstract readonly kind: "size" | "master";
+    protected log: LogEntry[];
+    protected constructor(transport: Transport, open: {
+        id: string;
+        elements: EditElement[];
+        check: EditCheck;
+        label: string;
+    });
+    /** What `If-Match` carries on the next save. */
+    protected abstract ifMatchHeader(): string;
+    /** Opens the same design again on a new session and answers its id. Throws SizeChangedError if it differs. */
+    protected abstract reopen(): Promise<string>;
+    /** Takes what a save answered. */
+    protected abstract saved(answer: Record<string, unknown>): Saved;
+    private sendEdit;
+    private absorb;
+    protected replay(id: string): Promise<void>;
+    private diverged;
+    private recover;
+    /** Runs a call; if the session is gone, recovers it and runs the call once more. */
+    protected call<T>(fn: () => Promise<T>): Promise<T>;
+    /** Makes one edit. A refusal comes back as `answer.refused`, with nothing applied. */
+    edit(name: string, input?: Record<string, unknown>): Promise<EditAnswer>;
+    /** Makes several edits in one request. They share one checkpoint and stop at the first refusal. */
+    editMany(edits: Edit[]): Promise<EditAnswer>;
+    private apply;
+    /** Puts the session back on a checkpoint: `loaded`, an `e<n>` label an edit answered, `current` or `best`. */
+    undo(label: string): Promise<EditAnswer>;
+    /** Checks the design against the rules. With `render` it is also drawn and judged. */
+    check(o?: {
+        render?: boolean;
+    }): Promise<CheckAnswer>;
+    /** Draws the design as it stands. Mestra's servers draw it; nothing is drawn here. */
+    preview(): Promise<Preview>;
+    /** Keeps a picture for the session; then `edit("swap_picture", {ref, sha256})`. Works on a size and on a master. */
+    uploadPicture(bytes: Uint8Array, mime?: "image/png" | "image/jpeg"): Promise<Picture>;
+    /**
+     * Saves the design. The key makes the save safe to retry: pass your own and send the same one again if an answer
+     * is lost, and nothing is saved twice. If the session has ended the save is first tried again with the same key
+     * (the server may have recorded it); only then is the session reopened, checked and replayed, and the save made.
+     */
+    save(o?: {
+        idempotencyKey?: string;
+    }): Promise<Saved>;
+}
+/** One size of a run, open for editing. */
+export declare class SizeSession extends EditSession<SizeSaveAnswer> {
+    readonly kind = "size";
+    /** The run's id (the `{id}` of the run). */
+    readonly runId: string;
+    /** The size's key. */
+    readonly size: string;
+    /** The hash the log is built on, and what the next save sends as `If-Match`. */
+    sceneHash: string;
+    format: FormatInfo | undefined;
+    constructor(transport: Transport, runId: string, size: string, open: {
+        id: string;
+        elements: EditElement[];
+        check: EditCheck;
+        label: string;
+        sceneHash: string;
+        format?: FormatInfo;
+    });
+    /** A session `editSizes` opened and edited for you: the edit it made is in the log so recovery keeps it. */
+    static fromBatch(transport: Transport, r: {
+        run: string;
+        size: string;
+        session: string;
+        sceneHash: string;
+        label?: string;
+        check?: EditCheck;
+        elements?: EditElement[];
+    }, edit: {
+        name: string;
+        input?: Record<string, unknown>;
+    }): SizeSession;
+    protected ifMatchHeader(): string;
+    protected reopen(): Promise<string>;
+    protected saved(a: Record<string, unknown>): SizeSaveAnswer;
+    /** After a save made across sizes. */
+    markSaved(sceneHash: string): void;
+}
+/** One version of a master, open for editing. */
+export declare class MasterSession extends EditSession<MasterSaveAnswer> {
+    readonly kind = "master";
+    readonly masterId: string;
+    /** The version the session stands on: the one opened, then the one the last save made. Recovery reopens it. */
+    version: number;
+    /** What the next save sends as `If-Match`. Only a save moves it, never a reopen. */
+    ifMatch: number;
+    master: MasterInfo;
+    ruleSets: unknown[];
+    copyOverrides: Record<string, number>;
+    constructor(transport: Transport, open: {
+        id: string;
+        elements: EditElement[];
+        check: EditCheck;
+        label: string;
+        master: MasterInfo;
+        ifMatch: number;
+        ruleSets: unknown[];
+        copyOverrides: Record<string, number>;
+    });
+    protected ifMatchHeader(): string;
+    protected reopen(): Promise<string>;
+    protected saved(a: Record<string, unknown>): MasterSaveAnswer;
+}
+/** Opens one size of a run for editing. */
+export declare function openSize(t: Transport, runId: string, size: string): Promise<SizeSession>;
+/** Opens a master for editing: `version` is a number, or the latest by default. */
+export declare function openMaster(t: Transport, masterId: string, o?: {
+    version?: number | "latest";
+}): Promise<MasterSession>;
+export {};

package/dist/edit.js

@@ -0,0 +1,344 @@
+import { sessionHeader } from "./http.js";
+import { ReplayDivergedError, SessionGoneError, SizeChangedError } from "./errors.js";
+/** A check with nothing in it, for a session built before its first check. */
+const emptyCheck = () => ({ failures: [], warnings: [], objective: 0 });
+function answerOf(body) {
+    return {
+        elements: [],
+        fixes: [],
+        carried: {},
+        check: emptyCheck(),
+        refused: "",
+        detail: "",
+        limit: null,
+        noChange: false,
+        label: "",
+        ...body,
+    };
+}
+function randomKey() {
+    return globalThis.crypto.randomUUID();
+}
+async function sha256Hex(bytes) {
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+    return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function sniffMime(bytes) {
+    if (bytes[0] === 0xff && bytes[1] === 0xd8)
+        return "image/jpeg";
+    return "image/png";
+}
+function fromBase64(data) {
+    const raw = atob(data);
+    const out = new Uint8Array(raw.length);
+    for (let i = 0; i < raw.length; i++)
+        out[i] = raw.charCodeAt(i);
+    return out;
+}
+/**
+ * What a size session and a master session share: the op log, recovery from a lost session, and the calls.
+ *
+ * The log keeps what changed the design since the session opened (edits that made a checkpoint, restores and
+ * uploads). When the server forgets the session (404 `session_gone`) the helper opens it again, checks it is the
+ * same design, replays the log, and retries the call. It never replays onto a design that has changed.
+ */
+export class EditSession {
+    transport;
+    /** The session id. It changes when a lost session is reopened. */
+    id;
+    elements;
+    /** The latest check of the design rules the session has seen. Call `check()` for a fresh one. */
+    lastCheck;
+    /** The checkpoint the session stands on. */
+    label;
+    log = [];
+    constructor(transport, open) {
+        this.transport = transport;
+        this.id = open.id;
+        this.elements = open.elements;
+        this.lastCheck = open.check;
+        this.label = open.label;
+    }
+    async sendEdit(path, json, id = this.id) {
+        return this.transport.send("POST", path, { headers: { [sessionHeader]: id }, json });
+    }
+    absorb(a) {
+        if (a.check && Object.keys(a.check).length > 0)
+            this.lastCheck = a.check;
+        if (a.label)
+            this.label = a.label;
+        // A refusal carries no copy, so its elements would blank the text we hold.
+        if (a.refused === "" && a.elements.length > 0)
+            this.elements = a.elements;
+    }
+    async replay(id) {
+        for (const e of this.log) {
+            if (e.kind === "apply") {
+                const a = answerOf((await this.sendEdit("/api/v1/edit/apply", e.body, id)).body);
+                if (a.label !== e.label)
+                    this.diverged(e.label, a.label);
+            }
+            else if (e.kind === "restore") {
+                const a = answerOf((await this.sendEdit("/api/v1/edit/restore", { label: e.asked }, id)).body);
+                if (a.label !== e.label)
+                    this.diverged(e.label, a.label);
+            }
+            else {
+                await this.transport.send("PUT", `/api/v1/edit/assets/${e.sha256}`, {
+                    headers: { [sessionHeader]: id },
+                    bytes: e.bytes,
+                    contentType: e.mime,
+                });
+            }
+        }
+    }
+    diverged(was, now) {
+        throw new ReplayDivergedError(`Replaying the edits after the session ended gave checkpoint "${now}" where it first gave "${was}". Nothing was saved.`, { status: 409, code: "replay_diverged" });
+    }
+    async recover() {
+        const id = await this.reopen();
+        await this.replay(id);
+        this.id = id;
+    }
+    /** Runs a call; if the session is gone, recovers it and runs the call once more. */
+    async call(fn) {
+        try {
+            return await fn();
+        }
+        catch (e) {
+            if (!(e instanceof SessionGoneError))
+                throw e;
+        }
+        await this.recover();
+        return fn();
+    }
+    /** Makes one edit. A refusal comes back as `answer.refused`, with nothing applied. */
+    edit(name, input = {}) {
+        return this.apply({ name, input });
+    }
+    /** Makes several edits in one request. They share one checkpoint and stop at the first refusal. */
+    editMany(edits) {
+        return this.apply({ edits: edits.map((e) => ({ name: e.name, input: e.input ?? {} })) });
+    }
+    async apply(body) {
+        const a = answerOf((await this.call(() => this.sendEdit("/api/v1/edit/apply", body))).body);
+        if (a.label)
+            this.log.push({ kind: "apply", body, label: a.label });
+        this.absorb(a);
+        return a;
+    }
+    /** Puts the session back on a checkpoint: `loaded`, an `e<n>` label an edit answered, `current` or `best`. */
+    async undo(label) {
+        const a = answerOf((await this.call(() => this.sendEdit("/api/v1/edit/restore", { label }))).body);
+        if (a.label && a.refused === "")
+            this.log.push({ kind: "restore", asked: label, label: a.label });
+        this.absorb(a);
+        return a;
+    }
+    /** Checks the design against the rules. With `render` it is also drawn and judged. */
+    async check(o = {}) {
+        const json = o.render ? { render: true } : undefined;
+        const res = await this.call(() => this.transport.send("POST", "/api/v1/edit/check", {
+            headers: { [sessionHeader]: this.id },
+            ...(json ? { json } : {}),
+        }));
+        const a = res.body;
+        if (a.check)
+            this.lastCheck = a.check;
+        return a;
+    }
+    /** Draws the design as it stands. Mestra's servers draw it; nothing is drawn here. */
+    async preview() {
+        const res = await this.call(() => this.transport.send("POST", "/api/v1/edit/preview", { headers: { [sessionHeader]: this.id } }));
+        const b = res.body;
+        if (b.check)
+            this.lastCheck = b.check;
+        return {
+            png: fromBase64(b.image.data),
+            width: b.image.width,
+            height: b.image.height,
+            check: b.check,
+            current: b.current !== false,
+            standIns: b.standIns ?? [],
+            lossy: b.lossy === true,
+            hash: b.hash ?? "",
+        };
+    }
+    /** Keeps a picture for the session; then `edit("swap_picture", {ref, sha256})`. Works on a size and on a master. */
+    async uploadPicture(bytes, mime) {
+        const type = mime ?? sniffMime(bytes);
+        const sha256 = await sha256Hex(bytes);
+        const res = await this.call(() => this.transport.send("PUT", `/api/v1/edit/assets/${sha256}`, {
+            headers: { [sessionHeader]: this.id },
+            bytes,
+            contentType: type,
+        }));
+        this.log.push({ kind: "upload", bytes, mime: type, sha256 });
+        return { ...res.body.asset, created: res.body.created === true };
+    }
+    /**
+     * Saves the design. The key makes the save safe to retry: pass your own and send the same one again if an answer
+     * is lost, and nothing is saved twice. If the session has ended the save is first tried again with the same key
+     * (the server may have recorded it); only then is the session reopened, checked and replayed, and the save made.
+     */
+    async save(o = {}) {
+        const idempotencyKey = o.idempotencyKey ?? randomKey();
+        const attempt = () => this.transport.send("PUT", "/api/v1/edit/save", {
+            headers: { [sessionHeader]: this.id, "If-Match": this.ifMatchHeader() },
+            json: { idempotencyKey },
+        });
+        let res;
+        try {
+            res = await attempt();
+        }
+        catch (e) {
+            if (!(e instanceof SessionGoneError))
+                throw e;
+            try {
+                res = await attempt();
+            }
+            catch (e2) {
+                if (!(e2 instanceof SessionGoneError))
+                    throw e2;
+                await this.recover();
+                res = await attempt();
+            }
+        }
+        const out = this.saved(res.body);
+        this.log = [];
+        return out;
+    }
+}
+/** One size of a run, open for editing. */
+export class SizeSession extends EditSession {
+    kind = "size";
+    /** The run's id (the `{id}` of the run). */
+    runId;
+    /** The size's key. */
+    size;
+    /** The hash the log is built on, and what the next save sends as `If-Match`. */
+    sceneHash;
+    format;
+    constructor(transport, runId, size, open) {
+        super(transport, open);
+        this.runId = runId;
+        this.size = size;
+        this.sceneHash = open.sceneHash;
+        this.format = open.format;
+    }
+    /** A session `editSizes` opened and edited for you: the edit it made is in the log so recovery keeps it. */
+    static fromBatch(transport, r, edit) {
+        const s = new SizeSession(transport, r.run, r.size, {
+            id: r.session,
+            elements: r.elements ?? [],
+            check: r.check ?? emptyCheck(),
+            label: r.label || "loaded",
+            sceneHash: r.sceneHash,
+        });
+        if (r.label)
+            s.log.push({ kind: "apply", body: { name: edit.name, input: edit.input ?? {} }, label: r.label });
+        return s;
+    }
+    ifMatchHeader() {
+        return this.sceneHash;
+    }
+    async reopen() {
+        const o = await openSizeRaw(this.transport, this.runId, this.size);
+        if (o.sceneHash !== this.sceneHash) {
+            throw new SizeChangedError("This size changed since you opened it, so your edits were not replayed. Open it again and redo them.", { status: 412, code: "scene_changed" });
+        }
+        return o.id;
+    }
+    saved(a) {
+        const out = a;
+        this.sceneHash = out.sceneHash;
+        if (out.check)
+            this.lastCheck = out.check;
+        if (out.label)
+            this.label = out.label;
+        return out;
+    }
+    /** After a save made across sizes. */
+    markSaved(sceneHash) {
+        this.sceneHash = sceneHash;
+        this.log = [];
+    }
+}
+/** One version of a master, open for editing. */
+export class MasterSession extends EditSession {
+    kind = "master";
+    masterId;
+    /** The version the session stands on: the one opened, then the one the last save made. Recovery reopens it. */
+    version;
+    /** What the next save sends as `If-Match`. Only a save moves it, never a reopen. */
+    ifMatch;
+    master;
+    ruleSets;
+    copyOverrides;
+    constructor(transport, open) {
+        super(transport, open);
+        this.masterId = open.master.id;
+        this.version = open.master.version;
+        this.ifMatch = open.ifMatch;
+        this.master = open.master;
+        this.ruleSets = open.ruleSets;
+        this.copyOverrides = open.copyOverrides;
+    }
+    ifMatchHeader() {
+        return String(this.ifMatch);
+    }
+    async reopen() {
+        // The same version, by number: `latest` could land on a newer one. The answer's ifMatch is ignored on purpose,
+        // so a newer version still gets its 412 at save.
+        const o = await openMasterRaw(this.transport, this.masterId, this.version);
+        return o.session;
+    }
+    saved(a) {
+        const out = a;
+        this.ifMatch = out.ifMatch;
+        this.version = out.version;
+        if (out.check)
+            this.lastCheck = out.check;
+        if (out.label)
+            this.label = out.label;
+        return out;
+    }
+}
+/* eslint-disable @typescript-eslint/no-explicit-any */
+async function openSizeRaw(t, runId, size) {
+    const res = await t.send("POST", `/api/v1/jobs/${encodeURIComponent(runId)}/formats/${encodeURIComponent(size)}/edit`);
+    const b = res.body;
+    return {
+        run: (b.run ?? runId),
+        size: (b.size ?? size),
+        id: b.session,
+        elements: (b.elements ?? []),
+        check: (b.check ?? emptyCheck()),
+        label: (b.label ?? "loaded"),
+        sceneHash: b.sceneHash,
+        format: b.format,
+    };
+}
+async function openMasterRaw(t, masterId, version) {
+    const res = await t.send("POST", `/api/v1/masters/${encodeURIComponent(masterId)}/versions/${version}/edit`);
+    return res.body;
+}
+/** Opens one size of a run for editing. */
+export async function openSize(t, runId, size) {
+    const o = await openSizeRaw(t, runId, size);
+    return new SizeSession(t, o.run, o.size, o);
+}
+/** Opens a master for editing: `version` is a number, or the latest by default. */
+export async function openMaster(t, masterId, o = {}) {
+    const b = await openMasterRaw(t, masterId, o.version ?? "latest");
+    return new MasterSession(t, {
+        id: b.session,
+        elements: b.elements ?? [],
+        check: b.check ?? emptyCheck(),
+        label: b.label ?? "loaded",
+        master: b.master,
+        ifMatch: b.ifMatch,
+        ruleSets: b.ruleSets ?? [],
+        copyOverrides: b.copyOverrides ?? {},
+    });
+}

package/dist/errors.d.ts

@@ -0,0 +1,51 @@
+/** Anything the API answers with an error status. `code` and `field` are the API's own. */
+export declare class MestraError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly field?: string;
+    /** The rest of the error body (`limit`, `max`, `latest`, ...), as the API sent it. */
+    readonly details: Record<string, unknown>;
+    constructor(message: string, init: {
+        status: number;
+        code?: string;
+        field?: string;
+        details?: Record<string, unknown>;
+    });
+}
+/** 404 `session_gone`. The session helpers recover from it by themselves; you only see it if recovery fails. */
+export declare class SessionGoneError extends MestraError {
+}
+/** The size changed while you were editing (412 `scene_changed`), or changed before a lost session could be replayed. */
+export declare class SizeChangedError extends MestraError {
+}
+/** 412 `version_changed`: the master has a newer version than the one you opened. Open it again and redo the edits. */
+export declare class VersionChangedError extends MestraError {
+    /** The master's newest version number. */
+    readonly latest: number;
+    /** `mestra` for a save made here, else the app: `indesign`, `figma`, `canva` or `upload`. */
+    readonly by: string;
+    /** Who saved it, for a save made in Mestra; empty for an app's. */
+    readonly byName: string;
+    constructor(message: string, init: {
+        status: number;
+        code?: string;
+        field?: string;
+        details?: Record<string, unknown>;
+    });
+}
+/** A lost session was reopened and the log replayed, but an edit answered differently from the first time. */
+export declare class ReplayDivergedError extends MestraError {
+}
+/** 409 `sizes_busy`: another across-sizes call by the same user is still running. */
+export declare class SizesBusyError extends MestraError {
+}
+/** 404 `operation_gone`: the operation is unknown, has ended, or is another user's. */
+export declare class OperationGoneError extends MestraError {
+}
+/** Waiting for an across-sizes operation took longer than `timeoutMs`. The operation itself carries on. */
+export declare class WaitTimeoutError extends MestraError {
+    /** Pass it to `getSizesOperation` or `watchSizes` to keep waiting. */
+    readonly operation: string;
+    constructor(message: string, operation: string);
+}
+export declare function errorFor(status: number, body: unknown): MestraError;