Clean up Types, Add docs (#102)

* chore: improve docs & replace typedoc comments with links to docs page

* docs: add redeemEcash

* chore: improve lightning service return types

* chore: refactor to avoid explicit return types for functions

* docs: add spendNotes

* docs: add parseNotes

* docs: add FederationService docs

* chore: removed redundant initialize docs page

docs/.vitepress/sidebar.ts

@@ -50,10 +50,6 @@ const FedimintWalletSidebar = [
         text: 'joinFederation()',
         link: 'joinFederation',
       },
-      // {
-      //   text: 'initialize()',
-      //   link: 'initialize',
-      // },
       {
         text: 'isOpen()',
         link: 'isOpen',
@@ -94,12 +90,20 @@ const FedimintWalletSidebar = [
       {
         text: 'MintService',
         base: '/core/FedimintWallet/MintService/',
-        items: [{ text: 'Docs TODO' }],
+        items: [
+          { text: 'redeemEcash()', link: 'redeemEcash' },
+          { text: 'spendNotes()', link: 'spendNotes' },
+          { text: 'parseNotes()', link: 'parseNotes' },
+        ],
       },
       {
         text: 'FederationService',
         base: '/core/FedimintWallet/FederationService/',
-        items: [{ text: 'Docs TODO' }],
+        items: [
+          { text: 'getConfig()', link: 'getConfig' },
+          { text: 'getFederationId()', link: 'getFederationId' },
+          { text: 'getInviteCode()', link: 'getInviteCode' },
+        ],
       },
       {
         text: 'RecoveryService',

docs/core/FedimintWallet/BalanceService/getBalance.md

@@ -2,7 +2,7 @@
 
 ### `balance.getBalance()`
 
-Get the current balance of the wallet.
+Get the current balance of the wallet in milli-satoshis (MSats).
 
 ```ts twoslash
 // @esModuleInterop

docs/core/FedimintWallet/FederationService/getConfig.md

@@ -0,0 +1,15 @@
+# Redeem Ecash
+
+### `federation.getConfig()`
+
+Access configuration details about a connected federation.
+
+```ts twoslash
+// @esModuleInterop
+import { FedimintWallet } from '@fedimint/core-web'
+
+const wallet = new FedimintWallet()
+wallet.open()
+
+const config = await wallet.federation.getConfig() // [!code focus]
+```

docs/core/FedimintWallet/FederationService/getFederationId.md

@@ -0,0 +1,15 @@
+# Redeem Ecash
+
+### `federation.getFederationId()`
+
+Access the `federationId` of the connected Federation.
+
+```ts twoslash
+// @esModuleInterop
+import { FedimintWallet } from '@fedimint/core-web'
+
+const wallet = new FedimintWallet()
+wallet.open()
+
+const config = await wallet.federation.getFederationId() // [!code focus]
+```

docs/core/FedimintWallet/FederationService/getInviteCode.md

@@ -0,0 +1,17 @@
+# Redeem Ecash
+
+### `federation.getInviteCode()`
+
+Access the invite code for the connected federation.
+
+```ts twoslash
+// @esModuleInterop
+import { FedimintWallet } from '@fedimint/core-web'
+
+const wallet = new FedimintWallet()
+wallet.open()
+
+const peerId = 0 // Index of the guardian to ask for the invite code // [!code focus]
+
+const inviteCode = await wallet.federation.getInviteCode(peerId) // [!code focus]
+```

docs/core/FedimintWallet/LightningService/createInvoice.md

@@ -4,7 +4,9 @@
 
 Create a Lightning Invoice for a given amount. Returns a `CreateBolt11Response` object containing details about the created invoice.
 
-You can use `subscribeLnReceive` to track the payment status and `waitForReceive` to wait for the payment to be received.
+You can use `subscribeLnReceive` to track the invoice status.
+
+`waitForReceive` returns a `Promise` that resolves when the invoice succeeds or `timeoutMs` is reached.
 
 ```ts twoslash
 // @esModuleInterop

docs/core/FedimintWallet/LightningService/payInvoice.md

@@ -2,7 +2,7 @@
 
 ### `lightning.payInvoiceSync(invoice: string)`
 
-Helper function to pay an invoice and resolve when the payment is confirmed or fails.
+Attempts to pay an invoice. Returns a `Promise` that resolves when the payment succeeds or fails / times out.
 
 ```ts twoslash
 // @esModuleInterop
@@ -23,9 +23,9 @@ if (result.success) {
 
 ### `lightning.payInvoice(invoice: string)`
 
-Attempt to pay a lightning invoice. Returns an `OutgoingLightningPayment` object containing details about the in-flight payment.
+Attempts to pay a lightning invoice. Returns an `OutgoingLightningPayment` object containing details about the in-flight payment.
 
-You can use `subscribeLnPay` to track the payment status and `waitForPay` to wait for the payment to be confirmed or fail.
+You can use `subscribeLnPay` to track the payment status. `waitForPay` returns a `Promise` that resolves when the payment succeeds or fails / times out.
 
 ```ts twoslash
 // @esModuleInterop

docs/core/FedimintWallet/MintService/parseNotes.md

@@ -0,0 +1,21 @@
+# Spend Ecash
+
+### `mint.parseNotes(oobNotes: string)`
+
+Parses an ecash note string without redeeming it. Use [`redeemEcash()`](./redeemEcash) to redeem the notes.
+
+```ts twoslash
+// @esModuleInterop
+import { FedimintWallet } from '@fedimint/core-web'
+
+const wallet = new FedimintWallet()
+wallet.open()
+
+const longEcashNoteString = '01A...'
+
+const valueMsats = await wallet.mint.parseNotes(longEcashNoteString) // [!code focus]
+
+// later...
+
+await wallet.mint.redeemEcash(longEcashNoteString)
+```

docs/core/FedimintWallet/MintService/redeemEcash.md

@@ -0,0 +1,19 @@
+# Redeem Ecash
+
+### `mint.redeemEcash(notes: string)`
+
+Redeem a set of ecash notes.
+
+```ts twoslash
+// @esModuleInterop
+import { FedimintWallet } from '@fedimint/core-web'
+
+const wallet = new FedimintWallet()
+wallet.open()
+
+try {
+  await wallet.mint.redeemEcash('01...') // [!code focus]
+} catch (error) {
+  console.error('Failed to redeem ecash', error)
+}
+```

docs/core/FedimintWallet/MintService/spendNotes.md

@@ -0,0 +1,18 @@
+# Spend Ecash
+
+### `mint.spendNotes(amountMsats: number)`
+
+Generates ecash notes for spending.
+
+```ts twoslash
+// @esModuleInterop
+import { FedimintWallet } from '@fedimint/core-web'
+
+const wallet = new FedimintWallet()
+wallet.open()
+
+const amountMsats = 10_000 // [!code focus]
+const result = await wallet.mint.spendNotes(amountMsats) // [!code focus]
+
+console.log(result.notes) // ecash notes
+```

packages/core-web/src/services/BalanceService.ts

@@ -8,43 +8,22 @@ import { WorkerClient } from '../worker'
 export class BalanceService {
   constructor(private client: WorkerClient) {}
 
-  /**
-   * Get the balance of the current wallet in milli-satoshis (MSats)
-   *
-   * @example
-   * ```ts
-   * const balance = await wallet.balance.getBalance()
-   * ```
-   */
-  async getBalance(): Promise<number> {
-    return await this.client.rpcSingle('', 'get_balance', {})
+  /** https://web.fedimint.org/core/FedimintWallet/BalanceService/getBalance */
+  async getBalance() {
+    return await this.client.rpcSingle<number>('', 'get_balance', {})
   }
 
-  /**
-   * Subscribe to the balance of the current wallet in milli-satoshis (MSats)
-   *
-   * @example
-   * ```ts
-   * const unsubscribe = wallet.balance.subscribeBalance((balance) => {
-   *  console.log(balance)
-   * })
-   *
-   * // ...Cleanup Later
-   * unsubscribe()
-   * ```
-   */
+  /** https://web.fedimint.org/core/FedimintWallet/BalanceService/subscribeBalance */
   subscribeBalance(
     onSuccess: (balanceMsats: number) => void = () => {},
     onError: (error: string) => void = () => {},
   ) {
-    const unsubscribe = this.client.rpcStream<string>(
+    return this.client.rpcStream<string>(
       '',
       'subscribe_balance_changes',
       {},
       (res) => onSuccess(parseInt(res)),
       onError,
     )
-
-    return unsubscribe
   }
 }

packages/core-web/src/services/FederationService.ts

@@ -4,19 +4,21 @@ import { WorkerClient } from '../worker'
 export class FederationService {
   constructor(private client: WorkerClient) {}
 
-  async getConfig(): Promise<JSONValue> {
+  async getConfig() {
     return await this.client.rpcSingle('', 'get_config', {})
   }
 
-  async getFederationId(): Promise<string> {
-    return await this.client.rpcSingle('', 'get_federation_id', {})
+  async getFederationId() {
+    return await this.client.rpcSingle<string>('', 'get_federation_id', {})
   }
 
-  async getInviteCode(peer: number): Promise<string | null> {
-    return await this.client.rpcSingle('', 'get_invite_code', { peer })
+  async getInviteCode(peer: number = 0) {
+    return await this.client.rpcSingle<string | null>('', 'get_invite_code', {
+      peer,
+    })
   }
 
-  async listOperations(): Promise<JSONValue[]> {
-    return await this.client.rpcSingle('', 'list_operations', {})
+  async listOperations() {
+    return await this.client.rpcSingle<JSONValue[]>('', 'list_operations', {})
   }
 }