diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..acf92ed4 --- /dev/null +++ b/.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 diff --git a/.gitignore b/.gitignore index 9c97bbd4..c5016b25 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ node_modules dist .env + +docs/ + diff --git a/README.md b/README.md index d58aecab..55d4863c 100644 --- a/README.md +++ b/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`). + diff --git a/package.json b/package.json index d2757de0..b812a670 100644 --- a/package.json +++ b/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", diff --git a/src/network/provider.ts b/src/network/provider.ts index e4bd365c..964a2c26 100644 --- a/src/network/provider.ts +++ b/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 diff --git a/typedoc.json b/typedoc.json index 5d777deb..c382bc74 100644 --- a/typedoc.json +++ b/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 + } }