@truenas/api-client 3.0.1 → 3.0.3

package/dist/index.d.cts

@@ -13015,6 +13015,33 @@ interface ContainerStopOptions$1 {
     timeout?: number;
     force: boolean;
 }
+/**
+ * Options for deleting a container (unified interface)
+ *
+ * Both are optional and both default to off, matching middleware. Neither has a
+ * counterpart on v25.10 — `virt.instance.delete` takes an id and nothing else —
+ * so the v25.10 client cannot honour them; it says so rather than dropping them
+ * quietly, because `recursive` in particular destroys data.
+ */
+interface ContainerDeleteOptions$1 {
+    /**
+     * Stop the container first if it is not already stopped. Without it, v26+
+     * refuses to delete a running or suspended container rather than tearing it
+     * down underneath itself.
+     */
+    force?: boolean;
+    /**
+     * Destroy the container's dataset together with its child datasets and
+     * snapshots, any clones of those snapshots wherever they live in the pool,
+     * and any holds on them.
+     *
+     * Releasing a hold can break a replication task that depends on it, and none
+     * of what this destroys is recoverable. Without it, v26+ refuses to delete a
+     * container whose dataset has children or snapshots — which is the refusal
+     * this option exists to override, deliberately.
+     */
+    recursive?: boolean;
+}
 /**
  * Options for restarting a container (unified interface)
  */
