@truenas/api-client 4.0.0 → 4.0.2

package/dist/index.d.cts

@@ -14509,6 +14509,103 @@ interface ContainerRestartOptions {
     force: boolean;
 }
 
+/**
+ * Types for the version-agnostic `ops.smbStatus` operation.
+ *
+ * `smb.status` is one method with two different standings. On v26+ it is a
+ * public, role-gated endpoint (`SHARING_SMB_READ`) and appears in the generated
+ * directory. On v25.10 it is declared `private=True`, so `--dump-api` never
+ * emitted it and no generated v25.10 type describes it — but the method is
+ * there, under the same name, taking the same four positional arguments and
+ * returning the same union. These types describe that shared wire contract
+ * once, so the operation can present a single shape on every version.
+ *
+ * They are deliberately *not* re-exports of the generated v26 types. Those
+ * describe one version's dump; this describes the contract both versions
+ * happen to honour, and the two are only equal for as long as they stay equal.
+ */
+/**
+ * The kind of status being asked for.
+ *
+ * Neither version offers a seventh, but for two different reasons. v25.10
+ * carries a legacy `AUTH_LOG` in its enum and its implementation — it routes to
+ * `audit.query` rather than to `smbstatus` — while its own argument model
+ * refuses it: the `Literal` there lists exactly these six. It is unreachable
+ * even from middleware's own internal calls, because `api_method` validates
+ * every invocation. v26+ does not have it at all; the level was deleted rather
+ * than left dormant.
+ */
+type SmbStatusInfoLevel = 'ALL' | 'SESSIONS' | 'SHARES' | 'LOCKS' | 'BYTERANGE' | 'NOTIFICATIONS';
+/**
+ * Server-side options for the status query itself.
+ *
+ * Field names are snake_case because this object is passed to middleware
+ * verbatim; it is the wire shape, not a translation of it.
+ *
+ * Every field is optional here, matching the generated v26 type. Middleware
+ * defaults them on both versions — `verbose` and `resolve_uids` to true,
+ * `fast` to false, the two `restrict_*` to empty strings.
+ */
+interface SmbStatusOptions {
+    verbose?: boolean;
+    fast?: boolean;
+    restrict_user?: string;
+    restrict_session?: string;
+    resolve_uids?: boolean;
+}
+/**
+ * Rows returned by `smb.status` are not modelled by either version.
+ *
+ * The middleware result model is `list[dict] | dict | int` on both, and the
+ * dump reproduces that as a `Record<string, unknown>` — the shape genuinely
+ * varies with `info_level`, and neither version declares the per-level
+ * structures. Callers narrow it themselves.
+ */
+type SmbStatusRow = Record<string, unknown>;
+/**
+ * What `smb.status` may return.
+ *
+ * The three arms are not interchangeable and which one arrives is decided by
+ * the options, not by the info level: `{ count: true }` gives the number,
+ * `{ get: true }` a single row, anything else the list. This is the same
+ * polymorphism the query verbs exist to resolve, but `smb.status` is not a
+ * `.query` method — the generator did not mark it with an `entity` — so the
+ * union is returned as-is and the caller narrows.
+ */
+type SmbStatusResponse = SmbStatusRow[] | SmbStatusRow | number;
+/**
+ * Arguments for {@link OperationMappings.smbStatus}.
+ *
+ * A single object rather than four positional parameters: the wire form is
+ * positional and every argument is optional, so a caller wanting only
+ * `statusOptions` — the fourth — would otherwise have to pass three
+ * placeholder arguments to reach it. The operation maps this back onto the
+ * positional array.
+ */
+interface SmbStatusRequest {
+    /** Defaults to `ALL` on both versions. */
+    infoLevel?: SmbStatusInfoLevel;
+    /**
+     * Query filters applied to the rows.
+     *
+     * Both versions special-case a lone `uid` or `session_id` equality filter,
+     * turning it into the corresponding `restrict_*` status option instead of
+     * filtering after the fact.
+     *
+     * That *overwrites* the status option rather than combining with it. Passing
+     * `filters: [['uid', '=', 1000]]` together with
+     * `statusOptions: { restrict_user: 'bob' }` sends both, and middleware
+     * discards `'bob'`. This is middleware's behaviour on both versions, carried
+     * through unchanged — but the two look like they compose and do not, so do
+     * not set both.
+     */
+    filters?: QueryFilters<SmbStatusRow>;
+    /** Query options. `{ count: true }` is what makes the result a number. */
+    options?: QueryOptions<SmbStatusRow>;
+    /** Options for the status command itself. */
+    statusOptions?: SmbStatusOptions;
+}
+
 /**
  * OperationMappings Interface
  *
@@ -14594,6 +14691,64 @@ interface OperationMappings {
      * ignored, because `recursive` destroys data that cannot be recovered.
      */
     containerDelete: (id: string, options?: ContainerDeleteOptions$1) => Observable<Job | null>;
