@truenas/api-client 8.0.0 → 9.0.1

package/README.md

@@ -17,7 +17,7 @@ const users = await firstValueFrom(
   for every supported release. A misspelled method, a missing parameter or a
   filter on a field that doesn't exist fails the build, not the user.
 - **Version-aware.** The client asks the appliance which API it speaks and
-  builds the matching implementation. API versions v25.10.0 through v27.0.0
+  builds the matching implementation. API versions v25.10.0 through v28.0.0
   are supported side by side.
 - **One call across releases.** `client.ops` keeps working when middleware
   renames or reshapes an endpoint between versions.
@@ -89,7 +89,9 @@ client.api.call('alert.dismiss', ['uuid-1']);   // params checked against the me
 client.api.call('nope.nope');                   // ✗ compile error
 ```
 
-A failed call errors with middleware's own message.
+A failed call errors with a `TrueNasApiError`. Its `message` is middleware's own
+reason, and the rest of the error is there too: `errname` (such as `EINVAL`),
+and `data.extra`, where a validation error names the fields it rejected.
 
 ## Queries
 
@@ -116,7 +118,9 @@ client.api.job('pool.dataset.export_key', ['tank/encrypted']).subscribe(job => {
 ```
 
 The stream emits each state and completes when the job finishes. A failed job
-completes too, with `state` and `error` set.
+completes too, with `state` and `error` set. A job method refused before it
+starts a job, such as for a validation error, errors with a `TrueNasApiError`
+instead, because there is no job to report.
 
 ## Events
 
@@ -129,7 +133,20 @@ client.api.events('app.query').subscribe(change => {
 
 Changes are typed per collection and discriminated on `msg`. One server
 subscription is shared by every subscriber and re-registered after each
-reconnect.
+reconnect. When the last subscriber leaves, it is released with
+`core.unsubscribe`.
+
+Event sources take their arguments after the name, typed from the method's
+`subscriptionParams`:
+
+```typescript
+client.api.events('filesystem.file_tail_follow', { path: '/var/log/messages' })
+  .subscribe(line => append(line.fields.data));
+```
+
+A source with different arguments is a separate subscription. If middleware
+ends a source, the stream completes. If it rejects the arguments, the stream
+errors with a `TrueNasApiError`.
 
 ## Working across versions
 
@@ -137,12 +154,12 @@ Without a hint, the client is typed as the oldest supported version, since that
 is a safe floor against any appliance. Reach newer methods one of two ways:
 
 ```typescript
-// Discover the version, and write against v26:
-const client = await createTrueNasClient<ApiDirectoryV26_0_0>(options);
+// Discover the version, and write against v27:
+const client = await createTrueNasClient<ApiDirectoryV27_0_0>(options);
 client.api.query('container.query');
 
 // Or skip discovery, and let the types follow the version:
-const pinned = await createTrueNasClient({ ...options, version: 'v27.0.0' });
+const pinned = await createTrueNasClient({ ...options, version: 'v28.0.0' });
 pinned.api.query('container.query');
 ```
 
@@ -164,6 +181,17 @@ client.ops.smbStatus({ infoLevel: 'SESSIONS' });
 Per-version details, such as permissions that differ between releases, are in
 the `OperationMappings` reference.
 
+Some behaviour differs between versions in ways no type can express, because a
+default is not part of a TypeScript signature. One worth knowing: at v28.0.0,
+`config.save()` with no arguments includes the secret seed in the backup, where
+at v25.10 and v27.0 the same call left it out. That seed decrypts every
+password, private key and API key the backup contains, so treat such a backup
+as a secret; pass `{ secretseed: false }` for the old behaviour, bearing in mind
+a backup saved without it cannot be uploaded. These are recorded as they are
+found in
+[`src/generated/MANIFEST.md`](https://github.com/truenas/api-client-ts/blob/main/src/generated/MANIFEST.md),
+which is in the repository rather than the published package.
+
 ## Connection
 
 ```typescript
@@ -212,7 +240,8 @@ the client is doing.
 
 ## Errors
 
-- **Calls** error with middleware's message.
+- **Calls, queries and job starts** error with `TrueNasApiError`. Its `message`
+  is middleware's reason, and `errname`, `code` and `data` carry the rest.
 - **Logins** error with `AuthError`. Check `code` against `AuthErrorCode`.
 - **`createTrueNasClient`** rejects with a `VersionDiscoveryError` subclass, such
   as `VersionTooOldError`, `VersionTooNewError` or