@smarthome.exchange/api 0.1.0 → 1.0.0

package/ts/classes.smarthomeexchangeapiclient.ts

@@ -2,9 +2,63 @@ import * as plugins from './plugins.js';
 
 export interface IShxApiClientOptions {
   hubUrl?: string;
+  homeId: string;
+  authorizationHeaderProvider: TShxAuthorizationHeaderProvider;
+  socketConnectionPreparationTimeoutMs?: number;
 }
 
+export interface IShxAuthorizationContext {
+  readonly homeId: string;
+  readonly endpoint: string;
+  readonly transport: 'http';
+  readonly method: plugins.shxInterfaces.request.IReq_ListDevices['method']
+    | plugins.shxInterfaces.request.IReq_ListAgents['method']
+    | plugins.shxInterfaces.request.IReq_ListTools['method']
+    | plugins.shxInterfaces.request.IReq_GetHomeSnapshot['method']
+    | plugins.shxInterfaces.request.IReq_ExecuteToolPlan['method']
+    | plugins.shxInterfaces.request.IReq_ListApprovals['method']
+    | plugins.shxInterfaces.request.IReq_SubmitApproval['method'];
+  readonly abortSignal?: AbortSignal;
+}
+
+export interface IShxSocketAuthorizationContext extends Omit<
+  IShxAuthorizationContext, 'method' | 'transport' | 'abortSignal'
+> {
+  readonly method: 'connect';
+  readonly transport: 'websocket';
+  readonly abortSignal: AbortSignal;
+  readonly attempt: number;
+  readonly deadline: number;
+}
+
+export type TShxAuthorizationContext = IShxAuthorizationContext | IShxSocketAuthorizationContext;
+
+export type TShxAuthorizationHeaderProvider = (
+  contextArg: TShxAuthorizationContext
+) => Promise<string>;
+
+export interface IShxApiRequestOptions {
+  abortSignal?: AbortSignal;
+  timeoutMs?: number;
+  useCache?: boolean;
+}
+
+export type TListDevicesRequest = Omit<
+  plugins.shxInterfaces.request.IReq_ListDevices['request'], 'context'
+>;
+export type TListToolsRequest = Omit<
+  plugins.shxInterfaces.request.IReq_ListTools['request'], 'context'
+>;
+export type TListApprovalsRequest = Omit<
+  plugins.shxInterfaces.request.IReq_ListApprovals['request'], 'context'
+>;
+export type TSubmitApprovalRequest = Omit<
+  plugins.shxInterfaces.request.IReq_SubmitApproval['request'], 'context'
+>;
+
 export interface IHomeSnapshotWatchOptions {
+  abortSignal?: AbortSignal;
+  timeoutMs?: number;
   intervalMs?: number;
   immediate?: boolean;
   onError?: (errorArg: unknown) => void | Promise<void>;
@@ -16,75 +70,377 @@ export type THomeSnapshotWatchCallback = (
 
 export type THomeSnapshotWatchStop = () => Promise<void>;
 
+const maxLifecycleOperationCount = 64;
+
 export class SmarthomeExchangeApiClient {
-  private hubUrl: string;
-  public typedrouter = new plugins.typedrequest.TypedRouter();
-  public typedsocketClient?: plugins.typedsocket.TypedSocket;
+  readonly #homeId: string;
+  readonly #httpEndpoint: string;
+  readonly #hubUrl: string;
+  readonly #socketConnectionPreparationTimeoutMs?: number;
+  readonly #authorizationHeaderProvider: TShxAuthorizationHeaderProvider;
+  private lifecycleTail = Promise.resolve();
+  private lifecycleOperationCount = 0;
+  private queuedLifecycleOperation?: {
+    target: 'started' | 'stopped';
+    promise: Promise<void>;
+  };
+  private stopIntentGeneration = 0;
+  private pendingStartAbortController?: AbortController;
+  private socketPendingStop?: plugins.typedsocket.TypedSocket;
+  private socketNeedsCleanup = false;
+  #typedsocketClient?: plugins.typedsocket.TypedSocket;
+  public readonly typedrouter = new plugins.typedrequest.TypedRouter();
 
-  constructor(optionsArg: IShxApiClientOptions = {}) {
-    this.hubUrl = (optionsArg.hubUrl || 'http://localhost:8080').replace(/\/$/, '');
+  constructor(optionsArg: IShxApiClientOptions) {
+    this.assertKnownProperties(
+      optionsArg, ['hubUrl', 'homeId', 'authorizationHeaderProvider', 'socketConnectionPreparationTimeoutMs'], 'Client options'
+    );
+    if (!optionsArg || typeof optionsArg.homeId !== 'string'
+      || optionsArg.homeId.length < 1 || optionsArg.homeId.length > 200
+      || optionsArg.homeId.trim() !== optionsArg.homeId
+      || typeof optionsArg.authorizationHeaderProvider !== 'function'
+      || (optionsArg.hubUrl !== undefined && typeof optionsArg.hubUrl !== 'string')) {
+      throw new TypeError('The API client requires a homeId and authorizationHeaderProvider.');
+    }
+    let hubUrl: URL;
+    try {
+      hubUrl = new URL(optionsArg.hubUrl ?? 'http://localhost:8080');
+    } catch {
+      throw new TypeError('hubUrl must be an absolute HTTP or HTTPS URL.');
+    }
+    if (!['http:', 'https:'].includes(hubUrl.protocol)
+      || hubUrl.username || hubUrl.password || hubUrl.search || hubUrl.hash) {
+      throw new TypeError('hubUrl must be an HTTP or HTTPS URL without credentials, query, or fragment.');
+    }
+    const preparationTimeoutMs = optionsArg.socketConnectionPreparationTimeoutMs;
+    if (preparationTimeoutMs !== undefined && (!Number.isInteger(preparationTimeoutMs)
+      || preparationTimeoutMs < 1
+      || preparationTimeoutMs > plugins.typedsocket.TYPEDSOCKET_MAX_CONNECTION_PREPARATION_TIMEOUT_MS)) {
+      throw new TypeError('Socket credential preparation requires a positive deadline no greater than 10000ms.');
+    }
+    this.#socketConnectionPreparationTimeoutMs = preparationTimeoutMs;
+    this.#hubUrl = hubUrl.href.replace(/\/$/, '');
+    hubUrl.pathname = `${hubUrl.pathname.replace(/\/+$/, '')}/typedrequest`;
+    this.#httpEndpoint = hubUrl.href;
+    this.#homeId = optionsArg.homeId;
+    this.#authorizationHeaderProvider = optionsArg.authorizationHeaderProvider;
   }
 
-  private get httpEndpoint() {
-    return `${this.hubUrl}/typedrequest`;
+  public get homeId(): string {
+    return this.#homeId;
   }
 
-  private createWsRequest<T extends plugins.typedRequestInterfaces.ITypedRequest>(
-    operationArg: T['method']
-  ) {
-    return this.typedsocketClient?.createTypedRequest<T>(operationArg);
+  public get typedsocketClient(): plugins.typedsocket.TypedSocket | undefined {
+    return this.#typedsocketClient;
   }
 
   private createHttpRequest<T extends plugins.typedRequestInterfaces.ITypedRequest>(
     operationArg: T['method']
   ) {
-    return new plugins.typedrequest.TypedRequest<T>(this.httpEndpoint, operationArg);
+    return new plugins.typedrequest.TypedRequest<T>(this.#httpEndpoint, operationArg);
+  }
+
+  private captureRequestOptions(optionsArg: IShxApiRequestOptions): IShxApiRequestOptions {
+    this.assertKnownProperties(optionsArg, ['abortSignal', 'timeoutMs', 'useCache'], 'Request options');
+    const options = { ...optionsArg };
+    if ((options.abortSignal !== undefined && !(options.abortSignal instanceof AbortSignal))
+      || (options.useCache !== undefined && typeof options.useCache !== 'boolean')
+      || (options.timeoutMs !== undefined && (!Number.isInteger(options.timeoutMs)
+        || options.timeoutMs < 1 || options.timeoutMs > 2_147_483_647))) {
+      throw new TypeError('Request options require an AbortSignal, boolean cache option, and positive timer-safe deadline.');
+    }
+    return options;
   }
 
   private async fire<T extends plugins.typedRequestInterfaces.ITypedRequest>(
-    operationArg: T['method'],
-    payloadArg: T['request']
+    operationArg: IShxAuthorizationContext['method'] & T['method'],
+    requestPayloadArg: T['request'],
+    optionsArg: IShxApiRequestOptions = {}
   ): Promise<T['response']> {
-    const wsRequest = this.createWsRequest<T>(operationArg);
-    if (wsRequest) {
-      return wsRequest.fire(payloadArg);
+    const requestOptions = this.captureRequestOptions(optionsArg);
+    requestOptions.abortSignal?.throwIfAborted();
+    if (this.#typedsocketClient) {
+      return this.#typedsocketClient.createTypedRequest<T>(operationArg, undefined, {
+        timeoutMs: requestOptions.timeoutMs,
+      }).fire(requestPayloadArg, {
+        ...requestOptions,
+        maxRetries: 0,
+      });
     }
-    return this.createHttpRequest<T>(operationArg).fire(payloadArg);
+    const authorization = await this.getAuthorization(Object.freeze({
+      homeId: this.#homeId,
+      endpoint: this.#httpEndpoint,
+      method: operationArg,
+      transport: 'http',
+      abortSignal: requestOptions.abortSignal,
+    }));
+    requestOptions.abortSignal?.throwIfAborted();
+    return this.createHttpRequest<T>(operationArg).fire(requestPayloadArg, {
+      ...requestOptions,
+      maxRetries: 0,
+      headers: { authorization },
+    });
   }
 
-  public async start() {
-    this.typedsocketClient = await plugins.typedsocket.TypedSocket.createClient(
-      this.typedrouter,
-      this.hubUrl
-    );
+  private async getAuthorization(contextArg: TShxAuthorizationContext): Promise<string> {
+    const signal = contextArg.abortSignal;
+    signal?.throwIfAborted();
+    let removeAbortHandler = () => {};
+    let authorization: string;
+    try {
+      authorization = await new Promise<string>((resolve, reject) => {
+        const onAbort = () => reject(signal?.reason);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        removeAbortHandler = () => signal?.removeEventListener('abort', onAbort);
+        if (signal?.aborted) {
+          onAbort();
+          return;
+        }
+        void Promise.resolve(this.#authorizationHeaderProvider(contextArg)).then(resolve, reject);
+      });
+    } finally {
+      removeAbortHandler();
+    }
+    if (typeof authorization !== 'string' || authorization.trim().length === 0) {
+      throw new TypeError('authorizationHeaderProvider must return a nonempty Authorization header.');
+    }
+    return authorization;
+  }
+
+  private async prepareSocketConnection(
+    contextArg: plugins.typedsocket.ITypedSocketConnectionPreparationContext
+  ): Promise<plugins.typedsocket.ITypedSocketPreparedConnectionOptions> {
+    if (!contextArg.supportsHeaders) {
+      throw new plugins.typedsocket.TypedSocketConnectionPreparationError('unsupported-headers');
+    }
+    const authorization = await this.getAuthorization(Object.freeze({
+      homeId: this.#homeId,
+      endpoint: contextArg.url,
+      method: 'connect',
+      transport: 'websocket',
+      abortSignal: contextArg.abortSignal,
+      attempt: contextArg.attempt,
+      deadline: contextArg.deadline,
+    }));
+    contextArg.abortSignal.throwIfAborted();
+    return { headers: { authorization } };
+  }
+
+  private prepareRequest<T extends object>(
+    payloadArg: T, allowedKeysArg: readonly string[], omitUndefinedFiltersArg = false
+  ) {
+    this.assertKnownProperties(payloadArg, allowedKeysArg, 'Request');
+    const normalizedPayload = { ...payloadArg };
+    if (omitUndefinedFiltersArg) {
+      for (const key of allowedKeysArg) {
+        if (Object.getOwnPropertyDescriptor(normalizedPayload, key)?.value === undefined) {
+          Reflect.deleteProperty(normalizedPayload, key);
+        }
+      }
+    }
+    this.assertJsonData(normalizedPayload);
+    return { ...structuredClone(normalizedPayload), context: { homeId: this.#homeId } };
+  }
+
+  private assertJsonData(valueArg: unknown): void {
+    const activeObjects = new WeakSet<object>();
+    const pending: { value: unknown; exiting?: boolean }[] = [{ value: valueArg }];
+    while (pending.length > 0) {
+      const entry = pending.pop();
+      if (!entry) continue;
+      const value = entry.value;
+      if (entry.exiting) {
+        if (value && typeof value === 'object') activeObjects.delete(value);
+        continue;
+      }
+      if (value === null || typeof value === 'string' || typeof value === 'boolean') continue;
+      if (typeof value === 'number' && Number.isFinite(value)) continue;
+      if (!value || typeof value !== 'object' || activeObjects.has(value)) {
+        throw new TypeError('Request payload must contain finite, acyclic JSON data.');
+      }
+      const isArray = Array.isArray(value);
+      if (!isArray && ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+        throw new TypeError('Request payload must contain plain JSON objects.');
+      }
+      const keys = Reflect.ownKeys(value);
+      if (isArray && keys.length !== value.length + 1) {
+        throw new TypeError('Request payload arrays must contain only populated indices.');
+      }
+      activeObjects.add(value);
+      pending.push({ value, exiting: true });
+      for (const key of keys) {
+        if (isArray && key === 'length') continue;
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (typeof key !== 'string' || !descriptor || !('value' in descriptor)
+          || !descriptor.enumerable
+          || (isArray && (!/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= value.length))) {
+          throw new TypeError('Request payload cannot contain accessors or unsupported properties.');
+        }
+        pending.push({ value: descriptor.value });
+      }
+    }
+  }
+
+  private assertKnownProperties(valueArg: unknown, allowedKeysArg: readonly string[], labelArg: string) {
+    if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)
+      || ![Object.prototype, null].includes(Object.getPrototypeOf(valueArg))) {
+      throw new TypeError(`${labelArg} must be a plain object.`);
+    }
+    for (const key of Reflect.ownKeys(valueArg)) {
+      const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+      if (typeof key !== 'string' || !allowedKeysArg.includes(key)
+        || !descriptor || !('value' in descriptor) || !descriptor.enumerable) {
+        throw new TypeError(`${labelArg} contains unsupported properties.`);
+      }
+    }
+  }
+
+  private queueLifecycleOperation(targetArg: 'started' | 'stopped'): Promise<void> {
+    if (this.queuedLifecycleOperation?.target === targetArg) {
+      return this.queuedLifecycleOperation.promise;
+    }
+
+    if (this.lifecycleOperationCount >= maxLifecycleOperationCount) {
+      return Promise.reject(
+        new Error(
+          `SmarthomeExchangeApiClient lifecycle queue is limited to ${maxLifecycleOperationCount} active and queued operations.`
+        )
+      );
+    }
+
+    const startStopIntentGeneration = this.stopIntentGeneration;
+    if (targetArg === 'stopped') {
+      this.stopIntentGeneration++;
+      this.pendingStartAbortController?.abort();
+    }
+
+    this.lifecycleOperationCount++;
+    const operationPromise = this.lifecycleTail.then(async () => {
+      if (targetArg === 'started') {
+        if (this.stopIntentGeneration !== startStopIntentGeneration) {
+          return;
+        }
+        if (this.socketNeedsCleanup) {
+          throw new Error(
+            'Cannot start while the existing TypedSocket requires successful cleanup.'
+          );
+        }
+        if (!this.#typedsocketClient) {
+          const startAbortController = new AbortController();
+          this.pendingStartAbortController = startAbortController;
+          try {
+            const createdSocket = await plugins.typedsocket.TypedSocket.createClient(
+              this.typedrouter,
+              this.#hubUrl,
+              {
+                abortSignal: startAbortController.signal,
+                autoReconnect: false,
+                prepareConnection: (contextArg) => this.prepareSocketConnection(contextArg),
+                connectionPreparationTimeoutMs: this.#socketConnectionPreparationTimeoutMs,
+              }
+            );
+            if (this.stopIntentGeneration !== startStopIntentGeneration) {
+              this.socketPendingStop = createdSocket;
+            } else {
+              this.#typedsocketClient = createdSocket;
+            }
+          } catch (error) {
+            if (
+              startAbortController.signal.aborted &&
+              this.stopIntentGeneration !== startStopIntentGeneration &&
+              error instanceof plugins.typedsocket.TypedSocketClientStartupAbortedError
+            ) {
+              return;
+            }
+            throw error;
+          } finally {
+            if (this.pendingStartAbortController === startAbortController) {
+              this.pendingStartAbortController = undefined;
+            }
+          }
+        }
+        return;
+      }
+
+      const socketToStop = this.socketPendingStop ?? this.#typedsocketClient;
+      if (!socketToStop) {
+        return;
+      }
+      try {
+        await socketToStop.stop();
+      } catch (error) {
+        this.socketNeedsCleanup = true;
+        throw error;
+      }
+      if (this.socketPendingStop === socketToStop) {
+        this.socketPendingStop = undefined;
+      }
+      if (this.#typedsocketClient === socketToStop) {
+        this.#typedsocketClient = undefined;
+      }
+      this.socketNeedsCleanup = false;
+    });
+    const lifecycleOperation = {
+      target: targetArg,
+      promise: operationPromise,
+    };
+    this.queuedLifecycleOperation = lifecycleOperation;
+    this.lifecycleTail = operationPromise.catch(() => undefined);
+    const finishOperation = () => {
+      this.lifecycleOperationCount--;
+      if (this.queuedLifecycleOperation === lifecycleOperation) {
+        this.queuedLifecycleOperation = undefined;
+      }
+    };
+    void operationPromise.then(finishOperation, finishOperation);
+    return operationPromise;
+  }
+
+  public start(): Promise<void> {
+    return this.queueLifecycleOperation('started');
   }
 
-  public async stop() {
-    await this.typedsocketClient?.stop();
-    this.typedsocketClient = undefined;
+  public stop(): Promise<void> {
+    return this.queueLifecycleOperation('stopped');
   }
 
-  public async listDevices(requestArg: plugins.shxInterfaces.request.IReq_ListDevices['request'] = {}) {
-    return this.fire<plugins.shxInterfaces.request.IReq_ListDevices>('listDevices', requestArg);
+  public async listDevices(requestArg: TListDevicesRequest = {}, optionsArg?: IShxApiRequestOptions) {
+    return this.fire<plugins.shxInterfaces.request.IReq_ListDevices>(
+      'listDevices', this.prepareRequest(requestArg, ['room', 'capability'], true), optionsArg
+    );
   }
 
-  public async listAgents() {
-    return this.fire<plugins.shxInterfaces.request.IReq_ListAgents>('listAgents', {});
+  public async listAgents(optionsArg?: IShxApiRequestOptions) {
+    return this.fire<plugins.shxInterfaces.request.IReq_ListAgents>('listAgents', this.prepareRequest({}, []), optionsArg);
   }
 
-  public async listTools(requestArg: plugins.shxInterfaces.request.IReq_ListTools['request'] = {}) {
-    return this.fire<plugins.shxInterfaces.request.IReq_ListTools>('listTools', requestArg);
+  public async listTools(requestArg: TListToolsRequest = {}, optionsArg?: IShxApiRequestOptions) {
+    return this.fire<plugins.shxInterfaces.request.IReq_ListTools>(
+      'listTools', this.prepareRequest(requestArg, ['ownerId'], true), optionsArg
+    );
   }
 
-  public async getHomeSnapshot() {
-    return this.fire<plugins.shxInterfaces.request.IReq_GetHomeSnapshot>('getHomeSnapshot', {});
+  public async getHomeSnapshot(optionsArg?: IShxApiRequestOptions) {
+    return this.fire<plugins.shxInterfaces.request.IReq_GetHomeSnapshot>(
+      'getHomeSnapshot', this.prepareRequest({}, []), optionsArg
+    );
   }
 
   public watchHomeSnapshot(
     callbackArg: THomeSnapshotWatchCallback,
     optionsArg: IHomeSnapshotWatchOptions = {}
   ): THomeSnapshotWatchStop {
-    const intervalMs = optionsArg.intervalMs ?? 5000;
+    this.assertKnownProperties(
+      optionsArg, ['abortSignal', 'timeoutMs', 'intervalMs', 'immediate', 'onError'], 'Watcher options'
+    );
+    const options = { ...optionsArg };
+    if (typeof callbackArg !== 'function'
+      || (options.immediate !== undefined && typeof options.immediate !== 'boolean')
+      || (options.onError !== undefined && typeof options.onError !== 'function')) {
+      throw new TypeError('Snapshot watchers require a callback, boolean immediate option, and optional error handler.');
+    }
+    this.captureRequestOptions({ abortSignal: options.abortSignal, timeoutMs: options.timeoutMs });
+    const intervalMs = options.intervalMs ?? 5000;
     if (!Number.isInteger(intervalMs) || intervalMs < 1 || intervalMs > 2_147_483_647) {
       throw new Error(
         'watchHomeSnapshot intervalMs must be an integer from 1 through 2147483647.'
@@ -94,19 +450,31 @@ export class SmarthomeExchangeApiClient {
     let stopped = false;
     let timeout: ReturnType<typeof setTimeout> | undefined;
     let activePoll: Promise<void> | undefined;
+    let activeRequestController: AbortController | undefined;
     let userHandlerActive = false;
 
     const clearScheduledPoll = () => {
-      if (timeout) {
+      if (timeout !== undefined) {
         clearTimeout(timeout);
         timeout = undefined;
       }
     };
 
+    const stopForReason = async (reasonArg?: unknown) => {
+      stopped = true;
+      clearScheduledPoll();
+      options.abortSignal?.removeEventListener('abort', onExternalAbort);
+      activeRequestController?.abort(reasonArg);
+      const pollToWait = userHandlerActive ? undefined : activePoll;
+      await pollToWait;
+    };
+
+    const onExternalAbort = () => {
+      void stopForReason(options.abortSignal?.reason);
+    };
+
     const scheduleNextPoll = () => {
-      if (stopped) {
-        return;
-      }
+      if (stopped) return;
       timeout = setTimeout(() => {
         timeout = undefined;
         activePoll = runPoll();
@@ -114,13 +482,11 @@ export class SmarthomeExchangeApiClient {
     };
 
     const handlePollError = async (errorArg: unknown) => {
-      if (stopped) {
-        return;
-      }
-      if (optionsArg.onError) {
+      if (stopped) return;
+      if (options.onError) {
         userHandlerActive = true;
         try {
-          await optionsArg.onError(errorArg);
+          await options.onError(errorArg);
         } catch (errorHandlerError) {
           console.error('watchHomeSnapshot error handler failed:', errorHandlerError);
         } finally {
@@ -132,8 +498,13 @@ export class SmarthomeExchangeApiClient {
     };
 
     const runPoll = async () => {
+      const controller = new AbortController();
+      activeRequestController = controller;
       try {
-        const snapshotResponse = await this.getHomeSnapshot();
+        const snapshotResponse = await this.getHomeSnapshot({
+          abortSignal: controller.signal,
+          timeoutMs: options.timeoutMs,
+        });
         if (!stopped) {
           userHandlerActive = true;
           try {
@@ -145,36 +516,49 @@ export class SmarthomeExchangeApiClient {
       } catch (error) {
         await handlePollError(error);
       } finally {
+        controller.abort();
+        if (activeRequestController === controller) activeRequestController = undefined;
         activePoll = undefined;
         scheduleNextPoll();
       }
     };
 
-    if (optionsArg.immediate === false) {
+    options.abortSignal?.addEventListener('abort', onExternalAbort, { once: true });
+    if (options.abortSignal?.aborted) {
+      stopped = true;
+      options.abortSignal.removeEventListener('abort', onExternalAbort);
+    } else if (options.immediate === false) {
       scheduleNextPoll();
     } else {
       activePoll = runPoll();
     }
 
-    return async () => {
-      stopped = true;
-      clearScheduledPoll();
-      const pollToWait = userHandlerActive ? undefined : activePoll;
-      await pollToWait;
-    };
+    return () => stopForReason();
   }
 
-  public async executeToolPlan(planArg: plugins.shxInterfaces.data.IToolPlan) {
-    return this.fire<plugins.shxInterfaces.request.IReq_ExecuteToolPlan>('executeToolPlan', {
-      plan: planArg,
-    });
+  public async executeToolPlan(planArg: plugins.shxInterfaces.data.IToolPlan, optionsArg?: IShxApiRequestOptions) {
+    const request = this.prepareRequest({ plan: planArg }, ['plan']);
+    this.assertKnownProperties(
+      request.plan, ['id', 'callerId', 'title', 'reason', 'confidence', 'calls'], 'Tool plan'
+    );
+    if (!Array.isArray(request.plan.calls)) throw new TypeError('Tool plan calls must be an array.');
+    for (const call of request.plan.calls) {
+      this.assertKnownProperties(call, ['id', 'toolId', 'callerId', 'input'], 'Tool call');
+    }
+    return this.fire<plugins.shxInterfaces.request.IReq_ExecuteToolPlan>(
+      'executeToolPlan', request, optionsArg
+    );
   }
 
-  public async listApprovals(requestArg: plugins.shxInterfaces.request.IReq_ListApprovals['request'] = {}) {
-    return this.fire<plugins.shxInterfaces.request.IReq_ListApprovals>('listApprovals', requestArg);
+  public async listApprovals(requestArg: TListApprovalsRequest = {}, optionsArg?: IShxApiRequestOptions) {
+    return this.fire<plugins.shxInterfaces.request.IReq_ListApprovals>(
+      'listApprovals', this.prepareRequest(requestArg, ['status'], true), optionsArg
+    );
   }
 
-  public async submitApproval(requestArg: plugins.shxInterfaces.request.IReq_SubmitApproval['request']) {
-    return this.fire<plugins.shxInterfaces.request.IReq_SubmitApproval>('submitApproval', requestArg);
+  public async submitApproval(requestArg: TSubmitApprovalRequest, optionsArg?: IShxApiRequestOptions) {
+    return this.fire<plugins.shxInterfaces.request.IReq_SubmitApproval>(
+      'submitApproval', this.prepareRequest(requestArg, ['approvalId', 'expectedActionDigest', 'decision']), optionsArg
+    );
   }
 }