+    /**
+     * Read SMB server status — sessions, shares, locks, notifications.
+     *
+     * - v25.10: `smb.status`, which is declared `private=True` there
+     * - v26+: `smb.status`, public and gated on the `SHARING_SMB_READ` role
+     *
+     * The same method under the same name on both, taking the same four
+     * positional arguments and returning the same `list | dict | int` union. That
+     * is why this reads as one operation rather than a v26 feature with a v25.10
+     * excuse, and why v25.10 returns real data instead of throwing.
+     *
+     * **The two versions are not equally reachable, though.** Being private on
+     * v25.10 is not only a statement about documentation — it decides
+     * authorization too, and this is the one respect in which the operation
+     * cannot present a single face:
+     *
+     * - **v26+** declares `roles=['SHARING_SMB_READ']`, so any session holding
+     *   that role may call it.
+     * - **v25.10** declares no roles at all. Middleware registers a method with
+     *   the role manager only `if roles:`, so `smb.status` is in no role's
+     *   allowlist, and `authorize('CALL', 'smb.status')` fails for a role-scoped
+     *   session with `Not authorized` (`EACCES`). A session holding exactly
+     *   `SHARING_SMB_READ` — the role that works on v26+ — is refused on v25.10.
+     * - What does reach it is a **non-STIG full-admin** session, whose allowlist
+     *   is the wildcard `{ method: '*', resource: '*' }`. Under STIG, full admin
+     *   is expanded to the union of its roles' allowlists instead of the
+     *   wildcard, and `smb.status` is in none of them — so STIG full admin is
+     *   refused on v25.10 as well.
+     *
+     * Nothing here pre-empts that. The operation does not inspect the session or
+     * refuse ahead of the server; a caller lacking the authority gets
+     * middleware's own error, on the version where it applies.
+     *
+     * It is the first operation whose v25.10 leg is invisible to `--dump-api`: no
+     * generated v25.10 type describes `smb.status`, because the dump omits
+     * private methods. The v25.10 client therefore asserts the method's existence
+     * rather than reading it from the directory, and that assertion is checked
+     * against middleware source, not against the dump. See
+     * `TrueNasApiClientV2510.createOperations`.
+     *
+     * Calling a private method logs a warning server-side on every invocation.
+     * That is accepted for v25.10, which is in maintenance; it is not a pattern
+     * to extend to versions still taking features.
+     *
+     * A client count is this composed rather than given its own operation, since
+     * it is the same endpoint with different options:
+     *
+     * ```typescript
+     * truenas.ops
+     *   .smbStatus({
+     *     infoLevel: 'SESSIONS',
+     *     options: { count: true },
+     *     statusOptions: { fast: true },
+     *   })
+     *   .subscribe((count) => console.log(count as number));
+     * ```
+     */
+    smbStatus: (request?: SmbStatusRequest) => Observable<SmbStatusResponse>;
 }
 
 /**
@@ -30429,9 +30584,10 @@ interface CreateClientOptions {
      *
      * 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.
+     * `https` and `fetch` rejects, which reads exactly like the CORS block
+     * v25.10.0 has on `/api/versions`. The reachability probe now runs on the same
+     * scheme and fails the same way, so the mismatch is reported as unreachable
+     * rather than quietly answered with a v25.10.0 client.
      */
     protocol?: ApplianceProtocol;
 }
