TagHub API module

This is a JavaScript module wrapping the TagHub API.

It makes use of JavaScript modules and async/await and is designed to work both on the web and with NodeJS.

Requirements

Web: Tested with `create-react-app` (webpack).
NodeJS: 13.5+ and "type": "module" in package.json.

Install

npm install --save @taghub/api

Usage

import { login, getProjects } from '@taghub/api'

const credentials = await login('username', 'password')
const projects = await getProjects(credentials)

API

Common options

Most API calls take an options object as one of their parameters. Some of these options are common and are listed below.

param         type      description
--
init          boolean   If `true` the options will be stored in module state
consumerKey   string    Passed as the `TAGHUB_CONSUMER_KEY` header for API calls (required)
accessKey     string    Passed as the `TAGHUB_ACCESS_KEY` header for API calls (required)
endpoint      string    Used as base URL (optional) - overwrite any attempt at detecting the environment

.init(options)

Init will store options in the module state for future calls. Useful so you only have to pass the consumerKey once.

Example:

import { init } from '@taghub/api'

init({ consumerKey: '123' })

.login(username, password, options)

Logs the user into TagHub. Returns an object with an accessKey parameter that can be used for access to other APIs. Passing init: true in options will also store accessKey in module state.

Example:

import { login } from '@taghub/api'

await login('username', 'password', { consumerKey: '123', init: true })

.loginSSO(username, ssoKey, updateUserOptions, options)

Logs the user into TagHub from a SSO key which is linked to a Company. Returns an object with an accessKey parameter that can be used for access to other APIs. Passing init: true in options will also store accessKey in module state.

updateUserOptions contains options to update the user:

param                  type         description
--
createIfNotExists      boolean      If `true` it will create a user if it does not exist.
firstName              string       It will update the user's first name on every login.
lastName               string       It will update the user's last name on every login.
roles                  array        It will update the project-role relationship on every login. Of shape: `[{ project, role }]`.

Example:

import { loginSSO } from '@taghub/api'

await loginSSO('username', 'ssoKey', {}, { consumerKey: '123', init: true })

Updating user properties:

await loginSSO('username', 'ssoKey', {
  createIfNotExists: true,
  firstName: 'Bob',
  lastName: 'Sponge',
  roles: [
    { project: 'Norway', role: 'Spectator' },
    { project: 'USA', role: 'Administrator' }
  ]
}, { consumerKey: '123', init: true })

.getProjects(options)

Get a list of the projects the current user has access to.

Example:

import { login, getProjects } from '@taghub/api'

await login('username', 'password', { consumerKey: '123', init: true })
const projects = await getProjects()

.getProjectMeta(project_uuid, options)

Get the metadata of a project. Information about enabled services etc.

Example:

import { login, getProjectMeta } from '@taghub/api'

await login('username', 'password', { consumerKey: '123', init: true })
const meta = await getProjectMeta('project_uuid')

.getItems(project_uuid, options, fetchparams)

Get a list of items for the passed project.

Options:

param         type      description
--
query         object    Object containing query params to pass to items call (optional)
payload       object    If provided, uses POST method with multiple filter sets
fetchAll      boolean   Fetch all items in the project (might be heavy and take a long time)
parent        string    Filter items by parent epcString (returns children of this item)

Example:

import { login, getItems } from '@taghub/api'

await login('username', 'password', { consumerKey: '123', init: true })
const items = await getItems('project_uuid')
const equipment = await getItems('project_uuid', { query: { filter9: 1 }})

Using POST with multiple filter sets:

const items = await getItems('project_uuid', {
  payload: {
    one: { filter3: ['Item1', 'Item2'] },
    two: { filter3: ['Item3'] }
  }
})
// items.one.data and items.two.data contain the results

Fetching all items with pagination:

const allItems = await getItems('project_uuid', {
  query: { limit: 100, sort: 'asc', sortBy: 'epcString' },
  fetchAll: true
})

Fetching children of a parent item:

const children = await getItems('project_uuid', { parent: 'parentEpcString' })

.getItem(project_uuid, epcString, options)

Get a single item from a project.

Example:

import { login, getItem } from '@taghub/api'

await login('username', 'password', { consumerKey: '123', init: true })
const item = await getItem('project_uuid', 'epcString')

.getItemTypes(project_uuid, options)

Get a list of item types related to a project.

Example:

import { login, getItemTypes } from '@taghub/api'

await login('username', 'password', { consumerKey: '123', init: true })
const itemTypes = await getItemTypes('project_uuid')

.makeItems(type, nbr, project_uuid, initData, options)

Create new items asynchronously. The items are created in the background and may not be immediately available.

Parameters:

param         type      description
--
type          string    The item type ID (from getItemTypes)
nbr           number    Number of items to create
project_uuid  string    The project UUID
initData      array     Initial data for the items (optional). Array of { id, value } objects.
options       object    Common options (optional)

Returns an object with status: 'success' and data (which may be empty since items are created asynchronously).

