@withmestra/sdk 0.0.0-stage → 0.1.1

package/dist/errors.js

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

package/dist/http.d.ts

@@ -0,0 +1,36 @@
+/** Timers come from here so tests never wait. */
+export interface Clock {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+export declare const systemClock: Clock;
+/** The shape of the standard `fetch`. */
+export type FetchLike = (input: string | Request, init?: RequestInit) => Promise<Response>;
+export interface TransportOptions {
+    token: string;
+    /** The origin, such as `https://app.withmestra.com`. A trailing `/api/v1` is accepted and dropped. */
+    baseUrl?: string;
+    fetch?: FetchLike;
+    clock?: Clock;
+}
+export declare const defaultBaseUrl = "https://app.withmestra.com";
+export declare const sessionHeader = "X-Mestra-Edit-Session";
+export interface Sent {
+    status: number;
+    body: any;
+}
+/** One place that sends a request and turns an error answer into a MestraError. */
+export declare class Transport {
+    readonly clock: Clock;
+    readonly baseUrl: string;
+    private readonly token;
+    private readonly fetchFn;
+    constructor(o: TransportOptions);
+    fetch(input: string | Request, init?: RequestInit): Promise<Response>;
+    send(method: string, path: string, o?: {
+        headers?: Record<string, string>;
+        json?: unknown;
+        bytes?: Uint8Array;
+        contentType?: string;
+    }): Promise<Sent>;
+}

package/dist/http.js

@@ -0,0 +1,54 @@
+import { errorFor } from "./errors.js";
+export const systemClock = {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+export const defaultBaseUrl = "https://app.withmestra.com";
+export const sessionHeader = "X-Mestra-Edit-Session";
+/** One place that sends a request and turns an error answer into a MestraError. */
+export class Transport {
+    clock;
+    baseUrl;
+    token;
+    fetchFn;
+    constructor(o) {
+        this.token = o.token;
+        this.baseUrl = (o.baseUrl ?? defaultBaseUrl).replace(/\/+$/, "").replace(/\/api\/v1$/, "");
+        this.fetchFn = o.fetch;
+        this.clock = o.clock ?? systemClock;
+    }
+    fetch(input, init) {
+        return (this.fetchFn ?? globalThis.fetch.bind(globalThis))(input, init);
+    }
+    async send(method, path, o = {}) {
+        const headers = { Authorization: `Bearer ${this.token}`, Accept: "application/json", ...o.headers };
+        let body;
+        if (o.json !== undefined) {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(o.json);
+        }
+        else if (o.bytes !== undefined) {
+            // fetch sets Content-Length itself for a byte body.
+            if (o.contentType)
+                headers["Content-Type"] = o.contentType;
+            body = o.bytes;
+        }
+        const init = { method, headers };
+        if (body !== undefined)
+            init.body = body;
+        const res = await this.fetch(this.baseUrl + path, init);
+        const text = await res.text();
+        let parsed = {};
+        if (text !== "") {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = {};
+            }
+        }
+        if (res.status >= 400)
+            throw errorFor(res.status, parsed);
+        return { status: res.status, body: parsed };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+import type { paths } from "./v1.js";
+import { type TransportOptions } from "./http.js";
+import { MasterSession, SizeSession } from "./edit.js";
+import { type EditSizesRequest, type SaveSizesOptions } from "./sizes.js";
+import type { EditSizeResult, SaveSizeResult, SizesProgress, WaitOptions } from "./types.js";
+export * from "./errors.js";
+export * from "./types.js";
+export { EditSession, SizeSession, MasterSession } from "./edit.js";
+export type { EditSizesRequest, EditSizesResult, SaveSizesOptions } from "./sizes.js";
+export { defaultPollIntervalMs, defaultTimeoutMs } from "./sizes.js";
+export { defaultBaseUrl, systemClock, type Clock, type FetchLike, type TransportOptions } from "./http.js";
+export type { paths, components, operations } from "./v1.js";
+export type MestraOptions = TransportOptions;
+/**
+ * Makes a client. `baseUrl` is the origin (default `https://app.withmestra.com`); `fetch` and `clock` are for tests.
+ */
+export declare function createMestra(options: MestraOptions): {
+    /** The whole API, typed from the OpenAPI file. */
+    api: import("openapi-fetch").Client<paths, `${string}/${string}`>;
+    /** Opens one size of a run (`runId` is the run's id, `size` the format's key). */
+    openSize: (runId: string, size: string) => Promise<SizeSession>;
+    /** Opens a master for editing: the latest version, or `{version}`. Its save sends the version as `If-Match`. */
+    openMaster: (masterId: string, o?: {
+        version?: number | "latest";
+    }) => Promise<MasterSession>;
+    /** Which sizes of a run can be opened, with the scene hash each was last saved at. */
+    editable: (runId: string) => Promise<any>;
+    /** One edit on many sizes of a campaign. Waits for the answer, polling if the server needs longer. */
+    editSizes: (req: EditSizesRequest, o?: WaitOptions<EditSizeResult>) => Promise<{
+        results: import("./sizes.js").EditSizesResult[];
+    }>;
+    /** Saves several size sessions, each on its own. Waits for the answer. Size sessions only. */
+    saveSizes: (sessions: SizeSession[], o?: SaveSizesOptions<SaveSizeResult>) => Promise<{
+        results: SaveSizeResult[];
+    }>;
+    /** The raw first answer of an edit across sizes, for callers who watch progress themselves. */
+    startEditSizes: (req: EditSizesRequest) => Promise<SizesProgress<{
+        run?: string;
+        centre: string;
+        size?: string;
+        outcome: "applied" | "no_change" | "refused" | "not_editable" | "busy" | "failed";
+        status?: number;
+        code?: string;
+        session?: string;
+        sceneHash?: string;
+        label?: string;
+        check?: import("./v1.js").components["schemas"]["EditCheck"];
+        refused?: string;
+        detail?: string;
+        limit?: Record<string, never>;
+        candidates?: import("./v1.js").components["schemas"]["EditCandidate"][];
+        elements?: import("./v1.js").components["schemas"]["EditElement"][];
+    }>>;
+    /** The raw first answer of a save across sizes. */
+    startSaveSizes: (sessions: SizeSession[], idempotencyKey?: string) => Promise<SizesProgress<{
+        session: string;
+        outcome: "saved" | "failed";
+        status: number;
+        code?: string;
+        sceneHash?: string;
+        round?: number | null;
+        pull?: "ready" | "quiet" | "not_sent" | "superseded" | "none";
+        fileId?: string | null;
+        version?: number;
+    }>>;
+    /** Reads a running operation once. */
+    getSizesOperation: <R = {
+        run?: string;
+        centre: string;
+        size?: string;
+        outcome: "applied" | "no_change" | "refused" | "not_editable" | "busy" | "failed";
+        status?: number;
+        code?: string;
+        session?: string;
+        sceneHash?: string;
+        label?: string;
+        check?: import("./v1.js").components["schemas"]["EditCheck"];
+        refused?: string;
+        detail?: string;
+        limit?: Record<string, never>;
+        candidates?: import("./v1.js").components["schemas"]["EditCandidate"][];
+        elements?: import("./v1.js").components["schemas"]["EditElement"][];
+    } | {
+        session: string;
+        outcome: "saved" | "failed";
+        status: number;
+        code?: string;
+        sceneHash?: string;
+        round?: number | null;
+        pull?: "ready" | "quiet" | "not_sent" | "superseded" | "none";
+        fileId?: string | null;
+        version?: number;
+    }>(id: string) => Promise<SizesProgress<R>>;
+    /** An async iterator over an operation's progress, from the first answer until `done`. */
+    watchSizes: <R = {
+        run?: string;
+        centre: string;
+        size?: string;
+        outcome: "applied" | "no_change" | "refused" | "not_editable" | "busy" | "failed";
+        status?: number;
+        code?: string;
+        session?: string;
+        sceneHash?: string;
+        label?: string;
+        check?: import("./v1.js").components["schemas"]["EditCheck"];
+        refused?: string;
+        detail?: string;
+        limit?: Record<string, never>;
+        candidates?: import("./v1.js").components["schemas"]["EditCandidate"][];
+        elements?: import("./v1.js").components["schemas"]["EditElement"][];
+    } | {
+        session: string;
+        outcome: "saved" | "failed";
+        status: number;
+        code?: string;
+        sceneHash?: string;
+        round?: number | null;
+        pull?: "ready" | "quiet" | "not_sent" | "superseded" | "none";
+        fileId?: string | null;
+        version?: number;
+    }>(first: SizesProgress<R>, o?: WaitOptions<R>) => AsyncGenerator<SizesProgress<R>, void, undefined>;
+};
+export type Mestra = ReturnType<typeof createMestra>;

package/dist/index.js

@@ -0,0 +1,47 @@
+import createClient from "openapi-fetch";
+import { Transport } from "./http.js";
+import { openMaster as openMasterWith, openSize as openSizeWith } from "./edit.js";
+import { editSizes as editSizesWith, getSizesOperation, saveSizes as saveSizesWith, startEditSizes, startSaveSizes, watchSizes, } from "./sizes.js";
+export * from "./errors.js";
+export * from "./types.js";
+export { EditSession, SizeSession, MasterSession } from "./edit.js";
+export { defaultPollIntervalMs, defaultTimeoutMs } from "./sizes.js";
+export { defaultBaseUrl, systemClock } from "./http.js";
+/**
+ * Makes a client. `baseUrl` is the origin (default `https://app.withmestra.com`); `fetch` and `clock` are for tests.
+ */
+export function createMestra(options) {
+    const t = new Transport(options);
+    const api = createClient({
+        baseUrl: t.baseUrl,
+        fetch: (req) => t.fetch(req),
+    });
+    api.use({
+        onRequest({ request }) {
+            request.headers.set("Authorization", `Bearer ${options.token}`);
+            return request;
+        },
+    });
+    return {
+        /** The whole API, typed from the OpenAPI file. */
+        api,
+        /** Opens one size of a run (`runId` is the run's id, `size` the format's key). */
+        openSize: (runId, size) => openSizeWith(t, runId, size),
+        /** Opens a master for editing: the latest version, or `{version}`. Its save sends the version as `If-Match`. */
+        openMaster: (masterId, o) => openMasterWith(t, masterId, o),
+        /** Which sizes of a run can be opened, with the scene hash each was last saved at. */
+        editable: async (runId) => (await t.send("GET", `/api/v1/jobs/${encodeURIComponent(runId)}/editable`)).body,
+        /** One edit on many sizes of a campaign. Waits for the answer, polling if the server needs longer. */
+        editSizes: (req, o) => editSizesWith(t, req, o),
+        /** Saves several size sessions, each on its own. Waits for the answer. Size sessions only. */
+        saveSizes: (sessions, o) => saveSizesWith(t, sessions, o),
+        /** The raw first answer of an edit across sizes, for callers who watch progress themselves. */
+        startEditSizes: (req) => startEditSizes(t, req),
+        /** The raw first answer of a save across sizes. */
+        startSaveSizes: (sessions, idempotencyKey) => startSaveSizes(t, sessions, idempotencyKey),
+        /** Reads a running operation once. */
+        getSizesOperation: (id) => getSizesOperation(t, id),
+        /** An async iterator over an operation's progress, from the first answer until `done`. */
+        watchSizes: (first, o) => watchSizes(t, first, o),
+    };
+}

package/dist/sizes.d.ts

@@ -0,0 +1,33 @@
+import { SizeSession } from "./edit.js";
+import type { Transport } from "./http.js";
+import type { Edit, EditSizeResult, SaveSizeResult, SizesProgress, WaitOptions } from "./types.js";
+export declare const defaultPollIntervalMs = 1000;
+export declare const defaultTimeoutMs = 600000;
+/** Reads an operation once. Throws OperationGoneError when it has ended or isn't yours. */
+export declare function getSizesOperation<R>(t: Transport, id: string): Promise<SizesProgress<R>>;
+/**
+ * Yields the first answer, then every read of the operation, until it is done. The timer is the transport's clock.
+ */
+export declare function watchSizes<R>(t: Transport, first: SizesProgress<R>, o?: WaitOptions<R>): AsyncGenerator<SizesProgress<R>, void, undefined>;
+export interface EditSizesRequest {
+    campaign: string;
+    centres?: string[];
+    sizes: string[] | "all";
+    edit: Edit;
+    idempotencyKey?: string;
+}
+/** A size's result, with the session object when it has one. */
+export type EditSizesResult = EditSizeResult & {
+    editSession?: SizeSession;
+};
+export declare function startEditSizes(t: Transport, req: EditSizesRequest): Promise<SizesProgress<EditSizeResult>>;
+export declare function editSizes(t: Transport, req: EditSizesRequest, o?: WaitOptions<EditSizeResult>): Promise<{
+    results: EditSizesResult[];
+}>;
+export interface SaveSizesOptions<R> extends WaitOptions<R> {
+    idempotencyKey?: string;
+}
+export declare function startSaveSizes(t: Transport, sessions: SizeSession[], idempotencyKey?: string): Promise<SizesProgress<SaveSizeResult>>;
+export declare function saveSizes(t: Transport, sessions: SizeSession[], o?: SaveSizesOptions<SaveSizeResult>): Promise<{
+    results: SaveSizeResult[];
+}>;

package/dist/sizes.js

@@ -0,0 +1,97 @@
+import { SizeSession } from "./edit.js";
+import { WaitTimeoutError } from "./errors.js";
+export const defaultPollIntervalMs = 1000;
+export const defaultTimeoutMs = 600_000;
+function randomKey() {
+    return globalThis.crypto.randomUUID();
+}
+/** `200` is a finished call; `202` is an operation to read until its status is `done`. */
+function progressOf(status, body) {
+    if (status === 202 || body.operation !== undefined) {
+        return {
+            operation: body.operation,
+            ...(body.kind ? { kind: body.kind } : {}),
+            status: body.status,
+            done: body.done,
+            total: body.total,
+            results: body.results ?? [],
+        };
+    }
+    const results = (body.results ?? []);
+    return { status: "done", done: results.length, total: results.length, results };
+}
+/** Reads an operation once. Throws OperationGoneError when it has ended or isn't yours. */
+export async function getSizesOperation(t, id) {
+    const res = await t.send("GET", `/api/v1/edit/sizes/operations/${encodeURIComponent(id)}`);
+    return progressOf(res.status, res.body);
+}
+/**
+ * Yields the first answer, then every read of the operation, until it is done. The timer is the transport's clock.
+ */
+export async function* watchSizes(t, first, o = {}) {
+    const interval = o.pollIntervalMs ?? defaultPollIntervalMs;
+    const timeout = o.timeoutMs ?? defaultTimeoutMs;
+    const started = t.clock.now();
+    let p = first;
+    o.onProgress?.(p);
+    yield p;
+    while (p.status !== "done") {
+        const id = p.operation;
+        if (id === undefined)
+            return;
+        if (t.clock.now() - started >= timeout) {
+            throw new WaitTimeoutError(`Waited ${timeout} ms and the operation was still running. It carries on.`, id);
+        }
+        await t.clock.sleep(interval);
+        p = await getSizesOperation(t, id);
+        o.onProgress?.(p);
+        yield p;
+    }
+}
+async function finish(t, first, o) {
+    let last = first;
+    for await (const p of watchSizes(t, first, o))
+        last = p;
+    return last;
+}
+export async function startEditSizes(t, req) {
+    const res = await t.send("POST", "/api/v1/edit/sizes", {
+        json: { ...req, edit: { name: req.edit.name, input: req.edit.input ?? {} }, idempotencyKey: req.idempotencyKey ?? randomKey() },
+    });
+    return progressOf(res.status, res.body);
+}
+export async function editSizes(t, req, o = {}) {
+    const last = await finish(t, await startEditSizes(t, req), o);
+    const results = last.results.map((r) => {
+        if (r.session && r.sceneHash && r.run && r.size) {
+            const { session: id, sceneHash, run, size, label, check, elements } = r;
+            return {
+                ...r,
+                editSession: SizeSession.fromBatch(t, { run, size, session: id, sceneHash, ...(label ? { label } : {}), ...(check ? { check } : {}), ...(elements ? { elements } : {}) }, req.edit),
+            };
+        }
+        return r;
+    });
+    return { results };
+}
+export async function startSaveSizes(t, sessions, idempotencyKey = randomKey()) {
+    for (const s of sessions) {
+        if (s.kind !== "size") {
+            throw new TypeError("saveSizes saves size sessions only. Save a master session with its own save().");
+        }
+    }
+    const res = await t.send("PUT", "/api/v1/edit/sizes", {
+        json: { sizes: sessions.map((s) => ({ session: s.id, ifMatch: s.sceneHash })), idempotencyKey },
+    });
+    return progressOf(res.status, res.body);
+}
+export async function saveSizes(t, sessions, o = {}) {
+    const sent = sessions.map((s) => s.id);
+    const last = await finish(t, await startSaveSizes(t, sessions, o.idempotencyKey), o);
+    for (const r of last.results) {
+        const s = sessions[sent.indexOf(r.session)];
+        if (s && r.outcome === "saved" && r.sceneHash)
+            s.markSaved(r.sceneHash);
+    }
+    return { results: last.results };
+}

package/dist/types.d.ts

@@ -0,0 +1,115 @@
+import type { components } from "./v1.js";
+type S = components["schemas"];
+export type EditElement = S["EditElement"];
+export type EditCandidate = S["EditCandidate"];
+export type EditCheck = S["EditCheck"];
+export type EditSizeResult = S["EditSizeResult"];
+export type SaveSizeResult = S["SaveSizeResult"];
+/** One edit: `name` is `set_frame`, `set_text`, `set_copy`, `swap_picture`, ... and `input` names the element by `ref` or `role`. */
+export interface Edit {
+    name: string;
+    input?: Record<string, unknown>;
+}
+/**
+ * What an edit or a restore answers. A refusal is data, not an exception: `refused` is a code such as
+ * `ambiguous_role` (then `candidates` lists the elements), and is the empty string when the edit was made.
+ */
+export interface EditAnswer {
+    elements: EditElement[];
+    candidates?: EditCandidate[];
+    fixes: string[];
+    carried: Record<string, string>;
+    check: EditCheck;
+    refused: string;
+    detail: string;
+    limit: Record<string, unknown> | null;
+    noChange: boolean;
+    /** The checkpoint a committed edit made (`e1`, `e2`, ...), the label restored, or empty. */
+    label: string;
+}
+export interface CheckAnswer {
+    check: EditCheck;
+    /** Only with `render`. */
+    standIns?: string[];
+    lossy?: boolean;
+    hash?: string;
+    current?: boolean;
+}
+export interface Preview {
+    png: Uint8Array;
+    width: number;
+    height: number;
+    check: EditCheck;
+    /** False when the session moved on while the picture was drawn, so it shows an earlier state. */
+    current: boolean;
+    standIns: string[];
+    lossy: boolean;
+    hash: string;
+}
+export interface Picture {
+    /** Send it as the `swap_picture` edit's `sha256`. */
+    sha256: string;
+    mime: "image/png" | "image/jpeg";
+    width: number;
+    height: number;
+    /** True when the picture is new; false when the session or run already held it. */
+    created: boolean;
+}
+export interface SizeSaveAnswer {
+    sceneHash: string;
+    fileId: string | null;
+    round: number | null;
+    publications: number;
+    pull: "ready" | "quiet" | "not_sent" | "superseded";
+    check: EditCheck;
+    label: string;
+}
+export interface MasterSaveAnswer {
+    version: number;
+    /** The version number to send as `If-Match` on the next save. The session keeps it for you. */
+    ifMatch: number;
+    /** True, with no new version, when the edits left the master as it was. */
+    unchanged: boolean;
+    status: "checking" | "ready" | "not_ready";
+    pull: string;
+    runsKept: number;
+    ruleSets: unknown[];
+    newRuleFailures: string[];
+    check: EditCheck;
+    label: string;
+}
+export interface MasterInfo {
+    id: string;
+    version: number;
+    latest: number;
+    name: string;
+    sourceApp: string;
+    brand: string;
+    canPull: boolean;
+}
+export interface FormatInfo {
+    key: string;
+    name: string;
+    width: number;
+    height: number;
+    unit: "px" | "mm";
+}
+/** The progress of a call across sizes. A call that finished at once is `done` with no `operation`. */
+export interface SizesProgress<R> {
+    operation?: string;
+    /** Which call the operation is (`edit` or `save`); absent on a call that finished at once. */
+    kind?: "edit" | "save";
+    status: "running" | "done";
+    done: number;
+    total: number;
+    results: R[];
+}
+export interface WaitOptions<R> {
+    /** Milliseconds between reads of a running operation. Default 1000. */
+    pollIntervalMs?: number;
+    /** Give up waiting (not working) after this many milliseconds. Default 600000 (ten minutes). */
+    timeoutMs?: number;
+    /** Called with every snapshot, the first included. */
+    onProgress?: (progress: SizesProgress<R>) => void;
+}
+export {};

package/dist/types.js

@@ -0,0 +1 @@
+export {};