byod-app

BYOD App

Developer toolset for building a client-side BYOD app for the BYOD ecosystem.

Docs

bapp.json

• name: The name of your app.
• avatar: A url or path to your app's image avatar logo.
• description: A short description of what your app does (255 chars max, markdown accepted).
• categoryIcon: An icon name from this list

Authorizing your BYOD App

Your app needs permissiot before reading and/or writing data to a user's home server.

Token Tips:

• BYOD Apps as OAuth clients don't have client secrets. If you're using HTTP Basic Auth, just repeat your client id as the password.
• HTTP Basic Auth cannot contain colons in the username. If your client id has a port (e.g. example.com:8080), then you must include client_id in the request body instead.

API

Once you have an access token, you can use the following API:

Session API

The session API takes care of most of the sign-in logic for your bapp. Here's what you need to know:

//
// Verifies current session / access_token.
//
byod.autoInit()


//
// If the user is not signed in, then you need to
// ask them for their BYOD email and then
// redirect them to this url...
//
var BAPP_HOST = 'localhost:9080' // Your app's host
byod.oauthUrl({
  byod_email: userEmail,
  client_id: BAPP_HOST,
  redirect_uri: 'http://' + BAPP_HOST + window.location.pathname,
  scope: BAPP_HOST,
})
//
// ...and make sure this code is also your returning page.
// It checks for oauth success data, which is important after
// the user is redirected back to your bapp.
//
var query = byod.parseQueryString(window.location.search.substring(1))

if ( query.code ) {
  byod.handleAuthSuccess(query.code, query.state).then(function () {
    console.log("BYOD is ready!", byod.session)
  })
}


//
// If the user IS signed in, then
// this will eventually be true
//
byod.ready //=> true or false

//
// Once ready, the session object becomes available...
//
byod.session.username //=> String
byod.session.email //=> String
byod.session.avatar_url //=> String
byod.session.scope //=> Array<String>

//
// ...and you get access to cool APIs!
//
byod.pv // Path-Value API

Path-Value API

The Path-Value API allows you to store data via a folder-like interface. This not only allows for efficient key-value usage, but also for retrieving a list of values in a given path.

var todos = byod.pv.get('/todos') // Returns a stream-wrapped collection
todos() //=> undefined
// but later...
todos() //=> An array of datapoints!

//
// This creates a new datapoint to your user's server
// AND populates todos() when it's done
//
byod.pv.post('/todos', { title: 'try it out' })

// later...
var myTodo = todos()[0]
myTodo.path //=> /todos/:ouhOEco-uHOEc-UEeu-oeu
myTodo.created_at //=> epoch number
myTodo.updated_at //=> null | epoch number
myTodo.value //=> { title: 'try it out' }

//
// Given a datapoint path,
// you merge in data, giving you { title: 'try it out', x: 10 }...
//
byod.pv.patch(todo.path, { x: 10 })

//
// ...or replace the whole thing!
//
byod.pv.put(todo.path, { title: 'no more x' })

//
// If you don't like anymore, you can (soft) delete.
// All modifications will auto-update your todos() collection.
//
byod.pv.del(todo.path)

Developing

git clone https://github.com/byod/byod-app
cd byod-app
npm install
npm run dev

Now visit http://localhost:9080/docs

Build Information

npm run build builds the library to dist, generating three files:

• dist/byod-app.cjs.js A CommonJS bundle, suitable for use in Node.js, that requires the external dependency. This corresponds to the "main" field in package.json
• dist/byod-app.esm.js an ES module bundle, suitable for use in other people's libraries and applications, that imports the external dependency. This corresponds to the "module" field in package.json
• dist/byod-app.umd.js a UMD build, suitable for use in any environment (including the browser, as a <script> tag), that includes the external dependency. This corresponds to the "browser" field in package.json

npm run dev builds the library, then keeps rebuilding it whenever the source files change using rollup-watch.

npm test builds the library, then tests it.

Note that you would often include the dist folder in your .gitignore file, but they are included here for ease of illustration.

License

MIT.