feat(docs): TypeDoc API docs + GitHub Pages deploy on release tags (#122)

.github/workflows/docs.yml

@@ -0,0 +1,69 @@
+name: Docs
+
+on:
+  push:
+    tags:
+      - 'v*'
+      - 'V*'
+  workflow_dispatch:
+    inputs:
+      deploy:
+        description: 'Deploy built docs to GitHub Pages'
+        required: false
+        default: true
+        type: boolean
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages-docs
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build TypeDoc
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate API documentation
+        run: npm run docs
+
+      - name: Verify docs output
+        run: |
+          test -f docs/index.html
+          test -d docs/assets
+          echo "TypeDoc output OK:"
+          ls -la docs | head -20
+
+      - name: Upload Pages artifact
+        if: github.event_name == 'push' || inputs.deploy != false
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs
+
+  deploy:
+    name: Deploy GitHub Pages
+    needs: build
+    if: github.event_name == 'push' || inputs.deploy != false
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,3 +1,6 @@
 node_modules
 dist
 .env
+
+docs/
+

README.md

@@ -482,3 +482,16 @@ For security policies and vulnerability reporting, please refer to [SECURITY.md]
 ## 📄 License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## API Documentation
+
+HTML API docs are generated from TypeScript sources with [TypeDoc](https://typedoc.org/):
+
+```bash
+npm run docs
+# output ? ./docs (open docs/index.html)
+```
+
+On every release tag (`v*`), GitHub Actions rebuilds TypeDoc and deploys to **GitHub Pages**
+(see `.github/workflows/docs.yml`).
+

package.json

@@ -62,7 +62,8 @@
     "typecheck": "tsc --skipLibCheck -p tsconfig.json --noEmit",
     "test": "vitest run",
     "bench": "node bench/signer.bench.mjs",
-    "docs": "typedoc"
+    "docs": "typedoc --options typedoc.json",
+    "docs:check": "typedoc --options typedoc.json"
   },
   "keywords": [
     "whitechain",
@@ -74,7 +75,6 @@
   "dependencies": {
     "abitype": "^1.3.0",
     "@noble/curves": "^1.9.0",
-    "abitype": "^1.3.0",
     "chalk": "^6.0.0",
     "commander": "^15.0.0",
     "prompts": "^2.4.2",

src/network/provider.ts

@@ -1,7 +1,6 @@
 import { http, type Transport } from 'viem'
 import type { WhiteChainConfig, WhiteChainAddresses } from '../types.js'
 import type { NetworkProfile } from '../config/networks.js'
-import { ValidationError } from '../errors/index.js'
 import { TimeoutError, ValidationError } from '../errors/index.js'
 
 type RateLimitListener = () => void
@@ -15,6 +14,9 @@ export interface WaitForTransactionOptions {
   timeoutMs?: number
 }
 
+/**
+ * Options for the HTTP {@link Provider}, including 429 retry behaviour.
+ */
 export interface ProviderOptions {
   /** Maximum number of retry attempts on HTTP 429 rate limit responses (default: 3). */
   maxRetries?: number
@@ -24,105 +26,9 @@ export interface ProviderOptions {
   fetchFn?: typeof fetch
 }
 
-export interface ProviderOptions {
-  /** Maximum number of retry attempts on HTTP 429 rate limit responses (default: 3). */
-  maxRetries?: number
-  /** Base delay in milliseconds for exponential backoff calculations (default: 100). */
-  baseDelayMs?: number
-  /** Custom fetch implementation for network requests or testing. */
-  fetchFn?: typeof fetch
-}
-
-export interface ProviderOptions {
-  /** Maximum number of retry attempts on HTTP 429 rate limit responses (default: 3). */
-  maxRetries?: number
-  /** Base delay in milliseconds for exponential backoff calculations (default: 100). */
-  baseDelayMs?: number
-  /** Custom fetch implementation for network requests or testing. */
-  fetchFn?: typeof fetch
-}
-
-export interface ProviderOptions {
-  /** Maximum number of retry attempts on HTTP 429 rate limit responses (default: 3). */
-  maxRetries?: number
-  /** Base delay in milliseconds for exponential backoff calculations (default: 100). */
-  baseDelayMs?: number
-  /** Custom fetch implementation for network requests or testing. */
-  fetchFn?: typeof fetch
-}
-
-export interface ProviderOptions {
-  /** Maximum number of retry attempts on HTTP 429 rate limit responses (default: 3). */
-  maxRetries?: number
-  /** Base delay in milliseconds for exponential backoff calculations (default: 100). */
-  baseDelayMs?: number
-  /** Custom fetch implementation for network requests or testing. */
-  fetchFn?: typeof fetch
-}
-
-export interface ProviderOptions {
-  /** Maximum number of retry attempts on HTTP 429 rate limit responses (default: 3). */
-  maxRetries?: number
-  /** Base delay in milliseconds for exponential backoff calculations (default: 100). */
-  baseDelayMs?: number
-  /** Custom fetch implementation for network requests or testing. */
-  fetchFn?: typeof fetch
-}
-
-export interface ProviderOptions {
-  /** Maximum number of retry attempts on HTTP 429 rate limit responses (default: 3). */
-  maxRetries?: number
-  /** Base delay in milliseconds for exponential backoff calculations (default: 100). */
-  baseDelayMs?: number
-  /** Custom fetch implementation for network requests or testing. */
-  fetchFn?: typeof fetch
-}
-
-export interface ProviderOptions {
-  /** Maximum number of retry attempts on HTTP 429 rate limit responses (default: 3). */
-  maxRetries?: number
-  /** Base delay in milliseconds for exponential backoff calculations (default: 100). */
-  baseDelayMs?: number
-  /** Custom fetch implementation for network requests or testing. */
-  fetchFn?: typeof fetch
-}
-
-export interface ProviderOptions {
-  /** Maximum number of retry attempts on HTTP 429 rate limit responses (default: 3). */
-  maxRetries?: number
-  /** Base delay in milliseconds for exponential backoff calculations (default: 100). */
-  baseDelayMs?: number
-  /** Custom fetch implementation for network requests or testing. */
-  fetchFn?: typeof fetch
-}
-
-export interface ProviderOptions {
-  /** Maximum number of retry attempts on HTTP 429 rate limit responses (default: 3). */
-  maxRetries?: number
-  /** Base delay in milliseconds for exponential backoff calculations (default: 100). */
-  baseDelayMs?: number
-  /** Custom fetch implementation for network requests or testing. */
-  fetchFn?: typeof fetch
-}
-
-export interface ProviderOptions {
-  /** Maximum number of retry attempts on HTTP 429 rate limit responses (default: 3). */
-  maxRetries?: number
-  /** Base delay in milliseconds for exponential backoff calculations (default: 100). */
-  baseDelayMs?: number
-  /** Custom fetch implementation for network requests or testing. */
-  fetchFn?: typeof fetch
-}
-
-export interface ProviderOptions {
-  /** Maximum number of retry attempts on HTTP 429 rate limit responses (default: 3). */
-  maxRetries?: number
-  /** Base delay in milliseconds for exponential backoff calculations (default: 100). */
-  baseDelayMs?: number
-  /** Custom fetch implementation for network requests or testing. */
-  fetchFn?: typeof fetch
-}
-
+/**
+ * JSON-RPC HTTP provider with rate-limit retry and transaction receipt polling.
+ */
 export class Provider {
   public readonly network: NetworkProfile
   public readonly chainId: number

typedoc.json

@@ -1,7 +1,45 @@
 {
   "$schema": "https://typedoc.org/schema.json",
+  "name": "WhiteChain SDK",
   "entryPoints": ["src/index.ts"],
   "out": "docs",
   "tsconfig": "tsconfig.json",
-  "skipErrorChecking": true
+  "readme": "README.md",
+  "includeVersion": true,
+  "skipErrorChecking": true,
+  "excludePrivate": true,
+  "excludeProtected": true,
+  "excludeInternal": true,
+  "excludeExternals": true,
+  "excludeNotDocumented": false,
+  "githubPages": true,
+  "navigationLinks": {
+    "GitHub": "https://github.com/Adamantine-guild/whitechain-sdk",
+    "npm": "https://www.npmjs.com/package/whitechain-sdk"
+  },
+  "categorizeByGroup": true,
+  "searchInComments": true,
+  "treatWarningsAsErrors": false,
+  "validation": {
+    "notDocumented": false,
+    "notExported": false,
+    "invalidLink": false,
+    "rewrittenLink": false,
+    "unusedMergeModuleWith": false
+  },
+  "externalSymbolLinkMappings": {
+    "viem": {
+      "*": "https://viem.sh/"
+    },
+    "typescript": {
+      "*": "https://www.typescriptlang.org/docs/handbook/"
+    }
+  },
+  "commentStyle": "all",
+  "jsDocCompatibility": {
+    "exampleTag": true,
+    "defaultTag": true,
+    "inheritDocTag": true,
+    "ignoreUnescapedBraces": true
+  }
 }