Example:

import { login, getItemTypes, makeItems } from '@taghub/api'

await login('username', 'password', { consumerKey: '123', init: true })
const itemTypes = await getItemTypes('project_uuid')
const result = await makeItems(itemTypes[0].id, 1, 'project_uuid', [
  { id: 3, value: 'Item Name' }
])

.makeItemsNow(type, nbr, project_uuid, initData, options)

Create new items synchronously. Unlike makeItems, this returns immediately with the created items including their epcStrings.

Parameters:

param         type      description
--
type          string    The item type ID (from getItemTypes)
nbr           number    Number of items to create
project_uuid  string    The project UUID
initData      array     Initial data for the items (optional). Array of { id, value } objects.
options       object    Common options (optional)

Returns an object with status: 'success' and data containing the created items with their epcStrings.

Example:

import { login, getItemTypes, makeItemsNow } from '@taghub/api'

await login('username', 'password', { consumerKey: '123', init: true })
const itemTypes = await getItemTypes('project_uuid')
const result = await makeItemsNow(itemTypes[0].id, 1, 'project_uuid', [
  { id: 3, value: 'Item Name' }
])
const epcString = result.data[0].epcString

.updateItems(project_uuid, items, data, options)

Update one or more items asynchronously. The updates are processed in the background.

Parameters:

param         type      description
--
project_uuid  string    The project UUID
items         array     Array of epcStrings to update
data          array     Array of { id, value } objects representing the fields to update
options       object    Common options. Can include `files` for file uploads and `parent` for setting parent item.

Example:

import { login, updateItems } from '@taghub/api'

await login('username', 'password', { consumerKey: '123', init: true })
await updateItems('project_uuid', ['epcString1', 'epcString2'], [
  { id: 3, value: 'New Name' },
  { id: 4, value: 'New Description' }
])

With file upload (Node.js):

await updateItems('project_uuid', ['epcString'], [
  { id: 343, value: 'document.pdf' }
], {
  files: [{ filename: 'document.pdf', filepath: './document.pdf' }]
})

With file upload (Web):

await updateItems('project_uuid', ['epcString'], [
  { id: 343, value: 'document.pdf' }
], {
  files: [{ filename: 'document.pdf', file: fileObject }]
})

Setting parent item:

await updateItems('project_uuid', ['childEpcString'], [], { parent: 'parentEpcString' })

.updateItemsNow(project_uuid, items, data, options)

Update one or more items synchronously. Similar to updateItems but waits for the update to complete.

Parameters and options are the same as updateItems.

Example:

import { login, updateItemsNow } from '@taghub/api'

await login('username', 'password', { consumerKey: '123', init: true })
await updateItemsNow('project_uuid', ['epcString'], [
  { id: 3, value: 'New Name' }
])

.archiveItems(project_uuid, epcStrings, options)

Archive one or more items.

Parameters:

param         type      description
--
project_uuid  string    The project UUID
epcStrings    array     Array of epcStrings to archive
options       object    Common options (optional)

Example:

import { login, archiveItems } from '@taghub/api'

await login('username', 'password', { consumerKey: '123', init: true })
await archiveItems('project_uuid', ['epcString1', 'epcString2'])

.getEvents(project_uuid, epcString, serviceId, options)

Get a list of events for an item's service, or all services if serviceId is not passed.

Options:

param             type      description
--
query             object    Object containing query params to pass to items call (optional)
query.startFrom   number    Index from where to start fetching events (latest events come first).
query.maxHits     number    Max number of events to fetch

Example:

import { login, getEvents } from '@taghub/api'

await login('username', 'password', { consumerKey: '123', init: true })
const events = await getEvents('project_uuid', 'epcString', 'serviceId')
const limitedEvents = await getEvents('project_uuid', 'epcString', 'serviceId', {
  query: { startFrom: 0, maxHits: 5 }
})

.getProfiles(project_uuid, options)

Get a list of profiles for a project.

Options:

param         type      description
--
query         object    Object containing query params to pass to profiles call (optional)

Example:

import { login, getProfiles } from '@taghub/api'

await login('username', 'password', { consumerKey: '123', init: true })
const profiles = await getProfiles('project_uuid')

.getClients(options)

Get a list of clients (customers) the current user has access to.

Example:

import { login, getClients } from '@taghub/api'

await login('username', 'password', { consumerKey: '123', init: true })
const clients = await getClients()

.getProjectPlaces(project_uuid, options)

Get a list of places for a project.

Example:

import { login, getProjectPlaces } from '@taghub/api'

await login('username', 'password', { consumerKey: '123', init: true })
const places = await getProjectPlaces('project_uuid')

.getLocations(location_uuid, options)

Get locations within a location.

Options:

param         type      description
--
query         object    Object containing query params (optional)

Example:

import { login, getLocations } from '@taghub/api'

await login('username', 'password', { consumerKey: '123', init: true })
const locations = await getLocations('location_uuid')

enjoy.