Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

WIP: Chore/new docs #370

Merged
merged 39 commits into from
Jun 12, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
39 commits
Select commit Hold shift + click to select a range
7f20ef0
Started reworking Docs
ricricucit Mar 7, 2019
b0ca385
improved table of content
ricricucit Mar 7, 2019
7d3e50a
issue with anchors
ricricucit Mar 7, 2019
93189e8
issue with anchors
ricricucit Mar 7, 2019
6088575
More docs + more standalone examples
ricricucit Apr 16, 2019
6190b49
more consistency and new TOC
ricricucit Apr 30, 2019
41c182c
fix issues link
ricricucit Apr 30, 2019
229b32a
Started reworking Docs
ricricucit Mar 7, 2019
b3a9004
improved table of content
ricricucit Mar 7, 2019
186ab18
issue with anchors
ricricucit Mar 7, 2019
0e4c16d
issue with anchors
ricricucit Mar 7, 2019
e621cae
More docs + more standalone examples
ricricucit Apr 16, 2019
f1b8d70
more consistency and new TOC
ricricucit Apr 30, 2019
6f29f29
fix issues link
ricricucit Apr 30, 2019
231735b
docs(SDK Docs): Updated SDK Docs including Quick Start and Examples
ricricucit May 17, 2019
c26dd15
Merge branch 'develop' of github.com:aeternity/aepp-sdk-js into chore…
ricricucit May 17, 2019
4e47871
merge remote counterpart
ricricucit May 17, 2019
7af7077
merge develop
ricricucit May 21, 2019
84567f2
started reworking docs as per https://hackmd.aepps.com/s/rygc6uZp4
ricricucit May 21, 2019
080d829
restructure existing docs as per https://hackmd.aepps.com/s/rygc6uZp4
ricricucit May 21, 2019
cdd7528
adjust releasing instructions
ricricucit May 21, 2019
c0351cd
Merge branch 'develop' into chore/new-docs
nduchak May 23, 2019
a50a776
Merge branch 'develop' of github.com:aeternity/aepp-sdk-js into chore…
ricricucit May 28, 2019
af2baa6
more Docs restructuring according to https://hackmd.aepps.com/s/rygc6…
ricricucit May 28, 2019
ef0dfa9
merge remote branch
ricricucit May 28, 2019
b71f31b
splitted guides into more files
ricricucit May 28, 2019
9293be1
removed emojis to allow anchor links in github
ricricucit May 28, 2019
cb44d77
making it pretty
ricricucit May 28, 2019
edbfeb5
typo
ricricucit May 28, 2019
3eb155d
typos
ricricucit May 28, 2019
d6f342c
auto-generated docs for NodeJS Examples in new folder
ricricucit May 28, 2019
4007425
Merge branch 'develop' of github.com:aeternity/aepp-sdk-js into chore…
ricricucit Jun 7, 2019
1e9c1a7
updated examples, examples doc and needed deps
ricricucit Jun 7, 2019
5e22f1c
copy correct lock file for CI
ricricucit Jun 7, 2019
0abf990
update node on CI
ricricucit Jun 7, 2019
763795d
testing node 11-slim after 12-slim failed
ricricucit Jun 7, 2019
20aec9d
updating package.json an all lock files
ricricucit Jun 7, 2019
8fe64a6
Merge branch 'develop' into chore/new-docs
nduchak Jun 12, 2019
c07d37d
Revert node version for CI
Jun 12, 2019
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Dockerfile.ci
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ FROM node:10.12.0
USER root

