@truenas/api-client 9.0.0 → 9.0.1

package/dist/{truenas-auth-mechanism.enum-CW5Wwz1s.d.ts → truenas-auth-mechanism.enum-Bp2XMMwK.d.ts}

@@ -13543,17 +13543,35 @@ type JobResult<D extends ApiDirectoryShape, M extends JobMethod<D>> = D['job'][M
     response: infer R;
 } ? R : never;
 /**
- * The events a surface can be subscribed to by name alone.
- *
- * Excludes *event sources* (entries with a `subscriptionParams` model, e.g.
- * `app.stats`, `reporting.realtime`). They take subscribe-time arguments whose
- * encoding the dump does not record (`core.subscribe` takes one string), so
- * subscribing by name alone would give a silent stream. Widen this once the
- * encoding is confirmed against a live appliance (`yarn live-check`).
+ * The collections a surface can be subscribed to: by name alone, with no
+ * arguments. Event sources are {@link EventSourceName}.
  */
 type EventName<D extends ApiDirectoryShape> = {
     [E in keyof D['event']]: 'subscriptionParams' extends keyof D['event'][E] ? never : E;
 }[keyof D['event']] & string;
+/**
+ * The *event sources* of a surface: entries with a `subscriptionParams` model,
+ * such as `filesystem.file_tail_follow` or `reporting.realtime`, which take
+ * arguments when subscribed to. See {@link SubscriptionParams}.
+ */
+type EventSourceName<D extends ApiDirectoryShape> = {
+    [E in keyof D['event']]: 'subscriptionParams' extends keyof D['event'][E] ? E : never;
+}[keyof D['event']] & string;
+/** Everything a surface can be subscribed to: collections and event sources. */
+type SubscribableEvent<D extends ApiDirectoryShape> = EventName<D> | EventSourceName<D>;
+/** The arguments an event source takes, e.g. `{ path, tail_lines? }`. */
+type SubscriptionParams<D extends ApiDirectoryShape, E extends EventSourceName<D>> = D['event'][E] extends {
+    subscriptionParams: infer P;
+} ? P : never;
+/**
+ * What `events()` takes after an event source's name: its arguments, which may
+ * be left out when none of them is required.
+ *
+ * Not {@link ArgsOf}: that asks whether an empty *tuple* fits, and the
+ * arguments here are an object. `Record<string, never>` — a source taking no
+ * arguments, such as `zfs.tier.rewrite_job_query` — would then be required.
+ */
+type SubscriptionArgs<D extends ApiDirectoryShape, E extends EventSourceName<D>> = Record<never, never> extends SubscriptionParams<D, E> ? [params?: SubscriptionParams<D, E>] : [params: SubscriptionParams<D, E>];
 /** The kinds of change a collection event reports. */
 type EventKind = 'added' | 'changed' | 'removed';
 /**
@@ -13564,11 +13582,11 @@ type EventKind = 'added' | 'changed' | 'removed';
  * plenty of collections declare only `added`, and an arm for a kind that never
  * arrives would invite callers to handle it.
  */
