@truenas/api-client 9.0.2 → 9.0.3

package/README.md

@@ -171,6 +171,21 @@ client you get. A named `version` skips discovery and also selects the
 WebSocket endpoint, so name the version the appliance actually runs. The types
 follow it when the version is a literal.
 
+To be written against one version but run against whatever the appliance
+serves, as an appliance's own UI is, keep the `version` and move the socket:
+
+```typescript
+const client = await createTrueNasClient({
+  ...options,
+  version: 'v28.0.0',            // the surface you compile against
+  websocketPath: '/api/current', // the appliance's newest version, whichever it is
+});
+```
+
+The client then works against an older or newer release call for call; a
+method or field that release lacks fails when it is called rather than at
+compile time.
+
 For code that must run against any supported release, use `client.ops`. It
 offers the same calls on every version and maps them onto whatever that version
 provides:

package/dist/{chunk-MJFFBJJE.cjs → chunk-DJCZ545I.cjs}

@@ -4308,6 +4308,11 @@ async function createTrueNasClient(opts) {
       `Cannot create client for system ${uuid}: hostnames array is empty`
     );
   }
+  if (opts.websocketPath !== void 0 && !opts.websocketPath.startsWith("/")) {
+    throw new Error(
+      `Cannot create client for system ${uuid}: websocketPath must be an absolute path, got '${opts.websocketPath}'.`
+    );
+  }
   logger.info("Creating versioned API client", {
     uuid: uuid.slice(0, 8),
     hostnames: hostnames.join(", "),
@@ -4337,7 +4342,7 @@ async function createTrueNasClient(opts) {
     logger.info("API version supplied by the caller, skipping discovery", {
       uuid: uuid.slice(0, 8),
       version: known.version,
-      websocketPath: known.websocketPath
+      websocketPath: opts.websocketPath ?? known.websocketPath
     });
     return instantiateClientForVersion(known, opts, logger);
   }
@@ -4356,7 +4361,7 @@ async function createTrueNasClient(opts) {
       // of them anyway.
       hostname: winner.hostname,
       version: version.version,
-      websocketPath: version.websocketPath
+      websocketPath: opts.websocketPath ?? version.websocketPath
     });
   } catch (error) {
     const errorMessage = errorMessageOrDefault(error, "Unknown error");
@@ -4482,6 +4487,7 @@ function clientClassFor(version) {
 function instantiateClientForVersion(version, opts, logger) {
   const { uuid, hostnames, enabled, systemName } = opts;
   const versionKey = clientVersionKey(version);
+  const endpoint = opts.websocketPath === void 0 ? version : { ...version, websocketPath: opts.websocketPath };
   const Client = CLIENT_BY_VERSION_KEY[versionKey];
   if (!Client) {
     logger.error("No client implementation for version", {
@@ -4496,12 +4502,13 @@ function instantiateClientForVersion(version, opts, logger) {
   logger.info(`Instantiating ${Client.name}`, {
     uuid: uuid.slice(0, 8),
     version: version.version,
-    versionKey
+    versionKey,
+    websocketPath: endpoint.websocketPath
   });
   return new Client(
     uuid,
     hostnames,
-    version,
+    endpoint,
     enabled,
     systemName,
     logger,
@@ -4568,5 +4575,5 @@ exports.v25_10_4_exports = v25_10_4_exports;
 exports.v25_10_5_exports = v25_10_5_exports;
 exports.v27_0_0_exports = v27_0_0_exports;
 exports.v28_0_0_exports = v28_0_0_exports;
-//# sourceMappingURL=chunk-MJFFBJJE.cjs.map
-//# sourceMappingURL=chunk-MJFFBJJE.cjs.map
+//# sourceMappingURL=chunk-DJCZ545I.cjs.map
+//# sourceMappingURL=chunk-DJCZ545I.cjs.map