pizzly-js v0.2.8

Pizzly JavaScript client

The hassle-free way to connect and integrate with any OAuth web application.

Installation

Pizzly's JS can be used instantly in your page or with a package system.

Directly in your page

<script src="https://cdn.jsdelivr.net/npm/pizzly-js@latest/dist/index.umd.min.js"></script>
<script>
  // Initialize your code by passing your instance `hostname` as parameters.
  const pizzly = new Pizzly({ host: 'pizzly.example.org' })
</script>

With a build system

npm install pizzly-js
# or
yarn add pizzly-js

Usage

Connecting to an OAuth based API

The connect method lets you trigger an OAuth-dance. On success, Pizzly returns an authId that acts as a unique identifier of the authentication process.

const pizzly = new Pizzly({ host: 'pizzly.example.org' }) // Initialize Pizzly
const github = pizzly.integration('github')

github
  .connect()
  .then(({ authId }) => {
    // The authentication was successful
    console.log(`Auth ID is: ${authId}`)
  })
  .catch(error => {
    // The authentication failed
    console.error(error)
  })

Using this authId, you can make authenticated request to the API using the proxy mode.

Calling an API endpoint (proxy)

Once a user is connected, you can query the API by providing the authId.

github
  .auth('x-auth-id') // Replace with a valid authId
  .get('/repos')
  .then(response => console.log(response))
  .catch(console.error)

// Passing extra arguments
github
  .auth('x-auth-id')
  .post('/', { headers: {}, query: {}, body: '' })
  .then(response => console.log(response))
  .catch(console.error)

Most common HTTP methods are supported out-of-the-box, including .get(), .post(), .put() and .delete().

Handling the response

Under the hood, we use the Fetch API to send requests. As a consequence, each response from the API are Response interface of the Fetch API. When the API uses JSON response type, you can retrieve the JSON response as follow:

myAPI
  .auth('x-auth-id')
  .get('/x-endpoint')
  .then(response => response.json())
  .then(data => console.log(data)) // do something with the JSON payload (aka data)
  .catch(console.error)

Advanced usage

Retrieving the OAuth payload

When performing a connect, on success the OAuth payload is returned alongside the authId. Here's an example:

github
  .connect()
  .then(({ payload }) => {
    // The authentication was successful
    console.log(`Access token is: ${payload.accessToken}`)
  })
  .catch(error => {
    // The authentication failed
    console.error(error)
  })

Pizzly also provides an API endpoint to retrieve at any time the OAuth payload:

curl -X GET "/api/API-SLUGNAME/authentications/AUTH-ID"

Using a publishable key

When you've secured your instance, you'll have to provide a publishableKey when initializing Pizzly. Here's how to do it:

const pizzly = new Pizzly({ host: 'pizzly.example.org', publishableKey: '***' })

Dealing with multiple configurations

By default, each request made through Pizzly uses the latest configuration that you have saved. If you have multiple configurations in place for the same API, you can tell Pizzly which configuration should be used.

const config1 = '...'
const config2 = '...'

const github1 = pizzly.integration('github').setup(config1)
const github2 = pizzly.integration('github').setup(config2)

// Make a request with the 1st configuration
github1.get('/')

// Make another request with the 2nd configuration
github2.get('/')

Providing your own authId

For ease of use, you can provide your own authId when you connect a user to an API. For instance, you can reuse your own users IDs. This make it easy to keep track of which user is authenticated.

github
  .auth('my-own-non-guessable-auth-id')
  .connect()
  .then()
  .catch()

In that example, Pizzly will not generate an authId but instead will use my-own-non-guessable-auth-id.

Async / await

Using async/await is supported to improve code readability:

const response = await pizzly.integration('github').get('/repositories')

In that snippet, response will be a Response interface of the Fetch API.

Migration guide

For the developers previously using @bearer/js, find below a comparison with Pizzly:

Reference

Pizzly JavaScript client's reference:

/**
 * Pizzly global namespace. Call it to initialize a Pizzly instance.
 *
 * @params options <object>
 *  - host <string|number> - The host of your Pizzly's instance (e.g. "example.org")
 *  - publishableKey <string> - The publishable key of your Pizzly's instance (optional)
 *
 * @returns a new Pizzly instance.
 */

const Pizzly = (options) => {

  /**
   * OAuth authentication handler
   *
   * @params integration <string> - The integration name (e.g. "github")
   * @params options <object>
   * - authId <string> - The authentication ID
   * - configId <string> - The configuration ID
   * - setupId <string> - Alias of the configuration ID (for legacy)
   * @returns data <object>
   * - authId <string> - The authentication ID
   * - payload <object> - The OAuth payload
   */

  connect: (integration: string[, options]) => {},

  /**
   * Integration's instance
   */

  integration: {

    /**
     * Set the configuration to use
     *
     * @params setupId <string> - The configuration ID
     * @returns a new integration's instance
     */

    setup: (setupId) => {},

    /**
     * Set the authentication to use
     *
     * @params authId <string> - The authentication ID
     * @returns a new integration's instance
     */

    auth: (authId) => {},

    /**
     * Alias for connect. Will reuse auth and setup if provided.
     *
     * @returns data <object>
     * - authId <string> - The authentication ID
     * - payload <object> - The OAuth payload
     */

    connect: () => {},

    /**
     * Make a proxy request to the API (requests pass through the /proxy/ endpoint)
     *
     * @params endpoint <string> - The distant API endpoint
     * @params options <object> - The request options:
     * - headers <object> - The headers to send (e.g. { "Content-Type": "application/json" })
     * - query <object> - The query string to use (e.g. { "startAt": "1" } will be transformed into "?startAt=1")
     * - body <object> - The request's body to append (e.g. "foo=bar")
     * @returns a Fetch response schema (https://developer.mozilla.org/en-US/docs/Web/API/Response)
     */

    get: (endpoint[, options]) => {},
    post: (endpoint[, options]) => {},
    put: (endpoint[, options]) => {},
    delete: (endpoint[, options]) => {},
    head: (endpoint[, options]) => {},
    patch: (endpoint[, options]) => {},
  }
}