@truenas/api-client 3.0.1 → 3.0.3

package/README.md

@@ -84,19 +84,61 @@ client.api.events('app.query').subscribe(event => {
 
 ### Naming a version
 
-The version is discovered at runtime; the types are fixed at compile time.
-`createTrueNasClient` defaults to the oldest supported version, which
-understates a newer server rather than promising methods it lacks. Name a
-version to reach the rest:
+By default the version is discovered at runtime while the types are fixed at
+compile time, and `createTrueNasClient` assumes the oldest supported version —
+which understates a newer server rather than promising methods it lacks. There
+are two ways to reach the rest, and they differ in more than syntax.
+
+**Assert the surface** when you do not know the version but intend to write
+against a particular one:
 
 ```typescript
 const client = await createTrueNasClient<ApiDirectoryV26_0_0>(opts);
 client.api.query('container.query');                   // v26-only, reachable
 ```
 
-That is a claim about the server, not a guarantee — the client you get is
-whichever version discovery found. Operations that must work across versions
-belong on `client.ops`, which resolves them at runtime.
+Discovery still runs and still decides which client is built. The type argument
+is a claim about the server, not a guarantee — the client you get is whichever
+version discovery found, so a wrong claim fails at runtime.
+
+**State the version** when you already know it — a UI served by the appliance,
+a harness against a pinned image:
+
+```typescript
+const client = await createTrueNasClient({
+  uuid, hostnames, enabled: true, version: 'v27.0.0',
+});
+client.api.query('container.query');   // typed v27, derived from the string
+```
+
+This skips discovery entirely: no `GET /api/versions`, no CORS fallback. The
+surface is *derived* rather than asserted, so there is no type argument to get
+wrong, and a version the package ships no types for does not compile.
+
+It is the stronger claim of the two, because the version also selects the
+websocket path. Naming `v27.0.0` at a v26 appliance connects on `/api/v27.0.0`
+with v27 types over a v26 server, and discovery cannot correct it — declining
+discovery is the point.
+
+The derivation needs the version to be literal at the call site. Passing a type
+argument as well, forwarding `version` through a wrapper, or annotating the
+options object as `CreateClientOptions` all compile, all connect to the version
+you named, and all type as the default surface instead. That
+errs safely — understated types fail at the method call, not at runtime — but
+silently, so keep the literal where the call is.
+
+Compatibility is still checked, and two kinds of refusal reach a caller. A string that
+is not a supported version — reachable only from JavaScript — throws a plain
+`Error` naming the ones that are. A supported version this build has no client
+for throws `VersionTooNewError`, the same type discovery raises; that happens
+when types have been generated for a release before its client was written.
+There is no `VersionTooOldError` here, because the oldest version you can name
+is the oldest one supported.
+
+Operations that must work across versions belong on `client.ops`. On the
+discovery route that resolves against whatever the appliance turned out to be.
+On the named route it cannot: the client class is picked from the version you
+stated, so `ops` is that version's mappings whether or not the server agrees.
 
 ## Documentation
 

package/dist/index.cjs

@@ -3150,7 +3150,29 @@ var TrueNasApiClientV2510 = class extends TrueNasApiClient {
       containerQuery: () => this.api.query("virt.instance.query", [["type", "=", "CONTAINER"]]).pipe(rxjs.map((instances) => instances.map(toContainer))),
       containerStart: (id) => this.api.job("virt.instance.start", [id]),
       containerStop: (id, options) => this.api.job("virt.instance.stop", [id, options]),
-      containerRestart: (id, options) => this.api.job("virt.instance.restart", [id, options])
+      containerRestart: (id, options) => this.api.job("virt.instance.restart", [id, options]),
+      // Already a job here — `virt.instance.delete` has been one since
+      // v25.10.0 — so this needs no synthesis, only the id. It takes nothing
+      // else: there is no `force` and no `recursive` on this version.
+      //
+      // Unsupported options are reported rather than dropped. `recursive`
+      // destroys child datasets, snapshots and clones irrecoverably, so a
+      // caller who asked for it and silently did not get it has been told
+      // something false about what just happened to their data. Reporting is
+      // all this layer can do — refusing outright would make `ops.containerDelete`
+      // unusable on v25.10 for the ordinary case, which is the case that works.
+      containerDelete: (id, options) => {
+        const unsupported = ["force", "recursive"].filter(
+          (key) => options?.[key]
+        );
+        if (unsupported.length > 0) {
+          this.logger.warn(
+            "containerDelete: v25.10 has no counterpart for these options and will delete without them",
+            { ignored: unsupported, id, method: "virt.instance.delete" }
+          );
+        }
+        return this.api.job("virt.instance.delete", [id]);
+      }
     };
   }
 };
