Skip to content

Update readme #54

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.

Sign up for GitHub

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

Open
gmarcos87 wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Update readme #54

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7b6a673
update readme
gmarcos87 Jan 24, 2020
5d98a81
break the lines to read improve reading in some
gmarcos87 Feb 5, 2020
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
125 changes: 66 additions & 59 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,85 +1,83 @@
# ssb-client v2
Create an [rpc connection](https://ssbc.github.io/scuttlebutt-protocol-guide/#rpc-protocol) to an
*[sbot](https://github.com/ssbc/scuttlebot)* instance. Here are some resources that can help you
understand how it works in a practical way:

[Scuttlebot](https://github.com/ssbc/scuttlebot) client.
* Tutorials using this library to create basic clients:
[ssb-client-basic](https://github.com/mixmix/ssb-client-basic)
* A simple command line wrapper around this library:
[ssb-client-cli](https://github.com/qypea/ssb-client-cli)

Create an [rpc connection](https://ssbc.github.io/scuttlebutt-protocol-guide/#rpc-protocol) to an sbot running locally.
## Table of contents
[Example](#example) | [Api](#api) | [License](#license)

## example
___

# Example

```js
var ssbClient = require('ssb-client')
var ssbKeys = require('ssb-keys')

// simplest usage, connect to localhost sbot
// this will cb with an error if an sbot server is not running
ssbClient(function (err, sbot) {
var keys = ssbKeys.loadOrCreateSync('./my-ssb-folder')
var config = { caps: { shs: '1KHLiKZvAvjbY1ziZEHMXawbCEIM6qwjCDm3VYRan/s=' }}

// This is the clearest and
// recommended way to use ssb-client
ssbClient(keys, config, function (err, sbot, config) {
// ...
})

// configuration:
var keys = ssbKeys.loadOrCreateSync('./app-private.key')
ssbClient(
keys, // optional, defaults to ~/.ssb/secret
{
host: 'localhost', // optional, defaults to localhost
port: 8008, // optional, defaults to 8008
key: keys.id, // optional, defaults to keys.id

caps: {
// random string for `appKey` in secret-handshake
shs: ''
},

// Optional muxrpc manifest. Defaults to manifest provided by server.
manifest: {}

},
function (err, sbot, config) {
// ...
}
)
```

* Tutorials using this library to create basic clients: [ssb-client-basic](https://github.com/mixmix/ssb-client-basic)
* A simple command line wrapper around this library: [ssb-client-cli](https://github.com/qypea/ssb-client-cli)

## api
# Api

### require('ssb-client') => createEasyClient
## ssbClient(cb): async
Makes things as "easy" as possible, by loading configuration and defaults. This is useful for scripts
but applications should specify the configuration.

#### createEasyClient(cb(err, sbot))

Create a connection to the local `ssb-server` instance, using the default keys.
Configuration and keys will be loaded from directory specified by `ssb_appname`.
(by default `~/.ssb`)
```js
var ssbClient = require('ssb-client')
ssbClient(function(err, sbot, config) {})
```
Create a connection to the local `ssb-server` instance, using the default keys and configuration. This
will be loaded from directory specified by `ssb_appname` (by default `~/.ssb`).

The manifest will be the manifest provided by that server.

Calling this without arguments is handy for scripts, but applications
should use the clearer apis.
Calling this without arguments is handy for scripts, but applications should use the clearer apis.

there is a legacy api, that makes things as "easy" as possible,
by loading configuration and defaults. This is useful for scripts
but applications should probably use
## ssbClient({ keys, config, manifest, remote } | keys | config | cb): async
There are several ways to call ssb-client. Many of them are shortcuts for advanced users and can
generate some confusion.

##### createCustomClient({keys, config, manifest, remote}, cb(err, sbot))
```js
var ssbClient = require('ssb-client')
var ssbKeys = require('ssb-keys')

Connect to a specific server with fixed settings. All fields are mandatory.
var keys = ssbKeys.loadOrCreateSync()
var config = { port: 4321 }

#### createLegacyClient(keys, opts, cb(err, sbot))
// With keys and config,
// config.caps are required
ssbClient(keys, config, function(err, sbot, config) {})

Connect to a client with some custom settings.
//Only with config
ssbClient(config, function(err, sbot, config) {})

opts supports the keys:
//Only with keys
ssbClient(keys, function(err, sbot, config) {})

* `remote` multiserver address to connect to
* `host, port, key` (legacy) if remote is not set, assemble address from host, port, key.
* `manifest` use a custom manifest.
// With keys and custom ssb_appname
ssbClient(keys, 'testnet', function(err, sbot, config) {})

If you need custom options, it's recommended to use the `createCustomClient` API
instead, but this is still provided for legacy support.
// Only with custom ssb_appname
ssbClient('testnet', function(err, sbot, config) {})

// This is the option that offers more customization
ssbClient({ keys, config, manifest, remote }, function(err, sbot, config) {})
```

## Parameters
### keys

See [ssb-keys](https://github.com/ssbc/ssb-keys). The keys look like this:
Expand All @@ -91,14 +89,23 @@ See [ssb-keys](https://github.com/ssbc/ssb-keys). The keys look like this:
curve: 'ed25519'
}
```
### config
You can use [`ssb-config`](https://github.com/ssbc/ssb-config) to generate a valid configuration.

### caps
`caps.shs` is a random string passed to [secret-handshake](https://github.com/auditdrivencrypto/secret-handshake#example). It determines which sbot you are able to connect to. It defaults to a magic string in this repo and also in [scuttlebot](https://github.com/ssbc/scuttlebot/blob/master/lib/ssb-cap.js)
No parameters are required except `config.caps.shs` if the call is `ssbClient(keys, config, cb)`.

```js
var appKey = Buffer.from(opts.caps.shs, 'base64')
```
`config.caps.shs` is a random string passed to
[secret-handshake](https://github.com/auditdrivencrypto/secret-handshake#example). It determines which
sbot you are able to connect to.

In all other cases the configuration used will be the result of merging the configuration declared and
the one founded in the application directory (~/.ssb in most cases).

If `config.manifest` is not defined, the manifest will be provided by the server.

### ssb_appname
Declares where to look for further config, where to read and write databases. Stores data in
~/.${appName}, defaults to ssb (so data in ~/.ssb).

## License

Expand Down