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

`javascript
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:
`javascript
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:
`javascript
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:
`javascript
import { loginSSO } from '@taghub/api'

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

Updating user properties:

`javascript
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:
`javascript
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:
`javascript
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:
`javascript
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:
`javascript
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:
`javascript
const allItems = await getItems('project_uuid', {
query: { limit: 100, sort: 'asc', sortBy: 'epcString' },
fetchAll: true
})
`

Fetching children of a parent item:
`javascript
const children = await getItems('project_uuid', { parent: 'parentEpcString' })
`

#### .getItem(project_uuid, epcString, options)

Get a single item from a project.

Example:
`javascript
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:
`javascript
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:
`javascript
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:
`javascript
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:
`javascript
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):
`javascript
await updateItems('project_uuid', ['epcString'], [
{ id: 343, value: 'document.pdf' }
], {
files: [{ filename: 'document.pdf', filepath: './document.pdf' }]
})
`

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

Setting parent item:
`javascript
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:
`javascript
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:
`javascript
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:
`javascript
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:
`javascript
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:
`javascript
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:
`javascript
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:
`javascript
import { login, getLocations } from '@taghub/api'

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

enjoy.