@@ -30545,11 +30701,18 @@ interface CreateClientOptions {
  * @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.
- *   Note that when the selected failure is a `VersionDiscoveryNetworkError`,
- *   this function attempts to use a fallback API version (see `FALLBACK_VERSION`)
- *   because network errors are actually expected on 25.10.0 systems due to a CORS
- *   bug. A network error alongside a version-compatibility error or a 404 does
- *   *not* reach the fallback — see `selectRepresentativeFailure`.
+ *
+ *   A `VersionDiscoveryNetworkError` is not by itself a verdict: `fetch` reports
+ *   a CORS refusal, an absent appliance, a bad name and the wrong scheme
+ *   identically. So that failure opens a reachability probe and a second
+ *   discovery attempt. A retry that succeeds is used; one that fails with a
+ *   specific error raises that instead; an appliance that answers nothing
+ *   rejects with the network error. Only one that answers the probe and still
+ *   will not serve `/api/versions` — which is what 25.10.0 looks like from a
+ *   browser — falls back to `FALLBACK_VERSION`.
+ *
+ *   A network error alongside a version-compatibility error or a 404 does
+ *   *not* reach any of that — see `selectRepresentativeFailure`.
  */
 declare function createTrueNasClient<V extends SupportedApiVersion>(opts: CreateClientOptions & {
     version: V;
@@ -30582,6 +30745,12 @@ declare function createTrueNasClient<D extends ApiDirectoryShape = DefaultApiDir
  * - containerStop → virt.instance.stop (emits Job updates)
  * - containerRestart → virt.instance.restart (emits Job updates)
  * - containerDelete → virt.instance.delete (already a job; takes no options)
+ *
+ * SMB operations:
+ * - smbStatus → smb.status, which is declared `private=True` on this version
+ *   and so is absent from the generated directory. See `PrivateSmbStatusCall`
+ *   for how it is reached and why that is a cast, and `OperationMappings` for
+ *   the authorization difference being private carries with it here.
  */
 declare class TrueNasApiClientV2510 extends TrueNasApiClient<ApiDirectory$7> {
     /**
@@ -30620,6 +30789,9 @@ declare class TrueNasApiClientV2510 extends TrueNasApiClient<ApiDirectory$7> {
  * - 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)
+ *
+ * SMB operations:
+ * - smbStatus → smb.status, public here and gated on `SHARING_SMB_READ`
  */
 declare class TrueNasApiClientV26 extends TrueNasApiClient<ApiDirectory$1> {
     /**
@@ -30669,10 +30841,26 @@ declare class TrueNasApiClientV26 extends TrueNasApiClient<ApiDirectory$1> {
  * - 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
- * rather than assumed, and re-runnable: the spec pins all three against v26's,
- * so the day they diverge is a failure there.
+ * SMB operations:
+ * - smbStatus → smb.status, public and gated on `SHARING_SMB_READ`, as v26.
+ *   v27 inherits the entry rather than re-declaring it.
+ *
+ * All five container operations are currently identical to v26's, because v27
+ * inherits the container entries the facade touches rather than re-declaring
+ * them. Five operations, four entries — `containerRestart` has none of its own,
+ * being `container.stop` then `container.start`. Asserted rather than assumed,
+ * and re-runnable: the spec pins all four entries — `container.query`,
+ * `.start`, `.stop`, `.delete` — against v26's, so the day they diverge is a
+ * failure there.
+ *
+ * `smbStatus` is not among them. Its v27 entry is inherited from v26 too, but
+ * nothing pins it the way the container entries are pinned. `tsc` is a partial
+ * stand-in and worth stating precisely: this leg reads the method out of the
+ * directory, so a v27 entry that *narrowed* the arguments or widened the
+ * response past `SmbStatusResponse` would stop compiling here. The reverse
+ * would not. A widened `info_level` or a narrowed response still compiles, and
+ * the operation would go on advertising the stale union. Add an `Identical<>`
+ * assertion beside the container ones if that matters.
  *
  * They are written out here rather than shared with v26 because that is what
  * this repo's one-client-per-series design is for: the two are the same today
@@ -30680,8 +30868,9 @@ declare class TrueNasApiClientV26 extends TrueNasApiClient<ApiDirectory$1> {
  * the chained stop+start below is the workaround for its absence. Factoring the
  * bodies into a common base would couple two versions that exist in order to
  * evolve apart, and the coupling would have to be undone by whichever release
- * diverges first. The `@/generated` types are the guard against them drifting
- * silently: an entry that changes at v27 stops compiling here.
+ * diverges first. The `@/generated` types are what guard against them drifting
+ * silently — though only as far as the paragraph above says: a directory change
+ * this code cannot absorb stops compiling here, and one it can absorb does not.
  */
 declare class TrueNasApiClientV27 extends TrueNasApiClient<ApiDirectory> {
     /**
@@ -30694,6 +30883,13 @@ declare class TrueNasApiClientV27 extends TrueNasApiClient<ApiDirectory> {
     protected createOperations(): OperationMappings;
 }
 
+/**
+ * What a reachability probe found. Three states rather than two: "we asked and
+ * got silence" and "there was no way to ask" refuse the CORS fallback for
+ * different reasons, and collapsing them into one `false` is the conflation
+ * this whole change exists to undo.
+ */
+type Reachability = 'reachable' | 'silent' | 'cannot-ask';
 /**
  * Discovers available API versions from TrueNAS systems.
  *
@@ -30708,8 +30904,10 @@ declare class TrueNasApiClientV27 extends TrueNasApiClient<ApiDirectory> {
  * service. Because `fetch` resolves (rather than rejects) on non-2xx responses and
  * throws a `TypeError` on network/CORS/unreachable failures, the error contract
  * differs from the original: a network/CORS/unreachable failure surfaces as a
- * {@link VersionDiscoveryNetworkError} — the sentinel the client factory keys on for
- * its CORS fallback (replacing the old `HttpErrorResponse.status === 0` check).
+ * {@link VersionDiscoveryNetworkError} (replacing the old
+ * `HttpErrorResponse.status === 0` check). That error names a symptom with
+ * several causes, so it opens the client factory's disambiguation rather than
+ * deciding it — see {@link VersionDiscovery.probeReachable}.
  */
 declare class VersionDiscovery {
     private readonly logger;
@@ -30717,6 +30915,19 @@ declare class VersionDiscovery {
     private versionCache;
     constructor(logger?: Logger, protocol?: ApplianceProtocol);
     private versionsUrl;
+    /**
+     * Whether the appliance answers at all, asked in a way CORS cannot block.
+     *
+     * A `no-cors` request yields a response the page may not read, but its
+     * *arrival* is the whole answer here: something served it. That separates the
+     * two failures `fetch` reports identically — a box that refused to share its
+     * versions with this origin, and a box that is not there.
+     *
+     * `cannot-ask` where CORS is not enforced: nothing is blocking anything, so a
+     * failed fetch already means unreachable and a probe would only repeat what
+     * discovery just found. It is not a quieter way of saying "no".
+     */
+    probeReachable(hostname: string): Promise<Reachability>;
     /**
      * Discovers the API version for a given hostname.
      *
@@ -30912,4 +31123,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 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, UserRole, type UserRoleName, 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 SmbStatusInfoLevel, type SmbStatusOptions, type SmbStatusRequest, type SmbStatusResponse, type SmbStatusRow, type SupportedApiVersion, TrueNasApiClient, TrueNasApiClientV2510, TrueNasApiClientV26, TrueNasApiClientV27, TrueNasAuthMechanism, type TrueNasDate, UserRole, type UserRoleName, 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 };