@truenas/api-client 3.0.2 → 3.0.3

package/dist/index.d.cts

@@ -27559,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. */
@@ -27582,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.
@@ -27618,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.
@@ -27630,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>>;
 
 /**

package/dist/index.d.ts

@@ -27559,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. */
@@ -27582,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.
@@ -27618,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.
@@ -27630,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>>;
 
 /**

package/dist/index.js

@@ -3642,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(