@truenas/api-client 6.0.0 → 6.0.1

package/dist/index.d.cts

@@ -13814,6 +13814,94 @@ declare const consoleLogger: Logger;
 /** Logger that discards everything. The default when no logger is provided. */
 declare const noopLogger: Logger;
 
+/**
+ * API error types for versioned TrueNAS API
+ *
+ * Handles both JSON-RPC 2.0 standard errors and TrueNAS custom error formats.
+ */
+/**
+ * JSON-RPC 2.0 standard error format
+ * @see https://www.jsonrpc.org/specification#error_object
+ */
+interface JsonRpcError {
+    /** Error code indicating the error type */
+    code: number;
+    /** Human-readable error message */
+    message: string;
+    /** Optional additional error data */
+    data?: unknown;
+}
+/**
+ * TrueNAS custom error format
+ * Used in some API responses alongside JSON-RPC errors
+ */
+interface TrueNasError {
+    /** Additional error properties */
+    [key: string]: unknown;
+    /** Human-readable error reason (TrueNAS-specific field) */
+    reason: string;
+}
+/**
+ * The TrueNAS payload a versioned-API error carries in its `data`.
+ *
+ * `/api/<version>` answers a failed method call with a JSON-RPC error whose
+ * `data` holds this — `rpc.py`'s `format_truenas_error`. The legacy
+ * `/websocket` endpoint sends these fields at the top level instead, which is
+ * a different handler on a route this client never opens.
+ */
+interface TrueNasErrorData extends TrueNasError {
+    /** The errno middleware raised; `EINVAL` for anything it could not adapt. */
+    error: number;
+    /** `get_errname(errno)`, derived from `error` rather than chosen separately. */
+    errname: string;
+    /** `str(e) or repr(e)` — the repr for an exception that stringifies to nothing. */
+    reason: string;
+    /**
+     * `null` when the appliance has nothing to add.
+     *
+     * `rpc.py`'s generic arm sets `extra = None` for any exception it cannot
+     * adapt — `MatchNotFound` from an empty `get`, for one — and only an adapted
+     * error carries a list. A validation error carries the errors themselves.
+     */
+    extra: unknown[] | null;
+    /** The formatted traceback, or `null`, which is what a client normally sees. */
+    trace: {
+        class: string;
+        formatted: string;
+        repr: string;
+    } | null;
+}
+/**
+ * The error a versioned-API frame carries.
+ *
+ * A JSON-RPC error object throughout: `code` and `message` are always present,
+ * and `data` holds the TrueNAS payload for the codes that have one. The
+ * dataless codes are real — `-32601 "Method does not exist"`,
+ * `-32600 "Invalid request"`, `-32000 "too many concurrent calls"` — so `data`
+ * is optional rather than merely defensive.
+ */
+interface TrueNasErrorFrame extends JsonRpcError {
+    data?: TrueNasErrorData;
+}
+/**
+ * Union type for all possible API error formats
+ */
+type ApiError = JsonRpcError | TrueNasError;
+/**
+ * Extract a human-readable error message from an API error
+ *
+ * Handles multiple error formats:
+ * - JSON-RPC 2.0 with nested TrueNAS data: uses `data.reason` field
+ * - JSON-RPC 2.0 standard: uses `message` field
+ * - TrueNAS custom: uses `reason` field
+ * - Unknown format: returns fallback message
+ *
+ * @param error - The error object from API response
+ * @param fallback - Fallback message if error format is unrecognized
+ * @returns Human-readable error message
+ */
+declare function getApiErrorMessage(error: unknown, fallback?: string): string;
+
 interface TrueNasMessage {
     id?: string;
     /** JSON-RPC 2.0 protocol version, e.g. '2.0' (present on versioned-API messages). */
@@ -13828,12 +13916,18 @@ interface TrueNasMessage {
     collection?: string;
     fields?: unknown;
     subs?: string[];
-    error?: {
-        error: number;
-        errname: string;
-        extra: (string | number)[];
-        reason: string;
-    };
+    /**
+     * The JSON-RPC error object, with the TrueNAS payload under `data`.
+     *
+     * This used to declare `data`'s fields at the top level, which is the shape
+     * the legacy `/websocket` endpoint sends. The versioned endpoint this client
+     * connects to wraps them — `main.py` routes every `/api/{version}` to
+     * `RpcWebSocketHandler`, and `rpc.py`'s `send_error` puts `code` and
+     * `message` outside and the payload in `data`. Nothing here noticed, because
+     * `getApiErrorMessage` reads a `reason` at either depth and answers with the
+     * same string; a consumer branching on `code` or `data.errname` would have.
+     */
+    error?: TrueNasErrorFrame;
 }
 
 declare class TrueNasSocket {
@@ -31594,50 +31688,4 @@ declare enum TrueNasAuthMechanism {
     Token = "TOKEN_PLAIN"
 }
 
-/**
- * API error types for versioned TrueNAS API
- *
- * Handles both JSON-RPC 2.0 standard errors and TrueNAS custom error formats.
- */
-/**
- * JSON-RPC 2.0 standard error format
- * @see https://www.jsonrpc.org/specification#error_object
- */
-interface JsonRpcError {
-    /** Error code indicating the error type */
-    code: number;
-    /** Human-readable error message */
-    message: string;
-    /** Optional additional error data */
-    data?: unknown;
-}
-/**
- * TrueNAS custom error format
- * Used in some API responses alongside JSON-RPC errors
- */
-interface TrueNasError {
-    /** Additional error properties */
-    [key: string]: unknown;
-    /** Human-readable error reason (TrueNAS-specific field) */
-    reason: string;
-}
-/**
- * Union type for all possible API error formats
- */
-type ApiError = JsonRpcError | TrueNasError;
-/**
- * Extract a human-readable error message from an API error
- *
- * Handles multiple error formats:
- * - JSON-RPC 2.0 with nested TrueNAS data: uses `data.reason` field
- * - JSON-RPC 2.0 standard: uses `message` field
- * - TrueNAS custom: uses `reason` field
- * - Unknown format: returns fallback message
- *
- * @param error - The error object from API response
- * @param fallback - Fallback message if error format is unrecognized
- * @returns Human-readable error message
- */
-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 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 };

package/dist/index.d.ts

@@ -13814,6 +13814,94 @@ declare const consoleLogger: Logger;
 /** Logger that discards everything. The default when no logger is provided. */
 declare const noopLogger: Logger;
 
+/**
+ * API error types for versioned TrueNAS API
+ *
+ * Handles both JSON-RPC 2.0 standard errors and TrueNAS custom error formats.
+ */
+/**
+ * JSON-RPC 2.0 standard error format
+ * @see https://www.jsonrpc.org/specification#error_object
+ */
+interface JsonRpcError {
+    /** Error code indicating the error type */
+    code: number;
+    /** Human-readable error message */
+    message: string;
+    /** Optional additional error data */
+    data?: unknown;
+}
+/**
+ * TrueNAS custom error format
+ * Used in some API responses alongside JSON-RPC errors
+ */
+interface TrueNasError {
+    /** Additional error properties */
+    [key: string]: unknown;
+    /** Human-readable error reason (TrueNAS-specific field) */
+    reason: string;
+}
+/**
+ * The TrueNAS payload a versioned-API error carries in its `data`.
+ *
+ * `/api/<version>` answers a failed method call with a JSON-RPC error whose
+ * `data` holds this — `rpc.py`'s `format_truenas_error`. The legacy
+ * `/websocket` endpoint sends these fields at the top level instead, which is
+ * a different handler on a route this client never opens.
+ */
+interface TrueNasErrorData extends TrueNasError {
+    /** The errno middleware raised; `EINVAL` for anything it could not adapt. */
+    error: number;
+    /** `get_errname(errno)`, derived from `error` rather than chosen separately. */
+    errname: string;
+    /** `str(e) or repr(e)` — the repr for an exception that stringifies to nothing. */
+    reason: string;
+    /**
+     * `null` when the appliance has nothing to add.
+     *
+     * `rpc.py`'s generic arm sets `extra = None` for any exception it cannot
+     * adapt — `MatchNotFound` from an empty `get`, for one — and only an adapted
+     * error carries a list. A validation error carries the errors themselves.
+     */
+    extra: unknown[] | null;
+    /** The formatted traceback, or `null`, which is what a client normally sees. */
+    trace: {
+        class: string;
+        formatted: string;
+        repr: string;
+    } | null;
+}
+/**
+ * The error a versioned-API frame carries.
+ *
+ * A JSON-RPC error object throughout: `code` and `message` are always present,
+ * and `data` holds the TrueNAS payload for the codes that have one. The
+ * dataless codes are real — `-32601 "Method does not exist"`,
+ * `-32600 "Invalid request"`, `-32000 "too many concurrent calls"` — so `data`
+ * is optional rather than merely defensive.
+ */
+interface TrueNasErrorFrame extends JsonRpcError {
+    data?: TrueNasErrorData;
+}
+/**
+ * Union type for all possible API error formats
+ */
+type ApiError = JsonRpcError | TrueNasError;
+/**
+ * Extract a human-readable error message from an API error
+ *
+ * Handles multiple error formats:
+ * - JSON-RPC 2.0 with nested TrueNAS data: uses `data.reason` field
+ * - JSON-RPC 2.0 standard: uses `message` field
+ * - TrueNAS custom: uses `reason` field
+ * - Unknown format: returns fallback message
+ *
+ * @param error - The error object from API response
+ * @param fallback - Fallback message if error format is unrecognized
+ * @returns Human-readable error message
+ */
+declare function getApiErrorMessage(error: unknown, fallback?: string): string;
+
 interface TrueNasMessage {
     id?: string;
     /** JSON-RPC 2.0 protocol version, e.g. '2.0' (present on versioned-API messages). */
@@ -13828,12 +13916,18 @@ interface TrueNasMessage {
     collection?: string;
     fields?: unknown;
     subs?: string[];
-    error?: {
-        error: number;
-        errname: string;
-        extra: (string | number)[];
-        reason: string;
-    };
+    /**
+     * The JSON-RPC error object, with the TrueNAS payload under `data`.
+     *
+     * This used to declare `data`'s fields at the top level, which is the shape
+     * the legacy `/websocket` endpoint sends. The versioned endpoint this client
+     * connects to wraps them — `main.py` routes every `/api/{version}` to
+     * `RpcWebSocketHandler`, and `rpc.py`'s `send_error` puts `code` and
+     * `message` outside and the payload in `data`. Nothing here noticed, because
+     * `getApiErrorMessage` reads a `reason` at either depth and answers with the
+     * same string; a consumer branching on `code` or `data.errname` would have.
+     */
+    error?: TrueNasErrorFrame;
 }
 
 declare class TrueNasSocket {
@@ -31594,50 +31688,4 @@ declare enum TrueNasAuthMechanism {
     Token = "TOKEN_PLAIN"
 }
 
-/**
- * API error types for versioned TrueNAS API
- *
- * Handles both JSON-RPC 2.0 standard errors and TrueNAS custom error formats.
- */
-/**
- * JSON-RPC 2.0 standard error format
- * @see https://www.jsonrpc.org/specification#error_object
- */
-interface JsonRpcError {
-    /** Error code indicating the error type */
-    code: number;
-    /** Human-readable error message */
-    message: string;
-    /** Optional additional error data */
-    data?: unknown;
-}
-/**
- * TrueNAS custom error format
- * Used in some API responses alongside JSON-RPC errors
- */
-interface TrueNasError {
-    /** Additional error properties */
-    [key: string]: unknown;
-    /** Human-readable error reason (TrueNAS-specific field) */
-    reason: string;
-}
-/**
- * Union type for all possible API error formats
- */
-type ApiError = JsonRpcError | TrueNasError;
-/**
- * Extract a human-readable error message from an API error
- *
- * Handles multiple error formats:
- * - JSON-RPC 2.0 with nested TrueNAS data: uses `data.reason` field
- * - JSON-RPC 2.0 standard: uses `message` field
- * - TrueNAS custom: uses `reason` field
- * - Unknown format: returns fallback message
- *
- * @param error - The error object from API response
- * @param fallback - Fallback message if error format is unrecognized
- * @returns Human-readable error message
- */
-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 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 };