@truenas/api-client 4.0.1 → 4.0.2

package/README.md

@@ -183,6 +183,65 @@ discovery route that resolves against whatever the appliance turned out to be.
 On the named route it cannot: the client class is picked from the version you
 stated, so `ops` is that version's mappings whether or not the server agrees.
 
+`ops` is deliberately flat — `OperationMappings`, not parameterized by the
+directory — so every operation is callable whether or not you pinned a version.
+That is what lets an operation paper over a difference the type system would
+otherwise force the caller to handle.
+
+```ts
+// The same call on every supported version.
+const sessions = await firstValueFrom(
+  client.ops.smbStatus({ infoLevel: 'SESSIONS' })
+);
+
+// A client count is this composed, not a second operation.
+const count = await firstValueFrom(
+  client.ops.smbStatus({
+    infoLevel: 'SESSIONS',
+    options: { count: true },
+    statusOptions: { fast: true },
+  })
+);
+```
+
+`smbStatus` is worth singling out, because it is the first operation whose
+v25.10 leg is invisible to `middlewared --dump-api`. `smb.status` is public on
+v26+ and generated like any other method; on v25.10 it is the same method taking
+the same four positional arguments and returning the same `list | dict | int`,
+but middleware declares it `private=True`, so the dump omits it and no generated
+v25.10 type mentions it. The v25.10 client therefore *asserts* the method exists
+rather than reading it from the directory — a single narrow declaration admitting
+one method name, one argument tuple and one return type, checked against
+middleware source instead of against the dump.
+
+Three consequences worth knowing before you reach for it.
+
+**It needs a full-admin session on v25.10.** Being private there decides
+authorization, not just documentation. `smb.status` declares no roles on
+v25.10, and middleware role-registers a method only `if roles:` — so it is in no
+role's allowlist, and only a **non-STIG full-admin** session, whose allowlist is
+the wildcard `{ method: '*', resource: '*' }`, reaches it. A session holding
+exactly `SHARING_SMB_READ` is refused with `EACCES` on v25.10 and succeeds on
+v26+, where the method carries that role. Under STIG, full admin is expanded to
+the union of its roles' allowlists rather than the wildcard, so it is refused on
+v25.10 as well. The client does not pre-empt any of this: you get middleware's
+own error, on the version where it applies.
+
+**It logs server-side on every dispatch**, which matters if you poll it. v25.10
+is in maintenance and that cost is accepted there, but it is not a pattern to
+extend.
+
+**The result is the union middleware sends** — which arm arrives is decided by
+the options, not the info level — so callers narrow it themselves.
+
+These types are deliberately not the generated ones. `SmbStatusOptions` is not
+v26's `SMBStatusOptions`, and `SmbStatusResponse` is not that method's generated
+response: the generated types describe one version's dump, while these describe
+the contract both versions honour. They are named `Smb…` rather than `SMB…` so
+the two cannot be confused at a call site — and `SmbStatusOptions` is the one
+pair where the names sit closest, since it is the fourth positional argument on
+both versions.
+
 ## Documentation
 
 The API reference is generated from the TSDoc comments in the source with

package/dist/index.cjs

@@ -3449,6 +3449,16 @@ function toAppState(state) {
   }
 }
 
+// src/utils/smb-status.utils.ts
+function toSmbStatusParams(request = {}) {
+  return [
+    request.infoLevel ?? "ALL",
+    request.filters ?? [],
+    request.options ?? {},
+    request.statusOptions ?? {}
+  ];
+}
+
 // src/client/truenas-api-client-v25-10.ts
 var TrueNasApiClientV2510 = class extends TrueNasApiClient {
   /**
@@ -3488,6 +3498,42 @@ var TrueNasApiClientV2510 = class extends TrueNasApiClient {
           );
         }
         return this.api.job("virt.instance.delete", [id]);
+      },
+      // The private leg. See `PrivateSmbStatusCall` for why this is a cast and
+      // not a directory lookup.
+      //
+      // v25.10 answers rather than refusing, for a caller with the authority.
+      // Being private does not stop the method running: `ws_handler/rpc.py`
+      // logs a warning for a private call over websocket and dispatches it
+      // anyway — the `# FIXME: Eventually, prohibit this` above that branch is
+      // still unresolved on master.
+      //
+      // It does decide who may run it. `smb.status` carries no `roles=` here,
+      // and middleware role-registers a method only `if roles:`, so it is in no
+      // role's allowlist and only the non-STIG full-admin wildcard reaches it.
+      // That is documented on `OperationMappings.smbStatus`; this leg does not
+      // pre-empt it. A caller without the authority gets middleware's `EACCES`,
+      // which is the honest answer and the server's to give.
+      //
+      // The server-side warning is per dispatch, and a client count is exactly
+      // the sort of thing a caller polls. Reported at debug rather than warn,
+      // because nothing here is degraded or unhonoured — the request is served
+      // in full — and left to the caller to weigh.
+      //
+      // Future tense, and for the same reason as `containerDelete` above: this
+      // runs when the operation is built, and `api.call` is cold, so no request
+      // has gone out yet and may never. One built observable subscribed twice
+      // dispatches twice; this line is what will happen, not a record that it
+      // did.
+      smbStatus: (request) => {
+        this.logger.debug(
+          "smbStatus: smb.status is private on v25.10; each dispatch will log a warning server-side and needs a non-STIG full-admin session",
+          { method: "smb.status", infoLevel: request?.infoLevel ?? "ALL" }
+        );
+        return this.api.call(
+          "smb.status",
+          toSmbStatusParams(request)
+        );
       }
     };
   }
@@ -3575,7 +3621,16 @@ var TrueNasApiClientV26 = class extends TrueNasApiClient {
       containerDelete: (id, options) => this.api.job(
         "container.delete",
         options ? [parseInt(id, 10), options] : [parseInt(id, 10)]
-      )
+      ),
+      // `smb.status` is public here and gated on `SHARING_SMB_READ`, so it is
+      // an ordinary `call` read straight out of the generated directory — the
+      // one leg of this operation that needs no assertion about the server.
+      //
+      // Not a query verb: middleware returns the same `list | dict | int`
+      // polymorphism a `.query` does, but the generator did not mark the entry
+      // with an `entity`, so `api.query` does not accept it and the union is
+      // handed to the caller to narrow.
+      smbStatus: (request) => this.api.call("smb.status", toSmbStatusParams(request))
     };
   }
 };
@@ -3656,7 +3711,16 @@ var TrueNasApiClientV27 = class extends TrueNasApiClient {
       containerDelete: (id, options) => this.api.job(
         "container.delete",
         options ? [parseInt(id, 10), options] : [parseInt(id, 10)]
-      )
+      ),
+      // `smb.status` is public here and gated on `SHARING_SMB_READ`, so it is
+      // an ordinary `call` read straight out of the generated directory — the
+      // one leg of this operation that needs no assertion about the server.
+      //
+      // Not a query verb: middleware returns the same `list | dict | int`
+      // polymorphism a `.query` does, but the generator did not mark the entry
+      // with an `entity`, so `api.query` does not accept it and the union is
+      // handed to the caller to narrow.
+      smbStatus: (request) => this.api.call("smb.status", toSmbStatusParams(request))
     };
   }
 };