@truenas/api-client 3.0.2 → 3.0.4

package/dist/index.d.cts

@@ -12460,6 +12460,16 @@ declare class TrueNasSocket {
     complete(): void;
 }
 
+/**
+ * The scheme used to reach the appliance, in `location.protocol` form.
+ *
+ * Colon included, so a caller served *by the appliance* can pass
+ * `location.protocol` unchanged. That equivalence only holds same-origin: this
+ * value is spliced onto the hostname the client connects to, so a page served
+ * from somewhere else must say what the appliance uses, not what it uses.
+ */
+type ApplianceProtocol = 'http:' | 'https:';
+
 interface ActiveConnection {
     ws: TrueNasSocket;
     hostname: string;
@@ -12482,6 +12492,7 @@ declare class TrueNasConnection {
     readonly retryDelay: number;
     readonly maxRetry: number;
     readonly logger: Logger;
+    readonly protocol: ApplianceProtocol;
     opened: BehaviorSubject<boolean>;
     closed: Subject<void>;
     hostname: BehaviorSubject<string>;
@@ -12544,7 +12555,7 @@ declare class TrueNasConnection {
      * observable which always emits messages from the current socket.
      */
     messages$: Observable<TrueNasMessage>;
-    constructor(initialEnabled: boolean, hostnames: string[], systemUuid: string, websocketPath: string, systemName?: string | undefined, retryDelay?: number, maxRetry?: number, logger?: Logger);
+    constructor(initialEnabled: boolean, hostnames: string[], systemUuid: string, websocketPath: string, systemName?: string | undefined, retryDelay?: number, maxRetry?: number, logger?: Logger, protocol?: ApplianceProtocol);
     /**
      * whether the connection has exhausted its retries — the **cumulative** snapshot, read
      * synchronously. (Formerly `hasConnectionError()`; renamed to disambiguate it from the
@@ -13192,7 +13203,8 @@ declare abstract class TrueNasApiClient<D extends ApiDirectoryShape = BaseApiDir
     protected readonly systemName: string | undefined;
     /** Logger forwarded to the connection (defaults to a no-op). */
     protected readonly logger: Logger;
-    constructor(uuid: string, hostnames: string[], version: ApiVersion, enabled: boolean, systemName?: string, logger?: Logger);
+    protected readonly protocol: ApplianceProtocol;
+    constructor(uuid: string, hostnames: string[], version: ApiVersion, enabled: boolean, systemName?: string, logger?: Logger, protocol?: ApplianceProtocol);
     /**
      * Get current connection status.
      * @returns true if WebSocket is connected
@@ -27559,6 +27571,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. */
@@ -27582,12 +27607,44 @@ 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;
+    /**
+     * The scheme to reach the appliance on, in `location.protocol` form.
+     *
+     * Selects both halves of the transport: `https:` gives `https` discovery and
+     * a `wss` socket, `http:` gives `http` and `ws`. Defaults to `https:`, which
+     * is what an appliance serves and what Connect uses.
+     *
+     * This describes the *appliance*, not the page. Passing
+     * `location.protocol` is correct when the appliance serves the page — the
+     * same-origin case this exists for — and wrong otherwise. A page on
+     * `http://localhost:5173` talking to an https appliance gets both halves
+     * wrong, but only one of them says so: `fetch` follows the redirect and
+     * discovery appears to work, while the WebSocket has no such tolerance and
+     * fails the handshake without naming the scheme.
+     *
+     * Omitting it against a plaintext appliance is the quieter failure and the
+     * likelier one, since it is the case this option exists for. Discovery tries
+     * `https`, `fetch` rejects, and that is indistinguishable from the CORS block
+     * v25.10.0 has on `/api/versions` — so the fallback fires and the caller gets
+     * a client pinned to v25.10.0, warned about only in the log.
+     */
+    protocol?: ApplianceProtocol;
 }
 /**
  * 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.
@@ -27618,9 +27675,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.
@@ -27630,6 +27755,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>>;
 
 /**
@@ -27789,12 +27917,14 @@ declare class TrueNasApiClientV27 extends TrueNasApiClient<ApiDirectory> {
  */
 declare class VersionDiscovery {
     private readonly logger;
+    private readonly protocol;
     private versionCache;
-    constructor(logger?: Logger);
+    constructor(logger?: Logger, protocol?: ApplianceProtocol);
+    private versionsUrl;
     /**
      * Discovers the API version for a given hostname.
      *
-     * Makes a GET request to `https://{hostname}/api/versions` and returns the latest
+     * Makes a GET request to `{protocol}//{hostname}/api/versions` and returns the latest
      * compatible version. Results are cached per hostname; the cache entry is removed
      * on failure so the next call retries.
      *
@@ -27973,4 +28103,4 @@ type ApiError = JsonRpcError | TrueNasError;
  */
 declare function getApiErrorMessage(error: unknown, fallback?: string): string;
 
-export { type ApiCallDirectory$7 as ApiCallDirectoryV25_10_0, type ApiCallDirectory$6 as ApiCallDirectoryV25_10_1, type ApiCallDirectory$5 as ApiCallDirectoryV25_10_2, type ApiCallDirectory$4 as ApiCallDirectoryV25_10_3, type ApiCallDirectory$3 as ApiCallDirectoryV25_10_4, type ApiCallDirectory$2 as ApiCallDirectoryV25_10_5, type ApiCallDirectory$1 as ApiCallDirectoryV26_0_0, type ApiCallDirectory as ApiCallDirectoryV27_0_0, type ApiDirectoryByVersion, type ApiDirectoryShape, type ApiDirectory$7 as ApiDirectoryV25_10_0, type ApiDirectory$6 as ApiDirectoryV25_10_1, type ApiDirectory$5 as ApiDirectoryV25_10_2, type ApiDirectory$4 as ApiDirectoryV25_10_3, type ApiDirectory$3 as ApiDirectoryV25_10_4, type ApiDirectory$2 as ApiDirectoryV25_10_5, type ApiDirectory$1 as ApiDirectoryV26_0_0, type ApiDirectory as ApiDirectoryV27_0_0, type ApiError, type ApiEventDirectory$7 as ApiEventDirectoryV25_10_0, type ApiEventDirectory$6 as ApiEventDirectoryV25_10_1, type ApiEventDirectory$5 as ApiEventDirectoryV25_10_2, type ApiEventDirectory$4 as ApiEventDirectoryV25_10_3, type ApiEventDirectory$3 as ApiEventDirectoryV25_10_4, type ApiEventDirectory$2 as ApiEventDirectoryV25_10_5, type ApiEventDirectory$1 as ApiEventDirectoryV26_0_0, type ApiEventDirectory as ApiEventDirectoryV27_0_0, type ApiJobDirectory$7 as ApiJobDirectoryV25_10_0, type ApiJobDirectory$6 as ApiJobDirectoryV25_10_1, type ApiJobDirectory$5 as ApiJobDirectoryV25_10_2, type ApiJobDirectory$4 as ApiJobDirectoryV25_10_3, type ApiJobDirectory$3 as ApiJobDirectoryV25_10_4, type ApiJobDirectory$2 as ApiJobDirectoryV25_10_5, type ApiJobDirectory$1 as ApiJobDirectoryV26_0_0, type ApiJobDirectory as ApiJobDirectoryV27_0_0, type ApiKeyCreate, type ApiVersion, type ApiVersionResponse, AppState, type ArgsOf, AuthError, AuthErrorCode, type AuthResponse, type BaseApiDirectory, type CallMethod, type CallParams, type CallResponse, type Container, type CreateClientOptions, type DefaultApiDirectory, type EventKind, type EventName, type EventUnion, InvalidVersionResponseError, type Job, type JobMethod, type JobParams, type JobProgress, type JobResult, JobState, type Logger, NoCompatibleVersionsError, type OperationMappings, type QueryDirectory, type QueryEntity, type QueryListOptions, type QueryMethod, type QuerySingleOptions, SUPPORTED_API_VERSIONS, type SupportedApiVersion, TrueNasApiClient, TrueNasApiClientV2510, TrueNasApiClientV26, TrueNasApiClientV27, TrueNasAuthMechanism, type TrueNasDate, VersionCompatibility, VersionDiscovery, VersionDiscoveryError, VersionDiscoveryNetworkError, VersionDiscoveryTimeoutError, VersionEndpointNotFoundError, VersionTooNewError, VersionTooOldError, consoleLogger, createTrueNasClient, getApiErrorMessage, isJobFinished, noopLogger, index$7 as v25_10_0, index$6 as v25_10_1, index$5 as v25_10_2, index$4 as v25_10_3, index$3 as v25_10_4, index$2 as v25_10_5, index$1 as v26_0_0, index as v27_0_0 };
+export { type ApiCallDirectory$7 as ApiCallDirectoryV25_10_0, type ApiCallDirectory$6 as ApiCallDirectoryV25_10_1, type ApiCallDirectory$5 as ApiCallDirectoryV25_10_2, type ApiCallDirectory$4 as ApiCallDirectoryV25_10_3, type ApiCallDirectory$3 as ApiCallDirectoryV25_10_4, type ApiCallDirectory$2 as ApiCallDirectoryV25_10_5, type ApiCallDirectory$1 as ApiCallDirectoryV26_0_0, type ApiCallDirectory as ApiCallDirectoryV27_0_0, type ApiDirectoryByVersion, type ApiDirectoryShape, type ApiDirectory$7 as ApiDirectoryV25_10_0, type ApiDirectory$6 as ApiDirectoryV25_10_1, type ApiDirectory$5 as ApiDirectoryV25_10_2, type ApiDirectory$4 as ApiDirectoryV25_10_3, type ApiDirectory$3 as ApiDirectoryV25_10_4, type ApiDirectory$2 as ApiDirectoryV25_10_5, type ApiDirectory$1 as ApiDirectoryV26_0_0, type ApiDirectory as ApiDirectoryV27_0_0, type ApiError, type ApiEventDirectory$7 as ApiEventDirectoryV25_10_0, type ApiEventDirectory$6 as ApiEventDirectoryV25_10_1, type ApiEventDirectory$5 as ApiEventDirectoryV25_10_2, type ApiEventDirectory$4 as ApiEventDirectoryV25_10_3, type ApiEventDirectory$3 as ApiEventDirectoryV25_10_4, type ApiEventDirectory$2 as ApiEventDirectoryV25_10_5, type ApiEventDirectory$1 as ApiEventDirectoryV26_0_0, type ApiEventDirectory as ApiEventDirectoryV27_0_0, type ApiJobDirectory$7 as ApiJobDirectoryV25_10_0, type ApiJobDirectory$6 as ApiJobDirectoryV25_10_1, type ApiJobDirectory$5 as ApiJobDirectoryV25_10_2, type ApiJobDirectory$4 as ApiJobDirectoryV25_10_3, type ApiJobDirectory$3 as ApiJobDirectoryV25_10_4, type ApiJobDirectory$2 as ApiJobDirectoryV25_10_5, type ApiJobDirectory$1 as ApiJobDirectoryV26_0_0, type ApiJobDirectory as ApiJobDirectoryV27_0_0, type ApiKeyCreate, type ApiVersion, type ApiVersionResponse, AppState, type ApplianceProtocol, type ArgsOf, AuthError, AuthErrorCode, type AuthResponse, type BaseApiDirectory, type CallMethod, type CallParams, type CallResponse, type Container, type CreateClientOptions, type DefaultApiDirectory, type EventKind, type EventName, type EventUnion, InvalidVersionResponseError, type Job, type JobMethod, type JobParams, type JobProgress, type JobResult, JobState, type Logger, NoCompatibleVersionsError, type OperationMappings, type QueryDirectory, type QueryEntity, type QueryListOptions, type QueryMethod, type QuerySingleOptions, SUPPORTED_API_VERSIONS, type SupportedApiVersion, TrueNasApiClient, TrueNasApiClientV2510, TrueNasApiClientV26, TrueNasApiClientV27, TrueNasAuthMechanism, type TrueNasDate, VersionCompatibility, VersionDiscovery, VersionDiscoveryError, VersionDiscoveryNetworkError, VersionDiscoveryTimeoutError, VersionEndpointNotFoundError, VersionTooNewError, VersionTooOldError, consoleLogger, createTrueNasClient, getApiErrorMessage, isJobFinished, noopLogger, index$7 as v25_10_0, index$6 as v25_10_1, index$5 as v25_10_2, index$4 as v25_10_3, index$3 as v25_10_4, index$2 as v25_10_5, index$1 as v26_0_0, index as v27_0_0 };

package/dist/index.d.ts

@@ -12460,6 +12460,16 @@ declare class TrueNasSocket {
     complete(): void;
 }
 
+/**
+ * The scheme used to reach the appliance, in `location.protocol` form.
+ *
+ * Colon included, so a caller served *by the appliance* can pass
+ * `location.protocol` unchanged. That equivalence only holds same-origin: this
+ * value is spliced onto the hostname the client connects to, so a page served
+ * from somewhere else must say what the appliance uses, not what it uses.
+ */
+type ApplianceProtocol = 'http:' | 'https:';
+
 interface ActiveConnection {
     ws: TrueNasSocket;
     hostname: string;
@@ -12482,6 +12492,7 @@ declare class TrueNasConnection {
     readonly retryDelay: number;
     readonly maxRetry: number;
     readonly logger: Logger;
+    readonly protocol: ApplianceProtocol;
     opened: BehaviorSubject<boolean>;
     closed: Subject<void>;
     hostname: BehaviorSubject<string>;
@@ -12544,7 +12555,7 @@ declare class TrueNasConnection {
      * observable which always emits messages from the current socket.
      */
     messages$: Observable<TrueNasMessage>;
-    constructor(initialEnabled: boolean, hostnames: string[], systemUuid: string, websocketPath: string, systemName?: string | undefined, retryDelay?: number, maxRetry?: number, logger?: Logger);
+    constructor(initialEnabled: boolean, hostnames: string[], systemUuid: string, websocketPath: string, systemName?: string | undefined, retryDelay?: number, maxRetry?: number, logger?: Logger, protocol?: ApplianceProtocol);
     /**
      * whether the connection has exhausted its retries — the **cumulative** snapshot, read
      * synchronously. (Formerly `hasConnectionError()`; renamed to disambiguate it from the
@@ -13192,7 +13203,8 @@ declare abstract class TrueNasApiClient<D extends ApiDirectoryShape = BaseApiDir
     protected readonly systemName: string | undefined;
     /** Logger forwarded to the connection (defaults to a no-op). */
     protected readonly logger: Logger;
-    constructor(uuid: string, hostnames: string[], version: ApiVersion, enabled: boolean, systemName?: string, logger?: Logger);
+    protected readonly protocol: ApplianceProtocol;
+    constructor(uuid: string, hostnames: string[], version: ApiVersion, enabled: boolean, systemName?: string, logger?: Logger, protocol?: ApplianceProtocol);
     /**
      * Get current connection status.
      * @returns true if WebSocket is connected
@@ -27559,6 +27571,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. */
@@ -27582,12 +27607,44 @@ 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;
+    /**
+     * The scheme to reach the appliance on, in `location.protocol` form.
+     *
+     * Selects both halves of the transport: `https:` gives `https` discovery and
+     * a `wss` socket, `http:` gives `http` and `ws`. Defaults to `https:`, which
+     * is what an appliance serves and what Connect uses.
+     *
+     * This describes the *appliance*, not the page. Passing
+     * `location.protocol` is correct when the appliance serves the page — the
+     * same-origin case this exists for — and wrong otherwise. A page on
+     * `http://localhost:5173` talking to an https appliance gets both halves
+     * wrong, but only one of them says so: `fetch` follows the redirect and
+     * discovery appears to work, while the WebSocket has no such tolerance and
+     * fails the handshake without naming the scheme.
+     *
+     * Omitting it against a plaintext appliance is the quieter failure and the
+     * likelier one, since it is the case this option exists for. Discovery tries
+     * `https`, `fetch` rejects, and that is indistinguishable from the CORS block
+     * v25.10.0 has on `/api/versions` — so the fallback fires and the caller gets
+     * a client pinned to v25.10.0, warned about only in the log.
+     */
+    protocol?: ApplianceProtocol;
 }
 /**
  * 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.
@@ -27618,9 +27675,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.
@@ -27630,6 +27755,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>>;
 
 /**
@@ -27789,12 +27917,14 @@ declare class TrueNasApiClientV27 extends TrueNasApiClient<ApiDirectory> {
  */
 declare class VersionDiscovery {
     private readonly logger;
+    private readonly protocol;
     private versionCache;
-    constructor(logger?: Logger);
+    constructor(logger?: Logger, protocol?: ApplianceProtocol);
+    private versionsUrl;
     /**
      * Discovers the API version for a given hostname.
      *
-     * Makes a GET request to `https://{hostname}/api/versions` and returns the latest
+     * Makes a GET request to `{protocol}//{hostname}/api/versions` and returns the latest
      * compatible version. Results are cached per hostname; the cache entry is removed
      * on failure so the next call retries.
      *
@@ -27973,4 +28103,4 @@ type ApiError = JsonRpcError | TrueNasError;
  */
 declare function getApiErrorMessage(error: unknown, fallback?: string): string;
 
-export { type ApiCallDirectory$7 as ApiCallDirectoryV25_10_0, type ApiCallDirectory$6 as ApiCallDirectoryV25_10_1, type ApiCallDirectory$5 as ApiCallDirectoryV25_10_2, type ApiCallDirectory$4 as ApiCallDirectoryV25_10_3, type ApiCallDirectory$3 as ApiCallDirectoryV25_10_4, type ApiCallDirectory$2 as ApiCallDirectoryV25_10_5, type ApiCallDirectory$1 as ApiCallDirectoryV26_0_0, type ApiCallDirectory as ApiCallDirectoryV27_0_0, type ApiDirectoryByVersion, type ApiDirectoryShape, type ApiDirectory$7 as ApiDirectoryV25_10_0, type ApiDirectory$6 as ApiDirectoryV25_10_1, type ApiDirectory$5 as ApiDirectoryV25_10_2, type ApiDirectory$4 as ApiDirectoryV25_10_3, type ApiDirectory$3 as ApiDirectoryV25_10_4, type ApiDirectory$2 as ApiDirectoryV25_10_5, type ApiDirectory$1 as ApiDirectoryV26_0_0, type ApiDirectory as ApiDirectoryV27_0_0, type ApiError, type ApiEventDirectory$7 as ApiEventDirectoryV25_10_0, type ApiEventDirectory$6 as ApiEventDirectoryV25_10_1, type ApiEventDirectory$5 as ApiEventDirectoryV25_10_2, type ApiEventDirectory$4 as ApiEventDirectoryV25_10_3, type ApiEventDirectory$3 as ApiEventDirectoryV25_10_4, type ApiEventDirectory$2 as ApiEventDirectoryV25_10_5, type ApiEventDirectory$1 as ApiEventDirectoryV26_0_0, type ApiEventDirectory as ApiEventDirectoryV27_0_0, type ApiJobDirectory$7 as ApiJobDirectoryV25_10_0, type ApiJobDirectory$6 as ApiJobDirectoryV25_10_1, type ApiJobDirectory$5 as ApiJobDirectoryV25_10_2, type ApiJobDirectory$4 as ApiJobDirectoryV25_10_3, type ApiJobDirectory$3 as ApiJobDirectoryV25_10_4, type ApiJobDirectory$2 as ApiJobDirectoryV25_10_5, type ApiJobDirectory$1 as ApiJobDirectoryV26_0_0, type ApiJobDirectory as ApiJobDirectoryV27_0_0, type ApiKeyCreate, type ApiVersion, type ApiVersionResponse, AppState, type ArgsOf, AuthError, AuthErrorCode, type AuthResponse, type BaseApiDirectory, type CallMethod, type CallParams, type CallResponse, type Container, type CreateClientOptions, type DefaultApiDirectory, type EventKind, type EventName, type EventUnion, InvalidVersionResponseError, type Job, type JobMethod, type JobParams, type JobProgress, type JobResult, JobState, type Logger, NoCompatibleVersionsError, type OperationMappings, type QueryDirectory, type QueryEntity, type QueryListOptions, type QueryMethod, type QuerySingleOptions, SUPPORTED_API_VERSIONS, type SupportedApiVersion, TrueNasApiClient, TrueNasApiClientV2510, TrueNasApiClientV26, TrueNasApiClientV27, TrueNasAuthMechanism, type TrueNasDate, VersionCompatibility, VersionDiscovery, VersionDiscoveryError, VersionDiscoveryNetworkError, VersionDiscoveryTimeoutError, VersionEndpointNotFoundError, VersionTooNewError, VersionTooOldError, consoleLogger, createTrueNasClient, getApiErrorMessage, isJobFinished, noopLogger, index$7 as v25_10_0, index$6 as v25_10_1, index$5 as v25_10_2, index$4 as v25_10_3, index$3 as v25_10_4, index$2 as v25_10_5, index$1 as v26_0_0, index as v27_0_0 };
+export { type ApiCallDirectory$7 as ApiCallDirectoryV25_10_0, type ApiCallDirectory$6 as ApiCallDirectoryV25_10_1, type ApiCallDirectory$5 as ApiCallDirectoryV25_10_2, type ApiCallDirectory$4 as ApiCallDirectoryV25_10_3, type ApiCallDirectory$3 as ApiCallDirectoryV25_10_4, type ApiCallDirectory$2 as ApiCallDirectoryV25_10_5, type ApiCallDirectory$1 as ApiCallDirectoryV26_0_0, type ApiCallDirectory as ApiCallDirectoryV27_0_0, type ApiDirectoryByVersion, type ApiDirectoryShape, type ApiDirectory$7 as ApiDirectoryV25_10_0, type ApiDirectory$6 as ApiDirectoryV25_10_1, type ApiDirectory$5 as ApiDirectoryV25_10_2, type ApiDirectory$4 as ApiDirectoryV25_10_3, type ApiDirectory$3 as ApiDirectoryV25_10_4, type ApiDirectory$2 as ApiDirectoryV25_10_5, type ApiDirectory$1 as ApiDirectoryV26_0_0, type ApiDirectory as ApiDirectoryV27_0_0, type ApiError, type ApiEventDirectory$7 as ApiEventDirectoryV25_10_0, type ApiEventDirectory$6 as ApiEventDirectoryV25_10_1, type ApiEventDirectory$5 as ApiEventDirectoryV25_10_2, type ApiEventDirectory$4 as ApiEventDirectoryV25_10_3, type ApiEventDirectory$3 as ApiEventDirectoryV25_10_4, type ApiEventDirectory$2 as ApiEventDirectoryV25_10_5, type ApiEventDirectory$1 as ApiEventDirectoryV26_0_0, type ApiEventDirectory as ApiEventDirectoryV27_0_0, type ApiJobDirectory$7 as ApiJobDirectoryV25_10_0, type ApiJobDirectory$6 as ApiJobDirectoryV25_10_1, type ApiJobDirectory$5 as ApiJobDirectoryV25_10_2, type ApiJobDirectory$4 as ApiJobDirectoryV25_10_3, type ApiJobDirectory$3 as ApiJobDirectoryV25_10_4, type ApiJobDirectory$2 as ApiJobDirectoryV25_10_5, type ApiJobDirectory$1 as ApiJobDirectoryV26_0_0, type ApiJobDirectory as ApiJobDirectoryV27_0_0, type ApiKeyCreate, type ApiVersion, type ApiVersionResponse, AppState, type ApplianceProtocol, type ArgsOf, AuthError, AuthErrorCode, type AuthResponse, type BaseApiDirectory, type CallMethod, type CallParams, type CallResponse, type Container, type CreateClientOptions, type DefaultApiDirectory, type EventKind, type EventName, type EventUnion, InvalidVersionResponseError, type Job, type JobMethod, type JobParams, type JobProgress, type JobResult, JobState, type Logger, NoCompatibleVersionsError, type OperationMappings, type QueryDirectory, type QueryEntity, type QueryListOptions, type QueryMethod, type QuerySingleOptions, SUPPORTED_API_VERSIONS, type SupportedApiVersion, TrueNasApiClient, TrueNasApiClientV2510, TrueNasApiClientV26, TrueNasApiClientV27, TrueNasAuthMechanism, type TrueNasDate, VersionCompatibility, VersionDiscovery, VersionDiscoveryError, VersionDiscoveryNetworkError, VersionDiscoveryTimeoutError, VersionEndpointNotFoundError, VersionTooNewError, VersionTooOldError, consoleLogger, createTrueNasClient, getApiErrorMessage, isJobFinished, noopLogger, index$7 as v25_10_0, index$6 as v25_10_1, index$5 as v25_10_2, index$4 as v25_10_3, index$3 as v25_10_4, index$2 as v25_10_5, index$1 as v26_0_0, index as v27_0_0 };

package/dist/index.js

@@ -692,11 +692,19 @@ var TrueNasSocket = class {
   }
 };
 
+// src/types/transport.type.ts
+function httpScheme(protocol) {
+  return protocol === "http:" ? "http:" : "https:";
+}
+function socketScheme(protocol) {
+  return protocol === "http:" ? "ws:" : "wss:";
+}
+
 // src/connection/truenas-connection.ts
 var tenSeconds = 10 * 1e3;
 var twentySeconds = 20 * 1e3;
 var TrueNasConnection = class {
-  constructor(initialEnabled, hostnames, systemUuid, websocketPath, systemName, retryDelay = tenSeconds, maxRetry = 3, logger = noopLogger) {
+  constructor(initialEnabled, hostnames, systemUuid, websocketPath, systemName, retryDelay = tenSeconds, maxRetry = 3, logger = noopLogger, protocol = "https:") {
     this.hostnames = hostnames;
     this.systemUuid = systemUuid;
     this.websocketPath = websocketPath;
@@ -704,6 +712,7 @@ var TrueNasConnection = class {
     this.retryDelay = retryDelay;
     this.maxRetry = maxRetry;
     this.logger = logger;
+    this.protocol = protocol;
     // compatibility properties
     this.opened = new BehaviorSubject(false);
     this.closed = new Subject();
@@ -900,7 +909,7 @@ var TrueNasConnection = class {
    * error if the connection is never established and will not complete until unsubscribed from or closed.
    */
   createSocket(hostname) {
-    const url = `wss://${hostname}${this.websocketPath}`;
+    const url = `${socketScheme(this.protocol)}//${hostname}${this.websocketPath}`;
     let hasOpened = false;
     return new Observable((subscriber) => {
       const ws = new TrueNasSocket({
@@ -2999,13 +3008,14 @@ function getWebSocketPath(version) {
 
 // src/client/truenas-api-client.ts
 var TrueNasApiClient = class {
-  constructor(uuid, hostnames, version, enabled, systemName, logger = noopLogger) {
+  constructor(uuid, hostnames, version, enabled, systemName, logger = noopLogger, protocol = "https:") {
     this.uuid = uuid;
     this.hostnames = hostnames;
     this.version = version;
     this.enabled = enabled;
     this.systemName = systemName;
     this.logger = logger;
+    this.protocol = protocol;
     this.connection = this.createConnection();
     this.authenticator = this.createAuthenticator();
     this.api = this.createApi();
@@ -3048,7 +3058,8 @@ var TrueNasApiClient = class {
       // retryDelay (use default)
       void 0,
       // maxRetry (use default)
-      this.logger
+      this.logger,
+      this.protocol
     );
   }
   /**
@@ -3442,14 +3453,18 @@ function hasErrorName(error, expected) {
   return typeof error === "object" && error !== null && "name" in error && error.name === expected;
 }
 var VersionDiscovery = class {
-  constructor(logger = noopLogger) {
+  constructor(logger = noopLogger, protocol = "https:") {
     this.logger = logger;
+    this.protocol = protocol;
     this.versionCache = /* @__PURE__ */ new Map();
   }
+  versionsUrl(hostname) {
+    return `${httpScheme(this.protocol)}//${hostname}/api/versions`;
+  }
   /**
    * Discovers the API version for a given hostname.
    *
-   * Makes a GET request to `https://{hostname}/api/versions` and returns the latest
+   * Makes a GET request to `{protocol}//{hostname}/api/versions` and returns the latest
    * compatible version. Results are cached per hostname; the cache entry is removed
    * on failure so the next call retries.
    *
@@ -3463,8 +3478,10 @@ var VersionDiscovery = class {
       this.logger.info("Version discovery cache hit", { hostname });
       return cached;
     }
-    const url = `https://${hostname}/api/versions`;
-    this.logger.info("Starting version discovery", { hostname, url });
+    this.logger.info("Starting version discovery", {
+      hostname,
+      url: this.versionsUrl(hostname)
+    });
     const discovery$ = defer(() => from(this.fetchVersions(hostname))).pipe(
       map$1((versionStrings) => this.selectVersion(hostname, versionStrings)),
       catchError((error) => {
@@ -3502,7 +3519,7 @@ var VersionDiscovery = class {
    * misfile as a network error. Validating here keeps it an `InvalidVersionResponseError`.
    */
   async fetchVersions(hostname) {
-    const url = `https://${hostname}/api/versions`;
+    const url = this.versionsUrl(hostname);
     const controller = new AbortController();
     const timer2 = setTimeout(() => controller.abort(), discoveryTimeoutMs);
     try {
@@ -3642,12 +3659,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, opts.protocol);
   let version;
   try {
     const winner = await discoverVersionFromAnyHostname(
@@ -3756,7 +3801,8 @@ function instantiateClientForVersion(version, opts, logger) {
     version,
     enabled,
     systemName,
-    logger
+    logger,
+    opts.protocol
   );
 }
 function errorMessageOrDefault(error, fallback) {