RUN curl -L https://github.com/docker/compose/releases/download/1.22.0/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose && chmod +x /usr/local/bin/docker-compose
COPY package.json shrinkwrap.yaml /
COPY package.json package-lock.json pnpm-lock.yaml /
RUN npm install
RUN ln -f -s /node_modules/.bin/* /usr/local/bin/
WORKDIR /app
140 changes: 52 additions & 88 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,135 +1,98 @@
# aepp-sdk
# [Æternity](https://aeternity.com/)'s Javascript SDK

[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
[![Build Status](https://ci.aepps.com/buildStatus/icon?job=aepp-sdk-js/develop)](https://ci.aepps.com/job/aepp-sdk-js/job/develop/)
[![npm](https://img.shields.io/npm/v/@aeternity/aepp-sdk.svg)](https://www.npmjs.com/package/@aeternity/aepp-sdk)
[![npm](https://img.shields.io/npm/l/@aeternity/aepp-sdk.svg)](https://www.npmjs.com/package/@aeternity/aepp-sdk)

JavaScript SDK for the revolutionary [æternity] blockchain, targeting the
[æternity node] implementation.
[æternity node] implementation. Aepp-sdk is [hosted on GitHub].

aepp-sdk is [hosted on GitHub].

![Concept Drawing of aepp-sdk][concept]

[concept]: concept.png "Concept Drawing of aepp-sdk"
[æternity]: https://aeternity.com/
[æternity node]: https://github.com/aeternity/aeternity
[hosted on GitHub]: https://github.com/aeternity/aepp-sdk-js

#### Disclaimer

This SDK is at an alpha stage where things easily can break. We aim to make our
alpha releases as stable as possible. Neverless it should not be taken as
production-ready. To catch up with the more edgy state of development please
This SDK is in continuos development where things can easily break, especially if you're not an officially released version. We aim to make all our
releases as stable as possible, neverless it should not be taken as
production-ready.

To catch up with the more edgy state of development please
check out the [develop branch].

[develop branch]: https://github.com/aeternity/aepp-sdk-js/tree/develop

## [Usage Documentation]

1. Add the latest `@aeternity/aepp-sdk` release from npmjs.com to your project using one of these commands
## Table of content
- [Æternity's Javascript SDK](#%C3%A6ternitys-javascript-sdk)
- [Disclaimer](#disclaimer)
- [Table of content](#table-of-content)
- [Quick Start](#quick-start)
- [1. Install the SDK](#1-install-the-sdk)
- [2. Import (a chosen Flavor)](#2-import-a-chosen-flavor)
- [3. Create an Account and get some _AEs_](#3-create-an-account-and-get-some-aes)
- [Guides & Examples](#guides--examples)
- [CLI - Command Line Client](#cli---command-line-client)
- [Contributing](#contributing)
- [Change Log](#change-log)
- [License](#license)

## Quick Start

### 1. Install the SDK
Add the latest `@aeternity/aepp-sdk` release from npmjs.com to your project using one of these commands

```bash
pnpm i @aeternity/aepp-sdk
# or
# install using npm...or yarn or pnpm
npm i @aeternity/aepp-sdk
# or
yarn add @aeternity/aepp-sdk
```

**Note:** To install a _Pre-Release_ (latest `beta` or `alpha` version) using on the latest Node version, you have to install the package appending the `@next` tag reference.
**Note:** To install a _Pre-Release_ (latest `beta` or `alpha` version) using on the latest Node version, you have to install the package appending the `@next` tag reference, or even use the `#` symbol and the Repo URL to install a version coming from a specific branch.
```bash
pnpm i @aeternity/aepp-sdk@next
# install the @next version of the SDK
npm i @aeternity/aepp-sdk@next
yarn add @aeternity/aepp-sdk@next

# install the #develop version of the SDK
npm i https://github.com/aeternity/aepp-sdk-js#develop
```

> Hint: You can also add a development version from GitHub by dropping the `@` and
> adding `#` and a branch name at the end, for example
> `pnpm i aeternity/aepp-sdk#develop`.
### 2. Import (a chosen Flavor)

2. Import the right flavor. For this example with get the `Universal` flavor, which contains all the features of the SDK:
Import the right [flavor](docs/usage.md). For this example with get the `Universal` flavor, which contains all the features of the SDK:

```js
import Ae from '@aeternity/aepp-sdk/es/ae/universal' // or any other flavor
import Ae from '@aeternity/aepp-sdk/es/ae/universal' // or other flavor
```

3. Create an instance and interact with it
### 3. Create an Account and get some _AEs_
You can do many more things now, but you'll probably have to start by:

```js
1. Create an account using the [💻 CLI](#cli---command-line-client)
2. Give yourself some initial _AEs_ using the [🚰 Faucet Aepp](https://faucet.aepps.com/)
3. Enjoy building Aepps 🤓

// Start the instance

Ae({
url: 'https://sdk-testnet.aepps.com',
internalUrl: 'https://sdk-testnet.aepps.com',
keypair: { secretKey: 'A_PRIV_KEY', publicKey: 'A_PUB_ADDRESS' },
networkId: 'aet_ua' // or any other networkId your client should connect to
}).then(ae => {

// Interacting with the blockchain client

// getting the latest block height
ae.height().then(height => {
// logs current height
console.log('height', height)
}).catch(e => {
// logs error
console.log(e)
})

// getting the balance of a public address
ae.balance('A_PUB_ADDRESS').then(balance => {
// logs current balance of "A_PUB_ADDRESS"
console.log('balance', balance)
}).catch(e => {
// logs error
console.log(e)
})
})
```
## Guides & Examples

4. **IMPORTANT:** 🤓 Check out the [Usage Documentation] to avoid common pitfalls!
Check out our [Guides](docs/README.md) and [Examples](examples/README.md).

[Usage Documentation]: docs/usage.md
## CLI - Command Line Client

To quickly test _all_ of Aeternity's blockchain features from your Terminal, you can Install and use our **NodeJS [CLI](https://github.com/aeternity/aepp-cli-js)** by running:

> Remember: you can also "compose" your own flavor by mixing 2 or more flavors likes so:
1. `npm i -g @aeternity/aepp-cli` to globally install the CLI
2. `aecly --help` to get a list of possible commands

```js
import Wallet from '@aeternity/aepp-sdk/es/ae/wallet.js'
import Contract from '@aeternity/aepp-sdk/es/ae/contract.js'
import MemoryAccount from '@aeternity/aepp-sdk/es/account/memory.js'

// make a "mixed flavor" containing Wallet and Contracts flavors
Wallet.compose(Contract)({
url: 'https://sdk-testnet.aepps.com',
internalUrl: 'https://sdk-testnet.aepps.com',
accounts: [MemoryAccount({keypair: {secretKey: account.priv, publicKey: account.pub}})],
address: account.pub,
onTx: true, // or a function to Guard the Rpc client
onChain: true, // or a function to Guard the Rpc client
onAccount: true, // or a function to Guard the Rpc client
networkId: 'ae_uat'
}).then(ae => {
// ae is your initialised client now! :)
// ...
```
## [Hacking]
_eg._ Create an Account:

For advanced use, development versions and to get a deeper understanding of the
SDK, it is advised to read the [Hacking] documentation.
`aecli account create testWhateverAccountName`

[Hacking]: docs/hacking.md
## Contributing

## [API]
For advanced use, to get a deeper understanding of the SDK or to contribute to its development, it is advised to read the [Contributing Guidelines](docs/contrib/README.md) section.

[API]: docs/api.md
## Change Log

## [Change Log]
[Change Log]: CHANGELOG.md
We keep our [Changelog](CHANGELOG.md) up to date.

## License

Expand All @@ -147,3 +110,4 @@ INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
THIS SOFTWARE.

Binary file removed concept.png
Binary file not shown.
46 changes: 46 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# Guides

## Intro
There are three different ways of incorporating aepp-sdk-js into your project, depending on the particular scenario:
* ES Modules at `es/` (recommended)
* Node.js bundle at `dist/aepp-sdk.js`
* Browser bundle at `dist/aepp-sdk.browser.js`

Also, please be aware that using `require` instead of module loader syntax
(`import`) means that the default export automatically becomes exposed as
`default`, which is reflected below in the code examples. This is due to a
recent change in [Babel] compilation and fully compliant with the standard.

### Flavors / Entry Points

The recommended approach to use aepp-sdk is to import one of the following _Ae
Factories_ based on the specific use case:

* [@aeternity/aepp-sdk/es/ae/wallet](api/ae/wallet.md): for **Wallet**'s focused development
* [@aeternity/aepp-sdk/es/ae/contract](api/ae/contract.md): for **Contract**'s focused development
* [@aeternity/aepp-sdk/es/ae/aepp](api/ae/aepp.md): for **Web Aepp**'s focused development ⚠️ **_No Wallet support_**
* [@aeternity/aepp-sdk/es/ae/aens](api/ae/aens.md): for **AENs**' focused development
* [@aeternity/aepp-sdk/es/ae/oracle](api/ae/oracle.md): for **Oracle**'s focused development
* [@aeternity/aepp-sdk/es/ae/universal](api/ae/universal.md): for **Universal** development (includes all SDK features)

In order to cater to more specific needs, it is recommended to refer to the
[contributing Docs](contrib/README.md).

### Testing Networks
When initialising a client, to test, you can use Aeternity's Test Nework URLs:

### Testnet (https://sdk-testnet.aepps.com)
You can use this URL with any releasee on [npmjs](https://www.npmjs.com/package/@aeternity/aepp-sdk). It offers the last stable version of [Node](https://github.com/aeternity/aeternity), used by all of of Aeternity's Dev Tools.

## Guides
### Browser
- [**SDK usage** Understanding low vs high level](guides/low-vs-high-usage.md)
- [Import SDK bundle with **`<script>`** tag](guides/import-script-tag.md)
- [Import SDK **ES Modules** (enabling Tree-Shaking)](guides/import-tree-shaking.md)
- [Import SDK in **VueJS**](guides/import-vuejs.md)
### NodeJS Environment
- [Import SDK in **NodeJS**](guides/import-nodejs.md)


## Examples
Check out our [Examples](../examples/README.md) for more.
2 changes: 2 additions & 0 deletions docs/api/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# ⚠️ Disclaimer
We're doing our best to keep the API documentation up to date, but [please let us know if you see some out-of-date file](https://github.com/aeternity/aepp-sdk-js/issues/new). Thanks!
1 change: 1 addition & 0 deletions docs/api/account.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
## @aeternity/aepp-sdk/es/account
Account module

**Export**: Account
**Example**
```js
import Account from '@aeternity/aepp-sdk/es/account'
Expand Down
1 change: 1 addition & 0 deletions docs/api/account/memory.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
## @aeternity/aepp-sdk/es/account/memory
Memory Account module

**Export**: MemoryAccount
**Example**
```js
import MemoryAccount from '@aeternity/aepp-sdk/es/account/memory'
Expand Down
1 change: 1 addition & 0 deletions docs/api/account/selector.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ Accounts Selector module

This is the complement to [@aeternity/aepp-sdk/es/accounts](#module_@aeternity/aepp-sdk/es/accounts).

**Export**: Account
**Example**
```js
import Selector from '@aeternity/aepp-sdk/es/account/selector'
Expand Down
1 change: 1 addition & 0 deletions docs/api/accounts.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
## @aeternity/aepp-sdk/es/accounts
Accounts module

**Export**: Accounts
**Example**
```js
import Accounts from '@aeternity/aepp-sdk/es/accounts'
Expand Down
1 change: 1 addition & 0 deletions docs/api/ae.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
## @aeternity/aepp-sdk/es/ae
Ae module

**Export**: Ae
**Example**
```js
import Ae from '@aeternity/aepp-sdk/es/ae'
Expand Down
1 change: 1 addition & 0 deletions docs/api/ae/aens.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ The high-level description of the naming system is
https://github.com/aeternity/protocol/blob/master/AENS.md in the protocol
repository.

**Export**: Aens
**Example**
```js
import Aens from '@aeternity/aepp-sdk/es/ae/aens'
Expand Down
1 change: 1 addition & 0 deletions docs/api/ae/aepp.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
## @aeternity/aepp-sdk/es/ae/aepp
Aepp module

**Export**: Aepp
**Example**
```js
import Ae from '@aeternity/aepp-sdk/es/ae/aepp'
Expand Down
1 change: 1 addition & 0 deletions docs/api/ae/contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ Contract module - routines to interact with the æternity contract
High level documentation of the contracts are available at
https://github.com/aeternity/protocol/tree/master/contracts and

**Export**: Contract
**Example**
```js
import Contract from '@aeternity/aepp-sdk/es/ae/contract' (Using tree-shaking)
Expand Down
1 change: 1 addition & 0 deletions docs/api/ae/oracle.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ The high-level description of the oracle system is
https://github.com/aeternity/protocol/blob/master/ORACLE.md in the protocol
repository.

**Export**: Oracle
**Example**
```js
import Oracle from '@aeternity/aepp-sdk/es/ae/oracle'
Expand Down
1 change: 1 addition & 0 deletions docs/api/ae/universal.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
## @aeternity/aepp-sdk/es/ae/universal
Universal module

**Export**: Universal
**Example**
```js
import Ae from '@aeternity/aepp-sdk/es/ae/universal'
Expand Down
1 change: 1 addition & 0 deletions docs/api/ae/wallet.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
## @aeternity/aepp-sdk/es/ae/wallet
Wallet module

**Export**: Wallet
**Example**
```js
import Wallet from '@aeternity/aepp-sdk/es/ae/wallet'
Expand Down
1 change: 1 addition & 0 deletions docs/api/chain.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
## @aeternity/aepp-sdk/es/chain
Chain module

**Export**: Chain
**Example**
```js
import Chain from '@aeternity/aepp-sdk/es/chain'
Expand Down
1 change: 1 addition & 0 deletions docs/api/chain/node.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ ChainNode module

This is the complement to [@aeternity/aepp-sdk/es/chain](#module_@aeternity/aepp-sdk/es/chain).

**Export**: ChainNode
**Example**
```js
import ChainNode from '@aeternity/aepp-sdk/es/chain/node'
Expand Down
1 change: 1 addition & 0 deletions docs/api/channel/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
## @aeternity/aepp-sdk/es/channel/index
Channel module

**Export**: Channel
**Example**
```js
import Channel from '@aeternity/aepp-sdk/es/channel/index'
Expand Down
1 change: 1 addition & 0 deletions docs/api/contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
## @aeternity/aepp-sdk/es/contract
Contract Base module

**Export**: Contract
**Example**
```js
import ContractBase from '@aeternity/aepp-sdk/es/contract'
Expand Down
3 changes: 3 additions & 0 deletions docs/api/contract/aci.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
## @aeternity/aepp-sdk/es/contract/aci
ContractACI module

**Export**: ContractACI
**Example**
```js
import ContractACI from '@aeternity/aepp-sdk/es/contract/aci'
Expand Down Expand Up @@ -69,6 +70,8 @@ Generate contract ACI object with predefined js methods for contract usage
| source | `String` | Contract source code |
| [options] | `Object` | Options object |
| [options.aci] | `Object` | Contract ACI |
| [options.contractAddress] | `Object` | Contract address |
| [options.opt] | `Object` | Contract options |

**Example**
```js
Expand Down
1 change: 1 addition & 0 deletions docs/api/contract/compiler.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ ContractCompilerAPI module

This is the complement to [@aeternity/aepp-sdk/es/contract](#module_@aeternity/aepp-sdk/es/contract).

**Export**: ContractCompilerAPI
**Example**
```js
import ContractCompilerAPI from '@aeternity/aepp-sdk/es/contract/compiler'
Expand Down
Loading