@truenas/api-client 3.0.0 → 3.0.2

package/dist/index.cjs

@@ -2894,14 +2894,23 @@ var apiVersionConfig = {
   /**
    * Maximum supported API version. Systems above it are rejected.
    *
-   * NOT derived, deliberately. This should be the newest generated version by
-   * the same argument as MIN, but `instantiateClientForVersion` only maps
-   * `25.10` and `26` — a v27 system would pass the range check and then throw
-   * on client selection. It moves to the newest generated version once a v27
-   * client exists. Until then it lags on purpose, and the `satisfies` clause
-   * below still pins it to a version that was actually generated.
+   * NOT derived, deliberately — and for a different reason than it used to
+   * lag. It sat at v26.0.0 while types for v27 already shipped, because
+   * `CLIENT_BY_VERSION_KEY` had no `27` and a v27 system would have passed the
+   * range check only to throw on client selection. `TrueNasApiClientV27` now
+   * exists, so this moves up with it.
+   *
+   * What it must not become is `SUPPORTED_API_VERSIONS[length - 1]`, the mirror
+   * of how MIN is derived. MIN is safe to derive because the oldest generated
+   * version always has a client — it is the floor the clients were built from.
+   * The ceiling is not symmetric: generating types for v28 does not write a v28
+   * client, so deriving this would re-create the exact gap described above on
+   * the next regeneration, silently. The real invariant is "the newest version
+   * a client can be built for", which lives in `CLIENT_BY_VERSION_KEY`; a
+   * factory test asserts the two agree, which is the check that keeps this
+   * literal honest without importing the factory here.
    */
-  MAX_SUPPORTED_VERSION: "v26.0.0",
+  MAX_SUPPORTED_VERSION: "v27.0.0",
   /**
    * Fallback version to use when version discovery fails due to CORS/network errors.
    * When /api/versions returns HTTP status 0 (CORS block, network down, etc.),
@@ -3141,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]);
+      }
     };
   }
 };
@@ -3209,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)]
+      )
     };
   }
 };
@@ -3224,6 +3274,87 @@ function toContainer2(container) {
     description
   };
 }
+var TrueNasApiClientV27 = class extends TrueNasApiClient {
+  /**
+   * Create v27-specific operation mappings
+   *
+   * Operations return Observable<Job | null>:
+   * - Async operations emit Job updates until complete
+   * - Sync operations emit null once
+   */
+  createOperations() {
+    return {
+      // A polymorphic `.query`, so it goes through the verb rather than
+      // `call`: the directory types the raw method's response as the five-way
+      // union the server may return, and the verb is what fixes it to a list.
+      containerQuery: () => this.api.query("container.query").pipe(
+        rxjs.map((containers) => containers.map(toContainer3))
+      ),
+      // container.start is synchronous in v27 - emit null
+      containerStart: (id) => this.api.call("container.start", [parseInt(id, 10)]).pipe(rxjs.map(() => null)),
+      // container.stop emits job updates
+      containerStop: (id, options) => this.api.job("container.stop", [
+        parseInt(id, 10),
+        {
+          force: options.force,
+          force_after_timeout: options.force
+        }
+      ]),
+      // v27 still has no container.restart - chain stop + start.
+      // Emits Job updates during stop, then null when start completes.
+      containerRestart: (id, options) => {
+        const numericId = parseInt(id, 10);
+        return this.api.job("container.stop", [
+          numericId,
+          {
+            force: options.force,
+            force_after_timeout: options.force
+          }
+        ]).pipe(
+          // Collect all job updates to ensure stop fully completes
+          rxjs.toArray(),
+          // Re-emit job updates, then call start after stop is done
+          rxjs.switchMap(
+            (jobUpdates) => rxjs.concat(
+              rxjs.from(jobUpdates),
+              this.api.call("container.start", [numericId]).pipe(rxjs.map(() => null))
+            )
+          )
+        );
+      },
+      // 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)]
+      )
+    };
+  }
+};
+function toContainer3(container) {
+  const { description } = container;
+  return {
+    id: container.id.toString(),
+    name: container.name,
+    status: toAppState(container.status.state),
+    // Optional in the generated entry, required by `Container`.
+    autostart: container.autostart ?? false,
+    description
+  };
+}
 
 // src/errors/version-discovery.errors.ts
 var VersionDiscoveryError = class extends Error {
@@ -3593,7 +3724,8 @@ function selectRepresentativeFailure(failures) {
 }
 var CLIENT_BY_VERSION_KEY = {
   "25.10": TrueNasApiClientV2510,
-  "26": TrueNasApiClientV26
+  "26": TrueNasApiClientV26,
+  "27": TrueNasApiClientV27
 };
 function clientVersionKey(version) {
   if (version.year <= legacyCutoffYear) {
@@ -3649,6 +3781,7 @@ exports.SUPPORTED_API_VERSIONS = SUPPORTED_API_VERSIONS;
 exports.TrueNasApiClient = TrueNasApiClient;
 exports.TrueNasApiClientV2510 = TrueNasApiClientV2510;
 exports.TrueNasApiClientV26 = TrueNasApiClientV26;
+exports.TrueNasApiClientV27 = TrueNasApiClientV27;
 exports.TrueNasAuthMechanism = TrueNasAuthMechanism;
 exports.VersionCompatibility = VersionCompatibility;
 exports.VersionDiscovery = VersionDiscovery;