refactor(client)!: rename structs and params, extend docs #130 (#231)

Breaking changes are these renamings:

- `ApiTelemetry` to `TelemetryAPI`  (for consistency with `MainAPI` and `WebSocketAPI`)
- in `CreateClientParams`: `accountDomain` and `accountKeyPair` to `authority` and `authorityPrivateKey` (for consistency with data model)

Author: 0x009922

CONTRIBUTING.md

@@ -57,3 +57,16 @@ You can add this to `.git/hooks/pre-commit`:
 #!/bin/sh
 deno task ok
 ```
+
+## Preview Docs
+
+You can `cd` into a package directory (e.g. `packages/core`) and run these commands in parallel (requires `watchexec`
+and `jq` tools):
+
+```shell
+watchexec -e ts deno doc --html $(cat deno.json* | deno run npm:json5 | jq -r '.exports | .[]')
+```
+
+```shell
+deno run -A npm:vite serve docs
+```

README.md

@@ -31,8 +31,8 @@ const kp = types.KeyPair.random()
 const client = new Client({
   toriiBaseURL: new URL('http://localhost:8080'),
   chain: '000-000',
-  accountDomain: new types.Name('wonderland'),
-  accountKeyPair: kp,
+  authority: new types.AccountId(kp.publicKey(), new types.DomainId('wonderland')),
+  authorityPrivateKey: kp.privateKey(),
 })
 
 async function test() {

deno.lock

@@ -6,6 +6,9 @@ import type { SocketEmitMapBase } from './util.ts'
 import { setupWebSocket } from './util.ts'
 import { type IsomorphicWebSocketAdapter, nativeWS } from './web-socket/mod.ts'
 
+/**
+ * Lower-level client
+ */
 export class WebSocketAPI {
   public readonly toriiBaseURL: URL
   public readonly adapter: IsomorphicWebSocketAdapter

packages/client/api-ws.ts

@@ -16,7 +16,7 @@ import {
 import { urlJoinPath } from './util.ts'
 
 /**
- * Peer information returned from {@link ApiTelemetry.peers}
+ * Peer information returned from {@link TelemetryAPI.peers}
  */
 export interface PeerJson {
   /**
@@ -78,17 +78,26 @@ export class HttpTransport {
   }
 }
 
+/**
+ * Lower-level client to interact with Iroha HTTP APIs.
+ *
+ * It is separated from {@linkcode WebSocketAPI}.
+ *
+ * It is lower-level in a sense that, for example, {@linkcode MainAPI#transaction} accepts an already signed transaction
+ * and simply "fire and forget"s it, while {@linkcode Client#transaction} helps to construct a transaction, submit it,
+ * and verify that it is accepted.
+ */
 export class MainAPI {
   /**
    * Works only if Iroha is compiled with `telemetry` feature flag.
    */
-  public readonly telemetry: ApiTelemetry
+  public readonly telemetry: TelemetryAPI
 
   private readonly http: HttpTransport
 
   public constructor(http: HttpTransport) {
     this.http = http
-    this.telemetry = new ApiTelemetry(http)
+    this.telemetry = new TelemetryAPI(http)
   }
 
   public async health(): Promise<HealthResult> {
@@ -178,7 +187,7 @@ export class QueryValidationError extends Error {
 }
 
 // TODO: handle errors with a hint that Iroha might be not compiled with the needed features
-export class ApiTelemetry {
+export class TelemetryAPI {
   private readonly http: HttpTransport
 
   public constructor(http: HttpTransport) {

packages/client/api.ts

@@ -1,4 +1,4 @@
-import type { KeyPair, PrivateKey } from '@iroha/core/crypto'
+import type { PrivateKey } from '@iroha/core/crypto'
 import * as types from '@iroha/core/data-model'
 import type { Except } from 'type-fest'
 import defer from 'p-defer'
@@ -31,9 +31,18 @@ export interface CreateClientParams {
    * The base URL of **Torii**, Iroha API Gateway.
    */
   toriiBaseURL: URL
+  /**
+   * Chain ID.
+   */
   chain: string
-  accountDomain: types.DomainId
-  accountKeyPair: KeyPair
+  /**
+   * Authority on which behalf to sign transactions and queries.
+   */
+  authority: types.AccountId
+  /**
+   * The private key of {@linkcode CreateClientParams.authority}.
+   */
+  authorityPrivateKey: types.PrivateKey
 }
 
 export interface SubmitParams {
@@ -62,6 +71,20 @@ export class TransactionExpiredError extends Error {
   }
 }
 
+/**
+ * All-in-one Iroha client.
+ *
+ * Through it, it is possible to perform all different kinds of interactions with Iroha, e.g.
+ * signing and submitting transactions and queries or listening to events through WebSockets.
+ *
+ * It is possible to use each layer of functionality separately, through lower-level layers:
+ *
+ * - {@linkcode MainAPI}
+ * - {@linkcode WebSocketAPI}
+ *
+ * It could be useful if e.g. you don't need to submit transactions (which requires an account with a key pair),
+ * but only want to check Iroha status.
+ */
 export class Client {
   public readonly params: CreateClientParams
 
@@ -83,21 +106,18 @@ export class Client {
     const http = new HttpTransport(params.toriiBaseURL, params.fetch)
     this.api = new MainAPI(http)
 
-    const executor = new QueryExecutor(this.api, this.authority(), this.authorityPrivateKey())
+    const executor = new QueryExecutor(this.api, this.authority, this.authorityPrivateKey)
     this.find = new FindAPI(executor)
 
     this.socket = new WebSocketAPI(params.toriiBaseURL, params.ws)
   }
 
-  public authority(): types.AccountId {
-    return new types.AccountId(
-      this.params.accountKeyPair.publicKey(),
-      this.params.accountDomain,
-    )
+  public get authority(): types.AccountId {
+    return this.params.authority
   }
 
-  public authorityPrivateKey(): PrivateKey {
-    return this.params.accountKeyPair.privateKey()
+  public get authorityPrivateKey(): PrivateKey {
+    return this.params.authorityPrivateKey
   }
 
   /**
@@ -114,10 +134,10 @@ export class Client {
     const tx = signTransaction(
       buildTransactionPayload(executable, {
         chain: this.params.chain,
-        authority: this.authority(),
+        authority: this.authority,
         ...params,
       }),
-      this.params.accountKeyPair.privateKey(),
+      this.authorityPrivateKey,
     )
 
     return new TransactionHandle(tx, this)