Re-Introducing NEAR-API-JS: The NEAR JavaScript API

Jane Wang

NEAR Dev Tools
September 10, 2022

The vision for NEAR-API-JS is to create a compact library for interacting with the NEAR blockchain and its ecosystem. It is designed initially to make RPC requests and will expand into a more general-purpose library. For a while, this library has fallen short of its required attention and has had a lower priority than other projects requiring the Pagoda team's focus. However, with Pagoda's focus on Developer Tools and the JavaScript Stack, NEAR-API-JS has become a priority to improve DevX.

Since Consensus, the Pagoda team has been heads down working on NEAR-API-JS. We’d like to thank the NEAR community for providing valuable feedback on the repository. We have taken your feedback and have been working hard making many improvements to NEAR-API-JS.

-

Immediate Actions Since Consensus

Right after Consensus, the product and engineering team reviewed all open issues in the Github repository and added these issues into our scrum process. We’ve refocused a number of engineers on improving the NEAR-API-JS.

1) Creating an On-Call Process

We’ve removed a stalebot that was causing trouble on the repository, and established a support response process that triages incoming issues and requests. These incoming issues are assigned to current sprints or added to the backlog based on severity and priority. Issues submitted in Github are directly connected to our internal ticketing system.

2) Automated the Process for PR and PR Template More

As always, we welcome contributors to help us to improve NEAR-API-JS. We have created Github actions and a CI/CD pipeline which will run tests against new PRs. With a more automated process, your PRs can now be tested automatically and reviewed by the maintainers. To encourage contribution, we’ve created a PR template for contributors linked here. For additional information on how to contribute to NEAR-API-JS, please check out our contributing.md.

3) Releases using Changesets

We have enabled a changesets workflow that is centered around “changeset” files. An human authored file containing both the version bump and the changelog entry. These files are committed and included in PR’s along with the code change itself (See example).

When planning a release, changeset files are combined to create a full changelog and determine required version bumps. After reviewing the result, a publish can be triggered. This process is automated with a Github action which tracks changesets merged to master and writes the result to a PR, and once this PR is merged, packages will be published. We hope this release process enables the team to publish releases more efficiently.

4) Looking Back and Ahead

We have now 62 open issues, down from 106 issues that we saw after Consensus. We are happy to report that we have merged many PRs contributed by the community. In the latest NEAR-API-JS v1.0.0 release, a new era begins for NEAR-API-JS.

-

Highlights in this Update:

