1266/1234: Publish package to npm, deploy docs and update documentation

.github/workflows/build-and-test.yml

@@ -1,10 +1,11 @@
-name: Build and Test
+# This name appears on the "build" badge on README.
+name: build
 
 on:
   pull_request:
 
 jobs:
-  build-and-test:
+  build:
     runs-on: ubuntu-latest
 
     steps:

.github/workflows/deploy-docs.yml

@@ -0,0 +1,55 @@
+name: deploy-docs
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: 'pages'
+  cancel-in-progress: true
+
+jobs:
+  deploy-docs:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: latest
+          run_install: true
+
+      - name: Build docs
+        run: pnpm docs:build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/publish.yml

@@ -1,4 +1,4 @@
-name: Publish Package
+name: publish-package
 
 on:
   workflow_dispatch:
@@ -16,7 +16,7 @@ on:
           - prepatch
 
 jobs:
-  build:
+  publish-package:
     runs-on: ubuntu-latest
 
     permissions:
@@ -30,7 +30,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: '20.x'
-          registry-url: 'https://npm.pkg.github.com'
+          registry-url: 'https://registry.npmjs.org'
           # Defaults to the user or organization that owns the workflow file
           # scope: '@pufferfinance'
 
@@ -42,14 +42,18 @@ jobs:
 
       - name: Setup git
         run: |
-          git config --global user.name "github-actions[bot]"
-          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          git config user.name "${GITHUB_ACTOR}"
+          git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"
 
-      - name: Build
+      - name: Build package
         run: pnpm build
 
+        # This makes the API reference docs part of the release commit.
+      - name: Build docs
+        run: pnpm docs:build
+
       - name: Publish package
         run: pnpm release --increment ${{ inputs.increment }}
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.release-it.json

@@ -1,13 +1,14 @@
 {
   "git": {
-    "commitMessage": "[Github Actions] Release v${version}"
+    "commitMessage": "[Github Actions] Release v${version}",
+    "requireCleanWorkingDir": false
   },
   "github": {
     "release": true,
     "autoGenerate": true,
     "releaseName": "v${version}"
   },
   "hooks": {
-    "after:git:bump": "git add dist -f"
+    "after:npm:bump": "git add -A"
   }
 }

README.md

@@ -1,63 +1,81 @@
-<h1 align="center">Puffer SDK</h1>
-
-<p align="center">SDK for interacting with the puffer smart contracts<p>
+<div align="center">
+  <h1>Puffer SDK</h1>
+
+  <img alt="build" src="https://github.com/pufferfinance/puffer-sdk/actions/workflows/build-and-test.yml/badge.svg?branch=main" />
+  <img alt="license" src="https://img.shields.io/github/license/pufferfinance/puffer-sdk?color=limegreen" />
+  <img alt="npm downloads" src="https://img.shields.io/npm/dm/@pufferfinance/puffer-sdk?color=limegreen&logo=npm" />
+  <img alt="npm version" src="https://img.shields.io/npm/v/@pufferfinance/puffer-sdk?label=version&logo=npm" />
+  <!-- TODO: ADD COVERAGE BADGE -->
+
+  <p>SDK to seamlessly interact with puffer smart contracts<p>
+</div>
 
 ## Usage
 
-There are multiple ways to use the package.
+Install the package.
 
