kanocomputing/kano-api-client

Kano API client

Provides a js API for browsers to communicate with our set of microservices.

Usage

• Import the client for the service you require
• Instanciate with options
• Call its methods

import { AccountClient } from '@kano/api-client/index.js';

const account = new AccountClient({
    // Where to find the API
    url: 'https://my-api.stuff.me',
    // Default headers will be sent with all requests. Has default for json
    defaultHeaders: {
        'X-Special': 'Value',
    },
});

account.login('me', 'my-password').then(session => console.log(session));

You can share options across clients by giving another client to the contructor:

import { AccountClient, UserClient } from '@kano/api-client/index.js';

const account = new AccountClient({
    // Where to find the API
    url: 'https://my-api.stuff.me',
});

// Same options here
const user = new UserClient(account);

Clients

Implemented clients:

• AccountClient:
  • login(username, password)
  • register({ username, password, email, marketing })
  • checkUsernameAvailability(username)
• UserClient:
  • getById(id)
  • getByUsername(username)

More to come

Plugins

You can add plugin to a client. A plugin is a set of methods called during the lifecycle of a request.

Example:

account.addPlugin({
    // Will be called before fetch. The endpoint about to be called will be provided
    // You can change any of its values. Adding a response property will cancel the call
    // to fetch and return the response right away
    beforeFetch(endpoint) {
        // Hi-jack the login endpoint and return static content
        // You can use this to provide offline features
        if (endpoint.name === 'login') {
            endpoint.response = {
                data: {
                    user: {
                        id: 'Hello',
                    },
                },
            };
        }
        // Alwasy return a Promise
        return Promise.resolve(endpoint);
    },
    onError(endpoint, error) {
        if (error === 'fetch failed') {
            /* Silently spoof cached response */
            endpoint.response = ResponseCache.lookup(endponint),
            return Promise.resolve(endpoint);
        } else {
            /* Log and rethrow */
            console.log(error);
            throw error;
        }
    },
    // Will return raw data as received from the API before processing
    // Use this to cache raw responses
    afterDataReceived(endpoint, data) {
        if (name === 'login') {
            console.log(data);
        }
        return Promise.resolve(data);
    },
    // Will be called after the data was received but before it is resolved to the client user
    // Use this to reformat the data, or for logging
    afterDataProcessed(endpoint, data) {
        if (name === 'login') {
            console.log(data);
        }
        return Promise.resolve(data);
    },
});

Publishing

This is an npm package and published publicly on npm. To do this, change the version number in the package.json (eg: 2.0.3 => 2.0.4), run yarn, then push and merge to master then run the following command from the root of the repo: npm publish --access public

It will require you to have an account with npm and to be logged into npm in your terminal.

kano-api-client's Issues

data map RFC

shares.${sid}.${theShare}

users.${userName}.shares.${sid}
hardware.${hardwareName}.shares.${sid}
app.${appName}.shares.${sid}
featured.shares.${sid}
slug.${slug}.shares.${sid}

Caching strategy object

After trying out lots of different caching strategies and being frustrated by them.
Here is a way that will give us the flexibility we need. (and won't annoy me)

I'm thinking the caching strategy could be an object with this structure:

• cache
  • path
    • event / true / false
      • seconds / true / false
• sync
  • path
    • event / true / false
      • seconds / true / false

"path"

a dot(.) separated list of alphanumeric characters and anything that starts with that it an empty string signifies default

"event"

notWrittenToFor, notReadFromIn, login, logout, share, close, afterSuccessfulSync

example:

{
  cache: {
    "user.email": false,
    "analytics": {
      afterSuccessfulSync: false,
      logout: false,
    },
    "shares": {
      notReadFromIn: 432000,
    },
  },
  sync:
    "analytics": {
      afterSuccessfulSync: 300, 
      logout: true,
    },
  },
}

in this example:
Will not cache the user's email.
The analytics will only be sent every 5 minutes unless the user is logging out
When the analytics have been successfully sunk they will be deleted from the cache.
If the share hasn't been read for five days it will be deleted from the cache.

Everything else will be cache indefinitely and sync immediately (on idle).

p.s. In the future as well as cache and sync I'd like to add decrypt and encrypt

Table of last read

path and time accessed,

{
  path:date,
}

so on getting:

accessed[path] = Date.now()

I'm very aware that this is using up some of our local storage. Maybe if we can store it in another subdomain, https://github.com/ofirdagan/cross-domain-local-storage we can expand the amount of storage. Let's store the access to table in local storage on a different domain.

Conversational plugin infrastructure

If the plugin has the power to get more information then we can make powerful formats

following the pattern outlined in this video:
https://www.youtube.com/watch?v=HssczgaY9BM

if offline return no important updates

I noticed at the school Users thought they needed to be online to check for the important wand updates. they could have checked exit but didn't know about it.

new testing

https://medium.com/dailyjs/running-mocha-tests-as-native-es6-modules-in-a-browser-882373f2ecb0