Update README and migration guide

BitskiCo · Feb 9, 2019 · 3a1e0f4 · 3a1e0f4
1 parent 9feb598
commit 3a1e0f4
Show file tree

Hide file tree

Showing 2 changed files with 57 additions and 4 deletions.
diff --git a/MIGRATING.md b/MIGRATING.md
@@ -1,3 +1,56 @@
+# Migrating from 0.3.x to 0.4.x
+
+Starting in version 0.4.x we switched OAuth libraries, offering us the ability to use refresh tokens, and providing an overall smaller package size. There are just a couple of changes needed to get your app working with this new version.
+
+## Updated callback script
+
+We had to make a couple of changes to our callback script. Please update your link to point at our new version:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/bitski@0.4.0/dist/callback.js"></script>
+```
+
+## Requesting scopes
+
+We made it slightly more obvious how to request custom scopes, and removed the old way. If you pass in custom scopes, make sure to include the "offline" scope as well, in order to receive refresh tokens.
+
+**Solution**:
+
+You can now pass in an array at the top level:
+
+```javascript
+import { Bitski } from 'bitski';
+const bitski = new Bitski('client-id', 'redirect-url', ['offline', 'email']);
+```
+
+## User object has been modified
+
+Our previous library had a different model for user. In most cases, you don't need to do anything with the user object, but if you were using it to get their user id, access token, or email address, you'll need to make a couple of changes.
+
+**Solution**:
+
+```javascript
+import { Bitski } from 'bitski';
+const bitski = new Bitski('client-id', 'redirect-url');
+// Access user id, or email address:
+const user = await bitski.getUser();
+const id = user.id // user id (previously user.profile.sub)
+const email = user.email // email (previously user.profile.email)
+
+// Get the access token
+const token = bitski.authProvider.tokenStore.currentToken;
+```
+
+## Silent renew has been removed
+
+Previously we renewed access tokens by using a silent login flow in a hidden iframe. This was never an ideal flow, and it has been replaced with refresh tokens. This shouldn't have any negative effects in your app unless you are using our library in a non-standard way.
+
+## Logger has been removed
+
+Our previous oauth library allowed you to pass in a logger object to get more context into what was happening in the oauth process. Our new library does not provide that option, so we have removed the `setLogger()` method.
+
+---
+
 # Migrating from 0.1.x to 0.2.x
 
 Version 0.2.x introduced some great improvements but has a few breaking changes. This guide will cover some tips for updating your code.

diff --git a/docs/README.md b/docs/README.md
@@ -4,7 +4,7 @@
 
 The official Bitski Javascript SDK for the browser. Bitski connects your DApp with a user, a wallet, and a connection to the Ethereum blockchain. We currently support mainnet, as well as Kovan and Rinkeby test networks.
 
-*Note: These docs are for version 0.2.x. Upgrading from 0.1.x? Please see our [Migration Guide](https://github.com/BitskiCo/bitski-js/tree/develop/MIGRATING.md)*
+*Note: These docs are for version 0.4.x. Upgrading from 0.3.x or earlier? Please see our [Migration Guide](https://github.com/BitskiCo/bitski-js/tree/develop/MIGRATING.md)*
 
 
 ### Packages
@@ -74,7 +74,7 @@ Alternatively you can add this script tag to your app’s `<head>`:
 
 ```html
 <script src="https://cdn.jsdelivr.net/gh/ethereum/web3.js@1.0.0-beta.33/dist/web3.min.js"></script>
-<script src="https://cdn.jsdelivr.net/npm/bitski@0.3.0/dist/bitski.bundle.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/bitski@0.4.0/dist/bitski.min.js"></script>
 ```
 
 ### Starting the SDK
@@ -134,7 +134,7 @@ First, check the login status to see if you need to sign in or if the user is al
 There are 3 possible values:
 
 - *Connected*: The user has an active access token. No action is needed.
-- *Expired*: The user has previously logged in but does not have an access token.
+- *Expired*: The user is signed in but does not have a current access token
 - *NotConnected*: The user has not signed in before.
 
 If the status is Expired or NotConnected, you need to call either `start()` or `signIn()` to use wallet features.
@@ -160,7 +160,7 @@ import { Bitski } from 'bitski';
 Bitski.callback();
 ```
 
-_Note: The access token will be passed as a hash on the url (ie. #token=blah), which may conflict with existing hash-based navigation your app may be doing._
+_Note: The access token may be passed as a hash on the url (ie. #token=blah), which may conflict with existing hash-based navigation your app may be doing._
 
 
 #### Triggering sign in