-- [GitHub (Recommended)](#github-recommended)
-- [GitHub Packages](#github-packages)
-- [Local](#local)
+```sh
+npm install @pufferfinance/puffer-sdk
+```
 
-### GitHub (Recommended)
+Example code to check pufETH balance.
 
-> Note: You must have access to the [PufferFinance](https://github.com/PufferFinance) GitHub organization and [SSH setup for GitHub](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) for this to work.
+```ts
+import {
+  PufferClientHelpers,
+  PufferClient,
+  Chain,
+} from '@pufferfinance/puffer-sdk';
 
-Install the dependency through GitHub URL.
+const walletClient = PufferClientHelpers.createWalletClient({
+  chain: Chain.Holesky,
+  provider: window.ethereum,
+});
+const pufferClient = new PufferClient(Chain.Holesky, walletClient);
+const [walletAddress] = await pufferClient.requestAddresses();
 
-```sh
-npm install github:pufferfinance/puffer-sdk
-pnpm install github:pufferfinance/puffer-sdk
-yarn add github:pufferfinance/puffer-sdk
+const balance = await pufferClient.vault.balanceOf(walletAddress);
 ```
 
-Add `#<tag>` (for example, `github:pufferfinance/puffer-sdk#1.0.0`) at the end to use a different published tag from GitHub (<https://github.com/PufferFinance/puffer-sdk/tags>).
+## Features
 
-### GitHub Packages
+- Interact with puffer smart contracts.
+- Deposit ETH to mint pufETH.
+- Deposit stETH to mint pufETH.
+- Check pufETH balance.
+- Get latest rate of pufETH compared to ETH.
+- and much more.
 
-The package is published privately to GitHub Packages. It can be installed by authenticating to GitHub Packages. Please check [GitHub guide for installing a private package](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#installing-a-package).
+## Documentation
 
-Use `@pufferfinance` as the organization name and `@pufferfinance/puffer-sdk` as the complete dependency name.
+Check the [documentation website](https://pufferfinance.github.io/puffer-sdk/) for detailed documentation and guides.
 
-### Local
+## Development
 
-Clone this repository and locally link this package so it can used by other projects.
+Install dependencies.
 
 ```sh
-pnpm link --global
+pnpm install
 ```
 
-In the project where you want to use this package as a dependency, run the following command.
+Start the package in watch mode.
 
 ```sh
-pnpm link --global @pufferfinance/puffer-sdk
+pnpm dev
 ```
 
-## Setup
-
-Install dependencies.
+Setup linking so the package can be linked to other projects locally.
 
 ```sh
-pnpm install
+pnpm link --global
 ```
 
-Start the package in watch mode.
+To link the package to a local project, run the following command.
 
 ```sh
-pnpm dev
+pnpm link --global @pufferfinance/puffer-sdk
 ```
 
 ## Release
 
-The release is automated using [release-it](https://github.com/release-it/release-it) and the [`publish.yml`](./.github/workflows/publish.yml) GitHub action. The action can be [dispatched manually](https://github.com/PufferFinance/puffer-sdk/actions/workflows/publish.yml) to make the release.
+The release is automated using [release-it](https://github.com/release-it/release-it) and the [publish.yml](./.github/workflows/publish.yml) GitHub action. The action can be [dispatched manually](https://github.com/PufferFinance/puffer-sdk/actions/workflows/publish.yml) to make the release.

docs/README.md

@@ -30,16 +30,4 @@ This command generates static content into the `build` directory and can be serv
 
 ### Deployment
 
-Using SSH:
-
-```sh
-USE_SSH=true pnpm docs:deploy
-```
-
-Not using SSH:
-
-```sh
-GIT_USER=<Your GitHub username> pnpm docs:deploy
-```
-
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+The deployment of the docs is automated with each release. See the [deploy-docs.yml](../.github/workflows/deploy-docs.yml) GitHub action.

docs/docusaurus.config.ts

@@ -8,10 +8,10 @@ const config: Config = {
   favicon: 'img/favicon.ico',
 
   // Set the production url of your site here
-  url: 'https://your-docusaurus-site.example.com',
+  url: 'https://pufferfinance.github.io',
   // Set the /<baseUrl>/ pathname under which your site is served
   // For GitHub pages deployment, it is often '/<projectName>/'
-  baseUrl: '/',
+  baseUrl: '/puffer-sdk/',
 
   // GitHub pages deployment config.
   // If you aren't using GitHub pages, you don't need these.
@@ -137,14 +137,21 @@ const config: Config = {
     },
   } satisfies Preset.ThemeConfig,
   plugins: [
-    '@easyops-cn/docusaurus-search-local',
+    [
+      '@easyops-cn/docusaurus-search-local',
+      {
+        // For docs-only mode.
+        docsRouteBasePath: '/',
+      },
+    ],
     // Plugin for generating API docs.
     [
       'docusaurus-plugin-typedoc',
       // https://typedoc-plugin-markdown.org/plugins/docusaurus/options
       // https://typedoc-plugin-markdown.org/docs/options
       {
-        entryPoints: '../lib/api',
+        // Consider all files in subdirectories of the `lib` directory.
+        entryPoints: '../lib/*/**',
         exclude: '**/*+(test|spec|index).ts',
         entryPointStrategy: 'expand',
         tsconfig: '../tsconfig.json',

docs/src/css/custom.css

@@ -6,25 +6,25 @@
 
 /* You can override the default Infima variables here. */
 :root {
-  --ifm-color-primary: #2e8555;
-  --ifm-color-primary-dark: #29784c;
-  --ifm-color-primary-darker: #277148;
-  --ifm-color-primary-darkest: #205d3b;
-  --ifm-color-primary-light: #33925d;
-  --ifm-color-primary-lighter: #359962;
-  --ifm-color-primary-lightest: #3cad6e;
+  --ifm-color-primary: #874fff;
+  --ifm-color-primary-dark: #7141d8;
+  --ifm-color-primary-darker: #5d36b3;
+  --ifm-color-primary-darkest: #492a8d;
+  --ifm-color-primary-light: #8f5ef8;
+  --ifm-color-primary-lighter: #a07af1;
+  --ifm-color-primary-lightest: #ac8dee;
   --ifm-code-font-size: 95%;
   --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
 }
 
 /* For readability concerns, you should choose a lighter palette in dark mode. */
 [data-theme='dark'] {
-  --ifm-color-primary: #25c2a0;
-  --ifm-color-primary-dark: #21af90;
-  --ifm-color-primary-darker: #1fa588;
-  --ifm-color-primary-darkest: #1a8870;
-  --ifm-color-primary-light: #29d5b0;
-  --ifm-color-primary-lighter: #32d8b4;
-  --ifm-color-primary-lightest: #4fddbf;
+  --ifm-color-primary: #41ff54;
+  --ifm-color-primary-dark: #3be74c;
+  --ifm-color-primary-darker: #31d141;
+  --ifm-color-primary-darkest: #28b136;
+  --ifm-color-primary-light: #66e973;
+  --ifm-color-primary-lighter: #78f084;
+  --ifm-color-primary-lightest: #88e692;
   --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
 }

package.json

@@ -21,8 +21,7 @@
     "dist"
   ],
   "publishConfig": {
-    "access": "restricted",
-    "registry": "https://npm.pkg.github.com"
+    "access": "public"
   },
   "scripts": {
     "build": "vite build",