@simantic/cloud-sim 0.1.0 → 0.2.0

package/README.md

@@ -100,15 +100,38 @@ sim.runs.result(id, { signal? })   // { exit_code, output, log, truncated } of a
 sim.runs.output(id, { signal? })   // the UART output, as text
 sim.runs.log(id, { signal? })      // the engine's console, as text
 sim.runs.cancel(id, { signal? })
+sim.runs.firmware(id, { signal? })         // the stored ELF, as a Uint8Array
+sim.runs.deleteFirmware(id, { signal? })   // the run, its firmware no longer stored
 sim.runs.wait(id, { signal?, intervalMs? })
 sim.runs.follow(id, { signal?, transport?, intervalMs?, from? })
 sim.runs.compare({ engines, mcu, firmware, ...options, version?, timeoutMs?, signal? })
 ```
 
 `firmware` is a `Blob` (a `File` included), a `Uint8Array`, an
-`ArrayBuffer`, `{ url }` or `{ base64 }`. Bytes are uploaded as
+`ArrayBuffer`, `{ url }`, `{ base64 }` or `{ run }`. Bytes are uploaded as
 multipart/form-data; a URL is fetched by the server (https only, at most
-24 MiB); base64 goes in JSON.
+24 MiB); base64 goes in JSON; `run` is the id of one of your runs whose
+firmware the server stores, which this run runs again.
+
+### Stored firmware
+
+The server keeps each run's ELF, encrypted, after the run
+(`run.firmware.stored`), so you can download it and run it again, with
+other options or on a newer version:
+
+```ts
+const elf = await sim.runs.firmware(run.id)
+const again = await sim.runs.create({ mcu: run.mcu, firmware: { run: run.id }, simulatedSeconds: 30 })
+await sim.runs.deleteFirmware(run.id)   // gone; firmware.deleted_at says when
+```
+
+Storage is on unless you turn it off, which deletes every run's stored
+firmware:
+
+```ts
+await sim.settings.get()                          // { store_firmware, stored_firmware: { runs, bytes } }
+await sim.settings.update({ storeFirmware: false })
+```
 
 Every create carries an `Idempotency-Key`, generated when you give none, so
 a create the SDK retries after a lost answer gets the run it already made

package/dist/client.d.ts

@@ -1,6 +1,7 @@
 import { Mcus, Versions } from './catalog.js';
 import { type ApiKey, type RetryInfo } from './http.js';
 import { Runs } from './runs.js';
+import { Settings } from './settings.js';
 export interface CloudSimOptions {
     /**
      * An `smtc_` API key, or a simantic dashboard session's access token. A
@@ -49,5 +50,6 @@ export declare class CloudSim {
     readonly runs: Runs;
     readonly versions: Versions;
     readonly mcus: Mcus;
+    readonly settings: Settings;
     constructor(options: CloudSimOptions);
 }

package/dist/client.js

@@ -1,15 +1,18 @@
 import { Mcus, Versions } from './catalog.js';
 import { Transport } from './http.js';
 import { Runs } from './runs.js';
+import { Settings } from './settings.js';
 /** A client of the Cloud Sim API. */
 export class CloudSim {
     runs;
     versions;
     mcus;
+    settings;
     constructor(options) {
         const http = new Transport(options);
         this.runs = new Runs(http);
         this.versions = new Versions(http);
         this.mcus = new Mcus(http);
+        this.settings = new Settings(http);
     }
 }

package/dist/generated/v1.d.ts

@@ -86,6 +86,24 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/runs/{id}/firmware": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** @description The ELF the run simulated, as it was given, while the server stores it (`firmware.stored`): from the run's creation until its owner deletes it or turns firmware storage off. */
+        get: operations["firmware"];
+        put?: never;
+        post?: never;
+        /** @description Deletes the run's stored firmware: at once, or for a run that has not ended, when it does (it runs on it until then). Either way the run answers with `firmware.stored` false from now on, and `firmware.deleted_at` says when. A run whose firmware is not stored answers as it is. */
+        delete: operations["delete_firmware"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/runs/{id}/live": {
         parameters: {
             query?: never;
@@ -153,6 +171,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/settings": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["get_settings"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        /** @description Changes the settings given, and answers with all of them. Turning `store_firmware` off deletes every run's stored firmware. */
+        patch: operations["update_settings"];
+        trace?: never;
+    };
     "/v1/versions": {
         parameters: {
             query?: never;
@@ -279,6 +314,11 @@ export interface components {
             /** @description Repeat the field for each name. */
             usb_cdc_consoles?: string[] | null;
         };
+        /**
+         * Format: binary
+         * @description An ELF file, as `GET /v1/runs/{id}/firmware` answers it.
+         */
+        ElfFile: string;
         /** @description An engine as a version pins it. */
         EngineView: {
             build: components["schemas"]["Build"];
@@ -313,15 +353,20 @@ export interface components {
              *       version), `engine_unknown`, `engine_not_in_version`,
              *       `mcu_not_supported`, `mcu_not_runnable`, `option_not_supported`,
              *       `firmware_missing`, `firmware_invalid`, `firmware_url_refused`,
-             *       `firmware_fetch_failed`, `invalid_request`;
-             *     - 401 `unauthorized`; 403 `forbidden`;
-             *     - 404 `run_not_found`, `version_unknown` (in the path), `not_found`;
+             *       `firmware_fetch_failed`, `firmware_not_stored` (`firmware.run`
+             *       names no run of yours whose firmware is stored),
+             *       `invalid_request`;
+             *     - 401 `unauthorized`; 403 `forbidden`, `guest_firmware_only` (the
+             *       demo server runs only its examples, uploaded);
+             *     - 404 `run_not_found`, `firmware_not_stored` (the run's firmware is
+             *       not stored), `version_unknown` (in the path), `not_found`;
              *     - 409 `idempotency_key_reused`, `run_not_finished`, `run_finished`;
              *     - 410 `version_retired`;
              *     - 413 `firmware_too_large`, `payload_too_large`;
              *     - 415 `unsupported_media_type`;
              *     - 429 `too_many_runs` (the caller's unfinished runs are at the
-             *       limit; `Retry-After` says when to look again);
+             *       limit; `Retry-After` says when to look again), `demo_busy` (the
+             *       demo server's queue is full);
              *     - 503 `unavailable` (a service the API relies on; `Retry-After`).
              */
             code: string;
@@ -334,6 +379,17 @@ export interface components {
         };
         /** @description The firmware a run simulates. */
         Firmware: {
+            /**
+             * Format: date-time
+             * @description When its owner deleted the ELF, or turned storage off while the
+             *     server kept it.
+             */
+            deleted_at: string | null;
+            /**
+             * Format: uuid
+             * @description The run whose stored firmware it ran again, for `run`.
+             */
+            run: string | null;
             /** @description Hex SHA-256 of the ELF. */
             sha256: string;
             /**
@@ -342,13 +398,27 @@ export interface components {
              */
             size: number;
             source: components["schemas"]["FirmwareSource"];
+            /**
+             * @description Whether the server keeps the ELF, encrypted, after the run: `GET
+             *     /v1/runs/{id}/firmware` downloads it, and a run with `firmware:
+             *     {"run": id}` runs it again. It does unless its owner turned firmware
+             *     storage off (`PATCH /v1/settings`) or deleted it (`DELETE
+             *     /v1/runs/{id}/firmware`), or the run is from before storage.
+             */
+            stored: boolean;
             /** @description The URL it was fetched from, for `url`. */
             url: string | null;
         };
-        /** @description The firmware: exactly one of `base64` and `url`. */
+        /** @description The firmware: exactly one of `base64`, `url` and `run`. */
         FirmwareInput: {
             /** @description The ELF, base64-encoded (standard alphabet, padded). */
             base64?: string | null;
+            /**
+             * Format: uuid
+             * @description The id of one of your runs whose firmware the server stores
+             *     (`firmware.stored`): this run runs that ELF again.
+             */
+            run?: string | null;
             /**
              * @description An https URL the server fetches the ELF from when the run is
              *     submitted (at most 24 MiB, within 20 seconds; never a private
@@ -357,11 +427,11 @@ export interface components {
             url?: string | null;
         };
         /**
-         * @description How a run's firmware came: a multipart file part, base64 in JSON, or
-         *     fetched by the server from a URL.
+         * @description How a run's firmware came: a multipart file part, base64 in JSON,
+         *     fetched by the server from a URL, or another run's stored firmware.
          * @enum {string}
          */
-        FirmwareSource: "upload" | "base64" | "url";
+        FirmwareSource: "upload" | "base64" | "url" | "run";
         /**
          * @description Where a version is in its life (index.toml `status`).
          * @enum {string}
@@ -556,16 +626,52 @@ export interface components {
          * @enum {string}
          */
         RunStatus: "queued" | "starting" | "running" | "succeeded" | "failed" | "canceled";
+        /** @description The caller's settings. */
+        Settings: {
+            /**
+             * @description Whether the server keeps each run's firmware after the run, so it
+             *     can be downloaded and run again. On unless turned off. Off, a run's
+             *     firmware is deleted when the run ends.
+             */
+            store_firmware: boolean;
+            /** @description What the server keeps now. */
+            stored_firmware: components["schemas"]["StoredFirmware"];
+        };
         StatusChange: {
             from: string;
             mcu: string;
             to: string;
         };
+        /** @description The firmware the server keeps for the caller. */
+        StoredFirmware: {
+            /**
+             * Format: int64
+             * @description Their size in all, in bytes.
+             */
+            bytes: number;
+            /**
+             * Format: int64
+             * @description How many runs' firmware.
+             */
+            runs: number;
+        };
         /**
          * @description How UART bytes are written: hex rows (every engine's default) or text.
          * @enum {string}
          */
         UartEncoding: "hex" | "ascii";
+        /**
+         * @description `PATCH /v1/settings`: the settings to change. One left out stays as it
+         *     is.
+         */
+        UpdateSettings: {
+            /**
+             * @description Turning it off deletes every run's stored firmware, at once (or, for
+             *     a run that has not ended, when it does), and keeps none from then
+             *     on. Turning it on keeps the firmware of runs that end from then on.
+             */
+            store_firmware?: boolean | null;
+        };
         /** @description Every version this server serves. */
         VersionList: {
             /** @description What a request without `Cloud-Sim-Version` gets. */
@@ -770,7 +876,7 @@ export interface operations {
             path?: never;
             cookie?: never;
         };
-        /** @description The run: JSON (firmware as base64 or a URL) or multipart/form-data (firmware as the file part `firmware`). */
+        /** @description The run: JSON (firmware as base64, a URL, or a run whose stored firmware to run again) or multipart/form-data (firmware as the file part `firmware`). */
         requestBody: {
             content: {
                 "application/json": components["schemas"]["CreateRun"];
@@ -1281,6 +1387,203 @@ export interface operations {
             };
         };
     };
+    firmware: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    /** @description The API version that answered. */
+                    "Cloud-Sim-Version"?: string;
+                    /** @description For a deprecated version: `@` and the Unix time it was deprecated (RFC 9745). */
+                    Deprecation?: string;
+                    /** @description For a deprecated version with a sunset date: when it retires (RFC 8594). */
+                    Sunset?: string;
+                    /** @description The request's id, which an error's `request_id` repeats. */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/octet-stream": components["schemas"]["ElfFile"];
+                };
+            };
+            /** @description The request is not one the API takes (see `code`). */
+            400: {
+                headers: {
+                    /** @description The API version that answered. */
+                    "Cloud-Sim-Version"?: string;
+                    /** @description For a deprecated version: `@` and the Unix time it was deprecated (RFC 9745). */
+                    Deprecation?: string;
+                    /** @description For a deprecated version with a sunset date: when it retires (RFC 8594). */
+                    Sunset?: string;
+                    /** @description The request's id, which an error's `request_id` repeats. */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description No valid credential. */
+            401: {
+                headers: {
+                    /** @description The API version that answered. */
+                    "Cloud-Sim-Version"?: string;
+                    /** @description For a deprecated version: `@` and the Unix time it was deprecated (RFC 9745). */
+                    Deprecation?: string;
+                    /** @description For a deprecated version with a sunset date: when it retires (RFC 8594). */
+                    Sunset?: string;
+                    /** @description The request's id, which an error's `request_id` repeats. */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description No such run (`run_not_found`), or its firmware is not stored (`firmware_not_stored`). */
+            404: {
+                headers: {
+                    /** @description The API version that answered. */
+                    "Cloud-Sim-Version"?: string;
+                    /** @description For a deprecated version: `@` and the Unix time it was deprecated (RFC 9745). */
+                    Deprecation?: string;
+                    /** @description For a deprecated version with a sunset date: when it retires (RFC 8594). */
+                    Sunset?: string;
+                    /** @description The request's id, which an error's `request_id` repeats. */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description A service the API relies on is unavailable. */
+            503: {
+                headers: {
+                    /** @description The API version that answered. */
+                    "Cloud-Sim-Version"?: string;
+                    /** @description For a deprecated version: `@` and the Unix time it was deprecated (RFC 9745). */
+                    Deprecation?: string;
+                    /** @description Seconds to wait before trying again. */
+                    "Retry-After"?: string;
+                    /** @description For a deprecated version with a sunset date: when it retires (RFC 8594). */
+                    Sunset?: string;
+                    /** @description The request's id, which an error's `request_id` repeats. */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    delete_firmware: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    /** @description The API version that answered. */
+                    "Cloud-Sim-Version"?: string;
+                    /** @description For a deprecated version: `@` and the Unix time it was deprecated (RFC 9745). */
+                    Deprecation?: string;
+                    /** @description For a deprecated version with a sunset date: when it retires (RFC 8594). */
+                    Sunset?: string;
+                    /** @description The request's id, which an error's `request_id` repeats. */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Run"];
+                };
+            };
+            /** @description The request is not one the API takes (see `code`). */
+            400: {
+                headers: {
+                    /** @description The API version that answered. */
+                    "Cloud-Sim-Version"?: string;
+                    /** @description For a deprecated version: `@` and the Unix time it was deprecated (RFC 9745). */
+                    Deprecation?: string;
+                    /** @description For a deprecated version with a sunset date: when it retires (RFC 8594). */
+                    Sunset?: string;
+                    /** @description The request's id, which an error's `request_id` repeats. */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description No valid credential. */
+            401: {
+                headers: {
+                    /** @description The API version that answered. */
+                    "Cloud-Sim-Version"?: string;
+                    /** @description For a deprecated version: `@` and the Unix time it was deprecated (RFC 9745). */
+                    Deprecation?: string;
+                    /** @description For a deprecated version with a sunset date: when it retires (RFC 8594). */
+                    Sunset?: string;
+                    /** @description The request's id, which an error's `request_id` repeats. */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            404: {
+                headers: {
+                    /** @description The API version that answered. */
+                    "Cloud-Sim-Version"?: string;
+                    /** @description For a deprecated version: `@` and the Unix time it was deprecated (RFC 9745). */
+                    Deprecation?: string;
+                    /** @description For a deprecated version with a sunset date: when it retires (RFC 8594). */
+                    Sunset?: string;
+                    /** @description The request's id, which an error's `request_id` repeats. */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description A service the API relies on is unavailable. */
+            503: {
+                headers: {
+                    /** @description The API version that answered. */
+                    "Cloud-Sim-Version"?: string;
+                    /** @description For a deprecated version: `@` and the Unix time it was deprecated (RFC 9745). */
+                    Deprecation?: string;
+                    /** @description Seconds to wait before trying again. */
+                    "Retry-After"?: string;
+                    /** @description For a deprecated version with a sunset date: when it retires (RFC 8594). */
+                    Sunset?: string;
+                    /** @description The request's id, which an error's `request_id` repeats. */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
     live: {
         parameters: {
             query?: {
@@ -1726,6 +2029,170 @@ export interface operations {
             };
         };
     };
+    get_settings: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    /** @description The API version that answered. */
+                    "Cloud-Sim-Version"?: string;
+                    /** @description For a deprecated version: `@` and the Unix time it was deprecated (RFC 9745). */
+                    Deprecation?: string;
+                    /** @description For a deprecated version with a sunset date: when it retires (RFC 8594). */
+                    Sunset?: string;
+                    /** @description The request's id, which an error's `request_id` repeats. */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Settings"];
+                };
+            };
+            /** @description The request is not one the API takes (see `code`). */
+            400: {
+                headers: {
+                    /** @description The API version that answered. */
+                    "Cloud-Sim-Version"?: string;
+                    /** @description For a deprecated version: `@` and the Unix time it was deprecated (RFC 9745). */
+                    Deprecation?: string;
+                    /** @description For a deprecated version with a sunset date: when it retires (RFC 8594). */
+                    Sunset?: string;
+                    /** @description The request's id, which an error's `request_id` repeats. */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description No valid credential. */
+            401: {
+                headers: {
+                    /** @description The API version that answered. */
+                    "Cloud-Sim-Version"?: string;
+                    /** @description For a deprecated version: `@` and the Unix time it was deprecated (RFC 9745). */
+                    Deprecation?: string;
+                    /** @description For a deprecated version with a sunset date: when it retires (RFC 8594). */
+                    Sunset?: string;
+                    /** @description The request's id, which an error's `request_id` repeats. */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description A service the API relies on is unavailable. */
+            503: {
+                headers: {
+                    /** @description The API version that answered. */
+                    "Cloud-Sim-Version"?: string;
+                    /** @description For a deprecated version: `@` and the Unix time it was deprecated (RFC 9745). */
+                    Deprecation?: string;
+                    /** @description Seconds to wait before trying again. */
+                    "Retry-After"?: string;
+                    /** @description For a deprecated version with a sunset date: when it retires (RFC 8594). */
+                    Sunset?: string;
+                    /** @description The request's id, which an error's `request_id` repeats. */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    update_settings: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["UpdateSettings"];
+            };
+        };
+        responses: {
+            200: {
+                headers: {
+                    /** @description The API version that answered. */
+                    "Cloud-Sim-Version"?: string;
+                    /** @description For a deprecated version: `@` and the Unix time it was deprecated (RFC 9745). */
+                    Deprecation?: string;
+                    /** @description For a deprecated version with a sunset date: when it retires (RFC 8594). */
+                    Sunset?: string;
+                    /** @description The request's id, which an error's `request_id` repeats. */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Settings"];
+                };
+            };
+            /** @description The request is not one the API takes (see `code`). */
+            400: {
+                headers: {
+                    /** @description The API version that answered. */
+                    "Cloud-Sim-Version"?: string;
+                    /** @description For a deprecated version: `@` and the Unix time it was deprecated (RFC 9745). */
+                    Deprecation?: string;
+                    /** @description For a deprecated version with a sunset date: when it retires (RFC 8594). */
+                    Sunset?: string;
+                    /** @description The request's id, which an error's `request_id` repeats. */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description No valid credential. */
+            401: {
+                headers: {
+                    /** @description The API version that answered. */
+                    "Cloud-Sim-Version"?: string;
+                    /** @description For a deprecated version: `@` and the Unix time it was deprecated (RFC 9745). */
+                    Deprecation?: string;
+                    /** @description For a deprecated version with a sunset date: when it retires (RFC 8594). */
+                    Sunset?: string;
+                    /** @description The request's id, which an error's `request_id` repeats. */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description A service the API relies on is unavailable. */
+            503: {
+                headers: {
+                    /** @description The API version that answered. */
+                    "Cloud-Sim-Version"?: string;
+                    /** @description For a deprecated version: `@` and the Unix time it was deprecated (RFC 9745). */
+                    Deprecation?: string;
+                    /** @description Seconds to wait before trying again. */
+                    "Retry-After"?: string;
+                    /** @description For a deprecated version with a sunset date: when it retires (RFC 8594). */
+                    Sunset?: string;
+                    /** @description The request's id, which an error's `request_id` repeats. */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
     versions: {
         parameters: {
             query?: never;

package/dist/http.d.ts

@@ -22,7 +22,7 @@ export interface TransportOptions {
 }
 export type Query = Record<string, string | number | boolean | undefined>;
 export interface Call {
-    method: 'GET' | 'POST';
+    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
     path: string;
     query?: Query;
     /** A JSON body. */
@@ -40,8 +40,9 @@ export interface Call {
     /**
      * Whether a transient failure may be sent again: true for reads, for a
      * create that carries an Idempotency-Key, which the server answers with
-     * the run it already made, and for a cancel, which it answers with the
-     * run as it is.
+     * the run it already made, for a cancel or a firmware deletion, which it
+     * answers with the run as it is, and for a settings change, which sets
+     * what it sets again.
      */
     retry: boolean;
 }
@@ -60,6 +61,8 @@ export declare class Transport {
     json<T>(call: Call): Promise<T>;
     /** The answer as text. */
     text(call: Call): Promise<string>;
+    /** The answer's bytes. */
+    bytes(call: Call): Promise<Uint8Array>;
     /**
      * The answer itself, its body unread (an event stream). Aborting the
      * call's signal later still ends the body.

package/dist/http.js

@@ -54,6 +54,13 @@ export class Transport {
         const headers = { Accept: 'text/plain', ...call.headers };
         return this.request({ ...call, headers }, (response) => response.text());
     }
+    /** The answer's bytes. */
+    bytes(call) {
+        const headers = { Accept: 'application/octet-stream', ...call.headers };
+        return this.request({ ...call, headers }, async (response) => {
+            return new Uint8Array(await response.arrayBuffer());
+        });
+    }
     /**
      * The answer itself, its body unread (an event stream). Aborting the
      * call's signal later still ends the body.

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export type { ApiKey, RetryInfo } from './http.js';
 export { type FollowEvent, type FollowOptions, type FollowTransport, type Offsets, type StreamName, POLL_INTERVAL_MS, } from './follow.js';
 export type { CallOptions, Comparison, CompareParams, CreateOptions, CreateRunParams, FirmwareInput, ListRunsParams, RunListing, RunOptionsInput, Runs, WaitOptions, } from './runs.js';
 export type { McuFilter, McuListOptions, Mcus, Versions } from './catalog.js';
+export type { Settings as SettingsClient, UpdateSettingsParams } from './settings.js';
 export { type Difference, type ResultComparison, compareResults } from './compare.js';
-export { type Changes, type Engine, type EngineOption, type ErrorBody, type Firmware, type Lifecycle, type Live, type LiveStream, type Mcu, type McuEngine, type McuList, type Run, type RunEngine, type RunList, type RunOptions, type RunResult, type RunStatus, type UartEncoding, type Version, type VersionList, FINISHED, isFinished, } from './types.js';
+export { type Changes, type Engine, type EngineOption, type ErrorBody, type Firmware, type FirmwareSource, type Lifecycle, type Live, type LiveStream, type Mcu, type McuEngine, type McuList, type Run, type RunEngine, type RunList, type RunOptions, type RunResult, type RunStatus, type Settings, type StoredFirmware, type UartEncoding, type Version, type VersionList, FINISHED, isFinished, } from './types.js';
 export type { components, operations, paths } from './generated/v1.js';

package/dist/runs.d.ts

@@ -3,13 +3,16 @@ import { type Transport } from './http.js';
 import { type Run, type RunList, type RunResult, type UartEncoding, type Version } from './types.js';
 /**
  * A run's firmware: the ELF's bytes (sent as a multipart upload), an https
- * URL the server fetches it from, or the ELF already base64-encoded (sent
- * in JSON).
+ * URL the server fetches it from, the ELF already base64-encoded (sent in
+ * JSON), or the id of one of your runs whose firmware the server stores
+ * (`run.firmware.stored`), to run it again.
  */
 export type FirmwareInput = Blob | Uint8Array | ArrayBuffer | {
     url: string;
 } | {
     base64: string;
+} | {
+    run: string;
 };
 /** What every call takes. */
 export interface CallOptions {
@@ -105,6 +108,19 @@ export declare class Runs {
      * run that finished meanwhile gets the 409, which is not retried.
      */
     cancel(id: string, options?: CallOptions): Promise<Run>;
+    /**
+     * The ELF the run simulated, as it was given, while the server stores it
+     * (`run.firmware.stored`). One it does not store is 404
+     * `firmware_not_stored`.
+     */
+    firmware(id: string, options?: CallOptions): Promise<Uint8Array>;
+    /**
+     * Deletes the run's stored firmware: at once, or for a run that has not
+     * ended, when it does. Answers with the run, `firmware.stored` false and
+     * `firmware.deleted_at` saying when. Retried like a read: the server
+     * answers a repeated deletion with the run as it is.
+     */
+    deleteFirmware(id: string, options?: CallOptions): Promise<Run>;
     /** The run once it has finished: succeeded, failed or canceled. */
     wait(id: string, options?: WaitOptions): Promise<Run>;
     /**

package/dist/runs.js

@@ -74,6 +74,33 @@ export class Runs {
             retry: true,
         });
     }
+    /**
+     * The ELF the run simulated, as it was given, while the server stores it
+     * (`run.firmware.stored`). One it does not store is 404
+     * `firmware_not_stored`.
+     */
+    firmware(id, options = {}) {
+        return this.http.bytes({
+            method: 'GET',
+            path: `/v1/runs/${segment(id)}/firmware`,
+            signal: options.signal,
+            retry: true,
+        });
+    }
+    /**
+     * Deletes the run's stored firmware: at once, or for a run that has not
+     * ended, when it does. Answers with the run, `firmware.stored` false and
+     * `firmware.deleted_at` saying when. Retried like a read: the server
+     * answers a repeated deletion with the run as it is.
+     */
+    deleteFirmware(id, options = {}) {
+        return this.http.json({
+            method: 'DELETE',
+            path: `/v1/runs/${segment(id)}/firmware`,
+            signal: options.signal,
+            retry: true,
+        });
+    }
     /** The run once it has finished: succeeded, failed or canceled. */
     async wait(id, options = {}) {
         const { signal, intervalMs = WAIT_INTERVAL_MS } = options;
@@ -250,8 +277,11 @@ function firmwareBody(firmware) {
         if ('base64' in firmware && typeof firmware.base64 === 'string') {
             return { kind: 'json', json: { base64: firmware.base64 } };
         }
+        if ('run' in firmware && typeof firmware.run === 'string') {
+            return { kind: 'json', json: { run: firmware.run } };
+        }
     }
-    throw new TypeError('firmware must be a Blob, a Uint8Array, an ArrayBuffer, { url } or { base64 }');
+    throw new TypeError('firmware must be a Blob, a Uint8Array, an ArrayBuffer, { url }, { base64 } or { run }');
 }
 /** The run's fields other than its firmware, as the API names them. */
 function optionFields(params) {

package/dist/settings.d.ts

@@ -0,0 +1,21 @@
+import type { CallOptions } from './runs.js';
+import type { Transport } from './http.js';
+import type { Settings as SettingsBody } from './types.js';
+/** The settings to change. One left out stays as it is. */
+export interface UpdateSettingsParams extends CallOptions {
+    /**
+     * Whether the server stores runs' firmware. Turning it off deletes every
+     * run's stored firmware (an unfinished run's when it ends) and stores
+     * none from then on; turning it on stores the firmware of runs that end
+     * from then on.
+     */
+    storeFirmware?: boolean;
+}
+export declare class Settings {
+    private readonly http;
+    constructor(http: Transport);
+    /** Your settings, and how much firmware the server stores for you. */
+    get(options?: CallOptions): Promise<SettingsBody>;
+    /** Changes the settings given, and answers with all of them. */
+    update(params: UpdateSettingsParams): Promise<SettingsBody>;
+}

package/dist/settings.js

@@ -0,0 +1,32 @@
+// `client.settings`: your settings. One so far: whether the server stores
+// each run's firmware after the run, so you can download it
+// (`runs.firmware`) and run it again (`firmware: { run: id }`).
+export class Settings {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Your settings, and how much firmware the server stores for you. */
+    get(options = {}) {
+        return this.http.json({
+            method: 'GET',
+            path: '/v1/settings',
+            signal: options.signal,
+            retry: true,
+        });
+    }
+    /** Changes the settings given, and answers with all of them. */
+    update(params) {
+        const json = {};
+        if (params.storeFirmware !== undefined)
+            json['store_firmware'] = params.storeFirmware;
+        return this.http.json({
+            method: 'PATCH',
+            path: '/v1/settings',
+            json,
+            signal: params.signal,
+            // Setting the same value again changes nothing more.
+            retry: true,
+        });
+    }
+}

package/dist/types.d.ts

@@ -12,8 +12,14 @@ export type RunOptions = Schemas['RunOptions'];
 export type RunResult = Schemas['RunResult'];
 /** A page of the caller's runs, newest first. */
 export type RunList = Schemas['RunList'];
-/** The firmware a run simulates, as the server received it. */
+/** The firmware a run simulates, as the server received it, and whether it stores it. */
 export type Firmware = Schemas['Firmware'];
+/** How a run's firmware came: uploaded, base64, from a URL, or another run's stored firmware. */
+export type FirmwareSource = Schemas['FirmwareSource'];
+/** Your settings: whether the server stores runs' firmware, and how much it stores. */
+export type Settings = Schemas['Settings'];
+/** The firmware the server stores for you. */
+export type StoredFirmware = Schemas['StoredFirmware'];
 /** A run and a page of each of its streams (`GET /v1/runs/{id}/live`). */
 export type Live = Schemas['Live'];
 /** A page of one stream. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simantic/cloud-sim",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TypeScript client for the Cloud Sim API: run MCU firmware in the cloud, follow its output live, and compare simulation engines.",
   "type": "module",
   "exports": {