Add script to check documentation links

.husky/pre-commit

@@ -1,3 +1,3 @@
 sh ./scripts/pre-push.sh
-
-npm run lint
+pnpm run check:docLinks
+pnpm run lint

documentation/03-quick-start/_category_.json

@@ -0,0 +1,3 @@
+{
+  "label": "Quick Start"
+}

package.json

@@ -20,6 +20,7 @@
     "graphql": "graphql-codegen && tsx ./scripts/generateGraphqlExports/index.ts",
     "rollup": "rollup --config rollup.config.js",
     "check:version": "node ./scripts/checkVersion.js",
+    "check:docLinks": "node ./scripts/checkDocLinks.js",
     "lint": "eslint ./src --ext .ts,.tsx,.js,.jsx",
     "release": "pnpm build && pnpm publish --tag=latest",
     "sync:docs": "tsx ./scripts/syncDocs/index.ts"

scripts/checkDocLinks.js

@@ -0,0 +1,144 @@
+import path from 'path'
+import https from 'https'
+import { fileURLToPath } from 'url'
+import { execSync } from 'child_process'
+
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+// eslint-disable-next-line no-restricted-syntax
+const docsUrl = 'https://docs.stakewise.io'
+
+const srcDir = path.resolve(__dirname, '../src')
+
+const fetchSitemap = () => {
+  const sitemapUrl = `${docsUrl}/sitemap.xml`
+
+  return new Promise((resolve, reject) => {
+    https
+      .get(sitemapUrl, (res) => {
+        let data = ''
+
+        res.on('data', (chunk) => data += chunk)
+        res.on('end', () => {
+          const matches = data.match(/<loc>([^<]+)/g) || []
+
+          const urls = matches.map((match) => {
+            return match
+              .replace('<loc>', '')
+              .replace(/\/$/, '')
+              .toLowerCase()
+          })
+
+          resolve(urls)
+        })
+      })
+      .on('error', reject)
+  })
+}
+
+const getSdkApiSlugs = () => {
+  try {
+    const output = execSync(
+      `grep -r "^slug:" "${srcDir}" --include="*.md"`,
+      { encoding: 'utf-8' }
+    )
+
+    const slugs = output
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => line.replace(/.*slug:\s*/, '').trim().replace(/\/$/, '').toLowerCase())
+
+    const brokenSlugs = slugs.filter((slug) => !slug.startsWith('/'))
+
+    if (brokenSlugs.length) {
+      console.log('🚫 Slugs must start with /:')
+      brokenSlugs.forEach((slug) => console.log(`${slug}`))
+      process.exit(1)
+    }
+
+    return slugs.filter((slug) => slug.startsWith('/sdk/api/'))
+  }
+  catch {
+    return []
+  }
+}
+
+const getUrls = () => {
+  const rootDir = path.resolve(__dirname, '..')
+
+  try {
+    const output = execSync(
+      `grep -roh "https://docs\\.stakewise\\.io/[^\\"' )\\\`>]*" "${rootDir}" `
+      + '--include="*.ts" --include="*.tsx" --include="*.md" --include="*.mdx" '
+      + '--exclude-dir=node_modules',
+      { encoding: 'utf-8' }
+    )
+
+    return [ ...new Set(
+      output
+        .split('\n')
+        .map((url) => url.replace(/[.,;)]+$/, ''))
+        .filter((url) => url && url !== docsUrl && url !== `${docsUrl}/`)
+    )]
+  }
+  catch {
+    return []
+  }
+}
+
+const checkDocLinks = async () => {
+  const urls = getUrls()
+
+  if (!urls.length) {
+    console.log('No docs links found.')
+
+    return
+  }
+
+  const slugs = getSdkApiSlugs()
+  const broken = []
+
+  let sitemap = null
+
+  for (const url of urls) {
+    const urlPath = url.replace(docsUrl, '').replace(/[#?].*$/, '').replace(/\/$/, '').toLowerCase()
+
+    if (slugs.includes(urlPath)) {
+      continue
+    }
+
+    // Not found in local slugs — check against live sitemap
+    if (!sitemap) {
+      sitemap = await fetchSitemap()
+    }
+
+    if (!sitemap.includes(`${docsUrl}${urlPath}`)) {
+      broken.push(url)
+    }
+  }
+
+  if (broken.length) {
+    broken.forEach((url) => console.log(url))
+    console.log(`\n🚫 Found ${broken.length} broken link(s)!`)
+    process.exit(1)
+  }
+
+  console.log('✅ All docs links are valid.')
+
+  // Warn if staged md files were changed
+  try {
+    const stagedMd = execSync('git diff --cached --name-only -- "src/**/*.md" "documentation/**/*.md"', { encoding: 'utf-8' }).trim()
+
+    if (stagedMd) {
+      const warn = (text) => console.log(`\x1b[33m${text}\x1b[0m`)
+
+      console.log()
+      warn('⚠️SDK docs were changed! ⚠️')
+      warn("Don't forget to run: pnpm sync:docs")
+    }
+  }
+  catch {}
+}
+
+checkDocLinks()

scripts/syncDocs/index.ts

@@ -82,7 +82,7 @@ const changeTargetPath = (path: string) => path
       cwd: srcPath
     })
 