@@ -13058,8 +13085,14 @@ interface ContainerRestartOptions {
  *
  * To add new operations:
  * 1. Add the method signature here
- * 2. Implement in TrueNasApiClientV2510.createOperations()
- * 3. Implement in TrueNasApiClientV26.createOperations()
+ * 2. Implement it in every client's `createOperations()` —
+ *    `TrueNasApiClientV2510`, `TrueNasApiClientV26`, `TrueNasApiClientV27`
+ *
+ * This list used to name only v25.10 and v26, which is how a new operation
+ * would have quietly missed v27. It is not the real safety net either: adding a
+ * member here fails to compile in every client that has not implemented it, and
+ * that is what actually enumerates them. Keep the list current, but trust the
+ * compiler.
  */
 interface OperationMappings {
     /**
@@ -13086,6 +13119,22 @@ interface OperationMappings {
      * - v26+: Emits Job updates (stop phase), then null (sync start)
      */
     containerRestart: (id: string, options: ContainerRestartOptions) => Observable<Job | null>;
+    /**
+     * Delete a container
+     * - v25.10: `virt.instance.delete`, already a job — emits Job updates
+     * - v26+: `container.delete`, made a job in v26.0.0 — emits Job updates
+     *
+     * A job on every supported version, so unlike `containerStart` this one does
+     * not change shape across them. It is exposed here because the alternative is
+     * a caller reaching for `api.call('container.delete', …)`, which is the wrong
+     * verb: the method moved out of the call directory when middleware made it a
+     * job, so that does not compile on v26+ and would not track the job if it did.
+     *
+     * `options` are honoured on v26+ only. v25.10's `virt.instance.delete` takes
+     * an id and nothing else; passing them there is logged rather than silently
+     * ignored, because `recursive` destroys data that cannot be recovered.
+     */
+    containerDelete: (id: string, options?: ContainerDeleteOptions$1) => Observable<Job | null>;
 }
 
 /**
@@ -27510,6 +27559,19 @@ declare const SUPPORTED_API_VERSIONS: readonly ["v25.10.0", "v25.10.1", "v25.10.
  * how the missing 22 methods went unnoticed in the first place.
  */
 type DefaultApiDirectory = ApiDirectory$7;
+/**
+ * The surface a named version derives, falling back when nothing was narrowed.
+ *
+ * `V` only pins a directory when inference narrowed it. A wrapper typed
+ * `(version: SupportedApiVersion)` widens it back to the whole union, and
+ * indexing by a union yields a union of directories whose usable methods are
+ * their *intersection* — narrower than the default surface, so naming the
+ * version would buy fewer methods than naming nothing. That case falls back to
+ * {@link DefaultApiDirectory} instead, matching every other shape that loses
+ * the literal. A partial union still derives: methods common to the versions
+ * named is the right answer for "one of these".
+ */
+type DerivedDirectory<V extends SupportedApiVersion> = SupportedApiVersion extends V ? DefaultApiDirectory : ApiDirectoryByVersion[V];
 /** Options for {@link createTrueNasClient}. */
 interface CreateClientOptions {
     /** System UUID. */
@@ -27533,12 +27595,22 @@ interface CreateClientOptions {
      * through the client, to the connection.
      */
     logger?: Logger;
+    /**
+     * The appliance's API version, when the caller already knows it.
+     *
+     * Supplying it skips version discovery entirely — no `GET /api/versions`, no
+     * CORS fallback — and *derives* the client's typed surface from the string,
+     * so `version: 'v27.0.0'` yields `TrueNasApiClient<ApiDirectoryV27_0_0>`
+     * without the caller asserting it through a type parameter.
+     */
+    version?: SupportedApiVersion;
 }
 /**
  * Creates a version-specific TrueNAS API client.
  *
  * 1. Discovers the API version (`GET /api/versions`), asking every hostname in
- *    parallel. The first usable answer wins.
+ *    parallel. The first usable answer wins — *unless* `opts.version` says
+ *    which version this is, in which case discovery is skipped entirely.
  * 2. Selects the matching client implementation (`v25.10.x` -> `TrueNasApiClientV2510`,
  *    `v26.x.y` -> `TrueNasApiClientV26`, `v27.x.y` -> `TrueNasApiClientV27`).
  * 3. Instantiates and returns it.
@@ -27569,9 +27641,77 @@ interface CreateClientOptions {
  * supported version. Operations that must work across versions belong on
  * `client.ops`, which resolves them at runtime.
  *
+ * ## Naming the version instead
+ *
+ * A caller that already knows its appliance — a UI served by the appliance
+ * itself, a test harness against a pinned image — can say so and skip discovery
+ * altogether:
+ *
+ * ```typescript
+ * const client = await createTrueNasClient({
+ *   uuid, hostnames, enabled: true, version: 'v27.0.0',
+ * });
+ * // client: TrueNasApiClient<ApiDirectoryV27_0_0>, derived from the string
+ * ```
+ *
+ * The surface is *derived* rather than asserted: `ApiDirectoryByVersion` maps
+ * the version string to its directory, so the caller writes no cast and names
+ * no directory type. A version this package ships no types for does not
+ * compile.
+ *
+ * **The derivation needs the version to be literal at the call site.** It comes
+ * from inference on `{ version: V }`, so it holds for a string literal written
+ * in the options object (or a `const`-typed one). It does not survive
+ * indirection:
+ *
+ * - `createTrueNasClient<D>({ …, version: 'v27.0.0' })` — an explicit type
+ *   argument makes the derived overload inapplicable, so `D` wins.
+ * - `(v?: SupportedApiVersion) => createTrueNasClient({ …, version: v })` — the
+ *   property is `SupportedApiVersion | undefined`, which no `V` satisfies.
+ * - `(v: SupportedApiVersion) => …` — reaches this overload, but `V` widens to
+ *   the whole union, which derives nothing.
+ * - `const opts: CreateClientOptions = { …, version: 'v27.0.0' }` — the
+ *   annotation widens the property before the call sees it.
+ *
+ * All of them compile, run against the named version, and type as
+ * {@link DefaultApiDirectory}. That fails in the safe direction — understated
+ * types give a compile error at the method call rather than a runtime surprise —
+ * but it is silent, so a wrapper that forwards a version gets none of the
+ * surface it named. Keep the literal at the call site, and if you are adding
+ * `version` to an existing `createTrueNasClient<ApiDirectoryV26_0_0>(opts)`
+ * call, delete the type argument in the same edit.
+ *
+ * Two consequences worth knowing before reaching for it.
+ *
+ * It is a stronger claim than `D` alone, because it also picks 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 whole point. `D` on its own only mistyped the surface; this
+ * mistypes the surface *and* dials the wrong number.
+ *
+ * Compatibility is still checked. Skipping discovery skips the network round
+ * trip, not the range check, which is local and free. Two refusals reach a
+ * caller, and they are not interchangeable:
+ *
+ * - a string that is not a `SupportedApiVersion` at all — only reachable from
+ *   JavaScript — throws a plain `Error` naming the versions that are.
+ * - a version this package ships types for but cannot build a client for
+ *   throws {@link VersionTooNewError}, the same error discovery raises.
+ *
+ * The second is not hypothetical. `MAX_SUPPORTED_VERSION` is a hand-written
+ * literal, and while it matches the newest generated version today, a
+ * regeneration can add a year before anyone writes its client — at which point
+ * that version is nameable, promised by the overload, and has nothing to build.
+ * `VersionTooOldError` has no counterpart here: `MIN_SUPPORTED_VERSION` is
+ * derived from the same list that constrains the type, so nothing nameable is
+ * below it.
+ *
+ * @typeParam V - the version named in `opts.version`, when one is. The returned
+ *   surface is `ApiDirectoryByVersion[V]`, so it is derived rather than chosen.
  * @typeParam D - the generated API surface the client is typed against, as a
- *   whole (`call`, `job`, `event`). Every verb resolves method names against
- *   it, so naming a method this surface does not have is a build error.
+ *   whole (`call`, `job`, `event`), for the discovery path where no version is
+ *   named. Every verb resolves method names against it, so naming a method this
+ *   surface does not have is a build error.
  * @returns a Promise that resolves with the created client, or rejects with a
  *   {@link VersionDiscoveryError} subclass (or a client-selection error).
  *   Rejects if version discovery on all hostnames *fails* and is not recoverable.
@@ -27581,6 +27721,9 @@ interface CreateClientOptions {
  *   bug. A network error alongside a version-compatibility error or a 404 does
  *   *not* reach the fallback — see `selectRepresentativeFailure`.
  */
+declare function createTrueNasClient<V extends SupportedApiVersion>(opts: CreateClientOptions & {
+    version: V;
+}): Promise<TrueNasApiClient<DerivedDirectory<V>>>;
 declare function createTrueNasClient<D extends ApiDirectoryShape = DefaultApiDirectory>(opts: CreateClientOptions): Promise<TrueNasApiClient<D>>;
 
 /**
@@ -27608,6 +27751,7 @@ declare function createTrueNasClient<D extends ApiDirectoryShape = DefaultApiDir
  * - containerStart → virt.instance.start (emits Job updates)
  * - containerStop → virt.instance.stop (emits Job updates)
  * - containerRestart → virt.instance.restart (emits Job updates)
+ * - containerDelete → virt.instance.delete (already a job; takes no options)
  */
 declare class TrueNasApiClientV2510 extends TrueNasApiClient<ApiDirectory$7> {
     /**
@@ -27645,6 +27789,7 @@ declare class TrueNasApiClientV2510 extends TrueNasApiClient<ApiDirectory$7> {
  * - containerStart → container.start (synchronous, emits null)
  * - containerStop → container.stop (emits Job updates)
  * - containerRestart → container.stop + container.start (emits Job, then null)
+ * - containerDelete → container.delete (a job since v26.0.0; force/recursive)
  */
 declare class TrueNasApiClientV26 extends TrueNasApiClient<ApiDirectory$1> {
     /**
@@ -27692,6 +27837,7 @@ declare class TrueNasApiClientV26 extends TrueNasApiClient<ApiDirectory$1> {
  * - containerStart → container.start (synchronous, emits null)
  * - containerStop → container.stop (emits Job updates)
  * - containerRestart → container.stop + container.start (emits Job, then null)
+ * - containerDelete → container.delete (a job since v26.0.0; force/recursive)
  *
  * Those four are currently identical to v26's, because v27 inherits all three
  * container entries the facade touches rather than re-declaring them. Asserted

package/dist/index.d.ts

@@ -13015,6 +13015,33 @@ interface ContainerStopOptions$1 {
     timeout?: number;
     force: boolean;
 }
+/**
+ * Options for deleting a container (unified interface)
+ *
+ * Both are optional and both default to off, matching middleware. Neither has a
+ * counterpart on v25.10 — `virt.instance.delete` takes an id and nothing else —
+ * so the v25.10 client cannot honour them; it says so rather than dropping them
+ * quietly, because `recursive` in particular destroys data.
+ */
+interface ContainerDeleteOptions$1 {
+    /**
+     * Stop the container first if it is not already stopped. Without it, v26+
+     * refuses to delete a running or suspended container rather than tearing it
+     * down underneath itself.
+     */
+    force?: boolean;
+    /**
+     * Destroy the container's dataset together with its child datasets and
+     * snapshots, any clones of those snapshots wherever they live in the pool,
+     * and any holds on them.
+     *
+     * Releasing a hold can break a replication task that depends on it, and none
+     * of what this destroys is recoverable. Without it, v26+ refuses to delete a
+     * container whose dataset has children or snapshots — which is the refusal
+     * this option exists to override, deliberately.
+     */
+    recursive?: boolean;
+}
 /**
  * Options for restarting a container (unified interface)
  */
@@ -13058,8 +13085,14 @@ interface ContainerRestartOptions {
  *
  * To add new operations:
  * 1. Add the method signature here
- * 2. Implement in TrueNasApiClientV2510.createOperations()
- * 3. Implement in TrueNasApiClientV26.createOperations()
+ * 2. Implement it in every client's `createOperations()` —
+ *    `TrueNasApiClientV2510`, `TrueNasApiClientV26`, `TrueNasApiClientV27`
+ *
+ * This list used to name only v25.10 and v26, which is how a new operation
+ * would have quietly missed v27. It is not the real safety net either: adding a
+ * member here fails to compile in every client that has not implemented it, and
+ * that is what actually enumerates them. Keep the list current, but trust the
+ * compiler.
  */
 interface OperationMappings {
     /**
@@ -13086,6 +13119,22 @@ interface OperationMappings {
      * - v26+: Emits Job updates (stop phase), then null (sync start)
      */
     containerRestart: (id: string, options: ContainerRestartOptions) => Observable<Job | null>;
+    /**
+     * Delete a container
+     * - v25.10: `virt.instance.delete`, already a job — emits Job updates
+     * - v26+: `container.delete`, made a job in v26.0.0 — emits Job updates
+     *
+     * A job on every supported version, so unlike `containerStart` this one does
+     * not change shape across them. It is exposed here because the alternative is
+     * a caller reaching for `api.call('container.delete', …)`, which is the wrong
+     * verb: the method moved out of the call directory when middleware made it a
+     * job, so that does not compile on v26+ and would not track the job if it did.
+     *
+     * `options` are honoured on v26+ only. v25.10's `virt.instance.delete` takes
+     * an id and nothing else; passing them there is logged rather than silently
+     * ignored, because `recursive` destroys data that cannot be recovered.
+     */
+    containerDelete: (id: string, options?: ContainerDeleteOptions$1) => Observable<Job | null>;
 }
 
 /**
@@ -27510,6 +27559,19 @@ declare const SUPPORTED_API_VERSIONS: readonly ["v25.10.0", "v25.10.1", "v25.10.
  * how the missing 22 methods went unnoticed in the first place.
  */
 type DefaultApiDirectory = ApiDirectory$7;
+/**
+ * The surface a named version derives, falling back when nothing was narrowed.
+ *
+ * `V` only pins a directory when inference narrowed it. A wrapper typed
+ * `(version: SupportedApiVersion)` widens it back to the whole union, and
+ * indexing by a union yields a union of directories whose usable methods are
+ * their *intersection* — narrower than the default surface, so naming the
+ * version would buy fewer methods than naming nothing. That case falls back to
+ * {@link DefaultApiDirectory} instead, matching every other shape that loses
+ * the literal. A partial union still derives: methods common to the versions
+ * named is the right answer for "one of these".
+ */
+type DerivedDirectory<V extends SupportedApiVersion> = SupportedApiVersion extends V ? DefaultApiDirectory : ApiDirectoryByVersion[V];
 /** Options for {@link createTrueNasClient}. */
 interface CreateClientOptions {
     /** System UUID. */
@@ -27533,12 +27595,22 @@ interface CreateClientOptions {
      * through the client, to the connection.
      */
     logger?: Logger;
+    /**
+     * The appliance's API version, when the caller already knows it.
+     *
+     * Supplying it skips version discovery entirely — no `GET /api/versions`, no
+     * CORS fallback — and *derives* the client's typed surface from the string,
+     * so `version: 'v27.0.0'` yields `TrueNasApiClient<ApiDirectoryV27_0_0>`
+     * without the caller asserting it through a type parameter.
+     */
+    version?: SupportedApiVersion;
 }
 /**
  * Creates a version-specific TrueNAS API client.
  *
  * 1. Discovers the API version (`GET /api/versions`), asking every hostname in
- *    parallel. The first usable answer wins.
+ *    parallel. The first usable answer wins — *unless* `opts.version` says
+ *    which version this is, in which case discovery is skipped entirely.
  * 2. Selects the matching client implementation (`v25.10.x` -> `TrueNasApiClientV2510`,
  *    `v26.x.y` -> `TrueNasApiClientV26`, `v27.x.y` -> `TrueNasApiClientV27`).
  * 3. Instantiates and returns it.
@@ -27569,9 +27641,77 @@ interface CreateClientOptions {
  * supported version. Operations that must work across versions belong on
  * `client.ops`, which resolves them at runtime.
  *
+ * ## Naming the version instead
+ *
+ * A caller that already knows its appliance — a UI served by the appliance
+ * itself, a test harness against a pinned image — can say so and skip discovery
+ * altogether:
+ *
+ * ```typescript
+ * const client = await createTrueNasClient({
+ *   uuid, hostnames, enabled: true, version: 'v27.0.0',
+ * });
+ * // client: TrueNasApiClient<ApiDirectoryV27_0_0>, derived from the string
+ * ```
+ *
+ * The surface is *derived* rather than asserted: `ApiDirectoryByVersion` maps
+ * the version string to its directory, so the caller writes no cast and names
+ * no directory type. A version this package ships no types for does not
+ * compile.
+ *
+ * **The derivation needs the version to be literal at the call site.** It comes
+ * from inference on `{ version: V }`, so it holds for a string literal written
+ * in the options object (or a `const`-typed one). It does not survive
+ * indirection:
+ *
+ * - `createTrueNasClient<D>({ …, version: 'v27.0.0' })` — an explicit type
+ *   argument makes the derived overload inapplicable, so `D` wins.
+ * - `(v?: SupportedApiVersion) => createTrueNasClient({ …, version: v })` — the
+ *   property is `SupportedApiVersion | undefined`, which no `V` satisfies.
+ * - `(v: SupportedApiVersion) => …` — reaches this overload, but `V` widens to
+ *   the whole union, which derives nothing.
+ * - `const opts: CreateClientOptions = { …, version: 'v27.0.0' }` — the
+ *   annotation widens the property before the call sees it.
+ *
+ * All of them compile, run against the named version, and type as
+ * {@link DefaultApiDirectory}. That fails in the safe direction — understated
+ * types give a compile error at the method call rather than a runtime surprise —
+ * but it is silent, so a wrapper that forwards a version gets none of the
+ * surface it named. Keep the literal at the call site, and if you are adding
+ * `version` to an existing `createTrueNasClient<ApiDirectoryV26_0_0>(opts)`
+ * call, delete the type argument in the same edit.
+ *
+ * Two consequences worth knowing before reaching for it.
+ *
+ * It is a stronger claim than `D` alone, because it also picks 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 whole point. `D` on its own only mistyped the surface; this
+ * mistypes the surface *and* dials the wrong number.
+ *
+ * Compatibility is still checked. Skipping discovery skips the network round
+ * trip, not the range check, which is local and free. Two refusals reach a
+ * caller, and they are not interchangeable:
+ *
+ * - a string that is not a `SupportedApiVersion` at all — only reachable from
+ *   JavaScript — throws a plain `Error` naming the versions that are.
+ * - a version this package ships types for but cannot build a client for
+ *   throws {@link VersionTooNewError}, the same error discovery raises.
+ *
+ * The second is not hypothetical. `MAX_SUPPORTED_VERSION` is a hand-written
+ * literal, and while it matches the newest generated version today, a
+ * regeneration can add a year before anyone writes its client — at which point
+ * that version is nameable, promised by the overload, and has nothing to build.
+ * `VersionTooOldError` has no counterpart here: `MIN_SUPPORTED_VERSION` is
+ * derived from the same list that constrains the type, so nothing nameable is
+ * below it.
+ *
+ * @typeParam V - the version named in `opts.version`, when one is. The returned
+ *   surface is `ApiDirectoryByVersion[V]`, so it is derived rather than chosen.
  * @typeParam D - the generated API surface the client is typed against, as a
- *   whole (`call`, `job`, `event`). Every verb resolves method names against
- *   it, so naming a method this surface does not have is a build error.
+ *   whole (`call`, `job`, `event`), for the discovery path where no version is
+ *   named. Every verb resolves method names against it, so naming a method this
+ *   surface does not have is a build error.
  * @returns a Promise that resolves with the created client, or rejects with a
  *   {@link VersionDiscoveryError} subclass (or a client-selection error).
  *   Rejects if version discovery on all hostnames *fails* and is not recoverable.
@@ -27581,6 +27721,9 @@ interface CreateClientOptions {
  *   bug. A network error alongside a version-compatibility error or a 404 does
  *   *not* reach the fallback — see `selectRepresentativeFailure`.
  */
+declare function createTrueNasClient<V extends SupportedApiVersion>(opts: CreateClientOptions & {
+    version: V;
+}): Promise<TrueNasApiClient<DerivedDirectory<V>>>;
 declare function createTrueNasClient<D extends ApiDirectoryShape = DefaultApiDirectory>(opts: CreateClientOptions): Promise<TrueNasApiClient<D>>;
 
 /**
@@ -27608,6 +27751,7 @@ declare function createTrueNasClient<D extends ApiDirectoryShape = DefaultApiDir
  * - containerStart → virt.instance.start (emits Job updates)
  * - containerStop → virt.instance.stop (emits Job updates)
  * - containerRestart → virt.instance.restart (emits Job updates)
+ * - containerDelete → virt.instance.delete (already a job; takes no options)
  */
 declare class TrueNasApiClientV2510 extends TrueNasApiClient<ApiDirectory$7> {
     /**
@@ -27645,6 +27789,7 @@ declare class TrueNasApiClientV2510 extends TrueNasApiClient<ApiDirectory$7> {
  * - containerStart → container.start (synchronous, emits null)
  * - containerStop → container.stop (emits Job updates)
  * - containerRestart → container.stop + container.start (emits Job, then null)
+ * - containerDelete → container.delete (a job since v26.0.0; force/recursive)
  */
 declare class TrueNasApiClientV26 extends TrueNasApiClient<ApiDirectory$1> {
     /**
@@ -27692,6 +27837,7 @@ declare class TrueNasApiClientV26 extends TrueNasApiClient<ApiDirectory$1> {
  * - containerStart → container.start (synchronous, emits null)
  * - containerStop → container.stop (emits Job updates)
  * - containerRestart → container.stop + container.start (emits Job, then null)
+ * - containerDelete → container.delete (a job since v26.0.0; force/recursive)
  *
  * Those four are currently identical to v26's, because v27 inherits all three
  * container entries the facade touches rather than re-declaring them. Asserted

package/dist/index.js

@@ -3148,7 +3148,29 @@ var TrueNasApiClientV2510 = class extends TrueNasApiClient {
       containerQuery: () => this.api.query("virt.instance.query", [["type", "=", "CONTAINER"]]).pipe(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]);
+      }
     };
   }
 };
@@ -3216,7 +3238,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)]
+      )
     };
   }
 };
@@ -3278,7 +3319,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)]
+      )
     };
   }
 };
@@ -3582,12 +3642,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(