feat: better readme docs

packages/auth/README.md

@@ -1,6 +1,8 @@
 # @stacks/auth
 
-Construct and decode authentication requests for Stacks apps.
+Construct and decode authentication requests for Stacks apps. 
+
+This package provides the auth logic used by the [Stacks Connect](https://github.com/blockstack/ux/tree/master/packages/connect) library. If you're looking to integrate Stacks authentication into your web app, Stacks Connect provides a simple API and built-in user interface. See the [authentication tutorial](https://docs.blockstack.org/authentication/building-todo-app). 
 
 ## Installation
 
@@ -10,4 +12,97 @@ npm install @stacks/auth
 
 ## Usage
 
-See [documentation](https://docs.blockstack.org/authentication/building-todo-app)
+### Generating an authentication request
+
+```typescript
+import { UserSession, makeAuthRequest, AppConfig } from '@stacks/auth'
+```
+
+The app domain is the URL to your website/app. This is how the Stacks authentication system identifies apps and determines what credentials to provide. Changing the app domain is equivalent to changing the app. Note that you also need to have a valid manifest.json file at the domain.
+
+```typescript
+const appDomain = 'https://www.myapp.com';
+```
+
+Next we set the basic permissions for your app to read and store user data. If your app will allow users to share data with other users, you will need an additional `publish_data` permission. We will also initiate a `UserSession` object using the configuration.
+
+```typescript
+const appConfig = new AppConfig(['store_write'], appDomain);
+const userSession = new UserSession({ appConfig });
+```
+
+The authentication payloads are encrypted during transit, the encryption key generated below provides this
+
+```typescript
+const transitKey = userSession.generateAndStoreTransitKey();
+```
+
+The Stacks auth process will open a compatible Stacks authenticator or browser extension to perform the authentication. So you will need to provide a redirect URL which the authenticator or extension can redirect to with the authentication payload. This page should process the authentication payload. 
+
+```typescript
+const redirectUri = 'https://www.myapp.com/auth';
+```
+
+Set the location of your app manifest file. This file contains information about your app that is shown to the user during authentication.
+
+```typescript
+const manifestUri = 'https://www.myapp.com/manifest.json';
+```
+
+Finally generate the authentication request payload:
+
+```typescript
+const authRequest = userSession.makeAuthRequest(
+  transitKey,
+  redirectUri,
+  manifestUri
+);
+```
+
+The resulting payload can now be passed to a compatible Stacks authenticator or browser extension. If you are using Stacks connect, this is performed automatically. 
+
+If you would like to implement a Stacks authenticator, check out the reference implementation of the [Stacks browser extension](https://github.com/blockstack/ux/tree/master/packages/app).
+
+### Handling an authentication response payload
+
+After an authenticator has processed your app's request, and the user has granted permission, the resulting response will be passed back to your app via the URL set in your `redirectUri`.
+
+Below, we use `userSession.isSignInPending` to determine if there is an incoming authentication response. If detected, the `userSession.handlePendingSignIn` method will process the response and provide a `userData` object containing the user's identity, BNS username and profile information.
+
+```typescript
+if (userSession.isSignInPending()) {
+  userSession.handlePendingSignIn().then((userData) => {
+    // Do something with userData
+  });
+}
+```
+
+### Checking if the user is signed in
+
+Use the `userSession.isUserSignedIn` method to check if the user is already authenticated. If so, we can retrieve the user's profile data using `userSession.loadUserData`.
+
+```typescript
+if (userSession.isUserSignedIn()) {
+  const userData = userSession.loadUserData();
+}
+```
+
+### Sign out
+
+To sign the user out simply call the `userSession.signUserOut` method.
+
+```typescript
+userSession.signUserOut();
+```
+
+### Data encryption
+
+Stacks authentication also provides an easy way to encrypt the user's data. If you are using the [`@stacks/storage`](https://github.com/blockstack/stacks.js/tree/master/packages/storage) package, encryption is automatically enabled. If you would like to perform encryption outside of storage you can use the `userSession.encryptContent` and `userSession.decryptContent` methods.
+
+```typescript
+const message = 'My secret message';
+const cipherText = await userSession.encryptContent(message);
+const plainText = await userSession.decryptContent(cipherText);
+```
+
+Note that encryption here uses the user's private key associated with your app only. If you need to share this data with another app or other users, you should use the equivalent methods from `@stacks/encryption` and provide a custom private key.

packages/cli/README.md

@@ -10,4 +10,4 @@ npm install @stacks/cli
 
 ## Usage
 
-See [documentation](https://docs.blockstack.org/references/blockstack-cli)
+See [documentation](https://docs.blockstack.org/references/stacks-cli)

packages/network/README.md

@@ -7,3 +7,67 @@ Network and API library for working with Stacks blockchain nodes.
 ```
 npm install @stacks/network
 ```
+
+## Usage
+
+Creating a Stacks mainnet, testnet or mocknet network
+
+```typescript
+import { StacksMainnet, StacksTestnet, StacksMocknet } from '@stacks/network';
+
+const network = new StacksMainnet();
+
+const testnet = new StacksTestnet();
+
+const mocknet = new StacksMocknet();
+```
+
+Setting a custom node URL
+
+```typescript
+network.coreApiUrl = 'https://www.mystacksnode.com/';
+```
+
+Check if network is mainnet
+
+```typescript
+const isMainnet = network.isMainnet();
+```
+
+Example usage in transaction builder
+
+```typescript
+import { makeSTXTokenTransfer } from '@stacks/transactions';
+
+const txOptions = {
+  network,
+  recipient: 'SP2BS6HD7TN34V8Z5BNF8Q2AW3K8K2DPV4264CF26',
+  amount: new BigNum(12345),
+  senderKey: 'b244296d5907de9864c0b0d51f98a13c52890be0404e83f273144cd5b9960eed01',
+};
+
+const transaction = await makeSTXTokenTransfer(txOptions);
+```
+
+Get various API URLs
+
+```typescript
+  const txBroadcastUrl = network.getBroadcastApiUrl();
+
+  const feeEstimateUrl = network.getTransferFeeEstimateApiUrl();
+
+  const address = 'SP2BS6HD7TN34V8Z5BNF8Q2AW3K8K2DPV4264CF26';
+  const accountInfoUrl = network.getAccountApiUrl(address);
+
+  const contractName = 'hello_world';
+  const abiUrl = network.getAbiApiUrl(address, contractName);
+
+  const functionName = 'hello';
+  const readOnlyFunctionCallUrl = network.getReadOnlyFunctionCallApiUrl(address, contractName, functionName);
+
+  const nodeInfoUrl = network.getInfoUrl();
+
+  const blockTimeUrl = network.getBlockTimeInfoUrl();
+
+  const poxInfoUrl = network.getPoxInfoUrl();
+```

packages/storage/README.md

@@ -7,3 +7,104 @@ Store and fetch files with Gaia, the decentralized storage system.
 ```
 npm install @stacks/storage
 ```
+
+## Usage
+
+### Initiating a storage client
+
+```typescript
+import { UserSession } from '@stacks/auth';
+import { Storage } from '@stacks/storage';
+
+const appConfig = new AppConfig();
+const userSession = new UserSession({ appConfig });
+const storage = new Storage({ userSession });
+```
+
+Note that you can also use an existing `userSession` object created during the authentication process.
+
+### Put file
+
+```typescript
+const myData = JSON.stringify({
+  hello: "world",
+  num: 1
+});
+
+storage.putFile('my_data.json', myData));
+```
+
+Store data at a different path
+
+```typescript
+storage.putFile('path/my_data.json', myData));
+```
+
+Put file with options
+
+```typescript
+const putFileOptions = {
+  // override the default content type
+  contentType: 'application/json', 
+  // override encrypting data by default
+  // you can also set encrypt to a private key to specify a custom encryption key
+  encrypt: false, 
+  // ignore automatic conflict prevention using etags
+  dangerouslyIgnoreEtag: true
+}
+
+storage.putFile('my_data.json', myData, putFileOptions));
+```
+
+### Get file
+
+```typescript
+storage.getFile('my_data.json').then((fileContent) => {
+  console.log(fileContent);
+});
+```
+
+Get file with options
+
+```typescript
+const getFileOptions = {
+  decrypt: false,
+  // by default files stored are signed and can be verified for authenticity
+  verify: false
+}
+
+storage.getFile('my_data.json', getFileOptions).then((fileContent) => {
+  console.log(fileContent);
+});
+```
+
+### Delete file
+
+```typescript
+storage.deleteFile('my_data.json');
+```
+
+Delete the file and the corresponding signature file if signed
+
+```typescript
+storage.deleteFile('my_data.json', { wasSigned: true });
+```
+
+### List file
+
+List all files in the user's Gaia hub
+
+```typescript
+storage.listFiles((filename) => {
+  if (filename === 'my_data.json') {
+    return storage.getFile(filename).then((fileContent) => {
+      console.log(fileContent);
+      // return false to stop iterating through files
+      return false;
+    })
+  } else {
+    // return true to continue iterating
+    return true;
+  }
+});
+```