pdk-client

PDK Javascript Client

This is the Javascript client for interacting with the PDK auth and panel APIs.

This may be helpful as a guide even if you don't use Javascript. The APIs use a REST style HTTP JSON interface that is simple to use from nearly any language with an intelligent HTTP library.

NB: This client is still in beta and the interface may change in the future. Once 1.0 is pushed we will begin supporting a stable semver API.

Requirements

The client build targets node >= 8 in order to support async/await functionality.

There are plans to create a browser compatible build of the client. In this case the Promise async interface would be used unless the host application is being transpiled.

Layout

The src/ directory contains the client library implementation before transpiling. In src/examples/ are examples for using the API for various tasks.

Usage

Async Operations

Most of the operations with this client involve network or disk operations. Async operations are handled by promises which facilitate use of features like the await keyword.

import { makeSession, userauth } from 'pdk-client'

try {
  const session = await makeSession(userauth({ client_id, client_secret }))
  const panel = await session('panels/10702AG')
  console.log(panel)
} catch(err) {
  console.log(err)
}

Using the promises directly is also supported (with naket require thrown in for good measure):

const { makeSession, userauth } = require('pdk-client')

makeSession(userauth({ client_id, client_secret }))
  .then(session => session('panels/10702AG'))
  .then(panel => {
    console.log(panel)
  })
  .catch(err => console.log(err))

Creating a session with the Auth API

An authenticated session can be easily created against the authentication API by using the makeSession function. The makeSession function requires a configured authentication strategy. The two available strategies are currently userauth and clientauth.

The userauth strategy uses the system browser to authenticate the user and delegate access to the API consumer.

The clientauth strategy directly authenticates the openid connect client and accesses the API as its proxy user.

This session will automatically manage the authentication token lifetime, using a refresh token if available.

See the auth API documentation for operations and data types available.

import { makeSession, userauth } from 'pdk-client';

try {
  const session = await makeSession(userauth({ client_id, client_secret }));
} catch(err) {
  console.log(`Error authenticating: ${err.msg}`);
}

The session function as a thin facade around got that allows easily making authenticated requests, options are passed on to got.

Return value is a Javascript object representing the response body documented in the API docs. The promise will be rejected (await calls will throw) if there is an error with the request.

// `mine` is the ID for the authenticated user's default organization
const response = await session('ous/mine');

Creating a session with a panel API

Once an authenticated session is established with the auth API, it can be used to create an authenticated session to a specific panel.
This session will automatically manage the panel authentication token lifetime. This session is also a facade over the got library.

See the panel API documentation for operations and data types available.

Note: The term panel in the documentation is synonymous with the PDK cloud node hardware.

import { makeSession, makePanelSession, userauth } from 'pdk';

// Authenticate and create a session with the auth API
const session = await makeSession(userauth({ client_id, client_secret }));

// Get a panel document from the auth API
const panel = await session('panels/1070BBB');

// Create an authenticated session with the panel
const panelsession = await makePanelSession(session, panel);

// Retrieve an entity from the panel API
const me = await panelsession('people/123');

Connecting to the event stream of the panel API

The panel API supports a real-time socket.io event and command stream. This stream allows the reception of events from the system (credential scans, door open/close, etc), and injection of commands (door open/close, enable DND, etc) into the system.

See the Stream Oriented API section of the panel API documentation for information on available events and commands.

import { randomBytes } from 'crypto';

const stream = panelsession.createEventStream();

// Print events to the console as they come in
stream.on('liveEvent', event => console.log(`Event: ${JSON.stringify(event)}`));

// Send a door open/close command to door #6
const id = randomBytes(64).toString('hex'); // Random msg ID
stream.emit('command', {
  topic: 'door.try.open',
  body: { doorId: 6 },
  id
});

Client Authentication

Applications that support the client credentials authentication flow can use the clientauth strategy, in a similar way to the userauth method.

import { makeSession, clientauth } from 'pdk';

// Authenticate and create a session with the auth API using client credentials
const session = await makeSession(clientauth({ client_id, client_secret }));

Developers

If you want to use the client without messing with the guts, just add this module as an npm dependency and import pdk from 'pdk'; (or const pdk = require('pdk'); if you're not using ES6 modules).

This project uses babel to translate a couple features that haven't hitten node yet, mainly async/await and ES6 modules. If changes are made to src/ then npm run build needs to be run to create the output in lib/ that can be run by node.