These are some of the most critical updates coming to NEAR-API-js:

  • near-api-js v1.0.0 marks the beginning of proper semver versioning for near-api-js! From now on, breaking changes will be correctly represented by major version bumps, new features or added functionality will be represented as minor version bumps, and bug fixes will be represented by patch version bumps! See https://semver.org/ for more info.
  • You can now provide blockQuery as an argument to viewFunction and viewState calls (#863)
  • Lots of deprecated code has been removed, which simplifies TypeDoc descriptions for many commonly used functions
  • Account.viewFunction() now accepts its arguments as an object instead of positional arguments, making it consistent with other methods that have already undergone this migration such as Account.functionCall(), Account.signAndSendTransaction(). Using positional arguments for this function has been deprecated. (#918)
  • You can now await until sign in process is completely finished; this avoids a possible race condition where previously you could try to read a key from the keystore before it has been moved from 'temporary' to finalized state during initialization. (#842)
  • Attempting to use WalletConnection or WalletConnectedAccount objects outside of the browser context will now generate a user-friendly error message instead of throwing when trying to access local storage or the window object. (#896)
  • near-api-js now supports the latest version of Typescript (4.7)
  • Fixed a bug in JsonRpcProvider.txStatusReceipts() - providing txHash as a string rather than Uint8Array now works as expected (#866)
  • Account.findAccessKey() now throws a typed error if no key exists in keystore for the current account (#904)

Internal / Project Changes 🔍

We've also dedicated some time to improve the workflow and structure of the repository:

  • near-api-js is now a mono-repo! We are working towards modularization of the functionality that near-api-js provides, to allow more explicit dependency handling for code that runs in different environments (browser, node, react-native, etc.), better discoverability and documentation.
  • We are moving to a CI based development flow! Expect a more rapid cadence of releases as we get the CI pipeline fully configured and automate things like changelog generation.
-

Pull Request Deep-dive 🤿

From docs, to features and house-cleanup, here are all the PR's in this update:

PRs - Internal:

  • #940 - build(deps-dev): bump danger from 11.1.1 to 11.1.2 - 9c8d5d2
  • #934 - build(deps-dev): bump lerna from 5.3.0 to 5.4.3 - ae77e1b
  • #909 - Applied engines property on package.json - d4344ed
  • #913 - chore: Update CODEOWNERS - 3d3c259
  • #908 - Naj 6 move current near api js to be a lerna package lernify the repo - 7f16b10
  • #906 - fix: Fix eslint script/errors and run in PR builds - c0fe0a6
  • #899 - chore: Create Pull Request template - 87081fc
  • #939 - fix(near-api-js): optional headers in NearConfig - 92d20e9
  • #828 - Deprecated functionality deleted - f87aa7d
  • #890 - ci: Run tests on pull requests - 629dc30
  • #903 - Update README.md - 804a29a
  • #886 - build(deps-dev): bump danger from 10.7.0 to 11.1.1 - 320facb
  • #864 - build(deps): bump bn.js from 5.2.0 to 5.2.1 - 1ea0aa5
  • #871 - build(deps-dev): bump ts-morph from 11.0.3 to 15.1.0 - 42337af
  • #884 - build(deps): bump shell-quote from 1.7.2 to 1.7.3 - e7f4f60
  • #881 - Delete stale.yml - 22aa58b
  • #910 - NAJ-113-delete-hacks-related-to-error-types - 5696829

PRs - Documentation:

PRs - Functional

  • #918 - feat: changed viewFuction to support both POJO and existing arguments - 3850213
  • #896 - feat: explicit walletconnection errors on server - 3ba8423
  • #904 - Update error thrown when signTransaction() fails due to missing accessKey - 743a19e
  • #842 - Be able to await until sign in process done completely - 4c68be2
  • #856 - modify interface Transaction in provider.ts - 83d7695
  • #866 - Fix for json-rpc method EXPERIMENTAL_tx_status - 3e917ad
  • #863 - Support blockId in account viewFunction and fix viewState - 824059b
  • #883 - feat: warning that deleting an account does not transfer assets besides near - 3206032
-

What's next? Our Public Roadmap.

Looking ahead, we have great plans for NEAR-API-JS. We are currently finishing up on the following four initiatives.

1. Infrastructure - a CI/CD Pipeline & PR template & Better Tests

2. Milestone 1 - DevX Improvement - Fixes & Enhancements

3. Marketing - Public roadmap, Blog Post, and Community calls   

4. Documentation Enhancements

For the NEAR-API-JS future initiatives, we will be modularizing NEAR-API-JS into multiple new packages to support browser, node, react-native, and other environments. The first milestone will be to create modularization which allows each package to evolve to have explicit dependencies, improved tests, and better documentation. Each package will contain its own package.json. As a part of separating into new packages with each separately installable under the same org (e.g. npm install @near-js/browser-keystore, npm install @near-js/filesystem-keystore, etc.), we will be moving the near-api-js under a new namespace @near-js. The second milestone is to enhance each package to support different APIs specific to the environment. In addition, we will also be providing support for ES6 modules in addition to CommonJS modules. Finally, we will create a set of composable APIs and remove unnecessary coupling between classes.

To keep you – the community – up to date on what’s happening, we are releasing a public roadmap for NEAR-API-JS.

-

Contribute & Stay Up to Date

Want to stay up to date on what's happening in NEAR-API-JS? Please join us in the monthly NEAR Tools Community Meeting and register here https://near.ai/tooling-meetings. We have been sharing updates to NEAR-API-JS in community calls in July, August, and will continue to share what we are working on in future community meetings.

As always, if you have feature enhancements or bugfix requests, please open a Github ticket here. If you’d like to contribute, we are looking for contributions for the following issues: https://github.com/near/near-api-js/contribute.md. If you have any questions, please feel free to reach out to the Developers Relations Team at the office hours. We look forward to continued collaboration with you on NEAR-API-JS.

Don’t forget, tell us what you think about NEAR-API-JS by completing this survey.

Meet the first-ever

Web3 Startup

Platform.

All the tools you need to build, launch, and grow your Web3 startup.