fix: improve docs and type descriptions

README.md

@@ -6,10 +6,12 @@ Filecoin metamask snap and related packages to enable developers to add Filecoin
 
 - [filsnap](./packages/snap) - Filecoin snap for metamask
 - [filsnap-adapter](./packages/adapter) - Adapter to interact with Filsnap from a dapp
+- [filsnap-adapter-react](./packages/adapter-react) - React hooks to interact with Filsnap from a dapp
 
 ## Examples
 
 - [`demo`](./packages/demo) - Preact demo dapp using [filsnap-adapter](./packages/filsnap-adapter) to interact with [filsnap](./packages/filsnap)
+- [`fil-forwarder-viem`](./packages/fil-forwarder-viem) - [Viem](https://viem.sh/) example to send FIL using FilForwarder contract.
 
 ### Checkout examples
 
@@ -24,7 +26,7 @@ pnpm install
 pnpm dev
 ```
 
-You can try any of the examples by replacing `filsnap-demo` with the name of the example you want to try.
+You can try any of the examples by replacing `demo` with the name of the example you want to try.
 
 ## Contributing
 

examples/demo/package.json

@@ -53,20 +53,20 @@
     "dns-over-http-resolver": "^2.1.1",
     "filsnap-adapter": "workspace:^",
     "filsnap-adapter-react": "workspace:^",
-    "iso-base": "^1.1.1",
-    "iso-filecoin": "^2.0.1",
+    "iso-base": "^1.1.2",
+    "iso-filecoin": "^2.0.2",
     "metamask-testing-tools": "^1.1.4",
     "preact": "^10.16.0",
     "react-hook-form": "^7.45.2",
-    "viem": "^1.4.1",
+    "viem": "^1.4.2",
     "wagmi": "^1.3.9",
     "water.css": "^2.1.1"
   },
   "devDependencies": {
     "@babel/core": "^7.22.9",
-    "@playwright/test": "^1.36.1",
+    "@playwright/test": "^1.36.2",
     "@preact/preset-vite": "^2.5.0",
-    "@types/node": "^20.4.4",
+    "@types/node": "^20.4.5",
     "tiny-git-rev-sync": "^0.1.0",
     "vite": "^4.4.7"
   },

examples/fil-forwarder-viem/package.json

@@ -47,16 +47,16 @@
   "license": "MIT",
   "dependencies": {
     "filsnap-adapter": "workspace:^",
-    "iso-base": "^1.1.1",
-    "iso-filecoin": "^2.0.1",
+    "iso-base": "^1.1.2",
+    "iso-filecoin": "^2.0.2",
     "prettier": "3.0.0",
-    "viem": "^1.4.1"
+    "viem": "^1.4.2"
   },
   "devDependencies": {
     "@babel/core": "^7.22.9",
-    "@playwright/test": "^1.36.1",
+    "@playwright/test": "^1.36.2",
     "@preact/preset-vite": "^2.5.0",
-    "@types/node": "^20.4.4",
+    "@types/node": "^20.4.5",
     "vite": "^4.4.7"
   },
   "eslintConfig": {

package.json

@@ -17,7 +17,7 @@
     "build": "pnpm -r --if-present run build",
     "lint": "pnpm -r --if-present run lint",
     "test": "pnpm -r --if-present run test",
-    "docs": "typedoc --out docs --plugin typedoc-plugin-missing-exports --plugin typedoc-plugin-zod --plugin typedoc-plugin-expand-object-like-types"
+    "docs": "typedoc --out docs --plugin typedoc-plugin-missing-exports --plugin typedoc-plugin-zod"
   },
   "devDependencies": {
     "depcheck": "^1.4.3",
@@ -26,7 +26,6 @@
     "prettier": "3.0.0",
     "simple-git-hooks": "^2.9.0",
     "typedoc": "^0.24.8",
-    "typedoc-plugin-expand-object-like-types": "^0.1.2",
     "typedoc-plugin-missing-exports": "^2.0.0",
     "typedoc-plugin-zod": "^1.0.2",
     "typescript": "5.1.6",

packages/adapter-react/README.md

@@ -1,11 +1,56 @@
-# Filsnap adapter
+# filsnap-adapter-react
 
 [![NPM Version](https://img.shields.io/npm/v/filsnap-adapter-react.svg)](https://www.npmjs.com/package/filsnap-adapter-react)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Adapter](https://github.com/filecoin-project/filsnap/actions/workflows/adapter-react.yml/badge.svg)](https://github.com/filecoin-project/filsnap/actions/workflows/adapter-react.yml)
 
-React hook for [Filsnap adapter](../adapter/README.md).
+React hook for [Filsnap](../snap/README.md).
+
+## Installation
+
+```bash
+pnpm install filsnap-adapter-react
+```
+
+## Usage
+
+```js
+import { FilsnapProvider } from 'filsnap-adapter-react'
+
+const config = {
+  network: 'testnet',
+}
+
+function Main() {
+  return (
+    <FilsnapProvider snap="npm:filsnap" config={config}>
+      <App />
+    </FilsnapProvider>
+  )
+}
+```
+
+```js
+import { useFilsnap } from 'filsnap-adapter-react'
+
+function App() {
+  const { isLoading, hasFlask, isConnected, connect, account, error } =
+    useFilsnap()
+
+  if (isLoading) {
+    return <div>Loading...</div>
+  }
+
+  if (!isConnected) {
+    return <button onClick={() => connect()}>Connect to Filecoin Snap</button>
+  }
+
+  return <div>Connected to {account.address}</div>
+}
+```
+
+Check out the [demo](../../examples/demo) for a working example and the [API](https://filecoin-project.github.io/filsnap/modules/filsnap_adapter_react.html) for more details.
 
 ## Contributing
 

packages/adapter-react/package.json

@@ -45,7 +45,7 @@
   "devDependencies": {
     "@testing-library/react-hooks": "^8.0.1",
     "@types/mocha": "^10.0.1",
-    "@types/node": "^20.4.4",
+    "@types/node": "^20.4.5",
     "@types/react": "^17.0.0",
     "@types/react-dom": "^17.0.0",
     "assert": "^2.0.0",

packages/adapter/README.md

@@ -5,7 +5,44 @@
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Adapter](https://github.com/filecoin-project/filsnap/actions/workflows/adapter.yml/badge.svg)](https://github.com/filecoin-project/filsnap/actions/workflows/adapter.yml)
 
-Filsnap adapter is used to install Filecoin snap and expose it's.
+> Adapter for [Filsnap](../snap/)
+
+Exposes a simple API to interact the snap from a dapp and also Fil Forwarder contract metadata.
+
+## Installation
+
+```bash
+pnpm install filsnap-adapter
+```
+
+## Usage
+
+This adapter interacts directly with the snap, so Metamask Flask needs to be installed and unlocked in the browser.
+
+```js
+import * as Filsnap from 'filsnap-adapter'
+
+const hasFlask = await Filsnap.hasFlask()
+if (!hasFlask) {
+  console.error('Flask not installed')
+  return
+}
+
+const snap = await Filsnap.connect({ network: 'testnet' }, 'npm:filsnap')
+
+const { error, result } = await snap.getAddress()
+if (error) {
+  console.error(error)
+} else {
+  console.log(result)
+  // t1d2xrzcslx7xlbbylc5c3d5lvandqw4iwl6epxba
+}
+
+const isConnected = await snap.isConnected()
+// true
+```
+
+Check out the [demo](../../examples/demo) for a working example and the [API](https://filecoin-project.github.io/filsnap/modules/filsnap_adapter.html) for more details.
 
 ## Contributing
 

packages/adapter/package.json

@@ -52,8 +52,8 @@
     "filsnap": "workspace:^"
   },
   "devDependencies": {
-    "@playwright/test": "^1.36.1",
-    "@types/node": "^20.4.4",
+    "@playwright/test": "^1.36.2",
+    "@types/node": "^20.4.5",
     "metamask-testing-tools": "^1.1.4",
     "typescript": "5.1.6"
   },

packages/adapter/src/snap.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/strict-boolean-expressions */
 import type {
   FilSnapMethods,
   Network,
@@ -22,6 +23,9 @@ export class FilsnapAdapter {
     this.request = window.ethereum.request as RequestWithFilSnap
   }
 
+  /**
+   * Check if Metamask flask is installed and enabled
+   */
   static async hasFlask(): Promise<boolean> {
     if (window.ethereum == null || !window.ethereum.isMetaMask) {
       return false
@@ -38,6 +42,12 @@ export class FilsnapAdapter {
     return true
   }
 
+  /**
+   * Check if Filsnap is installed and enabled
+   *
+   * @param snapId - Snap ID to check for. Defaults to `npm:filsnap` which is the default ID for the Filsnap snap.
+   * @param snapVersion - Snap version to check for. Defaults to `*` which matches any version.
+   */
   static async isConnected(
     snapId: string = 'npm:filsnap',
     snapVersion: string = '*'
@@ -70,6 +80,15 @@ export class FilsnapAdapter {
     return true
   }
 
+  /**
+   * Create and configure a new Filsnap adapter
+   *
+   * This will check if Filsnap is installed and enabled, and if not, throw an error.
+   *
+   * @param config - Snap config
+   * @param snapId - Snap ID to check for. Defaults to `npm:filsnap` which is the default ID for the Filsnap snap.
+   * @param snapVersion - Snap version to check for. Defaults to `*` which matches any version.
+   */
   static async create(
     config: Parameters<FilSnapMethods['fil_configure']>[1],
     snapId: string = 'npm:filsnap',
@@ -91,6 +110,15 @@ export class FilsnapAdapter {
     return adapter
   }
 
+  /**
+   * Installs and connects to Filsnap
+   *
+   * @throws Error if Metamask flask is not installed
+   *
+   * @param config - Snap config
+   * @param snapId - Snap ID to check for. Defaults to `npm:filsnap` which is the default ID for the Filsnap snap.
+   * @param snapVersion - Snap version to check for. Defaults to `*` which matches any version.
+   */
   static async connect(
     config: Parameters<FilSnapMethods['fil_configure']>[1],
     snapId: string = 'npm:filsnap',
@@ -120,6 +148,11 @@ export class FilsnapAdapter {
     return adapter
   }
 
+  /**
+   * Configure the snap
+   *
+   * @param params - {@link FilSnapMethods.fil_configure} params
+   */
   async configure(
     params: Parameters<FilSnapMethods['fil_configure']>[1]
   ): ReturnType<FilSnapMethods['fil_configure']> {
@@ -141,6 +174,11 @@ export class FilsnapAdapter {
     return config
   }
 
+  /**
+   * Request account info from the snap
+   *
+   * @see {@link FilSnapMethods.fil_getAccountInfo}
+   */
   async getAccountInfo(): ReturnType<FilSnapMethods['fil_getAccountInfo']> {
     return await this.request({
       method: 'wallet_invokeSnap',
@@ -153,6 +191,11 @@ export class FilsnapAdapter {
     })
   }
 
+  /**
+   * Request account address from the snap
+   *
+   * @see {@link FilSnapMethods.fil_getAddress}
+   */
   async getAddress(): ReturnType<FilSnapMethods['fil_getAddress']> {
     return await this.request({
       method: 'wallet_invokeSnap',
@@ -165,6 +208,11 @@ export class FilsnapAdapter {
     })
   }
 
+  /**
+   * Request account public key from the snap
+   *
+   * @see {@link FilSnapMethods.fil_getPublicKey}
+   */
   async getPublicKey(): ReturnType<FilSnapMethods['fil_getPublicKey']> {
     return await this.request({
       method: 'wallet_invokeSnap',
@@ -177,6 +225,11 @@ export class FilsnapAdapter {
     })
   }
 
+  /**
+   * Export the account private key from the snap
+   *
+   * @see {@link FilSnapMethods.fil_exportPrivateKey}
+   */
   async exportPrivateKey(): ReturnType<FilSnapMethods['fil_exportPrivateKey']> {
     return await this.request({
       method: 'wallet_invokeSnap',
@@ -189,6 +242,11 @@ export class FilsnapAdapter {
     })
   }
 
+  /**
+   * Request account balance from the snap
+   *
+   * @see {@link FilSnapMethods.fil_getBalance}
+   */
   async getBalance(): ReturnType<FilSnapMethods['fil_getBalance']> {
     return await this.request({
       method: 'wallet_invokeSnap',
@@ -213,6 +271,11 @@ export class FilsnapAdapter {
     })
   }
 
+  /**
+   * Sign a message
+   *
+   * @param params - {@link FilSnapMethods.fil_signMessage} params
+   */
   async signMessage(
     params: Parameters<FilSnapMethods['fil_signMessage']>[1]
   ): ReturnType<FilSnapMethods['fil_signMessage']> {
@@ -228,6 +291,11 @@ export class FilsnapAdapter {
     })
   }
 
+  /**
+   * Sign a raw message
+   *
+   * @param params - {@link FilSnapMethods.fil_signMessageRaw} params
+   */
   async signMessageRaw(
     params: Parameters<FilSnapMethods['fil_signMessageRaw']>[1]
   ): ReturnType<FilSnapMethods['fil_signMessageRaw']> {
@@ -243,6 +311,11 @@ export class FilsnapAdapter {
     })
   }
 
+  /**
+   * Send a signed message
+   *
+   * @param params - {@link FilSnapMethods.fil_sendMessage} params
+   */
   async sendMessage(
     params: Parameters<FilSnapMethods['fil_sendMessage']>[1]
   ): ReturnType<FilSnapMethods['fil_sendMessage']> {
@@ -280,6 +353,11 @@ export class FilsnapAdapter {
     })
   }
 
+  /**
+   * Switch to or add a different network
+   *
+   * @param network - Network to switch to. Defaults to `mainnet`
+   */
   async switchOrAddChain(network: Network): Promise<void> {
     let config = {
       chainId: '0x13A',