docs: Documentation improvements (#408)

README.md

@@ -42,6 +42,7 @@ See more in the [Anatomy of a Contract](https://docs.near.org/build/smart-contra
 
 ## Documentation
 
+- [Learn how to use](https://github.com/near/create-near-app/tree/master/templates/contracts/ts)
 - [Learn by example with AgorApp](https://agorapp.dev/catalog/all?difficulty=&chains=near)
 - [Learn by example with NEAR Docs](https://docs.near.org/build/smart-contracts/quickstart)
 - Check our [detailed examples and tutorials](https://docs.near.org/tutorials/welcome)

examples/README.md

@@ -0,0 +1,62 @@
+# Example Smart Contracts
+
+This directory contains example smart contracts that demonstrate various functionalities using the `near-sdk-js`. These examples are meant to serve as a starting point for developers looking to build smart contracts on the NEAR blockchain using JavaScript/TypeScript.
+
+## Overview
+
+The example smart contracts provided here showcase different use cases and features of the NEAR blockchain. Each contract is written in JavaScript/TypeScript and demonstrates best practices for developing secure, efficient, and scalable smart contracts.
+
+## Build and Test
+
+To build and test the smart contracts in this directory, follow the steps below:
+
+### Build
+
+To build all the smart contracts, run the following command in the root of the project:
+
+```
+pnpm build
+```
+
+### Test
+
+To run the tests for the example smart contracts, use the following command:
+
+```
+pnpm test
+```
+
+This command will execute the test suites associated with each smart contract, ensuring that they function as expected.
+
+## List of Example Smart Contracts
+
+The following smart contracts demonstrate various capabilities of the NEAR blockchain, using JavaScript/TypeScript.
+Each example highlights specific features and serves as a practical guide for developers.
+
+**[basic-updates](https://github.com/near/near-sdk-js/tree/documentation-improvements/examples/src/basic-updates)**<br />
+A simple smart contract that can make basic state updates.
+
+**[counter](https://github.com/near/near-sdk-js/tree/documentation-improvements/examples/src/counter)**<br />
+A simple smart contract that demonstrates state management by implementing a basic counter with increment and decrement functionalities.
+
+**[cross-contract](https://github.com/near/near-sdk-js/tree/documentation-improvements/examples/src/cross-contract)**<br />
+A smart contract that demonstrates how to perform cross-contract calls on the NEAR blockchain, including querying external contracts to manage on-chain interactions.
+
+**[fungible-token](https://github.com/near/near-sdk-js/tree/documentation-improvements/examples/src/fungible-token)**<br />
+Example implementation of a Fungible Token (FT) contract using the [near-contract-standards](https://github.com/near/near-sdk-js/tree/develop/packages/near-contract-standards), including `storage_management`.
+
+**[non-fungible-token](https://github.com/near/near-sdk-js/tree/documentation-improvements/examples/src/non-fungible-token)**<br />
+Example implementation of a Non-Fungible Token (NFT) contract using the [near-contract-standards](https://github.com/near/near-sdk-js/tree/develop/packages/near-contract-standards).
+
+**[programmatic-updates](https://github.com/near/near-sdk-js/tree/documentation-improvements/examples/src/programmatic-updates)**<br />
+Contracts showcasing how contracts can evolve while maintaining certain logic from previous versions.
+
+**[state-migration](https://github.com/near/near-sdk-js/tree/documentation-improvements/examples/src/state-migration)**<br />
+A smart contract that demonstrates how to handle state migration in a NEAR smart contract.
+
+**[status-message](https://github.com/near/near-sdk-js/tree/documentation-improvements/examples/src/status-message)**<br />
+Smart contracts that record the status messages of the accounts that call the contracts.
+
+## Contributing
+
+If you find any issues or have suggestions for improvement, feel free to open an issue or submit a pull request. Contributions are welcome!

examples/package.json

@@ -6,36 +6,36 @@
  "type": "module",
  "scripts": {
  "build": "run-s build:*",
- "build:status-message": "near-sdk-js build src/status-message.js build/status-message.wasm",
- "build:status-message-migrate-add-field": "near-sdk-js build src/status-message-migrate-add-field.js build/status-message-migrate-add-field.wasm",
- "build:status-message-borsh": "near-sdk-js build src/status-message-borsh.js build/status-message-borsh.wasm",
- "build:status-message-serialize-err": "near-sdk-js build src/status-message-serialize-err.js build/status-message-serialize-err.wasm",
- "build:status-message-deserialize-err": "near-sdk-js build src/status-message-deserialize-err.js build/status-message-deserialize-err.wasm",
+ "build:status-message": "near-sdk-js build src/status-message/status-message.js build/status-message.wasm",
+ "build:status-message-migrate-add-field": "near-sdk-js build src/status-message/status-message-migrate-add-field.js build/status-message-migrate-add-field.wasm",
+ "build:status-message-borsh": "near-sdk-js build src/status-message/status-message-borsh.js build/status-message-borsh.wasm",
+ "build:status-message-serialize-err": "near-sdk-js build src/status-message/status-message-serialize-err.js build/status-message-serialize-err.wasm",
+ "build:status-message-deserialize-err": "near-sdk-js build src/status-message/status-message-deserialize-err.js build/status-message-deserialize-err.wasm",
  "build:clean-state": "near-sdk-js build src/clean-state.js build/clean-state.wasm",
- "build:counter": "near-sdk-js build src/counter.js build/counter.wasm",
- "build:counter-lowlevel": "near-sdk-js build src/counter-lowlevel.js build/counter-lowlevel.wasm",
- "build:counter-ts": "near-sdk-js build src/counter.ts build/counter-ts.wasm",
- "build:cross-contract-call": "near-sdk-js build src/status-message.js build/status-message.wasm && near-sdk-js build src/cross-contract-call.js build/cross-contract-call.wasm",
- "build:cross-contract-call-ts": "near-sdk-js build src/status-message.js build/status-message.wasm && near-sdk-js build src/cross-contract-call.ts build/cross-contract-call-ts.wasm",
- "build:cross-contract-call-loop": "near-sdk-js build src/counter.js build/counter.wasm && near-sdk-js build src/cross-contract-call-loop.js build/cross-contract-call-loop.wasm",
- "build:fungible-token-lockable": "near-sdk-js build src/fungible-token-lockable.js build/fungible-token-lockable.wasm",
- "build:fungible-token": "near-sdk-js build src/fungible-token.ts build/fungible-token.wasm && near-sdk-js build src/fungible-token-helper.ts build/fungible-token-helper.wasm",
- "build:non-fungible-token": "near-sdk-js build src/non-fungible-token-receiver.js build/non-fungible-token-receiver.wasm && near-sdk-js build src/non-fungible-token.js build/non-fungible-token.wasm",
- "build:status-message-collections": "near-sdk-js build src/status-message-collections.js build/status-message-collections.wasm",
+ "build:counter": "near-sdk-js build src/counter/counter.js build/counter.wasm",
+ "build:counter-lowlevel": "near-sdk-js build src/counter/counter-lowlevel.js build/counter-lowlevel.wasm",
+ "build:counter-ts": "near-sdk-js build src/counter/counter.ts build/counter-ts.wasm",
+ "build:cross-contract-call": "near-sdk-js build src/status-message/status-message.js build/status-message.wasm && near-sdk-js build src/cross-contract-calls/cross-contract-call.js build/cross-contract-call.wasm",
+ "build:cross-contract-call-ts": "near-sdk-js build src/status-message/status-message.js build/status-message.wasm && near-sdk-js build src/cross-contract-calls/cross-contract-call.ts build/cross-contract-call-ts.wasm",
+ "build:cross-contract-call-loop": "near-sdk-js build src/counter/counter.js build/counter.wasm && near-sdk-js build src/cross-contract-calls/cross-contract-call-loop.js build/cross-contract-call-loop.wasm",
+ "build:fungible-token-lockable": "near-sdk-js build src/fungible-token/fungible-token-lockable.js build/fungible-token-lockable.wasm",
+ "build:fungible-token": "near-sdk-js build src/fungible-token/fungible-token.ts build/fungible-token.wasm && near-sdk-js build src/fungible-token/fungible-token-helper.ts build/fungible-token-helper.wasm",
+ "build:non-fungible-token": "near-sdk-js build src/non-fungible-token/non-fungible-token-receiver.js build/non-fungible-token-receiver.wasm && near-sdk-js build src/non-fungible-token/non-fungible-token.js build/non-fungible-token.wasm",
+ "build:status-message-collections": "near-sdk-js build src/status-message/status-message-collections.js build/status-message-collections.wasm",
  "build:parking-lot": "near-sdk-js build src/parking-lot.ts build/parking-lot.wasm",
- "build:programmatic-update": "near-sdk-js build src/programmatic-update-before.ts build/programmatic-update-before.wasm && near-sdk-js build src/programmatic-update-after.ts build/programmatic-update-after.wasm",
+ "build:programmatic-updates": "near-sdk-js build src/programmatic-updates/programmatic-update-before.ts build/programmatic-update-before.wasm && near-sdk-js build src/programmatic-updates/programmatic-update-after.ts build/programmatic-update-after.wasm",
  "build:nested-collections": "near-sdk-js build src/nested-collections.ts build/nested-collections.wasm",
  "build-nft": "run-s build:nft-*",
- "build:nft-contract": "near-sdk-js build src/standard-nft/my-nft.ts build/my-nft.wasm",
- "build:nft-receiver": "near-sdk-js build src/standard-nft/test-token-receiver.ts build/nft-receiver.wasm",
- "build:nft-approval-receiver": "near-sdk-js build src/standard-nft/test-approval-receiver.ts build/nft-approval-receiver.wasm",
- "build:ft": "near-sdk-js build src/standard-ft/my-ft.ts build/my-ft.wasm",
+ "build:nft-contract": "near-sdk-js build src/non-fungible-token/my-nft.ts build/my-nft.wasm",
+ "build:nft-receiver": "near-sdk-js build src/non-fungible-token/test-token-receiver.ts build/nft-receiver.wasm",
+ "build:nft-approval-receiver": "near-sdk-js build src/non-fungible-token/test-approval-receiver.ts build/nft-approval-receiver.wasm",
+ "build:ft": "near-sdk-js build src/fungible-token/my-ft.ts build/my-ft.wasm",
  "build:state-migration": "run-s build:state-migration:*",
- "build:state-migration:original": "near-sdk-js build src/state-migration-original.ts build/state-migration-original.wasm",
- "build:state-migration:new": "near-sdk-js build src/state-migration-new.ts build/state-migration-new.wasm",
+ "build:state-migration:original": "near-sdk-js build src/state-migration/state-migration-original.ts build/state-migration-original.wasm",
+ "build:state-migration:new": "near-sdk-js build src/state-migration/state-migration-new.ts build/state-migration-new.wasm",
  "build:status-deserialize-class": "near-sdk-js build src/status-deserialize-class.js build/status-deserialize-class.wasm",
- "build:basic-updates-base": "near-sdk-js build src/basic-updates-base.js build/basic-updates-base.wasm",
- "build:basic-updates-update": "near-sdk-js build src/basic-updates-update.js build/basic-updates-update.wasm",
+ "build:basic-updates-base": "near-sdk-js build src/basic-updates/basic-updates-base.js build/basic-updates-base.wasm",
+ "build:basic-updates-update": "near-sdk-js build src/basic-updates/basic-updates-update.js build/basic-updates-update.wasm",
  "test": "ava && pnpm test:counter-lowlevel && pnpm test:counter-ts",
  "test:nft": "ava __tests__/standard-nft/*",
  "test:ft": "ava __tests__/standard-ft/*",

examples/src/basic-updates-base.js → examples/src/basic-updates/basic-updates-base.js

@@ -3,12 +3,8 @@ import {
  call,
  view,
  near,
- migrate,
  Vector,
- assert,
- UnorderedMap,
- LookupSet,
- validateAccountId, ONE_NEAR
+ ONE_NEAR
 } from "near-sdk-js";
 
 const POINT_ONE = ONE_NEAR / 10000n;

examples/src/basic-updates-update.js → examples/src/basic-updates/basic-updates-update.js

@@ -1,6 +1,4 @@
-import {NearBindgen, call, view, near, migrate, Vector, assert, UnorderedMap, LookupSet, ONE_NEAR} from "near-sdk-js";
-import {MigrationDemo} from "../build/state-migration-new.js";
-import {Contract} from "../build/nested-collections.js";
+import {NearBindgen, call, view, near, migrate, Vector, assert, ONE_NEAR} from "near-sdk-js";
 
 const POINT_ONE = ONE_NEAR / 10000n;
 

examples/src/cross-contract-call.js → examples/src/cross-contract-calls/cross-contract-call.js

@@ -1,4 +1,4 @@
-import { NearBindgen, call, view, initialize, near, bytes } from "near-sdk-js";
+import { NearBindgen, call, view, initialize, near } from "near-sdk-js";
 
 @NearBindgen({ requireInit: true })
 export class OnCall {

examples/src/cross-contract-call.ts → examples/src/cross-contract-calls/cross-contract-call.ts

@@ -1,4 +1,4 @@
-import { NearBindgen, call, view, initialize, near, bytes } from "near-sdk-js";
+import { NearBindgen, call, view, initialize, near } from "near-sdk-js";
 
 @NearBindgen({ requireInit: true })
 export class OnCall {

examples/src/non-fungible-token.js → examples/src/non-fungible-token/non-fungible-token.js

@@ -5,7 +5,6 @@ import {
  initialize,
  near,
  LookupMap,
- bytes,
  assert,
 } from "near-sdk-js";
 

examples/src/state-migration-original.ts → examples/src/state-migration/state-migration-original.ts

@@ -1,4 +1,4 @@
-import { NearBindgen, view, near, migrate, call, Vector, assert } from 'near-sdk-js'
+import { NearBindgen, view, near, call, Vector } from 'near-sdk-js'
 import { AccountId } from 'near-sdk-js/lib/types'
 
 type Message = {

examples/src/status-message-migrate-add-field.js → examples/src/status-message/status-message-migrate-add-field.js

@@ -1,4 +1,4 @@
-import {NearBindgen, call, view, near, migrate, Vector, assert} from "near-sdk-js";
+import {NearBindgen, call, view, near, migrate, assert} from "near-sdk-js";
 
 class OldStatusMessage {
  constructor() {

near-sdk-js@2.0.0-diff-1.0.0.md

@@ -1,7 +1,7 @@
 # Breaking features diff from SDK 2.0.0 to 1.0.0
 ## borsh data de/serializer for contract state
 * using for: new contracts or migrate from a borsh serialized contract
-[example](https://github.com/near/near-sdk-js/blob/develop/examples/src/status-message-borsh.js)
+[example](https://github.com/near/near-sdk-js/blob/develop/examples/src/status-message/status-message-borsh.js)
 ```js
 @NearBindgen({
  serializer(statusMessage) {
@@ -34,7 +34,7 @@ export class StatusMessage {
 ## js contract migration with data fields
 ### example1
 * using for: contract state migrations
-* [example](https://github.com/near/near-sdk-js/blob/develop/examples/src/status-message-migrate-add-field.js)
+* [example](https://github.com/near/near-sdk-js/blob/develop/examples/src/status-message/status-message-migrate-add-field.js)
 ```js
 import {NearBindgen, call, view, near, migrate, Vector, assert} from "near-sdk-js";
 
@@ -65,7 +65,7 @@ export class StatusMessage {
 }
 ```
 ### example2
-* another migration example can be found in [test-basic-updates.ava.js](./examples/__tests__/test-basic-updates.ava.js) with [old state contract](./examples/src/basic-updates-base.js) and new [new state contract](./examples/src/basic-updates-update.js). 
+* another migration example can be found in [test-basic-updates.ava.js](./examples/__tests__/test-basic-updates.ava.js) with [old state contract](./examples/src/basic-updates/basic-updates-base.js) and new [new state contract](./examples/src/basic-updates/basic-updates-update.js). 
 with the test command in [examples directory](./examples):
 ```shell
 pnpm run test:basic-updates

packages/near-contract-standards/src/fungible_token/core_impl.ts

@@ -32,7 +32,7 @@ const ERR_TOTAL_SUPPLY_OVERFLOW: string = "Total supply overflow";
  * - StorageManager -- interface for NEP-145 for allocating storage per account. FungibleToken provides methods for it.
  * - AccountRegistrar -- interface for an account to register and unregister
  *
- * For example usage, see examples/src/standard-ft/src/my-ft.ts
+ * For example usage, see examples/src/fungible-token/my-ft.ts
  */
 export class FungibleToken implements FungibleTokenCore, StorageManagement, FungibleTokenResolver {
  // AccountID -> Account balance.