@simantic/cloud-sim 0.2.0 → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simantic, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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.1`. `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.
@@ -318,4 +325,5 @@ answers with is checked against the schemas in `openapi/v1.json`.
 
 ## License
 
-Proprietary (`UNLICENSED`), as the API itself is.
+MIT, in `LICENSE`. The license is for this package; the Cloud Sim API
+it calls is a Simantic service, used with a Simantic API key.

package/dist/client.d.ts

@@ -15,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. */

package/dist/generated/v1.d.ts

@@ -545,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"];
@@ -872,6 +880,8 @@ 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;

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;
@@ -48,6 +49,8 @@ export interface Call {
 }
 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;

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.
@@ -289,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,4 +1,5 @@
 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';

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.js

@@ -169,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,

package/dist/version.d.ts

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

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.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simantic/cloud-sim",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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": {
@@ -23,13 +23,8 @@
   "engines": {
     "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",
+  "license": "MIT",
+  "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"
   }
 }