feat!: export ContractClient et al. in contract; rename `SorobanR…

…pc` to `rpc` (#962)

* Appease ESLint: This includes some fixes and updates to eslint 
configuration to make it work as expected

- Extended `airbnb-typescript/base` to get it to stop yelling at me
  about importing files without file extension. Saw this recommended as
  the fix on StackOverflow [[1]]. And it makes sense to me that if we are
  extending Airbnb's lint rules and using TypeScript, we probably want
  their TypeScript-specific lint rules, too.
- Added the `eslint-plugin-jsdoc` plugin because the old `valid-jsdoc`
  rule we were using has been deprecated [[2]], and this plugin is the new
  way. Previously we had `valid-jsdoc: 1` (with some extra customization),
  and my guess is that extending `plugin:jsdoc/recommended` (plus some
  customization) is roughly equivalent.
- Researched [[3]] whether JSDoc `@param`-style docs or TSDoc-style
  `/** inline param docs */` work better. TSDoc work better. So disabled
  `jsdoc/require-param`.
- Remove mostly-duplicate `src/soroban/.eslintrc.js`, which had only one
  setting different from `src/.eslintrc.js`

Note that `src/contract_client` is now perhaps the only directory of
code to pass our ESLint settings 🤔

  [1]: https://stackoverflow.com/a/67610259/249801
  [2]: https://eslint.org/docs/latest/rules/valid-jsdoc
  [3]: #962 (comment)

* New exports `contract` and `rpc`:

- `SorobanRpc` now also exported as `rpc`
- New main export `contract`.
  This allows us to import it the usual way, instead of needing to do
  things like

      import { ContractClient } from "stellar-sdk/lib/contract_client"

  which doesn't work in the browser (because `lib`)

- `ContractSpec` now available at `contract.Spec`
- Also includes other supporting classes, functions, and types:
  - `contract.AssembledTransaction`
  - `contract.ClientOptions`
  - etc

- These are also available at matching entrypoints, if your
node and TypeScript configuration support the `exports` declaration:

    import {
      Client,
      ClientOptions,
      AssembledTransaction,
    } from 'stellar-sdk/contract'

This also attempts to document exported modules. The JSDoc-style
comments in `src/index.ts` don't actually show up when you import these
things. We can figure this out later. Docs here
https://jsdoc.app/howto-es2015-modules. In the meantime, these are still
useful notes that we can use later.

---------

Co-authored-by: George <[email protected]>

.eslintrc.js

@@ -2,9 +2,12 @@ module.exports = {
   env: {
     es6: true,
   },
-  extends: ["airbnb-base", "prettier"],
+  extends: [
+    "airbnb-base",
+    "prettier",
+    "plugin:jsdoc/recommended",
+  ],
   plugins: ["@babel", "prettier", "prefer-import"],
-  parser: "@typescript-eslint/parser",
   rules: {
     "node/no-unpublished-require": 0,
   },

CHANGELOG.md

@@ -6,10 +6,75 @@ A breaking change will get clearly marked in this log.
 
 ## Unreleased
 
+### Breaking Changes
+
+- `ContractClient` functionality previously added in [v11.3.0](https://github.com/stellar/js-stellar-sdk/releases/tag/v11.3.0) was exported in a non-standard way. You can now import it as any other stellar-sdk module.
+
+  ```diff
+  - import { ContractClient } from '@stellar/stellar-sdk/lib/contract_client'
+  + import { contract } from '@stellar/stellar-sdk'
+  + const { Client } = contract
+  ```
+
+  Note that this top-level `contract` export is a container for ContractClient and related functionality. The ContractClient class is now available at `contract.Client`, as shown. Further note that there is a capitalized `Contract` export as well, which comes [from stellar-base](https://github.com/stellar/js-stellar-base/blob/b96281b9b3f94af23a913f93bdb62477f5434ccc/src/contract.js#L6-L19). You can remember which is which because capital-C `Contract` is a class, whereas lowercase-c `contract` is a container/module with a bunch of classes, functions, and types.
+
+  Additionally, this is available from the `/contract` entrypoint, if your version of Node [and TypeScript](https://stackoverflow.com/a/70020984/249801) support [the `exports` declaration](https://nodejs.org/api/packages.html#exports). Finally, some of its exports have been renamed.
+
+  ```diff
+   import {
+  -  ContractClient,
+  +  Client,
+     AssembledTransaction,
+  -  ContractClientOptions,
+  +  ClientOptions,
+     SentTransaction,
+  -} from '@stellar/stellar-sdk/lib/contract_client'
+  +} from '@stellar/stellar-sdk/contract'
+  ```
+
+
+- The `ContractSpec` class is now nested under the `contract` module, and has been renamed to `Spec`.
+
+  ```diff
+  -import { ContractSpec } from '@stellar/stellar-sdk'
+  +import { contract } from '@stellar/stellar-sdk'
+  +const { Spec } = contract
+  ```
+
+  Alternatively, you can import this from the `contract` entrypoint, if your version of Node [and TypeScript](https://stackoverflow.com/a/70020984/249801) support [the `exports` declaration](https://nodejs.org/api/packages.html#exports).
+
+  ```diff
+  -import { ContractSpec } from '@stellar/stellar-sdk'
+  +import { Spec } from '@stellar/stellar-sdk/contract'
+  ```
+
+- Previously, `AssembledTransaction.signAndSend()` would return a `SentTransaction` even if the transaction never finalized. That is, if it successfully sent the transaction to the network, but the transaction was still `status: 'PENDING'`, then it would `console.error` an error message, but return the indeterminate transaction anyhow.
+
+  It now throws a `SentTransaction.Errors.TransactionStillPending` error with that error message instead.
+
+### Deprecated
+
+- `SorobanRpc` module is now also exported as `rpc`. You can import it with either name for now, but `SorobanRpc` will be removed in a future release.
+
+  ```diff
+   import { SorobanRpc } from '@stellar/stellar-sdk'
+  +// OR
+  +import { rpc } from '@stellar/stellar-sdk'
+  ```
+
+  You can also now import it at the `/rpc` entrypoint, if your version of Node [and TypeScript](https://stackoverflow.com/a/70020984/249801) support [the `exports` declaration](https://nodejs.org/api/packages.html#exports).
+
+  ```diff
+  -import { SorobanRpc } from '@stellar/stellar-sdk'
+  -const { Api } = SorobanRpc
+  +import { Api } from '@stellar/stellar-sdk/rpc'
+  ```
+
 ### Added
-* Added a from method in `ContractClient` which takes the `ContractClientOptions` and instantiates the `ContractClient` by utilizing the `contractId` to retrieve the contract wasm from the blockchain. The custom section is then extracted and used to create a `ContractSpec` which is then used to create the client.
-* Similarly adds `fromWasm` and `fromWasmHash` methods in `ContractClient` which can be used to initialize a `ContractClient` if you already have the wasm bytes or the wasm hash along with the `ContractClientOptions`.
-* Added `getContractWasmByContractId` and `getContractWasmByHash` methods in `Server` which can be used to retrieve the wasm bytecode of a contract via its `contractId` and wasm hash respectively.
+
+* Added a `from` method in `contract.Client` which takes the `ClientOptions` and instantiates the `Client` by utilizing the `contractId` to retrieve the contract wasm from the blockchain. The custom section is then extracted and used to create a `contract.Spec` which is then used to create the client.
+* Similarly adds `fromWasm` and `fromWasmHash` methods in `Client` which can be used to initialize a `Client` if you already have the wasm bytes or the wasm hash along with the `ClientOptions`.
+* Added `getContractWasmByContractId` and `getContractWasmByHash` methods in `rpc.Server` which can be used to retrieve the wasm bytecode of a contract via its `contractId` and wasm hash respectively.
 
 ## [v12.0.0-rc.2](https://github.com/stellar/js-stellar-sdk/compare/v11.3.0...v12.0.0-rc.2)
 

README.md

@@ -96,7 +96,7 @@ The usage documentation for this library lives in a handful of places:
 You can also refer to:
 
  * the [documentation](https://developers.stellar.org/network/horizon) for the Horizon REST API (if using the `Horizon` module) and
- * the [documentation](https://soroban.stellar.org/docs/reference/rpc) for Soroban RPC's API (if using the `SorobanRpc` module)
+ * the [documentation](https://soroban.stellar.org/docs/reference/rpc) for Soroban RPC's API (if using the `rpc` module)
 
 ### Usage with React-Native
 

package.json

@@ -23,6 +23,21 @@
     "/lib",
     "/dist"
   ],
+  "exports": {
+    ".": {
+      "browser": "./dist/stellar-sdk.min.js",
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./contract": {
+      "types": "./lib/contract/index.d.ts",
+      "default": "./lib/contract/index.js"
+    },
+    "./rpc": {
+      "types": "./lib/rpc/index.d.ts",
+      "default": "./lib/rpc/index.js"
+    }
+  },
   "scripts": {
     "build": "cross-env NODE_ENV=development yarn _build",
     "build:prod": "cross-env NODE_ENV=production yarn _build",
@@ -109,8 +124,10 @@
     "dotenv": "^16.4.5",
     "eslint": "^8.57.0",
     "eslint-config-airbnb-base": "^15.0.0",
+    "eslint-config-airbnb-typescript": "^18.0.0",
     "eslint-config-prettier": "^9.0.0",
     "eslint-plugin-import": "^2.29.1",
+    "eslint-plugin-jsdoc": "^48.2.4",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-prefer-import": "^0.0.1",
     "eslint-plugin-prettier": "^5.1.2",

src/.eslintrc.js

@@ -1,6 +1,13 @@
 module.exports = {
-  env: {
-    es6: true,
+  extends: [
+    "airbnb-base",
+    "airbnb-typescript/base",
+    "prettier",
+    "plugin:jsdoc/recommended",
+  ],
+  parserOptions: {
+    parser: "@typescript-eslint/parser",
+    project: "./config/tsconfig.json",
   },
   rules: {
     // OFF
@@ -10,6 +17,8 @@ module.exports = {
     camelcase: 0,
     "class-methods-use-this": 0,
     "linebreak-style": 0,
+    "jsdoc/require-returns": 0,
+    "jsdoc/require-param": 0,
     "new-cap": 0,
     "no-param-reassign": 0,
     "no-underscore-dangle": 0,
@@ -18,19 +27,12 @@ module.exports = {
     "lines-between-class-members": 0,
 
     // WARN
-    "prefer-import/prefer-import-over-require": [1],
+    "arrow-body-style": 1,
     "no-console": ["warn", { allow: ["assert"] }],
     "no-debugger": 1,
-    "no-unused-vars": 1,
-    "arrow-body-style": 1,
-    "valid-jsdoc": [
-      1,
-      {
-        requireReturnDescription: false,
-      },
-    ],
-    "prefer-const": 1,
     "object-shorthand": 1,
+    "prefer-const": 1,
+    "prefer-import/prefer-import-over-require": [1],
     "require-await": 1,
 
     // ERROR