meldio-client v0.4.12

Meldio JavaScript Driver

Meldio is an open source GraphQL backend for building delightful mobile and web apps.

This library allows JavaScript applications to connect to Meldo, start authentication flow and execute GraphQL queries and mutations.

Need help?

• Join our Slack channel
• Ask a question on Stack Overflow

Installation and Setup

See our start building guide for detailed instructions on how to install Meldio.

Installation from NPM

To install Meldio Client Driver, run the following from your app project directory:

npm install meldio-client

Installation from Source

You can also install Meldio JavaScript client driver from source using the following steps:

git clone https://github.com/meldio/meldio-client-js.git
cd meldio-client-js
npm install
npm run build

Then reference the local meldio-client-js build from your project package.json, like this:

"dependencies": {
  "meldio-client": "file:../meldio-client-js/",
}

Include with HTML Script tag

Meldio client is hosted on JSDelivr CDN, so you can also include it with:

<script src="https://cdn.jsdelivr.net/meldio.client.js/0.4.12/meldio.min.js"></script>

Usage

Importing the module

Import the Meldio client module as follows:

import Meldio from 'meldio-client';  

Alternatively, you may use require:

const Meldio = require('meldio-client');

Constructor

When using Meldio together with the Relay framework, create a new instance of the Meldio client and inject Meldio network layer into Relay:

// with Relay:
import Meldio from 'meldio-client';
import Relay from 'react-relay';
const meldio = new Meldio('http://localhost:9000');
meldio.injectNetworkLayerInto(Relay);

When Meldio server is accessed directly, just create a new instance of the Meldio client:

// without Relay:
import Meldio from 'meldio-client';
const meldio = new Meldio('http://localhost:9000');

You may then export Meldio instance with:

export default meldio;

See Todo app for an example of setting up Meldio to work with Relay.

Events

Meldio class inherits from EventEmitter to allow users to subscribe to login and logout events like this:

// loginHandler function may take Meldio access token as a parameter
const loginListener = meldio.addListener('login', loginHandler);
const logoutListener = meldio.addListener('logout', logoutHandler);

To unsubscribe, simply use the remove method on the listener reference:

loginListener.remove();
logoutListener.remove();

OAuth Authentication

If the app is running within the browser environment, you may start authentication with the Meldio server using the OAuth provider popup with:

meldio.loginWithOAuthPopup('facebook')  // or 'google' or 'github'
  .then(accessToken => /* promise resolves with Meldio accessToken */)
  .catch(error => console.error('Login failed: ', error.code, error.message));

Alternatively, you may initiate authentication with the Meldio server using an access token obtained directly from the OAuth provider (e.g. using Facebook or Google client library). The following code exchanges Facebook access token stored in fbToken variable for a Meldio access token:

meldio.loginWithAccessToken('facebook', fbToken)
  .then(accessToken => /* promise resolves with Meldio accessToken */)
  .catch(error => console.error('Login failed: ', error.code, error.message));

Both loginWithOAuthPopup and loginWithAccessToken methods emit a login event upon successful login.

See Todo app's Login and AppContainer controls for a complete example of how to combine OAuth popup flow with authentication events.

Password Authentication

When password authentication is enabled and setup on the Meldio server, you may authenticate users with a loginId (e.g. email, phone number or user handle) and password using the loginWithPassword method:

loginWithPassword(loginId, password)
  .then(accessToken => /* promise resolves with Meldio accessToken */)
  .catch(error => {
    if (error.code === 'INVALID_LOGINID') {
      console.log('loginId is invalid');
    } else if (error.code === 'INVALID_PASSWORD') {
      console.log('password is invalid')
    } else if  (error.code === 'LOGIN_REFUSED') {
      console.log('Login Refused: ', error.message)
    } else {
      // misc. errors
      console.log(error.code, error.message)
    }
  });

Note that loginWithPassword method emits a login event upon successful login.

Authentication Status

Check authentication status using the isLoggedIn method which returns true if user is logged in and false otherwise:

if (meldio.isLoggedIn()) {
  console.log('User is logged in');
} else {
  console.log('User is not logged in');
}

Running Queries

Running GraphQL queries is very simple with the graphql method:

meldio.graphql(`{
  viewer {
    id
    firstName
    lastName
    emails
    profilePictureUrl
    todos {
      numberOfAllTodos: count(filter: ALL)
      numberOfCompletedTodos: count(filter: COMPLETED)
      edges {
        node {
          id
          text
          complete
        }
      }
    }
  }
}`)
  .then(result => /* handle the results returned by the query */ )
  .catch(error => /* handle errors */ )

To execute a query or mutation with parameters, pass an object with query string and variables object like this:

meldio.graphql({
  query: `
    query QueryWithParams($complete: Boolean){
      viewer {
        todos(filter: STATUS complete: $complete) {
          edges {
            node {
              id
              text
              complete
            }
          }
        }
      }
    }`,
  variables: {
    complete: true
  }
})
  .then(result => /* handle the results returned by the query */ )
  .catch(error => /* handle errors */ )

Logging out

Logout a user from the Meldio server using the logout method as follows:

meldio.logout()
  .then( () => /* logout handler */ )
  .catch( error => console.log(error.code, error.message) );

Note that logout method emits a logout event upon successful logout.

Next Steps

Check out our start building guide or get started with some cool examples.

License

This code is free software, licensed under the MIT license. See the LICENSE file for more details.