@@ -3218,7 +3240,26 @@ var TrueNasApiClientV26 = class extends TrueNasApiClient {
             )
           )
         );
-      }
+      },
+      // A job since v26.0.0 — middleware made deletion long-running (it stops
+      // the container when asked, tears down the libvirt domain and destroys
+      // the dataset), and the generated directory moved it out of `call`
+      // accordingly. `api.job` is what tracks it; `api.call` would not compile.
+      //
+      // Options pass straight through when given: the unified
+      // `ContainerDeleteOptions` is `force`/`recursive`, exactly what the
+      // generated params take.
+      //
+      // When they are not given the argument is *omitted* rather than passed as
+      // `undefined`. `JSON.stringify` renders a trailing `undefined` array
+      // element as `null`, and middleware declares `options: ContainerDeleteOptions`
+      // with a model default and no `| None` — so `[id, null]` is a validation
+      // error rather than "use the defaults", which is the one thing a caller
+      // passing nothing is asking for.
+      containerDelete: (id, options) => this.api.job(
+        "container.delete",
+        options ? [parseInt(id, 10), options] : [parseInt(id, 10)]
+      )
     };
   }
 };
@@ -3280,7 +3321,26 @@ var TrueNasApiClientV27 = class extends TrueNasApiClient {
             )
           )
         );
-      }
+      },
+      // A job since v26.0.0 — middleware made deletion long-running (it stops
+      // the container when asked, tears down the libvirt domain and destroys
+      // the dataset), and the generated directory moved it out of `call`
+      // accordingly. `api.job` is what tracks it; `api.call` would not compile.
+      //
+      // Options pass straight through when given: the unified
+      // `ContainerDeleteOptions` is `force`/`recursive`, exactly what the
+      // generated params take.
+      //
+      // When they are not given the argument is *omitted* rather than passed as
+      // `undefined`. `JSON.stringify` renders a trailing `undefined` array
+      // element as `null`, and middleware declares `options: ContainerDeleteOptions`
+      // with a model default and no `| None` — so `[id, null]` is a validation
+      // error rather than "use the defaults", which is the one thing a caller
+      // passing nothing is asking for.
+      containerDelete: (id, options) => this.api.job(
+        "container.delete",
+        options ? [parseInt(id, 10), options] : [parseInt(id, 10)]
+      )
     };
   }
 };
@@ -3584,12 +3644,40 @@ async function createTrueNasClient(opts) {
       `Cannot create client for system ${uuid}: hostnames array is empty`
     );
   }
-  const versionDiscovery = new VersionDiscovery(logger);
   logger.info("Creating versioned API client", {
     uuid: uuid.slice(0, 8),
     hostnames: hostnames.join(", "),
     systemName
   });
+  if (opts.version !== void 0) {
+    if (!SUPPORTED_API_VERSIONS.includes(opts.version)) {
+      throw new Error(
+        `Cannot create client for system ${uuid}: '${opts.version}' is not a version this package ships types for. Supported: ${SUPPORTED_API_VERSIONS.join(", ")}.`
+      );
+    }
+    const known = parseApiVersion(opts.version);
+    if (!known) {
+      throw new Error(
+        `Cannot create client for system ${uuid}: supported version '${opts.version}' failed to parse.`
+      );
+    }
+    const compatibility = checkVersionCompatibility(known);
+    if (compatibility === "too-new" /* TooNew */) {
+      throw new VersionTooNewError(hostnames[0], [known.version]);
+    }
+    if (compatibility !== "compatible" /* Compatible */) {
+      throw new Error(
+        `Cannot create client for system ${uuid}: the supported version range is not usable (${apiVersionConfig.MIN_SUPPORTED_VERSION}..${apiVersionConfig.MAX_SUPPORTED_VERSION}).`
+      );
+    }
+    logger.info("API version supplied by the caller, skipping discovery", {
+      uuid: uuid.slice(0, 8),
+      version: known.version,
+      websocketPath: known.websocketPath
+    });
+    return instantiateClientForVersion(known, opts, logger);
+  }
+  const versionDiscovery = new VersionDiscovery(logger);
   let version;
   try {
     const winner = await discoverVersionFromAnyHostname(