Merge pull request #14 from holochain-open-dev/11-api-docs-for-holoom…

…-client

11 api docs for holoom client

.github/workflows/typedoc.yml

@@ -0,0 +1,37 @@
+name: Deploy TypeDoc to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'packages/client/**' # directories to monitor
+      - '**.md'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Generate TypeDoc documentation
+        working-directory: ./packages/client
+        run: npx typedoc
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./packages/client/docs
+          publish_branch: gh-pages

.vscode/settings.json

@@ -3,8 +3,10 @@
   "cSpell.words": [
     "Dalek",
     "Faceit",
+    "happ",
     "Holochain",
     "Holoom",
+    "PKCE",
     "pubkey",
     "Solana",
     "zome",

README.md

@@ -47,3 +47,8 @@ The above script enables caching of `holoom_rocket_server` build artefacts. (CI
 ```
 npm run test:e2e
 ```
+
+## API documents 
+
+[Holoom API docs](https://holochain-open-dev.github.io/holoom)
+

packages/client/package.json

@@ -7,7 +7,8 @@
     "/dist"
   ],
   "scripts": {
-    "build": "tsc --build"
+    "build": "tsc --build",
+    "generate:docs": "npx typedoc"
   },
   "dependencies": {
     "@msgpack/msgpack": "^2.7.2",

packages/client/src/external-id-attestation-requestor-client.ts

@@ -21,13 +21,35 @@ class RequestResolver {
   }
 }
 
+/**
+ * This client is used for obtaining `ExternalIdAttestation`s from the holoom
+ * network's authority agent. It should be invoked after receiving an
+ * authorization code (by callback) from the identity provider in question.
+ *
+ * Currently the only PKCE Authorization Code flow is supported.
+ */
+
 export class ExternalIdAttestationRequestorClient {
   constructor(readonly appAgent: AppAgentWebsocket) {
     appAgent.on("signal", (signal) => this.handleAppSignal(signal));
   }
 
   resolvers: { [requestId: string]: RequestResolver } = {};
 
+  /**
+   *
+   * Submits sign-in flow related secrets to the holoom network's authority
+   * agent, which in turn makes use of them as evidence that the user controls
+   * the corresponding external web2 account. The authority subsequently
+   * creates an `ExternalIdAttestation` entry to attest this is so.
+   *
+   * @param codeVerifier The pre-image to the PKCE challenge that was submitted
+   * to the identity provider's sign-in flow
+   * @param code The secret received from the identity provider on sign-in
+   * callback. The holoom network's authority agent exchanges this for an
+   * access token.
+   * @returns The `ExternalIdAttestation` entry created by the authority
+   */
   async requestExternalIdAttestation(
     codeVerifier: string,
     code: string
@@ -52,7 +74,7 @@ export class ExternalIdAttestationRequestorClient {
     return attestation;
   }
 
-  handleAppSignal(signal: AppSignal) {
+  private handleAppSignal(signal: AppSignal) {
     if (signal.zome_name !== "username_registry") return;
     const localSignal = signal.payload as LocalHoloomSignal;
     switch (localSignal.type) {
@@ -67,7 +89,7 @@ export class ExternalIdAttestationRequestorClient {
     }
   }
 
-  handleExternalIdAttested(signal: ExternalIdAttested) {
+  private handleExternalIdAttested(signal: ExternalIdAttested) {
     try {
       const attestation = decodeAppEntry<ExternalIdAttestation>(signal.record);
 
@@ -90,7 +112,7 @@ export class ExternalIdAttestationRequestorClient {
     }
   }
 
-  handleExternalIdRejected(signal: ExternalIdRejected) {
+  private handleExternalIdRejected(signal: ExternalIdRejected) {
     const resolver = this.resolvers[signal.request_id];
     if (!resolver) {
       console.error(`Resolver for ${signal.request_id} not found`);

packages/client/src/faceit-auth-flow-client.ts

@@ -1,3 +1,4 @@
+/** @ignore */
 export class FaceitAuthFlowClient {
   constructor(
     readonly config: {

packages/client/src/holoom-client.ts

@@ -17,10 +17,18 @@ import {
 } from "viem";
 import bs58 from "bs58";
 
+/**
+ * This client is intended to be the primary and most convenient method of
+ * interaction for apps built on the holoom platform. It provides tools for:
+ * - Username registration and attestation with an authority
+ * - Management of a metadata for an agent
+ * - Binding Solana and Ethereum wallets to the user's AgentPubKey
+ */
 export class HoloomClient {
   constructor(readonly appAgent: AppAgentWebsocket) {}
 
-  async ping(): Promise<void> {
+  /** @ignore */
+  private async ping(): Promise<void> {
     await this.appAgent.callZome({
       role_name: "holoom",
       zome_name: "ping",
@@ -29,6 +37,10 @@ export class HoloomClient {
     });
   }
 
+  /**
+   * Returns a promise that resolves once the holoom happ is loaded and ready
+   * to use.
+   */
   async untilReady(interval = 1000, timeout = 30_000) {
     const start = Date.now();
     while (Date.now() - start < timeout) {
@@ -41,9 +53,15 @@ export class HoloomClient {
     }
     throw new Error("HoloomClient.untilReady timed out");
   }
-  /** 
-   * usernames are verified for uniqueness by the authority agent
-  */
+
+  /**
+   * Returns the user's username if they have registered one.
+   *
+   * Returning `null` doesn't guarantee that the user has never registered, as
+   * this can also happen if the holochain conductor hasn't yet received gossip
+   * of an existing registration - this is likely to happen when switching
+   * hosts on the holo network.
+   */
   async getUsername(): Promise<string | null> {
     const record = await this.appAgent.callZome({
       role_name: "holoom",
@@ -59,6 +77,12 @@ export class HoloomClient {
     return entry.username;
   }
 
+  /**
+   * Submits a username for registration.
+   *
+   * The user's conductor will sign the username and submit it to the authority
+   * agent, which checks the signature and attests the username's uniqueness.
+   */
   async registerUsername(username: string) {
     await this.appAgent.callZome({
       role_name: "holoom",
@@ -68,6 +92,13 @@ export class HoloomClient {
     });
   }
 
+  /**
+   * Sets a value for an item in the user's metadata key-value store.
+   *
+   * Each user has a public freeform (i.e. without specific validation)
+   * string-to-string K-V store, where K-V pairs are encoded into link tags
+   * on the agent in question.
+   */
   async setMetadata(name: string, value: string) {
     await this.appAgent.callZome({
       role_name: "holoom",
@@ -77,6 +108,14 @@ export class HoloomClient {
     });
   }
 
+  /**
+   * Retrieves the latest value (if any) of an item in the user's metadata K-V
+   * store.
+   *
+   * It is possible for this value to be stale (or `null`) if the agent's
+   * conductor hasn't received gossip of the latest information - this is
+   * likely to happen when switching hosts on the holo network.
+   */
   async getMetadata(name: string): Promise<string | null> {
     const value = await this.appAgent.callZome({
       role_name: "holoom",
@@ -88,6 +127,14 @@ export class HoloomClient {
     return value;
   }
 
+  /**
+   * Retrieves a message to be signed by the specified EVM wallet in order to
+   * bind it to the user's agent.
+   *
+   * This signing message includes the agent's chain head and thus becomes
+   * stale if the user performs another action that progresses their chain
+   * before first submitting their binding signature.
+   */
   async getEvmWalletBindingMessage(evmAddress: Hex) {
     const message: string = await this.appAgent.callZome({
       role_name: "holoom",
@@ -98,6 +145,13 @@ export class HoloomClient {
     return message;
   }
 
+  /**
+   * Creates a verifiable entry that shows that the user has control over the
+   * specified EVM wallet.
+   *
+   * The provided signature must be over the current binding message - see
+   * `getEvmWalletBindingMessage`.
+   */
   async submitEvmWalletBinding(evmAddress: Hex, evmSignature: Hex) {
     const chain_wallet_signature: ChainWalletSignature_Evm = {
       Evm: {
@@ -113,6 +167,14 @@ export class HoloomClient {
     });
   }
 
+  /**
+   * Retrieves a message to be signed by the specified Solana wallet in order
+   * to bind it to the user's agent.
+   *
+   * This signing message includes the agent's chain head and thus becomes
+   * stale if the user performs another action that progresses their chain
+   * before first submitting their binding signature.
+   */
   async getSolanaWalletBindingMessage(solanaPublicKey: SolanaPublicKey) {
     const message: string = await this.appAgent.callZome({
       role_name: "holoom",
@@ -123,6 +185,13 @@ export class HoloomClient {
     return message;
   }
 
+  /**
+   * Creates a verifiable entry that shows that the user has control over the
+   * specified Solana wallet.
+   *
+   * The provided signature must be over the current binding message - see
+   * `getSolanaWalletBindingMessage`.
+   */
   async submitSolanaWalletBinding(
     solanaPublicKey: SolanaPublicKey,
     solanaSignature: Uint8Array
@@ -141,6 +210,13 @@ export class HoloomClient {
     });
   }
 
+  /**
+   * Retrieves an array of all EVM and Solana addresses under the user's control.
+   *
+   * It is possible for this information to be stale if the agent's conductor
+   * hasn't received gossip of the latest information - this is likely to
+   * happen when switching hosts on the holo network.
+   */
   async getBoundWallets(): Promise<BoundWallet[]> {
     const records: Record[] = await this.appAgent.callZome({
       role_name: "holoom",
@@ -163,6 +239,7 @@ export class HoloomClient {
     });
   }
 
+  /** @ignore */
   async refreshJq(arg: {
     program: string;
     input: { collection: string };