docs: segregate api docs url/deployment (#3602)

.changeset/khaki-hairs-heal.md

@@ -0,0 +1,4 @@
+---
+---
+
+docs: segregate api docs url/deployment

.github/workflows/release.yaml

@@ -125,17 +125,29 @@ jobs:
           HOME: ${{ github.workspace }}
           npm_config_registry: "https://npm.pkg.github.com"
 
-      # ensure docs are always deployed after merge of changeset PR
+      # ensure docs API is always deployed after merge of changeset PR
       - name: Get the last commit message and set env vars
         run: echo LAST_COMMIT_MSG=$(git --no-pager log -1 --pretty=%B) >> $GITHUB_ENV
 
-      - name: Decides if Docs should be deployed
+      - name: Decides if Docs API should be deployed
         if: startsWith(env.LAST_COMMIT_MSG, 'ci(release):') && env.RELEASE_VERSION_HIGHER_THAN_LATEST == 'true'
-        run: echo SHOULD_DEPLOY_DOCS=true >> $GITHUB_ENV
+        run: echo DEPLOY_STABLE_DOCS_API=true >> $GITHUB_ENV
+
+      # nightly docs API gets updated on every merge to master
+      # and is configured in the vercel dashboard
+      # stable docs API gets updated only when a new release is published
+      - name: Update Docs API (stable)
+        if: github.ref_name == 'master' && env.DEPLOY_STABLE_DOCS_API == 'true'
+        env:
+          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_TS_DOCS_API_PROJECT_ID }}
+        run: |
+          pnpm install --global vercel@latest
+          vercel --prod --token=${{ secrets.VERCEL_TOKEN }}
 
       # # Commenting out as we require permissions to trigger across repos
-      # - name: Update docs (nightly)
-      #   if: github.ref_name == 'master' && env.SHOULD_DEPLOY_DOCS == 'true'
+      # - name: Update docs
+      #   if: github.ref_name == 'master'
       #   uses: benc-uk/workflow-dispatch@v1
       #   with:
       #     workflow: update-nightly.yml

apps/docs-api/index.md

@@ -12,15 +12,15 @@
 
 # Modules
 
-- [abi-coder](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_abi_coder.html)
-- [abi-typegen](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_abi_typegen.html)
-- [account](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_account.html)
-- [address](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_address.html)
-- [crypto](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_crypto.html)
-- [errors](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_errors.html)
-- [hasher](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_hasher.html)
-- [math](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_math.html)
-- [program](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_program.html)
-- [script](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_script.html)
-- [transactions](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_transactions.html)
-- [utils](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_utils.html)
+- [abi-coder](modules/_fuel_ts_abi_coder.html)
+- [abi-typegen](modules/_fuel_ts_abi_typegen.html)
+- [account](modules/_fuel_ts_account.html)
+- [address](modules/_fuel_ts_address.html)
+- [crypto](modules/_fuel_ts_crypto.html)
+- [errors](modules/_fuel_ts_errors.html)
+- [hasher](modules/_fuel_ts_hasher.html)
+- [math](modules/_fuel_ts_math.html)
+- [program](modules/_fuel_ts_program.html)
+- [script](modules/_fuel_ts_script.html)
+- [transactions](modules/_fuel_ts_transactions.html)
+- [utils](modules/_fuel_ts_utils.html)

apps/docs/.vitepress/config.ts

@@ -14,8 +14,21 @@ export default defineConfig({
       md.use(snippetPlugin);
       md.use(codeInContextPlugin);
       md.block.ruler.disable('snippet');
+      md.core.ruler.before('normalize', 'replace-docs-api-url', (state) => {
+        const apiUrl = process.env.NODE_ENV === 'development' ? 'http://localhost:5174' : '/api';
+        state.src = state.src.replace(/DOCS_API_URL/g, apiUrl);
+      });
     },
   },
