From 8cd9114764edfaf917f08c8bd646a84aacb97a88 Mon Sep 17 00:00:00 2001 From: Alex Lewin <43247027+alexlwn123@users.noreply.github.com> Date: Fri, 4 Oct 2024 11:32:31 -0400 Subject: [PATCH] chore: tweak docs site layout (#68) * chore: clean up docs * chore: update sidebar and exmaple instructions --- docs/.vitepress/sidebar.ts | 89 +++++++++++----------- docs/core/FedimintWallet/cleanup.md | 2 +- docs/core/FedimintWallet/index.md | 2 - docs/core/FedimintWallet/initialize.md | 2 +- docs/core/FedimintWallet/isOpen.md | 2 +- docs/core/FedimintWallet/joinFederation.md | 2 +- docs/core/FedimintWallet/open.md | 2 +- docs/core/FedimintWallet/setLogLevel.md | 2 +- docs/core/architecture.md | 4 +- docs/core/getting-started.md | 26 ++++--- docs/core/guides/balance.md | 2 +- docs/core/guides/cleanup.md | 2 +- docs/core/guides/first-payment.md | 2 +- docs/core/guides/index.md | 2 +- docs/core/guides/initialization.md | 2 +- docs/core/guides/multiple-federations.md | 2 +- docs/core/guides/sending-ecash.md | 2 +- docs/examples/bare-js.md | 24 ++++-- docs/examples/vite-react.md | 18 ++++- packages/core-web/README.md | 77 ++----------------- packages/core-web/docs/ARCHITECTURE.md | 71 +---------------- packages/core-web/docs/TESTING.md | 17 +---- 22 files changed, 114 insertions(+), 240 deletions(-) diff --git a/docs/.vitepress/sidebar.ts b/docs/.vitepress/sidebar.ts index 5193535..d56ab5a 100644 --- a/docs/.vitepress/sidebar.ts +++ b/docs/.vitepress/sidebar.ts @@ -1,38 +1,35 @@ import type { DefaultTheme } from 'vitepress' export function getSidebar() { - return { - '/core/': [ - { - base: '/core/', - text: 'Introduction', - items: [ - { text: 'Overview', link: 'overview' }, - { text: 'Getting Started', link: 'getting-started' }, - { text: 'Architecture', link: 'architecture' }, - ], - }, - ...FedimintWalletSidebar, - { - text: 'Dev', - base: '/core/dev/', - items: [ - { text: 'Contributing', link: 'contributing' }, - { text: 'Testing', link: 'testing' }, - ], - }, - ], - '/examples/': [ - { - base: '/examples/', - text: 'Examples', - items: [ - { text: 'Vite + React', link: 'vite-react' }, - { text: 'Vanilla JS', link: 'bare-js' }, - ], - }, - ], - } satisfies DefaultTheme.Sidebar + return [ + { + base: '/core/', + text: 'Introduction', + items: [ + { text: 'Overview', link: 'overview' }, + { text: 'Getting Started', link: 'getting-started' }, + { text: 'Architecture', link: 'architecture' }, + ], + }, + ...FedimintWalletSidebar, + { + base: '/examples/', + text: 'Examples', + items: [ + { text: 'Vite + React', link: 'vite-react' }, + { text: 'Vanilla JS', link: 'bare-js' }, + ], + }, + { + text: 'Dev', + collapsed: true, + base: '/core/dev/', + items: [ + { text: 'Contributing', link: 'contributing' }, + { text: 'Testing', link: 'testing' }, + ], + }, + ] satisfies DefaultTheme.Sidebar } const FedimintWalletSidebar = [ @@ -113,18 +110,18 @@ const FedimintWalletSidebar = [ }, ], }, - { - text: 'Type Aliases', - collapsed: true, - base: '/core/type-aliases/', - items: [ - { text: 'CreateResponse', link: 'CreateResponse' }, - { text: 'FeeToAmount', link: 'FeeToAmount' }, - { text: 'LightningGateway', link: 'LightningGateway' }, - { text: 'LnPayState', link: 'LnPayState' }, - { text: 'OutgoingLightningPayment', link: 'OutgoingLightningPayment' }, - { text: 'PayType', link: 'PayType' }, - { text: 'RouteHint', link: 'RouteHint' }, - ], - }, + // { + // text: 'Type Aliases', + // collapsed: true, + // base: '/core/type-aliases/', + // items: [ + // { text: 'CreateResponse', link: 'CreateResponse' }, + // { text: 'FeeToAmount', link: 'FeeToAmount' }, + // { text: 'LightningGateway', link: 'LightningGateway' }, + // { text: 'LnPayState', link: 'LnPayState' }, + // { text: 'OutgoingLightningPayment', link: 'OutgoingLightningPayment' }, + // { text: 'PayType', link: 'PayType' }, + // { text: 'RouteHint', link: 'RouteHint' }, + // ], + // }, ] diff --git a/docs/core/FedimintWallet/cleanup.md b/docs/core/FedimintWallet/cleanup.md index c362d83..31e86b6 100644 --- a/docs/core/FedimintWallet/cleanup.md +++ b/docs/core/FedimintWallet/cleanup.md @@ -2,4 +2,4 @@ This guide hasn't been written yet. If you'd like to contribute, please open a PR! -You can use the `Edit This Page` link below. +You can use the `Suggest changes to this page` link below. diff --git a/docs/core/FedimintWallet/index.md b/docs/core/FedimintWallet/index.md index e747bba..8630908 100644 --- a/docs/core/FedimintWallet/index.md +++ b/docs/core/FedimintWallet/index.md @@ -77,8 +77,6 @@ After this call, the FedimintWallet instance should be discarded. > **initialize**(): `Promise`\<`void`\> -https://wagmi.sh/react/api/hooks/useAccount - #### Returns `Promise`\<`void`\> diff --git a/docs/core/FedimintWallet/initialize.md b/docs/core/FedimintWallet/initialize.md index c362d83..31e86b6 100644 --- a/docs/core/FedimintWallet/initialize.md +++ b/docs/core/FedimintWallet/initialize.md @@ -2,4 +2,4 @@ This guide hasn't been written yet. If you'd like to contribute, please open a PR! -You can use the `Edit This Page` link below. +You can use the `Suggest changes to this page` link below. diff --git a/docs/core/FedimintWallet/isOpen.md b/docs/core/FedimintWallet/isOpen.md index c362d83..31e86b6 100644 --- a/docs/core/FedimintWallet/isOpen.md +++ b/docs/core/FedimintWallet/isOpen.md @@ -2,4 +2,4 @@ This guide hasn't been written yet. If you'd like to contribute, please open a PR! -You can use the `Edit This Page` link below. +You can use the `Suggest changes to this page` link below. diff --git a/docs/core/FedimintWallet/joinFederation.md b/docs/core/FedimintWallet/joinFederation.md index c362d83..31e86b6 100644 --- a/docs/core/FedimintWallet/joinFederation.md +++ b/docs/core/FedimintWallet/joinFederation.md @@ -2,4 +2,4 @@ This guide hasn't been written yet. If you'd like to contribute, please open a PR! -You can use the `Edit This Page` link below. +You can use the `Suggest changes to this page` link below. diff --git a/docs/core/FedimintWallet/open.md b/docs/core/FedimintWallet/open.md index c362d83..31e86b6 100644 --- a/docs/core/FedimintWallet/open.md +++ b/docs/core/FedimintWallet/open.md @@ -2,4 +2,4 @@ This guide hasn't been written yet. If you'd like to contribute, please open a PR! -You can use the `Edit This Page` link below. +You can use the `Suggest changes to this page` link below. diff --git a/docs/core/FedimintWallet/setLogLevel.md b/docs/core/FedimintWallet/setLogLevel.md index c362d83..31e86b6 100644 --- a/docs/core/FedimintWallet/setLogLevel.md +++ b/docs/core/FedimintWallet/setLogLevel.md @@ -2,4 +2,4 @@ This guide hasn't been written yet. If you'd like to contribute, please open a PR! -You can use the `Edit This Page` link below. +You can use the `Suggest changes to this page` link below. diff --git a/docs/core/architecture.md b/docs/core/architecture.md index 2a58912..e6db08f 100644 --- a/docs/core/architecture.md +++ b/docs/core/architecture.md @@ -1,6 +1,6 @@ # Architecture -The Fedimint Web SDK **Core Web** library is a modular and extensible JavaScript library designed to interact with the Fedimint client in a web browser. It provides a high-level API for developers to manage federated e-cash wallets, perform operations like minting and spending e-cash, and interact with the Lightning Network. The library is structured to promote maintainability, scalability, and ease of use, leveraging modern software development practices. +The Fedimint Web SDK **Core Web** library is a modular and extensible JavaScript library designed to interact with the Fedimint client in a web browser. It provides a high-level API for developers to manage federated ecash wallets, perform operations like minting and spending ecash, and interact with the Lightning Network. The library is structured to promote maintainability, scalability, and ease of use, leveraging modern software development practices. The **Core Web** library is built around a set of composable services and a communication layer that interacts with a Web Worker running WebAssembly (WASM) code. @@ -36,7 +36,7 @@ Handles federation-related operations such as joining federations, retrieving co ### **MintService** -Manages operations related to minting and handling e-cash notes, including redeeming, reissuing, spending, and validating notes. +Manages operations related to minting and handling ecash notes, including redeeming, reissuing, spending, and validating notes. ### **LightningService** diff --git a/docs/core/getting-started.md b/docs/core/getting-started.md index 74246c5..8cba747 100644 --- a/docs/core/getting-started.md +++ b/docs/core/getting-started.md @@ -1,12 +1,11 @@ # Getting Started -::: danger READ THIS FIRST (Disclaimer) +::: danger Disclaimer +This is very new. Use with caution. [Report bugs](https://github.com/fedimint/fedimint-web-sdk/issues). -This is very new. It is still a work in progress and should not be used for any serious applications. The api's are not settled and may change often. +APIs may change. ::: -[[toc]] - ## Installation To add @fedimint/core-web to your project, install the package using your preferred package manager: @@ -242,10 +241,15 @@ For a list of public federations with invite codes, visit [Bitcoin Mints](https: ## What's Next? -- To see the sdk in action, check out the [examples](../examples/vite-react.md) - - Vite + React: [`examples/vite-react`](../examples/vite-react.md) - - VanillaJS + HTML example: [`examples/bare-js`](../examples/bare-js.md) -- To learn more about @fedimint/core-web and how to use it effectively in your projects, explore the following topics: - - [Overview](overview) - - [API Reference](FedimintWallet/index) - - [Architecture](architecture) +#### Check out the Example Projects + +- [Vite + React](../examples/vite-react.md) +- [VanillaJS + HTML example](../examples/bare-js.md) + +
+ +#### To learn more about Web SDK, explore the docs + +- [SDK Overview](overview) +- [Library Architecture](architecture) +- [API Reference](FedimintWallet/index) diff --git a/docs/core/guides/balance.md b/docs/core/guides/balance.md index c362d83..31e86b6 100644 --- a/docs/core/guides/balance.md +++ b/docs/core/guides/balance.md @@ -2,4 +2,4 @@ This guide hasn't been written yet. If you'd like to contribute, please open a PR! -You can use the `Edit This Page` link below. +You can use the `Suggest changes to this page` link below. diff --git a/docs/core/guides/cleanup.md b/docs/core/guides/cleanup.md index c362d83..31e86b6 100644 --- a/docs/core/guides/cleanup.md +++ b/docs/core/guides/cleanup.md @@ -2,4 +2,4 @@ This guide hasn't been written yet. If you'd like to contribute, please open a PR! -You can use the `Edit This Page` link below. +You can use the `Suggest changes to this page` link below. diff --git a/docs/core/guides/first-payment.md b/docs/core/guides/first-payment.md index c362d83..31e86b6 100644 --- a/docs/core/guides/first-payment.md +++ b/docs/core/guides/first-payment.md @@ -2,4 +2,4 @@ This guide hasn't been written yet. If you'd like to contribute, please open a PR! -You can use the `Edit This Page` link below. +You can use the `Suggest changes to this page` link below. diff --git a/docs/core/guides/index.md b/docs/core/guides/index.md index c362d83..31e86b6 100644 --- a/docs/core/guides/index.md +++ b/docs/core/guides/index.md @@ -2,4 +2,4 @@ This guide hasn't been written yet. If you'd like to contribute, please open a PR! -You can use the `Edit This Page` link below. +You can use the `Suggest changes to this page` link below. diff --git a/docs/core/guides/initialization.md b/docs/core/guides/initialization.md index c362d83..31e86b6 100644 --- a/docs/core/guides/initialization.md +++ b/docs/core/guides/initialization.md @@ -2,4 +2,4 @@ This guide hasn't been written yet. If you'd like to contribute, please open a PR! -You can use the `Edit This Page` link below. +You can use the `Suggest changes to this page` link below. diff --git a/docs/core/guides/multiple-federations.md b/docs/core/guides/multiple-federations.md index c362d83..31e86b6 100644 --- a/docs/core/guides/multiple-federations.md +++ b/docs/core/guides/multiple-federations.md @@ -2,4 +2,4 @@ This guide hasn't been written yet. If you'd like to contribute, please open a PR! -You can use the `Edit This Page` link below. +You can use the `Suggest changes to this page` link below. diff --git a/docs/core/guides/sending-ecash.md b/docs/core/guides/sending-ecash.md index c362d83..31e86b6 100644 --- a/docs/core/guides/sending-ecash.md +++ b/docs/core/guides/sending-ecash.md @@ -2,4 +2,4 @@ This guide hasn't been written yet. If you'd like to contribute, please open a PR! -You can use the `Edit This Page` link below. +You can use the `Suggest changes to this page` link below. diff --git a/docs/examples/bare-js.md b/docs/examples/bare-js.md index f5c166e..baec401 100644 --- a/docs/examples/bare-js.md +++ b/docs/examples/bare-js.md @@ -13,21 +13,35 @@ There's no ui, so open your browser's console to see the library in action. ## Live Preview ::: tip -You might need to disable your adblocker or Brave Shields to see the preview. +The Live Previews don't always work. If you're having trouble, try running the example locally OR using the [StackBlitz link](https://stackblitz.com/github/fedimint/fedimint-web-sdk/tree/main/examples/bare-js). + +Also, you might need to disable your adblocker or Brave Shields to see the preview. ::: +
+ [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/fedimint/fedimint-web-sdk/tree/main/examples/bare-js) ## Running the Example Locally -```bash -# from the root of the repo +Clone the repo + +```sh +git clone https://github.com/fedimint/fedimint-web-sdk.git +cd fedimint-web-sdk +``` -# install dependencies +Install the package manager with [Corepack](https://nodejs.org/api/corepack.html) & install dependencies. + +```sh +corepack enable pnpm i +``` + +Run the Example -# run the dev server +```sh pnpm run dev:bare ``` diff --git a/docs/examples/vite-react.md b/docs/examples/vite-react.md index b755d98..75fb56e 100644 --- a/docs/examples/vite-react.md +++ b/docs/examples/vite-react.md @@ -20,12 +20,22 @@ You might need to disable your adblocker or Brave Shields to see the preview. ## Running the Example Locally -```bash -# from the root of the repo +Clone the repo -# install dependencies +```sh +git clone https://github.com/fedimint/fedimint-web-sdk.git +cd fedimint-web-sdk +``` + +Install the package manager with [Corepack](https://nodejs.org/api/corepack.html) & install dependencies. + +```sh +corepack enable pnpm i +``` + +Run the Example -# run the dev server +```sh pnpm run dev:vite ``` diff --git a/packages/core-web/README.md b/packages/core-web/README.md index 46fff7a..e8706bb 100644 --- a/packages/core-web/README.md +++ b/packages/core-web/README.md @@ -1,80 +1,15 @@ # @fedimint/core-web -### THIS IS A WORK IN PROGRESS AND NOT READY FOR SERIOUS USE +### This is early software. Use with caution. Report Bugs. -This package provides a typescript interface for a fedimint client in the browser. +Check out the [Getting Started Guide](https://web.fedimint.org/core/getting-started.html) for more information. -It contains the wasm-pack output of the rust-based [fedimint client](https://github.com/fedimint/fedimint/tree/master/fedimint-client-wasm). +--- -## Key Features: +Also check out the examples for working code -- **WebAssembly-powered Client**: Exposes the robust, fault-tolerant fedimint-client (built in Rust) via WebAssembly. Lazy-Loads within a web worker for performance. -- **eCash Payments**: Includes support for joining federations, sending/receiving eCash, and managing balances. -- **Lightning Payments**: Ships with zero-setup Lightning Network payments. -- 🛠️ **State Management**: Handles the complex state management and storage challenges for browser wallets. -- 🤫 **Privacy Included**: Offers a privacy-centric wallet by default. -- ⚙️ **Framework Agnostic**: Designed as a "core" library compatible with vanilla JavaScript, laying the groundwork for future framework-specific packages. - -## Installation - -```bash -// npm or yarn or pnpm -pnpm add @fedimint/core-web -``` - -## Setup - -This package relies on the wasm binary to be bundled with your application. You will likely need to update your bundler's or framework's configuration to load the wasm file. Setup guides for popular frameworks are coming soon. - -See the `vite.config.ts` file in the [vite-core example](../../examples/vite-core/vite.config.ts) for an example of configuring wasm within a web-worker using Vite. - -## Usage - -```ts -import { FedimintWallet } from '@fedimint/core-web' - -// Create the Wallet client -const wallet = new FedimintWallet() - -// This should be called only once in the application -// lifecycle. It will automatically load your saved -// wallet state from previous sessions. -await wallet.open() - -// Joining a Federation - -// You can't join a federation -// if your wallet is already open -if (!wallet.isOpen()) { - // Check out [bitcoin mints](https://bitcoinmints.com/?tab=mints&showFedimint=true) for - // a list of federations with public invite codes. - const inviteCode = 'fed11qgqpw9thwvaz7t...' - - await wallet.joinFederation(inviteCode) - // After you've joined a federation, your federation state - // will be stored in the browser. Future calls to `open()` - // will automatically load your saved federation. -} - -// Get Wallet Balance (sync) -const balance = await wallet.balance.getBalance() - -// Subscribe to Balance Updates -const unsubscribe = wallet.balance.subscribeBalance((balance: number) => { - console.log('updated balance', balance) -}) -// Make sure to call `unsubscribe()` when you're done - -// Receive Ecash Payments -await wallet.mint.reissueNotes('A11qgqpw9thwvaz7t...') - -// Pay Lightning Invoice -await wallet.lightning.payInvoice('lnbc...') -``` - -### Check out the example - -- Vite + React: [`examples/vite-core`](../../examples/vite-core/README.md) [(demo)](https://fedimint.github.io/fedimint-web-sdk/) +- [Vite + React](https://web.fedimint.org/examples/vite-react) +- [Bare JS](https://web.fedimint.org/examples/bare-js) ### Resources diff --git a/packages/core-web/docs/ARCHITECTURE.md b/packages/core-web/docs/ARCHITECTURE.md index 64925e7..e944a7a 100644 --- a/packages/core-web/docs/ARCHITECTURE.md +++ b/packages/core-web/docs/ARCHITECTURE.md @@ -1,70 +1 @@ -# Core Web Architecture - -Docs Page: [Architecture](https://web.fedimint.org/core/architecture.html) - -## **Overview** - -The Fedimint Web SDK **Core Web** library is a modular and extensible JavaScript library designed to interact with the Fedimint client in a web browser. It provides a high-level API for developers to manage federated e-cash wallets, perform operations like minting and spending e-cash, and interact with the Lightning Network. The library is structured to promote maintainability, scalability, and ease of use, leveraging modern software development practices. - ---- - -## **Core Components** - -The architecture of the FedimintWallet library is built around a set of composable services and a communication layer that interacts with a Web Worker running WebAssembly (WASM) code. Below is an outline of the core components: - -### **1. FedimintWallet Class** - -- **Purpose**: Serves as the main entry point for the library. -- **Responsibilities**: - - Orchestrates the various services and the WorkerClient. - - Provides methods to initialize and configure the wallet. - - Exposes services to the user for performing operations. - -### **2. WorkerClient** - -- **Purpose**: Manages all communication between the main thread and the Web Worker. -- **Responsibilities**: - - Initializes and maintains the Web Worker instance. - - Handles message passing and response callbacks. - - Provides methods for sending RPC requests and handling streaming responses. -- **Features**: - - Abstracts worker creation to support both bundler and no-bundler environments. - - Implements request tracking using a unique request ID system. - -### **3. Services** - -The library is decomposed into several services, each encapsulating a specific domain of functionality. This modular design allows for easier maintenance and testing. - -- **FederationService**: Handles federation-related operations such as joining federations, retrieving configurations, and obtaining invite codes. - -- **MintService**: Manages operations related to minting and handling e-cash notes, including redeeming, reissuing, spending, and validating notes. - -- **LightningService**: Facilitates interactions with the Lightning Network, handling invoice creation/payment, gateway management, and event subscriptions. - -- **BalanceService**: Manages balance inquiries and subscriptions, allowing users to fetch current wallet balance and subscribe to changes. - -- **RecoveryService**: Manages recovery operations, including checking for pending recoveries, waiting for completion, and subscribing to progress updates. - -## **Utilities** - -The library includes a configurable logging utility to aid in development and debugging. - -- **Logger Utility**: - - A `Logger` class supports multiple log levels: `DEBUG`, `INFO`, `WARN`, `ERROR`, and `NONE`. - - Users can set the desired log level using the `setLogLevel` method. - -## **Summary Diagram** - -```mermaid -graph TD - FedimintWallet - FedimintWallet --> WorkerClient - FedimintWallet --> Services - FedimintWallet --> Logger - - Services --> MintService - Services --> LightningService - Services --> FederationService - Services --> BalanceService - Services --> RecoveryService -``` +[Architecture Docs](https://web.fedimint.org/core/architecture.html) diff --git a/packages/core-web/docs/TESTING.md b/packages/core-web/docs/TESTING.md index 9509ca7..3bef3d3 100644 --- a/packages/core-web/docs/TESTING.md +++ b/packages/core-web/docs/TESTING.md @@ -1,16 +1 @@ -# Testing - -We use [vitest](https://vitest.dev/) for testing library code. - -Configuring this properly was tricky. Since the library heavily relies on browser APIs like web workers & wasm, it doesn't really make sense to mock the browser APIs for unit tests. To trust our tests in this library, we really need them to run in a realistic browser environment. - -Vitest browser mode + playwright (provider) seems to satisfy all our needs. It spins up a real browser to run tests and can run headlessly for CI. I had to add one hack to make it work with the web-worker, but otherwise it seems to work well out of the box. - -This framework should be suitable for all the additional libraries we have planned (e.g. react). - -## Usage - -```bash -# in the root of the repo -pnpm run test -``` +[Testing Docs](https://web.fedimint.org/core/dev/testing.html)