@simantic/cloud-sim 0.1.0 → 0.3.0

package/README.md

@@ -9,7 +9,7 @@ after.
 The package is ESM with no dependencies, built on `fetch`, so it runs on
 Node 18 and later, in browsers, and on Deno, Bun and edge runtimes. Its
 wire types are generated from the server's OpenAPI document
-(`openapi/v1.json` in the cloud-sim repo), so they change only when the
+(https://cloud.simantic.com/v1/openapi.json), so they change only when the
 contract does.
 
 ## Install
@@ -18,10 +18,8 @@ contract does.
 npm install @simantic/cloud-sim
 ```
 
-The package is private to the `simantic` npm organization for now: installing
-it needs an npm token of an org member (`npm login`, or `NPM_TOKEN` on CI and
-Vercel, which writes the `.npmrc` itself). The API it calls is open to any
-simantic account; its contract is at https://cloud.simantic.com/v1/openapi.json.
+The API it calls is open to any simantic account; its contract is at
+https://cloud.simantic.com/v1/openapi.json.
 
 ## Quick start
 
@@ -71,6 +69,7 @@ const run = await sim.runs.create({ mcu: 'STM32F072RB', firmware: input.files![0
 new CloudSim({
   apiKey,          // an smtc_ API key or a dashboard session token, or a function giving one
   version,         // Cloud-Sim-Version, such as '1.0'; the server's newest stable without it
+  client,          // your app or tool, such as 'my-tool/1.2', named on the runs it makes
   baseUrl,         // default https://cloud.simantic.com
   fetch,           // default the global fetch
   onUnauthorized,  // called once on a 401, before the request is sent again
@@ -85,6 +84,14 @@ release, so results do not change under you when the server's default
 moves on. A call that makes runs or reads a catalog can name another
 version for itself (`version`), so one client can serve a version picker.
 
+Every run the client makes names it in `Cloud-Sim-Client`, and keeps
+that as its `client`: `cloud-sim-ts/<version>` (the SDK's version, also
+exported as `SDK_VERSION`), after `client` when it is given, so a run made
+by `my-tool` reads `my-tool/1.2 cloud-sim-ts/0.3.0`. `client` is
+`product/version` tokens separated by single spaces, in printable ASCII;
+the constructor throws a `TypeError` for anything else. Only creates
+carry the header.
+
 Every call takes an optional `signal`. Aborting it ends the call, its
 retries and the waits between them, and the call throws the signal's
 reason.
@@ -100,15 +107,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
@@ -14,6 +15,14 @@ export interface CloudSimOptions {
      * stable version, which can change under a long-lived client.
      */
     version?: string;
+    /**
+     * The app or tool built on the SDK, as `product/version` (several
+     * separated by spaces), such as `my-tool/1.2`. A run it makes keeps it,
+     * followed by the SDK's own `cloud-sim-ts/<version>`, as its `client`
+     * (`Cloud-Sim-Client`); without it, the run names the SDK alone. Printable
+     * ASCII; the constructor throws a TypeError for anything else.
+     */
+    client?: string;
     /** Default `https://cloud.simantic.com`. */
     baseUrl?: string;
     /** Default the global fetch. */
@@ -49,5 +58,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}
@@ -475,6 +545,14 @@ export interface components {
              * @description When its owner asked to cancel it, while it is being stopped.
              */
             cancel_requested_at: string | null;
+            /**
+             * @description The client it was made with, as the `Cloud-Sim-Client` header of the
+             *     request that made it named it: `cloud-sim-cli/0.1.0`, say, or
+             *     `cloud-sim-mcp/0.2.1 cloud-sim-ts/0.2.1` for one client built on
+             *     another. Null when that request named none, and for a run submitted
+             *     through the legacy /jobs API.
+             */
+            client: string | null;
             /** Format: date-time */
             created_at: string;
             engine: null | components["schemas"]["RunEngine"];
@@ -556,16 +634,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. */
@@ -766,11 +880,13 @@ export interface operations {
                 "Cloud-Sim-Version"?: string | null;
                 /** @description Up to 255 printable ASCII characters: the same request again with it gets the same run. */
                 "Idempotency-Key"?: string | null;
+                /** @description The client making the run, as `product/version` tokens separated by spaces (`cloud-sim-mcp/0.2.1 cloud-sim-ts/0.2.1`): the run keeps it as `client`. Up to 200 printable ASCII characters; any other value is left out, not refused. */
+                "Cloud-Sim-Client"?: string | null;
             };
             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 +1397,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 +2039,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

@@ -13,6 +13,7 @@ export interface RetryInfo {
 export interface TransportOptions {
     apiKey: ApiKey;
     version?: string;
+    client?: string;
     baseUrl?: string;
     fetch?: typeof fetch;
     onUnauthorized?: () => Promise<void> | void;
@@ -22,7 +23,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,13 +41,16 @@ 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;
 }
 export declare class Transport {
     readonly version: string | undefined;
+    /** `Cloud-Sim-Client`, as a create sends it. */
+    readonly client: string;
     readonly baseUrl: string;
     /** How many times a transient failure is tried again. */
     readonly maxRetries: number;
@@ -60,6 +64,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

@@ -2,6 +2,7 @@
 // version header, a time limit on the answer, retries of what is safe to
 // retry, and the server's error body turned into a CloudSimError.
 import { CloudSimError, generalCode } from './errors.js';
+import { SDK_VERSION } from './version.js';
 export const DEFAULT_BASE_URL = 'https://cloud.simantic.com';
 const DEFAULT_MAX_RETRIES = 3;
 // The CLI's and the dashboard's own limit: a submit can take a while, as the
@@ -14,8 +15,14 @@ const MAX_BACKOFF_MS = 8_000;
 // A Retry-After longer than this is not waited out: a call that would sit
 // for minutes is the caller's to decide on, so it fails with the error.
 const MAX_RETRY_AFTER_MS = 60_000;
+// The SDK as `Cloud-Sim-Client` names it, after any client built on it.
+const SDK_CLIENT = `cloud-sim-ts/${SDK_VERSION}`;
+// The longest `Cloud-Sim-Client` the server keeps; it drops a longer one.
+const MAX_CLIENT_LENGTH = 200;
 export class Transport {
     version;
+    /** `Cloud-Sim-Client`, as a create sends it. */
+    client;
     baseUrl;
     /** How many times a transient failure is tried again. */
     maxRetries;
@@ -27,6 +34,7 @@ export class Transport {
     constructor(options) {
         this.apiKey = options.apiKey;
         this.version = options.version;
+        this.client = clientHeader(options.client);
         this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
         // Called as a plain function: a browser's fetch throws "Illegal
         // invocation" when called as a method of anything but the window.
@@ -54,6 +62,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.
@@ -282,3 +297,21 @@ export function sleep(ms, signal) {
 export function isRecord(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
+/**
+ * `Cloud-Sim-Client` for a client built on the SDK as `client` (none for the
+ * SDK used as it is): its products, then the SDK's. Checked here rather than
+ * left to the server, which keeps only 1-200 printable ASCII characters and
+ * otherwise drops it, and to fetch, which refuses other characters in a
+ * header only when a request is sent.
+ */
+function clientHeader(client) {
+    const named = client?.trim();
+    if (!named)
+        return SDK_CLIENT;
+    const header = `${named} ${SDK_CLIENT}`;
+    if (!/^[\x21-\x7e]+( [\x21-\x7e]+)*$/.test(named) || header.length > MAX_CLIENT_LENGTH) {
+        throw new TypeError(`client must be printable ASCII products separated by single spaces, such as "my-tool/1.2", ` +
+            `of at most ${MAX_CLIENT_LENGTH - SDK_CLIENT.length - 1} characters: got ${JSON.stringify(client)}`);
+    }
+    return header;
+}

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 export { CloudSim, type CloudSimOptions } from './client.js';
+export { SDK_VERSION } from './version.js';
 export { CloudSimError, type CloudSimErrorInit, CompareError, isTransient, } from './errors.js';
 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/index.js

@@ -3,6 +3,7 @@
 // fetch does: Node 18 and later, browsers, Deno, Bun, edge runtimes.
 // Anything that needs Node lives in '@simantic/cloud-sim/node'.
 export { CloudSim } from './client.js';
+export { SDK_VERSION } from './version.js';
 export { CloudSimError, CompareError, isTransient, } from './errors.js';
 export { POLL_INTERVAL_MS, } from './follow.js';
 export { compareResults } from './compare.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;
@@ -142,7 +169,7 @@ export class Runs {
         const call = {
             method: 'POST',
             path: '/v1/runs',
-            headers: { 'Idempotency-Key': key },
+            headers: { 'Idempotency-Key': key, 'Cloud-Sim-Client': this.http.client },
             version: params.version,
             signal: params.signal,
             timeoutMs: params.timeoutMs,
@@ -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/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const SDK_VERSION = "0.3.0";

package/dist/version.js

@@ -0,0 +1,4 @@
+// The SDK's own version, as a run's `Cloud-Sim-Client` names it
+// (`cloud-sim-ts/<version>`). A test keeps it equal to package.json's, so a
+// release that bumps one bumps the other.
+export const SDK_VERSION = '0.3.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simantic/cloud-sim",
-  "version": "0.1.0",
+  "version": "0.3.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": {
@@ -24,12 +24,7 @@
     "node": ">=18"
   },
   "license": "UNLICENSED",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/simantic-dev/cloud-sim.git",
-    "directory": "sdk/typescript"
-  },
-  "homepage": "https://github.com/simantic-dev/cloud-sim/tree/main/sdk/typescript#readme",
+  "homepage": "https://simantic.com/cloud-sim",
   "keywords": [
     "simantic",
     "cloud-sim",
@@ -52,8 +47,5 @@
     "openapi-typescript": "^7.13.0",
     "typescript": "~5.9.3",
     "vitest": "^4.1.11"
-  },
-  "publishConfig": {
-    "access": "restricted"
   }
 }