docs: Add docs generation

.c8rc.json

@@ -1,8 +1,8 @@
 {
   "all": true,
   "include": ["src/**/*.ts"],
-  "exclude": ["src/**/*.d.ts", "src/**/*.test.ts", "src/types/*.ts", "src/tests/**/*.ts"],
+  "exclude": ["src/**/*.d.ts", "src/**/*.test.ts", "src/types/*.ts", "src/tests/**/*.ts", "docs/**/*.md"],
   "reporter": ["text", "lcov"],
   "extension": [".ts"],
   "report-dir": "./coverage"
-} 
+}

.github/ci-scripts/update-sdk-docs.cjs

@@ -0,0 +1,194 @@
+const fs = require('fs/promises')
+const path = require('path')
+const simpleGit = require('simple-git')
+const { execSync } = require('child_process')
+
+/**
+ * Recursively gets all files from a directory
+ */
+async function getFilesRecursively(dir) {
+  const items = await fs.readdir(dir, { withFileTypes: true })
+  const files = await Promise.all(
+    items.map(async (item) => {
+      const filePath = path.join(dir, item.name)
+      return item.isDirectory() ? getFilesRecursively(filePath) : filePath
+    })
+  )
+  return files.flat()
+}
+
+/**
+ * Cleans generated documentation folders: classes and type-aliases
+ */
+async function cleanGeneratedDocs(targetDir) {
+  const foldersToClean = ['classes', 'type-aliases']
+  for (const folder of foldersToClean) {
+    const folderPath = path.join(targetDir, folder)
+    try {
+      await fs.rm(folderPath, { recursive: true, force: true })
+      console.log(`✨ Cleared existing ${folder} folder`)
+    } catch (error) {
+      if (error.code !== 'ENOENT') {
+        console.error(`❌ Error clearing ${folder} folder:`, error)
+      }
+    }
+  }
+}
+
+/**
+ * Copies documentation files while maintaining structure
+ */
+async function copyDocs(sourceDir, targetDir) {
+  try {
+    await fs.mkdir(targetDir, { recursive: true })
+    await cleanGeneratedDocs(targetDir)
+
+    const docFiles = await getFilesRecursively(sourceDir)
+    for (const file of docFiles) {
+      const relativePath = path.relative(sourceDir, file)
+      if (path.basename(file) === 'README.md') continue
+
+      const targetPath = path.join(targetDir, relativePath)
+      await fs.mkdir(path.dirname(targetPath), { recursive: true })
+      await fs.copyFile(file, targetPath)
+      console.log(`📄 Copied: ${relativePath}`)
+    }
+  } catch (error) {
+    console.error('❌ Error copying docs:', error)
+    throw error
+  }
+}
+
+/**
+ * Processes and updates the index.html.md file
+ */
+async function updateIndexHtmlMd(docsDir, indexHtmlMdPath) {
+  try {
+    const content = await fs.readFile(indexHtmlMdPath, 'utf8')
+    const docFiles = await getFilesRecursively(docsDir)
+
+    // Transform and validate files
+    const actualFiles = new Set(
+      docFiles.map((file) => path.relative(docsDir, file).replace(/\/_/g, '/').replace(/^_/, '').replace(/\.md$/, ''))
+    )
+
+    // Extract existing includes
+    const existingIncludesMatch = content.match(/^includes:\n((?:  - .*\n)*)/m)
+    const existingIncludes = existingIncludesMatch
+      ? existingIncludesMatch[1]
+          .split('\n')
+          .map((line) => line.replace('  - ', ''))
+          .filter(Boolean)
+      : []
+
+    // Process new includes
+    const newIncludes = docFiles
+      .filter((file) => file.endsWith('.md'))
+      .filter((file) => !file.includes('README.md'))
+      .map((file) => {
+        const relativePath = path.relative(docsDir, file)
+        return relativePath.replace(/\/_/g, '/').replace(/^_/, '').replace(/\.md$/, '')
+      })
+
+    // Combine and validate includes
+    const allIncludes = [
+      ...existingIncludes.filter((inc) => !inc.startsWith('classes/') && !inc.startsWith('type-aliases/')),
+      ...newIncludes,
+    ]
+      .filter((value, index, self) => self.indexOf(value) === index)
+      .filter((include) => {
+        if (include.startsWith('classes/') || include.startsWith('type-aliases/')) {
+          const exists = actualFiles.has(include)
+          if (!exists) console.log(`⚠️  Warning: File not found for include: ${include}`)
+          return exists
+        }
+        return true
+      })
+
+    // Update content
+    const [frontmatterStart, ...rest] = content.split(/^includes:/m)
+    const remainingContent = rest.join('includes:').split('---')
+    const postFrontmatter = remainingContent.slice(1).join('---')
+
+    const updatedContent = `${frontmatterStart}includes:
+${allIncludes.map((file) => `  - ${file}`).join('\n')}
+search: true
+---${postFrontmatter}`
+
+    await fs.writeFile(indexHtmlMdPath, updatedContent)
+
+    console.log(`✅ Total includes: ${allIncludes.length}`)
+  } catch (error) {
+    console.error('❌ Error updating index.html.md:', error)
+    throw error
+  }
+}
+
+/**
+ * Creates a PR in the sdk-docs repository
+ */
+async function createPullRequest(git, branchName) {
+  const prTitle = '[sdk:ci:bot] Update SDK Documentation'
+  const prBody =
+    '[sdk:ci:bot] Automated PR to update SDK documentation: [Actions](https://github.com/centrifuge/sdk/actions/workflows/update-docs.yml)'
+
+  const prCommand = `gh pr create \
+    --title "${prTitle}" \
+    --body "${prBody}" \
+    --base main \
+    --head ${branchName} \
+    --repo "centrifuge/sdk-docs"`
+
+  execSync(prCommand, {
+    stdio: 'inherit',
+    env: { ...process.env, GH_TOKEN: process.env.PAT_TOKEN },
+  })
+}
+
+async function hasChanges(git) {
+  try {
+    await git.fetch('origin', 'main')
+
+    // Get the diff between current state and main branch
+    const diff = await git.diff(['origin/main'])
+
+    return diff.length > 0
+  } catch (error) {
+    console.error('❌ Error checking for changes:', error)
+    throw error
+  }
+}
+
+async function main() {
+  try {
+    const git = simpleGit()
+    const repoUrl = `https://${process.env.PAT_TOKEN}@github.com/centrifuge/sdk-docs.git`
+
+    await git.clone(repoUrl)
+    await git
+      .cwd('./sdk-docs')
+      .addConfig('user.name', 'github-actions[bot]')
+      .addConfig('user.email', 'github-actions[bot]@users.noreply.github.com')
+
+    await copyDocs('./docs', './sdk-docs/source/includes')
+    await updateIndexHtmlMd('./docs', './sdk-docs/source/index.html.md')
+
+    if (await hasChanges(git)) {
+      const branchName = `docs-update-${new Date().toISOString().slice(0, 19).replace(/[:-]/g, '').replace(' ', '-')}`
+      await git.checkoutLocalBranch(branchName)
+      await git.add('.').commit('Update SDK documentation')
+      await git.push('origin', branchName)
+
+      await createPullRequest(git, branchName)
+      console.log('✅ Successfully created PR with documentation updates')
+    } else {
+      console.log('ℹ️  No documentation changes detected')
+    }
+    process.exit(0)
+  } catch (error) {
+    console.error('❌ Failed to process docs:', error)
+    process.exit(1)
+  }
+}
+
+main()