-type EventArm<D extends ApiDirectoryShape, E extends EventName<D>, K extends EventKind> = K extends keyof D['event'][E] ? {
+type EventArm<D extends ApiDirectoryShape, E extends SubscribableEvent<D>, K extends EventKind> = K extends keyof D['event'][E] ? {
     msg: K;
 } & D['event'][E][K] : never;
 /** The kinds the directory says this event reports. */
-type DeclaredKinds<D extends ApiDirectoryShape, E extends EventName<D>> = Extract<keyof D['event'][E], EventKind>;
+type DeclaredKinds<D extends ApiDirectoryShape, E extends SubscribableEvent<D>> = Extract<keyof D['event'][E], EventKind>;
 /**
  * An arm for the kinds the directory does NOT declare, carrying no payload.
  *
@@ -13580,7 +13598,7 @@ type DeclaredKinds<D extends ApiDirectoryShape, E extends EventName<D>> = Extrac
  * this arm a `removed` frame on a collection that lists only `added` and
  * `changed` would reach the caller typed as carrying `fields`.
  */
-type UndeclaredArm<D extends ApiDirectoryShape, E extends EventName<D>> = [Exclude<EventKind, DeclaredKinds<D, E>>] extends [never] ? never : {
+type UndeclaredArm<D extends ApiDirectoryShape, E extends SubscribableEvent<D>> = [Exclude<EventKind, DeclaredKinds<D, E>>] extends [never] ? never : {
     msg: Exclude<EventKind, DeclaredKinds<D, E>>;
     id?: unknown;
 };
@@ -13591,7 +13609,7 @@ type UndeclaredArm<D extends ApiDirectoryShape, E extends EventName<D>> = [Exclu
  * no `fields` in 55 of the 56 collections that declare one — so narrowing on
  * `msg` is what makes the payload safe to reach.
  */
-type EventUnion<D extends ApiDirectoryShape, E extends EventName<D>> = EventArm<D, E, 'added'> | EventArm<D, E, 'changed'> | EventArm<D, E, 'removed'> | UndeclaredArm<D, E>;
+type EventUnion<D extends ApiDirectoryShape, E extends SubscribableEvent<D>> = EventArm<D, E, 'added'> | EventArm<D, E, 'changed'> | EventArm<D, E, 'removed'> | UndeclaredArm<D, E>;
 
 /**
  * Types for the query verbs — `api.query` / `queryOne` / `queryCount`.
@@ -30802,14 +30820,29 @@ declare class TrueNasApi<D extends ApiDirectoryShape = BaseApiDirectory> {
     /**
      * Stream of job events from websocket.
      * JSON-RPC 2.0 events have structure: { method: 'collection_update', params: { collection, fields, ... } }
+     *
+     * Reads `messages()` when first subscribed, not when this is built, as every
+     * other verb does. A consumer that wraps the connection's `messages()` after
+     * the client is created — a debug panel mixing in mocked answers — is
+     * otherwise heard by `call` and `events` but not by job tracking.
      */
     private jobEvents;
     /**
-     * One shared stream per subscribed event name — see {@link events}.
-     * Keyed by name rather than by caller, because the subscription it stands
-     * for lives on the server and is per socket, not per caller.
+     * One shared stream per subscription — see {@link events}. Keyed by the
+     * name *with* its arguments: a tail of one file is not a tail of another.
      */
     private readonly eventStreams;
+    /**
+     * Releases awaiting their `core.unsubscribe` reply, per name. Middleware
+     * sends a source's release notice (`terminate`) before that reply, and a
+     * notice names only the collection; so an error-free one arriving inside
+     * that window belongs to the release, not to a later subscription. One per
+     * window, which closes on the reply whether or not a notice came.
+     */
+    private readonly releasing;
+    /** The live subscription per name, told when the server ends it. */
+    private readonly serverEnds;
+    private endNotices?;
     constructor(authenticated: BehaviorSubject<boolean>, connection: TrueNasConnection);
     /**
      * Call a method of the typed surface and emit its result.
@@ -30877,7 +30910,7 @@ declare class TrueNasApi<D extends ApiDirectoryShape = BaseApiDirectory> {
      * differs by version (v25.10 answers with the id, v27 with `null`), while
      * the event correlation holds for both.
      *
-     * @returns Observable that emits the job ID when received from websocket events
+     * @returns the job's id; errors with a {@link TrueNasApiError} if the method is refused before a job starts
      */
     callAndGetJobId<M extends JobMethod<D>>(method: M, ...params: ArgsOf<JobParams<D, M>>): Observable<number>;
     /**
@@ -30893,19 +30926,33 @@ declare class TrueNasApi<D extends ApiDirectoryShape = BaseApiDirectory> {
      */
     job<M extends JobMethod<D>>(method: M, ...params: ArgsOf<JobParams<D, M>>): Observable<Job<JobResult<D, M>>>;
     /**
-     * Subscribe to a collection and emit its changes, discriminated on `msg`.
+     * Subscribe to a collection or an event source and emit its changes,
+     * discriminated on `msg`.
      *
      * ```typescript
      * api.events('app.query').subscribe(event => {
      *   if (event.msg === 'removed') return drop(event.id);
      *   render(event.fields);          // only reachable once narrowed
      * });
+     * api.events('filesystem.file_tail_follow', { path: '/var/log/messages' });
      * ```
      *
      * Narrow before reading `fields`: `removed` events almost never carry it.
-     * Sources taking subscribe-time arguments are excluded; see {@link EventName}.
      */
     events<E extends EventName<D>>(event: E): Observable<EventUnion<D, E>>;
+    events<E extends EventSourceName<D>>(event: E, ...params: SubscriptionArgs<D, E>): Observable<EventUnion<D, E>>;
+    /**
+     * Release a subscription by the id `core.subscribe` answered with, holding
+     * its notice window (see {@link releasing}) open until the reply.
+     */
+    private unsubscribe;
+    /**
+     * Route each `notify_unsubscribed` once: an error-free one inside an open
+     * release window is that release's, anything else ends the name's live
+     * subscription. Installed on the first `events()` call, before any stream
+     * listens.
+     */
+    private listenForEndNotices;
     /**
      * Convenience wrapper for auth.generate_token API call.
      *
@@ -31625,4 +31672,4 @@ declare enum TrueNasAuthMechanism {
     Token = "TOKEN_PLAIN"
 }
 
-export { type CreateClientOptions as $, type ApiDirectory$7 as A, type ApiEventDirectory$1 as B, type ApiEventDirectory as C, type ApiJobDirectory$7 as D, type ApiJobDirectory$6 as E, type ApiJobDirectory$5 as F, type ApiJobDirectory$4 as G, type ApiJobDirectory$3 as H, type ApiJobDirectory$2 as I, type ApiJobDirectory$1 as J, type ApiJobDirectory as K, type Logger as L, type ApiKeyCreate as M, type ApiVersionResponse as N, type OperationMappings as O, AppState as P, type ArgsOf as Q, type AuthResponse as R, AuthResponseType as S, TrueNasApiClient as T, type BaseApiDirectory as U, type CallMethod as V, type CallParams as W, type CallResponse as X, type ConnectionClose as Y, type ConnectionEndpoint as Z, type Container as _, type ApiDirectory$1 as a, type DefaultApiDirectory as a0, type EventKind as a1, type EventName as a2, type EventUnion as a3, type Job as a4, type JobMethod as a5, type JobParams as a6, type JobProgress as a7, type JobResult as a8, JobState as a9, index$6 as aA, index$5 as aB, index$4 as aC, index$3 as aD, index$2 as aE, index$1 as aF, index as aG, TrueNasConnection as aH, type TrueNasMessage as aI, TrueNasAuthenticator as aJ, type DerivedDirectory as aK, type QueryDirectory as aa, type QueryEntity as ab, type QueryListOptions as ac, type QueryMethod as ad, type QuerySingleOptions as ae, type ReconnectOptions as af, SUPPORTED_API_VERSIONS as ag, type SmbStatusInfoLevel as ah, type SmbStatusOptions as ai, type SmbStatusRequest as aj, type SmbStatusResponse as ak, type SmbStatusRow as al, type SupportedApiVersion as am, TrueNasAuthMechanism as an, type TrueNasDate as ao, type TrueNasErrorData as ap, type TrueNasErrorFrame as aq, UserRole as ar, type UserRoleName as as, VersionCompatibility as at, consoleLogger as au, createTrueNasClient as av, getApiErrorMessage as aw, isJobFinished as ax, noopLogger as ay, index$7 as az, type ApiDirectory as b, type ApplianceProtocol as c, type ApiVersion as d, type ApiCallDirectory$7 as e, type ApiCallDirectory$6 as f, type ApiCallDirectory$5 as g, type ApiCallDirectory$4 as h, type ApiCallDirectory$3 as i, type ApiCallDirectory$2 as j, type ApiCallDirectory$1 as k, type ApiCallDirectory as l, type ApiDirectoryByVersion as m, type ApiDirectoryShape as n, type ApiDirectory$6 as o, type ApiDirectory$5 as p, type ApiDirectory$4 as q, type ApiDirectory$3 as r, type ApiDirectory$2 as s, type ApiError as t, type ApiEventDirectory$7 as u, type ApiEventDirectory$6 as v, type ApiEventDirectory$5 as w, type ApiEventDirectory$4 as x, type ApiEventDirectory$3 as y, type ApiEventDirectory$2 as z };
+export { type ConnectionEndpoint as $, type ApiDirectory$7 as A, type ApiEventDirectory$3 as B, type ApiEventDirectory$2 as C, type ApiEventDirectory$1 as D, type ApiEventDirectory as E, type ApiJobDirectory$7 as F, type ApiJobDirectory$6 as G, type ApiJobDirectory$5 as H, type ApiJobDirectory$4 as I, type ApiJobDirectory$3 as J, type ApiJobDirectory$2 as K, type Logger as L, type ApiJobDirectory$1 as M, type ApiJobDirectory as N, type OperationMappings as O, type ApiKeyCreate as P, type ApiVersionResponse as Q, AppState as R, type ArgsOf as S, TrueNasApiClient as T, type AuthResponse as U, AuthResponseType as V, type BaseApiDirectory as W, type CallMethod as X, type CallParams as Y, type CallResponse as Z, type ConnectionClose as _, type ApiDirectory$1 as a, type Container as a0, type CreateClientOptions as a1, type DefaultApiDirectory as a2, type EventKind as a3, type EventName as a4, type EventSourceName as a5, type EventUnion as a6, type Job as a7, type JobMethod as a8, type JobParams as a9, getApiErrorMessage as aA, isJobFinished as aB, noopLogger as aC, index$7 as aD, index$6 as aE, index$5 as aF, index$4 as aG, index$3 as aH, index$2 as aI, index$1 as aJ, index as aK, TrueNasConnection as aL, type TrueNasMessage as aM, TrueNasAuthenticator as aN, type DerivedDirectory as aO, type JobProgress as aa, type JobResult as ab, JobState as ac, type QueryDirectory as ad, type QueryEntity as ae, type QueryListOptions as af, type QueryMethod as ag, type QuerySingleOptions as ah, type ReconnectOptions as ai, SUPPORTED_API_VERSIONS as aj, type SmbStatusInfoLevel as ak, type SmbStatusOptions as al, type SmbStatusRequest as am, type SmbStatusResponse as an, type SmbStatusRow as ao, type SubscribableEvent as ap, type SubscriptionArgs as aq, type SubscriptionParams as ar, type SupportedApiVersion as as, TrueNasAuthMechanism as at, type TrueNasDate as au, UserRole as av, type UserRoleName as aw, VersionCompatibility as ax, consoleLogger as ay, createTrueNasClient as az, type ApiDirectory as b, type ApplianceProtocol as c, type ApiVersion as d, type TrueNasErrorFrame as e, type TrueNasErrorData as f, type ApiCallDirectory$7 as g, type ApiCallDirectory$6 as h, type ApiCallDirectory$5 as i, type ApiCallDirectory$4 as j, type ApiCallDirectory$3 as k, type ApiCallDirectory$2 as l, type ApiCallDirectory$1 as m, type ApiCallDirectory as n, type ApiDirectoryByVersion as o, type ApiDirectoryShape as p, type ApiDirectory$6 as q, type ApiDirectory$5 as r, type ApiDirectory$4 as s, type ApiDirectory$3 as t, type ApiDirectory$2 as u, type ApiError as v, type ApiEventDirectory$7 as w, type ApiEventDirectory$6 as x, type ApiEventDirectory$5 as y, type ApiEventDirectory$4 as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@truenas/api-client",
-  "version": "9.0.0",
+  "version": "9.0.1",
   "description": "Framework-agnostic TypeScript client for the TrueNAS JSON-RPC 2.0 WebSocket API",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -51,7 +51,7 @@
     "lint": "eslint .",
     "check:dist": "node scripts/check-dist.mjs",
     "docs": "typedoc",
-    "docs:check": "typedoc --emit none",
+    "docs:check": "typedoc --out .typedoc-validate",
     "check:package": "publint && yarn pack -o package.tgz && attw package.tgz && rm -f package.tgz",
     "clean": "rm -rf dist"
   },