+  transformHtml: (code) => {
+    // make the API links open in a new tab
+    // because opening in the same tab doesn't work in the preview
+    return code.replace(/(<a\s+[^>]*href="\/api\/[^"]*")/g, '$1 target="_blank" rel="noreferrer"');
+  },
+  // Finds dead DOCS_API_URL links and fails,
+  // but they get replaced later in the markdown transformer.
+  // We have the md link checker workflow which covers this.
+  ignoreDeadLinks: true,
   head: [
     ['link', { rel: 'icon', href: '/fuels-ts/favicon.ico', type: 'image/png' }],
     ['meta', { property: 'og:type', content: 'website' }],

apps/docs/package.json

@@ -5,14 +5,18 @@
   "description": "",
   "type": "module",
   "scripts": {
-    "dev": "nodemon --config nodemon.config.json -x 'run-s build:snippets dev:docs'",
+    "dev": "nodemon --config nodemon.config.json -x 'run-s build:snippets build:docs-api dev:docs'",
     "build": "run-s build:snippets build:docs",
-    "preview": "run-s build:snippets preview:docs",
+    "preview": "run-s build:snippets build:docs-api preview:docs",
     "test": "cd ../.. && pnpm run test:filter apps/docs",
     "build:snippets": "run-s wrap:snippets build:forc",
-    "build:docs": "vitepress build",
+    "build:docs": "run-s build:docs-app build:docs-api",
+    "build:docs-app": "vitepress build",
+    "build:docs-api": "cd ../docs-api && pnpm build && cp -r ./src/api ../docs/dist",
     "preview:docs": "vitepress preview",
-    "dev:docs": "vitepress dev",
+    "preview:docs-api": "pnpm vite preview --port 5174 --outDir ../docs-api/src/api",
+    "dev:docs": "run-p docs:dev preview:docs-api",
+    "docs:dev": "vitepress dev",
     "wrap:snippets": "tsx ./scripts/wrap-snippets.ts",
     "build:forc": "pnpm fuels build --deploy",
     "type:check": "pnpm tsc --noEmit --project tsconfig.emit.json"

apps/docs/src/guide/contracts/contract-balance.md

@@ -1,10 +1,10 @@
 # Contract Balance
 
-When working with contracts, it's crucial to be aware of the available contract balance of an asset while paying for costly operations. This guide will explain the `getBalance` method in the [Contract](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_program.Contract.html) class, which allows you to check a contract's available balance.
+When working with contracts, it's crucial to be aware of the available contract balance of an asset while paying for costly operations. This guide will explain the `getBalance` method in the [Contract](DOCS_API_URL/classes/_fuel_ts_program.Contract.html) class, which allows you to check a contract's available balance.
 
 ## The `getBalance` Method
 
-The [`Contract.getBalance`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_program.Contract.html#getBalance) method retrieves the available balance of a specific asset on your contract. This method is particularly useful for determining the remaining balance after sending assets to a contract and executing contract calls.
+The [`Contract.getBalance`](DOCS_API_URL/classes/_fuel_ts_program.Contract.html#getBalance) method retrieves the available balance of a specific asset on your contract. This method is particularly useful for determining the remaining balance after sending assets to a contract and executing contract calls.
 
 It is important to note that this method returns the total available contract balance, regardless of how often assets have been sent to it or spent.
 

apps/docs/src/guide/contracts/cost-estimation.md

@@ -1,6 +1,6 @@
 # Estimating Contract Call Cost
 
-The [`FunctionInvocationScope.getTransactionCost`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_program.FunctionInvocationScope.html#getTransactionCost) method allows you to estimate the cost of a specific contract call. The return type, `TransactionCost`, is an object containing relevant information for the estimation:
+The [`FunctionInvocationScope.getTransactionCost`](DOCS_API_URL/classes/_fuel_ts_program.FunctionInvocationScope.html#getTransactionCost) method allows you to estimate the cost of a specific contract call. The return type, `TransactionCost`, is an object containing relevant information for the estimation:
 
 <<< @/../../../packages/account/src/providers/provider.ts#cost-estimation-1{ts:line-numbers}
 

apps/docs/src/guide/contracts/dependency-estimation.md

@@ -4,6 +4,6 @@ In [variable outputs](./variable-outputs.md), we mention that a contract call mi
 
 However, by default the SDK always automatically estimates these dependencies and double-checks if everything is in order whenever you invoke a contract function or attempt to send a transaction.
 
-The SDK uses the [Provider.estimateTxDependencies](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_account.Provider.html#estimateTxDependencies) method to set any missing dependencies identified during the estimation process. This requires simulating the transaction a few times in the background.
+The SDK uses the [Provider.estimateTxDependencies](DOCS_API_URL/classes/_fuel_ts_account.Provider.html#estimateTxDependencies) method to set any missing dependencies identified during the estimation process. This requires simulating the transaction a few times in the background.
 
 While relying on the SDK's automatic estimation is a decent default behavior, we recommend manually specifying the dependencies if they are known in advance to avoid the performance impact of the estimation process.

apps/docs/src/guide/contracts/deploying-contracts.md

@@ -53,7 +53,7 @@ Now that the contract is deployed, you can interact with it by submitting a cont
 
 ## Deploying a Large Contract as Blobs
 
-In the above guide we use the recommended `deploy` method. If you are working with a contract that is too large to be deployed in a single transaction, then the SDK will chunk the contract for you and submit it as blobs, to then be accessed later by a create transaction. This process is handled by the [`ContractFactory.deployAsBlobTx`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_contract.index.ContractFactory.html#deployAsBlobTx) method.
+In the above guide we use the recommended `deploy` method. If you are working with a contract that is too large to be deployed in a single transaction, then the SDK will chunk the contract for you and submit it as blobs, to then be accessed later by a create transaction. This process is handled by the [`ContractFactory.deployAsBlobTx`](DOCS_API_URL/classes/_fuel_ts_contract.index.ContractFactory.html#deployAsBlobTx) method.
 
 <<< @./snippets/deploying-contracts/deployment.ts#blobs{ts:line-numbers}
 

apps/docs/src/guide/contracts/managing-deployed-contracts.md

@@ -4,9 +4,9 @@ To interact with a deployed contract using the SDK without redeploying it, you o
 
 ## Contract ID
 
-The `contractId` property from the [`Contract`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_program.Contract.html) class is an instance of the [`Address`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_address.Address.html) class.
+The `contractId` property from the [`Contract`](DOCS_API_URL/classes/_fuel_ts_program.Contract.html) class is an instance of the [`Address`](DOCS_API_URL/classes/_fuel_ts_address.Address.html) class.
 
-The [`Address`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_address.Address.html) class also provides a set of utility functions for easy manipulation and conversion between address formats along with one property; `b256Address`, which is a string encoded in [`B256`](../types/b256.md) format.
+The [`Address`](DOCS_API_URL/classes/_fuel_ts_address.Address.html) class also provides a set of utility functions for easy manipulation and conversion between address formats along with one property; `b256Address`, which is a string encoded in [`B256`](../types/b256.md) format.
 
 When you log the `contractId` property of an instantiated Contract using `console.log`, the output appears as follows:
 
@@ -22,10 +22,10 @@ If you have already an instantiated and deployed contract in hands you can creat
 
 <<< @./snippets/managing-deployed-contracts.ts#with-contractId{ts:line-numbers}
 
-The previous example assumes that you have a [`Contract`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_program.Contract.html) instance at hand. However, some Fuel tools and Sway use the [`B256`](../types/b256.md) type format, a hex-encoded string-like type, for contract IDs.
+The previous example assumes that you have a [`Contract`](DOCS_API_URL/classes/_fuel_ts_program.Contract.html) instance at hand. However, some Fuel tools and Sway use the [`B256`](../types/b256.md) type format, a hex-encoded string-like type, for contract IDs.
 
 You might have this format instead, for example, if you have deployed your contract with `forc deploy`.
 
-The process of instantiating a [`Contract`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_program.Contract.html) remains the same when using a contract ID of type `B256`:
+The process of instantiating a [`Contract`](DOCS_API_URL/classes/_fuel_ts_program.Contract.html) remains the same when using a contract ID of type `B256`:
 
 <<< @./snippets/managing-deployed-contracts.ts#with-b256{ts:line-numbers}

apps/docs/src/guide/contracts/minted-token-asset-id.md

@@ -23,6 +23,6 @@ Since the asset ID depends on the contract ID, which is always dynamic (unlike t
 
 ## Create Asset Id
 
-The SDK provides a helper named `createAssetId` which takes the contract ID and sub ID as parameters. This helper internally calls `getMintedAssetId` and returns the Sway native parameter [AssetId](https://fuels-ts-docs-api.vercel.app/types/_fuel_ts_address.AssetId.html), ready to be used in a Sway program invocation:
+The SDK provides a helper named `createAssetId` which takes the contract ID and sub ID as parameters. This helper internally calls `getMintedAssetId` and returns the Sway native parameter [AssetId](DOCS_API_URL/types/_fuel_ts_address.AssetId.html), ready to be used in a Sway program invocation:
 
 <<< @./snippets/utilities/create-asset-id.ts#create-asset-id-1{ts:line-numbers}

apps/docs/src/guide/contracts/using-different-wallets.md

@@ -1,6 +1,6 @@
 # Making Calls with Different Wallets or Providers
 
-This guide demonstrates how to make contract calls using different wallets and providers by passing either an [`Account`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_account.Account.html) or a [`Provider`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_account.Provider.html) to the contract on instantiation.
+This guide demonstrates how to make contract calls using different wallets and providers by passing either an [`Account`](DOCS_API_URL/classes/_fuel_ts_account.Account.html) or a [`Provider`](DOCS_API_URL/classes/_fuel_ts_account.Provider.html) to the contract on instantiation.
 
 ## Changing Wallets
 

apps/docs/src/guide/cookbook/custom-transactions-from-contract-calls.md

@@ -1,6 +1,6 @@
 # Custom Transactions From Contract Calls
 
-In the previous example we demonstrated how you can instantiate a [`ScriptTransactionRequest`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_account.ScriptTransactionRequest.html) to customize and build out a more complex transaction via a script. The same can be done using contracts, but this allows us to utilize functions available in the contract and access on-chain state. Allowing us to harness all of the power from an invocation scope and a transaction request.
+In the previous example we demonstrated how you can instantiate a [`ScriptTransactionRequest`](DOCS_API_URL/classes/_fuel_ts_account.ScriptTransactionRequest.html) to customize and build out a more complex transaction via a script. The same can be done using contracts, but this allows us to utilize functions available in the contract and access on-chain state. Allowing us to harness all of the power from an invocation scope and a transaction request.
 
 This cookbook demonstrates how we can utilize a contract call to build out a custom transaction, allowing us to update on-chain state and transfer assets to a recipient address.
 

apps/docs/src/guide/cookbook/custom-transactions.md

@@ -1,12 +1,12 @@
 # Custom Transactions
 
-There may be scenarios where you need to build out transactions that involve multiple program types and assets; this can be done by instantiating a [`ScriptTransactionRequest`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_account.ScriptTransactionRequest.html). This class allows you to a append multiple program types and assets to a single transaction.
+There may be scenarios where you need to build out transactions that involve multiple program types and assets; this can be done by instantiating a [`ScriptTransactionRequest`](DOCS_API_URL/classes/_fuel_ts_account.ScriptTransactionRequest.html). This class allows you to a append multiple program types and assets to a single transaction.
 
 Consider the following script that transfers multiple assets to a contract:
 
 <<< @/../../docs/sway/script-transfer-to-contract/src/main.sw#custom-transactions-1{rust:line-numbers}
 
-This script can be executed by creating a [`ScriptTransactionRequest`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_account.ScriptTransactionRequest.html), appending the resource and contract inputs/outputs and then sending the transaction, as follows:
+This script can be executed by creating a [`ScriptTransactionRequest`](DOCS_API_URL/classes/_fuel_ts_account.ScriptTransactionRequest.html), appending the resource and contract inputs/outputs and then sending the transaction, as follows:
 
 <<< @/../../docs/src/guide/scripts/snippets/script-custom-transaction.ts#custom-transactions-2{ts:line-numbers}
 

apps/docs/src/guide/errors/index.md

@@ -20,7 +20,7 @@ Check that the arguments supplied to the function match the required type.
 
 ### `ACCOUNT_REQUIRED`
 
-When an [`Account`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_account.Account.html) is required for an operation. This will usually be in the form of a [`Wallet`](../wallets/index.md).
+When an [`Account`](DOCS_API_URL/classes/_fuel_ts_account.Account.html) is required for an operation. This will usually be in the form of a [`Wallet`](../wallets/index.md).
 
 It could be caused during the deployments of contracts when an account is required to sign the transaction. This can be resolved by following the deployment guide [here](../contracts/deploying-contracts.md).
 
@@ -220,7 +220,7 @@ Check the status received is within `TransactionStatus`.
 
 When the transaction type from the Fuel Node is _not_ supported.
 
-The type is within [`TransactionType`](https://fuels-ts-docs-api.vercel.app/enums/_fuel_ts_account.TransactionType.html).
+The type is within [`TransactionType`](DOCS_API_URL/enums/_fuel_ts_account.TransactionType.html).
 
 ### `INVALID_TTL`
 
@@ -262,7 +262,7 @@ Ensure that a connector has been supplied to the `Account` or `Wallet`.
 
 A provider is missing when it's required for a given operation.
 
-It could be caused by the provider not being set for either an [`Account`](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_account.html) or a [`Wallet`](../wallets/index.md) - use the `connect` method to attach a provider.
+It could be caused by the provider not being set for either an [`Account`](DOCS_API_URL/modules/_fuel_ts_account.html) or a [`Wallet`](../wallets/index.md) - use the `connect` method to attach a provider.
 
 ### `MISSING_REQUIRED_PARAMETER`
 

apps/docs/src/guide/predicates/instantiating-a-predicate.md

@@ -12,7 +12,7 @@ After compiling, you will obtain the binary of the predicate and its JSON ABI (A
 
 <<< @./snippets/instantiation/simple.ts#predicate-simple-2{ts:line-numbers}
 
-The created [`Predicate`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_account.Predicate.html) instance, among other things, has three important properties: the predicate `bytes` (byte code), the `chainId`, and the predicate `address`.
+The created [`Predicate`](DOCS_API_URL/classes/_fuel_ts_account.Predicate.html) instance, among other things, has three important properties: the predicate `bytes` (byte code), the `chainId`, and the predicate `address`.
 
 This address, generated from the byte code, corresponds to the Pay-to-Script-Hash (P2SH) address used in Bitcoin.
 

apps/docs/src/guide/predicates/methods.md

@@ -1,6 +1,6 @@
 # Interacting With Predicates
 
-The `Predicate` class extends the [`Account`](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_account.html) class, inheriting all its methods. Therefore, there are multiple ways to interact with predicates, but broadly speaking, we can think about three:
+The `Predicate` class extends the [`Account`](DOCS_API_URL/modules/_fuel_ts_account.html) class, inheriting all its methods. Therefore, there are multiple ways to interact with predicates, but broadly speaking, we can think about three:
 
 - `Checking Balances`
 - `Transactions`