.github/workflows/update-docs.yml

@@ -0,0 +1,43 @@
+# This workflow will update the docs in the sdk-docs repo
+
+name: Update Docs
+
+on:
+  push:
+    branches:
+      - generate-docs
+
+jobs:
+  update-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Setup Yarn
+        run: |
+          corepack enable
+          corepack prepare [email protected] --activate
+
+      - name: Install dependencies
+        run: yarn install
+
+      - name: Run gen:docs command
+        run: yarn gen:docs
+
+      - name: Install dependencies
+        run: yarn add simple-git
+
+      - name: Setup GitHub CLI
+        run: |
+          gh auth login --with-token <<< "${{ secrets.GITHUB_TOKEN }}"
+
+      - name: Update docs
+        env:
+          PAT_TOKEN: ${{ secrets.PAT_TOKEN }}
+        run: node ./.github/ci-scripts/update-sdk-docs.cjs

README.md

@@ -182,6 +182,10 @@ yarn test:single <path-to-file>
 yarn test:simple:single <path-to-file> # without setup file, faster and without tenderly setup
 ```
 
+## User Docs
+
+User docs are written and maintained in the [sdk-docs](https://github.com/centrifuge/sdk-docs) repository. On push to the `main` branch, a GitHub Action will run and update the docs with the auto-generated docs from this repository using ([typedoc](https://typedoc.org/)).
+
 ### PR Naming Convention
 
 PR naming should follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centrifuge/sdk",
-  "version": "0.0.0-alpha.5",
+  "version": "0.0.0-alpha.6",
   "description": "",
   "homepage": "https://github.com/centrifuge/sdk/tree/main#readme",
   "author": "",
@@ -33,7 +33,8 @@
     "test:simple:single": "mocha --loader=ts-node/esm --exit --timeout 60000",
     "test:single": "mocha --loader=ts-node/esm --require $(pwd)/src/tests/setup.ts --exit --timeout 60000",
     "test:ci": "yarn test --reporter mocha-multi-reporters --reporter-options configFile=mocha-reporter-config.json",
-    "test:coverage": "c8 yarn test:ci"
+    "test:coverage": "c8 yarn test:ci",
+    "gen:docs": "typedoc"
   },
   "dependencies": {
     "decimal.js-light": "^2.5.1",
@@ -61,6 +62,8 @@
     "sinon-chai": "^4.0.0",
     "source-map-support": "^0.5.21",
     "ts-node": "^10.9.2",
+    "typedoc": "^0.27.6",
+    "typedoc-plugin-markdown": "^4.4.1",
     "typescript": "~5.6.3",
     "typescript-eslint": "^8.8.1",
     "viem": "^2.21.25"

src/Centrifuge.ts

@@ -24,7 +24,6 @@ import {
   type Abi,
   type Account as AccountType,
   type Chain,
-  type PublicClient,
   type WalletClient,
   type WatchEventOnLogsParameter,
 } from 'viem'
@@ -34,31 +33,14 @@ import { chains } from './config/chains.js'
 import type { CurrencyMetadata } from './config/lp.js'
 import { PERMIT_TYPEHASH } from './constants.js'
 import { Pool } from './Pool.js'
-import type { HexString } from './types/index.js'
+import type { Client, DerivedConfig, EnvConfig, HexString, UserProvidedConfig } from './types/index.js'
 import type { CentrifugeQueryOptions, Query } from './types/query.js'
 import type { OperationStatus, Signer, Transaction, TransactionCallbackParams } from './types/transaction.js'
 import { Currency } from './utils/BigInt.js'
 import { hashKey } from './utils/query.js'
 import { makeThenable, repeatOnEvents, shareReplayWithDelayedReset } from './utils/rx.js'
 import { doTransaction, isLocalAccount } from './utils/transaction.js'
 
-export type Config = {
-  environment: 'mainnet' | 'demo' | 'dev'
-  rpcUrls?: Record<number | string, string>
-  indexerUrl: string
-  ipfsUrl: string
-}
-
-export type UserProvidedConfig = Partial<Config>
-type EnvConfig = {
-  indexerUrl: string
-  alchemyKey: string
-  infuraKey: string
-  defaultChain: number
-  ipfsUrl: string
-}
-type DerivedConfig = Config & EnvConfig
-
 const envConfig = {
   mainnet: {
     indexerUrl: 'https://subql.embrio.tech/',
@@ -93,7 +75,7 @@ export class Centrifuge {
     return this.#config
   }
 
-  #clients = new Map<number, PublicClient<any, Chain>>()
+  #clients = new Map<number, Client>()
   getClient(chainId?: number) {
     return this.#clients.get(chainId ?? this.config.defaultChain)
   }
@@ -134,8 +116,8 @@ export class Centrifuge {
       })
   }
 
-  pool(id: string, metadataHash?: string) {
-    return this._query(null, () => of(new Pool(this, id, metadataHash)))
+  pool(id: string | number, metadataHash?: string) {
+    return this._query(null, () => of(new Pool(this, String(id), metadataHash)))
   }
 
   account(address: string, chainId?: number) {
@@ -535,6 +517,7 @@ export class Centrifuge {
    * // { type: 'SigningTransaction', title: 'Invest' }
    * // { type: 'TransactionPending', title: 'Invest', hash: '0x123...abc' }
    * // { type: 'TransactionConfirmed', title: 'Invest', hash: '0x123...abc', receipt: { ... } }
+   * ```
    *
    * @internal
    */

