@truenas/api-client 1.0.13 → 2.0.1

package/README.md

@@ -11,6 +11,93 @@ Framework-agnostic TypeScript client for the TrueNAS JSON-RPC 2.0 WebSocket API.
   implementation (e.g. the [`ws`](https://www.npmjs.com/package/ws) package) via the socket config.
 - **`rxjs` ^7.8** is a peer dependency — the consuming project provides it.
 
+## Usage
+
+```typescript
+import { createTrueNasClient } from '@truenas/api-client';
+
+const client = await createTrueNasClient({
+  uuid: 'system-uuid',
+  hostnames: ['truenas.local'],
+  enabled: true,
+});
+```
+
+`createTrueNasClient` does not take credentials, so log in before calling
+anything — middleware refuses an unauthenticated call, and `authenticated$`
+only turns true once one of these resolves:
+
+```typescript
+await firstValueFrom(
+  client.authenticator.loginWithApiKey({ username, key })
+);
+// or client.authenticator.loginWithUserPass(username, password)
+```
+
+Everything below hangs off `client.api`, and every method name it accepts comes
+from types generated from `middlewared --dump-api`. A name the declared version
+does not have is a compile error, and params and responses come from the same
+source — there is no list of endpoint constants to import.
+
+```typescript
+client.api.call('system.info');                        // SystemInfoResult
+client.api.call('alert.dismiss', ['uuid-1']);          // params required
+client.api.call('nope.nope');                          // ✗ compile error
+```
+
+**Queries.** Middleware's `.query` methods are polymorphic in their options —
+the same endpoint returns a list, one entry, or a count. Which you get is
+chosen by the verb, so there is nothing to narrow:
+
+```typescript
+client.api.query('user.query', [['uid', '>', 1000]]);  // UserEntry[]
+client.api.queryOne('user.query', [['id', '=', 1]]);   // UserEntry
+client.api.queryCount('user.query');                   // number
+
+client.api.query('user.query', [], { select: ['id', 'username'] });
+                                     // Pick<UserEntry, 'id' | 'username'>[]
+```
+
+Use `satisfies` rather than an annotation when building options into a
+variable — an annotated `QueryListOptions<E>` widens `select`, and the result
+degrades to `Partial<E>[]`.
+
+**Jobs.** A separate key space from `call`: `app.start` runs as a job and does
+not appear in the call directory. `job` starts one and follows it to
+completion, typing the result from the job directory:
+
+```typescript
+client.api.job('pool.dataset.export_key', ['tank/enc'])
+  .subscribe(job => report(job.progress.percent));     // Job<string | null>
+```
+
+**Events.** Emits the change as a union discriminated on `msg`. Narrowing is
+load-bearing: a removal carries an `id` and no `fields` in almost every
+collection.
+
+```typescript
+client.api.events('app.query').subscribe(event => {
+  if (event.msg === 'removed') return drop(event.id);
+  render(event.fields);
+});
+```
+
+### Naming a version
+
+The version is discovered at runtime; the types are fixed at compile time.
+`createTrueNasClient` defaults to the oldest supported version, which
+understates a newer server rather than promising methods it lacks. Name a
+version to reach the rest:
+
+```typescript
+const client = await createTrueNasClient<ApiDirectoryV26_0_0>(opts);
+client.api.query('container.query');                   // v26-only, reachable
+```
+
+That is a claim about the server, not a guarantee — the client you get is
+whichever version discovery found. Operations that must work across versions
+belong on `client.ops`, which resolves them at runtime.
+
 ## Documentation
 
 The API reference is generated from the TSDoc comments in the source with