Merge pull request #19 from CheesecakeLabs/documentation

Documentation

.npmignore

@@ -11,6 +11,7 @@ yarn-error.log
 src/
 tests/
 coverage/
+docs/
 
 # Various IDEs and editors
 .idea/
@@ -30,4 +31,4 @@ Thumbs.db
 #root files
 .github/
 nodemon.json
-tsconfig.json
+tsconfig.json

README.md

@@ -1 +1,44 @@
-# Stellar-Plus
+
+# Stellar-Plus
+
+stellar-plus is an all-in-one Javascript library for building and interacting with the Stellar network. It bundles the main resources from the community into an easy-to-use set of tools and capabilities.
+
+It provides:
+
+* **Account**: Handlers to create, load, and interact with stellar accounts, managing signatures and automatically integrating with Freighter Wallet for web applications.
+* **Asset**: Classic token handlers follow the standard token interface for triggering different asset capabilities as well as a suite of additional features for asset management and usage.
+* **Core**: Key engines for managing the different pipelines for building, submitting, and processing both Classic and Soroban transactions. These engines can be extended into your own tooling or used out-of-the-box with minimal configuration.
+* **Contracts**: Default contract client implementations for selected dApp use cases.
+* **RPC**: Handlers for connecting and using different RPC solutions, including a ready-to-use integration with Validation Cloud's RPC API.
+
+## Quick start
+
+Using npm to include js-stellar-plus in your own project:
+
+```shell
+npm install --save stellar-plus
+```
+
+## Install
+
+Install it using npm:
+
+```shell
+npm install --save stellar-plus
+```
+
+require/import it in your JavaScript:
+
+```js
+var StellarPlus = require("stellar-plus");
+```
+
+or
+
+```js
+import { StellarPlus } from "stellar-plus";
+```
+
+## Documentation
+
+For the full documentation, refer to our [Gitbook Documentation](https://cheesecake-labs.gitbook.io/stellar-plus/).

docs/README.md

@@ -0,0 +1,27 @@
+---
+layout:
+  title:
+    visible: true
+  description:
+    visible: true
+  tableOfContents:
+    visible: true
+  outline:
+    visible: true
+  pagination:
+    visible: true
+---
+
+# Welcome
+
+## Stellar-Plus
+
+stellar-plus is an all-in-one Javascript library for building and interacting with the Stellar network. It bundles the main resources from the community into an easy-to-use set of tools and capabilities.
+
+It provides:
+
+* **Account**: Handlers to create, load, and interact with stellar accounts, managing signatures and automatically integrating with **Freighter Wallet** for web applications.
+* **Asset**: Classic token handlers follow the standard token interface for triggering different asset capabilities as well as a suite of additional features for asset management and usage.
+* **Core**: Key engines for managing the different pipelines for building, submitting, and processing both Classic and Soroban transactions. These engines can be extended into your own tooling or used out-of-the-box with minimal configuration.
+* **Contracts**: Default contract client implementations for selected dApp use cases.
+* **RPC**: Handlers for connecting and using different RPC solutions, including a ready-to-use integration with **Validation Cloud's RPC API**.

docs/SUMMARY.md

@@ -0,0 +1,13 @@
+# Table of contents
+
+* [Welcome](README.md)
+* [Quick Start](quick-start.md)
+
+## 📄 Reference
+
+* [Account](reference/account/README.md)
+  * [Base](reference/account/base.md)
+  * [Default Account Handler](reference/account/default-account-handler.md)
+  * [Freighter Account Handler](reference/account/freighter-account-handler.md)
+  * [Helpers](reference/account/helpers/README.md)
+    * [Friendbot](reference/account/helpers/friendbot.md)

docs/quick-start.md

@@ -0,0 +1,31 @@
+# Quick Start
+
+
+
+Using npm to include js-stellar-plus in your own project:
+
+```shell
+npm install --save stellar-plus
+```
+
+## Install
+
+Install it using npm:
+
+```shell
+npm install --save stellar-plus
+```
+
+require/import it in your JavaScript:
+
+```js
+var StellarPlus = require("stellar-plus");
+```
+
+or
+
+```js
+import { StellarPlus } from "stellar-plus";
+```
+
+##

docs/reference/account/README.md

@@ -0,0 +1,22 @@
+---
+description: Initialize, manage and interact with Stellar accounts.
+---
+
+# Account
+
+Accounts in Stellar Plus are represented in a few different ways that abstract the complexity of managing Stellar keypairs and signing capabilities, integrating directly with the transaction pipeline in a seamless way.  They can be categorized as the following:
+
+
+
+* **Base:** The simplest representation of an account, it is initialized by a 'Public Key' string. Cannot perform any changes or approve transactions.
+* **Account Handler:** Management representation of an account, can sign and authorize transactions for a given account. These can be extended to implement custom key management pipelines that integrate directly with the library capabilities.
+
+
+
+
+
+{% hint style="info" %}
+Tip: Depending on the arguments provided when initializing an Account, extra helpers will be made available in the instance of that account. See[helpers](helpers/ "mention") for further information.
+{% endhint %}
+
+ 

docs/reference/account/base.md

@@ -0,0 +1,18 @@
+# Base
+
+The simplest representation of an account, it's initialized by a 'Public Key' string. Cannot perform any changes or approve transactions.
+
+
+
+### How to use
+
+'Base' accounts can be initialized by simply generating a new instance and passing a `publicKey` within an object as the main argument.
+
+{% code overflow="wrap" lineNumbers="true" fullWidth="false" %}
+```typescript
+const myAccount = new StellarPlus.Account.Base({publicKey: "GB4ILVTI56I4XFHCJENY4JO4V7XHFEZCF63SEPIA3MIIQQRMNHQ7TQNQ"})
+```
+{% endcode %}
+
+
+

docs/reference/account/default-account-handler.md

@@ -0,0 +1,40 @@
+---
+description: Initiate and manage an account directly through its secret key.
+---
+
+# Default Account Handler
+
+Extending the 'AccountHandler', the '**DefaultAccountHandler'** class allows for an account to be loaded through its secret key, enabling its management capabilities. This account can then be used in transaction invocation as a 'signer' parameter to integrate into the transactions pipeline.
+
+
+
+### How to use
+
+There are a few different options to initialize an account with the Default account that can be used depending on the use case.
+
+
+
+#### Initializing with the secret key
+
+The main way of initializing a default account handler is by providing its secret key to an object during the instantiation of the class as the following:
+
+{% code overflow="wrap" lineNumbers="true" %}
+```typescript
+const myAccount = new StellarPlus.Account.DefaultAccountHandler({secretKey:"SCGCPZYE24NMPOXAH3E3VZMMN4AIQSCXPN4K6MWZ7FLYVA57H26C5NWY”})
+```
+{% endcode %}
+
+This is used when you already have an existing account and want to handle it after loading it secret key from a different source.
+
+#### Initializing a new account
+
+Whenever the default account handler is instantiated without providing a secret key, it automatically generates a new random keypair and uses it.
+
+{% code overflow="wrap" lineNumbers="true" %}
+```typescript
+const myAccount = new StellarPlus.Account.DefaultAccountHandler({})
+```
+{% endcode %}
+
+When using this option, be aware that the keys are merely generated locally, the account still won't exist in the Stellar network until a 'create account' operation is performed. For this, when using test networks that have a Friendbot, one can make use of the 'Friendbot' helper for Accounts to initialize the account with some lumens funds. Refer to the article [friendbot.md](helpers/friendbot.md "mention") for more detail.
+

docs/reference/account/freighter-account-handler.md

@@ -0,0 +1,105 @@
+---
+description: Initiate and manage an account directly through its secret key.
+---
+
+# Freighter Account Handler
+
+Extending the 'AccountHandler', the '**FreighterAccountHandler'** class allows for an account to be loaded and managed through direct integration with a [Freighter wallet](https://www.freighter.app/).  This account can then be used in transaction invocation as a 'signer' parameter to integrate into the transactions pipeline, triggering the Freighter application automatically when a signature is necessary.
+
+{% hint style="info" %}
+**Important:** Freighter is a browser extension, therefore this integration can only be used for web applications.
+{% endhint %}
+
+### How to use
+
+The way of initializing a Freighter account handler is by providing a 'network' object during the instantiation of the class as the following:
+
+{% code overflow="wrap" lineNumbers="true" %}
+```typescript
+const selectedNetwork = StellarPlus.Constants.testnet
+const myAccount = new StellarPlus.Account.FreighterAccHandler({network:selectedNetwork})
+```
+{% endcode %}
+
+The network is used to connect and lock this instance to a specific target network and avoid accidentally triggering signatures to the wrong one.
+
+#### Connecting
+
+Once the object is installed, it'll provide several functions to verify and connect to the Freighter account in the browser. One can use the individual functions to verify the extension state or simply use the method `Connect()` that already performs all necessary validations and triggers the connection.
+
+{% code overflow="wrap" lineNumbers="true" %}
+```typescript
+await myAccount.connect()
+console.log(myAccount.publicKey)
+```
+{% endcode %}
+
+
+
+### Public Methods
+
+#### getPublicKey
+
+* **Returns**: `string` - The public key associated with the connected Freighter account.
+* **Description**:
+  * Retrieves the public key. If the public key is not already set, it triggers a connection to Freighter.
+
+#### connect
+
+* **Parameters**:
+  * `onPublicKeyReceived?: FreighterCallback` - Optional callback function to execute after receiving the public key.
+* **Returns**: `Promise<void>`
+* **Description**:
+  * Initiates a connection to Freighter and retrieves the public key, executing the provided callback upon success. The public key is also updated in the instance of the class to be used in the future.
+
+#### disconnect
+
+* **Returns**: `void`
+* **Description**:
+  * Disconnects from Freighter by resetting the public key to an empty string.
+
+#### loadPublicKey
+
+* **Parameters**:
+  * `onPublicKeyReceived?: FreighterCallback` - Optional callback function to execute after receiving the public key.
+  * `enforceConnection?: boolean` - Flag to enforce connection verification and initiation.
+* **Returns**: `Promise<void>`
+* **Description**:
+  * Obtains the public key from Freighter, optionally enforcing connection if not already established, and executes the callback with the public key.
+
+#### sign
+
+* **Parameters**:
+  * `tx: Transaction` - The transaction to be signed.
+* **Returns**: `Promise<string>` - The signed transaction in XDR format.
+* **Description**:
+  * Signs a given transaction using Freighter, ensuring that the Freighter is connected and authorized. Throws an error if unable to sign.
+
+#### isFreighterConnected
+
+* **Parameters**:
+  * `enforceConnection?: boolean` - Flag to enforce connection if not already established.
+  * `callback?: FreighterCallback` - Optional callback to execute after successful connection.
+* **Returns**: `Promise<boolean>` - Indicates whether the Freighter connection is established.
+* **Description**:
+  * Verifies if Freighter is connected and authorized for the current application and network, optionally enforcing connection and executing a callback upon success.
+
+#### isFreighterInstalled
+
+* **Returns**: `Promise<boolean>` - Indicates whether the Freighter extension is installed.
+* **Description**:
+  * Checks if the Freighter browser extension is installed.
+
+#### isApplicationAuthorized
+
+* **Returns**: `Promise<boolean>` - Indicates whether the application is authorized to connect to Freighter.
+* **Description**:
+  * Verifies if the current application is authorized to access the Freighter account.
+
+#### isNetworkCorrect
+
+* **Returns**: `Promise<boolean>` - Indicates whether the network selected in Freighter matches the one in the handler.
+* **Description**:
+  * Validates if the network passphrase in Freighter matches the one expected by the handler, ensuring network alignment.
+
+\

docs/reference/account/helpers/README.md

@@ -0,0 +1,28 @@
+# Helpers
+
+Whenever initializing accounts, one will have the option of adding optional arguments that can trigger additional helpers to be added to the account's instance. These helpers extend the capabilities of the account instance with utility functions that can be o assistance to many different use cases.
+
+
+
+E.g.  Initiating an account as a [default-account-handler.md](../default-account-handler.md "mention")and adding a network to use friendbot and creating the account on-chain.
+
+{% code overflow="wrap" lineNumbers="true" %}
+```typescript
+// Select a test network that has a Friendbot Url configured
+const selectedNetwork = StellarPlus.Constants.testnet
+
+// Instantiate the account with the extra network argument
+const myAccount = new StellarPlus.Account.DefaultAccountHandler({secretKey:"SCGCPZYE24NMPOXAH3E3VZMMN4AIQSCXPN4K6MWZ7FLYVA57H26C5NWY”, network:selectedNetwork})
+
+// Triggering Friendbot to create the account on chain an fund it.
+myAccount.Friendbot.initialize()
+```
+{% endcode %}
+
+
+
+### Account Helpers List
+
+{% content-ref url="friendbot.md" %}
+[friendbot.md](friendbot.md)
+{% endcontent-ref %}

docs/reference/account/helpers/friendbot.md

@@ -0,0 +1,14 @@
+# Friendbot
+
+
+
+**Prerequisites:**
+
+* The account instance must have been initialized with a 'network' argument.
+* the network provided must not be the mainnet.
+
+
+
+### **Features**
+
+* **Initialize:** Useful for accounts that haven't been created in a test network yet, the initialize feature will automatically trigger the Friendbot for the provided network based on the `friendbotUrl` present in the network object. This will trigger the on-chain account creation and fund with it with lumens.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "stellar-plus",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "beta version of stellar-plus, an all-in-one sdk for the Stellar blockchain",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",