src/Entity.ts

@@ -4,9 +4,12 @@ import type { CentrifugeQueryOptions } from './types/query.js'
 
 export class Entity {
   #baseKeys: (string | number)[]
+  /** @internal */
   _transact: Centrifuge['_transact']
+  /** @internal */
   _transactSequence: Centrifuge['_transactSequence']
   constructor(
+    /** @internal */
     protected _root: Centrifuge,
     queryKeys: (string | number)[]
   ) {
@@ -15,6 +18,7 @@ export class Entity {
     this._transactSequence = this._root._transactSequence.bind(this._root)
   }
 
+  /** @internal */
   protected _query<T>(
     keys: (string | number | undefined)[] | null,
     observableCallback: () => Observable<T>,

src/Pool.ts

@@ -6,6 +6,7 @@ import { Reports } from './Reports/index.js'
 import { PoolMetadata } from './types/poolMetadata.js'
 
 export class Pool extends Entity {
+  /** @internal */
   constructor(
     _root: Centrifuge,
     public id: string,
@@ -19,7 +20,9 @@ export class Pool extends Entity {
   }
 
   metadata() {
-    return this.metadataHash ? this._root._queryIPFS<PoolMetadata>(this.metadataHash) : of(undefined)
+    return this.metadataHash
+      ? this._root._queryIPFS<PoolMetadata>(this.metadataHash)
+      : this._query(null, () => of(null))
   }
 
   trancheIds() {