diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f5ed2c2f..e9de4a2c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,7 +9,7 @@ To view the contribution guide, go to the main 3box repo here: - [ ] Add release notes and update version in package.json - [ ] Run `$ npm run generate-readme` - [ ] Make sure correct dependencies are installed and that tests and builds pass -- [ ] Create release branch `release/vX.X.X` +- [ ] Create release branch `release/X.X.X` - [ ] Make a commit `$ git commit -m "Release vX.X.X"` and make a PR to `master` - [ ] Get at least one review and merge - [ ] Checkout `master` locally diff --git a/README.md b/README.md index 25ca230a..3ea607d7 100644 --- a/README.md +++ b/README.md @@ -51,16 +51,24 @@ console.log(profile) ``` ### Update (get, set, remove) public and private profile data -3Box allows applications to create, read, update, and delete public and private data stored in a user's 3Box. To enable this functionality, applications must first open the user's 3Box by calling the openBox method. This method prompts the user to authenticate (sign-in) to your dapp and returns a promise with a threeBox instance. You can only update (set, get, remove) data for users that have authenticated to and are currently interacting with your dapp. Below `ethereumProvider` refers to the object that you would get from `web3.currentProvider`, or `window.ethereum`. +3Box allows applications to create, read, update, and delete public and private data stored in a user's 3Box. To enable this functionality, applications must first authenticate the user's 3Box by calling the `auth` method. This method prompts the user to authenticate (sign-in) to your dapp and returns a promise with a threeBox instance. You can only update (set, get, remove) data for users that have authenticated to and are currently interacting with your dapp. Below `ethereumProvider` refers to the object that you would get from `web3.currentProvider`, or `window.ethereum`. -#### 1. Authenticate users to begin new 3Box session -Calling the openBox method will open a new 3Box session. If the user's ethereum address already has a 3Box account, your application will gain access to it. If the user does not have an existing 3Box account, this method will automatically create one for them in the background. +#### 1. Create a 3Box instance +To create a 3Box session you call the `create` method. This creates an instance of the Box class which can be used to joinThreads and authenticate the user in any order. In order to create a 3Box session a `provider` needs to be passed. This can be an `ethereum provider` (from `web3.currentProvider`, or `window.ethereum`) or a `3ID Provider` (from [IdentityWallet](https://github.com/3box/identity-wallet-js)). ```js -const box = await Box.openBox('0x12345abcde', ethereumProvider) +const box = await Box.create(provider) ``` -#### 2. Sync user's available 3Box data from the network -When you first open the box in your dapp all data might not be synced from the network yet. You should therefore wait for the data to be fully synced. To do this you can simply await the `box.syncDone` promise: +#### 2. Authenticate user +Calling the `auth` method will authenticate the user. If you want to authenticate the user to one or multiple spaces you can specify this here. If when you created the 3Box session you used an ethereum provider you need to pass an ethereum address to the `auth` method. If the user does not have an existing 3Box account, this method will automatically create one for them in the background. +```js +const address = '0x12345abcde' +const spaces = ['myDapp'] +await box.auth(spaces, { address }) +``` + +#### 3. Sync user's available 3Box data from the network +When you first authenticate the box in your dapp all data might not be synced from the network yet. You should therefore wait for the data to be fully synced. To do this you can simply await the `box.syncDone` promise: ```js await box.syncDone ``` @@ -104,6 +112,14 @@ const privateValues = ['xxx', 'yyy'] await box.private.setMultiple(privateFields, privateValues) ``` +##### Open a thread +Once you have created a 3Box session you can open a thread to view data in it. This can be done before you authenticate the user to be able to post in the thread. +When opening a thread the moderation options need to be given. You can pass `firstModerator`, a 3ID (or ethereum address) of the first moderator, and a `members` boolean which indicates if it is a members thread or not. +```js +const thread = await box.openThread('myDapp', 'myThread', { firstModerator: 'did:3:bafy...', members: true }) +``` + +