-    const documentationFiles = await glob(['**/*.md', '**/*.mdx'], {
+    const documentationFiles = await glob(['**/*.md', '**/*.mdx', '**/_category_.json'], {
       cwd: documentationPath
     })
 
@@ -127,7 +127,7 @@ const changeTargetPath = (path: string) => path
 
       await fs.ensureDir(path.dirname(targetFile))
       await fs.copy(sourceFile, targetFile)
-    } 
+    }
 
     log.success('Files are copied')
 
@@ -154,13 +154,13 @@ const changeTargetPath = (path: string) => path
       branchName,
       title,
     })
+
+    await fs.remove(docsRepoPath)
+    log.success('🧹 Cloned docs repository has been cleaned up.')
   }
   catch (error) {
     log.error(`${error}`)
-    process.exit(1)
-  }
-  finally {
     await fs.remove(docsRepoPath)
-    log.success('🧹 Cloned docs repository has been cleaned up.')
+    process.exit(1)
   }
 })()

src/services/boost/index.ts

@@ -25,31 +25,31 @@ class Boost extends BoostTransactions {
 
   /**
    * @description Get basic boost data for the user.
-   * @see https://docs.stakewise.io/boost/requests/getdata
+   * @see https://docs.stakewise.io/sdk/api/boost/requests/getdata
    */
   public getData(values: StakeWise.ExtractInput<GetBoostDataInput>) {
     return getData({ ...this.params, ...values })
   }
 
   /**
    * @description Get unlock position data.
-   * @see https://docs.stakewise.io/boost/requests/getqueueposition
+   * @see https://docs.stakewise.io/sdk/api/boost/requests/getqueueposition
    */
   public getQueuePosition(values: StakeWise.ExtractInput<GetQueuePositionInput>) {
     return getQueuePosition({ ...this.params, ...values })
   }
 
   /**
    * @description Get Aave leverage strategy contract data
-   * @see https://docs.stakewise.io/boost/requests/getleveragestrategydata
+   * @see https://docs.stakewise.io/sdk/api/boost/requests/getleveragestrategydata
    */
   public getLeverageStrategyData(values: StakeWise.ExtractInput<GetLeverageStrategyDataInput>) {
     return getLeverageStrategyData({ ...this.params, ...values })
   }
 
   /**
    * @description Get Aave leverage strategy proxy contract address
-   * @see https://docs.stakewise.io/boost/requests/getleveragestrategyproxy
+   * @see https://docs.stakewise.io/sdk/api/boost/requests/getleveragestrategyproxy
    */
   public getLeverageStrategyProxy(values: StakeWise.ExtractInput<GetLeverageStrategyProxyInput>) {
     return getLeverageStrategyProxy({ ...this.params, ...values })

src/services/boost/transactions/index.ts

@@ -10,25 +10,25 @@ class BoostTransactions {
 
   /**
    * @description Lock your osToken to increase apy
-   * @see https://docs.stakewise.io/boost/transactions/lock
+   * @see https://docs.stakewise.io/sdk/api/boost/transactions/lock
    */
   public lock: ExtractLock
 
   /**
    * @description Unlock your boosted osToken
-   * @see https://docs.stakewise.io/boost/transactions/unlock
+   * @see https://docs.stakewise.io/sdk/api/boost/transactions/unlock
    */
   public unlock: ExtractUnlock
 
   /**
    * @description Claim your boosted osTokens and accumulated rewards
-   * @see https://docs.stakewise.io/boost/transactions/claimqueue
+   * @see https://docs.stakewise.io/sdk/api/boost/transactions/claimqueue
    */
   public claimQueue: ExtractClaimQueue
 
   /**
    * @description Upgrade leverage strategy contract version
-   * @see https://docs.stakewise.io/boost/transactions/upgradeleveragestrategy
+   * @see https://docs.stakewise.io/sdk/api/boost/transactions/upgradeleveragestrategy
    */
   public upgradeLeverageStrategy: ExtractUpgradeLeverageStrategy
 

src/services/distributorRewards/index.ts

@@ -12,7 +12,7 @@ class DistributorRewards extends DistributorRewardsTransactions {
 
   /**
    * @description Returns the set of distributor rewards tokens that are currently claimable.
-   * @see https://docs.stakewise.io/distributorRewards/requests/getrewards
+   * @see https://docs.stakewise.io/sdk/api/distributorRewards/requests/getrewards
    */
   public getRewards(values: StakeWise.ExtractInput<GetRewardsInput>) {
     return getRewards({ ...this.params, ...values })

src/services/distributorRewards/transactions/index.ts

@@ -6,7 +6,7 @@ import { createClaim, ExtractClaim } from './claim'
 class DistributorRewardsTransactions {
   /**
    * @description Claims rewards from the merkle distributor V2 contract.
-   * @see https://docs.stakewise.io/distributorRewards/transactions/claim
+   * @see https://docs.stakewise.io/sdk/api/distributorRewards/transactions/claim
    */
   public claim: ExtractClaim
 

src/services/osToken/index.ts

@@ -45,15 +45,15 @@ class OsToken extends OsTokenTransactions {
 
   /**
    * @description Current osToken APY.
-   * @see https://docs.stakewise.io/osToken/requests/getostokenapy
+   * @see https://docs.stakewise.io/sdk/api/osToken/requests/getostokenapy
   */
   public getAPY() {
     return getAPY(this.params)
   }
 
   /**
    * @description Current osToken rate.
-   * @see https://docs.stakewise.io/osToken/requests/getostokenrate
+   * @see https://docs.stakewise.io/sdk/api/osToken/requests/getostokenrate
   */
   public getRate() {
     return getRate(this.params)
@@ -62,15 +62,15 @@ class OsToken extends OsTokenTransactions {
   /**
    * @description Maximum number of **shares** for minting.
    * @deprecated Use new getMaxMintAmount method.
-   * @see https://docs.stakewise.io/osToken/requests/getmaxmint
+   * @see https://docs.stakewise.io/sdk/api/osToken/requests/getmaxmint
   */
   public getMaxMint(values: StakeWise.ExtractInput<GetMaxMintInput>) {
     return getMaxMint({ ...this.params, ...values })
   }
 
   /**
    * @description Maximum number of **shares** for minting.
-   * @see https://docs.stakewise.io/osToken/requests/getmaxmintamount
+   * @see https://docs.stakewise.io/sdk/api/osToken/requests/getmaxmintamount
   */
   public getMaxMintAmount(values: StakeWise.ExtractInput<GetMaxMintAmountInput>) {
     return getMaxMintAmount({ ...this.params, ...values })
@@ -79,31 +79,31 @@ class OsToken extends OsTokenTransactions {
   /**
    * @description User position data
    * @deprecated Use osToken.getHealthFactor and osToken.getBalance
-   * @see https://docs.stakewise.io/osToken/requests/getposition
+   * @see https://docs.stakewise.io/sdk/api/osToken/requests/getposition
   */
   public getPosition(values: StakeWise.ExtractInput<GetOsTokenPositionInput>) {
     return getPosition({ ...this.params, ...values })
   }
 
   /**
    * @description User osToken balance
-   * @see https://docs.stakewise.io/osToken/helpers/getbalance
+   * @see https://docs.stakewise.io/sdk/api/osToken/requests/getbalance
   */
   public getBalance(values: StakeWise.ExtractInput<GetOsTokenBalanceInput>) {
     return getBalance({ ...this.params, ...values })
   }
 
   /**
    * @description Convert ETH (assets) → osToken (shares)
-   * @see https://docs.stakewise.io/osToken/requests/getsharesfromassets
+   * @see https://docs.stakewise.io/sdk/api/osToken/requests/getsharesfromassets
   */
   public getSharesFromAssets(values: StakeWise.ExtractInput<GetSharesFromAssetsInput>) {
     return getSharesFromAssets({ ...this.params, ...values })
   }
 
   /**
    * @description Convert osToken (shares) → ETH (assets)
-   * @see https://docs.stakewise.io/osToken/requests/getassetsfromshares
+   * @see https://docs.stakewise.io/sdk/api/osToken/requests/getassetsfromshares
   */
   public getAssetsFromShares(values: StakeWise.ExtractInput<GetAssetsFromSharesInput>) {
     return getAssetsFromShares({ ...this.params, ...values })
@@ -112,23 +112,23 @@ class OsToken extends OsTokenTransactions {
   /**
    * @description How many osToken burn do you need to make to withdraw all deposit.
    * @deprecated use new getBurnAmountForUnstake method
-   * @see https://docs.stakewise.io/osToken/helpers/getburnamount
+   * @see https://docs.stakewise.io/sdk/api/osToken/helpers/getburnamount
   */
   public getBurnAmount(values: StakeWise.ExtractInput<GetBurnAmountInput>) {
     return getBurnAmount({ ...this.params, ...values })
   }
 
   /**
    * @description Returns the amount of osToken to burn for full unstake.
-   * @see https://docs.stakewise.io/osToken/helpers/getburnamountforunstake
+   * @see https://docs.stakewise.io/sdk/api/osToken/helpers/getburnamountforunstake
   */
   public getBurnAmountForUnstake(values: StakeWise.ExtractInput<GetBurnAmountForUnstakeInput>) {
     return getBurnAmountForUnstake({ ...this.params, ...values })
   }
 
   /**
    * @description Get the health of osETH position
-   * @see https://docs.stakewise.io/osToken/helpers/gethealthfactor
+   * @see https://docs.stakewise.io/sdk/api/osToken/helpers/gethealthfactor
   */
   public getHealthFactor(values: StakeWise.ExtractInput<GetHealthFactorInput>) {
     return getHealthFactor({ ...this.params, ...values })

src/services/osToken/transactions/index.ts

@@ -10,13 +10,13 @@ class OsTokenTransactions {
    * Use data from methods osToken.getMaxMint and osToken.getHealthFactor to block a call to mint()
    * if the number of shares is greater than what getMaxMint returns or if the number of osToken after the transaction
    * would make the position unhealthy
-   * @see https://docs.stakewise.io/osToken/transactions/mint
+   * @see https://docs.stakewise.io/sdk/api/osToken/transactions/mint
   */
   public mint: ExtractMint
 
   /**
    * @description Burns your osToken
-   * @see https://docs.stakewise.io/osToken/transactions/burn
+   * @see https://docs.stakewise.io/sdk/api/osToken/transactions/burn
   */
   public burn: ExtractBurn